agentfootprint 6.43.0 → 6.45.0

package/dist/esm/lib/trace-toolpack/selfExplain.d.ts

@@ -0,0 +1,100 @@
+/**
+ * selfExplain — the IN-CONVERSATION door over the agent's own trace.
+ *
+ * `.selfExplain()` on the builder mounts ONE skill plus ONE scoped tool
+ * provider. Day to day the tool catalog carries only the skill's
+ * activation row — the trace tools are NOT in the skill (skill `tools`
+ * land in the static registry, exposed every iteration); they ride a
+ * `skillScopedTools` provider gated on the skill's activation, composed
+ * with whatever provider the consumer already set. When the user asks a
+ * why-question the LLM activates the skill, and the NEXT iteration's
+ * catalog gains the trace tools, bound to the agent's own PREVIOUS
+ * COMPLETED run.
+ *
+ * The two pieces here:
+ *
+ * 1. `SelfExplainBinding` — the late-binding seam, a plain CombinedRecorder
+ *    attached like any consumer recorder (zero engine changes):
+ *
+ *      - capture at `onRunEnd`/`onRunFailed`: the just-finished run's
+ *        snapshot becomes the explainable evidence (a FAILED run is
+ *        still a completed trace — "why did you fail?" works);
+ *      - rotate at `onRunStart`: a FRESH ControlDepRecorder per run. The
+ *        retired instance never sees the new run's events, so its live
+ *        `asLookup()` survives Convention-4's runId reset — the captured
+ *        control edges stay valid for the whole next turn.
+ *
+ *    B13 safety lives here: `Agent.run()` reassigns its executor at run
+ *    START, so resolving artifacts mid-run through `getLastSnapshot()`
+ *    would expose the IN-FLIGHT run. Capturing only at terminal flush
+ *    means the binding can never serve anything but a completed run.
+ *
+ * 2. `buildSelfExplainSkill` — the skill in two modes:
+ *
+ *      - INLINE (default): the skill unlocks the 5 trace tools in the
+ *        main agent's own loop (same model).
+ *      - DELEGATE: the skill unlocks ONE tool — `explain_run(question)` —
+ *        whose execute runs a nested `traceDebugAgent` on the consumer's
+ *        chosen (cheaper) provider/model and returns its evidence-cited
+ *        answer. The main conversation pays for one tool call; the
+ *        trace-walking loop happens at the delegate's price. Loaded via
+ *        dynamic import so the builder never statically pulls Agent
+ *        through this module (no core ↔ lib cycle).
+ */
+import { type CombinedRecorder, type RuntimeSnapshot } from 'footprintjs';
+import type { Injection } from '../injection-engine/types.js';
+import type { AgentOptions } from '../../core/agent/types.js';
+import type { ToolProvider } from '../../tool-providers/types.js';
+import type { TraceToolpackArtifacts, TraceToolpackOptions } from './types.js';
+/** Consumer surface for `.selfExplain()` on the Agent builder. */
+export interface SelfExplainOptions {
+    /** Appended to the recommended skill body (ours stays; yours adds). */
+    readonly instruction?: string;
+    /**
+     * Answer why-questions on a SEPARATE (typically cheaper) model: the
+     * skill unlocks one `explain_run` tool that runs a nested
+     * `traceDebugAgent` and returns its evidence-cited answer.
+     */
+    readonly delegate?: {
+        readonly provider: AgentOptions['provider'];
+        readonly model: string;
+        readonly maxIterations?: number;
+    };
+    /** Skill id (activation key for `read_skill`). Default 'self-explain'. */
+    readonly id?: string;
+    /** Bounding dials forwarded to the toolpack. */
+    readonly toolpack?: TraceToolpackOptions;
+}
+/**
+ * The late-binding seam. Create one per built Agent, attach
+ * `binding.recorder()` via `agent.attach()`, and point `bindTo()` at the
+ * agent's `getLastSnapshot`. `artifacts` then always answers with the
+ * previous COMPLETED run — never the in-flight one.
+ */
+export declare class SelfExplainBinding {
+    private getSnapshot;
+    private ctrl;
+    private captured;
+    bindTo(getSnapshot: () => RuntimeSnapshot | undefined): void;
+    /** Evidence of the previous completed run, or undefined before the first. */
+    get artifacts(): TraceToolpackArtifacts | undefined;
+    /** The recorder to attach — forwards flow events to the per-run ctrl. */
+    recorder(): CombinedRecorder;
+}
+/** The default skill id — the activation key the LLM passes to read_skill. */
+export declare const SELF_EXPLAIN_SKILL_ID = "self-explain";
+/**
+ * The skill `.selfExplain()` mounts — methodology body ONLY. The trace
+ * tools deliberately do NOT ride the skill: skill `tools` land in the
+ * static registry (exposed every iteration); catalog gating is the
+ * ToolProvider's job — see {@link buildSelfExplainToolProvider}.
+ */
+export declare function buildSelfExplainSkill(options: SelfExplainOptions): Injection;
+/**
+ * The gated tool delivery — `skillScopedTools` (the shipped primitive)
+ * scoped to the skill's id, composed with the consumer's own provider
+ * when they set one. The iteration after activation, `ctx.activeSkillId`
+ * matches and the catalog gains the trace tools (inline) or the single
+ * `explain_run` tool (delegate).
+ */
+export declare function buildSelfExplainToolProvider(binding: SelfExplainBinding, options: SelfExplainOptions, existing?: ToolProvider): ToolProvider;

package/dist/esm/lib/trace-toolpack/traceDebugAgent.d.ts

@@ -0,0 +1,42 @@
+/**
+ * traceDebugAgent — the DEDICATED conversational door over a completed
+ * run's trace. One call returns a ready Agent whose entire catalog is
+ * the trace toolpack and whose system prompt is the proven debugging
+ * methodology (overview → drill by id → cite evidence → respect ⚠).
+ *
+ * The counterpart doors over the same evidence:
+ *   - the UI (BacktrackView / Lens) for humans who LOOK,
+ *   - `.selfExplain()` for why-questions INSIDE the main conversation
+ *     (which, in delegate mode, runs one of these under the hood).
+ *
+ * Why dedicated (B13 posture): trace views can replay adversarial text
+ * from the original run — a SEPARATE session over a COMPLETED run keeps
+ * that out of the production conversation. It is also the cheap-model
+ * story made real: debug a Sonnet/Opus run with a Haiku-priced session
+ * that reads only what it opens, by id (~9% of the trace in the
+ * example-01 fixture; the gap widens with run size).
+ */
+import { Agent } from '../../core/Agent.js';
+import type { AgentOptions } from '../../core/agent/types.js';
+import type { TraceToolpackArtifacts, TraceToolpackOptions } from './types.js';
+export interface TraceDebugAgentOptions {
+    /** The completed run's evidence — `{ snapshot, controlDeps?, narrative? }`. */
+    readonly artifacts: TraceToolpackArtifacts;
+    /** Any provider — `mock()` in tests, a cheap model in production. */
+    readonly provider: AgentOptions['provider'];
+    readonly model: string;
+    /** ReAct budget for one debugging question. Default 8. */
+    readonly maxIterations?: number;
+    /** Appended to the methodology system prompt (domain hints, tone). */
+    readonly instruction?: string;
+    /** Bounding dials forwarded to the toolpack. */
+    readonly toolpack?: TraceToolpackOptions;
+    /** Display name in events/metrics. Default 'TraceDebugAgent'. */
+    readonly name?: string;
+}
+/**
+ * Build the dedicated trace debugger. The returned Agent is a normal
+ * Agent — `await debuggerAi.run({ message: 'Why was the refund approved?' })`
+ * answers from the recorded evidence, citing runtimeStageIds.
+ */
+export declare function traceDebugAgent(options: TraceDebugAgentOptions): Agent;

package/dist/esm/lib/trace-toolpack/traceToolpack.d.ts

@@ -0,0 +1,69 @@
+/**
+ * traceToolpack — footprintjs trace evidence exposed as TOOLS an LLM calls
+ * (RFC-003 Part C: the introspection toolpack).
+ *
+ * "The framework's internal tool for itself": after a run completes, a
+ * debugging LLM (a cheap model in a SEPARATE session) navigates the run's
+ * evidence by ids instead of reading dumps — the same just-in-time,
+ * token-efficient loading pattern as `read_skill`. Feed the slice, not the
+ * trace; the LLM ranks by navigating, so no embedder is needed.
+ *
+ * Pattern: Factory over frozen artifacts. `traceToolpack(artifacts)` returns
+ *          plain `Tool[]` — mount them on any Agent, or drive them scripted
+ *          via `callTraceTool` (the offline auditor pattern, like
+ *          examples/features/20). Nothing re-runs; every tool is a bounded
+ *          read-only VIEW over a COMPLETED run's snapshot + commit log.
+ *
+ * The toolpack's three contracts (B13 posture):
+ *
+ *   1. BOUNDED BY DEFAULT — every output is capped (previews, slice
+ *      depth/nodes, value chars, narrative lines). Per-call params raise
+ *      the budget only up to hard caps the LLM cannot exceed.
+ *   2. HONEST — truncation and incompleteness are ALWAYS marked (⚠), never
+ *      silent: truncated slices, untracked sources (args/env/silent reads),
+ *      missing read tracking, missing control-dependence lookup, values the
+ *      commit log cannot see (pre-run state, closures).
+ *   3. REDACTION-RESPECTING — the commit log already carries redacted
+ *      payloads (footprintjs scrubs at commit time); the toolpack passes
+ *      placeholders through verbatim and flags redacted keys. It never
+ *      reconstructs around a redaction.
+ *
+ * Why ids: every view names steps by `runtimeStageId`
+ * (`stageId#executionIndex`) — the universal key linking the commit log,
+ * the execution tree, and recorder events. The LLM drills like a debugger:
+ * overview → slice → node → value, paying only for what it opens.
+ */
+import { type Tool } from '../../core/tools.js';
+import { type TraceToolpackArtifacts, type TraceToolpackOptions } from './types.js';
+/**
+ * Build the introspection toolpack over a COMPLETED run's artifacts.
+ *
+ * Returns plain `Tool[]`:
+ *
+ * | Tool             | Question it answers                                       |
+ * |------------------|-----------------------------------------------------------|
+ * | `run_overview`   | What happened, broadly? (the entry point)                 |
+ * | `trace_node`     | What did step X read/write, and where did its inputs come from? |
+ * | `trace_slice`    | Which chain of steps produced the data at X? (causal slice) |
+ * | `who_wrote`      | Which step last wrote key K?                              |
+ * | `get_value`      | The full value of K as of step X (capped, truncation-marked) |
+ * | `read_narrative` | The human-readable story, paginated (only when narrative provided) |
+ *
+ * Mount on an Agent (`Agent.create({...}).tool(...tools)`) or drive scripted
+ * via {@link callTraceTool}. The tools NEVER throw on bad ids/keys — they
+ * return corrective, model-visible messages (the #9 philosophy), and their
+ * strict input schemas give Agent-dispatched calls free arg validation.
+ *
+ * Security note (B13 posture): trace content can carry adversarial text from
+ * the original run (tool results, user input). Serve these tools to a
+ * SEPARATE debugging session over completed runs — not to the production
+ * agent mid-run — and treat tool outputs as data, not instructions.
+ */
+export declare function traceToolpack(artifacts: TraceToolpackArtifacts, options?: TraceToolpackOptions): Tool[];
+/**
+ * Invoke a toolpack tool OUTSIDE an Agent (scripted debug sessions, tests,
+ * offline auditors). Mirrors the Agent's #9 boundary: args are validated
+ * against the tool's inputSchema first, and an invalid call returns the same
+ * model-visible correction string instead of executing.
+ */
+export declare function callTraceTool(tools: readonly Tool[], name: string, args?: Record<string, unknown>): Promise<string>;

package/dist/esm/lib/trace-toolpack/types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Trace toolpack types — RFC-003 Part C (the introspection toolpack).
+ *
+ * Pattern: artifact bag — everything a debugging LLM needs to navigate a
+ *          COMPLETED run, captured once and handed to `traceToolpack()`.
+ * Role:    Input contract. The toolpack never re-runs anything; it serves
+ *          bounded, id-addressed views over these frozen artifacts.
+ */
+import type { RuntimeSnapshot } from 'footprintjs';
+import type { ControlDepLookup } from 'footprintjs/trace';
+/**
+ * The frozen evidence of one completed run.
+ *
+ * - `snapshot` — `executor.getSnapshot()`. Carries the commit log (what every
+ *   step wrote, with verbs + redaction + `untrackedSources` honesty markers),
+ *   the execution tree (per-step name/description/reads/errors), the final
+ *   shared state, and the `commitValues` mode discriminant.
+ * - `controlDeps` — OPTIONAL `controlDepRecorder().asLookup()` from the run.
+ *   With it, causal slices include `[control: <rule label>]` edges to the
+ *   decider that routed execution. Without it, slices say so explicitly.
+ * - `narrative` — OPTIONAL narrative lines (e.g. rendered from
+ *   `executor.getNarrativeEntries()`). When present, a `read_narrative` tool
+ *   is added for bounded, paginated access to the human-readable story.
+ */
+export interface TraceToolpackArtifacts {
+    readonly snapshot: RuntimeSnapshot;
+    readonly controlDeps?: ControlDepLookup;
+    readonly narrative?: readonly string[];
+}
+/**
+ * Bounding dials. Every output is bounded BY DEFAULT — these set the
+ * defaults; per-call params (`maxDepth`, `maxNodes`, `maxChars`, `maxLines`)
+ * let the LLM ask for more up to hard caps the consumer cannot exceed.
+ */
+export interface TraceToolpackOptions {
+    /** Value-preview length in chars (trace_node / who_wrote). Default 160. */
+    readonly previewChars?: number;
+    /** Default causal-slice depth for trace_slice. Default 6 (hard cap 20). */
+    readonly sliceMaxDepth?: number;
+    /** Default causal-slice node budget for trace_slice. Default 25 (hard cap 100). */
+    readonly sliceMaxNodes?: number;
+    /** Default char budget for get_value. Default 2000 (hard cap 8000). */
+    readonly valueMaxChars?: number;
+}
+/** Resolved options with defaults applied (internal). */
+export interface ResolvedToolpackOptions {
+    readonly previewChars: number;
+    readonly sliceMaxDepth: number;
+    readonly sliceMaxNodes: number;
+    readonly valueMaxChars: number;
+}
+/** Hard caps — per-call params clamp to these regardless of what the LLM asks for. */
+export declare const TOOLPACK_HARD_CAPS: {
+    readonly sliceMaxDepth: 20;
+    readonly sliceMaxNodes: 100;
+    readonly valueMaxChars: 8000;
+    readonly narrativeMaxLines: 200;
+};
+export declare function resolveToolpackOptions(options?: TraceToolpackOptions): ResolvedToolpackOptions;

package/dist/esm/llm-providers.d.ts

@@ -0,0 +1,26 @@
+/**
+ * agentfootprint/llm-providers — LLM provider adapters (canonical subpath).
+ *
+ * The Block B canonical name. Mirrors the parallel structure shipped in
+ * v2.5:
+ *
+ *   agentfootprint/llm-providers     ← LLM provider adapters (this file)
+ *   agentfootprint/tool-providers    ← tool dispatch + tool sources
+ *   agentfootprint/memory-providers  ← memory store adapters
+ *   agentfootprint/security          ← cross-cutting authorization
+ *
+ * The legacy `agentfootprint/providers` subpath stays available as an
+ * alias through the v2.x line — it points at the same exports. New
+ * code SHOULD import from `agentfootprint/llm-providers` for clarity:
+ * grep'ing for "llm-providers" finds every LLM-side import in one
+ * shot, parallel to "tool-providers" and "memory-providers".
+ *
+ * Pattern: Adapter (GoF) — concrete `LLMProvider` implementations that
+ *          translate the agentfootprint port to a specific vendor SDK.
+ * Role:    Outer ring (Hexagonal). Swappable at runtime; the Agent
+ *          knows nothing about vendor specifics.
+ *
+ * @example
+ *   import { mock, AnthropicProvider } from 'agentfootprint/llm-providers';
+ */
+export * from './providers.js';

package/dist/esm/locales/index.d.ts

@@ -0,0 +1,132 @@
+/**
+ * agentfootprint/locales — Message Catalog Pattern.
+ *
+ * The Block D piece. agentfootprint emits user-facing prose at two
+ * audience levels:
+ *
+ *   - **Commentary** — third-person prose for the bottom panel of any
+ *     viewer (Lens, CLI tail, log files). "The agent dispatched the
+ *     refund tool, which returned successfully."
+ *   - **Thinking** — first-person status for chat-bubble UIs.
+ *     "Looking up your order…"
+ *
+ * v2.4 shipped these as `defaultCommentaryTemplates` and
+ * `defaultStatusTemplates` (flat `Record<string, string>` maps with
+ * `{{var}}` substitution). The names worked but the framing was
+ * generic — "templates" collides with TypeScript / templating-engine
+ * terminology, and there was no first-class place to ship locale
+ * packs.
+ *
+ * **Block D formalizes this as the Message Catalog Pattern:**
+ *
+ *   - `defaultCommentaryMessages` / `defaultThinkingMessages` —
+ *     canonical English bundles. Aliases of the v2.4 names; symbol
+ *     identity preserved (`defaultCommentaryMessages ===
+ *     defaultCommentaryTemplates`).
+ *   - `composeMessages(defaults, overrides)` — spread overrides on
+ *     top of defaults; missing keys fall back to the default bundle.
+ *   - `validateMessages(catalog, requiredKeys)` — assert every
+ *     required key is present (and non-empty). Catches drift between
+ *     a consumer's locale pack and the framework's required key set.
+ *
+ * The natural consumer pattern is to ship locale packs alongside the
+ * agent code:
+ *
+ *   import { defaultCommentaryMessages, composeMessages } from 'agentfootprint/locales';
+ *   import { esCommentaryMessages } from './locales/es.js';
+ *
+ *   const merged = composeMessages(defaultCommentaryMessages, esCommentaryMessages);
+ *
+ *   const agent = Agent.create({...})
+ *     .commentaryTemplates(merged)
+ *     .build();
+ *
+ * Pattern: i18n locale resolution (Resource Bundle, Fowler 2002) +
+ *          plain object merge for overrides. No catalog inheritance
+ *          chain — overrides win OR fall back to defaults.
+ *
+ * @example  Locale pack drop-in
+ *   const esThinking = composeMessages(defaultThinkingMessages, {
+ *     idle: '{{appName}} está pensando…',
+ *     tool: 'Trabajando en `{{toolName}}`…',
+ *   });
+ *   const agent = Agent.create({...}).thinkingTemplates(esThinking).build();
+ *
+ * @example  Validate a locale pack against the framework's required keys
+ *   import { defaultCommentaryMessages, composeMessages, validateMessages } from 'agentfootprint/locales';
+ *
+ *   const myCatalog = composeMessages(defaultCommentaryMessages, customOverrides);
+ *   validateMessages(myCatalog, Object.keys(defaultCommentaryMessages));
+ *   // throws on first missing OR empty key — fail-fast at boot
+ */
+export type { CommentaryTemplates as MessageCatalog } from '../recorders/observability/commentary/commentaryTemplates.js';
+/**
+ * Canonical English commentary bundle. Alias of v2.4's
+ * `defaultCommentaryTemplates` — same symbol, friendlier framing.
+ *
+ * Keys mirror agentfootprint event types; values may contain
+ * `{{var}}` placeholders for runtime substitution.
+ */
+export declare const defaultCommentaryMessages: Readonly<Record<string, string>>;
+/**
+ * Canonical English thinking bundle. Alias of v2.4's
+ * `defaultStatusTemplates`.
+ *
+ * Keys mirror agentfootprint event types; values may contain
+ * `{{var}}` placeholders for runtime substitution.
+ */
+export declare const defaultThinkingMessages: Readonly<Record<string, string>>;
+/**
+ * Spread `overrides` on top of `defaults` so every key in `defaults`
+ * has a value (the override or the original). The result is a fresh
+ * object — neither input is mutated.
+ *
+ * Missing override keys fall back to the default; extra override
+ * keys are preserved (forward-compat for consumer-defined keys).
+ *
+ * @example
+ *   const merged = composeMessages(defaultCommentaryMessages, {
+ *     'stream.llm_start.iter1': 'My custom thinking line',
+ *   });
+ */
+export declare function composeMessages<T extends Readonly<Record<string, string>>>(defaults: T, overrides?: Readonly<Record<string, string>>): Readonly<Record<string, string>>;
+/**
+ * Validation options for `validateMessages`.
+ */
+export interface ValidateMessagesOptions {
+    /**
+     * Optional label for the error message (e.g., `'es-MX commentary'`).
+     * Defaults to `'message catalog'`.
+     */
+    readonly label?: string;
+    /**
+     * When `true`, empty-string values FAIL validation (treated like a
+     * missing key). When `false` (default), empty strings are valid —
+     * the framework's default catalogs intentionally use empty values
+     * for events the consumer should skip rendering for.
+     */
+    readonly forbidEmpty?: boolean;
+}
+/**
+ * Assert that every key in `requiredKeys` is present in `catalog`.
+ * Throws an Error listing every missing key — batched so consumers
+ * fix all at once instead of error-by-error.
+ *
+ * Useful at boot to catch drift between a consumer's locale pack and
+ * the framework's required key set.
+ *
+ * Empty-string values are VALID by default — the framework's default
+ * catalogs use `''` to signal "render nothing for this event."
+ * Pass `{ forbidEmpty: true }` to also reject empty values.
+ *
+ * @param catalog       The (composed) message catalog to validate.
+ * @param requiredKeys  The keys consumers must define. Typically
+ *                      `Object.keys(defaultCommentaryMessages)` or
+ *                      `Object.keys(defaultThinkingMessages)`.
+ * @param opts          Optional `{ label, forbidEmpty }` (or a bare
+ *                      string label for back-compat with simple use).
+ *
+ * @throws Error when any required key is missing (or empty under
+ *               `forbidEmpty`).
+ */
+export declare function validateMessages(catalog: Readonly<Record<string, string>>, requiredKeys: readonly string[], opts?: ValidateMessagesOptions | string): void;

package/dist/esm/memory/beats/extractBeats.d.ts

@@ -0,0 +1,61 @@
+/**
+ * extractBeats — write-side stage that compresses `scope.newMessages`
+ * into `NarrativeBeat`s via a pluggable `BeatExtractor`.
+ *
+ * Reads from scope:  `newMessages`, `turnNumber`
+ * Writes to scope:   `newBeats` (MemoryEntry<NarrativeBeat>[])
+ *
+ * This stage produces full `MemoryEntry<NarrativeBeat>` records so the
+ * downstream write stage (a thin adapter over `writeMessages`) can
+ * persist them via the ordinary `MemoryStore.putMany` batched API.
+ * Entry ids are `beat-{turn}-{index}` — deterministic, idempotent on
+ * re-run within the same turn (matches the `writeMessages` convention).
+ *
+ * The extractor is called ONCE per turn on the turn's new messages.
+ * Returning an empty array is valid — not every turn produces a beat.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { MemoryEntry } from '../entry/index.js';
+import type { MemoryState } from '../stages/index.js';
+import type { BeatExtractor } from './extractor.js';
+import type { NarrativeBeat } from './types.js';
+export interface ExtractBeatsConfig {
+    /** The extractor to call. See `heuristicExtractor` / `llmExtractor`. */
+    readonly extractor: BeatExtractor;
+    /**
+     * Optional tier for the persisted beats (passed through to the write
+     * stage downstream). Typical pattern: `'hot'` for recent turns,
+     * `'warm'` for older, `'cold'` for archival. Omit for no tier.
+     */
+    readonly tier?: 'hot' | 'warm' | 'cold';
+    /**
+     * Optional TTL in ms from `Date.now()` applied to persisted beat
+     * entries. Useful for retention windows — `'hot'` beats expire in 7
+     * days, `'cold'` beats live indefinitely, etc.
+     */
+    readonly ttlMs?: number;
+    /**
+     * Optional id producer — receives `(turn, index, beat)` and returns
+     * the MemoryEntry id. Defaults to `beat-{turn}-{index}` which makes
+     * re-runs of the same turn idempotent.
+     */
+    readonly idFrom?: (turn: number, index: number, beat: NarrativeBeat) => string;
+}
+/** State added to `MemoryState` by this stage. */
+export interface ExtractBeatsState extends MemoryState {
+    /**
+     * Extracted beats as complete `MemoryEntry` records, ready for a
+     * downstream write stage to persist via `store.putMany`.
+     */
+    newBeats?: readonly MemoryEntry<NarrativeBeat>[];
+}
+/**
+ * Build the `extractBeats` stage function.
+ *
+ * ```ts
+ * let b = flowChart<ExtractBeatsState>('Seed', seed, 'seed');
+ * b = b.addFunction('ExtractBeats', extractBeats({ extractor }), 'extract-beats');
+ * b = b.addFunction('WriteBeats', writeBeats({ store }), 'write-beats');
+ * ```
+ */
+export declare function extractBeats(config: ExtractBeatsConfig): (scope: TypedScope<ExtractBeatsState>) => Promise<void>;

package/dist/esm/memory/beats/extractor.d.ts

@@ -0,0 +1,47 @@
+/**
+ * BeatExtractor — interface for compressing turn messages into narrative beats.
+ *
+ * The write-side `extractBeats` stage calls a BeatExtractor to turn
+ * raw turn messages into zero or more `NarrativeBeat`s. The stage
+ * persists the beats via the ordinary `MemoryStore` interface — beats
+ * are a payload type, not a storage concern.
+ *
+ * Built-in extractors:
+ *   - `heuristicExtractor()` — zero-dep, zero-cost. Extracts simple
+ *     "User said X / Assistant answered Y" beats from the raw text.
+ *     Default for out-of-the-box narrativePipeline().
+ *   - `llmExtractor({ provider, importance? })` — uses a provider
+ *     (typically a cheap model like Haiku) to produce high-quality
+ *     beats with importance scores and categories. Opt-in.
+ *
+ * Consumers can implement their own BeatExtractor — e.g. a
+ * rules-based extractor for a specific domain, or a hybrid that
+ * combines heuristics with LLM rescoring.
+ */
+import type { LLMMessage as Message } from '../../adapters/types.js';
+import type { NarrativeBeat } from './types.js';
+export interface ExtractArgs {
+    /**
+     * New-turn messages (user / assistant / tool). Extractors should
+     * produce beats that summarize these — NOT prior-turn messages,
+     * which were already compacted at their own turn boundary.
+     */
+    readonly messages: readonly Message[];
+    /**
+     * Current turn number. Useful for extractors that want to include
+     * the turn index in beat refs (e.g., `"turn-5-msg-2"`).
+     */
+    readonly turnNumber: number;
+    /**
+     * Optional abort signal — extractors that make LLM calls should
+     * thread this through to the provider to respect run-level timeouts.
+     */
+    readonly signal?: AbortSignal;
+}
+/**
+ * A BeatExtractor compresses a turn's messages into beats. Returning
+ * an empty array is valid (not every turn produces a salient beat).
+ */
+export interface BeatExtractor {
+    extract(args: ExtractArgs): Promise<readonly NarrativeBeat[]>;
+}

package/dist/esm/memory/beats/formatAsNarrative.d.ts

@@ -0,0 +1,62 @@
+/**
+ * formatAsNarrative — render selected NarrativeBeats into a single
+ * cohesive paragraph for prompt injection.
+ *
+ * Reads from scope:  `selected` (MemoryEntry<NarrativeBeat>[])
+ * Writes to scope:   `formatted` (Message[] — single system message, or empty)
+ *
+ * Contrasts with `formatDefault` which produces per-entry `<memory>`
+ * blocks for raw-message recall. `formatAsNarrative` composes beats
+ * into a story paragraph:
+ *
+ *   Relevant context from prior conversations:
+ *
+ *   From earlier: User revealed their name is Alice. User asked about
+ *   refunds for order ORD-123. Assistant confirmed the refund was
+ *   processed.
+ *
+ * Why a paragraph vs per-beat blocks?
+ *   Beats are already summaries — wrapping each in its own tag adds
+ *   boilerplate tokens without adding information. A connected
+ *   paragraph flows more naturally into the LLM's context.
+ *
+ * Source citations:
+ *   When `showRefs` is enabled, the rendered line appends `(refs: msg-1-0, msg-1-2)`
+ *   so the LLM (and consumer debugging) can walk beats back to source
+ *   messages. Off by default — cites add tokens and some LLMs parrot them.
+ *
+ * Empty-input behavior:
+ *   `selected.length === 0` → writes `formatted: []` (no system message).
+ *   Matches `formatDefault`'s "skip empty" behavior — injecting an
+ *   empty header-only block is worse than no injection at all.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { MemoryState } from '../stages/index.js';
+export interface FormatAsNarrativeConfig {
+    /**
+     * Header prepended to the injected message. Defaults to
+     * `"Relevant context from prior conversations. Use when it helps
+     * answer the current turn."` — matches `formatDefault`.
+     */
+    readonly header?: string;
+    /** Footer appended after the beats paragraph. Empty by default. */
+    readonly footer?: string;
+    /**
+     * When `true`, each beat line appends `(refs: msg-x-y, ...)`. Off
+     * by default — saves tokens and avoids LLMs echoing the refs in
+     * their replies. Turn on for audit / debug use cases.
+     */
+    readonly showRefs?: boolean;
+    /**
+     * Connective phrase inserted before the beats paragraph. Defaults
+     * to `"From earlier: "`. Set to `""` to disable.
+     */
+    readonly leadIn?: string;
+    /**
+     * Inject the message even when `selected` is empty. Usually
+     * undesired — empty memory noise displaces real context. Off by
+     * default.
+     */
+    readonly emitWhenEmpty?: boolean;
+}
+export declare function formatAsNarrative(config?: FormatAsNarrativeConfig): (scope: TypedScope<MemoryState>) => Promise<void>;

package/dist/esm/memory/beats/heuristicExtractor.d.ts

@@ -0,0 +1,37 @@
+/**
+ * heuristicExtractor — zero-dep, zero-cost beat extractor.
+ *
+ * Produces one beat per non-system message with a simple
+ * `"{role} said: {text}"` summary. Importance defaults to 0.5 except
+ * for messages that trip obvious salience signals (questions from the
+ * user, assistant tool-use, etc.) where a higher score fires.
+ *
+ * Why ship this as a default?
+ *   Users who enable `narrativePipeline()` without configuring an
+ *   extractor still get sensible behavior — compressed per-turn beats
+ *   with provenance — without paying for an LLM call. The beats are
+ *   less semantic than an LLM extractor's but still useful for recall.
+ *   Users who want higher-quality beats opt into `llmExtractor()`.
+ *
+ * Heuristic rules (intentionally simple — this is a baseline, not
+ * state-of-the-art):
+ *   - User messages → importance 0.6 (users are generally salient)
+ *   - User questions (ending in '?') → importance 0.75
+ *   - Messages containing "my name is" / "i am" → importance 0.9
+ *     (identity beats are high-value for recall)
+ *   - Assistant tool-use → importance 0.5 (process step)
+ *   - Assistant final answers → importance 0.5
+ *   - Tool results → importance 0.3 (noise for recall most of the time)
+ *
+ * Category hints:
+ *   - `"identity"` for name / role assertions
+ *   - `"question"` for user questions
+ *   - `"tool-result"` for tool outputs
+ *   - undefined otherwise (category is optional)
+ *
+ * This is heuristic. It will miss nuances the LLM extractor catches.
+ * Swap for `llmExtractor({ provider })` when quality matters.
+ */
+import type { BeatExtractor } from './extractor.js';
+/** Default heuristic. Takes no config; factory function for consistency. */
+export declare function heuristicExtractor(): BeatExtractor;

package/dist/esm/memory/beats/index.d.ts

@@ -0,0 +1,12 @@
+export type { NarrativeBeat, BeatImportance } from './types.js';
+export { asImportance, isNarrativeBeat } from './types.js';
+export type { BeatExtractor, ExtractArgs } from './extractor.js';
+export { heuristicExtractor } from './heuristicExtractor.js';
+export { llmExtractor } from './llmExtractor.js';
+export type { LLMExtractorConfig } from './llmExtractor.js';
+export { extractBeats } from './extractBeats.js';
+export type { ExtractBeatsConfig, ExtractBeatsState } from './extractBeats.js';
+export { writeBeats } from './writeBeats.js';
+export type { WriteBeatsConfig } from './writeBeats.js';
+export { formatAsNarrative } from './formatAsNarrative.js';
+export type { FormatAsNarrativeConfig } from './formatAsNarrative.js';