feat(dev): auto-start dev server on invoke

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

Author: aidandaly24

docs/commands.md

@@ -475,7 +475,7 @@ Start local development server with hot-reload.
 agentcore dev
 agentcore dev --agent MyAgent --port 3000
 agentcore dev --logs                      # Non-interactive
-agentcore dev "Hello" --stream            # Invoke running server
+agentcore dev "Hello" --stream            # Invoke agent (auto-starts server)
 agentcore dev "Hello" --agent MyAgent     # Invoke specific agent
 
 # MCP protocol dev commands
@@ -485,7 +485,7 @@ agentcore dev call-tool --tool myTool --input '{"arg": "value"}'
 
 | Flag / Argument      | Description                                          |
 | -------------------- | ---------------------------------------------------- |
-| `[prompt]`           | Invoke running dev server with this prompt           |
+| `[prompt]`           | Invoke local agent (auto-starts server if needed)    |
 | `-p, --port <port>`  | Port (default: 8080; MCP uses 8000, A2A uses 9000)   |
 | `-a, --agent <name>` | Agent to run or invoke (required if multiple agents) |
 | `-s, --stream`       | Stream response when invoking                        |

docs/local-development.md

@@ -20,10 +20,10 @@ agentcore dev --logs
 
 ## Invoking Local Agents
 
-With the dev server running, open another terminal:
+Send a prompt to your agent — the dev server starts automatically if it isn't already running:
 
 ```bash
-# Single prompt
+# Single prompt (auto-starts server, invokes, shuts down)
 agentcore dev "What can you do?"
 
 # With streaming
@@ -33,6 +33,9 @@ agentcore dev "Tell me a story" --stream
 agentcore dev "Hello" --agent MyAgent
 ```
 
+If you already have `agentcore dev` or `agentcore dev --logs` running in another terminal, the invoke reuses that
+server.
+
 ## Environment Setup
 
 ### Python Virtual Environment

src/cli/commands/dev/__tests__/dev.test.ts

@@ -36,29 +36,29 @@ describe('dev command', () => {
   });
 
   describe('positional prompt invoke', () => {
-    it('attempts invoke when positional prompt is provided', async () => {
-      // With no dev server running, the invoke path triggers a connection error
+    it('exits with helpful error when no server running and no project found', async () => {
+      // With no dev server running and no project, the auto-start path
+      // detects both conditions and shows a helpful error
       const result = await runCLI(['dev', 'Hello agent'], process.cwd());
 
       expect(result.exitCode).toBe(1);
-      // Should attempt to connect to dev server and fail — not show a project error
       const output = result.stderr.toLowerCase();
       expect(
-        output.includes('fetch failed') || output.includes('econnrefused') || output.includes('dev server not running'),
-        `Should attempt invoke and fail with connection error, got: ${result.stderr}`
+        output.includes('no dev server running'),
+        `Should mention no dev server running, got: ${result.stderr}`
       ).toBeTruthy();
     });
 
-    it('does not require project context when invoking', async () => {
-      // Invoke path loads config but does not call requireProject()
-      // So the error should be about connection, not missing project
+    it('does not go through requireProject guard when invoking', async () => {
+      // Invoke path uses loadProjectConfig (soft check), not requireProject()
+      // The error should mention the dev server, not the generic project guard message
       const result = await runCLI(['dev', 'test prompt'], process.cwd());
 
       expect(result.exitCode).toBe(1);
       const output = result.stderr.toLowerCase();
       expect(
-        !output.includes('no agentcore project found'),
-        `Should not fail with project error when prompt is provided, got: ${result.stderr}`
+        !output.includes('run agentcore create'),
+        `Should not show the requireProject guard message, got: ${result.stderr}`
       ).toBeTruthy();
     });
   });

src/cli/commands/dev/command.tsx

@@ -14,6 +14,7 @@ import {
   invokeForProtocol,
   listMcpTools,
   loadProjectConfig,
+  waitForServerReady,
 } from '../../operations/dev';
 import { getGatewayEnvVars } from '../../operations/dev/gateway-env.js';
 import { FatalError } from '../../tui/components';
@@ -137,7 +138,7 @@ export const registerDev = (program: Command) => {
     .command('dev')
     .alias('d')
     .description(COMMAND_DESCRIPTIONS.dev)
-    .argument('[prompt]', 'Invoke running dev server with this prompt [non-interactive]')
+    .argument('[prompt]', 'Invoke local agent with this prompt (auto-starts server if needed) [non-interactive]')
     .option('-p, --port <port>', 'Port for development server', '8080')
     .option('-a, --agent <name>', 'Agent to run or invoke (required if multiple agents)')
     .option('-s, --stream', 'Stream response when invoking [non-interactive]')
@@ -160,10 +161,11 @@ export const registerDev = (program: Command) => {
           headers = parseHeaderFlags(opts.header);
         }
 
-        // If a prompt is provided, call the dev server and exit
+        // If a prompt is provided, invoke the dev server (auto-starting if needed)
         const invokePrompt = positionalPrompt;
         if (invokePrompt) {
-          const invokeProject = await loadProjectConfig(getWorkingDirectory());
+          const workingDir = getWorkingDirectory();
+          const invokeProject = await loadProjectConfig(workingDir);
 
           // Determine which agent/port to invoke
           let invokePort = port;
@@ -184,18 +186,84 @@ export const registerDev = (program: Command) => {
           if (protocol === 'A2A') invokePort = 9000;
           else if (protocol === 'MCP') invokePort = 8000;
 
-          // Show model info if available (not applicable to MCP)
-          if (protocol !== 'MCP' && targetAgent?.modelProvider) {
-            console.log(`Provider: ${targetAgent.modelProvider}`);
+          // Check if a dev server is already running on the target port
+          const serverRunning = await waitForServerReady(invokePort, 500);
+
+          // Auto-start a dev server if none is running
+          let autoStartedServer: ReturnType<typeof createDevServer> | undefined;
+          if (!serverRunning) {
+            if (!invokeProject) {
+              console.error('Error: No dev server running and no agentcore project found.');
+              console.error('Start a dev server first: agentcore dev');
+              process.exit(1);
+            }
+
+            const configRoot = findConfigRoot(workingDir);
+            const envVars = configRoot ? await readEnvFile(configRoot) : {};
+            const gatewayEnvVars = await getGatewayEnvVars();
+            const mergedEnvVars = { ...gatewayEnvVars, ...envVars };
+            const agentName = opts.agent ?? invokeProject.agents[0]?.name;
+            const config = getDevConfig(workingDir, invokeProject, configRoot ?? undefined, agentName);
+
+            if (!config) {
+              console.error('Error: No dev-supported agents found.');
+              process.exit(1);
+            }
+
+            const serverErrors: string[] = [];
+            let resolveServerExit: () => void;
+            const serverExitPromise = new Promise<void>(resolve => {
+              resolveServerExit = resolve;
+            });
+
+            const devCallbacks = {
+              onLog: (level: string, msg: string) => {
+                if (level === 'error') serverErrors.push(msg);
+              },
+              onExit: () => {
+                resolveServerExit();
+              },
+            };
+
+            const server = createDevServer(config, {
+              port: invokePort,
+              envVars: mergedEnvVars,
+              callbacks: devCallbacks,
+            });
+            await server.start();
+
+            // Wait for server to accept connections, bail early if process crashes
+            const ready = await Promise.race([waitForServerReady(invokePort), serverExitPromise.then(() => false)]);
+
+            if (!ready) {
+              if (serverErrors.length > 0) {
+                console.error(serverErrors.slice(-5).join('\n'));
+              }
+              console.error('Error: Dev server failed to start. Run "agentcore dev --logs" for details.');
+              server.kill();
+              process.exit(1);
+            }
+            autoStartedServer = server;
           }
 
-          // Protocol-aware dispatch
-          if (protocol === 'MCP') {
-            await handleMcpInvoke(invokePort, invokePrompt, opts.tool, opts.input, headers);
-          } else if (protocol === 'A2A') {
-            await invokeA2ADevServer(invokePort, invokePrompt, headers);
-          } else {
-            await invokeDevServer(invokePort, invokePrompt, opts.stream ?? false, headers);
+          try {
+            // Show model info if available (not applicable to MCP)
+            if (protocol !== 'MCP' && targetAgent?.modelProvider) {
+              console.log(`Provider: ${targetAgent.modelProvider}`);
+            }
+
+            // Protocol-aware dispatch
+            if (protocol === 'MCP') {
+              await handleMcpInvoke(invokePort, invokePrompt, opts.tool, opts.input, headers);
+            } else if (protocol === 'A2A') {
+              await invokeA2ADevServer(invokePort, invokePrompt, headers);
+            } else {
+              await invokeDevServer(invokePort, invokePrompt, opts.stream ?? false, headers);
+            }
+          } finally {
+            if (autoStartedServer) {
+              autoStartedServer.kill();
+            }
           }
           return;
         }

src/cli/operations/dev/index.ts

@@ -1,6 +1,7 @@
 export {
   findAvailablePort,
   waitForPort,
+  waitForServerReady,
   createDevServer,
   DevServer,
   type LogLevel,

src/cli/operations/dev/server.ts

@@ -7,7 +7,7 @@ import type { DevServer, DevServerOptions } from './dev-server';
  * Dev server barrel module.
  * Re-exports types, utilities, and the factory function.
  */
-export { findAvailablePort, waitForPort } from './utils';
+export { findAvailablePort, waitForPort, waitForServerReady } from './utils';
 export { DevServer, type LogLevel, type DevServerCallbacks, type DevServerOptions } from './dev-server';
 export { CodeZipDevServer } from './codezip-dev-server';
 export { ContainerDevServer } from './container-dev-server';

src/cli/tui/copy.ts

@@ -32,7 +32,7 @@ export const COMMAND_DESCRIPTIONS = {
   add: 'Add resources (agent, evaluator, online-eval, memory, credential, target)',
   create: 'Create a new AgentCore project',
   deploy: 'Deploy project infrastructure to AWS via CDK.',
-  dev: 'Launch local dev server, or invoke a running one.',
+  dev: 'Launch local dev server, or invoke an agent locally.',
   invoke: 'Invoke a deployed agent endpoint.',
   logs: 'Stream or search agent runtime logs.',
   package: 'Package agent artifacts without deploying.',