agentfootprint 7.24.0 → 7.26.0

package/dist/core/agent/stages/callLLM.js

@@ -25,6 +25,7 @@ const typedEmit_js_1 = require("../../../recorders/core/typedEmit.js");
 const resilienceHooks_js_1 = require("../../../recorders/core/resilienceHooks.js");
 const cost_js_1 = require("../../cost.js");
 const outputSchema_js_1 = require("../../outputSchema.js");
+const outputEnforcement_js_1 = require("../outputEnforcement.js");
 const reliabilityExecution_js_1 = require("./reliabilityExecution.js");
 /**
  * Drop the fields that exist for the library and never for the model.
@@ -94,7 +95,14 @@ function buildCallLLMStage(deps) {
         // schemas at startup before the tools slot has run. Computed BEFORE the
         // llm_start emit so the event reports what the model ACTUALLY saw this call
         // (count + the name/description catalog), not the static startup set.
-        const activeToolSchemas = scope.dynamicToolSchemas ?? deps.toolSchemas;
+        const registeredToolSchemas = scope.dynamicToolSchemas ?? deps.toolSchemas;
+        // Under `'tool-forced'` the schema rides along as one more tool ON THE
+        // WIRE. It is reported in `llm_start` too, and deliberately: that event's
+        // whole claim is "what the model actually saw this call", and a tool the
+        // model was forced to use is the last thing to leave out of it.
+        const activeToolSchemas = deps.schemaTool
+            ? [...registeredToolSchemas, deps.schemaTool]
+            : registeredToolSchemas;
         (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.stream.llm_start', {
             iteration,
             provider: deps.provider.name,
@@ -121,6 +129,9 @@ function buildCallLLMStage(deps) {
             ...(deps.thinkingBudget !== undefined && {
                 thinking: { budget: deps.thinkingBudget },
             }),
+            ...(deps.schemaTool !== undefined && {
+                toolChoice: { type: 'tool', name: deps.schemaTool.name },
+            }),
         };
         // v2.6+ — call cache strategy to attach provider-specific cache
         // hints. CacheGate has already routed (apply-markers / no-markers)
@@ -191,6 +202,25 @@ function buildCallLLMStage(deps) {
                 // after a stream is a pre-existing quirk; see MENTAL_MODEL §14.)
                 resp = await deps.provider.complete(req, providerHooks);
             }
+            // `'tool-forced'`: the answer arrived as the synthetic tool's ARGUMENTS,
+            // so it is moved into `content` and the call is taken off the list here,
+            // at the single seam every later reader goes through. Everything
+            // downstream — the reliability validator, the scope writes, the Route
+            // decider, the retry loop — then sees the response it would have seen
+            // under `'instruct'`: a final answer that is a JSON string, and no tool
+            // calls. One normalization, no second code path, and nothing further
+            // down has to know which strategy is in force.
+            const forcedName = deps.schemaTool?.name;
+            if (forcedName !== undefined) {
+                const answer = (0, outputEnforcement_js_1.readSchemaToolAnswer)(resp);
+                if (answer !== undefined) {
+                    resp = {
+                        ...resp,
+                        content: answer,
+                        toolCalls: resp.toolCalls.filter((tc) => tc.name !== forcedName),
+                    };
+                }
+            }
             return resp;
         };
         // v2.13 — build the output-schema validator hook when both

package/dist/core/agent/stages/callLLM.js.map

@@ -1 +1 @@
-{"version":3,"file":"callLLM.js","sourceRoot":"","sources":["../../../../src/core/agent/stages/callLLM.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"callLLM.js","sourceRoot":"","sources":["../../../../src/core/agent/stages/callLLM.ts"],"names":[],"mappings":"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"}

package/dist/core/agent/stages/outputRetry.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * outputRetry — the branch that asks again when the answer failed the schema.
+ *
+ * Mounted as a THIRD branch of the Route decider, and only on an agent that
+ * opted into `.outputSchema(parser, { retries })`. It carries `{ loopTo }`
+ * to the same target the `tool-calls` branch loops to, which is the whole
+ * mechanism: a retry is not a special mode, it is one more ordinary turn of
+ * the ReAct loop. The injection engine re-evaluates, the slots recompose,
+ * the cache decides, the model is called — so the attempt gets its own
+ * `iteration_start` / `llm_start` / `llm_end` bracket and its own `cost.tick`
+ * against `costBudget`.
+ *
+ * That is the difference from the in-stage schema retry the reliability gate
+ * has done since v2.13. There, N attempts happen inside ONE `call-llm` stage:
+ * one bracket for all of them, and one cost tick carrying only the last
+ * attempt's usage — attempts that were genuinely billed and are invisible in
+ * the recording. Here every attempt is a turn, and the recording says so.
+ *
+ * The two layers compose rather than collide. With `.reliability()` also
+ * configured, its in-stage rules run FIRST and decide what to do with a
+ * response before it is committed; `retries` governs answers that WERE
+ * committed and turned out invalid.
+ *
+ * Pure function apart from its enforcement config — no closure over Agent
+ * class state.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildOutputRetryStage = void 0;
+const typedEmit_js_1 = require("../../../recorders/core/typedEmit.js");
+const outputEnforcement_js_1 = require("../outputEnforcement.js");
+/**
+ * Build the retry stage. `enforcement.retries` is the cap the decider already
+ * checked before routing here — this stage does the work of asking again.
+ */
+function buildOutputRetryStage(enforcement) {
+    return (scope) => {
+        const iteration = scope.iteration;
+        const failure = scope.outputSchemaFailure;
+        if (failure === undefined) {
+            // Unreachable through the decider, which writes the carrier immediately
+            // before routing here. Returning quietly rather than throwing keeps a
+            // hand-built chart that mounts this branch without the decider from
+            // taking down a run over a missing diagnostic.
+            return;
+        }
+        const failedAnswer = scope.llmLatestContent;
+        const [answerTurn, correctionTurn] = (0, outputEnforcement_js_1.buildCorrectiveTurn)(failedAnswer, failure, {
+            attempt: failure.attempt,
+            // The total the run may spend: the first attempt plus its retries.
+            totalAttempts: enforcement.retries + 1,
+        });
+        const hash = (0, outputEnforcement_js_1.correctiveMessageHash)(correctionTurn.content);
+        // The conversation, as it really went: the answer that failed, then the
+        // correction. A plain local array — a TypedScope array read is a live
+        // proxy view, and both the commit and the event payload below must be
+        // detached plain data.
+        const newHistory = [
+            ...scope.history,
+            answerTurn,
+            correctionTurn,
+        ];
+        scope.history = newHistory;
+        (0, outputEnforcement_js_1.recordOutputAttempt)(scope, {
+            attempt: failure.attempt,
+            iteration,
+            outcome: 'retried',
+            stage: failure.stage,
+            error: failure.error,
+            ...(failure.path !== undefined && { path: failure.path }),
+            correctiveMessageHash: hash,
+        });
+        (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.agent.output_schema_retry', {
+            attempt: failure.attempt,
+            // What is left AFTER this correction — `0` means this is the last ask.
+            retriesRemaining: enforcement.retries - failure.attempt,
+            iteration,
+            stage: failure.stage,
+            error: failure.error,
+            ...(failure.path !== undefined && { path: failure.path }),
+            correctiveMessageHash: hash,
+        });
+        // Close this iteration's bracket before the loop turns. Every recorder
+        // that synthesizes steps counts on `iteration_start` and `iteration_end`
+        // pairing per `iterIndex`, and the crash-checkpoint tracker takes its
+        // history snapshot from this payload — so a retry that skipped it would
+        // leave a run with one more start than end and a checkpoint one turn
+        // behind the conversation.
+        (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.agent.iteration_end', {
+            turnIndex: 0,
+            iterIndex: iteration,
+            toolCallCount: 0,
+            history: newHistory,
+        });
+        // A retry consumes an iteration, exactly as a tool call does. It is one
+        // more real turn against the agent's declared budget, and the iteration
+        // counter is the vocabulary every bracket in the run is keyed on.
+        scope.iteration = iteration + 1;
+    };
+}
+exports.buildOutputRetryStage = buildOutputRetryStage;
+//# sourceMappingURL=outputRetry.js.map

package/dist/core/agent/stages/outputRetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outputRetry.js","sourceRoot":"","sources":["../../../../src/core/agent/stages/outputRetry.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAIH,uEAAiE;AACjE,kEAKiC;AAGjC;;;GAGG;AACH,SAAgB,qBAAqB,CACnC,WAAsC;IAEtC,OAAO,CAAC,KAAK,EAAE,EAAE;QACf,MAAM,SAAS,GAAG,KAAK,CAAC,SAAmB,CAAC;QAC5C,MAAM,OAAO,GAAG,KAAK,CAAC,mBAAmB,CAAC;QAC1C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,wEAAwE;YACxE,sEAAsE;YACtE,oEAAoE;YACpE,+CAA+C;YAC/C,OAAO;QACT,CAAC;QAED,MAAM,YAAY,GAAG,KAAK,CAAC,gBAA0B,CAAC;QACtD,MAAM,CAAC,UAAU,EAAE,cAAc,CAAC,GAAG,IAAA,0CAAmB,EAAC,YAAY,EAAE,OAAO,EAAE;YAC9E,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,mEAAmE;YACnE,aAAa,EAAE,WAAW,CAAC,OAAO,GAAG,CAAC;SACvC,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,IAAA,4CAAqB,EAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QAE3D,wEAAwE;QACxE,sEAAsE;QACtE,sEAAsE;QACtE,uBAAuB;QACvB,MAAM,UAAU,GAAiB;YAC/B,GAAI,KAAK,CAAC,OAAiC;YAC3C,UAAU;YACV,cAAc;SACf,CAAC;QACF,KAAK,CAAC,OAAO,GAAG,UAAU,CAAC;QAE3B,IAAA,0CAAmB,EAAC,KAAK,EAAE;YACzB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,SAAS;YACT,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;YACzD,qBAAqB,EAAE,IAAI;SAC5B,CAAC,CAAC;QAEH,IAAA,wBAAS,EAAC,KAAK,EAAE,0CAA0C,EAAE;YAC3D,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,uEAAuE;YACvE,gBAAgB,EAAE,WAAW,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO;YACvD,SAAS;YACT,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;YACzD,qBAAqB,EAAE,IAAI;SAC5B,CAAC,CAAC;QAEH,uEAAuE;QACvE,yEAAyE;QACzE,sEAAsE;QACtE,wEAAwE;QACxE,qEAAqE;QACrE,2BAA2B;QAC3B,IAAA,wBAAS,EAAC,KAAK,EAAE,oCAAoC,EAAE;YACrD,SAAS,EAAE,CAAC;YACZ,SAAS,EAAE,SAAS;YACpB,aAAa,EAAE,CAAC;YAChB,OAAO,EAAE,UAAU;SACpB,CAAC,CAAC;QAEH,wEAAwE;QACxE,wEAAwE;QACxE,kEAAkE;QAClE,KAAK,CAAC,SAAS,GAAG,SAAS,GAAG,CAAC,CAAC;IAClC,CAAC,CAAC;AACJ,CAAC;AAxED,sDAwEC"}

package/dist/core/agent/stages/route.js

@@ -18,20 +18,35 @@ exports.buildRouteDeciderStage = exports.routeDeciderStage = void 0;
 const typedEmit_js_1 = require("../../../recorders/core/typedEmit.js");
 const runChain_js_1 = require("../middleware/runChain.js");
 const ledger_js_1 = require("../middleware/ledger.js");
-const routeDeciderStage = (scope) => {
+const outputEnforcement_js_1 = require("../outputEnforcement.js");
+/** The base decision, with the sentence that explains it. Split out so the
+ *  enforcement-enabled path can decide, then judge, then announce ONCE — an
+ *  agent whose answer is about to be re-asked should not have a route event
+ *  saying it finished. */
+function decideBranch(scope) {
     const toolCalls = scope.llmLatestToolCalls;
     const iteration = scope.iteration;
     const chosen = toolCalls.length > 0 && iteration < scope.maxIterations ? 'tool-calls' : 'final';
-    (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.agent.route_decided', {
-        turnIndex: 0,
-        iterIndex: iteration,
+    return {
         chosen,
         rationale: chosen === 'tool-calls'
             ? `LLM requested ${toolCalls.length} tool call(s)`
             : iteration >= scope.maxIterations
                 ? 'maxIterations reached — forcing final'
                 : 'LLM produced no tool calls — final answer',
+    };
+}
+function emitRouteDecided(scope, chosen, rationale) {
+    (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.agent.route_decided', {
+        turnIndex: 0,
+        iterIndex: scope.iteration,
+        chosen,
+        rationale,
     });
+}
+const routeDeciderStage = (scope) => {
+    const { chosen, rationale } = decideBranch(scope);
+    emitRouteDecided(scope, chosen, rationale);
     return chosen;
 };
 exports.routeDeciderStage = routeDeciderStage;
@@ -61,11 +76,28 @@ exports.routeDeciderStage = routeDeciderStage;
  * would be running it over something that is not the output.
  *
  * Empty chain → the exact synchronous decider this file has always exported.
+ *
+ * ## Why the schema is judged HERE too
+ *
+ * The same property that made this the output seam makes it the enforcement
+ * seam. `outputSchema` used to be judged only at the caller's boundary, after
+ * the run — a fine place to reject an answer and a useless place to fix one,
+ * because the loop has already stopped. Judged here, one stage before the
+ * Final branch, the run still HAS a loop: a failed answer can route to
+ * `'output-retry'`, which loops back for one more real turn.
+ *
+ * The judging runs AFTER the message chain, over the content the chain
+ * produced, because that is the string the caller will receive — validating
+ * the pre-chain value would judge an answer nobody gets. A DENIED answer is
+ * never judged or retried: it was withheld on purpose, and re-asking for it
+ * would be the library working around a rule the app wrote.
  */
-function buildRouteDeciderStage(messageMiddleware) {
+function buildRouteDeciderStage(messageMiddleware, enforcement) {
     const chain = messageMiddleware ?? [];
-    if (chain.length === 0)
+    if (chain.length === 0 && enforcement === undefined)
         return exports.routeDeciderStage;
+    if (enforcement !== undefined)
+        return buildEnforcingDecider(chain, enforcement);
     return async (scope) => {
         const chosen = (0, exports.routeDeciderStage)(scope);
         if (chosen !== 'final')
@@ -94,4 +126,77 @@ function buildRouteDeciderStage(messageMiddleware) {
     };
 }
 exports.buildRouteDeciderStage = buildRouteDeciderStage;
+/**
+ * The decider an agent with `.outputSchema(parser, { retries })` runs:
+ * decide, run the output chain if there is one, judge the answer, THEN
+ * announce the branch — so `route_decided` names the branch the run actually
+ * took rather than the one it was heading for.
+ */
+function buildEnforcingDecider(chain, enforcement) {
+    return async (scope) => {
+        const base = decideBranch(scope);
+        if (base.chosen !== 'final') {
+            emitRouteDecided(scope, base.chosen, base.rationale);
+            return base.chosen;
+        }
+        let denied = false;
+        if (chain.length > 0) {
+            const verdict = await (0, runChain_js_1.runMessageChain)(chain, {
+                phase: 'output',
+                content: scope.llmLatestContent,
+                history: [...scope.history],
+                iteration: scope.iteration,
+                ...(scope.runIdentity && { identity: scope.runIdentity }),
+            });
+            (0, ledger_js_1.recordDecisions)(scope, verdict.decisions);
+            if (verdict.kind === 'deny') {
+                denied = true;
+                scope.messageDeniedReason = verdict.reason;
+                scope.messageDeniedPhase = 'output';
+                scope.messageDeniedBy = verdict.middleware;
+            }
+            scope.llmLatestContent = verdict.content;
+        }
+        // A withheld answer is not judged and never re-asked. The app decided
+        // nobody gets this string; asking the model for a better-shaped version
+        // of it would be the library routing around that decision.
+        if (denied) {
+            emitRouteDecided(scope, 'final', base.rationale);
+            return 'final';
+        }
+        const attempt = (scope.outputAttempts?.length ?? 0) + 1;
+        const failure = (0, outputEnforcement_js_1.judgeAnswer)(scope.llmLatestContent, enforcement.parser);
+        if (failure === undefined) {
+            (0, outputEnforcement_js_1.recordOutputAttempt)(scope, {
+                attempt,
+                iteration: scope.iteration,
+                outcome: 'passed',
+            });
+            emitRouteDecided(scope, 'final', base.rationale);
+            return 'final';
+        }
+        if (attempt <= enforcement.retries) {
+            // The retry stage writes the correction and files the row, because it
+            // is the one that knows what it wrote. This is the hand-off.
+            scope.outputSchemaFailure = { attempt, ...failure };
+            emitRouteDecided(scope, 'output-retry', `final answer failed the output schema (${failure.stage}) — ` +
+                `asking again, attempt ${attempt + 1} of ${enforcement.retries + 1}`);
+            return 'output-retry';
+        }
+        // Out of retries. The answer stands as the run's answer; `runTyped()`
+        // throws on it at the boundary exactly as it did before any of this
+        // existed, and `.outputFallback()` still gets its turn there.
+        (0, outputEnforcement_js_1.recordOutputAttempt)(scope, {
+            attempt,
+            iteration: scope.iteration,
+            outcome: 'exhausted',
+            stage: failure.stage,
+            error: failure.error,
+            ...(failure.path !== undefined && { path: failure.path }),
+        });
+        emitRouteDecided(scope, 'final', `final answer failed the output schema (${failure.stage}) and ` +
+            `${enforcement.retries} retry/retries were spent`);
+        return 'final';
+    };
+}
 //# sourceMappingURL=route.js.map

package/dist/core/agent/stages/route.js.map

@@ -1 +1 @@
-{"version":3,"file":"route.js","sourceRoot":"","sources":["../../../../src/core/agent/stages/route.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAGH,uEAAiE;AAIjE,2DAA4D;AAC5D,uDAA0D;AAInD,MAAM,iBAAiB,GAAG,CAAC,KAA6B,EAAe,EAAE;IAC9E,MAAM,SAAS,GAAG,KAAK,CAAC,kBAAiD,CAAC;IAC1E,MAAM,SAAS,GAAG,KAAK,CAAC,SAAmB,CAAC;IAC5C,MAAM,MAAM,GACV,SAAS,CAAC,MAAM,GAAG,CAAC,IAAI,SAAS,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC;IAEnF,IAAA,wBAAS,EAAC,KAAK,EAAE,oCAAoC,EAAE;QACrD,SAAS,EAAE,CAAC;QACZ,SAAS,EAAE,SAAS;QACpB,MAAM;QACN,SAAS,EACP,MAAM,KAAK,YAAY;YACrB,CAAC,CAAC,iBAAiB,SAAS,CAAC,MAAM,eAAe;YAClD,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC,aAAa;gBAClC,CAAC,CAAC,uCAAuC;gBACzC,CAAC,CAAC,2CAA2C;KAClD,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAnBW,QAAA,iBAAiB,qBAmB5B;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,SAAgB,sBAAsB,CACpC,iBAAgD;IAEhD,MAAM,KAAK,GAAG,iBAAiB,IAAI,EAAE,CAAC;IACtC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,yBAAiB,CAAC;IACjD,OAAO,KAAK,EAAE,KAAK,EAAE,EAAE;QACrB,MAAM,MAAM,GAAG,IAAA,yBAAiB,EAAC,KAAK,CAAC,CAAC;QACxC,IAAI,MAAM,KAAK,OAAO;YAAE,OAAO,MAAM,CAAC;QAEtC,MAAM,OAAO,GAAG,MAAM,IAAA,6BAAe,EAAC,KAAK,EAAE;YAC3C,KAAK,EAAE,QAAQ;YACf,OAAO,EAAE,KAAK,CAAC,gBAAgB;YAC/B,OAAO,EAAE,CAAC,GAAI,KAAK,CAAC,OAAiC,CAAC;YACtD,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,GAAG,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC;SAC1D,CAAC,CAAC;QACH,IAAA,2BAAe,EAAC,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;QAC1C,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC5B,uEAAuE;YACvE,wEAAwE;YACxE,yEAAyE;YACzE,sEAAsE;YACtE,KAAK,CAAC,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;YAC3C,KAAK,CAAC,kBAAkB,GAAG,QAAQ,CAAC;YACpC,KAAK,CAAC,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;QAC7C,CAAC;QACD,wEAAwE;QACxE,qDAAqD;QACrD,KAAK,CAAC,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;QACzC,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC;AA/BD,wDA+BC"}
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../../../../src/core/agent/stages/route.ts"],"names":[],"mappings":"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"}

package/dist/core/outputSchema.js.map

@@ -1 +1 @@
-{"version":3,"file":"outputSchema.js","sourceRoot":"","sources":["../../src/core/outputSchema.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;;;AA6CH;;;;;;;GAOG;AACH,MAAa,iBAAkB,SAAQ,KAAK;IACjC,SAAS,CAAS;IAClB,KAAK,CAAmC;IAC/B,KAAK,CAAW;IAElC,YACE,OAAe,EACf,IAAqF;QAErF,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IACxD,CAAC;CACF;AAfD,8CAeC;AAED;;;;GAIG;AACH,SAAgB,uBAAuB,CAAC,MAAmC;IACzE,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,sBAAsB,MAAM,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACnF,OAAO,CACL,2DAA2D;QAC3D,6DAA6D;QAC7D,IAAI,CACL,CAAC;AACJ,CAAC;AAPD,0DAOC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,iBAAiB,CAAI,GAAW,EAAE,MAA6B;IAC7E,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,iBAAiB,CACzB,gFAAgF,EAChF,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,CAC/C,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,iBAAiB,CAAC,iEAAiE,EAAE;YAC7F,SAAS,EAAE,GAAG;YACd,KAAK,EAAE,iBAAiB;YACxB,KAAK;SACN,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAnBD,8CAmBC"}
+{"version":3,"file":"outputSchema.js","sourceRoot":"","sources":["../../src/core/outputSchema.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;;;AAiGH;;;;;;;GAOG;AACH,MAAa,iBAAkB,SAAQ,KAAK;IACjC,SAAS,CAAS;IAClB,KAAK,CAAmC;IAC/B,KAAK,CAAW;IAElC,YACE,OAAe,EACf,IAAqF;QAErF,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IACxD,CAAC;CACF;AAfD,8CAeC;AAED;;;;GAIG;AACH,SAAgB,uBAAuB,CAAC,MAAmC;IACzE,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,sBAAsB,MAAM,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACnF,OAAO,CACL,2DAA2D;QAC3D,6DAA6D;QAC7D,IAAI,CACL,CAAC;AACJ,CAAC;AAPD,0DAOC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,iBAAiB,CAAI,GAAW,EAAE,MAA6B;IAC7E,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,iBAAiB,CACzB,gFAAgF,EAChF,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,CAC/C,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,iBAAiB,CAAC,iEAAiE,EAAE;YAC7F,SAAS,EAAE,GAAG;YACd,KAAK,EAAE,iBAAiB;YACxB,KAAK;SACN,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAnBD,8CAmBC"}

package/dist/esm/adapters/hosting/agentcore.d.ts

@@ -23,12 +23,26 @@
  *
  *   POST /invocations   JSON `{ "prompt": "..." }` → JSON `{ "response", "status" }`
  *   GET  /ping          → `{ "status": "Healthy", "time_of_last_update": <unix seconds> }`
+ *   GET  /ws            a bidirectional WebSocket, on the SAME port
  *
  * and the caller's conversation arrives in the
  * `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header rather than in the body,
  * which is the one thing paths-and-bodies configuration alone could not
  * express before this release.
  *
+ * ── The second door ──────────────────────────────────────────────────────────
+ * `/ws` is this runtime's answer for a caller that cannot host an inbound
+ * endpoint — a browser, most obviously — and so dials out and parks a channel
+ * instead. It is the same container and the same port, which is exactly why the
+ * two doors here share one socket.
+ *
+ * Its wire facts are ADAPTER facts and live nowhere but this file: 32KB frames,
+ * a 15-minute idle ceiling, the bearer credential carried as a
+ * `Sec-WebSocket-Protocol` offer because a browser's WebSocket API cannot set a
+ * header, and session affinity that has to be readable from the query string
+ * for the same reason. The port knows none of it — it is handed a session id
+ * and a header bag, the same two things every other transport hands it.
+ *
  * ── Verification status, stated plainly ──────────────────────────────────────
  * `agentCoreRuntimeHost` is **plain HTTP and is really verified**: it runs the
  * same host conformance suite as `nodeHost`, over a real socket, in
@@ -54,7 +68,7 @@
  * importing this module costs zero peer-dep load.
  */
 /// <reference types="node" />
-import type { HttpHost, HttpWire } from '../../hosting/httpHost.js';
+import type { ConversationHandshake, HandshakeFacts, HttpHost, HttpWire } from '../../hosting/httpHost.js';
 import type { CheckpointEnvelope, SessionLifecycle } from '../../hosting/types.js';
 /** Options for {@link agentCoreRuntimeHost}. */
 export interface AgentCoreRuntimeHostOptions {
@@ -104,6 +118,14 @@ export interface AgentCoreRuntimeHostOptions {
      *   });
      */
     readonly server?: import('node:http').Server;
+    /**
+     * Path that takes a conversation upgrade. Default `'/ws'` — the runtime's
+     * own second door, beside `/invocations` on the same port.
+     *
+     * You do not need `server` for this: both doors share one socket by
+     * construction, which is what the single-port container required.
+     */
+    readonly conversationPath?: string;
 }
 /**
  * The AgentCore Runtime contract as an {@link HttpWire}.
@@ -113,6 +135,33 @@ export interface AgentCoreRuntimeHostOptions {
  * else can reuse them by name.
  */
 export declare function agentCoreRuntimeWire(busy?: () => boolean): HttpWire;
+/**
+ * The `/ws` handshake, in this runtime's spelling: **header-or-query session
+ * affinity, and the bearer subprotocol mapped into headers.**
+ *
+ * ── Why the query string is read at all ──────────────────────────────────────
+ * The same header carries the session on `/invocations`, and it is preferred
+ * here too. But the caller this door exists for is a browser, and the browser
+ * WebSocket API cannot set a header — so a session id has nowhere to travel
+ * except the URL. Both the runtime's header name and the plain `sessionId` are
+ * accepted as query parameters, case-insensitively; **the header wins** when
+ * both arrive, so a caller that sets both is never surprised by which one the
+ * server preferred. That is the same precedence rule the request dialect uses.
+ *
+ * ── Why the credential becomes a header ──────────────────────────────────────
+ * A bearer token offered as a subprotocol is this runtime's spelling of
+ * `Authorization`, and a port field spelled the way one vendor spells it is how
+ * a port stops being one. So it lands in `headers.authorization` as
+ * `Bearer <token>` — the vocabulary every other transport already uses — and
+ * the raw `sec-websocket-protocol` header is left in place, so an application
+ * that reads the offer itself still can. **Nothing here authenticates
+ * anything**: the port never proves who is calling, and a token that arrived is
+ * a claim, exactly like the session id beside it.
+ *
+ * Exported by name so the mapping is inspectable and testable without binding a
+ * socket, the same way the body shapes are.
+ */
+export declare function readAgentCoreConversation(facts: HandshakeFacts): ConversationHandshake;
 /**
  * An `AgentHost` that speaks AgentCore Runtime's container contract.
  *

package/dist/esm/adapters/hosting/agentcore.js

@@ -23,12 +23,26 @@
  *
  *   POST /invocations   JSON `{ "prompt": "..." }` → JSON `{ "response", "status" }`
  *   GET  /ping          → `{ "status": "Healthy", "time_of_last_update": <unix seconds> }`
+ *   GET  /ws            a bidirectional WebSocket, on the SAME port
  *
  * and the caller's conversation arrives in the
  * `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header rather than in the body,
  * which is the one thing paths-and-bodies configuration alone could not
  * express before this release.
  *
+ * ── The second door ──────────────────────────────────────────────────────────
+ * `/ws` is this runtime's answer for a caller that cannot host an inbound
+ * endpoint — a browser, most obviously — and so dials out and parks a channel
+ * instead. It is the same container and the same port, which is exactly why the
+ * two doors here share one socket.
+ *
+ * Its wire facts are ADAPTER facts and live nowhere but this file: 32KB frames,
+ * a 15-minute idle ceiling, the bearer credential carried as a
+ * `Sec-WebSocket-Protocol` offer because a browser's WebSocket API cannot set a
+ * header, and session affinity that has to be readable from the query string
+ * for the same reason. The port knows none of it — it is handed a session id
+ * and a header bag, the same two things every other transport hands it.
+ *
  * ── Verification status, stated plainly ──────────────────────────────────────
  * `agentCoreRuntimeHost` is **plain HTTP and is really verified**: it runs the
  * same host conformance suite as `nodeHost`, over a real socket, in
@@ -61,6 +75,7 @@ const HOST_NAME = 'agentCoreRuntimeHost';
 /** The runtime's container contract, as constants rather than as scattered literals. */
 const INVOKE_PATH = '/invocations';
 const HEALTH_PATH = '/ping';
+const CONVERSATION_PATH = '/ws';
 const RUNTIME_PORT = 8080;
 /**
  * The header the runtime puts the caller's conversation in. Matched
@@ -68,6 +83,34 @@ const RUNTIME_PORT = 8080;
  * front of the container is free to re-case them.
  */
 const SESSION_HEADER = 'X-Amzn-Bedrock-AgentCore-Runtime-Session-Id';
+/**
+ * What the `/ws` door caps, as the runtime imposes it — **32KB per frame and a
+ * 15-minute idle timeout.**
+ *
+ * Declared rather than worked around. A 32KB cap hidden inside auto-chunking
+ * would have this adapter deciding, for every consumer at once, how a message
+ * is split and how the far side knows the last piece landed; a 15-minute idle
+ * answered with an invented heartbeat would put bytes on the wire that the
+ * consumer's parser never agreed to. Both belong to the protocol above this
+ * door, and both are actionable only if the number is visible.
+ *
+ * `maxFrameBytes` is enforced here, in both directions, because a frame past it
+ * would be cut by the front door anyway and a refusal that names the ceiling
+ * beats a truncation that does not. `idleMs` is REPORTED: the timeout belongs
+ * to what sits in front of this container, and the honest thing is to say so
+ * rather than to close a channel the runtime might have kept.
+ */
+const CONVERSATION_LIMITS = { maxFrameBytes: 32_768, idleMs: 900_000 };
+/**
+ * The subprotocol a browser offers to carry its bearer credential, because the
+ * WebSocket API gives it no way to send an `Authorization` header.
+ *
+ * Two spellings are recognised and both are ordinary browser-expressible ones:
+ * `['bearer', '<token>']` (two offers) and `['bearer.<token>']` (one). What is
+ * echoed back in the 101 is the word `bearer` and never the token — a
+ * credential belongs in a request, not in a response header a proxy may log.
+ */
+const BEARER_SUBPROTOCOL = 'bearer';
 /**
  * The AgentCore Runtime contract as an {@link HttpWire}.
  *
@@ -118,8 +161,73 @@ export function agentCoreRuntimeWire(busy) {
         // 'success' nor 'error' because it is neither: the run stopped to ask a
         // person, it is stored, and a later call carrying `decision` finishes it.
         awaiting: (pending) => ({ awaiting: pending, status: 'awaiting' }),
+        readConversation: readAgentCoreConversation,
     };
 }
+/**
+ * The `/ws` handshake, in this runtime's spelling: **header-or-query session
+ * affinity, and the bearer subprotocol mapped into headers.**
+ *
+ * ── Why the query string is read at all ──────────────────────────────────────
+ * The same header carries the session on `/invocations`, and it is preferred
+ * here too. But the caller this door exists for is a browser, and the browser
+ * WebSocket API cannot set a header — so a session id has nowhere to travel
+ * except the URL. Both the runtime's header name and the plain `sessionId` are
+ * accepted as query parameters, case-insensitively; **the header wins** when
+ * both arrive, so a caller that sets both is never surprised by which one the
+ * server preferred. That is the same precedence rule the request dialect uses.
+ *
+ * ── Why the credential becomes a header ──────────────────────────────────────
+ * A bearer token offered as a subprotocol is this runtime's spelling of
+ * `Authorization`, and a port field spelled the way one vendor spells it is how
+ * a port stops being one. So it lands in `headers.authorization` as
+ * `Bearer <token>` — the vocabulary every other transport already uses — and
+ * the raw `sec-websocket-protocol` header is left in place, so an application
+ * that reads the offer itself still can. **Nothing here authenticates
+ * anything**: the port never proves who is calling, and a token that arrived is
+ * a claim, exactly like the session id beside it.
+ *
+ * Exported by name so the mapping is inspectable and testable without binding a
+ * socket, the same way the body shapes are.
+ */
+export function readAgentCoreConversation(facts) {
+    const sessionId = headerValue(facts, SESSION_HEADER) ?? queryValue(facts, SESSION_HEADER, 'sessionId');
+    const token = bearerFromSubprotocols(facts.headers['sec-websocket-protocol']);
+    return {
+        ...(sessionId !== undefined && { sessionId }),
+        ...(token !== undefined && {
+            headers: { authorization: `Bearer ${token}` },
+            // Echoed so a client that offered a subprotocol gets one back — the word
+            // only. Putting the token in a response header would hand the credential
+            // to every proxy on the way home.
+            protocol: BEARER_SUBPROTOCOL,
+        }),
+    };
+}
+/** A query parameter by any of several names, matched case-insensitively. */
+function queryValue(facts, ...names) {
+    const wanted = names.map((name) => name.toLowerCase());
+    for (const [key, value] of facts.query.entries()) {
+        if (wanted.includes(key.toLowerCase()) && value.length > 0)
+            return value;
+    }
+    return undefined;
+}
+/** The token out of a `Sec-WebSocket-Protocol` offer, in either browser spelling. */
+function bearerFromSubprotocols(offered) {
+    if (!offered)
+        return undefined;
+    const parts = offered
+        .split(',')
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+    const marker = parts.findIndex((part) => part.toLowerCase() === BEARER_SUBPROTOCOL);
+    if (marker >= 0 && parts[marker + 1] !== undefined)
+        return parts[marker + 1];
+    const prefix = `${BEARER_SUBPROTOCOL}.`;
+    const dotted = parts.find((part) => part.toLowerCase().startsWith(prefix));
+    return dotted?.slice(prefix.length) || undefined;
+}
 /**
  * An `AgentHost` that speaks AgentCore Runtime's container contract.
  *
@@ -140,6 +248,8 @@ export function agentCoreRuntimeHost(options = {}) {
         wire: agentCoreRuntimeWire(options.busy),
         invokePath: INVOKE_PATH,
         healthPath: HEALTH_PATH,
+        conversationPath: options.conversationPath ?? CONVERSATION_PATH,
+        conversationLimits: CONVERSATION_LIMITS,
         // With a caller-owned server this adapter binds nothing, so it must not
         // invent the contract's port either — the port is whatever the caller
         // listened on, and passing one anyway is refused by `httpHost` rather than