Skip to content

feat(box): Let a boxed agent use the MCP tools of the other gateways of its project - #2887

Open
SaiAbhishek98 wants to merge 17 commits into
aws:box-integrationfrom
SaiAbhishek98:sa/box-gateway-to-gateway
Open

SaiAbhishek98 wants to merge 17 commits into
aws:box-integrationfrom
SaiAbhishek98:sa/box-gateway-to-gateway

Conversation

@SaiAbhishek98

@SaiAbhishek98 SaiAbhishek98 commented Nov 21, 2026 •

Copy link
Copy Markdown

Description

The route needs aws/agentcore-l3-cdk-constructs#478. With the pinned @aws/agentcore-cdk 1.1.0, build writes no gateway-to-gateway target and gives one warning, and the project builds and deploys as before. The route starts to operate when the CLI pins a CDK release that has aws/agentcore-l3-cdk-constructs#478.

Problem

A runtime without a box gets the URL of each gateway of its project in
AGENTCORE_GATEWAY_<NAME>_URL, and its code uses the MCP tools of that gateway. A boxed agent on
AgentCore Runtime cannot do this. Its box has no route to the host of the gateway, so the box
refuses each request. The user cannot add the route: build refuses aws:// for a gateway host with
UNSIGNABLE_HOST, and the ID of the gateway is not known before the first deploy.

What changes

For each gateway without boundRuntime, build does these steps for each box runtime. The user
writes nothing.

Part What build writes
Box gateway target egress-gateway-<name>, with passthrough.gateway: "<name>" and GATEWAY_IAM_ROLE for bedrock-agentcore. A NONE gateway gets no outbound auth.
@box/agentcore pack The inputs gateways.<name>.url from env:<prefix>_URL and gateways.<name>.host from env:<prefix>_HOST, each with a pattern. The agent gets <prefix>_URL in [agent.env].
Runtime profile only [mcp.<name>], with destinations = ["${{ inputs.gateways.<name>.host }}"] and a backend to the URL of the Box gateway and /egress-gateway-<name>, signed with aws://.
Schema passthrough has gateway or endpoint. The value of gateway must be the name of a gateway of the project without boundRuntime.

Decisions

  • Only the gateways of the project. A PRIVATE_VPC runtime gets none, because the L3 binds none
    to it. A CUSTOM_JWT gateway gets a warning and no target, because the Box gateway signs only
    with its role.
  • The same variable as a runtime without a box. The agent reads AGENTCORE_GATEWAY_<NAME>_URL.
    Box reads the host from AGENTCORE_GATEWAY_<NAME>_HOST, because box 0.1.11-preview.10 takes an
    input in destinations only when its value is a host. The L3 sets _HOST.
  • One deploy. The L3 gives the endpoint and the grant from the gateway in the same stack. The
    CLI does not wait for deployed-state.json, because that needs a second deploy.
  • The Runtime profile changes, and the local profile does not. As in
    aws/agentcore-cli#2866, only what must be
    different on the Runtime changes.
  • Box permits each tool. Box adds a permit for each tool of a declared [mcp] server. A forbid
    rule of the user's policy stays, so the user can stop a tool.
  • A gateway host in the profile stays refused. Build cannot tell a gateway of this project from
    a gateway of a different project by its host, because the ID exists only after deploy. The message
    of UNSIGNABLE_HOST also names the route that build adds.
  • The name of a server. The server has the name of the gateway, so a policy rule names it with
    context.input.server == "<name>". A local server with that name stops build.
  • The input names start with gateways., not gateway., because gateway.url is the input of the
    Box gateway, and a gateway with the name url would have the same input name.
  • Build asks the installed library, not its version. Before build writes a gateway-to-gateway
    target, it runs node in agentcore/cdk and asks the installed @aws/agentcore-cdk if its
    PassthroughConfigSchema accepts { gateway, protocolType } (cdkAcceptsPassthroughGateway).
    Thus the check reads the same library as synth.
    • The check does not read the version, because no release has the field yet, and a local build
      of the L3 box-integration branch has the version 1.0.2.
    • Build does the check only when the project has a box runtime and a gateway without
      boundRuntime.
    • When the library refuses the field, is not there, or the check fails, build writes no target,
      no [mcp] server, and no pack input. It removes a target that it wrote before, and gives one
      warning that names the gateways.
    • @aws/agentcore-cdk 1.1.0 from npm gives false. The build of
      aws/agentcore-l3-cdk-constructs#478 gives true.
  • remove gateway removes the target that build wrote for that gateway. After a build, each Box
    gateway has egress-gateway-<name> for the gateway <name>. remove gateway <name> also
    removes, from each other gateway, each egress- target with passthrough.gateway: "<name>".
    Thus the spec stays correct for the schema. A target that the user wrote and that names the
    gateway stays, and the schema refuses it with its name.
  • Each gateway gets its own target name. The target name is egress-gateway-<name> when
    targetNameFor keeps all of the gateway name. targetNameFor changes -- to - and cuts a name
    at 100 characters. For such a name, the target name ends in 8 hex digits of the SHA-256 of the
    gateway name. It has 100 characters at most, and it is the same on each build.
  • China hosts. The _HOST and _URL patterns accept amazonaws.com.cn, as the gateway host
    of AWS_ENDPOINTS does.

Verified outside CI

  • Live test, a test account in us-west-2. I did it before the review changes. A new project from this branch
    (55e6f4b4)
    and the L3 branch
    (860f8093),
    with box 0.1.11-preview.10. I added a second gateway toolsgw (AWS_IAM) and one Lambda target
    with agentcore add gateway and agentcore add gateway-target. I did not change the box profile,
    the targets of the Box gateway, or IAM.
  • One deploy made egress-gateway-toolsgw with the endpoint of toolsgw, the grant on the role
    of the Box gateway, and AGENTCORE_GATEWAY_TOOLSGW_URL and _HOST on the runtime.
  • The known answer came back through the Box gateway. The agent used echo___known_answer and
    gave gw2gw-known-answer-7319.
    • Box: mcp:call toolsgw/echo___known_answer, permit, rule mcp_toolsgw_call.
    • Box gateway: "Executing Http request for target" egress-gateway-toolsgw.
    • toolsgw: tools/call echo___known_answer with {text=hello from the box}, and the reply with
      gw2gw-known-answer-7319.
  • Test-only changes. Agent code that uses the gateway with the Strands MCPClient, and
    enableApplicationLogs on toolsgw. I did agentcore deploy two more times for that agent code.
    add gateway gives protocolType: "None", so _URL has no /mcp. The agent code must add it,
    the same as without a box.
  • Teardown. I removed the stack and the log groups that it left.

Follow-ups

  • Pin a CDK release that has aws/agentcore-l3-cdk-constructs#478. Until then, build writes no gateway-to-gateway target and
    gives one warning. To test the route before that, use a local L3 build, as in step 5 of
    docs/box-local-testing.md.
  • aws/agentcore-l3-cdk-constructs#477
    removes the shared gateway grants from a boxed runtime. With it, the runtime of this change gets
    the variables of a gateway only through its Box gateway target, and no grant on that gateway.
  • agentcore dev gets no route to the gateways. The local profile is the user's.
  • GATEWAY_URL_PATTERN, for the input gateway.url of the Box gateway itself, also stops at
    amazonaws.com. That pattern was there before this PR.

Related Issue

None.

Documentation PR

docs/box-local-testing.md is in this change.

Type of Change

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

Testing

  • I ran bun test, with box 0.1.11-preview.10 on PATH. 5889 pass, 6 skip, 1 fail. The one
    failure is "the box on PATH > resolves a profile into the rules the tests fake". It fails on
    box-integration too with this box, and CI has no box, so CI skips it.
  • I ran the relevant end-to-end tests with bun run test:e2e, or explained why they are not
    applicable. I did the live test above, and not the e2e 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. This change does not change
    src/assets/.
  • If I re-recorded fixtures or golden files, every change beyond account identifiers is
    explained by this PR. I did not record fixtures.
  • This PR does not change command.md (the release workflow regenerates it)

Without the change in src/, 35 of the 265 tests of the six changed test files fail. Each of 19
mutations of src/ fails one or more of the new tests. For the review changes, each new test fails
before its change, and each of 5 more mutations fails one or more of them. The test for a gateway
name with - and capital letters passes before and after, because box 0.1.11-preview.10 accepts that
name. CI passes on Linux, Windows, and macOS.

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. The L3 change is not merged.

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

…of its project

## Problem

A runtime without a box gets the URL of each gateway of its project in
`AGENTCORE_GATEWAY_<NAME>_URL`, and its code uses the MCP tools of that gateway. A boxed agent on
AgentCore Runtime cannot do this. Its box has no route to the host of the gateway, so the box
refuses each request. The user cannot add the route. Build refuses `aws://` for a gateway host
with `UNSIGNABLE_HOST`, and the ID of the gateway is not known before the first deploy. A target
and a grant that you make by hand operate, but build does not keep them in `agentcore.json`.

## Solution

- **Which gateways.** A box runtime gets each gateway without `boundRuntime`, the same gateways
  that the L3 binds to a runtime without a box (`projectGatewaysOf`). A `PRIVATE_VPC` runtime gets
  none. A `CUSTOM_JWT` gateway gets a warning and no target, because the Box gateway signs only
  with its role.
- **The target.** Build writes `egress-gateway-<name>` on the Box gateway of the runtime, with
  `passthrough.gateway: "<name>"` and `GATEWAY_IAM_ROLE` for `bedrock-agentcore` in the build
  region. A `NONE` gateway gets no outbound auth. Build changes and removes the target as it does
  each other `egress-` target. A host of the profile cannot use its name
  (`TARGET_NAME_COLLISION`), and the limit of 100 targets counts it.
- **The schema.** `passthrough` can have `gateway` or `endpoint`, but not the two.
  The name must be a gateway of the project without `boundRuntime`, and not the gateway of the
  target.
- **The pack.** The `@box/agentcore` pack of each box runtime declares `gateways.<name>.url` from
  `env:<prefix>_URL` and `gateways.<name>.host` from `env:<prefix>_HOST`, each with a pattern. The
  agent gets `<prefix>_URL` in `[agent.env]` from the input, so the code that uses the gateway
  without a box operates in the box.
- **The Runtime profile.** Only the Runtime profile gets `[mcp.<name>]`, with
  `destinations = ["${{ inputs.gateways.<name>.host }}"]` and one backend to the URL of the Box
  gateway and `/egress-gateway-<name>`, signed with `aws://` for `bedrock-agentcore`. Box adds a
  permit for each tool of a declared server, and a forbid rule of the policy stays. The local
  profile does not change. A server of the local profile with the name of a gateway stops build
  (`RUNTIME_GATEWAY_SERVER_NAME_TAKEN`).
- **Gateway hosts in the profile.** `AWS_ENDPOINTS` has the gateway host, with the service
  `bedrock-agentcore`. An entry that signs for a gateway host with `aws://` stops build with
  `UNSIGNABLE_HOST`, and the message names the route that build adds. Build cannot tell a gateway
  of this project from a gateway of a different project by its host, because the ID of a gateway
  is known only after deploy.
- **IAM warnings.** `boxGatewayIamWarnings` gives no warning for a target with
  `passthrough.gateway`, because the L3 gives the grant. It gives a warning for a target to a gateway host
  when the role has no `bedrock-agentcore:InvokeGateway`.
- **Interfaces that changed.** `PassthroughConfigSchema` (`endpoint` is optional, `gateway` is
  new), `BoxNetwork.projectGateways`, `RuntimeProfileContext.projectGateways`,
  `renderAgentCorePack(spec, gateways)`, and the problem code
  `RUNTIME_GATEWAY_SERVER_NAME_TAKEN`.
- **Dependency.** The target needs the L3 branch `sa/box-gateway-to-gateway` of
  aws/agentcore-l3-cdk-constructs. That branch gives the endpoint, the grant, and
  `<prefix>_HOST`.
- **Not done.** box 0.1.11-preview.10 takes an input in `destinations` only when its value is a
  host. Thus the pack reads `<prefix>_HOST` and not the URL. If the CLI wrote the target from
  `deployed-state.json`, each new project must deploy two times.

## Tests

- `src/core/project/boxNetwork/network.test.ts`, "the gateways of the project": the gateways that
  the agent gets, a `PRIVATE_VPC` runtime, a `CUSTOM_JWT` gateway, the name collision, the target that
  build wrote, the limit of 100, and the refusal of a signed gateway host in `[egress]` and
  `[mcp]`. "boxGatewayIamWarnings for a gateway of the project" pins the two warnings.
- `src/core/project/boxNetworkWriters.test.ts`, "gatewayTargetsWriter for the gateways of the
  project": the writer adds, changes, and removes the target. "stages the inputs of each gateway
  that the agent calls in the @box/agentcore pack" pins the staged pack.
- `src/core/project/runtimeProfile/rules/gateway.test.ts`, "the gateway rule for a gateway of the
  project": the `[mcp.<name>]` server, no server with no gateway, and the stop for a server name
  that a gateway has.
- `src/core/project/templates/boxProfile.test.ts`, "for a gateway of the project that the agent
  calls" (a test name): the two inputs, the agent variable, and the host and URL patterns.
- `src/projectSchemas/project.test.ts`, "a passthrough target that names a gateway": the spec that
  it accepts and the five refusals.
- `src/core/project/boxNetwork/projectGateways.test.ts`: the two target shapes. "the box on PATH"
  operates box 0.1.11-preview.10 on the Runtime profile and the pack that build makes, with the
  variables that the L3 sets. Box resolves the server to the host, the backend to the target, the
  agent variable to the URL, and adds its `net:connect` permit for the host. The test skips when no
  box is on `PATH`.
- Without the change in `src/`, 35 of the 265 tests of these six files fail. Each of 19 mutations
  of `src/` fails one or more of these tests.
- `bun test` with box 0.1.11-preview.10 on `PATH`: 5867 pass, 6 skip, 1 fail. The one failure is "the box on
  PATH > resolves a profile into the rules the tests fake" in `boxProfileResolver.test.ts`. It
  fails on `upstream/box-integration` too, with this box. CI has no box, so CI skips it.
- `bun run typecheck`, `bun run lint:check`, and `bun run format:check` pass.
- Live test in a test account in us-west-2: a new project from this branch and the L3 branch, with a
  second gateway `toolsgw` (`AWS_IAM`) and one Lambda target that gives a known answer. I added the
  gateway and the target with `agentcore add gateway` and `agentcore add gateway-target`. I did not
  change the box profile, the targets of the Box gateway, or IAM. One deploy made the target, the
  grant, and the variables. The agent used `echo___known_answer` and gave the known answer
  `gw2gw-known-answer-7319`. Box logged a permit for `mcp:call toolsgw/echo___known_answer`, the
  Box gateway sent the request to `egress-gateway-toolsgw`, and `toolsgw` logged the tool call and
  the known answer. The test project only had these changes: agent code that uses the gateway,
  `enableApplicationLogs` on `toolsgw`. I did `agentcore deploy` two more times for that agent code. `add gateway`
  gives `protocolType: "None"`, so `_URL` has no `/mcp`, and the agent code must add it, the same
  as without a box.
- I did not do these: `bun run test:e2e`, `bun run audit`, `bun run secrets:check`, and `bun run build`.
@SaiAbhishek98
SaiAbhishek98 requested review from a team and leo237 November 21, 2026 00:25
@codecov-commenter

codecov-commenter commented Nov 21, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 99.42197% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.81%. Comparing base (3df8eab) to head (33c29a1).

Files with missing lines Patch % Lines
src/core/project/backends/cdk/compatibility.ts 96.00% 1 Missing ⚠️
src/core/project/boxNetwork/network.ts 97.77% 1 Missing ⚠️
Additional details and impacted files
@@                 Coverage Diff                 @@
##           box-integration    #2887      +/-   ##
===================================================
+ Coverage            96.80%   96.81%   +0.01%     
===================================================
  Files                  766      767       +1     
  Lines                66928    67245     +317     
===================================================
+ Hits                 64790    65105     +315     
- Misses                2138     2140       +2     

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

Thanks for this. The design holds together: the CLI writes the target, the L3 resolves the endpoint and the grant in the same stack, and the agent reads the same AGENTCORE_GATEWAY_<NAME>_URL it reads without a box. I checked the parts I was worried about and they're fine:

  • The Box gateway itself isn't selected, because it has boundRuntime, so there's no self-loop.
  • Two gateways with the same prefix are already a schema error (the existing discoveryPrefix collision check).
  • gatewayDiscoveryPrefix matches the existing non-box naming.
  • The L3 #478 grant is scoped to the named gateway only.
  • Nothing internal shows up in the diff or the commit message.
  • The must-survive fixes from earlier PRs are all still in place: inputs.gateway.url, inputs.aws.region, writesBedrockRoute, tomlKey, the xray grants, the enableApplicationLogs notice, the preview.10 pin and --containment.

CI is green on 55e6f4b (Linux/macOS/Windows verify, CodeQL, e2e CodeBuild). The branch is 2 commits behind box-integration (#2884) and merges into it cleanly.

Blocking

  1. Merging now breaks the deploy of an existing Box project that has another gateway. box-integration pins @aws/agentcore-cdk 1.1.0 in src/assets/cdk/package.json. At v1.1.0 the L3 PassthroughConfigSchema is .strict() and requires endpoint. aws/agentcore-l3-cdk-constructs#478 is still open and unmerged, and v1.2.0 doesn't have it either. With this PR, build writes an egress-gateway-<name> target with only passthrough.gateway for every unbound AWS_IAM/NONE gateway. The user doesn't have to do anything for this to happen, so any Box project with one more gateway will fail synth on the pinned L3. Today that same project deploys: its boxed agent just can't reach the gateway. The NONE-auth note in docs/box-local-testing.md is opt-in, and this isn't. Please do one of these: hold this PR (draft) until #478 ships and the pin is bumped in the same PR; gate it behind an L3 version check or a flag; or make it explicitly opt-in until then. (The PR body's Follow-ups still say the L3 change "is not a pull request yet". It is #478 now.)

  2. agentcore remove gateway <name> fails after one build. Once build has written egress-gateway-<name> with passthrough.gateway: "<name>", removing that gateway leaves the reference dangling. commitSpec re-validates with ProjectSpecSchema, and the new refine rejects it ("...names the gateway ... but the project has no gateway of that name. Name a gateway of this project without boundRuntime"). Build never runs, so it can't prune the target. The user has to know to run remove gateway-target egress-gateway-<name> --gateway <runtime>-box-egress first, for each box runtime. Hand-adding boundRuntime to that gateway hits the same error. The writer test "removes the target of a gateway that the agent no longer calls" bypasses the schema, so this path isn't covered. Suggested fix: removeResource for gateway should also drop the build-owned passthrough.gateway targets that name it, with a test. Alternatively, the refine could tolerate a dangling reference in a build-owned egress- target and let build prune it.

Non-blocking

  • Names with - or uppercase. GatewayNameSchema allows my-gw / MyGw. That produces [inputs.gateways.my-gw.url] and ${{ inputs.gateways.my-gw.host }}. The TOML side is fine. What I couldn't verify is whether box's ${{ }} expression parser accepts - in an input path segment. Memory names never contain -, so there's no precedent. The box-on-PATH test and the live test only use tools/toolsgw. Could you add a hyphenated name to the box-on-PATH test, or normalize the input key?
  • Target-name collisions. targetNameFor collapses runs of non-alphanumerics and truncates to 93 chars. So a--b and a-b both map to egress-gateway-a-b, and so do two 100-char names that share a long prefix. Their prefixes differ (A__B vs A_B), so the prefix check doesn't catch this, and the writer would push two targets with the same name. A collision check in projectGatewaysOf would make this fail loudly instead.
  • China partition. PROJECT_GATEWAY_HOST_PATTERN/_URL_PATTERN stop at amazonaws.com. AWS_ENDPOINTS accepts (?:\.cn)?, and #2883 adds .amazonaws.com.cn for the Bedrock/Memory hosts. In a China build, box would refuse the input when the run starts. That failure is loud, and the existing GATEWAY_URL_PATTERN has the same gap, but the two patterns should agree once #2883 lands.
  • Box permits every tool of each project gateway automatically. This matches what a runtime without a box gets, and the docs cover it. Still, it widens the boxed agent's reach without the user writing anything. Consider saying so in a build message (e.g. "adding gateway target ... the agent may call every tool of ''"), or offering an opt-out.
  • The CUSTOM_JWT warning repeats on every build for every box runtime. A JWT gateway that is meant for external clients only will warn forever. Consider a way to acknowledge it.
  • Interaction with #2877. #2877 (open) moves build-owned targets from the egress- prefix to the record in agentcore/box-gateway-targets.json. Whichever PR lands second has to record the egress-gateway-* targets as build-owned. The trial merge with #2877 conflicts in docs/box-local-testing.md and boxNetwork/network.test.ts.
  • Trial merges with the other open PRs. #2883 is clean. #2885 conflicts in docs/box-local-testing.md, boxNetworkWriters.ts and templates/boxProfile.ts. #2886 conflicts in docs/box-local-testing.md.
  • Back-merge. This also needs a back-merge to box-integration-development.
  • boxMemory.ts. The one-line change (passthrough?.endpoint &&) is correct for the now-optional endpoint.

Comment thread src/projectSchemas/project.ts Resolved
Sai Abhishek added 6 commits November 20, 2026 16:38
Review feedback: the `<prefix>_HOST` and `<prefix>_URL` patterns of `@box/agentcore` stopped at
`amazonaws.com`, and the gateway host of `AWS_ENDPOINTS` also accepts `amazonaws.com.cn`. Thus box
refused the two inputs in a China region. Each pattern now accepts `amazonaws.com.cn`.

Test: "the host pattern takes ... amazonaws.com.cn: true" and "the URL pattern takes
https://....amazonaws.com.cn/mcp: true" in `boxProfile.test.ts` fail before this change.
…x on PATH

Review question: a gateway name can hold "-" and upper case, so the Runtime profile has
`${{ inputs.gateways.My-Tools-GW.host }}` and `[mcp.My-Tools-GW]`. The test "the box on PATH" now
also uses the gateway `My-Tools-GW`. box 0.1.11-preview.10 resolves the input, the server, the
backend, the agent variable, and the permit `context.input.server == "My-Tools-GW"`.

No code changes, because box accepts these names. This test does not fail before this commit. It
pins the behaviour, and it skips when no box is on PATH.
… name

Review feedback: `targetNameFor` changes `--` to `-` and cuts a name at 100 characters. Thus the
gateways `a--b` and `a-b`, or two long names with the same start, got the same target name, and the
writer added two targets with one name.

The target name stays `egress-gateway-<name>` when that name keeps the gateway name whole. When
`targetNameFor` changes the name, the target name ends in 8 hex digits of the SHA-256 of the gateway
name, and it has at most 100 characters. The name is the same on each build.

Test: "is not the same for a--b and a-b" and "is not the same for" two names of 96 characters with
the same start, in `projectGateways.test.ts`, fail before this change.
…ject accepts it

Review feedback (blocking): `@aws/agentcore-cdk` 1.1.0, which `box-integration` pins, has a
strict `PassthroughConfigSchema` that requires `endpoint`. It refuses `passthrough.gateway`. Build
wrote that target for each gateway without `boundRuntime` of a Box project, so the synth of such a
project failed until a new library ships.

Build now asks the library of the CDK app, with `node` in `agentcore/cdk`, whether
`PassthroughConfigSchema` accepts `{ gateway, protocolType }` (`cdkAcceptsPassthroughGateway`).
Thus it reads the same library as synth, and a local build of the library works too. A version
number cannot tell this, because aws/agentcore-l3-cdk-constructs has not released the change, and
a local build of its `box-integration` branch has the version 1.0.2. Build asks only when a box
runtime and a gateway without `boundRuntime` are in the project. When the library refuses the
field, is not there, or the check fails, build writes no target, no server, and no pack input. It
removes a target that it wrote before, and gives one warning that names the gateways. The manager
takes the check in `cdkAcceptsPassthroughGateway`, so tests do not run `node`. Equal warnings of two
box runtimes show once.

Tests that fail before this change:
- `compatibility.test.ts`, "cdkAcceptsPassthroughGateway": true for a library that accepts the
  field, false for one that requires `endpoint`, and false with no library or no schema.
- `network.test.ts`, "gives the agent no gateway when the @aws/agentcore-cdk of the project
  refuses passthrough.gateway, and warns once".
- `manager.boxNetwork.test.ts`, "writes no target and no server, and warns once, when it does
  not". The test "writes the target and the server when the @aws/agentcore-cdk of the project
  accepts passthrough.gateway" pins the other case.

I also ran the check on two real libraries: `@aws/agentcore-cdk` 1.1.0 from npm gives false, and
the build of aws/agentcore-l3-cdk-constructs branch `sa/box-gateway-to-gateway` gives true.
Review feedback (blocking): after one build, each Box gateway has the target
`egress-gateway-<name>` with `passthrough.gateway: "<name>"`. `agentcore remove gateway <name>`
kept that target, the project schema refused the new spec because the target names no gateway, and
thus the user could not remove the gateway, and build could not remove the target.

`removeResource` now also removes, from each other gateway, each target that build owns (its name
starts with `egress-`) and that names the removed gateway in `passthrough.gateway`. A target of the
user's that names the gateway stays, and the schema still refuses it with its name, so build never
removes a target that the user wrote. I did not make the schema accept a target that names no
gateway, because the spec then is not valid for the CDK library until the next build.

Test: `manager.boxNetwork.test.ts`, "lets remove gateway remove the gateway after a build, with the
target build wrote for it", fails before this change with the schema error. It builds, removes the
gateway, and then builds again. The user's own target stays.
@SaiAbhishek98
SaiAbhishek98 requested a review from leo237 November 21, 2026 00:54

@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 743cd84 (since 55e6f4b: merge of box-integration, plus 5 fix commits). Both earlier blockers are fixed. Approving.

Earlier blockers

  1. Deploy breaks for existing Box projects (CDK 1.1.0 refuses passthrough.gateway): fixed in 801cff5. cdkAcceptsPassthroughGateway runs node -e in agentcore/cdk. That loads the same @aws/agentcore-cdk that synth loads, and it calls PassthroughConfigSchema.safeParse({ gateway, protocolType }). I checked the L3 side. At the #478 head the package is CJS (exports["."].require) and re-exports PassthroughConfigSchema through export * from './schema'. On 1.1.0 the schema is strict and needs endpoint, so the probe returns false. On #478 it returns true. When the answer is unknown it is safe: a missing library, a missing node, a throw or a timeout all give false. Build then writes no target, no [mcp] server and no pack input, drops any target it wrote before, and gives one deduplicated warning. When node_modules is missing, synth already stops with "CDK dependencies are missing", so a first build before npm install is fine. Tests cover accepts / refuses / not installed / no export (gated on Bun.which("node")), the network model with projectGatewayTargets: false, and both manager paths through an injected probe.
  2. remove gateway fails after one build: fixed in 743cd84. removeResource now drops each build-owned target (egress- prefix) whose passthrough.gateway names the removed gateway. A user target that names it stays and is still refused by name, which is correct. The new manager test runs through the real manager and commitSpec (with schema validation). It removes after a build, keeps the user's target, and builds again with no target coming back. #2877 is still open and not on base, so there is no box-gateway-targets.json record to update yet.

Other earlier items

  • China hosts: fixed in 7c9536d. ([.]cn)? is on the host and URL patterns, with a negative test for ….cn.evil.example.com.
  • Target-name collisions: fixed in 7545175. Names that survive targetNameFor unchanged keep egress-gateway-<name>, so nothing tested live is renamed. Changed names get an 8-hex SHA-256 suffix, stay at most 100 chars, and are the same on every build. Tests cover a--b vs a-b and long names that share a prefix. No migration is needed because nothing has shipped.
  • -/uppercase gateway names in inputs: partly addressed in 36d4d4a. The box-on-PATH test now also covers My-Tools-GW and checks the input, server, backend, agent env and policy. It is gated on a box with --format json --full, so CI never runs it; the commit message says box 0.1.11-preview.10 passes it locally. That is fine as a pin.
  • Merge ba614e4: clean. The PR's diff against the new base is identical, apart from hunk headers, to its diff at 55e6f4b against the old merge-base: 17 files, +875/-40. So no PR change was lost and no #2883/#2884 change was reverted.
  • Still open (non-blocking): automatic tool access (a message or opt-out); the CUSTOM_JWT warning repeats on every build (the new Set only dedupes across runtimes in one build); the interaction with #2877 once it lands; back-merge to dev.

New nits (non-blocking)

  • PR body: the top says it depends on aws/agentcore-l3-cdk-constructs#478, but Follow-ups still says the L3 change "is not a pull request yet". With the probe, merging before #478 now degrades to a warning, not a broken synth. The body could say that.
  • The warning always says the library "does not accept passthrough.gateway", even when the probe failed for another reason (see inline).

No internal references in the diff or commit messages. Test patterns look safe: tmpdir paths, and node/box spawns gated on PATH.

CI at 743cd84: CodeQL, Analyze, verify / Windows, verify / macOS and CodeBuild e2e pass. verify / Linux was still pending when I posted, so this approval assumes it goes green. e2e is skipped.

Sai Abhishek added 4 commits November 20, 2026 17:32
…eway that it cannot call

Review feedback: after a build, a gateway of the project that gets `boundRuntime`, or that is
removed from agentcore.json by hand, left the target `egress-gateway-<name>` with a reference that
the project schema refused. Each command then stopped when it read agentcore.json, so build could not
remove the target.

The schema does not do this check for a target whose name starts with `egress-`
(`BOX_EGRESS_TARGET_PREFIX`), because build writes and removes each such target. The next build
removes the target. A target of the user that names such a gateway is still refused. The prefix
moves to `projectSchemas/project.ts`, and `boxNetwork/egress.ts` exports it from there.

Tests that fail before this change: `manager.boxNetwork.test.ts`, "reads the project and removes
the target after a build when the gateway gets boundRuntime" and "reads the project and removes the
target when the gateway is gone from agentcore.json". `project.test.ts`, "accepts a target that build
owns and that names ...", pins the schema. The refusals in that file now use a target of the user.
…name

Review feedback: `hostTargets` put the target of each gateway of the project in `owners` with
`owners.set`. When two gateways got one target name, the second name replaced the first one with
no report, and the writer added two targets with one name.

The target names of 7545175 already differ for gateway names that share their first 90
characters: the test now has "a".repeat(90) + "x1" and + "x2". A gateway can still have, as its
name, the name that a different gateway gets with its hash, for example `a--b` and
`a-b-<hash of a--b>`. Build now stops with `TARGET_NAME_COLLISION` for two gateways with one target
name, as it does for two hosts. Thus the writer never runs with two targets of one name.

Test: `network.test.ts`, "fails two gateways whose targets still have one name, as for two hosts",
fails before this change. `projectGateways.test.ts`, "is not the same for" the two names of 92
characters, passes before and after.
…e profile

Review feedback: the gateway rule checked `gateway.name in mcp`, which is true for a key that each
object has from its prototype. Thus a gateway named `constructor` or `toString` stopped build with
`RUNTIME_GATEWAY_SERVER_NAME_TAKEN`. The rule now uses `Object.hasOwn(mcp, gateway.name)`.

Test: `gateway.test.ts`, "adds the server of a gateway whose name is a key of every object, such as
constructor", fails before this change.
…d not on each build

Review feedback: build gave the warning for a `CUSTOM_JWT` gateway on each build, one time for each
boxed runtime.

The CLI gives a notice about a resource when a command writes that resource: `create` and
`add runtime` give the notices of the Box gateway logs and of the default log target. This change
does the same. `agentcore add gateway` gives `customJwtGatewayNotice` one time, after it writes a
`CUSTOM_JWT` gateway without `boundRuntime` to a project that has a boxed runtime that is not
`PRIVATE_VPC`. Build gives no warning for the gateway. I did not add an opt-out, because a notice
at the write is simpler and is what the CLI does for its other notices.

Tests that fail before this change: `network.test.ts`, "gives the agent no route to a CUSTOM_JWT
gateway, and no warning on each build", and `manager.boxNetwork.test.ts`, "add gateway gives one
notice for a CUSTOM_JWT gateway, and build gives none".

@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 the four commits since my approval at 743cd84 (git diff 743cd84c e095a842): ff0c48f, a043718, 869d590, e095a84.

Why COMMENT and not APPROVE: the branch conflicts with box-integration. GitHub reports it as CONFLICTING/DIRTY, and no CI has run (gh pr checks reports no checks). A trial merge against the current origin/box-integration conflicts in:

  • docs/box-local-testing.md
  • src/core/project/boxNetworkWriters.ts
  • src/core/project/templates/boxProfile.ts

Please merge or rebase onto box-integration, then let CI run. The code in the new commits looks right except for the schema point below.

New commits

  • a043718 (one target name for two gateways): looks good. hostTargets now fails with TARGET_NAME_COLLISION, and the message names both gateways and says to rename one. The test builds a real hash collision (a--b and a-b-<hash>), and projectGateways.test.ts gets a new long-name case.

  • 869d590 (constructor): looks good. Object.hasOwn(mcp, gateway.name) takes the place of in, and there is a test for constructor. I checked the other lookups by gateway name in the PR. They use Map or find, or they assign to an own key (mcp[gateway.name] = ...). GatewayNameSchema (^[0-9a-zA-Z](?:[0-9a-zA-Z-]*[0-9a-zA-Z])?$) refuses _, so __proto__ cannot be a gateway name. toString and similar names go through the same hasOwn path.

  • ff0c48f (reading a project whose build-owned target names a gateway it cannot call): the build side is good. The two new manager tests show that build removes egress-gateway-tools after the gateway gets boundRuntime, and after it is removed from agentcore.json, with the right step message. But the schema change is wider than the fix needs. See the inline comment. In short, the egress- skip applies to every gateway in every project, not only to the Box gateways that build manages.

  • e095a84 (CUSTOM_JWT notice once, at add gateway): this answers my earlier item (e). The notice is sent after the spec write, only for an unbound CUSTOM_JWT gateway when some runtime runs in a box and is not PRIVATE_VPC. A test shows that add gateway gives it once and build gives none. Non-blocking: with this change, these cases get no notice at all:

    1. A CUSTOM_JWT gateway added before the boxed runtime. add runtime gives notices for log targets and the Box gateway, but not this one.
    2. A gateway whose authorizerType is changed to CUSTOM_JWT by hand, or added by hand.
    3. Projects that already had a CUSTOM_JWT gateway before this change.

    In all three cases the boxed agent silently has no route to that gateway. Two options: also give customJwtGatewayNotice from add runtime for each unbound CUSTOM_JWT gateway when the new runtime is boxed, or state in the docs that build adds no route and says nothing. I'm fine with either one, or with doing it as a follow-up.

Earlier non-blocking items

  • (a) compatibility.ts: still open, and not touched by these commits. If node is missing, or the check fails or times out, the result is still false, so the warning tells the user to update @aws/agentcore-cdk.
  • (b) PR body Follow-ups: addressed. It now links aws/agentcore-l3-cdk-constructs#478.
  • (c) The box-on-PATH test for -/uppercase names: unchanged, so it still does not run in CI.
  • (d) Opting out of automatic tool access: still open (follow-up).
  • (e) Addressed by e095a84 (see above).
  • (f) #2877 (box-gateway-targets.json record): both are still open. A trial merge of this PR with #2877's head conflicts widely (boxNetwork/network.ts, boxNetworkWriters.ts, manager.tsx, projectSchemas/project.ts, and others), partly from base drift. When the second of the two lands, it must make sure the record covers egress-gateway-* targets, and that the egress- schema skip agrees with the record.
  • (g) Back-merge to dev: still pending.

Interaction with #2889 (not blocking, FYI)

This PR adds no uses of getBoxGatewayAgentCoreTargetSpec, boxGatewayAgentCoreHost, or agentCoreDataPlaneHost. The existing import in network.test.ts comes from the base. A trial merge with #2889's head conflicts in boxNetwork/network.test.ts, boxNetworkWriters.ts, and runtimeProfile/types.ts. Whichever PR lands second has to adapt.

Other checks

  • Tests: the new tests have no hard-coded host paths, no splitting on :, no POSIX modes, no subprocess spawns, and no network calls (the JWT discovery URL is only data, on example.com).
  • Public repo: I found no internal references or account IDs in the diff or the commit messages.

Comment thread src/projectSchemas/project.ts Resolved
Comment thread src/core/project/manager.tsx Resolved
Sai Abhishek added 5 commits November 20, 2026 17:55
…hema now splits passthrough

aws/agentcore-l3-cdk-constructs PR 478, commit a1c7d24 (for its review), keeps
`PassthroughConfigSchema` with a required `endpoint`, and gives `passthrough.gateway` the schema
`GatewayPassthroughConfigSchema`. Thus the check of 801cff5, which parsed `{ gateway }` with
`PassthroughConfigSchema`, gave false for the library that accepts the field, and build wrote no
target.

`cdkAcceptsPassthroughGateway` now parses a whole target as build writes it with
`AgentCoreGatewayTargetSchema`, which both libraries export. `@aws/agentcore-cdk` 1.1.0 from npm
gives false, and the build of PR 478 at d57f789 gives true.

Test: in `compatibility.test.ts`, "is true when the installed library accepts passthrough.gateway"
fails before this change. Its fake library now exports `AgentCoreGatewayTargetSchema`.
…arget of a Box gateway

Review feedback on ff0c48f: the schema skipped the check for each target whose name starts with
`egress-`, on each gateway of each project. Build manages `egress-` targets only on the Box gateway
of a runtime: a gateway with `boundRuntime` in a project with `"projectType": "box"`.

The skip now applies only to such a target. An `egress-` target on a gateway without
`boundRuntime`, or in a project that is not a Box project, gets the check, as each other target
does.

Tests: in `project.test.ts`, "is refused on a gateway without boundRuntime, which build does not
write" and "is refused in a project that is not a Box project" fail before this change. "is
accepted on the Box gateway of a Box project when it names ..." pins the case that build removes.
…gh.gateway

Review feedback: `cdkAcceptsPassthroughGateway` gave false for a library that refuses the field,
and also when `node` is not there, when the check takes more than 60 seconds, and when the check
fails. In each case, the warning told the user to update the library.

The check now gives `PassthroughGatewayCheck`: `{ accepts: true }`, or `{ accepts: false, reason }`
with the reason `refuses`, `not-installed`, `no-node`, `timed-out`, or `failed`, and for `failed`
the first line of the error. The one warning of build says that reason and its fix. Build still
writes no target, no server, and no pack input in each case that is not `accepts`.
`cdkAcceptsPassthroughGateway` also takes `node` and `timeoutMs`, for tests.

Tests that fail before this change: in `compatibility.test.ts`, one test for each answer, with a
fake library, a library that throws, a library that does not stop, and a `node` that is not
there; in `network.test.ts`, "gives the agent no gateway, and one warning that says why, when the
check gives ..." for each reason.
…ds a boxed runtime

Review feedback: `customJwtGatewayNotice` came only from `add gateway`, when a boxed runtime was in
the project already. A boxed runtime that `add runtime` adds after the gateway got no notice.

`add runtime` now gives `customJwtGatewayNotice` after it writes agentcore.json, for each
`CUSTOM_JWT` gateway without `boundRuntime`, when the new runtime runs in a box and is not
`PRIVATE_VPC`. `docs/box-local-testing.md` says so.

Test: in `manager.box.test.ts`, "add runtime gives the notice of each CUSTOM_JWT gateway without
boundRuntime, as the new runtime is boxed" fails before this change.
@SaiAbhishek98

Copy link
Copy Markdown
Author

This comment lists each item of the review in the shared doc and of the second review by @leo237, with the commit that changes it. The head is 1721f474.

Items of the review doc

  1. remove gateway after a build: no new change. 743cd84c has the test "lets remove gateway remove the gateway after a build, with the target build wrote for it" in manager.boxNetwork.test.ts, and it passes.
  2. A build-owned target that names a gateway with boundRuntime, or a gateway that is gone: ff0c48f7. The schema does not refuse such a target, and the next build removes it. 2f398641 narrows this to the Box gateway of a Box project (item 2 of the second review). Tests: "reads the project and removes the target after a build when the gateway gets boundRuntime" and "... when the gateway is gone from agentcore.json".
  3. Two gateways with one target name: a0437182. The hash suffix of 7545175a already gives different names to "a".repeat(90) + "x1" and + "x2", and the test has them now. Build now stops with TARGET_NAME_COLLISION when two gateways still get one target name, as for hosts.
  4. A gateway named constructor: 869d590d. The rule uses Object.hasOwn.
  5. The CUSTOM_JWT warning on each build: e095a842. I chose a notice when a command writes the gateway, because create and add runtime give their other notices the same way. add gateway gives it, and build gives no warning. 1721f474 also gives it from add runtime (item 4 of the second review).
  6. The record of aws/agentcore-cli PR 2877: not pushed, because PR 2877 has not merged. I merged PR 2877 (fork/sa/review-fixes-host-map, 33ca203) into this branch in a local branch only. The change is ready there: hostTargets adds projectGateways[].target to managedTargets, so the record lists each one, and a later build removes it when the gateway gets CUSTOM_JWT. A gateway target with the name of a target that build does not own stops build. remove gateway reads the record. The new tests pass on the local merge. I will push it after PR 2877 merges.

Items of the second review

  1. The conflict with box-integration: 3d739f27 merges box-integration (PR 2885 and PR 2883) and keeps both sides. renderAgentCorePack takes the runtime for OTEL and the gateways of the project.
  2. The skip for egress- targets: 2f398641.
  3. The reason of the library check: 2f55c313.
  4. The notice at add runtime: 1721f474.

A change for the L3 review: aws/agentcore-l3-cdk-constructs PR 478 now gives passthrough.gateway its own schema. Thus 52f88f16 makes the library check parse a whole target with AgentCoreGatewayTargetSchema. @aws/agentcore-cdk 1.1.0 from npm gives refuses, and the build of PR 478 at d57f789 gives accepts. agentcore build with that build writes and synthesizes egress-gateway-toolsgw.

Tests: each code change has a test that fails before it. bun test, with box 0.1.11-preview.10 on PATH: 6088 pass, 6 skip, 1 fail. The failure is "the box on PATH > resolves a profile into the rules the tests fake". It also fails on box-integration with this box, and CI skips it. typecheck, lint:check, format:check, secrets:check, and build pass.

@SaiAbhishek98
SaiAbhishek98 requested a review from leo237 November 21, 2026 02:09

@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 1721f47 (since e095a84: 52f88f1, merge 3d739f2, 2f39864, 2f55c31, 1721f47).

Merge conflict (was blocking): fixed. No conflict markers left. I checked 3d739f2 with remerge-diff. docs/box-local-testing.md, boxNetworkWriters.ts and templates/boxProfile.ts keep both sides. renderAgentCorePack(spec, runtime, gateways) keeps the #2885 OTEL inputs and env, then appends the gateway inputs and env. The one non-test caller passes entry and network?.projectGateways, and the test callers were updated. No base change is reverted. GitHub now reports the PR as mergeable.

Addressed

  • Schema skip for egress- targets (project.ts): the skip now needs a Box project, a gateway with boundRuntime, and the egress- prefix. New tests check that the target is refused on a gateway without boundRuntime and in a project that is not a Box project. They also check that it is still accepted on the Box gateway of a Box project. Resolved.
  • (a) compatibility.ts: PassthroughGatewayCheck now returns a reason: refuses, not-installed, no-node, timed-out, or failed with the error. Each reason has its own warning and fix. It is still fail-safe: anything other than accepts writes no target. Each answer has a test. 52f88f1 also probes with a whole target through AgentCoreGatewayTargetSchema, which matches the new split passthrough schema in L3 #478. Resolved.
  • CUSTOM_JWT notice: add runtime now also gives the notice for a boxed runtime that is not PRIVATE_VPC, for each unbound CUSTOM_JWT gateway. There is a test, and the docs are updated. Mostly resolved. Hand edits and existing projects still get no notice. That is fine as a follow-up (for example, a build-time info line).

Still open (non-blocking, as before)

  • (c) The test for box on PATH still never runs in CI.
  • (d) There is still no opt-out for tool access, and the opt-out message is still missing.
  • (f) The #2877 record must cover the egress-gateway-* targets.
  • (g) Back-merge to dev.
  • Conflicts with open PRs (FYI): a trial merge with #2889 conflicts in boxNetwork/network.test.ts, boxNetworkWriters.ts and manager.test.ts. A trial merge with #2877 conflicts in docs/box-local-testing.md, boxNetwork/network.ts, network.test.ts, boxNetworkSource.ts, boxNetworkWriters.ts and its test, among others. Whichever PR lands second needs a careful resolution.
  • L3 #478 is still open and not merged. Until it ships, build writes no target and gives the refuses warning. That is the intended fail-safe.

New nits (non-blocking)

  • projectGateways.ts: the doc comment of projectGatewaysOf still says "With targets false". The parameter is now check. The doc of customJwtGatewayNotice mentions only add gateway (see inline).
  • The timed-out message hard-codes "60 seconds", but timeoutMs can be overridden. That is only for tests, so this is cosmetic.
  • add runtime has no negative test showing that a PRIVATE_VPC or non-box runtime gets no CUSTOM_JWT notice.
  • In the check script, process.stdout.write followed by process.exit(0) could cut off output on platforms where pipe writes are asynchronous. The output is short and falls through to failed with no detail, so this is low risk.

CI: at posting time, CodeQL, Analyze, verify/Windows, verify/macOS and CodeBuild e2e pass. verify/Linux is still pending. Approving on the code. Please merge only after all checks pass.

…f projectGateways.ts (comment of Leo on projectGateways.ts line 53)
@SaiAbhishek98

Copy link
Copy Markdown
Author

The head is now 33c29a1c. It changes only the two comments of projectGateways.ts that the last thread names.

@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 1721f47..33c29a1. Approving again.

The new commit changes only comments in projectGateways.ts (+4/-3). The code is unchanged. Both fixes are accurate:

  • The projectGatewaysOf doc now names the check parameter. "When check does not accept passthrough.gateway" matches the !check.accepts branch and uncheckedBecause.
  • "add gateway or add runtime" matches the two customJwtGatewayNotice call sites in manager.tsx: the gateway and runtime branches of the add flow.

That resolves my nit on line 53.

CI is green: verify Linux/macOS/Windows, CodeQL, CodeBuild e2e. The PR is mergeable; the blocked state is only branch protection.

Still open from earlier, none blocking this PR:

  • The box-on-PATH test never runs in CI.
  • A tool-access opt-out or message.
  • The #2877 record must cover egress-gateway-*.
  • The back-merge to dev.
  • Nits from my last review: the hard-coded "60 seconds" in the timeout message; no test that a PRIVATE_VPC or non-box runtime gets no CUSTOM_JWT notice; process.exit right after writing the check answer.
  • FYI: this conflicts with #2889 and #2877.
  • L3 #478 is still open and not merged.

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