@warlock.js/ai 4.14.0 → 4.16.0

package/esm/orchestrator/memory.d.mts

@@ -2,7 +2,7 @@ import { SupervisorInput } from "../contracts/supervisor/supervisor-input.type.m
 import { TurnSnapshot } from "../contracts/result/orchestrator-result.type.mjs";
 import { RecalledMemory } from "../contracts/memory/memory-item.type.mjs";
 import { MemoryContract } from "../contracts/memory/memory.contract.mjs";
-import { OrchestratorMemoryConfig } from "../contracts/orchestrator/orchestrator-config.type.mjs";
+import { OrchestratorMemoryConfig, OrchestratorMemoryScope } from "../contracts/orchestrator/orchestrator-config.type.mjs";
 
 //#region ../ai/src/orchestrator/memory.d.ts
 /**
@@ -18,7 +18,13 @@ type ResolvedOrchestratorMemory = {
   threshold?: number; /** Single-tier recall restriction. */
   tier?: ResolvedTier; /** Whether a clean turn writes its outcome back. Default `true`. */
   remember: boolean; /** Tier the remembered outcome lands in. Omit for the memory's `defaultTier`. */
-  rememberTier?: ResolvedTier; /** Context-bag key the recalled memories are injected under. */
+  rememberTier?: ResolvedTier;
+  /**
+   * Isolation boundary for recall + write-back. Default `"session"` —
+   * the turn's `sessionId` keys every read and write, so one session
+   * cannot recall another's memories out of the shared store.
+   */
+  scope: OrchestratorMemoryScope; /** Context-bag key the recalled memories are injected under. */
   injectKey: string;
 };
 type ResolvedTier = NonNullable<OrchestratorMemoryConfig["recall"]>["tier"];
@@ -29,6 +35,28 @@ type ResolvedTier = NonNullable<OrchestratorMemoryConfig["recall"]>["tier"];
  * shape and the lifecycle phase stays branch-free.
  */
 declare function resolveOrchestratorMemory(memory: MemoryContract | OrchestratorMemoryConfig | undefined): ResolvedOrchestratorMemory | undefined;
+/**
+ * Resolve the isolation key a turn reads and writes memories under
+ * (4.15.0 — security fix for cross-session recall).
+ *
+ * The memory store is resolved once per orchestrator instance and reused
+ * by every session, so this — not the store — is what keeps one session's
+ * remembered turns out of another's recall. It is derived from the
+ * execute-time `sessionId` by the engine and handed to every tier as an
+ * exact-match filter; the model, the tool payload, and the per-call
+ * `context` bag have no say in it.
+ *
+ * `"shared"` resolves to `undefined`, i.e. the store's unscoped pool —
+ * the explicit opt-in back to pre-4.15.0 cross-session behavior, which
+ * also keeps memories written before this release readable.
+ */
+declare function memoryScopeFor(memory: ResolvedOrchestratorMemory, sessionId: string): string | undefined;
+/**
+ * The default `"session"` scope key: the session id under a reserved
+ * prefix, so a custom `scope` callback returning a bare tenant id can
+ * never accidentally collide with a session-scoped pool.
+ */
+declare function sessionMemoryScope(sessionId: string): string;
 /**
  * Coerce a turn's {@link SupervisorInput} (string or structured object)
  * into the natural-language query the memory store recalls / embeds
@@ -44,8 +72,12 @@ declare function memoryQueryFromInput(input: SupervisorInput): string;
  * `memory.injectKey`. Returns an empty array — never throws on "no hits"
  * — and short-circuits when `k === 0` (recall disabled / write-only
  * memory) so a write-only config never round-trips the embedder.
+ *
+ * The recall is confined to the calling session's scope (see
+ * {@link memoryScopeFor}) — `sessionId` is required, not optional, so a
+ * new call site cannot silently recall across every session.
  */
-declare function recallForTurn(memory: ResolvedOrchestratorMemory, input: SupervisorInput): Promise<RecalledMemory[]>;
+declare function recallForTurn(memory: ResolvedOrchestratorMemory, input: SupervisorInput, sessionId: string): Promise<RecalledMemory[]>;
 /**
  * Merge the recalled memories into a fresh per-turn context bag under
  * `memory.injectKey` (memory core M2 — the injection half). Never
@@ -68,8 +100,12 @@ declare function injectMemories(context: Record<string, unknown> | undefined, me
  * The remembered text is the turn input followed by the model's textual
  * outcome when one is available, so a later `recall` keyed on a similar
  * input surfaces both the prior question and its answer.
+ *
+ * The write is tagged with the calling session's scope (see
+ * {@link memoryScopeFor}) so only that session recalls it later —
+ * turn text routinely contains one user's private content.
  */
-declare function rememberTurnOutcome(memory: ResolvedOrchestratorMemory, input: SupervisorInput, outcomeText: string | undefined): Promise<void>;
+declare function rememberTurnOutcome(memory: ResolvedOrchestratorMemory, input: SupervisorInput, outcomeText: string | undefined, sessionId: string): Promise<void>;
 /**
  * Derive a turn's textual outcome for remembering (memory core M2).
  * Prefers the validated `result.data` (an `output` schema reshaped it);
@@ -80,5 +116,5 @@ declare function rememberTurnOutcome(memory: ResolvedOrchestratorMemory, input:
  */
 declare function outcomeTextFromTurn(data: unknown, turnSnapshot: TurnSnapshot): string | undefined;
 //#endregion
-export { ResolvedOrchestratorMemory, injectMemories, memoryQueryFromInput, outcomeTextFromTurn, recallForTurn, rememberTurnOutcome, resolveOrchestratorMemory };
+export { ResolvedOrchestratorMemory, injectMemories, memoryQueryFromInput, memoryScopeFor, outcomeTextFromTurn, recallForTurn, rememberTurnOutcome, resolveOrchestratorMemory, sessionMemoryScope };
 //# sourceMappingURL=memory.d.mts.map

package/esm/orchestrator/memory.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"memory.d.mts","names":[],"sources":["../../../../../../../ai/src/orchestrator/memory.ts"],"mappings":";;;;;;;;;AAmBA;;;;;KAAY,0BAAA;EAYiB,yEAV3B,KAAA,EAAO,cAAA,EAAP;EAEA,CAAA;EAEA,SAAA,WAEA;EAAA,IAAA,GAAO,YAAA,EAEP;EAAA,QAAA,WAEe;EAAf,YAAA,GAAe,YAAA,EAEN;EAAT,SAAA;AAAA;AAAA,KAGG,YAAA,GAAe,WAAW,CAAC,wBAAA;;;AAAwB;AAoBxD;;;iBAAgB,yBAAA,CACd,MAAA,EAAQ,cAAA,GAAiB,wBAAA,eACxB,0BAAA;;;;;;;;iBA+Ba,oBAAA,CAAqB,KAAsB,EAAf,eAAe;;AA/B9B;AA+B7B;;;;AAA2D;AAY3D;iBAAsB,aAAA,CACpB,MAAA,EAAQ,0BAAA,EACR,KAAA,EAAO,eAAA,GACN,OAAA,CAAQ,cAAA;;;;;;;;;;;;;iBAwBK,cAAA,CACd,OAAA,EAAS,MAAA,+BACT,MAAA,EAAQ,0BAAA,EACR,QAAA,EAAU,cAAA,KACT,MAAA;;AA5BsB;AAwBzB;;;;;;;;iBAsBsB,mBAAA,CACpB,MAAA,EAAQ,0BAAA,EACR,KAAA,EAAO,eAAA,EACP,WAAA,uBACC,OAAA;;;;;;;;;iBA4Ca,mBAAA,CACd,IAAA,WACA,YAAA,EAAc,YAAY"}
+{"version":3,"file":"memory.d.mts","names":[],"sources":["../../../../../../../ai/src/orchestrator/memory.ts"],"mappings":";;;;;;;;;AA+BA;;;;;KAAY,0BAAA;EAkBH,yEAhBP,KAAA,EAAO,cAAA,EAgBuB;EAd9B,CAAA,WAFO;EAIP,SAAA;EAEA,IAAA,GAAO,YAAA,EAAA;EAEP,QAAA,WAEA;EAAA,YAAA,GAAe,YAAA;EAMf;;;;AAES;EAFT,KAAA,EAAO,uBAAA,EAKQ;EAHf,SAAA;AAAA;AAAA,KAGG,YAAA,GAAe,WAAW,CAAC,wBAAA;AAoBhC;;;;;;AAAA,iBAAgB,yBAAA,CACd,MAAA,EAAQ,cAAA,GAAiB,wBAAA,eACxB,0BAAA;;;;;;;AAA0B;AAyC7B;;;;;;;;iBAAgB,cAAA,CACd,MAAA,EAAQ,0BAA0B,EAClC,SAAA;AAkBF;;;;AAAoD;AAApD,iBAAgB,kBAAA,CAAmB,SAAiB;;;;AAWO;AAgB3D;;;iBAhBgB,oBAAA,CAAqB,KAAsB,EAAf,eAAe;;;;;;;;;;;;;iBAgBrC,aAAA,CACpB,MAAA,EAAQ,0BAAA,EACR,KAAA,EAAO,eAAA,EACP,SAAA,WACC,OAAA,CAAQ,cAAA;AAAc;AAyBzB;;;;;;;;;;;AAzByB,iBAyBT,cAAA,CACd,OAAA,EAAS,MAAA,+BACT,MAAA,EAAQ,0BAAA,EACR,QAAA,EAAU,cAAA,KACT,MAAA;;;;;;AAAM;AAsBT;;;;;;;;iBAAsB,mBAAA,CACpB,MAAA,EAAQ,0BAAA,EACR,KAAA,EAAO,eAAA,EACP,WAAA,sBACA,SAAA,WACC,OAAA;;;;;;;;AAAO;iBAgDM,mBAAA,CACd,IAAA,WACA,YAAA,EAAc,YAAY"}

package/esm/orchestrator/memory.mjs

@@ -2,6 +2,14 @@
 /** Default key the recalled memories are injected under in the context bag. */
 const DEFAULT_INJECT_KEY = "memories";
 /**
+* Default isolation boundary: a turn recalls only what its own session
+* remembered. Cross-session pooling is opt-in (`scope: "shared"`) — the
+* default must not leak one user's remembered turns into another's
+* context, since one memory store backs every session of an
+* orchestrator instance.
+*/
+const DEFAULT_SCOPE = "session";
+/**
 * A `MemoryContract` is the bare-store form; anything carrying a `store`
 * is the {@link OrchestratorMemoryConfig} wrapper. Distinguished by the
 * presence of `recall` — a method on the contract, absent on the config
@@ -21,6 +29,7 @@ function resolveOrchestratorMemory(memory) {
 	if (isBareMemory(memory)) return {
 		store: memory,
 		remember: true,
+		scope: DEFAULT_SCOPE,
 		injectKey: DEFAULT_INJECT_KEY
 	};
 	return {
@@ -30,10 +39,39 @@ function resolveOrchestratorMemory(memory) {
 		tier: memory.recall?.tier,
 		remember: memory.remember ?? true,
 		rememberTier: memory.rememberTier,
+		scope: memory.scope ?? DEFAULT_SCOPE,
 		injectKey: memory.injectKey ?? DEFAULT_INJECT_KEY
 	};
 }
 /**
+* Resolve the isolation key a turn reads and writes memories under
+* (4.15.0 — security fix for cross-session recall).
+*
+* The memory store is resolved once per orchestrator instance and reused
+* by every session, so this — not the store — is what keeps one session's
+* remembered turns out of another's recall. It is derived from the
+* execute-time `sessionId` by the engine and handed to every tier as an
+* exact-match filter; the model, the tool payload, and the per-call
+* `context` bag have no say in it.
+*
+* `"shared"` resolves to `undefined`, i.e. the store's unscoped pool —
+* the explicit opt-in back to pre-4.15.0 cross-session behavior, which
+* also keeps memories written before this release readable.
+*/
+function memoryScopeFor(memory, sessionId) {
+	if (memory.scope === "shared") return;
+	if (typeof memory.scope === "function") return memory.scope(sessionId);
+	return sessionMemoryScope(sessionId);
+}
+/**
+* The default `"session"` scope key: the session id under a reserved
+* prefix, so a custom `scope` callback returning a bare tenant id can
+* never accidentally collide with a session-scoped pool.
+*/
+function sessionMemoryScope(sessionId) {
+	return `session:${sessionId}`;
+}
+/**
 * Coerce a turn's {@link SupervisorInput} (string or structured object)
 * into the natural-language query the memory store recalls / embeds
 * against. Strings pass through; objects are JSON-serialized — the same
@@ -50,13 +88,18 @@ function memoryQueryFromInput(input) {
 * `memory.injectKey`. Returns an empty array — never throws on "no hits"
 * — and short-circuits when `k === 0` (recall disabled / write-only
 * memory) so a write-only config never round-trips the embedder.
+*
+* The recall is confined to the calling session's scope (see
+* {@link memoryScopeFor}) — `sessionId` is required, not optional, so a
+* new call site cannot silently recall across every session.
 */
-async function recallForTurn(memory, input) {
+async function recallForTurn(memory, input, sessionId) {
 	if (memory.k === 0) return [];
 	return memory.store.recall(memoryQueryFromInput(input), {
 		k: memory.k,
 		threshold: memory.threshold,
-		tier: memory.tier
+		tier: memory.tier,
+		scope: memoryScopeFor(memory, sessionId)
 	});
 }
 /**
@@ -87,14 +130,19 @@ function injectMemories(context, memory, recalled) {
 * The remembered text is the turn input followed by the model's textual
 * outcome when one is available, so a later `recall` keyed on a similar
 * input surfaces both the prior question and its answer.
+*
+* The write is tagged with the calling session's scope (see
+* {@link memoryScopeFor}) so only that session recalls it later —
+* turn text routinely contains one user's private content.
 */
-async function rememberTurnOutcome(memory, input, outcomeText) {
+async function rememberTurnOutcome(memory, input, outcomeText, sessionId) {
 	if (!memory.remember) return;
 	const text = buildOutcomeText(input, outcomeText);
 	if (!text) return;
 	const item = {
 		text,
-		tier: memory.rememberTier
+		tier: memory.rememberTier,
+		scope: memoryScopeFor(memory, sessionId)
 	};
 	await memory.store.remember(item);
 }
@@ -137,5 +185,5 @@ function stringifyOutcome(value) {
 }
 
 //#endregion
-export { injectMemories, memoryQueryFromInput, outcomeTextFromTurn, recallForTurn, rememberTurnOutcome, resolveOrchestratorMemory };
+export { injectMemories, memoryQueryFromInput, memoryScopeFor, outcomeTextFromTurn, recallForTurn, rememberTurnOutcome, resolveOrchestratorMemory, sessionMemoryScope };
 //# sourceMappingURL=memory.mjs.map

package/esm/orchestrator/memory.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"memory.mjs","names":[],"sources":["../../../../../../../ai/src/orchestrator/memory.ts"],"sourcesContent":["import type { MemoryContract } from \"../contracts/memory/memory.contract\";\nimport type {\n  MemoryItem,\n  RecalledMemory,\n} from \"../contracts/memory/memory-item.type\";\nimport type { OrchestratorMemoryConfig } from \"../contracts/orchestrator/orchestrator-config.type\";\nimport type { TurnSnapshot } from \"../contracts/result/orchestrator-result.type\";\nimport type { SupervisorInput } from \"../contracts/supervisor/supervisor-input.type\";\n\n/** Default key the recalled memories are injected under in the context bag. */\nconst DEFAULT_INJECT_KEY = \"memories\";\n\n/**\n * Memory wiring resolved once per turn from `OrchestratorConfig.memory`\n * (memory core M2). Normalizes the two accepted config shapes — a bare\n * {@link MemoryContract} or the richer {@link OrchestratorMemoryConfig} —\n * into a single flat record the lifecycle phase reads, so `runTurn` never\n * branches on which form the dev supplied.\n */\nexport type ResolvedOrchestratorMemory = {\n  /** The store recalled-from before dispatch and remembered-into after. */\n  store: MemoryContract;\n  /** Recall count cap; `0` disables recall (write-only memory). */\n  k?: number;\n  /** Semantic-similarity floor for recall. */\n  threshold?: number;\n  /** Single-tier recall restriction. */\n  tier?: ResolvedTier;\n  /** Whether a clean turn writes its outcome back. Default `true`. */\n  remember: boolean;\n  /** Tier the remembered outcome lands in. Omit for the memory's `defaultTier`. */\n  rememberTier?: ResolvedTier;\n  /** Context-bag key the recalled memories are injected under. */\n  injectKey: string;\n};\n\ntype ResolvedTier = NonNullable<OrchestratorMemoryConfig[\"recall\"]>[\"tier\"];\n\n/**\n * A `MemoryContract` is the bare-store form; anything carrying a `store`\n * is the {@link OrchestratorMemoryConfig} wrapper. Distinguished by the\n * presence of `recall` — a method on the contract, absent on the config\n * (whose own `recall` is a plain options object, never a function).\n */\nfunction isBareMemory(\n  value: MemoryContract | OrchestratorMemoryConfig,\n): value is MemoryContract {\n  return typeof (value as MemoryContract).recall === \"function\";\n}\n\n/**\n * Normalize `OrchestratorConfig.memory` into {@link ResolvedOrchestratorMemory},\n * or `undefined` when no memory is configured. Centralizes the\n * bare-store-vs-config distinction so the engine context carries one\n * shape and the lifecycle phase stays branch-free.\n */\nexport function resolveOrchestratorMemory(\n  memory: MemoryContract | OrchestratorMemoryConfig | undefined,\n): ResolvedOrchestratorMemory | undefined {\n  if (!memory) {\n    return undefined;\n  }\n\n  if (isBareMemory(memory)) {\n    return {\n      store: memory,\n      remember: true,\n      injectKey: DEFAULT_INJECT_KEY,\n    };\n  }\n\n  return {\n    store: memory.store,\n    k: memory.recall?.k,\n    threshold: memory.recall?.threshold,\n    tier: memory.recall?.tier,\n    remember: memory.remember ?? true,\n    rememberTier: memory.rememberTier,\n    injectKey: memory.injectKey ?? DEFAULT_INJECT_KEY,\n  };\n}\n\n/**\n * Coerce a turn's {@link SupervisorInput} (string or structured object)\n * into the natural-language query the memory store recalls / embeds\n * against. Strings pass through; objects are JSON-serialized — the same\n * coercion the supervisor applies when forwarding an object input to a\n * child agent without an explicit `input(ctx)` override.\n */\nexport function memoryQueryFromInput(input: SupervisorInput): string {\n  return typeof input === \"string\" ? input : JSON.stringify(input);\n}\n\n/**\n * Recall the memories relevant to a turn's input (memory core M2 — the\n * pre-dispatch half). Returns the scored {@link RecalledMemory}[] the\n * lifecycle injects into the turn's `context` bag under\n * `memory.injectKey`. Returns an empty array — never throws on \"no hits\"\n * — and short-circuits when `k === 0` (recall disabled / write-only\n * memory) so a write-only config never round-trips the embedder.\n */\nexport async function recallForTurn(\n  memory: ResolvedOrchestratorMemory,\n  input: SupervisorInput,\n): Promise<RecalledMemory[]> {\n  if (memory.k === 0) {\n    return [];\n  }\n\n  return memory.store.recall(memoryQueryFromInput(input), {\n    k: memory.k,\n    threshold: memory.threshold,\n    tier: memory.tier,\n  });\n}\n\n/**\n * Merge the recalled memories into a fresh per-turn context bag under\n * `memory.injectKey` (memory core M2 — the injection half). Never\n * mutates the caller's `context` object — returns a new bag (or the\n * original when there is nothing to inject) so the request-scoped input\n * stays immutable, and the supervisor's intake (which freezes a\n * shallow copy) sees the recalled set on every `ctx.context[injectKey]`.\n *\n * A pre-existing value at `injectKey` is preserved when recall produced\n * nothing, and overwritten with the recalled set otherwise — the\n * orchestrator owns that key once memory is configured.\n */\nexport function injectMemories(\n  context: Record<string, unknown> | undefined,\n  memory: ResolvedOrchestratorMemory,\n  recalled: RecalledMemory[],\n): Record<string, unknown> | undefined {\n  if (recalled.length === 0) {\n    return context;\n  }\n\n  return { ...(context ?? {}), [memory.injectKey]: recalled };\n}\n\n/**\n * Remember a settled turn's outcome (memory core M2 — the post-dispatch\n * half). Called only after a clean turn (cancelled / failed turns revert\n * and never remember — §17). No-ops when `remember` is `false`\n * (read-only memory) or when the produced text is empty.\n *\n * The remembered text is the turn input followed by the model's textual\n * outcome when one is available, so a later `recall` keyed on a similar\n * input surfaces both the prior question and its answer.\n */\nexport async function rememberTurnOutcome(\n  memory: ResolvedOrchestratorMemory,\n  input: SupervisorInput,\n  outcomeText: string | undefined,\n): Promise<void> {\n  if (!memory.remember) {\n    return;\n  }\n\n  const text = buildOutcomeText(input, outcomeText);\n\n  if (!text) {\n    return;\n  }\n\n  const item: MemoryItem = { text, tier: memory.rememberTier };\n\n  await memory.store.remember(item);\n}\n\n/**\n * Compose the text written to memory for a turn: the input query, plus\n * the outcome text on a following line when the dispatch produced one.\n * Returns `undefined` when neither side carries content so an empty turn\n * never pollutes the store.\n */\nfunction buildOutcomeText(\n  input: SupervisorInput,\n  outcomeText: string | undefined,\n): string | undefined {\n  const query = memoryQueryFromInput(input).trim();\n  const outcome = outcomeText?.trim();\n\n  if (query && outcome) {\n    return `${query}\\n${outcome}`;\n  }\n\n  return query || outcome || undefined;\n}\n\n/**\n * Derive a turn's textual outcome for remembering (memory core M2).\n * Prefers the validated `result.data` (an `output` schema reshaped it);\n * otherwise stringifies the dispatched intents' branch outputs from the\n * turn snapshot, joined newline-wise so a multi-branch fan-out\n * contributes every output. Returns `undefined` when the turn produced\n * no usable text — the caller then remembers the input alone.\n */\nexport function outcomeTextFromTurn(\n  data: unknown,\n  turnSnapshot: TurnSnapshot,\n): string | undefined {\n  const fromData = stringifyOutcome(data);\n\n  if (fromData) {\n    return fromData;\n  }\n\n  const outputs = Object.values(turnSnapshot.result)\n    .map((branch) => stringifyOutcome(branch.output))\n    .filter((text): text is string => Boolean(text));\n\n  return outputs.length > 0 ? outputs.join(\"\\n\") : undefined;\n}\n\n/**\n * Coerce one outcome value to text: strings pass through; everything\n * else (objects, numbers) is JSON-serialized. `undefined` / `null` and\n * empty strings collapse to `undefined` so they don't masquerade as\n * content.\n */\nfunction stringifyOutcome(value: unknown): string | undefined {\n  if (value === undefined || value === null) {\n    return undefined;\n  }\n\n  const text = typeof value === \"string\" ? value : JSON.stringify(value);\n\n  return text.trim() ? text : undefined;\n}\n"],"mappings":";;AAUA,MAAM,qBAAqB;;;;;;;AAkC3B,SAAS,aACP,OACyB;CACzB,OAAO,OAAQ,MAAyB,WAAW;AACrD;;;;;;;AAQA,SAAgB,0BACd,QACwC;CACxC,IAAI,CAAC,QACH;CAGF,IAAI,aAAa,MAAM,GACrB,OAAO;EACL,OAAO;EACP,UAAU;EACV,WAAW;CACb;CAGF,OAAO;EACL,OAAO,OAAO;EACd,GAAG,OAAO,QAAQ;EAClB,WAAW,OAAO,QAAQ;EAC1B,MAAM,OAAO,QAAQ;EACrB,UAAU,OAAO,YAAY;EAC7B,cAAc,OAAO;EACrB,WAAW,OAAO,aAAa;CACjC;AACF;;;;;;;;AASA,SAAgB,qBAAqB,OAAgC;CACnE,OAAO,OAAO,UAAU,WAAW,QAAQ,KAAK,UAAU,KAAK;AACjE;;;;;;;;;AAUA,eAAsB,cACpB,QACA,OAC2B;CAC3B,IAAI,OAAO,MAAM,GACf,OAAO,CAAC;CAGV,OAAO,OAAO,MAAM,OAAO,qBAAqB,KAAK,GAAG;EACtD,GAAG,OAAO;EACV,WAAW,OAAO;EAClB,MAAM,OAAO;CACf,CAAC;AACH;;;;;;;;;;;;;AAcA,SAAgB,eACd,SACA,QACA,UACqC;CACrC,IAAI,SAAS,WAAW,GACtB,OAAO;CAGT,OAAO;EAAE,GAAI,WAAW,CAAC;GAAK,OAAO,YAAY;CAAS;AAC5D;;;;;;;;;;;AAYA,eAAsB,oBACpB,QACA,OACA,aACe;CACf,IAAI,CAAC,OAAO,UACV;CAGF,MAAM,OAAO,iBAAiB,OAAO,WAAW;CAEhD,IAAI,CAAC,MACH;CAGF,MAAM,OAAmB;EAAE;EAAM,MAAM,OAAO;CAAa;CAE3D,MAAM,OAAO,MAAM,SAAS,IAAI;AAClC;;;;;;;AAQA,SAAS,iBACP,OACA,aACoB;CACpB,MAAM,QAAQ,qBAAqB,KAAK,CAAC,CAAC,KAAK;CAC/C,MAAM,UAAU,aAAa,KAAK;CAElC,IAAI,SAAS,SACX,OAAO,GAAG,MAAM,IAAI;CAGtB,OAAO,SAAS,WAAW;AAC7B;;;;;;;;;AAUA,SAAgB,oBACd,MACA,cACoB;CACpB,MAAM,WAAW,iBAAiB,IAAI;CAEtC,IAAI,UACF,OAAO;CAGT,MAAM,UAAU,OAAO,OAAO,aAAa,MAAM,CAAC,CAC/C,KAAK,WAAW,iBAAiB,OAAO,MAAM,CAAC,CAAC,CAChD,QAAQ,SAAyB,QAAQ,IAAI,CAAC;CAEjD,OAAO,QAAQ,SAAS,IAAI,QAAQ,KAAK,IAAI,IAAI;AACnD;;;;;;;AAQA,SAAS,iBAAiB,OAAoC;CAC5D,IAAI,UAAU,UAAa,UAAU,MACnC;CAGF,MAAM,OAAO,OAAO,UAAU,WAAW,QAAQ,KAAK,UAAU,KAAK;CAErE,OAAO,KAAK,KAAK,IAAI,OAAO;AAC9B"}
+{"version":3,"file":"memory.mjs","names":[],"sources":["../../../../../../../ai/src/orchestrator/memory.ts"],"sourcesContent":["import type { MemoryContract } from \"../contracts/memory/memory.contract\";\nimport type {\n  MemoryItem,\n  RecalledMemory,\n} from \"../contracts/memory/memory-item.type\";\nimport type {\n  OrchestratorMemoryConfig,\n  OrchestratorMemoryScope,\n} from \"../contracts/orchestrator/orchestrator-config.type\";\nimport type { TurnSnapshot } from \"../contracts/result/orchestrator-result.type\";\nimport type { SupervisorInput } from \"../contracts/supervisor/supervisor-input.type\";\n\n/** Default key the recalled memories are injected under in the context bag. */\nconst DEFAULT_INJECT_KEY = \"memories\";\n\n/**\n * Default isolation boundary: a turn recalls only what its own session\n * remembered. Cross-session pooling is opt-in (`scope: \"shared\"`) — the\n * default must not leak one user's remembered turns into another's\n * context, since one memory store backs every session of an\n * orchestrator instance.\n */\nconst DEFAULT_SCOPE = \"session\" as const;\n\n/**\n * Memory wiring resolved once per turn from `OrchestratorConfig.memory`\n * (memory core M2). Normalizes the two accepted config shapes — a bare\n * {@link MemoryContract} or the richer {@link OrchestratorMemoryConfig} —\n * into a single flat record the lifecycle phase reads, so `runTurn` never\n * branches on which form the dev supplied.\n */\nexport type ResolvedOrchestratorMemory = {\n  /** The store recalled-from before dispatch and remembered-into after. */\n  store: MemoryContract;\n  /** Recall count cap; `0` disables recall (write-only memory). */\n  k?: number;\n  /** Semantic-similarity floor for recall. */\n  threshold?: number;\n  /** Single-tier recall restriction. */\n  tier?: ResolvedTier;\n  /** Whether a clean turn writes its outcome back. Default `true`. */\n  remember: boolean;\n  /** Tier the remembered outcome lands in. Omit for the memory's `defaultTier`. */\n  rememberTier?: ResolvedTier;\n  /**\n   * Isolation boundary for recall + write-back. Default `\"session\"` —\n   * the turn's `sessionId` keys every read and write, so one session\n   * cannot recall another's memories out of the shared store.\n   */\n  scope: OrchestratorMemoryScope;\n  /** Context-bag key the recalled memories are injected under. */\n  injectKey: string;\n};\n\ntype ResolvedTier = NonNullable<OrchestratorMemoryConfig[\"recall\"]>[\"tier\"];\n\n/**\n * A `MemoryContract` is the bare-store form; anything carrying a `store`\n * is the {@link OrchestratorMemoryConfig} wrapper. Distinguished by the\n * presence of `recall` — a method on the contract, absent on the config\n * (whose own `recall` is a plain options object, never a function).\n */\nfunction isBareMemory(\n  value: MemoryContract | OrchestratorMemoryConfig,\n): value is MemoryContract {\n  return typeof (value as MemoryContract).recall === \"function\";\n}\n\n/**\n * Normalize `OrchestratorConfig.memory` into {@link ResolvedOrchestratorMemory},\n * or `undefined` when no memory is configured. Centralizes the\n * bare-store-vs-config distinction so the engine context carries one\n * shape and the lifecycle phase stays branch-free.\n */\nexport function resolveOrchestratorMemory(\n  memory: MemoryContract | OrchestratorMemoryConfig | undefined,\n): ResolvedOrchestratorMemory | undefined {\n  if (!memory) {\n    return undefined;\n  }\n\n  if (isBareMemory(memory)) {\n    return {\n      store: memory,\n      remember: true,\n      scope: DEFAULT_SCOPE,\n      injectKey: DEFAULT_INJECT_KEY,\n    };\n  }\n\n  return {\n    store: memory.store,\n    k: memory.recall?.k,\n    threshold: memory.recall?.threshold,\n    tier: memory.recall?.tier,\n    remember: memory.remember ?? true,\n    rememberTier: memory.rememberTier,\n    scope: memory.scope ?? DEFAULT_SCOPE,\n    injectKey: memory.injectKey ?? DEFAULT_INJECT_KEY,\n  };\n}\n\n/**\n * Resolve the isolation key a turn reads and writes memories under\n * (4.15.0 — security fix for cross-session recall).\n *\n * The memory store is resolved once per orchestrator instance and reused\n * by every session, so this — not the store — is what keeps one session's\n * remembered turns out of another's recall. It is derived from the\n * execute-time `sessionId` by the engine and handed to every tier as an\n * exact-match filter; the model, the tool payload, and the per-call\n * `context` bag have no say in it.\n *\n * `\"shared\"` resolves to `undefined`, i.e. the store's unscoped pool —\n * the explicit opt-in back to pre-4.15.0 cross-session behavior, which\n * also keeps memories written before this release readable.\n */\nexport function memoryScopeFor(\n  memory: ResolvedOrchestratorMemory,\n  sessionId: string,\n): string | undefined {\n  if (memory.scope === \"shared\") {\n    return undefined;\n  }\n\n  if (typeof memory.scope === \"function\") {\n    return memory.scope(sessionId);\n  }\n\n  return sessionMemoryScope(sessionId);\n}\n\n/**\n * The default `\"session\"` scope key: the session id under a reserved\n * prefix, so a custom `scope` callback returning a bare tenant id can\n * never accidentally collide with a session-scoped pool.\n */\nexport function sessionMemoryScope(sessionId: string): string {\n  return `session:${sessionId}`;\n}\n\n/**\n * Coerce a turn's {@link SupervisorInput} (string or structured object)\n * into the natural-language query the memory store recalls / embeds\n * against. Strings pass through; objects are JSON-serialized — the same\n * coercion the supervisor applies when forwarding an object input to a\n * child agent without an explicit `input(ctx)` override.\n */\nexport function memoryQueryFromInput(input: SupervisorInput): string {\n  return typeof input === \"string\" ? input : JSON.stringify(input);\n}\n\n/**\n * Recall the memories relevant to a turn's input (memory core M2 — the\n * pre-dispatch half). Returns the scored {@link RecalledMemory}[] the\n * lifecycle injects into the turn's `context` bag under\n * `memory.injectKey`. Returns an empty array — never throws on \"no hits\"\n * — and short-circuits when `k === 0` (recall disabled / write-only\n * memory) so a write-only config never round-trips the embedder.\n *\n * The recall is confined to the calling session's scope (see\n * {@link memoryScopeFor}) — `sessionId` is required, not optional, so a\n * new call site cannot silently recall across every session.\n */\nexport async function recallForTurn(\n  memory: ResolvedOrchestratorMemory,\n  input: SupervisorInput,\n  sessionId: string,\n): Promise<RecalledMemory[]> {\n  if (memory.k === 0) {\n    return [];\n  }\n\n  return memory.store.recall(memoryQueryFromInput(input), {\n    k: memory.k,\n    threshold: memory.threshold,\n    tier: memory.tier,\n    scope: memoryScopeFor(memory, sessionId),\n  });\n}\n\n/**\n * Merge the recalled memories into a fresh per-turn context bag under\n * `memory.injectKey` (memory core M2 — the injection half). Never\n * mutates the caller's `context` object — returns a new bag (or the\n * original when there is nothing to inject) so the request-scoped input\n * stays immutable, and the supervisor's intake (which freezes a\n * shallow copy) sees the recalled set on every `ctx.context[injectKey]`.\n *\n * A pre-existing value at `injectKey` is preserved when recall produced\n * nothing, and overwritten with the recalled set otherwise — the\n * orchestrator owns that key once memory is configured.\n */\nexport function injectMemories(\n  context: Record<string, unknown> | undefined,\n  memory: ResolvedOrchestratorMemory,\n  recalled: RecalledMemory[],\n): Record<string, unknown> | undefined {\n  if (recalled.length === 0) {\n    return context;\n  }\n\n  return { ...(context ?? {}), [memory.injectKey]: recalled };\n}\n\n/**\n * Remember a settled turn's outcome (memory core M2 — the post-dispatch\n * half). Called only after a clean turn (cancelled / failed turns revert\n * and never remember — §17). No-ops when `remember` is `false`\n * (read-only memory) or when the produced text is empty.\n *\n * The remembered text is the turn input followed by the model's textual\n * outcome when one is available, so a later `recall` keyed on a similar\n * input surfaces both the prior question and its answer.\n *\n * The write is tagged with the calling session's scope (see\n * {@link memoryScopeFor}) so only that session recalls it later —\n * turn text routinely contains one user's private content.\n */\nexport async function rememberTurnOutcome(\n  memory: ResolvedOrchestratorMemory,\n  input: SupervisorInput,\n  outcomeText: string | undefined,\n  sessionId: string,\n): Promise<void> {\n  if (!memory.remember) {\n    return;\n  }\n\n  const text = buildOutcomeText(input, outcomeText);\n\n  if (!text) {\n    return;\n  }\n\n  const item: MemoryItem = {\n    text,\n    tier: memory.rememberTier,\n    scope: memoryScopeFor(memory, sessionId),\n  };\n\n  await memory.store.remember(item);\n}\n\n/**\n * Compose the text written to memory for a turn: the input query, plus\n * the outcome text on a following line when the dispatch produced one.\n * Returns `undefined` when neither side carries content so an empty turn\n * never pollutes the store.\n */\nfunction buildOutcomeText(\n  input: SupervisorInput,\n  outcomeText: string | undefined,\n): string | undefined {\n  const query = memoryQueryFromInput(input).trim();\n  const outcome = outcomeText?.trim();\n\n  if (query && outcome) {\n    return `${query}\\n${outcome}`;\n  }\n\n  return query || outcome || undefined;\n}\n\n/**\n * Derive a turn's textual outcome for remembering (memory core M2).\n * Prefers the validated `result.data` (an `output` schema reshaped it);\n * otherwise stringifies the dispatched intents' branch outputs from the\n * turn snapshot, joined newline-wise so a multi-branch fan-out\n * contributes every output. Returns `undefined` when the turn produced\n * no usable text — the caller then remembers the input alone.\n */\nexport function outcomeTextFromTurn(\n  data: unknown,\n  turnSnapshot: TurnSnapshot,\n): string | undefined {\n  const fromData = stringifyOutcome(data);\n\n  if (fromData) {\n    return fromData;\n  }\n\n  const outputs = Object.values(turnSnapshot.result)\n    .map((branch) => stringifyOutcome(branch.output))\n    .filter((text): text is string => Boolean(text));\n\n  return outputs.length > 0 ? outputs.join(\"\\n\") : undefined;\n}\n\n/**\n * Coerce one outcome value to text: strings pass through; everything\n * else (objects, numbers) is JSON-serialized. `undefined` / `null` and\n * empty strings collapse to `undefined` so they don't masquerade as\n * content.\n */\nfunction stringifyOutcome(value: unknown): string | undefined {\n  if (value === undefined || value === null) {\n    return undefined;\n  }\n\n  const text = typeof value === \"string\" ? value : JSON.stringify(value);\n\n  return text.trim() ? text : undefined;\n}\n"],"mappings":";;AAaA,MAAM,qBAAqB;;;;;;;;AAS3B,MAAM,gBAAgB;;;;;;;AAwCtB,SAAS,aACP,OACyB;CACzB,OAAO,OAAQ,MAAyB,WAAW;AACrD;;;;;;;AAQA,SAAgB,0BACd,QACwC;CACxC,IAAI,CAAC,QACH;CAGF,IAAI,aAAa,MAAM,GACrB,OAAO;EACL,OAAO;EACP,UAAU;EACV,OAAO;EACP,WAAW;CACb;CAGF,OAAO;EACL,OAAO,OAAO;EACd,GAAG,OAAO,QAAQ;EAClB,WAAW,OAAO,QAAQ;EAC1B,MAAM,OAAO,QAAQ;EACrB,UAAU,OAAO,YAAY;EAC7B,cAAc,OAAO;EACrB,OAAO,OAAO,SAAS;EACvB,WAAW,OAAO,aAAa;CACjC;AACF;;;;;;;;;;;;;;;;AAiBA,SAAgB,eACd,QACA,WACoB;CACpB,IAAI,OAAO,UAAU,UACnB;CAGF,IAAI,OAAO,OAAO,UAAU,YAC1B,OAAO,OAAO,MAAM,SAAS;CAG/B,OAAO,mBAAmB,SAAS;AACrC;;;;;;AAOA,SAAgB,mBAAmB,WAA2B;CAC5D,OAAO,WAAW;AACpB;;;;;;;;AASA,SAAgB,qBAAqB,OAAgC;CACnE,OAAO,OAAO,UAAU,WAAW,QAAQ,KAAK,UAAU,KAAK;AACjE;;;;;;;;;;;;;AAcA,eAAsB,cACpB,QACA,OACA,WAC2B;CAC3B,IAAI,OAAO,MAAM,GACf,OAAO,CAAC;CAGV,OAAO,OAAO,MAAM,OAAO,qBAAqB,KAAK,GAAG;EACtD,GAAG,OAAO;EACV,WAAW,OAAO;EAClB,MAAM,OAAO;EACb,OAAO,eAAe,QAAQ,SAAS;CACzC,CAAC;AACH;;;;;;;;;;;;;AAcA,SAAgB,eACd,SACA,QACA,UACqC;CACrC,IAAI,SAAS,WAAW,GACtB,OAAO;CAGT,OAAO;EAAE,GAAI,WAAW,CAAC;GAAK,OAAO,YAAY;CAAS;AAC5D;;;;;;;;;;;;;;;AAgBA,eAAsB,oBACpB,QACA,OACA,aACA,WACe;CACf,IAAI,CAAC,OAAO,UACV;CAGF,MAAM,OAAO,iBAAiB,OAAO,WAAW;CAEhD,IAAI,CAAC,MACH;CAGF,MAAM,OAAmB;EACvB;EACA,MAAM,OAAO;EACb,OAAO,eAAe,QAAQ,SAAS;CACzC;CAEA,MAAM,OAAO,MAAM,SAAS,IAAI;AAClC;;;;;;;AAQA,SAAS,iBACP,OACA,aACoB;CACpB,MAAM,QAAQ,qBAAqB,KAAK,CAAC,CAAC,KAAK;CAC/C,MAAM,UAAU,aAAa,KAAK;CAElC,IAAI,SAAS,SACX,OAAO,GAAG,MAAM,IAAI;CAGtB,OAAO,SAAS,WAAW;AAC7B;;;;;;;;;AAUA,SAAgB,oBACd,MACA,cACoB;CACpB,MAAM,WAAW,iBAAiB,IAAI;CAEtC,IAAI,UACF,OAAO;CAGT,MAAM,UAAU,OAAO,OAAO,aAAa,MAAM,CAAC,CAC/C,KAAK,WAAW,iBAAiB,OAAO,MAAM,CAAC,CAAC,CAChD,QAAQ,SAAyB,QAAQ,IAAI,CAAC;CAEjD,OAAO,QAAQ,SAAS,IAAI,QAAQ,KAAK,IAAI,IAAI;AACnD;;;;;;;AAQA,SAAS,iBAAiB,OAAoC;CAC5D,IAAI,UAAU,UAAa,UAAU,MACnC;CAGF,MAAM,OAAO,OAAO,UAAU,WAAW,QAAQ,KAAK,UAAU,KAAK;CAErE,OAAO,KAAK,KAAK,IAAI,OAAO;AAC9B"}

package/esm/planner/plan-schema.d.mts

@@ -17,11 +17,22 @@ import { StandardSchemaV1 } from "@standard-schema/spec";
  * `PlannerPlanInvalidError`, with the full forensic context, rather
  * than as an opaque schema issue here.
  *
- * `maxSteps`, when provided, is emitted as the `steps` array's
- * `maxItems` so capable providers refuse to over-produce up front
- * (the planner still truncates the tail to `skipped` defensively).
+ * `maxSteps` cannot be expressed on the wire (strict mode rejects
+ * `maxItems`), so `validate()` enforces a hard parse-time ceiling
+ * derived from it — see {@link parsedStepCeiling}.
  */
-declare function planSchema(capabilityNames: string[], maxSteps?: number): StandardSchemaV1<PlannerPlan>;
+type PlanSchema = StandardSchemaV1<PlannerPlan> & {
+  "~standard": {
+    /**
+     * JSON Schema extension read by the native structured-output path.
+     * Part of the declared type so callers don't have to re-assert it.
+     */
+    jsonSchema: {
+      input: () => Record<string, unknown>;
+    };
+  };
+};
+declare function planSchema(capabilityNames: string[], maxSteps?: number): PlanSchema;
 //#endregion
 export { planSchema };
 //# sourceMappingURL=plan-schema.d.mts.map

package/esm/planner/plan-schema.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"plan-schema.d.mts","names":[],"sources":["../../../../../../../ai/src/planner/plan-schema.ts"],"mappings":";;;;;;AAsBA;;;;;;;;;AAG+B;;;;;;;;iBAHf,UAAA,CACd,eAAA,YACA,QAAA,YACC,gBAAgB,CAAC,WAAA"}
+{"version":3,"file":"plan-schema.d.mts","names":[],"sources":["../../../../../../../ai/src/planner/plan-schema.ts"],"mappings":";;;;;;AAsBA;;;;;;;;;;;;;;;AAMqC;AAsCrC;KA5CY,UAAA,GAAa,gBAAA,CAAiB,WAAA;EACxC,WAAA;IA2CkF;;;;IAtChF,UAAA;MAAc,KAAA,QAAa,MAAA;IAAA;EAAA;AAAA;AAAA,iBAsCf,UAAA,CAAW,eAAA,YAA2B,QAAA,YAAoB,UAAU"}

package/esm/planner/plan-schema.mjs

@@ -1,24 +1,34 @@
 //#region ../ai/src/planner/plan-schema.ts
 /**
-* Build the Standard Schema the planning agent emits — an ordered
-* `{ steps: [...], summary? }` plan whose every step references one of
-* `capabilityNames` via the `capability` field.
-*
-* Mirrors the router's hand-built schema approach
-* (`supervisor/router-factory.ts`): the JSON Schema extension carries
-* the capability names as an `enum` so capable providers enforce the
-* choice natively, while `validate()` still accepts the shape softly so
-* providers without native structured output can pass a parsed object
-* through. Validation is intentionally lenient on `capability` — an
-* unknown name is surfaced later by the planner as a typed
-* `PlannerPlanInvalidError`, with the full forensic context, rather
-* than as an opaque schema issue here.
+* Slack allowed over `maxSteps` before a returned plan is rejected
+* outright. A model that overshoots the prompt's "at most N steps" by a
+* little is normal and the runtime truncates the tail to `skipped`;
+* one that returns several times the budget is malfunctioning (or the
+* provider/proxy is not the one we think it is), and parsing it is
+* unbounded work on attacker-adjacent input.
+*/
+const STEP_CEILING_FACTOR = 4;
+/**
+* Ceiling used when `planSchema` is built without a `maxSteps` — direct
+* callers outside `PlannerRun`, which has no runtime truncation of its
+* own to fall back on.
+*/
+const DEFAULT_STEP_CEILING = 100;
+/**
+* Hard upper bound on the number of steps `validate()` will parse.
 *
-* `maxSteps`, when provided, is emitted as the `steps` array's
-* `maxItems` so capable providers refuse to over-produce up front
-* (the planner still truncates the tail to `skipped` defensively).
+* Strict-mode JSON Schema can't carry `maxItems`, so nothing on the wire
+* stops a provider from returning an arbitrarily long `steps[]`; before
+* 4.15.0 the whole array was parsed, normalized and stored, and only the
+* execution loop truncated it. This is the parse-time backstop that
+* makes the bound hold regardless of what the provider honors.
 */
+function parsedStepCeiling(maxSteps) {
+	if (maxSteps === void 0) return DEFAULT_STEP_CEILING;
+	return Math.max(1, Math.ceil(maxSteps)) * STEP_CEILING_FACTOR;
+}
 function planSchema(capabilityNames, maxSteps) {
+	const stepCeiling = parsedStepCeiling(maxSteps);
 	const jsonSchema = {
 		type: "object",
 		properties: {
@@ -43,6 +53,7 @@ function planSchema(capabilityNames, maxSteps) {
 			if (!value || typeof value !== "object") return { issues: [{ message: "plan must be an object" }] };
 			const record = value;
 			if (!Array.isArray(record.steps) || record.steps.length === 0) return { issues: [{ message: "plan `steps` must be a non-empty array" }] };
+			if (record.steps.length > stepCeiling) return { issues: [{ message: `plan \`steps\` must not exceed ${stepCeiling} entries (received ${record.steps.length})` }] };
 			const steps = [];
 			for (const raw of record.steps) {
 				const normalized = normalizeStep(raw);

package/esm/planner/plan-schema.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"plan-schema.mjs","names":[],"sources":["../../../../../../../ai/src/planner/plan-schema.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { PlannerPlan, PlannerStep } from \"../contracts/planner/planner-plan.type\";\n\n/**\n * Build the Standard Schema the planning agent emits — an ordered\n * `{ steps: [...], summary? }` plan whose every step references one of\n * `capabilityNames` via the `capability` field.\n *\n * Mirrors the router's hand-built schema approach\n * (`supervisor/router-factory.ts`): the JSON Schema extension carries\n * the capability names as an `enum` so capable providers enforce the\n * choice natively, while `validate()` still accepts the shape softly so\n * providers without native structured output can pass a parsed object\n * through. Validation is intentionally lenient on `capability` — an\n * unknown name is surfaced later by the planner as a typed\n * `PlannerPlanInvalidError`, with the full forensic context, rather\n * than as an opaque schema issue here.\n *\n * `maxSteps`, when provided, is emitted as the `steps` array's\n * `maxItems` so capable providers refuse to over-produce up front\n * (the planner still truncates the tail to `skipped` defensively).\n */\nexport function planSchema(\n  capabilityNames: string[],\n  maxSteps?: number,\n): StandardSchemaV1<PlannerPlan> {\n  // OpenAI strict `json_schema` mode (and other native structured-output\n  // providers) require EVERY property to appear in `required` — with truly\n  // optional fields expressed as nullable — and reject array `minItems` /\n  // `maxItems`. So the schema is strict-shaped: all keys required, the\n  // optional ones nullable, no item-count bounds. A non-empty plan is\n  // enforced in `validate()`, and `maxSteps` by the runtime's tail\n  // truncation, so neither bound is needed on the wire.\n  void maxSteps;\n\n  const jsonSchema = {\n    type: \"object\",\n    properties: {\n      summary: {\n        type: [\"string\", \"null\"],\n        description: \"One-line summary of the overall strategy.\",\n      },\n      steps: {\n        type: \"array\",\n        description: \"Ordered steps to execute, one capability dispatch each.\",\n        items: stepItemsSchema(capabilityNames),\n      },\n    },\n    required: [\"summary\", \"steps\"],\n    additionalProperties: false,\n  };\n\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: \"warlock-planner\",\n      jsonSchema: {\n        input: () => jsonSchema,\n      },\n      validate(value: unknown): StandardSchemaV1.Result<PlannerPlan> {\n        if (!value || typeof value !== \"object\") {\n          return { issues: [{ message: \"plan must be an object\" }] };\n        }\n\n        const record = value as { steps?: unknown; summary?: unknown };\n\n        if (!Array.isArray(record.steps) || record.steps.length === 0) {\n          return { issues: [{ message: \"plan `steps` must be a non-empty array\" }] };\n        }\n\n        const steps: PlannerStep[] = [];\n\n        for (const raw of record.steps) {\n          const normalized = normalizeStep(raw);\n\n          if (!normalized) {\n            return {\n              issues: [{ message: \"each plan step must carry a string `capability` and `input`\" }],\n            };\n          }\n\n          steps.push(normalized);\n        }\n\n        const summary = typeof record.summary === \"string\" ? record.summary : undefined;\n\n        return { value: summary !== undefined ? { steps, summary } : { steps } };\n      },\n    } as StandardSchemaV1<PlannerPlan>[\"~standard\"] & {\n      jsonSchema: { input: () => Record<string, unknown> };\n    },\n  };\n}\n\n/** Per-step JSON Schema object — one capability dispatch. */\nfunction stepItemsSchema(capabilityNames: string[]): Record<string, unknown> {\n  return {\n    type: \"object\",\n    properties: {\n      id: {\n        type: [\"string\", \"null\"],\n        description: \"Stable step id, referenced by dependsOn.\",\n      },\n      capability: {\n        type: \"string\",\n        enum: capabilityNames,\n        description: \"Name of the capability to dispatch for this step.\",\n      },\n      input: {\n        type: \"string\",\n        description: \"Concrete input passed to the capability's execute().\",\n      },\n      reason: { type: [\"string\", \"null\"], description: \"Why this step exists.\" },\n      dependsOn: {\n        type: [\"array\", \"null\"],\n        items: { type: \"string\" },\n        description: \"Ids of steps this one conceptually follows.\",\n      },\n    },\n    // Strict mode: every property required; the genuinely-optional ones\n    // (id / reason / dependsOn) are nullable. `validate()` treats null and\n    // missing identically, so a model emitting `null` round-trips fine.\n    required: [\"id\", \"capability\", \"input\", \"reason\", \"dependsOn\"],\n    additionalProperties: false,\n  };\n}\n\n/**\n * Coerce one raw step object into a {@link PlannerStep}, returning\n * `undefined` when the mandatory `capability` / `input` strings are\n * missing. Optional fields are copied only when well-typed.\n */\nfunction normalizeStep(raw: unknown): PlannerStep | undefined {\n  if (!raw || typeof raw !== \"object\") {\n    return undefined;\n  }\n\n  const record = raw as {\n    id?: unknown;\n    capability?: unknown;\n    input?: unknown;\n    reason?: unknown;\n    dependsOn?: unknown;\n  };\n\n  if (typeof record.capability !== \"string\" || record.capability.length === 0) {\n    return undefined;\n  }\n\n  if (typeof record.input !== \"string\") {\n    return undefined;\n  }\n\n  const step: PlannerStep = {\n    capability: record.capability,\n    input: record.input,\n  };\n\n  if (typeof record.id === \"string\") {\n    step.id = record.id;\n  }\n\n  if (typeof record.reason === \"string\") {\n    step.reason = record.reason;\n  }\n\n  if (Array.isArray(record.dependsOn) && record.dependsOn.every((entry) => typeof entry === \"string\")) {\n    step.dependsOn = record.dependsOn as string[];\n  }\n\n  return step;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,WACd,iBACA,UAC+B;CAU/B,MAAM,aAAa;EACjB,MAAM;EACN,YAAY;GACV,SAAS;IACP,MAAM,CAAC,UAAU,MAAM;IACvB,aAAa;GACf;GACA,OAAO;IACL,MAAM;IACN,aAAa;IACb,OAAO,gBAAgB,eAAe;GACxC;EACF;EACA,UAAU,CAAC,WAAW,OAAO;EAC7B,sBAAsB;CACxB;CAEA,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,YAAY,EACV,aAAa,WACf;EACA,SAAS,OAAsD;GAC7D,IAAI,CAAC,SAAS,OAAO,UAAU,UAC7B,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,yBAAyB,CAAC,EAAE;GAG3D,MAAM,SAAS;GAEf,IAAI,CAAC,MAAM,QAAQ,OAAO,KAAK,KAAK,OAAO,MAAM,WAAW,GAC1D,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,yCAAyC,CAAC,EAAE;GAG3E,MAAM,QAAuB,CAAC;GAE9B,KAAK,MAAM,OAAO,OAAO,OAAO;IAC9B,MAAM,aAAa,cAAc,GAAG;IAEpC,IAAI,CAAC,YACH,OAAO,EACL,QAAQ,CAAC,EAAE,SAAS,8DAA8D,CAAC,EACrF;IAGF,MAAM,KAAK,UAAU;GACvB;GAEA,MAAM,UAAU,OAAO,OAAO,YAAY,WAAW,OAAO,UAAU;GAEtE,OAAO,EAAE,OAAO,YAAY,SAAY;IAAE;IAAO;GAAQ,IAAI,EAAE,MAAM,EAAE;EACzE;CACF,EAGF;AACF;;AAGA,SAAS,gBAAgB,iBAAoD;CAC3E,OAAO;EACL,MAAM;EACN,YAAY;GACV,IAAI;IACF,MAAM,CAAC,UAAU,MAAM;IACvB,aAAa;GACf;GACA,YAAY;IACV,MAAM;IACN,MAAM;IACN,aAAa;GACf;GACA,OAAO;IACL,MAAM;IACN,aAAa;GACf;GACA,QAAQ;IAAE,MAAM,CAAC,UAAU,MAAM;IAAG,aAAa;GAAwB;GACzE,WAAW;IACT,MAAM,CAAC,SAAS,MAAM;IACtB,OAAO,EAAE,MAAM,SAAS;IACxB,aAAa;GACf;EACF;EAIA,UAAU;GAAC;GAAM;GAAc;GAAS;GAAU;EAAW;EAC7D,sBAAsB;CACxB;AACF;;;;;;AAOA,SAAS,cAAc,KAAuC;CAC5D,IAAI,CAAC,OAAO,OAAO,QAAQ,UACzB;CAGF,MAAM,SAAS;CAQf,IAAI,OAAO,OAAO,eAAe,YAAY,OAAO,WAAW,WAAW,GACxE;CAGF,IAAI,OAAO,OAAO,UAAU,UAC1B;CAGF,MAAM,OAAoB;EACxB,YAAY,OAAO;EACnB,OAAO,OAAO;CAChB;CAEA,IAAI,OAAO,OAAO,OAAO,UACvB,KAAK,KAAK,OAAO;CAGnB,IAAI,OAAO,OAAO,WAAW,UAC3B,KAAK,SAAS,OAAO;CAGvB,IAAI,MAAM,QAAQ,OAAO,SAAS,KAAK,OAAO,UAAU,OAAO,UAAU,OAAO,UAAU,QAAQ,GAChG,KAAK,YAAY,OAAO;CAG1B,OAAO;AACT"}
+{"version":3,"file":"plan-schema.mjs","names":[],"sources":["../../../../../../../ai/src/planner/plan-schema.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { PlannerPlan, PlannerStep } from \"../contracts/planner/planner-plan.type\";\n\n/**\n * Build the Standard Schema the planning agent emits — an ordered\n * `{ steps: [...], summary? }` plan whose every step references one of\n * `capabilityNames` via the `capability` field.\n *\n * Mirrors the router's hand-built schema approach\n * (`supervisor/router-factory.ts`): the JSON Schema extension carries\n * the capability names as an `enum` so capable providers enforce the\n * choice natively, while `validate()` still accepts the shape softly so\n * providers without native structured output can pass a parsed object\n * through. Validation is intentionally lenient on `capability` — an\n * unknown name is surfaced later by the planner as a typed\n * `PlannerPlanInvalidError`, with the full forensic context, rather\n * than as an opaque schema issue here.\n *\n * `maxSteps` cannot be expressed on the wire (strict mode rejects\n * `maxItems`), so `validate()` enforces a hard parse-time ceiling\n * derived from it — see {@link parsedStepCeiling}.\n */\nexport type PlanSchema = StandardSchemaV1<PlannerPlan> & {\n  \"~standard\": {\n    /**\n     * JSON Schema extension read by the native structured-output path.\n     * Part of the declared type so callers don't have to re-assert it.\n     */\n    jsonSchema: { input: () => Record<string, unknown> };\n  };\n};\n\n/**\n * Slack allowed over `maxSteps` before a returned plan is rejected\n * outright. A model that overshoots the prompt's \"at most N steps\" by a\n * little is normal and the runtime truncates the tail to `skipped`;\n * one that returns several times the budget is malfunctioning (or the\n * provider/proxy is not the one we think it is), and parsing it is\n * unbounded work on attacker-adjacent input.\n */\nconst STEP_CEILING_FACTOR = 4;\n\n/**\n * Ceiling used when `planSchema` is built without a `maxSteps` — direct\n * callers outside `PlannerRun`, which has no runtime truncation of its\n * own to fall back on.\n */\nconst DEFAULT_STEP_CEILING = 100;\n\n/**\n * Hard upper bound on the number of steps `validate()` will parse.\n *\n * Strict-mode JSON Schema can't carry `maxItems`, so nothing on the wire\n * stops a provider from returning an arbitrarily long `steps[]`; before\n * 4.15.0 the whole array was parsed, normalized and stored, and only the\n * execution loop truncated it. This is the parse-time backstop that\n * makes the bound hold regardless of what the provider honors.\n */\nexport function parsedStepCeiling(maxSteps?: number): number {\n  if (maxSteps === undefined) {\n    return DEFAULT_STEP_CEILING;\n  }\n\n  return Math.max(1, Math.ceil(maxSteps)) * STEP_CEILING_FACTOR;\n}\n\nexport function planSchema(capabilityNames: string[], maxSteps?: number): PlanSchema {\n  // OpenAI strict `json_schema` mode (and other native structured-output\n  // providers) require EVERY property to appear in `required` — with truly\n  // optional fields expressed as nullable — and reject array `minItems` /\n  // `maxItems`. So the schema is strict-shaped: all keys required, the\n  // optional ones nullable, no item-count bounds on the wire. Both bounds\n  // live in `validate()` instead: non-empty below, and the over-long\n  // ceiling that `maxItems` would have expressed.\n  const stepCeiling = parsedStepCeiling(maxSteps);\n\n  const jsonSchema = {\n    type: \"object\",\n    properties: {\n      summary: {\n        type: [\"string\", \"null\"],\n        description: \"One-line summary of the overall strategy.\",\n      },\n      steps: {\n        type: \"array\",\n        description: \"Ordered steps to execute, one capability dispatch each.\",\n        items: stepItemsSchema(capabilityNames),\n      },\n    },\n    required: [\"summary\", \"steps\"],\n    additionalProperties: false,\n  };\n\n  return {\n    \"~standard\": {\n      version: 1,\n      vendor: \"warlock-planner\",\n      jsonSchema: {\n        input: () => jsonSchema,\n      },\n      validate(value: unknown): StandardSchemaV1.Result<PlannerPlan> {\n        if (!value || typeof value !== \"object\") {\n          return { issues: [{ message: \"plan must be an object\" }] };\n        }\n\n        const record = value as { steps?: unknown; summary?: unknown };\n\n        if (!Array.isArray(record.steps) || record.steps.length === 0) {\n          return { issues: [{ message: \"plan `steps` must be a non-empty array\" }] };\n        }\n\n        // Reject an over-long plan HERE, before a single step is\n        // normalized — the runtime's tail truncation runs after the whole\n        // array has been parsed and stored, so it bounds execution but\n        // not the parsing cost of a pathological response. Rejecting\n        // rather than truncating is deliberate: a plan several times its\n        // budget is a malfunction worth surfacing as\n        // `PlannerPlanInvalidError`, not something to silently trim into\n        // a plausible-looking prefix.\n        if (record.steps.length > stepCeiling) {\n          return {\n            issues: [\n              {\n                message: `plan \\`steps\\` must not exceed ${stepCeiling} entries (received ${record.steps.length})`,\n              },\n            ],\n          };\n        }\n\n        const steps: PlannerStep[] = [];\n\n        for (const raw of record.steps) {\n          const normalized = normalizeStep(raw);\n\n          if (!normalized) {\n            return {\n              issues: [{ message: \"each plan step must carry a string `capability` and `input`\" }],\n            };\n          }\n\n          steps.push(normalized);\n        }\n\n        const summary = typeof record.summary === \"string\" ? record.summary : undefined;\n\n        return { value: summary !== undefined ? { steps, summary } : { steps } };\n      },\n    } as StandardSchemaV1<PlannerPlan>[\"~standard\"] & {\n      jsonSchema: { input: () => Record<string, unknown> };\n    },\n  };\n}\n\n/** Per-step JSON Schema object — one capability dispatch. */\nfunction stepItemsSchema(capabilityNames: string[]): Record<string, unknown> {\n  return {\n    type: \"object\",\n    properties: {\n      id: {\n        type: [\"string\", \"null\"],\n        description: \"Stable step id, referenced by dependsOn.\",\n      },\n      capability: {\n        type: \"string\",\n        enum: capabilityNames,\n        description: \"Name of the capability to dispatch for this step.\",\n      },\n      input: {\n        type: \"string\",\n        description: \"Concrete input passed to the capability's execute().\",\n      },\n      reason: { type: [\"string\", \"null\"], description: \"Why this step exists.\" },\n      dependsOn: {\n        type: [\"array\", \"null\"],\n        items: { type: \"string\" },\n        description: \"Ids of steps this one conceptually follows.\",\n      },\n    },\n    // Strict mode: every property required; the genuinely-optional ones\n    // (id / reason / dependsOn) are nullable. `validate()` treats null and\n    // missing identically, so a model emitting `null` round-trips fine.\n    required: [\"id\", \"capability\", \"input\", \"reason\", \"dependsOn\"],\n    additionalProperties: false,\n  };\n}\n\n/**\n * Coerce one raw step object into a {@link PlannerStep}, returning\n * `undefined` when the mandatory `capability` / `input` strings are\n * missing. Optional fields are copied only when well-typed.\n */\nfunction normalizeStep(raw: unknown): PlannerStep | undefined {\n  if (!raw || typeof raw !== \"object\") {\n    return undefined;\n  }\n\n  const record = raw as {\n    id?: unknown;\n    capability?: unknown;\n    input?: unknown;\n    reason?: unknown;\n    dependsOn?: unknown;\n  };\n\n  if (typeof record.capability !== \"string\" || record.capability.length === 0) {\n    return undefined;\n  }\n\n  if (typeof record.input !== \"string\") {\n    return undefined;\n  }\n\n  const step: PlannerStep = {\n    capability: record.capability,\n    input: record.input,\n  };\n\n  if (typeof record.id === \"string\") {\n    step.id = record.id;\n  }\n\n  if (typeof record.reason === \"string\") {\n    step.reason = record.reason;\n  }\n\n  if (Array.isArray(record.dependsOn) && record.dependsOn.every((entry) => typeof entry === \"string\")) {\n    step.dependsOn = record.dependsOn as string[];\n  }\n\n  return step;\n}\n"],"mappings":";;;;;;;;;AAwCA,MAAM,sBAAsB;;;;;;AAO5B,MAAM,uBAAuB;;;;;;;;;;AAW7B,SAAgB,kBAAkB,UAA2B;CAC3D,IAAI,aAAa,QACf,OAAO;CAGT,OAAO,KAAK,IAAI,GAAG,KAAK,KAAK,QAAQ,CAAC,IAAI;AAC5C;AAEA,SAAgB,WAAW,iBAA2B,UAA+B;CAQnF,MAAM,cAAc,kBAAkB,QAAQ;CAE9C,MAAM,aAAa;EACjB,MAAM;EACN,YAAY;GACV,SAAS;IACP,MAAM,CAAC,UAAU,MAAM;IACvB,aAAa;GACf;GACA,OAAO;IACL,MAAM;IACN,aAAa;IACb,OAAO,gBAAgB,eAAe;GACxC;EACF;EACA,UAAU,CAAC,WAAW,OAAO;EAC7B,sBAAsB;CACxB;CAEA,OAAO,EACL,aAAa;EACX,SAAS;EACT,QAAQ;EACR,YAAY,EACV,aAAa,WACf;EACA,SAAS,OAAsD;GAC7D,IAAI,CAAC,SAAS,OAAO,UAAU,UAC7B,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,yBAAyB,CAAC,EAAE;GAG3D,MAAM,SAAS;GAEf,IAAI,CAAC,MAAM,QAAQ,OAAO,KAAK,KAAK,OAAO,MAAM,WAAW,GAC1D,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,yCAAyC,CAAC,EAAE;GAW3E,IAAI,OAAO,MAAM,SAAS,aACxB,OAAO,EACL,QAAQ,CACN,EACE,SAAS,kCAAkC,YAAY,qBAAqB,OAAO,MAAM,OAAO,GAClG,CACF,EACF;GAGF,MAAM,QAAuB,CAAC;GAE9B,KAAK,MAAM,OAAO,OAAO,OAAO;IAC9B,MAAM,aAAa,cAAc,GAAG;IAEpC,IAAI,CAAC,YACH,OAAO,EACL,QAAQ,CAAC,EAAE,SAAS,8DAA8D,CAAC,EACrF;IAGF,MAAM,KAAK,UAAU;GACvB;GAEA,MAAM,UAAU,OAAO,OAAO,YAAY,WAAW,OAAO,UAAU;GAEtE,OAAO,EAAE,OAAO,YAAY,SAAY;IAAE;IAAO;GAAQ,IAAI,EAAE,MAAM,EAAE;EACzE;CACF,EAGF;AACF;;AAGA,SAAS,gBAAgB,iBAAoD;CAC3E,OAAO;EACL,MAAM;EACN,YAAY;GACV,IAAI;IACF,MAAM,CAAC,UAAU,MAAM;IACvB,aAAa;GACf;GACA,YAAY;IACV,MAAM;IACN,MAAM;IACN,aAAa;GACf;GACA,OAAO;IACL,MAAM;IACN,aAAa;GACf;GACA,QAAQ;IAAE,MAAM,CAAC,UAAU,MAAM;IAAG,aAAa;GAAwB;GACzE,WAAW;IACT,MAAM,CAAC,SAAS,MAAM;IACtB,OAAO,EAAE,MAAM,SAAS;IACxB,aAAa;GACf;EACF;EAIA,UAAU;GAAC;GAAM;GAAc;GAAS;GAAU;EAAW;EAC7D,sBAAsB;CACxB;AACF;;;;;;AAOA,SAAS,cAAc,KAAuC;CAC5D,IAAI,CAAC,OAAO,OAAO,QAAQ,UACzB;CAGF,MAAM,SAAS;CAQf,IAAI,OAAO,OAAO,eAAe,YAAY,OAAO,WAAW,WAAW,GACxE;CAGF,IAAI,OAAO,OAAO,UAAU,UAC1B;CAGF,MAAM,OAAoB;EACxB,YAAY,OAAO;EACnB,OAAO,OAAO;CAChB;CAEA,IAAI,OAAO,OAAO,OAAO,UACvB,KAAK,KAAK,OAAO;CAGnB,IAAI,OAAO,OAAO,WAAW,UAC3B,KAAK,SAAS,OAAO;CAGvB,IAAI,MAAM,QAAQ,OAAO,SAAS,KAAK,OAAO,UAAU,OAAO,UAAU,OAAO,UAAU,QAAQ,GAChG,KAAK,YAAY,OAAO;CAG1B,OAAO;AACT"}

package/esm/security/index.mjs

@@ -1,5 +1,6 @@
 import { isPrivateOrReservedIp } from "./private-ip.mjs";
 import { assertUrlAllowed, fetchTextWithPolicy, guardedFetch, readTextCapped, resolveOutboundPolicy } from "./outbound-policy.mjs";
+import { UNSAFE_MERGE_KEYS, assignSafeKey, isUnsafeMergeKey, mergeSafely } from "./safe-merge.mjs";
 import { DEFAULT_SENSITIVE_KEYS, SENSITIVE_HEADERS, redact, redactError, redactHeaders, scrubSecrets } from "./redact.mjs";
 
 export {  };

package/esm/security/outbound-policy.d.mts

@@ -21,6 +21,15 @@ declare function assertUrlAllowed(rawUrl: string, policy: ResolvedOutboundPolicy
  * caller signal merged. Returns the raw `Response` — read its body via
  * {@link readTextCapped} to enforce `maxBytes`. Throws
  * {@link OutboundPolicyError} on a policy violation or timeout.
+ *
+ * Redirects are NEVER delegated to the platform: every hop is issued
+ * with `redirect: "manual"` and its `Location` is re-run through
+ * {@link assertUrlAllowed} before being followed (capped at
+ * `maxRedirects`), so a 3xx from an allowed host cannot smuggle the
+ * request to a private / metadata / off-allowlist target. Credential
+ * headers are stripped when a hop crosses an origin boundary. Pass
+ * `init.redirect: "manual"` to receive the raw 3xx, or `"error"` to
+ * reject on any redirect.
  */
 declare function guardedFetch(rawUrl: string, policyInput: OutboundPolicy, init?: RequestInit): Promise<Response>;
 /**

package/esm/security/outbound-policy.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"outbound-policy.d.mts","names":[],"sources":["../../../../../../../ai/src/security/outbound-policy.ts"],"mappings":";;;;;AAmBA;;;iBAAgB,qBAAA,CACd,MAAA,GAAQ,cAAA,GACP,sBAAsB;;;;;AAAA;AAiCzB;;iBAAsB,gBAAA,CACpB,MAAA,UACA,MAAA,EAAQ,sBAAA,GACP,OAAA,CAAQ,GAAA;;;;;;;;iBAiGW,YAAA,CACpB,MAAA,UACA,WAAA,EAAa,cAAA,EACb,IAAA,GAAO,WAAA,GACN,OAAA,CAAQ,QAAA;;;;AArGG;AAiGd;;iBAkCsB,cAAA,CACpB,QAAA,EAAU,QAAA,EACV,QAAA,WACC,OAAO;;;;;;iBAgDY,mBAAA,CACpB,MAAA,UACA,WAAA,EAAa,cAAA,EACb,IAAA,GAAO,WAAA,GACN,OAAA;EAAU,EAAA;EAAa,MAAA;EAAgB,UAAA;EAAoB,IAAA;AAAA"}
+{"version":3,"file":"outbound-policy.d.mts","names":[],"sources":["../../../../../../../ai/src/security/outbound-policy.ts"],"mappings":";;;;;AA+BA;;;iBAAgB,qBAAA,CACd,MAAA,GAAQ,cAAA,GACP,sBAAsB;;;;;AAAA;AAkCzB;;iBAAsB,gBAAA,CACpB,MAAA,UACA,MAAA,EAAQ,sBAAA,GACP,OAAA,CAAQ,GAAA;;;;;;;;;;;;AAAG;AAqHd;;;;iBAAsB,YAAA,CACpB,MAAA,UACA,WAAA,EAAa,cAAA,EACb,IAAA,GAAO,WAAA,GACN,OAAA,CAAQ,QAAA;;;;;;;iBAwGW,cAAA,CACpB,QAAA,EAAU,QAAA,EACV,QAAA,WACC,OAAO;;;;;;iBAgDY,mBAAA,CACpB,MAAA,UACA,WAAA,EAAa,cAAA,EACb,IAAA,GAAO,WAAA,GACN,OAAA;EAAU,EAAA;EAAa,MAAA;EAAgB,UAAA;EAAoB,IAAA;AAAA"}

package/esm/security/outbound-policy.mjs

@@ -9,6 +9,22 @@ import { isIP } from "node:net";
 const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
 /** 10s — default per-request timeout. */
 const DEFAULT_TIMEOUT_MS = 1e4;
+/** Default cap on the number of policy-validated redirect hops. */
+const DEFAULT_MAX_REDIRECTS = 5;
+/** 3xx statuses whose `Location` a follow re-issues. */
+const REDIRECT_STATUSES = new Set([
+	301,
+	302,
+	303,
+	307,
+	308
+]);
+/** Credential headers that must not survive a cross-origin redirect. */
+const CROSS_ORIGIN_STRIP_HEADERS = [
+	"authorization",
+	"cookie",
+	"proxy-authorization"
+];
 /**
 * Fill an {@link OutboundPolicy} with strict defaults: https-only,
 * private-IP deny on, 10s timeout, 5 MiB cap, global `fetch`. Idempotent
@@ -21,6 +37,7 @@ function resolveOutboundPolicy(policy = {}) {
 		denyPrivateIPsAfterDNS: policy.denyPrivateIPsAfterDNS ?? true,
 		maxBytes: policy.maxBytes ?? DEFAULT_MAX_BYTES,
 		timeoutMs: policy.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+		maxRedirects: policy.maxRedirects ?? DEFAULT_MAX_REDIRECTS,
 		signal: policy.signal,
 		fetch: policy.fetch ?? globalThis.fetch
 	};
@@ -107,16 +124,33 @@ function mergeSignals(timeout, external) {
 	else external.addEventListener("abort", () => abort(external), { once: true });
 	return controller.signal;
 }
+/** Flatten a headers init into a mutable lower-cased-key record. */
+function headersToRecord(headersInit) {
+	const record = {};
+	new Headers(headersInit).forEach((value, key) => {
+		record[key] = value;
+	});
+	return record;
+}
 /**
 * Policy-guarded `fetch`: validates the URL ({@link assertUrlAllowed}),
 * then performs the request with the policy's timeout and (optional)
 * caller signal merged. Returns the raw `Response` — read its body via
 * {@link readTextCapped} to enforce `maxBytes`. Throws
 * {@link OutboundPolicyError} on a policy violation or timeout.
+*
+* Redirects are NEVER delegated to the platform: every hop is issued
+* with `redirect: "manual"` and its `Location` is re-run through
+* {@link assertUrlAllowed} before being followed (capped at
+* `maxRedirects`), so a 3xx from an allowed host cannot smuggle the
+* request to a private / metadata / off-allowlist target. Credential
+* headers are stripped when a hop crosses an origin boundary. Pass
+* `init.redirect: "manual"` to receive the raw 3xx, or `"error"` to
+* reject on any redirect.
 */
 async function guardedFetch(rawUrl, policyInput, init) {
 	const policy = resolveOutboundPolicy(policyInput);
-	const url = await assertUrlAllowed(rawUrl, policy);
+	let url = await assertUrlAllowed(rawUrl, policy);
 	const timeoutController = new AbortController();
 	const timer = setTimeout(() => {
 		timeoutController.abort(new OutboundPolicyError(`outbound request timed out after ${policy.timeoutMs}ms`, { context: {
@@ -124,11 +158,51 @@ async function guardedFetch(rawUrl, policyInput, init) {
 			timeoutMs: policy.timeoutMs
 		} }));
 	}, policy.timeoutMs);
+	const signal = mergeSignals(timeoutController.signal, policy.signal);
+	const redirectMode = init?.redirect ?? "follow";
+	const headers = headersToRecord(init?.headers);
+	let method = init?.method ?? "GET";
+	let body = init?.body ?? void 0;
 	try {
-		return await policy.fetch(url, {
-			...init,
-			signal: mergeSignals(timeoutController.signal, policy.signal)
-		});
+		for (let hop = 0;; hop++) {
+			const response = await policy.fetch(url, {
+				...init,
+				method,
+				headers: { ...headers },
+				body,
+				redirect: "manual",
+				signal
+			});
+			const location = response.headers.get("location");
+			if (!REDIRECT_STATUSES.has(response.status) || location === null) return response;
+			if (redirectMode === "manual") return response;
+			if (redirectMode === "error") throw new OutboundPolicyError(`outbound request blocked — redirect received with redirect: "error" (${response.status} → ${location})`, { context: {
+				url: url.toString(),
+				location,
+				status: response.status
+			} });
+			if (hop >= policy.maxRedirects) throw new OutboundPolicyError(`outbound request blocked — more than ${policy.maxRedirects} redirects`, { context: {
+				url: rawUrl,
+				maxRedirects: policy.maxRedirects
+			} });
+			let target;
+			try {
+				target = new URL(location, url);
+			} catch {
+				throw new OutboundPolicyError(`outbound request blocked — invalid redirect Location: ${location}`, { context: {
+					url: url.toString(),
+					location
+				} });
+			}
+			const next = await assertUrlAllowed(target.toString(), policy);
+			if (response.body) await response.body.cancel().catch(() => void 0);
+			if (next.origin !== url.origin) for (const name of CROSS_ORIGIN_STRIP_HEADERS) delete headers[name];
+			if (response.status === 303 || (response.status === 301 || response.status === 302) && method !== "GET" && method !== "HEAD") {
+				method = "GET";
+				body = void 0;
+			}
+			url = next;
+		}
 	} finally {
 		clearTimeout(timer);
 	}