holon-sh 0.0.1-dev.16 → 0.0.1-dev.17

package/src/ext/files.client.ts

@@ -6,7 +6,7 @@ import { EXTENSION, type Download } from "./files.js";
 
 type Json = Record<string, unknown>;
 
-export interface FileConnection {
+interface FileConnection {
   client: Pick<Client, "getServerCapabilities">;
   resolved: { endpoint: URL | string; fileOrigins?: string[]; installationUID?: string };
   authorization?: string;
@@ -14,7 +14,7 @@ export interface FileConnection {
 
 interface FileInput { id: string; name?: string; mimeType: string; size: number; digest?: { algorithm: "sha-256"; value: string }; data?: string }
 interface Attachment { blob: Blob; input: FileInput }
-export type Files = Map<string, Attachment>;
+type Files = Map<string, Attachment>;
 
 const list = (value: unknown): unknown[] => Array.isArray(value) ? value : [];
 const isObject = (value: unknown): value is Json => typeof value === "object" && value !== null && !Array.isArray(value);
@@ -26,7 +26,7 @@ function refuse(reason: string): never {
   throw new Error(reason);
 }
 
-export function settings({ client }: FileConnection): Json | undefined {
+function settings({ client }: FileConnection): Json | undefined {
   const advertised = client.getServerCapabilities()?.extensions?.[EXTENSION];
   return isObject(advertised) && advertised.revision == null ? advertised : undefined;
 }
@@ -143,6 +143,7 @@ const PATH = /^(?:\/(?!\.\.?(?:\/|$))[A-Za-z0-9\-_~.]+)+$/;
 const TIMESTAMP = /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:[Zz]|[+-]\d{2}:\d{2})$/;
 const loopback = (host: string) => host === "localhost" || host.endsWith(".localhost") || /^127\.\d+\.\d+\.\d+$/.test(host) || host === "[::1]";
 const expired = (target: { expiresAt?: string }) => target.expiresAt !== undefined && Date.parse(target.expiresAt) <= Date.now();
+const timestamp = (value: unknown): value is string | undefined => value === undefined || typeof value === "string" && TIMESTAMP.test(value) && !Number.isNaN(Date.parse(value));
 
 function parse(url: string): URL | undefined {
   try { return new URL(url); } catch { return undefined; }
@@ -156,7 +157,7 @@ function check(raw: unknown, kind: "upload" | "download", { resolved }: FileConn
   if (typeof target.url === "string" === (typeof target.path === "string") || [target.url, target.path].some(value => value !== undefined && typeof value !== "string")) refuse("needs exactly one of url and path");
   if (target.credentials !== "omit" && target.credentials !== "include") refuse("credentials must be omit or include");
   const { expiresAt } = target;
-  if (expiresAt !== undefined && !(typeof expiresAt === "string" && TIMESTAMP.test(expiresAt) && !Number.isNaN(Date.parse(expiresAt)))) refuse("expiresAt is not an RFC 3339 timestamp");
+  if (!timestamp(expiresAt)) refuse("expiresAt is not an RFC 3339 timestamp");
   if (target.headers !== undefined && !(isObject(target.headers) && Object.values(target.headers).every(value => typeof value === "string"))) refuse("headers must map names to strings");
   const headers = (target.headers ?? {}) as Record<string, string>;
   let form: Form | undefined;
@@ -175,12 +176,6 @@ function check(raw: unknown, kind: "upload" | "download", { resolved }: FileConn
       }
       form = { fileField: raw.fileField, fields: fields as Form["fields"] };
     }
-  } else {
-    if (target.name !== undefined && typeof target.name !== "string") refuse("name is not a string");
-    if (typeof target.mimeType !== "string") refuse("mimeType is not a string");
-    if (!Number.isSafeInteger(target.size) || (target.size as number) < 0) refuse("size is not a non-negative integer");
-    const digest = target.digest === undefined ? undefined : present(target.digest);
-    if (target.digest !== undefined && (!digest || Object.keys(digest).some(key => key !== "algorithm" && key !== "value") || digest.algorithm !== "sha-256" || typeof digest.value !== "string")) refuse("digest is malformed");
   }
   const include = target.credentials === "include";
   for (const [name, value] of Object.entries(headers)) {
@@ -283,14 +278,20 @@ export async function upload(request: Json, files: Files, connection: FileConnec
   return requestState;
 }
 
-function download(raw: unknown, connection: FileConnection): Download {
+function download(raw: unknown, connection: FileConnection): Download | undefined {
   const { name, mimeType, size, digest, expiresAt }: Json = present(raw) ?? {};
-  const label = `Downloading ${quoted(typeof name === "string" ? name : undefined)}`;
+  if (name !== undefined && typeof name !== "string" || typeof mimeType !== "string" || typeof size !== "number" || !Number.isSafeInteger(size) || size < 0 || !timestamp(expiresAt)) return undefined;
+  let value: string | undefined;
+  if (digest !== undefined) {
+    const given = present(digest);
+    if (!given || Object.keys(given).some(key => key !== "algorithm" && key !== "value") || given.algorithm !== "sha-256" || typeof given.value !== "string") return undefined;
+    value = given.value;
+  }
+  const label = `Downloading ${quoted(name)}`;
   const blob = async ({ signal }: { signal?: AbortSignal } = {}) => {
     let target: Target;
     try { target = check(raw, "download", connection); } catch (error) { throw new Error(`${label} was refused: its target was rejected (${(error as Error).message}).`); }
     if (expired(target)) throw new Error(`${label} was refused: its target expired.`);
-    const declared = size as number;
     const chunks: Uint8Array[] = [];
     let received = 0;
     try {
@@ -304,26 +305,26 @@ function download(raw: unknown, connection: FileConnection): Download {
         const chunk = await reader.read();
         if (chunk.done) break;
         received += chunk.value.byteLength;
-        if (received > declared) {
+        if (received > size) {
           await reader.cancel();
-          throw new Error(`more than the declared ${declared} bytes; discarded`);
+          throw new Error(`more than the declared ${size} bytes; discarded`);
         }
         chunks.push(chunk.value);
       }
     } catch (error) {
       throw new Error(`${label} failed (${reason(error)}).`);
     }
-    if (received !== declared) throw new Error(`${label} failed (${received} bytes, not the declared ${declared}; discarded).`);
-    const file = new Blob(chunks, { type: mimeType as string });
-    if (digest && await sha256(file) !== (digest as { value: string }).value) throw new Error(`${label} failed (the bytes do not match the digest; discarded).`);
+    if (received !== size) throw new Error(`${label} failed (${received} bytes, not the declared ${size}; discarded).`);
+    const file = new Blob(chunks, { type: mimeType });
+    if (value !== undefined && await sha256(file) !== value) throw new Error(`${label} failed (the bytes do not match the digest; discarded).`);
     return file;
   };
-  return Object.freeze({ ...Object.fromEntries(Object.entries({ name, mimeType, size, digest, expiresAt }).filter(([, value]) => value !== undefined)), blob }) as Download;
+  return Object.freeze({ ...(name !== undefined && { name }), mimeType, size, ...(value !== undefined && { digest: { algorithm: "sha-256" as const, value } }), ...(expiresAt !== undefined && { expiresAt }), blob });
 }
 
 export function downloads<R extends { resultType?: string; _meta?: object }>(result: R, connection: FileConnection): R & { downloads?: Download[] } {
   if (result.resultType === "input_required" || !isObject(result._meta) || !(EXTENSION in result._meta)) return result;
   const { [EXTENSION]: meta, ...rest } = result._meta;
-  const handles = settings(connection) ? list((meta as { downloads?: unknown } | null | undefined)?.downloads).map(target => download(target, connection)) : [];
+  const handles = settings(connection) ? list((meta as { downloads?: unknown } | null | undefined)?.downloads).flatMap(target => download(target, connection) ?? []) : [];
   return { ...result, _meta: rest, ...(handles.length > 0 && { downloads: handles }) };
 }

package/src/ext/files.ts

@@ -1,7 +1,7 @@
 /** Identifier of the MCP files extension (draft), the key under which a client and a server declare it in their capabilities. */
 export const EXTENSION = "io.modelcontextprotocol/files";
 
-/** A file a tool returned for the caller to fetch. Its fields come from the server and are untrusted. */
+/** A file a tool returned for the caller to fetch. Its fields come from the server: they have the types below, but their values are untrusted. */
 export interface Download {
   readonly name?: string;
   readonly mimeType: string;

package/src/link.ts

@@ -0,0 +1,136 @@
+import { Client, SdkHttpError, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import type { CacheableRequestOptions, PriorDiscovery, StandardSchemaV1 } from "@modelcontextprotocol/client";
+import { EXTENSION } from "./ext/files.js";
+import { acceptUploadRequests } from "./ext/files.client.js";
+import type { CallOptions } from "./protocol.js";
+import type { Binding, Identity, ToolSession } from "./runtime.js";
+
+interface Connection {
+  client: Client;
+  resolved: Binding;
+  authorization?: string;
+  ready: Promise<void>;
+  answered: boolean;
+  close(): Promise<void>;
+}
+
+export interface Link {
+  readonly name: string;
+  session<T>(options: CallOptions | undefined, run: (client: ToolSession, connection?: Connection) => Promise<T>): Promise<T>;
+  endpoint(what: string): Binding;
+  connect(binding: Binding): Connection;
+  close(): Promise<void>;
+}
+
+// Environment-bound calls reuse the last server/discover result for the same endpoint and token instead of discovering
+// the server on every call. A dependency keeps only its latest result, so a changed endpoint or token replaces it.
+const DISCOVERY: unique symbol = Symbol("discovery");
+const discovered = new Map<string, { key: string; prior: PriorDiscovery; expires: number }>();
+const LEGACY_VERDICT_MS = 10 * 60 * 1000;
+
+type Endpoint = Binding & { [DISCOVERY]?: string };
+/** Without an endpoint, a binding is served by the session hook or not at all. */
+type Resolved = Endpoint | { endpoint?: undefined };
+
+export function environment(name: string): Endpoint {
+  const prefix = `${name.toUpperCase().replaceAll("-", "_")}_MCP_`;
+  const endpoint = process.env[`${prefix}URL`];
+  const token = process.env[`${prefix}TOKEN`];
+  if (endpoint) return { endpoint, scoped: true, [DISCOVERY]: `${endpoint} ${token ?? ""}`, ...(token && { authProvider: { token: async () => token } }) };
+  throw new Error(`Dependency ${name} is unavailable (${prefix}URL). Provide a binding or set the environment variable.`);
+}
+
+function connect(identity: Identity, resolved: Binding, prior?: PriorDiscovery, onclose?: (connection: Connection) => void): Connection {
+  // Every client can be asked: a call answers with elicit, or the question reaches its caller. Servers must not assume a client answers: https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr#server-requirements-basic-workflow
+  // On 2026-07-28 the client sends these capabilities in every request's _meta: https://github.com/modelcontextprotocol/typescript-sdk/blob/fcef852f6cdafea07f36cf6fae69b37c8adf85be/packages/client/src/client/client.ts#L700-L711
+  const client = new Client({ name: identity.name, version: identity.version }, { capabilities: { elicitation: { form: {}, url: {} }, extensions: { [EXTENSION]: { upload: {}, download: {} } } }, versionNegotiation: { mode: "auto" } });
+  const endpoint = new URL(resolved.endpoint);
+  const transport = acceptUploadRequests(new StreamableHTTPClientTransport(endpoint, { authProvider: resolved.authProvider, fetch: async (input, init) => {
+    if (String(input) === endpoint.href) connection.authorization = new Headers(init?.headers).get("authorization") ?? undefined;
+    const response = await (resolved.fetch ?? fetch)(input, init);
+    connection.answered ||= response.ok;
+    return response;
+  }, requestInit: { credentials: "include", redirect: "error", headers: resolved.installationUID ? { "X-Holon-Installation-UID": resolved.installationUID } : {} } }));
+  transport.onclose = () => onclose?.(connection);
+  const ready = client.connect(transport, { prior }).catch(async (error: unknown) => {
+    await transport.close();
+    throw error;
+  });
+  const connection: Connection = { client, resolved, ready, answered: false, close: async () => {
+    await transport.terminateSession().catch(() => {});
+    await transport.close();
+    await ready.catch(() => {});
+  } };
+  return connection;
+}
+
+export function createLink(identity: Identity, name: string, { binding, resolve, host }: { binding: unknown; resolve?: (app: string) => Binding | undefined; host?: ToolSession | undefined }): Link {
+  const current = (): Resolved | undefined => (binding as Resolved | undefined) ?? resolve?.(name);
+  let kept: Connection | undefined;
+  const session = async <T>(options: CallOptions | undefined, run: (client: ToolSession, connection?: Connection) => Promise<T>): Promise<T> => {
+    options?.signal?.throwIfAborted();
+    if (host) return run(host);
+    const resolved = current();
+    if (!resolved?.endpoint) throw new Error(`Dependency ${name} is unavailable. Provide a binding.`);
+    const scoped = resolved.scoped === true;
+    const key = resolved[DISCOVERY];
+    const cached = discovered.get(name);
+    const prior = key !== undefined && cached?.key === key && Date.now() < cached.expires ? cached.prior : undefined;
+    const active = scoped ? connect(identity, resolved, prior) : (kept ??= connect(identity, resolved, undefined, closed => { if (kept === closed) kept = undefined; }));
+    try {
+      await untilAborted(active.ready, options?.signal);
+      if (key !== undefined && !prior) {
+        const discover = active.client.getDiscoverResult();
+        discovered.set(name, { key, prior: discover ? { kind: "modern", discover } : { kind: "legacy" }, expires: discover ? Infinity : Date.now() + LEGACY_VERDICT_MS });
+      }
+      return await run(active.client, active);
+    } catch (error) {
+      // A server that no longer speaks the discovered protocol rejects the first request without running it.
+      if (!prior || active.answered || !(SdkHttpError.isInstance(error) && error.status === 400)) throw error;
+      discovered.delete(name);
+      return session(options, run);
+    } finally { if (scoped) await active.close(); }
+  };
+  return {
+    name,
+    session,
+    endpoint(what) {
+      const resolved = current();
+      if (!resolved?.endpoint) throw new Error(`${what} requires an endpoint binding.`);
+      return resolved;
+    },
+    connect: resolved => connect(identity, resolved),
+    close: async () => { await kept?.close(); },
+  };
+}
+
+export function sleep(milliseconds: number, signal?: AbortSignal): Promise<void> {
+  return new Promise(resolve => {
+    const done = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, milliseconds);
+    signal?.addEventListener("abort", done, { once: true });
+  });
+}
+
+export function untilAborted<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (!signal) return promise;
+  return new Promise((resolve, reject) => {
+    const aborted = () => reject(signal.reason);
+    signal.addEventListener("abort", aborted, { once: true });
+    promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", aborted));
+  });
+}
+
+// The MCP client ends a request after 60 s unless given a timeout. A request without one waits as long as a timer can
+// (2^31 - 1 ms, about 24.8 days). A request with one asks for progress, and progress restarts its timeout.
+export function patient(options?: CacheableRequestOptions): CacheableRequestOptions {
+  return options?.timeout === undefined
+    ? { ...options, timeout: 2 ** 31 - 1 }
+    : { onprogress: () => {}, resetTimeoutOnProgress: true, ...options };
+}
+
+export const unchecked = <T>(): StandardSchemaV1<unknown, T> => ({ "~standard": { version: 1, vendor: "holon-sh", validate: value => ({ value: (value ?? {}) as T }) } });

package/src/protocol.ts

@@ -13,17 +13,15 @@ export type ToolCallOptions = CallOptions & { elicit?: ElicitHandler };
 /** MCP request metadata and input continuation fields. Pass inputResponses and requestState when continuing an input-required result. */
 export type CallMetadata = Omit<CallToolRequest["params"], "name" | "arguments"> & { inputResponses?: InputResponses; requestState?: string };
 type Fields<T> = { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K] };
-type Files = {
-  /** Files the tool returned, from a server with the files extension. Their targets are removed from _meta. */
+type Completed = Omit<Fields<CallToolResult>, "structuredContent" | "isError"> & {
+  resultType: "complete";
+  /** Files the tool returned, from a server with the files extension. Their targets are removed from _meta, and a file whose fields do not have their types is left out. */
   downloads?: Download[];
 };
 /** Successful tool result with contract-typed structured content. */
-export type CompleteResult<Output> = Omit<Fields<CallToolResult>, "structuredContent" | "isError"> & Files & { resultType: "complete"; isError?: false; structuredContent: Output };
+export type CompleteResult<Output> = Completed & { isError?: false; structuredContent: Output };
 /** Full tool result: successful typed output, an application error, or an input-required continuation. */
-export type ToolResult<Output> =
-  | CompleteResult<Output>
-  | (Omit<Fields<CallToolResult>, "structuredContent" | "isError"> & Files & { resultType: "complete"; isError: true; structuredContent?: unknown })
-  | InputRequiredResult;
+export type ToolResult<Output> = CompleteResult<Output> | (Completed & { isError: true; structuredContent?: unknown }) | InputRequiredResult;
 
 function json(text: string | undefined): unknown {
   try { return text === undefined ? undefined : JSON.parse(text); } catch { return undefined; }
@@ -39,7 +37,6 @@ export class ToolCallError extends Error {
   constructor(app: string, tool: string, result: ToolCallError["result"]) {
     const asking = result.resultType === "input_required";
     const text = (asking ? undefined : result.content.filter(part => part.type === "text").map(part => part.text).join("\n")) || undefined;
-    // A question says what it asks, and a URL question where to answer it.
     const detail = asking
       ? Object.values(result.inputRequests ?? {}).flatMap(question => question.method === "elicitation/create"
         ? [question.params.message, question.params.mode === "url" ? question.params.url : undefined]
@@ -66,7 +63,7 @@ export interface EventType {
   _meta?: Record<string, unknown>;
 }
 /** One occurrence of an event. `eventId` is stable, so an occurrence delivered twice is yielded once. */
-export interface EventOccurrence<Data = unknown> { eventId: string; name: string; timestamp: string; data: Data }
+export interface EventOccurrence<Data = unknown> { eventId: string; name: string; /** When it happened, in ISO 8601. */ timestamp: string; data: Data }
 export interface SubscribeOptions {
   /** Ends the subscription. */
   signal?: AbortSignal;