@flow-engineer/flow 0.0.0-stage → 0.2.0

package/dist/src/conversation.d.ts

@@ -0,0 +1,361 @@
+import { z } from "zod";
+import type { Emit, EventSink } from "./events.ts";
+import type { ConversationRow, InboxRow, QuietHours, StoreApi, TimeZoneSource } from "./store.ts";
+import { type TalkSettings } from "./talk.ts";
+import { type Tool } from "./tools.ts";
+import type { ChannelInfo, ChatMessage, Deliver, Incoming, Model, TemplateDefinition, ToolSpec, Transcribe } from "./types.ts";
+export interface ConversationSettings {
+    model: Model;
+    /** Speech to text for voice notes; without it the agent is told it can't listen to them. */
+    transcribe?: Transcribe;
+    tools: Map<string, Tool>;
+    specs: ToolSpec[];
+    instructions: string;
+    /** Per-turn context for the system prompt (the person's profile, the time). */
+    context?: (conversationId: string) => Promise<string> | string;
+    /** Sinks that asked for turn.context. Others, traces included, do not receive it. */
+    contextSinks: EventSink[];
+    /** The longest a reply waits for a tool that sets no limit of its own. */
+    deadlineMs: number;
+    /** When one tool of a response is done and others still run this long after, the finished results go back. */
+    partialAfterMs: number;
+    debounceMs: number;
+    maxSteps: number;
+    /** About how many tokens one model call may carry (instructions, tools and history). */
+    historyTokens: number;
+    /** The longest a tool result is kept, in characters. */
+    toolResultChars: number;
+    /** How many times one step restarts for new messages before it lets the step finish. */
+    maxRestarts: number;
+    talk: TalkSettings;
+    emit: Emit;
+    store: StoreApi;
+    /** Resolves once the store's tables exist. */
+    ready: Promise<void>;
+    now: () => number;
+    /** The agent's own time zone (the business's): the time it is told when the person's is not known. */
+    timeZone?: string;
+    /** The agent's quiet hours for everyone (false: none), unless a person set their own. */
+    quietHours?: QuietHours | false;
+    /** The WhatsApp templates the owner declared: a sent one's text goes in the history. */
+    templates: TemplateDefinition[];
+    /** The declared template Flow Framework sends when no other one fits a closed window (createAgent's fallbackTemplate). */
+    fallbackTemplate?: string;
+    /** Tag every message with its channel (the agent has several), even for a person on one so far. */
+    tagChannels: boolean;
+    /** How the channels of a conversation loaded from the store are reached again. */
+    links(conversationId: string): Promise<ChannelLink[]>;
+    /** Records how a scheduled run or a nudge ended. */
+    settle(target: {
+        run?: string;
+        nudge?: string;
+    }, status: string, reason?: string): Promise<void>;
+    /** A window-closed prompt nudge the agent sent no template for: held until they reply, and the fallback goes. */
+    windowClosed(nudge: string, to: {
+        channel: string;
+        address: string;
+    }): Promise<void>;
+}
+/** One channel this person writes on, and how to reach them there. */
+export interface ChannelLink {
+    name: string;
+    info: ChannelInfo;
+    /** The channel's own extra fields on its send tool. */
+    params?: Record<string, z.ZodType>;
+    /** The agent author's guidance for this channel, in the system prompt while it is in use. */
+    instructions?: string;
+    address: string;
+    deliver: Deliver;
+    lastMessageAt: number | null;
+}
+interface Task {
+    id: string;
+    tool: string;
+    /** Its input, as checked, with keys in a fixed order: a repeat of a running call has the same. */
+    input: string;
+    startedAt: number;
+}
+export declare class Conversation {
+    readonly id: string;
+    readonly personKey: string;
+    readonly history: ChatMessage[];
+    private readonly settings;
+    private readonly channels;
+    private pending;
+    private notes;
+    /** A tool's result is in the history and no message has gone out since: from the background, or returned to a response. */
+    private resultUnsent;
+    /** What the agent has sent in this turn, to tell its own text repeated from something new. */
+    private sentThisTurn;
+    private direct;
+    private owed;
+    /** The person's message ids, and the channel each came on. */
+    private readonly messageIds;
+    private readonly knownInbox;
+    private messageCount;
+    /** Turns begun, kept in the store: tools' idempotency keys carry the turn's number. */
+    private turns;
+    /** Aborted when the conversation closes: tools' signal. */
+    private readonly lifetime;
+    private recentChannels;
+    private timeZone;
+    /** Their own quiet hours ("off": none), or null for the agent's. */
+    private quietHours;
+    private running;
+    /** Messages whose files are still being read (downloaded, transcribed); later ones wait behind them. */
+    private preparing;
+    private stepAbort;
+    /** Ends the reply's wait for its tools now (the person wrote). */
+    private wakeTools;
+    private timer;
+    private readonly tasks;
+    private taskCount;
+    private idleSince;
+    private settled;
+    /** Channels where nothing has reached the person since their latest message there. */
+    private readonly unanswered;
+    /** The next model response is the first since their latest message. */
+    private firstResponse;
+    private readonly typingOn;
+    /** The send tool for each channel, this turn. */
+    private sendTools;
+    private readonly builtins;
+    private readonly builtinSpecs;
+    private readonly loaded;
+    private writes;
+    /** History entries already in the store. */
+    private saved;
+    /** A turn was cut off by a restart: it runs again with the history so far. */
+    private resumeTurn;
+    /** Forgotten: nothing more runs, is sent or is kept. */
+    private closed;
+    /** This turn took in a message from the person: if it fails, they are told. */
+    private theirMessages;
+    /** History entries left out of the latest model call (0: none), so a change is an event once. */
+    private leftOut;
+    /** They texted STOP (as of the latest look): what the business starts is dropped, with no model call. */
+    private stop;
+    constructor(id: string, personKey: string, settings: ConversationSettings, existing?: ConversationRow | null);
+    /** Their time zone, as the business set it or they said it: schedules, quiet hours and the time line use it from now on. */
+    setTimeZone(zone: string, source: TimeZoneSource): Promise<void>;
+    /** Their own quiet hours ("off": none; null: back to the agent's). */
+    setQuietHours(hours: QuietHours | "off" | null): Promise<void>;
+    /**
+     * send_template: the agent sends one of the business's WhatsApp templates, its values filled, when
+     * Flow Framework tells it their 24-hour window is closed. The fallback template is Flow Framework's to send.
+     */
+    private templateTool;
+    /** What a channel of this conversation can show, if the person has written on it. */
+    channelInfo(channel: string): ChannelInfo | undefined;
+    /** Reach the person on this channel (again): a new channel, or a fresh way to deliver. */
+    link(link: ChannelLink): void;
+    /** A message from the person on `channel`; returns the id the agent sees it by. */
+    receive(input: string | Incoming, options: {
+        channel: string;
+        messageId?: string;
+    }): string;
+    /** The message is ready for the agent: it joins the reply in progress, or starts one. */
+    private arrive;
+    /**
+     * A message the agent's own rules answered with no model call (its intercept, a STOP, START or
+     * HELP keyword), and `reply`, what goes back to them ("" for nothing). Both join the history in
+     * order with their other messages, at the next step of a turn running now or else at once, and
+     * start no turn. Null when the channel gave this message before.
+     *
+     * `taken` is false when its provider id was taken first (by another runner, or before the STOP
+     * written in `claimed`, which already holds the id): nothing is kept then. `send` delivers the
+     * reply, unless it was not taken; it starts the delivery at once, so call it once `taken` where
+     * a retry must not be answered twice.
+     */
+    answered(input: string | Incoming, options: {
+        channel: string;
+        messageId?: string;
+        claimed?: Promise<boolean>;
+        note?: string;
+    }, reply: string): {
+        id: string;
+        taken: Promise<boolean>;
+        send(): Promise<void>;
+    } | null;
+    /**
+     * What the agent gets of the person's files: photos and PDFs the model reads, a voice note as its
+     * transcript, and for anything else a mark saying why it cannot be read, so it can ask for text.
+     */
+    private readFiles;
+    /** An event from the inbox (a scheduled run, a nudge) for this conversation. */
+    enqueue(row: InboxRow): void;
+    /**
+     * The person reacted to one of the agent's messages. The agent learns it at its next turn; a
+     * reaction alone does not start one.
+     */
+    reacted(emoji: string, toText: string): void;
+    /** The channel reports, now or later, that a message did not reach the person. */
+    undelivered(text: string, reason: string): void;
+    /**
+     * They texted a STOP or START keyword: their STOP is kept (or lifted) with no model call, with
+     * the message's provider id. Returns the line the agent learns it by, kept with the message
+     * (`answered`), and `stored`, false when that id was taken before.
+     */
+    keyword(kind: "stop" | "start", text: string, channel: string, messageId?: string): {
+        note: string;
+        stored: Promise<boolean>;
+    };
+    get busy(): boolean;
+    get idleForMs(): number;
+    get backgroundTasks(): Task[];
+    /** Resolves once nothing is running or waiting (no turn, no background task) and all is stored. */
+    whenIdle(): Promise<void>;
+    /** Resolves once everything so far is in the store. */
+    stored(): Promise<void>;
+    /**
+     * The person was forgotten: a step in flight is cut off, nothing waiting runs, nothing more is
+     * sent or kept. Tools already running finish on their own, and their results go nowhere.
+     */
+    close(): void;
+    /** Runs `work` after every earlier write to the store, in order. */
+    persist(work: () => Promise<unknown>): Promise<void>;
+    /** Picks up where the conversation was: its history, events not yet handled, tools cut off. */
+    private load;
+    /** Messages from the person the agent has yet to answer (not those answered with no model call). */
+    private unread;
+    private hasWork;
+    private note;
+    private schedule;
+    private run;
+    /**
+     * A turn threw (the model failed): what it owed is settled as failed, what was waiting is taken
+     * in so it is not tried again, and only a person waiting on a reply is told something went wrong.
+     * A turn they did not start (a nudge, a scheduled message, a background result) stays silent.
+     */
+    private turnFailed;
+    private checkIdle;
+    private views;
+    /** The channel of the person's latest message. */
+    private currentChannel;
+    /** Move waiting messages and notes into the history; the person's messages are now read. */
+    private absorb;
+    /** Stores history entries not yet stored, and marks the inbox rows they came from handled. */
+    private flush;
+    /** Only the latest MEDIA_SHOWN photos and PDFs keep their bytes; older ones are named, not shown. */
+    private showLatestMedia;
+    private turn;
+    private isTalk;
+    /** The channels a talk call reaches (for the acknowledgement rule), before it runs. */
+    private targets;
+    /**
+     * Run one of the send tools, react or share_updates. A message that went out says where it was
+     * delivered; one that failed on the way is told as a message of its own. `refused` is a call
+     * that did nothing because of its input: the agent gets another step to fix it.
+     */
+    private talk;
+    /** How a scheduled run or a nudge ended, stored in order with everything else. */
+    private settle;
+    /** A message reached the person: whatever this turn owed them is sent. */
+    private sent;
+    private acknowledged;
+    private typing;
+    /** Hand one outbound to a channel; returns why it failed, or null. */
+    private send;
+    /** A fixed-text scheduled message or a text or template nudge, sent with no model turn. */
+    private sendDirect;
+    /**
+     * The history the model is sent: all of it while it fits the budget, else the latest entries
+     * that do, from the start of one (never between a call and its result), after a line that says
+     * older ones are left out. The latest turn always goes, however long.
+     */
+    private window;
+    /** A tool result as the history keeps it: cut at toolResultChars, saying so. */
+    private capped;
+    /** The send tools the agent has right now, for Flow Framework's notes: "send_sms", or "send_sms or send_app". */
+    private sendToolsNow;
+    /**
+     * Run a response's tool calls together and wait for all of them, except: a message from the
+     * person ends the wait, a finished result waits at most partialAfterMs for the others, and a tool
+     * past its limit stops holding the reply. Whatever is still running then moves to the background.
+     */
+    private runTools;
+    /** Start one tool call; the model's input is checked first (a refusal is the call's result). */
+    private start;
+    /** The reply stops waiting for this tool: it carries on in the background and its result comes back as a note. */
+    private detach;
+}
+/** The business may not message first on this channel now (WhatsApp, past 24 hours). */
+export declare function windowClosed(link: {
+    info: ChannelInfo;
+    lastMessageAt: number | null;
+}, now: number): boolean;
+/** One line of a conversation as the person saw it, read back from the history (the playground shows these). */
+export type TranscriptEntry = {
+    kind: "in";
+    channel: string;
+    id: string;
+    text: string;
+    at: number;
+    choice?: boolean;
+} | {
+    kind: "out";
+    channel: string;
+    text: string;
+    at: number;
+    replyTo?: string;
+    buttons?: string[];
+    list?: {
+        button: string;
+        rows: Array<{
+            id: string;
+            title: string;
+            description?: string;
+        }>;
+    };
+    /** As the agent sent them: fitMessage shows them as a channel can. */
+    link?: {
+        label: string;
+        url: string;
+    };
+    image?: {
+        url: string;
+    };
+    /** The channel's own params the agent filled in. */
+    fields?: Record<string, unknown>;
+    /** A WhatsApp template the business sent, by name; the text is its body when it was declared. */
+    template?: string;
+} | {
+    kind: "reaction";
+    channel: string;
+    messageId: string;
+    emoji: string;
+    at: number;
+} | {
+    kind: "tool";
+    callId: string;
+    tool: string;
+    input: unknown;
+    output: string;
+    ok: boolean;
+    at: number;
+};
+/**
+ * The history as the person saw it: their messages (with their ids and channels), what the agent
+ * delivered with its send tools and reactions, and its other tool calls with their results.
+ * Flow Framework's notes and the agent's plain text never reached the person and are left out. `only` is
+ * the channel of untagged messages (an agent with one channel does not tag them).
+ */
+export declare function transcriptOf(history: Array<{
+    entry: ChatMessage;
+    at: number;
+}>, only: string): TranscriptEntry[];
+/**
+ * The time, for every turn: in their zone when the business or the person gave it, else in the
+ * business's, saying theirs is not known (never guessed from the business's).
+ */
+export declare function nowLine(now: number, personZone: string | null, agentZone: string | undefined): string;
+export declare const PROFILE_TOOL = "get_user_profile";
+/** The built-in tool over createAgent's `profile`: no input, so it is always about the person in this conversation. */
+export declare function profileTool(profile: Profile): Tool;
+/** createAgent's `profile`: what the business knows about the person, fetched only when the agent asks. */
+export type Profile = (who: {
+    conversationId: string;
+    person: string;
+    channel: string;
+}) => Promise<unknown> | unknown;
+export {};