Skip to content

fix(box): Address the open review of the merged Box PRs - #2886

Open
mquang-amazon wants to merge 9 commits into
box-integrationfrom
box/address-tejas-review
Open

mquang-amazon wants to merge 9 commits into
box-integrationfrom
box/address-tejas-review

Conversation

@mquang-amazon

@mquang-amazon mquang-amazon commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Description

Follow-ups to the review of six merged box-integration PRs (#2850, #2852, #2857, #2862, #2865, #2867), from the open feedback on merged PRs. Each commit addresses one PR, so it can be reviewed on its own.

#2850: Bedrock through the Box gateway (24d7002a, ba28e29e)

  • agentcore build --region ignored the flag. The handler passed no region, and boxBuildRegion read only the environment, so the Box gateway targets and the Runtime profiles were built for AWS_REGION. build now takes the --region value. resolveRegion(flag, env) takes an environment, so boxBuildRegion goes, and build, add runtime, and --region resolve the region the same way.
  • The box download notice waited until staging finished. eventsWhile yields it when the download starts.
  • BOX_MINIMUM_VERSION goes. The box features and the profiles the CLI writes change together, so only the pinned box is supported. The install hints name only the pinned release. The README and the testing guide say that the CLI does not check the local box version yet, which is a possible later feature.
  • The TUI build screen passes the --region that withRegion resolved, as the command does.

Not changed here:

  • The gateway role's Bedrock grant: fix(build): Keep the Bedrock grant of the Box gateway in its region and account #2883 scopes it to the build region and account, and this PR's version (6072b2c1) is reverted in 9b179c8f so the two do not conflict.

  • Region-specific targets written into agentcore.json on every build: a larger design change, punted.

  • The 0644 dev credentials file: the folder is 0700 on the host, and inside the container the only users are the image's user (uid 1000) and root, so a 0600 file owned by uid 1000 lets in the same processes.

  • The box field in the L3 schema: needs an @aws/agentcore-cdk release.

#2852: regionFromConfigFile test (e485dcbd)

The tests pass AWS_CONFIG_FILE, AWS_PROFILE, HOME, and USERPROFILE through env, with static imports. They check that process.env is not read and that HOME comes before USERPROFILE, and they cover the order resolveRegion takes.

#2857: a box template for each Python agent (08fb9432)

  • The five non-box gitignore.template files are back to their v1.x bytes (no trailing newline).
  • agent-python-strands-box keeps only the two files that differ, its Dockerfile.template and gitignore.template. The resolver lays them over agent-python-strands (FsTreeNode.replaceChildren).
  • Each box shortcut is a spread of its twin. The resolved table is identical, key order included.
  • The empty .venv is part of boxCodeZipFiles, with start.py, which create and add runtime both write, instead of a --skip-install branch in create and a copy in add runtime.
  • The LangChain README says that traces are not collected when the agent runs in a box.
  • renderBoxProfile takes its region: the unused us-west-2 fallback goes, and its JSDoc says where box starts for a CodeZip agent.
  • Two tests use test.each.

#2862: dev hands box the profile's env:// keys (0a84859c)

  • When the environment sets a credential's reserved variable (AGENTCORE_CREDENTIAL_<NAME>) and the route's variable holds a different key, build says so: dev uses the route's variable, and deploy provisions the reserved one.
  • Build filled a blank stored key in .env.local with no message. It says so now.

#2865: e2e (89b4acff)

  • A new box-egress test on AgentCore Runtime: the egress agent, deployed in a box, reaches the profile's host through the Box gateway, and box refuses any other. It shares its agent and its checks with the dev test, and needs AGENTCORE_E2E_BOX_CDK.
  • Only the projects that deploy install the AGENTCORE_E2E_BOX_CDK build.
  • The README no longer says that the per-Python cases wait for fix(box): Ship only the pinned box, and drop the old box/<name> pack-name stop #2867.

#2867: ship only the pinned box (9e09dcff)

  • A pin bump stopped every existing Box project. Build refused any box.version but the pin, and nothing rewrote it. Build and deploy now set each box runtime's box.version to the pinned box and say so (boxVersionWriter), and the late stop in staging goes.
  • boxReleaseFor, the per-version build map, and the release getters of the staging functions and the container dev runner go: each stages BOX_RELEASE. Tests no longer stage 1.0.0 and 2.0.0 through fakes, and a build test covers the update.
  • The testing guide is rewrapped to 100 columns, which is most of its diff, and says how to publish an unreleased box. The pinned-release test title matches its assertions.

Related Issue

Closes #

Documentation PR

Not applicable: README.md, docs/box-local-testing.md, and e2eTest/README.md are updated in this PR.

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation update
  • Other (please describe): review follow-ups and test cleanup

Testing

  • I ran bun test (5858 pass, 7 skip, 0 fail, with no box on PATH)
  • I ran the relevant end-to-end tests with bun run test:e2e, or explained why they are not applicable
    (CI does not run them for you): not run. The new deployed box-egress test, the 4 per-Python cases, the 7 dev cases, and the dev egress test need AWS credentials, box on PATH, and AGENTCORE_E2E_BOX_CDK. vitest list collects both egress tests.
  • I ran bun run typecheck
  • I ran bun run lint:check
  • I ran bun run format:check
  • I ran bun run audit
  • I ran bun run secrets:check
  • I ran bun run build
  • If I modified src/assets/, I updated affected snapshots with bun test <test-file> --update-snapshots and committed them: no snapshot covers the changed templates
  • If I re-recorded fixtures or golden files, every change beyond account identifiers is explained by this PR: none re-recorded
  • This PR does not change command.md (the release workflow regenerates it)

These new tests fail when their fix is reverted (checked by reverting it): --region in the handler and in the manager, box.version in the writer, the blank-key message, and the region test's home order and AWS_PROFILE.

Not tested: a real deploy. The deployed egress test, and the box.version update need an AWS run.

Checklist

  • I have read the CONTRIBUTING document
  • I have added any necessary tests that prove my fix is effective or my feature works
  • I have updated the documentation accordingly
  • I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
  • My changes generate no new warnings
  • Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

…p BOX_MINIMUM_VERSION

Addresses the review of #2850:
- agentcore build --region ignored the flag: the handler passed no region and
  boxBuildRegion read only the environment. build takes the region now, and
  resolveRegion takes an environment, so boxBuildRegion goes.
- The box download notice waited until staging ended; eventsWhile yields it
  when the download starts.
- BOX_MINIMUM_VERSION goes: the box features and the profiles the CLI writes
  change together, so only the pinned box is supported.
…ith static imports

Addresses the review of #2852: the tests now give AWS_CONFIG_FILE,
AWS_PROFILE, and both home variables through env, check that process.env
is not read and that HOME comes before USERPROFILE, and cover the order
resolveRegion takes.
- Revert the trailing newline five non-box gitignore.template files gained,
  so their output matches v1.x.
- agent-python-strands-box keeps only the two files that differ (its
  Dockerfile and .gitignore); the resolver lays them over agent-python-strands.
- Each box shortcut is a spread of its twin, so a change to one reaches both.
- The empty .venv is part of the box CodeZip files (boxCodeZipFiles), which
  create and add runtime both write, not a --skip-install branch of create.
- The LangChain README says traces are not collected when the agent runs in
  a box.
- renderBoxProfile takes its region; the unused us-west-2 fallback goes, and
  its JSDoc says where box starts for a CodeZip agent.
- Two tests use test.each.
…s, and when build fills a blank one

Addresses the review of #2862:
- With the credential's reserved variable (AGENTCORE_CREDENTIAL_<NAME>) set
  in the environment, deploy provisions it while dev hands box the route's
  variable. Build now says so when the two hold different keys.
- Build filled a blank stored key in .env.local with no message; it says so
  now, as it does for a different key.
- Add the egress test on AgentCore Runtime: the egress agent deployed in a
  box reaches the profile's host through the Box gateway, and box refuses
  any other. It shares its agent and checks with the dev test.
- Install the AGENTCORE_E2E_BOX_CDK build only in projects that deploy; the
  dev and dev-egress cases have no use for it.
- Drop the README sentence that the per-Python cases wait for #2867, which
  has merged.
…version plumbing

Addresses the review of #2867:
- A pin bump stopped every existing Box project: build refused any
  box.version but the pin, and nothing rewrote the field. Build and deploy
  now set each box runtime's box.version to the pinned box (boxVersionWriter)
  and say so, since the box features and the profiles the CLI writes change
  together. The late stop in staging goes with it.
- boxReleaseFor, the per-version build Map, and the release getters of the
  staging functions and the container dev runner go: each stages BOX_RELEASE.
  Tests no longer stage 1.0.0 and 2.0.0 through fakes, and a build test
  covers the update.
- The testing guide is rewrapped to 100 columns and says how to publish an
  unreleased box; the pinned-release test title matches its assertions.
Addresses the review of #2850: the role could invoke any Bedrock model in any
region. It may now invoke an inference profile of its own account in the
region build builds for, a foundation model there, and a foundation model in
another region only through an inference profile in that region, which is
how a cross-region (us., global.) profile reaches it.
@mquang-amazon
mquang-amazon requested a review from a team November 20, 2026 23:35
@codecov-commenter

codecov-commenter commented Nov 20, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.80%. Comparing base (e2ac9d7) to head (9b179c8).
⚠️ Report is 6 commits behind head on box-integration.

Additional details and impacted files
@@               Coverage Diff                @@
##           box-integration    #2886   +/-   ##
================================================
  Coverage            96.79%   96.80%           
================================================
  Files                  766      766           
  Lines                66803    66820   +17     
================================================
+ Hits                 64665    64682   +17     
  Misses                2138     2138           

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

Review of #2886 at 6072b2c1 (first review)

Decision: APPROVE. I found nothing blocking. The branch is up to date with box-integration, and it reverts none of the earlier fixes I checked. Linux, Windows, CodeQL and Analyze pass. verify / macOS was still pending when I posted. One thing needs coordination before merge: the Bedrock grant in 6072b2c1 duplicates #2883, and the two conflict (see below).

I reviewed the PR one commit at a time. I did not run anything (no build, no tests).

#2850: 24d7002a (build --region, download notice, BOX_MINIMUM_VERSION)

  • Region order. resolveRegion(flag, env) takes --region, then AWS_REGION, then AWS_DEFAULT_REGION, then the config file, then DEFAULT_REGION. This is the same order boxBuildRegion used, now with the flag first. The build handler passes ctx.value(RegionKey), which withRegion has already resolved. applyBoxNetwork takes that region, so the gateway targets, the Runtime profiles, the Memory policy and the Bedrock policy all use the same region. Create's fallback goes through resolveRegion too. region.test.ts covers the full order and the fallback, and build/index.test.ts covers the handler.
  • Nit, not in the diff: the TUI build screen (src/handlers/project/build/screen.tsx:42) still calls projectManager.build(project) with no region. With no region, build resolves it from the environment, so a global --region is ignored on that path. Passing ctx.value(RegionKey) would make the two entry points match.
  • eventsWhile. I traced it. Each event is yielded as soon as it is emitted. A failure is thrown after the events emitted before it. running.then(finish, finish) stops an unhandled rejection when the consumer returns early.
  • BOX_MINIMUM_VERSION. I grep'd the PR head: no reference to BOX_MINIMUM_VERSION, BOX_MINIMUM_RELEASE_PAGE or BOX_OTHER_MACHINE_HINT remains, and no code compares versions. BOX_OTHER_MACHINE_HINT was the hint for machines the pinned release had no build for. Dropping it looks fine, because the testing guide now lists an aarch64-apple-darwin build in the pinned preview.10 release. I could not open that release page from here to confirm it. assertBoxRuntimesHaveBoxVersion is unchanged.

#2850: 6072b2c1 (Bedrock grant scoped to the build region). This overlaps #2883

The IAM looks correct. It follows the same pattern as #2883, which I approved:

  • Statement 1: inference profiles in region, with aws:ResourceAccount == ${aws:PrincipalAccount}. System-defined us. and global. profiles carry the caller's account in their ARN (inference-profiles-prereq), so they match.
  • Statement 2: foundation models in region.
  • Statement 3: arn:aws:bedrock:*::foundation-model/*, only when bedrock:InferenceProfileArn matches the in-region profile, using StringLike. The * region also covers the region-less arn:aws:bedrock:::foundation-model/* that global. profiles are checked against (global cross-Region inference). So cross-region inference keeps working.

Compared with #2883 (555f19c6): both PRs have the same three statements and the same region === undefined guard in defaultTargetsWriter. #2883 is a strict superset:

  • It takes the partition from partition(region).name. This PR hard-codes arn:aws, so the grant would match nothing in aws-cn or aws-us-gov.
  • It pins the account inside the bedrock:InferenceProfileArn condition (...:${region}:${aws:PrincipalAccount}:inference-profile/*). This PR uses * there. Statement 1 already limits the profile to the caller's account, so the gap is defense in depth only.
  • It has more tests: boxNetworkWriters.test.ts and network.test.ts.

A trial merge shows the two PRs conflict in boxMemory.ts and boxMemory.test.ts. I recommend landing #2883's version and dropping 6072b2c1 from this PR (or rebasing it away once #2883 merges). Keep this PR's manager.boxNetwork.test.ts case, which checks the policy file for the build region, if #2883 does not already cover it.

#2852: e485dcbd (region tests)

The tests use static imports and pass every input through env. The test that touches process.env restores AWS_CONFIG_FILE, AWS_PROFILE and HOME afterwards. The HOME-before-USERPROFILE and AWS_PROFILE cases are there. I saw no unsafe test patterns: no hard-coded host paths, POSIX modes or spawned processes.

#2857: 08fb9432 (template dedupe)

  • The resolved box template has the same files as before. I compared each file the base agent-python-strands-box had with agent-python-strands at the PR head. README.md, dockerignore.template, main.py, memory/__init__.py, memory/session.py, model/__init__.py, model/load.py, parse.py and pyproject.toml are all byte-identical. Only Dockerfile.template and gitignore.template are box-specific, and they stay. replaceChildren replaces only top-level children, which is all these two files need. Both trees use the same options, so the renamed Dockerfile and .gitignore match by name, and the CodeZip filter drops the Dockerfile from both. The new runtime.test.ts case checks that the two trees are equal apart from those two files.
  • The shortcut spreads give the same values for all seven box twins. I checked each one by hand.
  • gitignore bytes: the five non-box files are back to the v1.x bytes, with no trailing newline. That is harmless, because they are rendered as they are.
  • .venv: boxCodeZipFiles writes start.py and an empty .venv. add runtime writes them with skipExisting. .venv is recorded in scaffoldedPaths by hand, because write reports only files. Create now writes the empty .venv with or without --skip-install, and uv sync fills it. The test.each covers the CodeZip, container and plain cases.
  • The LangChain README {{#if box}} branch matches enableOtel: false for box runtimes, and a test covers it. renderBoxProfile now requires a region, and both callers pass one.

#2862: 0a84859c (credential messages)

The logic is right. When the shell exports the reserved variable, build stores nothing, and it names the mismatch only when the route's key is set and different. A blank or whitespace-only stored key gets the new "setting ... which is blank there" message. The three new tests cover a mismatch, a match, and a blank key. The wording is clear.

#2865: 89b4acff (e2e)

  • The new deployed box-egress test is gated on BOX_DEPLOYS, which needs both AGENTCORE_E2E_BOX_CDK and box on PATH. Its finally block runs remove all and then deploy, and a cleanup error does not hide the primary failure.
  • It reaches only checkip.amazonaws.com and example.com, which is expected for this opt-in test.
  • deploys: false keeps the opt-in CDK install out of the dev cases.
  • As the PR says, nobody has run it against AWS yet. Please record one run (the 403 from the denied host on Runtime is the part I could not check).

#2867: 9e09dcff (only the pinned box)

  • Staging now always uses BOX_RELEASE, with pinned checksums, so only the pinned box can ship. This keeps the goal of vvargu's request on #2867.
  • Design change: vvargu asked on #2867 for build and deploy to stop on a box.version other than the pin. This PR instead rewrites box.version in agentcore.json and prints a message. I think that is reasonable after a pin bump, but it reverses a reviewer request that was merged, so please confirm vvargu agrees.
  • boxVersionWriter updates only runtimes that appear in networks. That is fine, because staging uses the pin anyway. A build test covers the update.
  • Nit (inline): the BOX_NETWORK_WRITERS JSDoc is now orphaned above boxVersionWriter's doc block.

Earlier fixes that must survive

Present at the PR head: assertBoxRuntimesHaveBoxVersion, runtimeRunsInBox, ENV_LOCAL_RELATIVE_PATH, EnvLocalFile.upsert, writesBedrockRoute / tomlKey, Dockerfile curl --retry 3 and tar --no-same-owner, the xray grants, ${{ inputs.gateway.url }} and ${{ inputs.aws.region }}, boxStartFolder, .venv/bin/python, publishInstall, --containment, the enableApplicationLogs notice, and the pin 0.1.11-preview.10. There is no SHA256SUMS.txt lookup in code and no refuseOldShippedNames. The only removal is BOX_OTHER_MACHINE_HINT, which is intentional (see above).

Hygiene

  • The diff and commit messages add no account IDs and no internal URLs. The docs rewrap carries over a sentence that names internal credential tooling. That sentence is already on the base branch, so it is not new here, but consider making it generic in a follow-up.
  • On the "Not changed here" list: the 0644 dev credentials reasoning holds. The host folder is 0700, and inside the container only uid 1000 and root exist, so 0600 would let in the same processes.

Conflicts with other open PRs (trial git merge-tree, non-blocking)

  • #2883: conflicts in boxMemory.ts and boxMemory.test.ts. This is the duplicate Bedrock grant above.
  • #2877: conflicts in docs/box-local-testing.md, backends/boxCodeZip.ts and manager.boxNetwork.test.ts.
  • #2885: conflicts in docs/box-local-testing.md and backends/cdk.ts.
  • #2878, #2879 and #2882 merge cleanly.

Most of the doc conflicts come from rewrapping docs/box-local-testing.md to 100 columns.

This is an off-plan follow-up, and it is not on box-integration-development yet, so it will need a back-merge (non-blocking).

Comment thread src/core/project/boxMemory.ts Outdated
region: string,
): Record<string, unknown> | undefined {
if (boxedRuntimesCallingBedrock(spec).length === 0) return undefined;
const profiles = `arn:aws:bedrock:${region}:*:inference-profile/*`;

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

#2883 (555f19c6) changes this same function, and the two PRs conflict here. #2883 is a superset: it takes the partition from partition(region).name instead of arn:aws, and it pins ${aws:PrincipalAccount} in the bedrock:InferenceProfileArn condition on statement 3 (line 151). The IAM here is otherwise equivalent and correct. I suggest landing #2883's version and dropping this commit.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Agreed. 9b179c8 reverts 6072b2c, so the Bedrock grant lands with #2883 and the two no longer conflict. I will add the build-level check of the policy file once #2883 is in, if it does not already cover it.

Comment thread src/core/project/boxNetworkWriters.ts Outdated
@@ -482,7 +487,34 @@ function withoutUnsentRoutes(
}

/** The writers that build and deploy run before synth, in order. */

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Nit: this JSDoc belonged to BOX_NETWORK_WRITERS. With the new block inserted below it, it is orphaned, and BOX_NETWORK_WRITERS has no doc. Moving it down to sit above export const BOX_NETWORK_WRITERS fixes that.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Done in ba28e29: the JSDoc is back above BOX_NETWORK_WRITERS.

networks.flatMap(({ runtime: name }) => {
const runtime = copy.runtimes.find((candidate) => candidate.name === name);
const version = runtime?.box?.version;
if (!runtime?.box || version === BOX_RELEASE.version) return [];

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

On #2867, vvargu asked for build and deploy to stop on a non-pinned box.version. This rewrites the field instead, and only the pinned box is staged, so the goal of that request still holds. Since this reverses a merged reviewer request, it is worth confirming they are fine with rewriting. Non-blocking.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Agreed, it reverses the letter of that request while keeping its goal: only the pinned box ships, and the field now says which one, instead of a pin bump stopping every existing Box project. I will confirm with vvargu before merge.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Tejas asked for this in his review of #2867: "A pin bump breaks every existing Box project. boxRelease.ts:299-306 refuses any box.version other than the pin, nothing rewrites the field, and the bump in #2871 is already merged… Since only one value is legal, always stage BOX_RELEASE and let build update the field." Only the pinned box still ships, so the goal of the original request holds.

…' JSDoc on BOX_NETWORK_WRITERS

Addresses the review of #2886: the build screen called build with no region,
so a global --region was ignored there; it passes the region withRegion
resolved, as the command does.
…uild region"

This reverts commit 6072b2c. #2883 makes the same change and more (the
region's partition, and the account in the inference-profile condition), and
the two conflict, so the grant lands with #2883.

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

Re-reviewed 6072b2c..9b179c8. Approving again.

  • ba28e29: the build screen now passes ctx.value(RegionKey) to build, the same way the build command does, so --region applies in the TUI too. The JSDoc sits above BOX_NETWORK_WRITERS again.
  • 9b179c8: after the revert, boxMemory.ts and boxMemory.test.ts match the merge-base, and the box-bedrock-policy.json test is gone. A trial merge with box-integration (which has #2883) is clean. The branch is 6 commits behind base, with no conflicts.
  • CI is green on 9b179c8.

Still open, none blocking:

  • box.version rewrite: you said you'll confirm with the requester before merging.
  • The deployed box-egress e2e hasn't been run against AWS yet.
  • Back-merge to box-integration-development.
  • FYI, trial merges still conflict with open PRs: #2877 (docs/box-local-testing.md, backends/boxCodeZip.ts, manager.boxNetwork.test.ts), #2885 (docs/box-local-testing.md, backends/cdk.ts) and #2887 (docs/box-local-testing.md, manager.boxNetwork.test.ts). Whichever PR lands second will need a rebase.

error={null}
action={async function* () {
yield* core.projectManager.build(project);
yield* core.projectManager.build(project, { region });

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Nit, not blocking: the CLI path has builds for the region --region names in index.test.ts, but nothing covers this screen passing the region. A small screen test asserting that build gets { region } from RegionKey would keep the two paths from drifting apart.

This branch has not been deployed

No deployments
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.

3 participants