agentfootprint 7.16.0 → 7.18.0

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

@@ -20,7 +20,9 @@ import type { ToolProvider } from '../../tool-providers/types.js';
 import { type SelfExplainOptions } from '../../lib/trace-toolpack/selfExplain.js';
 import { Agent } from '../Agent.js';
 import type { AgentOptions, RunConfigFn } from './types.js';
-import type { CompactionOptions } from './compaction/types.js';
+import type { CompactionOptions } from './window/types.js';
+import type { WindowStrategy } from './window/strategy.js';
+import type { MessageMiddleware, ToolMiddleware } from './middleware/types.js';
 /**
  * Fluent builder. `tool()` accepts any Tool<TArgs, TResult> and registers
  * it by its schema.name. Duplicate names throw at build time.
@@ -125,9 +127,14 @@ export declare class AgentBuilder {
     /** Per-run config resolver set via `.configure()`. Undefined = the agent
      *  runs on its build-time model + system prompt, unchanged. */
     private runConfigFn?;
-    /** Resolved `.compaction()` config. Undefined = no compaction stage exists,
-     *  the ReAct loop target is unchanged, and the run is byte-identical. */
-    private compactionConfig?;
+    /** The agent's one window strategy, from `.window()` or `.compaction()`.
+     *  Undefined = no window stage exists, the ReAct loop target is unchanged,
+     *  and the run is byte-identical to an agent that never heard of them. */
+    private windowStrategyValue?;
+    /** The tool-dispatch chain, in call order. Empty = no chain, no ledger. */
+    private toolMiddlewareList;
+    /** The message chain, in call order. Empty = no chain, no ledger. */
+    private messageMiddlewareList;
     constructor(opts: AgentOptions);
     /**
      * Set the base system prompt.
@@ -234,10 +241,58 @@ export declare class AgentBuilder {
      *     .build();
      */
     configure(fn: RunConfigFn): this;
+    /**
+     * Choose how the live context window is kept inside its budget.
+     *
+     * This is the general door; the strategy decides everything about WHEN it
+     * acts and WHAT leaves. Three ship, and they share one turn segmentation
+     * and one refusal engine, so a refusal reason means the same thing under
+     * all of them:
+     *
+     *   `summarizeOldest({ thresholdTokens, summarizer, ... })`
+     *      fold the oldest span into one summary message. `.compaction()` is
+     *      this, spelled shorter.
+     *   `slidingWindow({ keepRecentTurns })`
+     *      keep the last N turns and drop older ones. No summarizer, no LLM
+     *      call, no usage requirement — it runs on any provider.
+     *   `tokenBudget({ thresholdTokens })`
+     *      the counted-token trigger, dropping instead of summarizing.
+     *
+     * Never removed by any of them: the system envelope, the recent turns, and
+     * any turn holding something unresolved — an unanswered tool call, a paused
+     * tool, a pending check-in. Those refuse BY NAME in the record and the
+     * strategy takes the next oldest instead. Removing an unanswered question
+     * would destroy the referent of the answer that has not arrived yet, and
+     * splitting a `tool_use` from its `tool_result` produces a request the
+     * vendor rejects.
+     *
+     * **Whatever leaves the window stays in the ledger.** footprintjs's commit
+     * log is append-only, so the turns were committed before the strategy ran
+     * and remain byte-identical; every strategy files its own recorded step
+     * naming the `runtimeStageId`s whose messages left, and emits one
+     * `context.evicted` per message. Removing is not forgetting.
+     *
+     * Exactly one strategy per agent. Omit this (and `.compaction()`) and
+     * nothing changes: no stage, no extra committed key, the same request bytes.
+     *
+     * @example
+     * ```ts
+     * import { Agent, slidingWindow } from 'agentfootprint';
+     *
+     * const agent = Agent.create({ provider, model })
+     *   .window(slidingWindow({ keepRecentTurns: 12 }))
+     *   .build();
+     * ```
+     */
+    window(strategy: WindowStrategy): this;
     /**
      * Keep the live context window inside a token budget — without ever losing
      * the record.
      *
+     * Sugar for `.window(summarizeOldest(options))`, and byte-for-byte the same
+     * agent. It keeps its own name because compaction is what the market calls
+     * this and it is the strategy most people want first.
+     *
      * At each ReAct iteration boundary, compaction compares the LAST call's
      * **adapter-reported** input tokens against `thresholdTokens`. Over budget,
      * it folds the oldest foldable span of the conversation into one summary
@@ -273,6 +328,12 @@ export declare class AgentBuilder {
      * ```
      */
     compaction(options: CompactionOptions): this;
+    /**
+     * One window strategy per agent, whichever door set it — a second would
+     * silently override the first, and a window policy that quietly changed is
+     * a policy you cannot audit.
+     */
+    private assertNoWindowStrategy;
     /**
      * Override the ReAct iteration cap set via `Agent.create({
      * maxIterations })`. Convenience for builder-style code that prefers
@@ -676,6 +737,98 @@ export declare class AgentBuilder {
      *     .checkIn({ evidence: 'standard' })
      *     .build();
      */
+    /**
+     * Wrap every tool dispatch in a governance chain.
+     *
+     * Each middleware answers with one of three verbs — `allow()`, `deny(reason)`
+     * or `ask({ question })` — and there is deliberately no fourth. In
+     * particular there is no way to return a result: whatever the chain decides,
+     * the answer the model finally reads is the real tool's output or a refusal.
+     * A rule cannot quietly become the tool.
+     *
+     * - **`allow()`** passes the call through. **`allow(args, why)`** replaces
+     *   the args and the run commits BOTH versions with your `why` beside them,
+     *   so a slice taken later can find the moment they changed and who changed
+     *   them.
+     * - **`deny(reason)`** refuses. The reason reaches the model verbatim, as
+     *   the tool result, and the loop continues — the agent adapts in-flight. A
+     *   denial is data, not a crash.
+     * - **`ask({ question })`** suspends the run for a person, on the same
+     *   checkpoint machinery `checkIn` and `askHuman` use. The answer is a
+     *   DECISION, not a result: approve and the chain resumes and the real tool
+     *   runs; decline and it becomes a denial the model reads.
+     *
+     * Order is call order, and each middleware sees the previous one's output.
+     * The first non-allow answer wins and the rest of the chain does not run. A
+     * middleware that throws is a denial carrying the error as its reason —
+     * never a silent pass.
+     *
+     * An existing `PermissionChecker` still decides FIRST: it is not part of
+     * this chain, it runs ahead of it, so a call it denies never reaches a
+     * middleware. `gatedTools` is a different layer again — it decides which
+     * tools the model can SEE; this decides what happens when one is called.
+     *
+     * Omit this and nothing changes: no chain walk, no committed ledger key, the
+     * same request bytes.
+     *
+     * @example
+     * ```ts
+     * import { Agent, allow, deny } from 'agentfootprint';
+     *
+     * const agent = Agent.create({ provider, model })
+     *   .toolMiddleware({
+     *     name: 'no-prod-writes',
+     *     onToolCall: (call) =>
+     *       call.args.env === 'prod' ? deny('writes to prod need a change ticket') : allow(),
+     *   })
+     *   .build();
+     * ```
+     */
+    toolMiddleware(...middleware: readonly ToolMiddleware[]): this;
+    /**
+     * Wrap the message boundary in a governance chain — the input before the
+     * model sees it, the output before the caller receives it.
+     *
+     * Same verbs as {@link toolMiddleware} minus one: there is no `ask` here,
+     * and the type says so. Tool dispatch runs inside a pausable stage, so it
+     * has a checkpoint to suspend on; 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.
+     *
+     * The `'input'` half runs at the very top of the run, BEFORE the message is
+     * committed. That placement is the point: everything downstream reads
+     * `scope.history` — the window strategies, the injections, all three slots,
+     * the bytes on the wire and every slice taken afterwards — so the
+     * transformed text is what the whole run agrees was said. The `'output'`
+     * half runs where the final answer is captured, so the record and the caller
+     * receive the same string.
+     *
+     * `deny(reason)` at either phase raises a `MessageDeniedError` rather than
+     * returning. At `'input'` there is no model to tell; at `'output'` the
+     * middleware has just refused to release an answer, and handing the caller a
+     * string in its place is the one substitution they must never make without
+     * noticing. The error carries the reason, the phase and the middleware's
+     * name — never the refused content.
+     *
+     * @example
+     * ```ts
+     * import { Agent, allow } from 'agentfootprint';
+     *
+     * const agent = Agent.create({ provider, model })
+     *   .messageMiddleware({
+     *     name: 'mask-card-numbers',
+     *     onMessage: (msg) => {
+     *       const clean = msg.content.replace(/\b(?:\d[ -]?){13,16}\b/g, '[card]');
+     *       return clean === msg.content ? allow() : allow(clean, 'masked a card number');
+     *     },
+     *   })
+     *   .build();
+     * ```
+     */
+    messageMiddleware(...middleware: readonly MessageMiddleware[]): this;
+    /** Shared shape check — a chain built from a typo fails at build time, not
+     *  as a silent no-op on the one call that needed governing. */
+    private assertMiddleware;
     checkIn(opts?: CheckInBuilderOptions): this;
     selfExplain(opts?: SelfExplainOptions): this;
     build(): Agent;

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

@@ -1 +1 @@
-{"version":3,"file":"AgentBuilder.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/AgentBuilder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AgentBuilder.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/AgentBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAGL,KAAK,qBAAqB,EAE3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,WAAW,EAAiB,MAAM,sBAAsB,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AACvF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAE7E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAE,IAAI,EAAqB,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAGlE,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAI/E;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC,OAAO,CAAC,iBAAiB,CAAM;IAC/B;;;;OAIG;IACH,OAAO,CAAC,uBAAuB,CAAyB;IACxD;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB,CAAS;IACrC;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB,CAAC,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2B;IACpD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmB;IACjD;;mCAE+B;IAC/B,OAAO,CAAC,mBAAmB,CAAC,CAAgD;IAC5E;;2DAEuD;IACvD,OAAO,CAAC,mBAAmB,CAAC,CAAiD;IAC7E;;+EAE2E;IAC3E,OAAO,CAAC,sBAAsB,CAAC,CAGJ;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA0B;IACrD;;;OAGG;IACH,OAAO,CAAC,kBAAkB,CAAC,CAA8B;IAEzD;2EACuE;IACvE,OAAO,CAAC,iBAAiB,CAAC,CAAkC;IAC5D;;;;;OAKG;IACH,OAAO,CAAC,eAAe,CAAC,CAAe;IACvC;;;;OAIG;IACH,OAAO,CAAC,qBAAqB,CAAC,CAAS;IACvC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAgD;IAM7E,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,mBAAmB,CAAwC;IACnE,OAAO,CAAC,iBAAiB,CAAwC;IACjE;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB,CAAC,CAAoB;IAE9C;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,oBAAoB,CAAC,CAAyB;IACtD;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB,CAAC,CAAS;IACrC,OAAO,CAAC,iBAAiB,CAAC,CAAqB;IAC/C,OAAO,CAAC,aAAa,CAAC,CAAwB;IAC9C;mEAC+D;IAC/D,OAAO,CAAC,WAAW,CAAC,CAAc;IAClC;;8EAE0E;IAC1E,OAAO,CAAC,mBAAmB,CAAC,CAAiB;IAC7C,2EAA2E;IAC3E,OAAO,CAAC,kBAAkB,CAAiC;IAC3D,qEAAqE;IACrE,OAAO,CAAC,qBAAqB,CAAoC;gBAErD,IAAI,EAAE,YAAY;IAS9B;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,IAAI;IAQxE,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,IAAI;IAStD;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,IAAI;IAKvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI;IAU1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACH,SAAS,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI;IAiBhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACH,MAAM,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAoBtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyCG;IACH,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI;IAU5C;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAmB9B;;;;;;;OAOG;IACH,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ9B;;;;;;;;;OASG;IACH,QAAQ,CAAC,GAAG,EAAE,OAAO,aAAa,EAAE,gBAAgB,GAAG,IAAI;IAK3D;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK3B;;;;;;;;;OASG;IACH,mBAAmB,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI;IAKtE;;;;;;OAMG;IACH,iBAAiB,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI;IAWpE;;;;OAIG;IACH,SAAS,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAQrC;;;;OAIG;IACH,KAAK,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAIjC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,QAAQ,EAAE;QAAE,IAAI,IAAI,SAAS,SAAS,EAAE,CAAA;KAAE,GAAG,IAAI;IAKxD;;;;;;;;;;;;;OAaG;IACH,UAAU,CAAC,KAAK,EAAE;QAChB,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;QAC7B,SAAS,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,MAAM,GAAG,SAAS,CAAC;QACzD,eAAe,CAAC,EAAE,CAAC,cAAc,CAAC,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,CAAC;QACjE,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;KACvF,GAAG,IAAI;IAiBR;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAIpC;;;;OAIG;IACH,WAAW,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAIvC;;;;;;OAMG;IACH,YAAY,CAAC,UAAU,EAAE,aAAa,CAAC,SAAS,CAAC,GAAG,IAAI;IAKxD;;;;;OAKG;IACH,IAAI,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI;IAIhC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI;IAW1C;;;;;;;;;;;;;;;;OAgBG;IACH,GAAG,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI;IAIvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,mBAAmB,GAAG,IAAI;IAqBhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,IAAI;IAwB1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmDG;IACH,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAU5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI;IAUtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACH,QAAQ,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAiBxC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8CG;IACH,cAAc,CAAC,GAAG,UAAU,EAAE,SAAS,cAAc,EAAE,GAAG,IAAI;IAM9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,iBAAiB,CAAC,GAAG,UAAU,EAAE,SAAS,iBAAiB,EAAE,GAAG,IAAI;IAMpE;mEAC+D;IAC/D,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,IAAI,GAAE,qBAA0B,GAAG,IAAI;IAQ/C,WAAW,CAAC,IAAI,GAAE,kBAAuB,GAAG,IAAI;IAmBhD,KAAK,IAAI,KAAK;CAsFf"}

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

@@ -63,9 +63,9 @@ export interface AgentChartDeps {
     /** Hard ReAct iteration cap, threaded into CacheDecision's
      *  inputMapper for max-iteration policies. */
     readonly maxIterations: number;
-    readonly seed: (scope: never) => void;
+    readonly seed: (scope: never) => void | Promise<void>;
     readonly callLLM: (scope: never) => Promise<void>;
-    readonly routeDecider: (scope: never) => 'tool-calls' | 'final';
+    readonly routeDecider: (scope: never) => 'tool-calls' | 'final' | Promise<'tool-calls' | 'final'>;
     readonly toolCallsHandler: import('footprintjs').PausableHandler<never>;
     readonly injectionEngineSubflow: FlowChart;
     /** Relevance entry router (`entryByRelevance`) — a once-per-turn function stage
@@ -73,18 +73,25 @@ export interface AgentChartDeps {
      *  skill graph was built with a relevance scorer. */
     readonly pickEntryStage?: (scope: never) => Promise<void>;
     /**
-     * Context-compaction stage (`.compaction()`, 7.16). Present ONLY when the
-     * consumer configured compaction — and when present it BECOMES the ReAct
-     * loop target, mounted immediately before the current one.
+     * The window-strategy stage (`.window()` / `.compaction()`). Present ONLY
+     * when the consumer configured a strategy — and when present it BECOMES the
+     * ReAct loop target, mounted immediately before the current one.
      *
      * It has to be the loop target rather than merely sit in the loop body:
      * the loop is branch-sourced (`tool-calls → { loopTo }`), so anything ahead
      * of the target runs once and is never seen again. Being the target also
-     * puts the fold BEFORE the injection engine and the slots, which is the
-     * point — the triggers, the three slots and the wire then all see the same
-     * window, and no component gets a different past than the model does.
+     * puts the window change BEFORE the injection engine and the slots, which
+     * is the point — the triggers, the three slots and the wire then all see
+     * the same window, and no component gets a different past than the model
+     * does.
+     *
+     * `strategyName` rides along so the chart itself says which policy is
+     * mounted; a reader of the graph should not have to guess.
      */
-    readonly compactStage?: (scope: never) => Promise<void>;
+    readonly windowStage?: {
+        readonly strategyName: string;
+        readonly run: (scope: never) => Promise<void>;
+    };
     readonly systemPromptSubflow: FlowChart;
     readonly messagesSubflow: FlowChart;
     readonly toolsSubflow: FlowChart;

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

@@ -1 +1 @@
-{"version":3,"file":"buildAgentChart.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/buildAgentChart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAc,MAAM,aAAa,CAAC;AAE5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAOxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAUrE;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAE/C;;;8DAG0D;IAC1D,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,OAAO,yCAAyC,EAAE,WAAW,CAAC;IAEpG;uEACmE;IACnE,QAAQ,CAAC,uBAAuB,EAAE,WAAW,CAAC;IAE9C;kDAC8C;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAG/B,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,YAAY,GAAG,OAAO,CAAC;IAChE,QAAQ,CAAC,gBAAgB,EAAE,OAAO,aAAa,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;IAGxE,QAAQ,CAAC,sBAAsB,EAAE,SAAS,CAAC;IAC3C;;yDAEqD;IACrD,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,QAAQ,CAAC,mBAAmB,EAAE,SAAS,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,SAAS,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,CAAC;IAMrC,QAAQ,CAAC,uBAAuB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAEzD;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAG3C;;;;0CAIsC;IACtC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC5D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,CA4X/D"}
+{"version":3,"file":"buildAgentChart.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/buildAgentChart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAc,MAAM,aAAa,CAAC;AAE5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAOxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAUrE;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAE/C;;;8DAG0D;IAC1D,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,OAAO,yCAAyC,EAAE,WAAW,CAAC;IAEpG;uEACmE;IACnE,QAAQ,CAAC,uBAAuB,EAAE,WAAW,CAAC;IAE9C;kDAC8C;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAG/B,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,YAAY,GAAG,OAAO,GAAG,OAAO,CAAC,YAAY,GAAG,OAAO,CAAC,CAAC;IAClG,QAAQ,CAAC,gBAAgB,EAAE,OAAO,aAAa,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;IAGxE,QAAQ,CAAC,sBAAsB,EAAE,SAAS,CAAC;IAC3C;;yDAEqD;IACrD,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KAC/C,CAAC;IACF,QAAQ,CAAC,mBAAmB,EAAE,SAAS,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,SAAS,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,CAAC;IAMrC,QAAQ,CAAC,uBAAuB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAEzD;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAG3C;;;;0CAIsC;IACtC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC5D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,CA4X/D"}

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

@@ -0,0 +1,52 @@
+/**
+ * MessageDeniedError — typed error thrown by `Agent.run()` when a
+ * `messageMiddleware` returns `deny(reason)`.
+ *
+ * Pattern: Typed Error (the `PolicyHaltError` shape, for the same reason).
+ * Role:    Surface layer for the message boundary. The stage writes the
+ *          refusal to scope; `Agent.finalizeResult` translates it here, so
+ *          a caller can `instanceof` it and route on `.phase` / `.middleware`.
+ * Emits:   N/A — `agentfootprint.middleware.decision` fires from the stage
+ *          at the moment the refusal is decided.
+ *
+ * ## Why a refusal is not returned as an answer
+ *
+ * At the `'input'` phase there is no model to tell: the message never
+ * reached one, so there is nothing in the run for a denial to become. At
+ * the `'output'` phase there IS an answer, and the middleware has just
+ * refused to release it — handing the caller a string in its place is the
+ * one substitution a caller must never be able to make silently. Both
+ * phases therefore raise, exactly the way a policy halt does.
+ *
+ * ## What it deliberately does not carry
+ *
+ * Never the refused content. A middleware that suppressed an answer would
+ * be undone by an error object that carried the answer out anyway. The
+ * content stays where the run put it — in the commit log, under whatever
+ * redaction the run configured.
+ *
+ * @example
+ *   try {
+ *     await agent.run({ message: userText });
+ *   } catch (e) {
+ *     if (e instanceof MessageDeniedError) {
+ *       console.log(`${e.middleware} refused this ${e.phase}: ${e.reason}`);
+ *     } else throw e;
+ *   }
+ */
+export interface MessageDeniedContext {
+    /** The refusal text the middleware returned. */
+    readonly reason: string;
+    /** Which boundary refused. */
+    readonly phase: 'input' | 'output';
+    /** `name` of the middleware that returned `deny`. */
+    readonly middleware: string;
+}
+export declare class MessageDeniedError extends Error {
+    readonly code: "ERR_MESSAGE_DENIED";
+    readonly reason: string;
+    readonly phase: 'input' | 'output';
+    readonly middleware: string;
+    constructor(ctx: MessageDeniedContext);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/middleware/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;IACnC,qDAAqD;IACrD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,uBAAiC;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,GAAG,EAAE,oBAAoB;CAOtC"}

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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"}