Skip to content

feat(dev): Hand box run the profile's env:// keys instead of copying them to .env.local - #2862

Merged
mquang-amazon merged 15 commits into
box-integrationfrom
box/mq-6
Nov 20, 2026
Merged

mquang-amazon merged 15 commits into
box-integrationfrom
box/mq-6

Conversation

@mquang-amazon

Copy link
Copy Markdown
Contributor

Description

MQ-6 (phase 11) of the Box integration squash plan: agentcore dev hands box run the box profile's env:// keys instead of copying them into agentcore/.env.local. Ported from 290ee861 on box-integration-development onto box-integration (the SYNC back-merge has not run).

  • Dev writes nothing. Each env:// key of an [egress.<name>] route or an [mcp.<name>] server goes to box run's environment: the shell's value first, then .env.local's.
  • A CodeZip agent's box run inherits it. A box container gets it through the run's own env file, never on the command line.
  • When neither has the key, dev warns, naming the variable, the table that reads it, and how to set it. box run still starts and reports its own error.
  • boxEnvLocal.ts (writeBoxDevEnvLocal) and its test are removed.

Conflicts, fixed with box-integration as the source of truth:

  • box-integration has one profile, .box/profile.toml, not dev's .box/<agent>/local/profile.toml. So boxDevSecrets(projectRoot, env) reads boxProfilePath(projectRoot) and takes no agent name, and the warning names .box/profile.toml. It uses box-integration's hasValue.
  • dev/index.ts keeps box-integration's boxProfilePath import and drops the writeBoxDevEnvLocal call.
  • The test helpers write .box/profile.toml, as on box-integration.
  • The docs/box-local-testing.md hunk is left for DOCS-2.

readBoxEnvRoutes and parseBoxEnvRoutes in boxProfileEgress.ts now have no caller outside their tests (writeBoxDevEnvLocal was the only one). I left them in place; say if you want them removed here.

Related Issue

Box integration squash plan, phase 11.

Testing

  • bun test: 5340 pass, 1 fail (the known the box on PATH > resolves a profile test, which fails only with the local box preview.6)
  • bun test src/core/dev: 230 pass
  • bun run typecheck, bun run lint:check, Prettier, bun run build, bun run compile:darwin-arm64, bun run secrets:check: pass
  • Not run here: agentcore dev by hand, and the e2e suite. The dev-branch commit was tested with container dev under Finch and an [egress.github] route, and with the full e2e suite.

…them to .env.local

Dev used to copy each variable an [egress] route of the box profile names from the shell into agentcore/.env.local. It now writes nothing: each env:// key of an [egress] route or an [mcp] server goes to box run's environment, the shell's value first and .env.local's when the shell has none. A CodeZip agent's box run inherits it; a box container gets it through the run's own env file, never on the command line. When neither has it, dev warns, naming the variable, the table that reads it, and how to set it.

Tested: bun test (5399 pass); container dev with Finch and an [egress.github] route, with the token set on the command line (no .env.local write, the agent answers) and without it (the warning, then box's own error); the full e2e suite: 15 harness, 15 runtime template and 7 box template cases.
@mquang-amazon
mquang-amazon requested a review from a team November 19, 2026 22:42
@codecov-commenter

codecov-commenter commented Nov 19, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.75%. Comparing base (1405932) to head (f9e63f1).

Additional details and impacted files
@@                Coverage Diff                @@
##           box-integration    #2862    +/-   ##
=================================================
  Coverage            96.74%   96.75%            
=================================================
  Files                  757      757            
  Lines                65530    65642   +112     
=================================================
+ Hits                 63398    63511   +113     
+ Misses                2132     2131     -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@leo237 leo237 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Plan PR: MQ-6 (phase 11) of the Box integration squash plan. The plan doc returned 401, so I checked the commits against the branches directly.

Commit-list check. The PR has one commit, b309d610, which ports 290ee861 from box-integration-development. I diffed the dev commit against this PR. The only differences are the ones the description lists:

  • .box/profile.toml instead of .box/<agent>/local/profile.toml, so there's no agentName parameter;
  • hasValue from boxProfileEgress;
  • the docs/box-local-testing.md hunk is left out for DOCS-2.

Nothing is missing or extra. The later dev commits that touch this code are 967cc9f1 (the @box/ comment rename, which belongs to its own PR) and 868325c0 (Windows tests for the now-deleted boxEnvLocal.test.ts, already on box-integration as b69851ca). Neither is needed here. Nothing from a merged PR, #2859 or #2860 is applied twice.

Protected box-integration-only fixes. This PR touches only src/core/dev/{box,boxDevSecrets,boxEnvLocal,container}* and src/handlers/project/dev/index.ts. None of the protected fixes are touched: boxProfileCredentials.ts, boxProfile.ts, the #2851 policies, the #2853 template and runtimeRunsInBox work, 68d2bbb4 and c1bc4576 all survive.

Review

The change looks right. Precedence is the same in both runners: the shell's value wins over .env.local's. For a CodeZip agent, spawning with { ...processEnv, ...fileEnv, ...secrets.env } restores the shell's value for the profile's own keys. For a container agent, the keys go through the 0o600 env file only (serializeEnvironment still rejects newlines), and the file is removed when the run ends. Removing writeBoxDevEnvLocal means agentcore dev no longer writes secrets to disk. The new type (BoxDevSecrets: readonly env and missing, with BoxDevSecretVariable) is small, readonly and fit for purpose. The comments match the code.

Tests: boxDevSecrets has unit tests for egress, MCP, dedupe, blank values, pack and aws:// refs, an unparseable profile and no profile. The CodeZip runner has tests for shell-only, shell over .env.local, .env.local-only and the missing-key warning. The container runner has tests for the env file only (not argv, and no unrelated shell keys) and the warning.

Findings

  1. Windows: two expected strings hard-code agentcore/.env.local (inline). missingBoxSecretWarning builds its message with ENV_LOCAL_RELATIVE_PATH = join("agentcore", ".env.local"), which is agentcore\.env.local on Windows. The warning tests in box.test.ts and boxDevSecrets.test.ts compare against the literal POSIX path, so they should fail on Windows. That is the same pattern b69851ca fixed in boxEnvLocal.test.ts. Interpolate ENV_LOCAL_RELATIVE_PATH into the expected strings. The dev commit 290ee861 has the same literals, so no later planned commit fixes this. Confirmed by CI: verify / Windows fails on exactly these two tests (boxDevSecrets.test.ts:104 and box.test.ts:217, with agentcore\.env.local received). This is the only blocking item.
  2. Semantic conflict with #2859 (non-blocking, for coordination). #2859 removes BOX_PROFILE_FILE and boxProfilePath in favour of boxLocalProfileFile(agent) and boxLocalProfilePath(root, agent). Whichever of #2859 and this PR merges second will fail to typecheck. If #2859 goes first, boxDevSecrets and missingBoxSecretWarning should take the agent name, as in 290ee861. If this PR goes first, #2859's rebase has to make that change.
  3. Open item assigned to MQ-6 is not addressed here. The empty .venv that c1bc4576 writes for CodeZip box agents with --skip-install still gets past dev's check, because src/core/dev/box.ts (existsSync(venv), now around lines 82-87) only tests that the folder exists. So agentcore dev shows box's "missing Python" error instead of the "Run uv sync" hint. There's no fix for this on box-integration-development either, since dev never writes the empty .venv. Please add it here, or say which follow-up will take it. I'm not blocking on it because the behaviour is already on the base and isn't a regression from this PR.
  4. Nit: dead code. As you noted, readBoxEnvRoutes and parseBoxEnvRoutes (and the BoxEnvRoute/BoxEnvRoutes types) in src/core/project/boxProfileEgress.ts now have no non-test caller. They also duplicate the egress parse in boxDevSecrets. box-integration-development doesn't have them, so I'd remove them (and their tests) here and keep hasValue. Not blocking.
  5. Nit: blank variable name (inline). parseBoxEnvRoutes skips env:// followed by only whitespace (variable.trim() === ""). boxDevSecrets checks variable === "", so secret.ref = "env:// " would produce a warning about a variable named " ". Not blocking.
  6. Nit: container precedence test. The container tests cover shell-only and missing, but not shell over .env.local (input.env) for a boxed container. That ordering depends on Object.assign(forwardedEnv, secrets.env) coming after Object.assign(forwardedEnv, input.env, ...), so a one-line test would pin it. Not blocking.

Other open items (none addressed by this PR; that's fine, they belong to later PRs):

  • the network?.region ?? DEFAULT_EGRESS_BEDROCK_REGION fallback;
  • the unreported credential refresh failure in agentcore dev, and a misspelled AWS_PROFILE failing silently;
  • dev not applying the box.version rule;
  • the "before anything is written" comment on the assert;
  • the wrong refusal message after remove;
  • the seven duplicated template files;
  • no start.py test;
  • the otlp/langfuse/langsmith/file telemetry targets skipped with no message (29d283d6, SA-4);
  • no local-profile test for the A2A, AG-UI and MCP box templates;
  • #2859's empty profile when .box/<name>/local/profile.toml is missing.

Known flaky CI (the Windows transactionSearch EFAULT test, and the macOS 5 s screen-test timeouts or slow queue) is non-blocking.

CI: Linux, CodeQL/Analyze and CodeBuild e2e pass. verify / Windows fails, on the two new tests in finding 1; that is not the known transactionSearch flake. verify / macOS was still pending when I posted (the macOS queue has been slow).

Decision: COMMENT. The Windows test failure (finding 1) is a real CI failure that this PR introduces, and no later planned PR fixes it. With the expected strings built from ENV_LOCAL_RELATIVE_PATH, I'd approve; everything else above is non-blocking.

Comment thread src/core/dev/boxDevSecrets.test.ts Resolved
Comment thread src/core/dev/box.test.ts Resolved
Comment thread src/core/dev/boxDevSecrets.ts Resolved
- Build the expected warnings from ENV_LOCAL_RELATIVE_PATH, so the
  tests pass on Windows, where it is agentcore\.env.local.
- Skip an env:// ref with a blank name, as parseBoxEnvRoutes did.
- Pin that a box container gets the shell's key over .env.local's.
- Remove parseBoxEnvRoutes and readBoxEnvRoutes, which no code calls
  since writeBoxDevEnvLocal went.
- Check for the venv's Python, not only .venv: create --skip-install
  (#2857) leaves an empty .venv, which dev must not take for an
  installed one.
@mquang-amazon

Copy link
Copy Markdown
Contributor Author

Thanks @leo237. All in d60bb176 except item 2:

  1. Windows strings: fixed, see the threads.
  2. feat(box): Keep a box profile for each agent in .box/<agent>/{local,aws}, and let add runtime add a box runtime #2859 (boxProfilePath removed): not changed here. Whichever of feat(box): Keep a box profile for each agent in .box/<agent>/{local,aws}, and let add runtime add a box runtime #2859 and this PR merges second gives boxDevSecrets and missingBoxSecretWarning the agent name back, as in 290ee861. I'll do it here if feat(box): Keep a box profile for each agent in .box/<agent>/{local,aws}, and let add runtime add a box runtime #2859 goes first.
  3. The empty .venv from create --skip-install: fixed here. Dev now checks for .venv/bin/python, not only .venv, so it shows its "Run uv sync" hint. The test runs both cases: no .venv, and the empty one.
  4. Dead code: removed parseBoxEnvRoutes, readBoxEnvRoutes, the BoxEnvRoutes type and their tests. BoxEnvRoute and hasValue stay, because boxNetwork/network.ts, boxNetworkWriters.ts and boxProfileCredentials.ts use them.
  5. Blank variable name: fixed, see the thread.
  6. Container precedence: added "hands box in the container the shell's env:// key over .env.local's".

@leo237 leo237 left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Plan PR: MQ-6 (phase 11) of the Box integration squash plan. The plan doc still returns 401, so I checked against the branches directly.

What changed since b309d610. This is not a rebase. The base is still dd36f7b2, and b309d610 is unchanged. There is one new commit, d60bb176, with no merges. It touches only src/core/dev/{box,boxDevSecrets,container}* and src/core/project/boxProfileEgress*. Nothing from another plan PR is pulled in, and nothing is applied twice. The .venv/bin/python check is new work; box-integration-development still has the bare existsSync(venv). The removed parseBoxEnvRoutes/readBoxEnvRoutes aren't on dev either. None of the protected box-integration-only files are touched (boxProfileCredentials.ts, boxProfile.ts, the #2851 policies, the #2853 template/runtimeRunsInBox work, 68d2bbb4, c1bc4576), so all of those fixes survive.

Earlier items

  1. Windows expected strings: addressed. Both tests now interpolate ENV_LOCAL_RELATIVE_PATH.
  2. Conflict with #2859 (BOX_PROFILE_FILE/boxProfilePath): still open, as agreed. Whichever merges second gives boxDevSecrets/missingBoxSecretWarning the agent name, as in 290ee861. Removing the boxProfilePath import from boxProfileEgress.ts leaves one fewer place to change. Non-blocking.
  3. Empty .venv from c1bc4576: addressed. Dev now checks .venv/bin/python, which is the interpreter the profile's serve() runs by default (${appDir}/.venv/bin/python), so the check and the profile agree. The test.each covers both a missing .venv and the empty one that --skip-install leaves. The new comment and error message are accurate.
  4. Dead code: addressed. parseBoxEnvRoutes, readBoxEnvRoutes, BoxEnvRoutes and their tests are gone. BoxEnvRoute and hasValue stay, and they are still used by boxNetwork/network.ts, boxNetworkWriters.ts and boxProfileCredentials.ts.
  5. Blank env:// : addressed. It now uses variable.trim() === "", and the "leaves out" test has a blank route.
  6. Container precedence: addressed. The new test passes GITHUB_TOKEN in both input.env and processEnv, and checks that the env file gets the shell's value.

Review of d60bb176

  • Tests: every change has a test. The new tests are Windows-safe: paths go through join, the expected strings use ENV_LOCAL_RELATIVE_PATH, and the fake bin/python is written by the test itself.
  • Silent failures: none added. The stricter venv check turns a confusing box "missing Python" failure into dev's own uv sync hint.
  • Comments: accurate.
  • Types: no new types. One type (BoxEnvRoutes) was removed.
  • No new findings.

The other open items listed in the previous review still belong to later PRs and are unchanged.

Known flaky CI (the Windows transactionSearch EFAULT test, and the macOS 5 s screen-test timeouts or slow queue) is non-blocking.

CI: verify / Windows now passes, so the earlier blocking failure is fixed. verify / Linux, CodeQL/Analyze and CodeBuild e2e also pass; the GitHub e2e job is skipped. verify / macOS was still pending when I posted (slow macOS queue). d60bb176 adds nothing macOS-specific, and a macOS failure would be unrelated to this change unless it shows up in these tests.

Decision: APPROVE. The only blocking item (the Windows test strings) is fixed. Everything else open is non-blocking or planned.

@tejaskash tejaskash left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice simplification, not copying keys into .env.local is the right call. One fix I'd like before merge (the blank shell value, inline), plus a couple of decisions:

  1. After a key rotation, dev and deploy now disagree. Build's seed returns early when AGENTCORE_CREDENTIAL_<ROUTE> already has a value (boxProfileCredentials.ts:95-98), so with AGENTCORE_CREDENTIAL_GITHUB=ghp_old stored and GITHUB_TOKEN=ghp_new exported, dev uses the new key but deploy provisions the old one and the deployed agent gets a 401. Before this PR both were stale together. docs/box-local-testing.md:151-153 says build does this on every run, which it doesn't. Fine as a follow-up: either refresh the stored key when VAR differs, or print a message.
  2. Keys that earlier builds of this branch copied into .env.local (with the "read by box under agentcore dev" comment) stay there and get used silently when the shell doesn't set them. Only box-integration users have them, so one line in the description or the docs telling them to delete those lines is enough.
  3. Small: the comment at boxProfileCredentials.ts:14-17 still says dev stores each box variable in .env.local.

Comment thread src/core/dev/box.ts Resolved
Comment thread src/core/dev/box.ts Resolved
Comment thread src/core/dev/container.ts Resolved
Comment thread src/core/dev/boxDevSecrets.ts Resolved
Comment thread src/core/dev/boxDevSecrets.ts Resolved

@tejaskash tejaskash left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Marking my earlier review as changes requested. The one I would like fixed before merge is the blank shell value hiding the .env.local value, which makes dev say a key is missing while box actually starts with it (box.ts:97). The Windows case-insensitive lookup is worth fixing here too. The rest can follow up. Details are in my review just above.

The box templates reuse the asset folders of the agents without box,
whose .gitignore does not list .box-dist/ (agent-python-minimal has no
.gitignore at all), so after a build 'git add .' committed the box
binaries. stageBoxCodeZip now writes a .gitignore of '*' into
.box-dist/, which covers every template and existing projects. The
CodeZip packager reads no .gitignore, so the zip still carries the
folder. A policy file named .gitignore at the top of the profile's
folder is now refused, as the staged one would replace it.
… box

On a CodeZip Runtime the L3 runs opentelemetry-instrument start.py, and
start.py hands over to box run, so the agent in the box runs without
it and sends no traces, as in a box container. The CodeZip box
templates now write instrumentation.enableOtel false, as the container
one does, and build warns for any box runtime with OTEL on, not only a
container. Running the agent under opentelemetry-instrument in the box
waits on a Box Core fix to the signing of X-Amzn-Trace-Id (plan
Phase 15, SA-7).
serve() set AGENTCORE_RUNTIME_URL to http://localhost:9000/ for any
target, and the CodeZip Runtime profile reused it. serve_a2a gives that
variable precedence for the agent card URL, so a deployed boxed A2A
agent advertised localhost, and clients that read the card connected
to themselves. The override is now local only. On the Runtime the
box/agentcore pack reads AGENTCORE_RUNTIME_URL into runtime.url, with
serve_a2a's own fallback http://localhost:9000/ when the Runtime sets
none, and the profile passes that to the agent.
start.py fell back to tomli on Python 3.10, which has no tomllib, but
only agent-python-strands-box depends on tomli. The five other CodeZip
box templates reuse the folders of the agents without box, so on
PYTHON_3_10 start.py failed to import and the agent never started.
start.py needs only the profile's 'policies' line, which deploy writes
on one line with names of letters, digits, '.', '_', '-' and '/', so
on Python 3.10 it reads that line as a JSON list. No template needs
tomli now, so agent-python-strands-box drops it.
The error for a second runtime in a Box project named two box
templates; there are seven. It now lists BOX_TEMPLATE_NAMES, taken
from the shortcut table. The box profile tests forced boxTemplate onto
templates without box, so nothing checked the box entries of the
table; they now resolve the real box templates and check that the
table marks each one.
Every local CodeZip profile has [project] access = "write", and dev
started box in the project root, so the agent could read and write the
whole project: agentcore/.env.local with the model provider's real key,
which the keyed route keeps from it, and .git/hooks, agentcore/cdk and
agentcore.json, which run outside the box on the next commit or
deploy. The local CodeZip profile now names the agent's own folder as
${{ workspace }}, and its header names that folder. dev, build and
deploy start box there, with the profile at ../../.box/profile.toml,
so the project grant covers app/<runtime> and nothing else. A profile
written before still runs from the project root.
@mquang-amazon

Copy link
Copy Markdown
Contributor Author

1, 2, 3 I would pick the refresh option, can ship it here as well

Build stored a route's key in .env.local as AGENTCORE_CREDENTIAL_<ROUTE>
on the first build only. After a rotation, with GITHUB_TOKEN=ghp_new in
the shell and ghp_old stored, dev used the new key but deploy
provisioned the old one, and the deployed agent got a 401. Build now
replaces the stored key, and says so, when the route's variable holds a
different one, picked as dev picks it; deploy already updates an
existing provider. The local testing guide says so, and its
troubleshooting tells box-integration users to delete the variables
earlier builds copied into .env.local.
dev checked a box profile's env:// keys in { ...envLocal, ...shell },
so a blank shell value hid the .env.local one, but started box with
.env.local over the shell. With GITHUB_TOKEN= in the shell and a key in
.env.local, dev warned box would not start, and box started.
boxDevSecrets now takes the shell and .env.local apart and picks each
variable as build does, the shell's when set and not blank, and both
runners hand box that value.
boxDevSecrets read and parsed the box profile again, though both
runners had read it, so its no-profile branch never ran. It now takes
the profile text and is synchronous, and parses each secret with
BoxEgressSecretSchema instead of casting the raw TOML. It also:

- Matches a shell variable's name in any case on Windows, where a copy
  of process.env loses that, so an exported Github_Token still sets
  env://GITHUB_TOKEN.
- Says, naming the variable and no value, when the shell and .env.local
  set a profile key to different values, since the shell's wins where
  the rest of dev prefers .env.local.
- Looks the keys up next to stageBox in the container runner, so its
  warnings come before the image build.
# Conflicts:
#	src/core/dev/box.test.ts
#	src/core/dev/box.ts
#	src/core/dev/boxEnvLocal.test.ts
#	src/core/dev/boxEnvLocal.ts
#	src/core/project/boxNetworkSource.ts
#	src/core/project/boxProfileEgress.test.ts
#	src/core/project/boxProfileEgress.ts
#	src/core/project/manager.box.test.ts
#	src/core/project/manager.tsx
#	src/core/project/templates/boxProfile.test.ts
#	src/core/project/templates/boxProfile.ts
#	src/handlers/project/dev/index.ts
@mquang-amazon

Copy link
Copy Markdown
Contributor Author

also address comment here in this pr #2857

boxDevSecrets checked `variable in found` and read the environments by
key, so a profile's env://constructor or env://toString matched
Object.prototype: it was skipped with no value and no warning. It now
reads only each record's own keys.
@mquang-amazon

Copy link
Copy Markdown
Contributor Author

Thanks @tejaskash and @leo237. Everything from the latest reviews, with its commit:

  • .box-dist/ in git (five new templates): stageBoxCodeZip writes .box-dist/.gitignore with *, so every project ignores it. The CodeZip packager reads no .gitignore, so the zip still carries it. .gitignore is now a reserved name for policy files. fcafbb6
  • OTEL in a box: every box template writes instrumentation.enableOtel: false, and the build warning drops its Container condition. Running the agent under opentelemetry-instrument in the box waits on the Box Core X-Amzn-Trace-Id signing fix (plan phase 15 / SA-7). 380e748
  • A2A card URL: the localhost:9000 override is local only. On the Runtime, the box/agentcore pack reads the Runtime's own AGENTCORE_RUNTIME_URL, which the service always injects, as inputs.runtime.url. Checked on a deployed a2a-python-strands-box runtime (us-west-2): the card's url is the Runtime invoke URL. 0dce816
  • Python 3.10 / tomli: start.py no longer needs tomli. On 3.10 it reads only the profile's one-line policies list. Tested on 3.10.22 and 3.13.17. 66fe267's template dependency is dropped. a6c5767
  • Profile tests forcing boxTemplate: the helper now resolves the real box shortcut and checks the table marks it. e303e4b. The stale two-template error went away with feat(box): Keep a box profile for each agent in .box/<agent>/{local,aws}, and let add runtime add a box runtime #2859's merge.
  • [project] access = "write" exposing .env.local, .git, agentcore/cdk: dev, build and deploy start box in app/<agent>, with the profile at ../../.box/<agent>/local/profile.toml, so the grant covers only the agent's folder. Checked with box preview.6: read and write are .../app/agent only. 690e3c3, merged onto feat(box): Keep a box profile for each agent in .box/<agent>/{local,aws}, and let add runtime add a box runtime #2859's layout in c9dbaa1. Not covered by a test: that the agent can't read .env.local at run time. That needs a real box run, which CI doesn't have.
  • Key rotation: build replaces a stored AGENTCORE_CREDENTIAL_<ROUTE>, and says so, when the route's variable holds a different key. Deploy already updates an existing provider. The local testing guide's "every run" line is fixed, and its troubleshooting tells box-integration users to delete the variables earlier builds copied into .env.local. 1b5b151
  • Stale comment at boxProfileCredentials.ts:14-17: fixed. 1b5b151

This branch is merged with box-integration (c9dbaa1), including #2859. It is not rebased.

The OTEL warning case for a box CodeZip runtime ran a full build,
which downloads box from GitHub; CI has no box cache, and the download
failed on every OS. The cases now check boxOtelWarnings directly, and
one build case with a container runtime checks that build yields it.

The resolver and dev runner built the project root through join(),
which turns /work/demo into \work\demo on Windows. With no start folder
they now use the project root as given.
@mquang-amazon
mquang-amazon requested a review from leo237 November 20, 2026 04:03
@mquang-amazon
mquang-amazon dismissed tejaskash’s stale review November 20, 2026 04:10

All comments from this review are addressed and their threads resolved (summary: #2862 (comment)). CI is green at f9e63f1. Dismissed by the author to unblock; please re-review.

@leo237 leo237 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Plan PR: MQ-6 (phase 11) of the Box integration squash plan. The plan doc loaded this time, so I checked the commits against its MQ-6 list and against the branches.

What changed since d60bb176. This was not a rebase. There are two merges of box-integration (badae5ea, and c9dbaa11, which brings in #2859), plus 11 new commits. The merge-base is the current box-integration tip 1405932a, so the branch is up to date (no test:package problem).

  • Review fixes for this PR (all only on box-integration, none on dev): 3421a139, aefc0b24, 6e26edc4, f9e63f1d.
  • Fixes from the #2857 review (also only on box-integration; none of them is in the plan's MQ-6 list or on box-integration-development): fcafbb66 (.box-dist/.gitignore), 380e748f (OTEL off for every box template), 0dce816e (A2A card runtime.url), a6c57679 (start.py on 3.10 without tomli; dev's 66fe2677 is the tomli version), e303e4bb (box template names and tests), 690e3c37 (start box in app/<runtime>), and 1b5b151e (refresh a rotated stored key).

The only dev port is still 290ee861. Everything else has to be carried back to dev by the SYNC back-merge, and SA-5 (#2866) and DOCS-2 need to know about it (see the coordination notes).

Key check: the #2859 conflict resolution is correct.

  • Both runners take the profile from the runtime: boxLocalProfileFile/Path(input.runtime.name) in box.ts, and in container.ts the profileText that stageBox read for that runtime. The warning names .box/<runtime>/local/profile.toml. Nothing in this PR's code refers to BOX_PROFILE_FILE, boxProfilePath or a single .box/profile.toml. The dev/index.ts loop over writeBoxDevEnvLocal is gone.
  • The tests use distinct runtime names (agent, and Hello_World in the container tests). The expected paths contain the name, which shows the name is used rather than a fixed path. However, no test runs two boxed runtimes with different env:// routes (see finding 1).
  • Leftover single-profile references are all on the base, not in this diff: docs/box-local-testing.md:112,117 (DOCS-2 fixes these; dev already has the per-runtime paths) and the comment in agent-python-strands-box/Dockerfile.template:45 (stale on dev too; it's a nit for whoever touches that file next). boxProfileResolver.test.ts still uses .box/profile.toml as an arbitrary string, which is harmless.

Earlier comments

  • Our review on b309d610: items 1 and 3 to 6 were already addressed at d60bb176. Item 2 (#2859 naming) is addressed now, as above.
  • tejaskash, blank shell value hiding .env.local (box.ts): addressed in 3421a139. Each variable is picked per variable from BoxKeySources (the shell's value when set and not blank, else .env.local's), and the check and the spawn agree. There's a test.
  • tejaskash, silent precedence flip: addressed in aefc0b24. shadowedBoxSecretNote names the variable and table, never the value, and a test checks that no value appears.
  • tejaskash, Windows case-insensitive lookup, and warning before the image build: addressed in aefc0b24, with win32 tests for the function and the container env file. Build uses process.env itself, which is already case-insensitive on Windows, so dev and build agree.
  • tejaskash, variable in found and prototype names: addressed in 6e26edc4 (Object.hasOwn, plus own-key reads of both sources), with a test.
  • tejaskash, pure boxDevSecrets(profileText, ...) and BoxEgressSecretSchema.safeParse: addressed in aefc0b24.
  • tejaskash's review items 1 to 3 (key rotation, the stale .env.local copies, the comment at boxProfileCredentials.ts:14-17): addressed in 1b5b151e, with docs troubleshooting and tests.

Must-survive box-integration fixes. boxProfileCredentials.ts is touched, but the model-provider skip, the key-presence check (seed/hasValue), the Secrets Manager skip (credentialEnvironmentVariableNames(existing).length > 0) and ENV_LOCAL_RELATIVE_PATH all survive. No removed line touches writesBedrockRoute, tomlKey, the #2850/#2851/#2852 items, ${{ inputs.gateway.url }}, ${{ inputs.aws.region }}, runtimeRunsInBox, assertBoxRuntimesHaveBoxVersion, selectTemplate, addBoxRuntime, validateBoxRuntimes or assertNoOtherStartScript. The boxTemplate: true that was removed is the test helper's forced flag; the shortcut-table mapping is kept and is now tested for real. The empty .venv from c1bc4576 survives.

The one deliberate change is the #2853 tomli fallback. a6c57679 replaces it rather than dropping it. On 3.10, start.py now reads the one-line policies = [...] as JSON (the renderer writes it with JSON.stringify names, and the stricter path pattern keeps them escape-free). The tomli dependency is removed. The 3.10 behaviour is kept and now covers all six CodeZip box templates instead of one, so I don't count this as a lost fix. Say if you'd rather keep tomli as well.

Review of the new code

  • Tests: good. Every fix has a test: per-variable precedence, blank shell value, shadowed note with no value, the win32 lookup, prototype names, warnings before the image build, upsert plus rollback, rotation, the start-folder cwd and profile argument for new and old profiles, the resolver start folder, boxOtelWarnings, runtime.url, .box-dist/.gitignore, and the real box shortcuts. The new tests are Windows-safe: paths are built with join or are fake-streamer strings, no sh is spawned, and no spawn gets an empty env.
  • Silent failures: none blocking. See finding 2 for one fragile spot.
  • Comments: two are stale (findings 3 and 4).
  • New types: BoxDevSecrets.shadowed and BoxDevSecretVariable are readonly and small. stageBox now returns { folder, profileText }, and upsert returns { written, updated }; both fit. BoxProfileResolver.resolve gains an optional startFolder. Because it's optional, a caller that forgets it resolves from the project root without any error. Only two callers exist and both pass it, so this is fine for now (nit).

Findings (all non-blocking)

  1. No test with two boxed runtimes. The per-runtime path is right, and the distinct names in the tests show the name is used. A test with two boxed runtimes (for example a with env://A_TOKEN and b with env://B_TOKEN) run by the same runner would pin that each box run or env file gets only its own runtime's keys and warning. Cheap to add here.
  2. boxStartFolder depends on the profile's header comment (inline). A new local profile uses a bare ${{ workspace }} and depends on line 1 to start in app/<runtime>. If a user edits or removes that comment, dev and build silently fall back to the project root. Then ${{ workspace }}/.venv/bin/python doesn't exist (box fails with a confusing error, while dev's own .venv check still passes, because it checks codeLocation), and the project-wide grant this PR narrows comes back without notice. Consider deriving the folder from runtime.codeLocation (dev and build have it), or a dedicated key, or at least warning when a profile has no header but uses a bare ${{ workspace }}.
  3. Stale docstring in boxProfileCredentials.ts:55. It says "The key comes from the credential's reserved variable when it is already set". After 1b5b151e that is only true for the environment's reserved variable. A stored .env.local value is now replaced when the route's variable holds a different key. (This line is outside the diff, so it isn't an inline comment.)
  4. Stale comment in serve() (inline): "The box starts the agent in the project folder". For the local CodeZip profile, box now starts in the runtime's folder.
  5. upsert and duplicate keys (inline). Only the first KEY= line is replaced. If .env.local holds the reserved key twice, the later line still wins on read (node:util parseEnv keeps the last occurrence), so build says "updating" but deploy provisions the old key. An export KEY= line also loses its export. Rare; nit.
  6. PR description is stale. It still says .box/profile.toml, "boxDevSecrets(projectRoot, env) ... takes no agent name", that readBoxEnvRoutes was left in place, that the docs hunk is left for DOCS-2, and it lists one commit. Please update it before squashing, and list the seven #2857-review commits as box-integration-only so the SYNC back-merge carries them.
  7. start.py's 3.10 path has no unit test. This is the existing "no start.py test" item, which now covers new logic. The plan's MQ-7 (#2865, 8d25cd6d "Run the CodeZip box template on each Runtime Python") covers it end to end. Planned, so non-blocking.

Coordination (non-blocking)

  • #2863: this PR adds EnvLocalFile.upsert and switches the box-credential write in manager.tsx to it. #2863 adds insertIfNew(..., { keep }) to fill a blank reserved key in place, and changes seed. upsert already covers #2863's blank-key case (seed pushes the entry, and upsert replaces it in place), so whichever merges second should keep one mechanism. As agreed, the second one should also reword BoxKeySources. This PR has already reworded it to "where a user can keep a box variable under its own name, as agentcore dev reads it", and #2863's boxKeyIsSet doc (which mentions keep/insertIfNew) has to follow.
  • #2866 (SA-5): it derives the Runtime profile from each runtime's local profile, and needs to account for the new bare ${{ workspace }} together with the header-driven start folder.
  • DOCS-2: dev's guide says "Dev runs box run .box/<runtime>/local/profile.toml in the project folder". After 690e3c37, dev runs box run ../../.box/<runtime>/local/profile.toml in app/<runtime>. The two docs/box-local-testing.md hunks here (rotation, and deleting the old copies) are box-integration-only and need to survive DOCS-2's port.

The other open items from the earlier reviews are unchanged and belong to later PRs.

CI (at f9e63f1d): verify / Linux, verify / Windows, verify / macOS, Analyze/CodeQL and CodeBuild e2e all pass; the GitHub e2e job is skipped. The known flakes (the Windows transactionSearch EFAULT test and the macOS 5 s screen-test timeouts) didn't show up this run; they're non-blocking anyway. Codecov reports all modified lines covered.

Decision: APPROVE. The #2859 resolution is correct, every earlier comment is addressed, the must-survive fixes are intact, and CI is green. Findings 1 to 7 and the coordination notes are non-blocking; finding 7 is fixed by MQ-7 (planned).

Comment thread src/core/project/envLocal.ts Resolved
@mquang-amazon
mquang-amazon merged commit 7252504 into box-integration Nov 20, 2026
7 checks passed
@mquang-amazon
mquang-amazon deleted the box/mq-6 branch November 20, 2026 04:36

@vvargu vvargu left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Post-merge review. The main change is correct: agentcore dev gives each env:// key to box run through its environment and writes no copies. The inline comments are follow-up items.

Nit on the PR description. It does not agree with the merged code:

  • It says box-integration has one profile, .box/profile.toml, and that boxDevSecrets(projectRoot, env) takes no agent name. The code reads .box/<agent>/local/profile.toml and takes the profile text.
  • It says the docs change waits for DOCS-2, but this PR changes docs/box-local-testing.md.
  • It does not list the later commits, for example the start folder, the OTEL change, Python 3.10, and the credential replacement.

Please update the description so that it is a correct record of the merge.

Comment thread docs/box-local-testing.md Resolved
Comment thread src/core/project/envLocal.ts Resolved
mquang-amazon added a commit that referenced this pull request Nov 20, 2026
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.
@mquang-amazon
mquang-amazon restored the box/mq-6 branch November 20, 2026 05:01
SaiAbhishek98 pushed a commit to SaiAbhishek98/agentcore-cli that referenced this pull request Nov 20, 2026
…he runtime turn it off

When the derived Runtime profile has no cloudwatch_logs target, build
adds [telemetry.agentcore]: box sends its deny, permit, and trace
records to the log group of the runtime. No command said so, no
document said what it costs or how long the records stay, and the
user could not turn it off without a cloudwatch_logs target of their
own. The pre-review of
[aws#2866](aws#2866)
found this, and Leo asked the guide to say that the target needs
OTEL_EXPORTER_OTLP_LOGS_HEADERS.

With this change:

- agentcore create and agentcore add runtime give a notice for each box
  runtime: what box sends, the log group
  /aws/bedrock-agentcore/runtimes/<runtime ID>-DEFAULT and the stream
  otel-rt-logs, that the log group is the Runtime's and stays after
  the runtime is removed, that CloudWatch Logs charges for the records,
  and how to send none. add runtime gives it after agentcore.json is
  written, so a failed write gives no notice.
- The Runtime profile gets no default target when the envVars of the
  runtime set DISABLE_ADOT_OBSERVABILITY to "true". This is the switch
  that the CLI already documents to turn off observability. The switch
  is not instrumentation.enableOtel: each box template writes
  enableOtel = false (aws#2862), because the agent in a
  box does not run under opentelemetry-instrument, and that says
  nothing about the records of box.
- The guide says what the target sends, that box does not start when
  the Runtime does not set OTEL_EXPORTER_OTLP_LOGS_HEADERS, the
  retention and the cost, and the two ways to change it.

Tests: additions.test.ts "adds the default target only when the envVars
do not set DISABLE_ADOT_OBSERVABILITY to true" (3 values).
manager.test.ts "writes the box profile into the agent's
.box/<name>/local folder" checks the notice of create.
manager.box.test.ts "add runtime gives the new runtime a box, its Box
gateway, and its own box profile" checks that the notice comes after
the write of agentcore.json, and "a failed write of agentcore.json
gives no notice of the default log target".
SaiAbhishek98 pushed a commit to SaiAbhishek98/agentcore-cli that referenced this pull request Nov 20, 2026
…gent-v5

[aws#2862](aws#2862)
merged into box-integration, and aws#2866 had conflicts
with it. This is a merge, not a rebase, so the commits that reviewers
read stay as they are.

The conflicts, and what each one keeps:

- start.py: staged_policies of aws#2862, which reads
  `policies` as a one-line JSON list on Python 3.10 with no tomli, and
  box_python of this PR. The copy of the profile and the exec of box
  stay in main(), so a test can import the module.
- templates/boxProfile.ts: the local CodeZip profile names the code
  folder as ${{ workspace }}, and its header names the folder that
  agentcore dev starts box in (690e3c3). runtimeAgentTemplate gives
  its Runtime [agent] in the same paths, and gives an A2A agent card
  AGENTCORE_RUNTIME_URL = "${{ inputs.runtime.url }}" (0dce816).
  @box/agentcore declares the runtime.url input beside the log group
  and log stream inputs.
- boxProfileEgress.ts and boxEnvLocal.test.ts: aws#2862
  removed the env-local writer, so its code and its test go.
- The tests: each side keeps its tests. The old renderer tests of
  boxProfile.test.ts stay removed.

To follow 690e3c3 in the derivation, the paths rule reads the folder
that box starts in (boxStartFolder) from the local profile. A profile
that create or add runtime writes now names the code folder as
${{ workspace }}, and one that was written before names it as
${{ workspace }}/<codeLocation>. Thus a new CodeZip box project builds
with no RUNTIME_PATH_NOT_FOUND, and a profile written before still
builds. Varun asked for this in the review of
[aws#2866](aws#2866).

The equivalence fixture has the output of the renderer at 7252504 for
the 72 build inputs and the 66 template inputs. The only change from
f5503f0 is AGENTCORE_RUNTIME_URL of an A2A runtime.

Tests: bun test gives 5772 pass, 7 skip, 0 fail. derive.test.ts "names
the code folder ${{ workspace }} when box starts in it, as for a
profile create writes now". The build tests of manager.boxNetwork.test.ts
build a created CodeZip project on the merged tree.
SaiAbhishek98 pushed a commit to SaiAbhishek98/agentcore-cli that referenced this pull request Nov 20, 2026
…policies on one line

Varun asked in the review of
[aws#2866](aws#2866)
to keep staged_policies of aws#2862 with box_python, and
to make sure that the derived Runtime profile writes `policies` on one
line. On Python 3.10 there is no tomllib, and staged_policies reads that
line as a JSON list.

- boxStartPy.test.ts runs main() of start.py with its folders in a
  temporary folder and os.execve replaced. It checks the box that
  main() runs and its arguments, that BOX_PYTHON is what box_python
  gives, and that the profile and each policy file are copied. It runs
  one time with tomllib and one time with tomllib set to None, as on
  Python 3.10. This test replaces the test that read the text of
  start.py.
- derive.test.ts checks that serializeRuntimeProfile writes 30 policy
  files on one line, and that the line reads as a JSON list.

Tests: the two tests pass with python3 3.9.6 on the PATH. A manual run
of main() gave the same copies with Python 3.10.21 (no tomllib), 3.12.14
(tomllib), and 3.9.6 (no tomllib).
vvargu pushed a commit that referenced this pull request Nov 20, 2026
* 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.

* 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.

* 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.

* 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.

* 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.

* 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.

* 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/<version>-<target>/ 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.

* 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'.

* 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.

* 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.

* 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.

* 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/<x>
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.

* 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.

* 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.

* 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.

* 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.

* 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.
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
…he runtime turn it off

When the derived Runtime profile has no cloudwatch_logs target, build
adds [telemetry.agentcore]: box sends its deny, permit, and trace
records to the log group of the runtime. No command said so, no
document said what it costs or how long the records stay, and the
user could not turn it off without a cloudwatch_logs target of their
own. The pre-review of
[#2866](#2866)
found this, and Leo asked the guide to say that the target needs
OTEL_EXPORTER_OTLP_LOGS_HEADERS.

With this change:

- agentcore create and agentcore add runtime give a notice for each box
  runtime: what box sends, the log group
  /aws/bedrock-agentcore/runtimes/<runtime ID>-DEFAULT and the stream
  otel-rt-logs, that the log group is the Runtime's and stays after
  the runtime is removed, that CloudWatch Logs charges for the records,
  and how to send none. add runtime gives it after agentcore.json is
  written, so a failed write gives no notice.
- The Runtime profile gets no default target when the envVars of the
  runtime set DISABLE_ADOT_OBSERVABILITY to "true". This is the switch
  that the CLI already documents to turn off observability. The switch
  is not instrumentation.enableOtel: each box template writes
  enableOtel = false (#2862), because the agent in a
  box does not run under opentelemetry-instrument, and that says
  nothing about the records of box.
- The guide says what the target sends, that box does not start when
  the Runtime does not set OTEL_EXPORTER_OTLP_LOGS_HEADERS, the
  retention and the cost, and the two ways to change it.

Tests: additions.test.ts "adds the default target only when the envVars
do not set DISABLE_ADOT_OBSERVABILITY to true" (3 values).
manager.test.ts "writes the box profile into the agent's
.box/<name>/local folder" checks the notice of create.
manager.box.test.ts "add runtime gives the new runtime a box, its Box
gateway, and its own box profile" checks that the notice comes after
the write of agentcore.json, and "a failed write of agentcore.json
gives no notice of the default log target".

Dev port: dev does not add a box runtime with agentcore add runtime,
and it finds a box runtime by its start.py entry point or its
Dockerfile (runsAgentInBox), not by box.version. Thus the notice uses
runsAgentInBox in a Box project, and the add runtime tests of
box-integration that check the notice are not in this port. The create
test of manager.test.ts checks the notice.

(cherry picked from commit 981588a)
SaiAbhishek98 pushed a commit that referenced this pull request Nov 20, 2026
…policies on one line

Varun asked in the review of
[#2866](#2866)
to keep staged_policies of #2862 with box_python, and
to make sure that the derived Runtime profile writes `policies` on one
line. On Python 3.10 there is no tomllib, and staged_policies reads that
line as a JSON list.

- boxStartPy.test.ts runs main() of start.py with its folders in a
  temporary folder and os.execve replaced. It checks the box that
  main() runs and its arguments, that BOX_PYTHON is what box_python
  gives, and that the profile and each policy file are copied. It runs
  one time with tomllib and one time with tomllib set to None, as on
  Python 3.10. This test replaces the test that read the text of
  start.py.
- derive.test.ts checks that serializeRuntimeProfile writes 30 policy
  files on one line, and that the line reads as a JSON list.

Tests: the two tests pass with python3 3.9.6 on the PATH. A manual run
of main() gave the same copies with Python 3.10.21 (no tomllib), 3.12.14
(tomllib), and 3.9.6 (no tomllib).

(cherry picked from commit 77d250e)

@tejaskash tejaskash left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, all eight of my points are fixed in the merged code. Two small message gaps for a follow-up:

const key = credentialEnvVarName(credential);
if (hasValue(sources.env[key]) || hasValue(sources.envLocal[key])) return true;
// Set in the environment itself, it is what deploy provisions; nothing to store.
if (hasValue(sources.env[key])) return true;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dev and deploy can still disagree with no message when the user exports the reserved variable themselves. With GITHUB_TOKEN=ghp_new and AGENTCORE_CREDENTIAL_GITHUB=ghp_old both in the shell, dev uses the new key and deploy provisions the old one. One message here naming both variables when they differ would cover it.

const stored = sources.envLocal[key];
if (!hasValue(value)) return hasValue(stored);
if (value === stored) return true;
if (hasValue(stored)) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: a blank stored key gets filled in with no message, because the "updating" message needs a non-blank stored value and the manager only prints written keys. Having seed add the message whenever the stored value differs, blank or not, would be the simplest fix.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants