@flow-engineer/flow 0.0.1 → 0.2.1

package/dist/src/store.d.ts

@@ -0,0 +1,214 @@
+import type { Database } from "./db.ts";
+import type { ChatMessage } from "./types.ts";
+/** Quiet hours, "HH:MM" to "HH:MM" in the person's own time; they may wrap midnight. */
+export interface QuietHours {
+    from: string;
+    to: string;
+}
+/** Who said where a person is: the business (setTimeZone), or the person (they named a place). */
+export type TimeZoneSource = "business" | "person";
+export interface ConversationRow {
+    id: string;
+    personKey: string;
+    timeZone: string | null;
+    timeZoneSource: TimeZoneSource | null;
+    /** Their own quiet hours: "off" for none, null for the agent's. */
+    quietHours: QuietHours | "off" | null;
+    turnOpen: boolean;
+    messageCount: number;
+    recentChannels: string[];
+    /** Turns begun so far; a turn run again after a restart keeps its number. */
+    turns: number;
+}
+export interface IdentityRow {
+    channel: string;
+    address: string;
+    conversationId: string;
+    verifiedBy: string;
+    lastMessageAt: number | null;
+    /** Where their latest message on this identity came from, so sends to it go back the same way. */
+    via: Via;
+}
+/** A real provider's webhook, or the test playground (a test person on a simulator). */
+export type Via = "provider" | "playground";
+export interface InboxRow {
+    id: number;
+    kind: "message" | "note" | "schedule" | "nudge";
+    payload: Record<string, unknown>;
+}
+export interface ScheduleRow {
+    id: string;
+    conversationId: string;
+    channel: string;
+    instruction: string;
+    fixedText: boolean;
+    mode: "message" | "check";
+    rule: Record<string, unknown>;
+    timeZone: string;
+    nextRunAt: number | null;
+    runCount: number;
+    maxRuns: number | null;
+    endsOn: string | null;
+    status: "active" | "done" | "cancelled";
+    version: number;
+    origin: "person" | "api";
+    createdAt: number;
+}
+export type NewSchedule = Omit<ScheduleRow, "version" | "runCount" | "status" | "createdAt">;
+export interface NudgeRow {
+    id: string;
+    conversationId: string;
+    channel: string;
+    body: Record<string, unknown>;
+    status: string;
+    reason: string | null;
+    idempotencyKey: string | null;
+}
+export interface NoContactRow {
+    id: string;
+    rule: string;
+    until: number | null;
+    /** They texted STOP: nothing the business starts goes to them, with no model call, until START. */
+    hard: boolean;
+    /** stop (their STOP), pause (nothing at all until `until`: no model call), topic (a model judges each message). */
+    kind: "stop" | "pause" | "topic";
+}
+/**
+ * What an agent needs of its store: a Store, or something that forwards each call to a Store
+ * elsewhere (a store service that holds the database, so the agent never holds its credentials).
+ */
+export type StoreApi = Omit<Store, "db" | "agentId">;
+export declare class Store {
+    readonly db: Database;
+    readonly agentId: string;
+    private ready;
+    constructor(db: Database, agentId: string);
+    /** The state survives a restart, so an agent must resume() before its first message. */
+    get durable(): boolean;
+    /** Creates or upgrades Flow Framework's tables; safe to call any number of times. */
+    migrate(): Promise<void>;
+    identity(channel: string, address: string): Promise<IdentityRow | null>;
+    identities(conversationId: string): Promise<IdentityRow[]>;
+    /** The conversation of one person, by their person key: `key:<resolve's value>`, `phone:<E.164>` or `<channel>:<address>`. */
+    conversationByKey(personKey: string): Promise<ConversationRow | null>;
+    conversation(id: string): Promise<ConversationRow | null>;
+    allConversations(): Promise<ConversationRow[]>;
+    createConversation(id: string, personKey: string): Promise<void>;
+    addIdentity(conversationId: string, channel: string, address: string, verifiedBy: string): Promise<void>;
+    touchIdentity(channel: string, address: string, at: number): Promise<void>;
+    setIdentityVia(channel: string, address: string, via: Via): Promise<void>;
+    /**
+     * Deletes everything kept about one person: their conversation, identities, history, inbox,
+     * background tools, schedules and their runs, nudges and no-contact rules.
+     */
+    forgetPerson(conversationId: string): Promise<void>;
+    updateConversation(id: string, fields: {
+        turnOpen?: boolean;
+        turns?: number;
+        messageCount?: number;
+        recentChannels?: string[];
+        timeZone?: string;
+        timeZoneSource?: TimeZoneSource;
+        quietHours?: QuietHours | "off" | null;
+    }): Promise<void>;
+    history(conversationId: string): Promise<ChatMessage[]>;
+    /** The history with when each entry was stored, for showing the conversation (the playground). */
+    historyWithTimes(conversationId: string): Promise<Array<{
+        entry: ChatMessage;
+        at: number;
+    }>>;
+    /** Appends history entries from `seq` on, and marks inbox rows handled, together. */
+    appendHistory(conversationId: string, seq: number, entries: ChatMessage[], doneInbox?: number[]): Promise<void>;
+    /** A provider's message id already taken in this conversation on this channel (a webhook sent again). */
+    inboundTaken(conversationId: string, channel: string, messageId: string): Promise<boolean>;
+    /** Records a provider's message id, in the transaction of what its message stores; false when it was already taken. */
+    private inbound;
+    /**
+     * A person's message into the inbox, with the provider's id for it in the same transaction, so
+     * a crash never keeps the id without the message (its retry would be refused). Returns the inbox
+     * row's id, or null when the id was already taken: nothing is written then.
+     */
+    addMessage(conversationId: string, payload: Record<string, unknown>, inbound?: {
+        channel: string;
+        messageId: string;
+    }): Promise<number | null>;
+    /** Deletes up to `limit` provider message ids recorded before `before`; returns how many it deleted. */
+    pruneInbound(before: number, limit: number): Promise<number>;
+    /**
+     * Claims an upkeep job that is due at `now` until `nextAt`, only if no other runner claimed it
+     * first (as a schedule's run is claimed): true for the one runner that does it.
+     */
+    claimUpkeep(job: string, now: number, nextAt: number): Promise<boolean>;
+    addInbox(conversationId: string, kind: InboxRow["kind"], payload: Record<string, unknown>, db?: Omit<Database, "transaction">): Promise<number>;
+    openInbox(conversationId: string): Promise<InboxRow[]>;
+    doneInbox(ids: number[]): Promise<void>;
+    addTask(conversationId: string, taskId: string, callId: string, tool: string, startedAt: number): Promise<void>;
+    removeTask(conversationId: string, taskId: string): Promise<void>;
+    tasks(conversationId: string): Promise<Array<{
+        taskId: string;
+        tool: string;
+        startedAt: number;
+    }>>;
+    /** Conversations with something left to do after a restart. */
+    unfinished(): Promise<string[]>;
+    addSchedule(s: NewSchedule, db?: Omit<Database, "transaction">): Promise<void>;
+    schedules(conversationId: string): Promise<ScheduleRow[]>;
+    cancelSchedule(conversationId: string, id: string): Promise<boolean>;
+    dueSchedules(now: number, limit?: number): Promise<ScheduleRow[]>;
+    /**
+     * Moves a due schedule on and records its run, in one transaction, only if no one else did first
+     * (the version must still match). A delivered run also gets its inbox row. Returns the inbox
+     * row's id, 0 for a run recorded without one, or null when another runner had it.
+     */
+    claimRun(s: ScheduleRow, next: {
+        nextRunAt: number | null;
+        status: ScheduleRow["status"];
+    }, run: {
+        id: string;
+        outcome: string;
+        reason?: string;
+        ranAt: number;
+    }, inbox?: Record<string, unknown>): Promise<number | null>;
+    settleRun(id: string, outcome: string, reason?: string): Promise<void>;
+    runs(scheduleId: string): Promise<Array<{
+        id: string;
+        dueAt: number;
+        outcome: string;
+        reason: string | null;
+    }>>;
+    nudgeByKey(key: string): Promise<NudgeRow | null>;
+    nudge(id: string): Promise<NudgeRow | null>;
+    /**
+     * Records a nudge with its inbox row (when queued) or its schedule (when it has a time), together.
+     * Returns the inbox row's id (0 for none), or null when its idempotency key was already taken:
+     * nothing is written then.
+     */
+    addNudge(n: NudgeRow, schedule?: NewSchedule): Promise<number | null>;
+    /** A nudge waits after all (their WhatsApp window is closed): held, with what its release needs. */
+    holdNudge(id: string, body: Record<string, unknown>, reason: string): Promise<void>;
+    /** Nudges held for quiet hours or a closed window, for one conversation or every one. */
+    heldNudges(conversationId?: string): Promise<NudgeRow[]>;
+    /**
+     * A held nudge goes on: queued, with its inbox row, in one transaction. Returns the inbox row's
+     * id, or null when it was no longer held (another runner took it, or it was settled).
+     */
+    releaseNudge(n: NudgeRow): Promise<number | null>;
+    settleNudge(id: string, status: string, reason?: string): Promise<void>;
+    addNoContact(conversationId: string, id: string, rule: string, until: number | null, kind?: "pause" | "topic"): Promise<void>;
+    /** Removes one of the agent's rules; a STOP is not one of them (only START lifts it). */
+    removeNoContact(conversationId: string, id: string): Promise<boolean>;
+    /**
+     * They texted STOP (`stop` is its rule, kept unless one is already in force) or START (null:
+     * their STOP is lifted), with the provider's id for the message in the same transaction. False
+     * when the id was already taken: nothing is changed then.
+     */
+    setStop(conversationId: string, stop: {
+        id: string;
+        rule: string;
+    } | null, inbound?: {
+        channel: string;
+        messageId: string;
+    }): Promise<boolean>;
+    /** The rules still in force at `now` (a rule with an `until` in the past has ended). */
+    noContact(conversationId: string, now: number): Promise<NoContactRow[]>;
+}

package/dist/src/store.js

@@ -0,0 +1,448 @@
+// Flow Framework's own state in the database: who each person is and on which channels, every
+// conversation's history, the inbox of events not yet handled, background tools in flight,
+// scheduled messages and their runs, nudges, and what each person asked not to be messaged about.
+// The author's data never lives here. Every row carries the agent's id, so one database can hold
+// several agents.
+/**
+ * The column types that differ between engines. Times are milliseconds since the epoch, past a
+ * 32-bit integer: SQLite's INTEGER holds 64 bits, Postgres needs BIGINT (which node-postgres hands
+ * back as a string, so every read goes through Number()). Flags stay integers 0/1 on both.
+ */
+const TYPES = {
+    sqlite: { int: "INTEGER", serial: "INTEGER PRIMARY KEY AUTOINCREMENT" },
+    postgres: { int: "BIGINT", serial: "BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY" },
+};
+const MIGRATIONS = [
+    (t) => `CREATE TABLE conversations (
+     agent_id TEXT NOT NULL, id TEXT NOT NULL, person_key TEXT NOT NULL, time_zone TEXT,
+     turn_open INTEGER NOT NULL DEFAULT 0, message_count INTEGER NOT NULL DEFAULT 0,
+     recent_channels TEXT NOT NULL DEFAULT '[]', created_at ${t.int} NOT NULL,
+     PRIMARY KEY (agent_id, id));
+   CREATE UNIQUE INDEX conversations_person ON conversations (agent_id, person_key);
+   CREATE TABLE identities (
+     agent_id TEXT NOT NULL, channel TEXT NOT NULL, address TEXT NOT NULL, conversation_id TEXT NOT NULL,
+     verified_by TEXT NOT NULL, last_message_at ${t.int},
+     PRIMARY KEY (agent_id, channel, address));
+   CREATE TABLE messages (
+     agent_id TEXT NOT NULL, conversation_id TEXT NOT NULL, seq INTEGER NOT NULL, entry TEXT NOT NULL, at ${t.int} NOT NULL,
+     PRIMARY KEY (agent_id, conversation_id, seq));
+   CREATE TABLE inbox (
+     id ${t.serial}, agent_id TEXT NOT NULL, conversation_id TEXT NOT NULL,
+     kind TEXT NOT NULL, payload TEXT NOT NULL, done INTEGER NOT NULL DEFAULT 0, at ${t.int} NOT NULL);
+   CREATE INDEX inbox_open ON inbox (agent_id, conversation_id, done);
+   CREATE TABLE background_tools (
+     agent_id TEXT NOT NULL, conversation_id TEXT NOT NULL, task_id TEXT NOT NULL, call_id TEXT NOT NULL,
+     tool TEXT NOT NULL, started_at ${t.int} NOT NULL,
+     PRIMARY KEY (agent_id, conversation_id, task_id));
+   CREATE TABLE schedules (
+     agent_id TEXT NOT NULL, id TEXT NOT NULL, conversation_id TEXT NOT NULL, channel TEXT NOT NULL,
+     instruction TEXT NOT NULL, fixed_text INTEGER NOT NULL DEFAULT 0, mode TEXT NOT NULL, rule TEXT NOT NULL,
+     time_zone TEXT NOT NULL, next_run_at ${t.int}, run_count INTEGER NOT NULL DEFAULT 0, max_runs INTEGER,
+     ends_on TEXT, status TEXT NOT NULL, version INTEGER NOT NULL DEFAULT 0, origin TEXT NOT NULL,
+     created_at ${t.int} NOT NULL,
+     PRIMARY KEY (agent_id, id));
+   CREATE INDEX schedules_due ON schedules (agent_id, status, next_run_at);
+   CREATE TABLE schedule_runs (
+     agent_id TEXT NOT NULL, id TEXT NOT NULL, schedule_id TEXT NOT NULL, due_at ${t.int} NOT NULL,
+     ran_at ${t.int} NOT NULL, outcome TEXT NOT NULL, reason TEXT,
+     PRIMARY KEY (agent_id, id));
+   CREATE TABLE nudges (
+     agent_id TEXT NOT NULL, id TEXT NOT NULL, conversation_id TEXT NOT NULL, channel TEXT NOT NULL,
+     body TEXT NOT NULL, status TEXT NOT NULL, reason TEXT, idempotency_key TEXT, created_at ${t.int} NOT NULL,
+     PRIMARY KEY (agent_id, id));
+   CREATE UNIQUE INDEX nudges_key ON nudges (agent_id, idempotency_key);
+   CREATE TABLE no_contact (
+     agent_id TEXT NOT NULL, id TEXT NOT NULL, conversation_id TEXT NOT NULL, rule TEXT NOT NULL,
+     until ${t.int}, created_at ${t.int} NOT NULL,
+     PRIMARY KEY (agent_id, id));`,
+    // Where an identity's latest message came from: the channel's provider, or the playground.
+    () => `ALTER TABLE identities ADD COLUMN via TEXT NOT NULL DEFAULT 'provider'`,
+    // A rule from a keyword (STOP): a hard stop, checked without the model, lifted only by START.
+    () => `ALTER TABLE no_contact ADD COLUMN hard INTEGER NOT NULL DEFAULT 0`,
+    // Phone keys are E.164 now: "phone:15550100100" (as WhatsApp gives it) and "phone:0015550100100"
+    // become "phone:+15550100100", so the same number on SMS joins them. Where a number already has
+    // two conversations (under any two of those forms), all are left as they are: merging two
+    // histories is the owner's call. Each look-up is by equality, so it uses the person_key index.
+    () => `UPDATE conversations SET person_key = 'phone:+' || substr(person_key, CASE WHEN person_key LIKE 'phone:00%' THEN 9 ELSE 7 END)
+     WHERE person_key LIKE 'phone:%' AND person_key NOT LIKE 'phone:+%'
+       AND NOT EXISTS (SELECT 1 FROM conversations other WHERE other.agent_id = conversations.agent_id
+         AND other.person_key = 'phone:+' || substr(conversations.person_key, CASE WHEN conversations.person_key LIKE 'phone:00%' THEN 9 ELSE 7 END))
+       AND NOT EXISTS (SELECT 1 FROM conversations other WHERE other.agent_id = conversations.agent_id
+         AND other.person_key = CASE WHEN conversations.person_key LIKE 'phone:00%' THEN 'phone:' || substr(conversations.person_key, 9) ELSE 'phone:00' || substr(conversations.person_key, 7) END)`,
+    // A provider's message ids, so a webhook's retry is taken once (per conversation: some providers
+    // number messages per chat); and each conversation's turn count, for tools' idempotency keys.
+    (t) => `CREATE TABLE inbound (
+     agent_id TEXT NOT NULL, conversation_id TEXT NOT NULL, channel TEXT NOT NULL, message_id TEXT NOT NULL, at ${t.int} NOT NULL,
+     PRIMARY KEY (agent_id, conversation_id, channel, message_id));
+   ALTER TABLE conversations ADD COLUMN turns INTEGER NOT NULL DEFAULT 0`,
+    // Provider ids are deleted once old; upkeep jobs (that pruning) are claimed, so one runner does each.
+    (t) => `CREATE INDEX inbound_at ON inbound (agent_id, at);
+   CREATE TABLE upkeep (agent_id TEXT NOT NULL, job TEXT NOT NULL, next_at ${t.int} NOT NULL, PRIMARY KEY (agent_id, job))`,
+    // A person's contact settings: their own quiet hours (null: the agent's), where their time zone
+    // came from, and each no-contact rule's kind (stop, pause: checked with no model; topic: judged).
+    () => `ALTER TABLE conversations ADD COLUMN quiet_hours TEXT;
+   ALTER TABLE conversations ADD COLUMN time_zone_source TEXT;
+   ALTER TABLE no_contact ADD COLUMN kind TEXT NOT NULL DEFAULT 'topic';
+   UPDATE no_contact SET kind = 'stop' WHERE hard = 1;
+   CREATE INDEX nudges_status ON nudges (agent_id, status)`,
+];
+const json = (value) => JSON.stringify(value);
+const parse = (text, fallback) => {
+    try {
+        return typeof text === "string" ? JSON.parse(text) : fallback;
+    }
+    catch {
+        return fallback;
+    }
+};
+const num = (v) => (v === null || v === undefined ? null : Number(v));
+export class Store {
+    db;
+    agentId;
+    ready = null;
+    constructor(db, agentId) {
+        this.db = db;
+        this.agentId = agentId;
+    }
+    /** The state survives a restart, so an agent must resume() before its first message. */
+    get durable() {
+        return this.db.durable;
+    }
+    /** Creates or upgrades Flow Framework's tables; safe to call any number of times. */
+    migrate() {
+        this.ready ??= (async () => {
+            const types = TYPES[this.db.dialect ?? "sqlite"];
+            await this.db.run(`CREATE TABLE IF NOT EXISTS parley_migrations (version INTEGER PRIMARY KEY, applied_at ${types.int} NOT NULL)`);
+            const done = new Set((await this.db.query("SELECT version FROM parley_migrations")).map((r) => Number(r.version)));
+            for (const [i, migration] of MIGRATIONS.entries()) {
+                if (done.has(i + 1))
+                    continue;
+                await this.db.transaction(async (tx) => {
+                    for (const statement of migration(types).split(";").map((s) => s.trim()).filter(Boolean))
+                        await tx.run(statement);
+                    await tx.run("INSERT INTO parley_migrations (version, applied_at) VALUES (?, ?)", [i + 1, Date.now()]);
+                });
+            }
+        })();
+        return this.ready;
+    }
+    // People and their channels.
+    async identity(channel, address) {
+        const [row] = await this.db.query("SELECT * FROM identities WHERE agent_id = ? AND channel = ? AND address = ?", [this.agentId, channel, address]);
+        return row ? identityOf(row) : null;
+    }
+    async identities(conversationId) {
+        const rows = await this.db.query("SELECT * FROM identities WHERE agent_id = ? AND conversation_id = ?", [this.agentId, conversationId]);
+        return rows.map(identityOf);
+    }
+    /** The conversation of one person, by their person key: `key:<resolve's value>`, `phone:<E.164>` or `<channel>:<address>`. */
+    async conversationByKey(personKey) {
+        const [row] = await this.db.query("SELECT * FROM conversations WHERE agent_id = ? AND person_key = ?", [this.agentId, personKey]);
+        return row ? conversationOf(row) : null;
+    }
+    async conversation(id) {
+        const [row] = await this.db.query("SELECT * FROM conversations WHERE agent_id = ? AND id = ?", [this.agentId, id]);
+        return row ? conversationOf(row) : null;
+    }
+    async allConversations() {
+        return (await this.db.query("SELECT * FROM conversations WHERE agent_id = ?", [this.agentId])).map(conversationOf);
+    }
+    async createConversation(id, personKey) {
+        await this.db.run("INSERT INTO conversations (agent_id, id, person_key, created_at) VALUES (?, ?, ?, ?) ON CONFLICT DO NOTHING", [this.agentId, id, personKey, Date.now()]);
+    }
+    async addIdentity(conversationId, channel, address, verifiedBy) {
+        await this.db.run("INSERT INTO identities (agent_id, channel, address, conversation_id, verified_by) VALUES (?, ?, ?, ?, ?) ON CONFLICT DO NOTHING", [this.agentId, channel, address, conversationId, verifiedBy]);
+    }
+    async touchIdentity(channel, address, at) {
+        await this.db.run("UPDATE identities SET last_message_at = ? WHERE agent_id = ? AND channel = ? AND address = ?", [at, this.agentId, channel, address]);
+    }
+    async setIdentityVia(channel, address, via) {
+        await this.db.run("UPDATE identities SET via = ? WHERE agent_id = ? AND channel = ? AND address = ?", [via, this.agentId, channel, address]);
+    }
+    /**
+     * Deletes everything kept about one person: their conversation, identities, history, inbox,
+     * background tools, schedules and their runs, nudges and no-contact rules.
+     */
+    async forgetPerson(conversationId) {
+        const scope = [this.agentId, conversationId];
+        await this.db.transaction(async (tx) => {
+            await tx.run("DELETE FROM schedule_runs WHERE agent_id = ? AND schedule_id IN (SELECT id FROM schedules WHERE agent_id = ? AND conversation_id = ?)", [this.agentId, ...scope]);
+            for (const table of ["schedules", "nudges", "no_contact", "background_tools", "inbox", "messages", "inbound", "identities"]) {
+                await tx.run(`DELETE FROM ${table} WHERE agent_id = ? AND conversation_id = ?`, scope);
+            }
+            await tx.run("DELETE FROM conversations WHERE agent_id = ? AND id = ?", scope);
+        });
+    }
+    async updateConversation(id, fields) {
+        const sets = [];
+        const params = [];
+        if (fields.turnOpen !== undefined)
+            sets.push("turn_open = ?"), params.push(fields.turnOpen ? 1 : 0);
+        if (fields.turns !== undefined)
+            sets.push("turns = ?"), params.push(fields.turns);
+        if (fields.messageCount !== undefined)
+            sets.push("message_count = ?"), params.push(fields.messageCount);
+        if (fields.recentChannels !== undefined)
+            sets.push("recent_channels = ?"), params.push(json(fields.recentChannels));
+        if (fields.timeZone !== undefined)
+            sets.push("time_zone = ?"), params.push(fields.timeZone);
+        if (fields.timeZoneSource !== undefined)
+            sets.push("time_zone_source = ?"), params.push(fields.timeZoneSource);
+        if (fields.quietHours !== undefined)
+            sets.push("quiet_hours = ?"), params.push(fields.quietHours === null ? null : json(fields.quietHours));
+        if (!sets.length)
+            return;
+        await this.db.run(`UPDATE conversations SET ${sets.join(", ")} WHERE agent_id = ? AND id = ?`, [...params, this.agentId, id]);
+    }
+    // History.
+    async history(conversationId) {
+        const rows = await this.db.query("SELECT entry FROM messages WHERE agent_id = ? AND conversation_id = ? ORDER BY seq", [this.agentId, conversationId]);
+        return rows.map((r) => parse(r.entry, { role: "user", content: "" }));
+    }
+    /** The history with when each entry was stored, for showing the conversation (the playground). */
+    async historyWithTimes(conversationId) {
+        const rows = await this.db.query("SELECT entry, at FROM messages WHERE agent_id = ? AND conversation_id = ? ORDER BY seq", [this.agentId, conversationId]);
+        return rows.map((r) => ({ entry: parse(r.entry, { role: "user", content: "" }), at: Number(r.at) }));
+    }
+    /** Appends history entries from `seq` on, and marks inbox rows handled, together. */
+    async appendHistory(conversationId, seq, entries, doneInbox = []) {
+        await this.db.transaction(async (tx) => {
+            for (const [i, entry] of entries.entries()) {
+                await tx.run("INSERT INTO messages (agent_id, conversation_id, seq, entry, at) VALUES (?, ?, ?, ?, ?)", [this.agentId, conversationId, seq + i, json(entry), Date.now()]);
+            }
+            for (const id of doneInbox)
+                await tx.run("UPDATE inbox SET done = 1 WHERE agent_id = ? AND id = ?", [this.agentId, id]);
+        });
+    }
+    /** A provider's message id already taken in this conversation on this channel (a webhook sent again). */
+    async inboundTaken(conversationId, channel, messageId) {
+        return (await this.db.query("SELECT 1 FROM inbound WHERE agent_id = ? AND conversation_id = ? AND channel = ? AND message_id = ?", [this.agentId, conversationId, channel, messageId])).length > 0;
+    }
+    /** Records a provider's message id, in the transaction of what its message stores; false when it was already taken. */
+    async inbound(conversationId, channel, messageId, db = this.db) {
+        return (await db.run("INSERT INTO inbound (agent_id, conversation_id, channel, message_id, at) VALUES (?, ?, ?, ?, ?) ON CONFLICT DO NOTHING", [this.agentId, conversationId, channel, messageId, Date.now()])) > 0;
+    }
+    /**
+     * A person's message into the inbox, with the provider's id for it in the same transaction, so
+     * a crash never keeps the id without the message (its retry would be refused). Returns the inbox
+     * row's id, or null when the id was already taken: nothing is written then.
+     */
+    async addMessage(conversationId, payload, inbound) {
+        return this.db.transaction(async (tx) => {
+            if (inbound && !(await this.inbound(conversationId, inbound.channel, inbound.messageId, tx)))
+                return null;
+            return this.addInbox(conversationId, "message", payload, tx);
+        });
+    }
+    /** Deletes up to `limit` provider message ids recorded before `before`; returns how many it deleted. */
+    async pruneInbound(before, limit) {
+        return this.db.run(`DELETE FROM inbound WHERE agent_id = ? AND (conversation_id, channel, message_id) IN
+         (SELECT conversation_id, channel, message_id FROM inbound WHERE agent_id = ? AND at < ? LIMIT ?)`, [this.agentId, this.agentId, before, limit]);
+    }
+    /**
+     * Claims an upkeep job that is due at `now` until `nextAt`, only if no other runner claimed it
+     * first (as a schedule's run is claimed): true for the one runner that does it.
+     */
+    async claimUpkeep(job, now, nextAt) {
+        return this.db.transaction(async (tx) => {
+            await tx.run("INSERT INTO upkeep (agent_id, job, next_at) VALUES (?, ?, 0) ON CONFLICT DO NOTHING", [this.agentId, job]);
+            return (await tx.run("UPDATE upkeep SET next_at = ? WHERE agent_id = ? AND job = ? AND next_at <= ?", [nextAt, this.agentId, job, now])) > 0;
+        });
+    }
+    // The inbox.
+    async addInbox(conversationId, kind, payload, db = this.db) {
+        const [row] = await db.query("INSERT INTO inbox (agent_id, conversation_id, kind, payload, at) VALUES (?, ?, ?, ?, ?) RETURNING id", [this.agentId, conversationId, kind, json(payload), Date.now()]);
+        return Number(row.id);
+    }
+    async openInbox(conversationId) {
+        const rows = await this.db.query("SELECT id, kind, payload FROM inbox WHERE agent_id = ? AND conversation_id = ? AND done = 0 ORDER BY id", [this.agentId, conversationId]);
+        return rows.map((r) => ({ id: Number(r.id), kind: r.kind, payload: parse(r.payload, {}) }));
+    }
+    async doneInbox(ids) {
+        for (const id of ids)
+            await this.db.run("UPDATE inbox SET done = 1 WHERE agent_id = ? AND id = ?", [this.agentId, id]);
+    }
+    // Background tools.
+    async addTask(conversationId, taskId, callId, tool, startedAt) {
+        await this.db.run("INSERT INTO background_tools (agent_id, conversation_id, task_id, call_id, tool, started_at) VALUES (?, ?, ?, ?, ?, ?)", [this.agentId, conversationId, taskId, callId, tool, startedAt]);
+    }
+    async removeTask(conversationId, taskId) {
+        await this.db.run("DELETE FROM background_tools WHERE agent_id = ? AND conversation_id = ? AND task_id = ?", [this.agentId, conversationId, taskId]);
+    }
+    async tasks(conversationId) {
+        const rows = await this.db.query("SELECT task_id, tool, started_at FROM background_tools WHERE agent_id = ? AND conversation_id = ?", [this.agentId, conversationId]);
+        return rows.map((r) => ({ taskId: String(r.task_id), tool: String(r.tool), startedAt: Number(r.started_at) }));
+    }
+    /** Conversations with something left to do after a restart. */
+    async unfinished() {
+        const rows = await this.db.query(`SELECT id FROM conversations WHERE agent_id = ? AND (turn_open = 1
+         OR id IN (SELECT conversation_id FROM inbox WHERE agent_id = ? AND done = 0)
+         OR id IN (SELECT conversation_id FROM background_tools WHERE agent_id = ?))`, [this.agentId, this.agentId, this.agentId]);
+        return rows.map((r) => String(r.id));
+    }
+    // Scheduled messages.
+    async addSchedule(s, db = this.db) {
+        await db.run(`INSERT INTO schedules (agent_id, id, conversation_id, channel, instruction, fixed_text, mode, rule, time_zone, next_run_at, max_runs, ends_on, status, origin, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', ?, ?)`, [this.agentId, s.id, s.conversationId, s.channel, s.instruction, s.fixedText ? 1 : 0, s.mode, json(s.rule), s.timeZone, s.nextRunAt, s.maxRuns, s.endsOn, s.origin, Date.now()]);
+    }
+    async schedules(conversationId) {
+        const rows = await this.db.query("SELECT * FROM schedules WHERE agent_id = ? AND conversation_id = ? AND status = 'active' ORDER BY next_run_at", [this.agentId, conversationId]);
+        return rows.map(scheduleOf);
+    }
+    async cancelSchedule(conversationId, id) {
+        const changed = await this.db.run("UPDATE schedules SET status = 'cancelled', version = version + 1 WHERE agent_id = ? AND conversation_id = ? AND id = ? AND status = 'active'", [this.agentId, conversationId, id]);
+        return changed > 0;
+    }
+    async dueSchedules(now, limit = 50) {
+        const rows = await this.db.query("SELECT * FROM schedules WHERE agent_id = ? AND status = 'active' AND next_run_at <= ? ORDER BY next_run_at LIMIT ?", [this.agentId, now, limit]);
+        return rows.map(scheduleOf);
+    }
+    /**
+     * Moves a due schedule on and records its run, in one transaction, only if no one else did first
+     * (the version must still match). A delivered run also gets its inbox row. Returns the inbox
+     * row's id, 0 for a run recorded without one, or null when another runner had it.
+     */
+    async claimRun(s, next, run, inbox) {
+        return this.db.transaction(async (tx) => {
+            const changed = await tx.run("UPDATE schedules SET next_run_at = ?, status = ?, run_count = run_count + 1, version = version + 1 WHERE agent_id = ? AND id = ? AND version = ?", [next.nextRunAt, next.status, this.agentId, s.id, s.version]);
+            if (!changed)
+                return null;
+            await tx.run("INSERT INTO schedule_runs (agent_id, id, schedule_id, due_at, ran_at, outcome, reason) VALUES (?, ?, ?, ?, ?, ?, ?)", [this.agentId, run.id, s.id, s.nextRunAt, run.ranAt, run.outcome, run.reason ?? null]);
+            return inbox ? this.addInbox(s.conversationId, "schedule", inbox, tx) : 0;
+        });
+    }
+    async settleRun(id, outcome, reason) {
+        await this.db.run("UPDATE schedule_runs SET outcome = ?, reason = ? WHERE agent_id = ? AND id = ?", [outcome, reason ?? null, this.agentId, id]);
+    }
+    async runs(scheduleId) {
+        const rows = await this.db.query("SELECT * FROM schedule_runs WHERE agent_id = ? AND schedule_id = ? ORDER BY due_at", [this.agentId, scheduleId]);
+        return rows.map((r) => ({ id: String(r.id), dueAt: Number(r.due_at), outcome: String(r.outcome), reason: r.reason ?? null }));
+    }
+    // Nudges.
+    async nudgeByKey(key) {
+        const [row] = await this.db.query("SELECT * FROM nudges WHERE agent_id = ? AND idempotency_key = ?", [this.agentId, key]);
+        return row ? nudgeOf(row) : null;
+    }
+    async nudge(id) {
+        const [row] = await this.db.query("SELECT * FROM nudges WHERE agent_id = ? AND id = ?", [this.agentId, id]);
+        return row ? nudgeOf(row) : null;
+    }
+    /**
+     * Records a nudge with its inbox row (when queued) or its schedule (when it has a time), together.
+     * Returns the inbox row's id (0 for none), or null when its idempotency key was already taken:
+     * nothing is written then.
+     */
+    async addNudge(n, schedule) {
+        return this.db.transaction(async (tx) => {
+            const added = await tx.run("INSERT INTO nudges (agent_id, id, conversation_id, channel, body, status, reason, idempotency_key, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT DO NOTHING", [this.agentId, n.id, n.conversationId, n.channel, json(n.body), n.status, n.reason, n.idempotencyKey, Date.now()]);
+            if (!added)
+                return null;
+            if (schedule)
+                await this.addSchedule(schedule, tx);
+            return n.status === "queued" ? this.addInbox(n.conversationId, "nudge", { nudge: n.id, channel: n.channel, ...n.body }, tx) : 0;
+        });
+    }
+    /** A nudge waits after all (their WhatsApp window is closed): held, with what its release needs. */
+    async holdNudge(id, body, reason) {
+        await this.db.run("UPDATE nudges SET status = 'held', reason = ?, body = ? WHERE agent_id = ? AND id = ?", [reason, json(body), this.agentId, id]);
+    }
+    /** Nudges held for quiet hours or a closed window, for one conversation or every one. */
+    async heldNudges(conversationId) {
+        const rows = conversationId
+            ? await this.db.query("SELECT * FROM nudges WHERE agent_id = ? AND status = 'held' AND conversation_id = ? ORDER BY created_at", [this.agentId, conversationId])
+            : await this.db.query("SELECT * FROM nudges WHERE agent_id = ? AND status = 'held' ORDER BY created_at", [this.agentId]);
+        return rows.map(nudgeOf);
+    }
+    /**
+     * A held nudge goes on: queued, with its inbox row, in one transaction. Returns the inbox row's
+     * id, or null when it was no longer held (another runner took it, or it was settled).
+     */
+    async releaseNudge(n) {
+        return this.db.transaction(async (tx) => {
+            const changed = await tx.run("UPDATE nudges SET status = 'queued', reason = NULL WHERE agent_id = ? AND id = ? AND status = 'held'", [this.agentId, n.id]);
+            if (!changed)
+                return null;
+            return this.addInbox(n.conversationId, "nudge", { nudge: n.id, channel: n.channel, ...n.body }, tx);
+        });
+    }
+    async settleNudge(id, status, reason) {
+        await this.db.run("UPDATE nudges SET status = ?, reason = ? WHERE agent_id = ? AND id = ?", [status, reason ?? null, this.agentId, id]);
+    }
+    // What a person asked not to be messaged about.
+    async addNoContact(conversationId, id, rule, until, kind = "topic") {
+        await this.db.run("INSERT INTO no_contact (agent_id, id, conversation_id, rule, until, kind, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)", [this.agentId, id, conversationId, rule, until, kind, Date.now()]);
+    }
+    /** Removes one of the agent's rules; a STOP is not one of them (only START lifts it). */
+    async removeNoContact(conversationId, id) {
+        return (await this.db.run("DELETE FROM no_contact WHERE agent_id = ? AND conversation_id = ? AND id = ? AND hard = 0", [this.agentId, conversationId, id])) > 0;
+    }
+    /**
+     * They texted STOP (`stop` is its rule, kept unless one is already in force) or START (null:
+     * their STOP is lifted), with the provider's id for the message in the same transaction. False
+     * when the id was already taken: nothing is changed then.
+     */
+    async setStop(conversationId, stop, inbound) {
+        return this.db.transaction(async (tx) => {
+            if (inbound && !(await this.inbound(conversationId, inbound.channel, inbound.messageId, tx)))
+                return false;
+            if (!stop)
+                await tx.run("DELETE FROM no_contact WHERE agent_id = ? AND conversation_id = ? AND hard = 1", [this.agentId, conversationId]);
+            else if (!(await tx.query("SELECT 1 FROM no_contact WHERE agent_id = ? AND conversation_id = ? AND hard = 1", [this.agentId, conversationId])).length) {
+                await tx.run("INSERT INTO no_contact (agent_id, id, conversation_id, rule, until, hard, kind, created_at) VALUES (?, ?, ?, ?, NULL, 1, 'stop', ?)", [this.agentId, stop.id, conversationId, stop.rule, Date.now()]);
+            }
+            return true;
+        });
+    }
+    /** The rules still in force at `now` (a rule with an `until` in the past has ended). */
+    async noContact(conversationId, now) {
+        const rows = await this.db.query("SELECT id, rule, until, hard, kind FROM no_contact WHERE agent_id = ? AND conversation_id = ? AND (until IS NULL OR until > ?) ORDER BY created_at", [this.agentId, conversationId, now]);
+        return rows.map((r) => ({ id: String(r.id), rule: String(r.rule), until: num(r.until), hard: Number(r.hard) === 1, kind: (Number(r.hard) === 1 ? "stop" : r.kind === "pause" ? "pause" : "topic") }));
+    }
+}
+function conversationOf(r) {
+    return {
+        id: String(r.id),
+        personKey: String(r.person_key),
+        timeZone: r.time_zone ?? null,
+        timeZoneSource: r.time_zone_source ?? null,
+        quietHours: r.quiet_hours == null ? null : parse(r.quiet_hours, null),
+        turnOpen: Number(r.turn_open) === 1,
+        messageCount: Number(r.message_count),
+        recentChannels: parse(r.recent_channels, []),
+        turns: Number(r.turns ?? 0),
+    };
+}
+function identityOf(r) {
+    return { channel: String(r.channel), address: String(r.address), conversationId: String(r.conversation_id), verifiedBy: String(r.verified_by), lastMessageAt: num(r.last_message_at), via: r.via === "playground" ? "playground" : "provider" };
+}
+function scheduleOf(r) {
+    return {
+        id: String(r.id),
+        conversationId: String(r.conversation_id),
+        channel: String(r.channel),
+        instruction: String(r.instruction),
+        fixedText: Number(r.fixed_text) === 1,
+        mode: r.mode,
+        rule: parse(r.rule, {}),
+        timeZone: String(r.time_zone),
+        nextRunAt: num(r.next_run_at),
+        runCount: Number(r.run_count),
+        maxRuns: num(r.max_runs),
+        endsOn: r.ends_on ?? null,
+        status: r.status,
+        version: Number(r.version),
+        origin: r.origin,
+        createdAt: Number(r.created_at),
+    };
+}
+function nudgeOf(r) {
+    return {
+        id: String(r.id),
+        conversationId: String(r.conversation_id),
+        channel: String(r.channel),
+        body: parse(r.body, {}),
+        status: String(r.status),
+        reason: r.reason ?? null,
+        idempotencyKey: r.idempotency_key ?? null,
+    };
+}