feat(dev): positional prompt arg for invoking dev server by aidandaly24 · Pull Request #707 · aws/agentcore-cli

aidandaly24 · 2026-03-27T19:11:43Z

Description

Adds a positional [prompt] argument to agentcore dev so users can invoke a running dev server with natural CLI syntax:

# Terminal 1: start the dev server
agentcore dev --logs

# Terminal 2: send prompts
agentcore dev "What can you do?"
agentcore dev "Tell me a story" --stream
agentcore dev "Hello" --agent MyAgent

Key changes:

Positional [prompt] argument replaces the hidden --invoke flag
Invoke path sends requests to an already-running dev server (no auto-start)
Improved connection error detection via isConnectionRefused() helper — properly handles Node's TypeError: fetch failed → ECONNREFUSED cause chain and the ConnectionError wrapper from invoke.ts
Clear error message when no server is running: "Dev server not running on port 8080" + "Start it with: agentcore dev --logs"
Protocol-aware dispatch preserved: HTTP (configurable port), A2A (fixed 9000), MCP (fixed 8000)

Related Issue

Closes #8

Type of Change

New feature
Documentation update

Testing

How have you tested the change?

I ran npm run test:unit and npm run test:integ
I ran npm run typecheck
I ran npm run lint
If I modified src/assets/, I ran npm run test:update-snapshots and committed the updated snapshots

Manual E2E testing performed:

Invoke with no server running (project dir) → clear error, exit 1
Invoke from non-project directory → clear error, no crash
--logs starts dev server → server listening
Invoke running server → full response, exit 0
--stream invoke → streamed response
Wrong port → port-specific error message
Custom -H headers → forwarded correctly
3 rapid sequential invocations → all succeed
dev without prompt outside project → requireProject guard fires
--help → correct descriptions

Checklist

I have read the CONTRIBUTING document
I have added any necessary tests that prove my fix is effective or my feature works
I have updated the documentation accordingly
I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
My changes generate no new warnings
Any dependent changes have been merged and published

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

Replace `agentcore dev --invoke "Hello"` with `agentcore dev "Hello"`. The dev command now accepts an optional positional [prompt] argument that invokes a running dev server directly. The --invoke/-i flag is removed entirely — this is a breaking change for scripts using it. Rejected: keep --invoke as deprecated alias | adds UX confusion with two ways to do the same thing Confidence: high Scope-risk: narrow

github-actions · 2026-03-27T19:12:28Z

Package Tarball

aws-agentcore-0.3.0-preview.9.0.tgz

How to install

npm install https://github.com/aws/agentcore-cli/releases/download/pr-707-tarball/aws-agentcore-0.3.0-preview.9.0.tgz

When running `agentcore dev "Hello"`, the CLI now automatically starts a dev server if none is running, invokes it, and shuts it down after. If a server is already running (via --logs or TUI), it reuses it. - Export waitForServerReady from dev operations barrel - Probe target port before invoking; auto-start if nothing listening - Use Promise.race to bail early if server crashes during startup - Silent startup (no "Starting dev server..." output) - Helpful error when outside project with no server running - Update tests, docs, and command descriptions Constraint: Must not add latency when server is already running Rejected: Always require separate terminal for dev server | poor UX parity with agentcore invoke Confidence: high Scope-risk: narrow

Fixes found during bugbash of auto-start feature: - Register process.on('exit') handler to kill auto-started server, ensuring cleanup even when invoke helpers call process.exit(1) - Initialize resolveServerExit with safe default to prevent potential undefined call if Promise executor changes - Add unref() to SIGKILL timer in DevServer.kill() so Node.js exits promptly instead of hanging 2 seconds - Use !== undefined check for prompt so empty string "" enters invoke path instead of falling through to interactive TUI Constraint: process.on('exit') handlers are synchronous; cannot await server shutdown Rejected: Modify invoke helpers to throw instead of process.exit | too many callers to change Confidence: high Scope-risk: narrow Not-tested: rapid consecutive invocations (port TIME_WAIT race)

After the TCP port probe finds something listening, do a lightweight HTTP GET to the endpoint. If the response is HTML (text/html), the server is not an agentcore dev server — show a clear error instead of sending a POST and dumping raw HTML as the error message. Constraint: Cannot add a /health endpoint without modifying all Python agent templates Rejected: HEAD request probe | some servers return different headers for HEAD vs GET Confidence: high Scope-risk: narrow

- Spawn child processes with detached:true and kill the entire process group (-pid) to clean up uvicorn workers and other grandchild processes on shutdown - Fix SIGKILL fallback that never fired: child.killed is set when the signal is sent, not when the process exits. Use child.exitCode to check actual termination. - Add explicit SIGINT handler in auto-start invoke path so Ctrl+C kills the server before Node exits - Improve port identity probe: detect non-HTTP processes (e.g., raw TCP listeners) by treating probe failures as port conflicts instead of silently falling through - Guard kill() in finally block with try-catch and remove exit listener to prevent leaks Constraint: process.kill(-pid) requires detached:true so child is its own process group leader Rejected: child.killed for exit check | set on signal send, not on actual termination Rejected: process.exit(130) in SIGINT handler | kills Node before child cleanup completes Confidence: high Scope-risk: moderate Not-tested: SIGINT during waitForServerReady phase (before invoke starts)

Reverts the detached:true, process group kill, and exitCode changes from dev-server.ts. These affected all dev server modes (TUI, --logs, auto-start) but were only needed for an edge case in auto-start SIGINT cleanup. Too much blast radius for the benefit. The command.tsx fixes (port probe, SIGINT handler, exit listener cleanup) remain — they are scoped to the invoke path only.

…ssages Remove auto-start logic from the invoke path. Users must now start the dev server in a separate terminal with `agentcore dev --logs` before invoking with `agentcore dev "prompt"`. Improve connection error detection by adding isConnectionRefused() helper that checks ConnectionError name, cause chain, and common fetch failure messages instead of only checking err.message for ECONNREFUSED. Constraint: Node fetch wraps ECONNREFUSED in TypeError cause chain Rejected: Auto-start server on invoke | orphaned processes, complexity Confidence: high Scope-risk: narrow

aidandaly24 requested a review from a team March 27, 2026 19:11

github-actions bot added the size/m PR size: M label Mar 27, 2026

aidandaly24 had a problem deploying to e2e-testing March 27, 2026 19:11 — with GitHub Actions Failure

aidandaly24 had a problem deploying to e2e-testing March 27, 2026 19:27 — with GitHub Actions Failure

vivdalal previously approved these changes Mar 27, 2026

View reviewed changes

aidandaly24 dismissed vivdalal’s stale review via 814a1d0 March 27, 2026 20:13