@adia-ai/agent 0.8.28 → 0.8.30

package/mcp-transport.js

@@ -0,0 +1,361 @@
+/**
+ * MCP streamable-HTTP client transport — the smallest thing that speaks the
+ * protocol.
+ *
+ * Deliberately NOT `@modelcontextprotocol/sdk`. The subset a client needs to
+ * consume a server as a tool/resource source is five methods over one POST
+ * endpoint (initialize · notifications/initialized · tools/list · tools/call ·
+ * resources/list · resources/read); the SDK brings a server framework, stdio
+ * and websocket transports, an auth stack, and zod along with it. This
+ * package's whole posture is zero runtime dependencies beyond `@adia-ai/llm`
+ * and a browser-first build, so the subset is hand-rolled here and the SDK
+ * stays where it belongs — `packages/a2ui/mcp`, which SERVES.
+ *
+ * Wire rules the spec fixes and this module obeys:
+ *  - Every request is a POST carrying one JSON-RPC message, with
+ *    `accept: application/json, text/event-stream` — the server picks.
+ *  - A `mcp-session-id` response header on the initialize response is echoed
+ *    on every subsequent request (and on the DELETE that closes the session).
+ *  - The negotiated `MCP-Protocol-Version` rides every post-initialize
+ *    request.
+ *  - An SSE response body is read until the event whose `data:` payload is
+ *    the JSON-RPC response for THIS request id; server-initiated
+ *    notifications interleaved on that stream are ignored (this client
+ *    subscribes to nothing, so there is nothing it can act on).
+ *  - The protocol headers are the LAST spread in every request, so a caller
+ *    header cannot quietly replace `accept` or the session id and turn a
+ *    working connection into an inexplicable one.
+ *
+ * Nothing here waits forever. Every round trip carries a deadline covering
+ * BOTH the fetch and the wait for the answer to arrive on an SSE body — a
+ * server that accepts a POST and then says nothing is a real failure mode,
+ * and it is indistinguishable from a hang unless someone is holding a clock.
+ * The deadline and the caller's `signal` share one abort path, so a timeout
+ * and a user cancellation both actually cancel the request rather than
+ * abandoning it.
+ *
+ * Everything is `fetch`-only, so it runs unchanged in a browser — with the
+ * CORS caveat the README records. `fetchImpl` exists so a test can hand the
+ * transport an in-process server instead of a network.
+ */
+const CLIENT_PROTOCOL_VERSION = '2025-06-18';
+/** Versions this client can talk. A server answering initialize with
+ *  anything else is a hard stop: guessing at an unknown dialect is how you
+ *  get a half-working tool list. A version NEWER than the one requested is
+ *  refused too — the server would be answering a question we did not ask,
+ *  and the dialect it picked is by definition one this client was not
+ *  written against. */
+const SUPPORTED_PROTOCOL_VERSIONS = new Set([
+    '2025-06-18', '2025-03-26', '2024-11-05',
+]);
+/**
+ * Default per-request deadline: 60 seconds.
+ *
+ * It has to clear the slowest legitimate answer, and for MCP that is a tool
+ * that thinks — the in-repo a2ui server's `generate_ui` runs an LLM inside
+ * `tools/call`. A handshake-sized number (5–10s) would make MCP-client mode
+ * useless for exactly the servers this repo has. One knob rather than
+ * separate connect/call budgets: two numbers to tune is worse than one
+ * generous one, and `timeoutMs` is per-request, so a caller with a slower
+ * tool raises it in the one place that matters.
+ */
+export const DEFAULT_MCP_TIMEOUT_MS = 60_000;
+/** Every MCP failure this package raises carries this name, so a consumer
+ *  can tell an MCP fault from a tool's own bad day without string-matching. */
+export class McpError extends Error {
+    name = 'McpError';
+    /** The server the fault belongs to. Empty for a fault raised while
+     *  assembling several sources, where no single server owns it. */
+    url;
+    constructor(message, url = '', options) {
+        super(url ? `${message} [${url}]` : message, options);
+        this.url = url;
+    }
+}
+/** Connect-time faults: unreachable server, non-2xx, protocol mismatch, a
+ *  timeout, a JSON-RPC error on initialize/list, or a listed tool this
+ *  harness cannot register. Thrown, never swallowed — an agent that
+ *  silently ran with an empty tool list would look like a model that forgot
+ *  how to use its tools. */
+export class McpConnectionError extends McpError {
+    name = 'McpConnectionError';
+}
+/** A `tools/call` or `resources/read` that failed after the connection was
+ *  established. Thrown inside a ToolDef's `execute`, which `executeTool`
+ *  turns into an `isError` tool_result — the model sees it and can react. */
+export class McpCallError extends McpError {
+    name = 'McpCallError';
+}
+function isResponseFor(message, id) {
+    return !!message && typeof message === 'object' && message.id === id;
+}
+/** One abort path for the deadline and every caller signal. Returns the
+ *  controller (so the caller can abort the underlying request on timeout)
+ *  plus a `settle` to release the timer and the listeners — a per-request
+ *  listener left on a long-lived connection signal IS a leak. */
+function abortPath(signals, timeoutMs) {
+    const controller = new AbortController();
+    let expired = false;
+    const live = signals.filter((s) => !!s);
+    const onAbort = () => controller.abort();
+    for (const signal of live) {
+        if (signal.aborted)
+            controller.abort();
+        else
+            signal.addEventListener('abort', onAbort, { once: true });
+    }
+    const timer = timeoutMs > 0
+        ? setTimeout(() => { expired = true; controller.abort(); }, timeoutMs)
+        : null;
+    return {
+        signal: controller.signal,
+        timedOut: () => expired,
+        settle: () => {
+            if (timer)
+                clearTimeout(timer);
+            for (const signal of live)
+                signal.removeEventListener('abort', onAbort);
+        },
+    };
+}
+/** Reject as soon as the shared abort path fires, whatever `promise` is
+ *  doing. `fetch` honors the signal; an in-memory Response's reader does
+ *  not, and a hung server is exactly the case where nobody else is holding
+ *  a clock — so the race is explicit rather than delegated. */
+function untilAborted(promise, path) {
+    if (path.signal.aborted)
+        return Promise.reject(abortReason(path));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(abortReason(path));
+        path.signal.addEventListener('abort', onAbort, { once: true });
+        promise.then(resolve, reject).finally(() => {
+            path.signal.removeEventListener('abort', onAbort);
+        });
+    });
+}
+function abortReason(path) {
+    return path.timedOut()
+        ? new Error('__mcp_timeout__')
+        : new Error('__mcp_aborted__');
+}
+/** Turn the internal marker (or a fetch's own AbortError) into the right
+ *  named MCP error, so a caller reads "timed out" / "aborted" instead of
+ *  the DOM's vocabulary. */
+function describeFailure(err, timeoutMs) {
+    const message = err?.message ?? String(err);
+    if (message === '__mcp_timeout__')
+        return `timed out after ${timeoutMs}ms`;
+    if (message === '__mcp_aborted__')
+        return 'aborted by caller';
+    if (err?.name === 'AbortError')
+        return 'aborted';
+    return message;
+}
+/** Pull the JSON-RPC response for `id` out of an SSE body.
+ *
+ *  Event-block granularity, per the SSE spec rather than per line: an event
+ *  ends at a blank line and its `data:` lines are joined with newlines, so a
+ *  server that pretty-prints its JSON across several `data:` lines is read
+ *  correctly instead of silently discarded as unparseable. */
+async function readSseResponse(res, id, url, path, ErrorClass) {
+    const body = res.body;
+    if (!body)
+        throw new ErrorClass('server sent an SSE response with no body', url);
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let data = [];
+    const flush = () => {
+        if (!data.length)
+            return null;
+        const payload = data.join('\n');
+        data = [];
+        let message;
+        try {
+            message = JSON.parse(payload);
+        }
+        catch {
+            return null; // A malformed event is not this request's answer.
+        }
+        return isResponseFor(message, id) ? message : null;
+    };
+    try {
+        for (;;) {
+            const { done, value } = await untilAborted(reader.read(), path);
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            let cut;
+            while ((cut = buffer.indexOf('\n')) !== -1) {
+                const line = buffer.slice(0, cut).replace(/\r$/, '');
+                buffer = buffer.slice(cut + 1);
+                if (!line) {
+                    const message = flush();
+                    if (message)
+                        return message;
+                    continue;
+                }
+                if (line.startsWith('data:')) {
+                    // One optional space after the colon is part of the framing.
+                    data.push(line.slice(5).replace(/^ /, ''));
+                }
+            }
+        }
+        const trailing = flush();
+        if (trailing)
+            return trailing;
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    throw new ErrorClass(`SSE stream ended before a response to request ${id} arrived`, url);
+}
+/** `connectOptions.signal` covers the HANDSHAKE only. It is deliberately not
+ *  `options.signal`: that one is connection-level and would keep aborting
+ *  every later call, so a turn that cancelled the connect would poison every
+ *  turn after it. */
+export async function connectStreamableHttp(options, connectOptions = {}) {
+    const { url } = options;
+    const doFetch = options.fetchImpl ?? globalThis.fetch;
+    if (typeof doFetch !== 'function') {
+        throw new McpConnectionError('no global fetch available — pass fetchImpl', url);
+    }
+    const clientInfo = options.clientInfo ?? { name: '@adia-ai/agent', version: '1' };
+    const defaultTimeout = options.timeoutMs ?? DEFAULT_MCP_TIMEOUT_MS;
+    let sessionId;
+    let negotiated = CLIENT_PROTOCOL_VERSION;
+    let nextId = 1;
+    /** Caller headers first: the protocol's own headers are not negotiable,
+     *  and a caller who sets `accept` or `mcp-session-id` by accident should
+     *  not be able to break the transport from the outside. */
+    function headers(extra) {
+        return {
+            ...options.headers,
+            'content-type': 'application/json',
+            accept: 'application/json, text/event-stream',
+            ...(sessionId ? { 'mcp-session-id': sessionId } : {}),
+            ...extra,
+        };
+    }
+    async function post(body, ErrorClass, path, timeoutMs, extraHeaders) {
+        let res;
+        try {
+            res = await untilAborted(doFetch(url, {
+                method: 'POST',
+                headers: headers(extraHeaders),
+                body: JSON.stringify(body),
+                signal: path.signal,
+            }), path);
+        }
+        catch (err) {
+            throw new ErrorClass(`cannot reach MCP server: ${describeFailure(err, timeoutMs)}`, url, { cause: err });
+        }
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new ErrorClass(`MCP server returned ${res.status}${text ? `: ${text.slice(0, 300)}` : ''}`, url);
+        }
+        return res;
+    }
+    async function rpc(method, params, ErrorClass, requestOptions) {
+        const id = nextId++;
+        const timeoutMs = requestOptions?.timeoutMs ?? defaultTimeout;
+        const path = abortPath([options.signal, requestOptions?.signal], timeoutMs);
+        try {
+            const res = await post({ jsonrpc: '2.0', id, method, ...(params ? { params } : {}) }, ErrorClass, path, timeoutMs, method === 'initialize' ? {} : { 'mcp-protocol-version': negotiated });
+            if (method === 'initialize') {
+                const assigned = res.headers.get('mcp-session-id');
+                if (assigned)
+                    sessionId = assigned;
+            }
+            const contentType = res.headers.get('content-type') ?? '';
+            let message;
+            if (contentType.includes('text/event-stream')) {
+                try {
+                    message = await readSseResponse(res, id, url, path, ErrorClass);
+                }
+                catch (err) {
+                    if (err instanceof McpError)
+                        throw err;
+                    throw new ErrorClass(`${method} failed: ${describeFailure(err, timeoutMs)}`, url, { cause: err });
+                }
+            }
+            else {
+                const text = await untilAborted(res.text(), path).catch((err) => {
+                    throw new ErrorClass(`${method} failed: ${describeFailure(err, timeoutMs)}`, url, { cause: err });
+                });
+                try {
+                    message = JSON.parse(text);
+                }
+                catch {
+                    throw new ErrorClass(`MCP server sent a non-JSON response to ${method}: ${text.slice(0, 200)}`, url);
+                }
+            }
+            if (message.error) {
+                throw new ErrorClass(`${method} failed (${message.error.code}): ${message.error.message}`, url);
+            }
+            return message.result;
+        }
+        finally {
+            path.settle();
+        }
+    }
+    const initResult = await rpc('initialize', {
+        protocolVersion: CLIENT_PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo,
+    }, McpConnectionError, connectOptions.signal ? { signal: connectOptions.signal } : undefined);
+    const serverVersion = initResult?.protocolVersion ?? CLIENT_PROTOCOL_VERSION;
+    // Dates sort lexicographically, so "newer than we asked for" is a string
+    // comparison — and it is refused as firmly as an unknown one.
+    if (!SUPPORTED_PROTOCOL_VERSIONS.has(serverVersion) || serverVersion > CLIENT_PROTOCOL_VERSION) {
+        throw new McpConnectionError(`server speaks MCP protocol "${serverVersion}", this client asked for ` +
+            `${CLIENT_PROTOCOL_VERSION} and accepts ${[...SUPPORTED_PROTOCOL_VERSIONS].join(', ')}`, url);
+    }
+    negotiated = serverVersion;
+    // The spec's post-initialize notification. It carries no id and gets no
+    // response body worth reading — but a server that rejects it has told us
+    // the handshake did not take, so the failure is fatal like any other
+    // connect-time fault.
+    {
+        const path = abortPath([options.signal, connectOptions.signal], defaultTimeout);
+        try {
+            const res = await post({ jsonrpc: '2.0', method: 'notifications/initialized' }, McpConnectionError, path, defaultTimeout, { 'mcp-protocol-version': negotiated });
+            await res.body?.cancel().catch(() => { });
+        }
+        finally {
+            path.settle();
+        }
+    }
+    return {
+        url,
+        serverInfo: {
+            name: initResult?.serverInfo?.name ?? 'unknown',
+            version: initResult?.serverInfo?.version ?? '0',
+        },
+        protocolVersion: negotiated,
+        capabilities: initResult?.capabilities ?? {},
+        request(method, params, requestOptions) {
+            return rpc(method, params, McpCallError, requestOptions);
+        },
+        async close() {
+            if (!sessionId)
+                return;
+            const path = abortPath([], defaultTimeout);
+            try {
+                await untilAborted(doFetch(url, {
+                    method: 'DELETE',
+                    headers: headers({ 'mcp-protocol-version': negotiated }),
+                    signal: path.signal,
+                }), path);
+            }
+            catch {
+                // A session the server will time out on its own is not worth a throw.
+            }
+            finally {
+                path.settle();
+            }
+            sessionId = undefined;
+        },
+    };
+}
+//# sourceMappingURL=mcp-transport.js.map

package/mcp-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-transport.js","sourceRoot":"","sources":["src/mcp-transport.ts"],"names":[],"mappings":"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"}

package/mcp.d.ts

@@ -0,0 +1,120 @@
+/**
+ * MCP-client mode — a server becomes a tool/resource source.
+ *
+ * `mcpServer({ url })` declares a source; the agent connects it and every
+ * tool the server lists arrives as a normal `ToolDef` in the loop. Nothing
+ * downstream knows the difference: guardrails see the calls, the tracer
+ * records the executions, `checkInput` runs at the boundary, a failure comes
+ * back as an `isError` tool_result. That sameness is the point — MCP is a
+ * SOURCE of tools, not a second kind of tool.
+ *
+ * How it composes with the tier-2 registry (integrations.ts):
+ *  - `register` — used, and it is the fail-fast the lead cares about: two
+ *    servers exposing `search`, or a server tool colliding with a declared
+ *    one, throws at connect instead of silently shadowing.
+ *  - `buildToolDispatch` — used: the ONE place a manifest becomes a ToolDef
+ *    (law 8's shared executor seam) stays the only place.
+ *  - `resolveIntegrations` — deliberately NOT used. Its two jobs are
+ *    persona-enablement intersection and dropping manifests whose env key is
+ *    unprovisioned; an MCP server has neither a persona list nor an env key,
+ *    and its `MAX_INTEGRATIONS` cap SILENTLY drops the overflow. A server
+ *    exposing more tools than the cap is a real thing (the in-repo a2ui
+ *    server has ~20), and quietly serving two thirds of them is the failure
+ *    mode this whole feature is supposed to prevent. So the cap here is
+ *    explicit and LOUD: `maxTools` (default `MAX_INTEGRATIONS`) throws when
+ *    exceeded, and `tools` narrows the list on purpose.
+ *
+ * Schemas arrive as JSON Schema and are passed to the model VERBATIM. They
+ * are not trimmed to `checkInput`'s allowlist: the MCP server is the
+ * authoritative validator (its rejection comes back as an error result the
+ * model can read), so a faithful copy of a contract someone else owns beats
+ * a locally-enforceable subset that describes the tool less accurately. The
+ * manifest says so with `validation: 'remote'` rather than leaving it
+ * implied.
+ *
+ * RESOURCES map onto the two existing modes and no new one. `tool` is the
+ * default — the harness cannot know which of a remote server's resources an
+ * app wants in every prompt, and attaching all of them would grow the system
+ * prompt without bound — and `attach: [name|uri]` promotes the ones the APP
+ * decides belong there every turn. That is the whole application-controlled
+ * vs. model-controlled distinction MCP itself draws, expressed with the
+ * modes the harness already has. gh#671's third mode is NOT needed here; see
+ * the README's ruling.
+ *
+ * Everything a server returns — tool descriptions, resource text, error
+ * strings — is DATA. A description that reads like an instruction is still a
+ * description; it lands inside the tool spec or a `<resource>` envelope and
+ * decides nothing about what the harness does.
+ */
+import { type ResourceDef } from './resource.js';
+import type { ToolDef } from './tools.js';
+import { type McpConnection, type McpTransportOptions } from './mcp-transport.js';
+export interface McpServerOptions extends McpTransportOptions {
+    /** Prefix for every tool name this server contributes — the way to run
+     *  two servers that both expose `search`. Applied before the
+     *  `[a-zA-Z0-9_-]` sanitize, so `weather_` + `get-forecast` is
+     *  `weather_get-forecast`. */
+    prefix?: string;
+    /** Allowlist of server-side tool names to register. Absent = all of them
+     *  (subject to `maxTools`). */
+    tools?: string[];
+    /** Loud cap: more listed tools than this throws at connect rather than
+     *  registering a silent subset. Default `MAX_INTEGRATIONS`. */
+    maxTools?: number;
+    /** `false` skips `resources/list` entirely — a server whose resources are
+     *  irrelevant to this agent shouldn't pay for the round trip. */
+    resources?: boolean;
+    /** Resource names or URIs to expose as `attach` mode (fetched every turn
+     *  and inlined in the system prompt). Everything else is `tool` mode. */
+    attach?: string[];
+}
+/** What `createAgent({ integrations })` accepts. One arm today; the union
+ *  is the extension point a future source (an OpenAPI spec, a worker) adds
+ *  an arm to without changing the config surface. */
+export interface McpSource {
+    kind: 'mcp';
+    url: string;
+    options: McpServerOptions;
+}
+export interface McpServerReport {
+    url: string;
+    serverInfo: {
+        name: string;
+        version: string;
+    };
+    protocolVersion: string;
+    tools: string[];
+    resources: Array<{
+        name: string;
+        uri: string;
+        mode: 'attach' | 'tool';
+    }>;
+}
+export interface ConnectedMcpServer extends McpServerReport {
+    connection: McpConnection;
+    toolDefs: ToolDef[];
+    resourceDefs: ResourceDef[];
+}
+/** Declare an MCP server as a source. Pure — no connection happens here, so
+ *  this is safe to call at module scope; the agent connects on first use (or
+ *  eagerly via `agent.connect()`). */
+export declare function mcpServer(options: McpServerOptions): McpSource;
+/** Connect one declared source: handshake, list, register, build. Any
+ *  failure along the way throws `McpConnectionError` — including a failure
+ *  the REGISTRY raises, which is a plain Error about a manifest and would
+ *  otherwise escape as a different error class than the one the failure
+ *  table promises. The caller never receives a half-built source or an empty
+ *  tool list that looks like a server with nothing to offer.
+ *
+ *  `signal` cancels the connect in flight (the turn that triggered it was
+ *  aborted); it does NOT stay attached to the resulting connection, whose
+ *  later calls carry their own turn's signal. */
+export declare function connectMcpSource(source: McpSource, opts?: {
+    signal?: AbortSignal;
+}): Promise<ConnectedMcpServer>;
+/** The whole assembled tool set must have unique names — the loop dispatches
+ *  by name, so a duplicate is a tool that silently never runs. Per-server
+ *  registration cannot see across sources or into the declared tools, so the
+ *  check lands here, once, over everything. */
+export declare function assertUniqueToolNames(tools: ToolDef[]): void;
+//# sourceMappingURL=mcp.d.ts.map

package/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["src/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAMH,OAAO,EAAkB,KAAK,WAAW,EAAwB,MAAM,eAAe,CAAC;AACvF,OAAO,KAAK,EAAe,OAAO,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,EAEL,KAAK,aAAa,EAAE,KAAK,mBAAmB,EAC7C,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,gBAAiB,SAAQ,mBAAmB;IAC3D;;;kCAG8B;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;mCAC+B;IAC/B,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;mEAC+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;qEACiE;IACjE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;6EACyE;IACzE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;qDAEqD;AACrD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAA;KAAE,CAAC,CAAC;CAC1E;AAED,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACzD,UAAU,EAAE,aAAa,CAAC;IAC1B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,YAAY,EAAE,WAAW,EAAE,CAAC;CAC7B;AAyBD;;sCAEsC;AACtC,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAG9D;AA2GD;;;;;;;;;iDASiD;AACjD,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,SAAS,EACjB,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GAClC,OAAO,CAAC,kBAAkB,CAAC,CAa7B;AA+GD;;;+CAG+C;AAC/C,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAW5D"}