emocentric 0.1.0

package/dist/pipeline/llm-interpreter.js

@@ -0,0 +1,173 @@
+import { renderEngagements } from "../short-term/short-term.js";
+const INTERPRETATION_SCHEMA = {
+    name: "interpretation",
+    schema: {
+        type: "object",
+        properties: {
+            description: { type: "string" },
+            fullyInterpreted: { type: "boolean" },
+            gaps: { type: "array", items: { type: "string" } },
+        },
+        required: ["description", "fullyInterpreted", "gaps"],
+        additionalProperties: false,
+    },
+};
+/**
+ * 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 class LLMInterpreter {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async interpret(event, memories, recent = []) {
+        const recentText = recentSection(recent, event.occurredAt);
+        const request = {
+            system: this.systemPrompt(),
+            messages: [
+                {
+                    role: "user",
+                    content: [
+                        ...(recentText ? [{ type: "text", text: recentText }] : []),
+                        { type: "text", text: eventHeader(event) },
+                        ...payloadToContent(event.payload),
+                        { type: "text", text: memoriesSection(memories) },
+                    ],
+                },
+            ],
+            jsonSchema: {
+                name: INTERPRETATION_SCHEMA.name,
+                schema: INTERPRETATION_SCHEMA.schema,
+            },
+            ...(this.options.maxTokens !== undefined && {
+                maxTokens: this.options.maxTokens,
+            }),
+        };
+        const response = await this.options.llm.complete(request);
+        return parseInterpretation(response.text, this.options.maxGaps ?? 3);
+    }
+    systemPrompt() {
+        const persona = this.options.personaHint
+            ? ` You perceive on behalf of this agent: ${this.options.personaHint}.`
+            : "";
+        return ("You are the perceptual system of an emotionally-driven agent." +
+            persona +
+            " Given an incoming event and the agent's relevant memories, state plainly and concisely what just happened, as the agent would understand it.\n" +
+            "- Be brief and to the point — usually one or two sentences. Keep the key content: who is involved and what they did or said, including any name or self-introduction, plan, or concrete fact the event reveals. Cut pleasantries and restating — but someone giving their name or sharing new information is key content, never filler.\n" +
+            "- If RECENT EXCHANGES are shown, use them to understand replies and follow-ups — what a 'yeah', a 'that', or a short answer refers to. They are the immediate conversation (with how long ago each happened); the memories below are durable facts.\n" +
+            "- Use the memories ONLY to resolve references — to identify who or what the event points to (e.g. 'my friend' → Jason when a memory says so). Weave in an identity only when a memory actually grounds it.\n" +
+            "- If the actor reveals their own name or identity (e.g. the sender says \"it's Roy\"), state it explicitly as the actor introducing themselves (e.g. 'the user introduces himself as Roy and …') — this is important new information the system may not have yet, not an already-known name.\n" +
+            "- Never invent or infer: do not add relationships, roles, backstory, or any detail not stated in the event or grounded in a memory (e.g. don't call someone a 'friend' or 'teammate' unless that is known). Unknowns stay unknown.\n" +
+            "- Describe, don't editorialize: no mood, tone, sentiment, or significance ('a warm message', 'a sense of camaraderie') — later stages do the feeling.\n" +
+            'Respond with JSON only: {"description": string, "fullyInterpreted": boolean, "gaps": string[]}.\n' +
+            "fullyInterpreted is true only when every notable element of the event is explained by the event itself or a memory. " +
+            "gaps lists at most 3 short memory-search queries that would fill what's unexplained (empty when nothing is missing).");
+    }
+}
+function eventHeader(event) {
+    const actor = event.actor.displayName
+        ? `${event.actor.displayName} (id ${event.actor.id})`
+        : `id ${event.actor.id}`;
+    const channel = event.channelId ? `; channel: ${event.channelId}` : "";
+    return `EVENT — platform: ${event.platform}; actor: ${actor}; time: ${event.occurredAt}${channel}. Payload follows:`;
+}
+function payloadToContent(payload) {
+    if (payload.kind === "composite") {
+        return payload.parts.flatMap((part, i) => [
+            { type: "text", text: `— part ${i + 1} of ${payload.parts.length} —` },
+            ...simplePayloadToContent(part),
+        ]);
+    }
+    return simplePayloadToContent(payload);
+}
+function simplePayloadToContent(payload) {
+    switch (payload.kind) {
+        case "text":
+            return [{ type: "text", text: `[text message]\n${payload.text}` }];
+        case "image":
+            return [
+                ...(payload.caption !== undefined
+                    ? [{ type: "text", text: `[image, caption: ${payload.caption}]` }]
+                    : [{ type: "text", text: "[image]" }]),
+                { type: "image", source: payload.source },
+            ];
+        case "audio":
+            return [
+                {
+                    type: "text",
+                    text: payload.transcript
+                        ? `[audio${durationNote(payload.durationMs)}, transcript follows]\n${payload.transcript}`
+                        : `[audio${durationNote(payload.durationMs)} — no transcript available; its spoken content is unknown]`,
+                },
+            ];
+        case "video":
+            return [
+                {
+                    type: "text",
+                    text: payload.transcript
+                        ? `[video${durationNote(payload.durationMs)}, transcript follows]\n${payload.transcript}`
+                        : `[video${durationNote(payload.durationMs)} — no transcript available; its content is unknown]`,
+                },
+            ];
+        case "action":
+            return [
+                {
+                    type: "text",
+                    text: `[platform action] name: ${payload.name}` +
+                        (payload.description ? `; description: ${payload.description}` : "") +
+                        (payload.data ? `; data: ${JSON.stringify(payload.data)}` : ""),
+                },
+            ];
+    }
+}
+function durationNote(durationMs) {
+    return durationMs !== undefined ? `, ~${Math.round(durationMs / 1000)}s` : "";
+}
+function memoriesSection(memories) {
+    if (memories.length === 0) {
+        return "MEMORIES: none retrieved yet (first pass).";
+    }
+    const lines = memories.map((fact, i) => `${i + 1}. [${fact.kind}] ${fact.content}`);
+    return `MEMORIES (${memories.length}):\n${lines.join("\n")}`;
+}
+/** The short-term window as a leading context block; "" when empty so the
+ * neutral first pass carries no recent context at all. */
+function recentSection(recent, now) {
+    const rendered = renderEngagements(recent, now);
+    if (rendered === "")
+        return "";
+    return `RECENT EXCHANGES (the immediate back-and-forth, most recent last; [how long ago] in brackets):\n${rendered}`;
+}
+/** Tolerant parse: providers without strict schema support may wrap the
+ * JSON in prose or fences. Worst case, the raw text becomes the description. */
+export function parseInterpretation(text, maxGaps) {
+    const candidate = extractJsonObject(text);
+    if (candidate) {
+        try {
+            const parsed = JSON.parse(candidate);
+            if (typeof parsed.description === "string") {
+                const gaps = Array.isArray(parsed.gaps)
+                    ? parsed.gaps
+                        .filter((g) => typeof g === "string" && g.length > 0)
+                        .slice(0, maxGaps)
+                    : [];
+                return {
+                    description: parsed.description,
+                    fullyInterpreted: parsed.fullyInterpreted === true,
+                    gaps,
+                };
+            }
+        }
+        catch {
+            // fall through to raw-text fallback
+        }
+    }
+    return { description: text.trim(), fullyInterpreted: false, gaps: [] };
+}
+function extractJsonObject(text) {
+    const start = text.indexOf("{");
+    const end = text.lastIndexOf("}");
+    return start !== -1 && end > start ? text.slice(start, end + 1) : null;
+}

package/dist/pipeline/loop.d.ts

@@ -0,0 +1,58 @@
+import type { ContextEvent } from "../events/context-event.js";
+import type { ScoredFact } from "../memory/store.js";
+import type { Engagement } from "../short-term/short-term.js";
+import type { Interpretation, Interpreter } from "./interpretation.js";
+import type { Recaller } from "./recaller.js";
+export type StopReason = 
+/** First recall found nothing — a second look would be identical. */
+"no-memories"
+/** A recall round surfaced no memory ids we hadn't already seen — the
+ * next description would be built from the same inputs. */
+ | "stabilized"
+/** The interpreter reported fullyInterpreted with no remaining gaps. */
+ | "fully-interpreted"
+/** Hit the iteration cap (cost/latency seatbelt). */
+ | "max-iterations";
+export interface InterpretRecallResult {
+    /** The final, memory-grounded description — input to appraiser/processor. */
+    description: string;
+    /** Full final interpretation (description + self-report + gaps). */
+    interpretation: Interpretation;
+    /** Memories relevant to the final description, ranked. */
+    memories: ScoredFact[];
+    /** Number of interpreter (LLM) calls made. */
+    iterations: number;
+    stopReason: StopReason;
+}
+export interface InterpretRecallLoopOptions {
+    interpreter: Interpreter;
+    recaller: Recaller;
+    /** Max interpreter calls per event. Default 3. */
+    maxIterations?: number;
+}
+/**
+ * The interpret → recall → reinterpret loop:
+ *
+ *   1. interpret the raw event with no memories
+ *   2. recall memories matching the description (and its gaps)
+ *   3. reinterpret with those memories in hand
+ *   4. repeat until no new memories turn up, the interpreter declares
+ *      itself done, or the iteration cap is reached
+ *
+ * Each iteration costs one LLM call; recalls are database-only.
+ */
+export declare class InterpretRecallLoop {
+    private readonly interpreter;
+    private readonly recaller;
+    private readonly maxIterations;
+    constructor(options: InterpretRecallLoopOptions);
+    /**
+     * @param recent The agent's short-term window. The FIRST interpret pass is
+     * always neutral — no memories AND no short-term context — for an unbiased
+     * read of the raw event. Recalled memories and `recent` join from the
+     * second pass. When `recent` is non-empty, the loop guarantees at least one
+     * context pass, so a simple first read can't skip the immediate thread.
+     */
+    run(event: ContextEvent, recent?: Engagement[]): Promise<InterpretRecallResult>;
+    private result;
+}

package/dist/pipeline/loop.js

@@ -0,0 +1,73 @@
+/**
+ * The interpret → recall → reinterpret loop:
+ *
+ *   1. interpret the raw event with no memories
+ *   2. recall memories matching the description (and its gaps)
+ *   3. reinterpret with those memories in hand
+ *   4. repeat until no new memories turn up, the interpreter declares
+ *      itself done, or the iteration cap is reached
+ *
+ * Each iteration costs one LLM call; recalls are database-only.
+ */
+export class InterpretRecallLoop {
+    interpreter;
+    recaller;
+    maxIterations;
+    constructor(options) {
+        this.interpreter = options.interpreter;
+        this.recaller = options.recaller;
+        this.maxIterations = Math.max(1, options.maxIterations ?? 3);
+    }
+    /**
+     * @param recent The agent's short-term window. The FIRST interpret pass is
+     * always neutral — no memories AND no short-term context — for an unbiased
+     * read of the raw event. Recalled memories and `recent` join from the
+     * second pass. When `recent` is non-empty, the loop guarantees at least one
+     * context pass, so a simple first read can't skip the immediate thread.
+     */
+    async run(event, recent = []) {
+        const seenIds = new Set();
+        let interpretation = await this.interpreter.interpret(event, [], []);
+        let iterations = 1;
+        let memories = [];
+        let usedRecent = false;
+        for (;;) {
+            const recalled = await this.recaller.recall(interpretation, event);
+            const hasNew = recalled.some((r) => !seenIds.has(r.fact.id));
+            // The neutral read is final only when there's nothing new to fold in:
+            // no fresh memories AND the short-term window has already been applied
+            // (or is empty), OR the neutral read already fully explained the event.
+            // Gating the forced STM pass on `!fullyInterpreted` means a self-contained
+            // event stops at one interpret call even when a window exists, while an
+            // ambiguous/relational one ("yeah", "my sister") still gets the context
+            // pass that resolves it.
+            const needContextPass = recent.length > 0 && !usedRecent && !interpretation.fullyInterpreted;
+            if (!hasNew && !needContextPass) {
+                return this.result(interpretation, memories.length > 0 ? memories : recalled, iterations, iterations === 1 ? "no-memories" : "stabilized");
+            }
+            for (const r of recalled)
+                seenIds.add(r.fact.id);
+            if (recalled.length > 0)
+                memories = recalled;
+            if (iterations >= this.maxIterations) {
+                return this.result(interpretation, memories, iterations, "max-iterations");
+            }
+            // Reinterpret WITH the short-term window and any recalled memories.
+            interpretation = await this.interpreter.interpret(event, memories.map((m) => m.fact), recent);
+            usedRecent = usedRecent || recent.length > 0;
+            iterations++;
+            if (interpretation.fullyInterpreted && interpretation.gaps.length === 0) {
+                return this.result(interpretation, memories, iterations, "fully-interpreted");
+            }
+        }
+    }
+    result(interpretation, memories, iterations, stopReason) {
+        return {
+            description: interpretation.description,
+            interpretation,
+            memories,
+            iterations,
+            stopReason,
+        };
+    }
+}

package/dist/pipeline/processor.d.ts

@@ -0,0 +1,63 @@
+import type { ContextEvent } from "../events/context-event.js";
+import type { Fact } from "../memory/fact.js";
+import { type Engagement } from "../short-term/short-term.js";
+import type { EmotionalState } from "../emotion/state.js";
+import type { Persona } from "../emotion/persona.js";
+import type { LLMClient } from "../llm/types.js";
+import { ActionPlan } from "../actions/action.js";
+import type { ActionRegistry } from "../actions/registry.js";
+export interface ProcessInput {
+    event: ContextEvent;
+    /** The interpret/recall loop's final, memory-grounded description. */
+    description: string;
+    memories: Fact[];
+    state: EmotionalState;
+    registry: ActionRegistry;
+    persona?: Persona;
+    /** The agent's short-term window, for staying coherent across the recent
+     * back-and-forth (not repeating itself, following up naturally). */
+    recent?: Engagement[];
+}
+export interface ProcessResult {
+    /** The chosen actions. The SDK never executes — call `plan.execute()`
+     * yourself (the agent decides, you act). */
+    plan: ActionPlan;
+}
+/**
+ * Decides what the agent does about an event. One method — swap in a
+ * rules-based or learned processor and the registry/callers don't change.
+ */
+export interface Processor {
+    process(input: ProcessInput): Promise<ProcessResult>;
+}
+export interface LLMProcessorOptions {
+    llm: LLMClient;
+    /** Cap on accepted actions per event. Default 5. */
+    maxActions?: number;
+    maxTokens?: number;
+}
+interface Selection {
+    name: string;
+    params: Record<string, unknown>;
+    reason?: string;
+}
+/**
+ * Default processor: one LLM call that sees the persona, every emotion's
+ * current value, the event description, the memories, and the action menu
+ * (with slots and param schemas) — and picks what to do, in character.
+ * Choosing nothing is valid. Slot conflicts are resolved first-pick-wins.
+ */
+export declare class LLMProcessor implements Processor {
+    private readonly llm;
+    private readonly maxActions;
+    private readonly maxTokens;
+    constructor(options: LLMProcessorOptions);
+    process(input: ProcessInput): Promise<ProcessResult>;
+    private systemPrompt;
+    private userPrompt;
+}
+/** Tolerant parse of processor output: extracts JSON from prose, defaults
+ * missing/invalid params to {}, drops malformed entries. Unparseable
+ * output yields an empty plan (the agent does nothing). */
+export declare function parseSelections(text: string): Selection[];
+export {};

package/dist/pipeline/processor.js

@@ -0,0 +1,144 @@
+import { renderEngagements } from "../short-term/short-term.js";
+import { ActionPlan, } from "../actions/action.js";
+/**
+ * Default processor: one LLM call that sees the persona, every emotion's
+ * current value, the event description, the memories, and the action menu
+ * (with slots and param schemas) — and picks what to do, in character.
+ * Choosing nothing is valid. Slot conflicts are resolved first-pick-wins.
+ */
+export class LLMProcessor {
+    llm;
+    maxActions;
+    maxTokens;
+    constructor(options) {
+        this.llm = options.llm;
+        this.maxActions = options.maxActions ?? 5;
+        this.maxTokens = options.maxTokens;
+    }
+    async process(input) {
+        const emotions = await input.state.snapshot();
+        const response = await this.llm.complete({
+            system: this.systemPrompt(input.persona),
+            messages: [
+                {
+                    role: "user",
+                    content: [{ type: "text", text: this.userPrompt(input, emotions) }],
+                },
+            ],
+            ...(this.maxTokens !== undefined && { maxTokens: this.maxTokens }),
+        });
+        const selections = parseSelections(response.text);
+        const accepted = [];
+        const droppedConflicts = [];
+        const unknownActions = [];
+        const takenSlots = new Set();
+        for (const selection of selections) {
+            const action = input.registry.get(selection.name);
+            if (!action) {
+                unknownActions.push(selection.name);
+                continue;
+            }
+            const planned = {
+                action,
+                params: selection.params,
+                ...(selection.reason !== undefined && { reason: selection.reason }),
+            };
+            if (action.slot !== undefined && takenSlots.has(action.slot)) {
+                droppedConflicts.push(planned);
+                continue;
+            }
+            if (accepted.length >= this.maxActions) {
+                droppedConflicts.push(planned);
+                continue;
+            }
+            if (action.slot !== undefined)
+                takenSlots.add(action.slot);
+            accepted.push(planned);
+        }
+        const context = {
+            event: input.event,
+            description: input.description,
+            memories: input.memories,
+            emotions,
+            ...(input.persona !== undefined && { persona: input.persona }),
+        };
+        const plan = new ActionPlan(accepted, droppedConflicts, unknownActions, context);
+        return { plan };
+    }
+    systemPrompt(persona) {
+        const identity = persona
+            ? `You are the action-selection system of ${persona.name}: ${persona.summary}.`
+            : "You are the action-selection system of an agent.";
+        return (identity +
+            " Given what just happened, what the agent remembers, and how the agent feels RIGHT NOW, choose what the agent does.\n" +
+            "- Let the current emotions drive the choice: high anger acts differently than high warmth. Stay in character.\n" +
+            "- If RECENT EXCHANGES are shown, stay coherent with them — don't repeat a message or question you just sent; follow up naturally.\n" +
+            "- Actions sharing a slot are mutually exclusive — pick at most one per slot.\n" +
+            "- Fill each action's params exactly per its schema (e.g. the actual words of a message, in the agent's voice).\n" +
+            "- Doing nothing is a valid choice: return an empty list when no action fits.\n" +
+            'Respond with JSON only, no prose: {"actions": [{"name": string, "params": object, "reason": string}]} ' +
+            'where each "params" is filled according to that action\'s params schema, ' +
+            'e.g. {"actions": [{"name": "send_message", "params": {"text": "the actual words to say"}, "reason": "..."}]}.');
+    }
+    userPrompt(input, emotions) {
+        const definitions = input.state.definitions();
+        const emotionLines = definitions.map((def) => `- ${def.name} (current ${(emotions[def.name] ?? def.baseline).toFixed(2)}): ${def.description}`);
+        const actionLines = input.registry.list().map((action) => {
+            const slot = action.slot !== undefined
+                ? ` (slot: ${action.slot} — at most one action from this slot)`
+                : "";
+            const params = action.paramsSchema
+                ? ` params schema: ${JSON.stringify(action.paramsSchema)}`
+                : " no params (use {})";
+            return `- ${action.name}${slot}: ${action.description}.${params}`;
+        });
+        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;
+        const recentText = renderEngagements(input.recent ?? [], input.event.occurredAt);
+        return (`CURRENT 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` +
+            (recentText
+                ? `RECENT EXCHANGES (most recent last; [how long ago] in brackets):\n${recentText}\n\n`
+                : "") +
+            `RELEVANT MEMORIES:\n${memoryLines}\n\n` +
+            `AVAILABLE ACTIONS:\n${actionLines.join("\n")}`);
+    }
+}
+/** Tolerant parse of processor output: extracts JSON from prose, defaults
+ * missing/invalid params to {}, drops malformed entries. Unparseable
+ * output yields an empty plan (the agent does nothing). */
+export function parseSelections(text) {
+    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.actions))
+            return [];
+        const selections = [];
+        for (const item of parsed.actions) {
+            if (typeof item !== "object" || item === null)
+                continue;
+            const { name, params, reason } = item;
+            if (typeof name !== "string" || name.trim() === "")
+                continue;
+            selections.push({
+                name: name.trim(),
+                params: typeof params === "object" && params !== null && !Array.isArray(params)
+                    ? params
+                    : {},
+                ...(typeof reason === "string" && reason.length > 0 && { reason }),
+            });
+        }
+        return selections;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/pipeline/recaller.d.ts

@@ -0,0 +1,34 @@
+import type { ContextEvent } from "../events/context-event.js";
+import type { MemoryStore, ScoredFact } from "../memory/store.js";
+import type { Interpretation } from "./interpretation.js";
+/**
+ * Finds memories relevant to an interpretation. No LLM involved — this is
+ * a pure memory lookup, so it's cheap to run every loop iteration.
+ * Swappable like everything else (e.g. an LLM-powered query planner).
+ */
+export interface Recaller {
+    recall(interpretation: Interpretation, event: ContextEvent): Promise<ScoredFact[]>;
+}
+export interface MemoryRecallerOptions {
+    store: MemoryStore;
+    /** Per-query fetch cap. Default: unbounded — return every fact above the
+     * store's relevance floor (no fixed top-K). */
+    limitPerQuery?: number;
+    /** Cap on the merged result set. Default: unbounded — the floor bounds it. */
+    totalLimit?: number;
+    /** Forwarded to MemoryStore.fetch. */
+    minScore?: number;
+}
+/**
+ * Default recaller: searches memory once with the full description and once
+ * per gap the interpreter flagged ("who is the woman in the photo"), then
+ * merges by fact id keeping each fact's best score.
+ */
+export declare class MemoryRecaller implements Recaller {
+    private readonly store;
+    private readonly limitPerQuery;
+    private readonly totalLimit;
+    private readonly minScore;
+    constructor(options: MemoryRecallerOptions);
+    recall(interpretation: Interpretation, _event: ContextEvent): Promise<ScoredFact[]>;
+}

package/dist/pipeline/recaller.js

@@ -0,0 +1,38 @@
+/**
+ * Default recaller: searches memory once with the full description and once
+ * per gap the interpreter flagged ("who is the woman in the photo"), then
+ * merges by fact id keeping each fact's best score.
+ */
+export class MemoryRecaller {
+    store;
+    limitPerQuery;
+    totalLimit;
+    minScore;
+    constructor(options) {
+        this.store = options.store;
+        this.limitPerQuery = options.limitPerQuery;
+        this.totalLimit = options.totalLimit;
+        this.minScore = options.minScore;
+    }
+    async recall(interpretation, _event) {
+        const queries = [interpretation.description, ...interpretation.gaps].filter((q) => q.trim().length > 0);
+        const merged = new Map();
+        for (const text of queries) {
+            const results = await this.store.fetch({
+                text,
+                ...(this.limitPerQuery !== undefined && { limit: this.limitPerQuery }),
+                ...(this.minScore !== undefined && { minScore: this.minScore }),
+            });
+            for (const result of results) {
+                const existing = merged.get(result.fact.id);
+                if (!existing || result.score > existing.score) {
+                    merged.set(result.fact.id, result);
+                }
+            }
+        }
+        const ranked = [...merged.values()].sort((a, b) => b.score - a.score);
+        return this.totalLimit !== undefined
+            ? ranked.slice(0, this.totalLimit)
+            : ranked;
+    }
+}

package/dist/pipeline/time-appraiser.d.ts

@@ -0,0 +1,85 @@
+import type { ContextEvent } from "../events/context-event.js";
+import type { EmotionDelta, EmotionSnapshot } from "../emotion/definitions.js";
+import type { Persona } from "../emotion/persona.js";
+import { type EmotionalState } from "../emotion/state.js";
+import type { LLMClient } from "../llm/types.js";
+import { type Engagement } from "../short-term/short-term.js";
+export interface TimeAppraisalInput {
+    state: EmotionalState;
+    /** Advance feelings to this moment — usually the incoming event's
+     * occurredAt. Defaults to the current time. */
+    now?: string;
+    /** Unused by the math implementation; carried so an LLM-based time
+     * appraiser (which reasons about HOW downtime felt) slots in without
+     * changing call sites. */
+    event?: ContextEvent;
+    /** The short-term window (timestamped). Unused by the math implementation;
+     * an LLM time-appraiser reasons about how the gap felt given the recent
+     * thread (e.g. silence after an argument). */
+    recent?: Engagement[];
+    /** Default true. False = dry run: deltas + projected `after`, state untouched. */
+    apply?: boolean;
+}
+export interface TimeAppraisalResult {
+    /** Actual movements (after − before), with human-readable reasons. */
+    deltas: EmotionDelta[];
+    before: EmotionSnapshot;
+    after: EmotionSnapshot;
+    applied: boolean;
+}
+/**
+ * The "time passes" stage. Runs when an event arrives, BEFORE the
+ * interpret/recall loop: feelings advance to the present moment first, then
+ * the event itself is appraised. One method — swap the math for an LLM (or
+ * anything else) by implementing it.
+ */
+export interface TimeAppraiser {
+    appraise(input: TimeAppraisalInput): Promise<TimeAppraisalResult>;
+}
+export interface DecayTimeAppraiserOptions {
+    /** Half-life for emotions that don't specify their own. Default 240 (4h). */
+    defaultHalfLifeMinutes?: number;
+}
+/**
+ * Mathematical time appraisal: every emotion drifts exponentially toward
+ * its baseline, each from its own last-touched timestamp, with per-emotion
+ * (or persona-temperament) half-life overrides. Deterministic, no LLM call.
+ * Decay is written via state.set() — exact targets, no sensitivity scaling.
+ */
+export declare class DecayTimeAppraiser implements TimeAppraiser {
+    private readonly defaultHalfLifeMinutes;
+    constructor(options?: DecayTimeAppraiserOptions);
+    appraise(input: TimeAppraisalInput): Promise<TimeAppraisalResult>;
+}
+export interface LLMTimeAppraiserOptions {
+    llm: LLMClient;
+    /** Summary + dispositions go into the prompt so the drift is in character. */
+    persona?: Persona;
+    /** Skip the LLM (a no-op) when less than this much time has passed — rapid
+     * exchanges aren't "downtime" and decay over a couple minutes is negligible.
+     * Default 2. Set 0 to always call. */
+    minGapMinutes?: number;
+    maxTokens?: number;
+}
+/**
+ * LLM time appraisal: instead of pure exponential decay, one LLM call reasons
+ * about how the DOWNTIME felt — given how long it's been and the recent thread
+ * (short-term memory, timestamped). Feelings still generally fade toward
+ * baseline, but context can sustain or even grow them (anger that stays warm,
+ * missing someone over a long silence). Returns per-emotion deltas, applied
+ * like the event appraiser's.
+ *
+ * MUST run past the heartbeat's commit point (the Agent places it there): it
+ * makes an LLM call and is non-deterministic, so it must fire exactly once —
+ * a coalesced/cancelled heartbeat would otherwise re-run it.
+ */
+export declare class LLMTimeAppraiser implements TimeAppraiser {
+    private readonly llm;
+    private readonly persona;
+    private readonly minGapMinutes;
+    private readonly maxTokens;
+    constructor(options: LLMTimeAppraiserOptions);
+    appraise(input: TimeAppraisalInput): Promise<TimeAppraisalResult>;
+    private systemPrompt;
+    private userPrompt;
+}