@flow-engineer/flow 0.0.1 → 0.2.0

package/dist/src/agent.d.ts

@@ -0,0 +1,504 @@
+import { type Channel, type ChannelSummary } from "./channels.ts";
+import { Conversation, type Profile, type TranscriptEntry } from "./conversation.ts";
+import { type Database } from "./db.ts";
+import { type EventSink } from "./events.ts";
+import { type AgentFiles } from "./skills.ts";
+import { type ConversationRow, type QuietHours, type StoreApi, type TimeZoneSource } from "./store.ts";
+import { type Tool } from "./tools.ts";
+import { type TracesOptions } from "./traces.ts";
+import type { ChannelInfo, Deliver, Incoming, Model, Outbound, Template, TemplateDefinition, Transcribe } from "./types.ts";
+export interface AgentOptions {
+    /** Folder holding AGENTS.md and skills/<name>/SKILL.md. Give this or `files`. */
+    dir?: string;
+    /** That folder's files as text, by path ("AGENTS.md", "skills/<name>/SKILL.md"), for hosts with no file system. */
+    files?: AgentFiles;
+    model: Model;
+    /**
+     * Speech to text for voice notes, with the provider you choose: the agent reads the transcript,
+     * marked as a voice note. Without it, it is told a voice note came that it can't listen to.
+     */
+    transcribe?: Transcribe;
+    tools?: Tool[];
+    /**
+     * Added to the system prompt at the start of every turn, before the model is called: keep it to
+     * small facts at hand. It runs on every turn, so a lookup here (an API call, a slow query) delays
+     * every reply; give the agent `profile` or a tool for those, which it calls only when it needs them.
+     */
+    context?: (conversationId: string) => Promise<string> | string;
+    /**
+     * What the business knows about the person (their account, plan, preferences), as the built-in
+     * tool get_user_profile: no input, always about the person in the conversation, and run only when
+     * the agent calls it. A tool of yours with that name is used instead.
+     */
+    profile?: Profile;
+    /**
+     * Answer some messages without the model: return the reply, "" to send nothing, or null to let
+     * the agent reply. `message.channel` is the channel it came in on, by the name in `channels`
+     * ("chat" from receive() without a `channelName`). It sees a channel's STOP, START and HELP
+     * first, with `message.keyword` set (null for other messages), to keep its own state; Flow Framework
+     * still keeps or lifts the STOP whatever it returns or throws, and sends its own reply unless
+     * this returns one. The message and the reply are kept in the history (the agent reads them at
+     * its next turn) and the transcript, and are `message.in` and `message.out` events marked
+     * `answered: true`.
+     */
+    intercept?: (conversationId: string, text: string, message: {
+        keyword: Keyword | null;
+        channel: string;
+    }) => string | null;
+    /**
+     * Put every skill's full text in the prompt instead of loading skills on demand. Saves a model
+     * round trip per skill; worth it when the skills are few and short.
+     */
+    inlineSkills?: boolean;
+    /**
+     * Live status lines (share_updates) on channels that can show them, web and app UIs. Default on;
+     * pass a string to replace Flow Framework's guidance on when and what to share.
+     */
+    shareUpdates?: boolean | string;
+    /**
+     * The longest a reply waits for a tool that sets no `deadlineMs` of its own; past it the tool
+     * moves to the background. Default 60,000 ms. Before that, the reply waits for all of a
+     * response's tools unless the person writes again or `partialAfterMs` passes.
+     */
+    deadlineMs?: number;
+    /** When one tool of a response is done and the others are still running this long after, the finished results go back to the agent. Default 5,000 ms. */
+    partialAfterMs?: number;
+    /** Quiet time after a message before the reply starts, to catch quick bursts. Default 300 ms. */
+    debounceMs?: number;
+    maxSteps?: number;
+    /**
+     * How much of a long conversation each model call carries. The latest messages are kept, older
+     * ones are left out (the agent is told so). `maxTokens` is the whole call's budget, roughly: default 60% of the model's
+     * `contextTokens` when it gives one, else 50,000. A tool result is cut to `toolResultChars`
+     * characters (default 12,000).
+     */
+    history?: {
+        maxTokens?: number;
+        toolResultChars?: number;
+    };
+    events?: EventSink[];
+    /** This agent's id in the database (several agents can share one). Default "default". */
+    id?: string;
+    /** Where Flow Framework keeps its state. Default: SQLite in memory (gone on restart). */
+    database?: Database;
+    /**
+     * Instead of `database`: a store that keeps the state elsewhere, such as a client of a store
+     * service that holds the database, so this process never holds its credentials. `id` is then
+     * the store's to know.
+     */
+    store?: StoreApi;
+    /** The channels people reach the agent on: whatsapp(...), sms(...), customUI(...), each with its own name. */
+    channels?: Channel[];
+    /**
+     * The owner's own key for a person (a member id), from a channel identity, or null when there is
+     * none. Identities with the same key are one person.
+     */
+    resolve?: (identity: {
+        channel: string;
+        address: string;
+    }) => Promise<string | null> | string | null;
+    /**
+     * The calling code ("+91", "+44", "+1") for phone numbers that come without one. Set it when
+     * your SMS provider gives national numbers ("098765 43210"): on every phone channel but
+     * WhatsApp (whose numbers are always full), a number with no "+" or "00" is then read as this
+     * country's, its trunk 0 dropped (Italy's +39 keeps it), so it joins the same number on
+     * WhatsApp. Without it, bare digits are taken as international.
+     */
+    defaultCountryCode?: string;
+    /**
+     * The template sent when a nudge meets someone's closed WhatsApp window and no other template fits
+     * ("You have a new message"): the nudge is then held until they reply, and a `template.missing`
+     * event says which message wanted a template of its own. Declare it in `templates`. Without it a
+     * nudge outside the window is refused (outside_window), as before.
+     */
+    fallbackTemplate?: Template;
+    /**
+     * Quiet hours in each person's own time ("22:00" to "07:00", the default), when what the business
+     * starts waits: a nudge is held until they end (or the person writes), then the agent writes one
+     * message for everything held. A person may set their own; `false` turns them off. They apply only
+     * where the person's time zone is known: without it nothing is held.
+     */
+    quietHours?: QuietHours | false;
+    /**
+     * The business's time zone (IANA): the time the agent is told when the person's zone is not known,
+     * and the time a business-started schedule is shown in. Never taken as the person's own: set
+     * theirs with setTimeZone, or the agent asks them.
+     */
+    timeZone?: string;
+    /** How often due scheduled messages are looked for. Default 5,000 ms; 0 turns the timer off. */
+    scheduleCheckMs?: number;
+    /**
+     * How long a provider's message id is kept, so a webhook retried within it is taken once.
+     * Older ones are deleted, hourly, by one runner, on the scheduled messages' timer. Default 7.
+     */
+    keepMessageIdsDays?: number;
+    /** The clock (tests move it). */
+    now?: () => number;
+    /**
+     * The people who may write from the test playground (`simulate`), and no one else. Each is a
+     * real person to the agent, by their phone number: the same conversation whether they write from
+     * the playground or, once a channel is live, from the provider.
+     */
+    testPeople?: TestPerson[];
+    /**
+     * The WhatsApp templates the owner set up with Meta. A nudge with one of them is checked against
+     * it before it goes (values that don't fit throw), the agent is told what it said, and the
+     * playground shows it as WhatsApp would. A template not declared here is sent as it is.
+     */
+    templates?: TemplateDefinition[];
+    /**
+     * Send every turn to a traces endpoint as a trace. Default: from the environment, on when
+     * FLOW_FRAMEWORK_TRACES_KEY is set (address FLOW_FRAMEWORK_TRACES_URL, else https://flow.engineer/observe; FLOW_FRAMEWORK_TRACES_CONTENT=1 for content),
+     * never under `node --test`.
+     */
+    traces?: TracesOptions;
+}
+export interface TestPerson {
+    name: string;
+    /** Their phone number; on channels that are not phone channels they are `test:<number>`. */
+    phone: string;
+}
+/** Where the playground shows what the agent sends to a test person who wrote from it. */
+export type PlaygroundSink = (delivery: {
+    conversationId: string;
+    person: TestPerson;
+    channel: string;
+    outbound: Outbound;
+}) => Promise<void> | void;
+export interface AgentStatus {
+    busy: boolean;
+    /** Milliseconds since the last thing ran anywhere; 0 while busy. */
+    idleForMs: number;
+    conversations: number;
+    backgroundTasks: number;
+}
+export interface ReceiveOptions {
+    /** What the channel can show. Default: plain text only (no reactions, no status). */
+    channel?: ChannelInfo;
+    /** The channel's own id for the message; Flow Framework makes one (m1, m2, ...) otherwise. */
+    messageId?: string;
+    /** The channel's name. Default "chat". */
+    channelName?: string;
+}
+export interface NudgeInput {
+    /** The person, by a channel identity they have written from. */
+    to: {
+        channel: string;
+        address: string;
+    };
+    /** Sent as written, with no model call. */
+    text?: string;
+    /** The agent gets a turn with this note and writes the message itself, or sends nothing. */
+    prompt?: string;
+    /** A template the owner already set up with the channel, sent as is (also outside WhatsApp's window). */
+    template?: Template;
+    /** Send it later, at this time (ms since the epoch), as a scheduled message. */
+    at?: number;
+    /** The same key twice sends once, also when both calls come at once: the second gets the first's result. */
+    idempotencyKey?: string;
+    /** Wait for the end of their quiet hours (default true); false sends it now, quiet hours or not. */
+    respectQuietHours?: boolean;
+    /** A nudge held for quiet hours past this (ms since the epoch; default 24 hours on) is dropped as expired. */
+    expiresAt?: number;
+}
+export interface NudgeResult {
+    id: string;
+    /**
+     * sent; silent (the agent chose not to); dropped (a no-contact rule, or their STOP); refused
+     * (outside_window, unknown_person); failed (it could not be sent, or the model failed: `reason`
+     * says why, and the person was sent nothing about it); scheduled; held (for their quiet hours,
+     * until they end or the person writes); or expired (held past its expiresAt, never sent).
+     */
+    status: NudgeStatus;
+    reason?: string;
+}
+export type NudgeStatus = "sent" | "silent" | "dropped" | "refused" | "failed" | "scheduled" | "held" | "expired";
+/** A scheduled message, as the playground lists it. */
+export interface ScheduledItem {
+    id: string;
+    message: string;
+    origin: "person" | "business";
+    mode: "message" | "check";
+    nextRunAt: number | null;
+    timeZone: string;
+    respectsQuietHours: boolean;
+    summary: string;
+}
+/** A nudge waiting for their quiet hours to end, or for their reply (a closed window). */
+export interface HeldItem {
+    id: string;
+    channel: string;
+    kind: "text" | "prompt" | "template";
+    what: string;
+    reason: string;
+    heldAt: number | null;
+    /** When their quiet hours end; null when it waits for their reply. */
+    holdUntil: number | null;
+    expiresAt: number | null;
+}
+/** What the business and the person set for someone, as the agent goes by it. */
+export interface Contact {
+    timeZone: string | null;
+    timeZoneSource: TimeZoneSource | null;
+    /** The quiet hours that apply to them: their own, the agent's, or none ("off", or no time zone known). */
+    quietHours: QuietHours | null;
+    quietHoursSource: "person" | "agent" | "off" | "no_time_zone";
+    /** They texted STOP. */
+    stop: boolean;
+    /** Nothing the business starts until each of these (ms since the epoch). */
+    pauses: Array<{
+        id: string;
+        until: number | null;
+    }>;
+    /** What they asked not to be messaged about, in their words. */
+    topics: Array<{
+        id: string;
+        rule: string;
+        until: number | null;
+    }>;
+}
+/** A nudge as it stands now: `queued` until it is sent or settled, else how it settled. */
+export interface NudgeState {
+    id: string;
+    status: NudgeStatus | "queued";
+    reason?: string;
+}
+export declare class Agent {
+    private readonly conversations;
+    private readonly options;
+    private readonly settings;
+    private readonly store;
+    private readonly startedAt;
+    /** Conversations in the store, known once resume() ran. */
+    private readonly rows;
+    private resumed;
+    private readonly arriving;
+    /** Callers waiting for a queued nudge to settle: its first call, and any with the same key. */
+    private readonly nudgeWaiters;
+    private readonly now;
+    private readonly channelsByName;
+    /** Where each identity (channel, address) last wrote from; sends go back the same way. */
+    private readonly via;
+    private playgroundSink;
+    /** Before this, this runner does not ask for the pruning claim again (it, or another runner, had it). */
+    private pruneAfter;
+    /** `defaultCountryCode`'s digits. */
+    private readonly countryCode;
+    private readonly traces;
+    constructor(options: AgentOptions);
+    /**
+     * 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.
+     */
+    resume(): Promise<void>;
+    /**
+     * 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.
+     */
+    message(input: {
+        channel: string;
+        from: string;
+        message: string | Incoming;
+        messageId?: string;
+    }): Promise<{
+        conversationId: string;
+        messageId: string;
+    } | null>;
+    /**
+     * 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.
+     */
+    simulate(input: {
+        person: string;
+        channel: string;
+        message: string | Incoming;
+        messageId?: string;
+    }): Promise<{
+        conversationId: string;
+        messageId: string;
+    } | null>;
+    /** They wrote, so they are there: what was held for their quiet hours goes now, in this turn. */
+    private released;
+    /**
+     * 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.
+     */
+    private releaseHeld;
+    /** Sends the traces of finished turns still waiting for the traces endpoint; call it before the process exits. */
+    flushTraces(): Promise<void>;
+    /** The templates declared in `templates`. */
+    templates(): TemplateDefinition[];
+    /** The people declared in `testPeople`. */
+    testPeople(): TestPerson[];
+    /** A test person's conversation, by their phone number, or null if they have not written yet. */
+    testConversation(phone: string): Promise<string | null>;
+    /** Where the playground shows what is sent to test people who wrote from it; null detaches it. */
+    attachPlayground(sink: PlaygroundSink | null): void;
+    /** A conversation as the person saw it, from the store: their messages, the agent's, and its tool calls. */
+    transcript(conversationId: string): Promise<TranscriptEntry[]>;
+    /**
+     * 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.
+     */
+    forgetPerson(conversationId: string): Promise<void>;
+    private channelOf;
+    /** Messages from one address are taken in order, so a new person is made only once. */
+    private take;
+    private arrive;
+    /**
+     * 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.
+     */
+    private intercepted;
+    /**
+     * 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.
+     */
+    private keyword;
+    /** The identity a message comes from, made (and linked to its person's conversation) the first time it writes. */
+    private conversationFor;
+    /**
+     * 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.
+     */
+    private testPersonKey;
+    private testPerson;
+    /** A test person's address on a channel: their number on phone channels, else `test:<number>`. */
+    private testAddress;
+    /** Sends to one identity: to the playground if it last wrote from there, else through the channel's provider. */
+    private deliverer;
+    /**
+     * 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: string, message: string | Incoming, deliver: Deliver, options?: ReceiveOptions): string | 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: string, emoji: string, toText: string): void;
+    /** The channel reports that a message did not reach the person; the agent hears about it, also after a restart. */
+    undelivered(conversationId: string, text: string, reason: string): void;
+    /** 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. */
+    private withConversation;
+    conversation(conversationId: string): Conversation | undefined;
+    /**
+     * 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.
+     */
+    setTimeZone(input: {
+        to: {
+            channel: string;
+            address: string;
+        };
+        timeZone: string;
+    }): Promise<{
+        status: "set";
+    } | {
+        status: "refused";
+        reason: "unknown_person";
+    }>;
+    /**
+     * 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.
+     */
+    setQuietHours(input: {
+        to: {
+            channel: string;
+            address: string;
+        };
+        quietHours: QuietHours | "off" | null;
+    }): Promise<{
+        status: "set";
+    } | {
+        status: "refused";
+        reason: "unknown_person";
+    }>;
+    /** What the business and the person set for someone, by a channel identity they wrote from; null for someone who never wrote. */
+    contact(to: {
+        channel: string;
+        address: string;
+    }): Promise<Contact | null>;
+    /** A window-closed prompt nudge got no template from the agent: held until they reply, and the fallback goes now. */
+    private windowClosed;
+    /** The fallback template for a held nudge, once, and the event that says it wanted a template of its own. */
+    private sendFallback;
+    /**
+     * 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.
+     */
+    outbox(conversationId: string): Promise<{
+        schedules: ScheduledItem[];
+        held: HeldItem[];
+    }>;
+    /** Whether the agent has a profile (get_user_profile), so the test cloud knows to play it. */
+    hasProfile(): boolean;
+    nudge(input: NudgeInput): Promise<NudgeResult>;
+    /**
+     * 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.
+     */
+    recordNudge(input: NudgeInput): Promise<NudgeState>;
+    /** A nudge's state now, or null for an id the store does not hold. */
+    nudgeState(id: string): Promise<NudgeState | null>;
+    /** A recorded nudge as `nudge()` returns it: settled, or (still queued) once it settles. */
+    private outcome;
+    private waitFor;
+    private release;
+    /**
+     * 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`.
+     */
+    runDue(): Promise<number>;
+    /** Deletes provider message ids past their keep, in batches, when this runner claims it (at most hourly). */
+    private pruneMessageIds;
+    /** The agent's channels without their sends: what the simulators and the test cloud play. */
+    channels(): ChannelSummary[];
+    status(): AgentStatus;
+    /** The conversation in memory, made (and loaded from the store, if it is there) when needed. */
+    private open;
+    /** An inbox row for a conversation: handed to it in memory, or found when it loads. */
+    private wake;
+    private links;
+    /** What a channel can show: its adapter's, else what the conversation was last told. */
+    private infoOf;
+    private settle;
+    /** Their STOP, if they texted one. */
+    private stopOf;
+    /** Their STOP, or a pause in force: either way nothing the business starts goes now. */
+    private blockOf;
+    /** When their quiet hours end, if they are in them now; null when not, or when their time zone is not known. */
+    private quietEnd;
+    private result;
+    private mustBeResumed;
+}
+type Keyword = "stop" | "start" | "help";
+/**
+ * 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 declare function normalizePhone(address: string, countryCode?: string): string;
+export declare function createAgent(options: AgentOptions): Agent;
+export declare const DEFAULT_QUIET_HOURS: QuietHours;
+/** The quiet hours that apply to a person: their own, else the agent's (the default unless it turned them off). */
+export declare function quietHoursOf(row: Pick<ConversationRow, "quietHours">, agent: QuietHours | false | undefined): QuietHours | null;
+export {};