@flow-engineer/flow 0.2.1 → 0.2.3

package/dist/flow-messaging/src/client.js

@@ -66,9 +66,9 @@ export class Client {
             throw await errorOf(response);
         return new Uint8Array(await response.arrayBuffer());
     }
-    /** A POST with its own Idempotency-Key, kept across the retries of this one call; `tries: 1` for courtesies. */
-    post(path, body, tries = TRIES) {
-        return this.request("POST", path, body, randomUUID(), tries);
+    /** A POST with its own Idempotency-Key (the caller's, else a new one), kept across the retries of this one call; `tries: 1` for courtesies. */
+    post(path, body, tries = TRIES, idempotencyKey = randomUUID()) {
+        return this.request("POST", path, body, idempotencyKey, tries);
     }
     async request(method, path, body, idempotencyKey, tries = TRIES) {
         if (!this.apiKey)

package/dist/flow-messaging/src/index.js

@@ -97,16 +97,16 @@ export function flowMessaging(options = {}) {
         return { phone: to.startsWith("+") ? to : `+${to}` };
     }
     /** One message: into the person's conversation, or a new one from the channel's sender. */
-    async function send(route, to, content, replyTo, about = replyTo) {
+    async function send(route, to, content, replyTo, about = replyTo, idempotencyKey) {
         try {
             const conversation = await conversationFor(route.name, to, about);
             let sent;
             if (conversation)
-                sent = await client.post(`/v1/conversations/${idSegment("conv", conversation)}/messages`, { content, ...(replyTo ? { reply_to: replyTo } : {}) });
+                sent = await client.post(`/v1/conversations/${idSegment("conv", conversation)}/messages`, { content, ...(replyTo ? { reply_to: replyTo } : {}) }, undefined, idempotencyKey);
             else {
                 if (!route.sender)
                     throw new Error(`no conversation with them on ${route.name} yet, and no sender to start one (set FLOW_MESSAGING_${route.kind.toUpperCase()}_SENDER)`);
-                sent = await client.post("/v1/messages", { sender: route.sender, to: recipient(route.kind, to), content });
+                sent = await client.post("/v1/messages", { sender: route.sender, to: recipient(route.kind, to), content }, undefined, idempotencyKey);
             }
             flowConversation.set(key(route.name, to), sent.conversation);
         }
@@ -114,7 +114,11 @@ export function flowMessaging(options = {}) {
             throw error instanceof FlowMessagingError ? new Error(reason(error)) : error;
         }
     }
-    /** Typing and read receipts are a courtesy: Flow's spec says to ignore their failures. */
+    /**
+     * Typing and read receipts are a courtesy: Flow's spec says to ignore their failures. Outside the
+     * window (iMessage and WhatsApp until the person writes) they are expected to be refused, so that
+     * is not logged; any other failure is, once.
+     */
     async function courtesy(route, to, action, body, messageId) {
         try {
             const conversation = await conversationFor(route.name, to, messageId);
@@ -122,6 +126,8 @@ export function flowMessaging(options = {}) {
                 await client.post(`/v1/conversations/${idSegment("conv", conversation)}/${action}`, body, 1);
         }
         catch (error) {
+            if (error instanceof FlowMessagingError && error.type === "outside_window")
+                return;
             console.warn(`@flow-engineer/flow/flow-messaging: ${action} on ${route.name} failed (${error instanceof FlowMessagingError ? error.type : "error"})`);
         }
     }
@@ -170,19 +176,20 @@ export function flowMessaging(options = {}) {
         return {
             sendMessage: async (to, message) => {
                 const [first, ...rest] = contents(route.kind, message);
-                await send(route, to, first, message.replyTo);
-                for (const next of rest)
-                    await send(route, to, next);
+                const key = message.idempotencyKey;
+                await send(route, to, first, message.replyTo, message.replyTo, key);
+                for (const [i, next] of rest.entries())
+                    await send(route, to, next, undefined, undefined, key && `${key}:${i + 1}`);
             },
             react: (to, messageId, emoji) => send(route, to, { type: "reaction", message_id: messageId, emoji }, undefined, messageId),
             typing: (to, on) => courtesy(route, to, "typing", { state: on ? "on" : "off" }),
             markRead: (to, messageIds) => courtesy(route, to, "read", { up_to: messageIds.at(-1) }, messageIds.at(-1)),
-            sendTemplate: async (to, wanted) => {
+            sendTemplate: async (to, wanted, idempotencyKey) => {
                 if (!route.sender)
                     throw new Error(`a template needs the channel's sender (set FLOW_MESSAGING_${route.kind.toUpperCase()}_SENDER)`);
                 const found = await template(route.sender, wanted);
                 const params = templateParams(wanted);
-                await send(route, to, { type: "template", template_id: found.id, language: wanted.language ?? found.language, ...(Object.keys(params).length ? { params } : {}) });
+                await send(route, to, { type: "template", template_id: found.id, language: wanted.language ?? found.language, ...(Object.keys(params).length ? { params } : {}) }, undefined, undefined, idempotencyKey);
             },
         };
     }
@@ -226,6 +233,7 @@ export function flowMessaging(options = {}) {
                             ...(outbound.buttons && info.buttons ? { buttons: outbound.buttons } : {}),
                             ...(outbound.link && info.linkButton ? { link: outbound.link } : {}),
                             ...(outbound.image && info.images ? { image: outbound.image } : {}),
+                            ...(outbound.idempotencyKey ? { idempotencyKey: outbound.idempotencyKey } : {}),
                         });
                     case "reaction":
                         return p.react(to, outbound.messageId, outbound.emoji);

package/dist/mcp/src/client.d.ts

@@ -0,0 +1,54 @@
+import { type Tool } from "../../src/tools.ts";
+export interface McpToolsOptions {
+    /** The server's name in mcp.lock.json. */
+    name: string;
+    /** Its Streamable HTTP endpoint. */
+    url: string;
+    /** Sent with every request, such as `authorization`. Keep keys in the environment, never in the lock. */
+    headers?: Record<string, string>;
+    /** Only these of its tools (default: every tool in the lock). */
+    only?: string[];
+    /** Put before each tool's name, to keep two servers' tools apart (default: none). */
+    prefix?: string;
+    /** Take the server's tools as they are now, with no lock (default false). */
+    live?: boolean;
+    /** Default: mcp.lock.json in the current folder (the agent's, for flow commands). */
+    lockFile?: string;
+}
+/** A tool as the server described it, as tools/list sends it. */
+export interface McpDescriptor {
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    annotations?: {
+        title?: string;
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+    };
+}
+export interface McpLock {
+    servers: Record<string, {
+        url: string;
+        tools: Record<string, {
+            fingerprint: string;
+            descriptor: McpDescriptor;
+        }>;
+    }>;
+}
+export declare const RECHECK_MS: number;
+/** Set by `flow mcp update`: mcpTools writes the server's current tools into the lock. */
+export declare const UPDATE_ENV = "CHINWAG_MCP_UPDATE";
+export declare function mcpTools(options: McpToolsOptions): Promise<Tool[]>;
+/** The fingerprint of what a model and a host see of a tool: any change to it is a change. */
+export declare function fingerprint(d: McpDescriptor): string;
+export declare function readLock(lockFile: string): McpLock;
+/**
+ * A model's placeholder for an argument it did not mean (null, "" or []) is left out when the schema
+ * does not require it, also inside objects: servers' validation refused them (Flow, 6 Oct 2026).
+ * false and 0 are real values and stay.
+ */
+export declare function withoutPlaceholders(value: Record<string, unknown>, schema: Record<string, unknown>): Record<string, unknown>;

package/dist/mcp/src/client.js

@@ -0,0 +1,175 @@
+// An existing MCP server's tools as Chinwag tools, so a chat agent uses them like its own.
+//
+// Pinned by default: the tools come from mcp.lock.json in the agent's folder (each tool's
+// descriptor and fingerprint, written by `flow mcp update`), never from what the server says
+// today. A tool the server has changed or removed since is refused with a clear error until the
+// lock is updated and committed: what was tested is what runs. Building the tools reads only the
+// lock; the server is first reached on a call, and its list is read again before a call once the
+// last look is older than RECHECK_MS. `live: true` takes the server's tools as they are instead.
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { z } from "zod";
+import { INPUT_SCHEMA } from "../../src/tools.js";
+export const RECHECK_MS = 5 * 60_000;
+/** Set by `flow mcp update`: mcpTools writes the server's current tools into the lock. */
+export const UPDATE_ENV = "CHINWAG_MCP_UPDATE";
+const IDEMPOTENCY_META = "chinwag/idempotency-key";
+export async function mcpTools(options) {
+    const lockFile = options.lockFile ?? join(process.cwd(), "mcp.lock.json");
+    const connection = connect(options);
+    if (options.live || process.env[UPDATE_ENV] === "1") {
+        const current = await connection.list();
+        if (!options.live)
+            writeLock(lockFile, options, current);
+        return picked(options, [...current.values()]).map((d) => wrap(options, d, connection, null));
+    }
+    const entry = readLock(lockFile).servers[options.name];
+    if (!entry)
+        throw new Error(`@flow-engineer/flow/mcp: ${options.name} is not in ${lockFile}. Run flow mcp update from the agent's folder, then commit the file.`);
+    return picked(options, Object.values(entry.tools).map((t) => t.descriptor)).map((d) => wrap(options, d, connection, entry.tools[d.name].fingerprint));
+}
+function picked(options, descriptors) {
+    return options.only ? descriptors.filter((d) => options.only.includes(d.name)) : descriptors;
+}
+/** The fingerprint of what a model and a host see of a tool: any change to it is a change. */
+export function fingerprint(d) {
+    const seen = { name: d.name, title: d.title, description: d.description, inputSchema: d.inputSchema, outputSchema: d.outputSchema, annotations: d.annotations };
+    return createHash("sha256").update(canonical(seen)).digest("hex");
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value).filter(([, v]) => v !== undefined).sort(([a], [b]) => (a < b ? -1 : 1));
+        return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+export function readLock(lockFile) {
+    if (!existsSync(lockFile))
+        return { servers: {} };
+    return JSON.parse(readFileSync(lockFile, "utf8"));
+}
+function writeLock(lockFile, options, current) {
+    const lock = readLock(lockFile);
+    const before = lock.servers[options.name]?.tools ?? {};
+    const tools = {};
+    for (const d of picked(options, [...current.values()]).sort((a, b) => (a.name < b.name ? -1 : 1)))
+        tools[d.name] = { fingerprint: fingerprint(d), descriptor: d };
+    for (const name of Object.keys(tools)) {
+        if (!before[name])
+            console.error(`  + ${options.name}.${name}`);
+        else if (before[name].fingerprint !== tools[name].fingerprint)
+            console.error(`  ~ ${options.name}.${name} changed`);
+    }
+    for (const name of Object.keys(before))
+        if (!tools[name])
+            console.error(`  - ${options.name}.${name} removed`);
+    lock.servers[options.name] = { url: options.url, tools };
+    const sorted = { servers: Object.fromEntries(Object.entries(lock.servers).sort(([a], [b]) => (a < b ? -1 : 1))) };
+    writeFileSync(lockFile, JSON.stringify(sorted, null, 2) + "\n");
+}
+function connect(options) {
+    let client;
+    let last;
+    function open() {
+        client ??= (async () => {
+            const c = new Client({ name: "flow", version: "1" });
+            await c.connect(new StreamableHTTPClientTransport(new URL(options.url), { requestInit: { headers: options.headers ?? {} } }));
+            return c;
+        })().catch((error) => {
+            client = undefined;
+            throw error;
+        });
+        return client;
+    }
+    async function list() {
+        const c = await open();
+        const tools = new Map();
+        let cursor;
+        do {
+            const page = await c.listTools(cursor ? { cursor } : {});
+            for (const t of page.tools)
+                tools.set(t.name, stripped(t));
+            cursor = page.nextCursor;
+        } while (cursor);
+        last = { at: Date.now(), tools };
+        return tools;
+    }
+    return {
+        list,
+        recent: async () => (last && Date.now() - last.at < RECHECK_MS ? last.tools : list()),
+        async call(name, args, meta, signal) {
+            const c = await open();
+            return (await c.callTool({ name, arguments: args, _meta: meta }, { signal }));
+        },
+    };
+}
+/** Only what the lock keeps of a descriptor. */
+function stripped(t) {
+    return { name: t.name, title: t.title, description: t.description, inputSchema: t.inputSchema, outputSchema: t.outputSchema, annotations: t.annotations };
+}
+function wrap(options, d, connection, locked) {
+    const a = d.annotations ?? {};
+    const hints = {
+        // A tool that does not say it only reads is taken as a write.
+        readOnly: a.readOnlyHint === true,
+        destructive: a.destructiveHint ?? true,
+        idempotent: a.idempotentHint ?? false,
+        openWorld: a.openWorldHint ?? true,
+    };
+    const t = {
+        name: `${options.prefix ?? ""}${d.name}`,
+        title: d.title ?? a.title,
+        description: d.description ?? "",
+        input: validator(d.inputSchema),
+        hints,
+        [INPUT_SCHEMA]: d.inputSchema,
+        async run(input, context) {
+            if (locked) {
+                const now = (await connection.recent()).get(d.name);
+                if (!now)
+                    throw new Error(`${options.name} no longer has ${d.name}. The agent's mcp.lock.json must be updated (flow mcp update) before it can be used.`);
+                if (fingerprint(now) !== locked)
+                    throw new Error(`${options.name} changed ${d.name} since it was tested. The agent's mcp.lock.json must be updated (flow mcp update) before it can be used.`);
+            }
+            const result = await connection.call(d.name, withoutPlaceholders(input, d.inputSchema), { [IDEMPOTENCY_META]: context.idempotencyKey }, context.signal);
+            const text = result.content
+                .map((block) => (block.type === "text" ? block.text : `[${block.type} not shown]`))
+                .join("\n");
+            if (result.isError)
+                throw new Error(text || `${d.name} failed.`);
+            return result.structuredContent ?? text;
+        },
+    };
+    return t;
+}
+/** Arguments are checked by the zod made from the server's schema; the server checks them again. */
+function validator(schema) {
+    try {
+        return z.fromJSONSchema(schema);
+    }
+    catch {
+        return z.looseObject({});
+    }
+}
+/**
+ * A model's placeholder for an argument it did not mean (null, "" or []) is left out when the schema
+ * does not require it, also inside objects: servers' validation refused them (Flow, 6 Oct 2026).
+ * false and 0 are real values and stay.
+ */
+export function withoutPlaceholders(value, schema) {
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    const properties = (schema.properties ?? {});
+    const out = {};
+    for (const [key, v] of Object.entries(value)) {
+        const empty = v === null || v === "" || (Array.isArray(v) && v.length === 0);
+        if (empty && !required.has(key))
+            continue;
+        const nested = properties[key];
+        out[key] = v && typeof v === "object" && !Array.isArray(v) && nested?.properties ? withoutPlaceholders(v, nested) : v;
+    }
+    return out;
+}

package/dist/mcp/src/describe.d.ts

@@ -0,0 +1,41 @@
+import type { SignIn, Tool } from "../../src/tools.ts";
+/** An MCP tool as `tools/list` sends it. */
+export interface McpToolDescriptor {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        [key: string]: unknown;
+    };
+    outputSchema?: {
+        [key: string]: unknown;
+    };
+    annotations: {
+        title: string;
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+    _meta: Record<string, unknown>;
+}
+/** The scopes an MCP server asks for: reads need `read`, writes `write` (both when given). */
+export interface Scopes {
+    read?: string;
+    write?: string;
+}
+/** Tools that exist only in a chat: a description naming one points a host at a tool it does not have. */
+export declare const CHAT_ONLY: RegExp;
+export declare function signInOf(tool: Tool): SignIn;
+export declare function isReadOnly(tool: Tool): boolean;
+/** The scopes a call needs, given the server's scope names. */
+export declare function scopesFor(tool: Tool, scopes: Scopes | undefined): string[];
+/** "place_order" → "Place order". */
+export declare function titleOf(tool: Tool): string;
+/** The MCP descriptor for a tool. Throws when its input or output has no exact JSON Schema. */
+export declare function describe(tool: Tool, scopes?: Scopes): McpToolDescriptor;
+/** Why a tool cannot be served over MCP exactly as declared, one sentence each (empty when it can). */
+export declare function toolProblems(tool: Tool): string[];
+/** Problems across a server's tools: each tool's, and names used twice. */
+export declare function toolsProblems(tools: Tool[]): string[];

package/dist/mcp/src/describe.js

@@ -0,0 +1,110 @@
+// A Chinwag tool as an MCP tool (spec 2026-07-28), and the rules that make that translation exact.
+// Every field of the descriptor comes from the tool or a stated default; nothing is guessed, and a
+// tool that cannot be described exactly is a problem `flow check` reports, not a schema we bend.
+import { z } from "zod";
+const NAME = /^[A-Za-z0-9_.-]{1,128}$/;
+const STATUS_MAX = 64;
+/** Tools that exist only in a chat: a description naming one points a host at a tool it does not have. */
+export const CHAT_ONLY = /\b(send_[a-z0-9_]+|share_updates|load_skill)\b/;
+export function signInOf(tool) {
+    return tool.signIn ?? "required";
+}
+export function isReadOnly(tool) {
+    return tool.hints?.readOnly ?? false;
+}
+/** The scopes a call needs, given the server's scope names. */
+export function scopesFor(tool, scopes) {
+    const name = isReadOnly(tool) ? scopes?.read : scopes?.write;
+    return name ? [name] : [];
+}
+/** "place_order" → "Place order". */
+export function titleOf(tool) {
+    if (tool.title)
+        return tool.title;
+    const words = tool.name.replace(/[_.-]+/g, " ").replace(/([a-z])([A-Z])/g, "$1 $2").trim().toLowerCase();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+function jsonSchema(schema) {
+    const { $schema: _ignored, ...rest } = z.toJSONSchema(schema, { target: "draft-2020-12", unrepresentable: "throw", io: "input" });
+    return rest;
+}
+/** The MCP descriptor for a tool. Throws when its input or output has no exact JSON Schema. */
+export function describe(tool, scopes) {
+    const readOnly = isReadOnly(tool);
+    const title = titleOf(tool);
+    const inputSchema = jsonSchema(tool.input);
+    const signIn = signInOf(tool);
+    const oauth = { type: "oauth2", scopes: scopesFor(tool, scopes) };
+    const _meta = {
+        // ChatGPT reads sign-in per tool from here; the spec keeps it at the HTTP layer only.
+        securitySchemes: signIn === "none" ? [{ type: "noauth" }] : signIn === "optional" ? [{ type: "noauth" }, oauth] : [oauth],
+    };
+    if (tool.status?.running)
+        _meta["openai/toolInvocation/invoking"] = tool.status.running;
+    if (tool.status?.done)
+        _meta["openai/toolInvocation/invoked"] = tool.status.done;
+    return {
+        name: tool.name,
+        title,
+        description: tool.description,
+        inputSchema,
+        ...(tool.output ? { outputSchema: jsonSchema(tool.output) } : {}),
+        annotations: {
+            title,
+            readOnlyHint: readOnly,
+            destructiveHint: readOnly ? false : (tool.hints?.destructive ?? true),
+            idempotentHint: tool.hints?.idempotent ?? false,
+            openWorldHint: tool.hints?.openWorld ?? true,
+        },
+        _meta,
+    };
+}
+/** Why a tool cannot be served over MCP exactly as declared, one sentence each (empty when it can). */
+export function toolProblems(tool) {
+    const problems = [];
+    const at = `tool ${tool.name}`;
+    if (!NAME.test(tool.name))
+        problems.push(`${at}: the name must be 1 to 128 of A-Z a-z 0-9 _ - . (MCP's tool names)`);
+    if (!tool.description.trim())
+        problems.push(`${at}: the description is empty; hosts show it to their model`);
+    const chatOnly = CHAT_ONLY.exec(tool.description);
+    if (chatOnly)
+        problems.push(`${at}: the description names ${chatOnly[1]}, a tool only chats have`);
+    if (!(tool.input instanceof z.ZodObject))
+        problems.push(`${at}: input must be a z.object (MCP needs an object at the root)`);
+    else {
+        try {
+            jsonSchema(tool.input);
+        }
+        catch (error) {
+            problems.push(`${at}: input has no exact JSON Schema (${error.message})`);
+        }
+    }
+    if (tool.output) {
+        try {
+            jsonSchema(tool.output);
+        }
+        catch (error) {
+            problems.push(`${at}: output has no exact JSON Schema (${error.message})`);
+        }
+    }
+    if (tool.hints?.readOnly && tool.hints.destructive)
+        problems.push(`${at}: hints say readOnly and destructive; a tool that changes nothing destroys nothing`);
+    for (const key of ["running", "done"]) {
+        const line = tool.status?.[key];
+        if (line !== undefined && (line.length === 0 || line.length > STATUS_MAX))
+            problems.push(`${at}: status.${key} must be 1 to ${STATUS_MAX} characters`);
+    }
+    return problems;
+}
+/** Problems across a server's tools: each tool's, and names used twice. */
+export function toolsProblems(tools) {
+    const problems = tools.flatMap(toolProblems);
+    const seen = new Set();
+    for (const t of tools) {
+        if (seen.has(t.name))
+            problems.push(`tool ${t.name}: two tools have this name`);
+        seen.add(t.name);
+    }
+    return problems;
+}

package/dist/mcp/src/index.d.ts

@@ -0,0 +1,4 @@
+export { mcpServer, type McpAuth, type McpIdentity, type McpServerHandle, type McpServerOptions } from "./server.ts";
+export { mcpTools, fingerprint, type McpDescriptor, type McpLock, type McpToolsOptions } from "./client.ts";
+export { describe, titleOf, toolProblems, toolsProblems, type McpToolDescriptor, type Scopes } from "./describe.ts";
+export { terminalServer, type TerminalServerOptions } from "./terminal.ts";

package/dist/mcp/src/index.js

@@ -0,0 +1,7 @@
+// @flow-engineer/flow/mcp: an agent's tools and skills as an MCP server, and other MCP servers' tools as an
+// agent's. Needs @modelcontextprotocol/server (serving) or @modelcontextprotocol/client (using),
+// optional peers of Flow Framework installed only by agents that turn MCP on.
+export { mcpServer } from "./server.js";
+export { mcpTools, fingerprint } from "./client.js";
+export { describe, titleOf, toolProblems, toolsProblems } from "./describe.js";
+export { terminalServer } from "./terminal.js";

package/dist/mcp/src/server.d.ts

@@ -0,0 +1,70 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { Server } from "@modelcontextprotocol/server";
+import { type EventSink } from "../../src/events.ts";
+import { type AgentFiles } from "../../src/skills.ts";
+import { type TracesOptions } from "../../src/traces.ts";
+import { type CredentialProvider, type Tool } from "../../src/tools.ts";
+import { type McpToolDescriptor, type Scopes } from "./describe.ts";
+export interface McpAuth {
+    /** The authorization server(s) that issue tokens for this server, as hosts discover them. */
+    issuer: string | string[];
+    /** This server's public URL as hosts reach it, the resource tokens are for. Default: the request's own. */
+    resource?: string;
+    /** Scope names: reads need `read`, writes `write`. Without them, being signed in is enough. */
+    scopes?: Scopes;
+    /**
+     * Check a bearer token, on every request. Return who it is for (`key`: the business's own id for
+     * the person, as ToolContext.key) and the scopes it grants, or null when it is not valid.
+     */
+    verify(token: string, request: Request): Promise<McpIdentity | null> | McpIdentity | null;
+}
+export interface McpIdentity {
+    key: string;
+    scopes?: string[];
+    /** Request-bound backend access, such as a brand token exchange. Never exposed to the model. */
+    credentials?: CredentialProvider;
+}
+export interface McpServerOptions {
+    name: string;
+    version: string;
+    tools: Tool[];
+    /** The agent's folder, for its skills (AGENTS.md is the chat agent's and is not sent). Or `files`. */
+    dir?: string;
+    files?: AgentFiles;
+    /** Replaces the instructions a host gets on connecting (default: the skills and how to read them). */
+    instructions?: string;
+    auth?: McpAuth;
+    /** Backend access by verified account, separate from the bearer token issued for this MCP resource. */
+    credentials?: CredentialProvider;
+    /** Where the endpoint is mounted (default "/mcp"). */
+    path?: string;
+    /** Native plugins deliver skills themselves. Default: tools only at `${path}/plugin`. */
+    plugin?: {
+        path?: string;
+    } | false;
+    /** Host names allowed in the Host header. Default: checked only for localhost, against DNS rebinding. */
+    allowedHosts?: string[];
+    /** Change the descriptor of any tool (default: exactly what `describe` makes). */
+    descriptor?: (tool: Tool, generated: McpToolDescriptor) => McpToolDescriptor;
+    /** Add your own handlers (resources, prompts, ...) to each server the SDK makes; one level down. */
+    extend?: (server: Server) => void;
+    events?: EventSink[];
+    /** Traces from FLOW_FRAMEWORK_TRACES_* (or legacy CHINWAG_TRACES_*) by default; false disables them. */
+    traces?: TracesOptions | false;
+}
+export interface McpServerHandle {
+    /** Serve one web-standard request. */
+    fetch(request: Request): Promise<Response>;
+    /** Serve one node:http request. */
+    node(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /** The descriptors `tools/list` sends. */
+    descriptors: McpToolDescriptor[];
+    /** The tools-only plugin endpoint, unless disabled. */
+    plugin?: {
+        path: string;
+        descriptors: McpToolDescriptor[];
+    };
+    /** Wait for calls queued for tracing, for shutdown or short-lived servers. */
+    flushTraces(): Promise<void>;
+}
+export declare function mcpServer(options: McpServerOptions): McpServerHandle;