@flow-engineer/flow 0.2.1 → 0.2.3

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;
@@ -431,7 +443,7 @@ export class Conversation {
         }
         else if (row.kind === "schedule") {
             if (p.fixed)
-                this.direct.push({ inbox: row.id, channel: p.channel, text: p.text, run: p.run });
+                this.direct.push({ inbox: row.id, channel: p.channel, text: p.text, run: p.run, schedule: p.schedule });
             else
                 this.notes.push({ text: p.text, inbox: row.id, owed: { run: p.run, mode: p.mode, channel: p.channel } });
         }
@@ -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);
@@ -559,8 +573,14 @@ export class Conversation {
             this.note(`[Chinwag] ${task.tool} (${task.taskId}) was still running in the background when the agent restarted. It may or may not have finished; check before telling them it is done.`);
             this.persist(() => store.removeTask(this.id, task.taskId));
         }
-        for (const row of await store.openInbox(this.id))
-            this.enqueue(row);
+        for (const row of await store.openInbox(this.id)) {
+            // Already in the history (its row was not marked done): answered, so not answered again.
+            const p = row.payload;
+            if (row.kind === "message" && this.messageIds.get(p.id) === p.channel)
+                this.persist(() => store.doneInbox([row.id]));
+            else
+                this.enqueue(row);
+        }
         const row = await store.conversation(this.id);
         this.resumeTurn = row?.turnOpen === true;
         if ((this.resumeTurn || this.hasWork()) && !this.running)
@@ -669,7 +689,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 +794,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 +836,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 +948,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 +1031,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.`);
             }
@@ -1100,11 +1142,17 @@ export class Conversation {
     }
     /** A fixed-text scheduled message or a text or template nudge, sent with no model turn. */
     async sendDirect(d) {
+        // Settled already (by an earlier process, or another one running beside this): never sent twice.
+        if (await this.directSettled(d)) {
+            if (d.inbox !== undefined)
+                this.persist(() => this.settings.store.doneInbox([d.inbox]));
+            return;
+        }
         const settle = (status, reason) => {
             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()))
@@ -1127,8 +1175,18 @@ 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);
+        // The same key in every process, so the channel's provider sends it once.
+        const idempotencyKey = d.nudge ? `nudge:${d.nudge}` : d.run ? `run:${d.run}` : `inbox:${this.id}:${d.inbox}`;
+        const outbound = d.template ? { type: "template", ...d.template, idempotencyKey } : { type: "message", text: d.text ?? "", idempotencyKey };
+        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) {
@@ -1151,6 +1209,18 @@ export class Conversation {
         this.settings.emit(this.id, "message.out", { text: d.text ?? d.template?.name, channel: d.channel, direct: true });
         settle("sent");
     }
+    async directSettled(d) {
+        const { store } = this.settings;
+        if (d.nudge) {
+            const status = (await store.nudge(d.nudge))?.status;
+            return status !== undefined && !["queued", "held", "scheduled"].includes(status);
+        }
+        if (d.run && d.schedule) {
+            const outcome = (await store.runs(d.schedule)).find((r) => r.id === d.run)?.outcome;
+            return outcome !== undefined && outcome !== "queued" && outcome !== "held";
+        }
+        return false;
+    }
     /**
      * 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
@@ -1205,6 +1275,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 +1347,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 +1515,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;

package/dist/src/index.d.ts

@@ -5,10 +5,10 @@ export { nudgeHandler, peopleHandler, type NudgeHandlerOptions, type PeopleHandl
 export { sqlite, type Database } from "./db.ts";
 export { postgres, type PostgresPool } from "./postgres.ts";
 export { jsonlSink, type EventSink, type FlowEvent, type ChinwagEvent } from "./events.ts";
-export { openAICompatible, type OpenAICompatibleOptions } from "./model.ts";
+export { flowModel, flowModelURL, openAICompatible, type OpenAICompatibleOptions } from "./model.ts";
 export { Store, type StoreApi } from "./store.ts";
 export type { AgentFiles } from "./skills.ts";
 export type { TracesOptions } from "./traces.ts";
-export { tool, toSpec, type Tool, type ToolContext } from "./tools.ts";
+export { tool, toSpec, type ChatAuth, type ChatAuthContext, type CredentialProvider, type Credentials, type SignIn, type Tool, type ToolContext, type ToolHints } from "./tools.ts";
 export type { Attachment, ChannelInfo, ChatMessage, Deliver, Incoming, ListRow, Media, Model, ModelRequest, ModelResponse, Outbound, PersonMessage, Template, TemplateButton, TemplateDefinition, ToolCall, ToolSpec, Transcribe } from "./types.ts";
 export { z } from "zod";

package/dist/src/index.js

@@ -5,7 +5,7 @@ export { nudgeHandler, peopleHandler } from "./http.js";
 export { sqlite } from "./db.js";
 export { postgres } from "./postgres.js";
 export { jsonlSink } from "./events.js";
-export { openAICompatible } from "./model.js";
+export { flowModel, flowModelURL, openAICompatible } from "./model.js";
 export { Store } from "./store.js";
 export { tool, toSpec } from "./tools.js";
 export { z } from "zod";

package/dist/src/model.d.ts

@@ -12,6 +12,27 @@ export interface OpenAICompatibleOptions {
     /** Its context window in tokens, so the history sent is kept within it. */
     contextTokens?: number;
 }
+/** Flow's OpenAI-compatible model API, reached with FLOW_KEY. */
+export declare const FLOW_MODEL_URL = "https://flow.engineer/llm/framework/v1";
+/**
+ * Where FLOW_KEY is sent for the model: FLOW_MODEL_URL when set, else the origin of the Flow server the CLI
+ * signs in to (FLOW_FRAMEWORK_LOGIN_URL) with /llm/framework/v1, else flow.engineer's.
+ */
+export declare function flowModelURL(env?: Record<string, string | undefined>): string;
+/** The .env names a model key may be on, in the order they are read. */
+export declare const MODEL_KEY_NAMES: readonly string[];
+/**
+ * What to tell the owner when no model key is set, said the same way by `chat`, `npm start`,
+ * `init`, `setup` and `link`: one sentence, and `next` as a command (`nextLine` is how it is printed).
+ */
+export declare const NO_MODEL_KEY: {
+    readonly code: "no_model_key";
+    readonly message: `This agent has no model key: npx @flow-engineer/flow setup writes FLOW_KEY, the agent's Flow key (with the account's free trial model credit), into .env in the agent's folder, or put your own on one of the lines ${string} or ANTHROPIC_API_KEY= (an OpenRouter key is made at https://openrouter.ai/keys).` | `This agent has no model key: npx @flow-engineer/flow setup writes FLOW_KEY, the agent's Flow key (with the account's free trial model credit), into .env in the agent's folder, or put your own on one of the lines ${string} or FLOW_KEY= (an OpenRouter key is made at https://openrouter.ai/keys).` | `This agent has no model key: npx @flow-engineer/flow setup writes FLOW_KEY, the agent's Flow key (with the account's free trial model credit), into .env in the agent's folder, or put your own on one of the lines ${string} or GEMINI_API_KEY= (an OpenRouter key is made at https://openrouter.ai/keys).` | `This agent has no model key: npx @flow-engineer/flow setup writes FLOW_KEY, the agent's Flow key (with the account's free trial model credit), into .env in the agent's folder, or put your own on one of the lines ${string} or OPENAI_API_KEY= (an OpenRouter key is made at https://openrouter.ai/keys).` | `This agent has no model key: npx @flow-engineer/flow setup writes FLOW_KEY, the agent's Flow key (with the account's free trial model credit), into .env in the agent's folder, or put your own on one of the lines ${string} or OPENROUTER_API_KEY= (an OpenRouter key is made at https://openrouter.ai/keys).`;
+    readonly next: "npx @flow-engineer/flow setup";
+    readonly nextLine: "Next: run npx @flow-engineer/flow setup to get Flow's free trial credit, or add your own key.";
+};
+/** True when the environment names a model key with a value. */
+export declare const hasModelKey: (env: Record<string, string | undefined>) => boolean;
 /** Which key, address and model an omitted `apiKey` / `baseURL` resolve to. */
 export declare function modelFromKeys(env: Record<string, string | undefined>): {
     apiKey?: string;
@@ -19,3 +40,9 @@ export declare function modelFromKeys(env: Record<string, string | undefined>):
     model: string;
 };
 export declare function openAICompatible(options?: OpenAICompatibleOptions): Model;
+/**
+ * The model through Flow: FLOW_KEY (written by `flow setup`) at {@link flowModelURL}, the
+ * account's Flow trial credit paying. `model` is one Flow offers (default anthropic/claude-haiku-5.5;
+ * GET /models lists them). With no key it fails when made, with a next step.
+ */
+export declare function flowModel(options?: Omit<OpenAICompatibleOptions, "baseURL">): Model;

package/dist/src/model.js

@@ -1,20 +1,53 @@
 // Models over the OpenAI-compatible chat API: OpenRouter by default; OpenAI, Gemini, Anthropic or a
-// local server by changing the base URL.
+// local server by changing the base URL; or Flow, with the agent's FLOW_KEY that `flow setup` writes,
+// which needs no provider key and spends the account's Flow trial credit.
 import OpenAI from "openai";
-/** The first of these with a value is the agent's model. `MODEL` overrides that provider's default id. */
+import { setting } from "./names.js";
+/** Flow's OpenAI-compatible model API, reached with FLOW_KEY. */
+export const FLOW_MODEL_URL = "https://flow.engineer/llm/framework/v1";
+/**
+ * Where FLOW_KEY is sent for the model: FLOW_MODEL_URL when set, else the origin of the Flow server the CLI
+ * signs in to (FLOW_FRAMEWORK_LOGIN_URL) with /llm/framework/v1, else flow.engineer's.
+ */
+export function flowModelURL(env = process.env) {
+    const named = env.FLOW_MODEL_URL?.trim();
+    if (named)
+        return named;
+    const login = URL.parse(setting("LOGIN_URL", env)?.trim() ?? "");
+    return login ? `${login.origin}/llm/framework/v1` : FLOW_MODEL_URL;
+}
+/**
+ * The first of these with a value is the agent's model. `MODEL` overrides that provider's default id.
+ * Flow's key is last, so a provider key the owner adds wins over the FLOW_KEY setup wrote.
+ */
 const KEYS = [
     { env: "OPENROUTER_API_KEY", baseURL: "https://openrouter.ai/api/v1", model: "anthropic/claude-haiku-5.5" },
     { env: "OPENAI_API_KEY", baseURL: "https://api.openai.com/v1", model: "gpt-6-luna" },
     { env: "ANTHROPIC_API_KEY", baseURL: "https://api.anthropic.com/v1/", model: "claude-haiku-5-5" },
     { env: "GEMINI_API_KEY", baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/", model: "gemini-3.8-flash" },
+    { env: "FLOW_KEY", baseURL: FLOW_MODEL_URL, model: "anthropic/claude-haiku-5.5" },
 ];
+/** The .env names a model key may be on, in the order they are read. */
+export const MODEL_KEY_NAMES = KEYS.map((k) => k.env);
+/**
+ * What to tell the owner when no model key is set, said the same way by `chat`, `npm start`,
+ * `init`, `setup` and `link`: one sentence, and `next` as a command (`nextLine` is how it is printed).
+ */
+export const NO_MODEL_KEY = {
+    code: "no_model_key",
+    message: `This agent has no model key: npx @flow-engineer/flow setup writes FLOW_KEY, the agent's Flow key (with the account's free trial model credit), into .env in the agent's folder, or put your own on one of the lines ${KEYS.slice(0, -2).map((k) => `${k.env}=`).join(", ")} or ${KEYS.at(-2).env}= (an OpenRouter key is made at https://openrouter.ai/keys).`,
+    next: "npx @flow-engineer/flow setup",
+    nextLine: "Next: run npx @flow-engineer/flow setup to get Flow's free trial credit, or add your own key.",
+};
+/** True when the environment names a model key with a value. */
+export const hasModelKey = (env) => KEYS.some((k) => Boolean(env[k.env]?.trim()));
 /** Which key, address and model an omitted `apiKey` / `baseURL` resolve to. */
 export function modelFromKeys(env) {
     const named = env.MODEL?.trim();
     for (const provider of KEYS) {
         const apiKey = env[provider.env]?.trim();
         if (apiKey)
-            return { apiKey, baseURL: provider.baseURL, model: named || provider.model };
+            return { apiKey, baseURL: provider.env === "FLOW_KEY" ? flowModelURL(env) : provider.baseURL, model: named || provider.model };
     }
     return { baseURL: KEYS[0].baseURL, model: named || KEYS[0].model };
 }
@@ -24,8 +57,9 @@ export function openAICompatible(options = {}) {
     const baseURL = options.baseURL ?? fromEnv?.baseURL ?? KEYS[0].baseURL;
     const apiKey = options.apiKey ?? fromEnv?.apiKey ?? (process.env.OPENROUTER_API_KEY?.trim() || process.env.OPENAI_API_KEY?.trim());
     // A server at a base URL you name (a local one) may need no key; the client still sends one.
+    // Code that builds its model itself can also pass apiKey, or baseURL for a server that needs none.
     if (!apiKey && options.baseURL === undefined) {
-        throw new Error(`No model key: set one of ${KEYS.map((k) => k.env).join(", ")} (in the agent's .env), or pass apiKey, or baseURL for a server that needs none.`);
+        throw Object.assign(new Error(`${NO_MODEL_KEY.message}\n${NO_MODEL_KEY.nextLine}`), { code: NO_MODEL_KEY.code, next: NO_MODEL_KEY.next });
     }
     const client = new OpenAI({
         apiKey: apiKey || "none",
@@ -33,18 +67,26 @@ export function openAICompatible(options = {}) {
         maxRetries: 1,
     });
     const model = options.model?.trim() || fromEnv?.model || KEYS[0].model;
+    // Flow reads PDFs for every model it offers, as OpenRouter (behind it) does.
+    const readsPdfs = baseURL.startsWith("https://openrouter.ai/") || baseURL === flowModelURL(process.env);
     return {
-        reads: { images: options.images ?? true, pdfs: options.pdfs ?? baseURL.startsWith("https://openrouter.ai/") },
+        reads: { images: options.images ?? true, pdfs: options.pdfs ?? readsPdfs },
         ...(options.contextTokens ? { contextTokens: options.contextTokens } : {}),
         async complete(request) {
-            const completion = await client.chat.completions.create({
-                model,
-                temperature: options.temperature,
-                messages: [{ role: "system", content: request.system }, ...request.messages.map(toWire)],
-                ...(request.tools.length
-                    ? { tools: request.tools.map((t) => ({ type: "function", function: t })) }
-                    : {}),
-            }, { signal: request.signal });
+            let completion;
+            try {
+                completion = await client.chat.completions.create({
+                    model,
+                    temperature: options.temperature,
+                    messages: [{ role: "system", content: request.system }, ...request.messages.map(toWire)],
+                    ...(request.tools.length
+                        ? { tools: request.tools.map((t) => ({ type: "function", function: t })) }
+                        : {}),
+                }, { signal: request.signal });
+            }
+            catch (error) {
+                throw flowError(error) ?? error;
+            }
             const message = completion.choices[0]?.message;
             return {
                 text: message?.content?.trim() || null,
@@ -57,6 +99,36 @@ export function openAICompatible(options = {}) {
         },
     };
 }
+/**
+ * The model through Flow: FLOW_KEY (written by `flow setup`) at {@link flowModelURL}, the
+ * account's Flow trial credit paying. `model` is one Flow offers (default anthropic/claude-haiku-5.5;
+ * GET /models lists them). With no key it fails when made, with a next step.
+ */
+export function flowModel(options = {}) {
+    const apiKey = options.apiKey?.trim() || process.env.FLOW_KEY?.trim();
+    if (!apiKey) {
+        throw Object.assign(new Error(`FLOW_KEY is not set: npx @flow-engineer/flow setup writes it into .env in the agent's folder.\nNext: run ${NO_MODEL_KEY.next}.`), { code: NO_MODEL_KEY.code, next: NO_MODEL_KEY.next });
+    }
+    return openAICompatible({ ...options, apiKey, baseURL: flowModelURL(process.env), model: options.model?.trim() || process.env.MODEL?.trim() || KEYS.at(-1).model });
+}
+/**
+ * A typed error from Flow's model API ({"error": {message, type, code, next}}: trial_credit_used,
+ * invalid_api_key, rate_limit_exceeded, ...) as an Error with its message and next step; undefined
+ * for any other error, which is thrown as it came.
+ */
+function flowError(error) {
+    if (!(error instanceof OpenAI.APIError))
+        return undefined;
+    const body = error.error;
+    if (typeof body?.next !== "string" || !body.next || typeof body.message !== "string")
+        return undefined;
+    const sentence = body.message.trim();
+    return Object.assign(new Error(`${sentence}\nNext: ${body.next}`, { cause: error }), {
+        code: typeof body.code === "string" ? body.code : `http_${error.status}`,
+        next: body.next,
+        status: error.status,
+    });
+}
 function toWire(message) {
     if (message.role === "tool")
         return { role: "tool", tool_call_id: message.toolCallId, content: message.content };

package/dist/src/skills.d.ts

@@ -9,4 +9,8 @@ export type AgentFiles = Record<string, string>;
 export declare function readAgentFolder(dir: string): AgentFiles;
 export declare function loadSkills(files: AgentFiles): Skill[];
 export declare function loadInstructions(files: AgentFiles, skills: Skill[], inline?: boolean): string;
+/** What an MCP server tells a host about its skills when it connects (chinwag/mcp). */
+export declare function mcpInstructions(skills: Skill[]): string | undefined;
+/** The MCP server's way to read a skill: a tool, since every host calls tools. */
+export declare function readSkillTool(skills: Skill[]): Tool;
 export declare function skillTool(skills: Skill[], onLoad: (conversationId: string, name: string) => void): Tool;

package/dist/src/skills.js

@@ -51,10 +51,33 @@ export function loadInstructions(files, skills, inline = false) {
     const list = skills.map((s) => `- ${s.name}: ${s.description}`).join("\n");
     return `${base}\n\n## Skills\nLoad a skill with load_skill before doing what it covers; call it together with the first other tool you need, not on its own.\n${list}`;
 }
+/** What an MCP server tells a host about its skills when it connects (chinwag/mcp). */
+export function mcpInstructions(skills) {
+    if (!skills.length)
+        return undefined;
+    const list = skills.map((s) => `- ${s.name}: ${s.description}`).join("\n");
+    return `This server's skills are rules for one kind of request each. Read a skill with read_skill before doing what it covers.\n${list}`;
+}
+/** The MCP server's way to read a skill: a tool, since every host calls tools. */
+export function readSkillTool(skills) {
+    const names = skills.map((s) => s.name);
+    return tool({
+        name: "read_skill",
+        title: "Read a skill",
+        description: "Read one of this server's skills in full. Read it before doing what its description covers.",
+        input: z.object({ name: z.enum(names) }),
+        signIn: "none",
+        hints: { readOnly: true, openWorld: false },
+        run({ name }) {
+            return skills.find((s) => s.name === name)?.body ?? `No skill named ${name}.`;
+        },
+    });
+}
 export function skillTool(skills, onLoad) {
     const names = skills.map((s) => s.name);
     return tool({
         name: "load_skill",
+        signIn: "none",
         description: "Read a skill's full instructions. Use it before doing what the skill covers.",
         input: z.object({ name: z.enum(names) }),
         deadlineMs: 60_000,

package/dist/src/store.d.ts

@@ -95,6 +95,8 @@ export declare class Store {
     allConversations(): Promise<ConversationRow[]>;
     createConversation(id: string, personKey: string): Promise<void>;
     addIdentity(conversationId: string, channel: string, address: string, verifiedBy: string): Promise<void>;
+    /** Bind verified login proof; an identity already owned by another account cannot move. */
+    linkIdentity(conversationId: string, channel: string, address: string): Promise<boolean>;
     touchIdentity(channel: string, address: string, at: number): Promise<void>;
     setIdentityVia(channel: string, address: string, via: Via): Promise<void>;
     /**