From ad7dda3e2df7bd8ef5a036d83a2da454a2da6aa0 Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Wed, 18 Nov 2026 04:39:23 +0000 Subject: [PATCH 01/17] test(e2e): Deploy and invoke every Strands Box template Adds a box tag and a test for each box template: create, deploy, invoke, then check the Runtime's logs show box running the agent, and tear the stack down. They skip agentcore dev, which runs box on a fixed ingress port. --- e2eTest/README.md | 8 + e2eTest/constants.ts | 1 + e2eTest/project/templates.test.ts | 243 +++++++++++++++++++++++++----- 3 files changed, 212 insertions(+), 40 deletions(-) diff --git a/e2eTest/README.md b/e2eTest/README.md index ea7f54dd9a..4980ca77bf 100644 --- a/e2eTest/README.md +++ b/e2eTest/README.md @@ -21,3 +21,11 @@ run through a shell, so paths containing spaces, quoting, and shell syntax are n ```sh AGENTCORE_CLI_PATH=/path/to/agentcore bun run test:e2e ``` + +The `box` tests deploy the Strands Box templates, which run their agent in a box on AgentCore +Runtime. They need `box` on your PATH, because `agentcore create` checks for it, and they skip +`agentcore dev`: + +```sh +bun run test:e2e -- --tagsFilter='box' +``` diff --git a/e2eTest/constants.ts b/e2eTest/constants.ts index c10c7dd989..79fb960b75 100644 --- a/e2eTest/constants.ts +++ b/e2eTest/constants.ts @@ -1,6 +1,7 @@ export const E2E_PREFIX = "e2e"; export const TAGS = { + BOX: "box", CANARY: "canary", HARNESS: "harness", RUNTIME: "runtime", diff --git a/e2eTest/project/templates.test.ts b/e2eTest/project/templates.test.ts index 48e8787774..c37130fd9a 100644 --- a/e2eTest/project/templates.test.ts +++ b/e2eTest/project/templates.test.ts @@ -15,6 +15,52 @@ type RuntimeTemplateTestCase = { payload: Record; invokeFlags?: string[]; skip?: boolean; + /** + * A Strands Box template: it runs its agent in a box on AgentCore Runtime. Create needs `box` on + * PATH. `agentcore dev` runs box on the protocol's fixed ingress port (8080, 8000 or 9000), so + * concurrent tests cannot run it side by side; the Runtime path is what these tests cover. + */ + box?: boolean; +}; + +const MCP_INITIALIZE_PAYLOAD = { + jsonrpc: "2.0", + id: 1, + method: "initialize", + params: { + protocolVersion: "2025-03-26", + capabilities: {}, + clientInfo: { name: "agentcore-e2e", version: "1" }, + }, +}; +const MCP_INITIALIZE_FLAGS = [ + "--accept", + "application/json, text/event-stream", + "--mcp-protocol-version", + "2025-03-26", + "--mcp-method", + "initialize", +]; +const A2A_MESSAGE_PAYLOAD = { + jsonrpc: "2.0", + id: "agentcore-e2e", + method: "message/send", + params: { + message: { + messageId: "agentcore-e2e", + role: "user", + parts: [{ kind: "text", text: "Reply with a short greeting." }], + }, + }, +}; +const AGUI_RUN_PAYLOAD = { + threadId: "agentcore-e2e", + runId: "agentcore-e2e", + state: {}, + messages: [{ id: "agentcore-e2e", role: "user", content: "Reply with a short greeting." }], + tools: [], + context: [], + forwardedProps: {}, }; const RUNTIME_TEMPLATES: RuntimeTemplateTestCase[] = [ @@ -61,58 +107,77 @@ const RUNTIME_TEMPLATES: RuntimeTemplateTestCase[] = [ name: "mcp_python_fastmcp", template: "mcp-python-fastmcp", protocol: "MCP" as const, - payload: { - jsonrpc: "2.0", - id: 1, - method: "initialize", - params: { - protocolVersion: "2025-03-26", - capabilities: {}, - clientInfo: { name: "agentcore-e2e", version: "1" }, - }, - }, - invokeFlags: [ - "--accept", - "application/json, text/event-stream", - "--mcp-protocol-version", - "2025-03-26", - "--mcp-method", - "initialize", - ], + payload: MCP_INITIALIZE_PAYLOAD, + invokeFlags: MCP_INITIALIZE_FLAGS, }, { name: "a2a_python_strands", template: "a2a-python-strands", protocol: "A2A" as const, - payload: { - jsonrpc: "2.0", - id: "agentcore-e2e", - method: "message/send", - params: { - message: { - messageId: "agentcore-e2e", - role: "user", - parts: [{ kind: "text", text: "Reply with a short greeting." }], - }, - }, - }, + payload: A2A_MESSAGE_PAYLOAD, }, { name: "agui_python_strands", template: "agui-python-strands", protocol: "AGUI" as const, - payload: { - threadId: "agentcore-e2e", - runId: "agentcore-e2e", - state: {}, - messages: [{ id: "agentcore-e2e", role: "user", content: "Reply with a short greeting." }], - tools: [], - context: [], - forwardedProps: {}, - }, + payload: AGUI_RUN_PAYLOAD, }, ].filter((r) => !r.skip); +/** The Strands Box templates, which run their agent in a box on AgentCore Runtime. */ +const BOX_TEMPLATES: RuntimeTemplateTestCase[] = [ + { + name: "agent_python_minimal_box", + template: "agent-python-minimal-box", + protocol: "HTTP" as const, + payload: { prompt: "Reply with a short greeting." }, + }, + { + name: "agent_python_strands_box", + template: "agent-python-strands-box", + protocol: "HTTP" as const, + payload: { prompt: "Reply with a short greeting." }, + }, + { + name: "py_strands_box_container", + template: "agent-python-strands-box-container", + protocol: "HTTP" as const, + payload: { prompt: "Reply with a short greeting." }, + // The same container limits as the non-box container template above. + skip: process.env.CI === "true" && process.platform !== "linux", + }, + { + name: "agent_python_langchain_box", + template: "agent-python-langchain-box", + protocol: "HTTP" as const, + payload: { prompt: "Reply with a short greeting." }, + }, + { + name: "mcp_python_fastmcp_box", + template: "mcp-python-fastmcp-box", + protocol: "MCP" as const, + payload: MCP_INITIALIZE_PAYLOAD, + invokeFlags: MCP_INITIALIZE_FLAGS, + }, + { + name: "a2a_python_strands_box", + template: "a2a-python-strands-box", + protocol: "A2A" as const, + payload: A2A_MESSAGE_PAYLOAD, + }, + { + name: "agui_python_strands_box", + template: "agui-python-strands-box", + protocol: "AGUI" as const, + payload: AGUI_RUN_PAYLOAD, + }, +] + .map((template) => ({ ...template, box: true })) + .filter((r) => !r.skip); + +/** Every template the suite creates, so each project gets its own name and local dev port. */ +const ALL_TEMPLATES = [...RUNTIME_TEMPLATES, ...BOX_TEMPLATES]; + const ProjectCreatedSchema = z.object({ project: z.object({ path: z.string() }), }); @@ -229,6 +294,104 @@ describe( }, ); +// The Strands Box templates run their agent in a box on AgentCore Runtime, so these tests create, +// deploy and invoke each one, then check that the Runtime started the agent in a box. They skip +// `agentcore dev`. They need `box` on PATH: create checks for it. Run them with +// `bun run test:e2e -- --tagsFilter='box'`. +describe( + "create, deploy, invoke for Strands Box templates", + { tags: [TAGS.RUNTIME, TAGS.BOX] }, + () => { + const cli = new CliRunner(); + + test.concurrent.each(BOX_TEMPLATES)( + "$name", + { + timeout: + TIMEOUT_MS.PROJECT_CREATE + + 2 * TIMEOUT_MS.PROJECT_INVOKE + + 2 * TIMEOUT_MS.PROJECT_DEPLOY + + TIMEOUT_MS.PROJECT_REMOVE, + }, + async (runtime) => { + const projectDir = await createTemplateProject(cli, runtime); + let scenarioCompleted = false; + try { + const deployment = parseResult( + DeployResponseSchema, + await cli.run(["deploy", "--yes", "--json"], projectDir), + ); + expect(deployment.message).toContain("deployed project"); + + const response = parseResult( + RuntimeInvokeResponseSchema, + await cli.run( + [ + "invoke", + "--runtime", + CREATED_RUNTIME_NAME, + "--session-id", + getSessionId(runtime.name), + "--payload", + JSON.stringify(runtime.payload), + "--json", + ...(runtime.invokeFlags ?? []), + ], + projectDir, + ), + ); + expect(response.complete).toBe(true); + if (runtime.protocol === "MCP" || runtime.protocol === "A2A") { + assertProtocolResponse(runtime, response.body); + } + + await assertRunsInBox(cli, projectDir); + scenarioCompleted = true; + } finally { + // Tear the stack down even when a step above failed. + await cli.run(["remove", "all", "--yes", "--json"], projectDir); + const cleanup = await cli.run(["deploy", "--yes", "--json"], projectDir); + // A cleanup error must not replace the scenario's primary diagnostic. + if (scenarioCompleted) parseResult(JsonObjectSchema, cleanup); + } + }, + ); + }, +); + +/** + * Given a deployed Box project, waits for the Runtime's logs to show that box started the agent. + * The logs arrive a little after the invoke, so it retries. + */ +async function assertRunsInBox(cli: CliRunner, projectDir: string): Promise { + const result = await retry( + async () => { + const found = await cli.run( + [ + "logs", + "runtime", + "--name", + CREATED_RUNTIME_NAME, + "--since", + "30m", + "--query", + '"running profile"', + ], + projectDir, + ); + if (found.exitCode !== 0 || !found.stdout.includes("running profile")) { + throw new Error( + `the Runtime's logs do not show box running the agent.\nstdout: ${found.stdout}\nstderr: ${found.stderr}`, + ); + } + return found; + }, + 2 * 60 * 1000, + 10 * 1000, + ); + expect(result.stdout).not.toMatch(/FALLBACK|FAILED/); +} + /** Given a template test case, creates a project scaffolded from it and returns its path. */ async function createTemplateProject( cli: CliRunner, @@ -237,7 +400,7 @@ async function createTemplateProject( const parent = await mkdtemp(join(tmpdir(), "agentcore-e2e-")); // A per-template suffix keeps concurrent projects (and their stacks) apart; // project names are alphanumeric, so it is the template's index. - const projectName = `${E2E_PREFIX}${Date.now().toString(36)}t${RUNTIME_TEMPLATES.indexOf(runtime)}`; + const projectName = `${E2E_PREFIX}${Date.now().toString(36)}t${ALL_TEMPLATES.indexOf(runtime)}`; const created = parseResult( ProjectCreatedSchema, await cli.run( From 6ca1d005841683a59c11ddbf40d28ee767d81abb Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Tue, 17 Nov 2026 19:03:47 -0800 Subject: [PATCH 02/17] test(e2e): Cover the two box templates outside CI Add agent-python-strands-box and agent-python-strands-box-container to the runtime template cases. CI deploys with the released @aws/agentcore-cdk, which has no Box support yet, and has no box on PATH for CodeZip dev, so the cases skip in CI. A CodeZip box agent's dev serves on the profile's ingress port, so that case pins dev to 8080. --- e2eTest/project/templates.test.ts | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/e2eTest/project/templates.test.ts b/e2eTest/project/templates.test.ts index c37130fd9a..9ace36e45d 100644 --- a/e2eTest/project/templates.test.ts +++ b/e2eTest/project/templates.test.ts @@ -14,6 +14,8 @@ type RuntimeTemplateTestCase = { protocol: "HTTP" | "MCP" | "A2A" | "AGUI"; payload: Record; invokeFlags?: string[]; + /** The port `agentcore dev` serves on; LOCAL_DEV_PORT_BASE plus the case's index otherwise. */ + devPort?: number; skip?: boolean; /** * A Strands Box template: it runs its agent in a box on AgentCore Runtime. Create needs `box` on @@ -85,6 +87,25 @@ const RUNTIME_TEMPLATES: RuntimeTemplateTestCase[] = [ // windows are also unable to run the linux container without a vm. skip: process.env.CI === "true" && process.platform !== "linux", }, + // The box templates run their agent in Strands Box. CI deploys with the released + // @aws/agentcore-cdk, which has no Box support yet, and its runners have no box on PATH for a + // CodeZip `agentcore dev`, so they run only outside CI for now. + { + name: "py_strands_box", + template: "agent-python-strands-box", + protocol: "HTTP" as const, + payload: { prompt: "Reply with a short greeting." }, + // A CodeZip box agent's dev serves on the box profile's ingress port, 8080 for HTTP. + devPort: 8080, + skip: process.env.CI === "true", + }, + { + name: "py_strands_box_container", + template: "agent-python-strands-box-container", + protocol: "HTTP" as const, + payload: { prompt: "Reply with a short greeting." }, + skip: process.env.CI === "true", + }, { name: "agent_python_langchain", template: "agent-python-langchain", @@ -242,7 +263,7 @@ describe( cli, runtime, projectDir, - LOCAL_DEV_PORT_BASE + RUNTIME_TEMPLATES.indexOf(runtime), + runtime.devPort ?? LOCAL_DEV_PORT_BASE + RUNTIME_TEMPLATES.indexOf(runtime), ); const deployment = parseResult( From 204da9ee1edec5dbcda05cd342aebeacabe7335f Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Tue, 17 Nov 2026 20:00:59 -0800 Subject: [PATCH 03/17] test(e2e): Skip dev for the box template cases The box cases test create, deploy and invoke on AgentCore Runtime, not agentcore dev, so they no longer start dev or invoke locally. --- e2eTest/project/templates.test.ts | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/e2eTest/project/templates.test.ts b/e2eTest/project/templates.test.ts index 9ace36e45d..2bbd41a72a 100644 --- a/e2eTest/project/templates.test.ts +++ b/e2eTest/project/templates.test.ts @@ -14,8 +14,8 @@ type RuntimeTemplateTestCase = { protocol: "HTTP" | "MCP" | "A2A" | "AGUI"; payload: Record; invokeFlags?: string[]; - /** The port `agentcore dev` serves on; LOCAL_DEV_PORT_BASE plus the case's index otherwise. */ - devPort?: number; + /** Skips the `agentcore dev` step and its local invoke; deploy and the remote invoke still run. */ + skipDev?: boolean; skip?: boolean; /** * A Strands Box template: it runs its agent in a box on AgentCore Runtime. Create needs `box` on @@ -87,16 +87,15 @@ const RUNTIME_TEMPLATES: RuntimeTemplateTestCase[] = [ // windows are also unable to run the linux container without a vm. skip: process.env.CI === "true" && process.platform !== "linux", }, - // The box templates run their agent in Strands Box. CI deploys with the released - // @aws/agentcore-cdk, which has no Box support yet, and its runners have no box on PATH for a - // CodeZip `agentcore dev`, so they run only outside CI for now. + // The box templates run their agent in Strands Box on AgentCore Runtime; the cases test create, + // deploy and invoke, not `agentcore dev`. CI deploys with the released @aws/agentcore-cdk, which + // has no Box support yet, so they run only outside CI for now. { name: "py_strands_box", template: "agent-python-strands-box", protocol: "HTTP" as const, payload: { prompt: "Reply with a short greeting." }, - // A CodeZip box agent's dev serves on the box profile's ingress port, 8080 for HTTP. - devPort: 8080, + skipDev: true, skip: process.env.CI === "true", }, { @@ -104,6 +103,7 @@ const RUNTIME_TEMPLATES: RuntimeTemplateTestCase[] = [ template: "agent-python-strands-box-container", protocol: "HTTP" as const, payload: { prompt: "Reply with a short greeting." }, + skipDev: true, skip: process.env.CI === "true", }, { @@ -259,12 +259,14 @@ describe( const projectDir = await createTemplateProject(cli, runtime); let scenarioCompleted = false; try { - await invokeLocally( - cli, - runtime, - projectDir, - runtime.devPort ?? LOCAL_DEV_PORT_BASE + RUNTIME_TEMPLATES.indexOf(runtime), - ); + if (!runtime.skipDev) { + await invokeLocally( + cli, + runtime, + projectDir, + LOCAL_DEV_PORT_BASE + RUNTIME_TEMPLATES.indexOf(runtime), + ); + } const deployment = parseResult( DeployResponseSchema, From 7d45b8813f38983044231103d8f12e144879e16e Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Tue, 17 Nov 2026 21:33:18 -0800 Subject: [PATCH 04/17] test(e2e): Run the CodeZip box template on each Runtime Python Add a py_strands_box case for PYTHON_3_10 through PYTHON_3_13, beside the template's default PYTHON_3_14, by setting runtimeVersion in agentcore.json after create. The remote invoke now also needs a 2xx status and a body, as the local invoke does, so an agent that failed to start in its box fails the case. --- e2eTest/project/templates.test.ts | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/e2eTest/project/templates.test.ts b/e2eTest/project/templates.test.ts index 2bbd41a72a..9e0479860e 100644 --- a/e2eTest/project/templates.test.ts +++ b/e2eTest/project/templates.test.ts @@ -1,5 +1,5 @@ import { describe, expect, test } from "vitest"; -import { mkdtemp } from "node:fs/promises"; +import { mkdtemp, readFile, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import z from "zod"; @@ -16,6 +16,8 @@ type RuntimeTemplateTestCase = { invokeFlags?: string[]; /** Skips the `agentcore dev` step and its local invoke; deploy and the remote invoke still run. */ skipDev?: boolean; + /** The runtime's runtimeVersion, written into agentcore.json after create; the template's otherwise. */ + runtimeVersion?: string; skip?: boolean; /** * A Strands Box template: it runs its agent in a box on AgentCore Runtime. Create needs `box` on @@ -98,6 +100,18 @@ const RUNTIME_TEMPLATES: RuntimeTemplateTestCase[] = [ skipDev: true, skip: process.env.CI === "true", }, + // The CodeZip box template on each other Python the CodeZip Runtime supports; it defaults to 3.14. + ...(["PYTHON_3_10", "PYTHON_3_11", "PYTHON_3_12", "PYTHON_3_13"] as const).map( + (runtimeVersion) => ({ + name: `py_strands_box_${runtimeVersion.slice("PYTHON_".length)}`, + template: "agent-python-strands-box", + protocol: "HTTP" as const, + payload: { prompt: "Reply with a short greeting." }, + skipDev: true, + runtimeVersion, + skip: process.env.CI === "true", + }), + ), { name: "py_strands_box_container", template: "agent-python-strands-box-container", @@ -292,6 +306,10 @@ describe( ), ); expect(response.complete).toBe(true); + // As locally: an agent that failed to start answers with an error status or nothing. + expect(response.statusCode).toBeGreaterThanOrEqual(200); + expect(response.statusCode).toBeLessThan(300); + expect(response.body.trim()).not.toBe(""); if (runtime.protocol === "MCP" || runtime.protocol === "A2A") { assertProtocolResponse(runtime, response.body); } @@ -431,6 +449,14 @@ async function createTemplateProject( parent, ), ); + if (runtime.runtimeVersion) { + const specPath = join(created.project.path, "agentcore", "agentcore.json"); + const spec = JSON.parse(await readFile(specPath, "utf8")) as { + runtimes: { runtimeVersion?: string }[]; + }; + for (const entry of spec.runtimes) entry.runtimeVersion = runtime.runtimeVersion; + await writeFile(specPath, `${JSON.stringify(spec, null, 2)}\n`); + } return created.project.path; } From 8d5f61991ae8a507395cbf284f59eec83657475a Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 15:55:51 -0800 Subject: [PATCH 05/17] test(e2e): Address the review of #2865 - Skip the Box template describe in CI, which deploys with the released CDK and has no box on PATH. - Look for the README's error lines with their own logs query, as --query returns only the events it matches. - Require a 2xx status and a body from a Box agent's remote invoke. - Check that box ran for the per-Python cases too, through the box field. - Drop py_strands_box and py_strands_box_container, which deployed the same templates as the Box describe. - Say that ALL_TEMPLATES sets only the project name. --- e2eTest/project/templates.test.ts | 77 +++++++++++++------------------ 1 file changed, 31 insertions(+), 46 deletions(-) diff --git a/e2eTest/project/templates.test.ts b/e2eTest/project/templates.test.ts index 9e0479860e..233efbc53b 100644 --- a/e2eTest/project/templates.test.ts +++ b/e2eTest/project/templates.test.ts @@ -20,9 +20,8 @@ type RuntimeTemplateTestCase = { runtimeVersion?: string; skip?: boolean; /** - * A Strands Box template: it runs its agent in a box on AgentCore Runtime. Create needs `box` on - * PATH. `agentcore dev` runs box on the protocol's fixed ingress port (8080, 8000 or 9000), so - * concurrent tests cannot run it side by side; the Runtime path is what these tests cover. + * A Strands Box template: it runs its agent in a box on AgentCore Runtime, so the test checks the + * Runtime's logs for box starting it. Create needs `box` on PATH. */ box?: boolean; }; @@ -92,15 +91,8 @@ const RUNTIME_TEMPLATES: RuntimeTemplateTestCase[] = [ // The box templates run their agent in Strands Box on AgentCore Runtime; the cases test create, // deploy and invoke, not `agentcore dev`. CI deploys with the released @aws/agentcore-cdk, which // has no Box support yet, so they run only outside CI for now. - { - name: "py_strands_box", - template: "agent-python-strands-box", - protocol: "HTTP" as const, - payload: { prompt: "Reply with a short greeting." }, - skipDev: true, - skip: process.env.CI === "true", - }, - // The CodeZip box template on each other Python the CodeZip Runtime supports; it defaults to 3.14. + // The CodeZip box template on each other Python the CodeZip Runtime supports; it defaults to 3.14, + // which the Box describe below covers, as it does the box container template. ...(["PYTHON_3_10", "PYTHON_3_11", "PYTHON_3_12", "PYTHON_3_13"] as const).map( (runtimeVersion) => ({ name: `py_strands_box_${runtimeVersion.slice("PYTHON_".length)}`, @@ -109,17 +101,11 @@ const RUNTIME_TEMPLATES: RuntimeTemplateTestCase[] = [ payload: { prompt: "Reply with a short greeting." }, skipDev: true, runtimeVersion, + box: true, + // CI deploys with the released @aws/agentcore-cdk, which has no Box support, and has no box. skip: process.env.CI === "true", }), ), - { - name: "py_strands_box_container", - template: "agent-python-strands-box-container", - protocol: "HTTP" as const, - payload: { prompt: "Reply with a short greeting." }, - skipDev: true, - skip: process.env.CI === "true", - }, { name: "agent_python_langchain", template: "agent-python-langchain", @@ -174,12 +160,10 @@ const BOX_TEMPLATES: RuntimeTemplateTestCase[] = [ payload: { prompt: "Reply with a short greeting." }, }, { - name: "py_strands_box_container", + name: "agent_python_strands_box_container", template: "agent-python-strands-box-container", protocol: "HTTP" as const, payload: { prompt: "Reply with a short greeting." }, - // The same container limits as the non-box container template above. - skip: process.env.CI === "true" && process.platform !== "linux", }, { name: "agent_python_langchain_box", @@ -206,11 +190,9 @@ const BOX_TEMPLATES: RuntimeTemplateTestCase[] = [ protocol: "AGUI" as const, payload: AGUI_RUN_PAYLOAD, }, -] - .map((template) => ({ ...template, box: true })) - .filter((r) => !r.skip); +].map((template) => ({ ...template, box: true })); -/** Every template the suite creates, so each project gets its own name and local dev port. */ +/** Every template the suite creates, so each project gets its own name. */ const ALL_TEMPLATES = [...RUNTIME_TEMPLATES, ...BOX_TEMPLATES]; const ProjectCreatedSchema = z.object({ @@ -313,6 +295,7 @@ describe( if (runtime.protocol === "MCP" || runtime.protocol === "A2A") { assertProtocolResponse(runtime, response.body); } + if (runtime.box) await assertRunsInBox(cli, projectDir); const removed = parseResult( OperationSchema, @@ -338,8 +321,9 @@ describe( // The Strands Box templates run their agent in a box on AgentCore Runtime, so these tests create, // deploy and invoke each one, then check that the Runtime started the agent in a box. They skip // `agentcore dev`. They need `box` on PATH: create checks for it. Run them with -// `bun run test:e2e -- --tagsFilter='box'`. -describe( +// `bun run test:e2e -- --tagsFilter='box'`. CI skips them: it deploys with the released +// @aws/agentcore-cdk, which has no Box support, and has no box on PATH. +describe.skipIf(process.env.CI === "true")( "create, deploy, invoke for Strands Box templates", { tags: [TAGS.RUNTIME, TAGS.BOX] }, () => { @@ -382,6 +366,10 @@ describe( ), ); expect(response.complete).toBe(true); + // An agent that box started but that failed answers with an error status or nothing. + expect(response.statusCode).toBeGreaterThanOrEqual(200); + expect(response.statusCode).toBeLessThan(300); + expect(response.body.trim()).not.toBe(""); if (runtime.protocol === "MCP" || runtime.protocol === "A2A") { assertProtocolResponse(runtime, response.body); } @@ -401,25 +389,18 @@ describe( ); /** - * Given a deployed Box project, waits for the Runtime's logs to show that box started the agent. - * The logs arrive a little after the invoke, so it retries. + * Given a deployed Box project, waits for the Runtime's logs to show that box started the agent, + * then checks they show no box error. The logs arrive a little after the invoke, so it retries. */ async function assertRunsInBox(cli: CliRunner, projectDir: string): Promise { - const result = await retry( + const logs = (query: string) => + cli.run( + ["logs", "runtime", "--name", CREATED_RUNTIME_NAME, "--since", "30m", "--query", query], + projectDir, + ); + await retry( async () => { - const found = await cli.run( - [ - "logs", - "runtime", - "--name", - CREATED_RUNTIME_NAME, - "--since", - "30m", - "--query", - '"running profile"', - ], - projectDir, - ); + const found = await logs('"running profile"'); if (found.exitCode !== 0 || !found.stdout.includes("running profile")) { throw new Error( `the Runtime's logs do not show box running the agent.\nstdout: ${found.stdout}\nstderr: ${found.stderr}`, @@ -430,7 +411,11 @@ async function assertRunsInBox(cli: CliRunner, projectDir: string): Promise Date: Thu, 19 Nov 2026 16:36:47 -0800 Subject: [PATCH 06/17] test(e2e): Wait before the Box error check, and say what box runs - Wait 30 s after 'running profile' before looking for error lines, so lines from the invoke have reached CloudWatch. - Say in e2eTest/README.md that --tagsFilter='box' leaves out the per-Python box cases, and that the Box describe's skipIf is the only skip for BOX_TEMPLATES. - Name the root README.md as the source of the error lines. --- e2eTest/README.md | 4 ++++ e2eTest/project/templates.test.ts | 10 ++++++++-- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/e2eTest/README.md b/e2eTest/README.md index 4980ca77bf..b7a6c440d0 100644 --- a/e2eTest/README.md +++ b/e2eTest/README.md @@ -29,3 +29,7 @@ Runtime. They need `box` on your PATH, because `agentcore create` checks for it, ```sh bun run test:e2e -- --tagsFilter='box' ``` + +That runs each Box template on its default Python. The CodeZip box template on Python 3.10 to 3.13 +(`py_strands_box_3_10` to `py_strands_box_3_13`) is in the runtime templates describe, so it runs +with `--tagsFilter='runtime'` or a full run, outside CI. diff --git a/e2eTest/project/templates.test.ts b/e2eTest/project/templates.test.ts index 233efbc53b..78dede346d 100644 --- a/e2eTest/project/templates.test.ts +++ b/e2eTest/project/templates.test.ts @@ -145,7 +145,10 @@ const RUNTIME_TEMPLATES: RuntimeTemplateTestCase[] = [ }, ].filter((r) => !r.skip); -/** The Strands Box templates, which run their agent in a box on AgentCore Runtime. */ +/** + * The Strands Box templates, which run their agent in a box on AgentCore Runtime. The describe's + * `skipIf` is their only skip: a `skip` on an entry here has no effect. + */ const BOX_TEMPLATES: RuntimeTemplateTestCase[] = [ { name: "agent_python_minimal_box", @@ -412,7 +415,10 @@ async function assertRunsInBox(cli: CliRunner, projectDir: string): Promise setTimeout(resolve, 30 * 1000)); const errors = await logs('?ERROR ?"blocked by egress control" ?AccessDenied'); expect(errors.exitCode).toBe(0); expect(errors.stdout).not.toMatch(/ERROR|blocked by egress control|AccessDenied/); From a3326d856203fbec5a6e041c61e178c3dd08d34c Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 22:51:33 +0000 Subject: [PATCH 07/17] fix(box): keep a box another process installed into the shared cache Concurrent build and deploy commands each download box into their own work folder, then moved it into ~/.agentcore/box/-/ by removing what was there first. A command that finished second removed the folder the first had just installed, while that command was copying out of it (ENOTEMPTY, EEXIST, or ENOENT on strands-box-contain-trampoline). An install now keeps a complete folder another process renamed in, and drops its own copy. --- src/core/project/backends/boxRelease.test.ts | 32 +++++++++++++++++++- src/core/project/backends/boxRelease.ts | 28 ++++++++++++++--- 2 files changed, 54 insertions(+), 6 deletions(-) diff --git a/src/core/project/backends/boxRelease.test.ts b/src/core/project/backends/boxRelease.test.ts index 2e4866cd98..994d24be63 100644 --- a/src/core/project/backends/boxRelease.test.ts +++ b/src/core/project/backends/boxRelease.test.ts @@ -1,7 +1,7 @@ import { afterEach, describe, expect, test } from "bun:test"; import { createHash } from "node:crypto"; import { execFileSync } from "node:child_process"; -import { existsSync } from "node:fs"; +import { cpSync, existsSync } from "node:fs"; import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; @@ -151,6 +151,36 @@ describe("resolveBoxLinuxBuild from the box release", () => { expect(commands[0]!.at(-1)).toContain("other/ffi-releases"); }); + test("keeps the release another process installed while this one downloaded it", async () => { + // Concurrent builds and deploys share the cache: each downloads into its own work folder, and + // one may finish while another is still downloading. The loser keeps the winner's folder, so a + // command already copying out of it does not lose files under it. + const { release, ffi, runner } = await fakeRelease(); + const winner = await resolveBoxLinuxBuild( + {}, + { runner, home: await temp("box-home-"), release, ffi }, + ); + const home = await temp("box-home-"); + const root = join(home, ".agentcore", "box", `${VERSION}-aarch64-unknown-linux-gnu`); + let installedMeanwhile: bigint | undefined; + const racing: ProcessRunner = async (command, options) => { + if (command[0] === "curl" && command.at(-1)!.endsWith(release.linux.asset)) { + cpSync(winner.binaries, root, { recursive: true }); + installedMeanwhile = (await stat(join(root, "box"), { bigint: true })).ino; + } + return runner(command, options); + }; + + const build = await resolveBoxLinuxBuild({}, { runner: racing, home, release, ffi }); + + expect(build.binaries).toBe(root); + expect(installedMeanwhile).toBeDefined(); + expect((await stat(join(root, "box"), { bigint: true })).ino).toBe(installedMeanwhile!); + expect(await readFile(join(root, "strands-box-contain-trampoline"), "utf8")).toBe( + "#!strands-box-contain-trampoline\n", + ); + }); + test("reuses an installed release without downloading again", async () => { const home = await temp("box-home-"); const { release, ffi, runner, commands } = await fakeRelease(); diff --git a/src/core/project/backends/boxRelease.ts b/src/core/project/backends/boxRelease.ts index b0cea5661e..52892a232e 100644 --- a/src/core/project/backends/boxRelease.ts +++ b/src/core/project/backends/boxRelease.ts @@ -255,8 +255,7 @@ async function installBox( `${build.asset} has no release.json for box ${release.version}, or no box packs.`, ); } - rmSync(root, { recursive: true, force: true }); - renameSync(payload, root); + publishInstall(payload, root, () => installedBox(release.version, root)); } finally { rmSync(work, { recursive: true, force: true }); } @@ -275,7 +274,8 @@ async function installFfi( ): Promise { const root = ffiCachePath(home, ffi.version, runtimeVersion); const marker = join(root, FFI_CACHE_MARKER); - if (isFile(marker) && readFileSync(marker, "utf8").trim() === asset.sha256) return root; + const installed = () => isFile(marker) && readFileSync(marker, "utf8").trim() === asset.sha256; + if (installed()) return root; const url = boxReleaseAssetUrl(ffi, asset.asset); onDownload?.({ name: `the box ffi shim for ${runtimeVersion}`, version: ffi.version, url }); @@ -294,15 +294,33 @@ async function installFfi( mkdirSync(payload); await runner(["tar", "-xzf", archive, "-C", payload], { cwd: work, env }); writeFileSync(join(payload, FFI_CACHE_MARKER), `${asset.sha256}\n`); - rmSync(root, { recursive: true, force: true }); mkdirSync(join(root, ".."), { recursive: true }); - renameSync(payload, root); + publishInstall(payload, root, installed); } finally { rmSync(work, { recursive: true, force: true }); } return root; } +/** + * Moves the checked `payload` into the cache folder `root`, where another process may be + * installing the same release at the same time: several concurrent build or deploy commands each + * download into their own work folder. `root` only ever appears through a rename of a complete + * payload, so once `installed()` holds it is never removed; a process that loses the race keeps + * the winner's copy and drops its own. + */ +function publishInstall(payload: string, root: string, installed: () => boolean): void { + if (installed()) return; + // An incomplete folder from an interrupted install; a concurrent process may remove it too. + rmSync(root, { recursive: true, force: true }); + try { + renameSync(payload, root); + } catch (error) { + // EEXIST or ENOTEMPTY: another process renamed its payload into `root` first. + if (!installed()) throw error; + } +} + async function download( release: Pick, asset: string, From 83ab7874134a1588637793bc85c9e0fcf728718b Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Fri, 20 Nov 2026 00:33:49 +0000 Subject: [PATCH 08/17] test(e2e): Run agentcore dev for every Strands Box template The Box tests deployed each Strands Box template but skipped agentcore dev, because box listens on the protocol's fixed ingress port and the tests run concurrently. A sequential group now creates each template, runs dev on that port, invokes it locally and checks that box started the agent. A box-egress test runs the minimal box template with an agent that fetches two hosts. Its local profile allows checkip.amazonaws.com with no credential, so that call returns 200 and box blocks example.com with a 403. It reaches public hosts, so it retries twice and has its own tag, which keeps it out of --tagsFilter='box'. --- e2eTest/README.md | 16 ++++- e2eTest/constants.ts | 1 + e2eTest/project/templates.test.ts | 114 ++++++++++++++++++++++++++++-- 3 files changed, 122 insertions(+), 9 deletions(-) diff --git a/e2eTest/README.md b/e2eTest/README.md index b7a6c440d0..e6703170a6 100644 --- a/e2eTest/README.md +++ b/e2eTest/README.md @@ -22,9 +22,11 @@ run through a shell, so paths containing spaces, quoting, and shell syntax are n AGENTCORE_CLI_PATH=/path/to/agentcore bun run test:e2e ``` -The `box` tests deploy the Strands Box templates, which run their agent in a box on AgentCore -Runtime. They need `box` on your PATH, because `agentcore create` checks for it, and they skip -`agentcore dev`: +The `box` tests cover the Strands Box templates, which run their agent in a box. They deploy and +invoke each one on AgentCore Runtime, and run `agentcore dev` with one local invoke for each. They +need `box` on your PATH, because `agentcore create` checks for it, and the `dev` tests need a +machine where `box run` can start its sandbox. Box listens on the protocol's fixed port (8080, 8000 +or 9000), so the `dev` tests run one at a time and need those ports free: ```sh bun run test:e2e -- --tagsFilter='box' @@ -33,3 +35,11 @@ bun run test:e2e -- --tagsFilter='box' That runs each Box template on its default Python. The CodeZip box template on Python 3.10 to 3.13 (`py_strands_box_3_10` to `py_strands_box_3_13`) is in the runtime templates describe, so it runs with `--tagsFilter='runtime'` or a full run, outside CI. + +The `box-egress` test checks that box, under `agentcore dev`, lets the agent reach the host its +profile allows (`checkip.amazonaws.com`) and blocks any other (`example.com`). It reaches public +hosts, so the network can make it fail. It retries twice, and `--tagsFilter='box'` leaves it out: + +```sh +bun run test:e2e -- --tagsFilter='box-egress' +``` diff --git a/e2eTest/constants.ts b/e2eTest/constants.ts index 79fb960b75..2df8881a34 100644 --- a/e2eTest/constants.ts +++ b/e2eTest/constants.ts @@ -2,6 +2,7 @@ export const E2E_PREFIX = "e2e"; export const TAGS = { BOX: "box", + BOX_EGRESS: "box-egress", CANARY: "canary", HARNESS: "harness", RUNTIME: "runtime", diff --git a/e2eTest/project/templates.test.ts b/e2eTest/project/templates.test.ts index 78dede346d..a3fc401557 100644 --- a/e2eTest/project/templates.test.ts +++ b/e2eTest/project/templates.test.ts @@ -21,7 +21,9 @@ type RuntimeTemplateTestCase = { skip?: boolean; /** * A Strands Box template: it runs its agent in a box on AgentCore Runtime, so the test checks the - * Runtime's logs for box starting it. Create needs `box` on PATH. + * Runtime's logs for box starting it. Create needs `box` on PATH. `agentcore dev` runs box on the + * protocol's fixed ingress port (8080, 8000 or 9000), so the concurrent Runtime tests skip it; the + * sequential dev tests below cover it. */ box?: boolean; }; @@ -233,6 +235,11 @@ const A2aResponseSchema = z.object({ const CREATED_RUNTIME_NAME = "agent"; /** Keep concurrent local-dev processes off protocol defaults and one another. */ const LOCAL_DEV_PORT_BASE = 18080; +/** + * The port a box profile's ingress listens on, by protocol. Box `dev` must use it, so the box dev + * tests run one at a time. + */ +const BOX_DEV_PORTS = { HTTP: 8080, AGUI: 8080, MCP: 8000, A2A: 9000 } as const; // Each template gets its own project from `agentcore create --template`, the // command that scaffolds template code (`add runtime` only writes docs). The @@ -323,9 +330,9 @@ describe( // The Strands Box templates run their agent in a box on AgentCore Runtime, so these tests create, // deploy and invoke each one, then check that the Runtime started the agent in a box. They skip -// `agentcore dev`. They need `box` on PATH: create checks for it. Run them with -// `bun run test:e2e -- --tagsFilter='box'`. CI skips them: it deploys with the released -// @aws/agentcore-cdk, which has no Box support, and has no box on PATH. +// `agentcore dev`, which the sequential tests below cover. They need `box` on PATH: create checks +// for it. Run them with `bun run test:e2e -- --tagsFilter='box'`. CI skips them: it deploys with +// the released @aws/agentcore-cdk, which has no Box support, and has no box on PATH. describe.skipIf(process.env.CI === "true")( "create, deploy, invoke for Strands Box templates", { tags: [TAGS.RUNTIME, TAGS.BOX] }, @@ -391,6 +398,97 @@ describe.skipIf(process.env.CI === "true")( }, ); +// `agentcore dev` for each Strands Box template: box runs the agent on the developer's machine. Box +// listens on the protocol's fixed ingress port, so these tests run one at a time. They deploy +// nothing. They need `box` on PATH and a machine where `box run` can start its sandbox. +describe.sequential("create and dev for Strands Box templates", { tags: [TAGS.BOX] }, () => { + const cli = new CliRunner(); + + test.each(BOX_TEMPLATES)( + "$name", + { timeout: TIMEOUT_MS.PROJECT_CREATE + TIMEOUT_MS.PROJECT_DEV + TIMEOUT_MS.PROJECT_INVOKE }, + async (runtime) => { + const projectDir = await createTemplateProject(cli, runtime); + const { devOutput } = await invokeLocally( + cli, + runtime, + projectDir, + BOX_DEV_PORTS[runtime.protocol], + ); + expect(devOutput).toContain("box: running profile"); + }, + ); +}); + +// Egress from a boxed agent under `agentcore dev`: the box profile allows one host with no +// credential, and box blocks every other host. The agent is the minimal template with its code +// replaced, so no model call decides the result. The hosts are public, so the network can make +// this fail; it has its own tag, keeping it out of `--tagsFilter='box'`. Run it with +// `bun run test:e2e -- --tagsFilter='box-egress'`. +const EGRESS_ALLOWED_URL = "https://checkip.amazonaws.com"; +const EGRESS_BLOCKED_URL = "https://example.com"; +const EGRESS_AGENT = `import urllib.request + +from bedrock_agentcore.runtime import BedrockAgentCoreApp + +app = BedrockAgentCoreApp() + + +def fetch(url): + try: + with urllib.request.urlopen(url, timeout=20) as response: + return {"status": response.status} + except Exception as error: + return {"error": f"{type(error).__name__}: {error}"} + + +@app.entrypoint +def invoke(payload, context): + return {"allowed": fetch("${EGRESS_ALLOWED_URL}"), "blocked": fetch("${EGRESS_BLOCKED_URL}")} + + +if __name__ == "__main__": + app.run() +`; +const EgressReplySchema = z.object({ + allowed: z.object({ status: z.number().optional(), error: z.string().optional() }), + blocked: z.object({ status: z.number().optional(), error: z.string().optional() }), +}); + +describe("egress under dev for a Strands Box template", { tags: [TAGS.BOX_EGRESS] }, () => { + const cli = new CliRunner(); + const runtime = BOX_TEMPLATES.find((t) => t.template === "agent-python-minimal-box"); + + test.skipIf(!runtime)( + "allows the profile's host and blocks any other", + { + retry: 2, + timeout: TIMEOUT_MS.PROJECT_CREATE + TIMEOUT_MS.PROJECT_DEV + TIMEOUT_MS.PROJECT_INVOKE, + }, + async () => { + const template = runtime!; + const projectDir = await createTemplateProject(cli, template); + await writeFile(join(projectDir, "app", CREATED_RUNTIME_NAME, "main.py"), EGRESS_AGENT); + const profile = join(projectDir, ".box", CREATED_RUNTIME_NAME, "local", "profile.toml"); + const host = new URL(EGRESS_ALLOWED_URL).host; + await writeFile( + profile, + `${await readFile(profile, "utf8")}\n[egress.checkip]\ndestinations = ["${host}"]\n`, + ); + + const { response } = await invokeLocally( + cli, + template, + projectDir, + BOX_DEV_PORTS[template.protocol], + ); + const reply = EgressReplySchema.parse(JSON.parse(response.body)); + expect(reply.allowed).toEqual({ status: 200 }); + expect(reply.blocked.error).toMatch(/403/); + }, + ); +}); + /** * Given a deployed Box project, waits for the Runtime's logs to show that box started the agent, * then checks they show no box error. The logs arrive a little after the invoke, so it retries. @@ -451,13 +549,16 @@ async function createTemplateProject( return created.project.path; } -/** Given a template test case, runs `agentcore dev` and invokes the runtime locally. */ +/** + * Given a template test case, runs `agentcore dev` and invokes the runtime locally. Returns the + * local invoke's response and everything dev printed. + */ async function invokeLocally( cli: CliRunner, runtime: RuntimeTemplateTestCase, projectDir: string, devPort: number, -): Promise { +): Promise<{ response: z.infer; devOutput: string }> { let port: number | undefined; let pendingOutput = ""; let devOutput = ""; @@ -516,6 +617,7 @@ async function invokeLocally( if (runtime.protocol === "MCP" || runtime.protocol === "A2A") { assertProtocolResponse(runtime, response.body); } + return { response, devOutput }; } finally { if (dev.exitCode === null) { dev.kill("SIGTERM"); From 61458ca15e1974dd1251bc9317dc45c9736e2607 Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Fri, 20 Nov 2026 00:53:52 +0000 Subject: [PATCH 09/17] test(e2e): Skip the Strands Box tests when no box runs from PATH Create, build and deploy of a Box template run box, and box ships only arm64 builds, so on the x86_64 Linux CI runner every Box test failed at create. The Box groups now skip there and run wherever a box does. --- e2eTest/README.md | 8 +- e2eTest/project/templates.test.ts | 119 +++++++++++++++++------------- 2 files changed, 72 insertions(+), 55 deletions(-) diff --git a/e2eTest/README.md b/e2eTest/README.md index e6703170a6..938a23092f 100644 --- a/e2eTest/README.md +++ b/e2eTest/README.md @@ -24,9 +24,11 @@ AGENTCORE_CLI_PATH=/path/to/agentcore bun run test:e2e The `box` tests cover the Strands Box templates, which run their agent in a box. They deploy and invoke each one on AgentCore Runtime, and run `agentcore dev` with one local invoke for each. They -need `box` on your PATH, because `agentcore create` checks for it, and the `dev` tests need a -machine where `box run` can start its sandbox. Box listens on the protocol's fixed port (8080, 8000 -or 9000), so the `dev` tests run one at a time and need those ports free: +are optional: they run only when a `box` runs from your PATH, and skip otherwise. Create, build and +deploy of a Box template run `box`, and box ships only arm64 builds, so they skip on the x86_64 Linux +CI runner. The `dev` tests also need a machine where `box run` can start its sandbox. Box listens on +the protocol's fixed port (8080, 8000 or 9000), so the `dev` tests run one at a time and need those +ports free: ```sh bun run test:e2e -- --tagsFilter='box' diff --git a/e2eTest/project/templates.test.ts b/e2eTest/project/templates.test.ts index a3fc401557..281a9fcbd7 100644 --- a/e2eTest/project/templates.test.ts +++ b/e2eTest/project/templates.test.ts @@ -1,4 +1,5 @@ import { describe, expect, test } from "vitest"; +import { spawnSync } from "node:child_process"; import { mkdtemp, readFile, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; @@ -240,6 +241,12 @@ const LOCAL_DEV_PORT_BASE = 18080; * tests run one at a time. */ const BOX_DEV_PORTS = { HTTP: 8080, AGUI: 8080, MCP: 8000, A2A: 9000 } as const; +/** + * Whether a `box` runs from PATH. Create, build and deploy of a Box template run it, and box ships + * only arm64 builds, so the Box tests are optional: they skip on a machine without one, such as + * the x86_64 Linux CI runner. + */ +const BOX_ON_PATH = spawnSync("box", ["--version"], { stdio: "ignore" }).status === 0; // Each template gets its own project from `agentcore create --template`, the // command that scaffolds template code (`add runtime` only writes docs). The @@ -331,9 +338,9 @@ describe( // The Strands Box templates run their agent in a box on AgentCore Runtime, so these tests create, // deploy and invoke each one, then check that the Runtime started the agent in a box. They skip // `agentcore dev`, which the sequential tests below cover. They need `box` on PATH: create checks -// for it. Run them with `bun run test:e2e -- --tagsFilter='box'`. CI skips them: it deploys with -// the released @aws/agentcore-cdk, which has no Box support, and has no box on PATH. -describe.skipIf(process.env.CI === "true")( +// for it. Run them with `bun run test:e2e -- --tagsFilter='box'`. CI skips them too: it deploys +// with the released @aws/agentcore-cdk, which has no Box support. +describe.skipIf(process.env.CI === "true" || !BOX_ON_PATH)( "create, deploy, invoke for Strands Box templates", { tags: [TAGS.RUNTIME, TAGS.BOX] }, () => { @@ -401,24 +408,28 @@ describe.skipIf(process.env.CI === "true")( // `agentcore dev` for each Strands Box template: box runs the agent on the developer's machine. Box // listens on the protocol's fixed ingress port, so these tests run one at a time. They deploy // nothing. They need `box` on PATH and a machine where `box run` can start its sandbox. -describe.sequential("create and dev for Strands Box templates", { tags: [TAGS.BOX] }, () => { - const cli = new CliRunner(); - - test.each(BOX_TEMPLATES)( - "$name", - { timeout: TIMEOUT_MS.PROJECT_CREATE + TIMEOUT_MS.PROJECT_DEV + TIMEOUT_MS.PROJECT_INVOKE }, - async (runtime) => { - const projectDir = await createTemplateProject(cli, runtime); - const { devOutput } = await invokeLocally( - cli, - runtime, - projectDir, - BOX_DEV_PORTS[runtime.protocol], - ); - expect(devOutput).toContain("box: running profile"); - }, - ); -}); +describe.skipIf(!BOX_ON_PATH)( + "create and dev for Strands Box templates", + { tags: [TAGS.BOX], sequential: true }, + () => { + const cli = new CliRunner(); + + test.each(BOX_TEMPLATES)( + "$name", + { timeout: TIMEOUT_MS.PROJECT_CREATE + TIMEOUT_MS.PROJECT_DEV + TIMEOUT_MS.PROJECT_INVOKE }, + async (runtime) => { + const projectDir = await createTemplateProject(cli, runtime); + const { devOutput } = await invokeLocally( + cli, + runtime, + projectDir, + BOX_DEV_PORTS[runtime.protocol], + ); + expect(devOutput).toContain("box: running profile"); + }, + ); + }, +); // Egress from a boxed agent under `agentcore dev`: the box profile allows one host with no // credential, and box blocks every other host. The agent is the minimal template with its code @@ -455,39 +466,43 @@ const EgressReplySchema = z.object({ blocked: z.object({ status: z.number().optional(), error: z.string().optional() }), }); -describe("egress under dev for a Strands Box template", { tags: [TAGS.BOX_EGRESS] }, () => { - const cli = new CliRunner(); - const runtime = BOX_TEMPLATES.find((t) => t.template === "agent-python-minimal-box"); +describe.skipIf(!BOX_ON_PATH)( + "egress under dev for a Strands Box template", + { tags: [TAGS.BOX_EGRESS] }, + () => { + const cli = new CliRunner(); + const runtime = BOX_TEMPLATES.find((t) => t.template === "agent-python-minimal-box"); - test.skipIf(!runtime)( - "allows the profile's host and blocks any other", - { - retry: 2, - timeout: TIMEOUT_MS.PROJECT_CREATE + TIMEOUT_MS.PROJECT_DEV + TIMEOUT_MS.PROJECT_INVOKE, - }, - async () => { - const template = runtime!; - const projectDir = await createTemplateProject(cli, template); - await writeFile(join(projectDir, "app", CREATED_RUNTIME_NAME, "main.py"), EGRESS_AGENT); - const profile = join(projectDir, ".box", CREATED_RUNTIME_NAME, "local", "profile.toml"); - const host = new URL(EGRESS_ALLOWED_URL).host; - await writeFile( - profile, - `${await readFile(profile, "utf8")}\n[egress.checkip]\ndestinations = ["${host}"]\n`, - ); + test.skipIf(!runtime)( + "allows the profile's host and blocks any other", + { + retry: 2, + timeout: TIMEOUT_MS.PROJECT_CREATE + TIMEOUT_MS.PROJECT_DEV + TIMEOUT_MS.PROJECT_INVOKE, + }, + async () => { + const template = runtime!; + const projectDir = await createTemplateProject(cli, template); + await writeFile(join(projectDir, "app", CREATED_RUNTIME_NAME, "main.py"), EGRESS_AGENT); + const profile = join(projectDir, ".box", CREATED_RUNTIME_NAME, "local", "profile.toml"); + const host = new URL(EGRESS_ALLOWED_URL).host; + await writeFile( + profile, + `${await readFile(profile, "utf8")}\n[egress.checkip]\ndestinations = ["${host}"]\n`, + ); - const { response } = await invokeLocally( - cli, - template, - projectDir, - BOX_DEV_PORTS[template.protocol], - ); - const reply = EgressReplySchema.parse(JSON.parse(response.body)); - expect(reply.allowed).toEqual({ status: 200 }); - expect(reply.blocked.error).toMatch(/403/); - }, - ); -}); + const { response } = await invokeLocally( + cli, + template, + projectDir, + BOX_DEV_PORTS[template.protocol], + ); + const reply = EgressReplySchema.parse(JSON.parse(response.body)); + expect(reply.allowed).toEqual({ status: 200 }); + expect(reply.blocked.error).toMatch(/403/); + }, + ); + }, +); /** * Given a deployed Box project, waits for the Runtime's logs to show that box started the agent, From 2e704fced7b4c2066db1165f43b1f1e40b8ca812 Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 19:55:02 -0800 Subject: [PATCH 10/17] test(e2e): Gate the Box deploy cases on a Box-capable CDK Address the review of #2865. - The Box cases that deploy run only with AGENTCORE_E2E_BOX_CDK, an @aws/agentcore-cdk version or file: tarball that deploys Box projects; createTemplateProject installs it in each Box project's agentcore/cdk. The pinned release still rejects boundRuntime, so the CI-only skip hid that a laptop run fails at synth the same way. CI sets no opt-in. - The per-Python Box cases take the same gate, so they also skip without box on PATH. - The README says which steps need box: create for a CodeZip box template, build and deploy (box profile show) for every Box template. - The egress test throws at collection when its template case is gone, instead of skipping silently. - publishInstall renames first and removes the cache folder only when the rename fails and the folder is not a complete install, and its comment names the window that remains and EPERM on Windows. A test covers replacing an interrupted install. --- e2eTest/README.md | 24 +++++-- e2eTest/project/templates.test.ts | 70 +++++++++++++++----- src/core/project/backends/boxRelease.test.ts | 14 ++++ src/core/project/backends/boxRelease.ts | 21 ++++-- 4 files changed, 100 insertions(+), 29 deletions(-) diff --git a/e2eTest/README.md b/e2eTest/README.md index 938a23092f..911f55f445 100644 --- a/e2eTest/README.md +++ b/e2eTest/README.md @@ -24,19 +24,29 @@ AGENTCORE_CLI_PATH=/path/to/agentcore bun run test:e2e The `box` tests cover the Strands Box templates, which run their agent in a box. They deploy and invoke each one on AgentCore Runtime, and run `agentcore dev` with one local invoke for each. They -are optional: they run only when a `box` runs from your PATH, and skip otherwise. Create, build and -deploy of a Box template run `box`, and box ships only arm64 builds, so they skip on the x86_64 Linux -CI runner. The `dev` tests also need a machine where `box run` can start its sandbox. Box listens on -the protocol's fixed port (8080, 8000 or 9000), so the `dev` tests run one at a time and need those -ports free: +are optional and need a `box` on your PATH: `create` checks for one for a CodeZip box template, and +`build` and `deploy` run `box profile show` for every Box template, the container one too. Without +one, they skip. `create` also installs the agent's dependencies and the CDK app's, which `dev` and +`deploy` use, so the tests don't pass `--skip-install`. + +The tests that deploy also need `AGENTCORE_E2E_BOX_CDK`: the pinned `@aws/agentcore-cdk` release +cannot deploy a Box project yet. Set it to an `@aws/agentcore-cdk` version or a `file:` tarball +that can, for example one packed from the `box-integration` branch of +[agentcore-l3-cdk-constructs](https://github.com/aws/agentcore-l3-cdk-constructs) with +`npm run build && npm pack --ignore-scripts`. The tests install it in each Box project's +`agentcore/cdk`. Without it, as in CI, they skip. + +The `dev` tests also need a machine where `box run` can start its sandbox, and for the container +template a container tool. Box listens on the protocol's fixed port (8080, 8000 or 9000), so the +`dev` tests run one at a time and need those ports free: ```sh -bun run test:e2e -- --tagsFilter='box' +AGENTCORE_E2E_BOX_CDK=file:/path/to/aws-agentcore-cdk-1.1.0.tgz bun run test:e2e -- --tagsFilter='box' ``` That runs each Box template on its default Python. The CodeZip box template on Python 3.10 to 3.13 (`py_strands_box_3_10` to `py_strands_box_3_13`) is in the runtime templates describe, so it runs -with `--tagsFilter='runtime'` or a full run, outside CI. +with `--tagsFilter='runtime'` or a full run, given `box` and the same opt-in. The `box-egress` test checks that box, under `agentcore dev`, lets the agent reach the host its profile allows (`checkip.amazonaws.com`) and blocks any other (`example.com`). It reaches public diff --git a/e2eTest/project/templates.test.ts b/e2eTest/project/templates.test.ts index 281a9fcbd7..35a8fc0ca3 100644 --- a/e2eTest/project/templates.test.ts +++ b/e2eTest/project/templates.test.ts @@ -1,4 +1,5 @@ import { describe, expect, test } from "vitest"; +import spawn from "cross-spawn"; import { spawnSync } from "node:child_process"; import { mkdtemp, readFile, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; @@ -22,7 +23,8 @@ type RuntimeTemplateTestCase = { skip?: boolean; /** * A Strands Box template: it runs its agent in a box on AgentCore Runtime, so the test checks the - * Runtime's logs for box starting it. Create needs `box` on PATH. `agentcore dev` runs box on the + * Runtime's logs for box starting it, and installs the AGENTCORE_E2E_BOX_CDK build to deploy it. + * `agentcore dev` runs box on the * protocol's fixed ingress port (8080, 8000 or 9000), so the concurrent Runtime tests skip it; the * sequential dev tests below cover it. */ @@ -69,6 +71,20 @@ const AGUI_RUN_PAYLOAD = { forwardedProps: {}, }; +/** + * Whether a `box` runs from PATH. Create checks for it for a CodeZip box template, and build and + * deploy of every Box template run `box profile show`, so the Box tests skip without one. + */ +const BOX_ON_PATH = spawnSync("box", ["--version"], { stdio: "ignore" }).status === 0; +/** + * The opt-in for the Box tests that deploy: an `@aws/agentcore-cdk` version or `file:` tarball + * that deploys Box projects, which the pinned release does not yet. It replaces the pin in each + * Box project's agentcore/cdk/package.json, so with it unset (as in CI) those tests skip. + */ +const BOX_CDK = process.env.AGENTCORE_E2E_BOX_CDK?.trim() || undefined; +/** Whether the Box tests that deploy run. */ +const BOX_DEPLOYS = BOX_CDK !== undefined && BOX_ON_PATH; + const RUNTIME_TEMPLATES: RuntimeTemplateTestCase[] = [ { name: "agent_python_minimal", @@ -92,8 +108,7 @@ const RUNTIME_TEMPLATES: RuntimeTemplateTestCase[] = [ skip: process.env.CI === "true" && process.platform !== "linux", }, // The box templates run their agent in Strands Box on AgentCore Runtime; the cases test create, - // deploy and invoke, not `agentcore dev`. CI deploys with the released @aws/agentcore-cdk, which - // has no Box support yet, so they run only outside CI for now. + // deploy and invoke, not `agentcore dev`. They run only with the AGENTCORE_E2E_BOX_CDK opt-in. // The CodeZip box template on each other Python the CodeZip Runtime supports; it defaults to 3.14, // which the Box describe below covers, as it does the box container template. ...(["PYTHON_3_10", "PYTHON_3_11", "PYTHON_3_12", "PYTHON_3_13"] as const).map( @@ -105,8 +120,7 @@ const RUNTIME_TEMPLATES: RuntimeTemplateTestCase[] = [ skipDev: true, runtimeVersion, box: true, - // CI deploys with the released @aws/agentcore-cdk, which has no Box support, and has no box. - skip: process.env.CI === "true", + skip: !BOX_DEPLOYS, }), ), { @@ -241,12 +255,6 @@ const LOCAL_DEV_PORT_BASE = 18080; * tests run one at a time. */ const BOX_DEV_PORTS = { HTTP: 8080, AGUI: 8080, MCP: 8000, A2A: 9000 } as const; -/** - * Whether a `box` runs from PATH. Create, build and deploy of a Box template run it, and box ships - * only arm64 builds, so the Box tests are optional: they skip on a machine without one, such as - * the x86_64 Linux CI runner. - */ -const BOX_ON_PATH = spawnSync("box", ["--version"], { stdio: "ignore" }).status === 0; // Each template gets its own project from `agentcore create --template`, the // command that scaffolds template code (`add runtime` only writes docs). The @@ -337,10 +345,10 @@ describe( // The Strands Box templates run their agent in a box on AgentCore Runtime, so these tests create, // deploy and invoke each one, then check that the Runtime started the agent in a box. They skip -// `agentcore dev`, which the sequential tests below cover. They need `box` on PATH: create checks -// for it. Run them with `bun run test:e2e -- --tagsFilter='box'`. CI skips them too: it deploys -// with the released @aws/agentcore-cdk, which has no Box support. -describe.skipIf(process.env.CI === "true" || !BOX_ON_PATH)( +// `agentcore dev`, which the sequential tests below cover. They need `box` on PATH and the +// AGENTCORE_E2E_BOX_CDK opt-in, a Box-capable @aws/agentcore-cdk build, so CI skips them. Run them +// with `bun run test:e2e -- --tagsFilter='box'`. +describe.skipIf(!BOX_DEPLOYS)( "create, deploy, invoke for Strands Box templates", { tags: [TAGS.RUNTIME, TAGS.BOX] }, () => { @@ -472,15 +480,16 @@ describe.skipIf(!BOX_ON_PATH)( () => { const cli = new CliRunner(); const runtime = BOX_TEMPLATES.find((t) => t.template === "agent-python-minimal-box"); + if (!runtime) throw new Error("BOX_TEMPLATES has no agent-python-minimal-box case"); - test.skipIf(!runtime)( + test( "allows the profile's host and blocks any other", { retry: 2, timeout: TIMEOUT_MS.PROJECT_CREATE + TIMEOUT_MS.PROJECT_DEV + TIMEOUT_MS.PROJECT_INVOKE, }, async () => { - const template = runtime!; + const template = runtime; const projectDir = await createTemplateProject(cli, template); await writeFile(join(projectDir, "app", CREATED_RUNTIME_NAME, "main.py"), EGRESS_AGENT); const profile = join(projectDir, ".box", CREATED_RUNTIME_NAME, "local", "profile.toml"); @@ -561,9 +570,36 @@ async function createTemplateProject( for (const entry of spec.runtimes) entry.runtimeVersion = runtime.runtimeVersion; await writeFile(specPath, `${JSON.stringify(spec, null, 2)}\n`); } + if (runtime.box && BOX_CDK) { + // The pinned @aws/agentcore-cdk cannot deploy a Box project yet; use the opted-in build. + const installed = await runCommand( + "npm", + ["install", "--no-audit", "--no-fund", `@aws/agentcore-cdk@${BOX_CDK}`], + join(created.project.path, "agentcore", "cdk"), + ); + if (installed.exitCode !== 0) { + throw new Error( + `npm could not install @aws/agentcore-cdk@${BOX_CDK} (AGENTCORE_E2E_BOX_CDK).\n` + + `stdout: ${installed.stdout}\nstderr: ${installed.stderr}`, + ); + } + } return created.project.path; } +/** Given a command, its arguments and a working directory, runs it and captures its result. */ +function runCommand(executable: string, args: string[], cwd: string): Promise { + return new Promise((resolve, reject) => { + const child = spawn(executable, args, { cwd, stdio: ["ignore", "pipe", "pipe"] }); + let stdout = ""; + let stderr = ""; + child.stdout!.on("data", (chunk) => (stdout += chunk)); + child.stderr!.on("data", (chunk) => (stderr += chunk)); + child.on("error", reject); + child.on("close", (exitCode) => resolve({ stdout, stderr, exitCode: exitCode ?? -1 })); + }); +} + /** * Given a template test case, runs `agentcore dev` and invokes the runtime locally. Returns the * local invoke's response and everything dev printed. diff --git a/src/core/project/backends/boxRelease.test.ts b/src/core/project/backends/boxRelease.test.ts index 994d24be63..4bf8d0fecf 100644 --- a/src/core/project/backends/boxRelease.test.ts +++ b/src/core/project/backends/boxRelease.test.ts @@ -181,6 +181,20 @@ describe("resolveBoxLinuxBuild from the box release", () => { ); }); + test("replaces the incomplete folder an interrupted install left", async () => { + const home = await temp("box-home-"); + const root = join(home, ".agentcore", "box", `${VERSION}-aarch64-unknown-linux-gnu`); + await mkdir(root, { recursive: true }); + await writeFile(join(root, "box"), "partial"); + const { release, ffi, runner } = await fakeRelease(); + + const build = await resolveBoxLinuxBuild({}, { runner, home, release, ffi }); + + expect(build.binaries).toBe(root); + expect(await readFile(join(root, "box"), "utf8")).toBe("#!box\n"); + expect(existsSync(join(root, "release.json"))).toBe(true); + }); + test("reuses an installed release without downloading again", async () => { const home = await temp("box-home-"); const { release, ffi, runner, commands } = await fakeRelease(); diff --git a/src/core/project/backends/boxRelease.ts b/src/core/project/backends/boxRelease.ts index 52892a232e..353e336c79 100644 --- a/src/core/project/backends/boxRelease.ts +++ b/src/core/project/backends/boxRelease.ts @@ -1,6 +1,7 @@ import { createHash } from "node:crypto"; import { chmodSync, + existsSync, mkdirSync, mkdtempSync, readFileSync, @@ -305,18 +306,28 @@ async function installFfi( /** * Moves the checked `payload` into the cache folder `root`, where another process may be * installing the same release at the same time: several concurrent build or deploy commands each - * download into their own work folder. `root` only ever appears through a rename of a complete - * payload, so once `installed()` holds it is never removed; a process that loses the race keeps - * the winner's copy and drops its own. + * download into their own work folder. A complete `root` only ever appears through a rename of a + * complete payload, and a process that loses the race keeps the winner's copy and drops its own. + * `root` is removed only when the rename fails and `installed()` does not hold, as for a folder an + * interrupted install left. Another process can finish its install between that check and the + * removal; the removal then takes a complete install away, and the next command downloads again. */ function publishInstall(payload: string, root: string, installed: () => boolean): void { if (installed()) return; - // An incomplete folder from an interrupted install; a concurrent process may remove it too. + try { + renameSync(payload, root); + return; + } catch (error) { + // `root` exists: EEXIST or ENOTEMPTY, or EPERM on Windows. It holds the install of a process + // that renamed its payload first, or an incomplete folder from an interrupted install. + if (installed()) return; + if (!existsSync(root)) throw error; + } + // A concurrent process may remove the incomplete folder too. rmSync(root, { recursive: true, force: true }); try { renameSync(payload, root); } catch (error) { - // EEXIST or ENOTEMPTY: another process renamed its payload into `root` first. if (!installed()) throw error; } } From 2e455e3608351d5a055a005fa92e9137d0ae3726 Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 20:42:49 -0800 Subject: [PATCH 11/17] fix(box): Start box from agentcore.json's code folder, not a comment Address leo237's last comments on #2862: - boxStartFolder read the folder box starts in from the local profile's header comment, so a user who edited or removed it moved box back to the project root, with its project-wide grant, and the agent's ${{ workspace }}/.venv went missing. It now takes a CodeZip runtime's codeLocation from agentcore.json; the project root stays for a container and for a profile written before, whose paths name the code folder under the project root. - A comment in serve() still said box starts the agent in the project folder. - EnvLocalFile.upsert replaced only the first line of a key, so a later one, which the parser keeps, left the old key in force while build said it updated it. It replaces every line of the key, and keeps an export line an export line. --- src/core/dev/box.ts | 2 +- src/core/project/boxNetworkSource.ts | 10 ++++--- src/core/project/envLocal.test.ts | 21 +++++++++++++++ src/core/project/envLocal.ts | 11 +++++--- src/core/project/manager.box.test.ts | 2 +- src/core/project/templates/boxProfile.test.ts | 20 +++++++++++++- src/core/project/templates/boxProfile.ts | 26 +++++++++++-------- 7 files changed, 70 insertions(+), 22 deletions(-) diff --git a/src/core/dev/box.ts b/src/core/dev/box.ts index a89f7240b4..0f0d2de801 100644 --- a/src/core/dev/box.ts +++ b/src/core/dev/box.ts @@ -110,7 +110,7 @@ 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 startFolder = boxStartFolder(profileText, input.runtime); const cwd = startFolder === "" ? input.projectRoot diff --git a/src/core/project/boxNetworkSource.ts b/src/core/project/boxNetworkSource.ts index bf17286f3a..f2c9a21401 100644 --- a/src/core/project/boxNetworkSource.ts +++ b/src/core/project/boxNetworkSource.ts @@ -9,6 +9,7 @@ import { tmpdir } from "node:os"; import { dirname, isAbsolute, join, relative, sep } from "node:path"; import { parse as parseToml, stringify as stringifyToml } from "smol-toml"; import type { ProjectSpec } from "../../projectSchemas/project"; +import type { ProjectRuntime } from "../../projectSchemas/runtime"; import { InvalidEnvironmentError, ProjectStateError } from "../../errors/errors"; import type { PolicyFileCopy } from "./backends/boxContainer"; import { DEFAULT_EGRESS_BEDROCK_REGION } from "../../handlers/project/shortcuts"; @@ -66,7 +67,7 @@ export async function readBoxNetworks( // Each boxed agent reads its own .box//local profile and policy files. const { parsed, failures: found } = await readResolvedPolicy( projectRoot, - runtime.name, + runtime, resolver, region, ); @@ -111,16 +112,17 @@ export function boxPolicyFileCopies(projectRoot: string, agentName: string): Pol } /** - * Box's resolution of the local box profile of `agentName` for a build in `region`, parsed, with + * Box's resolution of the local box profile of `runtime` for a build in `region`, parsed, with * the profile's own policy files to place its rules and to stage; nothing when the agent has no * local box profile. */ async function readResolvedPolicy( projectRoot: string, - agentName: string, + runtime: ProjectRuntime, resolver: BoxProfileResolver, region: string, ): Promise<{ parsed: ParsedPolicy; failures: readonly BoxNetworkFailure[] }> { + const agentName = runtime.name; const profileFile = boxLocalProfileFile(agentName); const text = profileText(projectRoot, agentName); if (text === undefined) return { parsed: noPolicy(profileFile), failures: [] }; @@ -137,7 +139,7 @@ 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 startFolder = boxStartFolder(text, runtime); const resolved = forRegion === undefined ? await resolver.resolve(projectRoot, profileFile, startFolder) diff --git a/src/core/project/envLocal.test.ts b/src/core/project/envLocal.test.ts index 53157a3d34..bf2b5ed42d 100644 --- a/src/core/project/envLocal.test.ts +++ b/src/core/project/envLocal.test.ts @@ -167,6 +167,27 @@ 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 every line of a key, so a later one cannot keep the old value", async () => { + const root = await tempRoot(); + const file = new EnvLocalFile(root); + await Bun.write(file.path, "# old\nSECRET='v'\nOTHER=1\nSECRET='stale'\n"); + + await file.upsert([{ key: "SECRET", value: "w", comment: "c" }]); + + expect(await Bun.file(file.path).text()).toStartWith("# old\nSECRET='w'\nOTHER=1\nSECRET='w'\n"); + expect(await file.read()).toEqual({ SECRET: "w", OTHER: "1" }); +}); + +test("upsert keeps an export line an export line", async () => { + const root = await tempRoot(); + const file = new EnvLocalFile(root); + await Bun.write(file.path, "export SECRET='v'\n"); + + await file.upsert([{ key: "SECRET", value: "w", comment: "c" }]); + + expect(await Bun.file(file.path).text()).toStartWith("export SECRET='w'\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); diff --git a/src/core/project/envLocal.ts b/src/core/project/envLocal.ts index f6caff6645..823541aff0 100644 --- a/src/core/project/envLocal.ts +++ b/src/core/project/envLocal.ts @@ -88,17 +88,20 @@ export class EnvLocalFile { } await this.enforcePermissions(); const values = new Map(entries.map((entry) => [entry.key, entry.value ?? ""])); + const encrypted = await this.secrets.encrypt(Object.fromEntries(values)); 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)) { + if (key === undefined || !values.has(key)) { lines.push(line); continue; } - const encrypted = await this.secrets.encrypt({ [key]: values.get(key)! }); - lines.push(`${key}=${formatValue(encrypted[key])}`); - updated.push(key); + // Every line of the key gets the value: the parser keeps the last, so replacing only the + // first would leave an older one in force. An `export` line stays one. + const exported = /^\s*export\s+/.exec(line)?.[0] ?? ""; + lines.push(`${exported}${key}=${formatValue(encrypted[key] ?? "")}`); + if (!updated.includes(key)) updated.push(key); } if (updated.length > 0) { this.snapshot = existing; diff --git a/src/core/project/manager.box.test.ts b/src/core/project/manager.box.test.ts index e7965f56a4..e9975ff726 100644 --- a/src/core/project/manager.box.test.ts +++ b/src/core/project/manager.box.test.ts @@ -345,7 +345,7 @@ describe("gateway targets in a Box project", () => { ); const profile = join(project.rootPath, ".box", "search", "local", "profile.toml"); // dev starts this profile's box in app/search, the runtime's own folder. - expect(boxStartFolder(await readFile(profile, "utf8"))).toBe("app/search"); + expect(boxStartFolder(await readFile(profile, "utf8"), search)).toBe("app/search"); expect(events).toContainEqual({ type: "step", message: `writing box profile ${profile}` }); expect(existsSync(join(project.rootPath, "app", "search", "start.py"))).toBe(true); expect(existsSync(join(project.rootPath, "app", "search", ".venv"))).toBe(true); diff --git a/src/core/project/templates/boxProfile.test.ts b/src/core/project/templates/boxProfile.test.ts index 18df8e00a8..81c9b738d7 100644 --- a/src/core/project/templates/boxProfile.test.ts +++ b/src/core/project/templates/boxProfile.test.ts @@ -88,7 +88,25 @@ describe("renderBoxProfile", () => { expect(profile("agent-python-minimal-box").profile).toEqual({ name: "V3Demo" }); const text = renderBoxProfile("V3Demo", STRANDS)!; expect(text).toContain("runs `box run ../../.box/agent/local/profile.toml` there"); - expect(boxStartFolder(text)).toBe("app/agent"); + expect(boxStartFolder(text, { build: "CodeZip", codeLocation: "app/agent/" })).toBe( + "app/agent", + ); + }); + + // The folder comes from agentcore.json, so a profile's comments, which a user may edit, never + // move box back to the project root and its project-wide grant. + test("starts a CodeZip runtime's box in its code folder, whatever the profile's comments say", () => { + const codeZip = { build: "CodeZip", codeLocation: "app/agent" }; + const text = renderBoxProfile("V3Demo", STRANDS)!; + const noComments = text + .split("\n") + .filter((line) => !line.startsWith("#")) + .join("\n"); + expect(boxStartFolder(noComments, codeZip)).toBe("app/agent"); + // A container profile describes the image's /app. + expect(boxStartFolder(text, { build: "Container", codeLocation: "app/agent" })).toBe(""); + // A profile written before this names the code folder under the project root, so it runs there. + expect(boxStartFolder('read = ["${{ workspace }}/app/agent"]\n', codeZip)).toBe(""); }); // agentcore dev starts box in app/, so ${{ workspace }} and the project grant are that diff --git a/src/core/project/templates/boxProfile.ts b/src/core/project/templates/boxProfile.ts index e1520cbd92..d4e61b28fa 100644 --- a/src/core/project/templates/boxProfile.ts +++ b/src/core/project/templates/boxProfile.ts @@ -171,17 +171,20 @@ export function hasBoxProfile(runtime: ScaffoldRuntimeInput): boolean { return startsInBoxOnCodeZip(runtime) || isBoxedContainer(runtime); } -/** The header line of a CodeZip profile that names the folder `agentcore dev` starts box in. */ -const START_FOLDER_LINE = - /^# Written by `agentcore create` or `agentcore add runtime` 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. + * The folder, from the project root, that box starts a run or a resolution of `runtime`'s local + * profile in: the runtime's own code folder for a CodeZip runtime, from agentcore.json, so the + * agent's grants reach no further than it, whatever the profile's comments say. The project root + * ("") for a container runtime, whose profile describes the image's /app, and for a profile + * written before box started in the code folder: its paths name that folder under the project root. */ -export function boxStartFolder(profileText: string): string { - return START_FOLDER_LINE.exec(profileText)?.[1] ?? ""; +export function boxStartFolder( + profileText: string, + runtime: { readonly build: string; readonly codeLocation: string }, +): string { + if (runtime.build !== "CodeZip") return ""; + if (profileText.includes("${{ workspace }}/app/")) return ""; + return runtime.codeLocation.replace(/^\.\/+/, "").replace(/\/+$/, ""); } /** The Strands box container template, whose image starts `box run` in /app. */ export function isBoxedContainer(runtime: ScaffoldRuntimeInput): boolean { @@ -341,8 +344,9 @@ function serve( env: { PORT: String(workloadPort) }, }; } - // 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. + // box starts the agent in the folder it runs in (the runtime's own, locally), and 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, and AGENTCORE_RUNTIME_URL takes // precedence. Locally, callers reach the agent only through box's ingress port, so the card names From 21e2c917f9c2b684abb4dad95be64ca58e306b89 Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 21:04:33 -0800 Subject: [PATCH 12/17] fix(box): Start every CodeZip box in its code folder, with no fallback boxStartFolder kept the project root for a profile whose text named ${{ workspace }}/app/, as a profile from before box started in the code folder does. A current profile that grants ${{ workspace }}/app/ matched it too, and box quietly started at the project root again, with its project-wide grant. Box projects are new, so there is no older profile to run: a CodeZip runtime's box starts in its codeLocation, and a container's in the project root. The dev runner's comment says so. --- src/core/dev/box.test.ts | 27 +++++++++---------- src/core/dev/box.ts | 7 ++--- src/core/project/boxNetworkSource.ts | 2 +- src/core/project/manager.box.test.ts | 2 +- src/core/project/templates/boxProfile.test.ts | 21 ++++----------- src/core/project/templates/boxProfile.ts | 15 +++++------ 6 files changed, 31 insertions(+), 43 deletions(-) diff --git a/src/core/dev/box.test.ts b/src/core/dev/box.test.ts index c497ae585b..1c7848ba03 100644 --- a/src/core/dev/box.test.ts +++ b/src/core/dev/box.test.ts @@ -132,46 +132,45 @@ describe("BoxDevRunner", () => { expect(fallbackRuns).toHaveLength(1); }); - test("runs a profile written before from the project folder", async () => { + test("runs the agent's box profile from the runtime's code folder", async () => { const { projectRoot, calls, fallbackRuns, runner } = await scene(true); const events = await collect(runner.run(input(projectRoot))); expect(calls.map(({ command }) => command)).toEqual([ - ["box", "run", ".box/agent/local/profile.toml", "--no-banner"], + ["box", "run", "../../.box/agent/local/profile.toml", "--no-banner"], ]); - expect(calls[0]!.options.cwd).toBe(projectRoot); + expect(calls[0]!.options.cwd).toBe(join(projectRoot, "app", "agent")); expect(fallbackRuns).toEqual([]); expect(events).toEqual([ TRACES_NOTICE, { type: "status", - message: "Starting the agent in a box (box run .box/agent/local/profile.toml)", + message: "Starting the agent in a box (box run ../../.box/agent/local/profile.toml)", }, { type: "stdout", line: "Uvicorn running" }, ]); }); - test("starts box in the runtime's folder for a profile create writes now", async () => { + test("starts box in the runtime's folder for a profile create writes, whatever it says", 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. + // project: not agentcore/.env.local, which holds the model's key. The folder comes from + // agentcore.json, so a profile without its header comment starts there too. const runtime = resolveRuntimeTemplateShortcut("agent-python-strands-box", { runtimeName: "agent", }); - const { projectRoot, calls, runner } = await scene(true, true, { - profile: renderBoxProfile("Demo", runtime)!, - }); + const noComments = renderBoxProfile("Demo", runtime)! + .split("\n") + .filter((line) => !line.startsWith("#")) + .join("\n"); + const { projectRoot, calls, runner } = await scene(true, true, { profile: noComments }); - const events = await collect(runner.run(input(projectRoot))); + await collect(runner.run(input(projectRoot))); expect(calls.map(({ command }) => command)).toEqual([ ["box", "run", "../../.box/agent/local/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/agent/local/profile.toml)", - }); }); test("hands box run the .env.local values, so it can attach the API key, and not dev's OTEL ones", async () => { diff --git a/src/core/dev/box.ts b/src/core/dev/box.ts index 0f0d2de801..b97726714e 100644 --- a/src/core/dev/box.ts +++ b/src/core/dev/box.ts @@ -108,9 +108,10 @@ export class BoxDevRunner implements DevRunner { 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, input.runtime); + // box starts in the runtime's code folder for a CodeZip runtime (the project root for a + // container), so the agent reaches no other folder of the project; box finds the profile from + // there. + const startFolder = boxStartFolder(input.runtime); const cwd = startFolder === "" ? input.projectRoot diff --git a/src/core/project/boxNetworkSource.ts b/src/core/project/boxNetworkSource.ts index f2c9a21401..6ad367b6bd 100644 --- a/src/core/project/boxNetworkSource.ts +++ b/src/core/project/boxNetworkSource.ts @@ -139,7 +139,7 @@ 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, runtime); + const startFolder = boxStartFolder(runtime); const resolved = forRegion === undefined ? await resolver.resolve(projectRoot, profileFile, startFolder) diff --git a/src/core/project/manager.box.test.ts b/src/core/project/manager.box.test.ts index e9975ff726..efad706561 100644 --- a/src/core/project/manager.box.test.ts +++ b/src/core/project/manager.box.test.ts @@ -345,7 +345,7 @@ describe("gateway targets in a Box project", () => { ); const profile = join(project.rootPath, ".box", "search", "local", "profile.toml"); // dev starts this profile's box in app/search, the runtime's own folder. - expect(boxStartFolder(await readFile(profile, "utf8"), search)).toBe("app/search"); + expect(boxStartFolder(search)).toBe("app/search"); expect(events).toContainEqual({ type: "step", message: `writing box profile ${profile}` }); expect(existsSync(join(project.rootPath, "app", "search", "start.py"))).toBe(true); expect(existsSync(join(project.rootPath, "app", "search", ".venv"))).toBe(true); diff --git a/src/core/project/templates/boxProfile.test.ts b/src/core/project/templates/boxProfile.test.ts index 81c9b738d7..e6951250a3 100644 --- a/src/core/project/templates/boxProfile.test.ts +++ b/src/core/project/templates/boxProfile.test.ts @@ -88,25 +88,14 @@ describe("renderBoxProfile", () => { expect(profile("agent-python-minimal-box").profile).toEqual({ name: "V3Demo" }); const text = renderBoxProfile("V3Demo", STRANDS)!; expect(text).toContain("runs `box run ../../.box/agent/local/profile.toml` there"); - expect(boxStartFolder(text, { build: "CodeZip", codeLocation: "app/agent/" })).toBe( - "app/agent", - ); }); - // The folder comes from agentcore.json, so a profile's comments, which a user may edit, never - // move box back to the project root and its project-wide grant. - test("starts a CodeZip runtime's box in its code folder, whatever the profile's comments say", () => { - const codeZip = { build: "CodeZip", codeLocation: "app/agent" }; - const text = renderBoxProfile("V3Demo", STRANDS)!; - const noComments = text - .split("\n") - .filter((line) => !line.startsWith("#")) - .join("\n"); - expect(boxStartFolder(noComments, codeZip)).toBe("app/agent"); + // The folder comes from agentcore.json, never from the profile, which a user may edit. + test("starts a CodeZip runtime's box in its code folder, and a container's in the project root", () => { + expect(boxStartFolder({ build: "CodeZip", codeLocation: "app/agent/" })).toBe("app/agent"); + expect(boxStartFolder({ build: "CodeZip", codeLocation: "./app/agent" })).toBe("app/agent"); // A container profile describes the image's /app. - expect(boxStartFolder(text, { build: "Container", codeLocation: "app/agent" })).toBe(""); - // A profile written before this names the code folder under the project root, so it runs there. - expect(boxStartFolder('read = ["${{ workspace }}/app/agent"]\n', codeZip)).toBe(""); + expect(boxStartFolder({ build: "Container", codeLocation: "app/agent" })).toBe(""); }); // agentcore dev starts box in app/, so ${{ workspace }} and the project grant are that diff --git a/src/core/project/templates/boxProfile.ts b/src/core/project/templates/boxProfile.ts index d4e61b28fa..5746bd2b65 100644 --- a/src/core/project/templates/boxProfile.ts +++ b/src/core/project/templates/boxProfile.ts @@ -174,18 +174,17 @@ export function hasBoxProfile(runtime: ScaffoldRuntimeInput): boolean { /** * The folder, from the project root, that box starts a run or a resolution of `runtime`'s local * profile in: the runtime's own code folder for a CodeZip runtime, from agentcore.json, so the - * agent's grants reach no further than it, whatever the profile's comments say. The project root - * ("") for a container runtime, whose profile describes the image's /app, and for a profile - * written before box started in the code folder: its paths name that folder under the project root. + * agent's grants reach no further than it, whatever the profile says. The project root ("") for a + * container runtime, whose profile describes the image's /app. */ -export function boxStartFolder( - profileText: string, - runtime: { readonly build: string; readonly codeLocation: string }, -): string { +export function boxStartFolder(runtime: { + readonly build: string; + readonly codeLocation: string; +}): string { if (runtime.build !== "CodeZip") return ""; - if (profileText.includes("${{ workspace }}/app/")) return ""; return runtime.codeLocation.replace(/^\.\/+/, "").replace(/\/+$/, ""); } + /** The Strands box container template, whose image starts `box run` in /app. */ export function isBoxedContainer(runtime: ScaffoldRuntimeInput): boolean { return ( From acb9b4c57f969b3092755059f30109888e3ec4e5 Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 21:04:34 -0800 Subject: [PATCH 13/17] fix(box): Stop start.py on a policies line it cannot read on 3.10 On Python 3.10, with no tomllib, start.py reads the staged profile's policies with a regex, and a line in any other form gave no policy files and no message, so box failed later with an unclear error. start.py now stops with an error that names the line. A test runs staged_policies with no tomllib on the profiles deploy renders. --- src/assets/templates/box-codezip/start.py | 11 +- src/core/project/backends/boxStartPy.test.ts | 101 +++++++++++++++++++ 2 files changed, 111 insertions(+), 1 deletion(-) create mode 100644 src/core/project/backends/boxStartPy.test.ts diff --git a/src/assets/templates/box-codezip/start.py b/src/assets/templates/box-codezip/start.py index 5e3d752c42..03e0bbaeae 100644 --- a/src/assets/templates/box-codezip/start.py +++ b/src/assets/templates/box-codezip/start.py @@ -41,7 +41,16 @@ def staged_policies(path): 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 [] + if match is not None: + return json.loads(match.group(1)) + # Any other `policies` line would leave box without its policy files, and failing later. + if re.search(rb"^\s*policies\s*=", text, re.MULTILINE): + sys.exit( + f"{path} has a `policies` line start.py cannot read on Python " + f"{sys.version_info.major}.{sys.version_info.minor}, which has no tomllib. Deploy " + "writes it as `policies = [\"a.dw\", ...]` on one line; run agentcore deploy again." + ) + return [] # box reads a profile's policy files from beside it, so copy the profile and each file its diff --git a/src/core/project/backends/boxStartPy.test.ts b/src/core/project/backends/boxStartPy.test.ts new file mode 100644 index 0000000000..bd95f7202e --- /dev/null +++ b/src/core/project/backends/boxStartPy.test.ts @@ -0,0 +1,101 @@ +import { afterEach, describe, expect, test } from "bun:test"; +import { mkdtemp, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import type { ProjectSpec } from "../../../projectSchemas/project"; +import { renderRuntimeBoxProfile } from "../templates/boxProfile"; + +/** The CodeZip box agent's entry point, which runs on the Runtime's Python. */ +const START_PY = join( + import.meta.dir, + "..", + "..", + "..", + "assets", + "templates", + "box-codezip", + "start.py", +); + +/** A Python 3 on PATH, which the CI runners have; the tests skip without one. */ +const PYTHON = ["python3", "python"].find( + (name) => + Bun.spawnSync([name, "-c", "import sys; assert sys.version_info >= (3,)"]).exitCode === 0, +); + +/** + * Runs start.py's staged_policies on `profile` as Python 3.10 does, with no tomllib: only the + * imports and the function run, not the rest of start.py, which would start box. + */ +const HARNESS = ` +import ast, json, sys +tree = ast.parse(open(sys.argv[1]).read()) +keep = [n for n in tree.body if isinstance(n, (ast.Import, ast.ImportFrom)) + or (isinstance(n, ast.FunctionDef) and n.name == "staged_policies")] +scope = {} +exec(compile(ast.Module(body=keep, type_ignores=[]), "start.py", "exec"), scope) +scope["tomllib"] = None +print(json.dumps(scope["staged_policies"](sys.argv[2]))) +`; + +const folders: string[] = []; +afterEach(async () => { + await Promise.all( + folders.splice(0).map((folder) => rm(folder, { recursive: true, force: true })), + ); +}); + +async function run(profile: string) { + const folder = await mkdtemp(join(tmpdir(), "box-start-py-")); + folders.push(folder); + const path = join(folder, "profile.toml"); + await writeFile(path, profile); + const result = Bun.spawnSync([PYTHON!, "-c", HARNESS, START_PY, path]); + return { + exitCode: result.exitCode, + stdout: result.stdout.toString(), + stderr: result.stderr.toString(), + }; +} + +const SPEC = { + name: "V3Demo", + runtimes: [ + { + name: "agent", + build: "CodeZip", + entrypoint: "start.py", + codeLocation: "app/agent", + protocol: "HTTP", + modelProvider: "Bedrock", + }, + ], + agentCoreGateways: [], +} as unknown as ProjectSpec; + +describe.skipIf(PYTHON === undefined)("start.py with no tomllib, as on Python 3.10", () => { + test("reads the policies of a Runtime profile deploy renders", async () => { + const profile = renderRuntimeBoxProfile(SPEC, SPEC.runtimes[0]!, { + policyFiles: ["policy.dw", "rules/extra.dw"], + }); + + const result = await run(profile); + + expect(result.exitCode).toBe(0); + expect(JSON.parse(result.stdout)).toEqual(["policy.dw", "rules/extra.dw"]); + }); + + test("reads no policies from a profile that names none", async () => { + const result = await run(renderRuntimeBoxProfile(SPEC, SPEC.runtimes[0]!)); + + expect(result.exitCode).toBe(0); + expect(JSON.parse(result.stdout)).toEqual([]); + }); + + test("stops with a clear error for a policies line it cannot read", async () => { + const result = await run('policies = [\n "policy.dw",\n]\n'); + + expect(result.exitCode).not.toBe(0); + expect(result.stderr).toContain("has a `policies` line start.py cannot read"); + }); +}); From ad4617d83ad5593f305e5e2c74f2d8739acaabef Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 21:04:35 -0800 Subject: [PATCH 14/17] fix(box): Keep upsert's first snapshot, and say which GITHUB_TOKEN build reads EnvLocalFile.upsert snapshotted the file before its in-place write, then insertIfNew snapshotted the half-updated file, and the first one came back only if insertIfNew succeeded. It now keeps the earliest snapshot, as removeKeys does, so rollback restores the original file. The local testing guide said a build with GITHUB_TOKEN unset keeps the stored key. Build reads GITHUB_TOKEN from .env.local too, so a line there replaces the stored key, even with an older one. --- docs/box-local-testing.md | 6 ++++-- src/core/project/envLocal.test.ts | 17 +++++++++++++++++ src/core/project/envLocal.ts | 19 ++++++++++++------- 3 files changed, 33 insertions(+), 9 deletions(-) diff --git a/docs/box-local-testing.md b/docs/box-local-testing.md index a7b9d1ae70..ef05714149 100644 --- a/docs/box-local-testing.md +++ b/docs/box-local-testing.md @@ -151,8 +151,10 @@ 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`. 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. +rotation, so deploy provisions the key `agentcore dev` uses. Build reads `GITHUB_TOKEN` as dev +does: from your shell, or from `agentcore/.env.local` when the shell has none. So a +`GITHUB_TOKEN` line in `agentcore/.env.local` replaces the stored key too, even with an older +key; keep the key in one place. With `GITHUB_TOKEN` in neither, build keeps the stored key. ``` cd "$DEMO/$PROJECT" diff --git a/src/core/project/envLocal.test.ts b/src/core/project/envLocal.test.ts index bf2b5ed42d..49005bcc42 100644 --- a/src/core/project/envLocal.test.ts +++ b/src/core/project/envLocal.test.ts @@ -178,6 +178,23 @@ test("upsert replaces every line of a key, so a later one cannot keep the old va expect(await file.read()).toEqual({ SECRET: "w", OTHER: "1" }); }); +test("rollback after a failed upsert restores the file from before it, not the half-written one", async () => { + const root = await tempRoot(); + const file = new EnvLocalFile(root); + await Bun.write(file.path, "# old\nSECRET='v'\n"); + + // The new key's value has a quote, so the append fails after the in-place replacement. + await expect( + file.upsert([ + { key: "SECRET", value: "w", comment: "c" }, + { key: "NEW", value: "a'b", comment: "c" }, + ]), + ).rejects.toThrow(/single quote/); + await file.rollback(); + + expect(await Bun.file(file.path).text()).toBe("# old\nSECRET='v'\n"); +}); + test("upsert keeps an export line an export line", 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 823541aff0..277f9f23c0 100644 --- a/src/core/project/envLocal.ts +++ b/src/core/project/envLocal.ts @@ -103,18 +103,23 @@ export class EnvLocalFile { lines.push(`${exported}${key}=${formatValue(encrypted[key] ?? "")}`); if (!updated.includes(key)) updated.push(key); } + // Keep the earliest snapshot, as removeKeys does, so rollback undoes this whole call even when + // insertIfNew, which snapshots the file it starts from, fails after the in-place write. + const snapshot = this.snapshot === undefined ? existing : this.snapshot; if (updated.length > 0) { - this.snapshot = existing; + this.snapshot = snapshot; 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 }; + try { + const { written } = await this.insertIfNew( + entries.filter((entry) => !updated.includes(entry.key)), + ); + return { written, updated }; + } finally { + if (updated.length > 0) this.snapshot = snapshot; + } } /** From 5a6a4417e7c9dffcc9e4c05e81d00404883bdec8 Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 21:04:36 -0800 Subject: [PATCH 15/17] test(e2e): Wait for the invoke's own log line before the error check The Box deploy cases waited a fixed 30 s after 'running profile' and then checked that no error line was logged, so a line CloudWatch delivered later passed unseen. They now wait for the agent server's access line for the invoke's POST first. Also: a README note that the Python 3.10-3.13 box cases pass only with #2867, a test of publishInstall's lost rename race, and two comment fixes. --- e2eTest/README.md | 4 +- e2eTest/project/templates.test.ts | 24 ++++++++--- src/core/project/backends/boxRelease.test.ts | 45 ++++++++++++++++++++ src/core/project/backends/boxRelease.ts | 5 ++- 4 files changed, 69 insertions(+), 9 deletions(-) diff --git a/e2eTest/README.md b/e2eTest/README.md index 911f55f445..2910594f9b 100644 --- a/e2eTest/README.md +++ b/e2eTest/README.md @@ -46,7 +46,9 @@ AGENTCORE_E2E_BOX_CDK=file:/path/to/aws-agentcore-cdk-1.1.0.tgz bun run test:e2e That runs each Box template on its default Python. The CodeZip box template on Python 3.10 to 3.13 (`py_strands_box_3_10` to `py_strands_box_3_13`) is in the runtime templates describe, so it runs -with `--tagsFilter='runtime'` or a full run, given `box` and the same opt-in. +with `--tagsFilter='runtime'` or a full run, given `box` and the same opt-in. Those four cases +pass only once box runs CodeZip agents without the ffi shim (#2867): until then `boxRelease.json` +pins a shim for `PYTHON_3_14` only, so they fail on any machine. The `box-egress` test checks that box, under `agentcore dev`, lets the agent reach the host its profile allows (`checkip.amazonaws.com`) and blocks any other (`example.com`). It reaches public diff --git a/e2eTest/project/templates.test.ts b/e2eTest/project/templates.test.ts index 35a8fc0ca3..9a1ca5478b 100644 --- a/e2eTest/project/templates.test.ts +++ b/e2eTest/project/templates.test.ts @@ -24,9 +24,8 @@ type RuntimeTemplateTestCase = { /** * A Strands Box template: it runs its agent in a box on AgentCore Runtime, so the test checks the * Runtime's logs for box starting it, and installs the AGENTCORE_E2E_BOX_CDK build to deploy it. - * `agentcore dev` runs box on the - * protocol's fixed ingress port (8080, 8000 or 9000), so the concurrent Runtime tests skip it; the - * sequential dev tests below cover it. + * `agentcore dev` runs box on the protocol's fixed ingress port (8080, 8000 or 9000), so the + * concurrent Runtime tests skip it; the sequential dev tests below cover it. */ box?: boolean; }; @@ -538,9 +537,22 @@ async function assertRunsInBox(cli: CliRunner, projectDir: string): Promise setTimeout(resolve, 30 * 1000)); + // never logs. box logs `running profile` when it starts, before the invoke, so the check first + // waits for a line the invoke itself writes, the agent server's access line for its POST, so + // the invoke's own lines have reached CloudWatch when it looks for errors. + await retry( + async () => { + const found = await logs('"POST /"'); + if (found.exitCode !== 0 || !found.stdout.includes("POST /")) { + throw new Error( + `the Runtime's logs show no request from the invoke yet.\nstdout: ${found.stdout}\nstderr: ${found.stderr}`, + ); + } + return found; + }, + 2 * 60 * 1000, + 10 * 1000, + ); const errors = await logs('?ERROR ?"blocked by egress control" ?AccessDenied'); expect(errors.exitCode).toBe(0); expect(errors.stdout).not.toMatch(/ERROR|blocked by egress control|AccessDenied/); diff --git a/src/core/project/backends/boxRelease.test.ts b/src/core/project/backends/boxRelease.test.ts index 4bf8d0fecf..e3b78364b1 100644 --- a/src/core/project/backends/boxRelease.test.ts +++ b/src/core/project/backends/boxRelease.test.ts @@ -13,6 +13,7 @@ import { type BoxRelease, type FfiRelease, boxReleaseFor, + publishInstall, resolveBoxLinuxBuild, } from "./boxRelease"; @@ -298,6 +299,50 @@ describe("boxReleaseFor a runtime's box.version", () => { }); }); +describe("publishInstall", () => { + /** A payload and a cache folder `root` beside it, each holding `file` with its folder's text. */ + async function folders(rootText?: string) { + const parent = await temp("box-publish-"); + const payload = join(parent, "payload"); + const root = join(parent, "root"); + await mkdir(payload); + await writeFile(join(payload, "box"), "mine"); + if (rootText !== undefined) { + await mkdir(root); + await writeFile(join(root, "box"), rootText); + } + return { payload, root }; + } + + test("keeps the install another process renamed in after the first check, before the rename", async () => { + // `root` is complete only by the time the rename fails: the other process won in between. + const { payload, root } = await folders("theirs"); + let checks = 0; + + publishInstall(payload, root, () => checks++ > 0); + + expect(await readFile(join(root, "box"), "utf8")).toBe("theirs"); + expect(checks).toBe(2); + }); + + test("replaces an incomplete folder an interrupted install left", async () => { + const { payload, root } = await folders("partial"); + + publishInstall(payload, root, () => false); + + expect(await readFile(join(root, "box"), "utf8")).toBe("mine"); + expect(existsSync(payload)).toBe(false); + }); + + test("renames the payload in when no install is there", async () => { + const { payload, root } = await folders(); + + publishInstall(payload, root, () => false); + + expect(await readFile(join(root, "box"), "utf8")).toBe("mine"); + }); +}); + describe("the pinned releases", () => { test("box and the ffi shim are pinned on their own, with a shim for each Python box runs", () => { expect(BOX_RELEASE.linux.asset).toContain(BOX_RELEASE.version); diff --git a/src/core/project/backends/boxRelease.ts b/src/core/project/backends/boxRelease.ts index 353e336c79..c55475a8aa 100644 --- a/src/core/project/backends/boxRelease.ts +++ b/src/core/project/backends/boxRelease.ts @@ -310,9 +310,10 @@ async function installFfi( * complete payload, and a process that loses the race keeps the winner's copy and drops its own. * `root` is removed only when the rename fails and `installed()` does not hold, as for a folder an * interrupted install left. Another process can finish its install between that check and the - * removal; the removal then takes a complete install away, and the next command downloads again. + * removal; the removal then takes that install away while its command may still be reading it, and + * this process's own payload replaces it. */ -function publishInstall(payload: string, root: string, installed: () => boolean): void { +export function publishInstall(payload: string, root: string, installed: () => boolean): void { if (installed()) return; try { renameSync(payload, root); From f7391f2447feeabe05a09279ea37eb19c8822d74 Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 21:05:46 -0800 Subject: [PATCH 16/17] docs(box): Drop the troubleshooting item for earlier branch builds Box is only for new projects, so the guide gives no cleanup hints for .env.local lines that earlier box-integration builds wrote. --- docs/box-local-testing.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/box-local-testing.md b/docs/box-local-testing.md index ef05714149..c97d0b4f9c 100644 --- a/docs/box-local-testing.md +++ b/docs/box-local-testing.md @@ -223,10 +223,5 @@ 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`. From 96c63bd98262e9eb1f5a5b44e192866b148dbb0c Mon Sep 17 00:00:00 2001 From: Quang Nguyen Date: Thu, 19 Nov 2026 21:36:46 -0800 Subject: [PATCH 17/17] test(box): find Python on Windows without throwing Bun.spawnSync throws on Windows when the executable is not on PATH, so the python3 probe failed the file before any test ran. --- src/core/project/backends/boxStartPy.test.ts | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/src/core/project/backends/boxStartPy.test.ts b/src/core/project/backends/boxStartPy.test.ts index bd95f7202e..85445a2639 100644 --- a/src/core/project/backends/boxStartPy.test.ts +++ b/src/core/project/backends/boxStartPy.test.ts @@ -18,10 +18,16 @@ const START_PY = join( ); /** A Python 3 on PATH, which the CI runners have; the tests skip without one. */ -const PYTHON = ["python3", "python"].find( - (name) => - Bun.spawnSync([name, "-c", "import sys; assert sys.version_info >= (3,)"]).exitCode === 0, -); +const PYTHON = ["python3", "python"].find((name) => { + // On Windows, spawnSync throws, rather than failing, for a name not on PATH. + try { + return ( + Bun.spawnSync([name, "-c", "import sys; assert sys.version_info >= (3,)"]).exitCode === 0 + ); + } catch { + return false; + } +}); /** * Runs start.py's staged_policies on `profile` as Python 3.10 does, with no tomllib: only the