factoryhub 0.1.0 → 0.1.1

package/packages/engine/src/flow-sources.mjs

@@ -0,0 +1,135 @@
+// Experimental: tool sources a flow declares, in the shape RFC 0017 (a
+// draft) proposes. Read only when a runner opts in to experimental tool
+// sources; the default parser still refuses a flow that requires
+// `tool-sources`, as it refuses any feature it does not know.
+//
+// What this reads: `requires: [tool-sources]` and a top-level `sources` map
+// in flow.yaml, and capability names `<source>/<tool>` in steps' `tools`.
+// What it does not read yet: the fields of other harnesses as references to
+// sources (RFC 0017 section 1.5), and the no-way-out rules beyond the two
+// simplest (section 3.7).
+// SPDX-License-Identifier: Apache-2.0
+import { parseYaml } from './factory-engine.mjs';
+
+export const SOURCES_FEATURE = 'tool-sources';
+export const EFFECT_ORDER = ['read', 'write', 'external', 'irreversible'];
+const SOURCE_KEY = /^[a-z0-9][a-z0-9_-]{0,40}$/;
+const TOOL_NAME = /^[A-Za-z0-9_.-]{1,128}$/;
+const ARGUMENT = /^[A-Za-z_$][A-Za-z0-9_$-]{0,63}$/;
+const REGISTRY = /^[A-Za-z0-9.-]{1,100}\/[A-Za-z0-9._-]{1,100}$/;
+const SOURCE_FIELDS = ['title', 'mcp', 'target', 'tools'];
+const TOOL_FIELDS = ['effect', 'title', 'target', 'idempotency'];
+const MAX_SOURCES = 8;
+const MAX_TOOLS = 24;
+const isMap = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+// Text a person reads at consent: one line, with no control, format or private-use characters.
+const PLAIN_LINE = /^[^\p{Cc}\p{Cf}\p{Co}\p{Cs}\u2028\u2029]*$/u;
+const plainLine = (value) => typeof value === 'string' && PLAIN_LINE.test(value);
+// The factory's own words, when a message repeats them: one line, short, no control characters.
+const quote = (value, limit = 60) => String(value).normalize('NFKC').replace(/[\p{Cc}\p{Cf}\p{Co}\p{Cs}\u2028\u2029]+/gu, ' ').replace(/\s+/g, ' ').trim().slice(0, limit);
+// An own property, also for a name such as __proto__.
+const put = (map, key, value) => Object.defineProperty(map, key, { value, enumerable: true, writable: true, configurable: true });
+const idOf = (text) => String(text || '').toLowerCase().normalize('NFKD').replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '').slice(0, 64);
+
+/** The stronger of two effect classes. */
+export const strongerEffect = (a, b) => (EFFECT_ORDER.indexOf(a) >= EFFECT_ORDER.indexOf(b) ? a : b);
+
+// An https address with a host name, no user name, query or fragment.
+function addressProblem(url) {
+  let parsed;
+  try { parsed = new URL(url); } catch { return true; }
+  const host = parsed.hostname;
+  return parsed.protocol !== 'https:' || parsed.username || parsed.password || parsed.search || parsed.hash || url.includes('#') || url.includes('?')
+    || !host.includes('.') || /^[\d.]+$/.test(host) || host.startsWith('[');
+}
+
+/**
+ * The sources a flow declares. Returns `{ declared: false }` for a flow
+ * that does not require `tool-sources`; otherwise `{ declared: true,
+ * sources, uses, problems }`, where `sources` maps each key to its
+ * declaration, `uses` lists for each capability `<source>/<tool>` the steps
+ * that name it, and `problems` are the errors of RFC 0017 section 1.6 this
+ * runner checks, in its words.
+ */
+export function declaredSources(files) {
+  let flow;
+  try { flow = parseYaml(files?.['flow.yaml'] ?? ''); } catch (error) {
+    // A flow that cannot be read says so, rather than seeming to declare nothing.
+    if (/^requires:.*\btool-sources\b/m.test(String(files?.['flow.yaml'] ?? ''))) return { declared: true, sources: {}, uses: {}, problems: [`flow.yaml: ${quote(error.message, 200)}`] };
+    return { declared: false };
+  }
+  if (!isMap(flow) || !Array.isArray(flow.requires) || !flow.requires.includes(SOURCES_FEATURE)) return { declared: false };
+  const problems = [];
+  const sources = {};
+  const raw = flow.sources;
+  if (raw !== undefined && !isMap(raw)) problems.push('The flow\'s sources must be a map from source name to source.');
+  const entries = isMap(raw) ? Object.entries(raw) : [];
+  if (entries.length > MAX_SOURCES) problems.push(`A flow declares at most ${MAX_SOURCES} sources, and a source at most ${MAX_TOOLS} tools.`);
+  for (const [key, spec] of entries) {
+    if (!SOURCE_KEY.test(key)) { problems.push(`Source "${quote(key)}" needs a name of lowercase letters, digits, _ and -, starting with a letter or digit, at most 41 characters.`); continue; }
+    if (!isMap(spec)) { problems.push(`Source "${key}" needs title, tools and one protocol field.`); continue; }
+    const unknown = Object.keys(spec).filter((field) => !SOURCE_FIELDS.includes(field));
+    if (unknown.length) problems.push(`Source "${key}" has a field the format does not define: ${unknown.map((field) => quote(field, 40)).join(', ')}. A source has title, target, tools and one protocol field.`);
+    if (typeof spec.title !== 'string' || !spec.title.trim() || spec.title.length > 100) problems.push(`Source "${key}" needs a title of 1 to 100 characters.`);
+    else if (!plainLine(spec.title)) problems.push(`Source "${key}" has a title that must be one line of plain text, without line breaks, tabs or control characters.`);
+    const mcp = spec.mcp;
+    if (!isMap(mcp)) problems.push(`Source "${key}" needs exactly one protocol field: mcp.`);
+    else {
+      const extra = Object.keys(mcp).filter((field) => !['url', 'registry'].includes(field));
+      if (extra.length) problems.push(`Source "${key}" has a field the format does not define: mcp.${extra.map((field) => quote(field, 40)).join(', mcp.')}. A source has title, target, tools and one protocol field.`);
+      if (mcp.url === undefined && mcp.registry === undefined) problems.push(`Source "${key}" needs an mcp url or registry name.`);
+      if (mcp.url !== undefined && (typeof mcp.url !== 'string' || addressProblem(mcp.url))) problems.push(`Source "${key}" needs an https address with a host name and no user name, query or fragment.`);
+      if (mcp.registry !== undefined && (typeof mcp.registry !== 'string' || !REGISTRY.test(mcp.registry))) problems.push(`Source "${key}" has a registry name this runner cannot read: use a name such as com.example/tracker.`);
+    }
+    let target = null;
+    if (spec.target !== undefined) {
+      const fieldsOk = isMap(spec.target) && Object.keys(spec.target).every((field) => ['label', 'help'].includes(field));
+      if (!fieldsOk || typeof spec.target.label !== 'string' || !spec.target.label.trim() || spec.target.label.length > 40 || (spec.target.help !== undefined && (typeof spec.target.help !== 'string' || spec.target.help.length > 200))) problems.push(`Source "${key}" has a target that needs a label of 1 to 40 characters and, optionally, help of up to 200.`);
+      else if (!plainLine(spec.target.label) || (spec.target.help !== undefined && !plainLine(spec.target.help))) problems.push(`Source "${key}" has a target label or help that must be one line of plain text, without line breaks, tabs or control characters.`);
+      else target = { label: spec.target.label, help: spec.target.help || '' };
+    }
+    const tools = {};
+    const toolEntries = isMap(spec.tools) ? Object.entries(spec.tools) : [];
+    if (!toolEntries.length || toolEntries.length > MAX_TOOLS) problems.push(`Source "${key}" needs tools: 1 to ${MAX_TOOLS} of them.`);
+    for (const [name, declaration] of toolEntries) {
+      if (!TOOL_NAME.test(name)) { problems.push(`Source "${key}" names a tool "${quote(name)}" that is not a tool name: letters, digits, _, - and ., at most 128.`); continue; }
+      if (!isMap(declaration) || !EFFECT_ORDER.includes(declaration.effect)) { problems.push(`The tool "${name}" of source "${key}" needs an effect: read, write, external or irreversible.`); continue; }
+      const unknownTool = Object.keys(declaration).filter((field) => !TOOL_FIELDS.includes(field));
+      if (unknownTool.length) problems.push(`The tool "${name}" of source "${key}" has a field the format does not define: ${unknownTool.map((field) => quote(field, 40)).join(', ')}.`);
+      if (declaration.title !== undefined && (typeof declaration.title !== 'string' || !declaration.title.trim() || declaration.title.length > 100)) problems.push(`The tool "${name}" of source "${key}" needs a title of 1 to 100 characters.`);
+      else if (declaration.title !== undefined && !plainLine(declaration.title)) problems.push(`The tool "${name}" of source "${key}" has a title that must be one line of plain text, without line breaks, tabs or control characters.`);
+      if (declaration.target !== undefined) {
+        if (!target) problems.push(`The tool "${name}" of source "${key}" names a target argument, but the source declares no target.`);
+        else if (typeof declaration.target !== 'string' || !ARGUMENT.test(declaration.target)) problems.push(`The tool "${name}" of source "${key}" names a target argument this runner cannot use: one argument name of letters, digits, _, $ and -.`);
+      }
+      if (declaration.idempotency !== undefined) {
+        if (declaration.effect === 'read') problems.push(`The tool "${name}" of source "${key}" only reads, so it takes no idempotency key.`);
+        else if (typeof declaration.idempotency !== 'string' || !ARGUMENT.test(declaration.idempotency)) problems.push(`The tool "${name}" of source "${key}" names an idempotency argument this runner cannot use.`);
+      }
+      put(tools, name, { effect: declaration.effect, title: typeof declaration.title === 'string' ? declaration.title : name, target: typeof declaration.target === 'string' ? declaration.target : null, idempotency: typeof declaration.idempotency === 'string' ? declaration.idempotency : null });
+    }
+    put(sources, key, { key, title: typeof spec.title === 'string' ? spec.title : key, url: isMap(mcp) && typeof mcp.url === 'string' ? mcp.url : null, registry: isMap(mcp) && typeof mcp.registry === 'string' ? mcp.registry : null, target, tools });
+  }
+  // Capability names in steps, and the two simplest no-way-out rules.
+  const uses = {};
+  for (const [stepKey, step] of Object.entries(isMap(flow.steps) ? flow.steps : {})) {
+    if (!isMap(step)) continue;
+    const title = quote(String(step.title || stepKey).replace(/_/g, ' '), 100);
+    const kind = String(step.kind || 'work').toLowerCase();
+    const asked = [].concat(step.tools ?? []).map((tool) => String(tool).trim());
+    const capabilities = asked.filter((tool) => tool.includes('/'));
+    if (!capabilities.length) continue;
+    if (!['work', 'deliver'].includes(kind)) { problems.push(`The step "${title}" is a ${quote(kind)} step. Only work and deliver steps use tools from sources.`); continue; }
+    const used = new Set();
+    for (const name of capabilities) {
+      const [source, tool, ...rest] = name.split('/');
+      if (rest.length || !Object.hasOwn(sources, source) || !Object.hasOwn(sources[source].tools, tool)) { problems.push(`The step "${title}" names ${quote(name, 120)}, which no source declares.`); continue; }
+      used.add(source);
+      if (!Object.hasOwn(uses, name)) put(uses, name, []);
+      uses[name].push(idOf(stepKey));
+    }
+    if (asked.some((tool) => tool === 'web_search' || tool === 'web_fetch')) problems.push(`The step "${title}" can reach the web and also read from source "${quote([...used][0] || capabilities[0].split('/')[0])}". Read in one step and use the web in another.`);
+    if (used.size > 1) problems.push(`The step "${title}" can read from source "${[...used][0]}" and source "${[...used][1]}". Give each source its own step.`);
+  }
+  return { declared: true, sources, uses, problems };
+}

package/packages/engine/src/mcp-client.mjs

@@ -0,0 +1,429 @@
+// Experimental: a client for remote MCP servers over Streamable HTTP.
+// Only runs that opt in to experimental tool sources use it (see
+// tool-sources.mjs); a default run never reaches this code. It will change
+// with the RFC on tool sources.
+//
+// No dependencies and no Node.js-only APIs: fetch, TextDecoder and
+// AbortSignal work in Node.js, browsers and workers alike.
+// SPDX-License-Identifier: Apache-2.0
+
+/** The protocol revision this client asks for. It accepts the one the server answers with. */
+export const MCP_PROTOCOL_VERSION = '2025-06-18';
+/** How long one request may take. Remote tools often call other services. */
+export const MCP_TIMEOUT_MS = 90000;
+const MAX_PAGES = 20;
+const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+const MAX_ERROR_BYTES = 64 * 1024;
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]']);
+/** A shorter token could not be found again reliably in what a server sends back. */
+export const MIN_TOKEN_LENGTH = 16;
+const PROTOCOL_VERSION = /^\d{4}-\d{2}-\d{2}$/;
+const SERVER_NAME = /^[A-Za-z0-9][A-Za-z0-9 ._@/+-]{0,99}$/;
+const SERVER_VERSION = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,39}$/;
+const DELETE_TIMEOUT_MS = 3000;
+
+/**
+ * A failed request. `retryable` says whether trying again later may work;
+ * `kind` names the class of failure: timeout, network, auth, http, rpc,
+ * redirect, too_large, input_required, closed or protocol. A message is
+ * always this client's own sentence: no text a server sent is in it.
+ */
+export class McpError extends Error {
+  constructor(message, { retryable = false, status, rpcCode, kind = 'protocol' } = {}) {
+    super(message);
+    this.name = 'McpError';
+    this.kind = kind;
+    this.retryable = retryable;
+    if (status) this.status = status;
+    if (rpcCode !== undefined) this.rpcCode = rpcCode;
+    if (kind === 'input_required') this.inputRequired = true;
+  }
+}
+
+const tooLarge = () => new McpError('The server sent more than 8 MB for one request.', { kind: 'too_large' });
+const isTimeout = (error) => error?.name === 'TimeoutError' || error?.name === 'AbortError';
+
+// The body, chunk by chunk, so nothing has to be read whole.
+async function* chunks(response) {
+  const reader = response.body?.getReader?.();
+  if (!reader) {
+    const text = await response.text();
+    if (text) yield new TextEncoder().encode(text);
+    return;
+  }
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) return;
+      if (value?.byteLength) yield value;
+    }
+  } finally {
+    reader.cancel().catch(() => {});
+  }
+}
+
+// At most `limit` bytes of text: past it, an error, or with `cut` the text so far.
+async function readText(response, limit, { cut = false } = {}) {
+  const decoder = new TextDecoder();
+  let text = '';
+  let total = 0;
+  for await (const chunk of chunks(response)) {
+    total += chunk.byteLength;
+    if (total > limit) {
+      if (cut) return text;
+      throw tooLarge();
+    }
+    text += decoder.decode(chunk, { stream: true });
+  }
+  return text + decoder.decode();
+}
+
+// Server-sent events, one `data` payload at a time, read as they arrive, so
+// a server that keeps its stream open after answering is fine.
+async function* sseData(response) {
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let data = [];
+  let total = 0;
+  const lines = function* (final) {
+    for (;;) {
+      const at = buffer.search(/\r|\n/);
+      if (at < 0 || (buffer[at] === '\r' && at === buffer.length - 1 && !final)) return;
+      const line = buffer.slice(0, at);
+      buffer = buffer.slice(at + (buffer[at] === '\r' && buffer[at + 1] === '\n' ? 2 : 1));
+      yield line;
+    }
+  };
+  const event = function* (line) {
+    if (line === '') { if (data.length) yield data.join('\n'); data = []; return; }
+    if (line.startsWith(':')) return;
+    const colon = line.indexOf(':');
+    const field = colon < 0 ? line : line.slice(0, colon);
+    const value = colon < 0 ? '' : line.slice(colon + 1).replace(/^ /, '');
+    if (field === 'data') data.push(value);
+  };
+  for await (const chunk of chunks(response)) {
+    total += chunk.byteLength;
+    if (total > MAX_RESPONSE_BYTES) throw tooLarge();
+    buffer += decoder.decode(chunk, { stream: true });
+    for (const line of lines(false)) yield* event(line);
+  }
+  buffer += decoder.decode();
+  for (const line of lines(true)) yield* event(line);
+  if (buffer) yield* event(buffer);
+  if (data.length) yield data.join('\n');
+}
+
+// A value that reads like a credential: long, letters and digits, varied,
+// and not a date. Words, tool names and dates never are.
+function credentialLike(value) {
+  if (value.length < 16 || !/[A-Za-z]/.test(value) || !/\d/.test(value) || /^\d{4}-\d{2}-\d{2}/.test(value)) return false;
+  const counts = new Map();
+  for (const char of value) counts.set(char, (counts.get(char) || 0) + 1);
+  let entropy = 0;
+  for (const count of counts.values()) { const share = count / value.length; entropy -= share * Math.log2(share); }
+  return entropy >= 3;
+}
+const CREDENTIAL_NAME = /key|token|secret|passw|auth|sig|credential|session|code/i;
+
+// The secrets an address carries: query values named like a credential (8
+// characters or more) or reading like one, and path segments reading like one.
+function addressSecrets(endpoint) {
+  const found = [];
+  for (const [name, value] of endpoint.searchParams) if (value.length >= 8 && (CREDENTIAL_NAME.test(name) || credentialLike(value))) found.push(value);
+  for (const segment of endpoint.pathname.split('/')) {
+    let value = segment;
+    try { value = decodeURIComponent(segment); } catch { /* kept as written */ }
+    if (credentialLike(value)) found.push(value);
+  }
+  return found;
+}
+
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+const hexOf = (bytes) => [...bytes].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+
+// The forms of a token this client removes from what a server sends: as
+// written and percent-encoded (any case), hex (any case), and base64 and
+// base64url with or without padding, also where the token starts at any
+// byte offset inside a longer encoded text.
+function secretPatterns(secrets) {
+  const anyCase = new Set();
+  const exact = new Set();
+  for (const token of secrets) addPatterns(token, anyCase, exact);
+  const alternation = (set) => [...set].filter(Boolean).sort((a, b) => b.length - a.length).map(escapeRegExp).join('|');
+  return [new RegExp(alternation(anyCase), 'gi'), new RegExp(alternation(exact), 'g')];
+}
+
+function addPatterns(token, anyCase, exact) {
+  const raw = new TextEncoder().encode(token);
+  for (const form of [token, encodeURIComponent(token), [...raw].map((byte) => `%${byte.toString(16).padStart(2, '0')}`).join(''), hexOf(raw)]) anyCase.add(form);
+  const encode = (bytes) => btoa(String.fromCharCode(...bytes));
+  const url = (text) => text.replace(/\+/g, '-').replace(/\//g, '_');
+  const full = encode(raw);
+  for (const form of [full, full.replace(/=+$/, '')]) { exact.add(form); exact.add(url(form)); }
+  for (let offset = 0; offset < 3; offset += 1) {
+    const shifted = new Uint8Array(offset + raw.length);
+    shifted.set(raw, offset);
+    // The characters that depend on the token's bytes alone.
+    const middle = encode(shifted).slice(Math.ceil((8 * offset) / 6), Math.floor((8 * (offset + raw.length)) / 6));
+    exact.add(middle);
+    exact.add(url(middle));
+  }
+}
+
+/**
+ * A client for one remote MCP server over Streamable HTTP.
+ *
+ * - `url`: the server's MCP endpoint: https, or http on this machine only.
+ * - `token`: sent as `Authorization: Bearer <token>` when given, at least
+ *   16 characters. It never appears in an error message. It is removed,
+ *   with the encodings secretPatterns lists, from everything the server
+ *   sends back; `mentionsSecret` finds a piece of it in text. A hostile
+ *   server holding the token can still pass it on by a channel this client
+ *   cannot see.
+ * - `fetchImpl`, `timeoutMs`, `clientInfo`: as named.
+ *
+ * Works with servers that keep a session (`Mcp-Session-Id`) and with
+ * stateless ones that need none. Answers may come as plain JSON or as
+ * server-sent events.
+ */
+export function createMcpClient({ url, token = '', fetchImpl = fetch, timeoutMs = MCP_TIMEOUT_MS, clientInfo = { name: 'factoryhub', version: 'experimental' } }) {
+  let endpoint;
+  try { endpoint = new URL(url); } catch { throw new McpError('The MCP server address is not a valid URL.'); }
+  if (endpoint.protocol !== 'https:' && !(endpoint.protocol === 'http:' && LOOPBACK.has(endpoint.hostname))) throw new McpError('The MCP server address must start with https:// (http:// only for this machine).');
+  if (endpoint.username || endpoint.password) throw new McpError('The MCP server address must not hold credentials: pass a token instead.');
+  if (token && String(token).length < MIN_TOKEN_LENGTH) throw new McpError(`A token must be at least ${MIN_TOKEN_LENGTH} characters long, so it can be found again in what a server sends back.`);
+  // Named in messages without its path or query, which can carry identifiers.
+  const origin = endpoint.origin;
+  // Secrets to remove: the token, and what in the address reads as a
+  // credential (a key put in the query or the path instead of in a token).
+  const secrets = [...new Set([...(token ? [String(token)] : []), ...addressSecrets(endpoint)])];
+  const patterns = secrets.length ? secretPatterns(secrets) : [];
+  const redact = (text) => patterns.reduce((out, pattern) => out.replace(pattern, '[redacted]'), String(text));
+  // Any piece of the token at least half its length, in text with spaces,
+  // invisible and control characters and case taken out, numeric HTML
+  // entities read, forwards or backwards: a split, spaced or reversed echo.
+  const span = Math.max(8, Math.ceil(String(token).length / 2));
+  const pieces = token ? Array.from({ length: String(token).length - span + 1 }, (_, at) => String(token).slice(at, at + span).toLowerCase()) : [];
+  const mentionsSecret = (text) => {
+    if (!pieces.length) return false;
+    const squashed = String(text)
+      .replace(/&#x([0-9a-f]{1,6});/gi, (_, code) => String.fromCodePoint(Math.min(parseInt(code, 16), 0x10ffff)))
+      .replace(/&#(\d{1,7});/g, (_, code) => String.fromCodePoint(Math.min(Number(code), 0x10ffff)))
+      .normalize('NFKC').replace(/[\s\p{Cf}\p{Cc}]/gu, '').toLowerCase();
+    const backwards = [...squashed].reverse().join('');
+    return pieces.some((piece) => squashed.includes(piece) || backwards.includes(piece));
+  };
+  const scrub = (value) => {
+    if (typeof value === 'string') return redact(value);
+    if (Array.isArray(value)) return value.map(scrub);
+    if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, item]) => [redact(key), scrub(item)]));
+    return value;
+  };
+  let nextId = 1;
+  let sessionId = null;
+  let protocolVersion = null;
+  let server = null;
+  let initialized = false;
+  let initializing = null;
+  let closed = false;
+  // Aborts every request in flight when the client is closed.
+  const closing = new AbortController();
+  const signalFor = () => (AbortSignal.any ? AbortSignal.any([AbortSignal.timeout(timeoutMs), closing.signal]) : AbortSignal.timeout(timeoutMs));
+  const closedError = () => new McpError('The connection to the tool source was closed.', { kind: 'closed' });
+
+  const headersFor = (method) => {
+    const headers = { 'content-type': 'application/json', accept: 'application/json, text/event-stream' };
+    if (token) headers.authorization = `Bearer ${token}`;
+    if (protocolVersion && method !== 'initialize') headers['mcp-protocol-version'] = protocolVersion;
+    if (sessionId) headers['mcp-session-id'] = sessionId;
+    return headers;
+  };
+  const timedOut = () => new McpError(`${origin} did not answer within ${Math.round(timeoutMs / 1000)} seconds.`, { retryable: true, kind: 'timeout' });
+
+  async function post(message) {
+    if (closed) throw closedError();
+    let response;
+    try {
+      // Redirects are not followed, so the token only ever goes to this address.
+      response = await fetchImpl(endpoint.href, { method: 'POST', headers: headersFor(message.method), body: JSON.stringify(message), redirect: 'manual', signal: signalFor() });
+    } catch (error) {
+      if (closed) throw closedError();
+      if (isTimeout(error)) throw timedOut();
+      throw new McpError(`The connection to ${origin} failed.`, { retryable: true, kind: 'network' });
+    }
+    if (response.type === 'opaqueredirect' || (response.status >= 300 && response.status < 400)) {
+      await response.body?.cancel?.().catch?.(() => {});
+      throw new McpError(`${origin} answered with a redirect, which this client does not follow. Give the server's final address.`, { kind: 'redirect' });
+    }
+    return response;
+  }
+
+  // The class and status of a failed answer. What the server wrote is read
+  // (at most 64 KB, to free the connection) and never put in the message.
+  async function failureOf(response, method) {
+    try { await readText(response, MAX_ERROR_BYTES, { cut: true }); } catch { /* nothing to keep */ }
+    const status = response.status;
+    if (status === 401 || status === 403) return new McpError(`${origin} refused the credentials for ${method} (HTTP ${status}).`, { status, kind: 'auth' });
+    const retryable = status === 408 || status === 429 || status >= 500;
+    return new McpError(`${origin} answered ${method} with HTTP ${status}.`, { status, retryable, kind: 'http' });
+  }
+
+  // Answers a ping the server sends while it works on a request. Never throws.
+  async function pong(requestId) {
+    try {
+      const response = await post({ jsonrpc: '2.0', id: requestId, result: {} });
+      await response.body?.cancel?.().catch?.(() => {});
+    } catch { /* the server goes on or gives up */ }
+  }
+
+  // Sends one request and returns its result, or throws an McpError.
+  async function request(method, params, retried = false) {
+    const id = nextId;
+    nextId += 1;
+    const used = sessionId;
+    const response = await post({ jsonrpc: '2.0', id, method, ...(params !== undefined ? { params } : {}) });
+    // An expired session: one new session, shared by every request that saw it expire.
+    if (response.status === 404 && used && method !== 'initialize' && !retried) {
+      await response.body?.cancel?.().catch?.(() => {});
+      if (sessionId === used) { sessionId = null; initialized = false; }
+      await ready();
+      return request(method, params, true);
+    }
+    if (!response.ok) throw await failureOf(response, method);
+    if (method === 'initialize') {
+      const given = response.headers.get('mcp-session-id');
+      if (given && /^[\x21-\x7e]{1,512}$/.test(given)) sessionId = given;
+    }
+    const type = (response.headers.get('content-type') || '').toLowerCase();
+    const answer = async (messages) => {
+      for (const raw of [].concat(messages)) {
+        const message = scrub(raw);
+        if (!message || typeof message !== 'object') continue;
+        if (message.id === id && (Object.hasOwn(message, 'result') || Object.hasOwn(message, 'error'))) return { done: true, message };
+        if (typeof message.method === 'string' && message.id !== undefined && message.id !== null) {
+          if (message.method === 'ping') { await pong(message.id); continue; }
+          // The server asks the client something (elicitation, sampling,
+          // roots) before it answers: this client cannot take part yet.
+          return { done: true, asks: message.method };
+        }
+      }
+      return { done: false };
+    };
+    let found = { done: false };
+    try {
+      if (type.includes('text/event-stream')) {
+        for await (const data of sseData(response)) {
+          let parsed;
+          try { parsed = JSON.parse(data); } catch { throw new McpError('The server sent an event that is not JSON.'); }
+          found = await answer(parsed);
+          if (found.done) break;
+        }
+      } else if (type.includes('application/json')) {
+        let parsed;
+        const text = await readText(response, MAX_RESPONSE_BYTES);
+        try { parsed = JSON.parse(text); } catch { throw new McpError('The server answered with invalid JSON.'); }
+        found = await answer(parsed);
+      } else {
+        await response.body?.cancel?.().catch?.(() => {});
+        throw new McpError(`${origin} answered ${method} with an unexpected content type.`);
+      }
+    } catch (error) {
+      if (closed) throw closedError();
+      if (error instanceof McpError) throw error;
+      if (isTimeout(error)) throw timedOut();
+      throw new McpError(`The connection to ${origin} broke while the answer was read.`, { retryable: true, kind: 'network' });
+    }
+    if (found.asks) throw new McpError('The server asked for input before answering, which this experimental mode does not support yet.', { kind: 'input_required' });
+    if (!found.done) throw new McpError(`${origin} closed the answer to ${method} without a result.`, { retryable: true });
+    const { message } = found;
+    if (message.error) {
+      const code = Number.isSafeInteger(message.error.code) ? message.error.code : undefined;
+      throw new McpError(`${origin} answered ${method} with JSON-RPC error ${code ?? 'without a code'}.`, { rpcCode: code, retryable: code === -32603, kind: 'rpc' });
+    }
+    return message.result;
+  }
+
+  async function notify(method, params) {
+    const response = await post({ jsonrpc: '2.0', method, ...(params !== undefined ? { params } : {}) });
+    await response.body?.cancel?.().catch?.(() => {});
+    if (response.status === 401 || response.status === 403) throw new McpError(`${origin} refused the credentials (HTTP ${response.status}).`, { status: response.status, kind: 'auth' });
+  }
+
+  // One handshake at a time: requests that need one while it runs wait for it.
+  function initialize() {
+    initializing ||= (async () => {
+      const result = await request('initialize', { protocolVersion: MCP_PROTOCOL_VERSION, capabilities: {}, clientInfo });
+      // A revision is a date. Anything else is refused: this value goes back
+      // to the server in a header and into every receipt entry.
+      if (!result || typeof result.protocolVersion !== 'string' || !PROTOCOL_VERSION.test(result.protocolVersion)) throw new McpError(`${origin} answered initialize with a protocol version that is not a date.`, { kind: 'protocol' });
+      protocolVersion = result.protocolVersion;
+      // The server's name and version, only when they read as a plain name and version.
+      const plain = (value, pattern) => (typeof value === 'string' && pattern.test(value) && !mentionsSecret(value) ? value : null);
+      server = { name: plain(result.serverInfo?.name, SERVER_NAME), version: plain(result.serverInfo?.version, SERVER_VERSION) };
+      await notify('notifications/initialized');
+      initialized = true;
+      return { protocolVersion, server };
+    })().finally(() => { initializing = null; });
+    return initializing;
+  }
+
+  async function ready() { if (!initialized) await initialize(); }
+
+  return {
+    origin,
+    get protocolVersion() { return protocolVersion; },
+    get server() { return server; },
+    get sessionId() { return sessionId; },
+    /** Removes the token, and the encodings of it this client knows, from text. */
+    redact,
+    /** True when text holds a piece of the token, however spaced, split or cased. */
+    mentionsSecret,
+    initialize,
+    /** Every tool the server lists, following `nextCursor` page by page. */
+    async listTools() {
+      await ready();
+      const tools = [];
+      const seen = new Set();
+      let cursor;
+      for (let page = 0; page < MAX_PAGES; page += 1) {
+        const result = await request('tools/list', cursor === undefined ? {} : { cursor });
+        if (!result || !Array.isArray(result.tools)) throw new McpError('The server answered tools/list without a list of tools.');
+        tools.push(...result.tools);
+        cursor = result.nextCursor;
+        if (cursor === undefined || cursor === null || cursor === '') return tools;
+        if (typeof cursor !== 'string' || seen.has(cursor)) throw new McpError('The server sent a tools/list page cursor that repeats or is not text.');
+        seen.add(cursor);
+      }
+      throw new McpError(`The server listed more than ${MAX_PAGES} pages of tools.`);
+    },
+    /** The raw `tools/call` result. Errors are thrown as McpError. */
+    async callTool(name, args) {
+      await ready();
+      return request('tools/call', { name, arguments: args });
+    },
+    /**
+     * Ends the server's session, when it gave one, and refuses new requests.
+     * During a handshake, the session it opens is ended once it settles;
+     * this waits for that at most a few seconds. Never throws.
+     */
+    async close() {
+      closed = true;
+      closing.abort();
+      const end = async () => {
+        if (!sessionId) return;
+        const ending = sessionId;
+        sessionId = null;
+        try {
+          const headers = { ...headersFor('close'), 'mcp-session-id': ending };
+          const response = await fetchImpl(endpoint.href, { method: 'DELETE', headers, redirect: 'manual', signal: AbortSignal.timeout(DELETE_TIMEOUT_MS) });
+          await response.body?.cancel?.().catch?.(() => {});
+        } catch { /* the session expires on its own */ }
+      };
+      const settled = initializing ? initializing.catch(() => {}).then(end) : end();
+      let timer;
+      await Promise.race([settled, new Promise((resolve) => { timer = setTimeout(resolve, DELETE_TIMEOUT_MS + 1000); })]);
+      clearTimeout(timer);
+    },
+  };
+}