emocentric 0.1.0

package/dist/pipeline/time-appraiser.js

@@ -0,0 +1,189 @@
+import { decayValue, projectDeltas, } from "../emotion/state.js";
+import { relativeTime, renderEngagements, } from "../short-term/short-term.js";
+import { parseDeltas } from "./appraiser.js";
+/** Moves smaller than this are skipped (no DB churn for noise). */
+const MIN_MOVE = 0.001;
+/**
+ * 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 class DecayTimeAppraiser {
+    defaultHalfLifeMinutes;
+    constructor(options = {}) {
+        this.defaultHalfLifeMinutes = options.defaultHalfLifeMinutes ?? 240;
+    }
+    async appraise(input) {
+        const apply = input.apply ?? true;
+        const now = input.now !== undefined ? Date.parse(input.now) : Date.now();
+        if (Number.isNaN(now)) {
+            throw new TypeError(`TimeAppraisalInput.now is not a date: ${input.now}`);
+        }
+        const definitions = new Map(input.state.definitions().map((d) => [d.name, d]));
+        const entries = await input.state.entries();
+        const before = {};
+        const targets = {};
+        const deltas = [];
+        for (const entry of entries) {
+            const def = definitions.get(entry.name);
+            if (!def)
+                continue;
+            before[entry.name] = entry.value;
+            const elapsedMs = Math.max(0, now - Date.parse(entry.updatedAt));
+            const halfLife = def.halfLifeMinutes ?? this.defaultHalfLifeMinutes;
+            const target = decayValue(entry.value, def.baseline, elapsedMs, halfLife);
+            if (Math.abs(target - entry.value) >= MIN_MOVE) {
+                targets[entry.name] = target;
+                deltas.push({
+                    emotion: entry.name,
+                    delta: target - entry.value,
+                    reason: `time passed (~${formatElapsed(elapsedMs)}): drifting toward baseline ${def.baseline}`,
+                });
+            }
+        }
+        let after;
+        if (deltas.length === 0) {
+            after = { ...before };
+        }
+        else if (apply) {
+            // Stamp the decayed values AS OF the appraisal moment, not wall clock:
+            // each slider's last-touched time then reflects when its value is
+            // current, so the next event measures the true elapsed gap. (Only
+            // sliders that moved are written, and a slider moves only when the
+            // moment is later than its last touch — so this never rewinds a stamp.)
+            after = await input.state.set(targets, new Date(now).toISOString());
+        }
+        else {
+            after = { ...before };
+            for (const [name, value] of Object.entries(targets)) {
+                if (typeof value === "number")
+                    after[name] = value;
+            }
+        }
+        return { deltas, before, after, applied: apply };
+    }
+}
+function formatElapsed(elapsedMs) {
+    const minutes = elapsedMs / 60_000;
+    if (minutes < 90)
+        return `${Math.round(minutes)}m`;
+    const hours = minutes / 60;
+    if (hours < 48)
+        return `${hours.toFixed(1)}h`;
+    return `${(hours / 24).toFixed(1)}d`;
+}
+const TIME_DELTAS_SCHEMA = {
+    name: "time_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,
+    },
+};
+/**
+ * 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 class LLMTimeAppraiser {
+    llm;
+    persona;
+    minGapMinutes;
+    maxTokens;
+    constructor(options) {
+        this.llm = options.llm;
+        this.persona = options.persona;
+        this.minGapMinutes = options.minGapMinutes ?? 2;
+        this.maxTokens = options.maxTokens;
+    }
+    async appraise(input) {
+        const apply = input.apply ?? true;
+        const nowMs = input.now !== undefined ? Date.parse(input.now) : Date.now();
+        if (Number.isNaN(nowMs)) {
+            throw new TypeError(`TimeAppraisalInput.now is not a date: ${input.now}`);
+        }
+        const nowIso = new Date(nowMs).toISOString();
+        const definitions = input.state.definitions();
+        const before = await input.state.snapshot();
+        const entries = await input.state.entries();
+        // The gap since feelings were last current. Below the threshold, decay is
+        // negligible — skip the call entirely (rapid back-and-forth isn't downtime).
+        const lastTouched = entries.reduce((max, e) => Math.max(max, Date.parse(e.updatedAt) || 0), 0);
+        const gapMs = Math.max(0, nowMs - lastTouched);
+        if (gapMs < this.minGapMinutes * 60_000) {
+            return { deltas: [], before, after: before, applied: apply };
+        }
+        const response = await this.llm.complete({
+            system: this.systemPrompt(),
+            messages: [
+                {
+                    role: "user",
+                    content: [{ type: "text", text: this.userPrompt(input, entries, nowIso) }],
+                },
+            ],
+            jsonSchema: TIME_DELTAS_SCHEMA,
+            ...(this.maxTokens !== undefined && { maxTokens: this.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() {
+        const identity = this.persona
+            ? `You are the emotional processing of ${this.persona.name}: ${this.persona.summary}.`
+            : "You are the emotional processing of an agent.";
+        return (identity +
+            " Time has passed since the agent was last active. No new event has happened — decide how the DOWNTIME itself shifted each feeling.\n" +
+            "- Feelings fade toward baseline as time passes: a few minutes barely moves anything; an hour or two softens strong feelings; a day or more largely returns to baseline.\n" +
+            "- Context can override simple fading: dwelling on an argument can keep anger warm or let hurt grow; a long silence can grow longing or unease; excitement can settle into calm contentment.\n" +
+            "- Deltas are -1..1 and are usually gentle. Only include emotions that should move; give each a short reason that references how much time passed.\n" +
+            "- React in character — the dispositions describe how this agent tends to feel.\n" +
+            'Respond with JSON only: {"deltas": [{"emotion": string, "delta": number, "reason": string}]}.');
+    }
+    userPrompt(input, entries, nowIso) {
+        const dispositions = new Map((this.persona?.temperament ?? [])
+            .filter((t) => t.disposition)
+            .map((t) => [t.emotion, t.disposition]));
+        const byName = new Map(entries.map((e) => [e.name, e]));
+        const emotionLines = input.state.definitions().map((def) => {
+            const entry = byName.get(def.name);
+            const value = entry?.value ?? def.baseline;
+            const ago = entry ? relativeTime(entry.updatedAt, nowIso) : "unknown";
+            const disposition = dispositions.get(def.name);
+            return (`- ${def.name} (current ${value.toFixed(2)}, baseline ${def.baseline.toFixed(2)}, last moved ${ago}): ${def.description}` +
+                (disposition ? ` [disposition: ${disposition}]` : ""));
+        });
+        const recentText = renderEngagements(input.recent ?? [], nowIso);
+        return (`IT IS NOW ${nowIso}. No new event yet — only time has passed since the agent was last active.\n\n` +
+            `EMOTIONS (value 0..1; "last moved" is how long ago each was last updated):\n${emotionLines.join("\n")}\n\n` +
+            (recentText
+                ? `WHAT WAS ON THE AGENT'S MIND (recent thread, most recent last; [how long ago] in brackets):\n${recentText}`
+                : "No recent thread — let feelings settle toward baseline by the elapsed time."));
+    }
+}

package/dist/pipeline/writer.d.ts

@@ -0,0 +1,113 @@
+import type { ContextEvent } from "../events/context-event.js";
+import type { Fact, FactKind } 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 { AppraisalResult } from "./appraiser.js";
+/** A fact the extraction phase proposed, before reconciliation. */
+export interface FactCandidate {
+    kind: FactKind;
+    content: string;
+    subjectId?: string;
+    importance: number;
+    /** Id of an existing memory the LLM says this contradicts/updates. */
+    replacesFactId?: string;
+}
+export interface WriteInput {
+    event: ContextEvent;
+    /** The interpret/recall loop's final, memory-grounded description. */
+    description: string;
+    /** The memories that were recalled for this event — shown to the LLM so
+     * it only extracts NEW information and can flag contradictions. */
+    memories: Fact[];
+    /** Emotional salience guide: bigger feelings → more important memories. */
+    appraisal?: AppraisalResult;
+    persona?: Persona;
+}
+/** A receipt of what the write did. Callers may ignore it (the spec's
+ * "output: none") — it exists for logging, debugging, and tests. */
+export interface WriteResult {
+    added: Fact[];
+    superseded: Array<{
+        old: Fact;
+        replacement: Fact;
+    }>;
+    skipped: Array<{
+        candidate: FactCandidate;
+        existing: Fact;
+    }>;
+}
+/**
+ * Decides what an event leaves behind in long-term memory. One method —
+ * swap the implementation and the rest of the SDK keeps working.
+ */
+export interface Writer {
+    write(input: WriteInput): Promise<WriteResult>;
+}
+export interface LLMWriterOptions {
+    llm: LLMClient;
+    store: MemoryStore;
+    /** Cap on facts extracted per event. Default 5. */
+    maxFacts?: number;
+    /** Similarity at/above which a candidate is an already-known duplicate
+     * and is skipped. Default 0.85. */
+    duplicateThreshold?: number;
+    /** Similarity at/above which a same-kind, same-subject existing fact is
+     * automatically superseded by the candidate. Default 0.5. */
+    supersedeThreshold?: number;
+    maxTokens?: number;
+}
+export declare const WRITE_SCHEMA: {
+    name: string;
+    schema: Record<string, unknown>;
+};
+/**
+ * Default writer. Two phases:
+ *
+ * 1. EXTRACTION (one LLM call) — propose standalone fact sentences with
+ *    kind/subject/importance, flagging which shown memory each one
+ *    contradicts ("replaces"), if any.
+ * 2. RECONCILIATION (no LLM) — per candidate, search memory for lookalikes:
+ *    near-duplicates are skipped; LLM-flagged contradictions supersede the
+ *    old fact; same-kind/same-subject near-matches auto-supersede (except
+ *    `event` facts, which are history and never auto-superseded); the rest
+ *    are stored as new. Superseded facts are kept, pointing at their
+ *    replacement. Every stored fact carries metadata.sourceEventId.
+ */
+export declare class LLMWriter implements Writer {
+    private readonly llm;
+    private readonly store;
+    private readonly maxFacts;
+    private readonly duplicateThreshold;
+    private readonly supersedeThreshold;
+    private readonly maxTokens;
+    constructor(options: LLMWriterOptions);
+    write(input: WriteInput): Promise<WriteResult>;
+    private systemPrompt;
+    private userPrompt;
+}
+/** Everything {@link reconcile} needs to fold one candidate into the store. */
+export interface ReconcileContext {
+    store: MemoryStore;
+    /** At/above this similarity, the candidate is a known duplicate (skipped). */
+    duplicateThreshold: number;
+    /** At/above this, a same-kind/same-subject existing fact is superseded. */
+    supersedeThreshold: number;
+    /** Stamped onto the stored fact's metadata for provenance. */
+    sourceEventId: string;
+    /** The memories shown to the LLM, for resolving an LLM-directed `replaces`. */
+    shownMemories: Fact[];
+    /** Extra metadata merged into the stored fact (e.g. which stage wrote it). */
+    extraMetadata?: Record<string, unknown>;
+}
+/**
+ * Fold one candidate fact into memory, shared by the writer and the
+ * consolidator: skip near-duplicates; store the rest; supersede an
+ * LLM-flagged contradiction, or a same-kind/same-subject near-match (never an
+ * `event` — those are history). Mutates `result` with what happened.
+ */
+export declare function reconcile(candidate: FactCandidate, ctx: ReconcileContext, result: WriteResult): Promise<void>;
+/** Tolerant parse of extraction output. Resolves `replaces` numbers against
+ * the shown memories; drops malformed entries; clamps importance; caps the
+ * batch. Unparseable output yields an empty list (nothing remembered). */
+export declare function parseCandidates(text: string, shownMemories: Fact[], maxFacts: number): FactCandidate[];

package/dist/pipeline/writer.js

@@ -0,0 +1,210 @@
+import { clamp01 } from "../memory/scoring.js";
+export const WRITE_SCHEMA = {
+    name: "memory_write",
+    schema: {
+        type: "object",
+        properties: {
+            facts: {
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: {
+                        kind: { type: "string" },
+                        content: { type: "string" },
+                        subject: { type: ["string", "null"] },
+                        importance: { type: "number" },
+                        replaces: { type: ["integer", "null"] },
+                    },
+                    required: ["kind", "content", "subject", "importance", "replaces"],
+                    additionalProperties: false,
+                },
+            },
+        },
+        required: ["facts"],
+        additionalProperties: false,
+    },
+};
+/**
+ * Default writer. Two phases:
+ *
+ * 1. EXTRACTION (one LLM call) — propose standalone fact sentences with
+ *    kind/subject/importance, flagging which shown memory each one
+ *    contradicts ("replaces"), if any.
+ * 2. RECONCILIATION (no LLM) — per candidate, search memory for lookalikes:
+ *    near-duplicates are skipped; LLM-flagged contradictions supersede the
+ *    old fact; same-kind/same-subject near-matches auto-supersede (except
+ *    `event` facts, which are history and never auto-superseded); the rest
+ *    are stored as new. Superseded facts are kept, pointing at their
+ *    replacement. Every stored fact carries metadata.sourceEventId.
+ */
+export class LLMWriter {
+    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 write(input) {
+        const response = await this.llm.complete({
+            system: this.systemPrompt(input.persona),
+            messages: [
+                { role: "user", content: [{ type: "text", text: this.userPrompt(input) }] },
+            ],
+            jsonSchema: WRITE_SCHEMA,
+            ...(this.maxTokens !== undefined && { maxTokens: this.maxTokens }),
+        });
+        const candidates = parseCandidates(response.text, input.memories, this.maxFacts);
+        const result = { added: [], superseded: [], skipped: [] };
+        for (const candidate of candidates) {
+            await reconcile(candidate, {
+                store: this.store,
+                duplicateThreshold: this.duplicateThreshold,
+                supersedeThreshold: this.supersedeThreshold,
+                sourceEventId: input.event.id,
+                shownMemories: input.memories,
+            }, result);
+        }
+        return result;
+    }
+    systemPrompt(persona) {
+        const identity = persona
+            ? `You are the memory-encoding system of ${persona.name}: ${persona.summary}.`
+            : "You are the memory-encoding system of an agent.";
+        return (identity +
+            " Your job is to EXTRACT durable facts worth remembering — not to summarize or restate what happened. Read the account below and pull out the concrete information that will still matter in future conversations. Most messages leave behind little or nothing.\n" +
+            "RULES:\n" +
+            '- EXTRACT, don\'t transcribe: store the underlying fact, never the message or the narrative. "yo wsg it\'s Roy" leaves behind ONE fact — that the person\'s name is Roy — NOT that they greeted you or asked how you are.\n' +
+            '- ATOMIC: each fact is exactly ONE piece of information. Never join two things with "and"; split them into separate facts.\n' +
+            "- DURABLE ONLY: keep concrete, lasting information — names, identity, relationships, stable preferences, traits, commitments, and significant dated events.\n" +
+            "- NEVER store any of these — they are NOT facts: the agent's own feelings, mood, or emotional reaction; the agent's persona or a trait it already has (the persona is given, not learned); atmosphere, tone, or inferred sentiment (e.g. \"camaraderie\", \"a welcome connection\", \"reinforces his fondness\"); or the mechanics of the exchange (that a message arrived, that someone greeted you or asked a question).\n" +
+            "- Record only what is concretely stated or unambiguously implied by the speaker — never the account's embellishment, mood, or vibe, and never something you inferred to be likely.\n" +
+            "- NEW ONLY: record nothing already covered by KNOWN MEMORIES. If the event corrects or updates 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 with no surrounding context — use real names (never pronouns like "he", "they", or "the user") and absolute dates (the event time is provided).\n' +
+            '- kind: "persona" (who the agent is — rare), "self" (RARE: a concrete, durable thing the agent newly LEARNED about itself through what happened — never a mood, introspection, or a trait it already has), "user" (durable information about a person), "event" (a real-world happening worth remembering — a move, a new job, an injury, a milestone). A turn in THIS conversation is never an event: a greeting, a question someone asked, or a message being sent or received is NOT an event.\n' +
+            "- importance 0..1: trivia ~0.2, ordinary ~0.4-0.6, identity-defining (names, relationships) or emotionally significant 0.7-0.9. The EMOTIONAL IMPACT section is only a guide to importance — it is never something to store.\n" +
+            "- Prefer a FEW high-quality facts. An empty list is the correct — and common — answer when nothing durable was shared.\n" +
+            "HOW TO EXTRACT (account → what to store):\n" +
+            '- "Roy greets you warmly and introduces himself; you feel a flash of affection." → one user fact: the person\'s name is Roy. (drop the greeting AND the feeling)\n' +
+            '- "Maya mentions her sister Dana borrowed her car last Tuesday and still hasn\'t returned it." → two facts: Maya has a sister named Dana; and a dated event — Dana borrowed Maya\'s car and has not returned it.\n' +
+            '- "An old friend asks how your week is going, which lifts your mood." → nothing durable; store nothing. (a question and a mood are not facts)\n' +
+            'Respond with JSON only: {"facts": [{"kind": string, "content": string, "subject": string|null, "importance": number, "replaces": integer|null}]}.');
+    }
+    userPrompt(input) {
+        const actor = input.event.actor.displayName
+            ? `${input.event.actor.displayName} (id ${input.event.actor.id})`
+            : `id ${input.event.actor.id}`;
+        const deltas = input.appraisal?.deltas ?? [];
+        const emotionalImpact = deltas.length === 0
+            ? "none notable"
+            : deltas
+                .map((d) => `${d.emotion} ${d.delta >= 0 ? "+" : ""}${d.delta.toFixed(2)}` +
+                (d.reason ? ` — ${d.reason}` : ""))
+                .join("\n");
+        const known = input.memories.length === 0
+            ? "none"
+            : input.memories
+                .map((fact, i) => `${i + 1}. [${fact.kind}] ${fact.content}`)
+                .join("\n");
+        return (`EVENT — platform: ${input.event.platform}; actor: ${actor}; time: ${input.event.occurredAt}.\n` +
+            `If a fact is about the actor, set "subject" to "${input.event.actor.id}".\n\n` +
+            `ACCOUNT OF WHAT HAPPENED (extract the durable facts from this; most of it is not worth storing):\n${input.description}\n\n` +
+            `EMOTIONAL IMPACT (how strongly the agent reacted — use ONLY to weight importance; never store any of this as a fact):\n${emotionalImpact}\n\n` +
+            `KNOWN MEMORIES:\n${known}`);
+    }
+}
+/**
+ * Fold one candidate fact into memory, shared by the writer and the
+ * consolidator: skip near-duplicates; store the rest; supersede an
+ * LLM-flagged contradiction, or a same-kind/same-subject near-match (never an
+ * `event` — those are history). Mutates `result` with what happened.
+ */
+export async function reconcile(candidate, ctx, result) {
+    const similar = await ctx.store.fetch({ text: candidate.content, limit: 3 });
+    const top = similar[0];
+    if (top && top.relevance >= ctx.duplicateThreshold) {
+        result.skipped.push({ candidate, existing: top.fact });
+        return;
+    }
+    const [fact] = await ctx.store.add([
+        {
+            kind: candidate.kind,
+            content: candidate.content,
+            importance: candidate.importance,
+            ...(candidate.subjectId !== undefined && { subjectId: candidate.subjectId }),
+            metadata: { sourceEventId: ctx.sourceEventId, ...ctx.extraMetadata },
+        },
+    ]);
+    result.added.push(fact);
+    // LLM-directed supersede takes precedence over the similarity heuristic.
+    let target;
+    if (candidate.replacesFactId !== undefined) {
+        target = ctx.shownMemories.find((m) => m.id === candidate.replacesFactId);
+    }
+    else if (top &&
+        top.relevance >= ctx.supersedeThreshold &&
+        top.fact.kind === candidate.kind &&
+        top.fact.kind !== "event" &&
+        top.fact.subjectId === candidate.subjectId) {
+        target = top.fact;
+    }
+    if (target && target.supersededBy === undefined) {
+        const updated = await ctx.store.update(target.id, { supersededBy: fact.id });
+        if (updated) {
+            result.superseded.push({ old: updated, replacement: fact });
+        }
+    }
+}
+/** Tolerant parse of extraction output. Resolves `replaces` numbers against
+ * the shown memories; drops malformed entries; clamps importance; caps the
+ * batch. Unparseable output yields an empty list (nothing remembered). */
+export function parseCandidates(text, shownMemories, maxFacts) {
+    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.facts))
+            return [];
+        const candidates = [];
+        for (const item of parsed.facts) {
+            if (candidates.length >= maxFacts)
+                break;
+            if (typeof item !== "object" || item === null)
+                continue;
+            const { kind, content, subject, importance, replaces } = item;
+            if (typeof kind !== "string" || kind.trim() === "")
+                continue;
+            if (typeof content !== "string" || content.trim() === "")
+                continue;
+            const replacesIndex = typeof replaces === "number" && Number.isInteger(replaces)
+                ? replaces
+                : undefined;
+            const replacesFact = replacesIndex !== undefined &&
+                replacesIndex >= 1 &&
+                replacesIndex <= shownMemories.length
+                ? shownMemories[replacesIndex - 1]
+                : undefined;
+            candidates.push({
+                kind: kind.trim(),
+                content: content.trim(),
+                importance: clamp01(typeof importance === "number" ? importance : 0.5),
+                ...(typeof subject === "string" &&
+                    subject.trim() !== "" && { subjectId: subject.trim() }),
+                ...(replacesFact !== undefined && { replacesFactId: replacesFact.id }),
+            });
+        }
+        return candidates;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/postgres/create-instance.d.ts

@@ -0,0 +1,107 @@
+import pg from "pg";
+import { Agent, type AgentOptions, type AgentResult } from "../agent.js";
+import type { ContextEvent } from "../events/context-event.js";
+import type { EnqueueOutcome } from "../pipeline/inbox.js";
+import type { LLMClient } from "../llm/types.js";
+import type { Embedder } from "../memory/store.js";
+import { type ActionExecutor, type AgentBlueprint } from "../blueprint/blueprint.js";
+import { type InstanceScope } from "../blueprint/scope.js";
+import { PostgresMemoryStore } from "./store.js";
+import { PostgresEmotionalState } from "./emotional-state.js";
+import { PostgresShortTermMemory } from "./short-term.js";
+/** Pipeline customizations forwarded to the Agent untouched — everything
+ * that isn't decided by the blueprint or owned by this factory. */
+type AgentOverrides = Omit<AgentOptions, "llm" | "memory" | "emotions" | "actions" | "persona" | "act">;
+export interface CreateAgentInstanceOptions {
+    /** The character, as authored in the studio. */
+    blueprint: AgentBlueprint;
+    /** Whose instance this is. With `blueprint.id`, determines all state.
+     * OMIT to mint a brand-new instance with a generated id (read it back off
+     * `result.scope.userId`); PASS an existing id to get that instance's
+     * shared live object (see {@link createAgentInstance}). */
+    userId?: string;
+    /** Reserved for shared-instance sessions; omit today. */
+    sessionId?: string;
+    llm: LLMClient;
+    /** Side effect for each blueprint action, by name. Required when the
+     * blueprint declares actions. */
+    executors?: Record<string, ActionExecutor>;
+    pool?: pg.Pool;
+    connectionString?: string;
+    ssl?: pg.PoolConfig["ssl"];
+    /** Forwarded to PostgresMemoryStore. */
+    embedder?: Embedder;
+    /** Pipeline-stage overrides, forwarded to the Agent (e.g. a processor on
+     * a different LLM client for split billing). */
+    overrides?: AgentOverrides;
+}
+/** A ready-to-use agent instance plus handles to its state. */
+export interface AgentInstance {
+    agent: Agent;
+    /** Funnel an event in: serialized + coalesced per instance. The production
+     * entry point — delegates to `agent.enqueue`. Resolves to the heartbeat
+     * result, or a merged marker when this event was folded into a later one. */
+    enqueue(event: ContextEvent): Promise<EnqueueOutcome<AgentResult>>;
+    scope: InstanceScope;
+    /** Canonical storage key — every row of this instance's state carries it. */
+    key: string;
+    /** True when the build birthed the instance (claimed the directory row and
+     * wrote seed facts). Set once at build time; a cached return carries that
+     * same value, so it means "birthed during this process," not "by this call." */
+    created: boolean;
+    memory: PostgresMemoryStore;
+    emotions: PostgresEmotionalState;
+    shortTermMemory: PostgresShortTermMemory;
+    /** Forget this instance from the registry, and end the pool if this build
+     * created it. Idempotent. With a shared pool you own, this only evicts the
+     * cache entry — you end the pool yourself at shutdown. */
+    close(): Promise<void>;
+}
+/**
+ * Forget every cached instance. Does NOT close pools (you own those) — it
+ * just empties the in-memory lookup so the next `createAgentInstance` rebuilds
+ * from the database. Blunt: for tests and full teardown only — to drop a
+ * single edited instance use {@link forgetInstance}.
+ */
+export declare function clearInstanceRegistry(): void;
+/**
+ * Forget ONE instance from the registry. The next `createAgentInstance` for
+ * that id rebuilds it from the database — picking up an edited blueprint
+ * (new persona, model, actions) that the cached object was frozen with. Every
+ * other instance is untouched. Returns true if an entry was removed.
+ *
+ * Call this when the instance is IDLE — e.g. after a blueprint edit, between
+ * events. Forgetting one that has a queued or in-flight heartbeat transiently
+ * splits its queue (the running heartbeat keeps the old object while new
+ * events build a fresh one), reopening the serialization the registry exists
+ * to provide.
+ */
+export declare function forgetInstance(scope: InstanceScope): boolean;
+/**
+ * Forget every cached instance of a blueprint — all its users and sessions —
+ * so the next `createAgentInstance` for any of them rebuilds from the
+ * database, applying an edited blueprint (new persona, model, actions). Other
+ * blueprints are untouched. Returns how many instances were forgotten. Same
+ * idle caveat as {@link forgetInstance}: forgetting an instance mid-heartbeat
+ * transiently splits its queue.
+ */
+export declare function forgetBlueprint(blueprintId: string): number;
+/**
+ * The one-call entry point: blueprint + user → that user's instance, as a
+ * shared live object.
+ *
+ * - **Omit `userId`** to MINT a new instance: a fresh id is generated, the
+ *   instance is birthed, and you read the id back off `result.scope.userId`
+ *   to address it later. (Same rule will extend to `sessionId`.)
+ * - **Pass a `userId`** to GET that instance: the first call this process
+ *   makes for an id builds it (birthing it in the DB on true first contact,
+ *   or attaching to existing persistent state otherwise) and caches the live
+ *   object; every later call with the same id returns that **same object**.
+ *
+ * Births write seed facts and claim a directory row exactly once; lived state
+ * is never re-seeded. Two ids share nothing. Pass one shared `pool` you own
+ * (recommended) — then per-instance `close()` only forgets the cache entry;
+ * you end the pool yourself at shutdown.
+ */
+export declare function createAgentInstance(options: CreateAgentInstanceOptions): Promise<AgentInstance>;
+export {};