From c6bb00b786718ff8bb405eec9921b8c3ef38eb5b Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 11:20:26 -0800 Subject: [PATCH 01/31] fix(box): Keep a host reachable when two path tests of one permit hold on one path The host map decides each host on sample requests. A sample path comes from one path test at a time. A permit with two path tests, such as `path like "/v1/*"` and `path like "*/items"`, got no sample that passes both. The host was then unreachable, with no failure, and build gave it no gateway target, but Box allows GET /v1/items. When no sample request is allowed, the host map now searches for a path that the path tests of a permit allow together and that no forbid surely denies (pathSolver.ts). The search is exact for `like`, `==`, and `!=`. When the search is too large (more than 4096 states), the host stays reachable, the permit goes in `uncheckedBy` and `enforcedByBox`, and build gives a warning that names the rule. Tests: hostMap.test.ts "finds a host reachable when two path patterns of one permit hold on one path", "finds a path of a permit that a forbid of one path leaves open", "finds no path when the path patterns of a permit never hold together", "keeps a host reachable, and names the permit, when its path tests are too many to check"; network.test.ts "names a permit whose path tests build cannot check together, and keeps its host". The random-rule property test still passes. Mutations: no search, a search that ignores the forbids, and no state limit each make a test fail. --- src/core/project/boxNetwork/hostMap.test.ts | 43 ++++++ src/core/project/boxNetwork/hostMap.ts | 85 ++++++++++-- src/core/project/boxNetwork/network.test.ts | 12 ++ src/core/project/boxNetwork/network.ts | 10 ++ src/core/project/boxNetwork/pathSolver.ts | 142 ++++++++++++++++++++ 5 files changed, 284 insertions(+), 8 deletions(-) create mode 100644 src/core/project/boxNetwork/pathSolver.ts diff --git a/src/core/project/boxNetwork/hostMap.test.ts b/src/core/project/boxNetwork/hostMap.test.ts index b8b54381f..e851971c4 100644 --- a/src/core/project/boxNetwork/hostMap.test.ts +++ b/src/core/project/boxNetwork/hostMap.test.ts @@ -63,6 +63,49 @@ describe("the policy decision on each host", () => { expect(host(result, "y.example.com")?.reachable).toBe(true); }); + test("finds a host reachable when two path patterns of one permit hold on one path", () => { + const both = 'context.input.path like "/v1/*" && context.input.path like "*/items"'; + const result = map(reach("items", "x.example.com", both)); + expect(host(result, "x.example.com")).toMatchObject({ + reachable: true, + enforcedByBox: ["items"], + uncheckedBy: [], + }); + expect(host(result, "x.example.com")?.decision.allowed.map((s) => s.path)).toContain( + "/v1/items", + ); + }); + + test("finds a path of a permit that a forbid of one path leaves open", () => { + const both = 'context.input.path like "/v1/*" && context.input.path like "*/items"'; + const result = map( + reach("items", "x.example.com", both) + + forbid("no_list", on("x.example.com", 'context.input.path == "/v1/items"')), + ); + const decided = host(result, "x.example.com"); + expect(decided?.reachable).toBe(true); + expect(decided?.decision.allowed.map((s) => s.path)).not.toContain("/v1/items"); + }); + + test("finds no path when the path patterns of a permit never hold together", () => { + const never = 'context.input.path like "/v1/*" && context.input.path like "/v2/*"'; + expect(host(map(reach("never", "x.example.com", never)), "x.example.com")).toMatchObject({ + reachable: false, + uncheckedBy: [], + }); + }); + + test("keeps a host reachable, and names the permit, when its path tests are too many to check", () => { + const many = [..."abcdefghijklm"].map((c) => `context.input.path like "*${c}*"`).join(" && "); + const result = map(reach("many", "x.example.com", many)); + expect(result.failures).toEqual([]); + expect(host(result, "x.example.com")).toMatchObject({ + reachable: true, + uncheckedBy: ["many"], + enforcedByBox: ["many"], + }); + }); + test("names the limited permits and the forbids Box enforces on its own, in policy order", () => { const result = map( forbid("no_admin", on("x.example.com", 'context.input.path like "/admin/*"')) + diff --git a/src/core/project/boxNetwork/hostMap.ts b/src/core/project/boxNetwork/hostMap.ts index 62a9cbf22..bf8eaf26b 100644 --- a/src/core/project/boxNetwork/hostMap.ts +++ b/src/core/project/boxNetwork/hostMap.ts @@ -24,6 +24,7 @@ import { type BoxEgressSecret, type Destination, } from "./egress"; +import { findPath, pathTest, type PathTest } from "./pathSolver"; import { BOX_METADATA_RULE_IDS } from "./places"; import { ROUTABLE_METHODS, @@ -85,7 +86,12 @@ export interface MappedHost { readonly forbiddenBy: readonly string[]; /** The rules that limit what Box allows to the host, which Box enforces and a gateway does not. */ readonly enforcedByBox: readonly string[]; - /** Whether Box allows at least one sample request to the host. */ + /** + * The permits whose path tests are too many for build to check together. They keep an otherwise + * unreachable host reachable. + */ + readonly uncheckedBy: readonly string[]; + /** Whether Box allows at least one sample request to the host, or a permit of `uncheckedBy` can. */ readonly reachable: boolean; } @@ -598,24 +604,39 @@ function decide(node: Node, policy: Policy): MappedHost { for (const c of policy.connectForbids) { if (c !== connectForbid && possible(c.clause, node)) enforced.set(c.ruleId, c.order); } - for (const sample of samples) { + const consider = (sample: SampleRequest) => { const permits = policy.requestPermits.filter((c) => possible(c.clause, node, sample)); - if (permits.length === 0) continue; + if (permits.length === 0) return; if (connectForbid) { forbiddenBy.set(connectForbid.ruleId, connectForbid.order); - continue; + return; } - if (!connectPermit) continue; + if (!connectPermit) return; const forbid = policy.requestForbids.find((c) => definite(c.clause, node, sample)); if (forbid) { forbiddenBy.set(forbid.ruleId, forbid.order); - continue; + return; } allowed.push({ ...sample, ruleId: permits[0]!.ruleId }); for (const p of permits) if (limits(p.clause)) enforced.set(p.ruleId, p.order); for (const f of policy.requestForbids) { if (possible(f.clause, node, sample)) enforced.set(f.ruleId, f.order); } + }; + for (const sample of samples) consider(sample); + let checked = samples.length; + const unchecked = new Map(); + if (allowed.length === 0 && !connectForbid && connectPermit) { + const solved = solvedSamples(node, policy); + checked += solved.samples.length; + for (const sample of solved.samples) consider(sample); + if (allowed.length === 0) { + for (const c of solved.undecided) unchecked.set(c.ruleId, c.order); + for (const [ruleId, order] of unchecked) enforced.set(ruleId, order); + for (const f of policy.requestForbids) { + if (possible(offPath(f.clause), node)) enforced.set(f.ruleId, f.order); + } + } } for (const [ruleId, order] of forbiddenBy) enforced.set(ruleId, order); for (const ruleId of BOX_METADATA_RULE_IDS) enforced.delete(ruleId); @@ -627,11 +648,59 @@ function decide(node: Node, policy: Policy): MappedHost { authority: hostKey(node.host, node.port), ...(node.entry && { entry: node.entry }), namedBy: node.namedBy, - decision: { samples: samples.length, allowed }, + decision: { samples: checked, allowed }, forbiddenBy: inOrder(forbiddenBy), enforcedByBox: inOrder(enforced), - reachable: allowed.length > 0, + uncheckedBy: inOrder(unchecked), + reachable: allowed.length > 0 || unchecked.size > 0, + }; +} + +/** The clause without its path tests. */ +function offPath(clause: Clause): Clause { + return { ...clause, fields: clause.fields.filter((atom) => atom.field !== "path") }; +} + +/** + * A sample request for each routable method on which a permit allows a path that no forbid + * surely denies, found from the path tests of the rules, and each permit clause whose path tests + * are too many to search. + */ +function solvedSamples( + node: Node, + policy: Policy, +): { samples: SampleRequest[]; undecided: RuleClause[] } { + const samples: SampleRequest[] = []; + const undecided: RuleClause[] = []; + const tests = (clause: Clause): PathTest[] | undefined => { + const found: PathTest[] = []; + for (const atom of clause.fields) { + if (atom.field !== "path") continue; + const test = pathTest(atom); + if (test === false) return undefined; + if (test !== true) found.push(test); + } + return found; }; + for (const method of ROUTABLE_METHODS) { + const on = { method, path: "/" }; + const excluded = policy.requestForbids.flatMap(({ clause }) => { + if (!definite(offPath(clause), node, on)) return []; + const group = tests(clause); + return group === undefined ? [] : [group]; + }); + for (const permit of policy.requestPermits) { + if (!possible(offPath(permit.clause), node, on)) continue; + const required = tests(permit.clause); + if (required === undefined) continue; + const found = findPath(required, excluded, SENTINEL_SEGMENT); + if (found.kind === "undecided" && !undecided.includes(permit)) undecided.push(permit); + if (found.kind !== "path") continue; + samples.push({ method, path: found.path }); + break; + } + } + return { samples, undecided }; } /** Whether a permit clause allows only some requests to its host: by method, path, or more. */ diff --git a/src/core/project/boxNetwork/network.test.ts b/src/core/project/boxNetwork/network.test.ts index 52d1f16d3..c885ad9b0 100644 --- a/src/core/project/boxNetwork/network.test.ts +++ b/src/core/project/boxNetwork/network.test.ts @@ -1010,6 +1010,18 @@ describe("warnings", () => { ]); }); + test("names a permit whose path tests build cannot check together, and keeps its host", () => { + const many = [..."abcdefghijklm"].map((c) => `context.input.path like "*${c}*"`).join(" && "); + const r = model(reach("many", "x.example.com", many)); + expect(r.failures()).toEqual([]); + expect(r.targets()).toEqual(["x.example.com -> egress-x-example-com"]); + expect(r.network.warnings[0]).toBe( + '.box/agent/local/policy.dw:2:1: The rule "many" has more path conditions than build can ' + + "check together, so build cannot tell whether your policy allows a request to " + + "x.example.com. Build gives the host a gateway target, and Box still applies the rule.", + ); + }); + test("names an entry whose host gets no target, and the forbids that deny it", () => { expect( model(forbid("no_github", on("api.github.com")), { github: GITHUB }).network.warnings, diff --git a/src/core/project/boxNetwork/network.ts b/src/core/project/boxNetwork/network.ts index 534d8ba54..8027f4524 100644 --- a/src/core/project/boxNetwork/network.ts +++ b/src/core/project/boxNetwork/network.ts @@ -229,6 +229,16 @@ export function buildBoxNetwork( }), grantedActions: project.grantedActions, warnings: [ + ...map.hosts.flatMap(({ authority, uncheckedBy }) => + uncheckedBy.map((ruleId) => { + const { place, subject } = describeRule(parsed, ruleId); + return ( + `${place}: ${subject} has more path conditions than build can check together, so ` + + `build cannot tell whether your policy allows a request to ${authority}. Build gives ` + + "the host a gateway target, and Box still applies the rule." + ); + }), + ), ...hostWarnings(targets.hosts), ...map.websocketOnly.map(({ ruleId, span }) => { const { place, subject } = describeRule(parsed, ruleId, span); diff --git a/src/core/project/boxNetwork/pathSolver.ts b/src/core/project/boxNetwork/pathSolver.ts new file mode 100644 index 000000000..257f0c83e --- /dev/null +++ b/src/core/project/boxNetwork/pathSolver.ts @@ -0,0 +1,142 @@ +/** + * Finds a request path that a set of path tests allow together, as Box compares a path: a `like` + * pattern matches the whole path, and its `*` matches any run of characters. + */ +import type { FieldAtom } from "./conditions"; +import type { LikePattern } from "./dogwood"; + +/** A path test: the path matches `pattern`, or, when `matches` is false, does not match it. */ +export interface PathTest { + readonly pattern: LikePattern; + readonly matches: boolean; +} + +/** A path, or no path; `undecided` when the search stops at {@link MAX_PATH_STATES}. */ +export type PathSearch = + | { readonly kind: "path"; readonly path: string } + | { readonly kind: "none" } + | { readonly kind: "undecided" }; + +/** The most search states before the search stops undecided. */ +export const MAX_PATH_STATES = 4096; + +/** Each request path starts with `/`. */ +const ROOTED: PathTest = { + pattern: { parts: [{ kind: "literal", text: "/" }, { kind: "wildcard" }] }, + matches: true, +}; + +/** The test of a path atom, or the atom's value on every path when it does not read the path. */ +export function pathTest(atom: FieldAtom): PathTest | boolean { + const comparison = atom.comparison; + if (comparison.op === "present") return !atom.negated; + if (comparison.op === "like") return { pattern: comparison.pattern, matches: !atom.negated }; + if (typeof comparison.value !== "string") return atom.negated; + const pattern: LikePattern = { parts: [{ kind: "literal", text: comparison.value }] }; + if (comparison.op === "==") return { pattern, matches: !atom.negated }; + if (comparison.op === "!=") return { pattern, matches: atom.negated }; + return atom.negated; +} + +/** + * The shortest path that passes each test of `required` and fails at least one test of each group + * of `excluded`. A character that no pattern names is written as `filler`. + */ +export function findPath( + required: readonly PathTest[], + excluded: readonly (readonly PathTest[])[], + filler: string, +): PathSearch { + if (excluded.some((group) => group.length === 0)) return { kind: "none" }; + const patterns: LikePattern[] = []; + const indexOf = (pattern: LikePattern) => { + const at = patterns.indexOf(pattern); + return at === -1 ? patterns.push(pattern) - 1 : at; + }; + const wanted = [ROOTED, ...required].map((test) => ({ ...test, at: indexOf(test.pattern) })); + const groups = excluded.map((group) => + group.map((test) => ({ ...test, at: indexOf(test.pattern) })), + ); + const machines = patterns.map(machineOf); + const literals = new Set(patterns.flatMap((p) => p.parts.flatMap(literalChars))); + const alphabet = [...literals, freeChar(literals, filler)]; + + const start = machines.map((machine) => machine.closure([0])); + const holds = (state: readonly number[][], test: { at: number; matches: boolean }) => + machines[test.at]!.accepts(state[test.at]!) === test.matches; + const accepted = (state: readonly number[][]) => + wanted.every((test) => holds(state, test)) && + groups.every((group) => !group.every((test) => holds(state, test))); + const dead = (state: readonly number[][]) => + wanted.some((test) => test.matches && state[test.at]!.length === 0); + + const key = (state: readonly number[][]) => state.map((set) => set.join(",")).join("|"); + const from = new Map(); + from.set(key(start), {}); + const queue: number[][][] = [start]; + for (let head = 0; head < queue.length; head++) { + const state = queue[head]!; + if (accepted(state)) return { kind: "path", path: pathTo(from, key(state)) }; + for (const char of alphabet) { + const next = state.map((set, i) => machines[i]!.step(set, char)); + const nextKey = key(next); + if (from.has(nextKey) || dead(next)) continue; + if (from.size >= MAX_PATH_STATES) return { kind: "undecided" }; + from.set(nextKey, { parent: key(state), char }); + queue.push(next); + } + } + return { kind: "none" }; +} + +/** A pattern as a machine whose state is the set of places in the pattern a prefix reaches. */ +function machineOf(pattern: LikePattern) { + const items = pattern.parts.flatMap((part) => + part.kind === "wildcard" ? [undefined] : [...part.text], + ); + const closure = (places: readonly number[]) => { + const reached = new Set(); + for (let place of places) { + reached.add(place); + while (place < items.length && items[place] === undefined) reached.add(++place); + } + return [...reached].sort((a, b) => a - b); + }; + return { + closure, + step: (places: readonly number[], char: string) => + closure( + places.flatMap((place) => { + if (place >= items.length) return []; + const item = items[place]; + if (item === undefined) return [place]; + return item === char ? [place + 1] : []; + }), + ), + accepts: (places: readonly number[]) => places.includes(items.length), + }; +} + +function literalChars(part: LikePattern["parts"][number]): string[] { + return part.kind === "literal" ? [...part.text] : []; +} + +/** `filler`, or another character that no pattern names. */ +function freeChar(literals: ReadonlySet, filler: string): string { + if (!literals.has(filler)) return filler; + for (let code = 0xe000; ; code++) { + const char = String.fromCharCode(code); + if (!literals.has(char)) return char; + } +} + +function pathTo( + from: ReadonlyMap, + end: string, +): string { + const chars: string[] = []; + for (let at = from.get(end); at?.parent !== undefined; at = from.get(at.parent)) { + chars.push(at.char!); + } + return chars.reverse().join(""); +} From acd1419694598c44d274ffb821321962bb4985d0 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 11:23:27 -0800 Subject: [PATCH 02/31] fix(box): Accept a field that an action test keeps from the action Box reads a rule as Cedar types it: it does not read the right operand of `||` after an action test that holds, the right operand of `&&` after one that does not, the other branch of `if`, or a later `when` after an action test that is false. So box 0.1.11-preview.10 accepts `permit (principal, action == Box::Action::"net:connect", resource) when { context.input.host == "a" && (action == Box::Action::"net:connect" || context.input.method == "GET") }`. The host map read every operand, refused the rule with UNKNOWN_ATTRIBUTE, and build stopped. checkAttributes now skips each operand that an action test keeps from the action (actionValue), and clausesFor stops at a condition that an action test makes false. A field that no action test keeps from the action is still refused. The review's own example puts http:request and net:connect in one rule. Box 0.1.11-preview.10 refuses that rule for another cause (it reads context.input under two action families), so the tests use the forms that box accepts. Tests: hostMap.test.ts "an attribute that an action test keeps from the action, as Box reads it" (6 tests: `||`, `&&` with `!=`, `if`, a request rule that reads ip4, a later `when`, and the refusal of an unguarded field). Mutations: no `&&`/`||` stop, both `if` branches read, and every condition read each make a test fail. --- src/core/project/boxNetwork/conditions.ts | 66 ++++++++++++++++++++- src/core/project/boxNetwork/hostMap.test.ts | 44 ++++++++++++++ 2 files changed, 108 insertions(+), 2 deletions(-) diff --git a/src/core/project/boxNetwork/conditions.ts b/src/core/project/boxNetwork/conditions.ts index e21245ce0..d59d534ab 100644 --- a/src/core/project/boxNetwork/conditions.ts +++ b/src/core/project/boxNetwork/conditions.ts @@ -123,8 +123,13 @@ export function clausesFor(statement: Statement, action: NetworkAction): ClauseS const parts: Formula[] = [ scopeFormula(statement.principal, "principal", SELF), scopeFormula(statement.resource, "resource", UNUSED_RESOURCE), - ...statement.conditions.map((condition) => conditionFormula(condition, action)), ]; + for (const condition of statement.conditions) { + parts.push(conditionFormula(condition, action)); + // Box does not read a condition after one that an action test makes false. + const value = condition.body.kind === "cedar" && actionValue(condition.body.expr, action); + if (value === (condition.polarity !== "when")) break; + } const clauses: Clause[] = []; const dead: DeadCause[] = []; for (const atoms of disjunctiveNormalForm({ kind: "and", items: parts }, false)) { @@ -246,16 +251,73 @@ function attributePath(expr: Expr): string[] | undefined { return undefined; } -/** Refuses an attribute the action's context does not declare, as Box refuses it at load. */ +/** + * Refuses an attribute the action's context does not declare, as Box refuses it at load. As Box + * reads a rule, an operand that an action test keeps from the action is not read: the right of + * `||` after a test that holds, the right of `&&` after one that does not, and the other branch of + * `if`. + */ function checkAttributes(expr: Expr, action: NetworkAction): void { const path = attributePath(expr); if (path && path.length > 1) { checkPath(path, action, expr.text); return; } + if (expr.kind === "and" || expr.kind === "or") { + for (const item of expr.items) { + checkAttributes(item, action); + if (actionValue(item, action) === (expr.kind === "or")) return; + } + return; + } + if (expr.kind === "if") { + checkAttributes(expr.test, action); + const test = actionValue(expr.test, action); + if (test !== false) checkAttributes(expr.then, action); + if (test !== true) checkAttributes(expr.otherwise, action); + return; + } for (const child of children(expr)) checkAttributes(child, action); } +/** The value of `expr` on `action` when only action tests and constants decide it. */ +function actionValue(expr: Expr, action: NetworkAction): boolean | undefined { + switch (expr.kind) { + case "literal": + return typeof expr.value === "boolean" ? expr.value : undefined; + case "not": { + const value = actionValue(expr.operand, action); + return value === undefined ? undefined : !value; + } + case "and": + case "or": { + const values = expr.items.map((item) => actionValue(item, action)); + const decides = expr.kind === "or"; + if (values.includes(decides)) return decides; + return values.every((value) => value === !decides) ? !decides : undefined; + } + case "binary": { + if (expr.op !== "==" && expr.op !== "!=" && expr.op !== "in") return undefined; + const variable = attributePath(expr.left); + if (variable?.length !== 1 || variable[0] !== "action") return undefined; + const right = expr.right; + const entities = + right.kind === "entity" + ? [right.entity] + : expr.op === "in" && + right.kind === "set" && + right.items.every((i) => i.kind === "entity") + ? right.items.map((i) => (i as Extract).entity) + : undefined; + if (!entities) return undefined; + const matches = entities.some((e) => sameEntity(e, { type: ["Box", "Action"], id: action })); + return expr.op === "!=" ? !matches : matches; + } + default: + return undefined; + } +} + function checkPath(path: string[], action: NetworkAction, text: string): void { const [root, group, field] = path; if (root === "principal" || root === "resource" || root === "action") { diff --git a/src/core/project/boxNetwork/hostMap.test.ts b/src/core/project/boxNetwork/hostMap.test.ts index e851971c4..defec9249 100644 --- a/src/core/project/boxNetwork/hostMap.test.ts +++ b/src/core/project/boxNetwork/hostMap.test.ts @@ -119,6 +119,50 @@ describe("the policy decision on each host", () => { }); }); + describe("an attribute that an action test keeps from the action, as Box reads it", () => { + const codes = (result: ReturnType) => + result.failures.map(({ code, ruleId }) => [code, ruleId]); + const get = permit("get", on("a.example.com", 'context.input.method == "GET"')); + + // The guard of `&&` is false on net:connect, so that rule never allows a connection. + test.each([ + ["||", `(${NC} || context.input.method == "GET")`, true], + [ + "&& with !=", + `(action != Box::Action::"net:connect" && context.input.method == "GET")`, + false, + ], + ["if", `(if ${NC} then true else context.input.method == "GET")`, true], + ])("accepts a connection rule that reads a request field behind %s", (_, guard, reachable) => { + const result = map(connect("guarded", on("a.example.com", guard)) + get); + expect(codes(result)).toEqual([]); + expect(host(result, "a.example.com")?.reachable).toBe(reachable); + }); + + test("accepts a request rule that reads a connection field behind an action test", () => { + const guarded = permit( + "guarded", + on("a.example.com", `(${HR} || context.input.ip4 == "1.2.3.4")`), + ); + expect(codes(map(connect("c", on("a.example.com")) + guarded))).toEqual([]); + }); + + test("accepts a later condition that an earlier action test keeps from the action", () => { + const later = rule( + "later", + `permit (principal, ${NC}, resource) when { ${HR} } when { context.input.method == "GET" };`, + ); + expect(codes(map(later + reach("get", "a.example.com")))).toEqual([]); + }); + + test("refuses the field when no action test keeps it from the action", () => { + const result = map( + connect("bare", on("a.example.com", 'context.input.method == "GET"')) + get, + ); + expect(codes(result)).toEqual([["UNKNOWN_ATTRIBUTE", "bare"]]); + }); + }); + test("gives a host only to a permit: a forbid with a fixed host makes no node", () => { expect(map(forbid("no_x", on("x.example.com"))).hosts).toEqual([]); }); From daeec2adf518a30b65130c9fd284980e31fcb7e4 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 11:25:41 -0800 Subject: [PATCH 03/31] fix(box): Name a connection permit that limits the address among the rules Box applies A host's enforcedByBox named the request permits that limit a host and the forbids, but no connection permit. A permit that allows connections to a host only at some addresses (`context.input.ip4 like "10.*"`) is a limit that Box applies and the gateway does not. Build gave no warning for it. The host map now names each connection permit of a reachable host whose every clause there limits the address or has a condition build cannot read. A connection permit with a clause that allows any address is not named. The review's example used `ip(context.input.ip4).isInRange(...)`. Box 0.1.11-preview.10 refuses that form (ip() takes only a literal, and ip4 is a string), so the test uses the form that Box writes itself. Tests: hostMap.test.ts "names a connection permit that limits the address, and not one that allows any". Mutations: no connection permits named, and every connection permit named, each make a test fail. --- src/core/project/boxNetwork/hostMap.test.ts | 12 ++++++++++++ src/core/project/boxNetwork/hostMap.ts | 13 +++++++++++++ 2 files changed, 25 insertions(+) diff --git a/src/core/project/boxNetwork/hostMap.test.ts b/src/core/project/boxNetwork/hostMap.test.ts index defec9249..e45699118 100644 --- a/src/core/project/boxNetwork/hostMap.test.ts +++ b/src/core/project/boxNetwork/hostMap.test.ts @@ -119,6 +119,18 @@ describe("the policy decision on each host", () => { }); }); + test("names a connection permit that limits the address, and not one that allows any", () => { + const lan = 'context.input has ip4 && context.input.ip4 like "10.*"'; + const result = map( + connect("lan", on("a.example.com", lan)) + + permit("get_a", on("a.example.com")) + + connect("any", on("b.example.com", `(${NC} || ${lan})`)) + + permit("get_b", on("b.example.com")), + ); + expect(host(result, "a.example.com")?.enforcedByBox).toEqual(["lan"]); + expect(host(result, "b.example.com")?.enforcedByBox).toEqual([]); + }); + describe("an attribute that an action test keeps from the action, as Box reads it", () => { const codes = (result: ReturnType) => result.failures.map(({ code, ruleId }) => [code, ruleId]); diff --git a/src/core/project/boxNetwork/hostMap.ts b/src/core/project/boxNetwork/hostMap.ts index bf8eaf26b..6e55c00e3 100644 --- a/src/core/project/boxNetwork/hostMap.ts +++ b/src/core/project/boxNetwork/hostMap.ts @@ -638,6 +638,11 @@ function decide(node: Node, policy: Policy): MappedHost { } } } + if (allowed.length > 0 || unchecked.size > 0) { + const connects = policy.connectPermits.filter((c) => possible(c.clause, node)); + const open = new Set(connects.filter((c) => !limitsConnection(c.clause)).map((c) => c.ruleId)); + for (const c of connects) if (!open.has(c.ruleId)) enforced.set(c.ruleId, c.order); + } for (const [ruleId, order] of forbiddenBy) enforced.set(ruleId, order); for (const ruleId of BOX_METADATA_RULE_IDS) enforced.delete(ruleId); const inOrder = (rules: Map) => @@ -703,6 +708,14 @@ function solvedSamples( return { samples, undecided }; } +/** Whether a connection permit clause allows only some connections to its host: by address, or more. */ +function limitsConnection(clause: Clause): boolean { + return ( + clause.opaque.length > 0 || + clause.fields.some((atom) => atom.field === "ip4" || atom.field === "ip6") + ); +} + /** Whether a permit clause allows only some requests to its host: by method, path, or more. */ function limits(clause: Clause): boolean { return ( From ec299b773424251df310a904cc1e9e1ce898cff5 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 11:26:58 -0800 Subject: [PATCH 04/31] fix(box): Refuse a rule that names a port out of the range 1 to 65535 The host map took the port that a rule fixes (`context.input.port == 65536`, `== 0`, or `== -1`) with no check. Box accepts such a rule, which never holds, but build made a host of `host:65536` and wrote a gateway target for an endpoint that is not a URL. The host map now refuses each rule that fixes a port that is not an integer from 1 to 65535, with the new failure code INVALID_PORT, at the rule's line. A destination of an [egress] entry already had this check (parseDestination). Tests: network.test.ts "fails each rule that names port %d, which is not a port" (65536, 0, and -1, for a connection and a request rule). Mutations: an upper bound of 65536 and a lower bound of 0 each make a test fail. --- src/core/project/boxNetwork/hostMap.ts | 9 +++++++++ src/core/project/boxNetwork/network.test.ts | 17 +++++++++++++++++ src/core/project/boxNetwork/types.ts | 1 + 3 files changed, 27 insertions(+) diff --git a/src/core/project/boxNetwork/hostMap.ts b/src/core/project/boxNetwork/hostMap.ts index 6e55c00e3..81a937336 100644 --- a/src/core/project/boxNetwork/hostMap.ts +++ b/src/core/project/boxNetwork/hostMap.ts @@ -361,6 +361,15 @@ class HostMapBuilder { let port: number; if (typeof pinned === "number") { if (!atoms("port").every((a) => holds(a, pinned)) || pinned === 80) continue; + if (!Number.isInteger(pinned) || pinned < 1 || pinned > 65535) { + this.ruleFailure( + rule, + "INVALID_PORT", + `allows ${host} on port ${pinned}, which is not a port. Name a port from 1 to ` + + "65535, such as context.input.port == 443.", + ); + continue; + } port = pinned; } else if (atoms("port").every((a) => holds(a, 443))) { port = 443; diff --git a/src/core/project/boxNetwork/network.test.ts b/src/core/project/boxNetwork/network.test.ts index c885ad9b0..21703d10c 100644 --- a/src/core/project/boxNetwork/network.test.ts +++ b/src/core/project/boxNetwork/network.test.ts @@ -558,6 +558,23 @@ describe("hosts the model cannot carry", () => { ]); }); + test.each([65536, 0, -1])("fails each rule that names port %d, which is not a port", (port) => { + const pinned = `context.input.port == ${port}`; + const r = model( + connect("odd_connect", on("api.example.com", pinned)) + + permit("odd", on("api.example.com", pinned)), + ); + expect(r.lines()).toEqual( + [".box/agent/local/policy.dw:1:1", ".box/agent/local/policy.dw:2:1"].map( + (place, i) => + `${place} The rule "${["odd_connect", "odd"][i]}" allows api.example.com on port ` + + `${port}, which is not a port. Name a port from 1 to 65535, such as ` + + "context.input.port == 443.", + ), + ); + expect(r.targets()).toEqual([]); + }); + test("fails a host reachable only over plain HTTP", () => { expect( model( diff --git a/src/core/project/boxNetwork/types.ts b/src/core/project/boxNetwork/types.ts index f9d8ad25f..f00e9c1df 100644 --- a/src/core/project/boxNetwork/types.ts +++ b/src/core/project/boxNetwork/types.ts @@ -25,6 +25,7 @@ export const FAILURE_CODES = [ "WILDCARD_HOST", "UNCONSTRAINED_HOST", "UNCONSTRAINED_PORT", + "INVALID_PORT", "INVALID_HOST", "METHOD_NOT_ROUTABLE", "PLAIN_HTTP_ONLY", From f93f4e743c8b6c0c11a25e17ea331dce6481639c Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 11:31:26 -0800 Subject: [PATCH 05/31] fix(box): Name the right folder in the uv sync hint, and remove the casts of the profile parser Box 0.1.11-preview.10 wraps its error at 80 columns. It wraps at a space or inside a word, and starts each next line with 12 spaces. The uv sync hint took the venv path from one line, up to the last space. For a project path with a space, or a path that Box wrapped, the hint named a wrong folder, such as "Run 'uv sync' in agent" or "in /agent". The hint now joins the lines of each Box error in each way (a space or no space at each wrap, up to 8 wraps). It names the folder only when one way gives a folder that is on disk. It quotes a folder that has a space. When no way, or more than one way, gives a folder, the error says "Fix what Box reports". The profile parser and the telemetry reader now use the shared Date-aware isTable of runtimeProfile/projectPaths.ts, TomlError for the place of a TOML syntax error, and type predicates in place of casts. The section banner comments of hostMap.ts and dogwood.ts are removed. Tests: boxProfileResolver.test.ts "the uv sync hint, when Box refuses a missing .venv under a write grant" (5 tests: one line, a wrap at a space in "my agent", a wrap before "/agent", a wrap inside a word, and a path of no folder). A run of box 0.1.11-preview.10 on a project in "/tmp/rf/venv test/proj with space" and on a long path gave the right folder. profileParser.test.ts "places a TOML syntax error at its line and column" pins the TomlError place. Mutations: no space at a wrap, no check on disk, and no quotes each make a test fail. --- src/core/project/boxNetwork/dogwood.ts | 16 ----- src/core/project/boxNetwork/hostMap.ts | 8 --- src/core/project/boxNetwork/profileParser.ts | 27 ++++---- src/core/project/boxNetwork/telemetry.ts | 10 +-- src/core/project/boxProfileResolver.test.ts | 71 ++++++++++++++++---- src/core/project/boxProfileResolver.ts | 48 ++++++++++--- 6 files changed, 114 insertions(+), 66 deletions(-) diff --git a/src/core/project/boxNetwork/dogwood.ts b/src/core/project/boxNetwork/dogwood.ts index 5ab901cb9..07fd872a7 100644 --- a/src/core/project/boxNetwork/dogwood.ts +++ b/src/core/project/boxNetwork/dogwood.ts @@ -128,10 +128,6 @@ function escapeRegExp(text: string): string { return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); } -// --------------------------------------------------------------------------- -// Tokens -// --------------------------------------------------------------------------- - type TokenKind = "ident" | "string" | "number" | "punct"; interface Token { @@ -288,10 +284,6 @@ function decodePattern(raw: string, span: SourceSpan): LikePattern { return { parts }; } -// --------------------------------------------------------------------------- -// Statements -// --------------------------------------------------------------------------- - const VARIABLES = new Set(["principal", "action", "resource", "context"]); const RELATION_OPERATORS = new Set(["==", "!=", "<", "<=", ">", ">="]); @@ -440,10 +432,6 @@ class Parser { return { polarity, body: { kind, text }, span: keyword.span }; } - // ------------------------------------------------------------------------- - // Expressions, by Cedar's precedence - // ------------------------------------------------------------------------- - private expr(): Expr { if (!this.isIdent("if")) return this.or(); const start = this.tokens[this.i++]!; @@ -712,10 +700,6 @@ class Parser { return this.fail("expected an attribute name after has", t); } - // ------------------------------------------------------------------------- - // Token helpers - // ------------------------------------------------------------------------- - private peek(): Token { const t = this.tokens[this.i]; if (t) return t; diff --git a/src/core/project/boxNetwork/hostMap.ts b/src/core/project/boxNetwork/hostMap.ts index 81a937336..914361de0 100644 --- a/src/core/project/boxNetwork/hostMap.ts +++ b/src/core/project/boxNetwork/hostMap.ts @@ -206,10 +206,6 @@ class HostMapBuilder { return { hosts, failures: this.failures, websocketOnly: this.websocketOnly }; } - // --------------------------------------------------------------------------- - // Sources - // --------------------------------------------------------------------------- - /** Adds the entry's nodes, or records why it fails and returns the destinations it names. */ private addEgressEntry(name: string, raw: unknown): Destination[] | undefined { const problems: { code: FailureCode; reason: string }[] = []; @@ -402,10 +398,6 @@ class HostMapBuilder { } } - // --------------------------------------------------------------------------- - // Rules - // --------------------------------------------------------------------------- - /** The statement's network clauses, or `undefined` for a rule that decides no host. */ private classify(statement: Statement, order: number): Rule | undefined { const scope = statement.action; diff --git a/src/core/project/boxNetwork/profileParser.ts b/src/core/project/boxNetwork/profileParser.ts index 8b8576d73..eaa91c44d 100644 --- a/src/core/project/boxNetwork/profileParser.ts +++ b/src/core/project/boxNetwork/profileParser.ts @@ -5,8 +5,9 @@ * entry, `packs`, and `policies` for a message. */ import { posix } from "node:path"; -import { parse as parseToml } from "smol-toml"; +import { parse as parseToml, TomlError } from "smol-toml"; import type { ResolvedBoxProfile } from "../boxProfileResolver"; +import { isTable } from "../runtimeProfile/projectPaths"; import type { TomlTable } from "../runtimeProfile/types"; import { cloudWatchTelemetry, type ProfileCloudWatchTelemetry } from "./telemetry"; @@ -67,7 +68,7 @@ export function parseResolvedProfile( }; } } - const egress: Record = { ...(boxToml.egress as object | undefined) }; + const egress: Record = isTable(boxToml.egress) ? { ...boxToml.egress } : {}; const telemetry = cloudWatchTelemetry(boxToml); for (const { route, destinations } of openRoutes) { if (!Object.hasOwn(egress, route)) egress[route] = { destinations }; @@ -76,7 +77,7 @@ export function parseResolvedProfile( profile: { path: profilePath, egress, - mcp: (boxToml.mcp as Record | undefined) ?? {}, + mcp: isTable(boxToml.mcp) ? boxToml.mcp : {}, policyFiles, ...(telemetry.length > 0 && { telemetry }), }, @@ -101,13 +102,12 @@ export function profilePolicyFiles( ok: false as const, failure: { code, reason, place }, }); - let table: Record; + let table: TomlTable; try { - table = parseToml(text) as Record; + table = parseToml(text); } catch (error) { - const at = error as { line?: number; column?: number }; const place = - at.line !== undefined ? `${profilePath}:${at.line}:${at.column ?? 1}` : profilePath; + error instanceof TomlError ? `${profilePath}:${error.line}:${error.column}` : profilePath; return fail(`This is not valid TOML (${tomlProblem(error)}). Correct the syntax.`, place); } if (table.policy !== undefined) { @@ -121,14 +121,17 @@ export function profilePolicyFiles( const named = table.policies ?? []; const place = placeOfKey(text, profilePath, "policies"); const folder = posix.dirname(profilePath); - if (!Array.isArray(named) || !named.every((file) => typeof file === "string" && file !== "")) { + if ( + !Array.isArray(named) || + !named.every((file): file is string => typeof file === "string" && file !== "") + ) { return fail( '`policies` must be a list of policy file paths, such as ["policy.dw"]. Correct it.', place, ); } const files: string[] = []; - for (const file of named as string[]) { + for (const file of named) { const normal = posix.normalize(file.replace(/\\/g, "/")); if (posix.isAbsolute(normal) || normal === ".." || normal.startsWith("../")) { return fail( @@ -196,10 +199,6 @@ function placeOfKey(text: string, profilePath: string, key: string): string { /** The TOML reader's message, without its "Invalid TOML document:" start and its excerpt. */ function tomlProblem(error: unknown): string { - const message = ((error as { message?: string }).message ?? String(error)).split("\n")[0]!; + const message = (error instanceof Error ? error.message : String(error)).split("\n")[0]!; return message.replace(/^Invalid TOML document:\s*/, ""); } - -function isTable(value: unknown): value is Record { - return typeof value === "object" && value !== null && !Array.isArray(value); -} diff --git a/src/core/project/boxNetwork/telemetry.ts b/src/core/project/boxNetwork/telemetry.ts index efe36cb31..101e24a39 100644 --- a/src/core/project/boxNetwork/telemetry.ts +++ b/src/core/project/boxNetwork/telemetry.ts @@ -3,6 +3,7 @@ * `box.toml` that Box resolves it to. On AgentCore Runtime, Box signs each CloudWatch target with * the execution role, so that role needs a grant for what these targets send. */ +import { isTable } from "../runtimeProfile/projectPaths"; /** A CloudWatch target of the box profile, as Box sends to it. */ export type CloudWatchTelemetry = CloudWatchTarget & { @@ -57,13 +58,12 @@ const SIGNAL_GROUPS: ReadonlySet = new Set(["deny", "permit", "trace", " function includeOf(value: unknown): readonly string[] | undefined | null { if (value === undefined) return undefined; if (!Array.isArray(value) || value.length === 0) return null; - const known = value.every((word) => typeof word === "string" && SIGNAL_GROUPS.has(word)); - return known && new Set(value).size === value.length ? (value as string[]) : null; + const known = value.every( + (word): word is string => typeof word === "string" && SIGNAL_GROUPS.has(word), + ); + return known && new Set(value).size === value.length ? value : null; } -const isTable = (value: unknown): value is Record => - typeof value === "object" && value !== null && !Array.isArray(value); - /** The trimmed string `value`, or undefined when it is not a string. */ const text = (value: unknown) => (typeof value === "string" ? value.trim() : undefined); diff --git a/src/core/project/boxProfileResolver.test.ts b/src/core/project/boxProfileResolver.test.ts index db877f739..dcc1f7d0b 100644 --- a/src/core/project/boxProfileResolver.test.ts +++ b/src/core/project/boxProfileResolver.test.ts @@ -338,19 +338,66 @@ describe("BoxCliProfileResolver", () => { ); }); - test("says to run uv sync in the agent's folder when Box refuses its missing .venv", async () => { - const error = await failure( - refusal([ - "box: error: /work/demo/app/agent/.venv/bin/python lies under the write grant /work/demo, so the workload can replace it", - ]), - ); + describe("the uv sync hint, when Box refuses a missing .venv under a write grant", () => { + /** A project folder with a space in its path, and the agent folders `agent` and `my agent`. */ + const project = async () => { + const root = await mkdtemp(join(tmpdir(), "box uv ")); + directories.push(root); + await mkdir(join(root, "app", "agent"), { recursive: true }); + await mkdir(join(root, "app", "my agent"), { recursive: true }); + return root; + }; + /** The last line of the error, which gives the hint. */ + const hint = async (root: string, lines: string[]) => { + const error = await new BoxCliProfileResolver(refusal(lines)) + .resolve(root, ".box/profile.toml") + .catch((caught: unknown) => caught); + return (error as Error).message.split("\n").at(-1); + }; + // Box 0.1.11-preview.10 wraps its error at 80 columns, at a space or inside a word, and + // indents each next line by 12 spaces. + const MORE = " ".repeat(12); + const grant = (root: string) => `lies under the write grant ${root} of \`[agent]\``; + + test("names the agent's folder", async () => { + const root = await project(); + const error = await new BoxCliProfileResolver( + refusal([`box: error: ${root}/app/agent/.venv/bin/python ${grant(root)}`]), + ) + .resolve(root, ".box/profile.toml") + .catch((caught: unknown) => caught); - expect((error as Error).message).toBe( - "Box refused the profile .box/profile.toml:\n" + - " box: error: /work/demo/app/agent/.venv/bin/python lies under the write grant " + - "/work/demo, so the workload can replace it\n" + - "Run 'uv sync' in app/agent, then retry.", - ); + expect((error as Error).message).toBe( + "Box refused the profile .box/profile.toml:\n" + + ` box: error: ${root}/app/agent/.venv/bin/python ${grant(root)}\n` + + "Run 'uv sync' in app/agent, then retry.", + ); + }); + + test("quotes a folder with a space, which Box wraps at that space", async () => { + const root = await project(); + const lines = [`box: error: ${root}/app/my`, `${MORE}agent/.venv/bin/python ${grant(root)}`]; + expect(await hint(root, lines)).toBe(`Run 'uv sync' in "app/my agent", then retry.`); + }); + + test("names the whole folder when Box wraps the path before the agent's folder", async () => { + const root = await project(); + const lines = [`box: error: ${root}/app`, `${MORE}/agent/.venv/bin/python lies under the`]; + lines.push(`${MORE}write grant ${root} of \`[agent]\``); + expect(await hint(root, lines)).toBe("Run 'uv sync' in app/agent, then retry."); + }); + + test("names the whole folder when Box wraps the path inside a word", async () => { + const root = await project(); + const lines = [`box: error: ${root}/app/ag`, `${MORE}ent/.venv/bin/python ${grant(root)}`]; + expect(await hint(root, lines)).toBe("Run 'uv sync' in app/agent, then retry."); + }); + + test("names no folder when the path names no folder of the project", async () => { + const root = await project(); + const lines = [`box: error: ${root}/app/gone/.venv/bin/python ${grant(root)}`]; + expect(await hint(root, lines)).toBe("Fix what Box reports, then retry."); + }); }); test("says how to see why when Box fails and prints no error", async () => { diff --git a/src/core/project/boxProfileResolver.ts b/src/core/project/boxProfileResolver.ts index 25ccbfbe1..a12483bf1 100644 --- a/src/core/project/boxProfileResolver.ts +++ b/src/core/project/boxProfileResolver.ts @@ -3,7 +3,7 @@ * the `box.toml` and `policy.dw` that a run of the profile gets, with every pack, option, and rule * Box adds already in them, so build reads them rather than compiling the profile itself. */ -import { realpathSync } from "node:fs"; +import { existsSync, realpathSync } from "node:fs"; import { isAbsolute, join, posix, relative, sep } from "node:path"; import { z } from "zod"; import { InvalidEnvironmentError } from "../../errors/errors"; @@ -210,21 +210,47 @@ function boxError(stderr: readonly string[]): string[] { return lines.filter((line) => line.trim() !== ""); } +/** The most places where Box wraps one error that build tries both ways. */ +const MAX_WRAPS = 8; + /** - * The agent's folder, from the project root, when Box refuses the profile because the agent's - * `.venv` lies under a write grant, as it does before `uv sync` makes the venv; else `undefined`. + * The agent's folder, from the project root and quoted when it has a space, when Box refuses the + * profile because the agent's `.venv` lies under a write grant, as it does before `uv sync` makes + * the venv; else `undefined`. Box wraps its error onto lines that start with spaces, at a space + * or inside a word, so the folder is the one way of joining the lines that names a folder on disk. */ function venvAgentFolder(lines: readonly string[], projectRoot: string): string | undefined { + const folders = new Set(); + for (const pieces of wrappedErrors(lines)) { + const wraps = Math.min(pieces.length - 1, MAX_WRAPS); + for (let joins = 0; joins < 2 ** wraps; joins++) { + const text = pieces.reduce( + (joined, piece, i) => `${joined}${(joins >> (i - 1)) & 1 ? " " : ""}${piece}`, + ); + const folder = /^box: error: (.+?)[\\/]\.venv[\\/]\S* lies under the write grant /.exec( + text, + )?.[1]; + if (folder !== undefined && existsSync(folder)) folders.add(folder); + } + } + const [folder, other] = [...folders]; + if (folder === undefined || other !== undefined) return undefined; + const inside = relative(realPath(projectRoot), realPath(folder)); + if (inside === "") return "the project folder"; + const outside = inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside); + const named = outside ? folder : inside.split(sep).join("/"); + return /\s/.test(named) ? `"${named}"` : named; +} + +/** Each error of Box as the pieces of its lines: a line that starts with a space goes on the last. */ +function wrappedErrors(lines: readonly string[]): string[][] { + const errors: string[][] = []; for (const line of lines) { - if (!line.includes("write grant")) continue; - const folder = /(\S+?)[\\/]\.venv[\\/]/.exec(line)?.[1]; - if (folder === undefined) continue; - const inside = relative(realPath(projectRoot), realPath(folder)); - if (inside === "") return "the project folder"; - const outside = inside === ".." || inside.startsWith(`..${sep}`) || isAbsolute(inside); - return outside ? folder : inside.split(sep).join("/"); + const last = errors.at(-1); + if (last && /^\s/.test(line)) last.push(line.trimStart()); + else errors.push([line]); } - return undefined; + return errors; } /** The path with every link resolved, or the path itself when it does not exist. */ From ddd140815a49ab097e805a1276c8cfd74e2fc138 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 11:35:17 -0800 Subject: [PATCH 06/31] fix(box): Give a Runtime route a free name when a rule of the policy has its route rule's @id Box adds the rules route__connect and route__request for each [egress.] route, and refuses a profile in which another rule has one of those @ids. The AgentCore Runtime profile names some routes after their gateway target: each other host of an entry (`egress-models-two`), a host that only a rule names, and an entry whose name a target of another host has (`egress-api`). A rule of the user's policy with the @id `route_egress-api_request` is valid locally, but box 0.1.11-preview.10 refused the Runtime profile: "box writes a rule with the id ... so give your rule another id". The gateway rule now gives each such route the first free name of ``, `-2`, `-3`, and so on: a name for which no rule of the local policy, other than the route rules that Box adds itself, has the @id route__connect or route__request, and that no other route has. The Box network model gives the derivation these @ids (RuntimeProfileContext.ruleIds). The route still sends its calls to the same gateway target. Tests: gateway.test.ts "names no route so that box adds a rule with the @id of a rule of the policy" (an entry whose route takes the name of its target, and another host of an entry past a name that another route has), and "give a route a free name when a rule of the policy has the @id of its route rule" through buildBoxNetwork. Box 0.1.11-preview.10 refused [egress.egress-api-b-example-com] beside the rule route_egress-api-b-example-com_request (exit 1), and accepts [egress.egress-api-b-example-com-2] beside it (exit 0). Mutations: no check of the rule ids, no check of the other routes' names, and no rule ids from the model each make a test fail. --- src/core/project/boxNetwork/network.ts | 8 +++ .../project/runtimeProfile/derive.test.ts | 1 + .../runtimeProfile/rules/additions.test.ts | 1 + .../runtimeProfile/rules/gateway.test.ts | 65 ++++++++++++++++++- .../project/runtimeProfile/rules/gateway.ts | 30 ++++++++- .../runtimeProfile/rules/paths.test.ts | 1 + .../runtimeProfile/rules/refusals.test.ts | 1 + src/core/project/runtimeProfile/types.ts | 6 ++ 8 files changed, 110 insertions(+), 3 deletions(-) diff --git a/src/core/project/boxNetwork/network.ts b/src/core/project/boxNetwork/network.ts index 8027f4524..5aa2693fa 100644 --- a/src/core/project/boxNetwork/network.ts +++ b/src/core/project/boxNetwork/network.ts @@ -208,6 +208,14 @@ export function buildBoxNetwork( gateway: { name: project.gateway, targets: project.targets }, hosts: targets.hosts, telemetry: telemetry?.telemetry ?? [], + ruleIds: new Set( + parsed.statements + .filter( + ({ id, span }) => + placeOf(parsed, span) !== undefined || ruleOrigin(parsed, id).by !== "box", + ) + .map(({ id }) => id), + ), places: source.places, }); const derived = source && context && deriveRuntimeProfile(source.table, context); diff --git a/src/core/project/runtimeProfile/derive.test.ts b/src/core/project/runtimeProfile/derive.test.ts index dff787616..e46eac831 100644 --- a/src/core/project/runtimeProfile/derive.test.ts +++ b/src/core/project/runtimeProfile/derive.test.ts @@ -29,6 +29,7 @@ const context = (runtime: ProjectRuntime, places = new Map()) => gateway: { name: "agent-box-egress", targets: [] }, hosts: [], telemetry: [], + ruleIds: new Set(), places, }); diff --git a/src/core/project/runtimeProfile/rules/additions.test.ts b/src/core/project/runtimeProfile/rules/additions.test.ts index 1b3dc8202..358677835 100644 --- a/src/core/project/runtimeProfile/rules/additions.test.ts +++ b/src/core/project/runtimeProfile/rules/additions.test.ts @@ -84,6 +84,7 @@ function contextOf( }, hosts: [], telemetry: options.telemetry ?? [], + ruleIds: new Set(), places: new Map(), }); } diff --git a/src/core/project/runtimeProfile/rules/gateway.test.ts b/src/core/project/runtimeProfile/rules/gateway.test.ts index 585b2e30d..c67ccc6e4 100644 --- a/src/core/project/runtimeProfile/rules/gateway.test.ts +++ b/src/core/project/runtimeProfile/rules/gateway.test.ts @@ -104,6 +104,7 @@ function contextOf( hosts: BoxNetworkHost[], targets: AgentCoreGatewayTarget[] = [], region = "us-west-2", + ruleIds: ReadonlySet = new Set(), ) { return runtimeProfileContext({ spec: project(targets), @@ -113,6 +114,7 @@ function contextOf( gateway: { name: GATEWAY, targets }, hosts, telemetry: [], + ruleIds, places: profileKeyPlaces(text, PROFILE), }); } @@ -123,8 +125,9 @@ function gateway( hosts: BoxNetworkHost[], targets: AgentCoreGatewayTarget[] = [], region?: string, + ruleIds?: ReadonlySet, ) { - return apply(parse(text) as TomlTable, contextOf(text, hosts, targets, region)); + return apply(parse(text) as TomlTable, contextOf(text, hosts, targets, region, ruleIds)); } /** @@ -267,6 +270,49 @@ describe("the gateway rule", () => { expect(Object.keys(table.egress as TomlTable).sort()).toEqual(["egress-orders", "orders"]); }); + describe("names no route so that box adds a rule with the @id of a rule of the policy", () => { + test("for an entry whose route takes the name of its target", () => { + const { table } = gateway( + '[egress.api]\ndestinations = ["api.example.com"]\n', + [host("api.example.com", entry("api", "api.example.com"), "egress-api")], + [passthrough("api", "https://orders.example.com")], + undefined, + new Set(["route_egress-api_request"]), + ); + + // The user's own target `api` keeps the route `api`. + expect(Object.keys(table.egress as TomlTable)).toEqual(["egress-api-2", "api"]); + expect(table.egress).toMatchObject({ + "egress-api-2": { backends: [{ url: "${{ inputs.gateway.url }}/egress-api" }] }, + }); + }); + + test("for each other host of an entry, and past a name that another route has", () => { + const { table } = gateway( + '[egress.models]\ndestinations = ["one.example.com", "two.example.com"]\n' + + '[egress.egress-models-two-2]\ndestinations = ["three.example.com"]\n', + [ + host("one.example.com", entry("models", "one.example.com"), "egress-models-one"), + host("two.example.com", entry("models", "two.example.com"), "egress-models-two"), + host( + "three.example.com", + entry("egress-models-two-2", "three.example.com"), + "egress-egress-models-two-2", + ), + ], + [], + undefined, + new Set(["route_egress-models-two_connect"]), + ); + + expect(Object.keys(table.egress as TomlTable)).toEqual([ + "models", + "egress-models-two-3", + "egress-models-two-2", + ]); + }); + }); + test("gives each host of an entry with several destinations its own route, signed for the Runtime's region and not the build region", () => { const text = '[egress.models]\ndestinations = ["api.one.example.com", "api.two.example.com:8443/v1"]\n'; @@ -616,6 +662,7 @@ describe("the gateway rule and the Runtime renderer it replaced", () => { gateway: { name: GATEWAY, targets }, hosts: network.hosts, telemetry: [], + ruleIds: new Set(), places: profileKeyPlaces(text, PROFILE), }), ); @@ -628,6 +675,22 @@ describe("the gateway rule and the Runtime renderer it replaced", () => { ), ); + test("give a route a free name when a rule of the policy has the @id of its route rule", () => { + const own = + '@id("route_egress-models-api-two-example-com_request")\n' + + 'permit (principal, action == Box::Action::"http:request", resource) when { ' + + 'context.input.host == "api.two.example.com" };\n'; + const { network } = bothProfiles(project(TARGETS, ["agentMemory"]), { + ...FIXTURE, + policy: FIXTURE.policy + own, + }); + + expect(network.failures).toEqual([]); + const keys = Object.keys(network.runtimeProfile?.egress as TomlTable); + expect(keys).toContain("egress-models-api-two-example-com-2"); + expect(keys).not.toContain("egress-models-api-two-example-com"); + }); + test("give the same [egress] and HTTP [mcp] tables on the first build", () => { const { network, derived } = bothProfiles(project(TARGETS, ["agentMemory"])); const old = rendered("first build"); diff --git a/src/core/project/runtimeProfile/rules/gateway.ts b/src/core/project/runtimeProfile/rules/gateway.ts index 321e267b6..a6acddf7e 100644 --- a/src/core/project/runtimeProfile/rules/gateway.ts +++ b/src/core/project/runtimeProfile/rules/gateway.ts @@ -43,6 +43,7 @@ interface GatewayRoute { export function apply(table: Readonly, context: RuntimeProfileContext): RuleResult { const routes = gatewayRoutes(context); + const keys = routeKeys(routes, context); const written = new Set(); const egress: TomlTable = {}; @@ -55,7 +56,7 @@ export function apply(table: Readonly, context: RuntimeProfileContext host.sources.some((source) => source.kind === "entry" && source.egressEntry === name), ); for (const route of routesOf(hosts, routes)) { - egress[routeKey(route, routes, context)] = egressRoute(entry, route); + egress[keys.get(route.target)!] = egressRoute(entry, route); written.add(route.target); } } @@ -77,7 +78,7 @@ export function apply(table: Readonly, context: RuntimeProfileContext if (route.server) { mcp[route.server.mcpEntry] = mcpServer({}, route, route.server); } else { - egress[routeKey(route, routes, context)] = egressRoute({}, route); + egress[keys.get(route.target)!] = egressRoute({}, route); } } @@ -171,6 +172,31 @@ function routeKey( return name; } +/** + * The `[egress]` key of each route that serves no HTTP MCP server, by its target: its + * {@link routeKey}, or that key with `-2`, `-3`, and so on after it when box would add a route rule + * with the `@id` of a rule of the policy. A key that another route has stays that route's. + */ +function routeKeys( + routes: readonly GatewayRoute[], + context: RuntimeProfileContext, +): Map { + const named = routes + .filter((route) => route.server === undefined) + .map((route) => ({ route, key: routeKey(route, routes, context) })); + const used = new Set(named.map(({ key }) => key)); + const taken = (key: string) => + context.ruleIds.has(`route_${key}_connect`) || context.ruleIds.has(`route_${key}_request`); + const keys = new Map(); + for (const { route, key } of named) { + let free = key; + for (let n = 2; taken(free) || (free !== key && used.has(free)); n++) free = `${key}-${n}`; + used.add(free); + keys.set(route.target, free); + } + return keys; +} + /** The routes of `hosts`, in the order of the hosts; a host with no route has none. */ function routesOf( hosts: readonly BoxNetworkHost[], diff --git a/src/core/project/runtimeProfile/rules/paths.test.ts b/src/core/project/runtimeProfile/rules/paths.test.ts index 075d6e1c3..183cd7b27 100644 --- a/src/core/project/runtimeProfile/rules/paths.test.ts +++ b/src/core/project/runtimeProfile/rules/paths.test.ts @@ -32,6 +32,7 @@ const contextOf = (text: string, runtime: ProjectRuntime = CODEZIP) => gateway: { name: "agent-box-egress", targets: [] }, hosts: [], telemetry: [], + ruleIds: new Set(), places: profileKeyPlaces(text, PROFILE), }); diff --git a/src/core/project/runtimeProfile/rules/refusals.test.ts b/src/core/project/runtimeProfile/rules/refusals.test.ts index ed1720f94..bff1b0522 100644 --- a/src/core/project/runtimeProfile/rules/refusals.test.ts +++ b/src/core/project/runtimeProfile/rules/refusals.test.ts @@ -34,6 +34,7 @@ const contextOf = (text: string, runtime: ProjectRuntime = CODEZIP) => hosts: [], telemetry: withDeployRegion(cloudWatchTelemetry(parse(text) as TomlTable), "us-west-2", PROFILE) .telemetry, + ruleIds: new Set(), places: profileKeyPlaces(text, PROFILE), }); diff --git a/src/core/project/runtimeProfile/types.ts b/src/core/project/runtimeProfile/types.ts index 628d1520f..d5a8cdb6b 100644 --- a/src/core/project/runtimeProfile/types.ts +++ b/src/core/project/runtimeProfile/types.ts @@ -68,6 +68,12 @@ export interface RuntimeProfileContext { readonly hosts: readonly BoxNetworkHost[]; /** The CloudWatch targets of the local profile, with the deploy region set. */ readonly telemetry: readonly CloudWatchTelemetry[]; + /** + * The `@id` of each rule of the local policy that box does not add for a route or a server. Box + * adds `route__connect` and `route__request` for each route, and refuses a second + * rule with the same `@id`. + */ + readonly ruleIds: ReadonlySet; readonly paths: RuntimePaths; /** * The profile that `agentcore create` writes for this runtime, `local`, and its Runtime form, From 47acc2f63bfe4bf7122d8878f574f0362f374672 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 11:38:34 -0800 Subject: [PATCH 07/31] fix(box): Take one API key credential for its own variable and one other variable `env://GITHUB_TOKEN` and `env://AGENTCORE_CREDENTIAL_GITHUB` both resolve to the API key credential `github`. The Box network model compared the two variable names, found them different, and failed the build and the deploy with API_KEY_CREDENTIAL_SHARED. The same comparison across two runtimes (sharedKeyFailures) failed in the same way. But the two names give one key: build copies the key of `GITHUB_TOKEN` to `AGENTCORE_CREDENTIAL_GITHUB`, the credential's own variable (`seed` in planBoxProfileCredentials), and deploy reads it from there. Both checks now skip an entry that reads the credential's own variable. Two entries that read two other variables for one credential still fail, because the credential can hold only one of the two keys. Not changed: on the first build, before the credential `github` is in agentcore.json, an entry that reads AGENTCORE_CREDENTIAL_GITHUB names the credential after its own entry. Its target is then not written until the next build. Tests: network.test.ts "takes one credential for its own variable and for one other variable, which build copies to it" (in both orders; it replaces the test that pinned the failure); boxNetworkSource.test.ts "takes the credential of another runtime for the credential's own variable". network.test.ts "fails a server that takes the API key credential of an [egress] entry for another variable" still pins the real conflict. Mutations: raw names in the model, raw names across runtimes, and no conflict at all each make a test fail. --- src/core/project/boxNetwork/network.test.ts | 35 ++++++++++----------- src/core/project/boxNetwork/network.ts | 21 +++++++++---- src/core/project/boxNetworkSource.test.ts | 30 ++++++++++++++++++ src/core/project/boxNetworkSource.ts | 6 +++- 4 files changed, 67 insertions(+), 25 deletions(-) diff --git a/src/core/project/boxNetwork/network.test.ts b/src/core/project/boxNetwork/network.test.ts index 21703d10c..e6ced9c43 100644 --- a/src/core/project/boxNetwork/network.test.ts +++ b/src/core/project/boxNetwork/network.test.ts @@ -459,24 +459,23 @@ describe("outbound auth", () => { ]); }); - test("fails an entry named for a credential that another entry's variable takes", () => { - const shared = model( - "", - { - mirror: { - destinations: ["mirror.example.com"], - secret: { ref: "env://AGENTCORE_CREDENTIAL_GITHUB" }, - }, - github: GITHUB, - }, - { credentials: [{ authorizerType: "ApiKeyCredentialProvider", name: "github" }] }, - ); - expect(shared.failures()).toEqual([["API_KEY_CREDENTIAL_SHARED", "github"]]); - expect(shared.lines()).toEqual([ - ".box/agent/local/profile.toml:3:1 [egress.github] needs the API key credential 'github' for " + - "env://GITHUB_TOKEN, and [egress.mirror] takes that credential for " + - "env://AGENTCORE_CREDENTIAL_GITHUB. One credential holds one key. Rename the entry.", - ]); + test("takes one credential for its own variable and for one other variable, which build copies to it", () => { + const github = { authorizerType: "ApiKeyCredentialProvider", name: "github" } as const; + const mirror = { + destinations: ["mirror.example.com"], + secret: { ref: "env://AGENTCORE_CREDENTIAL_GITHUB" }, + }; + for (const egress of [ + { mirror, github: GITHUB }, + { github: GITHUB, mirror }, + ]) { + const shared = model("", egress, { credentials: [github] }); + expect(shared.failures()).toEqual([]); + expect(shared.network.hosts.map(({ outboundAuth }) => outboundAuth)).toMatchObject([ + { kind: "apiKey", credentialName: "github" }, + { kind: "apiKey", credentialName: "github" }, + ]); + } }); test("leaves an env:// entry that cannot name an API key credential to the credentials writer", () => { diff --git a/src/core/project/boxNetwork/network.ts b/src/core/project/boxNetwork/network.ts index 5aa2693fa..172183397 100644 --- a/src/core/project/boxNetwork/network.ts +++ b/src/core/project/boxNetwork/network.ts @@ -5,6 +5,7 @@ * it. */ import { boxGatewayAgentCoreHost } from "../../../handlers/project/shortcuts"; +import { credentialEnvVarName } from "../../../projectSchemas/credential"; import type { AgentCoreGateway, AgentCoreGatewayTarget } from "../../../projectSchemas/gateway"; import type { ProjectSpec } from "../../../projectSchemas/project"; import type { ProjectRuntime } from "../../../projectSchemas/runtime"; @@ -369,7 +370,11 @@ function hostTargets( const claimed = new Set(); const reused = new Set(); - /** The variable and the entry of each API key credential an entry takes. */ + /** + * The variable and the entry of each API key credential an entry takes for a variable that is + * not the credential's own. Build copies the key of that variable to the credential's own, so an + * entry that reads the credential's own variable takes the same key. + */ const keys = new Map(); const hosts = mapped.map((host, index): BoxNetworkHost => { let auth: BoxEgressAuth = { kind: "none" }; @@ -380,17 +385,21 @@ function hostTargets( ); if (result.ok) auth = result.auth; else failAt(host, result.code, result.reason); - const holder = auth.kind === "apiKey" ? keys.get(auth.credentialName) : undefined; - if (auth.kind === "apiKey" && holder && holder.variable !== auth.variable) { + const alias = + auth.kind === "apiKey" && auth.variable !== credentialEnvVarName(auth.credentialName) + ? auth + : undefined; + const holder = alias && keys.get(alias.credentialName); + if (alias && holder && holder.variable !== alias.variable) { failAt( host, "API_KEY_CREDENTIAL_SHARED", - `needs the API key credential '${auth.credentialName}' for env://${auth.variable}, ` + + `needs the API key credential '${alias.credentialName}' for env://${alias.variable}, ` + `and ${holder.entry} takes that credential for env://${holder.variable}. One ` + "credential holds one key. Rename the entry.", ); - } else if (auth.kind === "apiKey" && !holder) { - keys.set(auth.credentialName, { variable: auth.variable, entry: entryLabel(entry) }); + } else if (alias && !holder) { + keys.set(alias.credentialName, { variable: alias.variable, entry: entryLabel(entry) }); } } let target: string | undefined; diff --git a/src/core/project/boxNetworkSource.test.ts b/src/core/project/boxNetworkSource.test.ts index 85151893e..f3d9afcaf 100644 --- a/src/core/project/boxNetworkSource.test.ts +++ b/src/core/project/boxNetworkSource.test.ts @@ -237,6 +237,36 @@ describe("readBoxNetworks", () => { ); }); + test("takes the credential of another runtime for the credential's own variable", async () => { + const root = await project([]); + const profiles: Record = { + ".box/agent/local/profile.toml": { variable: "GITHUB_TOKEN", host: "api.github.com" }, + ".box/second/local/profile.toml": { + variable: "AGENTCORE_CREDENTIAL_GITHUB", + host: "uploads.github.com", + }, + }; + for (const [file, { variable, host }] of Object.entries(profiles)) { + await mkdir(join(root, file, ".."), { recursive: true }); + await writeFile( + join(root, file), + `[egress.github]\ndestinations = ["${host}"]\nsecret.ref = "env://${variable}"\n`, + ); + } + const resolver: BoxProfileResolver = { + resolve: async (_root, profilePath) => { + const { variable, host } = profiles[profilePath]!; + return boxShowOf({ + egress: { github: { destinations: [host], secret: { ref: `env://${variable}` } } }, + }); + }, + }; + + const networks = await readBoxNetworks(specWith("second"), root, resolver); + + expect(networks.map(({ failures }) => failures)).toEqual([[], []]); + }); + test("places a rule of a policy file at its line, and an entry at its line in the profile", async () => { const root = await project(["policy.dw"]); await writeFile( diff --git a/src/core/project/boxNetworkSource.ts b/src/core/project/boxNetworkSource.ts index 0b18cb0c2..af3e8c6b7 100644 --- a/src/core/project/boxNetworkSource.ts +++ b/src/core/project/boxNetworkSource.ts @@ -8,6 +8,7 @@ import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { dirname, isAbsolute, join, relative, sep } from "node:path"; import { parse as parseToml, stringify as stringifyToml } from "smol-toml"; +import { credentialEnvVarName } from "../../projectSchemas/credential"; import type { ProjectSpec } from "../../projectSchemas/project"; import type { ProjectRuntime } from "../../projectSchemas/runtime"; import { InvalidEnvironmentError, ProjectStateError } from "../../errors/errors"; @@ -133,7 +134,10 @@ function sharedKeyFailures( ): BoxNetworkFailure[] { const failures: BoxNetworkFailure[] = []; for (const { outboundAuth: auth, sources } of network.hosts) { - if (auth.kind !== "apiKey") continue; + // Build copies the key of another variable to the credential's own, so it is the same key. + if (auth.kind !== "apiKey" || auth.variable === credentialEnvVarName(auth.credentialName)) { + continue; + } const holder = keys.get(auth.credentialName); if (holder === undefined) { keys.set(auth.credentialName, { variable: auth.variable, runtime: network.runtime }); From d0f95235f7f781611878dab29b94caa939a6bfd7 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 11:46:04 -0800 Subject: [PATCH 08/31] fix(box): Warn for a host that gets no gateway target, and give a model-provider route its credential A host whose target sends an API key that no credential of agentcore.json holds got no gateway target. Build said so only as a step ("not adding gateway target ..."), not as a warning, and the agent could not reach the host on AgentCore Runtime. For a model-provider route that `agentcore create` writes with no key ([egress.openai] with env://OPENAI_API_KEY, and the same for Anthropic and Gemini), the credential planner skipped the route with no message. Thus "set the key and build again" did not work for these routes: build never added their credential, so their target never came. This change ports the rule of box-integration-development: a model-provider route is a route like any other. On AgentCore Runtime its gateway target sends the key of its credential, so the planner declares the credential `openai` and stores the key of OPENAI_API_KEY under AGENTCORE_CREDENTIAL_OPENAI, when that key is set. The planner also records, for each route that gets no credential, why and what to do (BoxCredentialPlan.unprovisioned). Build gives a warning for each host with no target (unsentTargetWarnings): the host, the entry, that the agent cannot reach it on AgentCore Runtime, and the planner's cause and fix. The step stays only when build removes a target that agentcore.json had. Tests: manager.boxNetwork.test.ts "writes no target for an env:// route whose key build cannot find, and says what to set", "stages no Runtime [mcp] server for an HTTP MCP server whose key build cannot find", and "writes the target of a model-provider route once its key is set, as the warning says" (the fix of the warning works for OpenAI); boxNetworkWriters.test.ts "unsentTargetWarnings" (3 tests); boxProfileCredentials.test.ts "adds a credential for a model-provider route create writes, from the provider's variable" and "adds a credential for a route that uses a model-provider name or variable in another way" (these replace the two tests that pinned the skip). Mutations: the provider skip put back, no warnings, and no cause for an unset key each make a test fail. --- src/core/project/boxNetworkWriters.test.ts | 44 +++++++++++++++- src/core/project/boxNetworkWriters.ts | 46 +++++++++++++++-- .../project/boxProfileCredentials.test.ts | 34 ++++++++----- src/core/project/boxProfileCredentials.ts | 44 ++++++++-------- src/core/project/manager.boxNetwork.test.ts | 51 +++++++++++++++---- src/core/project/manager.tsx | 23 ++++++--- src/core/project/templates/boxProfile.ts | 19 ------- 7 files changed, 186 insertions(+), 75 deletions(-) diff --git a/src/core/project/boxNetworkWriters.test.ts b/src/core/project/boxNetworkWriters.test.ts index d63c5a501..3918cc7f9 100644 --- a/src/core/project/boxNetworkWriters.test.ts +++ b/src/core/project/boxNetworkWriters.test.ts @@ -12,8 +12,10 @@ import { gatewayTargetsWriter, runtimeProfileWriter, telemetryPolicyWriter, + unsentTargetWarnings, type BoxNetworkWriter, } from "./boxNetworkWriters"; +import { ENV_LOCAL_RELATIVE_PATH } from "./envLocal"; import { AGENTCORE_CODEZIP_PACK_PATH, AGENTCORE_PACK_PATH } from "./templates/boxProfile"; import { serializeRuntimeProfile } from "./runtimeProfile/serialize"; @@ -217,9 +219,10 @@ describe("gatewayTargetsWriter", () => { "sends the key of env://GITHUB_TOKEN, and agentcore.json has no API key credential " + "'github' to hold it", ]); + // A target that was never written changes nothing; unsentTargetWarnings says why it is not. const fresh = run([gatewayTargetsWriter], models); expect(fresh.specChanged).toBe(false); - expect(fresh.messages[0]).toStartWith("not adding gateway target 'egress-github'"); + expect(fresh.messages).toEqual([]); }); test("writes to the gateway bound to the runtime, whatever its name", () => { @@ -238,6 +241,45 @@ describe("gatewayTargetsWriter", () => { }); }); +describe("unsentTargetWarnings", () => { + const github = (envRoutes: BoxNetwork["envRoutes"]) => + network({ + hosts: [ + host("api.github.com", "egress-github", { + outboundAuth: GITHUB_AUTH, + sources: [{ kind: "entry", egressEntry: "github", destinations: ["api.github.com"] }], + }), + ], + envRoutes, + }); + + test("warns for no host whose credential the credentials writer adds", () => { + const routes = [{ route: "github", variable: "GITHUB_TOKEN" }]; + expect(unsentTargetWarnings([github(routes)], contextFor())).toEqual([]); + }); + + test("says why a host gets no target, and what to do, from the credentials writer", () => { + const routes = [{ route: "github", variable: "GITHUB_TOKEN" }]; + expect( + unsentTargetWarnings([github(routes)], { ...contextFor(), env: {} }).map((w) => + w.replace(ENV_LOCAL_RELATIVE_PATH, ".env.local"), + ), + ).toEqual([ + "api.github.com: build gives [egress.github] no gateway target, so the agent cannot reach " + + "this host on AgentCore Runtime. GITHUB_TOKEN is not set here or in .env.local. Set " + + "GITHUB_TOKEN, or AGENTCORE_CREDENTIAL_GITHUB, and build again.", + ]); + }); + + test("names the credential and the variable when the credentials writer gives no reason", () => { + expect(unsentTargetWarnings([github([])], contextFor())).toEqual([ + "api.github.com: build gives [egress.github] no gateway target, so the agent cannot reach " + + "this host on AgentCore Runtime. agentcore.json has no API key credential 'github' to " + + "hold the key of env://GITHUB_TOKEN.", + ]); + }); +}); + describe("credentialsWriter", () => { test("declares each credential once and seeds its key from the box variable", () => { const envRoutes = [{ route: "github", variable: "GITHUB_TOKEN" }]; diff --git a/src/core/project/boxNetworkWriters.ts b/src/core/project/boxNetworkWriters.ts index cd8b28324..5b04a574b 100644 --- a/src/core/project/boxNetworkWriters.ts +++ b/src/core/project/boxNetworkWriters.ts @@ -257,12 +257,12 @@ function writeGatewayTargets(spec: ProjectSpec, network: BoxNetwork): string[] { messages.push(`adding gateway target '${host.target}' to ${gatewayName} for ${host.authority}`); } for (const host of unsent) { + if (!existing.some(({ name }) => name === host.target)) continue; const auth = undeclaredKey(spec, host)!; - const removed = existing.some(({ name }) => name === host.target); messages.push( - `${removed ? "removing" : "not adding"} gateway target '${host.target}' of ${gatewayName} ` + - `for ${host.authority}: it sends the key of env://${auth.variable}, and agentcore.json ` + - `has no API key credential '${auth.credentialName}' to hold it`, + `removing gateway target '${host.target}' of ${gatewayName} for ${host.authority}: it ` + + `sends the key of env://${auth.variable}, and agentcore.json has no API key credential ` + + `'${auth.credentialName}' to hold it`, ); } if (isDeepStrictEqual(targets, existing)) return messages; @@ -270,6 +270,44 @@ function writeGatewayTargets(spec: ProjectSpec, network: BoxNetwork): string[] { return messages; } +/** + * A warning for each host of `networks` that gets no gateway target because no API key credential + * of agentcore.json, once the credentials writer runs, holds the key its target sends: the agent + * cannot reach the host on AgentCore Runtime. It says why, and what to do. + */ +export function unsentTargetWarnings( + networks: readonly BoxNetwork[], + context: BoxNetworkWriteContext, +): string[] { + const { spec, env, envLocal } = context; + const plan = planBoxProfileCredentials(structuredClone(spec), uniqueRoutes(networks), { + env, + envLocal, + }); + const after = { ...spec, credentials: [...spec.credentials, ...plan.added] }; + const warnings: string[] = []; + for (const host of networks.flatMap((network) => network.hosts)) { + if (host.target === undefined || !isManagedTarget({ name: host.target })) continue; + const auth = undeclaredKey(after, host); + const source = host.sources.find( + (candidate): candidate is Exclude => + candidate.kind !== "rule", + ); + if (auth === undefined || source === undefined) continue; + const [table, route] = + source.kind === "entry" ? ["egress", source.egressEntry] : ["mcp", source.mcpEntry]; + const why = + plan.unprovisioned.get(route) ?? + `agentcore.json has no API key credential '${auth.credentialName}' to hold the key of ` + + `env://${auth.variable}.`; + warnings.push( + `${host.authority}: build gives [${table}.${route}] no gateway target, so the agent ` + + `cannot reach this host on AgentCore Runtime. ${why}`, + ); + } + return warnings; +} + /** The API key that a host's target sends, when agentcore.json declares no credential for it. */ function undeclaredKey( spec: ProjectSpec, diff --git a/src/core/project/boxProfileCredentials.test.ts b/src/core/project/boxProfileCredentials.test.ts index 6c5ec7081..d6b964d61 100644 --- a/src/core/project/boxProfileCredentials.test.ts +++ b/src/core/project/boxProfileCredentials.test.ts @@ -160,20 +160,30 @@ describe("planBoxProfileCredentials", () => { messages: [], added: [], entries: [], + unprovisioned: new Map(), }); }); - test("skips, with no message, the model-provider routes create writes", () => { + test("adds a credential for a model-provider route create writes, from the provider's variable", () => { const s = spec(); const plan = planBoxProfileCredentials( s, [route("openai", "OPENAI_API_KEY"), route("anthropic", "ANTHROPIC_API_KEY")], - shell({ OPENAI_API_KEY: "sk-x", ANTHROPIC_API_KEY: "sk-ant-x" }), + shell({ OPENAI_API_KEY: "sk-x" }), ); - expect(plan).toEqual({ messages: [], added: [], entries: [] }); - expect(s.credentials).toEqual([]); + expect(plan.added).toEqual([{ authorizerType: "ApiKeyCredentialProvider", name: "openai" }]); + expect(plan.entries).toMatchObject([{ key: "AGENTCORE_CREDENTIAL_OPENAI", value: "sk-x" }]); + expect(plan.unprovisioned).toEqual( + new Map([ + [ + "anthropic", + `ANTHROPIC_API_KEY is not set here or in ${ENV_LOCAL_RELATIVE_PATH}. Set ` + + "ANTHROPIC_API_KEY, or AGENTCORE_CREDENTIAL_ANTHROPIC, and build again.", + ], + ]), + ); }); test("skips, with no message, a route whose variable an existing credential reserves", () => { @@ -185,23 +195,18 @@ describe("planBoxProfileCredentials", () => { shell({}), ); - expect(plan).toEqual({ messages: [], added: [], entries: [] }); + expect(plan).toEqual({ messages: [], added: [], entries: [], unprovisioned: new Map() }); }); - test("reports a route that uses a model-provider name or variable in another way", () => { + test("adds a credential for a route that uses a model-provider name or variable in another way", () => { const plan = planBoxProfileCredentials( spec(), [route("openai", "MY_KEY"), route("my-llm", "GEMINI_API_KEY")], shell({ MY_KEY: "k", GEMINI_API_KEY: "k" }), ); - expect(plan.added).toEqual([]); - expect(plan.messages).toEqual([ - "skipping box egress 'openai' (env://MY_KEY): 'openai' is a model-provider route; " + - "agentcore create declares its key", - "skipping box egress 'my-llm' (env://GEMINI_API_KEY): GEMINI_API_KEY is a model provider's " + - "key variable; agentcore create declares its key", - ]); + expect(plan.added.map(({ name }) => name)).toEqual(["openai", "my-llm"]); + expect(plan.unprovisioned.size).toBe(0); }); test("reports, but does not add, a name that is not a valid credential name", () => { @@ -215,6 +220,9 @@ describe("planBoxProfileCredentials", () => { expect(plan.messages).toEqual([ "skipping box egress 'bad name!' (env://SOME_KEY): 'bad name!' is not a valid credential name", ]); + expect(plan.unprovisioned.get("bad name!")).toBe( + "'bad name!' is not a valid credential name. Rename the entry.", + ); }); test("reports, but does not add, a name that ends in a credential field suffix", () => { diff --git a/src/core/project/boxProfileCredentials.ts b/src/core/project/boxProfileCredentials.ts index b289357d4..721d62066 100644 --- a/src/core/project/boxProfileCredentials.ts +++ b/src/core/project/boxProfileCredentials.ts @@ -8,7 +8,6 @@ import { import type { ProjectSpec } from "../../projectSchemas/project"; import type { EnvLocalEntry } from "../../handlers/project/types"; import { hasValue, type BoxEnvRoute } from "./boxProfileEgress"; -import { MODEL_PROVIDER_EGRESS_ROUTES, MODEL_PROVIDER_KEY_VARIABLES } from "./templates/boxProfile"; import { ENV_LOCAL_RELATIVE_PATH } from "./envLocal"; /** @@ -28,6 +27,11 @@ export type BoxCredentialPlan = { added: Credential[]; /** The `.env.local` entries that store each key under its credential's reserved variable. */ entries: EnvLocalEntry[]; + /** + * By route, why no API key credential holds the key of a route that gets none, and what to do, + * in whole sentences. + */ + unprovisioned: Map; }; /** @@ -60,15 +64,16 @@ export function boxEgressCredentialName( * * Mutates `spec.credentials` in place, and is idempotent. It skips, with no message: * - a route whose variable an existing credential reserves: that credential holds the key; - * - a model-provider route as `agentcore create` writes it (`openai`, `anthropic`, `gemini` or - * `openai-compatible`, reading the provider variable such as `OPENAI_API_KEY`): its key is - * the variable LiteLLM reads, not a credential; * - a route named for an API key credential that keeps its key in Secrets Manager. * - * It skips, with a message, a route that uses a model-provider name or variable in any other way, - * and a route whose name `agentcore credentials add` would refuse: a name that is not a valid - * credential name, that ends in a credential field suffix, that derives the same variable as an - * existing credential, or that names a credential which is not an API key credential. + * A model-provider route that `agentcore create` writes with no key (`openai` reading + * `OPENAI_API_KEY`) is a route like any other: on AgentCore Runtime its gateway target sends the + * key of its credential. + * + * It skips, with a message, a route whose name `agentcore credentials add` would refuse: a name + * that is not a valid credential name, that ends in a credential field suffix, that derives the + * same variable as an existing credential, or that names a credential which is not an API key + * credential. */ export function planBoxProfileCredentials( spec: ProjectSpec, @@ -91,6 +96,7 @@ export function planBoxProfileCredentials( const messages: string[] = []; const added: Credential[] = []; const entries: EnvLocalEntry[] = []; + const unprovisioned = new Map(); /** * Stores the route's key under `credential`'s reserved variable, as `agentcore dev` reads it: the * route's variable from the environment, else from `.env.local`. A stored key that differs is @@ -128,20 +134,11 @@ export function planBoxProfileCredentials( for (const entry of routes) { const { route, variable } = entry; if (reservedVars.has(variable)) continue; - const providerName = MODEL_PROVIDER_EGRESS_ROUTES.has(route); - const providerVariable = MODEL_PROVIDER_KEY_VARIABLES.has(variable); - if (providerName && providerVariable) continue; - const skip = (reason: string) => + const skip = (reason: string, fix = "Rename the entry.") => { messages.push(`skipping box egress '${route}' (env://${variable}): ${reason}`); - if (providerName || providerVariable) { - skip( - providerName - ? `'${route}' is a model-provider route; agentcore create declares its key` - : `${variable} is a model provider's key variable; agentcore create declares its key`, - ); - continue; - } + unprovisioned.set(route, `${reason[0]!.toUpperCase()}${reason.slice(1)}. ${fix}`); + }; const existing = spec.credentials.find((credential) => credential.name === route); if (existing !== undefined) { if (existing.authorizerType !== "ApiKeyCredentialProvider") { @@ -183,6 +180,11 @@ export function planBoxProfileCredentials( `set here or in ${ENV_LOCAL_RELATIVE_PATH}, so deploy could not provision it. ` + `Set ${toSet(variable, route)} and build again`, ); + unprovisioned.set( + route, + `${variable} is not set here or in ${ENV_LOCAL_RELATIVE_PATH}. Set ` + + `${toSet(variable, route)} and build again.`, + ); continue; } @@ -195,5 +197,5 @@ export function planBoxProfileCredentials( "so deploy provisions it in AgentCore Identity", ); } - return { messages, added, entries }; + return { messages, added, entries, unprovisioned }; } diff --git a/src/core/project/manager.boxNetwork.test.ts b/src/core/project/manager.boxNetwork.test.ts index 006c052d4..45e72ffe1 100644 --- a/src/core/project/manager.boxNetwork.test.ts +++ b/src/core/project/manager.boxNetwork.test.ts @@ -13,6 +13,7 @@ import type { DeployBackendInput, ProjectBackend } from "./backends/types"; import { boxShowOf, FakeBoxProfileResolver } from "./boxProfileResolver-test-support"; import type { ResolvedBoxProfile } from "./boxProfileResolver"; import { seedBoxCache } from "./backends/box-release-test-support"; +import { ENV_LOCAL_RELATIVE_PATH, EnvLocalFile } from "./envLocal"; import { boxGatewayLogsNotice, FsProjectManager } from "./manager"; /** The golden files of this suite; `RECORD=1 bun test ` rewrites them, with no AWS call. */ @@ -346,14 +347,15 @@ describe("build writes the Box network of the box profile", () => { await editProfile(root, { tables: GITHUB_ROUTE }); box.answer = shows({ github: GITHUB }); - const { steps } = await build(manager, root); + const { steps, warnings } = await build(manager, root); expect(await targetNames(root)).toEqual(["bedrock", "agentcore"]); expect(JSON.parse(await text(root, SPEC)).credentials ?? []).toEqual([]); - expect(steps).toContain( - `not adding gateway target 'egress-github' of '${GATEWAY}' for api.github.com: it sends ` + - "the key of env://GITHUB_TOKEN, and agentcore.json has no API key credential 'github' " + - "to hold it", + expect(steps.some((step) => step.startsWith("not adding gateway target"))).toBe(false); + expect(warnings).toContain( + "api.github.com: build gives [egress.github] no gateway target, so the agent cannot reach " + + `this host on AgentCore Runtime. GITHUB_TOKEN is not set here or in ${ENV_LOCAL_RELATIVE_PATH}. ` + + "Set GITHUB_TOKEN, or AGENTCORE_CREDENTIAL_GITHUB, and build again.", ); // With no target, the Runtime profile has no route to api.github.com, as the old renderer. const egress = (await runtimeProfile(root)).egress as Record< @@ -363,6 +365,35 @@ describe("build writes the Box network of the box profile", () => { expect(Object.keys(egress).sort()).toEqual(["agentcore", "bedrock"]); }); + test("writes the target of a model-provider route once its key is set, as the warning says", async () => { + const { manager, root, box } = await strandsProject(); + const openai = { + destinations: ["api.openai.com"], + secret: { ref: "env://OPENAI_API_KEY" }, + }; + await editProfile(root, { + tables: + '\n[egress.openai]\ndestinations = ["api.openai.com"]\n' + + 'secret.ref = "env://OPENAI_API_KEY"\n', + }); + box.answer = shows({ openai }); + + const first = await build(manager, root); + expect(await targetNames(root)).toEqual(["bedrock", "agentcore"]); + expect(first.warnings).toContain( + "api.openai.com: build gives [egress.openai] no gateway target, so the agent cannot reach " + + `this host on AgentCore Runtime. OPENAI_API_KEY is not set here or in ${ENV_LOCAL_RELATIVE_PATH}. ` + + "Set OPENAI_API_KEY, or AGENTCORE_CREDENTIAL_OPENAI, and build again.", + ); + + await new EnvLocalFile(root).insertIfNew([ + { key: "OPENAI_API_KEY", value: "sk-test", comment: "the key the agent reads locally" }, + ]); + const second = await build(manager, root); + expect(await targetNames(root)).toEqual(["bedrock", "agentcore", "egress-openai"]); + expect(second.warnings.filter((w) => w.startsWith("api.openai.com"))).toEqual([]); + }); + test("changes nothing on a second build", async () => { const { manager, root, counter, box } = await strandsProject({ env: { GITHUB_TOKEN: "ghp_123" }, @@ -436,13 +467,13 @@ describe("build writes the Box network of the box profile", () => { }); box.answer = boxShowOf({ egress: { bedrock: BEDROCK }, mcp: { tools } }); - const { steps } = await build(manager, root); + const { warnings } = await build(manager, root); expect(await targetNames(root)).toEqual(["bedrock", "agentcore"]); - expect(steps).toContain( - `not adding gateway target 'egress-tools' of '${GATEWAY}' for tools.example.com: it sends ` + - "the key of env://TOOLS_TOKEN, and agentcore.json has no API key credential 'tools' " + - "to hold it", + expect(warnings).toContain( + "tools.example.com: build gives [mcp.tools] no gateway target, so the agent cannot reach " + + `this host on AgentCore Runtime. TOOLS_TOKEN is not set here or in ${ENV_LOCAL_RELATIVE_PATH}. ` + + "Set TOOLS_TOKEN, or AGENTCORE_CREDENTIAL_TOOLS, and build again.", ); // With no target, the Runtime profile has no [mcp.tools] server, as it has no route above. expect((await runtimeProfile(root)).mcp).toBeUndefined(); diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx index d7c3b9bbe..c66aa0275 100644 --- a/src/core/project/manager.tsx +++ b/src/core/project/manager.tsx @@ -58,7 +58,12 @@ import { boxGatewayIamWarnings, type BoxNetwork } from "./boxNetwork"; import { boxNetworkFailureMessage, readBoxNetworks } from "./boxNetworkSource"; import { DEFAULT_REGION, regionFromConfigFile } from "../region"; import { BoxCliProfileResolver, type BoxProfileResolver } from "./boxProfileResolver"; -import { BOX_NETWORK_WRITERS, boxNetworkEdits, writeBoxNetworkFiles } from "./boxNetworkWriters"; +import { + BOX_NETWORK_WRITERS, + boxNetworkEdits, + unsentTargetWarnings, + writeBoxNetworkFiles, +} from "./boxNetworkWriters"; import { createProjectTree } from "./templates/project"; import { BOX_CODEZIP_ENTRYPOINT, @@ -1679,12 +1684,13 @@ export class FsProjectManager implements ProjectManager { throw new InputValidationError(boxNetworkFailureMessage(networks, command)); } const envLocal = new EnvLocalFile(project.rootPath); - const edits = boxNetworkEdits(BOX_NETWORK_WRITERS, networks, { + const context = { spec: project.spec, projectRoot: project.rootPath, env: this.processEnv, envLocal: networks.length > 0 ? await envLocal.read() : {}, - }); + }; + const edits = boxNetworkEdits(BOX_NETWORK_WRITERS, networks, context); const messages = [...edits.messages]; let result = project; if (edits.specChanged) { @@ -1721,10 +1727,13 @@ export class FsProjectManager implements ProjectManager { const { written } = await envLocal.upsert([...edits.envLocal]); for (const key of written) messages.push(`writing ${key} to ${ENV_LOCAL_RELATIVE_PATH}`); } - const warnings = networks.flatMap((network) => [ - ...network.warnings, - ...boxGatewayIamWarnings(edits.spec, network), - ]); + const warnings = [ + ...networks.flatMap((network) => [ + ...network.warnings, + ...boxGatewayIamWarnings(edits.spec, network), + ]), + ...unsentTargetWarnings(networks, context), + ]; const events: ProjectEvent[] = [ ...messages.map((message) => ({ type: "step" as const, message })), ...warnings.map((message) => ({ type: "warning" as const, message })), diff --git a/src/core/project/templates/boxProfile.ts b/src/core/project/templates/boxProfile.ts index 231f59ed8..d078c272d 100644 --- a/src/core/project/templates/boxProfile.ts +++ b/src/core/project/templates/boxProfile.ts @@ -262,25 +262,6 @@ const GEMINI: ApiKeyRoute = { }; const OPENAI_COMPATIBLE_ROUTE = "openai-compatible"; -/** - * The `[egress.]` routes `agentcore create` writes for a model provider's API key. Their key - * is the project's model-provider credential, which `create` declares when it is given a key, or - * else a provider variable that LiteLLM reads; build does not declare a credential for them. - */ -export const MODEL_PROVIDER_EGRESS_ROUTES: ReadonlySet = new Set([ - OPENAI.name, - ANTHROPIC.name, - GEMINI.name, - OPENAI_COMPATIBLE_ROUTE, -]); - -/** The provider variables a model-provider route reads its key from when `create` had no key. */ -export const MODEL_PROVIDER_KEY_VARIABLES: ReadonlySet = new Set( - [OPENAI, ANTHROPIC, GEMINI].flatMap(({ providerVariable }) => - providerVariable === undefined ? [] : [providerVariable], - ), -); - /** * The route the agent's model calls take when they carry an API key, or * `undefined` when the agent calls Bedrock, calls no model, or calls a host the From 662b2eaa295aa1b649ae3e68776f52988e6bdb13 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 11:54:06 -0800 Subject: [PATCH 09/31] refactor(box): Refuse two box runtimes in one folder in the schema, and remove casts and copies Four smaller items of the review of the Box gateway targets: - Two box runtimes that stage box in one folder (two CodeZip runtimes with one code folder, or a container runtime whose build context is the code folder of another) made staging stop with a programmer error: "Box network writers 'runtime profile' and 'runtime profile' both write {...}/.box-dist/profile.toml". ProjectSpecSchema now refuses them, with the two runtimes and the folder, however the path is written (`./app/agent` and `app/agent/`). - network.ts imported boxGatewayAgentCoreHost from src/handlers/project/shortcuts.ts. The function is now in boxNetwork/egress.ts, beside the other AWS endpoint names, and shortcuts.ts imports it from there. - boxNetworkSource.ts read an IAM policy document through `as` casts. It now parses the document and each Allow statement with zod, and uses the shared isTable. The other casts there are gone. - boxCodeZip.ts and boxContainer.ts each had a copy of the step that writes the Runtime profile into the staged folder and into .box//aws/. Both now use stagedRuntimeProfiles in boxStaging.ts, in the same order as before. Not done here: the box model is still on the generic ProjectBackend input (backends/types.ts `boxNetworks`), and boxNetworkSource.ts still imports DEFAULT_EGRESS_BEDROCK_REGION from src/handlers/. Both need the Box gateway constants out of shortcuts.ts, which is an item of [aws/agentcore-cli#2789](https://github.com/aws/agentcore-cli/pull/2789). Tests: project.test.ts "Box runtimes and the folder build stages box in" (3 tests); boxNetworkSource.test.ts "counts the actions of an Allow statement in each form IAM takes, and of no other". The staging, network, and manager suites pass with no change. Mutations: no folder rule, no path normalization, and any Effect counted each make a test fail. --- src/core/project/backends/boxCodeZip.ts | 21 +++------- src/core/project/backends/boxContainer.ts | 23 +++-------- src/core/project/backends/boxStaging.ts | 32 +++++++++++++++ src/core/project/boxNetwork/egress.ts | 5 +++ src/core/project/boxNetwork/network.ts | 2 +- src/core/project/boxNetworkSource.test.ts | 27 +++++++++++++ src/core/project/boxNetworkSource.ts | 41 ++++++++++++------- src/handlers/project/shortcuts.ts | 6 +-- src/projectSchemas/project.test.ts | 49 +++++++++++++++++++++++ src/projectSchemas/project.ts | 44 ++++++++++++++++++++ 10 files changed, 196 insertions(+), 54 deletions(-) diff --git a/src/core/project/backends/boxCodeZip.ts b/src/core/project/backends/boxCodeZip.ts index 2f2e7b7a7..d1108005c 100644 --- a/src/core/project/backends/boxCodeZip.ts +++ b/src/core/project/backends/boxCodeZip.ts @@ -2,14 +2,9 @@ import { chmodSync, copyFileSync, cpSync, mkdirSync, rmSync, writeFileSync } fro import { join, posix } from "node:path"; import type { Project } from "../../../handlers/project/types"; import type { BoxNetwork } from "../boxNetwork"; -import { - boxNetworkEdits, - runtimeProfileWriter, - writeBoxNetworkFiles, - writeRenderedBoxFiles, -} from "../boxNetworkWriters"; import { BOX_CODEZIP_DIST, runtimeRunsInBox } from "../templates/boxProfile"; import { BOX_BINARIES, type BoxLinuxBuild } from "./boxRelease"; +import { stagedRuntimeProfiles } from "./boxStaging"; /** The `.gitignore` staged into `.box-dist/`: build and deploy rewrite the folder every time. */ export const BOX_DIST_GITIGNORE = @@ -40,13 +35,7 @@ export async function stageBoxCodeZip( // @box/agentcore and @box/agentcore-codezip packs. kind: "codezip" as const, })); - const { files } = boxNetworkEdits([runtimeProfileWriter(staged)], networks, { - spec: project.spec, - projectRoot: project.rootPath, - env: {}, - envLocal: {}, - }); - const filesOf = (dist: string) => files.filter(({ path }) => path.startsWith(`${dist}/`)); + const writeProfile = stagedRuntimeProfiles(project, networks, staged); // One build for each box version the runtimes name, so each downloads once. const builds = new Map(); for (const runtime of runtimes) { @@ -54,7 +43,8 @@ export async function stageBoxCodeZip( if (!builds.has(version)) builds.set(version, await box(version)); } - for (const { runtime, dist } of staged) { + for (const stage of staged) { + const { runtime, dist } = stage; const entry = runtimes.find(({ name }) => name === runtime)!; const build = builds.get(entry.box?.version)!; const folder = join(project.rootPath, ...dist.split("/")); @@ -68,8 +58,7 @@ export async function stageBoxCodeZip( chmodSync(join(folder, binary), 0o755); } cpSync(build.resources, join(folder, "resources"), { recursive: true }); - writeBoxNetworkFiles(project.rootPath, filesOf(dist)); - writeRenderedBoxFiles(project.rootPath, runtime, dist, filesOf(dist)); + writeProfile(stage); } return runtimes.map((runtime) => runtime.name); } diff --git a/src/core/project/backends/boxContainer.ts b/src/core/project/backends/boxContainer.ts index 800769361..1ae29ffc2 100644 --- a/src/core/project/backends/boxContainer.ts +++ b/src/core/project/backends/boxContainer.ts @@ -4,16 +4,10 @@ import { dirname, join, posix } from "node:path"; import type { Project } from "../../../handlers/project/types"; import type { ProjectRuntime } from "../../../projectSchemas/runtime"; import type { BoxNetwork } from "../boxNetwork"; -import { - boxNetworkEdits, - runtimeProfileWriter, - writeBoxNetworkFiles, - writeRenderedBoxFiles, -} from "../boxNetworkWriters"; import { isFile } from "../runtimeBuild"; import { runtimeRunsInBox } from "../templates/boxProfile"; import type { BoxRelease } from "./boxRelease"; -import { assertImageCopiesPolicyFiles } from "./boxStaging"; +import { assertImageCopiesPolicyFiles, stagedRuntimeProfiles } from "./boxStaging"; /** The folder a box image's Dockerfile copies its box profile and policy files from. */ export const BOX_IMAGE_DIST = ".box-dist"; @@ -130,13 +124,7 @@ export async function stageBoxContainers( dist: posix.join(runtime.buildContextPath ?? runtime.codeLocation, BOX_IMAGE_DIST), kind: "container" as const, })); - const { files } = boxNetworkEdits([runtimeProfileWriter(staged)], networks, { - spec: project.spec, - projectRoot: project.rootPath, - env: {}, - envLocal: {}, - }); - const filesOf = (dist: string) => files.filter(({ path }) => path.startsWith(`${dist}/`)); + const writeProfile = stagedRuntimeProfiles(project, networks, staged); for (const runtime of runtimes) { const policyFiles = networks.find((n) => n.runtime === runtime.name)?.policyFiles ?? []; assertImageCopiesPolicyFiles( @@ -145,15 +133,14 @@ export async function stageBoxContainers( policyFiles, ); } - for (const [index, { dist }] of staged.entries()) { + for (const [index, stage] of staged.entries()) { const runtime = runtimes[index]!; - const folder = join(project.rootPath, ...dist.split("/")); + const folder = join(project.rootPath, ...stage.dist.split("/")); await rm(folder, { recursive: true, force: true }); await mkdir(folder, { recursive: true }); const release = await releaseFor(runtime.box?.version); await writeFile(join(folder, BOX_RELEASE_ENV), boxReleaseEnv(release)); - writeBoxNetworkFiles(project.rootPath, filesOf(dist)); - writeRenderedBoxFiles(project.rootPath, runtime.name, dist, filesOf(dist)); + writeProfile(stage); } return runtimes.map((runtime) => runtime.name); } diff --git a/src/core/project/backends/boxStaging.ts b/src/core/project/backends/boxStaging.ts index 250d191eb..0e2162a34 100644 --- a/src/core/project/backends/boxStaging.ts +++ b/src/core/project/backends/boxStaging.ts @@ -1,7 +1,39 @@ import { readFileSync } from "node:fs"; import { ProjectStateError } from "../../../errors/errors"; +import type { Project } from "../../../handlers/project/types"; +import type { BoxNetwork } from "../boxNetwork"; +import { + boxNetworkEdits, + runtimeProfileWriter, + writeBoxNetworkFiles, + writeRenderedBoxFiles, + type StagedRuntime, +} from "../boxNetworkWriters"; import { boxLocalProfileFile } from "../templates/boxProfile"; +/** + * What the runtime profile writer writes from each runtime's Box network model for the runtimes of + * `staged`, with the function that writes one runtime's files into its staged folder and a copy + * into its `.box//aws/`. + */ +export function stagedRuntimeProfiles( + project: Project, + networks: readonly BoxNetwork[], + staged: readonly StagedRuntime[], +): (runtime: StagedRuntime) => void { + const { files } = boxNetworkEdits([runtimeProfileWriter(staged)], networks, { + spec: project.spec, + projectRoot: project.rootPath, + env: {}, + envLocal: {}, + }); + return ({ runtime, dist }) => { + const own = files.filter(({ path }) => path.startsWith(`${dist}/`)); + writeBoxNetworkFiles(project.rootPath, own); + writeRenderedBoxFiles(project.rootPath, runtime, dist, own); + }; +} + /** A `COPY` of the whole staged folder, which takes the policy files in with the profile. */ const COPIES_WHOLE_DIST = /^\s*COPY\s+(?:--\S+\s+)*(?:\.box-dist|\$\{BOX_DIST\})\/?\s/m; diff --git a/src/core/project/boxNetwork/egress.ts b/src/core/project/boxNetwork/egress.ts index 3a9dcbd16..a096da5c8 100644 --- a/src/core/project/boxNetwork/egress.ts +++ b/src/core/project/boxNetwork/egress.ts @@ -134,6 +134,11 @@ const AWS_ENDPOINTS = [ }, ] as const; +/** The AgentCore data-plane host of `region`, which the Box gateway's AgentCore target fronts. */ +export function boxGatewayAgentCoreHost(region: string): string { + return `bedrock-agentcore.${region}.amazonaws.com`; +} + /** The API of an AWS endpoint that the gateway signs for. */ export type AwsEndpointApi = (typeof AWS_ENDPOINTS)[number]["api"]; diff --git a/src/core/project/boxNetwork/network.ts b/src/core/project/boxNetwork/network.ts index 172183397..495819e27 100644 --- a/src/core/project/boxNetwork/network.ts +++ b/src/core/project/boxNetwork/network.ts @@ -4,7 +4,6 @@ * the policy files to stage, and every warning and failure. Build, deploy, and staging write from * it. */ -import { boxGatewayAgentCoreHost } from "../../../handlers/project/shortcuts"; import { credentialEnvVarName } from "../../../projectSchemas/credential"; import type { AgentCoreGateway, AgentCoreGatewayTarget } from "../../../projectSchemas/gateway"; import type { ProjectSpec } from "../../../projectSchemas/project"; @@ -16,6 +15,7 @@ import { buildHostMap, entryLabel, entryRef, type MappedHost } from "./hostMap"; import { BOX_EGRESS_TARGET_PREFIX, awsEndpoint, + boxGatewayAgentCoreHost, outboundAuthFor, parseEndpoint, targetNameFor, diff --git a/src/core/project/boxNetworkSource.test.ts b/src/core/project/boxNetworkSource.test.ts index f3d9afcaf..ec9b3acde 100644 --- a/src/core/project/boxNetworkSource.test.ts +++ b/src/core/project/boxNetworkSource.test.ts @@ -533,6 +533,33 @@ describe("the IAM policy files of the Box gateway", () => { ]); }); + test("counts the actions of an Allow statement in each form IAM takes, and of no other", async () => { + const root = await project([]); + await mkdir(join(root, "agentcore")); + const files: Record = { + one: { Statement: { Effect: "Allow", Action: "lambda:InvokeFunctionUrl" } }, + mixed: { Statement: [{ Effect: "Deny", Action: "s3:*" }, null, "text", { Effect: "Allow" }] }, + none: { Version: "2012-10-17" }, + }; + for (const [name, document] of Object.entries(files)) { + await writeFile(join(root, "agentcore", `${name}.json`), JSON.stringify(document)); + } + const spec = { + ...SPEC, + agentCoreGateways: [ + { + ...boxGatewaySpec("agent"), + additionalPolicies: Object.keys(files).map((name) => `agentcore/${name}.json`), + }, + ], + } as unknown as ProjectSpec; + + const [network] = await readBoxNetworks(spec, root, new FakeBoxProfileResolver()); + + expect(network?.grantedActions).toEqual(["lambda:InvokeFunctionUrl"]); + expect(network?.warnings).toEqual([]); + }); + test("gives no warning for the Memory policy file that build writes before it writes it", async () => { const root = await project([]); const spec = { diff --git a/src/core/project/boxNetworkSource.ts b/src/core/project/boxNetworkSource.ts index af3e8c6b7..1989275f8 100644 --- a/src/core/project/boxNetworkSource.ts +++ b/src/core/project/boxNetworkSource.ts @@ -8,6 +8,7 @@ import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { dirname, isAbsolute, join, relative, sep } from "node:path"; import { parse as parseToml, stringify as stringifyToml } from "smol-toml"; +import { z } from "zod"; import { credentialEnvVarName } from "../../projectSchemas/credential"; import type { ProjectSpec } from "../../projectSchemas/project"; import type { ProjectRuntime } from "../../projectSchemas/runtime"; @@ -37,6 +38,7 @@ import { } from "./boxNetwork"; import type { BoxProfileResolver, ResolvedBoxProfile } from "./boxProfileResolver"; import { profileKeyPlaces } from "./runtimeProfile/context"; +import { isTable } from "./runtimeProfile/projectPaths"; import type { TomlTable } from "./runtimeProfile/types"; /** The policy of an agent that has no local box profile at `profilePath`. */ @@ -246,7 +248,7 @@ async function readResolvedPolicy( */ function profileSource(text: string, profileFile: string): ParsedProfileSource | undefined { try { - return { table: parseToml(text) as TomlTable, places: profileKeyPlaces(text, profileFile) }; + return { table: parseToml(text), places: profileKeyPlaces(text, profileFile) }; } catch { return undefined; } @@ -260,9 +262,6 @@ function profileText(projectRoot: string, agentName: string): string | undefined return existsSync(path) ? readFileSync(path, "utf8") : undefined; } -const isTable = (value: unknown): value is Record => - typeof value === "object" && value !== null && !Array.isArray(value); - /** The `[options] bedrock.region` of the profile `table`, as a dotted or a quoted key. */ function bedrockRegionOf(table: Record): unknown { const options = isTable(table.options) ? table.options : {}; @@ -277,9 +276,9 @@ function bedrockRegionOf(table: Record): unknown { * region. An edit of the line that sets the region keeps every other line where it is. */ function profileForRegion(text: string, region: string): string | undefined { - let table: Record; + let table: TomlTable; try { - table = parseToml(text) as Record; + table = parseToml(text); } catch { return undefined; } @@ -423,6 +422,15 @@ function policyFileProblem( return undefined; } +/** The part of an IAM policy document that build reads: one statement, or a list of them. */ +const PolicyDocumentSchema = z.object({ Statement: z.unknown().optional() }); + +/** An Allow statement, with the action or the list of actions it names. */ +const AllowStatementSchema = z.object({ + Effect: z.literal("Allow"), + Action: z.union([z.string(), z.array(z.unknown())]), +}); + /** The policy files that build writes for the gateway's role. */ const BUILD_POLICY_FILES: ReadonlySet = new Set([ BOX_BEDROCK_POLICY_FILE, @@ -453,7 +461,7 @@ function grantedActions( try { text = readFileSync(join(projectRoot, ...policy.split("/")), "utf8"); } catch (error) { - const code = (error as NodeJS.ErrnoException).code; + const code = error instanceof Error && "code" in error ? String(error.code) : undefined; if (code === "ENOENT") { skipped("does not exist", "Create it, or remove it from additionalPolicies."); } else { @@ -468,18 +476,23 @@ function grantedActions( try { document = JSON.parse(text); } catch (error) { - skipped(`is not valid JSON (${(error as Error).message})`, "Correct the JSON."); + skipped( + `is not valid JSON (${error instanceof Error ? error.message : String(error)})`, + "Correct the JSON.", + ); continue; } - if (typeof document !== "object" || document === null || Array.isArray(document)) { + const policyDocument = PolicyDocumentSchema.safeParse(document); + if (!policyDocument.success) { skipped("is not a JSON object", "Make it an IAM policy document."); continue; } - const { Statement } = document as { Statement?: unknown }; - const statements = Array.isArray(Statement) ? Statement : [Statement]; - for (const statement of statements as { Effect?: unknown; Action?: unknown }[]) { - if (statement?.Effect !== "Allow") continue; - const named = Array.isArray(statement.Action) ? statement.Action : [statement.Action]; + const { Statement } = policyDocument.data; + for (const statement of Array.isArray(Statement) ? Statement : [Statement]) { + const allow = AllowStatementSchema.safeParse(statement); + if (!allow.success) continue; + const { Action } = allow.data; + const named = Array.isArray(Action) ? Action : [Action]; actions.push(...named.filter((action): action is string => typeof action === "string")); } } diff --git a/src/handlers/project/shortcuts.ts b/src/handlers/project/shortcuts.ts index 4fc90438e..7f164aeec 100644 --- a/src/handlers/project/shortcuts.ts +++ b/src/handlers/project/shortcuts.ts @@ -5,6 +5,7 @@ import { defaultMemoryName, type Memory, } from "../../projectSchemas/memory"; +import { boxGatewayAgentCoreHost } from "../../core/project/boxNetwork/egress"; import { InputValidationError } from "../../errors"; import type { AgentCoreGatewayTarget } from "../../projectSchemas/gateway"; import { DEFAULT_MODEL_IDS } from "../../projectSchemas/runtime"; @@ -59,11 +60,6 @@ export function getBoxGatewayBedrockTargetSpec( */ export const BOX_GATEWAY_AGENTCORE_TARGET_NAME = "agentcore"; -/** The AgentCore data-plane host of `region`, which the Box gateway's AgentCore target fronts. */ -export function boxGatewayAgentCoreHost(region: string = DEFAULT_EGRESS_BEDROCK_REGION): string { - return `bedrock-agentcore.${region}.amazonaws.com`; -} - /** * The Box gateway's passthrough target for the AgentCore data plane (Memory), * signed with the gateway's role. diff --git a/src/projectSchemas/project.test.ts b/src/projectSchemas/project.test.ts index d643bb33d..683e5a378 100644 --- a/src/projectSchemas/project.test.ts +++ b/src/projectSchemas/project.test.ts @@ -594,6 +594,55 @@ describe("Box project gateways", () => { }); }); +describe("Box runtimes and the folder build stages box in", () => { + const boxed = (name: string, rest: Record = {}) => ({ + ...runtime, + name, + box: { version: "0.1.11-preview.10" }, + ...rest, + }); + const parse = (runtimes: { name: string }[]) => + ProjectSpecSchema.safeParse({ + ...minimalProject, + projectType: "box", + runtimes, + agentCoreGateways: runtimes.map(({ name }) => boxGatewaySpec(name)), + }); + const messages = (result: ReturnType) => + result.success ? [] : result.error.issues.map(({ message }) => message); + + test("rejects two box runtimes in one folder, however the path is written", () => { + expect( + messages( + parse([ + boxed("agent", { codeLocation: "./app/agent" }), + boxed("search", { codeLocation: "app/agent/" }), + ]), + ), + ).toEqual([ + 'Runtimes "agent" and "search" both run in a box from the folder app/agent, and build ' + + "stages the box of each in app/agent/.box-dist. Give each runtime its own folder.", + ]); + }); + + test("rejects a container runtime whose build context is the code folder of another", () => { + const container = boxed("image", { + build: "Container", + codeLocation: "./image", + buildContextPath: "./app/agent", + }); + expect(messages(parse([boxed("agent", { codeLocation: "app/agent" }), container]))).toEqual([ + 'Runtimes "agent" and "image" both run in a box from the folder app/agent, and build ' + + "stages the box of each in app/agent/.box-dist. Give each runtime its own folder.", + ]); + }); + + test("accepts one folder for a box runtime and a runtime that runs in no box", () => { + const plain = { ...runtime, name: "plain", codeLocation: "app/agent" }; + expect(parse([boxed("agent", { codeLocation: "app/agent" }), plain]).success).toBe(true); + }); +}); + describe("gateway variable prefixes", () => { const parse = (agentCoreGateways: unknown[]) => ProjectSpecSchema.safeParse({ ...minimalProject, runtimes: [runtime], agentCoreGateways }); diff --git a/src/projectSchemas/project.ts b/src/projectSchemas/project.ts index d0c472422..3cde3ae48 100644 --- a/src/projectSchemas/project.ts +++ b/src/projectSchemas/project.ts @@ -31,6 +31,29 @@ export const ProjectNameSchema = z export const ProjectTypeSchema = z.enum(["box"]); /** Whether the project is a Box project, so the CLI keeps a Box gateway for each runtime. */ export const isBoxProject = (spec: { projectType?: string }) => spec.projectType === "box"; + +/** + * The folder, from the project root, that build stages the box of a box runtime in: the code + * folder of a CodeZip runtime, and the build context of a container runtime. + */ +function boxFolderOf(runtime: { + readonly build: string; + readonly codeLocation: string; + readonly buildContextPath?: string; +}): string { + const folder = + runtime.build === "Container" + ? (runtime.buildContextPath ?? runtime.codeLocation) + : runtime.codeLocation; + const parts: string[] = []; + for (const part of folder.replace(/\\/g, "/").split("/")) { + if (part === "" || part === ".") continue; + if (part === ".." && parts.length > 0 && parts.at(-1) !== "..") parts.pop(); + else parts.push(part); + } + return parts.length > 0 ? parts.join("/") : "."; +} + /** The suffix of each Box gateway name: the runtime `agent` gets the gateway `agent-box-egress`. */ export const BOX_GATEWAY_SUFFIX = "-box-egress"; /** @@ -164,6 +187,27 @@ export const ProjectSpecSchema = z // A Box project keeps one Box gateway for each runtime. Without it, a deploy would delete the // deployed gateway, so every command stops here and prints the entry to add back. if (isBoxProject(spec)) { + // Build stages the box of each box runtime in .box-dist of its folder, so two in one folder + // would write one file twice. + const byFolder = new Map(); + for (const runtime of spec.runtimes) { + if (runtime.box === undefined) continue; + const folder = boxFolderOf(runtime); + const other = byFolder.get(folder); + if (other === undefined) { + byFolder.set(folder, runtime.name); + continue; + } + ctx.addIssue({ + code: "custom", + message: + `Runtimes "${other}" and "${runtime.name}" both run in a box from the folder ` + + `${folder}, and build stages the box of each in ` + + `${folder === "." ? "" : `${folder}/`}.box-dist. ` + + "Give each runtime its own folder.", + path: ["runtimes"], + }); + } const bound = new Set(spec.agentCoreGateways.map((gateway) => gateway.boundRuntime)); for (const runtime of spec.runtimes) { if (bound.has(runtime.name)) continue; From 8942a80299ed87b29bc4a349e126f503655395bc Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 12:05:09 -0800 Subject: [PATCH 10/31] fix(box): Own only the gateway targets that build recorded, and keep a user's egress- target Build took each gateway target whose name starts with `egress-` as its own, by the name alone (isManagedTarget, writeGatewayTargets, and the gateway rule of the Runtime profile). So it changed or removed a target that a user added with that name, and stopped on one with another shape (MANAGED_TARGET_CHANGED). Build now records, in agentcore/box-gateway-targets.json, the targets that it writes for each Box gateway, by the gateway's name. It owns only the targets in that record: it adds, rewrites, and removes them, and it keeps each other target, whatever its name. MANAGED_TARGET_CHANGED now applies only to a recorded target, and it says to remove the name from the record to keep the target. The Box network model gives the writers and the Runtime profile one set of the targets build owns (BoxNetwork.managedTargets). A project that an older CLI built has no record of its gateway. For such a gateway, build takes as its own each `egress-` target that has exactly the shape build writes (a CUSTOM passthrough target to an https:// host, with one of the outbound auths build writes), once, and then writes the record. It keeps an `egress-` target of another shape as the user's. A target that build wrote and the user then changed is thus the user's. The record is a file beside agentcore.json and not a field in it: the L3 schema of agentcore.json is strict, so a new field stops synth until the L3 takes it. A malformed record stops build, names the file, and says to remove it. Tests: network.test.ts "the targets build owns" (4 tests); boxNetworkWriters.test.ts "keeps a user's egress- target that the record does not name, and records the targets it writes" and "records no file for a project with no box runtime"; boxNetworkSource.test.ts "the record of the targets build writes" (3 tests); manager.boxNetwork.test.ts "owns only the targets it records, after it takes its old egress- targets once", which also checks the route of the Runtime profile. manager.test.ts expects the new step "writing agentcore/box-gateway-targets.json". docs/box-local-testing.md says the new rule. Mutations: the record not read, every egress- target taken in an old project, and no owned set for the Runtime profile each make a test fail. --- docs/box-local-testing.md | 6 +- src/core/project/backends/boxCodeZip.test.ts | 1 + .../project/backends/boxContainer.test.ts | 1 + src/core/project/backends/cdk.test.ts | 1 + src/core/project/boxNetwork/index.ts | 1 + src/core/project/boxNetwork/network.test.ts | 100 ++++++++++------ src/core/project/boxNetwork/network.ts | 60 +++++++--- src/core/project/boxNetworkSource.test.ts | 50 ++++++++ src/core/project/boxNetworkSource.ts | 29 +++++ src/core/project/boxNetworkWriters.test.ts | 44 +++++++ src/core/project/boxNetworkWriters.ts | 107 ++++++++++++------ src/core/project/manager.boxNetwork.test.ts | 31 +++++ src/core/project/manager.test.ts | 1 + .../project/runtimeProfile/rules/gateway.ts | 6 +- src/core/project/runtimeProfile/types.ts | 7 +- 15 files changed, 360 insertions(+), 85 deletions(-) diff --git a/docs/box-local-testing.md b/docs/box-local-testing.md index a677b6852..c5710ec94 100644 --- a/docs/box-local-testing.md +++ b/docs/box-local-testing.md @@ -130,8 +130,10 @@ the generated packs, and the policy files into `.box//aws/` for you to - **Gateway targets.** Each host or `host:port` that an `[egress]` entry or a policy permit names, and that the policy allows at least one request to, gets one passthrough target on `-box-egress`. A host the gateway already has a target for keeps that target. Build owns - only the targets whose name starts with `egress-`: it adds them, changes them, and removes - one when no host needs it. It never changes another target. + only the targets it wrote, which it lists in `agentcore/box-gateway-targets.json`: it adds them, + changes them, and removes one when no host needs it. It never changes another target, also one + whose name starts with `egress-`. For a gateway that the file does not list, which an older CLI + built, build takes each `egress-` target that has the shape it writes as its own, once. - **Outbound auth.** An `aws://` secret signs with the gateway's role, an `env://` secret sends an API key from AgentCore Identity, and an entry with no secret sends no credential. - **Failures.** A wildcard host, a plain-HTTP-only host, an unsupported secret or pack, an diff --git a/src/core/project/backends/boxCodeZip.test.ts b/src/core/project/backends/boxCodeZip.test.ts index 36f99bc4d..101e1cea1 100644 --- a/src/core/project/backends/boxCodeZip.test.ts +++ b/src/core/project/backends/boxCodeZip.test.ts @@ -251,6 +251,7 @@ function model(policyFiles: string[], runtime = "agent"): BoxNetwork { region: "us-west-2", hosts: [], envRoutes: [], + managedTargets: new Set(), policyFiles, runtimeProfile: runtimeProfileOf(policyFiles, runtime), runtimeProfileHeader: [`Derived from .box/${runtime}/local/profile.toml.`], diff --git a/src/core/project/backends/boxContainer.test.ts b/src/core/project/backends/boxContainer.test.ts index 2bb9f1a03..d18a8ec37 100644 --- a/src/core/project/backends/boxContainer.test.ts +++ b/src/core/project/backends/boxContainer.test.ts @@ -174,6 +174,7 @@ function model(policyFiles: string[]): BoxNetwork { region: "us-west-2", hosts: [], envRoutes: [], + managedTargets: new Set(), policyFiles, runtimeProfile: { packs: ["@box/base", "@box/agentcore"], diff --git a/src/core/project/backends/cdk.test.ts b/src/core/project/backends/cdk.test.ts index 8466da265..daf34d1f4 100644 --- a/src/core/project/backends/cdk.test.ts +++ b/src/core/project/backends/cdk.test.ts @@ -388,6 +388,7 @@ describe("CdkBackend.build", () => { region: "us-west-2", hosts: [], envRoutes: [], + managedTargets: new Set(), policyFiles: [], runtimeProfile: { packs: ["@box/base", "@box/agentcore"] }, grantedActions: [], diff --git a/src/core/project/boxNetwork/index.ts b/src/core/project/boxNetwork/index.ts index af6e1596c..4c9dd46db 100644 --- a/src/core/project/boxNetwork/index.ts +++ b/src/core/project/boxNetwork/index.ts @@ -1,5 +1,6 @@ export { parseEndpoint } from "./egress"; export { + BOX_GATEWAY_TARGETS_FILE, boxGatewayIamWarnings, boxGatewayOf, buildBoxNetwork, diff --git a/src/core/project/boxNetwork/network.test.ts b/src/core/project/boxNetwork/network.test.ts index e6ced9c43..588b0c06e 100644 --- a/src/core/project/boxNetwork/network.test.ts +++ b/src/core/project/boxNetwork/network.test.ts @@ -45,6 +45,8 @@ interface Options { readonly credentials?: ProjectSpec["credentials"]; readonly grantedActions?: string[]; readonly executionRoleArn?: string; + /** The targets that agentcore/box-gateway-targets.json names for the gateway. */ + readonly ownedTargets?: ReadonlySet; } /** The local box profile of runtime `agent`. */ @@ -94,6 +96,7 @@ function model(policy: string, egress: Record = {}, options: Op region: "us-west-2", targets: options.targets ?? [], grantedActions: options.grantedActions ?? [], + ...(options.ownedTargets && { ownedTargets: options.ownedTargets }), }); return { spec, @@ -286,40 +289,71 @@ describe("the gateway's targets", () => { ]); }); - test("refuses to manage an egress- target that build would not write, and names it", () => { - const r = model( - "", - { github: GITHUB }, - { - targets: [ - passthrough("egress-github", "https://api.github.com", { - passthrough: { endpoint: "https://api.github.com", protocolType: "MCP" }, - }), - passthrough("egress-old", "https://old.example.com", { - outboundAuth: { - type: "API_KEY", - credentialName: "old", - location: "QUERY_PARAMETER", - parameterName: "key", - }, - }), - ], + describe("the targets build owns", () => { + const mcpTarget = passthrough("egress-github", "https://api.github.com", { + passthrough: { endpoint: "https://api.github.com", protocolType: "MCP" }, + }); + const queryKey = passthrough("egress-old", "https://old.example.com", { + outboundAuth: { + type: "API_KEY", + credentialName: "old", + location: "QUERY_PARAMETER", + parameterName: "key", }, - ); - expect(r.failures()).toEqual([ - ["MANAGED_TARGET_CHANGED", "egress-github"], - ["MANAGED_TARGET_CHANGED", "egress-old"], - ]); - expect(r.lines()).toEqual([ - "agentcore/agentcore.json The gateway target 'egress-github' has protocolType MCP, " + - 'which build does not write for a target whose name starts with "egress-", so build ' + - 'does not change or remove it. Rename it without "egress-" to keep it as yours, or ' + - "remove it so build writes it again.", - "agentcore/agentcore.json The gateway target 'egress-old' sends the API key credential " + - "'old' in the query parameter key, which build does not write for a target whose name " + - 'starts with "egress-", so build does not change or remove it. Rename it without ' + - '"egress-" to keep it as yours, or remove it so build writes it again.', - ]); + }); + + test("are the ones agentcore/box-gateway-targets.json names, and a user's egress- target is not", () => { + const r = model( + "", + { github: GITHUB }, + { + targets: [passthrough("egress-mine", "https://mine.example.com"), queryKey], + ownedTargets: new Set(), + }, + ); + expect(r.failures()).toEqual([]); + expect([...r.network.managedTargets]).toEqual(["egress-github"]); + }); + + test("fail a target the file names that the user changed, and say how to keep it", () => { + const r = model( + "", + { github: GITHUB }, + { + targets: [mcpTarget, queryKey], + ownedTargets: new Set(["egress-github", "egress-old"]), + }, + ); + expect(r.failures()).toEqual([ + ["MANAGED_TARGET_CHANGED", "egress-github"], + ["MANAGED_TARGET_CHANGED", "egress-old"], + ]); + expect(r.lines()[1]).toBe( + "agentcore/agentcore.json The gateway target 'egress-old' sends the API key credential " + + "'old' in the query parameter key, which build does not write, and " + + "agentcore/box-gateway-targets.json names it as a target that build writes, so build " + + "does not change or remove it. Remove 'egress-old' from that file to keep the target " + + "as yours, or remove the target so build writes it again.", + ); + }); + + test("are, for a gateway the file does not name, the egress- targets that build would write", () => { + const r = model( + "", + { github: GITHUB }, + { + targets: [passthrough("egress-stale", "https://stale.example.com"), queryKey], + }, + ); + expect(r.failures()).toEqual([]); + expect([...r.network.managedTargets]).toEqual(["egress-stale", "egress-github"]); + }); + + test("leave a user's target of another shape on an entry's host to the user", () => { + const r = model("", { github: GITHUB }, { targets: [mcpTarget] }); + expect(r.failures()).toEqual([["EXISTING_TARGET_CONFLICT", "github"]]); + expect([...r.network.managedTargets]).toEqual([]); + }); }); test("lets a new host take the name of an egress- target that no host takes now", () => { diff --git a/src/core/project/boxNetwork/network.ts b/src/core/project/boxNetwork/network.ts index 495819e27..700ac0b4d 100644 --- a/src/core/project/boxNetwork/network.ts +++ b/src/core/project/boxNetwork/network.ts @@ -44,6 +44,12 @@ export type { BoxNetworkFailure } from "./types"; /** Where a failure of a target in agentcore.json is. */ const PROJECT_SPEC_PLACE = "agentcore/agentcore.json"; +/** + * The file, from the project root, where build records the targets of each Box gateway that it + * writes, by the gateway's name. Build owns those targets, and no other. + */ +export const BOX_GATEWAY_TARGETS_FILE = "agentcore/box-gateway-targets.json"; + /** How the gateway authenticates its requests to a host. */ export type BoxEgressAuth = | { readonly kind: "none" } @@ -115,6 +121,11 @@ export interface BoxNetwork { readonly hosts: readonly BoxNetworkHost[]; /** The `env://` route of each target that sends an API key, for the credentials writer. */ readonly envRoutes: readonly BoxEnvRoute[]; + /** + * The targets of the gateway that build owns, which it adds, rewrites, and removes: each one it + * wrote before, and the new target of each host. Build keeps every other target as it is. + */ + readonly managedTargets: ReadonlySet; /** * The policy files, relative to the agent's local box folder, to copy beside the AgentCore * Runtime profile. @@ -155,6 +166,12 @@ export interface BoxNetworkProject { readonly targets: readonly AgentCoreGatewayTarget[]; /** The IAM actions that the gateway's `additionalPolicies` files grant, except build's own. */ readonly grantedActions: readonly string[]; + /** + * The targets that {@link BOX_GATEWAY_TARGETS_FILE} names for the gateway. Absent when the file + * does not name the gateway, which build last built before it kept the file: then build owns each + * target whose name starts with `egress-` and that has the shape build writes. + */ + readonly ownedTargets?: ReadonlySet; } /** The Box gateway of `runtime`: the gateway bound to it. */ @@ -206,7 +223,7 @@ export function buildBoxNetwork( runtime: project.runtime, profileFile: parsed.profile.path, region: project.region, - gateway: { name: project.gateway, targets: project.targets }, + gateway: { name: project.gateway, targets: project.targets, managed: targets.managed }, hosts: targets.hosts, telemetry: telemetry?.telemetry ?? [], ruleIds: new Set( @@ -229,6 +246,7 @@ export function buildBoxNetwork( region: project.region, hosts: targets.hosts, envRoutes: envRoutesOf(targets.hosts), + managedTargets: targets.managed, policyFiles: parsed.profile.policyFiles, ...(telemetry && { telemetry: telemetry.telemetry }), ...(derived && @@ -279,9 +297,12 @@ function envRoutesOf(hosts: readonly BoxNetworkHost[]): BoxEnvRoute[] { return routes; } -/** Whether build manages `target`: it adds, changes, and removes each target with the prefix. */ -export function isManagedTarget(target: Pick): boolean { - return target.name.startsWith(BOX_EGRESS_TARGET_PREFIX); +/** + * Whether build owns `target` of a gateway that {@link BOX_GATEWAY_TARGETS_FILE} does not name: its + * name starts with `egress-`, and it has the shape build writes. + */ +export function isManagedTarget(target: AgentCoreGatewayTarget): boolean { + return target.name.startsWith(BOX_EGRESS_TARGET_PREFIX) && unmanagedShape(target) === undefined; } /** The host map key of a passthrough target's endpoint, or `undefined` for another target. */ @@ -337,20 +358,27 @@ function hostTargets( project: BoxNetworkProject, located: (failure: ConversionFailure) => BoxNetworkFailure, profilePath: string, -): { hosts: BoxNetworkHost[]; failures: BoxNetworkFailure[] } { +): { + hosts: BoxNetworkHost[]; + failures: BoxNetworkFailure[]; + managed: ReadonlySet; +} { const existing = project.targets; const failures: BoxNetworkFailure[] = []; + const recorded = project.ownedTargets; + const isManaged = (target: AgentCoreGatewayTarget) => + recorded ? recorded.has(target.name) : isManagedTarget(target); for (const target of existing) { - const changed = isManagedTarget(target) ? unmanagedShape(target) : undefined; + const changed = recorded?.has(target.name) ? unmanagedShape(target) : undefined; if (changed === undefined) continue; failures.push({ code: "MANAGED_TARGET_CHANGED", target: target.name, reason: - `The gateway target '${target.name}' ${changed}, which build does not write for a ` + - `target whose name starts with "${BOX_EGRESS_TARGET_PREFIX}", so build does not change ` + - `or remove it. Rename it without "${BOX_EGRESS_TARGET_PREFIX}" to keep it as yours, or ` + - "remove it so build writes it again.", + `The gateway target '${target.name}' ${changed}, which build does not write, and ` + + `${BOX_GATEWAY_TARGETS_FILE} names it as a target that build writes, so build does not ` + + `change or remove it. Remove '${target.name}' from that file to keep the target as ` + + "yours, or remove the target so build writes it again.", place: PROJECT_SPEC_PLACE, }); } @@ -410,7 +438,7 @@ function hostTargets( if (held) { claimed.add(held.name); reused.add(index); - const conflict = isManagedTarget(held) + const conflict = isManaged(held) ? undefined : targetConflict(held, host, auth, profilePath); if (conflict) { @@ -464,7 +492,7 @@ function hostTargets( // A target that build does not manage keeps its name, and two hosts take no one name. const owners = new Map(); for (const target of existing) { - if (!isManagedTarget(target)) owners.set(target.name, `the gateway target '${target.name}'`); + if (!isManaged(target)) owners.set(target.name, `the gateway target '${target.name}'`); } const describeHost = (host: MappedHost) => host.entry ? `${entryLabel(host.entry)} for ${host.authority}` : `the host ${host.authority}`; @@ -489,7 +517,7 @@ function hostTargets( }); const served = hosts.filter((host) => host.target !== undefined).length; - const kept = existing.filter((target) => !isManagedTarget(target) && !claimed.has(target.name)); + const kept = existing.filter((target) => !isManaged(target) && !claimed.has(target.name)); if (served + kept.length > MAX_GATEWAY_TARGETS) { failures.push({ code: "TOO_MANY_TARGETS", @@ -500,7 +528,11 @@ function hostTargets( place: profilePath, }); } - return { hosts, failures }; + const managed = new Set(existing.filter(isManaged).map(({ name }) => name)); + hosts.forEach(({ target }, index) => { + if (target !== undefined && !reused.has(index)) managed.add(target); + }); + return { hosts, failures, managed }; } /** The source of the entry that names a host. */ diff --git a/src/core/project/boxNetworkSource.test.ts b/src/core/project/boxNetworkSource.test.ts index ec9b3acde..4045583fb 100644 --- a/src/core/project/boxNetworkSource.test.ts +++ b/src/core/project/boxNetworkSource.test.ts @@ -501,6 +501,56 @@ describe("two routes of one profile to one host", () => { }); }); +describe("the record of the targets build writes", () => { + const mine = { + name: "egress-mine", + targetType: "passthrough", + passthrough: { endpoint: "https://mine.example.com", protocolType: "CUSTOM" }, + }; + const withTarget = { + ...SPEC, + agentCoreGateways: [{ ...boxGatewaySpec("agent"), targets: [mine] }], + } as unknown as ProjectSpec; + const managed = async (root: string) => [ + ...(await readBoxNetworks(withTarget, root, new FakeBoxProfileResolver()))[0]!.managedTargets, + ]; + + test("makes only the targets it names build's", async () => { + const root = await project([]); + await mkdir(join(root, "agentcore")); + await writeFile( + join(root, "agentcore", "box-gateway-targets.json"), + '{"agent-box-egress": []}', + ); + expect(await managed(root)).not.toContain("egress-mine"); + }); + + test("makes each egress- target of the shape build writes build's, for a gateway it does not name", async () => { + const root = await project([]); + expect(await managed(root)).toContain("egress-mine"); + await mkdir(join(root, "agentcore")); + await writeFile( + join(root, "agentcore", "box-gateway-targets.json"), + '{"other-box-egress": []}', + ); + expect(await managed(root)).toContain("egress-mine"); + }); + + test("stops on a record that is not the one build writes, and names the file", async () => { + const root = await project([]); + await mkdir(join(root, "agentcore")); + await writeFile( + join(root, "agentcore", "box-gateway-targets.json"), + '{"agent-box-egress": "x"}', + ); + await expect(readBoxNetworks(withTarget, root, new FakeBoxProfileResolver())).rejects.toThrow( + "agentcore/box-gateway-targets.json is not the record of the gateway targets that build " + + "writes: a JSON object with a list of target names for each Box gateway. Remove the " + + "file, and build writes it again.", + ); + }); +}); + describe("the IAM policy files of the Box gateway", () => { test("counts the actions of each listed file, and warns for one it cannot count", async () => { const root = await project([]); diff --git a/src/core/project/boxNetworkSource.ts b/src/core/project/boxNetworkSource.ts index 1989275f8..1856539fc 100644 --- a/src/core/project/boxNetworkSource.ts +++ b/src/core/project/boxNetworkSource.ts @@ -25,6 +25,7 @@ import { runtimeRunsInBox, } from "./templates/boxProfile"; import { + BOX_GATEWAY_TARGETS_FILE, boxGatewayOf, buildBoxNetwork, parseResolvedPolicy, @@ -68,6 +69,7 @@ export async function readBoxNetworks( addBoxGatewayTargets(withDefaults, region); const networks: BoxNetwork[] = []; const keys: SharedKeys = new Map(); + const record = readBoxGatewayTargets(projectRoot); for (const runtime of runtimes) { // ProjectSpecSchema requires a Box project to keep a gateway bound to each runtime. const entry = boxGatewayOf(withDefaults, runtime.name); @@ -87,6 +89,8 @@ export async function readBoxNetworks( region, targets: entry.targets, grantedActions: granted.actions, + ...(record && + Object.hasOwn(record, entry.name) && { ownedTargets: new Set(record[entry.name]) }), }); networks.push({ ...network, @@ -97,6 +101,31 @@ export async function readBoxNetworks( return networks; } +/** The record of the targets build writes, as {@link BOX_GATEWAY_TARGETS_FILE} holds it. */ +const BoxGatewayTargetsSchema = z.record(z.string(), z.array(z.string())); + +/** + * The targets build wrote for each Box gateway, by the gateway's name, or `undefined` when the + * project has no {@link BOX_GATEWAY_TARGETS_FILE}. Throws for a file that is not that record. + */ +function readBoxGatewayTargets(projectRoot: string): Record | undefined { + const path = join(projectRoot, ...BOX_GATEWAY_TARGETS_FILE.split("/")); + if (!existsSync(path)) return undefined; + let document: unknown; + try { + document = JSON.parse(readFileSync(path, "utf8")); + } catch { + document = undefined; + } + const record = BoxGatewayTargetsSchema.safeParse(document); + if (record.success) return record.data; + throw new ProjectStateError( + `${BOX_GATEWAY_TARGETS_FILE} is not the record of the gateway targets that build writes: a ` + + "JSON object with a list of target names for each Box gateway. Remove the file, and build " + + "writes it again.", + ); +} + /** * Throws, naming each profile to create, when a runtime that runs its agent in a box has no local * box profile of its own: build has nothing to derive its AgentCore Runtime profile from. diff --git a/src/core/project/boxNetworkWriters.test.ts b/src/core/project/boxNetworkWriters.test.ts index 3918cc7f9..55e487586 100644 --- a/src/core/project/boxNetworkWriters.test.ts +++ b/src/core/project/boxNetworkWriters.test.ts @@ -15,10 +15,18 @@ import { unsentTargetWarnings, type BoxNetworkWriter, } from "./boxNetworkWriters"; +import { BOX_GATEWAY_TARGETS_FILE } from "./boxNetwork"; import { ENV_LOCAL_RELATIVE_PATH } from "./envLocal"; import { AGENTCORE_CODEZIP_PACK_PATH, AGENTCORE_PACK_PATH } from "./templates/boxProfile"; import { serializeRuntimeProfile } from "./runtimeProfile/serialize"; +/** The targets build owns in a gateway that agentcore/box-gateway-targets.json does not name. */ +class EgressTargets extends Set { + override has(name: string): boolean { + return name.startsWith("egress-"); + } +} + /** A hand-built model of runtime `agent`, which each test changes as it needs. */ function network(overrides: Partial = {}): BoxNetwork { return { @@ -27,6 +35,7 @@ function network(overrides: Partial = {}): BoxNetwork { region: "us-west-2", hosts: [], envRoutes: [], + managedTargets: new EgressTargets(), policyFiles: [], runtimeProfile: { packs: ["@box/base", "@box/agentcore"], profile: { name: "demo" } }, runtimeProfileHeader: ["Derived from .box/agent/local/profile.toml."], @@ -145,6 +154,41 @@ describe("boxNetworkEdits", () => { }); describe("gatewayTargetsWriter", () => { + test("keeps a user's egress- target that the record does not name, and records the targets it writes", () => { + const project = spec([ + passthrough("egress-mine", "https://mine.example.com"), + passthrough("egress-gone", "https://gone.example.com"), + ]); + const models = [ + network({ + hosts: [ + host("httpbin.org", "egress-httpbin-org"), + host("api.github.com", "egress-github", { outboundAuth: GITHUB_AUTH }), + ], + managedTargets: new Set(["egress-gone", "egress-httpbin-org", "egress-github"]), + }), + ]; + + const edits = run([gatewayTargetsWriter], models, project); + + expect(targetNames(edits.spec)).toEqual(["egress-mine", "egress-httpbin-org"]); + expect(edits.messages).toContain( + "removing gateway target 'egress-gone' from 'agent-box-egress': the Box profile no longer " + + "allows gone.example.com", + ); + // No credential holds the GitHub key, so build writes no egress-github and records none. + expect(edits.files).toEqual([ + { + path: BOX_GATEWAY_TARGETS_FILE, + text: `${JSON.stringify({ "agent-box-egress": ["egress-httpbin-org"] }, undefined, 2)}\n`, + }, + ]); + }); + + test("records no file for a project with no box runtime", () => { + expect(run([gatewayTargetsWriter], []).files).toEqual([]); + }); + test("adds a host's target, rewrites a managed one, removes a stale one, and keeps the user's", () => { const project = spec([ passthrough("ours", "https://ours.example.com"), diff --git a/src/core/project/boxNetworkWriters.ts b/src/core/project/boxNetworkWriters.ts index 5b04a574b..76ce448ba 100644 --- a/src/core/project/boxNetworkWriters.ts +++ b/src/core/project/boxNetworkWriters.ts @@ -11,10 +11,10 @@ import type { EnvLocalEntry } from "../../handlers/project/types"; import type { AgentCoreGatewayTarget } from "../../projectSchemas/gateway"; import type { ProjectSpec } from "../../projectSchemas/project"; import { + BOX_GATEWAY_TARGETS_FILE, boxGatewayOf, gatewayTargetFor, hostKey, - isManagedTarget, parseEndpoint, type BoxNetwork, type BoxNetworkHost, @@ -198,15 +198,59 @@ function uniqueRoutes(networks: readonly BoxNetwork[]): BoxEnvRoute[] { return routes; } -/** The `egress-` targets of each Box gateway, which build adds, rewrites, and removes. */ +/** + * The targets of each Box gateway that build owns, which it adds, rewrites, and removes, and the + * record of the targets it writes ({@link BOX_GATEWAY_TARGETS_FILE}). + */ export const gatewayTargetsWriter: BoxNetworkWriter = { name: "gateway targets", - writes: (networks) => networks.map(({ gateway }) => ({ kind: "gatewayTargets", gateway })), - edits: (networks) => ({ - spec: networks.map((network) => (spec: ProjectSpec) => writeGatewayTargets(spec, network)), - }), + writes: (networks) => [ + ...networks.map(({ gateway }) => ({ kind: "gatewayTargets" as const, gateway })), + ...(networks.length > 0 ? [{ kind: "file" as const, path: BOX_GATEWAY_TARGETS_FILE }] : []), + ], + edits: (networks, context) => { + if (networks.length === 0) return {}; + const after = withPlannedCredentials(networks, context).spec; + const record = Object.fromEntries( + networks.map((network) => [ + network.gateway, + [ + ...new Set( + network.hosts.flatMap((host) => + host.target !== undefined && + network.managedTargets.has(host.target) && + undeclaredKey(after, host) === undefined + ? [host.target] + : [], + ), + ), + ], + ]), + ); + return { + spec: networks.map((network) => (spec: ProjectSpec) => writeGatewayTargets(spec, network)), + files: [ + { path: BOX_GATEWAY_TARGETS_FILE, text: `${JSON.stringify(record, undefined, 2)}\n` }, + ], + }; + }, }; +/** + * `context.spec` with the API key credentials that the credentials writer adds, and the plan that + * adds them. + */ +function withPlannedCredentials( + networks: readonly BoxNetwork[], + { spec, env, envLocal }: BoxNetworkWriteContext, +): { spec: ProjectSpec; plan: ReturnType } { + const plan = planBoxProfileCredentials(structuredClone(spec), uniqueRoutes(networks), { + env, + envLocal, + }); + return { spec: { ...spec, credentials: [...spec.credentials, ...plan.added] }, plan }; +} + /** * Sets the build-owned targets of the network's Box gateway: a managed target that a host takes is * rewritten in place, every other managed target goes, a host whose managed target the gateway @@ -217,8 +261,9 @@ export const gatewayTargetsWriter: BoxNetworkWriter = { function writeGatewayTargets(spec: ProjectSpec, network: BoxNetwork): string[] { const gateway = boxGatewayOf(spec, network.runtime); if (!gateway) return []; + const managed = network.managedTargets; const served = network.hosts.flatMap((host) => - host.target === undefined || !isManagedTarget({ name: host.target }) + host.target === undefined || !managed.has(host.target) ? [] : [{ ...host, target: host.target }], ); @@ -229,7 +274,7 @@ function writeGatewayTargets(spec: ProjectSpec, network: BoxNetwork): string[] { const targets: AgentCoreGatewayTarget[] = []; const gatewayName = `'${gateway.name}'`; for (const target of existing) { - if (!isManagedTarget(target)) { + if (!managed.has(target.name)) { targets.push(target); continue; } @@ -279,32 +324,28 @@ export function unsentTargetWarnings( networks: readonly BoxNetwork[], context: BoxNetworkWriteContext, ): string[] { - const { spec, env, envLocal } = context; - const plan = planBoxProfileCredentials(structuredClone(spec), uniqueRoutes(networks), { - env, - envLocal, - }); - const after = { ...spec, credentials: [...spec.credentials, ...plan.added] }; + const { spec: after, plan } = withPlannedCredentials(networks, context); const warnings: string[] = []; - for (const host of networks.flatMap((network) => network.hosts)) { - if (host.target === undefined || !isManagedTarget({ name: host.target })) continue; - const auth = undeclaredKey(after, host); - const source = host.sources.find( - (candidate): candidate is Exclude => - candidate.kind !== "rule", - ); - if (auth === undefined || source === undefined) continue; - const [table, route] = - source.kind === "entry" ? ["egress", source.egressEntry] : ["mcp", source.mcpEntry]; - const why = - plan.unprovisioned.get(route) ?? - `agentcore.json has no API key credential '${auth.credentialName}' to hold the key of ` + - `env://${auth.variable}.`; - warnings.push( - `${host.authority}: build gives [${table}.${route}] no gateway target, so the agent ` + - `cannot reach this host on AgentCore Runtime. ${why}`, - ); - } + for (const { hosts, managedTargets } of networks) + for (const host of hosts) { + if (host.target === undefined || !managedTargets.has(host.target)) continue; + const auth = undeclaredKey(after, host); + const source = host.sources.find( + (candidate): candidate is Exclude => + candidate.kind !== "rule", + ); + if (auth === undefined || source === undefined) continue; + const [table, route] = + source.kind === "entry" ? ["egress", source.egressEntry] : ["mcp", source.mcpEntry]; + const why = + plan.unprovisioned.get(route) ?? + `agentcore.json has no API key credential '${auth.credentialName}' to hold the key of ` + + `env://${auth.variable}.`; + warnings.push( + `${host.authority}: build gives [${table}.${route}] no gateway target, so the agent ` + + `cannot reach this host on AgentCore Runtime. ${why}`, + ); + } return warnings; } diff --git a/src/core/project/manager.boxNetwork.test.ts b/src/core/project/manager.boxNetwork.test.ts index 45e72ffe1..1d4c51b91 100644 --- a/src/core/project/manager.boxNetwork.test.ts +++ b/src/core/project/manager.boxNetwork.test.ts @@ -394,6 +394,37 @@ describe("build writes the Box network of the box profile", () => { expect(second.warnings.filter((w) => w.startsWith("api.openai.com"))).toEqual([]); }); + test("owns only the targets it records, after it takes its old egress- targets once", async () => { + const { manager, root } = await strandsProject(); + // A project built before the record: build wrote egress-old, for a host the profile has left. + await editGateway(root, (gateway) => + gateway.targets.push(userTarget("egress-old", "https://old.example.com")), + ); + + const first = await build(manager, root); + expect(await targetNames(root)).toEqual(["bedrock", "agentcore"]); + expect(first.steps).toContain( + `removing gateway target 'egress-old' from '${GATEWAY}': the Box profile no longer allows ` + + "old.example.com", + ); + expect(JSON.parse(await text(root, "agentcore/box-gateway-targets.json"))).toEqual({ + [GATEWAY]: [], + }); + + // The user's own target with the prefix, of the shape build writes, now stays theirs. + await editGateway(root, (gateway) => + gateway.targets.push(userTarget("egress-mine", "https://mine.example.com")), + ); + await build(manager, root); + expect(await targetNames(root)).toEqual(["bedrock", "agentcore", "egress-mine"]); + // The Runtime profile routes the user's target, as a target build does not own. + const egress = (await runtimeProfile(root)).egress as Record< + string, + { destinations: string[] } + >; + expect(egress["egress-mine"]?.destinations).toEqual(["mine.example.com"]); + }); + test("changes nothing on a second build", async () => { const { manager, root, counter, box } = await strandsProject({ env: { GITHUB_TOKEN: "ghp_123" }, diff --git a/src/core/project/manager.test.ts b/src/core/project/manager.test.ts index 99f66dc18..ed0ede47f 100644 --- a/src/core/project/manager.test.ts +++ b/src/core/project/manager.test.ts @@ -2128,6 +2128,7 @@ describe("FsProjectManager.build", () => { message: "adding 'agentcore/box-memory-policy.json' to gateway 'agent-python-strands-box-box-egress' additionalPolicies in agentcore.json, so its role can call Memory", }, + { type: "step", message: "writing agentcore/box-gateway-targets.json" }, { type: "step", message: "writing agentcore/box-bedrock-policy.json" }, { type: "step", message: "writing agentcore/box-memory-policy.json" }, { type: "step", message: "synthesizing CloudFormation templates" }, diff --git a/src/core/project/runtimeProfile/rules/gateway.ts b/src/core/project/runtimeProfile/rules/gateway.ts index a6acddf7e..1cd9dd75a 100644 --- a/src/core/project/runtimeProfile/rules/gateway.ts +++ b/src/core/project/runtimeProfile/rules/gateway.ts @@ -93,12 +93,14 @@ export function apply(table: Readonly, context: RuntimeProfileContext /** * The routes of the runtime: one for each passthrough target of its Box gateway, in the order of * the gateway's targets once build writes them. Build keeps each target it does not manage where - * it is, keeps each `egress-` target that a host takes, removes the other `egress-` targets, and + * it is, keeps each target it manages that a host takes, removes the other targets it manages, and * adds the target of each other host at the end. Throws for two targets for one host, which would * give the box two routes to that host. */ function gatewayRoutes(context: RuntimeProfileContext): GatewayRoute[] { - const managed = (name: string) => name.startsWith(BOX_EGRESS_TARGET_PREFIX); + const owned = context.gateway.managed; + const managed = (name: string) => + owned ? owned.has(name) : name.startsWith(BOX_EGRESS_TARGET_PREFIX); const served = context.hosts.filter( (host): host is BoxNetworkHost & { readonly target: string } => host.target !== undefined && managed(host.target), diff --git a/src/core/project/runtimeProfile/types.ts b/src/core/project/runtimeProfile/types.ts index d5a8cdb6b..7c30fb762 100644 --- a/src/core/project/runtimeProfile/types.ts +++ b/src/core/project/runtimeProfile/types.ts @@ -63,7 +63,12 @@ export interface RuntimeProfileContext { /** The region build builds for: of the Box gateway and its `bedrock` and `agentcore` targets. */ readonly region: string; /** The runtime's Box gateway: its name, and its targets with the ones build adds. */ - readonly gateway: { readonly name: string; readonly targets: readonly AgentCoreGatewayTarget[] }; + readonly gateway: { + readonly name: string; + readonly targets: readonly AgentCoreGatewayTarget[]; + /** The targets build owns (`BoxNetwork.managedTargets`); absent: each `egress-` target. */ + readonly managed?: ReadonlySet; + }; /** The hosts of the Box network model, each with the gateway target it gets. */ readonly hosts: readonly BoxNetworkHost[]; /** The CloudWatch targets of the local profile, with the deploy region set. */ From c065a0a1450b1a14dc7cbc99b1c0e51ac83c8c38 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 12:44:22 -0800 Subject: [PATCH 11/31] test(box): Compare the warning host exactly, for the CodeQL URL check --- src/core/project/manager.boxNetwork.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/core/project/manager.boxNetwork.test.ts b/src/core/project/manager.boxNetwork.test.ts index 1d4c51b91..49f7038dd 100644 --- a/src/core/project/manager.boxNetwork.test.ts +++ b/src/core/project/manager.boxNetwork.test.ts @@ -391,7 +391,7 @@ describe("build writes the Box network of the box profile", () => { ]); const second = await build(manager, root); expect(await targetNames(root)).toEqual(["bedrock", "agentcore", "egress-openai"]); - expect(second.warnings.filter((w) => w.startsWith("api.openai.com"))).toEqual([]); + expect(second.warnings.filter((w) => w.split(":", 1)[0] === "api.openai.com")).toEqual([]); }); test("owns only the targets it records, after it takes its old egress- targets once", async () => { From 2d3ef4a4c41f8105af5783f5a68352cb43f98e00 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 13:28:49 -0800 Subject: [PATCH 12/31] test(box): Test pathTest and findPath directly, for the review comment on pathSolver.ts --- .../project/boxNetwork/pathSolver.test.ts | 87 +++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 src/core/project/boxNetwork/pathSolver.test.ts diff --git a/src/core/project/boxNetwork/pathSolver.test.ts b/src/core/project/boxNetwork/pathSolver.test.ts new file mode 100644 index 000000000..fc4dfa121 --- /dev/null +++ b/src/core/project/boxNetwork/pathSolver.test.ts @@ -0,0 +1,87 @@ +import { describe, expect, test } from "bun:test"; +import type { Comparison, FieldAtom } from "./conditions"; +import type { LikePattern } from "./dogwood"; +import { findPath, pathTest, type PathTest } from "./pathSolver"; + +/** A `like` pattern, with each `*` as a wildcard. */ +function like(text: string): LikePattern { + const parts: LikePattern["parts"][number][] = []; + for (const [i, piece] of text.split("*").entries()) { + if (i > 0) parts.push({ kind: "wildcard" }); + if (piece !== "") parts.push({ kind: "literal", text: piece }); + } + return { parts }; +} + +const atom = (comparison: Comparison, negated = false): FieldAtom => ({ + kind: "field", + field: "path", + comparison, + negated, + text: "context.input.path", +}); +const literal = (text: string): LikePattern => ({ parts: [{ kind: "literal", text }] }); +const must = (text: string): PathTest => ({ pattern: like(text), matches: true }); +const never = (text: string): PathTest => ({ pattern: like(text), matches: false }); + +describe("pathTest", () => { + test.each<[string, FieldAtom, PathTest | boolean]>([ + ["like", atom({ op: "like", pattern: like("/v1/*") }), must("/v1/*")], + ["!(like)", atom({ op: "like", pattern: like("/v1/*") }, true), never("/v1/*")], + ["==", atom({ op: "==", value: "/a" }), { pattern: literal("/a"), matches: true }], + ["!(==)", atom({ op: "==", value: "/a" }, true), { pattern: literal("/a"), matches: false }], + ["!=", atom({ op: "!=", value: "/a" }), { pattern: literal("/a"), matches: false }], + ["!(!=)", atom({ op: "!=", value: "/a" }, true), { pattern: literal("/a"), matches: true }], + ["has", atom({ op: "present" }), true], + ["!(has)", atom({ op: "present" }, true), false], + ])("reads %s", (_, input, expected) => { + expect(pathTest(input)).toEqual(expected); + }); +}); + +describe("findPath", () => { + const filler = "ยง"; + const path = (required: PathTest[], excluded: PathTest[][] = []) => { + const found = findPath(required, excluded, filler); + return found.kind === "path" ? found.path : found.kind; + }; + + test("finds the shortest path that two patterns of a permit allow together", () => { + expect(path([must("/v1/*"), must("*/items")])).toBe("/v1/items"); + }); + + test("finds a path past a != in a permit", () => { + const found = path([must("/a*"), { pattern: literal("/a"), matches: false }]); + expect(found).not.toBe("/a"); + expect(found).toStartWith("/a"); + }); + + test("finds a path past a negated like in a permit", () => { + const found = path([must("/v1/*"), never("/v1/admin*"), never("/v1/")]); + expect(found).toStartWith("/v1/"); + expect(found).not.toStartWith("/v1/admin"); + expect(found).not.toBe("/v1/"); + }); + + test("finds a path that a forbid does not hold on, and none when every path is forbidden", () => { + const found = path([must("/v1/*"), must("*/items")], [[must("/v1/items")]]); + expect(found).toBe("/v1//items"); + expect(path([must("/v1/*")], [[must("/*")]])).toBe("none"); + expect(path([must("/*")], [[]])).toBe("none"); + }); + + test("uses a character that no pattern names when the filler is in a pattern", () => { + const found = path([must("/*"), never("/"), never("/ยง*"), never("//*")]); + // U+E000, the first private-use character, which no pattern names. + expect(found).toBe("/\uE000"); + }); + + test("finds no path for patterns that never hold together", () => { + expect(path([must("/v1/*"), must("/v2/*")])).toBe("none"); + expect(path([must("v1/*")])).toBe("none"); + }); + + test("stops undecided when the search has too many states", () => { + expect(path([..."abcdefghijklm"].map((c) => must(`*${c}*`)))).toBe("undecided"); + }); +}); From 40116bd99533772abed89952e0403381a6290d03 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 13:29:57 -0800 Subject: [PATCH 13/31] fix(box): Warn for each egress- target that the one-time migration keeps as the user's, for the review comment on network.ts --- src/core/project/boxNetwork/network.test.ts | 8 ++++++++ src/core/project/boxNetwork/network.ts | 17 ++++++++++++++++- 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/src/core/project/boxNetwork/network.test.ts b/src/core/project/boxNetwork/network.test.ts index 588b0c06e..61c9854db 100644 --- a/src/core/project/boxNetwork/network.test.ts +++ b/src/core/project/boxNetwork/network.test.ts @@ -313,6 +313,7 @@ describe("the gateway's targets", () => { ); expect(r.failures()).toEqual([]); expect([...r.network.managedTargets]).toEqual(["egress-github"]); + expect(r.network.warnings.filter((w) => w.includes("'egress-"))).toEqual([]); }); test("fail a target the file names that the user changed, and say how to keep it", () => { @@ -347,6 +348,13 @@ describe("the gateway's targets", () => { ); expect(r.failures()).toEqual([]); expect([...r.network.managedTargets]).toEqual(["egress-stale", "egress-github"]); + // The one build that takes the old egress- targets says which one it keeps as the user's. + expect(r.network.warnings.filter((w) => w.includes("'egress-"))).toEqual([ + "agentcore/agentcore.json: build keeps the gateway target 'egress-old' as yours, because " + + "it sends the API key credential 'old' in the query parameter key, which build does " + + "not write. Build does not change or remove it. Remove the target if build wrote it " + + "before and you do not use it.", + ]); }); test("leave a user's target of another shape on an entry's host to the user", () => { diff --git a/src/core/project/boxNetwork/network.ts b/src/core/project/boxNetwork/network.ts index 700ac0b4d..743a2367d 100644 --- a/src/core/project/boxNetwork/network.ts +++ b/src/core/project/boxNetwork/network.ts @@ -266,6 +266,7 @@ export function buildBoxNetwork( ); }), ), + ...targets.warnings, ...hostWarnings(targets.hosts), ...map.websocketOnly.map(({ ruleId, span }) => { const { place, subject } = describeRule(parsed, ruleId, span); @@ -362,13 +363,27 @@ function hostTargets( hosts: BoxNetworkHost[]; failures: BoxNetworkFailure[]; managed: ReadonlySet; + warnings: string[]; } { const existing = project.targets; const failures: BoxNetworkFailure[] = []; const recorded = project.ownedTargets; const isManaged = (target: AgentCoreGatewayTarget) => recorded ? recorded.has(target.name) : isManagedTarget(target); + const warnings: string[] = []; for (const target of existing) { + // The one build that takes a gateway's old egress- targets names each one it keeps. + const kept = + recorded === undefined && target.name.startsWith(BOX_EGRESS_TARGET_PREFIX) + ? unmanagedShape(target) + : undefined; + if (kept !== undefined) { + warnings.push( + `${PROJECT_SPEC_PLACE}: build keeps the gateway target '${target.name}' as yours, ` + + `because it ${kept}, which build does not write. Build does not change or remove it. ` + + "Remove the target if build wrote it before and you do not use it.", + ); + } const changed = recorded?.has(target.name) ? unmanagedShape(target) : undefined; if (changed === undefined) continue; failures.push({ @@ -532,7 +547,7 @@ function hostTargets( hosts.forEach(({ target }, index) => { if (target !== undefined && !reused.has(index)) managed.add(target); }); - return { hosts, failures, managed }; + return { hosts, failures, managed, warnings }; } /** The source of the entry that names a host. */ From 0628b154bc96d67e664948cbcae06eb5f07e03fe Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 13:31:06 -0800 Subject: [PATCH 14/31] docs(box): Say to commit agentcore/box-gateway-targets.json, for the review comment on box-local-testing.md --- docs/box-local-testing.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/box-local-testing.md b/docs/box-local-testing.md index c5710ec94..1e2c609c8 100644 --- a/docs/box-local-testing.md +++ b/docs/box-local-testing.md @@ -133,7 +133,11 @@ the generated packs, and the policy files into `.box//aws/` for you to only the targets it wrote, which it lists in `agentcore/box-gateway-targets.json`: it adds them, changes them, and removes one when no host needs it. It never changes another target, also one whose name starts with `egress-`. For a gateway that the file does not list, which an older CLI - built, build takes each `egress-` target that has the shape it writes as its own, once. + built, build takes each `egress-` target that has the shape it writes as its own, once, and warns + for each other `egress-` target, which it keeps as yours. Commit + `agentcore/box-gateway-targets.json` with `agentcore.json`: in a clone without it, build goes + back to that `egress-` rule, and can take or give up the wrong targets. The `.gitignore` that + `agentcore create` writes does not exclude it. - **Outbound auth.** An `aws://` secret signs with the gateway's role, an `env://` secret sends an API key from AgentCore Identity, and an entry with no secret sends no credential. - **Failures.** A wildcard host, a plain-HTTP-only host, an unsupported secret or pack, an From 4170b5433f3badeabfd8537047779b0c82d3cf42 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 13:43:25 -0800 Subject: [PATCH 15/31] fix(box): Read each condition after a temporal or guardrails condition, for the review comment on conditions.ts line 130 --- src/core/project/boxNetwork/conditions.ts | 4 ++-- src/core/project/boxNetwork/hostMap.test.ts | 17 +++++++++++++++++ 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/src/core/project/boxNetwork/conditions.ts b/src/core/project/boxNetwork/conditions.ts index d59d534ab..5d21722bb 100644 --- a/src/core/project/boxNetwork/conditions.ts +++ b/src/core/project/boxNetwork/conditions.ts @@ -127,8 +127,8 @@ export function clausesFor(statement: Statement, action: NetworkAction): ClauseS for (const condition of statement.conditions) { parts.push(conditionFormula(condition, action)); // Box does not read a condition after one that an action test makes false. - const value = condition.body.kind === "cedar" && actionValue(condition.body.expr, action); - if (value === (condition.polarity !== "when")) break; + if (condition.body.kind !== "cedar") continue; + if (actionValue(condition.body.expr, action) === (condition.polarity !== "when")) break; } const clauses: Clause[] = []; const dead: DeadCause[] = []; diff --git a/src/core/project/boxNetwork/hostMap.test.ts b/src/core/project/boxNetwork/hostMap.test.ts index e45699118..592424070 100644 --- a/src/core/project/boxNetwork/hostMap.test.ts +++ b/src/core/project/boxNetwork/hostMap.test.ts @@ -167,6 +167,23 @@ describe("the policy decision on each host", () => { expect(codes(map(later + reach("get", "a.example.com")))).toEqual([]); }); + test("reads a host condition after a temporal condition, which no action test decides", () => { + const temporal = + "exists (n: Long). ((count for (t: Timepoint). where (formerly within 10m (" + + 'Box::Action::"http:request"::response{ input.host: "api.github.com" } && tp(t)))) == n ' + + "&& n < 3)"; + const limited = rule( + "limited", + `permit (principal, ${HR}, resource) when temporal { ${temporal} } when { ${on("a.example.com")} };`, + ); + const result = map(connect("c", on("a.example.com")) + limited); + expect(codes(result)).toEqual([]); + expect(host(result, "a.example.com")).toMatchObject({ + reachable: true, + enforcedByBox: ["limited"], + }); + }); + test("refuses the field when no action test keeps it from the action", () => { const result = map( connect("bare", on("a.example.com", 'context.input.method == "GET"')) + get, From 460c7c9c63e8bd08ea19aa32cafe972acd777c32 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 13:49:24 -0800 Subject: [PATCH 16/31] fix(box): Write an empty record entry for each new Box gateway in create and add runtime, for the review comment on network.ts line 304 --- docs/box-local-testing.md | 8 ++- src/core/project/boxGatewayTargets.ts | 64 +++++++++++++++++++++ src/core/project/boxNetwork/network.ts | 7 +-- src/core/project/boxNetworkSource.ts | 27 +-------- src/core/project/boxNetworkWriters.ts | 5 +- src/core/project/manager.box.test.ts | 42 ++++++++++++++ src/core/project/manager.boxNetwork.test.ts | 34 ++++++++--- src/core/project/manager.test.ts | 1 - src/core/project/manager.tsx | 15 ++++- src/core/project/templates/project.ts | 25 +++++--- 10 files changed, 171 insertions(+), 57 deletions(-) create mode 100644 src/core/project/boxGatewayTargets.ts diff --git a/docs/box-local-testing.md b/docs/box-local-testing.md index 1e2c609c8..dd1897753 100644 --- a/docs/box-local-testing.md +++ b/docs/box-local-testing.md @@ -132,9 +132,11 @@ the generated packs, and the policy files into `.box//aws/` for you to `-box-egress`. A host the gateway already has a target for keeps that target. Build owns only the targets it wrote, which it lists in `agentcore/box-gateway-targets.json`: it adds them, changes them, and removes one when no host needs it. It never changes another target, also one - whose name starts with `egress-`. For a gateway that the file does not list, which an older CLI - built, build takes each `egress-` target that has the shape it writes as its own, once, and warns - for each other `egress-` target, which it keeps as yours. Commit + whose name starts with `egress-`. `agentcore create` and `agentcore add runtime` write an empty + entry for each new Box gateway, so build owns none of its targets until it writes one. For a + gateway that the file does not list, which an older CLI made, build takes each `egress-` target + that has the shape it writes as its own, once, and warns for each other `egress-` target, which it + keeps as yours. Commit `agentcore/box-gateway-targets.json` with `agentcore.json`: in a clone without it, build goes back to that `egress-` rule, and can take or give up the wrong targets. The `.gitignore` that `agentcore create` writes does not exclude it. diff --git a/src/core/project/boxGatewayTargets.ts b/src/core/project/boxGatewayTargets.ts new file mode 100644 index 000000000..a4e67cd52 --- /dev/null +++ b/src/core/project/boxGatewayTargets.ts @@ -0,0 +1,64 @@ +/** + * The record of the targets that build writes for each Box gateway, by the gateway's name. Build + * owns those targets, and no other. `agentcore create` and `agentcore add runtime` write an empty + * entry for each new Box gateway, so the `egress-` rule applies only to a gateway an older CLI made. + */ +import { existsSync, readFileSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; +import { z } from "zod"; +import { ProjectStateError } from "../../errors/errors"; + +/** The record's name in the `agentcore/` folder. */ +export const BOX_GATEWAY_TARGETS_NAME = "box-gateway-targets.json"; + +/** The record's path from the project root. */ +export const BOX_GATEWAY_TARGETS_FILE = `agentcore/${BOX_GATEWAY_TARGETS_NAME}`; + +const BoxGatewayTargetsSchema = z.record(z.string(), z.array(z.string())); + +/** The record as a file holds it. */ +export function boxGatewayTargetsText(record: Readonly>): string { + return `${JSON.stringify(record, undefined, 2)}\n`; +} + +/** + * The targets build wrote for each Box gateway, or `undefined` when the project has no record. + * Throws for a file that is not the record. + */ +export function readBoxGatewayTargets(projectRoot: string): Record | undefined { + const path = join(projectRoot, ...BOX_GATEWAY_TARGETS_FILE.split("/")); + if (!existsSync(path)) return undefined; + let document: unknown; + try { + document = JSON.parse(readFileSync(path, "utf8")); + } catch { + document = undefined; + } + const record = BoxGatewayTargetsSchema.safeParse(document); + if (record.success) return record.data; + throw new ProjectStateError( + `${BOX_GATEWAY_TARGETS_FILE} is not the record of the gateway targets that build writes: a ` + + "JSON object with a list of target names for each Box gateway. Remove the file, and build " + + "writes it again.", + ); +} + +/** + * Adds an empty entry for each of `gateways` that the record does not name yet. Returns whether it + * wrote the record; it leaves a file that is not the record to build, which refuses it. + */ +export function addBoxGatewaysToRecord(projectRoot: string, gateways: readonly string[]): boolean { + let record: Record; + try { + record = readBoxGatewayTargets(projectRoot) ?? {}; + } catch (error) { + if (error instanceof ProjectStateError) return false; + throw error; + } + const added = gateways.filter((gateway) => !Object.hasOwn(record, gateway)); + if (added.length === 0) return false; + for (const gateway of added) record[gateway] = []; + const path = join(projectRoot, ...BOX_GATEWAY_TARGETS_FILE.split("/")); + writeFileSync(path, boxGatewayTargetsText(record)); + return true; +} diff --git a/src/core/project/boxNetwork/network.ts b/src/core/project/boxNetwork/network.ts index 743a2367d..408980d08 100644 --- a/src/core/project/boxNetwork/network.ts +++ b/src/core/project/boxNetwork/network.ts @@ -8,6 +8,7 @@ import { credentialEnvVarName } from "../../../projectSchemas/credential"; import type { AgentCoreGateway, AgentCoreGatewayTarget } from "../../../projectSchemas/gateway"; import type { ProjectSpec } from "../../../projectSchemas/project"; import type { ProjectRuntime } from "../../../projectSchemas/runtime"; +import { BOX_GATEWAY_TARGETS_FILE } from "../boxGatewayTargets"; import { BOX_BEDROCK_POLICY_FILE, BOX_MEMORY_POLICY_FILE } from "../boxMemory"; import { boxEgressCredentialName } from "../boxProfileCredentials"; import type { BoxEnvRoute } from "../boxProfileEgress"; @@ -44,11 +45,7 @@ export type { BoxNetworkFailure } from "./types"; /** Where a failure of a target in agentcore.json is. */ const PROJECT_SPEC_PLACE = "agentcore/agentcore.json"; -/** - * The file, from the project root, where build records the targets of each Box gateway that it - * writes, by the gateway's name. Build owns those targets, and no other. - */ -export const BOX_GATEWAY_TARGETS_FILE = "agentcore/box-gateway-targets.json"; +export { BOX_GATEWAY_TARGETS_FILE }; /** How the gateway authenticates its requests to a host. */ export type BoxEgressAuth = diff --git a/src/core/project/boxNetworkSource.ts b/src/core/project/boxNetworkSource.ts index 1856539fc..0d1b50b47 100644 --- a/src/core/project/boxNetworkSource.ts +++ b/src/core/project/boxNetworkSource.ts @@ -24,8 +24,8 @@ import { boxStartFolder, runtimeRunsInBox, } from "./templates/boxProfile"; +import { readBoxGatewayTargets } from "./boxGatewayTargets"; import { - BOX_GATEWAY_TARGETS_FILE, boxGatewayOf, buildBoxNetwork, parseResolvedPolicy, @@ -101,31 +101,6 @@ export async function readBoxNetworks( return networks; } -/** The record of the targets build writes, as {@link BOX_GATEWAY_TARGETS_FILE} holds it. */ -const BoxGatewayTargetsSchema = z.record(z.string(), z.array(z.string())); - -/** - * The targets build wrote for each Box gateway, by the gateway's name, or `undefined` when the - * project has no {@link BOX_GATEWAY_TARGETS_FILE}. Throws for a file that is not that record. - */ -function readBoxGatewayTargets(projectRoot: string): Record | undefined { - const path = join(projectRoot, ...BOX_GATEWAY_TARGETS_FILE.split("/")); - if (!existsSync(path)) return undefined; - let document: unknown; - try { - document = JSON.parse(readFileSync(path, "utf8")); - } catch { - document = undefined; - } - const record = BoxGatewayTargetsSchema.safeParse(document); - if (record.success) return record.data; - throw new ProjectStateError( - `${BOX_GATEWAY_TARGETS_FILE} is not the record of the gateway targets that build writes: a ` + - "JSON object with a list of target names for each Box gateway. Remove the file, and build " + - "writes it again.", - ); -} - /** * Throws, naming each profile to create, when a runtime that runs its agent in a box has no local * box profile of its own: build has nothing to derive its AgentCore Runtime profile from. diff --git a/src/core/project/boxNetworkWriters.ts b/src/core/project/boxNetworkWriters.ts index 76ce448ba..eb3003aac 100644 --- a/src/core/project/boxNetworkWriters.ts +++ b/src/core/project/boxNetworkWriters.ts @@ -26,6 +26,7 @@ import { boxBedrockPolicy, boxMemoryPolicy, } from "./boxMemory"; +import { boxGatewayTargetsText } from "./boxGatewayTargets"; import { planBoxProfileCredentials, type BoxKeySources } from "./boxProfileCredentials"; import type { BoxEnvRoute } from "./boxProfileEgress"; import { @@ -229,9 +230,7 @@ export const gatewayTargetsWriter: BoxNetworkWriter = { ); return { spec: networks.map((network) => (spec: ProjectSpec) => writeGatewayTargets(spec, network)), - files: [ - { path: BOX_GATEWAY_TARGETS_FILE, text: `${JSON.stringify(record, undefined, 2)}\n` }, - ], + files: [{ path: BOX_GATEWAY_TARGETS_FILE, text: boxGatewayTargetsText(record) }], }; }, }; diff --git a/src/core/project/manager.box.test.ts b/src/core/project/manager.box.test.ts index 9fe6b1320..9f93c9011 100644 --- a/src/core/project/manager.box.test.ts +++ b/src/core/project/manager.box.test.ts @@ -155,6 +155,9 @@ async function existingProject(manager: FsProjectManager): Promise { return project; } +/** The record of the gateway targets that build writes, `agentcore/box-gateway-targets.json`. */ +const recordOf = (project: Project) => + join(project.rootPath, "agentcore", "box-gateway-targets.json"); const specText = (project: Project) => readFile(join(project.rootPath, "agentcore", "agentcore.json"), "utf8"); /** The spec on disk, parsed, for a test that reads runtimes or gateway bindings. */ @@ -286,6 +289,26 @@ describe("agentcore create", () => { expect(runtime?.network).toEqual(network); }); + test("a Box template writes an empty entry for each Box gateway in the record of build's targets", async () => { + const directory = await mkdtemp(join(tmpdir(), "agentcore-box-")); + tempDirectories.push(directory); + process.chdir(directory); + const project = await drain( + subject().create({ + name: "example", + skipInstall: true, + skipGit: true, + scaffoldRuntimeInput: resolveRuntimeTemplateShortcut("agent-python-strands-box", { + runtimeName: "agent", + }), + }), + ); + + expect(JSON.parse(await readFile(recordOf(project), "utf8"))).toEqual({ + "agent-box-egress": [], + }); + }); + test("templates that are not Box templates write no projectType and no gateway", () => { const spec = newProjectSpec("example", [{ runtimes: [{ name: "agent" } as never] }]); expect("projectType" in spec).toBe(false); @@ -417,6 +440,24 @@ describe("gateway targets in a Box project", () => { ]); }); + test("add runtime adds an empty entry for its Box gateway to the record of build's targets", async () => { + const manager = subject(); + const project = await createdProject(manager); + await writeFile(recordOf(project), '{\n "agent-box-egress": ["egress-x"]\n}\n'); + + await drain( + manager.addResource(project, { + resourceType: "runtime", + resourceConfig: { name: "search", language: "Python", protocol: "HTTP" }, + } as never), + ); + + expect(JSON.parse(await readFile(recordOf(project), "utf8"))).toEqual({ + "agent-box-egress": ["egress-x"], + "search-box-egress": [], + }); + }); + test("add runtime says that the new Box gateway sends its logs, and how to stop them", async () => { const manager = subject(); const project = await createdProject(manager); @@ -666,6 +707,7 @@ describe("gateway targets in a Box project", () => { expect(messages).toContain(`writing box profile ${profile}`); expect(messages).not.toContain(boxGatewayLogsNotice(boxGatewaySpec("search").name)); expect(await specText(project)).toBe(before); + expect(existsSync(recordOf(project))).toBe(false); }); test("add runtime warns when the kept box profile is for another protocol", async () => { diff --git a/src/core/project/manager.boxNetwork.test.ts b/src/core/project/manager.boxNetwork.test.ts index 49f7038dd..284bde3d7 100644 --- a/src/core/project/manager.boxNetwork.test.ts +++ b/src/core/project/manager.boxNetwork.test.ts @@ -394,9 +394,31 @@ describe("build writes the Box network of the box profile", () => { expect(second.warnings.filter((w) => w.split(":", 1)[0] === "api.openai.com")).toEqual([]); }); - test("owns only the targets it records, after it takes its old egress- targets once", async () => { + test("keeps a user's egress- target that a new project has before its first build", async () => { const { manager, root } = await strandsProject(); - // A project built before the record: build wrote egress-old, for a host the profile has left. + // create wrote an empty entry for the Box gateway, so build owns none of its targets yet. + await editGateway(root, (gateway) => + gateway.targets.push(userTarget("egress-mine", "https://mine.example.com")), + ); + + await build(manager, root); + + expect(await targetNames(root)).toEqual(["egress-mine", "bedrock", "agentcore"]); + expect(JSON.parse(await text(root, "agentcore/box-gateway-targets.json"))).toEqual({ + [GATEWAY]: [], + }); + // The Runtime profile routes the user's target, as a target build does not own. + const egress = (await runtimeProfile(root)).egress as Record< + string, + { destinations: string[] } + >; + expect(egress["egress-mine"]?.destinations).toEqual(["mine.example.com"]); + }); + + test("takes the old egress- targets of a gateway that an older CLI made, one time", async () => { + const { manager, root } = await strandsProject(); + // A project of an older CLI has no record, and build wrote egress-old for a host it has left. + await rm(path(root, "agentcore/box-gateway-targets.json")); await editGateway(root, (gateway) => gateway.targets.push(userTarget("egress-old", "https://old.example.com")), ); @@ -411,18 +433,12 @@ describe("build writes the Box network of the box profile", () => { [GATEWAY]: [], }); - // The user's own target with the prefix, of the shape build writes, now stays theirs. + // Once the record names the gateway, a user's egress- target of the shape build writes stays. await editGateway(root, (gateway) => gateway.targets.push(userTarget("egress-mine", "https://mine.example.com")), ); await build(manager, root); expect(await targetNames(root)).toEqual(["bedrock", "agentcore", "egress-mine"]); - // The Runtime profile routes the user's target, as a target build does not own. - const egress = (await runtimeProfile(root)).egress as Record< - string, - { destinations: string[] } - >; - expect(egress["egress-mine"]?.destinations).toEqual(["mine.example.com"]); }); test("changes nothing on a second build", async () => { diff --git a/src/core/project/manager.test.ts b/src/core/project/manager.test.ts index ed0ede47f..99f66dc18 100644 --- a/src/core/project/manager.test.ts +++ b/src/core/project/manager.test.ts @@ -2128,7 +2128,6 @@ describe("FsProjectManager.build", () => { message: "adding 'agentcore/box-memory-policy.json' to gateway 'agent-python-strands-box-box-egress' additionalPolicies in agentcore.json, so its role can call Memory", }, - { type: "step", message: "writing agentcore/box-gateway-targets.json" }, { type: "step", message: "writing agentcore/box-bedrock-policy.json" }, { type: "step", message: "writing agentcore/box-memory-policy.json" }, { type: "step", message: "synthesizing CloudFormation templates" }, diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx index c66aa0275..605cf8cff 100644 --- a/src/core/project/manager.tsx +++ b/src/core/project/manager.tsx @@ -58,6 +58,7 @@ import { boxGatewayIamWarnings, type BoxNetwork } from "./boxNetwork"; import { boxNetworkFailureMessage, readBoxNetworks } from "./boxNetworkSource"; import { DEFAULT_REGION, regionFromConfigFile } from "../region"; import { BoxCliProfileResolver, type BoxProfileResolver } from "./boxProfileResolver"; +import { addBoxGatewaysToRecord, BOX_GATEWAY_TARGETS_FILE } from "./boxGatewayTargets"; import { BOX_NETWORK_WRITERS, boxNetworkEdits, @@ -1105,9 +1106,19 @@ export class FsProjectManager implements ProjectManager { newProjectSpec, newProjectSpec.runtimes.filter(({ name }) => name === added), ); - yield* boxGatewayLogsWarnings( - newProjectSpec.agentCoreGateways.filter(({ boundRuntime }) => boundRuntime === added), + const boxGateways = newProjectSpec.agentCoreGateways.filter( + ({ boundRuntime }) => boundRuntime === added, ); + yield* boxGatewayLogsWarnings(boxGateways); + // Build owns no target of the new Box gateway yet: an empty entry in the record says so. + if ( + addBoxGatewaysToRecord( + project.rootPath, + boxGateways.map(({ name }) => name), + ) + ) { + yield { type: "step", message: `writing ${BOX_GATEWAY_TARGETS_FILE}` }; + } } return { diff --git a/src/core/project/templates/project.ts b/src/core/project/templates/project.ts index 289a98e30..64523ff80 100644 --- a/src/core/project/templates/project.ts +++ b/src/core/project/templates/project.ts @@ -8,6 +8,7 @@ import type { import { InputValidationError } from "../../../errors/errors"; import { getRuntimeTemplateResolver } from "./runtime"; import { BOX_RELEASE } from "../backends/boxRelease"; +import { BOX_GATEWAY_TARGETS_NAME } from "../boxGatewayTargets"; import { BOX_CODEZIP_ENTRYPOINT, hasBoxProfile, @@ -62,6 +63,14 @@ export async function createProjectTree( const envEntries = templates.flatMap((template) => template.envEntries ?? []); const boxProject = options?.runtime !== undefined && hasBoxProfile(options.runtime); + const spec = newProjectSpec( + input.projectName, + templates.map(({ spec }) => spec), + ); + // Build owns no target of a new Box gateway yet: an empty entry in the record says so. + const boxGateways = (spec.agentCoreGateways ?? []).flatMap(({ name, boundRuntime }) => + boundRuntime === undefined ? [] : [name], + ); const tree = FsTreeNode.createDirectory(".", [ FsTreeNode.createFile(".gitignore", async () => { const shared = await config.assetSource.read("templates/shared/gitignore.template"); @@ -69,14 +78,14 @@ export async function createProjectTree( }), FsTreeNode.createDirectory("agentcore", [ await FsTreeNode.fromAssetSource({ assetSource: config.assetSource }, { assetDir: "cdk" }), - FsTreeNode.createFile("agentcore.json", async () => - json( - newProjectSpec( - input.projectName, - templates.map(({ spec }) => spec), - ), - ), - ), + FsTreeNode.createFile("agentcore.json", async () => json(spec)), + ...(boxGateways.length > 0 + ? [ + FsTreeNode.createFile(BOX_GATEWAY_TARGETS_NAME, async () => + json(Object.fromEntries(boxGateways.map((name) => [name, []]))), + ), + ] + : []), FsTreeNode.createFile("aws-targets.json", async () => json([])), FsTreeNode.createFile(".env.local", () => config.assetSource.read("templates/shared/env.local.template"), From a8116afa0c0005b1a2a388f5359f86bee83c030d Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 13:50:54 -0800 Subject: [PATCH 17/31] fix(box): Plan the credential of each route and variable that the runtimes read, for the review comment on boxNetworkSource.ts line 168 --- src/core/project/boxNetworkWriters.test.ts | 30 ++++++++++++++++++++++ src/core/project/boxNetworkWriters.ts | 9 ++++++- 2 files changed, 38 insertions(+), 1 deletion(-) diff --git a/src/core/project/boxNetworkWriters.test.ts b/src/core/project/boxNetworkWriters.test.ts index 55e487586..8d7e0b9e3 100644 --- a/src/core/project/boxNetworkWriters.test.ts +++ b/src/core/project/boxNetworkWriters.test.ts @@ -343,6 +343,36 @@ describe("credentialsWriter", () => { ]); }); + test.each([ + ["the credential's own variable", "first"], + ["the other variable", "first"], + ])("stores a rotated key of a route that two runtimes read, with %s %s", (first) => { + const own = network({ + envRoutes: [{ route: "github", variable: "AGENTCORE_CREDENTIAL_GITHUB" }], + }); + const alias = network({ + runtime: "other", + gateway: "other-box-egress", + envRoutes: [{ route: "github", variable: "GITHUB_TOKEN" }], + }); + const project = spec(); + project.credentials.push({ authorizerType: "ApiKeyCredentialProvider", name: "github" }); + + const edits = boxNetworkEdits( + [credentialsWriter], + first === "the credential's own variable" ? [own, alias] : [alias, own], + { + ...contextFor(project), + env: { GITHUB_TOKEN: "ghp_new" }, + envLocal: { AGENTCORE_CREDENTIAL_GITHUB: "ghp_old" }, + }, + ); + + expect(edits.envLocal).toEqual([ + expect.objectContaining({ key: "AGENTCORE_CREDENTIAL_GITHUB", value: "ghp_new" }), + ]); + }); + test("runs before the gateway targets, so a target gets the credential it adds", () => { const models = [ network({ diff --git a/src/core/project/boxNetworkWriters.ts b/src/core/project/boxNetworkWriters.ts index eb3003aac..dc73e077b 100644 --- a/src/core/project/boxNetworkWriters.ts +++ b/src/core/project/boxNetworkWriters.ts @@ -191,10 +191,17 @@ export const credentialsWriter: BoxNetworkWriter = { }, }; +/** + * Each `env://` route of the networks once, by its name and its variable: two runtimes can read + * one credential from its own variable and from one other, and build copies the other's key. + */ function uniqueRoutes(networks: readonly BoxNetwork[]): BoxEnvRoute[] { const routes: BoxEnvRoute[] = []; for (const route of networks.flatMap((network) => network.envRoutes)) { - if (!routes.some((other) => other.route === route.route)) routes.push(route); + const seen = routes.some( + (other) => other.route === route.route && other.variable === route.variable, + ); + if (!seen) routes.push(route); } return routes; } From 36cae3b0e29945a7811262c564db8c8f8c94413f Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 13:51:47 -0800 Subject: [PATCH 18/31] fix(box): Say to build again for the variable of a credential that this build adds, for the review comment on boxNetworkWriters.ts line 341 --- src/core/project/boxNetworkWriters.test.ts | 26 ++++++++++++++++++++++ src/core/project/boxNetworkWriters.ts | 13 +++++++++-- 2 files changed, 37 insertions(+), 2 deletions(-) diff --git a/src/core/project/boxNetworkWriters.test.ts b/src/core/project/boxNetworkWriters.test.ts index 8d7e0b9e3..00d6830a3 100644 --- a/src/core/project/boxNetworkWriters.test.ts +++ b/src/core/project/boxNetworkWriters.test.ts @@ -315,6 +315,32 @@ describe("unsentTargetWarnings", () => { ]); }); + test("says to build again for the variable of a credential that this build adds", () => { + const mirror = network({ + hosts: [ + host("mirror.example.com", "egress-mirror", { + outboundAuth: { + ...GITHUB_AUTH, + credentialName: "mirror", + variable: "AGENTCORE_CREDENTIAL_GITHUB", + }, + sources: [{ kind: "entry", egressEntry: "mirror", destinations: ["mirror.example.com"] }], + }), + ], + envRoutes: [ + { route: "github", variable: "GITHUB_TOKEN" }, + { route: "mirror", variable: "AGENTCORE_CREDENTIAL_GITHUB" }, + ], + }); + + expect(unsentTargetWarnings([mirror], contextFor())).toEqual([ + "mirror.example.com: build gives [egress.mirror] no gateway target, so the agent cannot " + + "reach this host on AgentCore Runtime. env://AGENTCORE_CREDENTIAL_GITHUB is the " + + "variable of the credential 'github', which this build adds to agentcore.json. Build " + + "again, and the next build gives the host its target.", + ]); + }); + test("names the credential and the variable when the credentials writer gives no reason", () => { expect(unsentTargetWarnings([github([])], contextFor())).toEqual([ "api.github.com: build gives [egress.github] no gateway target, so the agent cannot reach " + diff --git a/src/core/project/boxNetworkWriters.ts b/src/core/project/boxNetworkWriters.ts index dc73e077b..d99a0dfe3 100644 --- a/src/core/project/boxNetworkWriters.ts +++ b/src/core/project/boxNetworkWriters.ts @@ -8,6 +8,7 @@ import { copyFileSync, existsSync, mkdirSync, rmSync, unlinkSync, writeFileSync import { dirname, join } from "node:path"; import { isDeepStrictEqual } from "node:util"; import type { EnvLocalEntry } from "../../handlers/project/types"; +import { credentialEnvironmentVariableNames } from "../../projectSchemas/credential"; import type { AgentCoreGatewayTarget } from "../../projectSchemas/gateway"; import type { ProjectSpec } from "../../projectSchemas/project"; import { @@ -343,10 +344,18 @@ export function unsentTargetWarnings( if (auth === undefined || source === undefined) continue; const [table, route] = source.kind === "entry" ? ["egress", source.egressEntry] : ["mcp", source.mcpEntry]; + // The model names a credential from agentcore.json before this build adds to it. + const holder = after.credentials.find((credential) => + credentialEnvironmentVariableNames(credential).includes(auth.variable), + ); const why = plan.unprovisioned.get(route) ?? - `agentcore.json has no API key credential '${auth.credentialName}' to hold the key of ` + - `env://${auth.variable}.`; + (holder + ? `env://${auth.variable} is the variable of the credential '${holder.name}', which ` + + "this build adds to agentcore.json. Build again, and the next build gives the host " + + "its target." + : `agentcore.json has no API key credential '${auth.credentialName}' to hold the key ` + + `of env://${auth.variable}.`); warnings.push( `${host.authority}: build gives [${table}.${route}] no gateway target, so the agent ` + `cannot reach this host on AgentCore Runtime. ${why}`, From 8b47d0ddb93556ce595882fcd58494a482a57651 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 13:55:26 -0800 Subject: [PATCH 19/31] refactor(box): Run the credential planner once, and read the record and the warnings from the written spec, for the review comment on boxNetworkWriters.ts line 214 --- src/core/project/boxNetworkWriters.test.ts | 51 +++++++++++-- src/core/project/boxNetworkWriters.ts | 83 ++++++++++------------ src/core/project/manager.tsx | 9 +-- 3 files changed, 86 insertions(+), 57 deletions(-) diff --git a/src/core/project/boxNetworkWriters.test.ts b/src/core/project/boxNetworkWriters.test.ts index 00d6830a3..0526206c3 100644 --- a/src/core/project/boxNetworkWriters.test.ts +++ b/src/core/project/boxNetworkWriters.test.ts @@ -12,7 +12,7 @@ import { gatewayTargetsWriter, runtimeProfileWriter, telemetryPolicyWriter, - unsentTargetWarnings, + type BoxNetworkWriteContext, type BoxNetworkWriter, } from "./boxNetworkWriters"; import { BOX_GATEWAY_TARGETS_FILE } from "./boxNetwork"; @@ -153,6 +153,41 @@ describe("boxNetworkEdits", () => { }); }); +describe("boxNetworkEdits", () => { + test("gives a writer's warnings and late files agentcore.json as every writer changed it", () => { + const seen: string[] = []; + const reader: BoxNetworkWriter = { + name: "reader", + writes: () => [{ kind: "file", path: "seen.txt" }], + edits: () => ({ + warnings: (spec) => [`warning: ${spec.name}`], + filesAfter: (spec) => { + seen.push(spec.name); + return [{ path: "seen.txt", text: spec.name }]; + }, + }), + }; + const renamer: BoxNetworkWriter = { + name: "renamer", + writes: () => [{ kind: "defaultTargets" }], + edits: () => ({ + spec: [ + (spec) => { + spec.name = "renamed"; + return []; + }, + ], + }), + }; + + const edits = boxNetworkEdits([reader, renamer], [], contextFor()); + + expect(seen).toEqual(["renamed"]); + expect(edits.files).toEqual([{ path: "seen.txt", text: "renamed" }]); + expect(edits.warnings).toEqual(["warning: renamed"]); + }); +}); + describe("gatewayTargetsWriter", () => { test("keeps a user's egress- target that the record does not name, and records the targets it writes", () => { const project = spec([ @@ -285,7 +320,11 @@ describe("gatewayTargetsWriter", () => { }); }); -describe("unsentTargetWarnings", () => { +describe("the warning for a host with no gateway target", () => { + /** The warnings of the credentials and gateway targets writers, as build runs them. */ + const warningsOf = (networks: BoxNetwork[], context: BoxNetworkWriteContext) => + boxNetworkEdits([credentialsWriter, gatewayTargetsWriter], networks, context).warnings; + const github = (envRoutes: BoxNetwork["envRoutes"]) => network({ hosts: [ @@ -299,13 +338,13 @@ describe("unsentTargetWarnings", () => { test("warns for no host whose credential the credentials writer adds", () => { const routes = [{ route: "github", variable: "GITHUB_TOKEN" }]; - expect(unsentTargetWarnings([github(routes)], contextFor())).toEqual([]); + expect(warningsOf([github(routes)], contextFor())).toEqual([]); }); test("says why a host gets no target, and what to do, from the credentials writer", () => { const routes = [{ route: "github", variable: "GITHUB_TOKEN" }]; expect( - unsentTargetWarnings([github(routes)], { ...contextFor(), env: {} }).map((w) => + warningsOf([github(routes)], { ...contextFor(), env: {} }).map((w) => w.replace(ENV_LOCAL_RELATIVE_PATH, ".env.local"), ), ).toEqual([ @@ -333,7 +372,7 @@ describe("unsentTargetWarnings", () => { ], }); - expect(unsentTargetWarnings([mirror], contextFor())).toEqual([ + expect(warningsOf([mirror], contextFor())).toEqual([ "mirror.example.com: build gives [egress.mirror] no gateway target, so the agent cannot " + "reach this host on AgentCore Runtime. env://AGENTCORE_CREDENTIAL_GITHUB is the " + "variable of the credential 'github', which this build adds to agentcore.json. Build " + @@ -342,7 +381,7 @@ describe("unsentTargetWarnings", () => { }); test("names the credential and the variable when the credentials writer gives no reason", () => { - expect(unsentTargetWarnings([github([])], contextFor())).toEqual([ + expect(warningsOf([github([])], contextFor())).toEqual([ "api.github.com: build gives [egress.github] no gateway target, so the agent cannot reach " + "this host on AgentCore Runtime. agentcore.json has no API key credential 'github' to " + "hold the key of env://GITHUB_TOKEN.", diff --git a/src/core/project/boxNetworkWriters.ts b/src/core/project/boxNetworkWriters.ts index d99a0dfe3..270968763 100644 --- a/src/core/project/boxNetworkWriters.ts +++ b/src/core/project/boxNetworkWriters.ts @@ -72,8 +72,12 @@ export interface BoxNetworkEdits { /** Changes to the copy of agentcore.json, in order; each returns its step messages. */ readonly spec?: readonly ((spec: ProjectSpec) => string[])[]; readonly files?: readonly BoxNetworkFile[]; + /** Files that depend on the copy of agentcore.json once every writer changed it. */ + readonly filesAfter?: (spec: ProjectSpec) => readonly BoxNetworkFile[]; /** Entries for `.env.local`; each replaces the value it holds under that key. */ readonly envLocal?: readonly EnvLocalEntry[]; + /** Warnings on the copy of agentcore.json once every writer changed it. */ + readonly warnings?: (spec: ProjectSpec) => readonly string[]; } /** What a writer reads besides the models: the project, and where build looks for each key. */ @@ -104,6 +108,7 @@ export interface CollectedEdits { readonly files: readonly BoxNetworkFile[]; readonly envLocal: readonly EnvLocalEntry[]; readonly messages: readonly string[]; + readonly warnings: readonly string[]; } /** @@ -131,12 +136,17 @@ export function boxNetworkEdits( const messages: string[] = []; const files: BoxNetworkFile[] = []; const envLocal: EnvLocalEntry[] = []; - for (const writer of writers) { - const edits = writer.edits(networks, context); + const all = writers.map((writer) => writer.edits(networks, context)); + for (const edits of all) { for (const change of edits.spec ?? []) messages.push(...change(spec)); files.push(...(edits.files ?? [])); envLocal.push(...(edits.envLocal ?? [])); } + const warnings: string[] = []; + for (const edits of all) { + files.push(...(edits.filesAfter?.(spec) ?? [])); + warnings.push(...(edits.warnings?.(spec) ?? [])); + } const changedFields = (Object.keys(spec) as (keyof ProjectSpec)[]).filter( (field) => !isDeepStrictEqual(spec[field], context.spec[field]), ); @@ -147,6 +157,7 @@ export function boxNetworkEdits( files, envLocal, messages, + warnings, }; } @@ -188,6 +199,7 @@ export const credentialsWriter: BoxNetworkWriter = { }, ], envLocal: plan.entries, + warnings: (written) => unsentTargetWarnings(written, networks, plan.unprovisioned), }; }, }; @@ -217,47 +229,29 @@ export const gatewayTargetsWriter: BoxNetworkWriter = { ...networks.map(({ gateway }) => ({ kind: "gatewayTargets" as const, gateway })), ...(networks.length > 0 ? [{ kind: "file" as const, path: BOX_GATEWAY_TARGETS_FILE }] : []), ], - edits: (networks, context) => { + edits: (networks) => { if (networks.length === 0) return {}; - const after = withPlannedCredentials(networks, context).spec; - const record = Object.fromEntries( - networks.map((network) => [ - network.gateway, - [ - ...new Set( - network.hosts.flatMap((host) => - host.target !== undefined && - network.managedTargets.has(host.target) && - undeclaredKey(after, host) === undefined - ? [host.target] - : [], - ), - ), - ], - ]), - ); return { spec: networks.map((network) => (spec: ProjectSpec) => writeGatewayTargets(spec, network)), - files: [{ path: BOX_GATEWAY_TARGETS_FILE, text: boxGatewayTargetsText(record) }], + filesAfter: (written) => [ + { + path: BOX_GATEWAY_TARGETS_FILE, + text: boxGatewayTargetsText( + Object.fromEntries( + networks.map((network) => [ + network.gateway, + (boxGatewayOf(written, network.runtime)?.targets ?? []).flatMap(({ name }) => + network.managedTargets.has(name) ? [name] : [], + ), + ]), + ), + ), + }, + ], }; }, }; -/** - * `context.spec` with the API key credentials that the credentials writer adds, and the plan that - * adds them. - */ -function withPlannedCredentials( - networks: readonly BoxNetwork[], - { spec, env, envLocal }: BoxNetworkWriteContext, -): { spec: ProjectSpec; plan: ReturnType } { - const plan = planBoxProfileCredentials(structuredClone(spec), uniqueRoutes(networks), { - env, - envLocal, - }); - return { spec: { ...spec, credentials: [...spec.credentials, ...plan.added] }, plan }; -} - /** * Sets the build-owned targets of the network's Box gateway: a managed target that a host takes is * rewritten in place, every other managed target goes, a host whose managed target the gateway @@ -324,19 +318,20 @@ function writeGatewayTargets(spec: ProjectSpec, network: BoxNetwork): string[] { /** * A warning for each host of `networks` that gets no gateway target because no API key credential - * of agentcore.json, once the credentials writer runs, holds the key its target sends: the agent - * cannot reach the host on AgentCore Runtime. It says why, and what to do. + * of `spec`, agentcore.json as the writers changed it, holds the key its target sends: the agent + * cannot reach the host on AgentCore Runtime. It says why, from the credential planner's + * `unprovisioned`, and what to do. */ -export function unsentTargetWarnings( +function unsentTargetWarnings( + spec: ProjectSpec, networks: readonly BoxNetwork[], - context: BoxNetworkWriteContext, + unprovisioned: ReadonlyMap, ): string[] { - const { spec: after, plan } = withPlannedCredentials(networks, context); const warnings: string[] = []; for (const { hosts, managedTargets } of networks) for (const host of hosts) { if (host.target === undefined || !managedTargets.has(host.target)) continue; - const auth = undeclaredKey(after, host); + const auth = undeclaredKey(spec, host); const source = host.sources.find( (candidate): candidate is Exclude => candidate.kind !== "rule", @@ -345,11 +340,11 @@ export function unsentTargetWarnings( const [table, route] = source.kind === "entry" ? ["egress", source.egressEntry] : ["mcp", source.mcpEntry]; // The model names a credential from agentcore.json before this build adds to it. - const holder = after.credentials.find((credential) => + const holder = spec.credentials.find((credential) => credentialEnvironmentVariableNames(credential).includes(auth.variable), ); const why = - plan.unprovisioned.get(route) ?? + unprovisioned.get(route) ?? (holder ? `env://${auth.variable} is the variable of the credential '${holder.name}', which ` + "this build adds to agentcore.json. Build again, and the next build gives the host " + diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx index 605cf8cff..29908c5c8 100644 --- a/src/core/project/manager.tsx +++ b/src/core/project/manager.tsx @@ -59,12 +59,7 @@ import { boxNetworkFailureMessage, readBoxNetworks } from "./boxNetworkSource"; import { DEFAULT_REGION, regionFromConfigFile } from "../region"; import { BoxCliProfileResolver, type BoxProfileResolver } from "./boxProfileResolver"; import { addBoxGatewaysToRecord, BOX_GATEWAY_TARGETS_FILE } from "./boxGatewayTargets"; -import { - BOX_NETWORK_WRITERS, - boxNetworkEdits, - unsentTargetWarnings, - writeBoxNetworkFiles, -} from "./boxNetworkWriters"; +import { BOX_NETWORK_WRITERS, boxNetworkEdits, writeBoxNetworkFiles } from "./boxNetworkWriters"; import { createProjectTree } from "./templates/project"; import { BOX_CODEZIP_ENTRYPOINT, @@ -1743,7 +1738,7 @@ export class FsProjectManager implements ProjectManager { ...network.warnings, ...boxGatewayIamWarnings(edits.spec, network), ]), - ...unsentTargetWarnings(networks, context), + ...edits.warnings, ]; const events: ProjectEvent[] = [ ...messages.map((message) => ({ type: "step" as const, message })), From 54e25ad9fe5e460c9699e34b3f883bcee34884a9 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 13:56:25 -0800 Subject: [PATCH 20/31] refactor(box): Replace the two entity casts with one type predicate, for the review comment on conditions.ts line 307 --- src/core/project/boxNetwork/conditions.ts | 31 ++++++++++----------- src/core/project/boxNetwork/hostMap.test.ts | 5 ++++ 2 files changed, 19 insertions(+), 17 deletions(-) diff --git a/src/core/project/boxNetwork/conditions.ts b/src/core/project/boxNetwork/conditions.ts index 5d21722bb..dfbf6fef5 100644 --- a/src/core/project/boxNetwork/conditions.ts +++ b/src/core/project/boxNetwork/conditions.ts @@ -300,15 +300,7 @@ function actionValue(expr: Expr, action: NetworkAction): boolean | undefined { if (expr.op !== "==" && expr.op !== "!=" && expr.op !== "in") return undefined; const variable = attributePath(expr.left); if (variable?.length !== 1 || variable[0] !== "action") return undefined; - const right = expr.right; - const entities = - right.kind === "entity" - ? [right.entity] - : expr.op === "in" && - right.kind === "set" && - right.items.every((i) => i.kind === "entity") - ? right.items.map((i) => (i as Extract).entity) - : undefined; + const entities = namedEntities(expr); if (!entities) return undefined; const matches = entities.some((e) => sameEntity(e, { type: ["Box", "Action"], id: action })); return expr.op === "!=" ? !matches : matches; @@ -510,14 +502,7 @@ function identityFormula( ): Formula | undefined { const variable = attributePath(expr.left); if (variable?.length !== 1) return undefined; - const entities = - expr.right.kind === "entity" - ? [expr.right.entity] - : expr.op === "in" && - expr.right.kind === "set" && - expr.right.items.every((i) => i.kind === "entity") - ? expr.right.items.map((i) => (i as Extract).entity) - : undefined; + const entities = namedEntities(expr); if (!entities) return undefined; let matches: boolean; if (variable[0] === "action") { @@ -532,6 +517,18 @@ function identityFormula( return constant(expr.op === "!=" ? !matches : matches, expr.text); } +/** The entities the right of `==`, `!=`, or `in` names: one entity, or a set of entities. */ +function namedEntities(expr: Extract): EntityRef[] | undefined { + const right = expr.right; + if (right.kind === "entity") return [right.entity]; + if (expr.op !== "in" || right.kind !== "set" || !right.items.every(isEntity)) return undefined; + return right.items.map((item) => item.entity); +} + +function isEntity(expr: Expr): expr is Extract { + return expr.kind === "entity"; +} + /** Why a rule that names the `Box::Action` `id`, which Box does not have, fails. */ export function unknownActionReason(id: string): string { return ( diff --git a/src/core/project/boxNetwork/hostMap.test.ts b/src/core/project/boxNetwork/hostMap.test.ts index 592424070..ff82b2ccc 100644 --- a/src/core/project/boxNetwork/hostMap.test.ts +++ b/src/core/project/boxNetwork/hostMap.test.ts @@ -145,6 +145,11 @@ describe("the policy decision on each host", () => { false, ], ["if", `(if ${NC} then true else context.input.method == "GET")`, true], + [ + "|| with in", + `(action in [Box::Action::"net:connect"] || context.input.method == "GET")`, + true, + ], ])("accepts a connection rule that reads a request field behind %s", (_, guard, reachable) => { const result = map(connect("guarded", on("a.example.com", guard)) + get); expect(codes(result)).toEqual([]); From 065825ae6e217d02b9003d1771376a02e8b0f74e Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 13:56:49 -0800 Subject: [PATCH 21/31] docs(box): Say when to edit agentcore/box-gateway-targets.json, for the review comment on network.ts line 377 --- docs/box-local-testing.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/box-local-testing.md b/docs/box-local-testing.md index dd1897753..859bca474 100644 --- a/docs/box-local-testing.md +++ b/docs/box-local-testing.md @@ -139,7 +139,9 @@ the generated packs, and the policy files into `.box//aws/` for you to keeps as yours. Commit `agentcore/box-gateway-targets.json` with `agentcore.json`: in a clone without it, build goes back to that `egress-` rule, and can take or give up the wrong targets. The `.gitignore` that - `agentcore create` writes does not exclude it. + `agentcore create` writes does not exclude it. Build writes the file, but you edit it in one case: + when you change a target that build wrote, build stops and tells you to remove that target's name + from the file to keep the target as yours. Then build no longer records, changes, or removes it. - **Outbound auth.** An `aws://` secret signs with the gateway's role, an `env://` secret sends an API key from AgentCore Identity, and an entry with no secret sends no credential. - **Failures.** A wildcard host, a plain-HTTP-only host, an unsupported secret or pack, an From 808e9c4d375e7806ae608b04612d34737f739c56 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 16:14:20 -0800 Subject: [PATCH 22/31] test(box): Test a guardrails condition beside the temporal one, for the review comment on hostMap.test.ts --- src/core/project/boxNetwork/hostMap.test.ts | 38 +++++++++++++-------- 1 file changed, 23 insertions(+), 15 deletions(-) diff --git a/src/core/project/boxNetwork/hostMap.test.ts b/src/core/project/boxNetwork/hostMap.test.ts index ff82b2ccc..7986729a0 100644 --- a/src/core/project/boxNetwork/hostMap.test.ts +++ b/src/core/project/boxNetwork/hostMap.test.ts @@ -172,22 +172,30 @@ describe("the policy decision on each host", () => { expect(codes(map(later + reach("get", "a.example.com")))).toEqual([]); }); - test("reads a host condition after a temporal condition, which no action test decides", () => { - const temporal = + // Box 0.1.11-preview.10 accepts each of these bodies before a host `when`. + test.each([ + [ + "temporal", "exists (n: Long). ((count for (t: Timepoint). where (formerly within 10m (" + - 'Box::Action::"http:request"::response{ input.host: "api.github.com" } && tp(t)))) == n ' + - "&& n < 3)"; - const limited = rule( - "limited", - `permit (principal, ${HR}, resource) when temporal { ${temporal} } when { ${on("a.example.com")} };`, - ); - const result = map(connect("c", on("a.example.com")) + limited); - expect(codes(result)).toEqual([]); - expect(host(result, "a.example.com")).toMatchObject({ - reachable: true, - enforcedByBox: ["limited"], - }); - }); + 'Box::Action::"http:request"::response{ input.host: "api.github.com" } && tp(t)))) == n ' + + "&& n < 3)", + ], + ["guardrails", 'context.input.method == "GET"'], + ])( + "reads a host condition after a %s condition, which no action test decides", + (kind, body) => { + const limited = rule( + "limited", + `permit (principal, ${HR}, resource) when ${kind} { ${body} } when { ${on("a.example.com")} };`, + ); + const result = map(connect("c", on("a.example.com")) + limited); + expect(codes(result)).toEqual([]); + expect(host(result, "a.example.com")).toMatchObject({ + reachable: true, + enforcedByBox: ["limited"], + }); + }, + ); test("refuses the field when no action test keeps it from the action", () => { const result = map( From df61acb4362625e1c34245a7b89410ef8d75d29f Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 16:14:48 -0800 Subject: [PATCH 23/31] test(box): Drop the unused column of the rotated key test, for the review comment on boxNetworkWriters.test.ts --- src/core/project/boxNetworkWriters.test.ts | 56 +++++++++++----------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/src/core/project/boxNetworkWriters.test.ts b/src/core/project/boxNetworkWriters.test.ts index 0526206c3..551e95e0d 100644 --- a/src/core/project/boxNetworkWriters.test.ts +++ b/src/core/project/boxNetworkWriters.test.ts @@ -408,35 +408,35 @@ describe("credentialsWriter", () => { ]); }); - test.each([ - ["the credential's own variable", "first"], - ["the other variable", "first"], - ])("stores a rotated key of a route that two runtimes read, with %s %s", (first) => { - const own = network({ - envRoutes: [{ route: "github", variable: "AGENTCORE_CREDENTIAL_GITHUB" }], - }); - const alias = network({ - runtime: "other", - gateway: "other-box-egress", - envRoutes: [{ route: "github", variable: "GITHUB_TOKEN" }], - }); - const project = spec(); - project.credentials.push({ authorizerType: "ApiKeyCredentialProvider", name: "github" }); - - const edits = boxNetworkEdits( - [credentialsWriter], - first === "the credential's own variable" ? [own, alias] : [alias, own], - { - ...contextFor(project), - env: { GITHUB_TOKEN: "ghp_new" }, - envLocal: { AGENTCORE_CREDENTIAL_GITHUB: "ghp_old" }, - }, - ); + test.each([["the credential's own variable"], ["the other variable"]])( + "stores a rotated key of a route that two runtimes read, with %s first", + (first) => { + const own = network({ + envRoutes: [{ route: "github", variable: "AGENTCORE_CREDENTIAL_GITHUB" }], + }); + const alias = network({ + runtime: "other", + gateway: "other-box-egress", + envRoutes: [{ route: "github", variable: "GITHUB_TOKEN" }], + }); + const project = spec(); + project.credentials.push({ authorizerType: "ApiKeyCredentialProvider", name: "github" }); + + const edits = boxNetworkEdits( + [credentialsWriter], + first === "the credential's own variable" ? [own, alias] : [alias, own], + { + ...contextFor(project), + env: { GITHUB_TOKEN: "ghp_new" }, + envLocal: { AGENTCORE_CREDENTIAL_GITHUB: "ghp_old" }, + }, + ); - expect(edits.envLocal).toEqual([ - expect.objectContaining({ key: "AGENTCORE_CREDENTIAL_GITHUB", value: "ghp_new" }), - ]); - }); + expect(edits.envLocal).toEqual([ + expect.objectContaining({ key: "AGENTCORE_CREDENTIAL_GITHUB", value: "ghp_new" }), + ]); + }, + ); test("runs before the gateway targets, so a target gets the credential it adds", () => { const models = [ From 25a3faaa2511afab74c63a9b23cb90781038d1aa Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 16:15:37 -0800 Subject: [PATCH 24/31] test(box): Compare the whole host or host:port of a warning, for the review nit on split in manager.boxNetwork.test.ts --- src/core/project/manager.boxNetwork.test.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/core/project/manager.boxNetwork.test.ts b/src/core/project/manager.boxNetwork.test.ts index 284bde3d7..edf2e1823 100644 --- a/src/core/project/manager.boxNetwork.test.ts +++ b/src/core/project/manager.boxNetwork.test.ts @@ -182,6 +182,8 @@ async function strandsProject( const path = (root: string, relative: string) => join(root, ...relative.split("/")); const text = (root: string, relative: string) => readFile(path(root, relative), "utf8"); +/** The `host` or `host:port` a host warning starts with, before its first ": ". */ +const authorityOf = (warning: string) => warning.slice(0, Math.max(warning.indexOf(": "), 0)); /** Adds `tables` to the end of the profile, `top` to its start, and writes `.box/agent_python_strands/local/policy.dw`. */ async function editProfile(root: string, edit: { top?: string; tables?: string; policy?: string }) { @@ -380,6 +382,7 @@ describe("build writes the Box network of the box profile", () => { const first = await build(manager, root); expect(await targetNames(root)).toEqual(["bedrock", "agentcore"]); + expect(first.warnings.filter((w) => authorityOf(w) === "api.openai.com")).toHaveLength(1); expect(first.warnings).toContain( "api.openai.com: build gives [egress.openai] no gateway target, so the agent cannot reach " + `this host on AgentCore Runtime. OPENAI_API_KEY is not set here or in ${ENV_LOCAL_RELATIVE_PATH}. ` + @@ -391,7 +394,7 @@ describe("build writes the Box network of the box profile", () => { ]); const second = await build(manager, root); expect(await targetNames(root)).toEqual(["bedrock", "agentcore", "egress-openai"]); - expect(second.warnings.filter((w) => w.split(":", 1)[0] === "api.openai.com")).toEqual([]); + expect(second.warnings.filter((w) => authorityOf(w) === "api.openai.com")).toEqual([]); }); test("keeps a user's egress- target that a new project has before its first build", async () => { From 854efbd9c58e14bd84bba64ad7582c9d8f3bbee7 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 17:30:22 -0800 Subject: [PATCH 25/31] refactor(box): Keep the targets build owns in one function, for the Chorus note on PR 2887 --- src/core/project/boxNetwork/network.ts | 19 +++++++++++++++++-- src/core/project/boxNetworkWriters.ts | 26 ++++++++++++++++---------- 2 files changed, 33 insertions(+), 12 deletions(-) diff --git a/src/core/project/boxNetwork/network.ts b/src/core/project/boxNetwork/network.ts index 6d026f211..373c588d5 100644 --- a/src/core/project/boxNetwork/network.ts +++ b/src/core/project/boxNetwork/network.ts @@ -541,11 +541,26 @@ function hostTargets( place: profilePath, }); } - const managed = new Set(existing.filter(isManaged).map(({ name }) => name)); + const managed = managedTargetsOf(existing.filter(isManaged), hosts, reused); + return { hosts, failures, managed, warnings }; +} + +/** + * The targets of a Box gateway that build owns (`BoxNetwork.managedTargets`), which the writers + * change and remove and the record lists: each target of `owned`, and the new target of each host + * that takes no target the gateway has (`reused`). Each other kind of target that build writes + * belongs in this set too. + */ +function managedTargetsOf( + owned: readonly AgentCoreGatewayTarget[], + hosts: readonly BoxNetworkHost[], + reused: ReadonlySet, +): Set { + const managed = new Set(owned.map(({ name }) => name)); hosts.forEach(({ target }, index) => { if (target !== undefined && !reused.has(index)) managed.add(target); }); - return { hosts, failures, managed, warnings }; + return managed; } /** The source of the entry that names a host. */ diff --git a/src/core/project/boxNetworkWriters.ts b/src/core/project/boxNetworkWriters.ts index 6ec04747b..d4ab80b25 100644 --- a/src/core/project/boxNetworkWriters.ts +++ b/src/core/project/boxNetworkWriters.ts @@ -236,22 +236,28 @@ export const gatewayTargetsWriter: BoxNetworkWriter = { filesAfter: (written) => [ { path: BOX_GATEWAY_TARGETS_FILE, - text: boxGatewayTargetsText( - Object.fromEntries( - networks.map((network) => [ - network.gateway, - (boxGatewayOf(written, network.runtime)?.targets ?? []).flatMap(({ name }) => - network.managedTargets.has(name) ? [name] : [], - ), - ]), - ), - ), + text: boxGatewayTargetsText(recordOf(written, networks)), }, ], }; }, }; +/** + * The record of the targets build writes: for each Box gateway, the targets of the gateway in + * `spec`, agentcore.json as the writers changed it, that the model owns (`managedTargets`). + */ +function recordOf(spec: ProjectSpec, networks: readonly BoxNetwork[]): Record { + return Object.fromEntries( + networks.map((network) => [ + network.gateway, + (boxGatewayOf(spec, network.runtime)?.targets ?? []).flatMap(({ name }) => + network.managedTargets.has(name) ? [name] : [], + ), + ]), + ); +} + /** * Sets the build-owned targets of the network's Box gateway: a managed target that a host takes is * rewritten in place, every other managed target goes, a host whose managed target the gateway From adad22d48fd683c322d17b7ca5a6b868b7c4ce7a Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 17:31:43 -0800 Subject: [PATCH 26/31] fix(box): Drop the record entry of each Box gateway that remove runtime or remove all deletes, for the Chorus note on manager.tsx line 1270 --- src/core/project/boxGatewayTargets.ts | 25 +++++++++++++++++++++ src/core/project/manager.box.test.ts | 31 +++++++++++++++++++++++++++ src/core/project/manager.tsx | 15 ++++++++++++- 3 files changed, 70 insertions(+), 1 deletion(-) diff --git a/src/core/project/boxGatewayTargets.ts b/src/core/project/boxGatewayTargets.ts index a4e67cd52..086381b6e 100644 --- a/src/core/project/boxGatewayTargets.ts +++ b/src/core/project/boxGatewayTargets.ts @@ -62,3 +62,28 @@ export function addBoxGatewaysToRecord(projectRoot: string, gateways: readonly s writeFileSync(path, boxGatewayTargetsText(record)); return true; } + +/** + * Removes the entry of each of `gateways` from the record, when the record names it. Returns + * whether it wrote the record; it leaves a file that is not the record to build, which refuses it. + */ +export function removeBoxGatewaysFromRecord( + projectRoot: string, + gateways: readonly string[], +): boolean { + let record: Record | undefined; + try { + record = readBoxGatewayTargets(projectRoot); + } catch (error) { + if (error instanceof ProjectStateError) return false; + throw error; + } + const named = gateways.filter( + (gateway) => record !== undefined && Object.hasOwn(record, gateway), + ); + if (record === undefined || named.length === 0) return false; + for (const gateway of named) delete record[gateway]; + const path = join(projectRoot, ...BOX_GATEWAY_TARGETS_FILE.split("/")); + writeFileSync(path, boxGatewayTargetsText(record)); + return true; +} diff --git a/src/core/project/manager.box.test.ts b/src/core/project/manager.box.test.ts index 9f93c9011..7b97a91c5 100644 --- a/src/core/project/manager.box.test.ts +++ b/src/core/project/manager.box.test.ts @@ -574,6 +574,32 @@ describe("gateway targets in a Box project", () => { ]); }); + test("remove runtime drops its Box gateway from the record, so add runtime again writes an empty entry", async () => { + const manager = subject(); + let project = await createdProject(manager, ["agent", "search"]); + await writeFile( + recordOf(project), + '{\n "agent-box-egress": ["egress-a"],\n "search-box-egress": ["egress-old"]\n}\n', + ); + + project = (await manager.removeResource(project, { resourceType: "runtime", name: "search" })) + .project; + expect(JSON.parse(await readFile(recordOf(project), "utf8"))).toEqual({ + "agent-box-egress": ["egress-a"], + }); + + await drain( + manager.addResource(project, { + resourceType: "runtime", + resourceConfig: { name: "search", language: "Python", protocol: "HTTP" }, + } as never), + ); + expect(JSON.parse(await readFile(recordOf(project), "utf8"))).toEqual({ + "agent-box-egress": ["egress-a"], + "search-box-egress": [], + }); + }); + test("add runtime refuses a start.py of the user's own, and changes nothing", async () => { const manager = subject(); const project = await createdProject(manager); @@ -921,7 +947,9 @@ describe("gateway targets in a Box project", () => { test("remove all, then add runtime, adds a box runtime, as the project is still a Box project", async () => { const manager = subject(); let project = await createdProject(manager); + await writeFile(recordOf(project), '{\n "agent-box-egress": ["egress-old"]\n}\n'); project = (await manager.removeAllResources(project)).project; + expect(JSON.parse(await readFile(recordOf(project), "utf8"))).toEqual({}); await drain( manager.addResource(project, { @@ -935,6 +963,9 @@ describe("gateway targets in a Box project", () => { ["agent", { version: BOX_RELEASE.version }], ]); expect(spec.agentCoreGateways.map(({ boundRuntime }) => boundRuntime)).toEqual(["agent"]); + expect(JSON.parse(await readFile(recordOf(project), "utf8"))).toEqual({ + "agent-box-egress": [], + }); }); }); diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx index 29908c5c8..ecf8208c5 100644 --- a/src/core/project/manager.tsx +++ b/src/core/project/manager.tsx @@ -58,7 +58,11 @@ import { boxGatewayIamWarnings, type BoxNetwork } from "./boxNetwork"; import { boxNetworkFailureMessage, readBoxNetworks } from "./boxNetworkSource"; import { DEFAULT_REGION, regionFromConfigFile } from "../region"; import { BoxCliProfileResolver, type BoxProfileResolver } from "./boxProfileResolver"; -import { addBoxGatewaysToRecord, BOX_GATEWAY_TARGETS_FILE } from "./boxGatewayTargets"; +import { + addBoxGatewaysToRecord, + BOX_GATEWAY_TARGETS_FILE, + removeBoxGatewaysFromRecord, +} from "./boxGatewayTargets"; import { BOX_NETWORK_WRITERS, boxNetworkEdits, writeBoxNetworkFiles } from "./boxNetworkWriters"; import { createProjectTree } from "./templates/project"; import { @@ -1299,6 +1303,11 @@ export class FsProjectManager implements ProjectManager { } const newProjectSpec = await this.commitSpec(agentCoreSpecPath, newSpec, envFile); + // A Box gateway that goes takes its entry in the record of build's targets with it. + removeBoxGatewaysFromRecord( + project.rootPath, + removedGateways.map(({ name }) => name), + ); // Build and deploy generate the runtime's .box//aws/ folder, so it goes with the runtime. // Its .box//local/ profile is the user's, as its code folder is, so it stays. if (input.resourceType === "runtime") { @@ -1355,6 +1364,10 @@ export class FsProjectManager implements ProjectManager { }; const newProjectSpec = await this.commitSpec(agentCoreSpecPath, newSpec, envFile); + removeBoxGatewaysFromRecord( + project.rootPath, + existingProjectSpec.agentCoreGateways.map(({ name }) => name), + ); return { project: { ...project, spec: newProjectSpec }, From 298dac84d7d8c6af768284e8a012651465c5e50f Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 17:32:15 -0800 Subject: [PATCH 27/31] docs(box): Say that build provisions a model-provider key from the shell, for the Chorus note on item 10 --- README.md | 5 ++++- docs/box-local-testing.md | 4 ++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 65dab78c2..61a939a02 100644 --- a/README.md +++ b/README.md @@ -75,7 +75,10 @@ flags: for templates that take a model provider (`agent-python-strands` and its variant, `a2a-python-strands`, `agui-python-strands`, `agent-typescript-strands`) the wizard asks for the provider (Amazon Bedrock, Anthropic, OpenAI, an OpenAI-compatible endpoint, Gemini, or LiteLLM, which is Python-only), the model id, and an API-key file. The API key is kept in -`agentcore/.env.local` and provisioned as an AgentCore Identity credential on deploy. +`agentcore/.env.local` and provisioned as an AgentCore Identity credential on deploy. For a Box +template created with no API key, build reads the provider's key (such as `OPENAI_API_KEY`) from +your shell or `agentcore/.env.local`, adds a credential such as `openai`, and deploy provisions +that key in AgentCore Identity. To bring your own code into a project instead, add a runtime for it: diff --git a/docs/box-local-testing.md b/docs/box-local-testing.md index 38fe66712..afed277a2 100644 --- a/docs/box-local-testing.md +++ b/docs/box-local-testing.md @@ -225,6 +225,10 @@ A profile that names a pack `box/` fails: box refuses it and names the `@b changes, or removes it. - **Outbound auth.** An `aws://` secret signs with the gateway's role, an `env://` secret sends an API key from AgentCore Identity, and an entry with no secret sends no credential. + This includes the model-provider route that `agentcore create` writes when you give it no key, + such as `[egress.openai]` with `env://OPENAI_API_KEY` (also for Anthropic and Gemini). When that + key is set in your shell or in `agentcore/.env.local`, build adds an API key credential such as + `openai`, and deploy provisions your key in AgentCore Identity. - **Failures.** A profile Box refuses stops build and deploy with box's own error. A wildcard host, a plain-HTTP-only host, an unsupported secret, an MCP server that names more than one host, a path, or a port other than 443, and similar cases stop them too. The error starts with `Build stopped:` or `Deploy stopped:` and the From 006f4baafdf7356d6949cd65ae57cb3154dd7ca2 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 17:33:38 -0800 Subject: [PATCH 28/31] fix(box): Give equal path patterns one machine, for the Chorus nit on pathSolver.ts --- .../project/boxNetwork/pathSolver.test.ts | 20 +++++++- src/core/project/boxNetwork/pathSolver.ts | 48 ++++++++++++++----- 2 files changed, 56 insertions(+), 12 deletions(-) diff --git a/src/core/project/boxNetwork/pathSolver.test.ts b/src/core/project/boxNetwork/pathSolver.test.ts index fc4dfa121..064af2882 100644 --- a/src/core/project/boxNetwork/pathSolver.test.ts +++ b/src/core/project/boxNetwork/pathSolver.test.ts @@ -1,7 +1,7 @@ import { describe, expect, test } from "bun:test"; import type { Comparison, FieldAtom } from "./conditions"; import type { LikePattern } from "./dogwood"; -import { findPath, pathTest, type PathTest } from "./pathSolver"; +import { findPath, machinesFor, pathTest, type PathTest } from "./pathSolver"; /** A `like` pattern, with each `*` as a wildcard. */ function like(text: string): LikePattern { @@ -85,3 +85,21 @@ describe("findPath", () => { expect(path([..."abcdefghijklm"].map((c) => must(`*${c}*`)))).toBe("undecided"); }); }); + +describe("machinesFor", () => { + test("gives equal patterns from different atoms one machine, beside the one for the leading /", () => { + const a = pathTest(atom({ op: "==", value: "/a" })) as PathTest; + const b = pathTest(atom({ op: "!=", value: "/a" }, true)) as PathTest; + expect(a.pattern).not.toBe(b.pattern); + expect(machinesFor([a, must("/v1/*")], [[b], [must("/v1/*")]]).count).toBe(3); + }); + + test("keeps a literal * apart from a wildcard", () => { + const star: PathTest = { + pattern: { parts: [{ kind: "literal", text: "/a*" }] }, + matches: true, + }; + expect(machinesFor([star, must("/a*")], []).count).toBe(3); + expect(findPath([star], [], "ยง")).toEqual({ kind: "path", path: "/a*" }); + }); +}); diff --git a/src/core/project/boxNetwork/pathSolver.ts b/src/core/project/boxNetwork/pathSolver.ts index 257f0c83e..a87f6471c 100644 --- a/src/core/project/boxNetwork/pathSolver.ts +++ b/src/core/project/boxNetwork/pathSolver.ts @@ -48,17 +48,7 @@ export function findPath( filler: string, ): PathSearch { if (excluded.some((group) => group.length === 0)) return { kind: "none" }; - const patterns: LikePattern[] = []; - const indexOf = (pattern: LikePattern) => { - const at = patterns.indexOf(pattern); - return at === -1 ? patterns.push(pattern) - 1 : at; - }; - const wanted = [ROOTED, ...required].map((test) => ({ ...test, at: indexOf(test.pattern) })); - const groups = excluded.map((group) => - group.map((test) => ({ ...test, at: indexOf(test.pattern) })), - ); - const machines = patterns.map(machineOf); - const literals = new Set(patterns.flatMap((p) => p.parts.flatMap(literalChars))); + const { machines, wanted, groups, literals } = machinesFor(required, excluded); const alphabet = [...literals, freeChar(literals, filler)]; const start = machines.map((machine) => machine.closure([0])); @@ -89,6 +79,42 @@ export function findPath( return { kind: "none" }; } +/** + * One machine for each different pattern of the tests, with the leading `/` that each path has, + * and each test with the index of its pattern's machine. Equal patterns share one machine. + */ +export function machinesFor( + required: readonly PathTest[], + excluded: readonly (readonly PathTest[])[], +) { + const patterns: LikePattern[] = []; + const byKey = new Map(); + const indexOf = (pattern: LikePattern) => { + const key = patternKey(pattern); + const at = byKey.get(key) ?? patterns.push(pattern) - 1; + byKey.set(key, at); + return at; + }; + const wanted = [ROOTED, ...required].map((test) => ({ ...test, at: indexOf(test.pattern) })); + const groups = excluded.map((group) => + group.map((test) => ({ ...test, at: indexOf(test.pattern) })), + ); + return { + machines: patterns.map(machineOf), + count: patterns.length, + wanted, + groups, + literals: new Set(patterns.flatMap((p) => p.parts.flatMap(literalChars))), + }; +} + +/** A pattern as text, with each wildcard as `*` and each literal `*` and `\` escaped. */ +function patternKey(pattern: LikePattern): string { + return pattern.parts + .map((part) => (part.kind === "wildcard" ? "*" : part.text.replace(/[\\*]/g, "\\$&"))) + .join(""); +} + /** A pattern as a machine whose state is the set of places in the pattern a prefix reaches. */ function machineOf(pattern: LikePattern) { const items = pattern.parts.flatMap((part) => From f43a55a82f3699b4579c02e021f24ad336f16613 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 17:56:15 -0800 Subject: [PATCH 29/31] fix(box): Keep the record and agentcore.json the same when either write fails, for the review nit on manager.tsx --- src/core/project/boxGatewayTargets.ts | 73 +++++++++++++--------- src/core/project/manager.box.test.ts | 87 +++++++++++++++++++++++++++ src/core/project/manager.tsx | 66 ++++++++++++++------ src/core/project/templates/project.ts | 3 +- 4 files changed, 183 insertions(+), 46 deletions(-) diff --git a/src/core/project/boxGatewayTargets.ts b/src/core/project/boxGatewayTargets.ts index 086381b6e..0e3e52f4b 100644 --- a/src/core/project/boxGatewayTargets.ts +++ b/src/core/project/boxGatewayTargets.ts @@ -3,7 +3,7 @@ * owns those targets, and no other. `agentcore create` and `agentcore add runtime` write an empty * entry for each new Box gateway, so the `egress-` rule applies only to a gateway an older CLI made. */ -import { existsSync, readFileSync, writeFileSync } from "node:fs"; +import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs"; import { join } from "node:path"; import { z } from "zod"; import { ProjectStateError } from "../../errors/errors"; @@ -43,47 +43,64 @@ export function readBoxGatewayTargets(projectRoot: string): Record void; + /** - * Adds an empty entry for each of `gateways` that the record does not name yet. Returns whether it - * wrote the record; it leaves a file that is not the record to build, which refuses it. + * Adds an empty entry for each of `gateways` that the record does not name yet. Returns the + * function that puts the record back, when it wrote the record; it leaves a file that is not the + * record to build, which refuses it. */ -export function addBoxGatewaysToRecord(projectRoot: string, gateways: readonly string[]): boolean { - let record: Record; - try { - record = readBoxGatewayTargets(projectRoot) ?? {}; - } catch (error) { - if (error instanceof ProjectStateError) return false; - throw error; - } - const added = gateways.filter((gateway) => !Object.hasOwn(record, gateway)); - if (added.length === 0) return false; - for (const gateway of added) record[gateway] = []; - const path = join(projectRoot, ...BOX_GATEWAY_TARGETS_FILE.split("/")); - writeFileSync(path, boxGatewayTargetsText(record)); - return true; +export function addBoxGatewaysToRecord( + projectRoot: string, + gateways: readonly string[], +): RestoreRecord | undefined { + return changeRecord(projectRoot, (record) => { + const added = gateways.filter((gateway) => !Object.hasOwn(record ?? {}, gateway)); + if (added.length === 0) return undefined; + return { ...record, ...Object.fromEntries(added.map((gateway) => [gateway, []])) }; + }); } /** - * Removes the entry of each of `gateways` from the record, when the record names it. Returns - * whether it wrote the record; it leaves a file that is not the record to build, which refuses it. + * Removes the entry of each of `gateways` from the record, when the record names it. Returns the + * function that puts the record back, when it wrote the record; it leaves a file that is not the + * record to build, which refuses it. */ export function removeBoxGatewaysFromRecord( projectRoot: string, gateways: readonly string[], -): boolean { +): RestoreRecord | undefined { + return changeRecord(projectRoot, (record) => { + if (!record || !gateways.some((gateway) => Object.hasOwn(record, gateway))) return undefined; + return Object.fromEntries( + Object.entries(record).filter(([gateway]) => !gateways.includes(gateway)), + ); + }); +} + +/** + * Writes the record that `change` makes of the record, or of no record; `undefined` from `change` + * writes nothing. Returns the function that puts the old text back, or removes the file. + */ +function changeRecord( + projectRoot: string, + change: (record: Record | undefined) => Record | undefined, +): RestoreRecord | undefined { let record: Record | undefined; try { record = readBoxGatewayTargets(projectRoot); } catch (error) { - if (error instanceof ProjectStateError) return false; + if (error instanceof ProjectStateError) return undefined; throw error; } - const named = gateways.filter( - (gateway) => record !== undefined && Object.hasOwn(record, gateway), - ); - if (record === undefined || named.length === 0) return false; - for (const gateway of named) delete record[gateway]; + const changed = change(record); + if (changed === undefined) return undefined; const path = join(projectRoot, ...BOX_GATEWAY_TARGETS_FILE.split("/")); - writeFileSync(path, boxGatewayTargetsText(record)); - return true; + const before = record === undefined ? undefined : readFileSync(path, "utf8"); + writeFileSync(path, boxGatewayTargetsText(changed)); + return () => { + if (before === undefined) rmSync(path, { force: true }); + else writeFileSync(path, before); + }; } diff --git a/src/core/project/manager.box.test.ts b/src/core/project/manager.box.test.ts index 7b97a91c5..3dd5edb78 100644 --- a/src/core/project/manager.box.test.ts +++ b/src/core/project/manager.box.test.ts @@ -969,6 +969,93 @@ describe("gateway targets in a Box project", () => { }); }); +describe("the record of build's targets and agentcore.json, when a write fails", () => { + const RECORD = '{\n "agent-box-egress": ["egress-a"],\n "search-box-egress": ["egress-s"]\n}\n'; + const addSearch = (manager: FsProjectManager, project: Project) => + drain( + manager.addResource(project, { + resourceType: "runtime", + resourceConfig: { name: "search", language: "Python", protocol: "HTTP" }, + } as never), + ); + const flows: [ + string, + string[], + (manager: FsProjectManager, project: Project) => Promise, + ][] = [ + ["add runtime", ["agent"], addSearch], + [ + "remove runtime", + ["agent", "search"], + (manager, project) => + manager.removeResource(project, { resourceType: "runtime", name: "search" }), + ], + ["remove all", ["agent", "search"], (manager, project) => manager.removeAllResources(project)], + ]; + + test.each(flows)( + "%s keeps the record as it was when the write of agentcore.json fails", + async (_, runtimes, flow) => { + const project = await createdProject(subject(), runtimes); + const record = runtimes.length === 1 ? '{\n "agent-box-egress": ["egress-a"]\n}\n' : RECORD; + await writeFile(recordOf(project), record); + const before = await specText(project); + const specFile = join(project.rootPath, "agentcore", "agentcore.json"); + + await expect(flow(subject(refusingSpecWrites(specFile)), project)).rejects.toThrow( + `the test refuses the write of ${specFile}`, + ); + + expect(await specText(project)).toBe(before); + expect(await readFile(recordOf(project), "utf8")).toBe(record); + }, + ); + + // A read-only record makes its own write fail. Windows has no mode bits, and root writes through them. + test.skipIf(process.platform === "win32" || process.getuid?.() === 0).each(flows)( + "%s keeps agentcore.json as it was when the write of the record fails", + async (_, runtimes, flow) => { + const project = await createdProject(subject(), runtimes); + const record = runtimes.length === 1 ? '{\n "agent-box-egress": ["egress-a"]\n}\n' : RECORD; + await writeFile(recordOf(project), record); + await chmod(recordOf(project), 0o444); + const before = await specText(project); + + try { + await expect(flow(subject(), project)).rejects.toThrow(); + } finally { + await chmod(recordOf(project), 0o644); + } + + expect(await specText(project)).toBe(before); + expect(await readFile(recordOf(project), "utf8")).toBe(record); + }, + ); + + test("create writes the record before agentcore.json, so a failed record write leaves no project", async () => { + const directory = await mkdtemp(join(tmpdir(), "agentcore-box-")); + tempDirectories.push(directory); + process.chdir(directory); + await mkdir(join(directory, "example", "agentcore"), { recursive: true }); + await writeFile(join(directory, "example", "agentcore", "box-gateway-targets.json"), "{}\n"); + + await expect( + drain( + subject().create({ + name: "example", + skipInstall: true, + skipGit: true, + scaffoldRuntimeInput: resolveRuntimeTemplateShortcut("agent-python-strands-box", { + runtimeName: "agent", + }), + }), + ), + ).rejects.toThrow("File already exists"); + + expect(existsSync(join(directory, "example", "agentcore", "agentcore.json"))).toBe(false); + }); +}); + describe("a project without projectType", () => { test("add gateway-target --gateway box fails as before and adds no projectType", async () => { const manager = subject(); diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx index 894c62139..e2970a5e8 100644 --- a/src/core/project/manager.tsx +++ b/src/core/project/manager.tsx @@ -62,6 +62,7 @@ import { addBoxGatewaysToRecord, BOX_GATEWAY_TARGETS_FILE, removeBoxGatewaysFromRecord, + type RestoreRecord, } from "./boxGatewayTargets"; import { BOX_NETWORK_WRITERS, boxNetworkEdits, writeBoxNetworkFiles } from "./boxNetworkWriters"; import { createProjectTree } from "./templates/project"; @@ -1077,17 +1078,29 @@ export class FsProjectManager implements ProjectManager { yield { type: "step", message: `updating project spec file at '${agentCoreSpecPath}'` }; let newProjectSpec: z.infer; + let restoreRecord: RestoreRecord | undefined; try { const newSpecParseResult = ProjectSpecSchema.safeParse(projectSpec); if (!newSpecParseResult.success) throw new ProjectStateError(z.prettifyError(newSpecParseResult.error), { cause: newSpecParseResult.error, }); + // Build owns no target of a new Box gateway yet: an empty entry in the record says so. The + // record changes first, and goes back when agentcore.json cannot take the gateway. + if (input.resourceType === "runtime") { + restoreRecord = addBoxGatewaysToRecord( + project.rootPath, + newSpecParseResult.data.agentCoreGateways.flatMap(({ name, boundRuntime }) => + boundRuntime === input.resourceConfig.name ? [name] : [], + ), + ); + } newProjectSpec = await this.json.write(agentCoreSpecPath, newSpecParseResult.data); } catch (err) { this.logger.warn( `could not commit the spec update to ${agentCoreSpecPath}; attempting best-effort cleanup of staged changes`, ); + this.restoreRecord(restoreRecord); await Promise.all([ this.discardStaged(scaffoldedPaths), envFile?.rollback().catch((e) => { @@ -1110,15 +1123,7 @@ export class FsProjectManager implements ProjectManager { ({ boundRuntime }) => boundRuntime === added, ); yield* boxGatewayLogsWarnings(boxGateways); - // Build owns no target of the new Box gateway yet: an empty entry in the record says so. - if ( - addBoxGatewaysToRecord( - project.rootPath, - boxGateways.map(({ name }) => name), - ) - ) { - yield { type: "step", message: `writing ${BOX_GATEWAY_TARGETS_FILE}` }; - } + if (restoreRecord) yield { type: "step", message: `writing ${BOX_GATEWAY_TARGETS_FILE}` }; } return { @@ -1127,6 +1132,18 @@ export class FsProjectManager implements ProjectManager { }; } + /** Puts the record of build's targets back after a failed spec write; a failure is logged. */ + private restoreRecord(restore: RestoreRecord | undefined): void { + try { + restore?.(); + } catch (e) { + const error = AgentCoreCLIError.fromError(e); + this.logger + .child({ errorName: error.name, errorMessage: error.message }) + .warn(`failed to restore ${BOX_GATEWAY_TARGETS_FILE}`); + } + } + /** Best-effort removal of paths an add created; failures are logged, not thrown. */ private async discardStaged(paths: string[]): Promise { // A path inside another one goes with it. Removing both at the same time races: the @@ -1303,12 +1320,19 @@ export class FsProjectManager implements ProjectManager { } } - const newProjectSpec = await this.commitSpec(agentCoreSpecPath, newSpec, envFile); - // A Box gateway that goes takes its entry in the record of build's targets with it. - removeBoxGatewaysFromRecord( + // A Box gateway that goes takes its entry in the record of build's targets with it. The record + // changes first, and goes back when agentcore.json cannot lose the gateway. + const restoreRecord = removeBoxGatewaysFromRecord( project.rootPath, removedGateways.map(({ name }) => name), ); + let newProjectSpec: z.infer; + try { + newProjectSpec = await this.commitSpec(agentCoreSpecPath, newSpec, envFile); + } catch (err) { + this.restoreRecord(restoreRecord); + throw err; + } // Build and deploy generate the runtime's .box//aws/ folder, so it goes with the runtime. // Its .box//local/ profile is the user's, as its code folder is, so it stays. if (input.resourceType === "runtime") { @@ -1331,6 +1355,12 @@ export class FsProjectManager implements ProjectManager { const agentCoreSpecPath = this.getProjectSpecPath(project); const existingProjectSpec = await this.json.read(agentCoreSpecPath, ProjectSpecSchema); + // The record changes first, so a failed write of it changes nothing, and it goes back when + // agentcore.json cannot lose the gateways. + const restoreRecord = removeBoxGatewaysFromRecord( + project.rootPath, + existingProjectSpec.agentCoreGateways.map(({ name }) => name), + ); let envFile: EnvLocalFile | undefined; let removedEnvKeys: string[] = []; const envKeys = existingProjectSpec.credentials.flatMap((credential) => @@ -1364,11 +1394,13 @@ export class FsProjectManager implements ProjectManager { payments: undefined, }; - const newProjectSpec = await this.commitSpec(agentCoreSpecPath, newSpec, envFile); - removeBoxGatewaysFromRecord( - project.rootPath, - existingProjectSpec.agentCoreGateways.map(({ name }) => name), - ); + let newProjectSpec: z.infer; + try { + newProjectSpec = await this.commitSpec(agentCoreSpecPath, newSpec, envFile); + } catch (err) { + this.restoreRecord(restoreRecord); + throw err; + } return { project: { ...project, spec: newProjectSpec }, diff --git a/src/core/project/templates/project.ts b/src/core/project/templates/project.ts index 64523ff80..518928788 100644 --- a/src/core/project/templates/project.ts +++ b/src/core/project/templates/project.ts @@ -78,7 +78,7 @@ export async function createProjectTree( }), FsTreeNode.createDirectory("agentcore", [ await FsTreeNode.fromAssetSource({ assetSource: config.assetSource }, { assetDir: "cdk" }), - FsTreeNode.createFile("agentcore.json", async () => json(spec)), + // The record comes first: a failed write of either file leaves no project with one alone. ...(boxGateways.length > 0 ? [ FsTreeNode.createFile(BOX_GATEWAY_TARGETS_NAME, async () => @@ -86,6 +86,7 @@ export async function createProjectTree( ), ] : []), + FsTreeNode.createFile("agentcore.json", async () => json(spec)), FsTreeNode.createFile("aws-targets.json", async () => json([])), FsTreeNode.createFile(".env.local", () => config.assetSource.read("templates/shared/env.local.template"), From 6596b31cafbd69328ec03cb5f562195f087054a2 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 18:11:07 -0800 Subject: [PATCH 30/31] fix(box): Change the record in commitSpec, after remove all removes its keys, for the review nit on manager.tsx line 1360 --- src/core/project/manager.box.test.ts | 18 +++++++++++ src/core/project/manager.tsx | 45 +++++++++++++--------------- 2 files changed, 38 insertions(+), 25 deletions(-) diff --git a/src/core/project/manager.box.test.ts b/src/core/project/manager.box.test.ts index 3dd5edb78..d202ffc7e 100644 --- a/src/core/project/manager.box.test.ts +++ b/src/core/project/manager.box.test.ts @@ -1032,6 +1032,24 @@ describe("the record of build's targets and agentcore.json, when a write fails", }, ); + test("remove all keeps the record and agentcore.json as they were when it cannot remove a key", async () => { + const project = await createdProject(subject(), ["agent", "search"]); + const spec = JSON.parse(await specText(project)) as { credentials?: unknown[] }; + spec.credentials = [{ authorizerType: "ApiKeyCredentialProvider", name: "github" }]; + await writeFile(join(project.rootPath, "agentcore", "agentcore.json"), JSON.stringify(spec)); + await writeFile(recordOf(project), RECORD); + // A folder in the place of .env.local makes the removal of the credential's key fail. + const envLocal = join(project.rootPath, "agentcore", ".env.local"); + await rm(envLocal, { force: true }); + await mkdir(envLocal); + const before = await specText(project); + + await expect(subject().removeAllResources(project)).rejects.toThrow(); + + expect(await specText(project)).toBe(before); + expect(await readFile(recordOf(project), "utf8")).toBe(RECORD); + }); + test("create writes the record before agentcore.json, so a failed record write leaves no project", async () => { const directory = await mkdtemp(join(tmpdir(), "agentcore-box-")); tempDirectories.push(directory); diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx index e2970a5e8..a38dbe276 100644 --- a/src/core/project/manager.tsx +++ b/src/core/project/manager.tsx @@ -1320,19 +1320,13 @@ export class FsProjectManager implements ProjectManager { } } - // A Box gateway that goes takes its entry in the record of build's targets with it. The record - // changes first, and goes back when agentcore.json cannot lose the gateway. - const restoreRecord = removeBoxGatewaysFromRecord( - project.rootPath, - removedGateways.map(({ name }) => name), + // A Box gateway that goes takes its entry in the record of build's targets with it. + const newProjectSpec = await this.commitSpec(agentCoreSpecPath, newSpec, envFile, () => + removeBoxGatewaysFromRecord( + project.rootPath, + removedGateways.map(({ name }) => name), + ), ); - let newProjectSpec: z.infer; - try { - newProjectSpec = await this.commitSpec(agentCoreSpecPath, newSpec, envFile); - } catch (err) { - this.restoreRecord(restoreRecord); - throw err; - } // Build and deploy generate the runtime's .box//aws/ folder, so it goes with the runtime. // Its .box//local/ profile is the user's, as its code folder is, so it stays. if (input.resourceType === "runtime") { @@ -1355,12 +1349,6 @@ export class FsProjectManager implements ProjectManager { const agentCoreSpecPath = this.getProjectSpecPath(project); const existingProjectSpec = await this.json.read(agentCoreSpecPath, ProjectSpecSchema); - // The record changes first, so a failed write of it changes nothing, and it goes back when - // agentcore.json cannot lose the gateways. - const restoreRecord = removeBoxGatewaysFromRecord( - project.rootPath, - existingProjectSpec.agentCoreGateways.map(({ name }) => name), - ); let envFile: EnvLocalFile | undefined; let removedEnvKeys: string[] = []; const envKeys = existingProjectSpec.credentials.flatMap((credential) => @@ -1394,13 +1382,12 @@ export class FsProjectManager implements ProjectManager { payments: undefined, }; - let newProjectSpec: z.infer; - try { - newProjectSpec = await this.commitSpec(agentCoreSpecPath, newSpec, envFile); - } catch (err) { - this.restoreRecord(restoreRecord); - throw err; - } + const newProjectSpec = await this.commitSpec(agentCoreSpecPath, newSpec, envFile, () => + removeBoxGatewaysFromRecord( + project.rootPath, + existingProjectSpec.agentCoreGateways.map(({ name }) => name), + ), + ); return { project: { ...project, spec: newProjectSpec }, @@ -1410,19 +1397,27 @@ export class FsProjectManager implements ProjectManager { // Validates and writes an updated spec; a failure rolls back any .env.local // edit staged for the same removal so the two files stay consistent. + /** + * Writes `newSpec` to agentcore.json. `changeRecord` changes the record of build's targets just + * before the write. When either fails, the record and `envFile` go back to what they were. + */ private async commitSpec( agentCoreSpecPath: string, newSpec: unknown, envFile: EnvLocalFile | undefined, + changeRecord?: () => RestoreRecord | undefined, ): Promise> { + let restoreRecord: RestoreRecord | undefined; try { const newSpecParseResult = ProjectSpecSchema.safeParse(newSpec); if (!newSpecParseResult.success) throw new InputValidationError(z.prettifyError(newSpecParseResult.error), { cause: newSpecParseResult.error, }); + restoreRecord = changeRecord?.(); return await this.json.write(agentCoreSpecPath, newSpecParseResult.data); } catch (err) { + this.restoreRecord(restoreRecord); await envFile?.rollback().catch((e) => { const error = AgentCoreCLIError.fromError(e); this.logger From eb8673a88226eccc87c280909bb161b7e259de2e Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 18:12:47 -0800 Subject: [PATCH 31/31] test(box): Make the record write fail through an injected writer on every OS, for the review nit on manager.box.test.ts line 1015 --- src/core/project/boxGatewayTargets.ts | 25 ++++++++++++++++++++----- src/core/project/manager.box.test.ts | 26 +++++++++++++++++--------- src/core/project/manager.tsx | 9 +++++++++ 3 files changed, 46 insertions(+), 14 deletions(-) diff --git a/src/core/project/boxGatewayTargets.ts b/src/core/project/boxGatewayTargets.ts index 0e3e52f4b..2a1315f40 100644 --- a/src/core/project/boxGatewayTargets.ts +++ b/src/core/project/boxGatewayTargets.ts @@ -46,6 +46,18 @@ export function readBoxGatewayTargets(projectRoot: string): Record void; +/** How the record file is written and removed. */ +export interface RecordFiles { + readonly write: (path: string, text: string) => void; + readonly remove: (path: string) => void; +} + +/** The record file on disk. */ +export const FS_RECORD_FILES: RecordFiles = { + write: (path, text) => writeFileSync(path, text), + remove: (path) => rmSync(path, { force: true }), +}; + /** * Adds an empty entry for each of `gateways` that the record does not name yet. Returns the * function that puts the record back, when it wrote the record; it leaves a file that is not the @@ -54,8 +66,9 @@ export type RestoreRecord = () => void; export function addBoxGatewaysToRecord( projectRoot: string, gateways: readonly string[], + files: RecordFiles = FS_RECORD_FILES, ): RestoreRecord | undefined { - return changeRecord(projectRoot, (record) => { + return changeRecord(projectRoot, files, (record) => { const added = gateways.filter((gateway) => !Object.hasOwn(record ?? {}, gateway)); if (added.length === 0) return undefined; return { ...record, ...Object.fromEntries(added.map((gateway) => [gateway, []])) }; @@ -70,8 +83,9 @@ export function addBoxGatewaysToRecord( export function removeBoxGatewaysFromRecord( projectRoot: string, gateways: readonly string[], + files: RecordFiles = FS_RECORD_FILES, ): RestoreRecord | undefined { - return changeRecord(projectRoot, (record) => { + return changeRecord(projectRoot, files, (record) => { if (!record || !gateways.some((gateway) => Object.hasOwn(record, gateway))) return undefined; return Object.fromEntries( Object.entries(record).filter(([gateway]) => !gateways.includes(gateway)), @@ -85,6 +99,7 @@ export function removeBoxGatewaysFromRecord( */ function changeRecord( projectRoot: string, + files: RecordFiles, change: (record: Record | undefined) => Record | undefined, ): RestoreRecord | undefined { let record: Record | undefined; @@ -98,9 +113,9 @@ function changeRecord( if (changed === undefined) return undefined; const path = join(projectRoot, ...BOX_GATEWAY_TARGETS_FILE.split("/")); const before = record === undefined ? undefined : readFileSync(path, "utf8"); - writeFileSync(path, boxGatewayTargetsText(changed)); + files.write(path, boxGatewayTargetsText(changed)); return () => { - if (before === undefined) rmSync(path, { force: true }); - else writeFileSync(path, before); + if (before === undefined) files.remove(path); + else files.write(path, before); }; } diff --git a/src/core/project/manager.box.test.ts b/src/core/project/manager.box.test.ts index d202ffc7e..8517ca07f 100644 --- a/src/core/project/manager.box.test.ts +++ b/src/core/project/manager.box.test.ts @@ -9,6 +9,7 @@ import type { AddResourceInput, Project } from "../../handlers/project/types"; import { resolveRuntimeTemplateShortcut } from "../../handlers/project/shortcuts"; import { createSilentLogger, TestIdentityClient } from "../../testing"; import { BOX_RELEASE } from "./backends/boxRelease"; +import type { RecordFiles } from "./boxGatewayTargets"; import { boxGatewayLogsNotice, FsProjectManager } from "./manager"; import { newProjectSpec } from "./templates/project"; import { defaultLogTargetNotice } from "./runtimeProfile/rules/additions"; @@ -33,7 +34,7 @@ afterEach(async () => { ); }); -function subject(json?: ReadWriteJson): FsProjectManager { +function subject(json?: ReadWriteJson, recordFiles?: RecordFiles): FsProjectManager { return new FsProjectManager({ logger: createSilentLogger(), identity: new TestIdentityClient(), @@ -41,9 +42,20 @@ function subject(json?: ReadWriteJson): FsProjectManager { runner: async () => {}, checkTool: async () => {}, ...(json && { json }), + ...(recordFiles && { recordFiles }), }); } +/** A writer of the record of build's targets that refuses each write and each removal. */ +const refusingRecordWrites: RecordFiles = { + write: (path) => { + throw new Error(`the test refuses the write of ${path}`); + }, + remove: (path) => { + throw new Error(`the test refuses the removal of ${path}`); + }, +}; + /** A JSON reader and writer that refuses each write of `specFile`, for each user, root too. */ function refusingSpecWrites(specFile: string): ReadWriteJson { const files = new FsReadWriteJson({ logger: createSilentLogger() }); @@ -1011,21 +1023,17 @@ describe("the record of build's targets and agentcore.json, when a write fails", }, ); - // A read-only record makes its own write fail. Windows has no mode bits, and root writes through them. - test.skipIf(process.platform === "win32" || process.getuid?.() === 0).each(flows)( + test.each(flows)( "%s keeps agentcore.json as it was when the write of the record fails", async (_, runtimes, flow) => { const project = await createdProject(subject(), runtimes); const record = runtimes.length === 1 ? '{\n "agent-box-egress": ["egress-a"]\n}\n' : RECORD; await writeFile(recordOf(project), record); - await chmod(recordOf(project), 0o444); const before = await specText(project); - try { - await expect(flow(subject(), project)).rejects.toThrow(); - } finally { - await chmod(recordOf(project), 0o644); - } + await expect(flow(subject(undefined, refusingRecordWrites), project)).rejects.toThrow( + `the test refuses the write of ${recordOf(project)}`, + ); expect(await specText(project)).toBe(before); expect(await readFile(recordOf(project), "utf8")).toBe(record); diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx index a38dbe276..008fd3e7b 100644 --- a/src/core/project/manager.tsx +++ b/src/core/project/manager.tsx @@ -61,7 +61,9 @@ import { BoxCliProfileResolver, type BoxProfileResolver } from "./boxProfileReso import { addBoxGatewaysToRecord, BOX_GATEWAY_TARGETS_FILE, + FS_RECORD_FILES, removeBoxGatewaysFromRecord, + type RecordFiles, type RestoreRecord, } from "./boxGatewayTargets"; import { BOX_NETWORK_WRITERS, boxNetworkEdits, writeBoxNetworkFiles } from "./boxNetworkWriters"; @@ -434,6 +436,8 @@ type ProjectManagerConfig = { runner?: ProcessRunner; checkTool?: typeof requireTool; json?: ReadWriteJson; + /** How the record of build's targets is written; the file on disk by default. */ + recordFiles?: RecordFiles; /** * The environment the CDK backend reads HOME (the box cache) from, and build reads box `env://` * egress secrets from; process.env by default. @@ -464,6 +468,7 @@ export class FsProjectManager implements ProjectManager { private readonly runner: ProcessRunner; private readonly checkTool: typeof requireTool; private readonly json: ReadWriteJson; + private readonly recordFiles: RecordFiles; private readonly backends: Partial>; private readonly resolveAccount: (region: string) => Promise; private readonly processEnv: NodeJS.ProcessEnv; @@ -475,6 +480,7 @@ export class FsProjectManager implements ProjectManager { this.runner = config.runner ?? runProcess; this.checkTool = config.checkTool ?? requireTool; this.json = config.json ?? new FsReadWriteJson({ logger: config.logger }); + this.recordFiles = config.recordFiles ?? FS_RECORD_FILES; this.backends = config.backends ?? { CDK: new CdkBackend({ logger: config.logger, @@ -1093,6 +1099,7 @@ export class FsProjectManager implements ProjectManager { newSpecParseResult.data.agentCoreGateways.flatMap(({ name, boundRuntime }) => boundRuntime === input.resourceConfig.name ? [name] : [], ), + this.recordFiles, ); } newProjectSpec = await this.json.write(agentCoreSpecPath, newSpecParseResult.data); @@ -1325,6 +1332,7 @@ export class FsProjectManager implements ProjectManager { removeBoxGatewaysFromRecord( project.rootPath, removedGateways.map(({ name }) => name), + this.recordFiles, ), ); // Build and deploy generate the runtime's .box//aws/ folder, so it goes with the runtime. @@ -1386,6 +1394,7 @@ export class FsProjectManager implements ProjectManager { removeBoxGatewaysFromRecord( project.rootPath, existingProjectSpec.agentCoreGateways.map(({ name }) => name), + this.recordFiles, ), );