@flow-engineer/flow 0.2.1 → 0.2.3

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();
+    }
+}

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

@@ -0,0 +1,24 @@
+import type { Agent } from "../../src/agent.ts";
+import type { McpAuth } from "./server.ts";
+export interface TerminalServerOptions {
+    /** A getter lets the channel be declared before building the agent that uses it. */
+    agent: () => Agent;
+    auth: Pick<McpAuth, "verify">;
+    path?: string;
+    channel?: string;
+}
+export declare function terminalServer(options: TerminalServerOptions): {
+    path: string;
+    channel: {
+        name: string;
+        kind: import("../../src/channels.ts").ChannelKind;
+        info: import("../../src/types.ts").ChannelInfo;
+        phone?: boolean;
+        params?: Record<string, import("zod").ZodType>;
+        instructions?: string;
+        keywords?: import("../../src/channels.ts").Keywords;
+        send(address: string, outbound: import("../../src/types.ts").Outbound): Promise<void> | void;
+        traceChannel: string;
+    };
+    fetch(request: Request): Promise<Response>;
+};

package/dist/mcp/src/terminal.js

@@ -0,0 +1,54 @@
+// An authenticated terminal channel beside MCP. Mount fetch wherever the agent's HTTP routes live.
+import { customUI } from "../../src/channels.js";
+export function terminalServer(options) {
+    const path = options.path ?? "/agent/terminal";
+    const channel = { ...customUI(options.channel ?? "terminal", { sendMessage: async () => { throw new Error("No terminal request is listening"); } }), traceChannel: "cli" };
+    let inFlight = 0;
+    const pending = new Map();
+    return {
+        path,
+        channel,
+        async fetch(request) {
+            if (new URL(request.url).pathname !== path)
+                return new Response("Not found", { status: 404 });
+            if (request.method !== "POST")
+                return new Response("Method not allowed", { status: 405, headers: { allow: "POST" } });
+            const token = /^Bearer\s+(.+)$/i.exec(request.headers.get("authorization") ?? "")?.[1];
+            let identity;
+            try {
+                identity = token ? await options.auth.verify(token, request) : null;
+            }
+            catch {
+                identity = null;
+            }
+            if (!identity?.key)
+                return Response.json({ error: "sign_in_required" }, { status: 401, headers: { "www-authenticate": "Bearer" } });
+            let input;
+            try {
+                input = await request.json();
+            }
+            catch {
+                return Response.json({ error: "invalid_request" }, { status: 400 });
+            }
+            if (!input || typeof input.text !== "string" || !input.text.trim() || input.text.length > 32_768 || (input.conversationId !== undefined && typeof input.conversationId !== "string"))
+                return Response.json({ error: "invalid_request" }, { status: 400 });
+            if (inFlight >= 128)
+                return Response.json({ error: "busy" }, { status: 429 });
+            inFlight++;
+            const previous = pending.get(identity.key) ?? Promise.resolve();
+            const work = previous.catch(() => undefined).then(() => options.agent().request({ channel: channel.name, key: identity.key, text: input.text, conversationId: input.conversationId, credentials: identity.credentials }));
+            pending.set(identity.key, work);
+            try {
+                return Response.json(await work);
+            }
+            catch {
+                return Response.json({ error: "turn_failed" }, { status: 500 });
+            }
+            finally {
+                inFlight--;
+                if (pending.get(identity.key) === work)
+                    pending.delete(identity.key);
+            }
+        },
+    };
+}

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

@@ -1,2 +1,2 @@
-export { playgroundClock, simulators, type AgentConnection, type PlaygroundClock, type Line, type LinkCard, type Playground, type PlaygroundAgent, type SimulatorsOptions, type TestCloudSimulators } from "./server.ts";
+export { playgroundClock, simulators, type AgentConnection, type PlaygroundClock, type Line, type LinkCard, type LocalCliOptions, type Playground, type PlaygroundAgent, type SimulatorsOptions, type TestCloudSimulators } from "./server.ts";
 export { PLATFORMS, platform, channelOf, smsSegments, type Platform } from "./platforms.ts";