fix(dev): address container runtime feedback

Author: tejaskash

src/core/dev/container.test.ts

@@ -3,7 +3,7 @@ import { createHash } from "node:crypto";
 import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
-import { InputValidationError } from "../../errors";
+import { InputValidationError, InvalidEnvironmentError } from "../../errors";
 import type { DevEvent, DevServerInput } from "../../handlers/project/dev/types";
 import {
   MissingToolError,
@@ -125,7 +125,7 @@ function commandCall(calls: ProcessCall[], operation: "build" | "run"): ProcessC
 }
 
 describe("ContainerDevRunner", () => {
-  test("builds with a widened context and keeps build arg values out of argv", async () => {
+  test("builds with a widened context and redacts build arg values from errors", async () => {
     const projectRuntime = runtime({
       buildContextPath: ".",
       dockerfile: "docker/Dockerfile",
@@ -148,18 +148,17 @@ describe("ContainerDevRunner", () => {
       "-t",
       imageTag(root),
       "--build-arg",
-      "AGENT_NAME",
+      "AGENT_NAME=hello-world",
       "--build-arg",
-      "TARGET",
+      "TARGET=development",
       ".",
     ]);
     expect(build.options.cwd).toBe(root);
-    expect(build.options.env).toMatchObject({
-      AGENT_NAME: "hello-world",
-      TARGET: "development",
-    });
-    expect(build.command.join(" ")).not.toContain("hello-world");
-    expect(build.command.join(" ")).not.toContain("development");
+    expect(build.options.env).toBe(process.env);
+    expect(build.options.redactedCommand).toContain("AGENT_NAME=<redacted>");
+    expect(build.options.redactedCommand).toContain("TARGET=<redacted>");
+    expect(build.options.redactedCommand?.join(" ")).not.toContain("hello-world");
+    expect(build.options.redactedCommand?.join(" ")).not.toContain("development");
 
     const dockerignore = await readFile(join(root, ".dockerignore"), "utf8");
     for (const pattern of [".env", "**/.env", "**/node_modules", "agentcore/"]) {
@@ -190,21 +189,17 @@ describe("ContainerDevRunner", () => {
       "-p",
       `127.0.0.1:3000:${containerPort}`,
       "-e",
-      "API_KEY",
+      "API_KEY=super-secret",
       "-e",
-      "PORT",
+      `PORT=${containerPort}`,
       "-e",
-      "LOCAL_DEV",
-      ...(protocol === "MCP" ? ["-e", "FASTMCP_PORT"] : []),
+      "LOCAL_DEV=1",
+      ...(protocol === "MCP" ? ["-e", "FASTMCP_PORT=8000"] : []),
       imageTag(root),
     ]);
-    expect(run.options.env).toMatchObject({
-      API_KEY: "super-secret",
-      PORT: String(containerPort),
-      LOCAL_DEV: "1",
-    });
-    expect(run.options.env?.FASTMCP_PORT).toBe(protocol === "MCP" ? "8000" : undefined);
-    expect(run.command.join(" ")).not.toContain("super-secret");
+    expect(run.options.env).toBe(process.env);
+    expect(run.options.redactedCommand).toContain("API_KEY=<redacted>");
+    expect(run.options.redactedCommand?.join(" ")).not.toContain("super-secret");
   });
 
   test("preserves an existing build context .dockerignore", async () => {
@@ -237,6 +232,33 @@ describe("ContainerDevRunner", () => {
     expect(containerName(firstRoot)).not.toBe(containerName(secondRoot));
   });
 
+  test("limits image names to two consecutive underscores", async () => {
+    const projectRuntime = runtime({ name: "Hello___World" });
+    const root = await projectRoot(projectRuntime);
+    const { calls, runner } = harness();
+
+    await collect(runner.run(input(root, projectRuntime)));
+
+    expect(commandCall(calls, "build").command).toContain(
+      `agentcore-dev/hello__world-${hashString(resolve(root))}`,
+    );
+  });
+
+  test("keeps app variables out of the container CLI environment", async () => {
+    const projectRuntime = runtime();
+    const root = await projectRoot(projectRuntime);
+    const { calls, runner } = harness();
+    const runInput = input(root, projectRuntime);
+    runInput.env = { ...runInput.env, DOCKER_HOST: "tcp://application-value" };
+
+    await collect(runner.run(runInput));
+
+    const run = commandCall(calls, "run");
+    expect(run.command).toContain("DOCKER_HOST=tcp://application-value");
+    expect(run.options.env).toBe(process.env);
+    expect(run.options.redactedCommand).toContain("DOCKER_HOST=<redacted>");
+  });
+
   test("selects the first tool that supports container builds", async () => {
     const probes: Array<[string, string[] | undefined]> = [];
     const projectRuntime = runtime();
@@ -286,6 +308,31 @@ describe("ContainerDevRunner", () => {
     expect(commandCall(calls, "build").command[0]).toBe("finch");
   });
 
+  test("passes explicit build arg values to finch", async () => {
+    const projectRuntime = runtime({ customDockerBuildArgs: { AGENT_NAME: "hello-world" } });
+    const root = await projectRoot(projectRuntime);
+    const { calls, runner } = harness({
+      available: async (tool) => tool === "finch",
+    });
+
+    await collect(runner.run(input(root, projectRuntime)));
+
+    expect(commandCall(calls, "build").command).toContain("AGENT_NAME=hello-world");
+  });
+
+  test("suggests initializing the Finch VM when its build probe fails", async () => {
+    const projectRuntime = runtime();
+    const root = await projectRoot(projectRuntime);
+    const { runner } = harness({
+      available: async (tool, probeArgs) => tool === "finch" && probeArgs === undefined,
+    });
+
+    const promise = collect(runner.run(input(root, projectRuntime)));
+
+    await expect(promise).rejects.toBeInstanceOf(InvalidEnvironmentError);
+    await expect(promise).rejects.toThrow("finch vm init");
+  });
+
   test("throws a useful error when no container runtime is available", async () => {
     const projectRuntime = runtime();
     const root = await projectRoot(projectRuntime);

src/core/dev/container.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { InputValidationError } from "../../errors";
+import { InputValidationError, InvalidEnvironmentError } from "../../errors";
 import type { DevEvent, DevRunner, DevServerInput } from "../../handlers/project/dev/types";
 import {
   MissingToolError,
@@ -82,24 +82,39 @@ export class ContainerDevRunner implements DevRunner {
 
     const runtimeName = input.runtime.name.toLowerCase();
     const projectId = hashString(resolve(input.projectRoot));
-    const imageTag = `agentcore-dev/${runtimeName}-${projectId}`;
+    const imageTag = `agentcore-dev/${sanitizeImageNameComponent(runtimeName)}-${projectId}`;
     const containerName = `agentcore-dev-${runtimeName}-${projectId}`;
     await this.removeContainer(tool, containerName, context);
     input.signal.throwIfAborted();
 
     const buildArgs = input.runtime.customDockerBuildArgs ?? {};
-    const buildArgFlags = Object.keys(buildArgs).flatMap((key) => ["--build-arg", key]);
+    const buildArgFlags = Object.entries(buildArgs).flatMap(([key, value]) => [
+      "--build-arg",
+      `${key}=${value}`,
+    ]);
+    const redactedBuildArgFlags = Object.keys(buildArgs).flatMap((key) => [
+      "--build-arg",
+      `${key}=<redacted>`,
+    ]);
+    const buildCommand = [tool, "build", "-f", dockerfile, "-t", imageTag, ...buildArgFlags, "."];
     const buildOptions: StreamProcessOptions = {
       cwd: context,
-      env: { ...process.env, ...buildArgs },
+      env: process.env,
+      redactedCommand: [
+        tool,
+        "build",
+        "-f",
+        dockerfile,
+        "-t",
+        imageTag,
+        ...redactedBuildArgFlags,
+        ".",
+      ],
       signal: input.signal,
     };
 
     yield { type: "status", message: `Building image with ${tool}` };
-    yield* this.streamProcess(
-      [tool, "build", "-f", dockerfile, "-t", imageTag, ...buildArgFlags, "."],
-      buildOptions,
-    );
+    yield* this.streamProcess(buildCommand, buildOptions);
 
     const containerPort = portForProtocol(input.runtime.protocol);
     const forwardedEnv: Record<string, string> = {
@@ -110,28 +125,44 @@ export class ContainerDevRunner implements DevRunner {
     if (input.runtime.protocol === "MCP") {
       forwardedEnv.FASTMCP_PORT = String(containerPort);
     }
-    const envNameFlags = Object.keys(forwardedEnv).flatMap((key) => ["-e", key]);
+    const envFlags = Object.entries(forwardedEnv).flatMap(([key, value]) => [
+      "-e",
+      `${key}=${value}`,
+    ]);
+    const redactedEnvFlags = Object.keys(forwardedEnv).flatMap((key) => [
+      "-e",
+      `${key}=<redacted>`,
+    ]);
+    const runCommand = [
+      tool,
+      "run",
+      "--rm",
+      "--name",
+      containerName,
+      "-p",
+      `127.0.0.1:${input.port}:${containerPort}`,
+      ...envFlags,
+      imageTag,
+    ];
 
     yield { type: "status", message: "Starting container" };
     try {
-      yield* this.streamProcess(
-        [
+      yield* this.streamProcess(runCommand, {
+        cwd: context,
+        env: process.env,
+        redactedCommand: [
           tool,
           "run",
           "--rm",
           "--name",
           containerName,
           "-p",
           `127.0.0.1:${input.port}:${containerPort}`,
-          ...envNameFlags,
+          ...redactedEnvFlags,
           imageTag,
         ],
-        {
-          cwd: context,
-          env: { ...process.env, ...forwardedEnv },
-          signal: input.signal,
-        },
-      );
+        signal: input.signal,
+      });
     } finally {
       await this.removeContainer(tool, containerName, context);
     }
@@ -146,6 +177,11 @@ export class ContainerDevRunner implements DevRunner {
       const canBuild = await this.toolAvailable(tool, ["build", "--help"]);
       signal.throwIfAborted();
       if (canBuild) return tool;
+      if (tool === "finch") {
+        throw new InvalidEnvironmentError(
+          "Finch is installed but its VM is not initialized. Run 'finch vm init' and retry.",
+        );
+      }
     }
     throw new MissingToolError("container runtime", CONTAINER_RUNTIME_INSTALL_HINT);
   }
@@ -200,3 +236,7 @@ function ensureBuildContextDockerignore(context: string): string | undefined {
 function hashString(value: string): string {
   return createHash("sha256").update(value).digest("hex").slice(0, 12);
 }
+
+function sanitizeImageNameComponent(value: string): string {
+  return value.replace(/_{3,}/g, "__");
+}

src/io/exec.test.ts

@@ -111,6 +111,20 @@ describe("streamProcess", () => {
     await expect(iterator.next()).rejects.toThrow(/exit code 3/);
   });
 
+  test("redacts sensitive command arguments from process errors", async () => {
+    const failing = await script("stream-redacted-fail.js", "process.exit(3)");
+    const iterator = streamProcess(["node", failing, "super-secret"], {
+      cwd: process.cwd(),
+      redactedCommand: ["node", failing, "<redacted>"],
+    });
+
+    const error = await iterator.next().catch((caught: unknown) => caught);
+
+    expect(error).toBeInstanceOf(ProcessFailedError);
+    expect(String(error)).toContain("<redacted>");
+    expect(String(error)).not.toContain("super-secret");
+  });
+
   test("throws ProcessFailedError when the executable cannot spawn", async () => {
     await expect(
       collect(streamProcess(["definitely-not-a-real-tool-xyz"], { cwd: process.cwd() })),

src/io/exec.ts

@@ -66,6 +66,8 @@ export type StreamProcessOptions = {
   cwd: string;
   env?: NodeJS.ProcessEnv;
   signal?: AbortSignal;
+  /** Command rendered in errors when the actual arguments contain sensitive values. */
+  redactedCommand?: string[];
   /** Required on Windows for command scripts such as npm.cmd. */
   shell?: boolean;
 };
@@ -115,8 +117,9 @@ export async function* streamProcess(
   options: StreamProcessOptions,
 ): AsyncGenerator<ProcessEvent, void> {
   const [executable, ...args] = command;
+  const errorCommand = options.redactedCommand ?? command;
   if (!executable) {
-    throw new ProcessFailedError(command, options.cwd, null, "command is empty");
+    throw new ProcessFailedError(errorCommand, options.cwd, null, "command is empty");
   }
   if (options.signal?.aborted) throw abortReason(options.signal);
 
@@ -130,7 +133,7 @@ export async function* streamProcess(
       detached: !useShell,
     });
   } catch (error) {
-    throw new ProcessFailedError(command, options.cwd, null, String(error));
+    throw new ProcessFailedError(errorCommand, options.cwd, null, String(error));
   }
 
   const events: ProcessEvent[] = [];
@@ -203,12 +206,12 @@ export async function* streamProcess(
 
     if (options.signal?.aborted) throw abortReason(options.signal);
     if (spawnError) {
-      throw new ProcessFailedError(command, options.cwd, null, String(spawnError));
+      throw new ProcessFailedError(errorCommand, options.cwd, null, String(spawnError));
     }
     if (exitCode !== 0) {
       const signalMessage = exitSignal ? `terminated by ${exitSignal}` : "";
       throw new ProcessFailedError(
-        command,
+        errorCommand,
         options.cwd,
         exitCode,
         [...recentOutput, signalMessage].filter(Boolean).join("\n"),