feat(project): wire dev handler

Author: tejaskash

package.json

@@ -7,6 +7,9 @@
     "agentcore": "./dist/index.js"
   },
   "main": "./dist/index.js",
+  "engines": {
+    "node": ">=20.12.0"
+  },
   "files": [
     "dist"
   ],

src/assets/templates/shared/env.local.template

@@ -1,7 +1,7 @@
 # Environment variables for local development.
-# `agentcore dev` loads this file into your agent's process. Values here
-# override anything the CLI injects. This file is gitignored — keep secrets
-# out of version control, but they are safe here.
+# `agentcore project dev` loads this file into your agent's process. Values here
+# override injected values except PORT, FASTMCP_PORT, and LOCAL_DEV, which the
+# CLI owns. This file is gitignored — keep secrets out of version control.
 #
 # Example:
 # MY_API_KEY=...

src/core/dev/codezip.test.ts

@@ -110,6 +110,37 @@ describe("CodeZipDevRunner", () => {
     ]);
   });
 
+  test("keeps runner-owned variables and omits the host profile with explicit credentials", async () => {
+    const root = await projectRoot();
+    const { calls, runner } = harness();
+    const devInput = input(root, runtime({ protocol: "MCP" }));
+    devInput.env = {
+      AWS_ACCESS_KEY_ID: "access",
+      AWS_SECRET_ACCESS_KEY: "secret",
+      PORT: "9999",
+      FASTMCP_PORT: "9998",
+      LOCAL_DEV: "0",
+    };
+    const profile = process.env.AWS_PROFILE;
+    process.env.AWS_PROFILE = "host-profile";
+
+    try {
+      await collect(runner.run(devInput));
+    } finally {
+      if (profile === undefined) delete process.env.AWS_PROFILE;
+      else process.env.AWS_PROFILE = profile;
+    }
+
+    expect(calls[0]?.options.env).toMatchObject({
+      AWS_ACCESS_KEY_ID: "access",
+      AWS_SECRET_ACCESS_KEY: "secret",
+      PORT: "9000",
+      FASTMCP_PORT: "9000",
+      LOCAL_DEV: "1",
+    });
+    expect(calls[0]?.options.env?.AWS_PROFILE).toBeUndefined();
+  });
+
   test.each(["MCP", "A2A", "AGUI"] as const)(
     "runs %s Python entrypoints directly",
     async (protocol) => {

src/core/dev/codezip.ts

@@ -48,6 +48,9 @@ function commandForRuntime(
     PORT: String(input.port),
     LOCAL_DEV: "1",
   };
+  if (input.env?.AWS_ACCESS_KEY_ID && input.env.AWS_SECRET_ACCESS_KEY) {
+    delete env.AWS_PROFILE;
+  }
 
   if (input.runtime.protocol === "MCP") {
     env.FASTMCP_PORT = String(input.port);

src/core/dev/container.ts

@@ -10,6 +10,7 @@ import {
   type ProcessStreamer,
   type StreamProcessOptions,
 } from "../../io";
+import { devPortForProtocol } from "./port";
 
 const CONTAINER_TOOLS = ["docker", "podman", "finch"] as const;
 const CLEANUP_TIMEOUT_MS = 2_000;
@@ -101,7 +102,7 @@ export class ContainerDevRunner implements DevRunner {
       buildOptions,
     );
 
-    const containerPort = portForProtocol(input.runtime.protocol);
+    const containerPort = devPortForProtocol(input.runtime.protocol);
     const forwardedEnv: Record<string, string> = {
       ...input.env,
       PORT: String(containerPort),
@@ -168,12 +169,6 @@ export class ContainerDevRunner implements DevRunner {
   }
 }
 
-function portForProtocol(protocol: DevServerInput["runtime"]["protocol"]): number {
-  if (protocol === "MCP") return 8000;
-  if (protocol === "A2A") return 9000;
-  return 8080;
-}
-
 function isDirectory(path: string): boolean {
   try {
     return statSync(path).isDirectory();

src/core/dev/port.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "bun:test";
+import { InputValidationError } from "../../errors";
+import type { PortChecker } from "../../io";
+import { resolveDevPort } from "./port";
+
+const signal = new AbortController().signal;
+
+function checker(occupied: number[] = []): { check: PortChecker; checked: number[] } {
+  const checked: number[] = [];
+  return {
+    checked,
+    check: async (port) => {
+      checked.push(port);
+      return !occupied.includes(port);
+    },
+  };
+}
+
+describe("resolveDevPort", () => {
+  test("uses the HTTP default when it is free", async () => {
+    const { check, checked } = checker();
+
+    expect(await resolveDevPort("HTTP", undefined, check, signal)).toEqual({
+      port: 8080,
+      requestedPort: 8080,
+    });
+    expect(checked).toEqual([8080]);
+  });
+
+  test("walks up from an occupied default HTTP port", async () => {
+    const { check, checked } = checker([8080, 8081]);
+
+    expect(await resolveDevPort("AGUI", undefined, check, signal)).toEqual({
+      port: 8082,
+      requestedPort: 8080,
+    });
+    expect(checked).toEqual([8080, 8081, 8082]);
+  });
+
+  test("honors an explicit free HTTP port", async () => {
+    const { check } = checker();
+    expect(await resolveDevPort("HTTP", 4567, check, signal)).toEqual({
+      port: 4567,
+      requestedPort: 4567,
+    });
+  });
+
+  test("rejects an occupied explicit port with inspection commands", async () => {
+    const { check } = checker([4567]);
+
+    await expect(resolveDevPort("HTTP", 4567, check, signal)).rejects.toMatchObject({
+      name: InputValidationError.name,
+      message: expect.stringContaining("lsof -i :4567"),
+    });
+  });
+
+  test.each([
+    ["MCP", 8000, 8001],
+    ["A2A", 9000, 9001],
+  ] as const)("requires the fixed %s port", async (protocol, required, invalid) => {
+    const { check, checked } = checker();
+
+    await expect(resolveDevPort(protocol, invalid, check, signal)).rejects.toThrow(
+      `${protocol} development servers require port ${required}`,
+    );
+    expect(checked).toEqual([]);
+  });
+
+  test.each([
+    ["MCP", 8000],
+    ["A2A", 9000],
+  ] as const)("rejects an occupied default %s port", async (protocol, port) => {
+    const { check } = checker([port]);
+    await expect(resolveDevPort(protocol, undefined, check, signal)).rejects.toThrow(
+      `${protocol} development servers require this port`,
+    );
+  });
+
+  test("bounds the default HTTP search to 100 ports", async () => {
+    const check: PortChecker = async () => false;
+    await expect(resolveDevPort("HTTP", undefined, check, signal)).rejects.toThrow(
+      "No free port found in range 8080-8179",
+    );
+  });
+});

src/core/dev/port.ts

@@ -0,0 +1,60 @@
+import { InputValidationError } from "../../errors";
+import type { ProjectRuntime } from "../project/schema";
+import type { PortChecker } from "../../io";
+
+const MAX_PORT_ATTEMPTS = 100;
+
+export type DevPort = {
+  port: number;
+  requestedPort: number;
+};
+
+export function devPortForProtocol(protocol: ProjectRuntime["protocol"]): number {
+  if (protocol === "MCP") return 8000;
+  if (protocol === "A2A") return 9000;
+  return 8080;
+}
+
+function portInUse(port: number, suffix = ""): InputValidationError {
+  return new InputValidationError(
+    `Port ${port} is already in use. Find the process with ` +
+      `'lsof -i :${port}' (macOS/Linux) or 'netstat -ano | findstr :${port}' (Windows), ` +
+      `then stop it${suffix}.`,
+  );
+}
+
+export async function resolveDevPort(
+  protocol: ProjectRuntime["protocol"],
+  explicitPort: number | undefined,
+  checkPort: PortChecker,
+  signal: AbortSignal,
+): Promise<DevPort> {
+  const defaultPort = devPortForProtocol(protocol);
+  const fixedPort = protocol === "MCP" || protocol === "A2A";
+  const requestedPort = explicitPort ?? defaultPort;
+
+  if (fixedPort && explicitPort !== undefined && explicitPort !== defaultPort) {
+    throw new InputValidationError(
+      `${protocol} development servers require port ${defaultPort}; received --port ${explicitPort}.`,
+    );
+  }
+
+  if (await checkPort(requestedPort, signal)) {
+    return { port: requestedPort, requestedPort };
+  }
+
+  if (explicitPort !== undefined) {
+    throw portInUse(requestedPort, " or choose a different --port");
+  }
+  if (fixedPort) {
+    throw portInUse(requestedPort, `; ${protocol} development servers require this port`);
+  }
+
+  for (let port = requestedPort + 1; port < requestedPort + MAX_PORT_ATTEMPTS; port++) {
+    if (await checkPort(port, signal)) return { port, requestedPort };
+  }
+
+  throw new InputValidationError(
+    `No free port found in range ${requestedPort}-${requestedPort + MAX_PORT_ATTEMPTS - 1}.`,
+  );
+}

src/errors/errors.tsx

@@ -135,7 +135,7 @@ export class EmbeddedAssetNotFoundError extends AgentCoreCLIError {
   }
 }
 
-export class RuntimeInvokeInterruptedError extends AgentCoreCLIError {
+export class CommandInterruptedError extends AgentCoreCLIError {
   readonly reported: boolean;
 
   constructor(cause?: unknown, reported = false) {

src/errors/index.tsx

@@ -1,5 +1,6 @@
 export {
   AgentCoreCLIError,
+  CommandInterruptedError,
   DeserializationError,
   EmbeddedAssetNotFoundError,
   FileWriteError,
@@ -9,7 +10,6 @@ export {
   NetworkingError,
   NotImplementedError,
   ProjectFileExistsError,
-  RuntimeInvokeInterruptedError,
   RuntimeInvokeResponseError,
   SourceResolutionError,
   type AgentCoreCLIErrorOptions,