agentfootprint 6.44.0 → 7.0.0

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

@@ -0,0 +1,141 @@
+/**
+ * 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
+ */
+import { defaultStatusTemplates } from '../recorders/observability/status/statusTemplates.js';
+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>>;
+/**
+ * Canonical English status bundle — the chat-bubble prose. `/locales` is the
+ * single i18n home for ALL prose catalogs; `agentfootprint/status` keeps the
+ * status LOGIC (`selectStatus` / `renderStatusLine`) and renders with these
+ * words. Same object as `defaultThinkingMessages`.
+ */
+export { defaultStatusTemplates };
+export type { StatusTemplates } from '../recorders/observability/status/statusTemplates.js';
+/**
+ * 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/locales/index.js

@@ -77,6 +77,13 @@ export const defaultCommentaryMessages = defaultCommentaryTemplates;
  * `{{var}}` placeholders for runtime substitution.
  */
 export const defaultThinkingMessages = defaultStatusTemplates;
+/**
+ * Canonical English status bundle — the chat-bubble prose. `/locales` is the
+ * single i18n home for ALL prose catalogs; `agentfootprint/status` keeps the
+ * status LOGIC (`selectStatus` / `renderStatusLine`) and renders with these
+ * words. Same object as `defaultThinkingMessages`.
+ */
+export { defaultStatusTemplates };
 /**
  * Spread `overrides` on top of `defaults` so every key in `defaults`
  * has a value (the override or the original). The result is a fresh

package/dist/esm/locales/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/locales/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,8DAA8D,CAAC;AAC1G,OAAO,EAAE,sBAAsB,EAAE,MAAM,sDAAsD,CAAC;AAI9F;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,0BAA0B,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,sBAAsB,CAAC;AAE9D;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAW,EACX,YAA8C,EAAE;IAEhD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,QAAQ,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;AACtD,CAAC;AAoBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAyC,EACzC,YAA+B,EAC/B,OAAyC,EAAE;IAE3C,MAAM,QAAQ,GAA4B,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5F,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,IAAI,iBAAiB,CAAC;IAClD,MAAM,WAAW,GAAG,QAAQ,CAAC,WAAW,IAAI,KAAK,CAAC;IAElD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC3B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;aAAM,IAAI,WAAW,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7C,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACvD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,iBAAiB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC,iBAAiB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAClD,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,oBAAoB,KAAK,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACtE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/locales/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,8DAA8D,CAAC;AAC1G,OAAO,EAAE,sBAAsB,EAAE,MAAM,sDAAsD,CAAC;AAI9F;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,0BAA0B,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,sBAAsB,CAAC;AAE9D;;;;;GAKG;AACH,OAAO,EAAE,sBAAsB,EAAE,CAAC;AAGlC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAW,EACX,YAA8C,EAAE;IAEhD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,QAAQ,EAAE,GAAG,SAAS,EAAE,CAAC,CAAC;AACtD,CAAC;AAoBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAyC,EACzC,YAA+B,EAC/B,OAAyC,EAAE;IAE3C,MAAM,QAAQ,GAA4B,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5F,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,IAAI,iBAAiB,CAAC;IAClD,MAAM,WAAW,GAAG,QAAQ,CAAC,WAAW,IAAI,KAAK,CAAC;IAElD,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC3B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;aAAM,IAAI,WAAW,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7C,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACvD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,KAAK,CAAC,IAAI,CAAC,iBAAiB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC,iBAAiB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAClD,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,oBAAoB,KAAK,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACtE,CAAC"}

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';

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

@@ -0,0 +1,56 @@
+/**
+ * llmExtractor — LLM-backed beat extractor.
+ *
+ * Uses an LLMProvider (typically a cheap model like Claude Haiku or
+ * GPT-4o-mini) to produce semantically rich beats. One extraction LLM
+ * call per turn. Opt-in — default is `heuristicExtractor()` which is
+ * free.
+ *
+ * The extractor asks the LLM for a JSON response in this shape:
+ *
+ * ```json
+ * {
+ *   "beats": [
+ *     {
+ *       "summary": "User revealed their name is Alice",
+ *       "importance": 0.9,
+ *       "refs": ["msg-1-0"],
+ *       "category": "identity"
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * The extractor parses, clamps importance via `asImportance()`, and
+ * returns the beats. Malformed responses fall back to an empty array
+ * — a bad extraction should not break the agent turn.
+ *
+ * Usage:
+ * ```ts
+ * import { anthropic } from 'agentfootprint';
+ * import { llmExtractor, narrativePipeline, InMemoryStore } from 'agentfootprint/memory';
+ *
+ * const pipeline = narrativePipeline({
+ *   store: new InMemoryStore(),
+ *   extractor: llmExtractor({ provider: yourLLMProvider }),
+ * });
+ * ```
+ */
+import type { LLMProvider } from '../../adapters/types.js';
+import type { BeatExtractor } from './extractor.js';
+export interface LLMExtractorConfig {
+    /** The provider used for extraction. Typically a cheap/fast model. */
+    readonly provider: LLMProvider;
+    /**
+     * Override the system prompt. Defaults to a one-paragraph instruction
+     * that elicits the JSON shape described in the module docs.
+     */
+    readonly systemPrompt?: string;
+    /**
+     * Dev-mode logger invoked when the LLM response fails to parse.
+     * Defaults to `console.warn` — production consumers can route the
+     * signal to their telemetry pipeline.
+     */
+    readonly onParseError?: (error: unknown, rawContent: string) => void;
+}
+export declare function llmExtractor(config: LLMExtractorConfig): BeatExtractor;

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

@@ -0,0 +1,60 @@
+/**
+ * Narrative beats — the unit of narrative memory.
+ *
+ * A `NarrativeBeat` is a self-contained summary extracted from one or
+ * more messages during a turn. Instead of persisting raw conversation
+ * forever, a narrative pipeline compresses each turn into beats and
+ * recalls them by composing beats back into a coherent story.
+ *
+ * Core properties:
+ *   - **Summary**: a single sentence describing what happened.
+ *   - **Importance**: 0..1 score the picker uses to prefer salient
+ *     beats when the context-token budget is tight.
+ *   - **Refs**: ids of the source messages the beat was extracted
+ *     from. Lets consumers walk backwards from a recalled beat to
+ *     the raw source — the explainability story.
+ *   - **Category**: optional free-form tag (e.g. `"identity"`,
+ *     `"preference"`, `"fact"`). Extractors / consumers pick their
+ *     own taxonomy.
+ *
+ * Beats are persisted via the ordinary `MemoryStore` interface —
+ * `MemoryEntry<NarrativeBeat>` slots in unchanged. No storage changes
+ * needed to support narrative memory.
+ */
+/** Importance score in the half-open range [0, 1]. */
+export type BeatImportance = number;
+export interface NarrativeBeat {
+    /** One-sentence summary of what happened in this beat. */
+    readonly summary: string;
+    /**
+     * Importance score in [0, 1]. Picker stages use this to prefer
+     * salient beats when the budget is tight. Default 0.5 (neutral).
+     * Values outside [0, 1] are clamped by `asImportance()`.
+     */
+    readonly importance: BeatImportance;
+    /**
+     * Ids of the source messages this beat was extracted from. Consumers
+     * answer "why does the agent remember X?" by walking refs backwards
+     * to the raw message text. May be empty for synthesized beats
+     * (e.g., beats produced from prior beats during compaction).
+     */
+    readonly refs: readonly string[];
+    /**
+     * Optional free-form category — `"identity"`, `"preference"`,
+     * `"task-status"`, etc. Extractors / consumers pick their own
+     * taxonomy. Useful for filtering recalls by type.
+     */
+    readonly category?: string;
+}
+/**
+ * Clamp a value to the valid [0, 1] importance range. Non-finite
+ * inputs collapse to 0.5 (neutral) so extractors that produce NaN
+ * / ±Infinity don't poison the picker's comparisons.
+ */
+export declare function asImportance(value: unknown): BeatImportance;
+/**
+ * Duck-typed guard — true iff `value` has the shape of a
+ * `NarrativeBeat`. Used by pipelines that handle mixed-payload stores
+ * (raw messages + beats) to route entries correctly.
+ */
+export declare function isNarrativeBeat(value: unknown): value is NarrativeBeat;

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

@@ -0,0 +1,22 @@
+/**
+ * writeBeats — persist extracted beats to the memory store.
+ *
+ * Reads from scope:  `newBeats`, `identity`
+ * Writes to store:   one MemoryEntry<NarrativeBeat> per beat via `putMany`
+ *
+ * Parallels `writeMessages` — same shape, but the payload is beats
+ * rather than raw messages. Uses `store.putMany` so N beats from a
+ * single turn become 1 round-trip on network-backed adapters
+ * (Redis / DynamoDB / Postgres).
+ */
+import type { TypedScope } from 'footprintjs';
+import type { MemoryStore } from '../store/index.js';
+import type { ExtractBeatsState } from './extractBeats.js';
+export interface WriteBeatsConfig {
+    /** The store to persist to. Typically the same store as the pipeline's read side. */
+    readonly store: MemoryStore;
+}
+/**
+ * Build the `writeBeats` stage function.
+ */
+export declare function writeBeats(config: WriteBeatsConfig): (scope: TypedScope<ExtractBeatsState>) => Promise<void>;

package/dist/esm/memory/causal/evidenceRecorder.d.ts

@@ -0,0 +1,66 @@
+/**
+ * causalEvidenceRecorder — the evidence bridge (backlog Phase-1 #5).
+ *
+ * Harvests, DURING the run, everything a causal snapshot needs beyond
+ * (query, finalContent) — from events the engine already fires:
+ *
+ *   stream.tool_start/tool_end  → ToolCallRecord (name, args, resultPreview, errored)
+ *   stream.llm_end              → tokenUsage accumulation + iteration high-water
+ *   agent.turn_start/turn_end   → durationMs (+ authoritative totals when seen)
+ *   FlowRecorder.onDecision     → DecisionRecord with footprintjs decide()/select()
+ *                                 operator-level evidence (rule, conditions, chosen)
+ *   context.evaluated routing   → DecisionRecord per skill the graph routed to
+ *
+ * Pattern: CombinedRecorder (Convention 1 — single purpose: evidence
+ *          accumulation); per-turn reset anchored on `agent.turn_start`
+ *          (Convention 4 — executor `clear()` resets between runs; same-
+ *          executor pause/resume PRESERVES pre-pause evidence by design).
+ * PII note: tool args/results and decide() evidence persist into snapshots.
+ *          footprintjs `RedactionPolicy.emitPatterns` redacts the emit channel
+ *          BEFORE this recorder IF the consumer configures one on the executor
+ *          — the Agent does NOT configure one by default. Values are bounded
+ *          (`maxPreviewChars` for results, `maxFieldChars` for args/evidence);
+ *          treat the snapshot store as PII-bearing and protect it accordingly.
+ *
+ * The Agent attaches this automatically when a CAUSAL memory is mounted and
+ * threads `collect` into the memory write mount (`evidenceSource`) — so
+ * `writeSnapshot` persists real evidence instead of zeros.
+ */
+import type { FlowDecisionEvent, FlowSelectedEvent } from 'footprintjs';
+import type { DecisionRecord, ToolCallRecord } from './types.js';
+/** What the bridge delivers to `writeSnapshot` for one run. */
+export interface RunEvidence {
+    readonly iterations: number;
+    readonly decisions: ReadonlyArray<DecisionRecord>;
+    readonly toolCalls: ReadonlyArray<ToolCallRecord>;
+    readonly durationMs: number;
+    readonly tokenUsage: {
+        readonly input: number;
+        readonly output: number;
+    };
+}
+export interface CausalEvidenceRecorderOptions {
+    /** Recorder id (default 'causal-evidence'). */
+    readonly id?: string;
+    /** Max chars kept of each tool result preview. Default 200. */
+    readonly maxPreviewChars?: number;
+    /** Max serialized chars kept of tool ARGS and decision EVIDENCE (the
+     *  PII-dense fields). Oversized values are replaced by a truncated
+     *  preview marker. Default 2000. */
+    readonly maxFieldChars?: number;
+}
+export interface CausalEvidenceRecorderHandle {
+    readonly id: string;
+    /** Snapshot the evidence accumulated for the CURRENT run. */
+    collect(): RunEvidence;
+    clear(): void;
+    onEmit(event: {
+        name: string;
+        payload: unknown;
+    }): void;
+    onDecision(event: FlowDecisionEvent): void;
+    onSelected(event: FlowSelectedEvent): void;
+}
+/** Build the evidence-harvesting recorder. Attach via `.recorder(rec)` (the
+ *  Agent does this automatically for CAUSAL memories). */
+export declare function causalEvidenceRecorder(options?: CausalEvidenceRecorderOptions): CausalEvidenceRecorderHandle;

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

@@ -0,0 +1,6 @@
+export type { SnapshotEntry, DecisionRecord, ToolCallRecord, ProjectedSnapshot, SnapshotMessage, } from './types.js';
+export { DEFAULT_TOOL_RESULT_PREVIEW_LEN } from './types.js';
+export { causalEvidenceRecorder, type CausalEvidenceRecorderHandle, type CausalEvidenceRecorderOptions, type RunEvidence, } from './evidenceRecorder.js';
+export { writeSnapshot, type WriteSnapshotConfig } from './writeSnapshot.js';
+export { loadSnapshot, type LoadSnapshotConfig } from './loadSnapshot.js';
+export { snapshotPipeline, type SnapshotPipelineConfig } from './snapshotPipeline.js';

package/dist/esm/memory/causal/loadSnapshot.d.ts

@@ -0,0 +1,51 @@
+/**
+ * loadSnapshot — read-side stage for Causal memory.
+ *
+ * Embeds the user's current question, searches the store for the most
+ * similar past run, projects the snapshot per `SnapshotProjection`,
+ * and writes the formatted result to `scope.formatted` so the
+ * downstream slot subflow injects it as a system message.
+ *
+ * Reads from scope:   `identity`, `messages` (or `newMessages` fallback)
+ * Writes to scope:    `formatted` — array of `LLMMessage` to inject
+ *
+ * Strict-threshold semantics:
+ *   When `minScore` is set and no past snapshot meets it, returns an
+ *   empty `formatted`. NO fallback — garbage past context is worse than
+ *   no context.
+ *
+ * Empty-query handling:
+ *   No user message → no embedding → no search → empty result.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { MemoryStore } from '../store/index.js';
+import type { Embedder } from '../embedding/index.js';
+import type { MemoryState } from '../stages/index.js';
+import { type SnapshotProjection } from '../define.types.js';
+export interface LoadSnapshotConfig {
+    /** Vector-capable store. Must implement `search()`. */
+    readonly store: MemoryStore;
+    /** Embedder used to vectorize the current query. */
+    readonly embedder: Embedder;
+    /** Stable id of the embedder — filters cross-model results out. */
+    readonly embedderId?: string;
+    /** Top-k snapshots to retrieve. Default 1 (most-relevant past run). */
+    readonly topK?: number;
+    /**
+     * Minimum cosine score [-1, 1]. Strict — entries below this are
+     * dropped. When no entry meets the threshold, the stage emits no
+     * messages (no fallback). Default 0.7.
+     */
+    readonly minScore?: number;
+    /**
+     * Slice of the snapshot to project. Default `'decisions'` —
+     * decision evidence is the highest-signal field for "why" follow-ups.
+     */
+    readonly projection?: SnapshotProjection;
+    /**
+     * Optional override for query extraction. Default: last user
+     * message in `scope.messages` (current turn's question).
+     */
+    readonly queryFrom?: (scope: TypedScope<MemoryState>) => string;
+}
+export declare function loadSnapshot(config: LoadSnapshotConfig): (scope: TypedScope<MemoryState>) => Promise<void>;