agentfootprint 7.17.0 → 7.18.0

package/dist/core/agent/middleware/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/agent/middleware/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAEH,6CAAiD;AAAxC,oGAAA,KAAK,OAAA;AAAE,kGAAA,GAAG,OAAA;AAAE,mGAAA,IAAI,OAAA;AACzB,yCAA4E;AAAnE,+GAAA,kBAAkB,OAAA"}

package/dist/core/agent/middleware/ledger.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * middleware/ledger — INTERNAL. Where a chain's decisions become record.
+ *
+ * Pattern: one writer for one committed key.
+ * Role:    core/ layer. `runChain` decides; this file is the only thing
+ *          that commits what it decided and emits the matching event, so
+ *          the three call sites cannot record the same fact three
+ *          different ways.
+ * Emits:   `agentfootprint.middleware.decision`, one per row.
+ *
+ * ## Why the original value is committed too
+ *
+ * A transform makes the trace and the wire disagree — the model saw one
+ * string, the run remembers another. Committing the pair, with the
+ * middleware's name and its `why` beside it, is what turns that
+ * disagreement from a lie into a record. Every slice taken afterwards can
+ * then find the moment the value changed and who changed it.
+ *
+ * This is not a redaction layer, and it is not trying to be one. For the
+ * `'input'` phase in particular, the ledger row is the ONLY copy of the
+ * pre-scrub text anywhere in the run — the seed stage commits the
+ * transformed message and nothing else ever holds the original. If your
+ * threat model says the original must not survive in the commit log,
+ * configure footprintjs redaction over this key; it scrubs `before` /
+ * `after` at write time and the row itself survives, so the run still says
+ * a scrub happened and who did it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordDecisions = void 0;
+const typedEmit_js_1 = require("../../../recorders/core/typedEmit.js");
+/**
+ * Append decision rows to the run's ledger and emit one event per row.
+ *
+ * No-op on an empty list, so an agent with no middleware never writes the
+ * key at all and its commit log is the one it always had.
+ */
+function recordDecisions(scope, rows) {
+    if (rows.length === 0)
+        return;
+    const prev = scope.middlewareDecisions ?? [];
+    // Spread into a plain local array first: a TypedScope array read is a live
+    // deep-proxy view, and both the commit and the event payloads below must be
+    // detached plain data (RFC-001 'clone' capture under deferred delivery).
+    scope.middlewareDecisions = [...prev, ...rows];
+    for (const row of rows) {
+        (0, typedEmit_js_1.typedEmit)(scope, 'agentfootprint.middleware.decision', {
+            middleware: row.middleware,
+            at: row.at,
+            ...(row.phase !== undefined && { phase: row.phase }),
+            ...(row.toolName !== undefined && { toolName: row.toolName }),
+            ...(row.toolCallId !== undefined && { toolCallId: row.toolCallId }),
+            iteration: row.iteration,
+            outcome: row.outcome,
+            changed: row.changed,
+            ...(row.why !== undefined && { why: row.why }),
+        });
+    }
+}
+exports.recordDecisions = recordDecisions;
+//# sourceMappingURL=ledger.js.map

package/dist/core/agent/middleware/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../../../src/core/agent/middleware/ledger.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;AAEH,uEAAiE;AASjE;;;;;GAKG;AACH,SAAgB,eAAe,CAAC,KAAkB,EAAE,IAAmC;IACrF,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAC9B,MAAM,IAAI,GAAI,KAAK,CAAC,mBAAiE,IAAI,EAAE,CAAC;IAC5F,2EAA2E;IAC3E,4EAA4E;IAC5E,yEAAyE;IACzE,KAAK,CAAC,mBAAmB,GAAG,CAAC,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC,CAAC;IAC/C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAA,wBAAS,EAAC,KAAK,EAAE,oCAAoC,EAAE;YACrD,UAAU,EAAE,GAAG,CAAC,UAAU;YAC1B,EAAE,EAAE,GAAG,CAAC,EAAE;YACV,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC;YACpD,GAAG,CAAC,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC;YAC7D,GAAG,CAAC,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC;YACnE,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC;SAC/C,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AApBD,0CAoBC"}

package/dist/core/agent/middleware/outcomes.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * middleware/outcomes — PUBLIC. The three verbs a middleware speaks.
+ *
+ * Pattern: Smart constructors over a closed union.
+ * Role:    core/ layer. `allow` / `deny` / `ask` are the entire vocabulary
+ *          of both chains, which is why they are short: they are written
+ *          inside every middleware body, several times, and a governance
+ *          rule reads better as `deny('writes to prod need a ticket')` than
+ *          as a namespaced ceremony.
+ * Emits:   N/A.
+ *
+ * The `allow` overloads carry a rule: you can pass the value through
+ * untouched with no explanation, but you cannot CHANGE it without one. A
+ * transform is the only thing here that makes the trace and the wire
+ * disagree, so it is the only thing required to say why.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ask = exports.deny = exports.allow = void 0;
+function allow(value, why) {
+    if (value === undefined)
+        return { kind: 'allow' };
+    if (typeof why !== 'string' || why.length === 0) {
+        throw new Error('allow(value, why): a transform must say why. Pass a short reason — it is what the ' +
+            'ledger shows next to the before/after pair. To pass the value through unchanged, ' +
+            'call allow() with no arguments.');
+    }
+    return { kind: 'allow', value, why };
+}
+exports.allow = allow;
+/**
+ * Refuse the call.
+ *
+ * For a tool the reason reaches the model verbatim, as the tool's result,
+ * and the loop continues — the agent gets to adapt. For a message it
+ * surfaces as a `MessageDeniedError`.
+ */
+function deny(reason) {
+    if (typeof reason !== 'string' || reason.length === 0) {
+        throw new Error('deny(reason): a refusal must carry a reason. For a tool it is the text the model ' +
+            'reads and adapts to, so write it for the model, not for a log line.');
+    }
+    return { kind: 'deny', reason };
+}
+exports.deny = deny;
+/**
+ * Suspend the run and put the question to a person. Tool dispatch only —
+ * `MessageOutcome` has no `ask` arm, so this cannot be returned from a
+ * message middleware.
+ *
+ * The answer is a decision, not a result: approve and the chain continues
+ * and the REAL tool runs; decline and it becomes a denial the model reads.
+ * A middleware never gets to write the answer itself.
+ */
+function ask(payload) {
+    if (payload === null ||
+        typeof payload !== 'object' ||
+        typeof payload.question !== 'string' ||
+        payload.question.length === 0) {
+        throw new Error('ask(payload): expected { question, detail? } with a non-empty question. The question ' +
+            'is what a person is shown when the run pauses.');
+    }
+    return { kind: 'ask', payload };
+}
+exports.ask = ask;
+//# sourceMappingURL=outcomes.js.map

package/dist/core/agent/middleware/outcomes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outcomes.js","sourceRoot":"","sources":["../../../../src/core/agent/middleware/outcomes.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAcH,SAAgB,KAAK,CAAI,KAAS,EAAE,GAAY;IAC9C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAClD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CACb,oFAAoF;YAClF,mFAAmF;YACnF,iCAAiC,CACpC,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AACvC,CAAC;AAVD,sBAUC;AAED;;;;;;GAMG;AACH,SAAgB,IAAI,CAAC,MAAc;IACjC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CACb,mFAAmF;YACjF,qEAAqE,CACxE,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAClC,CAAC;AARD,oBAQC;AAED;;;;;;;;GAQG;AACH,SAAgB,GAAG,CAAC,OAAmB;IACrC,IACE,OAAO,KAAK,IAAI;QAChB,OAAO,OAAO,KAAK,QAAQ;QAC3B,OAAO,OAAO,CAAC,QAAQ,KAAK,QAAQ;QACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAC7B,CAAC;QACD,MAAM,IAAI,KAAK,CACb,uFAAuF;YACrF,gDAAgD,CACnD,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAClC,CAAC;AAbD,kBAaC"}

package/dist/core/agent/middleware/runChain.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * middleware/runChain — INTERNAL. The one place a chain is walked.
+ *
+ * Pattern: Chain of Responsibility driver.
+ * Role:    core/ layer. Both stages (tool dispatch, message boundary) and
+ *          the MCP server call in here, so the ordering law, the
+ *          throw-is-a-denial law and the ledger row shape are written once
+ *          and cannot drift between the three callers.
+ * Emits:   N/A — it RETURNS rows; the caller commits and emits them, so a
+ *          middleware still never touches scope.
+ *
+ * ## The rules this file implements
+ *
+ * **Order is declaration order.** The chain is walked front to back, and
+ * each link is handed the previous link's output — so a scrubber placed
+ * first is a scrubber every later rule sees the effect of.
+ *
+ * **The first non-allow answer wins.** A deny or an ask stops the walk;
+ * the links behind it do not run. There is no "second opinion" pass,
+ * because a refusal that a later middleware could overturn is not a
+ * refusal.
+ *
+ * **A middleware that throws is a denial, never a pass.** The thrown
+ * message becomes the reason. This is the same deny-by-default the
+ * permission gate has always applied to a checker that throws: a
+ * governance layer whose failure mode is "allow" is not a governance
+ * layer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMessageChain = exports.runToolChain = void 0;
+/** Walk the tool chain. Never throws — a throwing link becomes a denial. */
+async function runToolChain(chain, input) {
+    const decisions = [];
+    const askPolicy = input.askPolicy ?? 'pause';
+    let args = input.args;
+    for (let i = input.startIndex ?? 0; i < chain.length; i++) {
+        const mw = chain[i];
+        const row = (extra) => ({
+            middleware: mw.name,
+            at: 'tool',
+            toolName: input.toolName,
+            toolCallId: input.toolCallId,
+            iteration: input.iteration,
+            outcome: 'allow',
+            changed: false,
+            ...extra,
+        });
+        let outcome;
+        try {
+            outcome = await mw.onToolCall({
+                toolName: input.toolName,
+                toolCallId: input.toolCallId,
+                iteration: input.iteration,
+                args,
+                history: input.history,
+                ...(input.identity && { identity: input.identity }),
+                ...(input.signal && { signal: input.signal }),
+            });
+        }
+        catch (err) {
+            const reason = `middleware '${mw.name}' threw: ${err instanceof Error ? err.message : String(err)}`;
+            decisions.push(row({ outcome: 'deny', why: reason }));
+            return { kind: 'deny', reason, middleware: mw.name, args, decisions };
+        }
+        if (outcome.kind === 'deny') {
+            decisions.push(row({ outcome: 'deny', why: outcome.reason }));
+            return { kind: 'deny', reason: outcome.reason, middleware: mw.name, args, decisions };
+        }
+        if (outcome.kind === 'ask') {
+            if (askPolicy === 'refuse') {
+                const reason = `middleware '${mw.name}' asked a person to decide, and there is no pause here to ` +
+                    `carry that ask: ${outcome.payload.question}`;
+                decisions.push(row({ outcome: 'deny', why: reason }));
+                return { kind: 'deny', reason, middleware: mw.name, args, decisions };
+            }
+            decisions.push(row({ outcome: 'ask', why: outcome.payload.question }));
+            return {
+                kind: 'ask',
+                payload: outcome.payload,
+                middleware: mw.name,
+                index: i,
+                args,
+                decisions,
+            };
+        }
+        if (outcome.value !== undefined) {
+            const before = args;
+            args = outcome.value;
+            decisions.push(row({ changed: true, ...(outcome.why && { why: outcome.why }), before, after: args }));
+        }
+        else {
+            decisions.push(row({}));
+        }
+    }
+    return { kind: 'allow', args, decisions };
+}
+exports.runToolChain = runToolChain;
+/** Walk the message chain. Never throws — a throwing link becomes a denial. */
+async function runMessageChain(chain, input) {
+    const decisions = [];
+    let content = input.content;
+    for (const mw of chain) {
+        const row = (extra) => ({
+            middleware: mw.name,
+            at: 'message',
+            phase: input.phase,
+            iteration: input.iteration,
+            outcome: 'allow',
+            changed: false,
+            ...extra,
+        });
+        let outcome;
+        try {
+            outcome = await mw.onMessage({
+                phase: input.phase,
+                content,
+                history: input.history,
+                ...(input.identity && { identity: input.identity }),
+                ...(input.signal && { signal: input.signal }),
+            });
+        }
+        catch (err) {
+            const reason = `middleware '${mw.name}' threw: ${err instanceof Error ? err.message : String(err)}`;
+            decisions.push(row({ outcome: 'deny', why: reason }));
+            return { kind: 'deny', reason, middleware: mw.name, content, decisions };
+        }
+        if (outcome.kind === 'deny') {
+            decisions.push(row({ outcome: 'deny', why: outcome.reason }));
+            return { kind: 'deny', reason: outcome.reason, middleware: mw.name, content, decisions };
+        }
+        if (outcome.value !== undefined) {
+            const before = content;
+            content = outcome.value;
+            decisions.push(row({ changed: true, ...(outcome.why && { why: outcome.why }), before, after: content }));
+        }
+        else {
+            decisions.push(row({}));
+        }
+    }
+    return { kind: 'allow', content, decisions };
+}
+exports.runMessageChain = runMessageChain;
+//# sourceMappingURL=runChain.js.map

package/dist/core/agent/middleware/runChain.js.map

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

package/dist/core/agent/middleware/types.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * middleware/types — PUBLIC. The shape of a governance chain.
+ *
+ * Pattern: Chain of Responsibility (GoF), with the one dangerous answer
+ *          removed at the type level.
+ * Role:    core/ layer. Two chains, one vocabulary:
+ *
+ *            `toolMiddleware`     wraps every tool dispatch
+ *            `messageMiddleware`  wraps the message boundary — the input
+ *                                 before the model sees it, the output
+ *                                 before the caller receives it
+ *
+ * Emits:   N/A. A middleware is a pure decision. It never touches scope,
+ *          never emits and never writes — the stage does all of that, so
+ *          "record everything that happened" lives in ONE place rather
+ *          than being re-implemented per middleware.
+ *
+ * ## The law that shapes these types
+ *
+ * **A middleware cannot answer for the tool.** The outcome union has three
+ * arms — allow, deny, ask — and no `result` arm. There is no spelling of
+ * "here is what the tool would have returned". Whatever the chain decides,
+ * the answer the model finally reads is the real tool's output or a
+ * refusal. That is not a convention a reviewer has to enforce; it is the
+ * absence of a field.
+ *
+ * **A transform declares itself.** `allow(value, why)` requires a reason
+ * whenever it changes something, and the stage commits BOTH the original
+ * and the transformed value into the run's ledger. A prompt scrubbed by a
+ * middleware that hid its own scrubbing would poison every slice taken
+ * afterwards: the trace would show text nobody ever sent.
+ *
+ * **`ask` exists only where a pause exists.** `ToolOutcome` has it because
+ * tool dispatch runs inside a footprintjs pausable stage — the same door
+ * `checkIn` and `askHuman` already go through. `MessageOutcome` does not,
+ * because the message boundary is a plain stage, and inventing a second
+ * pause to give it one would be a worse answer than not offering it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/core/agent/middleware/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/core/agent/middleware/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG"}

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

@@ -14,6 +14,16 @@
  *
  * Pure function — no closure over Agent class state. Imported and
  * passed directly to `flowChart(...)` in buildAgentChart.
+ *
+ * NOT the seam for `messageMiddleware`'s `'output'` half, deliberately.
+ * This stage runs inside the Final BRANCH subflow, whose state does not
+ * merge back into the run (a branch mount hands its outputMapper the
+ * branch's RESULT, not its scope). Rows filed here would land in an
+ * isolated commit log and never reach `snapshot.sharedState`, splitting
+ * one ledger across two places. The chain runs one stage earlier instead
+ * — in the Route decider, in the main chart — and rewrites
+ * `llmLatestContent`, which is the value this stage copies. See
+ * `stages/route.ts`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.prepareFinalStage = void 0;

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

@@ -1 +1 @@
-{"version":3,"file":"prepareFinal.js","sourceRoot":"","sources":["../../../../src/core/agent/stages/prepareFinal.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAGH,uEAAiE;AAG1D,MAAM,iBAAiB,GAAG,CAAC,KAA6B,EAAQ,EAAE;IACvE,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;IAClC,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,gBAAgB,CAAC;IAC5C,gEAAgE;IAChE,mEAAmE;IACnE,oEAAoE;IACpE,iEAAiE;IACjE,+DAA+D;IAC/D,MAAM,cAAc,GAAG,KAAK,CAAC,cAAc,CAAC;IAC5C,MAAM,WAAW,GAAG,cAAc,KAAK,SAAS,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC;IAC9E,6DAA6D;IAC7D,wCAAwC;IACxC,KAAK,CAAC,WAAW,GAAG;QAClB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,WAAW,EAAE;QAC5C;YACE,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,KAAK,CAAC,YAAY;YAC3B,GAAG,CAAC,WAAW,IAAI,EAAE,cAAc,EAAE,CAAC;SACvC;KACF,CAAC;IAEF,IAAA,wBAAS,EAAC,KAAK,EAAE,oCAAoC,EAAE;QACrD,SAAS,EAAE,CAAC;QACZ,SAAS,EAAE,SAAS;QACpB,aAAa,EAAE,CAAC;KACjB,CAAC,CAAC;IACH,IAAA,wBAAS,EAAC,KAAK,EAAE,+BAA+B,EAAE;QAChD,SAAS,EAAE,CAAC;QACZ,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;QACxC,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;QAC1C,cAAc,EAAE,SAAS;QACzB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,WAAW;KAC3C,CAAC,CAAC;AACL,CAAC,CAAC;AAlCW,QAAA,iBAAiB,qBAkC5B"}
+{"version":3,"file":"prepareFinal.js","sourceRoot":"","sources":["../../../../src/core/agent/stages/prepareFinal.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAGH,uEAAiE;AAG1D,MAAM,iBAAiB,GAAG,CAAC,KAA6B,EAAQ,EAAE;IACvE,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;IAClC,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,gBAAgB,CAAC;IAC5C,gEAAgE;IAChE,mEAAmE;IACnE,oEAAoE;IACpE,iEAAiE;IACjE,+DAA+D;IAC/D,MAAM,cAAc,GAAG,KAAK,CAAC,cAAc,CAAC;IAC5C,MAAM,WAAW,GAAG,cAAc,KAAK,SAAS,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC;IAC9E,6DAA6D;IAC7D,wCAAwC;IACxC,KAAK,CAAC,WAAW,GAAG;QAClB,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,WAAW,EAAE;QAC5C;YACE,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,KAAK,CAAC,YAAY;YAC3B,GAAG,CAAC,WAAW,IAAI,EAAE,cAAc,EAAE,CAAC;SACvC;KACF,CAAC;IAEF,IAAA,wBAAS,EAAC,KAAK,EAAE,oCAAoC,EAAE;QACrD,SAAS,EAAE,CAAC;QACZ,SAAS,EAAE,SAAS;QACpB,aAAa,EAAE,CAAC;KACjB,CAAC,CAAC;IACH,IAAA,wBAAS,EAAC,KAAK,EAAE,+BAA+B,EAAE;QAChD,SAAS,EAAE,CAAC;QACZ,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,gBAAgB,EAAE,KAAK,CAAC,gBAAgB;QACxC,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;QAC1C,cAAc,EAAE,SAAS;QACzB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,WAAW;KAC3C,CAAC,CAAC;AACL,CAAC,CAAC;AAlCW,QAAA,iBAAiB,qBAkC5B"}

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

@@ -14,8 +14,10 @@
  * passed directly to `addDeciderFunction(...)` in buildAgentChart.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.routeDeciderStage = void 0;
+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 toolCalls = scope.llmLatestToolCalls;
     const iteration = scope.iteration;
@@ -33,4 +35,63 @@ const routeDeciderStage = (scope) => {
     return chosen;
 };
 exports.routeDeciderStage = routeDeciderStage;
+/**
+ * Build the Route decider, optionally carrying the `'output'` half of the
+ * message chain.
+ *
+ * ## Why the chain runs HERE and not in PrepareFinal
+ *
+ * PrepareFinal is where `finalContent` is set, which makes it look like the
+ * output seam. It is not, for one structural reason: it lives inside the Final
+ * BRANCH subflow, and a branch mount hands its `outputMapper` the branch's
+ * RESULT, not its scope — so nothing that stage writes reaches the run's
+ * shared state. Ledger rows filed there would sit in an isolated commit log,
+ * and one ledger would be split across two places a reader has to know about.
+ *
+ * The decider is one stage earlier, in the main chart, and it is the first
+ * moment the run KNOWS this turn is the final answer. Its writes commit before
+ * the branch resolves (footprintjs commits a decider stage ahead of matching
+ * the branch), and the value it rewrites — `llmLatestContent` — is exactly
+ * what PrepareFinal copies into `finalContent`. So the caller, the committed
+ * record, the `newMessages` the memory writes persist, and the ledger row all
+ * carry the same string. One seam, one answer.
+ *
+ * The `'tool-calls'` path is untouched: a turn that is still calling tools has
+ * not produced an answer, and running an output rule over a half-finished turn
+ * would be running it over something that is not the output.
+ *
+ * Empty chain → the exact synchronous decider this file has always exported.
+ */
+function buildRouteDeciderStage(messageMiddleware) {
+    const chain = messageMiddleware ?? [];
+    if (chain.length === 0)
+        return exports.routeDeciderStage;
+    return async (scope) => {
+        const chosen = (0, exports.routeDeciderStage)(scope);
+        if (chosen !== 'final')
+            return chosen;
+        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') {
+            // The answer is NOT released. It stays in the commit log where the run
+            // put it, under whatever redaction the run configured, and the boundary
+            // raises instead of returning — handing the caller a refusal in place of
+            // an answer is the one substitution they must never make unknowingly.
+            scope.messageDeniedReason = verdict.reason;
+            scope.messageDeniedPhase = 'output';
+            scope.messageDeniedBy = verdict.middleware;
+        }
+        // Committed either way: on a refusal this is what was withheld, and the
+        // ledger row beside it says who withheld it and why.
+        scope.llmLatestContent = verdict.content;
+        return chosen;
+    };
+}
+exports.buildRouteDeciderStage = buildRouteDeciderStage;
 //# 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;AAK1D,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"}
+{"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"}