From b309d6101fb4d40e2a578c94e33bca4168398dc0 Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Wed, 18 Nov 2026 22:54:04 -0800 Subject: [PATCH 01/13] feat(dev): Hand box run the profile's env:// keys instead of copying them to .env.local Dev used to copy each variable an [egress] route of the box profile names from the shell into agentcore/.env.local. It now writes nothing: each env:// key of an [egress] route or an [mcp] server goes to box run's environment, the shell's value first and .env.local's when the shell has none. A CodeZip agent's box run inherits it; a box container gets it through the run's own env file, never on the command line. When neither has it, dev warns, naming the variable, the table that reads it, and how to set it. Tested: bun test (5399 pass); container dev with Finch and an [egress.github] route, with the token set on the command line (no .env.local write, the agent answers) and without it (the warning, then box's own error); the full e2e suite: 15 harness, 15 runtime template and 7 box template cases. --- src/core/dev/box.test.ts | 72 ++++++++++++++++++- src/core/dev/box.ts | 17 ++++- src/core/dev/boxDevSecrets.test.ts | 110 +++++++++++++++++++++++++++++ src/core/dev/boxDevSecrets.ts | 80 +++++++++++++++++++++ src/core/dev/boxEnvLocal.test.ts | 88 ----------------------- src/core/dev/boxEnvLocal.ts | 41 ----------- src/core/dev/container.test.ts | 39 ++++++++++ src/core/dev/container.ts | 14 ++++ src/handlers/project/dev/index.ts | 4 -- 9 files changed, 329 insertions(+), 136 deletions(-) create mode 100644 src/core/dev/boxDevSecrets.test.ts create mode 100644 src/core/dev/boxDevSecrets.ts delete mode 100644 src/core/dev/boxEnvLocal.test.ts delete mode 100644 src/core/dev/boxEnvLocal.ts diff --git a/src/core/dev/box.test.ts b/src/core/dev/box.test.ts index 775a58120..1c0c3e98b 100644 --- a/src/core/dev/box.test.ts +++ b/src/core/dev/box.test.ts @@ -1,4 +1,5 @@ import { afterEach, describe, expect, test } from "bun:test"; +import { existsSync } from "node:fs"; import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; @@ -33,13 +34,17 @@ async function temp(prefix: string): Promise { } /** A project named `Demo` that holds its box profile in .box/profile.toml when `profiled`. */ -async function scene(profiled: boolean, boxOnPath = true) { +async function scene( + profiled: boolean, + boxOnPath = true, + options: { profile?: string; processEnv?: NodeJS.ProcessEnv } = {}, +) { const projectRoot = await temp("agentcore-box-project-"); await mkdir(join(projectRoot, "agentcore")); await writeFile(join(projectRoot, "agentcore", "agentcore.json"), '{"name":"Demo"}'); if (profiled) { await mkdir(join(projectRoot, ".box")); - await writeFile(join(projectRoot, ".box", "profile.toml"), PROFILE); + await writeFile(join(projectRoot, ".box", "profile.toml"), options.profile ?? PROFILE); await mkdir(join(projectRoot, "app", "agent", ".venv"), { recursive: true }); } @@ -63,6 +68,7 @@ async function scene(profiled: boolean, boxOnPath = true) { checked.push(tool); if (!boxOnPath) throw new MissingToolError(tool, installHint); }, + ...(options.processEnv && { processEnv: options.processEnv }), }); return { projectRoot, calls, fallbackRuns, runner, checked }; } @@ -158,6 +164,68 @@ describe("BoxDevRunner", () => { expect(env.OTEL_SERVICE_NAME).toBe(process.env.OTEL_SERVICE_NAME); }); + describe("with an env:// key in the profile", () => { + const GITHUB_PROFILE = + PROFILE + + '[egress.github]\ndestinations = ["api.github.com"]\nsecret.ref = "env://GITHUB_TOKEN"\n'; + + test("hands box run the shell's value, and writes no .env.local", async () => { + const { projectRoot, calls, runner } = await scene(true, true, { + profile: GITHUB_PROFILE, + processEnv: { GITHUB_TOKEN: "ghp_shell" }, + }); + + const events = await collect(runner.run({ ...input(projectRoot), env: {} })); + + expect(calls[0]!.options.env!.GITHUB_TOKEN).toBe("ghp_shell"); + expect(existsSync(join(projectRoot, "agentcore", ".env.local"))).toBe(false); + expect(events.some((event) => "message" in event && event.message.includes("not set"))).toBe( + false, + ); + }); + + test("prefers the shell's value to .env.local's", async () => { + const { projectRoot, calls, runner } = await scene(true, true, { + profile: GITHUB_PROFILE, + processEnv: { GITHUB_TOKEN: "ghp_shell" }, + }); + + await collect(runner.run({ ...input(projectRoot), env: { GITHUB_TOKEN: "ghp_file" } })); + + expect(calls[0]!.options.env!.GITHUB_TOKEN).toBe("ghp_shell"); + }); + + test("uses .env.local's value when the shell has none", async () => { + const { projectRoot, calls, runner } = await scene(true, true, { + profile: GITHUB_PROFILE, + processEnv: {}, + }); + + await collect(runner.run({ ...input(projectRoot), env: { GITHUB_TOKEN: "ghp_file" } })); + + expect(calls[0]!.options.env!.GITHUB_TOKEN).toBe("ghp_file"); + }); + + test("warns when neither has it, before box run reports it", async () => { + const { projectRoot, calls, runner } = await scene(true, true, { + profile: GITHUB_PROFILE, + processEnv: {}, + }); + + const events = await collect(runner.run({ ...input(projectRoot), env: {} })); + + expect(events).toContainEqual({ + type: "status", + message: + "the box profile .box/profile.toml reads GITHUB_TOKEN for [egress.github], but it is " + + "not set, and box does not start without it. Export it in this shell " + + "(export GITHUB_TOKEN=...) or put it in agentcore/.env.local, then restart dev.", + }); + // box run still starts, so its own error follows the warning. + expect(calls).toHaveLength(1); + }); + }); + test("runs the agent the usual way when the project has no box profile", async () => { const { projectRoot, calls, fallbackRuns, runner } = await scene(false); diff --git a/src/core/dev/box.ts b/src/core/dev/box.ts index 8c60becc8..8225a9a67 100644 --- a/src/core/dev/box.ts +++ b/src/core/dev/box.ts @@ -5,6 +5,7 @@ import type { DevEvent, DevRunner, DevServerInput } from "../../handlers/project import { streamProcess, type ProcessStreamer } from "../../io"; import { requireTool } from "../../io/exec"; import { BOX_INSTALL_HINT } from "../project/backends/boxRelease"; +import { boxDevSecrets, missingBoxSecretWarning } from "./boxDevSecrets"; import { BOX_PROFILE_FILE, boxIngressPort, @@ -19,6 +20,8 @@ type BoxDevRunnerConfig = { streamProcess?: ProcessStreamer; /** Fails when `box` is not on PATH, with the install hint; tests inject one. */ checkTool?: (tool: string, installHint: string) => Promise; + /** The environment `box run` starts from, the shell's by default; tests inject one. */ + processEnv?: NodeJS.ProcessEnv; }; /** @@ -32,11 +35,13 @@ export class BoxDevRunner implements DevRunner { private readonly fallback: DevRunner; private readonly streamProcess: ProcessStreamer; private readonly checkTool: NonNullable; + private readonly processEnv: NodeJS.ProcessEnv; constructor(config: BoxDevRunnerConfig) { this.fallback = config.fallback; this.streamProcess = config.streamProcess ?? streamProcess; this.checkTool = config.checkTool ?? requireTool; + this.processEnv = config.processEnv ?? process.env; } public async *run(input: DevServerInput): AsyncGenerator { @@ -84,13 +89,23 @@ export class BoxDevRunner implements DevRunner { if (input.env?.OTEL_EXPORTER_OTLP_ENDPOINT) { yield { type: "status", message: "Traces are not collected when the agent runs in a box" }; } + const fileEnv = credentialEnvironment(input.env); + // box reads each env:// key of the profile from its own environment. The shell's value wins + // over agentcore/.env.local's, and dev writes neither anywhere. + const secrets = await boxDevSecrets(input.projectRoot, { + ...fileEnv, + ...this.processEnv, + }); + for (const missing of secrets.missing) { + yield { type: "status", message: missingBoxSecretWarning(missing) }; + } yield { type: "status", message: `Starting the agent in a box (box run ${BOX_PROFILE_FILE})`, }; yield* this.streamProcess(["box", "run", BOX_PROFILE_FILE, "--no-banner"], { cwd: input.projectRoot, - env: { ...process.env, ...credentialEnvironment(input.env) }, + env: { ...this.processEnv, ...fileEnv, ...secrets.env }, signal: input.signal, }); } diff --git a/src/core/dev/boxDevSecrets.test.ts b/src/core/dev/boxDevSecrets.test.ts new file mode 100644 index 000000000..b7d8667ef --- /dev/null +++ b/src/core/dev/boxDevSecrets.test.ts @@ -0,0 +1,110 @@ +import { afterEach, describe, expect, test } from "bun:test"; +import { existsSync } from "node:fs"; +import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { EnvLocalFile } from "../project/envLocal"; +import { boxDevSecrets, missingBoxSecretWarning } from "./boxDevSecrets"; + +const GITHUB_ROUTE = + '[egress.github]\ndestinations = ["api.github.com"]\nsecret.ref = "env://GITHUB_TOKEN"\n'; +const TOOLS_SERVER = + '[mcp.tools]\ntype = "http"\nurl = "https://tools.example.com/mcp"\nsecret.ref = "env://TOOLS_TOKEN"\n'; + +const roots: string[] = []; + +afterEach(async () => { + await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true }))); +}); + +async function project(profile?: string): Promise { + const root = await mkdtemp(join(tmpdir(), "agentcore-box-dev-secrets-")); + roots.push(root); + await mkdir(join(root, "agentcore")); + if (profile !== undefined) { + await mkdir(join(root, ".box")); + await writeFile(join(root, ".box", "profile.toml"), profile); + } + return root; +} + +describe("boxDevSecrets", () => { + test("returns an env:// route's variable under its own name, and writes no .env.local", async () => { + const root = await project(GITHUB_ROUTE); + + expect(await boxDevSecrets(root, { GITHUB_TOKEN: "ghp_1", OTHER: "x" })).toEqual({ + env: { GITHUB_TOKEN: "ghp_1" }, + missing: [], + }); + expect(existsSync(new EnvLocalFile(root).path)).toBe(false); + }); + + test("returns an HTTP MCP server's env:// variable too", async () => { + const root = await project(GITHUB_ROUTE + TOOLS_SERVER); + + expect(await boxDevSecrets(root, { GITHUB_TOKEN: "ghp_1", TOOLS_TOKEN: "tk_1" })).toEqual({ + env: { GITHUB_TOKEN: "ghp_1", TOOLS_TOKEN: "tk_1" }, + missing: [], + }); + }); + + test("names one variable once when two tables read it", async () => { + const root = await project( + GITHUB_ROUTE + + '[egress.gist]\ndestinations = ["gist.github.com"]\nsecret.ref = "env://GITHUB_TOKEN"\n', + ); + + expect(await boxDevSecrets(root, {})).toEqual({ + env: {}, + missing: [{ variable: "GITHUB_TOKEN", table: "[egress.github]" }], + }); + }); + + test("reports a variable that is unset or blank as missing, with the table that reads it", async () => { + const root = await project(GITHUB_ROUTE + TOOLS_SERVER); + + expect(await boxDevSecrets(root, { GITHUB_TOKEN: " " })).toEqual({ + env: {}, + missing: [ + { variable: "GITHUB_TOKEN", table: "[egress.github]" }, + { variable: "TOOLS_TOKEN", table: "[mcp.tools]" }, + ], + }); + }); + + test("leaves out a pack's variable and a secret that is not env://", async () => { + const root = await project( + 'packs = ["box/bedrock"]\n[egress.s3]\ndestinations = ["s3.amazonaws.com"]\nsecret.ref = "aws://default"\n', + ); + + expect(await boxDevSecrets(root, { AWS_BEARER_TOKEN_BEDROCK: "token", default: "x" })).toEqual({ + env: {}, + missing: [], + }); + }); + + test("returns nothing for a profile that does not parse; box run reports it", async () => { + const root = await project("[egress\n"); + + expect(await boxDevSecrets(root, {})).toEqual({ env: {}, missing: [] }); + }); + + test("returns nothing without a box profile", async () => { + const root = await project(); + + expect(await boxDevSecrets(root, { GITHUB_TOKEN: "ghp_1" })).toEqual({ + env: {}, + missing: [], + }); + }); +}); + +describe("missingBoxSecretWarning", () => { + test("names the profile, the variable, its table, and both ways to set it", () => { + expect(missingBoxSecretWarning({ variable: "GITHUB_TOKEN", table: "[egress.github]" })).toBe( + "the box profile .box/profile.toml reads GITHUB_TOKEN for [egress.github], but it is not " + + "set, and box does not start without it. Export it in this shell " + + "(export GITHUB_TOKEN=...) or put it in agentcore/.env.local, then restart dev.", + ); + }); +}); diff --git a/src/core/dev/boxDevSecrets.ts b/src/core/dev/boxDevSecrets.ts new file mode 100644 index 000000000..9bcd8b888 --- /dev/null +++ b/src/core/dev/boxDevSecrets.ts @@ -0,0 +1,80 @@ +import { existsSync } from "node:fs"; +import { readFile } from "node:fs/promises"; +import { parse as parseToml } from "smol-toml"; +import { hasValue } from "../project/boxProfileEgress"; +import { ENV_LOCAL_RELATIVE_PATH } from "../project/envLocal"; +import { BOX_PROFILE_FILE, boxProfilePath } from "../project/templates/boxProfile"; + +const ENV_SCHEME = "env://"; + +/** A variable the box profile reads a key from, and the table that reads it. */ +export type BoxDevSecretVariable = { readonly variable: string; readonly table: string }; + +/** The keys the box profile reads from the environment, as dev hands them to `box run`. */ +export type BoxDevSecrets = { + /** Each variable with its value, for `box run`'s environment. */ + readonly env: Record; + /** Each variable that is unset or blank; box refuses to start without it. */ + readonly missing: readonly BoxDevSecretVariable[]; +}; + +/** + * The variables that the project's box profile reads its keys from: each `env://` secret of + * an `[egress.]` route or an `[mcp.]` server, with its value in `env`. Dev hands these + * to `box run` as they are and writes none of them anywhere. A CodeZip agent's `box run` inherits + * the whole environment already; a box container gets them in its environment, since it gets + * nothing else from the host's. Only the profile's own tables count: a pack's variable, such as + * box/bedrock's `AWS_BEARER_TOKEN_BEDROCK`, is not the profile author's to pass. A profile that + * does not parse has none here; `box run` reports it. + */ +export async function boxDevSecrets( + projectRoot: string, + env: Readonly>, +): Promise { + const profile = boxProfilePath(projectRoot); + if (!existsSync(profile)) return { env: {}, missing: [] }; + const table = parseProfile(await readFile(profile, "utf-8")); + + const found: Record = {}; + const missing: BoxDevSecretVariable[] = []; + for (const kind of ["egress", "mcp"] as const) { + for (const [name, entry] of Object.entries(tableOf(table[kind]))) { + const ref = (entry as { secret?: { ref?: unknown } } | null)?.secret?.ref; + if (typeof ref !== "string" || !ref.startsWith(ENV_SCHEME)) continue; + const variable = ref.slice(ENV_SCHEME.length); + if (variable === "" || variable in found) continue; + const value = env[variable]; + if (!hasValue(value)) { + if (!missing.some((other) => other.variable === variable)) { + missing.push({ variable, table: `[${kind}.${name}]` }); + } + continue; + } + found[variable] = value; + } + } + return { env: found, missing }; +} + +/** The warning dev shows for a variable the box profile reads that is not set. */ +export function missingBoxSecretWarning({ variable, table }: BoxDevSecretVariable): string { + return ( + `the box profile ${BOX_PROFILE_FILE} reads ${variable} for ${table}, but it is not set, and ` + + `box does not start without it. Export it in this shell (export ${variable}=...) or put it ` + + `in ${ENV_LOCAL_RELATIVE_PATH}, then restart dev.` + ); +} + +function parseProfile(text: string): Record { + try { + return parseToml(text) as Record; + } catch { + return {}; + } +} + +function tableOf(value: unknown): Record { + return typeof value === "object" && value !== null && !Array.isArray(value) + ? (value as Record) + : {}; +} diff --git a/src/core/dev/boxEnvLocal.test.ts b/src/core/dev/boxEnvLocal.test.ts deleted file mode 100644 index 13c9890d7..000000000 --- a/src/core/dev/boxEnvLocal.test.ts +++ /dev/null @@ -1,88 +0,0 @@ -import { afterEach, describe, expect, test } from "bun:test"; -import { existsSync } from "node:fs"; -import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; -import { tmpdir } from "node:os"; -import { join } from "node:path"; -import { ENV_LOCAL_RELATIVE_PATH, EnvLocalFile } from "../project/envLocal"; -import { writeBoxDevEnvLocal } from "./boxEnvLocal"; - -const GITHUB_ROUTE = - '[egress.github]\ndestinations = ["api.github.com"]\nsecret.ref = "env://GITHUB_TOKEN"\n'; - -const roots: string[] = []; - -afterEach(async () => { - await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true }))); -}); - -async function project(profile?: string): Promise { - const root = await mkdtemp(join(tmpdir(), "agentcore-box-env-local-")); - roots.push(root); - await mkdir(join(root, "agentcore")); - if (profile !== undefined) { - await mkdir(join(root, ".box")); - await writeFile(join(root, ".box", "profile.toml"), profile); - } - return root; -} - -const envLocal = (root: string) => new EnvLocalFile(root).read(); - -describe("writeBoxDevEnvLocal", () => { - test("writes an env:// route's variable under its own name", async () => { - const root = await project(GITHUB_ROUTE); - - const messages = await writeBoxDevEnvLocal(root, { GITHUB_TOKEN: "ghp_1" }); - - expect(await envLocal(root)).toEqual({ GITHUB_TOKEN: "ghp_1" }); - expect(messages).toEqual([ - `writing GITHUB_TOKEN to ${ENV_LOCAL_RELATIVE_PATH} for box egress 'github' (env://GITHUB_TOKEN)`, - ]); - }); - - test("keeps a value .env.local holds already", async () => { - const root = await project(GITHUB_ROUTE); - await new EnvLocalFile(root).insertIfNew([ - { key: "GITHUB_TOKEN", value: "ghp_old", comment: "mine" }, - ]); - - expect(await writeBoxDevEnvLocal(root, { GITHUB_TOKEN: "ghp_new" })).toEqual([]); - expect(await envLocal(root)).toEqual({ GITHUB_TOKEN: "ghp_old" }); - }); - - test("writes nothing for a variable that is unset or blank", async () => { - const root = await project(GITHUB_ROUTE); - - expect(await writeBoxDevEnvLocal(root, {})).toEqual([]); - expect(await writeBoxDevEnvLocal(root, { GITHUB_TOKEN: " " })).toEqual([]); - expect(existsSync(new EnvLocalFile(root).path)).toBe(false); - }); - - test("does not copy the credential's stored key into the route's variable", async () => { - const root = await project(GITHUB_ROUTE); - await new EnvLocalFile(root).insertIfNew([ - { key: "AGENTCORE_CREDENTIAL_GITHUB", value: "ghp_1", comment: "deploy" }, - ]); - - expect(await writeBoxDevEnvLocal(root, {})).toEqual([]); - expect(await envLocal(root)).toEqual({ AGENTCORE_CREDENTIAL_GITHUB: "ghp_1" }); - }); - - test("leaves out a pack's variable and a route without an env:// secret", async () => { - const root = await project( - 'packs = ["box/bedrock"]\n[egress.s3]\ndestinations = ["s3.amazonaws.com"]\nsecret.ref = "aws://default"\n', - ); - - expect( - await writeBoxDevEnvLocal(root, { AWS_BEARER_TOKEN_BEDROCK: "token", default: "x" }), - ).toEqual([]); - expect(existsSync(new EnvLocalFile(root).path)).toBe(false); - }); - - test("does nothing without a box profile", async () => { - const root = await project(); - - expect(await writeBoxDevEnvLocal(root, { GITHUB_TOKEN: "ghp_1" })).toEqual([]); - expect(existsSync(new EnvLocalFile(root).path)).toBe(false); - }); -}); diff --git a/src/core/dev/boxEnvLocal.ts b/src/core/dev/boxEnvLocal.ts deleted file mode 100644 index 526408077..000000000 --- a/src/core/dev/boxEnvLocal.ts +++ /dev/null @@ -1,41 +0,0 @@ -import type { EnvLocalEntry } from "../../handlers/project/types"; -import { hasValue, readBoxEnvRoutes } from "../project/boxProfileEgress"; -import { EnvLocalFile, ENV_LOCAL_RELATIVE_PATH } from "../project/envLocal"; - -/** - * Writes into `agentcore/.env.local`, under its own name, each variable that a - * `[egress.] secret.ref = "env://"` route of the project's box profile - * names and `env` holds, so `box run` finds it under `agentcore dev`, on the host - * and in a container alike. A variable `.env.local` holds already keeps its value, - * and one that is unset or blank in `env` is left out, so box names it. A profile - * that does not parse has no routes here; `box run` reports it. Returns a message - * for each variable it writes. - */ -export async function writeBoxDevEnvLocal( - projectRoot: string, - env: NodeJS.ProcessEnv = process.env, -): Promise { - const routes = readBoxEnvRoutes(projectRoot)?.routes ?? []; - - const entries: (EnvLocalEntry & { route: string })[] = []; - for (const { route, variable: key } of routes) { - const value = env[key]; - if (!hasValue(value)) continue; - if (entries.some((other) => other.key === key)) continue; - entries.push({ - key, - value, - route, - comment: `Key for box egress '${route}' (env://${key}), read by box under agentcore dev`, - }); - } - if (entries.length === 0) return []; - - const { written } = await new EnvLocalFile(projectRoot).insertIfNew(entries); - return entries - .filter(({ key }) => written.includes(key)) - .map( - ({ key, route }) => - `writing ${key} to ${ENV_LOCAL_RELATIVE_PATH} for box egress '${route}' (env://${key})`, - ); -} diff --git a/src/core/dev/container.test.ts b/src/core/dev/container.test.ts index dc7a70a9b..df7088bd5 100644 --- a/src/core/dev/container.test.ts +++ b/src/core/dev/container.test.ts @@ -994,6 +994,45 @@ describe("ContainerDevRunner", () => { expect(existsSync(join(context, ".box-dist"))).toBe(false); }); + test("hands box in the container the profile's env:// key from the shell, through the run's env file", async () => { + const { projectRuntime, root } = await boxedScene({ + profileText: + '[egress.github]\ndestinations = ["api.github.com"]\nsecret.ref = "env://GITHUB_TOKEN"\n', + }); + const { calls, runner } = harness({ + processEnv: { ...credentials, GITHUB_TOKEN: "ghp_shell", UNRELATED: "x" }, + }); + + await collect(runner.run(input(root, projectRuntime))); + + const run = commandCall(calls, "run"); + const forwarded = parseEnv(run.envFile!.contents); + expect(forwarded.GITHUB_TOKEN).toBe("ghp_shell"); + // Only the keys the profile names, not the rest of the shell. + expect(forwarded.UNRELATED).toBeUndefined(); + // Passed through the env file, never on the command line, and written to no .env.local. + expect(run.command.join(" ")).not.toContain("ghp_shell"); + expect(existsSync(join(root, "agentcore", ".env.local"))).toBe(false); + }); + + test("warns when the profile's env:// key is not set, before the container's box reports it", async () => { + const { projectRuntime, root } = await boxedScene({ + profileText: + '[egress.github]\ndestinations = ["api.github.com"]\nsecret.ref = "env://GITHUB_TOKEN"\n', + }); + const { calls, runner } = harness({ processEnv: credentials }); + + const events = await collect(runner.run(input(root, projectRuntime))); + + expect(events).toContainEqual({ + type: "status", + message: expect.stringContaining( + "reads GITHUB_TOKEN for [egress.github], but it is not set", + ), + }); + expect(commandCall(calls, "run")).toBeDefined(); + }); + test("stages box of the runtime's box.version", async () => { const { projectRuntime, root } = await boxedScene(); const { boxVersions, runner } = harness({ processEnv: credentials }); diff --git a/src/core/dev/container.ts b/src/core/dev/container.ts index 96d8d8683..371347479 100644 --- a/src/core/dev/container.ts +++ b/src/core/dev/container.ts @@ -10,6 +10,7 @@ import { ResourceNotFoundError, } from "../../errors"; import { notBoxProjectMessage } from "./box"; +import { boxDevSecrets, missingBoxSecretWarning } from "./boxDevSecrets"; import type { DevEvent, DevRunner, DevServerInput } from "../../handlers/project/dev/types"; import { MissingToolError, @@ -243,6 +244,19 @@ export class ContainerDevRunner implements DevRunner { PORT: String(containerPort), LOCAL_DEV: "1", }); + if (boxed) { + // The container gets none of the host's environment, so box in it gets each env:// key of + // the profile here. The shell's value wins over agentcore/.env.local's, and dev writes + // neither anywhere but the run's own env file, removed when the run ends. + const secrets = await boxDevSecrets(input.projectRoot, { + ...input.env, + ...this.processEnv, + }); + for (const missing of secrets.missing) { + yield { type: "status", message: missingBoxSecretWarning(missing) }; + } + Object.assign(forwardedEnv, secrets.env); + } if (input.runtime.protocol === "MCP") { forwardedEnv.FASTMCP_PORT = String(containerPort); } diff --git a/src/handlers/project/dev/index.ts b/src/handlers/project/dev/index.ts index a8fd04d3b..2664dd053 100644 --- a/src/handlers/project/dev/index.ts +++ b/src/handlers/project/dev/index.ts @@ -5,7 +5,6 @@ import { createInspectorHandler } from "../../../core/dev/inspector/server"; import type { InspectorDeps } from "../../../core/dev/inspector/types"; import { rewriteOtelEndpointForContainer } from "../../../core/dev/otel/collector"; import { findFreePort, resolveDevPort, resolveDevPorts } from "../../../core/dev/port"; -import { writeBoxDevEnvLocal } from "../../../core/dev/boxEnvLocal"; import { boxProfilePath, boxWorkloadPort } from "../../../core/project/templates/boxProfile"; import { projectSpecPath } from "../../../core/project/fsUtils"; import type { V0DeployRunner } from "../../../core/project/legacy/deploy"; @@ -394,9 +393,6 @@ async function runRuntimeDev({ runtimeNames, }); for (const message of synced.messages) renderStatus({ io: config.io, message, json }); - for (const message of await writeBoxDevEnvLocal(project.rootPath)) { - renderStatus({ io: config.io, message, json }); - } const runtimes = synced.project.spec.runtimes.filter(({ name }) => runtimeNames.includes(name), ); From d60bb17688788fb3af98beeea098925bb25cadcd Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 14:51:28 -0800 Subject: [PATCH 02/13] fix(dev): Address the review of #2862 - Build the expected warnings from ENV_LOCAL_RELATIVE_PATH, so the tests pass on Windows, where it is agentcore\.env.local. - Skip an env:// ref with a blank name, as parseBoxEnvRoutes did. - Pin that a box container gets the shell's key over .env.local's. - Remove parseBoxEnvRoutes and readBoxEnvRoutes, which no code calls since writeBoxDevEnvLocal went. - Check for the venv's Python, not only .venv: create --skip-install (#2857) leaves an empty .venv, which dev must not take for an installed one. --- src/core/dev/box.test.ts | 15 +++-- src/core/dev/box.ts | 6 +- src/core/dev/boxDevSecrets.test.ts | 10 ++-- src/core/dev/boxDevSecrets.ts | 2 +- src/core/dev/container.test.ts | 16 +++++ src/core/project/boxProfileEgress.test.ts | 72 +---------------------- src/core/project/boxProfileEgress.ts | 50 ---------------- 7 files changed, 40 insertions(+), 131 deletions(-) diff --git a/src/core/dev/box.test.ts b/src/core/dev/box.test.ts index 1c0c3e98b..e8d099df2 100644 --- a/src/core/dev/box.test.ts +++ b/src/core/dev/box.test.ts @@ -9,6 +9,7 @@ import type { DevEvent, DevRunner, DevServerInput } from "../../handlers/project import type { ProcessStreamer, StreamProcessOptions } from "../../io"; import { MissingToolError } from "../../io/exec"; import { BOX_INSTALL_HINT } from "../project/backends/boxRelease"; +import { ENV_LOCAL_RELATIVE_PATH } from "../project/envLocal"; import { BoxDevRunner } from "./box"; /** The line of a CodeZip profile that names its runtime's folder. */ @@ -45,7 +46,8 @@ async function scene( if (profiled) { await mkdir(join(projectRoot, ".box")); await writeFile(join(projectRoot, ".box", "profile.toml"), options.profile ?? PROFILE); - await mkdir(join(projectRoot, "app", "agent", ".venv"), { recursive: true }); + await mkdir(join(projectRoot, "app", "agent", ".venv", "bin"), { recursive: true }); + await writeFile(join(projectRoot, "app", "agent", ".venv", "bin", "python"), ""); } const calls: { command: string[]; options: StreamProcessOptions }[] = []; @@ -219,7 +221,8 @@ describe("BoxDevRunner", () => { message: "the box profile .box/profile.toml reads GITHUB_TOKEN for [egress.github], but it is " + "not set, and box does not start without it. Export it in this shell " + - "(export GITHUB_TOKEN=...) or put it in agentcore/.env.local, then restart dev.", + "(export GITHUB_TOKEN=...) or put it in " + + `${ENV_LOCAL_RELATIVE_PATH}, then restart dev.`, }); // box run still starts, so its own error follows the warning. expect(calls).toHaveLength(1); @@ -343,9 +346,13 @@ describe("BoxDevRunner", () => { ]); }); - test("tells the user to run uv sync when the runtime has no .venv", async () => { + test.each([ + ["has no .venv", true], + ["has the empty .venv that create --skip-install leaves", false], + ])("tells the user to run uv sync when the runtime %s", async (_, removeVenv) => { const { projectRoot, calls, runner } = await scene(true); - await rm(join(projectRoot, "app", "agent", ".venv"), { recursive: true }); + const venv = join(projectRoot, "app", "agent", ".venv"); + await rm(removeVenv ? venv : join(venv, "bin"), { recursive: true }); const run = collect(runner.run(input(projectRoot))); diff --git a/src/core/dev/box.ts b/src/core/dev/box.ts index 8225a9a67..b9d328279 100644 --- a/src/core/dev/box.ts +++ b/src/core/dev/box.ts @@ -79,10 +79,12 @@ export class BoxDevRunner implements DevRunner { `${input.port}. Free port ${listen}, then retry.`, ); } + // `create --skip-install` leaves an empty .venv, which `uv sync` fills; the profile runs its + // Python. const venv = join(input.projectRoot, input.runtime.codeLocation, ".venv"); - if (!existsSync(venv)) { + if (!existsSync(join(venv, "bin", "python"))) { throw new ResourceNotFoundError( - `${venv} does not exist. Run \`uv sync\` in ${input.runtime.codeLocation}, then retry.`, + `${venv} has no Python. Run \`uv sync\` in ${input.runtime.codeLocation}, then retry.`, ); } await this.checkTool("box", BOX_INSTALL_HINT); diff --git a/src/core/dev/boxDevSecrets.test.ts b/src/core/dev/boxDevSecrets.test.ts index b7d8667ef..565f03c01 100644 --- a/src/core/dev/boxDevSecrets.test.ts +++ b/src/core/dev/boxDevSecrets.test.ts @@ -3,7 +3,7 @@ import { existsSync } from "node:fs"; import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; -import { EnvLocalFile } from "../project/envLocal"; +import { ENV_LOCAL_RELATIVE_PATH, EnvLocalFile } from "../project/envLocal"; import { boxDevSecrets, missingBoxSecretWarning } from "./boxDevSecrets"; const GITHUB_ROUTE = @@ -72,9 +72,10 @@ describe("boxDevSecrets", () => { }); }); - test("leaves out a pack's variable and a secret that is not env://", async () => { + test("leaves out a pack's variable, a secret that is not env://, and a blank name", async () => { const root = await project( - 'packs = ["box/bedrock"]\n[egress.s3]\ndestinations = ["s3.amazonaws.com"]\nsecret.ref = "aws://default"\n', + 'packs = ["box/bedrock"]\n[egress.s3]\ndestinations = ["s3.amazonaws.com"]\nsecret.ref = "aws://default"\n' + + '[egress.blank]\ndestinations = ["blank.example.com"]\nsecret.ref = "env:// "\n', ); expect(await boxDevSecrets(root, { AWS_BEARER_TOKEN_BEDROCK: "token", default: "x" })).toEqual({ @@ -104,7 +105,8 @@ describe("missingBoxSecretWarning", () => { expect(missingBoxSecretWarning({ variable: "GITHUB_TOKEN", table: "[egress.github]" })).toBe( "the box profile .box/profile.toml reads GITHUB_TOKEN for [egress.github], but it is not " + "set, and box does not start without it. Export it in this shell " + - "(export GITHUB_TOKEN=...) or put it in agentcore/.env.local, then restart dev.", + "(export GITHUB_TOKEN=...) or put it in " + + `${ENV_LOCAL_RELATIVE_PATH}, then restart dev.`, ); }); }); diff --git a/src/core/dev/boxDevSecrets.ts b/src/core/dev/boxDevSecrets.ts index 9bcd8b888..0e6185ef4 100644 --- a/src/core/dev/boxDevSecrets.ts +++ b/src/core/dev/boxDevSecrets.ts @@ -42,7 +42,7 @@ export async function boxDevSecrets( const ref = (entry as { secret?: { ref?: unknown } } | null)?.secret?.ref; if (typeof ref !== "string" || !ref.startsWith(ENV_SCHEME)) continue; const variable = ref.slice(ENV_SCHEME.length); - if (variable === "" || variable in found) continue; + if (variable.trim() === "" || variable in found) continue; const value = env[variable]; if (!hasValue(value)) { if (!missing.some((other) => other.variable === variable)) { diff --git a/src/core/dev/container.test.ts b/src/core/dev/container.test.ts index df7088bd5..4b08b7749 100644 --- a/src/core/dev/container.test.ts +++ b/src/core/dev/container.test.ts @@ -1015,6 +1015,22 @@ describe("ContainerDevRunner", () => { expect(existsSync(join(root, "agentcore", ".env.local"))).toBe(false); }); + test("hands box in the container the shell's env:// key over .env.local's", async () => { + const { projectRuntime, root } = await boxedScene({ + profileText: + '[egress.github]\ndestinations = ["api.github.com"]\nsecret.ref = "env://GITHUB_TOKEN"\n', + }); + const { calls, runner } = harness({ + processEnv: { ...credentials, GITHUB_TOKEN: "ghp_shell" }, + }); + // input.env is what dev read from agentcore/.env.local. + const fromFile = input(root, projectRuntime); + + await collect(runner.run({ ...fromFile, env: { GITHUB_TOKEN: "ghp_file" } })); + + expect(parseEnv(commandCall(calls, "run").envFile!.contents).GITHUB_TOKEN).toBe("ghp_shell"); + }); + test("warns when the profile's env:// key is not set, before the container's box reports it", async () => { const { projectRuntime, root } = await boxedScene({ profileText: diff --git a/src/core/project/boxProfileEgress.test.ts b/src/core/project/boxProfileEgress.test.ts index 37a9e8ac1..6bb5d3d3d 100644 --- a/src/core/project/boxProfileEgress.test.ts +++ b/src/core/project/boxProfileEgress.test.ts @@ -1,73 +1,5 @@ -import { afterEach, describe, expect, test } from "bun:test"; -import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; -import { tmpdir } from "node:os"; -import { join } from "node:path"; -import { hasValue, parseBoxEnvRoutes, readBoxEnvRoutes } from "./boxProfileEgress"; - -describe("parseBoxEnvRoutes", () => { - test("lists each env:// route in profile order", () => { - expect( - parseBoxEnvRoutes( - '[egress.github]\nsecret.ref = "env://GITHUB_TOKEN"\n\n' + - '[egress.stripe]\nsecret.ref = "env://STRIPE_KEY"\n', - ), - ).toEqual({ - routes: [ - { route: "github", variable: "GITHUB_TOKEN" }, - { route: "stripe", variable: "STRIPE_KEY" }, - ], - }); - }); - - test("skips aws:// refs, routes with no secret, and env:// refs with no variable", () => { - expect( - parseBoxEnvRoutes( - '[egress.bedrock]\nsecret.ref = "aws://default"\n\n' + - '[egress.open]\nhost = "example.com"\n\n' + - '[egress.empty]\nsecret.ref = "env://"\n\n' + - '[egress.blank]\nsecret.ref = "env:// "\n', - ), - ).toEqual({ routes: [] }); - }); - - test("has no routes when egress is not a table", () => { - expect(parseBoxEnvRoutes('[[egress]]\nsecret.ref = "env://GITHUB_TOKEN"\n')).toEqual({ - routes: [], - }); - expect(parseBoxEnvRoutes('egress = "none"\n')).toEqual({ routes: [] }); - expect(parseBoxEnvRoutes("")).toEqual({ routes: [] }); - }); - - test("reports a profile that does not parse", () => { - const parsed = parseBoxEnvRoutes("[egress.github\n"); - - expect(parsed.routes).toEqual([]); - expect(parsed.error).toBeString(); - }); -}); - -describe("readBoxEnvRoutes", () => { - const directories: string[] = []; - afterEach(async () => { - await Promise.all(directories.splice(0).map((d) => rm(d, { recursive: true, force: true }))); - }); - - test("reads the project's .box/profile.toml, or is undefined with no profile", async () => { - const root = await mkdtemp(join(tmpdir(), "box-profile-egress-")); - directories.push(root); - expect(readBoxEnvRoutes(root)).toBeUndefined(); - - await mkdir(join(root, ".box")); - await writeFile( - join(root, ".box", "profile.toml"), - '[egress.github]\nsecret.ref = "env://GITHUB_TOKEN"\n', - ); - - expect(readBoxEnvRoutes(root)).toEqual({ - routes: [{ route: "github", variable: "GITHUB_TOKEN" }], - }); - }); -}); +import { describe, expect, test } from "bun:test"; +import { hasValue } from "./boxProfileEgress"; describe("hasValue", () => { test("is true only for a set, non-blank value", () => { diff --git a/src/core/project/boxProfileEgress.ts b/src/core/project/boxProfileEgress.ts index 0dcf867a8..c662ca051 100644 --- a/src/core/project/boxProfileEgress.ts +++ b/src/core/project/boxProfileEgress.ts @@ -1,56 +1,6 @@ -import { existsSync, readFileSync } from "node:fs"; -import { parse as parseToml } from "smol-toml"; -import { boxProfilePath } from "./templates/boxProfile"; - -const ENV_SCHEME = "env://"; - /** An `[egress.]` of the box profile whose `secret.ref` is `env://`. */ export type BoxEnvRoute = { route: string; variable: string }; -/** - * The `env://` routes of a box profile. `error` is set when the profile does not parse; `routes` - * is then empty. - */ -export type BoxEnvRoutes = { routes: BoxEnvRoute[]; error?: string }; - -/** - * The profile's own `[egress]` routes whose `secret.ref` is an `env://` reference, in profile - * order. A pack's routes, such as box/bedrock's, are not in the profile's own `[egress]` table, so - * they are not here. An `egress` that is not a table (an array of tables, or a scalar) has no - * routes, and nor does a ref with no variable after `env://`. - */ -export function parseBoxEnvRoutes(text: string): BoxEnvRoutes { - let table: Record; - try { - table = parseToml(text) as Record; - } catch (error) { - return { routes: [], error: error instanceof Error ? error.message : String(error) }; - } - const egress = table.egress; - if (typeof egress !== "object" || egress === null || Array.isArray(egress)) { - return { routes: [] }; - } - const routes: BoxEnvRoute[] = []; - for (const [route, entry] of Object.entries(egress as Record)) { - const ref = (entry as { secret?: { ref?: unknown } } | null)?.secret?.ref; - if (typeof ref !== "string" || !ref.startsWith(ENV_SCHEME)) continue; - const variable = ref.slice(ENV_SCHEME.length); - if (variable.trim() === "") continue; - routes.push({ route, variable }); - } - return { routes }; -} - -/** - * The `env://` routes of the box profile of the project at `projectRoot`, or `undefined` when the - * project has no box profile. - */ -export function readBoxEnvRoutes(projectRoot: string): BoxEnvRoutes | undefined { - const path = boxProfilePath(projectRoot); - if (!existsSync(path)) return undefined; - return parseBoxEnvRoutes(readFileSync(path, "utf8")); -} - /** Whether an environment value holds a key: set, and not blank. */ export function hasValue(value: string | undefined): value is string { return value !== undefined && value.trim() !== ""; From fcafbb66663859f7bc534633d16efb2a51bb14a7 Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 17:15:36 -0800 Subject: [PATCH 03/13] fix(box): Keep a CodeZip runtime's staged box out of git The box templates reuse the asset folders of the agents without box, whose .gitignore does not list .box-dist/ (agent-python-minimal has no .gitignore at all), so after a build 'git add .' committed the box binaries. stageBoxCodeZip now writes a .gitignore of '*' into .box-dist/, which covers every template and existing projects. The CodeZip packager reads no .gitignore, so the zip still carries the folder. A policy file named .gitignore at the top of the profile's folder is now refused, as the staged one would replace it. --- src/core/project/backends/boxCodeZip.test.ts | 4 +++- src/core/project/backends/boxCodeZip.ts | 9 ++++++++- src/core/project/boxNetworkSource.ts | 1 + 3 files changed, 12 insertions(+), 2 deletions(-) diff --git a/src/core/project/backends/boxCodeZip.test.ts b/src/core/project/backends/boxCodeZip.test.ts index 172172d82..ff1ad2f69 100644 --- a/src/core/project/backends/boxCodeZip.test.ts +++ b/src/core/project/backends/boxCodeZip.test.ts @@ -13,7 +13,7 @@ import { renderAgentCorePack, renderRuntimeBoxProfile, } from "../templates/boxProfile"; -import { stageBoxCodeZip } from "./boxCodeZip"; +import { BOX_DIST_GITIGNORE, stageBoxCodeZip } from "./boxCodeZip"; import type { BoxLinuxBuild } from "./boxRelease"; const directories: string[] = []; @@ -111,6 +111,8 @@ describe("stageBoxCodeZip", () => { expect(await readFile(join(dist, AGENTCORE_CODEZIP_PACK_PATH), "utf8")).toBe( renderAgentCoreCodeZipPack(), ); + // A template's own .gitignore may not list .box-dist/, so the folder ignores itself. + expect(await readFile(join(dist, ".gitignore"), "utf8")).toBe(BOX_DIST_GITIGNORE); }); test("asks for the box of the runtime's box.version", async () => { diff --git a/src/core/project/backends/boxCodeZip.ts b/src/core/project/backends/boxCodeZip.ts index a0dbbc80e..8e9bcbeb6 100644 --- a/src/core/project/backends/boxCodeZip.ts +++ b/src/core/project/backends/boxCodeZip.ts @@ -1,4 +1,4 @@ -import { chmodSync, copyFileSync, cpSync, mkdirSync, rmSync } from "node:fs"; +import { chmodSync, copyFileSync, cpSync, mkdirSync, rmSync, writeFileSync } from "node:fs"; import { join, posix } from "node:path"; import type { Project } from "../../../handlers/project/types"; import type { BoxNetwork } from "../boxNetwork"; @@ -6,6 +6,10 @@ import { boxNetworkEdits, runtimeProfileWriter, writeBoxNetworkFiles } from "../ import { BOX_CODEZIP_DIST, runtimeRunsInBox } from "../templates/boxProfile"; import { BOX_BINARIES, type BoxLinuxBuild } from "./boxRelease"; +/** The `.gitignore` staged into `.box-dist/`: build and deploy rewrite the folder every time. */ +export const BOX_DIST_GITIGNORE = + "# Written by agentcore build and deploy, which rewrite this folder.\n*\n"; + /** * Stages box into each CodeZip runtime that runs in a box ({@link runtimeRunsInBox}), * so the zip carries it: `/.box-dist/` gets box, its @@ -51,6 +55,9 @@ export async function stageBoxCodeZip( const folder = join(project.rootPath, ...dist.split("/")); rmSync(folder, { recursive: true, force: true }); mkdirSync(folder, { recursive: true }); + // Keeps the staged box out of git in every project, whatever its own .gitignore says. The zip + // still carries the folder: the CodeZip packager does not read .gitignore files. + writeFileSync(join(folder, ".gitignore"), BOX_DIST_GITIGNORE); for (const binary of BOX_BINARIES) { copyFileSync(join(build.binaries, binary), join(folder, binary)); chmodSync(join(folder, binary), 0o755); diff --git a/src/core/project/boxNetworkSource.ts b/src/core/project/boxNetworkSource.ts index 6d1d4d7ed..cc41eb4a9 100644 --- a/src/core/project/boxNetworkSource.ts +++ b/src/core/project/boxNetworkSource.ts @@ -249,6 +249,7 @@ const BOX_DIST_NAMES: ReadonlySet = new Set([ "resources", "ffi", "profile.toml", + ".gitignore", ]); /** From 380e748f509d9080e5cc1ac2f73f0177469c5d15 Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 17:26:59 -0800 Subject: [PATCH 04/13] fix(box): Turn OTEL off for every box template until traces work in a box On a CodeZip Runtime the L3 runs opentelemetry-instrument start.py, and start.py hands over to box run, so the agent in the box runs without it and sends no traces, as in a box container. The CodeZip box templates now write instrumentation.enableOtel false, as the container one does, and build warns for any box runtime with OTEL on, not only a container. Running the agent under opentelemetry-instrument in the box waits on a Box Core fix to the signing of X-Amzn-Trace-Id (plan Phase 15, SA-7). --- src/core/project/backends/cdk.test.ts | 71 ++++++++++++---------- src/core/project/backends/cdk.ts | 3 +- src/core/project/templates/runtime.test.ts | 16 +++++ src/core/project/templates/runtime.ts | 8 ++- 4 files changed, 60 insertions(+), 38 deletions(-) diff --git a/src/core/project/backends/cdk.test.ts b/src/core/project/backends/cdk.test.ts index 4f1c3caa8..fa38a99e2 100644 --- a/src/core/project/backends/cdk.test.ts +++ b/src/core/project/backends/cdk.test.ts @@ -329,41 +329,46 @@ describe("CdkBackend.build", () => { }); test.each([ - ["a box container", "box", true, true], - ["a box container with enableOtel false", "box", false, false], - ["a container outside a Box project", undefined, true, false], - ] as const)("warns that %s sends no traces: %p", async (_label, projectType, otel, warns) => { - const input = await project(); - input.spec = ProjectSpecSchema.parse({ - name: "example", - version: 2, - ...(projectType && { projectType }), - runtimes: [ - { - name: "agent", - build: "Container", - entrypoint: "main.py", - codeLocation: "app/agent", - ...(projectType && { box: { version: BOX_RELEASE.version } }), - ...(!otel && { instrumentation: { enableOtel: false } }), - }, - ], - agentCoreGateways: projectType ? [boxGatewaySpec("agent")] : [], - }); - await mkdir(join(input.rootPath, "app", "agent"), { recursive: true }); - await writeFile(join(input.rootPath, "app", "agent", "Dockerfile"), "FROM scratch\n"); + ["a box container", "box", "Container", true, true], + ["a box CodeZip runtime", "box", "CodeZip", true, true], + ["a box container with enableOtel false", "box", "Container", false, false], + ["a container outside a Box project", undefined, "Container", true, false], + ] as const)( + "warns that %s sends no traces: %p", + async (_label, projectType, build, otel, warns) => { + const input = await project(); + input.spec = ProjectSpecSchema.parse({ + name: "example", + version: 2, + ...(projectType && { projectType }), + runtimes: [ + { + name: "agent", + build, + ...(build === "CodeZip" && { runtimeVersion: "PYTHON_3_14" }), + entrypoint: "main.py", + codeLocation: "app/agent", + ...(projectType && { box: { version: BOX_RELEASE.version } }), + ...(!otel && { instrumentation: { enableOtel: false } }), + }, + ], + agentCoreGateways: projectType ? [boxGatewaySpec("agent")] : [], + }); + await mkdir(join(input.rootPath, "app", "agent"), { recursive: true }); + await writeFile(join(input.rootPath, "app", "agent", "Dockerfile"), "FROM scratch\n"); - const events = await collect(harness().backend.build(input, NO_BOX_NETWORKS)); + const events = await collect(harness().backend.build(input, NO_BOX_NETWORKS)); - const warning: ProjectEvent = { - type: "warning", - message: - "Runtime 'agent' runs its agent in a box, whose image does not run " + - "opentelemetry-instrument, so it sends no traces. Set instrumentation.enableOtel to false.", - }; - if (warns) expect(events).toContainEqual(warning); - else expect(events).not.toContainEqual(warning); - }); + const warning: ProjectEvent = { + type: "warning", + message: + "Runtime 'agent' runs its agent in a box, where the agent does not run under " + + "opentelemetry-instrument, so it sends no traces. Set instrumentation.enableOtel to false.", + }; + if (warns) expect(events).toContainEqual(warning); + else expect(events).not.toContainEqual(warning); + }, + ); test("warns but continues when the installed CDK is legacy", async () => { const input = await project(); diff --git a/src/core/project/backends/cdk.ts b/src/core/project/backends/cdk.ts index 183659dd7..f00f936df 100644 --- a/src/core/project/backends/cdk.ts +++ b/src/core/project/backends/cdk.ts @@ -254,14 +254,13 @@ export class CdkBackend implements ProjectBackend { for (const runtime of project.spec.runtimes) { if ( - runtime.build === "Container" && runtimeRunsInBox(project.spec, runtime) && (runtime.instrumentation?.enableOtel ?? true) ) { yield { type: "warning", message: - `Runtime '${runtime.name}' runs its agent in a box, whose image does not run ` + + `Runtime '${runtime.name}' runs its agent in a box, where the agent does not run under ` + `opentelemetry-instrument, so it sends no traces. Set instrumentation.enableOtel to false.`, }; } diff --git a/src/core/project/templates/runtime.test.ts b/src/core/project/templates/runtime.test.ts index cd5ca140a..e7632bf00 100644 --- a/src/core/project/templates/runtime.test.ts +++ b/src/core/project/templates/runtime.test.ts @@ -96,6 +96,22 @@ describe("runtime templates", () => { expect(await Bun.file(join(appDir, ".dockerignore")).exists()).toBe(isContainer); }); + // The agent in a box does not run under opentelemetry-instrument, CodeZip or container, so a box + // template turns OTEL off; any other template keeps it on. + test.each<[RuntimeTemplateShortcutName, boolean]>([ + ["agent-python-strands-box", false], + ["agent-python-strands-box-container", false], + ["agent-python-minimal-box", false], + ["agent-python-langchain-box", false], + ["a2a-python-strands-box", false], + ["agui-python-strands-box", false], + ["mcp-python-fastmcp-box", false], + ["agent-python-strands", true], + ])("%s writes enableOtel %p", async (template, enableOtel) => { + const { runtime } = await addTemplate("my_agent", template); + expect(runtime.instrumentation?.enableOtel ?? true).toBe(enableOtel); + }); + test("Bedrock Managed Agents keeps infrastructure overrides and its required policy", async () => { const { runtime, appDir, core } = await addTemplate("my_bma", "environment-python-bma", { infra: { diff --git a/src/core/project/templates/runtime.ts b/src/core/project/templates/runtime.ts index e496fe1e9..05722b94d 100644 --- a/src/core/project/templates/runtime.ts +++ b/src/core/project/templates/runtime.ts @@ -2,7 +2,7 @@ import { FsTreeNode } from "./fsTree"; import type { AssetSource } from "../source"; import type { RuntimeResourceConfig } from "../../../handlers/project/add/runtime/types"; import { DEFAULT_MODEL_IDS, type ProjectRuntime } from "../../../projectSchemas/runtime"; -import { isBoxedContainer } from "./boxProfile"; +import { hasBoxProfile } from "./boxProfile"; import { mergeSpecEntries } from "./spec"; import type { SpecEntries, TemplateRenderer, TemplateResolver } from "./types"; import type { @@ -132,8 +132,10 @@ function buildRuntimeSpec(input: RuntimeResourceConfig): ProjectRuntime { ...(scaffoldRuntimeInput.framework === "bma" && { bedrockManagedAgents: true, }), - // The boxed container's image does not run opentelemetry-instrument, so say so in agentcore.json. - ...(isBoxedContainer(scaffoldRuntimeInput) && { instrumentation: { enableOtel: false } }), + // The agent in a box does not run under opentelemetry-instrument: a container's image does not + // run it, and on CodeZip it wraps start.py, which hands over to box run. So say so in + // agentcore.json until traces work in a box. + ...(hasBoxProfile(scaffoldRuntimeInput) && { instrumentation: { enableOtel: false } }), ...(infra.envVars && { envVars: infra.envVars }), ...(infra.networkMode && { networkMode: infra.networkMode }), ...(infra.networkConfig && { networkConfig: infra.networkConfig }), From 0dce816e40edeb0c32d0bc4ced44f711567d9503 Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 17:31:58 -0800 Subject: [PATCH 05/13] fix(box): Advertise the Runtime's URL in a deployed A2A agent card serve() set AGENTCORE_RUNTIME_URL to http://localhost:9000/ for any target, and the CodeZip Runtime profile reused it. serve_a2a gives that variable precedence for the agent card URL, so a deployed boxed A2A agent advertised localhost, and clients that read the card connected to themselves. The override is now local only. On the Runtime the box/agentcore pack reads AGENTCORE_RUNTIME_URL into runtime.url, with serve_a2a's own fallback http://localhost:9000/ when the Runtime sets none, and the profile passes that to the agent. --- src/core/project/templates/boxProfile.test.ts | 20 ++++++++++++ src/core/project/templates/boxProfile.ts | 31 +++++++++++++------ 2 files changed, 42 insertions(+), 9 deletions(-) diff --git a/src/core/project/templates/boxProfile.test.ts b/src/core/project/templates/boxProfile.test.ts index 3b8670ad8..f83993cc9 100644 --- a/src/core/project/templates/boxProfile.test.ts +++ b/src/core/project/templates/boxProfile.test.ts @@ -363,6 +363,19 @@ describe("renderBoxProfile for AgentCore Runtime", () => { expect(profile.agent.env.AWS_DEFAULT_REGION).toBe("${{ inputs.aws.region }}"); }); + test("gives an A2A agent card the Runtime's own URL, not the local ingress port", () => { + const spec = { + name: "V3Demo", + runtimes: [{ name: "agent", build: "CodeZip", protocol: "A2A", modelProvider: "Bedrock" }], + agentCoreGateways: [], + } as unknown as ProjectSpec; + const profile = parse(renderRuntimeBoxProfile(spec, spec.runtimes[0]!)) as Record; + + // serve_a2a gives AGENTCORE_RUNTIME_URL precedence, so localhost here would send clients that + // read the card back to themselves. + expect(profile.agent.env.AGENTCORE_RUNTIME_URL).toBe("${{ inputs.runtime.url }}"); + }); + test("runs agent-python-strands from the zip with the Runtime's Python, read through the packs", () => { const text = renderBoxProfile( "V3Demo", @@ -905,6 +918,13 @@ describe("renderAgentCorePack", () => { expect(new RegExp(`^${inputs.aws.region.pattern}$`).test("us-west-2; rm")).toBe(false); }); + test("declares the A2A card URL input from the Runtime's AGENTCORE_RUNTIME_URL", () => { + const { inputs } = pack([]); + expect(inputs.runtime.url.from).toBe("env:AGENTCORE_RUNTIME_URL"); + // What serve_a2a advertises outside a box when the Runtime sets none. + expect(inputs.runtime.url.default).toBe("http://localhost:9000/"); + }); + test("declares one input per memory and carries each ID into the agent's environment", () => { const toml = pack([{ name: "agentMemory" }, { name: "notes" }]); expect(toml.inputs.memory.agentMemory.id.from).toBe("env:MEMORY_AGENTMEMORY_ID"); diff --git a/src/core/project/templates/boxProfile.ts b/src/core/project/templates/boxProfile.ts index cd49d5a86..f84cf4d73 100644 --- a/src/core/project/templates/boxProfile.ts +++ b/src/core/project/templates/boxProfile.ts @@ -295,6 +295,7 @@ function serve( workloadPort: number, reload: boolean, python = `${appDir}/.venv/bin/python`, + cardUrl = `http://localhost:${boxIngressPort(protocol)}/`, ): { command: string[]; env: Record } { if (protocol === "HTTP") { return { @@ -317,15 +318,13 @@ function serve( // The box starts the agent in the project folder, and boxy refuses a script path inside it, // so the module is found through PYTHONPATH. `agentcore dev` runs these without a reload too. const portVariable = { AGUI: "PORT", A2A: "A2A_PORT", MCP: "FASTMCP_PORT" }[protocol]; - // serve_a2a puts its listen port in the agent card's URL, but callers reach the agent only - // through box's ingress port, so the card names that port instead. - const cardUrl: Record = - protocol === "A2A" - ? { AGENTCORE_RUNTIME_URL: `http://localhost:${boxIngressPort(protocol)}/` } - : {}; + // serve_a2a puts its listen port in the agent card's URL, and AGENTCORE_RUNTIME_URL takes + // precedence. Locally, callers reach the agent only through box's ingress port, so the card names + // that port; on the Runtime, `cardUrl` is the Runtime's own value (see renderAgentCorePack). + const card: Record = protocol === "A2A" ? { AGENTCORE_RUNTIME_URL: cardUrl } : {}; return { command: [python, "-m", "main"], - env: { PYTHONPATH: appDir, [portVariable]: String(workloadPort), ...cardUrl }, + env: { PYTHONPATH: appDir, [portVariable]: String(workloadPort), ...card }, }; } @@ -397,7 +396,14 @@ function runtimeCodeZipRunner(protocol: Protocol, workloadPort: number): Runner const code = "${{ inputs.code.dir }}"; const python = "${{ inputs.python.path }}"; const pythonPrefix = "${{ inputs.python.prefix }}"; - const { command, env } = serve(protocol, code, workloadPort, false, python); + const { command, env } = serve( + protocol, + code, + workloadPort, + false, + python, + "${{ inputs.runtime.url }}", + ); return { command, env: { @@ -833,7 +839,14 @@ pattern = ${str(GATEWAY_URL_PATTERN)} [inputs.aws.region] description = "The AWS region the runtime runs in." from = "env:AWS_REGION" -pattern = ${str(AWS_REGION_PATTERN)}${memoryInputs} +pattern = ${str(AWS_REGION_PATTERN)} + +# The URL an A2A agent card advertises. Outside a box, serve_a2a reads AGENTCORE_RUNTIME_URL itself +# and otherwise names the contract port; the agent in the box gets the same value through this. +[inputs.runtime.url] +description = "The URL an A2A agent card advertises on the Runtime." +from = "env:AGENTCORE_RUNTIME_URL" +default = "http://localhost:9000/"${memoryInputs} ${agentEnv}`; } From a6c576794126d2bfcb827e7a6ef3b02a08046f09 Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 17:38:46 -0800 Subject: [PATCH 06/13] fix(box): Start every CodeZip box template on Python 3.10 start.py fell back to tomli on Python 3.10, which has no tomllib, but only agent-python-strands-box depends on tomli. The five other CodeZip box templates reuse the folders of the agents without box, so on PYTHON_3_10 start.py failed to import and the agent never started. start.py needs only the profile's 'policies' line, which deploy writes on one line with names of letters, digits, '.', '_', '-' and '/', so on Python 3.10 it reads that line as a JSON list. No template needs tomli now, so agent-python-strands-box drops it. --- .../agent-python-strands-box/pyproject.toml | 2 -- src/assets/templates/box-codezip/start.py | 24 +++++++++++++++---- 2 files changed, 20 insertions(+), 6 deletions(-) diff --git a/src/assets/templates/agent-python-strands-box/pyproject.toml b/src/assets/templates/agent-python-strands-box/pyproject.toml index 35b75fad9..2ded30441 100644 --- a/src/assets/templates/agent-python-strands-box/pyproject.toml +++ b/src/assets/templates/agent-python-strands-box/pyproject.toml @@ -12,8 +12,6 @@ dependencies = [ "aws-opentelemetry-distro ~= 0.21.0", "bedrock-agentcore[strands-agents] >= 1.18.1, < 2.0.0", "botocore[crt] ~= 1.43.0", - # start.py reads the box profile with tomllib, which Python 3.10 does not have. - "tomli >= 2.0.0; python_version < '3.11'", "strands-agents{{#if (eq modelProvider "Anthropic")}}[anthropic]{{else}}{{#if (or (eq modelProvider "OpenAI") (eq modelProvider "OpenAICompatible"))}}[openai]{{else}}{{#if (eq modelProvider "Gemini")}}[gemini]{{else}}{{#if (eq modelProvider "LiteLLM")}}[litellm]{{/if}}{{/if}}{{/if}}{{/if}} >= 1.62.0, < 2.0.0", ] diff --git a/src/assets/templates/box-codezip/start.py b/src/assets/templates/box-codezip/start.py index c3a7086f0..5e3d752c4 100644 --- a/src/assets/templates/box-codezip/start.py +++ b/src/assets/templates/box-codezip/start.py @@ -7,14 +7,16 @@ # directory from the environment through the box/agentcore and box/agentcore-codezip packs, and # signs AWS routes with the execution role through a bare `aws://`. So there is nothing to fill in, # no credentials to write, and no start.sh. +import json import os +import re import shutil import sys try: import tomllib -except ModuleNotFoundError: # Python 3.10: the template depends on tomli there. - import tomli as tomllib +except ModuleNotFoundError: # Python 3.10, which has no tomllib. + tomllib = None CODE = os.path.dirname(os.path.abspath(__file__)) DIST = os.path.join(CODE, ".box-dist") @@ -27,12 +29,26 @@ for directory in (HOME, WORKSPACE, PROFILE_DIR): os.makedirs(directory, exist_ok=True) +def staged_policies(path): + """The policy files the staged profile's `policies` names. + + Deploy writes `policies` on one line, with names of only letters, digits, ".", "_", "-" and + "/", so on Python 3.10 the line reads as a JSON list. The box templates reuse the folders of + the agents without box, so no template has to depend on tomli for it. + """ + with open(path, "rb") as handle: + text = handle.read() + if tomllib is not None: + return tomllib.loads(text.decode("utf-8")).get("policies", []) + match = re.search(rb"^policies = (\[.*\])$", text, re.MULTILINE) + return json.loads(match.group(1)) if match else [] + + # box reads a profile's policy files from beside it, so copy the profile and each file its # `policies` names out of the read-only zip, into this user's folder, outside the workspace. staged_profile = os.path.join(DIST, "profile.toml") shutil.copyfile(staged_profile, PROFILE) -with open(staged_profile, "rb") as handle: - policies = tomllib.load(handle).get("policies", []) +policies = staged_policies(staged_profile) for policy in policies: destination = os.path.join(PROFILE_DIR, policy) os.makedirs(os.path.dirname(destination), exist_ok=True) From e303e4bb9dc49d0a1400443be97fdf46a0779630 Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 17:38:46 -0800 Subject: [PATCH 07/13] fix(box): Name every box template, and test the real box shortcuts The error for a second runtime in a Box project named two box templates; there are seven. It now lists BOX_TEMPLATE_NAMES, taken from the shortcut table. The box profile tests forced boxTemplate onto templates without box, so nothing checked the box entries of the table; they now resolve the real box templates and check that the table marks each one. --- src/core/project/manager.box.test.ts | 5 +- src/core/project/manager.tsx | 6 +- src/core/project/templates/boxProfile.test.ts | 61 +++++++++---------- src/core/project/templates/project.ts | 4 +- src/handlers/project/shortcuts.ts | 4 ++ 5 files changed, 43 insertions(+), 37 deletions(-) diff --git a/src/core/project/manager.box.test.ts b/src/core/project/manager.box.test.ts index 2f57937fc..72ddb61ae 100644 --- a/src/core/project/manager.box.test.ts +++ b/src/core/project/manager.box.test.ts @@ -338,7 +338,10 @@ describe("gateway targets in a Box project", () => { await expect(add).rejects.toBeInstanceOf(ProjectStateError); await expect(add).rejects.toThrow( "cannot add runtime 'search': a Box project holds one runtime, which `agentcore create` " + - "makes from a box template", + "makes from a box template (agent-python-strands-box, agent-python-strands-box-container, " + + "agent-python-langchain-box, agent-python-minimal-box, a2a-python-strands-box, " + + "agui-python-strands-box, mcp-python-fastmcp-box), and every runtime of a Box project " + + "runs in a box. Create a separate project for this runtime.", ); expect(await specText(project)).toBe(before); expect(existsSync(join(project.rootPath, "app", "search"))).toBe(false); diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx index c2817e9d5..499e24377 100644 --- a/src/core/project/manager.tsx +++ b/src/core/project/manager.tsx @@ -70,6 +70,7 @@ import { } from "./templates/boxProfile"; import { assertBoxRuntimesHaveBoxVersion } from "./backends/boxContainer"; import { BOX_INSTALL_HINT } from "./backends/boxRelease"; +import { BOX_TEMPLATE_NAMES } from "../../handlers/project/shortcuts"; import { getRuntimeTemplateResolver } from "./templates/runtime"; import { EXPORT_NOTES_FILENAME, @@ -2261,9 +2262,8 @@ function assertNoSecondBoxRuntime(spec: z.infer, what: if (!isBoxProject(spec)) return; throw new ProjectStateError( `cannot add ${what}: a Box project holds one runtime, which \`agentcore ` + - "create` makes from a box template (agent-python-strands-box or " + - "agent-python-strands-box-container), and every runtime of a Box project runs in a box. " + - "Create a separate project for this runtime.", + `create\` makes from a box template (${BOX_TEMPLATE_NAMES.join(", ")}), and every runtime ` + + "of a Box project runs in a box. Create a separate project for this runtime.", ); } diff --git a/src/core/project/templates/boxProfile.test.ts b/src/core/project/templates/boxProfile.test.ts index f83993cc9..c021a8408 100644 --- a/src/core/project/templates/boxProfile.test.ts +++ b/src/core/project/templates/boxProfile.test.ts @@ -22,22 +22,19 @@ import { startsInBoxOnCodeZip, } from "./boxProfile"; -/** - * The scaffold input of a template, as a box template would give it: the renderer takes every - * template's shape, though create writes a profile only for the box templates. - */ +/** The scaffold input of a box template, as create resolves it from the shortcut table. */ function template(name: RuntimeTemplateShortcutName, overrides: Record = {}) { - return { - ...resolveRuntimeTemplateShortcut(name, { runtimeName: "agent", ...overrides }), - boxTemplate: true, - }; + const runtime = resolveRuntimeTemplateShortcut(name, { runtimeName: "agent", ...overrides }); + // The shortcut entry itself marks it a box template; the tests do not force it. + expect(runtime.boxTemplate).toBe(true); + return runtime; } function profile(name: RuntimeTemplateShortcutName, overrides: Record = {}) { return parse(renderBoxProfile("V3Demo", template(name, overrides))!) as Record; } -const STRANDS = template("agent-python-strands"); +const STRANDS = template("agent-python-strands-box"); const VENV_GRANTS = { read: [ @@ -87,7 +84,7 @@ describe("renderBoxProfile", () => { }); test("names itself after the project, so `box run .box/profile.toml` can load it by its path", () => { - expect(profile("agent-python-minimal").profile).toEqual({ name: "V3Demo" }); + expect(profile("agent-python-minimal-box").profile).toEqual({ name: "V3Demo" }); expect(renderBoxProfile("V3Demo", STRANDS)).toContain("Run `box run .box/profile.toml`"); }); @@ -97,7 +94,7 @@ describe("renderBoxProfile", () => { expect(text).not.toMatch(/"\/(Users|home)\//); }); - test.each(["agent-python-minimal", "agent-python-langchain"] as const)( + test.each(["agent-python-minimal-box", "agent-python-langchain-box"] as const)( "runs %s with uvicorn on Bedrock, like the Strands agent", (name) => { const { packs, agent, egress } = profile(name); @@ -109,9 +106,9 @@ describe("renderBoxProfile", () => { ); test.each([ - ["agui-python-strands", "PORT", 8080], - ["a2a-python-strands", "A2A_PORT", 9000], - ["mcp-python-fastmcp", "FASTMCP_PORT", 8000], + ["agui-python-strands-box", "PORT", 8080], + ["a2a-python-strands-box", "A2A_PORT", 9000], + ["mcp-python-fastmcp-box", "FASTMCP_PORT", 8000], ] as const)("runs %s as a module on its own port, one above dev's", (name, variable, devPort) => { const { agent } = profile(name); expect(agent.command).toEqual(["${{ workspace }}/app/agent/.venv/bin/python", "-m", "main"]); @@ -124,16 +121,18 @@ describe("renderBoxProfile", () => { }); test("names box's ingress port, not the agent's, in the A2A agent card", () => { - const { agent } = profile("a2a-python-strands"); + const { agent } = profile("a2a-python-strands-box"); expect(agent.env).toMatchObject({ A2A_PORT: "9001", AGENTCORE_RUNTIME_URL: "http://localhost:9000/", }); - expect(profile("agui-python-strands").agent.env).not.toHaveProperty("AGENTCORE_RUNTIME_URL"); + expect(profile("agui-python-strands-box").agent.env).not.toHaveProperty( + "AGENTCORE_RUNTIME_URL", + ); }); test("gives the MCP server no route, because it calls no model", () => { - const mcp = profile("mcp-python-fastmcp"); + const mcp = profile("mcp-python-fastmcp-box"); expect(mcp.packs).toEqual(["box/base"]); expect(mcp.options).toBeUndefined(); expect(mcp.egress).toBeUndefined(); @@ -192,7 +191,7 @@ describe("renderBoxProfile", () => { ] as const)( "routes %s model calls with the API key from the environment, and not through Bedrock", (provider, overrides, route, expected) => { - const { packs, options, egress } = profile("agent-python-strands", { + const { packs, options, egress } = profile("agent-python-strands-box", { modelProvider: provider as ModelProvider, apiKey: "sk-test", ...overrides, @@ -204,7 +203,7 @@ describe("renderBoxProfile", () => { ); test("routes a LiteLLM agent on a bedrock/ model through Bedrock", () => { - const { packs, egress } = profile("agent-python-strands", { modelProvider: "LiteLLM" }); + const { packs, egress } = profile("agent-python-strands-box", { modelProvider: "LiteLLM" }); expect(packs).toEqual(["box/base", "box/bedrock"]); expect(egress).toEqual({ bedrock: { secret: { ref: "aws://default" } } }); }); @@ -216,7 +215,7 @@ describe("renderBoxProfile", () => { ] as const)( "reads a LiteLLM %s key created without --api-key from LiteLLM's own variable", (modelId, route, variable) => { - const runtime = template("agent-python-strands", { modelProvider: "LiteLLM", modelId }); + const runtime = template("agent-python-strands-box", { modelProvider: "LiteLLM", modelId }); const { egress } = parse(renderBoxProfile("V3Demo", runtime)!) as { egress: Record; }; @@ -231,16 +230,16 @@ describe("renderBoxProfile", () => { test("does not warn when the LiteLLM agent has a key, or calls Bedrock", () => { const keyed = { modelProvider: "LiteLLM", modelId: "openai/gpt-4o", apiKey: "sk-test" }; - expect(boxProfileWarnings(template("agent-python-strands", keyed))).toEqual([]); + expect(boxProfileWarnings(template("agent-python-strands-box", keyed))).toEqual([]); expect( - boxProfileWarnings(template("agent-python-strands", { modelProvider: "LiteLLM" })), + boxProfileWarnings(template("agent-python-strands-box", { modelProvider: "LiteLLM" })), ).toEqual([]); }); test("warns that a LiteLLM agent on a provider with no route gets no model route", () => { const groq = { modelProvider: "LiteLLM", modelId: "groq/llama3", apiKey: "sk-test" }; - expect(profile("agent-python-strands", groq).egress).toBeUndefined(); - expect(boxProfileWarnings(template("agent-python-strands", groq))).toEqual([ + expect(profile("agent-python-strands-box", groq).egress).toBeUndefined(); + expect(boxProfileWarnings(template("agent-python-strands-box", groq))).toEqual([ "the box profile has no route for the LiteLLM model 'groq/llama3': add an [egress.groq] " + "section with its provider's host to .box/profile.toml, or the box blocks the agent's " + "model calls", @@ -255,7 +254,7 @@ describe("renderBoxProfile", () => { }); test("keeps the port of an OpenAI-compatible endpoint in its destination", () => { - const { egress } = profile("agent-python-strands", { + const { egress } = profile("agent-python-strands-box", { modelProvider: "OpenAICompatible", modelId: "llama3", apiKey: "sk-test", @@ -267,7 +266,7 @@ describe("renderBoxProfile", () => { test("gives an OpenAI-compatible agent with no base URL no route, rather than OpenAI's", () => { // The schema requires --api-base, so drop it from a valid input; the type still allows it. const runtime = { - ...template("agent-python-strands", { + ...template("agent-python-strands-box", { modelProvider: "OpenAICompatible", modelId: "llama3", apiKey: "sk-test", @@ -281,7 +280,7 @@ describe("renderBoxProfile", () => { }); test("names the provider section generically for a LiteLLM model ID with no prefix", () => { - const runtime = template("agent-python-strands", { + const runtime = template("agent-python-strands-box", { modelProvider: "LiteLLM", modelId: "gpt-4o", apiKey: "sk-test", @@ -379,7 +378,7 @@ describe("renderBoxProfile for AgentCore Runtime", () => { test("runs agent-python-strands from the zip with the Runtime's Python, read through the packs", () => { const text = renderBoxProfile( "V3Demo", - template("agent-python-strands"), + template("agent-python-strands-box"), "us-west-2", "runtime", )!; @@ -421,7 +420,7 @@ describe("renderBoxProfile for AgentCore Runtime", () => { }); }); - test.each(["agent-python-strands-container"] as const)( + test.each(["agent-python-strands-box-container"] as const)( "runs %s from /app without --reload, signing calls with the Runtime's role", (name) => { const text = renderBoxProfile("V3Demo", template(name), "us-west-2", "runtime")!; @@ -462,14 +461,14 @@ describe("renderBoxProfile for AgentCore Runtime", () => { ); test("serves the MCP server on all interfaces on the Runtime", () => { - const mcp = runtimeProfile("mcp-python-fastmcp"); + const mcp = runtimeProfile("mcp-python-fastmcp-box"); expect(mcp.agent.ingress).toEqual([{ listen: "0.0.0.0:8000", workload_port: 8001 }]); // The template has no default Memory route; build and deploy add it when the project has one. expect(mcp.egress).toBeUndefined(); }); test("gives a non-Bedrock model no route, since its key comes from AgentCore Identity", () => { - const openai = runtimeProfile("agent-python-strands", { + const openai = runtimeProfile("agent-python-strands-box", { modelProvider: "OpenAI", apiKey: "sk-test", }); diff --git a/src/core/project/templates/project.ts b/src/core/project/templates/project.ts index 68db3b9f0..0e2b8fc76 100644 --- a/src/core/project/templates/project.ts +++ b/src/core/project/templates/project.ts @@ -44,8 +44,8 @@ export async function createProjectTree( const template = await resolver.resolve(runtimeConfig); if (startsInBoxOnCodeZip(options.runtime)) withBoxStartScript(config, template); if (isBoxedContainer(options.runtime)) withBoxContainerBoxVersion(template); - // Only a box template (agent-python-strands-box or agent-python-strands-box-container) runs its - // agent in a box, so only it makes a Box project. + // Only a box template (BOX_TEMPLATE_NAMES) runs its agent in a box, so only it makes a Box + // project. templates.push( hasBoxProfile(options.runtime) ? { ...template, spec: { ...template.spec, projectType: "box" } } diff --git a/src/handlers/project/shortcuts.ts b/src/handlers/project/shortcuts.ts index 099730d58..05f7b81cc 100644 --- a/src/handlers/project/shortcuts.ts +++ b/src/handlers/project/shortcuts.ts @@ -387,6 +387,10 @@ export const PROJECT_TEMPLATE_NAMES = [ EMPTY_TEMPLATE_NAME, ] as unknown as readonly [TemplateName, ...TemplateName[]]; +/** The box templates, which run their agent in a box, in `--template` order. */ +export const BOX_TEMPLATE_NAMES: readonly RuntimeTemplateShortcutName[] = + RUNTIME_TEMPLATE_SHORTCUT_NAMES.filter((name) => RUNTIME_TEMPLATE_SHORTCUTS[name].box); + /** * Long-form `--template` help generated from the same registry used to resolve * templates and populate the TUI. Project creation also offers the empty From 690e3c3741e68af0c10c46d5834aad578324ea09 Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 19:04:28 -0800 Subject: [PATCH 08/13] fix(box): Start a CodeZip agent's box in its own folder under dev Every local CodeZip profile has [project] access = "write", and dev started box in the project root, so the agent could read and write the whole project: agentcore/.env.local with the model provider's real key, which the keyed route keeps from it, and .git/hooks, agentcore/cdk and agentcore.json, which run outside the box on the next commit or deploy. The local CodeZip profile now names the agent's own folder as ${{ workspace }}, and its header names that folder. dev, build and deploy start box there, with the profile at ../../.box/profile.toml, so the project grant covers app/ and nothing else. A profile written before still runs from the project root. --- src/core/dev/box.test.ts | 26 +++++++++++- src/core/dev/box.ts | 17 +++++--- src/core/project/boxNetworkSource.ts | 15 +++++-- src/core/project/boxProfileResolver.ts | 25 +++++++++--- src/core/project/templates/boxProfile.test.ts | 40 ++++++++++++++----- src/core/project/templates/boxProfile.ts | 31 +++++++++++--- 6 files changed, 122 insertions(+), 32 deletions(-) diff --git a/src/core/dev/box.test.ts b/src/core/dev/box.test.ts index e8d099df2..6e38a1a86 100644 --- a/src/core/dev/box.test.ts +++ b/src/core/dev/box.test.ts @@ -9,6 +9,8 @@ import type { DevEvent, DevRunner, DevServerInput } from "../../handlers/project import type { ProcessStreamer, StreamProcessOptions } from "../../io"; import { MissingToolError } from "../../io/exec"; import { BOX_INSTALL_HINT } from "../project/backends/boxRelease"; +import { renderBoxProfile } from "../project/templates/boxProfile"; +import { resolveRuntimeTemplateShortcut } from "../../handlers/project/shortcuts"; import { ENV_LOCAL_RELATIVE_PATH } from "../project/envLocal"; import { BoxDevRunner } from "./box"; @@ -129,7 +131,7 @@ describe("BoxDevRunner", () => { expect(fallbackRuns).toHaveLength(1); }); - test("runs the project's box profile from the project folder", async () => { + test("runs a profile written before from the project folder", async () => { const { projectRoot, calls, fallbackRuns, runner } = await scene(true); const events = await collect(runner.run(input(projectRoot))); @@ -146,6 +148,28 @@ describe("BoxDevRunner", () => { ]); }); + test("starts box in the runtime's folder for a profile create writes now", async () => { + // So the agent's workspace, and the project grant, are app/agent and nothing else of the + // project: not agentcore/.env.local, which holds the model's key. + const runtime = resolveRuntimeTemplateShortcut("agent-python-strands-box", { + runtimeName: "agent", + }); + const { projectRoot, calls, runner } = await scene(true, true, { + profile: renderBoxProfile("Demo", runtime)!, + }); + + const events = await collect(runner.run(input(projectRoot))); + + expect(calls.map(({ command }) => command)).toEqual([ + ["box", "run", "../../.box/profile.toml", "--no-banner"], + ]); + expect(calls[0]!.options.cwd).toBe(join(projectRoot, "app", "agent")); + expect(events).toContainEqual({ + type: "status", + message: "Starting the agent in a box (box run ../../.box/profile.toml)", + }); + }); + test("hands box run the .env.local values, so it can attach the API key, and not dev's OTEL ones", async () => { const { projectRoot, calls, runner } = await scene(true); diff --git a/src/core/dev/box.ts b/src/core/dev/box.ts index b9d328279..ecbcc277e 100644 --- a/src/core/dev/box.ts +++ b/src/core/dev/box.ts @@ -1,5 +1,5 @@ import { existsSync, readFileSync } from "node:fs"; -import { join } from "node:path"; +import { join, posix } from "node:path"; import { InputValidationError, ProjectStateError, ResourceNotFoundError } from "../../errors"; import type { DevEvent, DevRunner, DevServerInput } from "../../handlers/project/dev/types"; import { streamProcess, type ProcessStreamer } from "../../io"; @@ -11,6 +11,7 @@ import { boxIngressPort, boxProfileIsFor, boxProfilePath, + boxStartFolder, runsInBox, } from "../project/templates/boxProfile"; @@ -64,7 +65,8 @@ export class BoxDevRunner implements DevRunner { return; } const hasProfile = existsSync(profile); - if (!hasProfile || !boxProfileIsFor(readFileSync(profile, "utf8"), input.runtime)) { + const profileText = hasProfile ? readFileSync(profile, "utf8") : ""; + if (!hasProfile || !boxProfileIsFor(profileText, input.runtime)) { throw new ResourceNotFoundError( `runtime "${input.runtime.name}" runs its agent in a box (it has box.version in ` + `agentcore.json), but ${profile} ` + @@ -101,12 +103,17 @@ export class BoxDevRunner implements DevRunner { for (const missing of secrets.missing) { yield { type: "status", message: missingBoxSecretWarning(missing) }; } + // box starts in the folder the profile names, the runtime's own for a CodeZip profile, so the + // agent reaches no other folder of the project; box finds the profile from there. + const startFolder = boxStartFolder(profileText); + const cwd = join(input.projectRoot, ...startFolder.split("/").filter(Boolean)); + const profileArg = posix.relative(startFolder, BOX_PROFILE_FILE); yield { type: "status", - message: `Starting the agent in a box (box run ${BOX_PROFILE_FILE})`, + message: `Starting the agent in a box (box run ${profileArg})`, }; - yield* this.streamProcess(["box", "run", BOX_PROFILE_FILE, "--no-banner"], { - cwd: input.projectRoot, + yield* this.streamProcess(["box", "run", profileArg, "--no-banner"], { + cwd, env: { ...this.processEnv, ...fileEnv, ...secrets.env }, signal: input.signal, }); diff --git a/src/core/project/boxNetworkSource.ts b/src/core/project/boxNetworkSource.ts index cc41eb4a9..c3c1a6088 100644 --- a/src/core/project/boxNetworkSource.ts +++ b/src/core/project/boxNetworkSource.ts @@ -13,7 +13,12 @@ import { InvalidEnvironmentError, ProjectStateError } from "../../errors/errors" import type { PolicyFileCopy } from "./backends/boxContainer"; import { DEFAULT_EGRESS_BEDROCK_REGION } from "../../handlers/project/shortcuts"; import { addBoxGatewayTargets, BOX_BEDROCK_POLICY_FILE, BOX_MEMORY_POLICY_FILE } from "./boxMemory"; -import { BOX_PROFILE_FILE, boxProfilePath, runtimeRunsInBox } from "./templates/boxProfile"; +import { + BOX_PROFILE_FILE, + boxProfilePath, + boxStartFolder, + runtimeRunsInBox, +} from "./templates/boxProfile"; import { boxGatewayOf, buildBoxNetwork, @@ -118,10 +123,11 @@ async function readResolvedPolicy( // a failure of its own stops build either way, so Box resolves it as it is. const forRegion = named.ok && files.failures.length === 0 ? profileForRegion(text, region) : undefined; + const startFolder = boxStartFolder(text); const resolved = forRegion === undefined - ? await resolver.resolve(projectRoot, BOX_PROFILE_FILE) - : await resolveCopy(projectRoot, resolver, forRegion, files.texts); + ? await resolver.resolve(projectRoot, BOX_PROFILE_FILE, startFolder) + : await resolveCopy(projectRoot, resolver, forRegion, files.texts, startFolder); const profile = parseResolvedProfile(resolved, named.ok ? named.files : [], BOX_PROFILE_FILE); const policy = parseResolvedPolicy({ ...profile.profile, places }, resolved.policy, files.texts); return { @@ -191,6 +197,7 @@ async function resolveCopy( resolver: BoxProfileResolver, text: string, policies: readonly PolicyFileText[], + startFolder: string, ): Promise { const folder = realpathSync(await mkdtemp(join(tmpdir(), "agentcore-box-profile-"))); const copy = join(folder, "profile.toml"); @@ -201,7 +208,7 @@ async function resolveCopy( await mkdir(dirname(to), { recursive: true }); await writeFile(to, policy.text); } - return await resolver.resolve(projectRoot, copy); + return await resolver.resolve(projectRoot, copy, startFolder); } catch (error) { if (!(error instanceof InvalidEnvironmentError)) throw error; throw new InvalidEnvironmentError( diff --git a/src/core/project/boxProfileResolver.ts b/src/core/project/boxProfileResolver.ts index 36466d008..2e50ef389 100644 --- a/src/core/project/boxProfileResolver.ts +++ b/src/core/project/boxProfileResolver.ts @@ -4,7 +4,7 @@ * Box adds already in them, so build reads them rather than compiling the profile itself. */ import { realpathSync } from "node:fs"; -import { isAbsolute, relative, sep } from "node:path"; +import { isAbsolute, join, posix, relative, sep } from "node:path"; import { z } from "zod"; import { InvalidEnvironmentError } from "../../errors/errors"; import { ProcessFailedError, streamProcess, type ProcessStreamer } from "../../io"; @@ -33,9 +33,16 @@ export interface ResolvedBoxProfile { readonly warnings: readonly string[]; } -/** Resolves the box profile at `profilePath`, relative to `projectRoot`, as a run there gets it. */ +/** + * Resolves the box profile at `profilePath`, relative to `projectRoot`, as a run there gets it: + * box starts in `startFolder`, from the project root, as `agentcore dev` starts it. + */ export interface BoxProfileResolver { - resolve(projectRoot: string, profilePath: string): Promise; + resolve( + projectRoot: string, + profilePath: string, + startFolder?: string, + ): Promise; } /** The box release that `boxRelease.json` pins, which each error that asks for a box names. */ @@ -122,13 +129,19 @@ export class BoxCliProfileResolver implements BoxProfileResolver { this.streamProcess = config.streamProcess ?? streamProcess; } - public async resolve(projectRoot: string, profilePath: string): Promise { - const command = ["box", "profile", "show", profilePath, "--format", "json", "--full"]; + public async resolve( + projectRoot: string, + profilePath: string, + startFolder = "", + ): Promise { + // box takes a relative profile path from the folder it starts in. + const shown = isAbsolute(profilePath) ? profilePath : posix.relative(startFolder, profilePath); + const command = ["box", "profile", "show", shown, "--format", "json", "--full"]; const stdout: string[] = []; const stderr: string[] = []; try { const events = this.streamProcess(command, { - cwd: projectRoot, + cwd: join(projectRoot, ...startFolder.split("/").filter(Boolean)), env: { ...this.env, NO_COLOR: "1" }, }); for await (const event of events) { diff --git a/src/core/project/templates/boxProfile.test.ts b/src/core/project/templates/boxProfile.test.ts index c021a8408..c70f28d1a 100644 --- a/src/core/project/templates/boxProfile.test.ts +++ b/src/core/project/templates/boxProfile.test.ts @@ -14,6 +14,7 @@ import { boxGatewaySpec, type ProjectSpec } from "../../../projectSchemas/projec import type { ProjectRuntime } from "../../../projectSchemas/runtime"; import { boxProfileWarnings, + boxStartFolder, hasBoxProfile, renderAgentCoreCodeZipPack, renderAgentCorePack, @@ -38,27 +39,27 @@ const STRANDS = template("agent-python-strands-box"); const VENV_GRANTS = { read: [ - "${{ workspace }}/app/agent", - { path: "${{ workspace }}/app/agent/.venv", optional: true }, + "${{ workspace }}", + { path: "${{ workspace }}/.venv", optional: true }, { path: "${{ home }}/.local/share/uv/python", optional: true }, ], exec: [ - { path: "${{ workspace }}/app/agent/.venv", optional: true }, + { path: "${{ workspace }}/.venv", optional: true }, { path: "${{ home }}/.local/share/uv/python", optional: true }, ], - deny_write: [{ path: "${{ workspace }}/app/agent/.venv", optional: true }], + deny_write: [{ path: "${{ workspace }}/.venv", optional: true }], }; const UVICORN = [ - "${{ workspace }}/app/agent/.venv/bin/python", + "${{ workspace }}/.venv/bin/python", "-m", "uvicorn", "main:app", "--app-dir", - "${{ workspace }}/app/agent", + "${{ workspace }}", "--reload", "--reload-dir", - "${{ workspace }}/app/agent", + "${{ workspace }}", "--host", "127.0.0.1", "--port", @@ -83,9 +84,26 @@ describe("renderBoxProfile", () => { }); }); - test("names itself after the project, so `box run .box/profile.toml` can load it by its path", () => { + test("names itself after the project, and the folder `agentcore dev` starts box in", () => { expect(profile("agent-python-minimal-box").profile).toEqual({ name: "V3Demo" }); - expect(renderBoxProfile("V3Demo", STRANDS)).toContain("Run `box run .box/profile.toml`"); + const text = renderBoxProfile("V3Demo", STRANDS)!; + expect(text).toContain("runs `box run ../../.box/profile.toml` there"); + expect(boxStartFolder(text)).toBe("app/agent"); + }); + + // agentcore dev starts box in app/, so ${{ workspace }} and the project grant are that + // folder: agentcore/.env.local, with the model's key, .git and agentcore/cdk lie outside them. + test("grants the agent its own folder and no other folder of the project", () => { + const { project, agent, tool } = profile("agent-python-strands-box", { + modelProvider: "OpenAI", + apiKey: "sk-test", + }); + expect(project).toEqual({ access: "write" }); + for (const grant of [...agent.filesystem.read, ...agent.filesystem.exec]) { + const path = typeof grant === "string" ? grant : grant.path; + expect(path).not.toMatch(/agentcore|\.git|\.\./); + } + expect(JSON.stringify(tool)).not.toMatch(/agentcore|\.git|\.\./); }); test("names no host path, so the profile works on any machine and after a move", () => { @@ -111,9 +129,9 @@ describe("renderBoxProfile", () => { ["mcp-python-fastmcp-box", "FASTMCP_PORT", 8000], ] as const)("runs %s as a module on its own port, one above dev's", (name, variable, devPort) => { const { agent } = profile(name); - expect(agent.command).toEqual(["${{ workspace }}/app/agent/.venv/bin/python", "-m", "main"]); + expect(agent.command).toEqual(["${{ workspace }}/.venv/bin/python", "-m", "main"]); expect(agent.env).toMatchObject({ - PYTHONPATH: "${{ workspace }}/app/agent", + PYTHONPATH: "${{ workspace }}", [variable]: String(devPort + 1), }); expect(agent.ingress).toEqual([{ listen: `127.0.0.1:${devPort}`, workload_port: devPort + 1 }]); diff --git a/src/core/project/templates/boxProfile.ts b/src/core/project/templates/boxProfile.ts index f84cf4d73..256e56851 100644 --- a/src/core/project/templates/boxProfile.ts +++ b/src/core/project/templates/boxProfile.ts @@ -1,4 +1,4 @@ -import { join } from "node:path"; +import { join, posix } from "node:path"; import { InputValidationError } from "../../../errors/errors"; import { DEFAULT_EGRESS_BEDROCK_REGION, @@ -152,9 +152,24 @@ export function boxProfileIsFor( profileText: string, runtime: { build: string; codeLocation: string }, ): boolean { - const codeZip = profileText.includes("${{ workspace }}/app/"); + const folder = boxStartFolder(profileText); + // A profile from before box started in the runtime's folder names that folder in its paths. + const codeZip = folder !== "" || profileText.includes("${{ workspace }}/app/"); if (runtime.build === "Container") return !codeZip; - return profileText.includes(`/${runtime.codeLocation}"`); + const code = runtime.codeLocation.replace(/\/+$/, ""); + return folder === code || profileText.includes(`/${runtime.codeLocation}"`); +} + +/** The header line of a CodeZip profile that names the folder `agentcore dev` starts box in. */ +const START_FOLDER_LINE = /^# Written by `agentcore create` for (\S+?): /m; + +/** + * The folder, from the project root, that box starts a run or a resolution of the profile in: the + * runtime's code folder for a CodeZip profile, so the agent's grants reach no further than it, and + * the project root ("") for the container profile and for profiles written before. + */ +export function boxStartFolder(profileText: string): string { + return START_FOLDER_LINE.exec(profileText)?.[1] ?? ""; } /** The Strands box container template, whose image starts `box run` in /app. */ @@ -452,7 +467,11 @@ export function renderBoxProfile( if (!hasBoxProfile(runtime)) return undefined; const protocol = runtime.protocol ?? "HTTP"; - const appDir = `\${{ workspace }}/app/${runtime.runtimeName}`; + // `agentcore dev` starts box in the runtime's folder, so the agent can read and write that folder + // and nothing else of the project: not agentcore/.env.local, with the model's key, nor .git or + // agentcore/cdk, which run outside the box. + const codeFolder = `app/${runtime.runtimeName}`; + const appDir = "${{ workspace }}"; const ingressPort = boxIngressPort(protocol); const workloadPort = boxWorkloadPort(protocol); const onRuntime = target === "runtime"; @@ -489,7 +508,9 @@ export function renderBoxProfile( ? "# Rendered by agentcore build and deploy from agentcore.json, for AgentCore Runtime. The box/agentcore pack carries the deployed resources' variables." : container ? "# Written by `agentcore create` for the agent's image, to run with `box run` in /app." - : `# Written by \`agentcore create\`. Run \`box run ${BOX_PROFILE_FILE}\` in the project folder.`; + : `# Written by \`agentcore create\` for ${codeFolder}: \`agentcore dev\` runs \`box run ` + + `${posix.relative(codeFolder, BOX_PROFILE_FILE)}\` there, so the agent can reach no other ` + + "folder of the project."; const regionComment = onRuntime ? "" : "# The AWS region `agentcore create` resolved. Change it to call Bedrock in another region\n" + From 1b5b151e723e9f4ac0a47e1750cc7c2f7e80f204 Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 19:24:43 -0800 Subject: [PATCH 09/13] fix(box): Refresh a box route's stored key when its variable changes Build stored a route's key in .env.local as AGENTCORE_CREDENTIAL_ on the first build only. After a rotation, with GITHUB_TOKEN=ghp_new in the shell and ghp_old stored, dev used the new key but deploy provisioned the old one, and the deployed agent got a 401. Build now replaces the stored key, and says so, when the route's variable holds a different one, picked as dev picks it; deploy already updates an existing provider. The local testing guide says so, and its troubleshooting tells box-integration users to delete the variables earlier builds copied into .env.local. --- docs/box-local-testing.md | 9 ++++- src/core/project/boxNetworkWriters.ts | 2 +- .../project/boxProfileCredentials.test.ts | 36 +++++++++++++++++ src/core/project/boxProfileCredentials.ts | 21 ++++++++-- src/core/project/envLocal.test.ts | 32 +++++++++++++++ src/core/project/envLocal.ts | 39 +++++++++++++++++++ src/core/project/manager.tsx | 3 +- 7 files changed, 135 insertions(+), 7 deletions(-) diff --git a/docs/box-local-testing.md b/docs/box-local-testing.md index 292777f27..a7b9d1ae7 100644 --- a/docs/box-local-testing.md +++ b/docs/box-local-testing.md @@ -150,7 +150,9 @@ npm install "$L3"/aws-agentcore-cdk-*.tgz Export `GITHUB_TOKEN` before build. Build reads it and writes its value into `agentcore/.env.local` under the credential's reserved name `AGENTCORE_CREDENTIAL_GITHUB`. -Build does this on **every** run, so you set only the one variable the box already uses. +On a later build it replaces that value when `GITHUB_TOKEN` holds a different key, as after a +rotation, so deploy provisions the key `agentcore dev` uses. A build with `GITHUB_TOKEN` unset +keeps the stored key. ``` cd "$DEMO/$PROJECT" @@ -219,5 +221,10 @@ bun run "$CLI" deploy - **Deploy says a credential has no secret.** The credential's value did not reach `agentcore/.env.local`. Export `GITHUB_TOKEN` and run build again, or set `AGENTCORE_CREDENTIAL_GITHUB` in the deploy environment. +- **`agentcore dev` uses an old key when the shell sets none.** Earlier builds of the + box-integration branches copied each box variable into `agentcore/.env.local`, under a + `# Key for box egress '' (env://), read by box under agentcore dev` comment, and + dev still reads it there. Delete those lines (the comment and the `=` line under it), then + export the variable in your shell instead. - **The CDK app uses the published constructs, not yours.** Redo step 5. Confirm with `cat agentcore/cdk/node_modules/@aws/agentcore-cdk/package.json`. diff --git a/src/core/project/boxNetworkWriters.ts b/src/core/project/boxNetworkWriters.ts index 424f96765..3ed35c1c3 100644 --- a/src/core/project/boxNetworkWriters.ts +++ b/src/core/project/boxNetworkWriters.ts @@ -64,7 +64,7 @@ export interface BoxNetworkEdits { /** Changes to the copy of agentcore.json, in order; each returns its step messages. */ readonly spec?: readonly ((spec: ProjectSpec) => string[])[]; readonly files?: readonly BoxNetworkFile[]; - /** Entries for `.env.local`, which keep any value it holds already. */ + /** Entries for `.env.local`; each replaces the value it holds under that key. */ readonly envLocal?: readonly EnvLocalEntry[]; } diff --git a/src/core/project/boxProfileCredentials.test.ts b/src/core/project/boxProfileCredentials.test.ts index c23a3f992..6c5ec7081 100644 --- a/src/core/project/boxProfileCredentials.test.ts +++ b/src/core/project/boxProfileCredentials.test.ts @@ -105,6 +105,42 @@ describe("planBoxProfileCredentials", () => { expect(s.credentials).toEqual([API_KEY]); }); + // dev hands box the route's variable, so after a rotation deploy must provision the same key. + test("replaces a stored key the route's variable no longer holds, and says so", () => { + const plan = planBoxProfileCredentials(spec([API_KEY]), [GITHUB], { + env: { GITHUB_TOKEN: "ghp_new" }, + envLocal: { [RESERVED]: "ghp_old" }, + }); + + expect(plan.entries.map(({ key, value }) => [key, value])).toEqual([[RESERVED, "ghp_new"]]); + expect(plan.messages).toEqual([ + `updating ${RESERVED} in ${ENV_LOCAL_RELATIVE_PATH}: GITHUB_TOKEN holds a different key, ` + + "which agentcore dev uses, so deploy provisions it too", + ]); + }); + + test("leaves a stored key alone when the variable holds it, or when nothing sets the variable", () => { + for (const env of [{ GITHUB_TOKEN: "ghp_same" }, {}]) { + const plan = planBoxProfileCredentials(spec([API_KEY]), [GITHUB], { + env, + envLocal: { [RESERVED]: "ghp_same" }, + }); + + expect(plan.entries).toEqual([]); + expect(plan.messages).toEqual([]); + } + }); + + test("leaves the stored key alone when the shell sets the credential's own variable", () => { + // Deploy provisions that one, so the route's variable has nothing to change. + const plan = planBoxProfileCredentials(spec([API_KEY]), [GITHUB], { + env: { GITHUB_TOKEN: "ghp_new", [RESERVED]: "ghp_explicit" }, + envLocal: { [RESERVED]: "ghp_old" }, + }); + + expect(plan.entries).toEqual([]); + }); + test("keeps an earlier build's credential and says what to set when its key has gone", () => { const plan = planBoxProfileCredentials(spec([API_KEY]), [GITHUB], shell({})); diff --git a/src/core/project/boxProfileCredentials.ts b/src/core/project/boxProfileCredentials.ts index d8d1af7b7..b289357d4 100644 --- a/src/core/project/boxProfileCredentials.ts +++ b/src/core/project/boxProfileCredentials.ts @@ -13,7 +13,7 @@ import { ENV_LOCAL_RELATIVE_PATH } from "./envLocal"; /** * Where build looks for a route's key: the environment it runs in, and the project's `.env.local`, - * where `agentcore dev` stores each box variable under its own name. + * where a user can keep a box variable under its own name, as `agentcore dev` reads it. */ export type BoxKeySources = { env: NodeJS.ProcessEnv; @@ -91,15 +91,28 @@ export function planBoxProfileCredentials( const messages: string[] = []; const added: Credential[] = []; const entries: EnvLocalEntry[] = []; - /** Stores the route's key under `credential`'s reserved variable; false when there is none. */ + /** + * Stores the route's key under `credential`'s reserved variable, as `agentcore dev` reads it: the + * route's variable from the environment, else from `.env.local`. A stored key that differs is + * replaced, so dev and deploy use the same key after a rotation. False when there is none. + */ const seed = ({ variable }: BoxEnvRoute, credential: string): boolean => { const key = credentialEnvVarName(credential); - if (hasValue(sources.env[key]) || hasValue(sources.envLocal[key])) return true; + // Set in the environment itself, it is what deploy provisions; nothing to store. + if (hasValue(sources.env[key])) return true; if (entries.some((entry) => entry.key === key)) return true; const value = hasValue(sources.env[variable]) ? sources.env[variable] : sources.envLocal[variable]; - if (!hasValue(value)) return false; + const stored = sources.envLocal[key]; + if (!hasValue(value)) return hasValue(stored); + if (value === stored) return true; + if (hasValue(stored)) { + messages.push( + `updating ${key} in ${ENV_LOCAL_RELATIVE_PATH}: ${variable} holds a different key, which ` + + "agentcore dev uses, so deploy provisions it too", + ); + } entries.push({ key, value, diff --git a/src/core/project/envLocal.test.ts b/src/core/project/envLocal.test.ts index c8d4d1b28..53157a3d3 100644 --- a/src/core/project/envLocal.test.ts +++ b/src/core/project/envLocal.test.ts @@ -167,6 +167,38 @@ test("rollback restores the content removeKeys deleted", async () => { expect(await Bun.file(file.path).text()).toBe("# api key\nSECRET='v'\nOTHER=1\n"); }); +test("upsert replaces a key's value under its own comment, and appends a new key", async () => { + const root = await tempRoot(); + const file = new EnvLocalFile(root); + await Bun.write(file.path, "# old key\nSECRET='v'\nOTHER=1\n"); + + const result = await file.upsert([ + { key: "SECRET", value: "w", comment: "unused for an existing key" }, + { key: "NEW", value: "n", comment: "new key" }, + ]); + + expect(result).toEqual({ written: ["NEW"], updated: ["SECRET"] }); + expect(await file.read()).toEqual({ SECRET: "w", OTHER: "1", NEW: "n" }); + expect(await Bun.file(file.path).text()).toStartWith("# old key\nSECRET='w'\nOTHER=1\n"); +}); + +test("rollback undoes an upsert, the replaced value and the appended key", async () => { + const root = await tempRoot(); + const file = new EnvLocalFile(root); + await Bun.write(file.path, "# old key\nSECRET='v'\n"); + + await file.upsert([ENTRY, { key: "SECRET", value: "w", comment: "c" }]); + await file.upsert([{ key: "NEW", value: "n", comment: "c" }]); + const second = new EnvLocalFile(root); + await second.upsert([ + { key: "SECRET", value: "x", comment: "c" }, + { key: "MORE", value: "m", comment: "c" }, + ]); + await second.rollback(); + + expect(await second.read()).toEqual({ SECRET: "w", NEW: "n" }); +}); + testPosix("removeKeys keeps owner-only permissions on the rewritten file", async () => { const root = await tempRoot(); const file = new EnvLocalFile(root); diff --git a/src/core/project/envLocal.ts b/src/core/project/envLocal.ts index 1500cb395..f6caff664 100644 --- a/src/core/project/envLocal.ts +++ b/src/core/project/envLocal.ts @@ -75,6 +75,45 @@ export class EnvLocalFile { return { written, skipped }; } + /** + * Writes each entry: replaces the value of a key the file holds already, in place and under its + * own comment, and appends the others as {@link insertIfNew} does. Returns the keys appended and + * those whose value it replaced. + */ + async upsert(entries: EnvLocalEntry[]): Promise<{ written: string[]; updated: string[] }> { + const existing = await this.readOrNull(); + if (existing === null) { + const { written } = await this.insertIfNew(entries); + return { written, updated: [] }; + } + await this.enforcePermissions(); + const values = new Map(entries.map((entry) => [entry.key, entry.value ?? ""])); + const updated: string[] = []; + const lines: string[] = []; + for (const line of existing.split("\n")) { + const key = KEY_LINE.exec(line)?.[1]; + if (key === undefined || !values.has(key) || updated.includes(key)) { + lines.push(line); + continue; + } + const encrypted = await this.secrets.encrypt({ [key]: values.get(key)! }); + lines.push(`${key}=${formatValue(encrypted[key])}`); + updated.push(key); + } + if (updated.length > 0) { + this.snapshot = existing; + await atomicWrite(this.path, await this.encryptContent(lines.join("\n")), { + mode: SECRET_FILE_MODE, + }); + } + const { written } = await this.insertIfNew( + entries.filter((entry) => !updated.includes(entry.key)), + ); + // insertIfNew snapshots what this call wrote; rollback restores the file from before it. + if (updated.length > 0) this.snapshot = existing; + return { written, updated }; + } + /** * Reads the file's entries as a key/value map, returning {} when the file * does not exist. Values are read back with the same parser `agentcore dev` diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx index 499e24377..fef9edeae 100644 --- a/src/core/project/manager.tsx +++ b/src/core/project/manager.tsx @@ -1657,7 +1657,8 @@ export class FsProjectManager implements ProjectManager { } writeBoxNetworkFiles(project.rootPath, edits.files); if (edits.envLocal.length > 0) { - const { written } = await envLocal.insertIfNew([...edits.envLocal]); + // Box credential keys follow their route's variable, so a rotated key replaces the stored one. + const { written } = await envLocal.upsert([...edits.envLocal]); for (const key of written) messages.push(`writing ${key} to ${ENV_LOCAL_RELATIVE_PATH}`); } const warnings = networks.flatMap((network) => [ From 3421a139c1bc1b2790d5faac7cdc056eeb06f8b0 Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 19:24:44 -0800 Subject: [PATCH 10/13] fix(dev): Pick a box key from the shell or .env.local as build does dev checked a box profile's env:// keys in { ...envLocal, ...shell }, so a blank shell value hid the .env.local one, but started box with .env.local over the shell. With GITHUB_TOKEN= in the shell and a key in .env.local, dev warned box would not start, and box started. boxDevSecrets now takes the shell and .env.local apart and picks each variable as build does, the shell's when set and not blank, and both runners hand box that value. --- src/core/dev/box.test.ts | 16 +++++++++++ src/core/dev/box.ts | 8 +++--- src/core/dev/boxDevSecrets.test.ts | 44 +++++++++++++++++++++++++----- src/core/dev/boxDevSecrets.ts | 20 ++++++++------ src/core/dev/container.ts | 4 +-- 5 files changed, 71 insertions(+), 21 deletions(-) diff --git a/src/core/dev/box.test.ts b/src/core/dev/box.test.ts index 6e38a1a86..958d5b68b 100644 --- a/src/core/dev/box.test.ts +++ b/src/core/dev/box.test.ts @@ -232,6 +232,22 @@ describe("BoxDevRunner", () => { expect(calls[0]!.options.env!.GITHUB_TOKEN).toBe("ghp_file"); }); + test("uses .env.local's value, with no warning, when the shell's is blank", async () => { + // A blank shell value, such as an unset CI secret, hid the .env.local one from the check + // but not from box run, so dev warned that box would not start, and box started. + const { projectRoot, calls, runner } = await scene(true, true, { + profile: GITHUB_PROFILE, + processEnv: { GITHUB_TOKEN: "" }, + }); + + const events = await collect( + runner.run({ ...input(projectRoot), env: { GITHUB_TOKEN: "ghp_file" } }), + ); + + expect(calls[0]!.options.env!.GITHUB_TOKEN).toBe("ghp_file"); + expect(JSON.stringify(events)).not.toContain("GITHUB_TOKEN for [egress.github]"); + }); + test("warns when neither has it, before box run reports it", async () => { const { projectRoot, calls, runner } = await scene(true, true, { profile: GITHUB_PROFILE, diff --git a/src/core/dev/box.ts b/src/core/dev/box.ts index ecbcc277e..b607124c8 100644 --- a/src/core/dev/box.ts +++ b/src/core/dev/box.ts @@ -94,11 +94,11 @@ export class BoxDevRunner implements DevRunner { yield { type: "status", message: "Traces are not collected when the agent runs in a box" }; } const fileEnv = credentialEnvironment(input.env); - // box reads each env:// key of the profile from its own environment. The shell's value wins - // over agentcore/.env.local's, and dev writes neither anywhere. + // box reads each env:// key of the profile from its own environment, picked as build picks it: + // the shell's value when set and not blank, else agentcore/.env.local's. Dev writes neither. const secrets = await boxDevSecrets(input.projectRoot, { - ...fileEnv, - ...this.processEnv, + env: this.processEnv, + envLocal: fileEnv, }); for (const missing of secrets.missing) { yield { type: "status", message: missingBoxSecretWarning(missing) }; diff --git a/src/core/dev/boxDevSecrets.test.ts b/src/core/dev/boxDevSecrets.test.ts index 565f03c01..323399333 100644 --- a/src/core/dev/boxDevSecrets.test.ts +++ b/src/core/dev/boxDevSecrets.test.ts @@ -28,11 +28,39 @@ async function project(profile?: string): Promise { return root; } +/** The secrets of the profile when only the shell sets the variables. */ +const secretsFromShell = (root: string, env: NodeJS.ProcessEnv) => + boxDevSecrets(root, { env, envLocal: {} }); + +describe("boxDevSecrets picks each variable as build does", () => { + test("takes a set shell value over .env.local's", async () => { + const root = await project(GITHUB_ROUTE); + expect( + await boxDevSecrets(root, { + env: { GITHUB_TOKEN: "ghp_shell" }, + envLocal: { GITHUB_TOKEN: "ghp_file" }, + }), + ).toEqual({ env: { GITHUB_TOKEN: "ghp_shell" }, missing: [] }); + }); + + test("takes .env.local's value when the shell's is blank, as box then gets it", async () => { + // A blank shell value, such as an unset CI secret, must not hide the .env.local one: box + // starts with the .env.local key, so dev must not warn that it is missing. + const root = await project(GITHUB_ROUTE); + for (const env of [{ GITHUB_TOKEN: "" }, { GITHUB_TOKEN: " " }, {}]) { + expect(await boxDevSecrets(root, { env, envLocal: { GITHUB_TOKEN: "ghp_file" } })).toEqual({ + env: { GITHUB_TOKEN: "ghp_file" }, + missing: [], + }); + } + }); +}); + describe("boxDevSecrets", () => { test("returns an env:// route's variable under its own name, and writes no .env.local", async () => { const root = await project(GITHUB_ROUTE); - expect(await boxDevSecrets(root, { GITHUB_TOKEN: "ghp_1", OTHER: "x" })).toEqual({ + expect(await secretsFromShell(root, { GITHUB_TOKEN: "ghp_1", OTHER: "x" })).toEqual({ env: { GITHUB_TOKEN: "ghp_1" }, missing: [], }); @@ -42,7 +70,7 @@ describe("boxDevSecrets", () => { test("returns an HTTP MCP server's env:// variable too", async () => { const root = await project(GITHUB_ROUTE + TOOLS_SERVER); - expect(await boxDevSecrets(root, { GITHUB_TOKEN: "ghp_1", TOOLS_TOKEN: "tk_1" })).toEqual({ + expect(await secretsFromShell(root, { GITHUB_TOKEN: "ghp_1", TOOLS_TOKEN: "tk_1" })).toEqual({ env: { GITHUB_TOKEN: "ghp_1", TOOLS_TOKEN: "tk_1" }, missing: [], }); @@ -54,7 +82,7 @@ describe("boxDevSecrets", () => { '[egress.gist]\ndestinations = ["gist.github.com"]\nsecret.ref = "env://GITHUB_TOKEN"\n', ); - expect(await boxDevSecrets(root, {})).toEqual({ + expect(await secretsFromShell(root, {})).toEqual({ env: {}, missing: [{ variable: "GITHUB_TOKEN", table: "[egress.github]" }], }); @@ -63,7 +91,7 @@ describe("boxDevSecrets", () => { test("reports a variable that is unset or blank as missing, with the table that reads it", async () => { const root = await project(GITHUB_ROUTE + TOOLS_SERVER); - expect(await boxDevSecrets(root, { GITHUB_TOKEN: " " })).toEqual({ + expect(await secretsFromShell(root, { GITHUB_TOKEN: " " })).toEqual({ env: {}, missing: [ { variable: "GITHUB_TOKEN", table: "[egress.github]" }, @@ -78,7 +106,9 @@ describe("boxDevSecrets", () => { '[egress.blank]\ndestinations = ["blank.example.com"]\nsecret.ref = "env:// "\n', ); - expect(await boxDevSecrets(root, { AWS_BEARER_TOKEN_BEDROCK: "token", default: "x" })).toEqual({ + expect( + await secretsFromShell(root, { AWS_BEARER_TOKEN_BEDROCK: "token", default: "x" }), + ).toEqual({ env: {}, missing: [], }); @@ -87,13 +117,13 @@ describe("boxDevSecrets", () => { test("returns nothing for a profile that does not parse; box run reports it", async () => { const root = await project("[egress\n"); - expect(await boxDevSecrets(root, {})).toEqual({ env: {}, missing: [] }); + expect(await secretsFromShell(root, {})).toEqual({ env: {}, missing: [] }); }); test("returns nothing without a box profile", async () => { const root = await project(); - expect(await boxDevSecrets(root, { GITHUB_TOKEN: "ghp_1" })).toEqual({ + expect(await secretsFromShell(root, { GITHUB_TOKEN: "ghp_1" })).toEqual({ env: {}, missing: [], }); diff --git a/src/core/dev/boxDevSecrets.ts b/src/core/dev/boxDevSecrets.ts index 0e6185ef4..2cfa09872 100644 --- a/src/core/dev/boxDevSecrets.ts +++ b/src/core/dev/boxDevSecrets.ts @@ -2,6 +2,7 @@ import { existsSync } from "node:fs"; import { readFile } from "node:fs/promises"; import { parse as parseToml } from "smol-toml"; import { hasValue } from "../project/boxProfileEgress"; +import type { BoxKeySources } from "../project/boxProfileCredentials"; import { ENV_LOCAL_RELATIVE_PATH } from "../project/envLocal"; import { BOX_PROFILE_FILE, boxProfilePath } from "../project/templates/boxProfile"; @@ -20,16 +21,17 @@ export type BoxDevSecrets = { /** * The variables that the project's box profile reads its keys from: each `env://` secret of - * an `[egress.]` route or an `[mcp.]` server, with its value in `env`. Dev hands these - * to `box run` as they are and writes none of them anywhere. A CodeZip agent's `box run` inherits - * the whole environment already; a box container gets them in its environment, since it gets - * nothing else from the host's. Only the profile's own tables count: a pack's variable, such as - * box/bedrock's `AWS_BEARER_TOKEN_BEDROCK`, is not the profile author's to pass. A profile that - * does not parse has none here; `box run` reports it. + * an `[egress.]` route or an `[mcp.]` server, with its value as build picks it + * ({@link BoxKeySources}): the environment's when it is set and not blank, else `.env.local`'s. + * Dev hands these to `box run` as they are and writes none of them anywhere. A CodeZip agent's + * `box run` inherits the whole environment already; a box container gets them in its environment, + * since it gets nothing else from the host's. Only the profile's own tables count: a pack's + * variable, such as box/bedrock's `AWS_BEARER_TOKEN_BEDROCK`, is not the profile author's to pass. + * A profile that does not parse has none here; `box run` reports it. */ export async function boxDevSecrets( projectRoot: string, - env: Readonly>, + sources: BoxKeySources, ): Promise { const profile = boxProfilePath(projectRoot); if (!existsSync(profile)) return { env: {}, missing: [] }; @@ -43,7 +45,9 @@ export async function boxDevSecrets( if (typeof ref !== "string" || !ref.startsWith(ENV_SCHEME)) continue; const variable = ref.slice(ENV_SCHEME.length); if (variable.trim() === "" || variable in found) continue; - const value = env[variable]; + const value = hasValue(sources.env[variable]) + ? sources.env[variable] + : sources.envLocal[variable]; if (!hasValue(value)) { if (!missing.some((other) => other.variable === variable)) { missing.push({ variable, table: `[${kind}.${name}]` }); diff --git a/src/core/dev/container.ts b/src/core/dev/container.ts index 371347479..34d3f63c4 100644 --- a/src/core/dev/container.ts +++ b/src/core/dev/container.ts @@ -249,8 +249,8 @@ export class ContainerDevRunner implements DevRunner { // the profile here. The shell's value wins over agentcore/.env.local's, and dev writes // neither anywhere but the run's own env file, removed when the run ends. const secrets = await boxDevSecrets(input.projectRoot, { - ...input.env, - ...this.processEnv, + env: this.processEnv, + envLocal: input.env ?? {}, }); for (const missing of secrets.missing) { yield { type: "status", message: missingBoxSecretWarning(missing) }; From aefc0b249d3dd98ecdccb91bd9e915f78eaedfd1 Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 19:35:56 -0800 Subject: [PATCH 11/13] refactor(dev): Read box keys from the profile dev already read boxDevSecrets read and parsed the box profile again, though both runners had read it, so its no-profile branch never ran. It now takes the profile text and is synchronous, and parses each secret with BoxEgressSecretSchema instead of casting the raw TOML. It also: - Matches a shell variable's name in any case on Windows, where a copy of process.env loses that, so an exported Github_Token still sets env://GITHUB_TOKEN. - Says, naming the variable and no value, when the shell and .env.local set a profile key to different values, since the shell's wins where the rest of dev prefers .env.local. - Looks the keys up next to stageBox in the container runner, so its warnings come before the image build. --- src/core/dev/box.test.ts | 15 ++- src/core/dev/box.ts | 27 ++-- src/core/dev/boxDevSecrets.test.ts | 172 ++++++++++++-------------- src/core/dev/boxDevSecrets.ts | 75 +++++++---- src/core/dev/container.test.ts | 35 ++++++ src/core/dev/container.ts | 47 ++++--- src/core/project/boxNetwork/egress.ts | 2 +- 7 files changed, 225 insertions(+), 148 deletions(-) diff --git a/src/core/dev/box.test.ts b/src/core/dev/box.test.ts index 958d5b68b..4f783619a 100644 --- a/src/core/dev/box.test.ts +++ b/src/core/dev/box.test.ts @@ -210,15 +210,26 @@ describe("BoxDevRunner", () => { ); }); - test("prefers the shell's value to .env.local's", async () => { + test("prefers the shell's value to .env.local's, and says which, with no value", async () => { + // A wide-scope GITHUB_TOKEN in a shell profile would otherwise silently replace a narrow + // project token in .env.local. const { projectRoot, calls, runner } = await scene(true, true, { profile: GITHUB_PROFILE, processEnv: { GITHUB_TOKEN: "ghp_shell" }, }); - await collect(runner.run({ ...input(projectRoot), env: { GITHUB_TOKEN: "ghp_file" } })); + const events = await collect( + runner.run({ ...input(projectRoot), env: { GITHUB_TOKEN: "ghp_file" } }), + ); expect(calls[0]!.options.env!.GITHUB_TOKEN).toBe("ghp_shell"); + expect(events).toContainEqual({ + type: "status", + message: + "GITHUB_TOKEN, which [egress.github] of the box profile reads, is set in this shell and " + + `in ${ENV_LOCAL_RELATIVE_PATH} to different values; box uses the shell's`, + }); + expect(JSON.stringify(events)).not.toMatch(/ghp_shell|ghp_file/); }); test("uses .env.local's value when the shell has none", async () => { diff --git a/src/core/dev/box.ts b/src/core/dev/box.ts index b607124c8..f4cb01374 100644 --- a/src/core/dev/box.ts +++ b/src/core/dev/box.ts @@ -5,7 +5,7 @@ import type { DevEvent, DevRunner, DevServerInput } from "../../handlers/project import { streamProcess, type ProcessStreamer } from "../../io"; import { requireTool } from "../../io/exec"; import { BOX_INSTALL_HINT } from "../project/backends/boxRelease"; -import { boxDevSecrets, missingBoxSecretWarning } from "./boxDevSecrets"; +import { boxDevSecrets, missingBoxSecretWarning, shadowedBoxSecretNote } from "./boxDevSecrets"; import { BOX_PROFILE_FILE, boxIngressPort, @@ -23,26 +23,29 @@ type BoxDevRunnerConfig = { checkTool?: (tool: string, installHint: string) => Promise; /** The environment `box run` starts from, the shell's by default; tests inject one. */ processEnv?: NodeJS.ProcessEnv; + /** The platform, whose rules for variable names apply to `processEnv`; tests inject one. */ + platform?: NodeJS.Platform; }; /** - * Runs a CodeZip agent with `box run .box/profile.toml` in the project folder - * when the project has that box profile, the one `agentcore create` writes, - * and with the fallback runner otherwise. `box` is the one on PATH, which the - * user installs from the box release. The box listens on the profile's - * ingress port and relays to the agent, so the dev port must be that port. + * Runs a CodeZip agent with `box run` in the runtime's folder when the project has the box + * profile `agentcore create` writes, and with the fallback runner otherwise. `box` is the one on + * PATH, which the user installs from the box release. The box listens on the profile's ingress + * port and relays to the agent, so the dev port must be that port. */ export class BoxDevRunner implements DevRunner { private readonly fallback: DevRunner; private readonly streamProcess: ProcessStreamer; private readonly checkTool: NonNullable; private readonly processEnv: NodeJS.ProcessEnv; + private readonly platform: NodeJS.Platform; constructor(config: BoxDevRunnerConfig) { this.fallback = config.fallback; this.streamProcess = config.streamProcess ?? streamProcess; this.checkTool = config.checkTool ?? requireTool; this.processEnv = config.processEnv ?? process.env; + this.platform = config.platform ?? process.platform; } public async *run(input: DevServerInput): AsyncGenerator { @@ -96,13 +99,17 @@ export class BoxDevRunner implements DevRunner { const fileEnv = credentialEnvironment(input.env); // box reads each env:// key of the profile from its own environment, picked as build picks it: // the shell's value when set and not blank, else agentcore/.env.local's. Dev writes neither. - const secrets = await boxDevSecrets(input.projectRoot, { - env: this.processEnv, - envLocal: fileEnv, - }); + const secrets = boxDevSecrets( + profileText, + { env: this.processEnv, envLocal: fileEnv }, + this.platform, + ); for (const missing of secrets.missing) { yield { type: "status", message: missingBoxSecretWarning(missing) }; } + for (const shadowed of secrets.shadowed) { + yield { type: "status", message: shadowedBoxSecretNote(shadowed) }; + } // box starts in the folder the profile names, the runtime's own for a CodeZip profile, so the // agent reaches no other folder of the project; box finds the profile from there. const startFolder = boxStartFolder(profileText); diff --git a/src/core/dev/boxDevSecrets.test.ts b/src/core/dev/boxDevSecrets.test.ts index 323399333..ce46518d1 100644 --- a/src/core/dev/boxDevSecrets.test.ts +++ b/src/core/dev/boxDevSecrets.test.ts @@ -1,132 +1,108 @@ -import { afterEach, describe, expect, test } from "bun:test"; -import { existsSync } from "node:fs"; -import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; -import { tmpdir } from "node:os"; -import { join } from "node:path"; -import { ENV_LOCAL_RELATIVE_PATH, EnvLocalFile } from "../project/envLocal"; -import { boxDevSecrets, missingBoxSecretWarning } from "./boxDevSecrets"; +import { describe, expect, test } from "bun:test"; +import { ENV_LOCAL_RELATIVE_PATH } from "../project/envLocal"; +import { boxDevSecrets, missingBoxSecretWarning, shadowedBoxSecretNote } from "./boxDevSecrets"; const GITHUB_ROUTE = '[egress.github]\ndestinations = ["api.github.com"]\nsecret.ref = "env://GITHUB_TOKEN"\n'; const TOOLS_SERVER = '[mcp.tools]\ntype = "http"\nurl = "https://tools.example.com/mcp"\nsecret.ref = "env://TOOLS_TOKEN"\n'; -const roots: string[] = []; - -afterEach(async () => { - await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true }))); -}); - -async function project(profile?: string): Promise { - const root = await mkdtemp(join(tmpdir(), "agentcore-box-dev-secrets-")); - roots.push(root); - await mkdir(join(root, "agentcore")); - if (profile !== undefined) { - await mkdir(join(root, ".box")); - await writeFile(join(root, ".box", "profile.toml"), profile); - } - return root; -} - -/** The secrets of the profile when only the shell sets the variables. */ -const secretsFromShell = (root: string, env: NodeJS.ProcessEnv) => - boxDevSecrets(root, { env, envLocal: {} }); - -describe("boxDevSecrets picks each variable as build does", () => { - test("takes a set shell value over .env.local's", async () => { - const root = await project(GITHUB_ROUTE); - expect( - await boxDevSecrets(root, { - env: { GITHUB_TOKEN: "ghp_shell" }, - envLocal: { GITHUB_TOKEN: "ghp_file" }, - }), - ).toEqual({ env: { GITHUB_TOKEN: "ghp_shell" }, missing: [] }); - }); - - test("takes .env.local's value when the shell's is blank, as box then gets it", async () => { - // A blank shell value, such as an unset CI secret, must not hide the .env.local one: box - // starts with the .env.local key, so dev must not warn that it is missing. - const root = await project(GITHUB_ROUTE); - for (const env of [{ GITHUB_TOKEN: "" }, { GITHUB_TOKEN: " " }, {}]) { - expect(await boxDevSecrets(root, { env, envLocal: { GITHUB_TOKEN: "ghp_file" } })).toEqual({ - env: { GITHUB_TOKEN: "ghp_file" }, - missing: [], - }); - } - }); -}); +/** The secrets of `profile` when only the shell sets the variables. */ +const fromShell = (profile: string, env: NodeJS.ProcessEnv) => + boxDevSecrets(profile, { env, envLocal: {} }); describe("boxDevSecrets", () => { - test("returns an env:// route's variable under its own name, and writes no .env.local", async () => { - const root = await project(GITHUB_ROUTE); - - expect(await secretsFromShell(root, { GITHUB_TOKEN: "ghp_1", OTHER: "x" })).toEqual({ + test("returns an env:// route's variable under its own name", () => { + expect(fromShell(GITHUB_ROUTE, { GITHUB_TOKEN: "ghp_1", OTHER: "x" })).toEqual({ env: { GITHUB_TOKEN: "ghp_1" }, missing: [], + shadowed: [], }); - expect(existsSync(new EnvLocalFile(root).path)).toBe(false); }); - test("returns an HTTP MCP server's env:// variable too", async () => { - const root = await project(GITHUB_ROUTE + TOOLS_SERVER); - - expect(await secretsFromShell(root, { GITHUB_TOKEN: "ghp_1", TOOLS_TOKEN: "tk_1" })).toEqual({ - env: { GITHUB_TOKEN: "ghp_1", TOOLS_TOKEN: "tk_1" }, - missing: [], - }); + test("returns an HTTP MCP server's env:// variable too", () => { + expect( + fromShell(GITHUB_ROUTE + TOOLS_SERVER, { GITHUB_TOKEN: "ghp_1", TOOLS_TOKEN: "tk_1" }).env, + ).toEqual({ GITHUB_TOKEN: "ghp_1", TOOLS_TOKEN: "tk_1" }); }); - test("names one variable once when two tables read it", async () => { - const root = await project( + test("names one variable once when two tables read it", () => { + const profile = GITHUB_ROUTE + - '[egress.gist]\ndestinations = ["gist.github.com"]\nsecret.ref = "env://GITHUB_TOKEN"\n', - ); - - expect(await secretsFromShell(root, {})).toEqual({ - env: {}, - missing: [{ variable: "GITHUB_TOKEN", table: "[egress.github]" }], - }); + '[egress.gist]\ndestinations = ["gist.github.com"]\nsecret.ref = "env://GITHUB_TOKEN"\n'; + expect(fromShell(profile, {}).missing).toEqual([ + { variable: "GITHUB_TOKEN", table: "[egress.github]" }, + ]); }); - test("reports a variable that is unset or blank as missing, with the table that reads it", async () => { - const root = await project(GITHUB_ROUTE + TOOLS_SERVER); - - expect(await secretsFromShell(root, { GITHUB_TOKEN: " " })).toEqual({ + test("reports a variable that is unset or blank as missing, with the table that reads it", () => { + expect(fromShell(GITHUB_ROUTE + TOOLS_SERVER, { GITHUB_TOKEN: " " })).toEqual({ env: {}, missing: [ { variable: "GITHUB_TOKEN", table: "[egress.github]" }, { variable: "TOOLS_TOKEN", table: "[mcp.tools]" }, ], + shadowed: [], }); }); - test("leaves out a pack's variable, a secret that is not env://, and a blank name", async () => { - const root = await project( + test("leaves out a pack's variable, a secret that is not env://, and a blank name", () => { + const profile = 'packs = ["box/bedrock"]\n[egress.s3]\ndestinations = ["s3.amazonaws.com"]\nsecret.ref = "aws://default"\n' + - '[egress.blank]\ndestinations = ["blank.example.com"]\nsecret.ref = "env:// "\n', - ); + '[egress.blank]\ndestinations = ["blank.example.com"]\nsecret.ref = "env:// "\n'; + expect(fromShell(profile, { AWS_BEARER_TOKEN_BEDROCK: "token", default: "x" })).toEqual({ + env: {}, + missing: [], + shadowed: [], + }); + }); + + test("returns nothing for a profile that does not parse; box run reports it", () => { + expect(fromShell("[egress\n", {})).toEqual({ env: {}, missing: [], shadowed: [] }); + }); +}); +describe("boxDevSecrets picks each variable as build does", () => { + test("takes a set shell value over .env.local's, and notes that the two differ", () => { expect( - await secretsFromShell(root, { AWS_BEARER_TOKEN_BEDROCK: "token", default: "x" }), + boxDevSecrets(GITHUB_ROUTE, { + env: { GITHUB_TOKEN: "ghp_shell" }, + envLocal: { GITHUB_TOKEN: "ghp_file" }, + }), ).toEqual({ - env: {}, + env: { GITHUB_TOKEN: "ghp_shell" }, missing: [], + shadowed: [{ variable: "GITHUB_TOKEN", table: "[egress.github]" }], }); }); - test("returns nothing for a profile that does not parse; box run reports it", async () => { - const root = await project("[egress\n"); - - expect(await secretsFromShell(root, {})).toEqual({ env: {}, missing: [] }); + test("notes nothing when the shell and .env.local hold the same key", () => { + const secrets = boxDevSecrets(GITHUB_ROUTE, { + env: { GITHUB_TOKEN: "ghp_same" }, + envLocal: { GITHUB_TOKEN: "ghp_same" }, + }); + expect(secrets.shadowed).toEqual([]); }); - test("returns nothing without a box profile", async () => { - const root = await project(); + test("takes .env.local's value when the shell's is blank, as box then gets it", () => { + // A blank shell value, such as an unset CI secret, must not hide the .env.local one: box + // starts with the .env.local key, so dev must not warn that it is missing. + for (const env of [{ GITHUB_TOKEN: "" }, { GITHUB_TOKEN: " " }, {}]) { + expect(boxDevSecrets(GITHUB_ROUTE, { env, envLocal: { GITHUB_TOKEN: "ghp_file" } })).toEqual({ + env: { GITHUB_TOKEN: "ghp_file" }, + missing: [], + shadowed: [], + }); + } + }); - expect(await secretsFromShell(root, { GITHUB_TOKEN: "ghp_1" })).toEqual({ - env: {}, - missing: [], - }); + // process.env is case-insensitive on Windows; a copy of it is not, so the name is matched here. + test("finds the shell's variable in any case on Windows, under the profile's name", () => { + const sources = { env: { Github_Token: "ghp_win" }, envLocal: {} }; + expect(boxDevSecrets(GITHUB_ROUTE, sources, "win32").env).toEqual({ GITHUB_TOKEN: "ghp_win" }); + expect(boxDevSecrets(GITHUB_ROUTE, sources, "linux").missing).toEqual([ + { variable: "GITHUB_TOKEN", table: "[egress.github]" }, + ]); }); }); @@ -135,8 +111,16 @@ describe("missingBoxSecretWarning", () => { expect(missingBoxSecretWarning({ variable: "GITHUB_TOKEN", table: "[egress.github]" })).toBe( "the box profile .box/profile.toml reads GITHUB_TOKEN for [egress.github], but it is not " + "set, and box does not start without it. Export it in this shell " + - "(export GITHUB_TOKEN=...) or put it in " + - `${ENV_LOCAL_RELATIVE_PATH}, then restart dev.`, + `(export GITHUB_TOKEN=...) or put it in ${ENV_LOCAL_RELATIVE_PATH}, then restart dev.`, + ); + }); +}); + +describe("shadowedBoxSecretNote", () => { + test("names the variable and its table, and no value", () => { + expect(shadowedBoxSecretNote({ variable: "GITHUB_TOKEN", table: "[egress.github]" })).toBe( + "GITHUB_TOKEN, which [egress.github] of the box profile reads, is set in this shell and in " + + `${ENV_LOCAL_RELATIVE_PATH} to different values; box uses the shell's`, ); }); }); diff --git a/src/core/dev/boxDevSecrets.ts b/src/core/dev/boxDevSecrets.ts index 2cfa09872..182b0d942 100644 --- a/src/core/dev/boxDevSecrets.ts +++ b/src/core/dev/boxDevSecrets.ts @@ -1,10 +1,9 @@ -import { existsSync } from "node:fs"; -import { readFile } from "node:fs/promises"; import { parse as parseToml } from "smol-toml"; +import { BoxEgressSecretSchema } from "../project/boxNetwork/egress"; import { hasValue } from "../project/boxProfileEgress"; import type { BoxKeySources } from "../project/boxProfileCredentials"; import { ENV_LOCAL_RELATIVE_PATH } from "../project/envLocal"; -import { BOX_PROFILE_FILE, boxProfilePath } from "../project/templates/boxProfile"; +import { BOX_PROFILE_FILE } from "../project/templates/boxProfile"; const ENV_SCHEME = "env://"; @@ -17,47 +16,51 @@ export type BoxDevSecrets = { readonly env: Record; /** Each variable that is unset or blank; box refuses to start without it. */ readonly missing: readonly BoxDevSecretVariable[]; + /** Each variable that the shell and `.env.local` both set, to different values: box gets the shell's. */ + readonly shadowed: readonly BoxDevSecretVariable[]; }; /** - * The variables that the project's box profile reads its keys from: each `env://` secret of - * an `[egress.]` route or an `[mcp.]` server, with its value as build picks it - * ({@link BoxKeySources}): the environment's when it is set and not blank, else `.env.local`'s. - * Dev hands these to `box run` as they are and writes none of them anywhere. A CodeZip agent's - * `box run` inherits the whole environment already; a box container gets them in its environment, - * since it gets nothing else from the host's. Only the profile's own tables count: a pack's - * variable, such as box/bedrock's `AWS_BEARER_TOKEN_BEDROCK`, is not the profile author's to pass. - * A profile that does not parse has none here; `box run` reports it. + * The variables that the box profile `profileText` reads its keys from: each `env://` secret + * of an `[egress.]` route or an `[mcp.]` server, with its value as build picks it + * ({@link BoxKeySources}): the shell's when it is set and not blank, else `.env.local`'s. On + * Windows, where variable names are case-insensitive, the shell's `Github_Token` sets + * `GITHUB_TOKEN`. Dev hands these to `box run` as they are and writes none of them anywhere. Only + * the profile's own tables count: a pack's variable, such as box/bedrock's + * `AWS_BEARER_TOKEN_BEDROCK`, is not the profile author's to pass. A profile that does not parse + * has none here; `box run` reports it. */ -export async function boxDevSecrets( - projectRoot: string, +export function boxDevSecrets( + profileText: string, sources: BoxKeySources, -): Promise { - const profile = boxProfilePath(projectRoot); - if (!existsSync(profile)) return { env: {}, missing: [] }; - const table = parseProfile(await readFile(profile, "utf-8")); - + platform: NodeJS.Platform = process.platform, +): BoxDevSecrets { + const table = parseProfile(profileText); const found: Record = {}; const missing: BoxDevSecretVariable[] = []; + const shadowed: BoxDevSecretVariable[] = []; for (const kind of ["egress", "mcp"] as const) { for (const [name, entry] of Object.entries(tableOf(table[kind]))) { - const ref = (entry as { secret?: { ref?: unknown } } | null)?.secret?.ref; - if (typeof ref !== "string" || !ref.startsWith(ENV_SCHEME)) continue; - const variable = ref.slice(ENV_SCHEME.length); + const secret = BoxEgressSecretSchema.safeParse(tableOf(entry).secret); + if (!secret.success || !secret.data.ref.startsWith(ENV_SCHEME)) continue; + const variable = secret.data.ref.slice(ENV_SCHEME.length); if (variable.trim() === "" || variable in found) continue; - const value = hasValue(sources.env[variable]) - ? sources.env[variable] - : sources.envLocal[variable]; + const fromShell = shellValue(sources.env, variable, platform); + const fromFile = sources.envLocal[variable]; + const value = hasValue(fromShell) ? fromShell : fromFile; if (!hasValue(value)) { if (!missing.some((other) => other.variable === variable)) { missing.push({ variable, table: `[${kind}.${name}]` }); } continue; } + if (hasValue(fromShell) && hasValue(fromFile) && fromShell !== fromFile) { + shadowed.push({ variable, table: `[${kind}.${name}]` }); + } found[variable] = value; } } - return { env: found, missing }; + return { env: found, missing, shadowed }; } /** The warning dev shows for a variable the box profile reads that is not set. */ @@ -69,6 +72,28 @@ export function missingBoxSecretWarning({ variable, table }: BoxDevSecretVariabl ); } +/** + * The note dev shows for a variable that the shell and `.env.local` both set, to different + * values. It names the variable and never a value. + */ +export function shadowedBoxSecretNote({ variable, table }: BoxDevSecretVariable): string { + return ( + `${variable}, which ${table} of the box profile reads, is set in this shell and in ` + + `${ENV_LOCAL_RELATIVE_PATH} to different values; box uses the shell's` + ); +} + +/** The shell's value of `variable`, found by its name in any case on Windows, as Windows does. */ +function shellValue( + env: NodeJS.ProcessEnv, + variable: string, + platform: NodeJS.Platform, +): string | undefined { + if (env[variable] !== undefined || platform !== "win32") return env[variable]; + const name = Object.keys(env).find((key) => key.toUpperCase() === variable.toUpperCase()); + return name === undefined ? undefined : env[name]; +} + function parseProfile(text: string): Record { try { return parseToml(text) as Record; diff --git a/src/core/dev/container.test.ts b/src/core/dev/container.test.ts index 4b08b7749..a90dbf7e4 100644 --- a/src/core/dev/container.test.ts +++ b/src/core/dev/container.test.ts @@ -75,6 +75,7 @@ function harness( awsDirectory?: string; processEnv?: NodeJS.ProcessEnv; resolveAwsCredentials?: ResolveAwsCredentials; + platform?: NodeJS.Platform; } = {}, ) { const calls: ProcessCall[] = []; @@ -129,6 +130,7 @@ function harness( }, // Never the real chain in a test: none unless the test gives some. resolveAwsCredentials: config.resolveAwsCredentials ?? (async () => undefined), + ...(config.platform && { platform: config.platform }), }), }; } @@ -1049,6 +1051,39 @@ describe("ContainerDevRunner", () => { expect(commandCall(calls, "run")).toBeDefined(); }); + test("warns before the image build, as the lookup needs only the profile and the env", async () => { + const { projectRuntime, root } = await boxedScene({ + profileText: + '[egress.github]\ndestinations = ["api.github.com"]\nsecret.ref = "env://GITHUB_TOKEN"\n', + }); + const { runner } = harness({ processEnv: credentials }); + + const events = await collect(runner.run(input(root, projectRuntime))); + const messages = events.map((event) => ("message" in event ? event.message : "")); + + const warning = messages.findIndex((message) => message.includes("reads GITHUB_TOKEN")); + const build = messages.findIndex((message) => message.startsWith("Building image with")); + expect(warning).toBeGreaterThanOrEqual(0); + expect(warning).toBeLessThan(build); + }); + + test("hands the container a Windows shell's variable in another case, under its name", async () => { + // process.env is case-insensitive on Windows, so an exported Github_Token sets GITHUB_TOKEN. + const { projectRuntime, root } = await boxedScene({ + profileText: + '[egress.github]\ndestinations = ["api.github.com"]\nsecret.ref = "env://GITHUB_TOKEN"\n', + }); + const { calls, runner } = harness({ + processEnv: { ...credentials, Github_Token: "ghp_win" }, + platform: "win32", + }); + + const events = await collect(runner.run(input(root, projectRuntime))); + + expect(parseEnv(commandCall(calls, "run").envFile!.contents).GITHUB_TOKEN).toBe("ghp_win"); + expect(JSON.stringify(events)).not.toContain("reads GITHUB_TOKEN for [egress.github]"); + }); + test("stages box of the runtime's box.version", async () => { const { projectRuntime, root } = await boxedScene(); const { boxVersions, runner } = harness({ processEnv: credentials }); diff --git a/src/core/dev/container.ts b/src/core/dev/container.ts index 34d3f63c4..dbba8cb1b 100644 --- a/src/core/dev/container.ts +++ b/src/core/dev/container.ts @@ -10,7 +10,7 @@ import { ResourceNotFoundError, } from "../../errors"; import { notBoxProjectMessage } from "./box"; -import { boxDevSecrets, missingBoxSecretWarning } from "./boxDevSecrets"; +import { boxDevSecrets, missingBoxSecretWarning, shadowedBoxSecretNote } from "./boxDevSecrets"; import type { DevEvent, DevRunner, DevServerInput } from "../../handlers/project/dev/types"; import { MissingToolError, @@ -115,6 +115,8 @@ type ContainerDevRunnerConfig = { releaseFor?: (version: string | undefined) => Promise; /** Resolves the credentials a boxed container signs with; the default AWS SDK chain by default. */ resolveAwsCredentials?: ResolveAwsCredentials; + /** The platform, whose rules for variable names apply to `processEnv`; tests inject one. */ + platform?: NodeJS.Platform; }; export class ContainerDevRunner implements DevRunner { @@ -124,6 +126,7 @@ export class ContainerDevRunner implements DevRunner { private readonly processEnv: NodeJS.ProcessEnv; private readonly releaseFor: (version: string | undefined) => Promise; private readonly resolveAwsCredentials: ResolveAwsCredentials; + private readonly platform: NodeJS.Platform; constructor(config: ContainerDevRunnerConfig = {}) { this.streamProcess = config.streamProcess ?? streamProcess; @@ -132,6 +135,7 @@ export class ContainerDevRunner implements DevRunner { this.processEnv = config.processEnv ?? process.env; this.releaseFor = config.releaseFor ?? ((version) => boxReleaseFor(version, this.processEnv)); this.resolveAwsCredentials = config.resolveAwsCredentials ?? resolveDefaultAwsCredentials; + this.platform = config.platform ?? process.platform; } public async *run(input: DevServerInput): AsyncGenerator { @@ -189,8 +193,25 @@ export class ContainerDevRunner implements DevRunner { "--build-arg", `${key}=`, ]); - const boxDist = await this.stageBox(input, context); - const boxed = boxDist !== undefined; + const staged = await this.stageBox(input, context); + const boxDist = staged?.folder; + const boxed = staged !== undefined; + // The container gets none of the host's environment, so box in it gets each env:// key of the + // profile here, picked as build picks it: the shell's when set and not blank, else + // agentcore/.env.local's. Looked up before the image build, so its warnings come first. + const secrets = staged + ? boxDevSecrets( + staged.profileText, + { env: this.processEnv, envLocal: input.env ?? {} }, + this.platform, + ) + : undefined; + for (const missing of secrets?.missing ?? []) { + yield { type: "status", message: missingBoxSecretWarning(missing) }; + } + for (const shadowed of secrets?.shadowed ?? []) { + yield { type: "status", message: shadowedBoxSecretNote(shadowed) }; + } // The folder dev staged, for a Dockerfile that takes it as a build argument. const boxDistFlags = boxDist === BOX_DEV_DIST ? ["--build-arg", `${BOX_DIST_ARG}=${BOX_DEV_DIST}`] : []; @@ -244,17 +265,8 @@ export class ContainerDevRunner implements DevRunner { PORT: String(containerPort), LOCAL_DEV: "1", }); - if (boxed) { - // The container gets none of the host's environment, so box in it gets each env:// key of - // the profile here. The shell's value wins over agentcore/.env.local's, and dev writes - // neither anywhere but the run's own env file, removed when the run ends. - const secrets = await boxDevSecrets(input.projectRoot, { - env: this.processEnv, - envLocal: input.env ?? {}, - }); - for (const missing of secrets.missing) { - yield { type: "status", message: missingBoxSecretWarning(missing) }; - } + if (secrets) { + // dev writes the keys nowhere but the run's own env file, removed when the run ends. Object.assign(forwardedEnv, secrets.env); } if (input.runtime.protocol === "MCP") { @@ -348,7 +360,10 @@ export class ContainerDevRunner implements DevRunner { * leaves build and deploy's `.box-dist/` alone; an older one gets `.box-dist/`. The image then * runs `box run`, which needs BOX_RUN_FLAGS. */ - private async stageBox(input: DevServerInput, context: string): Promise { + private async stageBox( + input: DevServerInput, + context: string, + ): Promise<{ folder: string; profileText: string } | undefined> { // As build and deploy, dev decides whether a runtime is boxed from runsInBox alone. if (!runsInBox(input.boxProject, input.runtime)) { // A box runtime's image installs box and starts `box run`, which needs the Box project. @@ -383,7 +398,7 @@ export class ContainerDevRunner implements DevRunner { await this.releaseFor(input.runtime.box?.version), folder, ); - return folder; + return { folder, profileText }; } private async resolveContainerTool(signal: AbortSignal): Promise { diff --git a/src/core/project/boxNetwork/egress.ts b/src/core/project/boxNetwork/egress.ts index 156a9f241..3a9dcbd16 100644 --- a/src/core/project/boxNetwork/egress.ts +++ b/src/core/project/boxNetwork/egress.ts @@ -3,7 +3,7 @@ import type { BoxEgressAuth } from "./network"; import type { FailureCode } from "./types"; /** One `[egress.]` `secret` table, as Box reads it. */ -const BoxEgressSecretSchema = z +export const BoxEgressSecretSchema = z .object({ ref: z.string().min(1), header: z.string().min(1).optional(), From 6e26edc4485776e664ea60d1d3f3b82cf2b22a83 Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 19:48:20 -0800 Subject: [PATCH 12/13] fix(dev): Find a box key named like an Object property boxDevSecrets checked `variable in found` and read the environments by key, so a profile's env://constructor or env://toString matched Object.prototype: it was skipped with no value and no warning. It now reads only each record's own keys. --- src/core/dev/boxDevSecrets.test.ts | 12 ++++++++++++ src/core/dev/boxDevSecrets.ts | 14 ++++++++++---- 2 files changed, 22 insertions(+), 4 deletions(-) diff --git a/src/core/dev/boxDevSecrets.test.ts b/src/core/dev/boxDevSecrets.test.ts index cbfc45774..d0005152c 100644 --- a/src/core/dev/boxDevSecrets.test.ts +++ b/src/core/dev/boxDevSecrets.test.ts @@ -60,6 +60,18 @@ describe("boxDevSecrets", () => { test("returns nothing for a profile that does not parse; box run reports it", () => { expect(fromShell("[egress\n", {})).toEqual({ env: {}, missing: [], shadowed: [] }); }); + + test("treats a variable named like an Object property as any other", () => { + // `in` would find `constructor` on the prototype and skip it with no value and no warning. + const profile = + '[egress.odd]\ndestinations = ["odd.example.com"]\nsecret.ref = "env://constructor"\n'; + expect(fromShell(profile, { constructor: "k" } as NodeJS.ProcessEnv).env).toEqual({ + constructor: "k", + }); + expect(fromShell(profile, {}).missing).toEqual([ + { variable: "constructor", table: "[egress.odd]" }, + ]); + }); }); describe("boxDevSecrets picks each variable as build does", () => { diff --git a/src/core/dev/boxDevSecrets.ts b/src/core/dev/boxDevSecrets.ts index 280216f3a..ad9b3f86a 100644 --- a/src/core/dev/boxDevSecrets.ts +++ b/src/core/dev/boxDevSecrets.ts @@ -43,9 +43,9 @@ export function boxDevSecrets( const secret = BoxEgressSecretSchema.safeParse(tableOf(entry).secret); if (!secret.success || !secret.data.ref.startsWith(ENV_SCHEME)) continue; const variable = secret.data.ref.slice(ENV_SCHEME.length); - if (variable.trim() === "" || variable in found) continue; + if (variable.trim() === "" || Object.hasOwn(found, variable)) continue; const fromShell = shellValue(sources.env, variable, platform); - const fromFile = sources.envLocal[variable]; + const fromFile = own(sources.envLocal, variable); const value = hasValue(fromShell) ? fromShell : fromFile; if (!hasValue(value)) { if (!missing.some((other) => other.variable === variable)) { @@ -91,9 +91,15 @@ function shellValue( variable: string, platform: NodeJS.Platform, ): string | undefined { - if (env[variable] !== undefined || platform !== "win32") return env[variable]; + const exact = own(env, variable); + if (exact !== undefined || platform !== "win32") return exact; const name = Object.keys(env).find((key) => key.toUpperCase() === variable.toUpperCase()); - return name === undefined ? undefined : env[name]; + return name === undefined ? undefined : own(env, name); +} + +/** The value `env` itself holds for `name`, not one an Object property such as `constructor` gives. */ +function own(env: Readonly>, name: string): string | undefined { + return Object.hasOwn(env, name) ? env[name] : undefined; } function parseProfile(text: string): Record { From f9e63f1d268dcc25f3ffce20d9903a46f058666d Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 20:02:22 -0800 Subject: [PATCH 13/13] test(box): Keep the box tests off the network and Windows-safe The OTEL warning case for a box CodeZip runtime ran a full build, which downloads box from GitHub; CI has no box cache, and the download failed on every OS. The cases now check boxOtelWarnings directly, and one build case with a container runtime checks that build yields it. The resolver and dev runner built the project root through join(), which turns /work/demo into \work\demo on Windows. With no start folder they now use the project root as given. --- src/core/dev/box.ts | 5 +- src/core/project/backends/cdk.test.ts | 85 ++++++++++++--------- src/core/project/backends/cdk.ts | 30 ++++---- src/core/project/boxProfileResolver.test.ts | 22 ++++++ src/core/project/boxProfileResolver.ts | 5 +- 5 files changed, 97 insertions(+), 50 deletions(-) diff --git a/src/core/dev/box.ts b/src/core/dev/box.ts index 2ef95aa5d..a89f7240b 100644 --- a/src/core/dev/box.ts +++ b/src/core/dev/box.ts @@ -111,7 +111,10 @@ export class BoxDevRunner implements DevRunner { // box starts in the folder the profile names, the runtime's own for a CodeZip profile, so the // agent reaches no other folder of the project; box finds the profile from there. const startFolder = boxStartFolder(profileText); - const cwd = join(input.projectRoot, ...startFolder.split("/").filter(Boolean)); + const cwd = + startFolder === "" + ? input.projectRoot + : join(input.projectRoot, ...startFolder.split("/").filter(Boolean)); const profileArg = posix.relative(startFolder, profileFile); yield { type: "status", diff --git a/src/core/project/backends/cdk.test.ts b/src/core/project/backends/cdk.test.ts index fa38a99e2..edd9813b9 100644 --- a/src/core/project/backends/cdk.test.ts +++ b/src/core/project/backends/cdk.test.ts @@ -10,7 +10,7 @@ import { BOX_RELEASE } from "./boxRelease"; import { ProjectRuntimeSchema } from "../../../projectSchemas/runtime"; import { createSilentLogger } from "../../../testing"; import { TransactionSearchSetupError } from "../../../errors"; -import { CdkBackend } from "./cdk"; +import { boxOtelWarnings, CdkBackend } from "./cdk"; import type { CredentialProviderCalls, CredentialProvisionInput, @@ -68,6 +68,10 @@ function unusedIdentity(): CredentialProviderCalls { /** A build of a project that has no box runtime. */ const NO_BOX_NETWORKS = { boxNetworks: [] }; +const OTEL_WARNING = + "Runtime 'agent' runs its agent in a box, where the agent does not run under " + + "opentelemetry-instrument, so it sends no traces. Set instrumentation.enableOtel to false."; + function deployInput(overrides: Partial = {}): DeployBackendInput { return { target: TARGET, confirmTeardown: async () => false, boxNetworks: [], ...overrides }; } @@ -328,47 +332,58 @@ describe("CdkBackend.build", () => { expect(subject.commands).toEqual([{ command: synthCommand(input), cwd: cdkDirectory(input) }]); }); + // A CodeZip box build downloads box before it warns, so the cases check the warning itself. test.each([ ["a box container", "box", "Container", true, true], ["a box CodeZip runtime", "box", "CodeZip", true, true], ["a box container with enableOtel false", "box", "Container", false, false], ["a container outside a Box project", undefined, "Container", true, false], - ] as const)( - "warns that %s sends no traces: %p", - async (_label, projectType, build, otel, warns) => { - const input = await project(); - input.spec = ProjectSpecSchema.parse({ - name: "example", - version: 2, - ...(projectType && { projectType }), - runtimes: [ - { - name: "agent", - build, - ...(build === "CodeZip" && { runtimeVersion: "PYTHON_3_14" }), - entrypoint: "main.py", - codeLocation: "app/agent", - ...(projectType && { box: { version: BOX_RELEASE.version } }), - ...(!otel && { instrumentation: { enableOtel: false } }), - }, - ], - agentCoreGateways: projectType ? [boxGatewaySpec("agent")] : [], - }); - await mkdir(join(input.rootPath, "app", "agent"), { recursive: true }); - await writeFile(join(input.rootPath, "app", "agent", "Dockerfile"), "FROM scratch\n"); + ] as const)("warns that %s sends no traces: %p", (_label, projectType, build, otel, warns) => { + const spec = ProjectSpecSchema.parse({ + name: "example", + version: 2, + ...(projectType && { projectType }), + runtimes: [ + { + name: "agent", + build, + ...(build === "CodeZip" && { runtimeVersion: "PYTHON_3_14" }), + entrypoint: "main.py", + codeLocation: "app/agent", + ...(projectType && { box: { version: BOX_RELEASE.version } }), + ...(!otel && { instrumentation: { enableOtel: false } }), + }, + ], + agentCoreGateways: projectType ? [boxGatewaySpec("agent")] : [], + }); - const events = await collect(harness().backend.build(input, NO_BOX_NETWORKS)); + expect(boxOtelWarnings(spec)).toEqual(warns ? [OTEL_WARNING] : []); + }); - const warning: ProjectEvent = { - type: "warning", - message: - "Runtime 'agent' runs its agent in a box, where the agent does not run under " + - "opentelemetry-instrument, so it sends no traces. Set instrumentation.enableOtel to false.", - }; - if (warns) expect(events).toContainEqual(warning); - else expect(events).not.toContainEqual(warning); - }, - ); + test("build yields the OTEL warning of a box runtime", async () => { + const input = await project(); + input.spec = ProjectSpecSchema.parse({ + name: "example", + version: 2, + projectType: "box", + runtimes: [ + { + name: "agent", + build: "Container", + entrypoint: "main.py", + codeLocation: "app/agent", + box: { version: BOX_RELEASE.version }, + }, + ], + agentCoreGateways: [boxGatewaySpec("agent")], + }); + await mkdir(join(input.rootPath, "app", "agent"), { recursive: true }); + await writeFile(join(input.rootPath, "app", "agent", "Dockerfile"), "FROM scratch\n"); + + const events = await collect(harness().backend.build(input, NO_BOX_NETWORKS)); + + expect(events).toContainEqual({ type: "warning", message: OTEL_WARNING } as ProjectEvent); + }); test("warns but continues when the installed CDK is legacy", async () => { const input = await project(); diff --git a/src/core/project/backends/cdk.ts b/src/core/project/backends/cdk.ts index f00f936df..1dfce38a1 100644 --- a/src/core/project/backends/cdk.ts +++ b/src/core/project/backends/cdk.ts @@ -158,6 +158,22 @@ export type CdkBackendConfig = { processEnv?: NodeJS.ProcessEnv; }; +/** + * A warning for each runtime of `spec` that runs its agent in a box with OTEL on: the agent in the + * box does not run under opentelemetry-instrument, CodeZip or container, so it sends no traces. + */ +export function boxOtelWarnings(spec: Project["spec"]): string[] { + return spec.runtimes + .filter( + (runtime) => runtimeRunsInBox(spec, runtime) && (runtime.instrumentation?.enableOtel ?? true), + ) + .map( + (runtime) => + `Runtime '${runtime.name}' runs its agent in a box, where the agent does not run under ` + + "opentelemetry-instrument, so it sends no traces. Set instrumentation.enableOtel to false.", + ); +} + /** Builds and deploys projects through the scaffolded CDK app. */ export class CdkBackend implements ProjectBackend { private readonly logger: Logger; @@ -252,19 +268,7 @@ export class CdkBackend implements ProjectBackend { ): AsyncGenerator { yield* await this.ensureCdkDependencies(project, boxNetworks); - for (const runtime of project.spec.runtimes) { - if ( - runtimeRunsInBox(project.spec, runtime) && - (runtime.instrumentation?.enableOtel ?? true) - ) { - yield { - type: "warning", - message: - `Runtime '${runtime.name}' runs its agent in a box, where the agent does not run under ` + - `opentelemetry-instrument, so it sends no traces. Set instrumentation.enableOtel to false.`, - }; - } - } + for (const message of boxOtelWarnings(project.spec)) yield { type: "warning", message }; const compatibilityWarning = await cdkCompatibilityWarning(this.cdkDirectory(project)); if (compatibilityWarning) { diff --git a/src/core/project/boxProfileResolver.test.ts b/src/core/project/boxProfileResolver.test.ts index 94f18d281..d5d14c58e 100644 --- a/src/core/project/boxProfileResolver.test.ts +++ b/src/core/project/boxProfileResolver.test.ts @@ -264,6 +264,28 @@ describe("BoxCliProfileResolver", () => { ]); }); + test("runs box in the start folder, with the profile path from there", async () => { + const fake = streamer(stdout(SHOWN)); + const resolver = new BoxCliProfileResolver({ env: { PATH: "/bin" }, ...fake }); + + await resolver.resolve("/work/demo", ".box/agent/local/profile.toml", "app/agent"); + + expect(fake.calls).toEqual([ + { + command: [ + "box", + "profile", + "show", + "../../.box/agent/local/profile.toml", + "--format", + "json", + "--full", + ], + options: { cwd: join("/work/demo", "app", "agent"), env: { PATH: "/bin", NO_COLOR: "1" } }, + }, + ]); + }); + const COMMAND = ["box", "profile", "show", ".box/profile.toml", "--format", "json", "--full"]; const refusal = (lines: string[], exitCode: number | null = 1) => streamer( diff --git a/src/core/project/boxProfileResolver.ts b/src/core/project/boxProfileResolver.ts index 2e50ef389..49e29b520 100644 --- a/src/core/project/boxProfileResolver.ts +++ b/src/core/project/boxProfileResolver.ts @@ -141,7 +141,10 @@ export class BoxCliProfileResolver implements BoxProfileResolver { const stderr: string[] = []; try { const events = this.streamProcess(command, { - cwd: join(projectRoot, ...startFolder.split("/").filter(Boolean)), + cwd: + startFolder === "" + ? projectRoot + : join(projectRoot, ...startFolder.split("/").filter(Boolean)), env: { ...this.env, NO_COLOR: "1" }, }); for await (const event of events) {