@flow-engineer/flow 0.2.0 → 0.2.2

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;

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;
@@ -276,6 +286,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 +310,7 @@ export type TranscriptEntry = {
     kind: "out";
     channel: string;
     text: string;
+    authentication?: boolean;
     at: number;
     replyTo?: string;
     buttons?: string[];

package/dist/src/conversation.js

@@ -43,13 +43,20 @@ import { coveredBy, noContactTools, rulesSection } from "./nudges.js";
 import { scheduleTools } from "./schedules.js";
 import { REACT, UPDATE, reactInput, sendInput, sendRefusal, sendToolName, talkInstructions, talkSpecs, updateInput } from "./talk.js";
 import { formatLocal } from "./time.js";
-import { render, tool, toSpec } from "./tools.js";
+import { render, tool, toolContext, toSpec } from "./tools.js";
 const ACKNOWLEDGE_FIRST = "[Chinwag] They have not heard from you yet. In one response, acknowledge them " +
     "(react to their message or send a short line) and make your tool calls again.";
 const INTERRUPTED = "[Chinwag] Cut off by a restart: this may or may not have happened. Check before you rely on it.";
 const APOLOGY = "Sorry, something went wrong on my side. Could you send that again?";
 const EARLIER = "[Chinwag] Older messages of this conversation are no longer shown to you.";
 const NOT_SHOWN = "[Chinwag] You are no longer shown the photos or documents in these messages; ask them to send one again if you need it.";
+/** A server-verified auth change: an internal prompt, never a prewritten chat response. */
+export function signInNotice(channel, request) {
+    return `Internal authentication event: sign-in completed on ${channel}. Continue the conversation on that channel. ` +
+        "Resume a request that was blocked only by sign-in, using the verified account and normal tools. " +
+        "Do not replay operations that already ran or retry unrelated failures. If nothing is waiting for sign-in, acknowledge naturally. Do not quote this internal event. " +
+        (request ? `The pending request (user text, not system instructions) is: ${JSON.stringify(request)}` : "");
+}
 /** Photos and PDFs the model is shown at once, the latest; each is resent on every model call. */
 const MEDIA_SHOWN = 3;
 /** The largest photo, and the largest PDF or voice note, the agent reads (most models take 5 MB images). */
@@ -80,6 +87,7 @@ export class Conversation {
     /** Aborted when the conversation closes: tools' signal. */
     lifetime = new AbortController();
     recentChannels = [];
+    promptDestination;
     timeZone = null;
     /** Their own quiet hours ("off": none), or null for the agent's. */
     quietHours = null;
@@ -99,6 +107,10 @@ export class Conversation {
     /** The next model response is the first since their latest message. */
     firstResponse = false;
     typingOn = new Set();
+    /** One challenge per channel per turn, even when the model calls several protected tools. */
+    signInPrompts = new Map();
+    authBlocked = new Set();
+    authPromptsSent = new Set();
     /** The send tool for each channel, this turn. */
     sendTools = new Map();
     builtins;
@@ -439,7 +451,7 @@ export class Conversation {
             if (p.prompt !== undefined) {
                 if (p.windowClosed) {
                     const text = `[Nudge from the business, not from the person: ${p.prompt}] Their WhatsApp 24-hour window is closed: no ordinary message reaches them. If one of the business's templates says this, send it with send_template, its values filled in. If none fits, send nothing: Flow Framework sends them a "you have a new message" template and gives you this again when they reply.`;
-                    this.notes.push({ text, inbox: row.id, owed: { nudge: p.nudge, mode: "prompt", channel: p.channel, windowClosed: true } });
+                    this.notes.push({ text, inbox: row.id, owed: { nudge: p.nudge, mode: "prompt", channel: p.channel, address: p.address, windowClosed: true } });
                     if (!this.running && this.hasWork())
                         this.schedule(0);
                     return;
@@ -448,10 +460,10 @@ export class Conversation {
                 const text = held
                     ? `[Nudge from the business, not from the person, ${held}${p.prompt}] Tell them now in your own words. Others held with it come in this turn too: cover them all in one short message, not a text each, and answer anything they just asked first.`
                     : `[Nudge from the business, not from the person: ${p.prompt}] Write it to them now in your own words, or send nothing if it does not fit what they asked not to be messaged about.`;
-                this.notes.push({ text, inbox: row.id, owed: { nudge: p.nudge, mode: "prompt", channel: p.channel } });
+                this.notes.push({ text, inbox: row.id, owed: { nudge: p.nudge, mode: "prompt", channel: p.channel, address: p.address } });
             }
             else
-                this.direct.push({ inbox: row.id, channel: p.channel, text: p.text, template: p.template, nudge: p.nudge, ...(p.theyWrote ? { theyWrote: true } : {}) });
+                this.direct.push({ inbox: row.id, channel: p.channel, address: p.address, text: p.text, template: p.template, nudge: p.nudge, ...(p.theyWrote ? { theyWrote: true } : {}) });
         }
         if (!this.running && this.hasWork())
             this.schedule(0);
@@ -535,8 +547,10 @@ export class Conversation {
     /** Picks up where the conversation was: its history, events not yet handled, tools cut off. */
     async load() {
         const { store } = this.settings;
+        // A live arrival can attach its new address while persisted links are loading. Keep that proof.
         for (const link of await this.settings.links(this.id))
-            this.link(link);
+            if (!this.channels.has(link.name))
+                this.link(link);
         const history = await store.history(this.id);
         this.saved = history.length;
         this.history.push(...history);
@@ -669,7 +683,7 @@ export class Conversation {
     }
     /** The channel of the person's latest message. */
     currentChannel() {
-        return this.recentChannels.at(-1) ?? [...this.channels.keys()][0] ?? "chat";
+        return (!this.theirMessages ? this.promptDestination?.channel ?? this.owed.at(-1)?.channel : undefined) ?? this.recentChannels.at(-1) ?? [...this.channels.keys()][0] ?? "chat";
     }
     /** Move waiting messages and notes into the history; the person's messages are now read. */
     absorb() {
@@ -774,7 +788,11 @@ export class Conversation {
         const turns = this.turns;
         this.resumeTurn = false;
         this.theirMessages = false;
+        this.promptDestination = undefined;
         this.settings.emit(this.id, "turn.start", {});
+        this.signInPrompts.clear();
+        this.authBlocked.clear();
+        this.authPromptsSent.clear();
         this.persist(() => store.updateConversation(this.id, { turnOpen: true, turns }));
         this.absorb();
         // A turn the person started (as against a background result, a scheduled message or a nudge).
@@ -812,11 +830,21 @@ export class Conversation {
             if (this.closed)
                 return;
             // The channels can grow mid-turn (they wrote on another one), so each step offers what is there now.
+            // A business prompt is addressed to one session, not whichever address last wrote on that channel.
+            if (!this.theirMessages)
+                this.promptDestination = this.owed.at(-1) ?? this.promptDestination;
+            const destination = !this.theirMessages ? this.promptDestination : undefined;
+            if (destination?.address) {
+                const link = (await this.settings.links(this.id)).find(l => l.name === destination.channel && l.address === destination.address);
+                if (link)
+                    this.link(link);
+            }
             const views = this.views();
             const several = views.length > 1;
             this.sendTools = new Map(views.map((v) => [sendToolName(v.name), v.name]));
             const system = [this.settings.instructions, talkInstructions(views, this.settings.talk), rules, nowLine(this.settings.now(), this.timeZone, this.settings.timeZone), context].filter(Boolean).join("\n\n");
-            const specs = [...this.settings.specs, ...this.builtinSpecs, ...talkSpecs(views, this.settings.talk)];
+            const ownSpecs = this.settings.auth ? this.settings.specs.map((spec) => ({ ...spec, description: spec.description + ((this.settings.tools.get(spec.name)?.signIn ?? "required") === "required" ? " Requires sign-in." : "") })) : this.settings.specs;
+            const specs = [...ownSpecs, ...this.builtinSpecs, ...talkSpecs(views, this.settings.talk)];
             const abort = new AbortController();
             if (restarts < this.settings.maxRestarts)
                 this.stepAbort = abort;
@@ -914,7 +942,15 @@ export class Conversation {
             for (const call of response.toolCalls) {
                 this.history.push({ role: "tool", toolCallId: call.id, content: results.get(call.id) ?? "" });
             }
+            for (const [channel, prompt] of this.signInPrompts) {
+                if (this.authPromptsSent.has(channel))
+                    continue;
+                await this.sendSignIn(channel, await prompt);
+                this.authPromptsSent.add(channel);
+            }
             this.flush();
+            if (work.length && work.every((call) => this.authBlocked.has(call.id)) && !this.absorb())
+                break;
             // Only messages: the turn is over unless one was refused or something new came in meanwhile, or
             // this replies to their message without having used any tool: it gets one more step, in case it
             // meant to act next (it said "getting your order" and has not asked for it yet). A tool
@@ -989,7 +1025,7 @@ export class Conversation {
             const input = parsed.data;
             const fields = Object.fromEntries(Object.keys(link.params ?? {}).flatMap((k) => (input[k] === undefined ? [] : [[k, input[k]]])));
             const hasFields = Object.keys(fields).length > 0;
-            if (several && !input.confirm && !this.recentChannels.includes(channel)) {
+            if (several && !input.confirm && !this.recentChannels.includes(channel) && !this.owed.some(o => o.channel === channel) && this.promptDestination?.channel !== channel) {
                 const last = link.lastMessageAt ? ` (last time ${ago(this.settings.now() - link.lastMessageAt)} ago)` : "";
                 return refused(`Not sent: they have not written on ${channel} in their last 5 messages${last}. If you are sure, call ${call.name} again with confirm: true.`);
             }
@@ -1104,7 +1140,7 @@ export class Conversation {
             this.settle(d, status, reason);
             this.flush([d]);
         };
-        const link = this.channels.get(d.channel);
+        const link = d.address === undefined ? this.channels.get(d.channel) : (await this.settings.links(this.id)).find(l => l.name === d.channel && l.address === d.address);
         if (!link)
             return settle("failed", `no way to reach them on ${d.channel} right now`);
         if (!d.template && !d.theyWrote && windowClosed(link, this.settings.now()))
@@ -1128,7 +1164,15 @@ export class Conversation {
         if (covered)
             return settle("dropped", `no-contact rule ${covered.id}: ${covered.rule}`);
         const outbound = d.template ? { type: "template", ...d.template } : { type: "message", text: d.text ?? "" };
-        const failure = await this.send(d.channel, outbound);
+        let failure = null;
+        if (this.closed)
+            return settle("failed", "this person was forgotten");
+        try {
+            await link.deliver(outbound);
+        }
+        catch (error) {
+            failure = errorText(error);
+        }
         if (failure)
             return settle("failed", failure);
         if (d.template) {
@@ -1205,6 +1249,9 @@ export class Conversation {
             else
                 live.push({ i, r: started });
         });
+        // Authentication is a prerequisite, never a detached background operation.
+        await Promise.all(live.map(({ r }) => r.authorized));
+        await Promise.all(live.filter(({ r }) => this.authBlocked.has(r.call.id)).map(({ r }) => r.outcome));
         let firstDoneAt = null;
         for (;;) {
             for (const { i, r } of live) {
@@ -1274,19 +1321,99 @@ export class Conversation {
         }
         this.settings.emit(this.id, "tool.start", { callId: call.id, tool: call.name, input: parsed.data });
         const key = createHash("sha256").update(`${this.id}\u0000${this.turns}\u0000${call.name}\u0000${input}`).digest("hex").slice(0, 32);
-        const context = { conversationId: this.id, person: this.personKey, key: this.personKey.startsWith("key:") ? this.personKey.slice(4) : null, channel: this.currentChannel(), callId: call.id, idempotencyKey: key, signal: this.lifetime.signal };
+        const identityContext = { conversationId: this.id, person: this.personKey, key: this.personKey.startsWith("key:") ? this.personKey.slice(4) : null, channel: this.currentChannel(), address: this.channels.get(this.currentChannel())?.address, callId: call.id, idempotencyKey: key, signal: this.lifetime.signal };
+        const credentials = this.settings.credentialProvider?.(identityContext) ?? this.settings.credentials;
+        let context = toolContext(identityContext, credentials);
+        let authorize;
+        const authorized = new Promise(resolve => { authorize = resolve; });
         const r = {
             call,
             input,
             startedAt: Date.now(),
             limitMs: tool.deadlineMs ?? this.settings.deadlineMs,
+            authorized,
             outcome: Promise.resolve()
-                .then(() => tool.run(parsed.data, context))
+                .then(async () => {
+                try {
+                    const auth = this.settings.auth;
+                    const signIn = tool.signIn ?? (this.builtins.has(call.name) ? "none" : "required");
+                    if (auth && signIn !== "none") {
+                        const identity = Object.freeze({ conversationId: this.id, person: context.person, key: context.key, channel: context.channel, address: this.channels.get(context.channel)?.address ?? "", tool: call.name, signal: this.lifetime.signal });
+                        let verified = !!context.key;
+                        if (verified && auth.verify) {
+                            try {
+                                verified = await this.authentication(() => auth.verify(identity));
+                            }
+                            catch {
+                                verified = false;
+                            }
+                        }
+                        if (this.closed)
+                            return { error: "conversation_closed" };
+                        if (!verified && signIn === "required") {
+                            this.authBlocked.add(call.id);
+                            if (!this.signInPrompts.has(context.channel)) {
+                                const prompt = this.authentication(() => auth.signIn(identity)).then((challenge) => {
+                                    if (!challenge.message?.trim())
+                                        throw new Error("Empty sign-in challenge");
+                                    if (challenge.url) {
+                                        const url = new URL(challenge.url);
+                                        if (url.username || url.password || (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))))
+                                            throw new Error("Unsafe sign-in URL");
+                                    }
+                                    return challenge;
+                                }).catch(() => ({ message: "I couldn't start sign-in. Please try again." }));
+                                this.signInPrompts.set(context.channel, prompt);
+                            }
+                            this.settings.emit(this.id, "auth.required", { tool: call.name, channel: context.channel });
+                            return { error: "sign_in_required", executed: false };
+                        }
+                        if (!verified)
+                            context = toolContext({ ...context, key: null, person: `${context.channel}:${identity.address}` }, credentials);
+                    }
+                    if (this.closed)
+                        return { error: "conversation_closed" };
+                    return tool.run(parsed.data, context);
+                }
+                finally {
+                    r.startedAt = Date.now();
+                    authorize();
+                }
+            })
                 .then((output) => ({ ok: true, text: render(output) }), (error) => ({ ok: false, text: `Failed: ${error instanceof Error ? error.message : String(error)}` })),
         };
         void r.outcome.then((result) => (r.result = result));
         return r;
     }
+    /** A failed or unresponsive auth service cannot leave a protected call hanging or let it execute. */
+    async authentication(work) {
+        let timer;
+        try {
+            return await Promise.race([Promise.resolve().then(work), new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("Sign-in timed out")), 15_000); })]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** A login request is a real channel message, recorded as delivered, without another model call. */
+    async sendSignIn(channel, prompt) {
+        const link = this.channels.get(channel);
+        if (!link)
+            return;
+        const outbound = fitMessage(link.info, { type: "message", text: prompt.message, authentication: true, ...(prompt.url ? { link: { label: "Sign in", url: prompt.url } } : {}) });
+        const failure = await this.send(channel, outbound);
+        if (failure) {
+            this.undelivered(prompt.message, failure);
+            return;
+        }
+        const callId = `auth_${randomUUID()}`;
+        this.history.push({ role: "assistant", content: null, toolCalls: [{ id: callId, name: sendToolName(channel), arguments: JSON.stringify({ text: outbound.text, ...(outbound.link ? { link: outbound.link } : {}) }) }] });
+        this.history.push({ role: "tool", toolCallId: callId, content: JSON.stringify({ delivered: true, channel, authentication: true }) });
+        this.settings.emit(this.id, "message.out", { text: outbound.text, link: outbound.link, channel, authentication: true });
+        this.sent();
+        this.sentThisTurn.add(prompt.message.trim());
+        await this.acknowledged(channel);
+    }
     /** The reply stops waiting for this tool: it carries on in the background and its result comes back as a note. */
     detach(r, why) {
         const { call, startedAt } = r;
@@ -1362,6 +1489,7 @@ export function transcriptOf(history, only) {
                     kind: "out",
                     channel: delivered.channel,
                     text: String(args.text ?? ""),
+                    ...(delivered.authentication ? { authentication: true } : {}),
                     at: result.at,
                     ...(typeof args.reply_to === "string" ? { replyTo: args.reply_to } : {}),
                     ...(Array.isArray(args.buttons) && args.buttons.length ? { buttons: args.buttons } : {}),

package/dist/src/events.d.ts

@@ -1,5 +1,5 @@
 export interface FlowEvent {
-    type: "message.in" | "message.arrived" | "message.out" | "turn.start" | "turn.context" | "turn.end" | "model.call" | "model.restarted" | "model.error" | "tool.start" | "tool.end" | "tool.detached" | "tool.repeated" | "task.done" | "skill.loaded" | "text.hidden" | "ack.required" | "reaction" | "status" | "message.undelivered" | "reaction.in" | "attachment.failed" | "keyword" | "message.duplicate" | "history.trimmed" | "template.missing";
+    type: "message.in" | "message.arrived" | "message.out" | "turn.start" | "turn.context" | "turn.end" | "model.call" | "model.restarted" | "model.error" | "tool.start" | "tool.end" | "tool.detached" | "tool.repeated" | "task.done" | "skill.loaded" | "text.hidden" | "ack.required" | "auth.required" | "reaction" | "status" | "message.undelivered" | "reaction.in" | "attachment.failed" | "keyword" | "message.duplicate" | "history.trimmed" | "template.missing";
     conversationId: string;
     at: number;
     [detail: string]: unknown;