@flow-engineer/flow 0.0.1 → 0.2.1

package/dist/src/db.d.ts

@@ -0,0 +1,18 @@
+export type Row = Record<string, unknown>;
+export interface Database {
+    /** The database survives a restart (a file, or a server); in-memory SQLite does not. */
+    readonly durable: boolean;
+    /** The SQL it speaks, where engines differ (column types in Flow Framework's tables). Default "sqlite". */
+    readonly dialect?: "sqlite" | "postgres";
+    /** Rows of a SELECT, or [] for a statement that returns none. */
+    query(sql: string, params?: unknown[]): Promise<Row[]>;
+    /** A statement that changes rows; resolves to how many it changed. */
+    run(sql: string, params?: unknown[]): Promise<number>;
+    /** Everything inside commits together or not at all. */
+    transaction<T>(work: (db: Omit<Database, "transaction">) => Promise<T>): Promise<T>;
+}
+/**
+ * SQLite in a file (one process may use it at a time) or, by default, in memory. Statements run
+ * one at a time per connection: a transaction holds the connection until it ends.
+ */
+export declare function sqlite(path?: string): Database;

package/dist/src/db.js

@@ -0,0 +1,57 @@
+// The database under Flow Framework's state. Flow Framework talks to it through this small interface, so any
+// engine can sit behind it: SQLite is built in (Node's own node:sqlite), and a Postgres adapter
+// wraps a client the app already has. SQL is written once with `?` placeholders; an adapter turns
+// them into its own.
+/**
+ * SQLite in a file (one process may use it at a time) or, by default, in memory. Statements run
+ * one at a time per connection: a transaction holds the connection until it ends.
+ */
+export function sqlite(path = ":memory:") {
+    const { DatabaseSync: Sqlite } = process.getBuiltinModule("node:sqlite");
+    const db = new Sqlite(path);
+    if (path !== ":memory:")
+        db.exec("PRAGMA journal_mode = WAL");
+    let lock = Promise.resolve();
+    const exclusive = (work) => {
+        const next = lock.then(work, work);
+        lock = next.catch(() => undefined);
+        return next;
+    };
+    const inner = {
+        durable: path !== ":memory:",
+        query: async (sql, params = []) => db.prepare(sql).all(...params),
+        run: async (sql, params = []) => Number(db.prepare(sql).run(...params).changes),
+    };
+    return {
+        durable: inner.durable,
+        query: (sql, params) => exclusive(() => inner.query(sql, params)),
+        run: (sql, params) => exclusive(() => inner.run(sql, params)),
+        transaction: (work) => exclusive(async () => {
+            await begin(db);
+            try {
+                const result = await work(inner);
+                db.exec("COMMIT");
+                return result;
+            }
+            catch (error) {
+                db.exec("ROLLBACK");
+                throw error;
+            }
+        }),
+    };
+}
+/** BEGIN IMMEDIATE, waiting while another connection to the same file holds it. */
+async function begin(db) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            db.exec("BEGIN IMMEDIATE");
+            return;
+        }
+        catch (error) {
+            const busy = error.errcode === 5;
+            if (!busy || attempt > 200)
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, 5));
+        }
+    }
+}

package/dist/src/events.d.ts

@@ -0,0 +1,17 @@
+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";
+    conversationId: string;
+    at: number;
+    [detail: string]: unknown;
+}
+/** @deprecated Renamed {@link FlowEvent} with the package (formerly chinwag). */
+export type ChinwagEvent = FlowEvent;
+/** A place events go. `context` asks for `turn.context`; without it the person's record is not sent. */
+export interface EventSink {
+    (event: FlowEvent): void;
+    context?: boolean;
+}
+/** One JSON line per event, to a file. */
+export declare function jsonlSink(path: string): EventSink;
+export declare function emitter(sinks: EventSink[]): (conversationId: string, type: FlowEvent["type"], detail?: Record<string, unknown>) => void;
+export type Emit = ReturnType<typeof emitter>;

package/dist/src/events.js

@@ -0,0 +1,20 @@
+// Observability: everything the agent does is an event. Sinks send them anywhere (a log, a
+// dashboard, a test); they must never throw into the conversation.
+import { appendFileSync } from "node:fs";
+/** One JSON line per event, to a file. */
+export function jsonlSink(path) {
+    return (event) => appendFileSync(path, JSON.stringify(event) + "\n");
+}
+export function emitter(sinks) {
+    return (conversationId, type, detail = {}) => {
+        const event = { type, conversationId, at: Date.now(), ...detail };
+        for (const sink of sinks) {
+            try {
+                sink(event);
+            }
+            catch (error) {
+                console.warn("flow: an event sink failed:", error);
+            }
+        }
+    };
+}

package/dist/src/http.d.ts

@@ -0,0 +1,45 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Agent } from "./agent.ts";
+/** Throws unless the token is a string of at least 32 characters; `what` names who needs it. */
+export declare function requireToken(token: unknown, what: string): asserts token is string;
+/** Whether two secrets are the same, in constant time whatever their lengths. */
+export declare function sameSecret(given: string, wanted: string): boolean;
+/** Wrong tokens per address: past MAX_FAILURES in a window, the address is refused until it ends. */
+export declare function wrongTries(): {
+    blocked(ip: string): boolean;
+    failed(ip: string): void;
+};
+export interface NudgeHandlerOptions {
+    /** At least 32 characters, from a secret; callers send it as `Authorization: Bearer <token>`. */
+    token: string;
+    /** The path it answers under. Default "/nudges". */
+    base?: string;
+}
+/** What the handler needs from an agent; Flow Framework's Agent is one. */
+export type NudgeAgent = Pick<Agent, "recordNudge" | "nudgeState" | "channels" | "templates">;
+/**
+ * Nudges over HTTP, as a request handler for your own server: hand it the requests under `base`.
+ * Requests outside `base` get 404 without a token check. A nudge refused or dropped as it is
+ * recorded (unknown_person, outside_window, a STOP) is still a 202: that is the nudge's state, not
+ * an HTTP error.
+ */
+export declare function nudgeHandler(agent: NudgeAgent, options: NudgeHandlerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+export interface PeopleHandlerOptions {
+    /** At least 32 characters, from a secret; callers send it as `Authorization: Bearer <token>`. */
+    token: string;
+    /** The path it answers under. Default "/people". */
+    base?: string;
+}
+/**
+ * What a business knows about people, over HTTP: their time zone and quiet hours, and their whole
+ * contact record (what they and the business set). Requests outside `base` get 404 without a token check.
+ *
+ *   PUT {base}/time-zone    { to, time_zone }                       → 200 { status: "set" }
+ *   PUT {base}/quiet-hours  { to, quiet_hours: { from, to } | "off" | null }  (null: the agent's)
+ *   GET {base}/contact?channel=&address=                            → 200 the contact record
+ *
+ * Someone who never wrote is 404 `{ status: "refused", reason: "unknown_person" }`.
+ */
+export declare function peopleHandler(agent: Pick<Agent, "setTimeZone" | "setQuietHours" | "contact" | "channels">, options: PeopleHandlerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+/** A path with its trailing slashes taken off, in one pass (no regular expression to backtrack). */
+export declare function withoutTrailingSlashes(path: string): string;

package/dist/src/http.js

@@ -0,0 +1,269 @@
+// Nudges and people's time zones over HTTP: handlers the owner mounts in their own server, so a
+// backend that is a separate service can reach the agent without routes of its own. Behind one
+// bearer token each.
+//
+// nudgeHandler:
+//   POST {base}        { to: { channel, address }, text | prompt | template, at?, idempotency_key? }
+//                      → 202 { id, status, reason? } as soon as it is recorded, before any send or turn
+//   GET  {base}/:id    → 200 { id, status, reason? }, its state now; 404 for an id the agent never recorded
+//
+// peopleHandler: a person's time zone and quiet hours as the business knows them, and their contact
+// record (see its doc comment below).
+//
+// The token lock (a token of at least 32 characters, compared in constant time, wrong tries limited
+// per address) is shared with the deployed playground.
+import { createHash, timingSafeEqual } from "node:crypto";
+import { z } from "zod";
+import { declaredTemplate, fillTemplate } from "./channels.js";
+/** Wrong tokens one address may try in a window before it is refused for the rest of it. */
+const MAX_FAILURES = 10;
+const FAILURE_WINDOW_MS = 15 * 60_000;
+const MAX_BODY = 16_384;
+/** Throws unless the token is a string of at least 32 characters; `what` names who needs it. */
+export function requireToken(token, what) {
+    if (typeof token !== "string" || token.length < 32)
+        throw new Error(`${what} needs a token of at least 32 characters`);
+}
+/** Whether two secrets are the same, in constant time whatever their lengths. */
+export function sameSecret(given, wanted) {
+    const hash = (text) => createHash("sha256").update(text).digest();
+    return timingSafeEqual(hash(given), hash(wanted));
+}
+/** Wrong tokens per address: past MAX_FAILURES in a window, the address is refused until it ends. */
+export function wrongTries() {
+    const failures = new Map();
+    return {
+        blocked(ip) {
+            const failed = failures.get(ip);
+            if (failed && failed.until <= Date.now())
+                failures.delete(ip);
+            return (failures.get(ip)?.count ?? 0) >= MAX_FAILURES;
+        },
+        failed(ip) {
+            const now = Date.now();
+            for (const [k, v] of failures)
+                if (v.until <= now)
+                    failures.delete(k);
+            const entry = failures.get(ip) ?? { count: 0, until: now + FAILURE_WINDOW_MS };
+            entry.count++;
+            failures.set(ip, entry);
+        },
+    };
+}
+const Header = z.union([
+    z.object({ kind: z.literal("text"), text: z.string() }).strict(),
+    z.object({ kind: z.enum(["image", "video", "document"]), url: z.string().optional(), fileId: z.string().optional() }).strict(),
+]);
+const Template = z
+    .object({
+    name: z.string().min(1),
+    language: z.string().optional(),
+    header: Header.optional(),
+    body: z.array(z.string()).optional(),
+    buttons: z.array(z.object({ index: z.number().int().nonnegative(), value: z.string() }).strict()).optional(),
+    variables: z.record(z.string(), z.string()).optional(),
+})
+    .strict();
+const Body = z
+    .object({
+    to: z.object({ channel: z.string().min(1), address: z.string().min(1) }).strict(),
+    text: z.string().min(1).optional(),
+    prompt: z.string().min(1).optional(),
+    template: Template.optional(),
+    /** Milliseconds since the epoch, as `agent.nudge()` takes it. */
+    at: z.number().int().nonnegative().optional(),
+    idempotency_key: z.string().min(1).max(200).optional(),
+    /** Wait for the end of their quiet hours (default true). */
+    respect_quiet_hours: z.boolean().optional(),
+    /** Held for quiet hours past this (ms since the epoch), it is dropped as expired. */
+    expires_at: z.number().int().nonnegative().optional(),
+})
+    .strict()
+    .refine((b) => [b.text, b.prompt, b.template].filter((v) => v !== undefined).length === 1, { message: "give exactly one of text, prompt or template" })
+    .refine((b) => !(b.template && b.at !== undefined), { message: "a template nudge cannot be scheduled yet: leave out at" });
+/**
+ * Nudges over HTTP, as a request handler for your own server: hand it the requests under `base`.
+ * Requests outside `base` get 404 without a token check. A nudge refused or dropped as it is
+ * recorded (unknown_person, outside_window, a STOP) is still a 202: that is the nudge's state, not
+ * an HTTP error.
+ */
+export function nudgeHandler(agent, options) {
+    requireToken(options?.token, "flow nudges");
+    const token = options.token;
+    const base = withoutTrailingSlashes(options.base ?? "/nudges");
+    const tries = wrongTries();
+    async function handle(req, res) {
+        const path = new URL(req.url ?? "/", "http://localhost").pathname;
+        const id = path.startsWith(`${base}/`) ? path.slice(base.length + 1) : null;
+        if (path !== base && (id === null || !id || id.includes("/")))
+            return json(res, 404, { error: "not found" });
+        const ip = req.socket.remoteAddress ?? "unknown";
+        if (!authorized(req, res, ip, token, tries))
+            return;
+        if (id !== null) {
+            if (req.method !== "GET")
+                return json(res, 404, { error: "not found" });
+            let asked;
+            try {
+                asked = decodeURIComponent(id);
+            }
+            catch {
+                return json(res, 404, { error: "no nudge with this id" });
+            }
+            const state = await agent.nudgeState(asked);
+            return state ? json(res, 200, state) : json(res, 404, { error: "no nudge with this id" });
+        }
+        if (req.method !== "POST")
+            return json(res, 404, { error: "not found" });
+        const raw = await readBody(req);
+        if (raw === undefined)
+            return json(res, 400, { error: `the body must be JSON of at most ${MAX_BODY} bytes` });
+        const parsed = Body.safeParse(raw);
+        if (!parsed.success)
+            return json(res, 400, { error: parsed.error.issues.map((i) => (i.path.length ? `${i.path.join(".")}: ${i.message}` : i.message)).join("; ") });
+        const body = parsed.data;
+        const channels = agent.channels().map((c) => c.name);
+        if (!channels.includes(body.to.channel))
+            return json(res, 400, { error: `to.channel must be one of the agent's channels: ${channels.join(", ") || "it has none"}` });
+        if (body.template) {
+            // A declared template sent with values that don't fit it is a bad request, not a failed nudge.
+            const declared = declaredTemplate(agent.templates(), body.template);
+            try {
+                if (declared)
+                    fillTemplate(declared, body.template);
+            }
+            catch (error) {
+                return json(res, 400, { error: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        const { idempotency_key, respect_quiet_hours, expires_at, ...rest } = body;
+        const input = {
+            ...rest,
+            ...(idempotency_key ? { idempotencyKey: idempotency_key } : {}),
+            ...(respect_quiet_hours !== undefined ? { respectQuietHours: respect_quiet_hours } : {}),
+            ...(expires_at !== undefined ? { expiresAt: expires_at } : {}),
+        };
+        const state = await agent.recordNudge(input);
+        const kind = body.text !== undefined ? "text" : body.prompt !== undefined ? "prompt" : "template";
+        console.info(JSON.stringify({ chinwag: "nudge", id: state.id, status: state.status, ...(state.reason ? { reason: state.reason } : {}), channel: body.to.channel, kind, at: new Date().toISOString(), ip }));
+        return json(res, 202, state);
+    }
+    return (req, res) => handle(req, res).catch((error) => {
+        console.warn("flow nudges:", error);
+        if (!res.headersSent)
+            json(res, 500, { error: "the nudge could not be recorded" });
+    });
+}
+/** Checks the bearer token, answering 401 or 429 itself when it fails. */
+function authorized(req, res, ip, token, tries) {
+    const bearer = /^Bearer (.+)$/.exec(req.headers.authorization ?? "")?.[1];
+    let refusal = null;
+    if (bearer === undefined)
+        refusal = [401, "send Authorization: Bearer <token>"];
+    else if (tries.blocked(ip))
+        refusal = [429, "too many wrong tokens from this address; try again later"];
+    else if (!sameSecret(bearer, token)) {
+        tries.failed(ip);
+        refusal = [401, "wrong token"];
+    }
+    if (refusal)
+        json(res, refusal[0], { error: refusal[1] });
+    return refusal === null;
+}
+const To = z.object({ channel: z.string().min(1), address: z.string().min(1) }).strict();
+const TimeZoneBody = z.object({ to: To, time_zone: z.string().min(1) }).strict();
+const Hours = z.object({ from: z.string(), to: z.string() }).strict();
+const QuietHoursBody = z.object({ to: To, quiet_hours: z.union([Hours, z.literal("off"), z.null()]) }).strict();
+/**
+ * What a business knows about people, over HTTP: their time zone and quiet hours, and their whole
+ * contact record (what they and the business set). Requests outside `base` get 404 without a token check.
+ *
+ *   PUT {base}/time-zone    { to, time_zone }                       → 200 { status: "set" }
+ *   PUT {base}/quiet-hours  { to, quiet_hours: { from, to } | "off" | null }  (null: the agent's)
+ *   GET {base}/contact?channel=&address=                            → 200 the contact record
+ *
+ * Someone who never wrote is 404 `{ status: "refused", reason: "unknown_person" }`.
+ */
+export function peopleHandler(agent, options) {
+    requireToken(options?.token, "flow people");
+    const token = options.token;
+    const base = withoutTrailingSlashes(options.base ?? "/people");
+    const tries = wrongTries();
+    const routes = new Set(["time-zone", "quiet-hours", "contact"]);
+    const unknown = { status: "refused", reason: "unknown_person" };
+    async function handle(req, res) {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const route = url.pathname.startsWith(`${base}/`) ? url.pathname.slice(base.length + 1) : "";
+        if (!routes.has(route))
+            return json(res, 404, { error: "not found" });
+        const ip = req.socket.remoteAddress ?? "unknown";
+        if (!authorized(req, res, ip, token, tries))
+            return;
+        const channels = agent.channels().map((c) => c.name);
+        const badChannel = (channel) => (channels.includes(channel) ? null : `to.channel must be one of the agent's channels: ${channels.join(", ") || "it has none"}`);
+        if (route === "contact") {
+            if (req.method !== "GET")
+                return json(res, 404, { error: "not found" });
+            const to = { channel: url.searchParams.get("channel") ?? "", address: url.searchParams.get("address") ?? "" };
+            if (!to.channel || !to.address)
+                return json(res, 400, { error: "give channel and address as query parameters" });
+            const problem = badChannel(to.channel);
+            if (problem)
+                return json(res, 400, { error: problem });
+            const contact = await agent.contact(to);
+            return contact ? json(res, 200, contact) : json(res, 404, unknown);
+        }
+        if (req.method !== "PUT")
+            return json(res, 404, { error: "not found" });
+        const raw = await readBody(req);
+        if (raw === undefined)
+            return json(res, 400, { error: `the body must be JSON of at most ${MAX_BODY} bytes` });
+        const parsed = (route === "time-zone" ? TimeZoneBody : QuietHoursBody).safeParse(raw);
+        if (!parsed.success)
+            return json(res, 400, { error: parsed.error.issues.map((i) => (i.path.length ? `${i.path.join(".")}: ${i.message}` : i.message)).join("; ") });
+        const body = parsed.data;
+        const problem = badChannel(body.to.channel);
+        if (problem)
+            return json(res, 400, { error: problem });
+        let result;
+        try {
+            result = route === "time-zone" ? await agent.setTimeZone({ to: body.to, timeZone: body.time_zone }) : await agent.setQuietHours({ to: body.to, quietHours: body.quiet_hours ?? null });
+        }
+        catch (error) {
+            return json(res, 400, { error: error instanceof Error ? error.message.replace(/^flow: /, "") : String(error) });
+        }
+        return json(res, result.status === "set" ? 200 : 404, result);
+    }
+    return (req, res) => handle(req, res).catch((error) => {
+        console.warn("flow people:", error);
+        if (!res.headersSent)
+            json(res, 500, { error: "that could not be done" });
+    });
+}
+/** A path with its trailing slashes taken off, in one pass (no regular expression to backtrack). */
+export function withoutTrailingSlashes(path) {
+    let end = path.length;
+    while (end > 0 && path[end - 1] === "/")
+        end--;
+    return path.slice(0, end);
+}
+/** The parsed JSON body, or undefined when it is too large or not JSON. */
+async function readBody(req) {
+    let size = 0;
+    const chunks = [];
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY)
+            return undefined;
+        chunks.push(chunk);
+    }
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function json(res, status, value) {
+    res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" }).end(JSON.stringify(value));
+}

package/dist/src/index.d.ts

@@ -0,0 +1,14 @@
+export { Agent, createAgent, type AgentOptions, type AgentStatus, type Contact, type HeldItem, type ScheduledItem, type NudgeInput, type NudgeResult, type NudgeState, type NudgeStatus, type PlaygroundSink, type ReceiveOptions, type TestPerson } from "./agent.ts";
+export { customUI, declaredTemplate, fillTemplate, fitMessage, sms, SMS_KEYWORDS, US_CARRIER_KEYWORDS, WHATSAPP_KEYWORDS, whatsapp, SMS, WHATSAPP, type Channel, type ChannelKind, type ChannelSummary, type CustomUIProvider, type FilledTemplate, type Keywords, type Message, type SmsProvider, type WhatsAppFeature, type WhatsAppProvider, } from "./channels.ts";
+export { Conversation, type Profile, type TranscriptEntry } from "./conversation.ts";
+export { nudgeHandler, peopleHandler, type NudgeHandlerOptions, type PeopleHandlerOptions } from "./http.ts";
+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 { 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 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

@@ -0,0 +1,11 @@
+export { Agent, createAgent } from "./agent.js";
+export { customUI, declaredTemplate, fillTemplate, fitMessage, sms, SMS_KEYWORDS, US_CARRIER_KEYWORDS, WHATSAPP_KEYWORDS, whatsapp, SMS, WHATSAPP, } from "./channels.js";
+export { Conversation } from "./conversation.js";
+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 { Store } from "./store.js";
+export { tool, toSpec } from "./tools.js";
+export { z } from "zod";

package/dist/src/model.d.ts

@@ -0,0 +1,21 @@
+import type { Model } from "./types.ts";
+export interface OpenAICompatibleOptions {
+    /** The provider's model id. When omitted, the key in the environment picks a default. */
+    model?: string;
+    apiKey?: string;
+    baseURL?: string;
+    temperature?: number;
+    /** The model sees photos (OpenAI-style image_url parts). Default true; false for a text-only model. */
+    images?: boolean;
+    /** The model reads PDFs (file parts). Default true on OpenRouter, which reads them for any model; false elsewhere. */
+    pdfs?: boolean;
+    /** Its context window in tokens, so the history sent is kept within it. */
+    contextTokens?: number;
+}
+/** Which key, address and model an omitted `apiKey` / `baseURL` resolve to. */
+export declare function modelFromKeys(env: Record<string, string | undefined>): {
+    apiKey?: string;
+    baseURL: string;
+    model: string;
+};
+export declare function openAICompatible(options?: OpenAICompatibleOptions): Model;

package/dist/src/model.js

@@ -0,0 +1,96 @@
+// Models over the OpenAI-compatible chat API: OpenRouter by default; OpenAI, Gemini, Anthropic or a
+// local server by changing the base URL.
+import OpenAI from "openai";
+/** The first of these with a value is the agent's model. `MODEL` overrides that provider's default id. */
+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" },
+];
+/** 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 { baseURL: KEYS[0].baseURL, model: named || KEYS[0].model };
+}
+export function openAICompatible(options = {}) {
+    // An explicit key or address is that provider. Otherwise the first key in the environment wins.
+    const fromEnv = options.apiKey !== undefined || options.baseURL !== undefined ? undefined : modelFromKeys(process.env);
+    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.
+    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.`);
+    }
+    const client = new OpenAI({
+        apiKey: apiKey || "none",
+        baseURL,
+        maxRetries: 1,
+    });
+    const model = options.model?.trim() || fromEnv?.model || KEYS[0].model;
+    return {
+        reads: { images: options.images ?? true, pdfs: options.pdfs ?? baseURL.startsWith("https://openrouter.ai/") },
+        ...(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 });
+            const message = completion.choices[0]?.message;
+            return {
+                text: message?.content?.trim() || null,
+                toolCalls: (message?.tool_calls ?? [])
+                    .filter((call) => call.type === "function")
+                    .map((call) => ({ id: call.id, name: call.function.name, arguments: call.function.arguments || "{}" })),
+                usage: completion.usage ? { inputTokens: completion.usage.prompt_tokens, outputTokens: completion.usage.completion_tokens, ...costOf(completion.usage) } : undefined,
+                model: completion.model,
+            };
+        },
+    };
+}
+function toWire(message) {
+    if (message.role === "tool")
+        return { role: "tool", tool_call_id: message.toolCallId, content: message.content };
+    if (message.role === "user") {
+        const media = (message.media ?? []).filter((m) => m.data);
+        if (!media.length)
+            return { role: "user", content: message.content };
+        return {
+            role: "user",
+            content: [
+                { type: "text", text: message.content },
+                ...media.map((m) => {
+                    const url = `data:${m.mime};base64,${m.data}`;
+                    return m.kind === "image" ? { type: "image_url", image_url: { url } } : { type: "file", file: { filename: m.name ?? "document.pdf", file_data: url } };
+                }),
+            ],
+        };
+    }
+    return {
+        role: "assistant",
+        content: message.content,
+        ...(message.toolCalls?.length
+            ? {
+                tool_calls: message.toolCalls.map((call) => ({
+                    id: call.id,
+                    type: "function",
+                    function: { name: call.name, arguments: call.arguments },
+                })),
+            }
+            : {}),
+    };
+}
+/** OpenRouter adds the call's cost in US dollars to usage; other providers leave it out. */
+function costOf(usage) {
+    const cost = usage.cost;
+    return typeof cost === "number" ? { costUsd: cost } : {};
+}

package/dist/src/names.d.ts

@@ -0,0 +1,22 @@
+/** A setting from the environment: FLOW_FRAMEWORK_<name>, else CHINWAG_<name> from before the rename. */
+export declare function setting(name: string, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * The command to print in a next step. `npx flow` would fetch another npm package wherever this one is
+ * not installed, so a hint always names the package.
+ */
+export declare const RUN = "npx @flow-engineer/flow";
+/** An agent's results folder, in the agent's folder: written here, and git-ignored by `flow new`. */
+export declare const RESULTS_DIR = ".flow";
+/** The results folder from before the rename, still read until a run writes {@link RESULTS_DIR}. */
+export declare const OLD_RESULTS_DIR = ".chinwag";
+/** ~/.config/flow-framework (XDG_CONFIG_HOME when set): where this machine's files are written. */
+export declare function configDir(env?: NodeJS.ProcessEnv): string;
+/** ~/.config/chinwag (XDG_CONFIG_HOME when set): the config folder from before the rename, only read. */
+export declare function oldConfigDir(env?: NodeJS.ProcessEnv): string;
+/**
+ * The file to read for a name in the config folder: ~/.config/flow-framework/<file>, else, while only it
+ * exists, ~/.config/chinwag/<file>. Write to {@link configDir} whichever this returns.
+ */
+export declare function configFile(file: string, env?: NodeJS.ProcessEnv): string;
+/** The file to read in an agent's results folder: .flow/<file>, else, while only it exists, .chinwag/<file>. */
+export declare function resultsFile(dir: string, file: string): string;

package/dist/src/names.js

@@ -0,0 +1,43 @@
+// The Flow Framework's names on a machine: its settings in the environment, its config folder and an
+// agent's results folder. Each is read under its name from before the rename (chinwag) too, so an
+// install that moved from chinwag keeps working; everything new is written under Flow Framework's name.
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** A setting from the environment: FLOW_FRAMEWORK_<name>, else CHINWAG_<name> from before the rename. */
+export function setting(name, env = process.env) {
+    return env[`FLOW_FRAMEWORK_${name}`] ?? env[`CHINWAG_${name}`];
+}
+/**
+ * The command to print in a next step. `npx flow` would fetch another npm package wherever this one is
+ * not installed, so a hint always names the package.
+ */
+export const RUN = "npx @flow-engineer/flow";
+/** An agent's results folder, in the agent's folder: written here, and git-ignored by `flow new`. */
+export const RESULTS_DIR = ".flow";
+/** The results folder from before the rename, still read until a run writes {@link RESULTS_DIR}. */
+export const OLD_RESULTS_DIR = ".chinwag";
+const configBase = (env) => env.XDG_CONFIG_HOME || join(homedir(), ".config");
+/** ~/.config/flow-framework (XDG_CONFIG_HOME when set): where this machine's files are written. */
+export function configDir(env = process.env) {
+    return join(configBase(env), "flow-framework");
+}
+/** ~/.config/chinwag (XDG_CONFIG_HOME when set): the config folder from before the rename, only read. */
+export function oldConfigDir(env = process.env) {
+    return join(configBase(env), "chinwag");
+}
+/**
+ * The file to read for a name in the config folder: ~/.config/flow-framework/<file>, else, while only it
+ * exists, ~/.config/chinwag/<file>. Write to {@link configDir} whichever this returns.
+ */
+export function configFile(file, env = process.env) {
+    const path = join(configDir(env), file);
+    const old = join(oldConfigDir(env), file);
+    return !existsSync(path) && existsSync(old) ? old : path;
+}
+/** The file to read in an agent's results folder: .flow/<file>, else, while only it exists, .chinwag/<file>. */
+export function resultsFile(dir, file) {
+    const path = join(dir, RESULTS_DIR, file);
+    const old = join(dir, OLD_RESULTS_DIR, file);
+    return !existsSync(path) && existsSync(old) ? old : path;
+}