holon-sh 0.0.1-dev.6 → 0.0.1-dev.8

package/src/runtime.ts

@@ -0,0 +1,315 @@
+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 { AjvJsonSchemaValidator } from "@modelcontextprotocol/client/validators/ajv";
+import { EXTENSION } from "./ext/files.js";
+import { acceptUploadRequests, downloads, isUploadRequest, prepare, settings, upload } from "./ext/files.client.js";
+import { ToolCallError } 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, ToolCallOptions, ToolResult, ToolClient } from "./protocol.js";
+
+/** Connection settings for an MCP endpoint. */
+export interface Binding {
+  /** Streamable HTTP MCP endpoint. */
+  endpoint: URL | string;
+  /** Authentication provider; use application-owned credentials. */
+  authProvider?: AuthProvider;
+  /** Custom fetch implementation, for example for an in-process transport. */
+  fetch?: typeof fetch;
+  /** Optional X-Holon-Installation-UID routing header. */
+  installationUID?: string;
+  /** Close the session after every call instead of keeping one connection open. */
+  scoped?: boolean;
+  /** 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 }> }
+/** Generation-time tool and JSON resource schemas. A null contract permits unvalidated callTool requests. */
+export interface Contract {
+  tools: Array<{ name: string; inputSchema: Record<string, unknown>; outputSchema?: Record<string, unknown> }>;
+  resources?: Array<{ uri: string; outputSchema: Record<string, unknown> }>;
+}
+/** Untyped client returned by the low-level runtime. Generated clients specialize its inputs, outputs, and resources. */
+export type RuntimeClient = ToolClient<Record<string, Record<string, unknown>>, Record<string, unknown>, Record<string, unknown>>;
+/** The subset of an MCP client a session must provide. A tool call may also resolve to the server's input_required question. */
+export interface ToolSession {
+  callTool(request: CallToolRequest["params"], options?: CallToolRequestOptions): Promise<CallToolResult | InputRequiredResult>;
+  readResource(request: ReadResourceRequest["params"], options?: CacheableRequestOptions): Promise<ReadResourceResult>;
+  listTools(params?: ListToolsRequest["params"], options?: CacheableRequestOptions): Promise<ListToolsResult>;
+}
+/** Optional validation, binding resolution, and host-session hooks. */
+export interface CreateOptions<B = Binding> {
+  /** JSON Schema validator factory. The default uses Ajv. A check may set errors, which a failure reports. */
+  validator?: (schema: object) => { (value: unknown): boolean; errors?: unknown };
+  /** Binding of an app created without explicit bindings; consulted on every call. */
+  resolve?: (app: string) => Binding | undefined;
+  /** Session for a binding the runtime does not connect to itself (anything without an endpoint). */
+  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"]>>;
+
+// 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>();
+
+function defaultValidator(schema: object): Check {
+  const cached = checks.get(schema);
+  if (cached) return cached;
+  const compiled = new AjvJsonSchemaValidator().getValidator(schema);
+  const check: Check = value => {
+    const { valid, errorMessage } = compiled(value);
+    check.errors = errorMessage;
+    return valid;
+  };
+  checks.set(schema, 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 };
+}
+
+/** 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] => {
+    if (!Object.hasOwn(contracts, name) && !Object.hasOwn(identity.requires ?? {}, name)) throw new Error("Unknown app binding: " + name);
+    return [name, contracts[name] ?? null];
+  }));
+  return createApps(identity, selected, bindings, options);
+}
+
+/** 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 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 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;
+          }
+          // 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, settings(connection) !== undefined) : 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 (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;
+        }
+      };
+      resources[resource.uri] = Object.freeze({ read, watch });
+    }
+    // Generated clients narrow callTool to their contract's tools and outputs, which validation upholds.
+    apps[name] = Object.freeze({ callTool: callTool as RuntimeClient["callTool"], listTools, resources: Object.freeze(resources), close: async () => { await connection?.close(); }, tools: Object.freeze(tools) });
+  }
+  return Object.freeze(apps);
+}

package/generated/holon-generated.json

@@ -1,4 +0,0 @@
-{
-  "marker": "holon-generated-apps-v1",
-  "placeholder": true
-}

package/generated/index.d.ts

@@ -1,12 +0,0 @@
-// holon-generated-apps-v1 placeholder
-export type Apps = Record<never, never>;
-export type Inputs = Record<never, never>;
-export type Outputs = Record<never, never>;
-export type InputTypes = Inputs;
-export type OutputTypes = Outputs;
-export type Resources = Record<never, never>;
-export { ToolCallError } from "../protocol.js";
-export type { Binding, EndpointBinding, CreateOptions } from "../runtime.js";
-import type { CreateOptions } from "../runtime.js";
-export declare function createApps(bindings: Record<string, never>, options?: CreateOptions): Apps;
-export declare const apps: Apps;

package/generated/index.js

@@ -1,5 +0,0 @@
-// holon-generated-apps-v1 placeholder
-import {createApps as create} from "../runtime.mjs";
-export {ToolCallError} from "../runtime.mjs";
-export const apps = create({name:"unconfigured",version:"0",requires:{}}, {});
-export function createApps(bindings, options) { if (Object.keys(bindings).length) throw new Error("Run holon types generate to configure app bindings."); return apps; }

package/runtime.d.ts

@@ -1,49 +0,0 @@
-import type { AuthProvider, CallOptions, ToolClient } from "./protocol.js";
-export { ToolCallError } from "./protocol.js";
-export type { AuthProvider, CallOptions, CallMetadata, ElicitHandler, ToolCallOptions, ToolResult, ToolClient } from "./protocol.js";
-
-/** Connection settings for an MCP endpoint. */
-export interface Binding {
-  /** Streamable HTTP MCP endpoint. */
-  endpoint: URL | string;
-  /** Authentication provider; use application-owned credentials. */
-  authProvider?: AuthProvider;
-  /** Custom fetch implementation, for example for an in-process transport. */
-  fetch?: typeof fetch;
-  /** Optional X-Holon-Installation-UID routing header. */
-  installationUID?: string;
-  /** Close the session after every call instead of keeping one connection open. */
-  scoped?: boolean;
-}
-/** 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 }> }
-/** Generation-time tool and JSON resource schemas. A null contract permits unvalidated callTool requests. */
-export interface Contract {
-  tools: Array<{ name: string; inputSchema: Record<string, unknown>; outputSchema?: Record<string, unknown> }>;
-  resources?: Array<{ uri: string; outputSchema: Record<string, unknown> }>;
-}
-/** Untyped client returned by the low-level runtime. Generated clients specialize its inputs, outputs, and resources. */
-export type RuntimeClient = ToolClient<Record<string, Record<string, unknown>>, Record<string, unknown>, Record<string, unknown>>;
-/** The subset of an MCP client a session must provide. */
-export interface ToolSession {
-  callTool(request: { name: string; arguments?: Record<string, unknown> }, options?: Record<string, unknown>): Promise<any>;
-  readResource(request: { uri: string }, options?: Record<string, unknown>): Promise<any>;
-  listTools(params?: undefined, options?: Record<string, unknown>): Promise<any>;
-}
-/** Optional validation, binding resolution, and host-session hooks. */
-export interface CreateOptions<B = Binding> {
-  /** JSON Schema validator factory. The default uses Ajv. */
-  validator?: (schema: object) => (value: unknown) => boolean;
-  /** Binding of an app created without explicit bindings; consulted on every call. */
-  resolve?: (app: string) => Binding | undefined;
-  /** Session for a binding the runtime does not connect to itself (anything without an endpoint). */
-  session?: (app: string, binding: B) => ToolSession | undefined;
-}
-/** 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 package root. */
-export declare function createApps<B = Binding>(identity: Identity, contracts: Record<string, Contract | null>, bindings?: Record<string, B>, options?: CreateOptions<B>): Readonly<Record<string, RuntimeClient>>;
-/** Construct only the explicitly bound dependencies. Unknown names throw; an empty binding map selects none. Used by generated createApps factories. */
-export declare function bindApps<B = Binding>(identity: Identity, contracts: Record<string, Contract | null>, bindings: Record<string, B>, options?: CreateOptions<B>): Readonly<Record<string, RuntimeClient>>;
-/** For hosts: register a process-wide resolver for clients created without explicit bindings. Explicit bindings take precedence; return undefined to fall back to the <NAME>_MCP_URL environment variable. Register during startup. */
-export declare function setDefaultBinding(resolve: (app: string) => Binding | undefined): void;

package/runtime.mjs

@@ -1,191 +0,0 @@
-import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
-import { validator as defaultValidator } from "./validate.mjs";
-
-// Shared with the private @holon-sh/sdk and existing hosts.
-const DEFAULT_BINDING = Symbol.for("@holon-sh/sdk/default-binding");
-
-// Unbound clients fall back to <NAME>_MCP_URL when the resolver returns undefined.
-export function setDefaultBinding(resolve) {
-  if (typeof resolve !== "function") throw new TypeError("Binding resolver must be a function.");
-  globalThis[DEFAULT_BINDING] = resolve;
-}
-
-function environment(identity, name) {
-  if (!Object.hasOwn(identity.requires ?? {}, name)) return undefined;
-  const variable = `${name.toUpperCase().replaceAll("-", "_")}_MCP_URL`;
-  const endpoint = process.env[variable];
-  // Environment-bound dependencies connect for one call at a time.
-  if (endpoint) return { endpoint, scoped: true };
-  throw new Error(`Dependency ${name} is unavailable (${variable}). Provide a binding or set the environment variable.`);
-}
-
-export class ToolCallError extends Error {
-  constructor(app, tool, result) {
-    const asking = result.resultType === "input_required";
-    const detail = asking
-      ? Object.values(result.inputRequests ?? {}).flatMap(({ params }) => [params?.message, params?.url]).filter(Boolean).join(" ")
-      : result.content?.find(part => part.type === "text")?.text;
-    super(`${app}.${tool}: ${asking ? "additional input required" : "tool failed"}${detail ? `: ${detail}` : ""}`);
-    this.name = "ToolCallError";
-    this.result = result;
-  }
-}
-
-function validate(check, value, label) {
-  if (!check(value)) throw new Error(`Invalid ${label}: ${JSON.stringify(check.errors)}`);
-}
-
-function untilAborted(promise, signal) {
-  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));
-  });
-}
-
-function delay(milliseconds, signal) {
-  return new Promise(resolve => {
-    const timer = setTimeout(resolve, milliseconds);
-    signal?.addEventListener("abort", () => { clearTimeout(timer); resolve(); }, { once: true });
-  });
-}
-
-export function bindApps(identity, contracts, bindings, options) {
-  const selected = Object.fromEntries(Object.keys(bindings).map(name => {
-    if (!Object.hasOwn(contracts, name) && !Object.hasOwn(identity.requires ?? {}, name)) throw new Error("Unknown app binding: " + name);
-    return [name, contracts[name] ?? null];
-  }));
-  return createApps(identity, selected, bindings, options);
-}
-
-export function createApps(identity, contracts, bindings, options) {
-  const { validator = defaultValidator, resolve = name => globalThis[DEFAULT_BINDING]?.(name) ?? environment(identity, name), session: hosted } = options ?? {};
-  const apps = Object.create(null);
-  // Without explicit bindings, every declared dependency gets a client; those without a contract are untyped.
-  const members = { ...(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 = () => binding ?? (bindings ? undefined : resolve(name));
-    let connection;
-    const connect = resolved => {
-      // 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: {} } }, versionNegotiation: { mode: "auto" } });
-      const transport = new StreamableHTTPClientTransport(new URL(resolved.endpoint), { authProvider: resolved.authProvider, fetch: resolved.fetch, requestInit: { credentials: "include", redirect: "error", headers: resolved.installationUID ? { "X-Holon-Installation-UID": resolved.installationUID } : {} } });
-      const current = { client, close: async () => {
-        await transport.close();
-        await current.ready.catch(() => {});
-      } };
-      transport.onclose = () => { if (connection === current) connection = undefined; };
-      current.ready = client.connect(transport).catch(async error => {
-        await transport.close();
-        throw error;
-      });
-      return current;
-    };
-    // The session hook serves bindings the runtime does not connect to itself.
-    const host = binding && hosted?.(name, binding);
-    const session = async (options, run) => {
-      options?.signal?.throwIfAborted();
-      if (host) return run(host);
-      const resolved = current();
-      if (!resolved) throw new Error(Object.hasOwn(identity.requires ?? {}, name)
-        ? `Dependency ${name} is unavailable. Provide a binding.`
-        : `Dependency ${name} is not declared by this application.`);
-      if (!resolved.endpoint) throw new Error(`Dependency ${name} binding has no endpoint.`);
-      // Bindings marked scoped connect for one call at a time.
-      const scoped = resolved.scoped === true;
-      const active = scoped ? connect(resolved) : (connection ??= connect(resolved));
-      try {
-        await untilAborted(active.ready, options?.signal);
-        return await run(active.client);
-      } finally { if (scoped) await active.close(); }
-    };
-    const tools = Object.create(null);
-    const definitions = new Map((contract?.tools ?? []).map(definition => [definition.name, { definition }]));
-    const callTool = async (request, { elicit, ...options } = {}) => {
-      const tool = definitions.get(request.name);
-      if (!tool && contract) throw new Error(`Unknown tool ${name}.${request.name}.`);
-      let validation;
-      if (tool) {
-        const { definition } = tool;
-        validation = tool.validation ??= {
-          input: validator(definition.inputSchema),
-          output: definition.outputSchema ? validator(definition.outputSchema) : undefined,
-        };
-        validate(validation.input, request.arguments, `arguments for ${name}.${request.name}`);
-      }
-      const result = await session(options, async client => {
-        const send = request => client.callTool(request, {
-          ...options, allowInputRequired: true,
-          ...(tool && { toolDefinition: { ...tool.definition, outputSchema: undefined } }),
-        });
-        let result = await send(request);
-        // A server may keep asking, so answering stops after ten rounds, the MCP clients' own limit, and the last question reaches the caller.
-        for (let round = 0; elicit && result.resultType === "input_required" && round < 10; round++) {
-          const inputResponses = {};
-          for (const [key, { params }] of Object.entries(result.inputRequests ?? {})) inputResponses[key] = await elicit(params);
-          result = await send({ ...request, inputResponses, requestState: result.requestState });
-        }
-        return result;
-      });
-      if (result.resultType === "input_required") return result;
-      if (!result.isError && validation?.output) {
-        validate(validation.output, result.structuredContent, `structured output from ${name}.${request.name}`);
-      }
-      return { ...result, resultType: "complete" };
-    };
-    const listTools = options => session(options, client => client.listTools(undefined, options));
-    for (const tool of contract?.tools ?? []) if (!["then", "toJSON", "toString", "valueOf", "toLocaleString"].includes(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 = Object.create(null);
-    for (const resource of contract?.resources ?? []) {
-      let valid;
-      const parse = result => {
-        const value = JSON.parse(result.contents[0].text);
-        valid ??= validator(resource.outputSchema);
-        validate(valid, value, `contents from ${name} ${resource.uri}`);
-        return value;
-      };
-      const read = async options => parse(await session(options, client => client.readResource({ uri: resource.uri }, options)));
-      const watch = async (onChange, { signal } = {}) => {
-        const resolved = current();
-        if (!resolved?.endpoint) throw new Error(`Watching ${name} ${resource.uri} requires an endpoint binding.`);
-        for (let established = false; !signal?.aborted; await delay(1000, signal)) {
-          const current = connect(resolved);
-          let failure;
-          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 }, { 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;
-        }
-      };
-      resources[resource.uri] = Object.freeze({ read, watch });
-    }
-    apps[name] = Object.freeze({ callTool, listTools, resources: Object.freeze(resources), close: async () => { await connection?.close(); }, tools: Object.freeze(tools) });
-  }
-  return Object.freeze(apps);
-}

package/validate.mjs

@@ -1,10 +0,0 @@
-import Ajv from "ajv";
-import { Ajv2020 } from "ajv/dist/2020.js";
-import addFormats from "ajv-formats";
-
-export function validator(schema) {
-  const constructor = schema.$schema?.includes("draft-07") ? Ajv : Ajv2020;
-  const ajv = new constructor({ strict: false, ownProperties: true, allErrors: true });
-  addFormats(ajv);
-  return ajv.compile(schema);
-}

package/view.d.ts

@@ -1,47 +0,0 @@
-/** MIME type of an MCP App HTML resource. */
-export declare const VIEW_MIME_TYPE = "text/html;profile=mcp-app";
-/** Allowed network and asset domains for the view content security policy. */
-export interface ViewOptions {
-    csp?: {
-        connectDomains?: string[];
-        resourceDomains?: string[];
-    };
-}
-type ViewRegistration = [
-    name: string,
-    uri: string,
-    metadata: {
-        mimeType: string;
-        _meta: {
-            ui: {
-                csp: {
-                    connectDomains: string[];
-                    resourceDomains: string[];
-                };
-            };
-        };
-    },
-    read: () => Promise<{
-        ttlMs: number;
-        cacheScope: "private";
-        contents: {
-            uri: string;
-            mimeType: string;
-            text: string;
-        }[];
-    }>
-];
-/**
- * Create a registration tuple for server.registerResource(...appView(...)).
- * Node only: the HTML file is read once when this helper is called.
- * Resource reads reuse that promise; file read failures reject resource requests.
- * @param name Human-readable resource name.
- * @param uri Resource URI, usually starting with ui://.
- * @param file Built HTML file path or file URL.
- * @param options View content security policy.
- * @returns Name, URI, metadata, and resource-read callback.
- * @example
- * server.registerResource(...appView("App", "ui://app/index.html", new URL("./index.html", import.meta.url)));
- */
-export declare function appView(name: string, uri: string, file: URL | string, options?: ViewOptions): ViewRegistration;
-export {};