agentfootprint 7.17.0 → 7.18.0

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

@@ -0,0 +1,17 @@
+/**
+ * middleware — PUBLIC barrel. The governance chain family.
+ *
+ * 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
+ *
+ * Three verbs: `allow`, `deny`, `ask`. There is no fourth, and in
+ * particular there is no way to return a result — see `types.ts`.
+ */
+export { allow, ask, deny } from './outcomes.js';
+export { MessageDeniedError, type MessageDeniedContext } from './errors.js';
+export type { AllowOutcome, AskOutcome, AskPayload, DenyOutcome, MessageMiddleware, MessageMiddlewareContext, MessageOutcome, MiddlewareDecision, ToolMiddleware, ToolMiddlewareContext, ToolOutcome, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/core/agent/middleware/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/middleware/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC5E,YAAY,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,WAAW,EACX,iBAAiB,EACjB,wBAAwB,EACxB,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,WAAW,GACZ,MAAM,YAAY,CAAC"}

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

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+import type { MiddlewareDecision } from './types.js';
+/** The scope surface this file needs. Structurally a `TypedScope<AgentState>`. */
+export interface LedgerScope {
+    middlewareDecisions?: readonly MiddlewareDecision[];
+    $emit(name: string, payload?: unknown): void;
+}
+/**
+ * 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.
+ */
+export declare function recordDecisions(scope: LedgerScope, rows: readonly MiddlewareDecision[]): void;
+//# sourceMappingURL=ledger.d.ts.map

package/dist/types/core/agent/middleware/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/middleware/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,kFAAkF;AAClF,MAAM,WAAW,WAAW;IAC1B,mBAAmB,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACpD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9C;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,kBAAkB,EAAE,GAAG,IAAI,CAoB7F"}

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

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ */
+import type { AllowOutcome, AskOutcome, AskPayload, DenyOutcome } from './types.js';
+/** Pass the value through untouched. */
+export declare function allow(): AllowOutcome<never>;
+/**
+ * Replace the value and say why.
+ *
+ * The `why` is mandatory and lands in the ledger next to the before/after
+ * pair, so a run that was scrubbed can be read back as a run that was
+ * scrubbed rather than as a run whose input was always that way.
+ */
+export declare function allow<T>(value: T, why: string): AllowOutcome<T>;
+/**
+ * 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`.
+ */
+export declare function deny(reason: string): DenyOutcome;
+/**
+ * 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.
+ */
+export declare function ask(payload: AskPayload): AskOutcome;
+//# sourceMappingURL=outcomes.d.ts.map

package/dist/types/core/agent/middleware/outcomes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outcomes.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/middleware/outcomes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEpF,wCAAwC;AACxC,wBAAgB,KAAK,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC;AAC7C;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;AAajE;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAQhD;AAED;;;;;;;;GAQG;AACH,wBAAgB,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU,CAanD"}

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

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+import type { LLMMessage } from '../../../adapters/types.js';
+import type { MemoryIdentity } from '../../../memory/identity/types.js';
+import type { AskPayload, MessageMiddleware, MiddlewareDecision, ToolMiddleware } from './types.js';
+/** Tool args, as they travel the chain. */
+export type ToolArgs = Readonly<Record<string, unknown>>;
+/**
+ * What to do when a middleware answers `ask` somewhere that cannot pause.
+ *
+ * `'pause'` — the caller will checkpoint (the normal dispatch path).
+ * `'refuse'` — the ask is converted into a deny naming the middleware. Used
+ * on the resume path (footprintjs's `PausableHandler.resume` returns void,
+ * so a resumed dispatch cannot suspend a second time) and by `mcpServe`
+ * (MCP is request/response — there is no pause to carry the ask).
+ */
+export type AskPolicy = 'pause' | 'refuse';
+export type ToolChainResult = {
+    readonly kind: 'allow';
+    readonly args: ToolArgs;
+    readonly decisions: MiddlewareDecision[];
+} | {
+    readonly kind: 'deny';
+    readonly reason: string;
+    readonly middleware: string;
+    readonly args: ToolArgs;
+    readonly decisions: MiddlewareDecision[];
+} | {
+    readonly kind: 'ask';
+    readonly payload: AskPayload;
+    readonly middleware: string;
+    /** Index of the link that asked — resume continues from `index + 1`. */
+    readonly index: number;
+    /** Args as transformed up to the ask. These ride the checkpoint. */
+    readonly args: ToolArgs;
+    readonly decisions: MiddlewareDecision[];
+};
+export interface ToolChainInput {
+    readonly toolName: string;
+    readonly toolCallId: string;
+    readonly iteration: number;
+    readonly args: ToolArgs;
+    readonly history: readonly LLMMessage[];
+    readonly identity?: MemoryIdentity;
+    readonly signal?: AbortSignal;
+    /**
+     * Where to start walking. `0` for a fresh dispatch; `n` on resume, to
+     * continue the chain AFTER the link that asked without re-running the
+     * links whose decisions the checkpoint already carries.
+     */
+    readonly startIndex?: number;
+    readonly askPolicy?: AskPolicy;
+}
+/** Walk the tool chain. Never throws — a throwing link becomes a denial. */
+export declare function runToolChain(chain: readonly ToolMiddleware[], input: ToolChainInput): Promise<ToolChainResult>;
+export type MessageChainResult = {
+    readonly kind: 'allow';
+    readonly content: string;
+    readonly decisions: MiddlewareDecision[];
+} | {
+    readonly kind: 'deny';
+    readonly reason: string;
+    readonly middleware: string;
+    /** Content as transformed by the links BEFORE the refusal. */
+    readonly content: string;
+    readonly decisions: MiddlewareDecision[];
+};
+export interface MessageChainInput {
+    readonly phase: 'input' | 'output';
+    readonly content: string;
+    readonly history: readonly LLMMessage[];
+    /** ReAct iteration for the ledger row. `0` at `'input'` (before iter 1). */
+    readonly iteration: number;
+    readonly identity?: MemoryIdentity;
+    readonly signal?: AbortSignal;
+}
+/** Walk the message chain. Never throws — a throwing link becomes a denial. */
+export declare function runMessageChain(chain: readonly MessageMiddleware[], input: MessageChainInput): Promise<MessageChainResult>;
+//# sourceMappingURL=runChain.d.ts.map

package/dist/types/core/agent/middleware/runChain.d.ts.map

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

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

@@ -0,0 +1,192 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"prepareFinal.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/prepareFinal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,eAAO,MAAM,iBAAiB,UAAW,WAAW,UAAU,CAAC,KAAG,IAkCjE,CAAC"}
+{"version":3,"file":"prepareFinal.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/prepareFinal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,eAAO,MAAM,iBAAiB,UAAW,WAAW,UAAU,CAAC,KAAG,IAkCjE,CAAC"}

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

@@ -14,6 +14,35 @@
  */
 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>;
 //# sourceMappingURL=route.d.ts.map

package/dist/types/core/agent/stages/route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,OAAO,CAAC;AAEjD,eAAO,MAAM,iBAAiB,UAAW,WAAW,UAAU,CAAC,KAAG,WAmBjE,CAAC"}
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAIhE,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,OAAO,CAAC;AAEjD,eAAO,MAAM,iBAAiB,UAAW,WAAW,UAAU,CAAC,KAAG,WAmBjE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,sBAAsB,CACpC,iBAAiB,CAAC,EAAE,SAAS,iBAAiB,EAAE,GAC/C,CAAC,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CA6BvE"}

package/dist/types/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,11 +54,25 @@ 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>;
 //# sourceMappingURL=seed.d.ts.map

package/dist/types/core/agent/stages/seed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/seed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE5E,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAErE,MAAM,WAAW,aAAa;IAC5B;4BACwB;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC;;iEAE6D;IAC7D,QAAQ,CAAC,WAAW,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/C;;;;;;OAMG;IACH,QAAQ,CAAC,2BAA2B,EAAE,MAAM,SAAS,UAAU,EAAE,GAAG,SAAS,CAAC;IAC9E;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IACnD;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,SAAS,GAAG,SAAS,CAAC;CAC1E;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,IAAI,CA0F3F"}
+{"version":3,"file":"seed.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/seed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE5E,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAIhE,MAAM,WAAW,aAAa;IAC5B;4BACwB;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC;;iEAE6D;IAC7D,QAAQ,CAAC,WAAW,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/C;;;;;;OAMG;IACH,QAAQ,CAAC,2BAA2B,EAAE,MAAM,SAAS,UAAU,EAAE,GAAG,SAAS,CAAC;IAC9E;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;IACnD;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,SAAS,GAAG,SAAS,CAAC;IACzE;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC3D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,aAAa,GAClB,CAAC,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCzD"}

package/dist/types/core/agent/stages/toolCalls.d.ts

@@ -20,6 +20,19 @@
  * `tool.execute`. Deny → tool not executed; result is a synthetic
  * denial string. Allow / gate_open → execution proceeds.
  *
+ * Gate order for one call, and why it is this order:
+ *
+ *   permission → MIDDLEWARE CHAIN → arg validation → check-in →
+ *   credentials → execute
+ *
+ * The chain sits after the permission gate so an existing checker still
+ * decides first (a denial there means no middleware runs), and before arg
+ * validation so validation judges the args that will actually be sent —
+ * a middleware that transformed args into something the tool's schema
+ * rejects must be caught, not forwarded. A middleware answering `ask`
+ * pauses on the SAME wire `checkIn` uses; the human's answer is a
+ * decision, not a result, so the chain resumes and the REAL tool runs.
+ *
  * `read_skill` is the auto-attached activation tool — when the LLM
  * calls it with a valid Skill id, the next InjectionEngine pass
  * activates that Skill (lifetime: turn).
@@ -31,6 +44,7 @@ import type { CredentialProvider } from '../../../identity/types.js';
 import { type ResolvedCheckInConfig } from '../../checkin.js';
 import type { ProviderToolCache } from '../../slots/buildToolsSlot.js';
 import type { Tool } from '../../tools.js';
+import type { ToolMiddleware } from '../middleware/types.js';
 import { type ToolArgValidationMode } from '../toolArgsValidation.js';
 import type { AgentState } from '../types.js';
 export interface ToolCallsHandlerDeps {
@@ -78,6 +92,15 @@ export interface ToolCallsHandlerDeps {
      * Agent (no check-in). The gate fires ONLY for tools that declared `checkIn`.
      */
     readonly checkIn?: ResolvedCheckInConfig;
+    /**
+     * The tool-dispatch governance chain (`.toolMiddleware(...)`), in
+     * declaration order. Walked AFTER the permission gate — so an existing
+     * `PermissionChecker` still decides first and a denial there means no
+     * middleware runs at all — and BEFORE arg validation, so validation judges
+     * the args that will actually be sent rather than the ones the model
+     * proposed. Empty / undefined → not walked, no ledger key, no events.
+     */
+    readonly toolMiddleware?: readonly ToolMiddleware[];
 }
 /**
  * Build the pausable tool-call handler for the agent's chart.

package/dist/types/core/agent/stages/toolCalls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toolCalls.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/toolCalls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAIhF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,KAAK,EAAc,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAGjF,OAAO,EAIL,KAAK,qBAAqB,EAG3B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,oBAAoB;IACnC;;4DAEwD;IACxD,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACnD;;qDAEiD;IACjD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,YAAY,CAAC;IAC7C;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAC/C;;4DAEwD;IACxD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAC/C;;kEAE8D;IAC9D,QAAQ,CAAC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACjD;;;8EAG0E;IAC1E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;IACnD;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,cAAc,CAAC,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,CAAC;IAC1E;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC;CAC1C;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,oBAAoB,GACzB,eAAe,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CA0pBzC"}
+{"version":3,"file":"toolCalls.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/toolCalls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAIhF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,KAAK,EAAc,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAGjF,OAAO,EAIL,KAAK,qBAAqB,EAG3B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAG7D,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,oBAAoB;IACnC;;4DAEwD;IACxD,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACnD;;qDAEiD;IACjD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,YAAY,CAAC;IAC7C;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAC/C;;4DAEwD;IACxD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAC/C;;kEAE8D;IAC9D,QAAQ,CAAC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACjD;;;8EAG0E;IAC1E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;IACnD;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,cAAc,CAAC,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,CAAC;IAC1E;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC;IACzC;;;;;;;OAOG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;CACrD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,oBAAoB,GACzB,eAAe,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CA60BzC"}

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

@@ -19,6 +19,7 @@ import type { ToolArgValidationMode } from './toolArgsValidation.js';
 import type { ThinkingBlock } from '../../thinking/types.js';
 import type { ReliabilityScope } from '../../reliability/types.js';
 import type { WindowRecord } from './window/types.js';
+import type { MiddlewareDecision } from './middleware/types.js';
 /**
  * Dials for the deferred observer queue (RFC-001) — only meaningful with
  * `observerDelivery: 'deferred'` (passing them without it throws at
@@ -347,6 +348,23 @@ export interface AgentState {
     pausedToolStartMs: number;
     pausedCheckIn?: boolean;
     pausedCheckInArgs?: Readonly<Record<string, unknown>>;
+    pausedAsk?: boolean;
+    pausedAskArgs?: Readonly<Record<string, unknown>>;
+    pausedAskIndex?: number;
+    pausedAskMiddleware?: string;
+    /** One row per middleware decision, in the order they were decided —
+     *  including the pass-throughs, because "the rule looked and was fine with
+     *  it" and "the rule never ran" are different facts about a run. A transform
+     *  files both the value it received and the value it produced, so a slice
+     *  taken later can find the moment the text changed and who changed it.
+     *  Written only by an agent that configured a chain; absent otherwise. */
+    middlewareDecisions?: readonly MiddlewareDecision[];
+    /** Set by the seed / prepare-final stage when a `messageMiddleware` returned
+     *  `deny`. Read at the API boundary, where it becomes a `MessageDeniedError`.
+     *  Never carries the refused content — see MessageDeniedError. */
+    messageDeniedReason?: string;
+    messageDeniedPhase?: 'input' | 'output';
+    messageDeniedBy?: string;
     cumTokensInput: number;
     cumTokensOutput: number;
     cumEstimatedUsd: number;