fix(exec): support harness deployments (#1724)

[jesseturner21]

Problem

Fixes #1724. agentcore exec reported "No deployed runtimes found" for harness deployments, while agentcore status and agentcore invoke worked. Deployed resources live in two buckets — resources.runtimes and resources.harnesses — and exec only inspected runtimes.

Root cause

Two layers:

1. Discovery: loadExecContext (and the ExecScreen picker) only enumerated resources.runtimes, so a harness-only project always hit the "No deployed runtimes found" throw.
2. Correct target ARN (found during E2E): a harness must be exec'd via its harness ARN, not the underlying agentRuntimeArn. The Yggdrasill data plane's HarnessLinkedRuntimeValidator blocks ExecuteCommand / InvokeAgentRuntimeCommandShell against a harness-linked runtime ARN ("managed by a harness and cannot be invoked directly"), but routes a harness ARN on the /runtimes/{arn}/... path through the harness exec path (ExecuteCommandActivity.invokeHarnessExecuteCommand → LoopyDP). The first attempt resolved to agentRuntimeArn and got rejected by the service; the corrected fix targets harnessState.harnessArn.

Changes

• loadExecContext (src/cli/commands/exec/action.ts): harness-aware. Considers both buckets; adds --harness <name>; auto-selects a single runtime, else a single harness; errors when both kinds are deployed and no flag is given; resolves harnesses to the harness ARN.
• ExecScreen (src/cli/tui/screens/exec/ExecScreen.tsx): picker lists harnesses (via harness ARN); empty-state message updated.
• --harness flag registered on agentcore exec (command.tsx, types.ts); mutual-exclusion with --runtime.
• Telemetry: added has_harness to exec metrics (command-run.ts schema + all 3 call sites).

Tests

• Unit: new loadExecContext with harnesses block (regression for agentcore exec reports 'No deployed runtimes found' for harness deployments #1724) — auto-select single harness, --harness, not-found, missing harness ARN, multiple-harness ambiguity, runtime+harness ambiguity, --runtime/--harness mutual exclusion. Existing runtime-only tests unchanged.
• Full unit suite: 404 files / 5830 tests passing.

End-to-end validation (real AWS)

Built the tarball (npm run bundle), installed it into a scratch project, agentcore create (harness is the default) + agentcore deploy to a real harness in us-east-1, then exercised exec against the deployed harness. Verbatim output:

$ agentcore status
Harnesses
  execharness: Deployed (v1) (arn:aws:bedrock-agentcore:us-east-1:...:harness/execharness_execharness-v3okdvEDxv)

# Before the ARN fix — resolving to agentRuntimeArn was rejected by the service:
$ agentcore exec "echo hello"
Error: The agent runtime arn:...:runtime/harness_execharness_execharness-ammHHsAwGz is managed by a harness and cannot be invoked directly. Use the InvokeAgentRuntimeCommand API with the relevant harness ID instead.

# After the fix — plain exec auto-selects the harness (by harness ARN):
$ agentcore exec --json "echo hello && uname -m && id -un"
{"success":true,"exitCode":0,"stdout":"hello\naarch64\nroot\n","stderr":""}

# --harness by name:
$ agentcore exec --harness execharness "echo FIXED-byname && pwd"
FIXED-byname
/home

The deployed CloudFormation stack was torn down after validation.

Constraint: Data plane only accepts a harness ARN (not its linked runtime ARN) on the exec/shell path.
Confidence: high
Scope-risk: narrow

[github-actions]

Package Tarball

aws-agentcore-0.23.0.tgz

How to install

gh release download pr-1728-tarball --repo aws/agentcore-cli --pattern "*.tgz" --dir /tmp/pr-tarball
npm install -g /tmp/pr-tarball/aws-agentcore-0.23.0.tgz

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-cli-automation]

Nice fix — the harness discovery path is well-structured and the tests cover the important branches. Found two related issues around --harness handling in the command wiring that should be addressed before merging. Both are behavioral (not style), and neither is exercised by the current tests.

[agentcore-cli-automation]

Interactive mode with --harness still opens the picker.

This branch only guards on options.runtimeArn, so agentcore exec --it --harness foo falls through to runExecLoop(options) on line 165 and shows the picker instead of connecting straight to the harness. loadExecContext already understands harnessName — the direct-PTY path just isn't taking it into account.

Suggested fix:

// With --runtime or --harness: skip agent picker, go straight to PTY
if (options.runtimeArn || options.harnessName) {
  requireTTY();
  await runInteractiveShell(options);
  process.exit(0);
}

Worth adding a test asserting that --harness <name> in --it mode goes through runInteractiveShell (or at least does not invoke pickAgent).

[agentcore-cli-automation]

Mutual exclusion is bypassed when --runtime is passed as an ARN.

The --runtime <arn> short-circuit on line 53 returns before the mutex check on line 58, so agentcore exec --runtime arn:... --harness foo silently ignores --harness instead of erroring. The existing test only exercises the name form of --runtime.

Two ways to fix:

1. Move the mutual-exclusion check above the ARN short-circuit (and above the earlier runtimeArn + region short-circuit on line 24 as well):

   if (options.runtimeArn && options.harnessName) {
     throw new Error('Cannot specify both --runtime and --harness.');
   }
   // ...then the ARN short-circuits and name-form resolution

2. Enforce mutual exclusion at the CLI layer in command.tsx before constructing ExecOptions, so loadExecContext never has to consider the combination.

Either way, please add a regression test for the ARN + --harness case.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	39.61%	14670 / 37035
🔵	Statements	38.87%	15633 / 40214
🔵	Functions	33.67%	2495 / 7408
🔵	Branches	33.16%	9763 / 29435

Generated in workflow #4058 for commit 2dd6a6f by the Vitest Coverage Report Action