@flow-engineer/flow 0.2.0 → 0.2.2

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/names.d.ts

@@ -1,5 +1,10 @@
 /** 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}. */

package/dist/src/names.js

@@ -8,6 +8,11 @@ import { join } from "node:path";
 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}. */

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>;
     /**

package/dist/src/store.js

@@ -153,6 +153,24 @@ export class Store {
     async addIdentity(conversationId, channel, address, verifiedBy) {
         await this.db.run("INSERT INTO identities (agent_id, channel, address, conversation_id, verified_by) VALUES (?, ?, ?, ?, ?) ON CONFLICT DO NOTHING", [this.agentId, channel, address, conversationId, verifiedBy]);
     }
+    /** Bind verified login proof; an identity already owned by another account cannot move. */
+    async linkIdentity(conversationId, channel, address) {
+        return this.db.transaction(async (tx) => {
+            const lock = this.db.dialect === "postgres" ? " FOR UPDATE" : "";
+            const [previous] = await tx.query(`SELECT conversation_id FROM identities WHERE agent_id = ? AND channel = ? AND address = ?${lock}`, [this.agentId, channel, address]);
+            const rows = await tx.query(`INSERT INTO identities (agent_id, channel, address, conversation_id, verified_by)
+        VALUES (?, ?, ?, ?, 'resolver') ON CONFLICT (agent_id, channel, address) DO UPDATE SET
+        conversation_id = excluded.conversation_id, verified_by = excluded.verified_by
+        WHERE identities.conversation_id = excluded.conversation_id OR EXISTS (
+          SELECT 1 FROM conversations c WHERE c.agent_id = identities.agent_id
+          AND c.id = identities.conversation_id AND c.person_key NOT LIKE 'key:%') RETURNING conversation_id`, [this.agentId, channel, address, conversationId]);
+            if (rows.length && previous && previous.conversation_id !== conversationId) {
+                // Signing in must not undo an anonymous sender's STOP or other no-contact preferences.
+                await tx.run("UPDATE no_contact SET conversation_id = ? WHERE agent_id = ? AND conversation_id = ?", [conversationId, this.agentId, previous.conversation_id]);
+            }
+            return rows.length > 0;
+        });
+    }
     async touchIdentity(channel, address, at) {
         await this.db.run("UPDATE identities SET last_message_at = ? WHERE agent_id = ? AND channel = ? AND address = ?", [at, this.agentId, channel, address]);
     }

package/dist/src/tools.d.ts

@@ -13,6 +13,8 @@ export interface ToolContext {
     key: string | null;
     /** The channel of their latest message. */
     channel: string;
+    /** Provider/server-issued address on a chat channel; absent for standalone MCP calls. */
+    address?: string;
     /** The model's id for this call, as the history keeps it. */
     callId: string;
     /**
@@ -23,7 +25,40 @@ export interface ToolContext {
     idempotencyKey: string;
     /** Aborted when the conversation closes (the person was forgotten): stop and drop the work. */
     signal: AbortSignal;
+    /** Server-side backend access for this verified person. Never supplied by the model or serialized into history or traces. */
+    credentials?: Credentials;
 }
+/** A business supplies named backend credentials or clients, resolved afresh for the verified person. */
+export type CredentialProvider = (name: string, context: Readonly<Omit<ToolContext, "credentials">>) => unknown | Promise<unknown>;
+export interface Credentials {
+    /** The business decides how to obtain, refresh and revoke access. The name is written by the tool author, not an account id from the model. */
+    get<T = unknown>(name: string): Promise<T>;
+}
+/** Server-side identity at a chat tool boundary. No credentials or model-supplied account ids. */
+export interface ChatAuthContext {
+    conversationId: string;
+    person: string;
+    key: string | null;
+    channel: string;
+    address: string;
+    tool: string;
+    signal: AbortSignal;
+}
+/** Brand-owned login: OAuth, an existing login page, verified phone, or a custom challenge. */
+export interface ChatAuth {
+    /** Recheck a resolved account's current access. Without this, a non-null resolved key is enough. */
+    verify?: (context: Readonly<ChatAuthContext>) => boolean | Promise<boolean>;
+    /** Called only when a protected operation needs authentication. A custom in-chat prompt needs no URL. */
+    signIn: (context: Readonly<ChatAuthContext>) => {
+        message: string;
+        url?: string;
+    } | Promise<{
+        message: string;
+        url?: string;
+    }>;
+}
+/** Bind backend access without putting secrets on an enumerable context or in any event. */
+export declare function toolContext(context: Omit<ToolContext, "credentials">, provider?: CredentialProvider): ToolContext;
 export interface Tool<Input = any> {
     name: string;
     description: string;
@@ -31,6 +66,35 @@ export interface Tool<Input = any> {
     run(input: Input, context: ToolContext): Promise<unknown> | unknown;
     /** The longest the reply waits for this tool before it moves to the background (default: the agent's, 60 s). */
     deadlineMs?: number;
+    /** A name for people ("Place an order"); derived from `name` when absent. */
+    title?: string;
+    /** The result's shape. Over MCP the result is checked against it and sent as structured content too. */
+    output?: z.ZodType;
+    /** Short lines a host shows while the tool runs and once it is done (at most 64 characters each). */
+    status?: {
+        running?: string;
+        done?: string;
+    };
+    /**
+     * Whether the person must be signed in. "required" (the default) refuses a call without sign-in,
+     * "optional" runs either way, "none" never needs it. Enforced where sign-in is configured:
+     * createAgent({ auth }) for chat, or mcpServer({ auth }) for MCP. Existing agents without auth
+     * keep their current behaviour.
+     */
+    signIn?: SignIn;
+    /** How the tool behaves, for hosts to decide what to ask the person first. Nothing enforces them. */
+    hints?: ToolHints;
+}
+export type SignIn = "required" | "optional" | "none";
+export interface ToolHints {
+    /** It changes nothing (default false: a tool counts as a write). */
+    readOnly?: boolean;
+    /** A write that may delete or overwrite (default true for writes; always false for reads). */
+    destructive?: boolean;
+    /** Calling it again with the same input changes nothing more (default false). */
+    idempotent?: boolean;
+    /** It reaches things outside the business's own systems, such as the web (default true). */
+    openWorld?: boolean;
 }
 /**
  * Marks a tool the test cloud plays in place of a built-in (get_user_profile): it is offered only
@@ -38,6 +102,11 @@ export interface Tool<Input = any> {
  */
 export declare const STAND_IN: unique symbol;
 export declare function tool<Input>(definition: Tool<Input>): Tool<Input>;
+/**
+ * Marks a tool whose input schema is given as JSON Schema (a tool another MCP server defines): the
+ * model is shown that schema exactly, not one rebuilt from the zod that validates it.
+ */
+export declare const INPUT_SCHEMA: unique symbol;
 export declare function toSpec(t: Tool): ToolSpec;
 /** A tool's output as the model reads it. */
 export declare function render(output: unknown): string;

package/dist/src/tools.js

@@ -1,6 +1,16 @@
 // Tools are plain functions with a zod input. The runtime decides at call time whether one runs
 // in the reply or carries on in the background; tool authors mark nothing.
 import { z } from "zod";
+/** Bind backend access without putting secrets on an enumerable context or in any event. */
+export function toolContext(context, provider) {
+    const identity = Object.freeze({ ...context });
+    if (provider)
+        Object.defineProperty(context, "credentials", {
+            value: Object.freeze({ get: (name) => Promise.resolve().then(() => provider(name, identity)) }),
+            enumerable: false,
+        });
+    return context;
+}
 /**
  * Marks a tool the test cloud plays in place of a built-in (get_user_profile): it is offered only
  * to an agent that has that built-in, and then instead of it, so a test never runs the real one.
@@ -9,8 +19,14 @@ export const STAND_IN = Symbol("chinwag.standIn");
 export function tool(definition) {
     return definition;
 }
+/**
+ * Marks a tool whose input schema is given as JSON Schema (a tool another MCP server defines): the
+ * model is shown that schema exactly, not one rebuilt from the zod that validates it.
+ */
+export const INPUT_SCHEMA = Symbol("chinwag.inputSchema");
 export function toSpec(t) {
-    const { $schema: _ignored, ...parameters } = z.toJSONSchema(t.input);
+    const given = t[INPUT_SCHEMA];
+    const { $schema: _ignored, ...parameters } = given ?? z.toJSONSchema(t.input);
     return { name: t.name, description: t.description, parameters };
 }
 /** A tool's output as the model reads it. */

package/dist/src/traces.js

@@ -41,10 +41,14 @@ export function tracesFromEnv(env = process.env) {
     return { key, url: setting("TRACES_URL", env)?.trim() || OBSERVE_URL, content: setting("TRACES_CONTENT", env) === "1" };
 }
 /** The endpoint's channel names: Flow Framework's custom UIs are web or app chats. */
-const CHANNEL_KIND = { sms: "sms", whatsapp: "whatsapp", custom: "web" };
+const CHANNEL_KIND = { sms: "sms", mms: "mms", whatsapp: "whatsapp", telegram: "telegram", imessage: "imessage", web: "web", voice: "voice", other: "other", custom: "web", cli: "cli" };
 let warnedMetadataOnly = false;
 export function traces(options, agent) {
-    const base = (options.url ?? "").replace(/\/+$/, "");
+    const url = options.url ?? "";
+    let end = url.length;
+    while (end > 0 && url.charCodeAt(end - 1) === 47)
+        end--;
+    const base = url.slice(0, end);
     if (!options.key)
         throw new Error("flow: traces need a key");
     if (!base)
@@ -58,6 +62,7 @@ export function traces(options, agent) {
         console.warn("flow: traces are metadata only. Set FLOW_FRAMEWORK_TRACES_CONTENT=1 to send what was written.");
     }
     const open = new Map();
+    const calls = new Map();
     /** Messages and background results that came while no turn was open: they join the next one. */
     const waiting = new Map();
     const queue = [];
@@ -168,6 +173,29 @@ export function traces(options, agent) {
         }
     }
     function handle(e) {
+        // An MCP/CLI call has no conversation or model turn. Reuse the same bounded exporter.
+        if (["mcp", "mcp-plugin", "cli"].includes(String(e.surface))) {
+            const call = String(e.callId);
+            if (e.type === "tool.start") {
+                calls.set(call, { at: e.at, ...(content ? { input: e.input } : {}) });
+                if (calls.size > MAX_QUEUED)
+                    calls.delete(calls.keys().next().value);
+            }
+            else if (e.type === "tool.end") {
+                const started = calls.get(call);
+                calls.delete(call);
+                const attributes = toolAttributes(e, started?.input);
+                attributes.push(attr("chinwag.surface", String(e.surface)), attr("openinference.span.kind", "TOOL"));
+                for (const [field, key] of Object.entries({ client: "chinwag.mcp.client", clientVersion: "chinwag.mcp.client_version", session: "chinwag.mcp.session", person: "chinwag.person", command: "chinwag.command" })) {
+                    if (typeof e[field] === "string")
+                        attributes.push(attr(key, e[field]));
+                }
+                if (e.ok === false)
+                    attributes.push(attr("error", typeof e.error === "string" ? clip(e.error) : "Tool failed"));
+                enqueue([span(hex(16), `mcp.call ${e.tool}`, started?.at ?? e.at - Number(e.ms ?? 0), e.at, attributes, undefined, e.ok === false)]);
+            }
+            return;
+        }
         const id = e.conversationId;
         const turn = open.get(id);
         switch (e.type) {
@@ -241,8 +269,8 @@ export function traces(options, agent) {
         const attributes = [attr("gen_ai.operation.name", "execute_tool"), attr("gen_ai.tool.name", String(e.tool)), attr("gen_ai.tool.call.id", String(e.callId))];
         if (content && input !== undefined)
             attributes.push(attr("gen_ai.tool.call.arguments", clip(JSON.stringify(input))));
-        if (content && typeof e.output === "string")
-            attributes.push(attr("gen_ai.tool.call.result", clip(e.output)));
+        if (content && e.output !== undefined)
+            attributes.push(attr("gen_ai.tool.call.result", clip(typeof e.output === "string" ? e.output : JSON.stringify(e.output))));
         return attributes;
     }
     return {

package/dist/src/types.d.ts

@@ -85,6 +85,8 @@ export interface ListRow {
 export type Outbound = {
     type: "message";
     text: string;
+    /** A framework-generated login challenge; its link opens real authentication in simulators. */
+    authentication?: boolean;
     /** The person's message this one quotes (channels with replies). */
     replyTo?: string;
     /** Reply buttons; a tap comes back as the person's message. */

package/dist/testing/src/account.d.ts

@@ -0,0 +1,4 @@
+export declare const ACCOUNT_COMMANDS: Set<string>;
+export declare const ACCOUNT_LINES = "  flow login [--wait | --no-wait] [--timeout <s>] [--force] [--no-browser] [--json]\n                            Sign in to flow.engineer: opens the browser, prints the link and code,\n                            and waits up to --timeout (default 120) for approval; --wait goes on\n                            waiting for the same code, --no-wait returns at once\n  flow logout [--json]      End this machine's sign-in and delete its token\n  flow whoami [--json]      Show the account you are signed in as\n  flow setup [--replace] [--rotate <keys> [--now]] [--ci] [--json]\n                            Write this agent's keys (its Flow key FLOW_KEY, which also pays for the\n                            model on the account's trial credit when there is no provider key, test\n                            cloud, traces, Flow Messaging) and each open channel's sender into\n                            ./.env (in an agent's folder: package.json); --rotate key,cloud,traces,\n                            messaging or all makes those keys again (the old FLOW_KEY works 24 h\n                            more; --now ends it at once)\n  flow link [--channel telegram|whatsapp|imessage] [--timeout <s>] [--no-browser] [--json]\n                            Print the link that opens a chat with this agent from a phone; signs in\n                            and runs setup first when this folder is not set up yet\n  flow status [--json]      What this folder has and lacks: FLOW_KEY and the model key (never their\n                            values) with the trial credit left, the\n                            sign-in, each channel's sender in .env, and, signed in, which channels\n                            are open now and their free-trial counts";
+/** Runs one account command; resolves to the exit status. */
+export declare function accountCli(command: string, args: string[]): Promise<number>;