@flow-engineer/flow 0.2.1 → 0.2.3

package/dist/src/agent.js

@@ -14,7 +14,7 @@
 // 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 { Conversation, PROFILE_TOOL, profileTool, signInNotice, transcriptOf, windowClosed } from "./conversation.js";
 import { sqlite } from "./db.js";
 import { emitter } from "./events.js";
 import { businessSchedule, claimDue, summary } from "./schedules.js";
@@ -36,6 +36,8 @@ export class Agent {
     /** Conversations in the store, known once resume() ran. */
     rows = new Map();
     resumed = false;
+    requestReplies = new Map();
+    requestCredentials = new Map();
     arriving = new Map();
     /** Callers waiting for a queued nudge to settle: its first call, and any with the same key. */
     nudgeWaiters = new Map();
@@ -44,6 +46,7 @@ export class Agent {
     /** Where each identity (channel, address) last wrote from; sends go back the same way. */
     via = new Map();
     playgroundSink = null;
+    playgroundVisitors = new Map();
     /** Before this, this runner does not ask for the pruning claim again (it, or another runner, had it). */
     pruneAfter = 0;
     /** `defaultCountryCode`'s digits. */
@@ -72,7 +75,7 @@ export class Agent {
             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;
+        this.traces = tracing ? traces(tracing, { service: options.id ?? "flow", kindOf: (name) => this.channelsByName.get(name)?.traceChannel ?? 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))
@@ -92,6 +95,9 @@ export class Agent {
             model: options.model,
             transcribe: options.transcribe,
             tools: new Map(tools.map((t) => [t.name, t])),
+            credentials: options.credentials,
+            credentialProvider: ctx => this.requestCredentials.get(viaKey(ctx.channel, ctx.address ?? "")) ?? options.credentials,
+            auth: options.auth,
             specs: tools.map(toSpec),
             instructions: loadInstructions(files, skills, options.inlineSkills),
             context: options.context,
@@ -145,6 +151,33 @@ export class Agent {
     async message(input) {
         return this.released(await this.take(this.channelOf(input.channel), { ...input, via: "provider" }));
     }
+    /**
+     * A signed-in HTTP channel's request. `key` must come from verified auth, never the body.
+     * Uses the same person as resolve() on other channels. The caller serializes requests per key.
+     */
+    async request(input) {
+        await this.settings.ready;
+        const adapter = this.channelOf(input.channel);
+        if (adapter.kind !== "custom")
+            throw new Error("chinwag: request needs a custom UI channel");
+        const identity = await this.conversationFor(adapter, input.channel, input.key, undefined, input.key);
+        if (input.conversationId && input.conversationId !== identity.conversationId)
+            throw new Error("chinwag: conversation does not belong to this person");
+        const replies = [];
+        const address = viaKey(input.channel, input.key);
+        if (input.credentials)
+            this.requestCredentials.set(address, input.credentials);
+        this.requestReplies.set(address, (reply) => { replies.push(reply); });
+        try {
+            await this.released(await this.take(adapter, { channel: input.channel, from: input.key, message: input.text, via: "provider", verifiedKey: input.key }));
+            await this.conversation(identity.conversationId)?.whenIdle();
+            return { conversationId: identity.conversationId, replies };
+        }
+        finally {
+            this.requestReplies.delete(address);
+            this.requestCredentials.delete(address);
+        }
+    }
     /**
      * 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
@@ -157,6 +190,106 @@ export class Agent {
         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 }));
     }
+    /**
+     * A playground visitor, signed out or authenticated. `key` is verified by server code, never
+     * accepted from the browser. Replies stay in the simulator; no provider send is made.
+     */
+    async simulateVisitor(input) {
+        if (!input.address)
+            throw new Error("chinwag: a playground visitor needs a server-issued channel address");
+        return this.released(await this.take(this.channelOf(input.channel), { channel: input.channel, from: input.key ? input.address : `visitor:${input.address}`, message: input.message, via: "playground", verifiedKey: input.key ?? undefined, visitor: input.key ? undefined : input.address }));
+    }
+    /**
+     * A completed server-verified login. Bind its channel address to the account before sending a
+     * confirmation with recordNudge/nudge. Never take key from a browser body or model input.
+     * Anonymous history stays separate; an identity belonging to another account is refused.
+     */
+    async linkIdentity(input) {
+        if (!input.address || !input.key)
+            throw new Error("chinwag: linking needs a verified account and channel address");
+        const adapter = this.channelOf(input.channel);
+        const lock = viaKey(input.channel, input.address);
+        const work = (this.arriving.get(lock) ?? Promise.resolve()).then(async () => {
+            await this.settings.ready;
+            const personKey = `key:${input.key}`;
+            let row = await this.store.conversationByKey(personKey);
+            if (!row) {
+                await this.store.createConversation(`p_${randomUUID().slice(0, 12)}`, personKey);
+                row = await this.store.conversationByKey(personKey);
+            }
+            if (!row)
+                throw new Error("chinwag: could not open the verified account conversation");
+            if (!await this.store.linkIdentity(row.id, input.channel, input.address))
+                throw new Error("chinwag: channel identity belongs to a different person");
+            const identity = (await this.store.identity(input.channel, input.address));
+            const via = input.via ?? identity.via;
+            if (identity.via !== via)
+                await this.store.setIdentityVia(input.channel, input.address, via);
+            this.via.set(lock, via);
+            if (via === "playground")
+                this.playgroundVisitors.set(lock, { key: input.key });
+            this.rows.set(row.id, row);
+            this.open(row.id).link({ name: input.channel, info: adapter.info, params: adapter.params, instructions: adapter.instructions, address: input.address, deliver: this.deliverer(adapter, input.address, row.id), lastMessageAt: identity.lastMessageAt });
+            return { conversationId: row.id };
+        });
+        this.arriving.set(lock, work.catch(() => undefined));
+        return work;
+    }
+    /** Wake the agent after verified sign-in; a repeated completion queues one internal event. */
+    async signInCompleted(input) {
+        await this.settings.ready;
+        if (!input.idempotencyKey)
+            throw new Error("chinwag: sign-in completion needs an idempotency key");
+        const earlier = await this.store.nudgeByKey(input.idempotencyKey);
+        if (earlier) {
+            const linked = await this.linkIdentity(input);
+            if (earlier.conversationId !== linked.conversationId || earlier.channel !== input.channel || earlier.body.address !== input.address)
+                throw new Error("chinwag: sign-in completion belongs to a different identity");
+            return this.result(earlier.id, earlier.status, earlier.reason);
+        }
+        const known = await this.store.identity(input.channel, input.address);
+        const anonymous = await this.store.identity(input.channel, `visitor:${input.address}`);
+        let source = input.conversationId ? [known, anonymous].find(i => i?.conversationId === input.conversationId) ?? null : known ?? anonymous;
+        if (input.conversationId && !source) {
+            // A previous attempt may have linked this address before the internal event could be queued.
+            const row = await this.store.conversation(input.conversationId);
+            const adapter = this.channelOf(input.channel);
+            const phone = adapter.phone ? normalizePhone(input.address, adapter.kind === "whatsapp" ? undefined : this.countryCode) : "";
+            const allowed = [`key:${input.key}`, `${input.channel}:${input.address}`, `${input.channel}:visitor:${input.address}`, ...(phone ? [`phone:${phone}`] : [])];
+            if (!row || !allowed.includes(row.personKey))
+                throw new Error("chinwag: sign-in context does not belong to this channel address");
+            source = { conversationId: row.id };
+        }
+        const history = source ? await this.transcript(source.conversationId) : [];
+        const latest = history.findLastIndex(e => e.kind === "in" && e.channel === input.channel);
+        const request = latest >= 0 ? history[latest] : undefined;
+        const after = history.slice(latest + 1);
+        const blocked = request?.kind === "in" && after.some(e => e.kind === "out" && e.channel === input.channel && e.authentication) && after.some(e => {
+            if (e.kind !== "tool")
+                return false;
+            try {
+                const output = JSON.parse(e.output);
+                return output.error === "sign_in_required" && output.executed === false;
+            }
+            catch {
+                return false;
+            }
+        });
+        const { conversationId } = await this.linkIdentity(input);
+        const account = source?.conversationId === conversationId ? history : await this.transcript(conversationId);
+        const newer = request && account.some(e => e.kind === "in" && e.at > request.at);
+        return this.recordNudge({ to: { channel: input.channel, address: input.address },
+            prompt: signInNotice(input.channel, blocked && !newer && request?.kind === "in" ? request.text : undefined),
+            idempotencyKey: input.idempotencyKey, respectQuietHours: false,
+        });
+    }
+    /** A verified playground visitor's account history, including messages on other interfaces. */
+    async visitorConversation(key, identity) {
+        await this.settings.ready;
+        if (!key)
+            return identity ? (await this.store.identity(identity.channel, `visitor:${identity.address}`))?.conversationId ?? null : null;
+        return (await this.store.conversationByKey(`key:${key}`))?.id ?? null;
+    }
     /** They wrote, so they are there: what was held for their quiet hours goes now, in this turn. */
     async released(taken) {
         if (taken)
@@ -254,7 +387,14 @@ export class Agent {
     }
     async arrive(adapter, input) {
         await this.settings.ready;
-        const identity = await this.conversationFor(adapter, input.channel, input.from, input.person);
+        const identity = await this.conversationFor(adapter, input.channel, input.from, input.person, input.verifiedKey);
+        if (input.via === "playground") {
+            const address = viaKey(input.channel, input.from);
+            if (input.verifiedKey || input.visitor)
+                this.playgroundVisitors.set(address, { key: input.verifiedKey, visitor: input.visitor });
+            else
+                this.playgroundVisitors.delete(address);
+        }
         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
@@ -309,10 +449,13 @@ export class Agent {
         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) {
+    async conversationFor(adapter, channel, address, testPerson, verifiedKey) {
         const known = await this.store.identity(channel, address);
-        if (known)
+        if (known) {
+            if (verifiedKey && (await this.store.conversation(known.conversationId))?.personKey !== `key:${verifiedKey}`)
+                throw new Error("chinwag: channel identity belongs to a different person");
             return known;
+        }
         let personKey;
         let verifiedBy;
         if (testPerson && !adapter.phone) {
@@ -320,8 +463,8 @@ export class Agent {
             [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) : "";
+            const owner = verifiedKey ?? await this.options.resolve?.({ channel, address, ...(phone ? { phone } : {}) });
             [personKey, verifiedBy] = owner ? [`key:${owner}`, "resolver"] : phone ? [`phone:${phone}`, "phone"] : [`${channel}:${address}`, "channel"];
         }
         let row = await this.store.conversationByKey(personKey);
@@ -347,7 +490,7 @@ export class Agent {
     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;
+        const owner = channel ? await this.options.resolve?.({ channel: channel.name, address: phone, ...(channel.phone ? { phone } : {}) }) : null;
         return owner ? `key:${owner}` : `phone:${phone}`;
     }
     testPerson(phone) {
@@ -362,13 +505,24 @@ export class Agent {
     /** 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) => {
+            const reply = this.requestReplies.get(viaKey(adapter.name, address));
+            if (reply)
+                return reply(outbound);
             if (this.via.get(viaKey(adapter.name, address)) !== "playground")
                 return adapter.send(address, outbound);
+            const visitor = this.playgroundVisitors.get(viaKey(adapter.name, address));
+            if (visitor)
+                return this.playgroundSink?.({ conversationId, person: { name: visitor.key ? "Signed-in user" : "New user", phone: "", ...visitor }, channel: adapter.name, 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 });
+            const key = this.rows.get(conversationId)?.personKey;
+            if (key?.startsWith("key:"))
+                return this.playgroundSink?.({ conversationId, person: { name: "Signed-in user", phone: "", key: key.slice(4) }, channel: adapter.name, outbound });
+            if (address.startsWith("visitor:"))
+                return this.playgroundSink?.({ conversationId, person: { name: "New user", phone: "", visitor: address.slice(8) }, channel: adapter.name, outbound });
         };
     }
     /**
@@ -601,7 +755,7 @@ export class Agent {
             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 body = { address: input.to.address, ...(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) {

package/dist/src/channels.d.ts

@@ -6,6 +6,8 @@ export interface Channel {
     /** The agent's name for it; its send tool is always send_<name> (lowercase, other characters as _). "key" and "phone" are reserved. */
     name: string;
     kind: ChannelKind;
+    /** Override the trace channel classification, e.g. a terminal custom UI as cli. */
+    traceChannel?: string;
     info: ChannelInfo;
     /** Addresses are phone numbers the channel verified, so the same number on two channels is one person. */
     phone?: boolean;
@@ -74,6 +76,8 @@ export interface Message {
     image?: {
         url: string;
     };
+    /** Given for a send the business starts (a nudge, a scheduled text): the same in every process, so a provider that takes one sends it once. */
+    idempotencyKey?: string;
 }
 export interface WhatsAppProvider {
     sendMessage(to: string, message: Message): Promise<void>;
@@ -88,12 +92,10 @@ export interface WhatsAppProvider {
     react?(to: string, messageId: string, emoji: string): Promise<void>;
     typing?(to: string, on: boolean): Promise<void>;
     markRead?(to: string, messageIds: string[]): Promise<void>;
-    sendTemplate?(to: string, template: Template): Promise<void>;
+    sendTemplate?(to: string, template: Template, idempotencyKey?: string): Promise<void>;
 }
 export interface SmsProvider {
-    sendMessage(to: string, message: {
-        text: string;
-    }): Promise<void>;
+    sendMessage(to: string, message: Pick<Message, "text" | "idempotencyKey">): Promise<void>;
 }
 /** Your own UI. `message` carries the text, any buttons, and your params by name. */
 export interface CustomUIProvider {

package/dist/src/channels.js

@@ -93,8 +93,8 @@ export function whatsapp(provider, options = {}) {
                 case "template": {
                     if (!provider.sendTemplate || off.has("templates"))
                         throw new Error("this WhatsApp provider sends no templates");
-                    const { type: _type, ...template } = outbound;
-                    return provider.sendTemplate(to, template);
+                    const { type: _type, idempotencyKey, ...template } = outbound;
+                    return provider.sendTemplate(to, template, idempotencyKey);
                 }
                 case "status":
                     return;
@@ -112,7 +112,7 @@ export function sms(provider, options = {}) {
         phone: true,
         send: (to, outbound) => {
             if (outbound.type === "message")
-                return provider.sendMessage(to, { text: outbound.text });
+                return provider.sendMessage(to, { text: outbound.text, ...(outbound.idempotencyKey ? { idempotencyKey: outbound.idempotencyKey } : {}) });
             if (outbound.type === "template")
                 throw new Error("SMS has no templates");
             // Reactions, typing, read receipts and status do not exist on SMS.
@@ -159,6 +159,7 @@ function message(outbound) {
         ...(outbound.list ? { list: outbound.list } : {}),
         ...(outbound.link ? { link: outbound.link } : {}),
         ...(outbound.image ? { image: outbound.image } : {}),
+        ...(outbound.idempotencyKey ? { idempotencyKey: outbound.idempotencyKey } : {}),
     };
 }
 /**

package/dist/src/conversation.d.ts

@@ -2,13 +2,16 @@ 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 ChatAuth, type CredentialProvider, type Tool, type ToolContext } 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>;
+    credentials?: CredentialProvider;
+    credentialProvider?: (context: Readonly<Omit<ToolContext, "credentials">>) => CredentialProvider | undefined;
+    auth?: ChatAuth;
     specs: ToolSpec[];
     instructions: string;
     /** Per-turn context for the system prompt (the person's profile, the time). */
@@ -68,6 +71,8 @@ export interface ChannelLink {
     deliver: Deliver;
     lastMessageAt: number | null;
 }
+/** A server-verified auth change: an internal prompt, never a prewritten chat response. */
+export declare function signInNotice(channel: string, request?: string): string;
 interface Task {
     id: string;
     tool: string;
@@ -98,6 +103,7 @@ export declare class Conversation {
     /** Aborted when the conversation closes: tools' signal. */
     private readonly lifetime;
     private recentChannels;
+    private promptDestination?;
     private timeZone;
     /** Their own quiet hours ("off": none), or null for the agent's. */
     private quietHours;
@@ -117,6 +123,10 @@ export declare class Conversation {
     /** The next model response is the first since their latest message. */
     private firstResponse;
     private readonly typingOn;
+    /** One challenge per channel per turn, even when the model calls several protected tools. */
+    private signInPrompts;
+    private authBlocked;
+    private authPromptsSent;
     /** The send tool for each channel, this turn. */
     private sendTools;
     private readonly builtins;
@@ -258,6 +268,7 @@ export declare class Conversation {
     private send;
     /** A fixed-text scheduled message or a text or template nudge, sent with no model turn. */
     private sendDirect;
+    private directSettled;
     /**
      * 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
@@ -276,6 +287,10 @@ export declare class Conversation {
     private runTools;
     /** Start one tool call; the model's input is checked first (a refusal is the call's result). */
     private start;
+    /** A failed or unresponsive auth service cannot leave a protected call hanging or let it execute. */
+    private authentication;
+    /** A login request is a real channel message, recorded as delivered, without another model call. */
+    private sendSignIn;
     /** The reply stops waiting for this tool: it carries on in the background and its result comes back as a note. */
     private detach;
 }
@@ -296,6 +311,7 @@ export type TranscriptEntry = {
     kind: "out";
     channel: string;
     text: string;
+    authentication?: boolean;
     at: number;
     replyTo?: string;
     buttons?: string[];