feat(dev): wire the Agent Inspector into project dev by tejaskash · Pull Request #2086 · aws/agentcore-cli

tejaskash · 2026-08-24T17:49:02Z

What

Third and final PR of the Agent Inspector stack (C1 #2082 → C2 #2085 → C3). C1 built the Inspector HTTP layer and C2 added the agent-proxy routes, both tested in isolation behind fake dependencies. This PR wires that layer into agentcore project dev and adds the two IO leaves it needs, so the Inspector is reachable from the CLI for the first time.

Changes

project dev is UI-by-default. New --ui flag (default true, so --no-ui is auto-generated) and --ui-port. In UI mode the handler resolves a UI port (explicit port must be free, else scans from 8081), starts the Inspector server via startHttpServer(createInspectorHandler({...})), hands the collector's TraceStore to it as InspectorTraces, watches agentcore.json to reload the supervised runtime set live, and opens the browser when interactive and not --json. --no-ui keeps the existing plain single-runtime log stream.
src/io/openBrowser.ts — best-effort detached browser launch (open / cmd start / xdg-open), never blocks or fails the command.
src/io/watchFile.ts — single-file watcher, debounced, closes on abort, fails quietly on a missing file or unsupported platform.
OtelCollector.store renamed to traces so the collector hands its store to the Inspector without the Inspector knowing the collector exists. DevTraceCollector gains the matching traces accessor.

Why the two IO primitives belong in `src/io`

The handler is a real second caller of both, and both are raw platform mechanics (child-process spawn, fs.watch) that the boundary rule keeps out of src/core and the handlers. They live beside checkPort, startHttpServer, and the other IO leaves.

Lifecycle

The Inspector server rides the one AbortController shared with the collector, supervisor, and watcher, so Ctrl-C tears everything down through one cancellation domain. The collector closes only after runners return, so an agent's final spans still reach it. The config watcher's onChange swallows parse errors deliberately: a half-saved config parses on the next change event.

Tests

project dev UI-mode suite: starts the Inspector and prints the URL, opens the browser only on a TTY and never in --json, /api/status lists every runtime with none started (lazy), agentcore.json edits reload the set, --agent narrows it, a taken --ui-port fails fast, --port with several runtimes is rejected.
watchFile suite: debounces a burst of edits to one callback and stops on abort, a missing file fails quietly.
All existing trace-collection and interruption tests kept, updated for the traces rename.
bun test full suite green, typecheck / lint:check / format:check clean.

Verification altitudes

Per layer: the suites above.
End to end: pending on this branch after review — build the CLI, real project with two runtimes, confirm the browser opens the Inspector, invocations stream, MCP/A2A/resources answer, config reload is live, --no-ui gives the plain stream, --json never opens a browser.

Stacked on #2085. Merge C1 → C2 → C3 in order.

codecov-commenter · 2026-08-25T17:48:53Z

Codecov Report

❌ Patch coverage is 90.52632% with 18 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.17%. Comparing base (acfbd73) to head (66aecaf).

Files with missing lines	Patch %	Lines
src/io/openBrowser.ts	11.76%	15 Missing ⚠️
src/handlers/project/dev/index.ts	97.02%	3 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## refactor #2086 +/- ##
============================================
- Coverage 97.24% 97.17% -0.07% 
============================================
Files 465 467 +2 Lines 28417 28579 +162 ============================================
+ Hits 27635 27773 +138 - Misses 782 806 +24

☔ 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.

agentcore-devx-automation · 2026-08-27T17:23:34Z

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

notgitika

added some comments and just a question, why are we changing the flag name? why cant we just go ahead with what we have -b which means --no-browser?

browser (default, Agent Inspector), headless (one agent in the terminal), and tui as a reserved value for the planned terminal UI. Clearer than a boolean as more modes arrive. Addresses review feedback on #2086.

The dev handler took a bespoke reloadRuntimes closure; inject the project manager (narrowed to resolve) like the sibling handlers do, and re-resolve on config change. Addresses review feedback on #2086.

agentcore-devx-automation · 2026-08-27T19:29:43Z

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

Make the Inspector reachable from the CLI. project dev now runs UI-by-default: resolve a UI port, start the Inspector HTTP server, watch agentcore.json to reload the supervised runtime set live, and open the browser when interactive and not --json. --no-ui keeps the plain single-runtime log stream. Add the two IO leaves the handler needs: openBrowser (best-effort detached launch) and watchFile (debounced single-file watch, closes on abort). Expose the collector's TraceStore to the Inspector by renaming OtelCollector.store to traces so the store is handed over without the Inspector knowing the collector. The Inspector server rides the one AbortController with the collector, supervisor, and watcher, so Ctrl-C tears everything down through one cancellation domain; the collector closes only after runners return so final spans persist.

- Extract findFreePort in core/dev/port.ts; resolveDevPort delegates to it and the dev handler's UI port resolution reuses it, deleting the duplicated resolveUiPort helper and its UI_PORT_ATTEMPTS copy of MAX_PORT_ATTEMPTS. - Drop the dead resolvePort ternary: the --port guard already rejects an explicit port with more than one runtime, so flags.port applies directly. - Rewrite the config-watch closure as a linear async function. - Add projectSpecPath/PROJECT_SPEC_RELATIVE_PATH in core/project/fsUtils.ts and route the manager and the watch target through it, so the watched file and the read file resolve from one source.

Without the UI there is no lazy per-agent start, so a multi-runtime project must name which one streams to the terminal.

Rename extractSseEventText to extractA2aEventText; it only handles A2A artifact/status/task event kinds, so the generic SSE name misled. Addresses review feedback on #2085.

browser (default, Agent Inspector), headless (one agent in the terminal), and tui as a reserved value for the planned terminal UI. Clearer than a boolean as more modes arrive. Addresses review feedback on #2086.

The dev handler took a bespoke reloadRuntimes closure; inject the project manager (narrowed to resolve) like the sibling handlers do, and re-resolve on config change. Addresses review feedback on #2086.

…down setRuntimes no longer overwrites a running or starting agent's definition, so the Inspector never proxies it with metadata that no longer matches the child; the edit is applied on the agent's next start. events() now waits for every live child's pump before ending, so an agent's final spans reach the collector before shutdown closes it. Addresses review feedback on #2086.

agentcore-devx-automation · 2026-08-27T19:46:02Z

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

tejaskash · 2026-08-24T17:49:02Z

What

Third and final PR of the Agent Inspector stack (C1 #2082 → C2 #2085 → C3). C1 built the Inspector HTTP layer and C2 added the agent-proxy routes, both tested in isolation behind fake dependencies. This PR wires that layer into agentcore project dev and adds the two IO leaves it needs, so the Inspector is reachable from the CLI for the first time.

Changes

project dev is UI-by-default. New --ui flag (default true, so --no-ui is auto-generated) and --ui-port. In UI mode the handler resolves a UI port (explicit port must be free, else scans from 8081), starts the Inspector server via startHttpServer(createInspectorHandler({...})), hands the collector's TraceStore to it as InspectorTraces, watches agentcore.json to reload the supervised runtime set live, and opens the browser when interactive and not --json. --no-ui keeps the existing plain single-runtime log stream.
src/io/openBrowser.ts — best-effort detached browser launch (open / cmd start / xdg-open), never blocks or fails the command.
src/io/watchFile.ts — single-file watcher, debounced, closes on abort, fails quietly on a missing file or unsupported platform.
OtelCollector.store renamed to traces so the collector hands its store to the Inspector without the Inspector knowing the collector exists. DevTraceCollector gains the matching traces accessor.

Why the two IO primitives belong in `src/io`

The handler is a real second caller of both, and both are raw platform mechanics (child-process spawn, fs.watch) that the boundary rule keeps out of src/core and the handlers. They live beside checkPort, startHttpServer, and the other IO leaves.

Lifecycle

The Inspector server rides the one AbortController shared with the collector, supervisor, and watcher, so Ctrl-C tears everything down through one cancellation domain. The collector closes only after runners return, so an agent's final spans still reach it. The config watcher's onChange swallows parse errors deliberately: a half-saved config parses on the next change event.

Tests

project dev UI-mode suite: starts the Inspector and prints the URL, opens the browser only on a TTY and never in --json, /api/status lists every runtime with none started (lazy), agentcore.json edits reload the set, --agent narrows it, a taken --ui-port fails fast, --port with several runtimes is rejected.
watchFile suite: debounces a burst of edits to one callback and stops on abort, a missing file fails quietly.
All existing trace-collection and interruption tests kept, updated for the traces rename.
bun test full suite green, typecheck / lint:check / format:check clean.

Verification altitudes

Per layer: the suites above.
End to end: pending on this branch after review — build the CLI, real project with two runtimes, confirm the browser opens the Inspector, invocations stream, MCP/A2A/resources answer, config reload is live, --no-ui gives the plain stream, --json never opens a browser.

Stacked on #2085. Merge C1 → C2 → C3 in order.

codecov-commenter · 2026-08-25T17:48:53Z

Codecov Report

❌ Patch coverage is 90.52632% with 18 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.17%. Comparing base (acfbd73) to head (66aecaf).

Files with missing lines	Patch %	Lines
src/io/openBrowser.ts	11.76%	15 Missing ⚠️
src/handlers/project/dev/index.ts	97.02%	3 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## refactor #2086 +/- ##
============================================
- Coverage 97.24% 97.17% -0.07% 
============================================
Files 465 467 +2 Lines 28417 28579 +162 ============================================
+ Hits 27635 27773 +138 - Misses 782 806 +24

☔ 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.

agentcore-devx-automation · 2026-08-27T17:23:34Z

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

notgitika

added some comments and just a question, why are we changing the flag name? why cant we just go ahead with what we have -b which means --no-browser?

browser (default, Agent Inspector), headless (one agent in the terminal), and tui as a reserved value for the planned terminal UI. Clearer than a boolean as more modes arrive. Addresses review feedback on #2086.

The dev handler took a bespoke reloadRuntimes closure; inject the project manager (narrowed to resolve) like the sibling handlers do, and re-resolve on config change. Addresses review feedback on #2086.

agentcore-devx-automation · 2026-08-27T19:29:43Z