@flow-engineer/flow 0.0.1 → 0.2.1

package/dist/src/agent.js

@@ -0,0 +1,818 @@
+// An agent: instructions, skills and tools, and one Conversation per person, across every channel
+// they write on. Channels hand it messages; it says whether anything is running, so a host can stop
+// it when it is idle. Its state lives in a database (in memory unless one is given), so a restart
+// carries on where it stopped.
+//
+// Who a person is gets fixed when their message arrives, from what the channel verified, never
+// from anything the model or a tool says: the owner's own key from `resolve`, else the phone
+// number of a phone channel (SMS, WhatsApp, iMessage verify it), else that channel's address alone.
+// Identities with the same key are one person in one conversation.
+//
+// Test people, declared in `testPeople`, can also write from the test playground (`simulate`), a
+// different phone for the same person: same identity, history, lookups and schedules. Each identity
+// remembers whether its latest message came from the playground or the channel's provider, and
+// every send to it (replies, scheduled messages, nudges) goes back the same way.
+import { randomUUID } from "node:crypto";
+import { declaredTemplate, fillTemplate, keywordOf, summarize } from "./channels.js";
+import { Conversation, PROFILE_TOOL, profileTool, transcriptOf, windowClosed } from "./conversation.js";
+import { sqlite } from "./db.js";
+import { emitter } from "./events.js";
+import { businessSchedule, claimDue, summary } from "./schedules.js";
+import { loadInstructions, loadSkills, readAgentFolder, skillTool } from "./skills.js";
+import { Store } from "./store.js";
+import { clock, quietUntil, validZone } from "./time.js";
+import { STAND_IN, toSpec } from "./tools.js";
+import { traces, tracesFromEnv } from "./traces.js";
+const NO_EXTRAS = { reactions: false, status: false };
+const HOUR_MS = 3_600_000;
+/** Provider ids deleted per statement, so each one holds its locks briefly. */
+const PRUNE_BATCH = 1_000;
+export class Agent {
+    conversations = new Map();
+    options;
+    settings;
+    store;
+    startedAt = Date.now();
+    /** Conversations in the store, known once resume() ran. */
+    rows = new Map();
+    resumed = false;
+    arriving = new Map();
+    /** Callers waiting for a queued nudge to settle: its first call, and any with the same key. */
+    nudgeWaiters = new Map();
+    now;
+    channelsByName;
+    /** Where each identity (channel, address) last wrote from; sends go back the same way. */
+    via = new Map();
+    playgroundSink = null;
+    /** Before this, this runner does not ask for the pruning claim again (it, or another runner, had it). */
+    pruneAfter = 0;
+    /** `defaultCountryCode`'s digits. */
+    countryCode;
+    traces;
+    constructor(options) {
+        this.options = options;
+        this.channelsByName = new Map((options.channels ?? []).map((c) => [c.name, c]));
+        if (this.channelsByName.size !== (options.channels ?? []).length)
+            throw new Error("flow: two channels have the same name");
+        // A person's key is "key:<resolve's value>", "phone:<number>" or "<channel>:<address>": a channel
+        // named key or phone would make a channel identity read as one of the other two.
+        for (const name of ["key", "phone"])
+            if (this.channelsByName.has(name))
+                throw new Error(`flow: "${name}" is reserved; give the channel another name`);
+        this.now = options.now ?? Date.now;
+        if (options.fallbackTemplate) {
+            const declared = declaredTemplate(options.templates, options.fallbackTemplate);
+            if (!declared)
+                throw new Error(`flow: fallbackTemplate ${options.fallbackTemplate.name} is not one of the declared templates`);
+            fillTemplate(declared, options.fallbackTemplate);
+        }
+        if (options.quietHours && !validQuietHours(options.quietHours))
+            throw new Error('flow: quietHours is { from: "HH:MM", to: "HH:MM" }');
+        if (options.defaultCountryCode !== undefined && !/^\+?[1-9]\d{0,2}$/.test(options.defaultCountryCode.trim()))
+            throw new Error(`flow: defaultCountryCode is a calling code such as "+91", not "${options.defaultCountryCode}"`);
+        this.countryCode = options.defaultCountryCode?.trim().replace(/^\+/, "");
+        const tracing = options.traces ?? tracesFromEnv();
+        this.traces = tracing ? traces(tracing, { service: options.id ?? "flow", kindOf: (name) => this.channelsByName.get(name)?.kind }) : null;
+        const sinks = [...(options.events ?? []), ...(this.traces ? [this.traces.sink] : [])];
+        const emit = emitter(sinks);
+        if ((options.dir === undefined) === (options.files === undefined))
+            throw new Error("flow: give an agent exactly one of dir or files");
+        const files = options.files ?? readAgentFolder(options.dir);
+        const skills = loadSkills(files);
+        // The test cloud's stand-in for get_user_profile counts only for an agent with a profile.
+        const tools = (options.tools ?? []).filter((t) => options.profile || !t[STAND_IN]);
+        if (options.profile && !tools.some((t) => t.name === PROFILE_TOOL))
+            tools.push(profileTool(options.profile));
+        if (skills.length && !options.inlineSkills)
+            tools.push(skillTool(skills, (id, name) => emit(id, "skill.loaded", { skill: name })));
+        if (options.store && (options.database || options.id))
+            throw new Error("flow: give an agent a store or a database (and id), not both");
+        this.store = options.store ?? new Store(options.database ?? sqlite(), options.id ?? "default");
+        this.settings = {
+            model: options.model,
+            transcribe: options.transcribe,
+            tools: new Map(tools.map((t) => [t.name, t])),
+            specs: tools.map(toSpec),
+            instructions: loadInstructions(files, skills, options.inlineSkills),
+            context: options.context,
+            contextSinks: sinks.filter((sink) => sink.context === true),
+            deadlineMs: options.deadlineMs ?? 60_000,
+            partialAfterMs: options.partialAfterMs ?? 5_000,
+            debounceMs: options.debounceMs ?? 300,
+            maxSteps: options.maxSteps ?? 8,
+            historyTokens: options.history?.maxTokens ?? (options.model.contextTokens ? Math.floor(options.model.contextTokens * 0.6) : 50_000),
+            toolResultChars: options.history?.toolResultChars ?? 12_000,
+            maxRestarts: Number.POSITIVE_INFINITY,
+            talk: {
+                shareUpdates: options.shareUpdates !== false,
+                shareUpdatesInstructions: typeof options.shareUpdates === "string" ? options.shareUpdates : undefined,
+            },
+            emit,
+            store: this.store,
+            ready: this.store.migrate(),
+            now: this.now,
+            timeZone: options.timeZone,
+            quietHours: options.quietHours,
+            templates: options.templates ?? [],
+            fallbackTemplate: options.fallbackTemplate?.name,
+            windowClosed: (nudge, to) => this.windowClosed(nudge, to),
+            tagChannels: (options.channels ?? []).length > 1,
+            links: (id) => this.links(id),
+            settle: (target, status, reason) => this.settle(target, status, reason),
+        };
+        const every = options.scheduleCheckMs ?? 5_000;
+        if (every > 0)
+            setInterval(() => void this.runDue().catch((error) => console.warn("flow: scheduled messages:", error)), every).unref();
+    }
+    /**
+     * Loads what the database holds and carries on: turns cut off by a restart run again, events not
+     * yet handled are handled, background tools that were running are reported as interrupted. A
+     * durable database needs this before the first message.
+     */
+    async resume() {
+        await this.settings.ready;
+        for (const row of await this.store.allConversations())
+            this.rows.set(row.id, row);
+        this.resumed = true;
+        for (const id of await this.store.unfinished())
+            this.open(id);
+    }
+    /**
+     * A message from a person on a channel set up in `channels`. Returns the conversation and the id
+     * the agent knows the message by, or null when `intercept` or a keyword answered it. Give the
+     * provider's own `messageId`: the same one again (a webhook retried) is not taken twice.
+     */
+    async message(input) {
+        return this.released(await this.take(this.channelOf(input.channel), { ...input, via: "provider" }));
+    }
+    /**
+     * A message from a test person (by their phone number) in the test playground: exactly what
+     * message() does for the same person writing on that channel, but its replies go to the
+     * playground. Anyone not in `testPeople` is refused.
+     */
+    async simulate(input) {
+        const person = this.testPerson(input.person);
+        if (!person)
+            throw new Error("flow: only the agent's testPeople can be simulated");
+        const adapter = this.channelOf(input.channel);
+        return this.released(await this.take(adapter, { channel: input.channel, from: this.testAddress(adapter, person), message: input.message, messageId: input.messageId, via: "playground", person }));
+    }
+    /** They wrote, so they are there: what was held for their quiet hours goes now, in this turn. */
+    async released(taken) {
+        if (taken)
+            await this.releaseHeld(this.now(), taken.conversationId);
+        return taken;
+    }
+    /**
+     * Held nudges whose quiet hours are over (or every one of a conversation whose person just wrote)
+     * go on; ones past their expiresAt are settled as expired. Released together, they reach one turn.
+     */
+    async releaseHeld(now, writer) {
+        for (const n of await this.store.heldNudges(writer)) {
+            const body = n.body;
+            if ((body.expiresAt ?? Infinity) <= now) {
+                await this.settle({ nudge: n.id }, "expired", "held past its expiresAt for their quiet hours");
+                continue;
+            }
+            // Held for a closed window (no holdUntil), it waits for their reply.
+            if (!writer && (body.holdUntil ?? Infinity) > now)
+                continue;
+            // Released because they just wrote: their window is open, though their message may not have landed yet.
+            const inbox = await this.store.releaseNudge(writer ? { ...n, body: { ...n.body, theyWrote: true } } : n);
+            if (inbox !== null)
+                this.wake(n.conversationId, inbox);
+        }
+    }
+    /** Sends the traces of finished turns still waiting for the traces endpoint; call it before the process exits. */
+    flushTraces() {
+        return this.traces?.flush() ?? Promise.resolve();
+    }
+    /** The templates declared in `templates`. */
+    templates() {
+        return [...(this.options.templates ?? [])];
+    }
+    /** The people declared in `testPeople`. */
+    testPeople() {
+        return [...(this.options.testPeople ?? [])];
+    }
+    /** A test person's conversation, by their phone number, or null if they have not written yet. */
+    async testConversation(phone) {
+        await this.settings.ready;
+        const person = this.testPerson(phone);
+        if (!person)
+            return null;
+        for (const adapter of this.channelsByName.values()) {
+            const known = await this.store.identity(adapter.name, this.testAddress(adapter, person));
+            if (known)
+                return known.conversationId;
+        }
+        return (await this.store.conversationByKey(await this.testPersonKey(person, [...this.channelsByName.values()][0])))?.id ?? null;
+    }
+    /** Where the playground shows what is sent to test people who wrote from it; null detaches it. */
+    attachPlayground(sink) {
+        this.playgroundSink = sink;
+    }
+    /** A conversation as the person saw it, from the store: their messages, the agent's, and its tool calls. */
+    async transcript(conversationId) {
+        await this.settings.ready;
+        await this.conversations.get(conversationId)?.stored();
+        const only = [...this.channelsByName.keys()][0] ?? "chat";
+        return transcriptOf(await this.store.historyWithTimes(conversationId), only);
+    }
+    /**
+     * Forgets a person: a turn in progress stops, and everything kept about them goes (history,
+     * inbox, background tools, schedules and their runs, nudges, no-contact rules, identities and
+     * the conversation). Their next message starts from nothing.
+     */
+    async forgetPerson(conversationId) {
+        await this.settings.ready;
+        const resident = this.conversations.get(conversationId);
+        if (resident) {
+            resident.close();
+            this.conversations.delete(conversationId);
+            await resident.stored();
+        }
+        for (const i of await this.store.identities(conversationId))
+            this.via.delete(viaKey(i.channel, i.address));
+        this.rows.delete(conversationId);
+        await this.store.forgetPerson(conversationId);
+    }
+    channelOf(name) {
+        const adapter = this.channelsByName.get(name);
+        if (!adapter)
+            throw new Error(`flow: no channel named ${name}`);
+        this.mustBeResumed();
+        return adapter;
+    }
+    /** Messages from one address are taken in order, so a new person is made only once. */
+    take(adapter, input) {
+        const key = viaKey(input.channel, input.from);
+        const previous = this.arriving.get(key) ?? Promise.resolve();
+        const handled = previous.then(() => this.arrive(adapter, input));
+        this.arriving.set(key, handled.catch(() => undefined));
+        return handled;
+    }
+    async arrive(adapter, input) {
+        await this.settings.ready;
+        const identity = await this.conversationFor(adapter, input.channel, input.from, input.person);
+        const conversationId = identity.conversationId;
+        if (input.messageId !== undefined && (await this.store.inboundTaken(conversationId, input.channel, input.messageId))) {
+            // The provider sent this message before (a webhook retried): it was taken then. Its id is
+            // written with what the message stores (its inbox row, a STOP), so a crash keeps neither.
+            this.settings.emit(conversationId, "message.duplicate", { messageId: input.messageId, channel: input.channel });
+            return { conversationId, messageId: input.messageId };
+        }
+        if (identity.via !== input.via)
+            await this.store.setIdentityVia(input.channel, input.from, input.via);
+        this.via.set(viaKey(input.channel, input.from), input.via);
+        const conversation = this.open(conversationId);
+        const deliver = this.deliverer(adapter, input.from, conversationId);
+        conversation.link({ name: input.channel, info: adapter.info, params: adapter.params, instructions: adapter.instructions, address: input.from, deliver, lastMessageAt: null });
+        const text = typeof input.message === "string" ? input.message : input.message.text;
+        const kind = keywordIn(adapter.keywords, input.message);
+        const fixed = this.intercepted(conversationId, text, { keyword: kind, channel: input.channel });
+        const answer = kind ? this.keyword(conversation, adapter.keywords, kind, text, fixed, input.channel, input.messageId) : null;
+        const reply = answer ? answer.reply : fixed;
+        if (reply === null)
+            return { conversationId, messageId: conversation.receive(input.message, { channel: input.channel, messageId: input.messageId }) };
+        // Answered with no model call: kept with its reply and its id, and sent once that is stored, so a retry is not answered again.
+        const answered = conversation.answered(input.message, { channel: input.channel, messageId: input.messageId, claimed: answer?.stored, note: answer?.note }, reply);
+        if (answered && (await answered.taken))
+            await answered.send();
+        return null;
+    }
+    /**
+     * The agent's `intercept`, told the message's channel and whether it is a keyword. A keyword is
+     * handled the same whatever the hook does, so its error there is logged, not thrown.
+     */
+    intercepted(conversationId, text, message) {
+        if (!message.keyword)
+            return this.options.intercept?.(conversationId, text, message) ?? null;
+        try {
+            return this.options.intercept?.(conversationId, text, message) ?? null;
+        }
+        catch (error) {
+            console.warn(`flow: intercept threw on a ${message.keyword.toUpperCase()} keyword; Flow Framework handled it as usual:`, error);
+            return null;
+        }
+    }
+    /**
+     * A STOP, START or HELP keyword, answered with no model call: what to send back (the hook's own
+     * reply, else the channel's, else "" for nothing), and for STOP and START the line the agent
+     * learns it by and their write, which holds the message's id. Null for HELP with no reply: the
+     * hook's answer, or the agent, takes it like any message.
+     */
+    keyword(conversation, keywords, kind, text, own, channel, messageId) {
+        const reply = own || keywords.replies?.[kind] || "";
+        if (kind === "help")
+            return reply ? { reply } : null;
+        return { reply, ...conversation.keyword(kind, text, channel, messageId) };
+    }
+    /** The identity a message comes from, made (and linked to its person's conversation) the first time it writes. */
+    async conversationFor(adapter, channel, address, testPerson) {
+        const known = await this.store.identity(channel, address);
+        if (known)
+            return known;
+        let personKey;
+        let verifiedBy;
+        if (testPerson && !adapter.phone) {
+            // Not a phone channel: their playground address joins the person their number is.
+            [personKey, verifiedBy] = [await this.testPersonKey(testPerson, adapter), "test person"];
+        }
+        else {
+            const owner = await this.options.resolve?.({ channel, address });
+            const phone = adapter.phone ? normalizePhone(address, adapter.kind === "whatsapp" ? undefined : this.countryCode) : "";
+            [personKey, verifiedBy] = owner ? [`key:${owner}`, "resolver"] : phone ? [`phone:${phone}`, "phone"] : [`${channel}:${address}`, "channel"];
+        }
+        let row = await this.store.conversationByKey(personKey);
+        if (!row) {
+            // Two first messages from one person at once (on two channels) both get here; one insert
+            // wins, and both carry on with the conversation that is there now.
+            await this.store.createConversation(`p_${randomUUID().slice(0, 12)}`, personKey);
+            row = await this.store.conversationByKey(personKey);
+            if (!row)
+                throw new Error(`flow: could not make a conversation for ${personKey}`);
+            if (!this.conversations.has(row.id))
+                this.rows.set(row.id, row);
+        }
+        const id = row.id;
+        await this.store.addIdentity(id, channel, address, verifiedBy);
+        return { channel, address, conversationId: id, verifiedBy, lastMessageAt: null, via: "provider" };
+    }
+    /**
+     * The key the real person has: what the owner's resolve() gives their phone number (on the
+     * agent's first phone channel, else this one), else their phone number. So the playground and
+     * the provider reach one conversation, on every channel.
+     */
+    async testPersonKey(person, adapter) {
+        const phone = normalizePhone(person.phone);
+        const channel = [...this.channelsByName.values()].find((c) => c.phone) ?? adapter;
+        const owner = channel ? await this.options.resolve?.({ channel: channel.name, address: phone }) : null;
+        return owner ? `key:${owner}` : `phone:${phone}`;
+    }
+    testPerson(phone) {
+        const wanted = normalizePhone(phone);
+        return wanted ? this.options.testPeople?.find((p) => normalizePhone(p.phone) === wanted) : undefined;
+    }
+    /** A test person's address on a channel: their number on phone channels, else `test:<number>`. */
+    testAddress(adapter, person) {
+        const phone = normalizePhone(person.phone);
+        return adapter.phone ? phone : `test:${phone}`;
+    }
+    /** Sends to one identity: to the playground if it last wrote from there, else through the channel's provider. */
+    deliverer(adapter, address, conversationId) {
+        return (outbound) => {
+            if (this.via.get(viaKey(adapter.name, address)) !== "playground")
+                return adapter.send(address, outbound);
+            const phone = address.startsWith("test:") ? address.slice(5) : address;
+            const person = this.testPerson(phone);
+            // With no playground page open, nothing is shown, and the conversation keeps it as sent.
+            if (person)
+                return this.playgroundSink?.({ conversationId, person, channel: adapter.name, outbound });
+        };
+    }
+    /**
+     * A message from a person; replies go to `deliver`, the channel it came in on. Returns the id
+     * the agent knows the message by, or null when `intercept` or a keyword answered it. The conversation is
+     * this id alone: use message() and `channels` for one person across several channels. When
+     * `channelName` is one of the agent's channels, its definition (what it shows, its params) is
+     * used and replies go to `deliver`: that is how the simulators play an agent's own channels.
+     */
+    receive(conversationId, message, deliver, options = {}) {
+        const text = typeof message === "string" ? message : message.text;
+        const name = options.channelName ?? "chat";
+        const defined = this.channelsByName.get(name);
+        const kind = keywordIn(defined?.keywords, message);
+        const fixed = this.intercepted(conversationId, text, { keyword: kind, channel: name });
+        this.mustBeResumed();
+        const isNew = !this.conversations.has(conversationId) && !this.rows.has(conversationId);
+        const conversation = this.open(conversationId, `${name}:${conversationId}`);
+        if (isNew)
+            conversation.persist(() => this.store.addIdentity(conversationId, name, conversationId, "channel"));
+        conversation.link({ name, info: defined?.info ?? options.channel ?? NO_EXTRAS, params: defined?.params, instructions: defined?.instructions, address: conversationId, deliver, lastMessageAt: null });
+        const answer = kind ? this.keyword(conversation, defined.keywords, kind, text, fixed, name) : null;
+        const reply = answer ? answer.reply : fixed;
+        if (reply === null)
+            return conversation.receive(message, { channel: name, messageId: options.messageId });
+        const answered = conversation.answered(message, { channel: name, messageId: options.messageId, claimed: answer?.stored, note: answer?.note }, reply);
+        // A STOP's or START's reply goes once it is kept; any other starts now, while receive() runs, so
+        // a caller that waits on what it delivers sees it.
+        if (answered)
+            void (answer?.stored ? answer.stored.then((taken) => (taken ? answered.send() : undefined)) : answered.send());
+        return null;
+    }
+    /**
+     * The person reacted to one of the agent's messages; the agent learns it at its next turn. The
+     * conversation is loaded from the store when it is not in memory (after a restart).
+     */
+    reacted(conversationId, emoji, toText) {
+        this.withConversation(conversationId, (c) => c.reacted(emoji, toText));
+    }
+    /** The channel reports that a message did not reach the person; the agent hears about it, also after a restart. */
+    undelivered(conversationId, text, reason) {
+        this.withConversation(conversationId, (c) => c.undelivered(text, reason));
+    }
+    /** Acts on a conversation now when it is in memory, else once it is loaded from the store; never on one the store does not hold. */
+    withConversation(conversationId, act) {
+        const resident = this.conversations.get(conversationId);
+        if (resident)
+            return act(resident);
+        void (async () => {
+            await this.settings.ready;
+            const row = this.rows.get(conversationId) ?? (await this.store.conversation(conversationId));
+            if (!row)
+                return;
+            this.rows.set(conversationId, row);
+            act(this.open(conversationId));
+        })().catch((error) => console.warn("flow: conversation %s could not be loaded for a report:", conversationId, error));
+    }
+    conversation(conversationId) {
+        return this.conversations.get(conversationId);
+    }
+    /**
+     * A message the business starts. Resolves once it is settled: sent, silent (a prompt nudge the
+     * agent chose not to send), dropped (a no-contact rule covers it), refused (outside_window,
+     * unknown_person) or failed; or scheduled, for one with `at`.
+     */
+    /**
+     * The person's time zone as the business knows it (an IANA name, "Asia/Kolkata"), by a channel
+     * identity they have written from, like a nudge's `to`. Schedules and the agent's time use it from
+     * then on. Throws for a name that is not a zone; refused (unknown_person) for someone who never wrote.
+     */
+    async setTimeZone(input) {
+        if (!validZone(input.timeZone))
+            throw new Error(`flow: ${input.timeZone} is not a time zone; use an IANA name such as America/New_York`);
+        await this.settings.ready;
+        const identity = await this.store.identity(input.to.channel, input.to.address);
+        if (!identity)
+            return { status: "refused", reason: "unknown_person" };
+        const id = identity.conversationId;
+        const resident = this.conversations.get(id);
+        if (resident)
+            await resident.setTimeZone(input.timeZone, "business");
+        else {
+            await this.store.updateConversation(id, { timeZone: input.timeZone, timeZoneSource: "business" });
+            const row = this.rows.get(id);
+            if (row)
+                this.rows.set(id, { ...row, timeZone: input.timeZone, timeZoneSource: "business" });
+        }
+        return { status: "set" };
+    }
+    /**
+     * Their own quiet hours, as the business knows them: `{ from, to }`, "off" for none, or null to go
+     * back to the agent's. Refused (unknown_person) for someone who never wrote.
+     */
+    async setQuietHours(input) {
+        const q = input.quietHours;
+        if (q !== null && q !== "off" && !validQuietHours(q))
+            throw new Error('flow: quietHours is { from: "HH:MM", to: "HH:MM" }, "off" or null');
+        await this.settings.ready;
+        const identity = await this.store.identity(input.to.channel, input.to.address);
+        if (!identity)
+            return { status: "refused", reason: "unknown_person" };
+        const resident = this.conversations.get(identity.conversationId);
+        if (resident)
+            await resident.setQuietHours(q);
+        else
+            await this.store.updateConversation(identity.conversationId, { quietHours: q });
+        return { status: "set" };
+    }
+    /** What the business and the person set for someone, by a channel identity they wrote from; null for someone who never wrote. */
+    async contact(to) {
+        await this.settings.ready;
+        const identity = await this.store.identity(to.channel, to.address);
+        const row = identity && (await this.store.conversation(identity.conversationId));
+        if (!row)
+            return null;
+        const rules = await this.store.noContact(row.id, this.now());
+        const own = row.quietHours;
+        const hours = quietHoursOf(row, this.options.quietHours);
+        return {
+            timeZone: row.timeZone,
+            timeZoneSource: row.timeZoneSource,
+            quietHours: row.timeZone ? hours : null,
+            quietHoursSource: !hours ? "off" : !row.timeZone ? "no_time_zone" : own && own !== "off" ? "person" : "agent",
+            stop: rules.some((r) => r.kind === "stop"),
+            pauses: rules.filter((r) => r.kind === "pause").map((r) => ({ id: r.id, until: r.until })),
+            topics: rules.filter((r) => r.kind === "topic").map((r) => ({ id: r.id, rule: r.rule, until: r.until })),
+        };
+    }
+    /** A window-closed prompt nudge got no template from the agent: held until they reply, and the fallback goes now. */
+    async windowClosed(nudge, to) {
+        const row = await this.store.nudge(nudge);
+        if (!row)
+            return;
+        const { windowClosed: _closed, ...body } = row.body;
+        await this.store.holdNudge(nudge, body, "window_closed");
+        this.release(nudge, this.result(nudge, "held", "window_closed"));
+        await this.sendFallback(row.conversationId, to, nudge, body);
+    }
+    /** The fallback template for a held nudge, once, and the event that says it wanted a template of its own. */
+    async sendFallback(conversationId, to, nudge, body) {
+        this.settings.emit(conversationId, "template.missing", { nudge, channel: to.channel, ...(body.text !== undefined ? { text: body.text } : { prompt: body.prompt }) });
+        await this.recordNudge({ to, template: this.options.fallbackTemplate, idempotencyKey: `fallback:${nudge}` });
+    }
+    /**
+     * What is waiting to go to a person: their scheduled messages (theirs and the business's) and the
+     * nudges held for their quiet hours or a closed window. The playground shows it.
+     */
+    async outbox(conversationId) {
+        await this.settings.ready;
+        const schedules = (await this.store.schedules(conversationId)).map((s) => ({
+            id: s.id,
+            message: s.instruction,
+            origin: s.origin === "person" ? "person" : "business",
+            mode: s.mode,
+            nextRunAt: s.nextRunAt,
+            timeZone: s.timeZone,
+            respectsQuietHours: s.rule.quiet === true,
+            summary: summary(s).summary,
+        }));
+        const held = (await this.store.heldNudges(conversationId)).map((n) => {
+            const b = n.body;
+            return {
+                id: n.id,
+                channel: n.channel,
+                kind: b.template ? "template" : b.text !== undefined ? "text" : "prompt",
+                what: b.template?.name ?? b.text ?? b.prompt ?? "",
+                reason: n.reason ?? "",
+                heldAt: b.heldAt ?? null,
+                holdUntil: b.holdUntil ?? null,
+                expiresAt: b.expiresAt ?? null,
+            };
+        });
+        return { schedules, held };
+    }
+    /** Whether the agent has a profile (get_user_profile), so the test cloud knows to play it. */
+    hasProfile() {
+        return this.options.profile !== undefined;
+    }
+    async nudge(input) {
+        // outcome() waits while it is queued, so what it resolves is settled.
+        return (await this.outcome(await this.recordNudge(input)));
+    }
+    /**
+     * Records a nudge and resolves at once, without waiting for its send or turn: `queued`, or what
+     * was decided as it was recorded (dropped, refused, scheduled). The same idempotency key gets the
+     * first nudge's state now. `nudgeState(id)` reads it later.
+     */
+    async recordNudge(input) {
+        await this.settings.ready;
+        const kinds = [input.text, input.prompt, input.template].filter((v) => v !== undefined).length;
+        if (kinds !== 1)
+            throw new Error("flow: a nudge has exactly one of text, prompt or template");
+        // A declared template whose values don't fit it never goes: Meta would refuse it, the playground would show nonsense.
+        const declared = input.template && declaredTemplate(this.options.templates, input.template);
+        if (declared)
+            fillTemplate(declared, input.template);
+        if (input.idempotencyKey) {
+            const earlier = await this.store.nudgeByKey(input.idempotencyKey);
+            if (earlier)
+                return this.result(earlier.id, earlier.status, earlier.reason);
+        }
+        const identity = await this.store.identity(input.to.channel, input.to.address);
+        if (!identity)
+            return { id: "", status: "refused", reason: "unknown_person" };
+        const id = `n_${randomUUID().slice(0, 8)}`;
+        const conversationId = identity.conversationId;
+        const record = { id, conversationId, channel: input.to.channel, idempotencyKey: input.idempotencyKey ?? null, reason: null };
+        const stop = input.at === undefined ? await this.blockOf(conversationId) : null;
+        // Written once per key: a call that loses the insert to one with the same key gets that one's result.
+        const add = async (row, schedule) => {
+            const inbox = await this.store.addNudge(row, schedule);
+            if (inbox !== null)
+                return inbox;
+            const first = (await this.store.nudgeByKey(input.idempotencyKey));
+            return this.result(first.id, first.status, first.reason);
+        };
+        const settledAs = async (row) => {
+            const added = await add(row);
+            return typeof added === "number" ? this.result(row.id, row.status, row.reason) : added;
+        };
+        if (stop) {
+            const reason = `no-contact rule ${stop.id}: ${stop.rule}`;
+            return settledAs({ ...record, body: input.template ? { template: input.template } : { text: input.text, prompt: input.prompt }, status: "dropped", reason });
+        }
+        if (input.at !== undefined) {
+            if (input.template)
+                throw new Error("flow: a template nudge cannot be scheduled yet");
+            const zone = (await this.store.conversation(conversationId))?.timeZone ?? this.options.timeZone ?? "UTC";
+            const schedule = businessSchedule(conversationId, input.to.channel, input.at, zone, { text: input.text, prompt: input.prompt }, input.respectQuietHours !== false);
+            const added = await add({ ...record, body: { text: input.text, prompt: input.prompt, at: input.at }, status: "scheduled" }, schedule);
+            return typeof added === "number" ? { id, status: "scheduled" } : added;
+        }
+        const body = input.template ? { template: input.template } : input.text !== undefined ? { text: input.text } : { prompt: input.prompt };
+        const now = this.now();
+        const quietEnds = input.respectQuietHours === false ? null : await this.quietEnd(conversationId, now);
+        if (quietEnds !== null) {
+            const held = { ...body, heldAt: now, holdUntil: quietEnds, expiresAt: input.expiresAt ?? now + DAY_MS };
+            const added = await add({ ...record, body: held, status: "held", reason: "quiet_hours" });
+            return typeof added === "number" ? { id, status: "held", reason: "quiet_hours" } : added;
+        }
+        if (!input.template && windowClosed({ info: this.infoOf(input.to.channel, conversationId), lastMessageAt: identity.lastMessageAt }, this.now())) {
+            if (!this.options.fallbackTemplate)
+                return settledAs({ ...record, body, status: "refused", reason: "outside_window" });
+            if (input.text !== undefined) {
+                // Exact wording: it waits for their reply, and the fallback tells them something is waiting.
+                const added = await add({ ...record, body: { ...body, expiresAt: input.expiresAt ?? now + DAY_MS }, status: "held", reason: "window_closed" });
+                if (typeof added !== "number")
+                    return added;
+                await this.sendFallback(conversationId, input.to, id, body);
+                return { id, status: "held", reason: "window_closed" };
+            }
+            // A prompt nudge: the agent may find a template that says it; else the fallback (windowClosed below).
+            Object.assign(body, { windowClosed: true, expiresAt: input.expiresAt ?? now + DAY_MS });
+        }
+        const added = await add({ ...record, body, status: "queued" });
+        if (typeof added !== "number")
+            return added;
+        this.wake(conversationId, added);
+        return { id, status: "queued" };
+    }
+    /** A nudge's state now, or null for an id the store does not hold. */
+    async nudgeState(id) {
+        await this.settings.ready;
+        const row = await this.store.nudge(id);
+        return row && this.result(row.id, row.status, row.reason);
+    }
+    /** A recorded nudge as `nudge()` returns it: settled, or (still queued) once it settles. */
+    async outcome(state) {
+        if (state.status !== "queued")
+            return state;
+        const settled = this.waitFor(state.id);
+        // It may have settled between the read and the wait.
+        const now = await this.store.nudge(state.id);
+        if (now && now.status !== "queued")
+            this.release(state.id, this.result(state.id, now.status, now.reason));
+        return settled;
+    }
+    waitFor(id) {
+        return new Promise((resolve) => this.nudgeWaiters.set(id, [...(this.nudgeWaiters.get(id) ?? []), resolve]));
+    }
+    release(id, result) {
+        for (const resolve of this.nudgeWaiters.get(id) ?? [])
+            resolve(result);
+        this.nudgeWaiters.delete(id);
+    }
+    /**
+     * Looks for due scheduled messages once and hands each to its conversation. Returns how many.
+     * Once an hour, one runner also deletes provider message ids older than `keepMessageIdsDays`.
+     */
+    async runDue() {
+        await this.settings.ready;
+        if (this.store.durable && !this.resumed)
+            return 0;
+        const now = this.now();
+        const queued = await claimDue(this.store, now, (s) => this.quietEnd(s.conversationId, now), async (s) => {
+            const stop = s.origin === "person" ? await this.stopOf(s.conversationId) : await this.blockOf(s.conversationId);
+            if (stop)
+                return `no-contact rule ${stop.id}: ${stop.rule}`;
+            const identity = (await this.store.identities(s.conversationId)).find((i) => i.channel === s.channel);
+            if (!identity)
+                return `no way to reach them on ${s.channel}`;
+            return windowClosed({ info: this.infoOf(s.channel, s.conversationId), lastMessageAt: identity.lastMessageAt }, now) ? "outside_window" : null;
+        });
+        for (const q of queued)
+            this.wake(q.conversationId, q.inbox);
+        await this.releaseHeld(now);
+        await this.pruneMessageIds(now).catch((error) => console.warn("flow: pruning message ids:", error));
+        return queued.length;
+    }
+    /** Deletes provider message ids past their keep, in batches, when this runner claims it (at most hourly). */
+    async pruneMessageIds(now) {
+        if (now < this.pruneAfter)
+            return;
+        this.pruneAfter = now + HOUR_MS;
+        if (!(await this.store.claimUpkeep("prune_message_ids", now, now + HOUR_MS)))
+            return;
+        const before = now - (this.options.keepMessageIdsDays ?? 7) * 24 * HOUR_MS;
+        while ((await this.store.pruneInbound(before, PRUNE_BATCH)) === PRUNE_BATCH)
+            ;
+    }
+    /** The agent's channels without their sends: what the simulators and the test cloud play. */
+    channels() {
+        return [...this.channelsByName.values()].map(summarize);
+    }
+    status() {
+        const all = [...this.conversations.values()];
+        const busy = all.some((c) => c.busy);
+        const idle = all.length ? Math.min(...all.map((c) => c.idleForMs)) : Date.now() - this.startedAt;
+        return {
+            busy,
+            idleForMs: busy ? 0 : idle,
+            conversations: all.length,
+            backgroundTasks: all.reduce((n, c) => n + c.backgroundTasks.length, 0),
+        };
+    }
+    /** The conversation in memory, made (and loaded from the store, if it is there) when needed. */
+    open(id, personKey = id) {
+        let conversation = this.conversations.get(id);
+        if (!conversation) {
+            const row = this.rows.get(id) ?? null;
+            conversation = new Conversation(id, row?.personKey ?? personKey, this.settings, row);
+            this.conversations.set(id, conversation);
+        }
+        return conversation;
+    }
+    /** An inbox row for a conversation: handed to it in memory, or found when it loads. */
+    wake(conversationId, inbox) {
+        const resident = this.conversations.get(conversationId);
+        if (!resident) {
+            void this.store.conversation(conversationId).then((row) => {
+                if (row)
+                    this.rows.set(conversationId, row);
+                this.open(conversationId);
+            });
+            return;
+        }
+        void this.store.openInbox(conversationId).then((rows) => {
+            const row = rows.find((r) => r.id === inbox);
+            if (row)
+                resident.enqueue(row);
+        });
+    }
+    async links(conversationId) {
+        const identities = await this.store.identities(conversationId);
+        // Oldest first, so on a channel with two identities (the app, and the playground's) the latest one wins.
+        identities.sort((a, b) => (a.lastMessageAt ?? 0) - (b.lastMessageAt ?? 0));
+        return identities.flatMap((i) => {
+            const adapter = this.channelsByName.get(i.channel);
+            if (!adapter)
+                return [];
+            this.via.set(viaKey(i.channel, i.address), i.via);
+            return [{ name: i.channel, info: adapter.info, params: adapter.params, instructions: adapter.instructions, address: i.address, deliver: this.deliverer(adapter, i.address, conversationId), lastMessageAt: i.lastMessageAt }];
+        });
+    }
+    /** What a channel can show: its adapter's, else what the conversation was last told. */
+    infoOf(channel, conversationId) {
+        return this.channelsByName.get(channel)?.info ?? this.conversations.get(conversationId)?.channelInfo(channel) ?? NO_EXTRAS;
+    }
+    async settle(target, status, reason) {
+        if (target.run)
+            await this.store.settleRun(target.run, status, reason);
+        if (target.nudge) {
+            await this.store.settleNudge(target.nudge, status, reason);
+            this.release(target.nudge, this.result(target.nudge, status, reason));
+        }
+    }
+    /** Their STOP, if they texted one. */
+    async stopOf(conversationId) {
+        return (await this.store.noContact(conversationId, this.now())).find((r) => r.hard) ?? null;
+    }
+    /** Their STOP, or a pause in force: either way nothing the business starts goes now. */
+    async blockOf(conversationId) {
+        return (await this.store.noContact(conversationId, this.now())).find((r) => r.hard || r.kind === "pause") ?? null;
+    }
+    /** When their quiet hours end, if they are in them now; null when not, or when their time zone is not known. */
+    async quietEnd(conversationId, now) {
+        const row = await this.store.conversation(conversationId);
+        const hours = row && quietHoursOf(row, this.options.quietHours);
+        return row?.timeZone && hours ? quietUntil(now, row.timeZone, hours) : null;
+    }
+    result(id, status, reason) {
+        return reason ? { id, status: status, reason } : { id, status: status };
+    }
+    mustBeResumed() {
+        if (this.store.durable && !this.resumed)
+            throw new Error("flow: call await agent.resume() before the first message when the database is durable");
+    }
+}
+const viaKey = (channel, address) => `${channel}\u0000${address}`;
+/** Which keyword a message is on a channel with them: text alone, never a file or a tap. */
+function keywordIn(keywords, message) {
+    if (typeof message !== "string" && (message.attachments?.length || message.choice))
+        return null;
+    return keywordOf(keywords, typeof message === "string" ? message : message.text);
+}
+/**
+ * A phone number as one string however the channel gave it, in E.164: formatting dropped, a 00
+ * prefix read as +, and digits with no + taken as international (WhatsApp gives "15550100100" for
+ * "+1 555 010 0100"), or, given a `countryCode`, as that country's national number. "" when there
+ * are no digits (not a phone number).
+ */
+export function normalizePhone(address, countryCode) {
+    const trimmed = address.trim();
+    const digits = trimmed.replace(/^00/, "").replace(/\D/g, "");
+    if (!digits)
+        return "";
+    if (!countryCode || trimmed.startsWith("+") || trimmed.startsWith("00"))
+        return `+${digits}`;
+    return `+${countryCode}${countryCode === "39" ? digits : digits.replace(/^0/, "")}`;
+}
+export function createAgent(options) {
+    return new Agent(options);
+}
+const DAY_MS = 24 * 60 * 60_000;
+export const DEFAULT_QUIET_HOURS = { from: "22:00", to: "07:00" };
+function validQuietHours(q) {
+    const v = q;
+    return typeof v === "object" && v !== null && typeof v.from === "string" && typeof v.to === "string" && !!clock(v.from) && !!clock(v.to);
+}
+/** The quiet hours that apply to a person: their own, else the agent's (the default unless it turned them off). */
+export function quietHoursOf(row, agent) {
+    if (row.quietHours === "off")
+        return null;
+    if (row.quietHours)
+        return row.quietHours;
+    return agent === false ? null : (agent ?? DEFAULT_QUIET_HOURS);
+}