feat(runtime): add Runtime invocation by aidandaly24 · Pull Request #1820 · aws/agentcore-cli

aidandaly24 · 2026-07-23T21:10:34Z

Description

Adds headless and interactive invocation for the Runtime commands and TUI introduced in #1802.

Headless invocation supports both IAM and CUSTOM_JWT Runtimes. IAM requests use the AgentCore data-plane SDK, while CUSTOM_JWT requests use the generated Runtime data endpoint with an explicit bearer token. Payloads and bearer tokens can come from inline values, files, or stdin, with validation preventing both from consuming stdin at once.

The command maps the public Runtime invocation contract, including endpoint qualifiers, content negotiation, Runtime and MCP session IDs, application headers, MCP metadata, and tracing headers. Application headers are validated against the Runtime allowlist and cannot override reserved protocol headers. -H is available as the short form of --header.

Raw output streams the exact response bytes to stdout and writes response metadata to stderr. Binary responses can be written directly to a file, while --json emits one buffered response envelope with UTF-8 or base64 body encoding. Partial responses retain the bytes already received and report whether the stream completed.

Without --payload, runtime invoke opens a persistent console. Users can select a Runtime and endpoint, edit request options, send repeated requests, retain response history, switch targets, toggle completed JSON between raw and formatted views, and save binary responses to a file. Returned Runtime and MCP sessions are adopted only after a response completes.

Headless SIGINT, interactive Escape, route changes, and component unmounts propagate cancellation through Runtime lookup, transport, and response output. Usage failures return exit code 2, interruptions return 130, and transport or stream failures avoid exposing payloads, tokens, headers, or arbitrary upstream error causes. Invoke payloads, application headers, and bearer tokens are marked sensitive for command logging.

This change also adds shared abortable-stream handling used by Runtime and Harness, extends the Core Runtime client with invocation transport and injectable fetch support, and documents IAM, CUSTOM_JWT, MCP, binary, JSON, and persistent-console workflows.

Runtime creation and mutation, deployment or project resolution, cross-account invocation, Runtime ARNs, version targeting, custom request paths, and the Runtime /commands route remain outside this change.

Related Issue

N/A

Documentation PR

N/A. README command, invocation, output, MCP, and interactive-console documentation is included in this PR.

Type of Change

Testing

Verified from current HEAD cbd491b0:

Checklist

I have read the CONTRIBUTING document
I have added necessary tests that prove the feature works
I have updated the documentation accordingly
I have added appropriate examples to the documentation
My changes generate no new warnings
No dependent changes are required

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

codecov-commenter · 2026-07-23T21:12:38Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.35%. Comparing base (272e50e) to head (cbd491b).

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #1820      +/-   ##
============================================
+ Coverage     94.84%   95.35%   +0.51%     
============================================
  Files           143      151       +8     
  Lines          7120     8208    +1088     
============================================
+ Hits           6753     7827    +1074     
- Misses          367      381      +14

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Hweinstock · 2026-07-24T16:49:36Z

  breadcrumb: string[];
  description?: string;
  onSelect: (qualifier: string) => void;
+  onEscape?: () => void;


do we want to allow this to be overridden? My understanding is the esc consistently means go back to the last page right now in the tui, and by allowing an override we open the door to potentially unexpected behavior.

Hweinstock · 2026-07-24T16:58:18Z

+
 export class RuntimeClient implements CoreRuntimeClient {
-  constructor(private readonly clients: AwsClients) {}
+  constructor(


should we be injecting the logger here? I see a few places below that might benefit from some detailed debug logs

I'll add some logging here, agreed.

Hweinstock · 2026-07-24T17:17:51Z

+        throw new TypeError("CUSTOM_JWT requires an HTTPS endpoint");
+      }
+      url.pathname = `${url.pathname.replace(/\/?$/, "/")}runtimes/${encodeURIComponent(runtimeId)}/invocations`;
+      url.search = new URLSearchParams({


does it makes sense to expand the responsibility of CoreFetch to be a generic HttpClient where we can move some of this logic? I imagine we'll hit other cases where we want to do something similar to here.

I think that would be a good use case for CoreFetch. I agree that this logic could be moved over I'll scope that out.

Hweinstock · 2026-07-24T17:26:02Z

+        try {
+          await renderTuiAt(path, ctx, core, io);
+        } catch (error) {
+          throw error instanceof TypeError &&


is it worth defining an explicit error for this case? wondering if depending on the message might be brittle.

Hweinstock · 2026-07-24T17:30:34Z

+      if (jsonOutput && flags["output-file"] !== undefined) {
+        throw new UsageError("--json cannot be used with --output-file");
+      }
+      if (flags["output-file"] === "") {


could this be enforced in the schema?

Hweinstock · 2026-07-24T17:42:08Z

@@ -0,0 +1,165 @@
+import { readFile } from "node:fs/promises";


should this request/response live outside of handlers? I kind of thought the original idea is that handlers are lightweight and mirror the command structure, with functionality mostly coming from core or injected through context.

@AlexanderRichey curious to your thoughts here.

Hweinstock · 2026-07-24T17:46:45Z

+    try {
+      validateHeaderValue(name, value);
+    } catch {
+      throw new UsageError(`Invalid header value for ${name}`);


is there a way we can give a hint to the user about why its invalid? Also, I think wiring up logging here could be valuable as well.

Hweinstock · 2026-07-24T17:54:38Z

-  } catch (e) {
-    const error = e instanceof Error ? e : new Error(String(e));
-    console.error(`${error.name}: ${error.message}`);
+  } catch (error) {


Would it be simpler to define our own error base class that carries the exit code directly, and then leverage it here?

Hweinstock · 2026-07-24T17:57:16Z

    return ExitCode.SUCCESS;
-  } catch (e) {
-    const error = e instanceof Error ? e : new Error(String(e));
-    console.error(`${error.name}: ${error.message}`);


I think we want to keep this console.error, it ensures that any initialization errors are logged to the user.

Hweinstock · 2026-07-24T17:59:31Z

 });

-test("reports invalid input via command.error (throws under exitOverride)", async () => {
+test("a short alias preserves encounter order for repeated variadic values", async () => {


what exactly are we verifying here?

AlexanderRichey

I didn't have time to read the whole thing, but left some initial feedback in the comments.

AlexanderRichey · 2026-07-24T17:54:48Z

-    const error = e instanceof Error ? e : new Error(String(e));
-    console.error(`${error.name}: ${error.message}`);
+  } catch (error) {
+    if (error instanceof CommanderError) {


I see the need for something that controls the exit code, but I'm not sure this is how we ought to do it. I think we should define something like AgentCoreError that is a custom Error type that has an optional exitCode field. This should probably come in a separate PR.

AlexanderRichey · 2026-07-24T17:55:53Z

 // Flag<string, unknown>.
 export interface Flag<N extends string = string, T = unknown> {
  name: N;
+  short?: string;


I think we should hold off on adding this feature for now. This will end up adding a lot more for us to maintain.

AlexanderRichey · 2026-07-24T17:56:49Z

 } from "@aws-sdk/client-bedrock-agentcore-control";
 import type { CoreOptions } from "../../core/types";

+export interface RuntimeInvokeRequest {


These should be types and not interfaces. Types hold data whereas interfaces are abstract, don't hold data themselves, and have to be implemented by something else.

AlexanderRichey · 2026-07-24T18:01:37Z

+        }
+        responseText += decoder.decode();
+        updateExchange({ response: responseText });
+        let text: string | undefined;


There's a whole lot going on here. I tend to think there's a way to simplify all this. Let's find some time next week to discuss.

aidandaly24 added 30 commits July 23, 2026 20:09

feat(runtime): add IAM invoke vertical slice

ce97a2b

test(runtime): include invoke in command hierarchy

7d21c9e

feat(runtime): add persistent invoke console

0ed12ad

refactor(runtime): simplify invoke console tests

090ad0f

test(runtime): prove invoke history ownership

c96217b

test(runtime): prove response is not duplicated

e279d1d

fix(runtime): handle invoke console navigation errors

d0f73cc

feat(runtime): add invoke request options and JWT

6ce02e7

refactor(runtime): simplify invoke request flow

e347c21

fix(runtime): keep invoke options at UI boundary

647a52b

fix(runtime): protect invoke secrets and endpoint paths

a0c30cc

feat(runtime): add native invoke output

752b4eb

test(runtime): consolidate invoke output coverage

d0fd5b2

fix(runtime): snapshot buffered response chunks

cb3c63b

fix(runtime): preserve native output bytes

00b0929

refactor(runtime): consolidate invoke behavior

d6def5c

fix(runtime): complete invoke contracts

e37e74c

fix(runtime): preserve usage and cancellation contracts

6ddb900

fix(runtime): abort stdin and omit hidden MCP options

e36d841

docs(runtime): document invoke workflows

e8906b9

docs(runtime): clarify MCP session invocation

2ab0779

fix(runtime): default MCP response types

df700c3

fix(runtime): protect target-scoped request secrets

924c535

fix(runtime): close invoke review gaps

3075f0f

test(runtime): preserve Core call recording shape

caf19b7

refactor(runtime): simplify invoke implementation

bdd13ae

refactor(runtime): remove redundant invoke guards

f72a58d

fix(runtime): tighten invoke error handling

1fe8f8f

fix(runtime): remove arbitrary header limits

049be16

refactor(runtime): simplify invoke validation and cleanup

d404b33

chore(runtime): format invoke header flag

1f79e4d

github-actions Bot added agentcore-harness-reviewing AgentCore Harness review in progress and removed agentcore-harness-reviewing AgentCore Harness review in progress labels Jul 23, 2026

aidandaly24 added 4 commits July 24, 2026 14:21

test(runtime): complete invoke failure coverage

a296cd0

test(core): simplify data client fixtures

e25c3db

docs(core): explain abortable stream semantics

0a5a952

refactor(core): generalize fetch dependency type

cbd491b

Hweinstock reviewed Jul 24, 2026

View reviewed changes

AlexanderRichey requested changes Jul 24, 2026

View reviewed changes

		@@ -0,0 +1,165 @@
		import { readFile } from "node:fs/promises";

Uh oh!

Conversation

aidandaly24 commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related Issue

Documentation PR

Type of Change

Testing

Checklist

Uh oh!

codecov-commenter commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AlexanderRichey left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

aidandaly24 commented Jul 23, 2026 •

edited

Loading

codecov-commenter commented Jul 23, 2026 •

edited

Loading