agentfootprint 7.17.0 → 7.19.0

package/dist/esm/core/agent/middleware/types.d.ts

@@ -0,0 +1,191 @@
+/**
+ * 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.
+ */
+import type { LLMMessage } from '../../../adapters/types.js';
+import type { MemoryIdentity } from '../../../memory/identity/types.js';
+/**
+ * Let the call through — optionally with a replacement for what the chain
+ * carries forward.
+ *
+ * `allow()` passes the value along untouched. `allow(value, why)` replaces
+ * it and says why; the `why` is not decoration, it is the row the ledger
+ * shows a person asking "who changed this, and what did it look like
+ * before?".
+ */
+export interface AllowOutcome<T> {
+    readonly kind: 'allow';
+    /** The replacement value. Absent = pass through unchanged. */
+    readonly value?: T;
+    /** Why the value changed. Present whenever `value` is. */
+    readonly why?: string;
+}
+/**
+ * Refuse the call. For a tool, `reason` reaches the model verbatim as the
+ * tool result and the run continues — a denial is data the agent can adapt
+ * to, not a crash. For a message, `reason` surfaces as a
+ * `MessageDeniedError` at the API boundary.
+ */
+export interface DenyOutcome {
+    readonly kind: 'deny';
+    readonly reason: string;
+}
+/** Suspend the run and put the question to a person. Tool dispatch only. */
+export interface AskOutcome {
+    readonly kind: 'ask';
+    readonly payload: AskPayload;
+}
+/** What a person is being asked. Carried verbatim to the checkpoint. */
+export interface AskPayload {
+    /** The question, in your own words. Shown to whoever answers. */
+    readonly question: string;
+    /** Anything else the answering UI should render. Never interpreted here. */
+    readonly detail?: unknown;
+}
+/**
+ * Everything a tool middleware may answer. Closed, and every arm has a
+ * home in this codebase: allow rides the normal dispatch, deny rides the
+ * synthetic tool result every other gate already uses, ask rides the
+ * pausable-stage checkpoint that `checkIn` rides.
+ */
+export type ToolOutcome = AllowOutcome<Readonly<Record<string, unknown>>> | DenyOutcome | AskOutcome;
+/** Everything a message middleware may answer. No `ask` — see the header. */
+export type MessageOutcome = AllowOutcome<string> | DenyOutcome;
+/** The call a tool middleware is deciding about. */
+export interface ToolMiddlewareContext {
+    readonly toolName: string;
+    /** Matches `stream.tool_start.toolCallId` for this dispatch. */
+    readonly toolCallId: string;
+    /** ReAct iteration this call belongs to. */
+    readonly iteration: number;
+    /**
+     * The args as THIS middleware sees them — every earlier transform in the
+     * chain already applied. The first middleware sees what the model asked
+     * for; the last sees what the tool is about to receive.
+     */
+    readonly args: Readonly<Record<string, unknown>>;
+    /** Conversation so far, including the assistant turn that made this call. */
+    readonly history: readonly LLMMessage[];
+    /** Multi-tenant run identity, when the run carried one. */
+    readonly identity?: MemoryIdentity;
+    /** Abort signal from `run({ env: { signal } })`. */
+    readonly signal?: AbortSignal;
+}
+/** The message a message middleware is deciding about. */
+export interface MessageMiddlewareContext {
+    /**
+     * `'input'` runs at the very top of the run, BEFORE the user's message is
+     * committed — so the window strategies, the injections, the slots, the
+     * request bytes and every later slice all see the transformed text and
+     * agree with each other. `'output'` runs where the final answer is
+     * captured, so the record and the caller receive the same string.
+     */
+    readonly phase: 'input' | 'output';
+    /** The content as THIS middleware sees it — earlier transforms applied. */
+    readonly content: string;
+    /** Conversation so far. Empty at `'input'`. */
+    readonly history: readonly LLMMessage[];
+    readonly identity?: MemoryIdentity;
+    readonly signal?: AbortSignal;
+}
+/**
+ * One link in the tool-dispatch chain.
+ *
+ * @example
+ * ```ts
+ * const noProdWrites: ToolMiddleware = {
+ *   name: 'no-prod-writes',
+ *   onToolCall: (call) =>
+ *     call.args.env === 'prod' ? deny('writes to prod need a change ticket') : allow(),
+ * };
+ * ```
+ */
+export interface ToolMiddleware {
+    /** Identifies this middleware in every ledger row and event it produces. */
+    readonly name: string;
+    onToolCall(call: ToolMiddlewareContext): ToolOutcome | Promise<ToolOutcome>;
+}
+/**
+ * One link in the message chain. Runs at both phases unless it decides
+ * otherwise by reading `msg.phase`.
+ *
+ * @example
+ * ```ts
+ * const scrubSSNs: MessageMiddleware = {
+ *   name: 'scrub-ssns',
+ *   onMessage: (msg) => {
+ *     const clean = msg.content.replace(/\b\d{3}-\d{2}-\d{4}\b/g, '[ssn]');
+ *     return clean === msg.content ? allow() : allow(clean, 'masked a US SSN');
+ *   },
+ * };
+ * ```
+ */
+export interface MessageMiddleware {
+    readonly name: string;
+    onMessage(msg: MessageMiddlewareContext): MessageOutcome | Promise<MessageOutcome>;
+}
+/**
+ * One row per middleware decision, committed to `scope.middlewareDecisions`.
+ *
+ * Every decision files a row, including the pass-throughs. A chain that
+ * only recorded its refusals would leave you unable to tell "the middleware
+ * looked and was fine with it" apart from "the middleware never ran" — and
+ * those are different facts about a run.
+ */
+export interface MiddlewareDecision {
+    /** The middleware's `name`. */
+    readonly middleware: string;
+    /** Which chain this row came from. */
+    readonly at: 'tool' | 'message';
+    /** Message chain only. */
+    readonly phase?: 'input' | 'output';
+    /** Tool chain only. */
+    readonly toolName?: string;
+    /** Tool chain only. */
+    readonly toolCallId?: string;
+    /** ReAct iteration. `0` for the `'input'` phase, which runs before iter 1. */
+    readonly iteration: number;
+    readonly outcome: 'allow' | 'deny' | 'ask';
+    /** True when this row changed the value the chain carries forward. */
+    readonly changed: boolean;
+    /** The transform's `why`, the denial's `reason`, or the ask's `question`. */
+    readonly why?: string;
+    /** The value before this middleware. Present only when `changed`. */
+    readonly before?: unknown;
+    /** The value after this middleware. Present only when `changed`. */
+    readonly after?: unknown;
+}

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

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/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/esm/core/agent/stages/prepareFinal.d.ts

@@ -13,6 +13,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`.
  */
 import type { TypedScope } from 'footprintjs';
 import type { AgentState } from '../types.js';

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

@@ -13,6 +13,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`.
  */
 import { typedEmit } from '../../../recorders/core/typedEmit.js';
 export const prepareFinalStage = (scope) => {

package/dist/esm/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,OAAO,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAGjE,MAAM,CAAC,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,SAAS,CAAC,KAAK,EAAE,oCAAoC,EAAE;QACrD,SAAS,EAAE,CAAC;QACZ,SAAS,EAAE,SAAS;QACpB,aAAa,EAAE,CAAC;KACjB,CAAC,CAAC;IACH,SAAS,CAAC,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"}
+{"version":3,"file":"prepareFinal.js","sourceRoot":"","sources":["../../../../../src/core/agent/stages/prepareFinal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAGjE,MAAM,CAAC,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,SAAS,CAAC,KAAK,EAAE,oCAAoC,EAAE;QACrD,SAAS,EAAE,CAAC;QACZ,SAAS,EAAE,SAAS;QACpB,aAAa,EAAE,CAAC;KACjB,CAAC,CAAC;IACH,SAAS,CAAC,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"}

package/dist/esm/core/agent/stages/route.d.ts

@@ -14,5 +14,34 @@
  */
 import type { TypedScope } from 'footprintjs';
 import type { AgentState } from '../types.js';
+import type { MessageMiddleware } from '../middleware/types.js';
 export type RouteBranch = 'tool-calls' | 'final';
 export declare const routeDeciderStage: (scope: TypedScope<AgentState>) => RouteBranch;
+/**
+ * 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.
+ */
+export declare function buildRouteDeciderStage(messageMiddleware?: readonly MessageMiddleware[]): (scope: TypedScope<AgentState>) => RouteBranch | Promise<RouteBranch>;

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

@@ -13,6 +13,8 @@
  * passed directly to `addDeciderFunction(...)` in buildAgentChart.
  */
 import { typedEmit } from '../../../recorders/core/typedEmit.js';
+import { runMessageChain } from '../middleware/runChain.js';
+import { recordDecisions } from '../middleware/ledger.js';
 export const routeDeciderStage = (scope) => {
     const toolCalls = scope.llmLatestToolCalls;
     const iteration = scope.iteration;
@@ -29,4 +31,62 @@ export const routeDeciderStage = (scope) => {
     });
     return chosen;
 };
+/**
+ * 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.
+ */
+export function buildRouteDeciderStage(messageMiddleware) {
+    const chain = messageMiddleware ?? [];
+    if (chain.length === 0)
+        return routeDeciderStage;
+    return async (scope) => {
+        const chosen = routeDeciderStage(scope);
+        if (chosen !== 'final')
+            return chosen;
+        const verdict = await runMessageChain(chain, {
+            phase: 'output',
+            content: scope.llmLatestContent,
+            history: [...scope.history],
+            iteration: scope.iteration,
+            ...(scope.runIdentity && { identity: scope.runIdentity }),
+        });
+        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;
+    };
+}
 //# sourceMappingURL=route.js.map

package/dist/esm/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,OAAO,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAKjE,MAAM,CAAC,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,SAAS,CAAC,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"}
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../../../../../src/core/agent/stages/route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,sCAAsC,CAAC;AAIjE,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAI1D,MAAM,CAAC,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,SAAS,CAAC,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;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,sBAAsB,CACpC,iBAAgD;IAEhD,MAAM,KAAK,GAAG,iBAAiB,IAAI,EAAE,CAAC;IACtC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,iBAAiB,CAAC;IACjD,OAAO,KAAK,EAAE,KAAK,EAAE,EAAE;QACrB,MAAM,MAAM,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,MAAM,KAAK,OAAO;YAAE,OAAO,MAAM,CAAC;QAEtC,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,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,eAAe,CAAC,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"}

package/dist/esm/core/agent/stages/seed.d.ts

@@ -19,6 +19,7 @@
 import type { TypedScope } from 'footprintjs';
 import type { LLMMessage, LLMToolSchema } from '../../../adapters/types.js';
 import type { AgentInput, AgentState, RunConfig } from '../types.js';
+import type { MessageMiddleware } from '../middleware/types.js';
 export interface SeedStageDeps {
     /** Resolved `clampIterations(opts.maxIterations ?? 10)`. Frozen at
      *  chart-build time. */
@@ -53,10 +54,24 @@ export interface SeedStageDeps {
      * written, so the commit log is byte-identical to earlier releases.
      */
     readonly resolveRunConfig?: (input: AgentInput) => RunConfig | undefined;
+    /**
+     * The message chain (`.messageMiddleware(...)`), walked here at the
+     * `'input'` phase — BEFORE `userMessage` and `history` are written.
+     *
+     * This is the only placement that keeps the run honest. Everything
+     * downstream reads `scope.history`: the window strategies, the injection
+     * engine, all three slots, the request that goes on the wire, and every
+     * slice taken afterwards. Transform later than this and those components
+     * disagree about what the user actually said — the trace would show one
+     * message and the model would have answered another.
+     *
+     * Empty / undefined → seed stays the synchronous stage it always was.
+     */
+    readonly messageMiddleware?: readonly MessageMiddleware[];
 }
 /**
  * Build the seed stage function for an Agent instance. Captures both
  * the chart-build-time constants and the per-run mutable accessors
  * via the deps object.
  */
-export declare function buildSeedStage(deps: SeedStageDeps): (scope: TypedScope<AgentState>) => void;
+export declare function buildSeedStage(deps: SeedStageDeps): (scope: TypedScope<AgentState>) => void | Promise<void>;

package/dist/esm/core/agent/stages/seed.js

@@ -17,99 +17,144 @@
  * features need.
  */
 import { typedEmit } from '../../../recorders/core/typedEmit.js';
+import { runMessageChain } from '../middleware/runChain.js';
+import { recordDecisions } from '../middleware/ledger.js';
 /**
  * Build the seed stage function for an Agent instance. Captures both
  * the chart-build-time constants and the per-run mutable accessors
  * via the deps object.
  */
 export function buildSeedStage(deps) {
-    return (scope) => {
-        const args = scope.$getArgs();
-        scope.userMessage = args.message;
-        // If `resumeOnError(...)` set the side channel, restore the
-        // checkpointed conversation history. The next iteration sees
-        // the prior messages and continues from the failure point.
-        // Always clear the field after reading so subsequent runs
-        // (without resumeOnError) start fresh.
-        const resumeHistory = deps.consumePendingResumeHistory();
-        if (resumeHistory && resumeHistory.length > 0) {
-            scope.history = [...resumeHistory];
-        }
-        else {
-            scope.history = [{ role: 'user', content: args.message }];
-        }
-        // Default identity uses the runId so multi-run isolation works
-        // without consumer changes; explicit identity (multi-tenant)
-        // overrides via `agent.run({ identity })`.
-        scope.runIdentity = args.identity ?? {
-            conversationId: deps.getCurrentRunId() ?? 'default',
+    const chain = deps.messageMiddleware ?? [];
+    // No chain → the same synchronous function this stage has always been.
+    // Not an optimisation: an agent without middleware must produce the same
+    // stage shape, the same committed keys and the same request bytes as before.
+    if (chain.length === 0) {
+        return (scope) => {
+            seedFrom(scope, scope.$getArgs().message, deps);
         };
-        scope.newMessages = [];
-        scope.turnNumber = 1;
-        // Permissive default — explicit cap will land when PricingTable
-        // gets a context-window field. Memory pickByBudget treats anything
-        // ≥ minimumTokens as "fits", so this just enables the budget path.
-        scope.contextTokensRemaining = 32_000;
-        scope.iteration = 1;
-        scope.maxIterations = deps.maxIterations;
-        scope.finalContent = '';
-        scope.totalInputTokens = 0;
-        scope.totalOutputTokens = 0;
-        scope.turnStartMs = Date.now();
-        scope.systemPromptInjections = [];
-        scope.messagesInjections = [];
-        scope.toolsInjections = [];
-        scope.llmLatestContent = '';
-        scope.llmLatestToolCalls = [];
-        // v2.14 — initialize thinking blocks. Empty array means "no thinking
-        // this iteration"; the NormalizeThinking sub-subflow overwrites
-        // this AFTER each CallLLM when a ThinkingHandler is configured.
-        scope.thinkingBlocks = [];
-        scope.pausedToolCallId = '';
-        scope.pausedToolName = '';
-        scope.pausedToolStartMs = 0;
-        scope.cumTokensInput = 0;
-        scope.cumTokensOutput = 0;
-        scope.cumEstimatedUsd = 0;
-        scope.costBudgetHit = false;
-        scope.activeInjections = [];
-        scope.activatedInjectionIds = [];
-        scope.dynamicToolSchemas = deps.toolSchemas;
-        // Cache layer state (v2.6) — initialized to inert defaults.
-        // CacheDecision subflow populates `cacheMarkers` per iteration;
-        // UpdateSkillHistory + CacheGate consume `cachingDisabled`,
-        // `recentHitRate`, `skillHistory`. Empty defaults mean the
-        // CacheGate falls through to 'apply-markers' on iter 1 (no
-        // history yet → no churn detected; recentHitRate undefined →
-        // hit-rate floor doesn't fire).
-        scope.cacheMarkers = [];
-        scope.cachingDisabled = deps.cachingDisabled;
-        scope.recentHitRate = undefined;
-        scope.skillHistory = [];
-        // Skill-graph cursor — reset per turn so each new user message re-enters the
-        // graph through the entry router (cold start). The Injection Engine advances
-        // it each iteration; undefined for agents without a skillGraph().
-        scope.currentSkillId = undefined;
-        // `.configure()` — resolved ONCE here (seed runs exactly once per run)
-        // and written to scope, which means the run's commit log records the
-        // model and instructions the run actually used. A run that changed its
-        // own model without committing that fact would produce a trace that
-        // reads as if the built-in default answered.
-        //
-        // Only what the resolver actually returned is written: an agent with no
-        // `.configure()`, or one whose resolver returned `{}`, commits nothing
-        // extra and behaves exactly as before.
-        if (deps.resolveRunConfig) {
-            const resolved = deps.resolveRunConfig(args);
-            if (resolved?.model !== undefined)
-                scope.resolvedModel = resolved.model;
-            if (resolved?.instructions !== undefined)
-                scope.resolvedInstructions = resolved.instructions;
-        }
-        typedEmit(scope, 'agentfootprint.agent.turn_start', {
-            turnIndex: 0,
-            userPrompt: args.message,
+    }
+    return async (scope) => {
+        const args = scope.$getArgs();
+        const verdict = await runMessageChain(chain, {
+            phase: 'input',
+            content: args.message,
+            history: [],
+            // The input boundary runs before iteration 1 exists.
+            iteration: 0,
+            ...(args.identity && { identity: args.identity }),
         });
+        recordDecisions(scope, verdict.decisions);
+        if (verdict.kind === 'deny') {
+            // Seed the run anyway, with the content as it stood when it was
+            // refused, then stop. Committing it costs nothing (a refusal is a fact
+            // about a run, and hiding what was refused would make the record
+            // useless), and a fully-seeded state means `resumeOnError` and every
+            // recorder see the shape they expect rather than a half-built one.
+            seedFrom(scope, verdict.content, deps);
+            scope.messageDeniedReason = verdict.reason;
+            scope.messageDeniedPhase = 'input';
+            scope.messageDeniedBy = verdict.middleware;
+            // Stops the chart here: no injections, no slots, no LLM call. The
+            // boundary turns these flags into a MessageDeniedError.
+            scope.$break(`message denied at input: ${verdict.reason}`);
+            return;
+        }
+        seedFrom(scope, verdict.content, deps);
+    };
+}
+/**
+ * Initialise every mutable field of `AgentState` from `message` + the run
+ * args. Split out so the message the run proceeds with can come either
+ * straight from the caller or from the `'input'` middleware chain — one
+ * initialiser, so the two paths cannot drift.
+ */
+function seedFrom(scope, message, deps) {
+    const args = scope.$getArgs();
+    scope.userMessage = message;
+    // If `resumeOnError(...)` set the side channel, restore the
+    // checkpointed conversation history. The next iteration sees
+    // the prior messages and continues from the failure point.
+    // Always clear the field after reading so subsequent runs
+    // (without resumeOnError) start fresh.
+    const resumeHistory = deps.consumePendingResumeHistory();
+    if (resumeHistory && resumeHistory.length > 0) {
+        scope.history = [...resumeHistory];
+    }
+    else {
+        scope.history = [{ role: 'user', content: message }];
+    }
+    // Default identity uses the runId so multi-run isolation works
+    // without consumer changes; explicit identity (multi-tenant)
+    // overrides via `agent.run({ identity })`.
+    scope.runIdentity = args.identity ?? {
+        conversationId: deps.getCurrentRunId() ?? 'default',
     };
+    scope.newMessages = [];
+    scope.turnNumber = 1;
+    // Permissive default — explicit cap will land when PricingTable
+    // gets a context-window field. Memory pickByBudget treats anything
+    // ≥ minimumTokens as "fits", so this just enables the budget path.
+    scope.contextTokensRemaining = 32_000;
+    scope.iteration = 1;
+    scope.maxIterations = deps.maxIterations;
+    scope.finalContent = '';
+    scope.totalInputTokens = 0;
+    scope.totalOutputTokens = 0;
+    scope.turnStartMs = Date.now();
+    scope.systemPromptInjections = [];
+    scope.messagesInjections = [];
+    scope.toolsInjections = [];
+    scope.llmLatestContent = '';
+    scope.llmLatestToolCalls = [];
+    // v2.14 — initialize thinking blocks. Empty array means "no thinking
+    // this iteration"; the NormalizeThinking sub-subflow overwrites
+    // this AFTER each CallLLM when a ThinkingHandler is configured.
+    scope.thinkingBlocks = [];
+    scope.pausedToolCallId = '';
+    scope.pausedToolName = '';
+    scope.pausedToolStartMs = 0;
+    scope.cumTokensInput = 0;
+    scope.cumTokensOutput = 0;
+    scope.cumEstimatedUsd = 0;
+    scope.costBudgetHit = false;
+    scope.activeInjections = [];
+    scope.activatedInjectionIds = [];
+    scope.dynamicToolSchemas = deps.toolSchemas;
+    // Cache layer state (v2.6) — initialized to inert defaults.
+    // CacheDecision subflow populates `cacheMarkers` per iteration;
+    // UpdateSkillHistory + CacheGate consume `cachingDisabled`,
+    // `recentHitRate`, `skillHistory`. Empty defaults mean the
+    // CacheGate falls through to 'apply-markers' on iter 1 (no
+    // history yet → no churn detected; recentHitRate undefined →
+    // hit-rate floor doesn't fire).
+    scope.cacheMarkers = [];
+    scope.cachingDisabled = deps.cachingDisabled;
+    scope.recentHitRate = undefined;
+    scope.skillHistory = [];
+    // Skill-graph cursor — reset per turn so each new user message re-enters the
+    // graph through the entry router (cold start). The Injection Engine advances
+    // it each iteration; undefined for agents without a skillGraph().
+    scope.currentSkillId = undefined;
+    // `.configure()` — resolved ONCE here (seed runs exactly once per run)
+    // and written to scope, which means the run's commit log records the
+    // model and instructions the run actually used. A run that changed its
+    // own model without committing that fact would produce a trace that
+    // reads as if the built-in default answered.
+    //
+    // Only what the resolver actually returned is written: an agent with no
+    // `.configure()`, or one whose resolver returned `{}`, commits nothing
+    // extra and behaves exactly as before.
+    if (deps.resolveRunConfig) {
+        const resolved = deps.resolveRunConfig(args);
+        if (resolved?.model !== undefined)
+            scope.resolvedModel = resolved.model;
+        if (resolved?.instructions !== undefined)
+            scope.resolvedInstructions = resolved.instructions;
+    }
+    typedEmit(scope, 'agentfootprint.agent.turn_start', {
+        turnIndex: 0,
+        userPrompt: message,
+    });
 }
 //# sourceMappingURL=seed.js.map