@flow-engineer/flow 0.2.0 → 0.2.2

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;

package/dist/mcp/src/server.js

@@ -0,0 +1,252 @@
+// An agent's tools and skills as an MCP server (Streamable HTTP, spec 2026-07-28 with the 2025
+// fallback), on the official SDK. It needs no model, channels or store: mount `fetch` on any
+// web-standard runtime (Cloudflare Workers, Deno, Bun) or `node` on node:http.
+//
+// Sign-in is the host's OAuth against the business's own authorization server; this server only
+// verifies the token on every request (`auth.verify`) and turns it into the person. A call that
+// needs sign-in and has none is answered HTTP 401 with WWW-Authenticate before the SDK runs: hosts
+// start sign-in only on that, never on a tool result. A token without a needed scope gets 403
+// insufficient_scope. Without `auth`, every tool answers and the person is anonymous.
+import { randomUUID } from "node:crypto";
+import { createMcpHandler, hostHeaderValidationResponse, localhostAllowedHostnames, localhostAllowedOrigins, originValidationResponse, ProtocolError, ProtocolErrorCode, Server, } from "@modelcontextprotocol/server";
+import { emitter } from "../../src/events.js";
+import { loadSkills, mcpInstructions, readAgentFolder, readSkillTool } from "../../src/skills.js";
+import { traces, tracesFromEnv } from "../../src/traces.js";
+import { render, toolContext } from "../../src/tools.js";
+import { describe, scopesFor, signInOf, toolsProblems } from "./describe.js";
+const LOCAL = new Set(localhostAllowedHostnames());
+export function mcpServer(options) {
+    if (options.dir !== undefined && options.files !== undefined)
+        throw new Error("@flow-engineer/flow/mcp: give dir or files, not both");
+    const skills = options.dir !== undefined || options.files !== undefined ? loadSkills(options.files ?? readAgentFolder(options.dir)) : [];
+    const tools = [...options.tools, ...(skills.length ? [readSkillTool(skills)] : [])];
+    const problems = toolsProblems(tools);
+    if (problems.length)
+        throw new Error(`@flow-engineer/flow/mcp: these tools cannot be served as declared:\n- ${problems.join("\n- ")}`);
+    const scopes = options.auth?.scopes;
+    const byName = new Map(tools.map((t) => [t.name, t]));
+    const descriptors = tools.map((t) => (options.descriptor ? options.descriptor(t, describe(t, scopes)) : describe(t, scopes)));
+    const path = options.path ?? "/mcp";
+    const pluginPath = options.plugin === false ? undefined : options.plugin?.path ?? `${path}/plugin`;
+    for (const endpoint of [path, pluginPath].filter((p) => p !== undefined)) {
+        if (!endpoint.startsWith("/") || /[?#]/.test(endpoint))
+            throw new Error("@flow-engineer/flow/mcp: paths must be absolute URL paths");
+    }
+    if (pluginPath === path)
+        throw new Error("@flow-engineer/flow/mcp: plugin and standalone paths must differ");
+    const pluginDescriptors = descriptors.slice(0, options.tools.length);
+    const traceOptions = options.traces === false ? undefined : options.traces ?? tracesFromEnv();
+    const trace = traceOptions ? traces(traceOptions, { service: options.name, kindOf: () => undefined }) : undefined;
+    const emit = emitter([...(options.events ?? []), ...(trace ? [trace.sink] : [])]);
+    // Legacy HTTP carries clientInfo only on initialize. Keep bounded metadata, never auth.
+    const sessions = new Map();
+    const SESSION_TTL = 24 * 60 * 60 * 1000;
+    function endpointHandler(plugin) {
+        const instructions = options.instructions ?? (plugin ? "" : mcpInstructions(skills));
+        const listed = plugin ? pluginDescriptors : descriptors;
+        const available = plugin ? new Map(options.tools.map((t) => [t.name, t])) : byName;
+        return createMcpHandler(({ requestInfo }) => {
+            const server = new Server({ name: options.name, version: options.version }, { capabilities: { tools: {} }, ...(instructions ? { instructions } : {}) });
+            server.setRequestHandler("tools/list", async () => ({ tools: listed }));
+            server.setRequestHandler("tools/call", async (request, ctx) => {
+                const t = available.get(request.params.name);
+                if (!t)
+                    throw new ProtocolError(ProtocolErrorCode.InvalidParams, `No tool named ${request.params.name}.`);
+                const parsed = t.input.safeParse(request.params.arguments ?? {});
+                if (!parsed.success)
+                    throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Invalid arguments for ${t.name}: ${parsed.error.message}`);
+                const identity = identityOf(ctx.http?.authInfo);
+                const person = identity ? `key:${identity.key}` : "mcp:anonymous";
+                const meta = ctx.mcpReq._meta ?? {};
+                const sentKey = meta["chinwag/idempotency-key"];
+                const session = requestInfo?.headers.get("mcp-session-id") ?? undefined;
+                const host = server.getClientVersion() ?? (session ? sessions.get(session)?.client : undefined);
+                const detail = {
+                    surface: meta["chinwag/surface"] === "cli" ? "cli" : plugin ? "mcp-plugin" : "mcp",
+                    client: host?.name,
+                    clientVersion: host?.version,
+                    session: ctx.sessionId ?? session,
+                    person,
+                    command: typeof meta["chinwag/command"] === "string" ? meta["chinwag/command"] : undefined,
+                };
+                const context = toolContext({
+                    conversationId: `mcp:${person}`,
+                    person,
+                    key: identity?.key ?? null,
+                    channel: "mcp",
+                    callId: randomUUID(),
+                    // CLI retries can preserve a call key; other hosts get one per request.
+                    idempotencyKey: typeof sentKey === "string" && sentKey.length > 0 && sentKey.length <= 256 ? sentKey : randomUUID(),
+                    signal: ctx.mcpReq?.signal ?? new AbortController().signal,
+                }, ctx.http?.authInfo?.extra?.credentials ?? options.credentials);
+                const started = Date.now();
+                emit(context.conversationId, "tool.start", { callId: context.callId, tool: t.name, input: parsed.data, ...detail });
+                const result = await callTool(t, parsed.data, context);
+                emit(context.conversationId, "tool.end", { callId: context.callId, tool: t.name, ms: Date.now() - started, ok: !result.isError, output: result.structuredContent ?? result.content, error: result.isError ? result.content.filter(c => c.type === "text").map(c => c.text).join("\n") : undefined, ...detail });
+                return result;
+            });
+            options.extend?.(server);
+            return server;
+        });
+    }
+    const handler = endpointHandler(false);
+    const pluginHandler = pluginPath ? endpointHandler(true) : undefined;
+    async function serve(request) {
+        const url = new URL(request.url);
+        const metadataPrefix = "/.well-known/oauth-protected-resource";
+        const plugin = pluginPath !== undefined && (url.pathname === pluginPath || url.pathname === `${metadataPrefix}${pluginPath}`);
+        const servedPath = plugin ? pluginPath : path;
+        if (request.method === "GET" && (url.pathname === metadataPrefix || url.pathname === `${metadataPrefix}${servedPath}`)) {
+            if (!options.auth)
+                return new Response("Not found", { status: 404 });
+            return Response.json({
+                resource: resourceOf(url, servedPath),
+                authorization_servers: [options.auth.issuer].flat(),
+                bearer_methods_supported: ["header"],
+                ...(scopes && (scopes.read || scopes.write) ? { scopes_supported: [...new Set([scopes.read, scopes.write].filter(Boolean))] } : {}),
+            });
+        }
+        if (url.pathname !== servedPath)
+            return new Response("Not found", { status: 404 });
+        const rejected = options.allowedHosts
+            ? hostHeaderValidationResponse(request, options.allowedHosts)
+            : LOCAL.has(url.hostname)
+                ? (hostHeaderValidationResponse(request, localhostAllowedHostnames()) ?? originValidationResponse(request, localhostAllowedOrigins()))
+                : undefined;
+        if (rejected)
+            return rejected;
+        for (const [id, saved] of sessions)
+            if (Date.now() - saved.at > SESSION_TTL)
+                sessions.delete(id);
+        const session = request.headers.get("mcp-session-id");
+        if (session && sessions.get(session)?.path !== servedPath)
+            return new Response("Session not found", { status: 404 });
+        let authInfo;
+        const bearer = /^Bearer\s+(.+)$/i.exec(request.headers.get("authorization") ?? "")?.[1];
+        if (options.auth && bearer) {
+            const identity = await options.auth.verify(bearer, request);
+            if (!identity)
+                return challenge(url, servedPath, 401, "invalid_token", "The token is not valid.", []);
+            authInfo = { token: bearer, clientId: "", scopes: identity.scopes ?? [], extra: { key: identity.key } };
+            if (identity.credentials)
+                Object.defineProperty(authInfo.extra, "credentials", { value: identity.credentials, enumerable: false });
+        }
+        let parsedBody;
+        if (request.method === "POST") {
+            try {
+                parsedBody = JSON.parse(await request.clone().text());
+            }
+            catch {
+                parsedBody = undefined;
+            }
+            if (options.auth) {
+                for (const message of [parsedBody].flat()) {
+                    const call = message;
+                    if (!call || call.method !== "tools/call" || typeof call.params?.name !== "string")
+                        continue;
+                    const t = plugin && call.params.name === "read_skill" ? undefined : byName.get(call.params.name);
+                    if (!t || signInOf(t) === "none")
+                        continue;
+                    const needed = scopesFor(t, scopes);
+                    if (!authInfo) {
+                        if (signInOf(t) === "required")
+                            return challenge(url, servedPath, 401, "invalid_token", `Sign in to use ${t.name}.`, needed);
+                        continue;
+                    }
+                    const missing = needed.filter((s) => !authInfo.scopes.includes(s));
+                    if (missing.length)
+                        return challenge(url, servedPath, 403, "insufficient_scope", `${t.name} needs ${missing.join(" ")}.`, [...new Set([...authInfo.scopes, ...needed])]);
+                }
+            }
+        }
+        if (request.method === "DELETE" && session) {
+            sessions.delete(session);
+            return new Response(null, { status: 200 });
+        }
+        const response = await (plugin ? pluginHandler : handler).fetch(request, { authInfo, parsedBody });
+        const init = parsedBody;
+        if (response.ok && init?.method === "initialize") {
+            const client = init.params?.clientInfo;
+            if (typeof client?.name === "string" && typeof client.version === "string") {
+                const id = randomUUID();
+                sessions.set(id, { client: { name: client.name.slice(0, 256), version: client.version.slice(0, 256) }, path: servedPath, at: Date.now() });
+                if (sessions.size > 4096)
+                    sessions.delete(sessions.keys().next().value);
+                const headers = new Headers(response.headers);
+                headers.set("mcp-session-id", id);
+                return new Response(response.body, { status: response.status, headers });
+            }
+        }
+        return response;
+    }
+    function resourceOf(url, servedPath) {
+        const resource = options.auth?.resource ?? `${url.origin}${path}`;
+        if (servedPath === path)
+            return resource;
+        const pluginResource = new URL(resource);
+        pluginResource.pathname = servedPath;
+        return pluginResource.href;
+    }
+    function challenge(url, servedPath, status, error, description, scope) {
+        const metadata = `${new URL(resourceOf(url, servedPath)).origin}/.well-known/oauth-protected-resource${servedPath}`;
+        const header = `Bearer error="${error}", error_description="${description}", resource_metadata="${metadata}"${scope.length ? `, scope="${scope.join(" ")}"` : ""}`;
+        return Response.json({ error, error_description: description }, { status, headers: { "WWW-Authenticate": header } });
+    }
+    return {
+        fetch: serve,
+        node: (req, res) => serveNode(serve, req, res),
+        descriptors,
+        flushTraces: () => trace?.flush() ?? Promise.resolve(),
+        ...(pluginPath ? { plugin: { path: pluginPath, descriptors: pluginDescriptors } } : {}),
+    };
+}
+function identityOf(authInfo) {
+    const key = authInfo?.extra?.key;
+    return typeof key === "string" ? { key, scopes: authInfo.scopes } : null;
+}
+async function callTool(t, input, context) {
+    let output;
+    try {
+        output = await t.run(input, context);
+    }
+    catch (error) {
+        return { isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }] };
+    }
+    if (!t.output)
+        return { content: [{ type: "text", text: render(output) }] };
+    const checked = t.output.safeParse(output);
+    if (!checked.success)
+        return { isError: true, content: [{ type: "text", text: `${t.name} returned a result that does not match its output schema.` }] };
+    return { content: [{ type: "text", text: render(checked.data) }], structuredContent: checked.data };
+}
+/** node:http in front of the web-standard handler, streaming the answer (event streams included). */
+async function serveNode(serve, req, res) {
+    const abort = new AbortController();
+    res.on("close", () => abort.abort());
+    const secure = req.socket.encrypted === true;
+    const url = `${secure ? "https" : "http"}://${req.headers.host ?? "localhost"}${req.url ?? "/"}`;
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(req.headers)) {
+        if (value !== undefined)
+            headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+    }
+    let body;
+    if (req.method !== "GET" && req.method !== "HEAD") {
+        const chunks = [];
+        for await (const chunk of req)
+            chunks.push(chunk);
+        const all = Buffer.concat(chunks);
+        body = all.buffer.slice(all.byteOffset, all.byteOffset + all.byteLength);
+    }
+    const response = await serve(new Request(url, { method: req.method, headers, body, signal: abort.signal }));
+    res.writeHead(response.status, Object.fromEntries(response.headers));
+    if (!response.body)
+        return void res.end();
+    try {
+        for await (const chunk of response.body)
+            res.write(chunk);
+    }
+    finally {
+        res.end();
+    }
+}