Skip to content

feat(box): Send a boxed agent's Memory calls to Memory directly - #2889

Open
vvargu wants to merge 3 commits into
aws:box-integrationfrom
vvargu:box/memory-direct-access
Open

vvargu wants to merge 3 commits into
aws:box-integrationfrom
vvargu:box/memory-direct-access

Conversation

@vvargu

@vvargu vvargu commented Nov 21, 2026

Copy link
Copy Markdown

Description

A boxed agent's AgentCore Memory calls now go to Memory directly, and not through the Box gateway.

Before this change, build added an agentcore passthrough target to each Box gateway, and the gateway signed the Memory calls with its own role. Memory then could not hold each call to the session of the runtime by its context keys. One session could read or write the memory of another session.

What changes:

  • Build adds no agentcore target to the Box gateway, and writes no agentcore/box-memory-policy.json for the gateway role.
  • The Runtime profile gets a direct [egress.agentcore] route to bedrock-agentcore.<build region>.<dns suffix>. Box signs it with a bare aws:// (the execution role), and the route has no gateway backend. The execution role already has the Memory data-plane grants, because the runtime binds its Memory.
  • The route is added only for a runtime with its default Memory. A route or HTTP MCP server of the profile that already has the AgentCore host keeps it, so the box has one route to that host.
  • A user route named agentcore for another host stops build with RUNTIME_ROUTE_NAME_TAKEN.
  • boxGatewayAgentCoreHost is now agentCoreDataPlaneHost. getBoxGatewayAgentCoreTargetSpec, BOX_GATEWAY_AGENTCORE_TARGET_NAME, addBoxMemoryTarget, and boxMemoryPolicy are removed.

Runtime profile route, before and after:

# before
[egress.agentcore]
destinations = ["bedrock-agentcore.us-west-2.amazonaws.com"]
[[egress.agentcore.backends]]
url = "${{ inputs.gateway.url }}/agentcore"
auth = { ref = "aws://", aws = { service = "bedrock-agentcore", region = "${{ inputs.aws.region }}" } }

# after
[egress.agentcore]
destinations = ["bedrock-agentcore.us-west-2.amazonaws.com"]
secret.ref = "aws://"

When AgentCore Gateway can get the session from the context keys, Memory calls can go through the gateway again.

A runtime in VPC network mode needs a bedrock-agentcore VPC endpoint (or another egress path) to reach Memory directly.

Related Issue

Closes #

Documentation PR

Not applicable. The rule docs in runtimeProfile/ are updated in this PR.

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation update
  • Other (please describe):

Testing

How have you tested the change?

  • I ran bun test: 5829 pass, 1 fail. The one failure is the box on PATH. It runs the local box on PATH, which is an older build that rejects @box/base. This change does not cause it.
  • 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. A deployed check of Memory from a boxed agent is still open.
  • 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: not applicable.
  • If I re-recorded fixtures or golden files, every change beyond account identifiers is explained
    by this PR: not applicable. The old-renderer fixture stays as it is. The tests change its Memory route to the direct form.

The Box gateway signed the agent's Memory calls with its own role. Memory then
could not hold each call to the session of the runtime by its context keys, so
one session could read or write the memory of another session.

Build now adds no `agentcore` target to the Box gateway, and writes no
`agentcore/box-memory-policy.json` for the gateway role. The Runtime profile
gets a direct `[egress.agentcore]` route to the AgentCore host of the build
region. Box signs that route with a bare `aws://`, the execution role, and the
route has no gateway backend. The execution role already has the Memory
data-plane grants, because the runtime binds its Memory.

The route is added only for a runtime with its default Memory. A route or HTTP
MCP server of the profile that already has the AgentCore host keeps it. A user
route named `agentcore` for another host stops build.

When AgentCore Gateway can get the session from the context keys, Memory calls
can go through the gateway again.
@vvargu
vvargu requested a review from a team November 21, 2026 01:42

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

Thanks for this. Moving Memory off the gateway role so Memory can scope each call to the runtime's session is the right fix, and the code for new projects is clean: the route is added only for the runtime's default Memory, it is a direct aws:// route with no backend, and the RUNTIME_ROUTE_NAME_TAKEN problem and the old-renderer parity tests are good. I checked the box egress docs: a bare aws:// route takes its SigV4 service and region from an *.amazonaws.com host, so bedrock-agentcore.<region>.amazonaws.com gets signed as bedrock-agentcore in the build region. I also checked that the L3 grants the runtime role the Memory data-plane actions for a bound Memory.

Blocking

  1. Conflicts with box-integration. A trial merge conflicts in src/core/project/runtimeProfile/rules/additions.ts (1 hunk, the rule table and imports next to #2885's [telemetry.agentcore_traces] row), src/core/project/runtimeProfile/rules/additions.test.ts (3 hunks), and src/core/project/manager.test.ts (2 hunks). They look textual, so keep both sides, but CI can't run until they're resolved. Please keep #2885's OTEL/X-Ray additions when you resolve them.

  2. Projects built before this change keep sending Memory through the gateway role, and nothing tells the user. Build saves its targets and additionalPolicies into agentcore.json, so an existing Box project already has the agentcore passthrough target on its Box gateway, agentcore/box-memory-policy.json in that gateway's additionalPolicies, and the file on disk. After this PR:

    • Nothing removes the agentcore target. It is not an egress- target, so the gateway rule treats it as the user's, keeps it, and writes [egress.agentcore] with a ${{ inputs.gateway.url }}/agentcore backend.
    • The additions rule then sees a route that already has the Memory host (routes.some(hasHost)) and adds no direct route. Memory calls still go through the gateway and are signed by the gateway role, which is the cross-session problem this PR is meant to fix.
    • box-memory-policy.json is no longer in BUILD_POLICY_FILES, so the IAM check now reads it as a user policy. It grants bedrock-agentcore:* data-plane actions, so boxGatewayIamWarnings stays quiet too. No warning appears and the role keeps the grant.

    I think build should remove what it wrote before. If the Box gateway has a target named agentcore that matches { passthrough https://bedrock-agentcore.<r>.<dnsSuffix>, CUSTOM, GATEWAY_IAM_ROLE bedrock-agentcore <r> } for some region (the shape the old getBoxGatewayAgentCoreTargetSpec produced), remove it with a step message. Also drop agentcore/box-memory-policy.json from additionalPolicies and emit { path, remove: true } for the file, which BoxNetworkFile already supports. Leave a target the user changed, as placeTarget already does for region moves. Please add a build test that starts from an old project (target, listing, and file present) and checks that the Runtime profile's [egress.agentcore] has no backend and the three leftovers are gone.

Non-blocking

  1. hasHost returns early for any route to the Memory host, including one that goes through the gateway. A user [egress.x] with destinations = ["bedrock-agentcore.<r>.amazonaws.com"] and secret.ref = "aws://" becomes a managed egress-x target with GATEWAY_IAM_ROLE, so Memory again goes out under the gateway role. That case does print a gateway IAM warning, so it isn't silent. Still, for this one host I'd only defer to a route with no backends, or report a problem when the route to the Memory host goes through the gateway. The unit test calls apply directly, so it doesn't cover what the gateway rule does before the additions rule runs.
  2. Stale doc: docs/box-local-testing.md (line 51) still says build writes "the Box gateway's Bedrock and Memory targets". README line ~262 ("its calls go out through its Box gateway") could mention the Memory exception and the VPC endpoint note from the PR description.
  3. hasHost matches destinations by exact string, so an entry for bedrock-agentcore.<r>.amazonaws.com:443 or a wildcard isn't counted, and box would then refuse two routes to one host. It's an edge case, but hostKey/buildHostMap could do the matching instead.
  4. For later: in China, box infers the signing scope only for .amazonaws.com / .api.aws, not .amazonaws.com.cn. Memory isn't offered there today (docs/china-regions.md), so nothing breaks now. If Memory ships in China, this route will need an explicit scope or a box change.

No internal references or account IDs in the diff or the commit message. I didn't find any unsafe test patterns.

Comment thread src/core/project/boxMemory.ts Outdated
region: string = DEFAULT_EGRESS_BEDROCK_REGION,
): string[] {
return [...addBoxBedrockTarget(spec, region), ...addBoxMemoryTarget(spec, region)];
return addBoxBedrockTarget(spec, 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.

Blocking: for a project built before this change, nothing removes what the old build wrote. The agentcore target stays on the Box gateway in agentcore.json, agentcore/box-memory-policy.json stays in additionalPolicies, and the file stays on disk. The gateway rule keeps the unmanaged agentcore target and routes [egress.agentcore] through the gateway, so Memory is still signed by the gateway role. Could this function remove a target whose shape matches the old getBoxGatewayAgentCoreTargetSpec(region) for any region, drop the listing, and have defaultTargetsWriter emit { path: "agentcore/box-memory-policy.json", remove: true }? A build test that starts from an old project would cover it.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

Fixed in fafa189. removeLegacyMemoryAccess runs first in addBoxGatewayTargets. It removes an agentcore target that is deep-equal to the old target shape for its own region (any partition), and drops agentcore/box-memory-policy.json from additionalPolicies. defaultTargetsWriter now emits { path, remove: true } for the file. A target of that name that the user changed stays, and build then stops with RUNTIME_ROUTE_NAME_TAKEN and names that target. The new build test in manager.boxNetwork.test.ts starts from an old project (target, listing, and file). It checks that all three are gone and that [egress.agentcore] has no backend.

const routes = [...Object.values(egress ?? {}), ...Object.values(tableOf(mcp))];
const hasHost = (entry: unknown) =>
isTable(entry) && Array.isArray(entry.destinations) && entry.destinations.includes(host);
if (routes.some(hasHost)) return egress;

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

This returns early for gateway-backed routes too. That covers the stale agentcore target from earlier builds (see the comment on boxMemory.ts) and a user aws:// route to the Memory host, which becomes an egress- target signed by the gateway role. In both cases Memory goes out under the gateway role again. For this host, could it defer only to a route with no backends, and otherwise replace the route or report a problem? destinations.includes(host) also misses host:443.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

Fixed in fafa189. The rule now defers only to a route or HTTP MCP server with no backends. A route to the Memory host that goes through the gateway stops build with RUNTIME_MEMORY_THROUGH_GATEWAY. The build test covers a local [egress.memory] with aws://default, through the gateway rule and then the additions rule. The host match now uses parseDestination, so host:443, any case, and a *. wildcard all count.

BOX_BEDROCK_POLICY_FILE,
BOX_MEMORY_POLICY_FILE,
]);
const BUILD_POLICY_FILES: ReadonlySet<string> = new Set([BOX_BEDROCK_POLICY_FILE]);

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Because this file is no longer here, a leftover agentcore/box-memory-policy.json from an earlier build is now read as a user policy. Its bedrock-agentcore actions count as granted, so the IAM warnings say nothing while the gateway role keeps Memory access. Removing the file and its listing on build (see the comment on boxMemory.ts) fixes this too.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

Fixed in fafa189, as you suggested. Build removes the listing and the file, so the IAM check no longer reads the old file as a user policy.

…-direct-access

# Conflicts:
#	src/core/project/manager.test.ts
#	src/core/project/runtimeProfile/rules/additions.test.ts
#	src/core/project/runtimeProfile/rules/additions.ts

@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-review at 4bca2ed (merge of box-integration at 3df8eab).

Merge: fixed, looks clean. The PR merges cleanly and has no conflict markers. #2885's OTEL/X-Ray changes are still there in additions.ts, additions.test.ts and manager.test.ts: the agentcore_traces row, defaultTracesTelemetry/withOtel in the derive test, and the box-telemetry-policy-* steps. The PR's own net diff matches what it was at 18f07c6, apart from line offsets and the comment and test changes that come from the merge. No change on the base is reverted.

Still blocking: the upgrade path (point 2 of my last review). No new commit addresses it. A project built before this PR keeps its agentcore gateway target. Build treats that target as the user's because it has no egress- prefix, so routes.some(hasHost) skips the direct route. Its Memory calls therefore still go through the gateway role. The project also keeps agentcore/box-memory-policy.json in its list and on disk. That file is no longer in BUILD_POLICY_FILES, so build reads it as a user policy and boxGatewayIamWarnings gives no warning. #2877 is still open, and its ownership record would not cover projects built before it anyway. What I suggested before still applies: remove the old target shape and the policy listing, delete the file (remove: true), and add a test that builds from an old project.

CI: CodeQL, Analyze, macOS and CodeBuild e2e pass. verify / Linux and verify / Windows were still pending when I posted this.

My earlier non-blocking notes still stand and I won't repeat them.

@codecov-commenter

codecov-commenter commented Nov 21, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.80%. Comparing base (3df8eab) to head (fafa189).

Additional details and impacted files
@@               Coverage Diff                @@
##           box-integration    #2889   +/-   ##
================================================
  Coverage            96.80%   96.80%           
================================================
  Files                  766      766           
  Lines                66928    66945   +17     
================================================
+ Hits                 64790    64807   +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.

A project that an earlier build wrote kept the `agentcore` target on its Box
gateway and `agentcore/box-memory-policy.json` in the gateway's
additionalPolicies and on disk. The gateway rule kept that target as the
user's, so the Memory calls still went through the gateway role, and the IAM
check read the old file as a user policy and gave no warning.

Build now removes the `agentcore` target when it is as the earlier build wrote
it for some region, removes the policy listing, and removes the policy file.
A target of that name that the user changed stays, and build then stops until
the user renames it, because its route would take the name of the Memory
route.

The Memory route rule now defers only to a direct route or HTTP MCP server to
the Memory host. A route through the Box gateway stops build with
RUNTIME_MEMORY_THROUGH_GATEWAY. The rule matches the host with `:443`, in any
case, and as a `*.` wildcard.

The README and the local testing guide now say that Memory calls go to Memory
directly, and that a runtime in VPC network mode needs a `bedrock-agentcore`
VPC endpoint.

@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-review of fafa189 (git diff 4bca2ed3..fafa189f, one new commit: "fix(box): Remove the Memory gateway access that an earlier build wrote"). Follow-up to my earlier COMMENT review.

Blocker (projects upgraded from an older build keep the cross-session Memory problem): fixed.

  • Old target: removeLegacyMemoryAccess finds the old target with isDeepStrictEqual against the exact shape the old getBoxGatewayAgentCoreTargetSpec wrote: name agentcore, passthrough to the AgentCore data-plane host of the target's own region, CUSTOM protocol, and GATEWAY_IAM_ROLE/bedrock-agentcore auth. Because the region comes from the target itself, a target written for any region is removed, including the China partition (tested). It runs over every bound Box gateway, so per-runtime networks are covered. It leaves alone a user's own agentcore target with a different shape, and the same shape on a non-Box gateway (both tested). If a user's own agentcore target remains, build stops with RUNTIME_ROUTE_NAME_TAKEN. That problem now points at agentcore.json and asks the user to rename the target. It doesn't fall back to a gateway route.
  • Policy: the box-memory-policy.json entry is dropped from additionalPolicies, and additionalPolicies itself is removed if that was its only entry. The file is deleted through { remove: true } with a removing <file> step, so the deletion is visible to the user. The delete uses unlinkSync behind existsSync, so a failure throws instead of being swallowed. Deleting without checking the content is fine: the older build owned this file and rewrote it on every build, so user edits never survived anyway.
  • End to end: the new manager-level test starts from an old project (old target, policy listing, policy file on disk) and runs build. It asserts that the target is gone, the listing is gone, the file is gone, the three step messages are printed, and [egress.agentcore] is the direct route (aws://, no backends).
  • Idempotent / new projects: on a second build, or on a new project, nothing matches and nothing is printed, because the remove step only reports when the file exists. That holds by construction; there is no explicit second-build test (see nit below).

Non-blocking items from my earlier review

  • hasHost also skipped the direct route when a gateway route already covered the Memory host: addressed. A route or MCP server with backends to the Memory host is now RUNTIME_MEMORY_THROUGH_GATEWAY and stops the build. This is tested in the rule and through build.
  • Stale docs (docs/box-local-testing.md, the README VPC endpoint note): addressed.
  • hasHost matched only the exact string: addressed. hasDestination now accepts any letter case, :443, and *. wildcards, and rejects other ports (tested).
  • China signing inference: still open as far as I can see. Fine to leave for a later phase.

New nits (non-blocking)

  1. hasDestination treats a *. wildcard as matching any number of subdomain levels (*.amazonaws.com covers bedrock-agentcore.<region>.amazonaws.com). Please confirm box matches wildcards the same way. If box's * matches only one label, a user's *.amazonaws.com route would stop build from adding the direct Memory route while box doesn't send Memory calls through that route either. Separately, a direct wildcard route without secret = aws:// now also stops the Memory route from being added, and then the Memory calls go out unsigned. A warning for that case may be worth adding.
  2. The legacy file is deleted no matter who lists it, but the listing is only removed from bound Box gateways. If a non-Box gateway lists agentcore/box-memory-policy.json, it is left pointing at a missing file. That's unlikely; one line in the step message or a check would cover it.
  3. A second build run in the old-project manager test would pin the idempotency.

Other checks: no internal references or account IDs in the diff. New tests use join(root, ...relative.split("/")) and existsSync, with no hard-coded / paths, chmod, spawned shells, or network. #2877 (box-gateway-targets.json) and #2864 (reserved names) are both still open. When they land, whichever merges second should include agentcore in, or reconcile it with, the reserved/recorded names. Nothing in this diff conflicts with them.

CI at review time: Linux and Windows verify pass, CodeQL, Analyze, and CodeBuild e2e pass. macOS verify failed only on project add runtime-endpoint wizard > a rejected add reports itself and hands the form back (timed out after 5000ms). That is the known macOS screen-test timeout flake and unrelated to this change. Please re-run macOS and merge only after checks are green. Merge state is blocked only because a review is required; the PR is up to date with box-integration.

Approving: the upgrade-path blocker is resolved and the rest are nits.

const destination = typeof text === "string" ? parseDestination(text) : undefined;
if (destination === undefined || destination.port !== 443) return false;
const name = destination.host.toLowerCase();
return destination.wildcard

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 treats *.amazonaws.com as covering any number of subdomain levels. Does box match a *. wildcard the same way? If box's * matches only one label, this would skip adding [egress.agentcore] while box doesn't send the Memory calls through the wildcard route. Also, a direct wildcard route without secret = aws:// would send the Memory calls unsigned. Maybe warn in that case.

.flatMap(({ path, policy }): BoxNetworkFile[] =>
policy ? [{ path, text: `${JSON.stringify(policy, undefined, 2)}\n` }] : [],
)
.concat({ path: LEGACY_BOX_MEMORY_POLICY_FILE, remove: true }),

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: the file is deleted for the whole project, but removeLegacyMemoryAccess drops the listing only from bound Box gateways. A non-Box gateway that lists this file would be left pointing at a missing file. That's unlikely, but a check (or keeping the file when another gateway still lists it) would close the gap.

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