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

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;

package/src/runtime.ts

@@ -1,10 +1,11 @@
-import { Client, isInputRequiredResult, SdkHttpError, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
-import type { CacheableRequestOptions, CallToolRequest, CallToolRequestOptions, CallToolResult, InputRequiredResult, InputResponses, ListToolsRequest, ListToolsResult, PriorDiscovery, ReadResourceRequest, ReadResourceResult, Tool } from "@modelcontextprotocol/client";
+import { isInputRequiredResult } from "@modelcontextprotocol/client";
+import type { CacheableRequestOptions, CallToolRequest, CallToolRequestOptions, CallToolResult, InputRequiredResult, InputResponses, ListToolsRequest, ListToolsResult, ReadResourceRequest, ReadResourceResult, Tool } from "@modelcontextprotocol/client";
 import { AjvJsonSchemaValidator } from "@modelcontextprotocol/client/validators/ajv";
-import { EXTENSION } from "./ext/files.js";
-import { acceptUploadRequests, downloads, isUploadRequest, prepare, upload } from "./ext/files.client.js";
+import { events } from "./ext/events.client.js";
+import { downloads, isUploadRequest, prepare, upload } from "./ext/files.client.js";
+import { createLink, environment, patient, sleep, untilAborted, type Link } from "./link.js";
 import { ToolCallError } from "./protocol.js";
-import type { AuthProvider, CallMetadata, CallOptions, EventOccurrence, EventType, SubscribeOptions, Subscription, ToolCallOptions, ToolClient, ToolResult } from "./protocol.js";
+import type { AuthProvider, CallMetadata, CallOptions, ToolCallOptions, ToolClient, ToolResult } from "./protocol.js";
 
 export { ToolCallError } from "./protocol.js";
 export type { AuthProvider, CallOptions, CallMetadata, ElicitHandler, EventOccurrence, EventType, SubscribeOptions, Subscription, ToolCallOptions, ToolResult, ToolClient } from "./protocol.js";
@@ -24,7 +25,6 @@ export interface Binding {
   /** Origins the server may name as file upload or download targets, e.g. "https://storage.example.com". Unset, any https origin on a globally reachable address is allowed; set, only these, which may also be http on loopback or have a non-global address. */
   fileOrigins?: string[];
 }
-/** Alias for an endpoint binding. */
 export type EndpointBinding = Binding;
 /** Calling application identity and its declared dependencies. */
 export interface Identity { name: string; version: string; requires?: Record<string, { name?: string; version?: string }> }
@@ -52,21 +52,9 @@ export interface CreateOptions<B = Binding> {
   session?: (app: string, binding: B) => ToolSession | undefined;
 }
 
-// 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 = Symbol("discovery");
-const discovered = new Map<string, { key: string; prior: PriorDiscovery; expires: number }>();
-const LEGACY_VERDICT_MS = 10 * 60 * 1000;
-
-/** A binding the runtime connects to itself. */
-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 };
-/** Checks a value against one JSON Schema; errors describes the last failure. */
 type Check = ReturnType<NonNullable<CreateOptions["validator"]>>;
+type Expect = (schema: object, label: string) => (value: unknown) => void;
 
-// Object methods JavaScript calls implicitly; tools with these names stay reachable through callTool.
-const reserved = new Set(["then", "toJSON", "toString", "valueOf", "toLocaleString"]);
 // The MCP client's own Ajv, one engine per schema so contracts that reuse an $id stay apart. Contracts are module
 // constants, so each schema compiles once however often createApps runs.
 const checks = new WeakMap<object, Check>();
@@ -84,72 +72,6 @@ function defaultValidator(schema: object): Check {
   return check;
 }
 
-interface Connection {
-  client: Client;
-  resolved: Endpoint;
-  authorization?: string;
-  ready: Promise<void>;
-  /** Whether the server answered any request on this connection. */
-  answered: boolean;
-  close(): Promise<void>;
-}
-
-function environment(name: string): Endpoint {
-  const prefix = `${name.toUpperCase().replaceAll("-", "_")}_MCP_`;
-  const endpoint = process.env[`${prefix}URL`];
-  // Environment-bound dependencies connect for one call at a time, sending <NAME>_MCP_TOKEN as the bearer token when it is set.
-  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 validate(check: Check, value: unknown, label: string): void {
-  if (!check(value)) throw new Error(`Invalid ${label}: ${JSON.stringify(check.errors)}`);
-}
-
-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 });
-  });
-}
-
-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.
-function patient(options?: CacheableRequestOptions): CacheableRequestOptions {
-  return options?.timeout === undefined
-    ? { ...options, timeout: 2 ** 31 - 1 }
-    : { onprogress: () => {}, resetTimeoutOnProgress: true, ...options };
-}
-
-// Requests outside the core protocol are checked by their callers.
-const anything = { "~standard": { version: 1 as const, vendor: "holon-sh", validate: (value: unknown) => ({ value: (value ?? {}) as any }) } };
-// A stream that has said nothing for twice the longest heartbeat interval is dead: https://github.com/modelcontextprotocol/experimental-ext-triggers-events/blob/main/docs/design-sketch-proposal.md#lifecycle
-const QUIET = 60_000;
-/** An occurrence as the server sends it, at the cursor after it. */
-type Sent = EventOccurrence & { cursor?: string | null; _meta?: unknown };
-/** One page of events/list. */
-type Listed = { events?: EventType[]; nextCursor?: string };
-/** What an events/poll answers. */
-type Polled = { events?: Sent[]; cursor?: string | null; truncated?: boolean; hasMore?: boolean; nextPollMs?: number };
-// A server's refusal ends a subscription: a client error, or an answer that the event type is gone, that access was
-// lost, or that the request is no longer valid. Anything else is tried again from the cursor.
-const refused = (error: any): boolean => error?.status >= 400 && error.status < 500 || error?.data?.status >= 400 && error.data.status < 500 || [-32602, -32023, -32024, -32026].includes(error?.code);
-
 /** Construct only the explicitly bound dependencies. Unknown names throw; an empty binding map selects none. Used by generated createApps factories. */
 export function bindApps<B = Binding>(identity: Identity, contracts: Record<string, Contract | null>, bindings: Record<string, B>, options?: CreateOptions<B>): Readonly<Record<string, RuntimeClient>> {
   const selected = Object.fromEntries(Object.keys(bindings).map((name): [string, Contract | null] => {
@@ -162,312 +84,131 @@ export function bindApps<B = Binding>(identity: Identity, contracts: Record<stri
 /** Construct runtime clients from identity and contracts. Connections open lazily. Explicit and resolved endpoint bindings reuse one session unless scoped is true; <NAME>_MCP_URL bindings use one session per call. Close persistent clients on shutdown. Most callers use the generated clients. */
 export function createApps<B = Binding>(identity: Identity, contracts: Record<string, Contract | null>, bindings?: Record<string, B>, options?: CreateOptions<B>): Readonly<Record<string, RuntimeClient>> {
   const { validator = defaultValidator, resolve = environment, session: hosted } = options ?? {};
+  const expect: Expect = (schema, label) => {
+    let check: Check | undefined;
+    return value => {
+      check ??= validator(schema);
+      if (!check(value)) throw new Error(`Invalid ${label}: ${JSON.stringify(check.errors)}`);
+    };
+  };
   const apps: Record<string, RuntimeClient> = Object.create(null);
   // Without explicit bindings, every declared dependency gets a client; those without a contract are untyped.
   const members: Record<string, Contract | null> = { ...(bindings ? {} : Object.fromEntries(Object.keys(identity.requires ?? {}).map(name => [name, null]))), ...contracts };
   for (const [name, contract] of Object.entries(members)) {
     const binding = bindings?.[name];
-    // Without explicit bindings, the resolve hook supplies the binding on every call.
-    const current = (): Resolved | undefined => (binding as Resolved | undefined) ?? (bindings ? undefined : resolve(name));
-    let connection: Connection | undefined;
-    const connect = (resolved: Endpoint, prior?: PriorDiscovery): 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) current.authorization = new Headers(init?.headers).get("authorization") ?? undefined;
-        const response = await (resolved.fetch ?? fetch)(input, init);
-        current.answered ||= response.ok;
-        return response;
-      }, requestInit: { credentials: "include", redirect: "error", headers: resolved.installationUID ? { "X-Holon-Installation-UID": resolved.installationUID } : {} } }));
-      transport.onclose = () => { if (connection === current) connection = undefined; };
-      const ready = client.connect(transport, { prior }).catch(async (error: unknown) => {
-        await transport.close();
-        throw error;
+    const link = createLink(identity, name, { binding, resolve: bindings ? undefined : resolve, host: binding ? hosted?.(name, binding) : undefined });
+    apps[name] = Object.freeze({ ...tools(link, contract, expect), resources: resources(link, contract, expect), ext: Object.freeze({ events: events(link, contract, expect) }), close: link.close });
+  }
+  return Object.freeze(apps);
+}
+
+// Object methods JavaScript calls implicitly; tools with these names stay reachable through callTool.
+const reserved = new Set(["then", "toJSON", "toString", "valueOf", "toLocaleString"]);
+
+function tools(link: Link, contract: Contract | null, expect: Expect): Pick<RuntimeClient, "callTool" | "listTools" | "tools"> {
+  const { name } = link;
+  const definitions = new Map((contract?.tools ?? []).map(definition => [definition.name, { definition, output: definition.outputSchema && expect(definition.outputSchema, `structured output from ${name}.${definition.name}`) }]));
+  const callTool = async (request: CallMetadata & { name: string; arguments?: Record<string, unknown> }, { elicit, ...options }: ToolCallOptions = {}): Promise<ToolResult<unknown>> => {
+    const tool = definitions.get(request.name);
+    if (!tool && contract) throw new Error(`Unknown tool ${name}.${request.name}.`);
+    // A contract's tool is the tool as its server listed it.
+    const sent = { ...patient(options), allowInputRequired: true, ...(tool && { toolDefinition: { ...tool.definition, outputSchema: undefined } as Tool }) };
+    const label = `${name}.${request.name}`;
+    const result = await link.session(options, async (client, connection) => {
+      const { arguments: args, files } = await prepare(request.arguments, {
+        label, connection,
+        schema: async () => tool?.definition.inputSchema ?? (await client.listTools(undefined, patient(options))).tools.find(({ name }) => name === request.name)?.inputSchema,
       });
-      const current: Connection = { client, resolved, ready, answered: false, close: async () => {
-        await transport.terminateSession().catch(() => {});
-        await transport.close();
-        await ready.catch(() => {});
-      } };
-      return current;
-    };
-    // The session hook serves bindings the runtime does not connect to itself.
-    const host = binding ? hosted?.(name, binding) : 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.`);
-      // Bindings marked scoped connect for one call at a time.
-      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(resolved, prior) : (connection ??= connect(resolved));
-      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(); }
-    };
-    const tools: Record<string, RuntimeClient["tools"][string]> = Object.create(null);
-    const definitions = new Map<string, { definition: Contract["tools"][number]; output?: Check }>((contract?.tools ?? []).map(definition => [definition.name, { definition }]));
-    const callTool = async (request: CallMetadata & { name: string; arguments?: Record<string, unknown> }, { elicit, ...options }: ToolCallOptions = {}): Promise<ToolResult<unknown>> => {
-      const tool = definitions.get(request.name);
-      if (!tool && contract) throw new Error(`Unknown tool ${name}.${request.name}.`);
-      // A contract's tool is the tool as its server listed it.
-      const sent = { ...patient(options), allowInputRequired: true, ...(tool && { toolDefinition: { ...tool.definition, outputSchema: undefined } as Tool }) };
-      const label = `${name}.${request.name}`;
-      const result = await session(options, async (client, connection) => {
-        const { arguments: args, files } = await prepare(request.arguments, {
-          label, connection,
-          schema: async () => tool?.definition.inputSchema ?? (await client.listTools(undefined, patient(options))).tools.find(({ name }) => name === request.name)?.inputSchema,
-        });
-        // The SDK's request type leaves out the continuation fields the protocol carries.
-        let next: typeof request = files.size ? { ...request, arguments: args } : request;
-        let uploaded = false;
-        for (let round = 0; ;) {
-          let result: CallToolResult | InputRequiredResult;
-          try {
-            result = await client.callTool(next, sent);
-          } catch (error) {
-            if (connection && isUploadRequest(error)) {
-              if (uploaded) throw new Error(`${label}: the server asked for a second upload; the tool did not run.`);
-              const requestState = await upload(error.data, files, connection, options.signal, label);
-              uploaded = true;
-              const { inputResponses, ...retry } = next;
-              next = { ...retry, requestState };
-              continue;
-            }
-            if (uploaded) throw new Error(`${label}: the outcome is unknown; the tool may have run (${(error as { message?: unknown } | null | undefined)?.message ?? error}).`, { cause: error });
-            throw error;
+      // The SDK's request type leaves out the continuation fields the protocol carries.
+      let next: typeof request = files.size ? { ...request, arguments: args } : request;
+      let uploaded = false;
+      for (let round = 0; ;) {
+        let result: CallToolResult | InputRequiredResult;
+        try {
+          result = await client.callTool(next, sent);
+        } catch (error) {
+          if (connection && isUploadRequest(error)) {
+            if (uploaded) throw new Error(`${label}: the server asked for a second upload; the tool did not run.`);
+            const requestState = await upload(error.data, files, connection, options.signal, label);
+            uploaded = true;
+            const { inputResponses, ...retry } = next;
+            next = { ...retry, requestState };
+            continue;
           }
-          // A server may keep asking, so answering stops after ten rounds, the MCP clients' own limit, and the last question reaches the caller.
-          if (!elicit || !isInputRequiredResult(result) || round++ === 10) return connection ? downloads(result, connection) : result;
-          const inputResponses: InputResponses = {};
-          for (const [key, question] of Object.entries(result.inputRequests ?? {})) {
-            // Every client declares elicitation alone, so it answers nothing else and such a question reaches the caller.
-            if (question.method !== "elicitation/create") return result;
-            inputResponses[key] = await elicit(question.params);
-          }
-          next = { ...next, inputResponses, requestState: result.requestState };
+          if (uploaded) throw new Error(`${label}: the outcome is unknown; the tool may have run (${(error as { message?: unknown } | null | undefined)?.message ?? error}).`, { cause: error });
+          throw error;
         }
-      });
-      if (isInputRequiredResult(result)) return result;
-      // The server validates arguments; the client checks the output against the contract it was compiled against.
-      if (!result.isError && tool?.definition.outputSchema) {
-        validate(tool.output ??= validator(tool.definition.outputSchema), result.structuredContent, `structured output from ${name}.${request.name}`);
-      }
-      // isError tells ToolResult's success variant from its error variant.
-      return { ...result, resultType: "complete" } as ToolResult<unknown>;
-    };
-    const listTools = (options?: CallOptions) => session(options, client => client.listTools(undefined, patient(options)));
-    for (const tool of contract?.tools ?? []) if (!reserved.has(tool.name)) {
-      tools[tool.name] = async (input, options) => {
-        const result = await callTool({ name: tool.name, arguments: input }, options);
-        if (result.resultType === "input_required" || result.isError) throw new ToolCallError(name, tool.name, result);
-        return tool.outputSchema ? result.structuredContent : result;
-      };
-    }
-    const resources: Record<string, RuntimeClient["resources"][string]> = Object.create(null);
-    for (const resource of contract?.resources ?? []) {
-      let valid: Check | undefined;
-      const parse = (result: ReadResourceResult): unknown => {
-        // Contracted resources are JSON in their first text content.
-        const [content] = result.contents;
-        if (!content || !("text" in content)) throw new Error(`Invalid contents from ${name} ${resource.uri}: no text content`);
-        const value = JSON.parse(content.text);
-        valid ??= validator(resource.outputSchema);
-        validate(valid, value, `contents from ${name} ${resource.uri}`);
-        return value;
-      };
-      const read = async (options?: CallOptions) => parse(await session(options, client => client.readResource({ uri: resource.uri }, patient(options))));
-      const watch = async (onChange: (value: unknown) => void | Promise<void>, { signal }: { signal?: AbortSignal } = {}) => {
-        const resolved = current();
-        if (!resolved?.endpoint) throw new Error(`Watching ${name} ${resource.uri} requires an endpoint binding.`);
-        // An abort ends the wait between attempts early instead of failing it.
-        for (let established = false; !signal?.aborted; await sleep(1000, signal)) {
-          const current = connect(resolved);
-          let failure: unknown;
-          try {
-            await untilAborted(current.ready, signal);
-            const { client } = current;
-            if (!client.getServerCapabilities()?.resources?.subscribe) throw new Error(`${name} does not advertise resource subscriptions.`);
-            let reads = Promise.resolve();
-            const refresh = () => (reads = reads.then(async () => onChange(parse(await client.readResource({ uri: resource.uri }, patient({ signal, cacheMode: "bypass" })))))
-              .catch(error => { failure ??= error; return current.close(); }));
-            client.setNotificationHandler("notifications/resources/updated", ({ params }) => { if (params.uri === resource.uri) void refresh(); });
-            const subscription = await client.listen({ resourceSubscriptions: [resource.uri] }, { signal });
-            if (!subscription.honoredFilter.resourceSubscriptions?.includes(resource.uri)) throw new Error(`${name} did not accept a subscription to ${resource.uri}.`);
-            established = true;
-            await refresh();
-            await subscription.closed;
-          } catch (error) {
-            failure ??= error;
-          } finally {
-            await current.close();
-          }
-          if (signal?.aborted) return;
-          if (failure && !established) throw failure;
+        // A server may keep asking, so answering stops after ten rounds, the MCP clients' own limit, and the last question reaches the caller.
+        if (!elicit || !isInputRequiredResult(result) || round++ === 10) return connection ? downloads(result, connection) : result;
+        const inputResponses: InputResponses = {};
+        for (const [key, question] of Object.entries(result.inputRequests ?? {})) {
+          // Every client declares elicitation alone, so it answers nothing else and such a question reaches the caller.
+          if (question.method !== "elicitation/create") return result;
+          inputResponses[key] = await elicit(question.params);
         }
-      };
-      resources[resource.uri] = Object.freeze({ read, watch });
-    }
-    // MCP Events, the draft extension: https://github.com/modelcontextprotocol/experimental-ext-triggers-events/blob/main/docs/design-sketch-proposal.md
-    // Its requests go over the runtime's own connection, which a hosted session does not have.
-    const connected = <T>(options: CallOptions | undefined, run: (client: Client) => Promise<T>) => session(options, (_, connection) => {
-      if (!connection) throw new Error(`MCP Events of ${name} require an endpoint binding.`);
-      return run(connection.client);
-    });
-    const list = (options?: CallOptions) => connected(options, async client => {
-      const events: EventType[] = [];
-      for (let cursor: string | undefined; ;) {
-        const page = await client.request({ method: "events/list", params: { ...(cursor && { cursor }) } }, anything, patient(options)) as Listed;
-        events.push(...page.events ?? []);
-        if (!(cursor = page.nextCursor)) return events;
+        next = { ...next, inputResponses, requestState: result.requestState };
       }
     });
-    const subscribe = async (event: string, args: unknown = {}, { signal, onGap, maxAgeMs, ...options }: SubscribeOptions = {}): Promise<Subscription> => {
-      const resolved = current();
-      if (!resolved?.endpoint) throw new Error(`Subscribing to ${name} ${event} requires an endpoint binding.`);
-      const offered = (await list(signal && { signal })).find(type => type.name === event)?.delivery;
-      if (!offered) throw new Error(`${name} has no event ${event}.`);
-      // Push hears of an event at once, and poll works wherever a request does. Webhook delivery is not supported.
-      const delivery = options.delivery ?? (["push", "poll"] as const).find(mode => offered.includes(mode));
-      // The sketch's NoCompatibleDeliveryMode: none of the modes the server offers is one this client uses.
-      if (!delivery || !offered.includes(delivery)) throw Object.assign(new Error(`${name} does not deliver ${event} by ${delivery ?? "poll or push"}.`), { name: "NoCompatibleDeliveryMode" });
-      const cancelled = new AbortController();
-      const ended = signal ? AbortSignal.any([signal, cancelled.signal]) : cancelled.signal;
-      let cursor = options.cursor ?? null;
-      const queue: EventOccurrence[] = [];
-      const seen = new Set<string>();
-      let wake = () => {};
-      let done = false;
-      let failure: unknown;
-      // An absent cursor is a null one, and a null one is never resumed from.
-      const reach = (next: string | null | undefined, truncated?: boolean) => {
-        cursor = next ?? null;
-        if (truncated) onGap?.();
-      };
-      // The client checks an event's data against the contract it was compiled against, as it does a tool's output.
-      const expected = contract?.events?.find(type => type.name === event)?.payloadSchema;
-      let valid: Check | undefined;
-      const deliver = ({ cursor: _, _meta, ...occurrence }: Sent) => {
-        if (seen.has(occurrence.eventId)) return;
-        seen.add(occurrence.eventId);
-        if (seen.size > 1024) seen.delete(seen.values().next().value!);
-        if (expected) validate(valid ??= validator(expected), occurrence.data, `data of ${name} ${event}`);
-        queue.push(occurrence);
-        wake();
-      };
-      const request = { name: event, arguments: args, ...(maxAgeMs !== undefined && { maxAgeMs }) };
-      let confirmed = false;
-      const established = Promise.withResolvers<void>();
-      const confirm = () => { confirmed = true; established.resolve(); };
-      const poll = async () => {
-        while (!ended.aborted) {
-          let wait = 1000;
-          try {
-            const result = await connected({ signal: ended }, client => client.request({ method: "events/poll", params: { ...request, cursor } }, anything, patient({ signal: ended })) as Promise<Polled>);
-            try { for (const occurrence of result.events ?? []) deliver(occurrence); } catch (error) { failure = error; return cancelled.abort(); }
-            reach(result.cursor, result.truncated);
-            confirm();
-            // A server that asks for a tight loop is not obeyed.
-            wait = result.hasMore ? 0 : Math.max(1000, result.nextPollMs ?? 0);
-          } catch (error) {
-            if (ended.aborted) return;
-            if (!confirmed || refused(error)) throw error;
-          }
-          await sleep(wait, ended);
-        }
-      };
-      const stream = async () => {
-        while (!ended.aborted) {
-          let wait = 1000;
-          const quiet = new AbortController();
-          // The MCP client keeps waiting for the answer of a request whose stream has ended, so the end is watched for here.
-          // Only the stream's own response is watched: a 2025 server answers its initialization as a stream too.
-          const watched: typeof fetch = async (input, init) => {
-            const response = await (resolved.fetch ?? fetch)(input, init);
-            const streaming = typeof init?.body === "string" && init.body.includes('"method":"events/stream"');
-            if (!streaming || !response.body || !response.headers.get("content-type")?.startsWith("text/event-stream")) return response;
-            const reader = response.body.getReader();
-            const body = new ReadableStream({
-              pull: controller => reader.read().then(({ done, value }) => {
-                if (!done) return controller.enqueue(value);
-                controller.close();
-                // The answer, when the stream ended with one, is handled first.
-                setTimeout(() => quiet.abort());
-              }, error => { controller.error(error); quiet.abort(); }),
-              cancel: reason => reader.cancel(reason),
-            });
-            return new Response(body, response);
-          };
-          // Each stream has its own connection, so every event notification on it is this subscription's.
-          const connection = connect({ ...resolved, fetch: watched });
-          let timer: ReturnType<typeof setTimeout> | undefined;
-          const heard = () => {
-            clearTimeout(timer);
-            timer = setTimeout(() => quiet.abort(), QUIET);
-          };
-          let terminated: { code?: number; message?: string; data?: unknown } | undefined;
-          try {
-            await untilAborted(connection.ready, ended);
-            const on = (method: string, handle: (params: any) => void) => connection.client.setNotificationHandler(`notifications/events/${method}`, { params: anything }, params => { heard(); handle(params); });
-            on("active", ({ cursor: next, truncated }) => { reach(next, truncated); confirm(); });
-            on("event", occurrence => {
-              wait = 0;
-              try { deliver(occurrence); } catch (error) { failure = error; return cancelled.abort(); }
-              reach(occurrence.cursor);
-            });
-            on("heartbeat", ({ cursor: next }) => reach(next));
-            // The server recovers from an error by itself, and the stream stays open.
-            on("error", () => {});
-            on("terminated", ({ error }) => { terminated = error; quiet.abort(); });
-            heard();
-            await connection.client.request({ method: "events/stream", params: { ...request, cursor } }, anything, { signal: AbortSignal.any([ended, quiet.signal]), timeout: 2 ** 31 - 1 });
-          } catch (error) {
-            if (!terminated && !ended.aborted && (!confirmed || refused(error))) throw error;
-          } finally {
-            clearTimeout(timer);
-            await connection.close();
-          }
-          if (terminated) throw Object.assign(new Error(`${name} ended the subscription to ${event}: ${terminated.message}`), { code: terminated.code, data: terminated.data });
-          await sleep(wait, ended);
+    if (isInputRequiredResult(result)) return result;
+    if (!result.isError) tool?.output?.(result.structuredContent);
+    // isError tells ToolResult's success variant from its error variant.
+    return { ...result, resultType: "complete" } as ToolResult<unknown>;
+  };
+  const listTools = (options?: CallOptions) => link.session(options, client => client.listTools(undefined, patient(options)));
+  const tools: Record<string, RuntimeClient["tools"][string]> = Object.create(null);
+  for (const tool of contract?.tools ?? []) if (!reserved.has(tool.name)) {
+    tools[tool.name] = async (input, options) => {
+      const result = await callTool({ name: tool.name, arguments: input }, options);
+      if (result.resultType === "input_required" || result.isError) throw new ToolCallError(name, tool.name, result);
+      return tool.outputSchema ? result.structuredContent : result;
+    };
+  }
+  // Generated clients narrow callTool to their contract's tools and outputs, which validation upholds.
+  return { callTool: callTool as RuntimeClient["callTool"], listTools, tools: Object.freeze(tools) };
+}
+
+function resources(link: Link, contract: Contract | null, expect: Expect): RuntimeClient["resources"] {
+  const { name } = link;
+  const resources: Record<string, RuntimeClient["resources"][string]> = Object.create(null);
+  for (const resource of contract?.resources ?? []) {
+    const check = expect(resource.outputSchema, `contents from ${name} ${resource.uri}`);
+    const parse = (result: ReadResourceResult): unknown => {
+      const [content] = result.contents;
+      if (!content || !("text" in content)) throw new Error(`Invalid contents from ${name} ${resource.uri}: no text content`);
+      const value = JSON.parse(content.text);
+      check(value);
+      return value;
+    };
+    const read = async (options?: CallOptions) => parse(await link.session(options, client => client.readResource({ uri: resource.uri }, patient(options))));
+    const watch = async (onChange: (value: unknown) => void | Promise<void>, { signal }: { signal?: AbortSignal } = {}) => {
+      const resolved = link.endpoint(`Watching ${name} ${resource.uri}`);
+      // An abort ends the wait between attempts early instead of failing it.
+      for (let established = false; !signal?.aborted; await sleep(1000, signal)) {
+        const current = link.connect(resolved);
+        let failure: unknown;
+        try {
+          await untilAborted(current.ready, signal);
+          const { client } = current;
+          if (!client.getServerCapabilities()?.resources?.subscribe) throw new Error(`${name} does not advertise resource subscriptions.`);
+          let reads = Promise.resolve();
+          const refresh = () => (reads = reads.then(async () => onChange(parse(await client.readResource({ uri: resource.uri }, patient({ signal, cacheMode: "bypass" })))))
+            .catch(error => { failure ??= error; return current.close(); }));
+          client.setNotificationHandler("notifications/resources/updated", ({ params }) => { if (params.uri === resource.uri) void refresh(); });
+          const subscription = await client.listen({ resourceSubscriptions: [resource.uri] }, { signal });
+          if (!subscription.honoredFilter.resourceSubscriptions?.includes(resource.uri)) throw new Error(`${name} did not accept a subscription to ${resource.uri}.`);
+          established = true;
+          await refresh();
+          await subscription.closed;
+        } catch (error) {
+          failure ??= error;
+        } finally {
+          await current.close();
         }
-      };
-      void (delivery === "push" ? stream() : poll())
-        .catch(error => { failure ??= error; })
-        .finally(() => { done = true; wake(); established.reject(failure ?? ended.reason); });
-      await established.promise;
-      return {
-        delivery,
-        get cursor() { return cursor; },
-        cancel: () => cancelled.abort(),
-        [Symbol.asyncIterator]: () => ({
-          next: async (): Promise<IteratorResult<EventOccurrence>> => {
-            while (!queue.length && !done) await new Promise<void>(resolve => { wake = resolve; });
-            const value = queue.shift();
-            if (value) return { value, done: false };
-            if (failure) throw failure;
-            return { value: undefined, done: true };
-          },
-          return: async (): Promise<IteratorResult<EventOccurrence>> => { cancelled.abort(); return { value: undefined, done: true }; },
-        }),
-      };
+        if (signal?.aborted) return;
+        if (failure && !established) throw failure;
+      }
     };
-    // Generated clients narrow callTool to their contract's tools and outputs, which validation upholds.
-    apps[name] = Object.freeze({ callTool: callTool as RuntimeClient["callTool"], listTools, ext: Object.freeze({ events: Object.freeze({ list, subscribe: subscribe as RuntimeClient["ext"]["events"]["subscribe"] }) }), resources: Object.freeze(resources), close: async () => { await connection?.close(); }, tools: Object.freeze(tools) });
+    resources[resource.uri] = Object.freeze({ read, watch });
   }
-  return Object.freeze(apps);
+  return Object.freeze(resources);
 }

package/src/serve.ts

@@ -50,9 +50,6 @@ async function respond(handler: App["default"], directory: URL | undefined, req:
     res.on("close", () => gone.abort());
     const headers = new Headers();
     for (const [name, values = []] of Object.entries(req.headersDistinct)) for (const value of values) headers.append(name, value);
-    // Holon forwards the origin it serves the app at. Here that is this server, unless a proxy in front forwards its own.
-    if (!headers.has("x-forwarded-host")) headers.set("x-forwarded-host", url.host);
-    if (!headers.has("x-forwarded-proto")) headers.set("x-forwarded-proto", "http");
     const body = req.method === "GET" || req.method === "HEAD" ? undefined : req;
     const response = await handler.fetch(new Request(url, { method: req.method, headers, body, duplex: "half", signal: gone.signal }));
     res.setHeaders(response.headers).writeHead(response.status);