emocentric 0.1.0

package/dist/pipeline/appraiser.js

@@ -0,0 +1,132 @@
+import { projectDeltas } from "../emotion/state.js";
+const DELTAS_SCHEMA = {
+    name: "appraisal",
+    schema: {
+        type: "object",
+        properties: {
+            deltas: {
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: {
+                        emotion: { type: "string" },
+                        delta: { type: "number" },
+                        reason: { type: "string" },
+                    },
+                    required: ["emotion", "delta", "reason"],
+                    additionalProperties: false,
+                },
+            },
+        },
+        required: ["deltas"],
+        additionalProperties: false,
+    },
+};
+/**
+ * Default appraiser: one LLM call that reads the persona (summary +
+ * dispositions), every emotion's description and current value, the event
+ * description, and the recalled memories — and returns per-emotion deltas
+ * with reasons.
+ */
+export class LLMAppraiser {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async appraise(input) {
+        const definitions = input.state.definitions();
+        const before = await input.state.snapshot();
+        const apply = input.apply ?? true;
+        const response = await this.options.llm.complete({
+            system: this.systemPrompt(input.persona),
+            messages: [
+                {
+                    role: "user",
+                    content: [
+                        {
+                            type: "text",
+                            text: this.userPrompt(input, before),
+                        },
+                    ],
+                },
+            ],
+            jsonSchema: DELTAS_SCHEMA,
+            ...(this.options.maxTokens !== undefined && {
+                maxTokens: this.options.maxTokens,
+            }),
+        });
+        const known = new Set(definitions.map((d) => d.name));
+        const deltas = parseDeltas(response.text, known);
+        const after = apply
+            ? await input.state.applyDeltas(deltas)
+            : projectDeltas(before, deltas, definitions);
+        return { deltas, before, after, applied: apply };
+    }
+    systemPrompt(persona) {
+        const identity = persona
+            ? `You are the emotional processing of ${persona.name}: ${persona.summary}.`
+            : "You are the emotional processing of an agent.";
+        return (identity +
+            " Given what just happened and what the agent remembers, decide how each emotion should move.\n" +
+            "- Deltas are numbers from -1 to 1; most events warrant small moves (±0.05 to ±0.25). Reserve large moves for genuinely major events.\n" +
+            "- Only include emotions that should move; give each a short reason.\n" +
+            "- React in character: the dispositions describe how this agent tends to feel.\n" +
+            "- Memories shape feeling: the same event lands differently depending on history.\n" +
+            'Respond with JSON only: {"deltas": [{"emotion": string, "delta": number, "reason": string}]}.');
+    }
+    userPrompt(input, before) {
+        const definitions = input.state.definitions();
+        const dispositions = new Map((input.persona?.temperament ?? [])
+            .filter((t) => t.disposition)
+            .map((t) => [t.emotion, t.disposition]));
+        const emotionLines = definitions.map((def) => {
+            const disposition = dispositions.get(def.name);
+            return (`- ${def.name} (current ${(before[def.name] ?? def.baseline).toFixed(2)}): ${def.description}` +
+                (disposition ? ` [disposition: ${disposition}]` : ""));
+        });
+        const memoryLines = input.memories.length === 0
+            ? "none relevant"
+            : input.memories
+                .map((fact, i) => `${i + 1}. [${fact.kind}] ${fact.content}`)
+                .join("\n");
+        const actor = input.event.actor.displayName ?? input.event.actor.id;
+        return (`EMOTIONS (value 0..1):\n${emotionLines.join("\n")}\n\n` +
+            `WHAT JUST HAPPENED (platform: ${input.event.platform}; actor: ${actor}; time: ${input.event.occurredAt}):\n` +
+            `${input.description}\n\n` +
+            `RELEVANT MEMORIES:\n${memoryLines}`);
+    }
+}
+/** Tolerant parse of appraisal output: extracts JSON from prose, drops
+ * deltas for emotions outside the palette, clamps deltas to [-1, 1].
+ * Unparseable output yields an empty delta list (a calm non-reaction). */
+export function parseDeltas(text, knownEmotions) {
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    if (start === -1 || end <= start)
+        return [];
+    try {
+        const parsed = JSON.parse(text.slice(start, end + 1));
+        if (!Array.isArray(parsed.deltas))
+            return [];
+        const deltas = [];
+        for (const item of parsed.deltas) {
+            if (typeof item !== "object" || item === null)
+                continue;
+            const { emotion, delta, reason } = item;
+            if (typeof emotion !== "string" || !knownEmotions.has(emotion))
+                continue;
+            const numeric = typeof delta === "number" ? delta : Number(delta);
+            if (!Number.isFinite(numeric))
+                continue;
+            deltas.push({
+                emotion,
+                delta: Math.max(-1, Math.min(1, numeric)),
+                ...(typeof reason === "string" && reason.length > 0 && { reason }),
+            });
+        }
+        return deltas;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/pipeline/consolidator.d.ts

@@ -0,0 +1,62 @@
+import type { ContextEvent } from "../events/context-event.js";
+import type { ActionExecution } from "../actions/action.js";
+import type { Fact } from "../memory/fact.js";
+import type { MemoryStore } from "../memory/store.js";
+import type { Persona } from "../emotion/persona.js";
+import type { LLMClient } from "../llm/types.js";
+import { type WriteResult } from "./writer.js";
+export interface ConsolidateInput {
+    event: ContextEvent;
+    /** What the agent actually did this turn (the act stage's executions). */
+    executions: ActionExecution[];
+    /** The interpreter's account of what prompted the agent — context only. */
+    description: string;
+    /** Memories in play, so consolidation only records NEW facts. */
+    memories: Fact[];
+    persona?: Persona;
+}
+/**
+ * Writes memory from the agent's OWN actions. Where the writer records what
+ * happened TO the agent, the consolidator records what the agent DID — so a
+ * sent message like "great seeing you, I met Bill" leaves behind that the
+ * agent met Bill (and Bill becomes someone it knows). One method — swap it.
+ */
+export interface Consolidator {
+    consolidate(input: ConsolidateInput): Promise<WriteResult>;
+}
+export interface LLMConsolidatorOptions {
+    llm: LLMClient;
+    store: MemoryStore;
+    /** Cap on facts extracted per turn. Default 5. */
+    maxFacts?: number;
+    /** Similarity at/above which a candidate is a known duplicate. Default 0.85. */
+    duplicateThreshold?: number;
+    /** Similarity at/above which a same-kind/same-subject fact is superseded.
+     * Default 0.5. */
+    supersedeThreshold?: number;
+    maxTokens?: number;
+}
+/**
+ * Default consolidator. After the agent acts, it reads what the agent said
+ * and did and extracts durable facts about the agent and the people it named
+ * or interacted with — reusing the writer's extraction discipline and
+ * dedupe/supersede reconciliation, but from the agent's perspective.
+ */
+export declare class LLMConsolidator implements Consolidator {
+    private readonly llm;
+    private readonly store;
+    private readonly maxFacts;
+    private readonly duplicateThreshold;
+    private readonly supersedeThreshold;
+    private readonly maxTokens;
+    constructor(options: LLMConsolidatorOptions);
+    consolidate(input: ConsolidateInput): Promise<WriteResult>;
+    private systemPrompt;
+    private userPrompt;
+}
+/** Render the agent's content-bearing actions — those that produced text
+ * output (a sent message, a written note) — into lines the LLM can extract
+ * facts from. Param-only or empty actions (silence, a bare reaction) carry
+ * nothing durable, so they're skipped; "" means the agent produced no content
+ * this turn and consolidation can be skipped entirely. */
+export declare function summarizeExecutions(executions: ActionExecution[]): string;

package/dist/pipeline/consolidator.js

@@ -0,0 +1,98 @@
+import { WRITE_SCHEMA, parseCandidates, reconcile, } from "./writer.js";
+const EMPTY = () => ({ added: [], superseded: [], skipped: [] });
+/**
+ * Default consolidator. After the agent acts, it reads what the agent said
+ * and did and extracts durable facts about the agent and the people it named
+ * or interacted with — reusing the writer's extraction discipline and
+ * dedupe/supersede reconciliation, but from the agent's perspective.
+ */
+export class LLMConsolidator {
+    llm;
+    store;
+    maxFacts;
+    duplicateThreshold;
+    supersedeThreshold;
+    maxTokens;
+    constructor(options) {
+        this.llm = options.llm;
+        this.store = options.store;
+        this.maxFacts = options.maxFacts ?? 5;
+        this.duplicateThreshold = options.duplicateThreshold ?? 0.85;
+        this.supersedeThreshold = options.supersedeThreshold ?? 0.5;
+        this.maxTokens = options.maxTokens;
+    }
+    async consolidate(input) {
+        const did = summarizeExecutions(input.executions);
+        // Nothing with substance was done (silence, or side-effect-only actions
+        // with no content) — skip the LLM call entirely.
+        if (did === "")
+            return EMPTY();
+        const response = await this.llm.complete({
+            system: this.systemPrompt(input.persona),
+            messages: [
+                { role: "user", content: [{ type: "text", text: this.userPrompt(input, did) }] },
+            ],
+            jsonSchema: WRITE_SCHEMA,
+            ...(this.maxTokens !== undefined && { maxTokens: this.maxTokens }),
+        });
+        const candidates = parseCandidates(response.text, input.memories, this.maxFacts);
+        const result = EMPTY();
+        for (const candidate of candidates) {
+            await reconcile(candidate, {
+                store: this.store,
+                duplicateThreshold: this.duplicateThreshold,
+                supersedeThreshold: this.supersedeThreshold,
+                sourceEventId: input.event.id,
+                shownMemories: input.memories,
+                extraMetadata: { origin: "consolidation" },
+            }, result);
+        }
+        return result;
+    }
+    systemPrompt(persona) {
+        const who = persona ? `${persona.name}` : "the agent";
+        const identity = persona
+            ? `You are the memory-consolidation system of ${persona.name}: ${persona.summary}.`
+            : "You are the memory-consolidation system of an agent.";
+        return (identity +
+            ` The agent just acted. Below is what ${who} said and did. Extract the durable facts ${who} should remember from its OWN actions — about itself and about the people it named or interacted with.\n` +
+            "RULES:\n" +
+            `- EXTRACT from what ${who} did, don't transcribe it: store the underlying fact. "${who}: great seeing you, I met Bill last night" leaves behind that ${who} met someone named Bill — and that Bill is now someone ${who} knows.\n` +
+            '- ATOMIC: each fact is exactly ONE piece of information; split compound statements.\n' +
+            `- ESTABLISH PEOPLE: when the agent meets or names someone new, record them as a full fact (kind "user") so the relationship persists — e.g. "Bill is someone ${who} met at the gym." NEVER store a bare name like "Bill" or any fragment; every fact is a complete sentence.\n` +
+            `- DURABLE ONLY: keep names, identities, relationships, commitments ${who} made, plans, and significant dated events. DROP the act mechanics ("sent a message", "replied"), pleasantries, and ${who}'s feelings or mood.\n` +
+            "- NEW ONLY: record nothing already covered by KNOWN MEMORIES. If something corrects a known memory, output the corrected fact and set `replaces` to that memory's number.\n" +
+            `- STANDALONE: each fact must make sense years from now — real names (never "he"/"they"), absolute dates (the time is given), and name ${who} explicitly rather than saying "the agent" or "I".\n` +
+            '- kind: "user" (a person the agent now knows something about, incl. someone it just met), "event" (a real-world happening the agent did or referenced — never "a message was sent"), "self" (RARE: a concrete durable thing about the agent it revealed), "persona" (rare).\n' +
+            "- importance 0..1: trivia ~0.2, ordinary ~0.4-0.6, identity-defining or relationship-forming 0.7-0.9.\n" +
+            "- Prefer a FEW high-quality facts. An empty list is correct when the agent's actions revealed nothing durable.\n" +
+            'Respond with JSON only: {"facts": [{"kind": string, "content": string, "subject": string|null, "importance": number, "replaces": integer|null}]}.');
+    }
+    userPrompt(input, did) {
+        const known = input.memories.length === 0
+            ? "none"
+            : input.memories
+                .map((fact, i) => `${i + 1}. [${fact.kind}] ${fact.content}`)
+                .join("\n");
+        return (`TIME: ${input.event.occurredAt}\n\n` +
+            `CONTEXT (what prompted the agent — for grounding only, do not extract facts from this):\n${input.description}\n\n` +
+            `WHAT THE AGENT DID (extract durable facts from this):\n${did}\n\n` +
+            `KNOWN MEMORIES:\n${known}`);
+    }
+}
+/** Render the agent's content-bearing actions — those that produced text
+ * output (a sent message, a written note) — into lines the LLM can extract
+ * facts from. Param-only or empty actions (silence, a bare reaction) carry
+ * nothing durable, so they're skipped; "" means the agent produced no content
+ * this turn and consolidation can be skipped entirely. */
+export function summarizeExecutions(executions) {
+    const lines = [];
+    for (const execution of executions) {
+        if (execution.status !== "succeeded")
+            continue;
+        if (typeof execution.result === "string" && execution.result.trim() !== "") {
+            lines.push(`- ${execution.name}: "${execution.result.trim()}"`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/pipeline/inbox.d.ts

@@ -0,0 +1,60 @@
+import type { ContextEvent } from "../events/context-event.js";
+/**
+ * Returned by `enqueue` for an event that was folded into a later, merged
+ * heartbeat instead of producing its own result. The real result belongs to
+ * the merged event whose id is `into`; this caller should do nothing.
+ */
+export interface MergedOutcome {
+    merged: true;
+    /** Id of the merged event whose result covers this one. */
+    into: string;
+}
+/** What `enqueue` resolves to: the heartbeat result, or a merged marker. */
+export type EnqueueOutcome<R> = R | MergedOutcome;
+/** Narrow an enqueue outcome to the merged-marker case. */
+export declare function isMerged<R>(outcome: EnqueueOutcome<R>): outcome is MergedOutcome;
+/**
+ * Thrown by the runner at a cancellation checkpoint when its signal has
+ * aborted. The inbox catches it to mean "a new event arrived in time to
+ * merge — re-run the heartbeat with the bigger batch"; it is never a real
+ * failure.
+ */
+export declare class HeartbeatCancelled extends Error {
+    constructor();
+}
+export interface RunControls {
+    /** Aborts when a mergeable event arrives before the commit point; the
+     * runner must check it at its stage boundaries and throw HeartbeatCancelled. */
+    signal: AbortSignal;
+    /** Call synchronously the instant the heartbeat passes its last cancellable
+     * point (feelings about to persist). After this the inbox stops cancelling
+     * and routes new events to the next round. MUST be called with no `await`
+     * between the final checkpoint and this call, or the cancel/commit race is
+     * not airtight. */
+    onCommit(): void;
+}
+/** Runs one (already-merged) heartbeat under cancellation control. */
+export type HeartbeatRunner<R> = (event: ContextEvent, controls: RunControls) => Promise<R>;
+/**
+ * Per-instance event funnel. Serializes heartbeats (one at a time, killing
+ * the lost-feeling race that concurrent runs cause) and coalesces bursts: an
+ * event that arrives while the current heartbeat is still cancellable (before
+ * its feelings persist) is merged into it and the heartbeat re-runs as one.
+ * Once a heartbeat commits, later events wait for the next round.
+ *
+ * Generic over the result type so it carries no dependency on the Agent.
+ */
+export declare class InstanceInbox<R> {
+    private readonly run;
+    /** Waiters of the in-flight round (null when idle). The same array the
+     * running heartbeat reads, so a merged-in event is picked up on re-run. */
+    private round;
+    /** Waiters that arrived after the current round committed. */
+    private queued;
+    /** Has the in-flight round passed its last cancellable point. */
+    private committed;
+    private controller;
+    constructor(run: HeartbeatRunner<R>);
+    enqueue(event: ContextEvent): Promise<EnqueueOutcome<R>>;
+    private runRound;
+}

package/dist/pipeline/inbox.js

@@ -0,0 +1,107 @@
+import { mergeEvents } from "../events/merge.js";
+/** Narrow an enqueue outcome to the merged-marker case. */
+export function isMerged(outcome) {
+    return (typeof outcome === "object" &&
+        outcome !== null &&
+        outcome.merged === true);
+}
+/**
+ * Thrown by the runner at a cancellation checkpoint when its signal has
+ * aborted. The inbox catches it to mean "a new event arrived in time to
+ * merge — re-run the heartbeat with the bigger batch"; it is never a real
+ * failure.
+ */
+export class HeartbeatCancelled extends Error {
+    constructor() {
+        super("heartbeat cancelled for merge");
+        this.name = "HeartbeatCancelled";
+    }
+}
+/**
+ * Per-instance event funnel. Serializes heartbeats (one at a time, killing
+ * the lost-feeling race that concurrent runs cause) and coalesces bursts: an
+ * event that arrives while the current heartbeat is still cancellable (before
+ * its feelings persist) is merged into it and the heartbeat re-runs as one.
+ * Once a heartbeat commits, later events wait for the next round.
+ *
+ * Generic over the result type so it carries no dependency on the Agent.
+ */
+export class InstanceInbox {
+    run;
+    /** Waiters of the in-flight round (null when idle). The same array the
+     * running heartbeat reads, so a merged-in event is picked up on re-run. */
+    round = null;
+    /** Waiters that arrived after the current round committed. */
+    queued = [];
+    /** Has the in-flight round passed its last cancellable point. */
+    committed = false;
+    controller = null;
+    constructor(run) {
+        this.run = run;
+    }
+    enqueue(event) {
+        return new Promise((resolve, reject) => {
+            const waiter = { event, resolve, reject };
+            if (this.round === null) {
+                this.round = [waiter];
+                void this.runRound();
+            }
+            else if (!this.committed) {
+                // Still cancellable: fold in and restart as one merged heartbeat.
+                this.round.push(waiter);
+                this.controller?.abort();
+            }
+            else {
+                // Already committed its feelings — this belongs to the next round.
+                this.queued.push(waiter);
+            }
+        });
+    }
+    async runRound() {
+        for (;;) {
+            this.committed = false;
+            this.controller = new AbortController();
+            const waiters = this.round;
+            const merged = mergeEvents(waiters.map((w) => w.event));
+            try {
+                const result = await this.run(merged, {
+                    signal: this.controller.signal,
+                    onCommit: () => {
+                        this.committed = true;
+                    },
+                });
+                settleSuccess(waiters, merged.id, result);
+                break;
+            }
+            catch (error) {
+                // A merge folded a new waiter in and aborted us: re-run, bigger batch.
+                if (error instanceof HeartbeatCancelled)
+                    continue;
+                settleFailure(waiters, error);
+                break;
+            }
+        }
+        this.round = null;
+        this.controller = null;
+        // Drain anything that queued behind the committed round.
+        if (this.queued.length > 0) {
+            this.round = this.queued;
+            this.queued = [];
+            void this.runRound();
+        }
+    }
+}
+function settleSuccess(waiters, mergedId, result) {
+    // The most recent event owns the real result — the merged event carries
+    // its reply handle. Earlier events learn they were absorbed.
+    waiters.forEach((waiter, i) => {
+        if (i === waiters.length - 1)
+            waiter.resolve(result);
+        else
+            waiter.resolve({ merged: true, into: mergedId });
+    });
+}
+function settleFailure(waiters, error) {
+    for (const waiter of waiters)
+        waiter.reject(error);
+}

package/dist/pipeline/index.d.ts

@@ -0,0 +1,11 @@
+export { InterpreterRouter, type Interpretation, type Interpreter, } from "./interpretation.js";
+export { LLMInterpreter, parseInterpretation, type LLMInterpreterOptions, } from "./llm-interpreter.js";
+export { MemoryRecaller, type MemoryRecallerOptions, type Recaller, } from "./recaller.js";
+export { InterpretRecallLoop, type InterpretRecallLoopOptions, type InterpretRecallResult, type StopReason, } from "./loop.js";
+export { LLMAppraiser, parseDeltas, type AppraisalInput, type AppraisalResult, type Appraiser, type LLMAppraiserOptions, } from "./appraiser.js";
+export { DecayTimeAppraiser, LLMTimeAppraiser, type DecayTimeAppraiserOptions, type LLMTimeAppraiserOptions, type TimeAppraisalInput, type TimeAppraisalResult, type TimeAppraiser, } from "./time-appraiser.js";
+export { LLMWriter, parseCandidates, type FactCandidate, type LLMWriterOptions, type WriteInput, type WriteResult, type Writer, } from "./writer.js";
+export { LLMProcessor, parseSelections, type LLMProcessorOptions, type ProcessInput, type ProcessResult, type Processor, } from "./processor.js";
+export { DefaultActor, type ActInput, type ActResult, type Actor as PlanActor, } from "./actor.js";
+export { LLMConsolidator, summarizeExecutions, type Consolidator, type ConsolidateInput, type LLMConsolidatorOptions, } from "./consolidator.js";
+export { InstanceInbox, HeartbeatCancelled, isMerged, type EnqueueOutcome, type MergedOutcome, type HeartbeatRunner, type RunControls, } from "./inbox.js";

package/dist/pipeline/index.js

@@ -0,0 +1,11 @@
+export { InterpreterRouter, } from "./interpretation.js";
+export { LLMInterpreter, parseInterpretation, } from "./llm-interpreter.js";
+export { MemoryRecaller, } from "./recaller.js";
+export { InterpretRecallLoop, } from "./loop.js";
+export { LLMAppraiser, parseDeltas, } from "./appraiser.js";
+export { DecayTimeAppraiser, LLMTimeAppraiser, } from "./time-appraiser.js";
+export { LLMWriter, parseCandidates, } from "./writer.js";
+export { LLMProcessor, parseSelections, } from "./processor.js";
+export { DefaultActor, } from "./actor.js";
+export { LLMConsolidator, summarizeExecutions, } from "./consolidator.js";
+export { InstanceInbox, HeartbeatCancelled, isMerged, } from "./inbox.js";

package/dist/pipeline/interpretation.d.ts

@@ -0,0 +1,47 @@
+import type { ContextEvent } from "../events/context-event.js";
+import type { PayloadKind } from "../events/payload.js";
+import type { Fact } from "../memory/fact.js";
+import type { Engagement } from "../short-term/short-term.js";
+/** What an interpreter concluded about an event. */
+export interface Interpretation {
+    /** Rich, factual text description of what happened, grounded in the
+     * provided memories where they helped identify things. */
+    description: string;
+    /** The interpreter's self-report: is every notable element of the event
+     * explained by the event itself or a memory? */
+    fullyInterpreted: boolean;
+    /** Up to ~3 short search queries for what additional memory would help
+     * ("who is the woman in the photo"). Feed the recaller. */
+    gaps: string[];
+}
+/**
+ * Turns an event (plus whatever memories are in hand) into a description.
+ * The SDK ships LLMInterpreter (multimodal, handles every payload kind);
+ * specialized interpreters — e.g. a transcription-backed audio interpreter,
+ * a game-state interpreter — implement this same interface and are wired in
+ * per payload kind via {@link InterpreterRouter}.
+ */
+export interface Interpreter {
+    /**
+     * @param recent The agent's short-term window — recent engagements with this
+     * instance, for understanding replies and follow-ups. Omitted/empty on the
+     * neutral first pass of the loop.
+     */
+    interpret(event: ContextEvent, memories: Fact[], recent?: Engagement[]): Promise<Interpretation>;
+}
+/**
+ * Dispatches to a different Interpreter per payload kind, falling back to a
+ * default for unregistered kinds. This is how media types get split across
+ * specialized interpreters without the loop knowing or caring:
+ *
+ *   const interpreter = new InterpreterRouter(llmInterpreter)
+ *     .register("audio", new WhisperAudioInterpreter(...))
+ *     .register("video", new VideoFrameInterpreter(...));
+ */
+export declare class InterpreterRouter implements Interpreter {
+    private readonly fallback;
+    private readonly byKind;
+    constructor(fallback: Interpreter);
+    register(kind: PayloadKind, interpreter: Interpreter): this;
+    interpret(event: ContextEvent, memories: Fact[], recent?: Engagement[]): Promise<Interpretation>;
+}

package/dist/pipeline/interpretation.js

@@ -0,0 +1,24 @@
+/**
+ * Dispatches to a different Interpreter per payload kind, falling back to a
+ * default for unregistered kinds. This is how media types get split across
+ * specialized interpreters without the loop knowing or caring:
+ *
+ *   const interpreter = new InterpreterRouter(llmInterpreter)
+ *     .register("audio", new WhisperAudioInterpreter(...))
+ *     .register("video", new VideoFrameInterpreter(...));
+ */
+export class InterpreterRouter {
+    fallback;
+    byKind = new Map();
+    constructor(fallback) {
+        this.fallback = fallback;
+    }
+    register(kind, interpreter) {
+        this.byKind.set(kind, interpreter);
+        return this;
+    }
+    interpret(event, memories, recent) {
+        const interpreter = this.byKind.get(event.payload.kind) ?? this.fallback;
+        return interpreter.interpret(event, memories, recent);
+    }
+}

package/dist/pipeline/llm-interpreter.d.ts

@@ -0,0 +1,28 @@
+import type { ContextEvent } from "../events/context-event.js";
+import type { Fact } from "../memory/fact.js";
+import type { LLMClient } from "../llm/types.js";
+import { type Engagement } from "../short-term/short-term.js";
+import type { Interpretation, Interpreter } from "./interpretation.js";
+export interface LLMInterpreterOptions {
+    llm: LLMClient;
+    /** Optional one-line description of the agent, to anchor perspective
+     * ("You perceive on behalf of Lyra, a cellist..."). */
+    personaHint?: string;
+    maxTokens?: number;
+    /** Cap on `gaps` returned per interpretation. Default 3. */
+    maxGaps?: number;
+}
+/**
+ * The default multimodal interpreter: one LLM call that sees the event's
+ * text/images directly (audio/video via their transcripts or captions) plus
+ * the memories recalled so far, and produces a grounded description.
+ */
+export declare class LLMInterpreter implements Interpreter {
+    private readonly options;
+    constructor(options: LLMInterpreterOptions);
+    interpret(event: ContextEvent, memories: Fact[], recent?: Engagement[]): Promise<Interpretation>;
+    private systemPrompt;
+}
+/** Tolerant parse: providers without strict schema support may wrap the
+ * JSON in prose or fences. Worst case, the raw text becomes the description. */
+export declare function parseInterpretation(text: string, maxGaps: number): Interpretation;