holon-sh 0.0.1-dev.5 → 0.0.1-dev.7

package/README.md

@@ -10,7 +10,7 @@ This repository contains the Node.js runtime for [`holon`](https://github.com/ho
 
 ```sh
 npm install holon-sh@dev
-npm install -D holon-types
+npm install -D holon-types@next
 ```
 
 `holon-types` is the `holon` CLI. `holon types check` brings its own TypeScript compiler and uses the project's `typescript` when one is installed.
@@ -25,11 +25,13 @@ The Holon TypeScript SDK allows generation of type-safe MCP clients. See [Exampl
 npx holon types check
 ```
 
+`holon types generate` and `holon types check` write the clients to `generated/holon-sh/` beside your `package.json`, and map `#holon-sh` to them in its `imports`. A package that publishes code calling them lists `generated/holon-sh` in its `files`, so the projects that install it need not generate.
+
 <details open>
 <summary><h3>Call a tool</h3></summary>
 
 ```ts
-import { apps } from "holon-sh";
+import { apps } from "#holon-sh";
 
 export async function greet(name: string): Promise<string> {
   const greeting = await apps.bar.tools.greet({ name }, { timeout: 5000 });
@@ -37,21 +39,21 @@ export async function greet(name: string): Promise<string> {
 }
 ```
 
-Arguments are validated before sending; the result is validated against the output schema and returned.
-
 </details>
 
 <details open>
 <summary><h3>Handle errors</h3></summary>
 
 ```ts
-import { ToolCallError, apps } from "holon-sh";
+import { ToolCallError, apps } from "#holon-sh";
 
 try {
   await apps.bar.tools.greet({ name: "world" });
 } catch (error) {
   if (!(error instanceof ToolCallError)) throw error;
-  error.result; // the original MCP result
+  error.message; // includes the server's text
+  error.data;    // the server's structured content, or its text parsed as JSON
+  error.result;  // the original MCP result
 }
 ```
 
@@ -65,7 +67,7 @@ try {
 ```ts
 const result = await apps.bar.callTool({ name: "greet", arguments: { name: "world" } });
 if (result.resultType === "input_required") {
-  // call again with inputResponses and requestState, or bind elicit to answer in place
+  // call again with inputResponses and requestState
 } else if (result.isError) {
   // inspect result.content
 } else {
@@ -78,27 +80,22 @@ if (result.resultType === "input_required") {
 <details open>
 <summary><h3>Answer a server's question</h3></summary>
 
-A tool can stop and ask for input through an [MCP elicitation](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation). Bind `elicit` to answer in place, and the call returns its usual typed output:
+A tool can stop and ask for input through an [MCP elicitation](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation). Pass `elicit` to answer in place, and the call returns its usual typed output:
 
 ```ts
-const apps = createApps({
-  bar: {
-    endpoint: "https://bar.example.com/mcp",
-    elicit: async ({ params }) => ({ action: "accept", content: await ask(params.message) }),
-  },
+const greeting = await apps.bar.tools.greet({ name: "world" }, {
+  elicit: async ({ message }) => ({ action: "accept", content: await ask(message) }),
 });
-
-const greeting = await apps.bar.tools.greet({ name: "world" });
 ```
 
-To answer later, for example in another request, declare `capabilities: { elicitation: { form: {} } }` instead. The question then arrives as an `input_required` result from `callTool`, or on `ToolCallError.result` from `tools`. Without either option, a server that needs the capability rejects the call.
+Without `elicit`, the question arrives on `ToolCallError.result`, or as an `input_required` result from `callTool`. To answer later, for example in another request, call again with `inputResponses` and `requestState`.
 
 </details>
 
 <details open>
 <summary><h3>Read a resource</h3></summary>
 
-A provider types a JSON resource by registering it with `mimeType: "application/json"` and an `"sh.holon/outputSchema"` JSON Schema in its `_meta`, as the `orders` server in `tests/fixtures` does. The client then offers `read` and `watch`:
+A provider types a JSON resource by registering it with `mimeType: "application/json"` and an `"sh.holon/outputSchema"` JSON Schema in its `_meta`. The client then offers `read` and `watch`:
 
 ```ts
 const summary = await apps.orders.resources["orders://summary"].read();
@@ -113,16 +110,17 @@ await apps.orders.resources["orders://summary"].watch(value => console.log(value
 
 </details>
 
-## Serve an [MCP App](https://modelcontextprotocol.io/extensions/apps/overview) view
+## Identify the caller
+
+Inside a tool callback, `getContext(ctx.http).principal` is the user Holon admitted for the request, or `null` for anonymous requests. A `createMcpHandler` factory can pass its `McpRequestContext` instead.
 
 ```ts
-import { appView } from "holon-sh/view";
+import { getContext } from "holon-sh/context";
 
-server.registerResource(
-  ...appView("Foo", "ui://foo/index.html", new URL("./dist/index.html", import.meta.url), {
-    csp: { connectDomains: ["https://bar.example.com"] },
-  }),
-);
+server.registerTool("whoami", {}, async ctx => {
+  const { principal } = getContext(ctx.http);
+  if (!principal) throw new Error("Sign in first.");
+  principal.claims.email; // standard OpenID claims are typed: string | undefined
+  return { content: [{ type: "text", text: `${principal.subject} at ${principal.issuer}` }] };
+});
 ```
-
-The page itself uses [`holon-ui`](https://github.com/holon-sh/sdk-ui).

package/context.d.ts

@@ -0,0 +1,19 @@
+/** Standard OpenID Connect address claims. */
+export interface AddressClaims {
+  formatted?: string; street_address?: string; locality?: string; region?: string; postal_code?: string; country?: string;
+  [claim: string]: unknown;
+}
+/** Standard OpenID Connect claims. Holon drops one whose value has the wrong type; other claims pass through as JSON. */
+export interface IdentityClaims {
+  name?: string; given_name?: string; family_name?: string; middle_name?: string; nickname?: string;
+  preferred_username?: string; profile?: string; picture?: string; website?: string; email?: string;
+  email_verified?: boolean; gender?: string; birthdate?: string; zoneinfo?: string; locale?: string;
+  phone_number?: string; phone_number_verified?: boolean; address?: AddressClaims; updated_at?: number;
+  [claim: string]: unknown;
+}
+/** The user a request acts for, as Holon admitted it. */
+export interface Principal { issuer: string; subject: string; clientId: string; scopes: string[]; claims: IdentityClaims; actor?: Record<string, unknown> }
+/** The caller of the current MCP request. principal is null for anonymous requests. */
+export interface RequestContext { principal: Principal | null }
+/** Read the caller from the context an MCP server receives: a tool callback's ctx.http, or the McpRequestContext of a createMcpHandler factory. */
+export declare function getContext(context?: { authInfo?: { clientId: string; scopes: string[]; extra?: Record<string, unknown> } }): RequestContext;

package/context.mjs

@@ -0,0 +1,6 @@
+// Holon admits the caller before the request reaches the server and hands it over as MCP's authInfo.
+export function getContext({ authInfo } = {}) {
+  const { iss, sub, claims, act } = authInfo?.extra ?? {};
+  if (typeof iss !== "string" || typeof sub !== "string") return { principal: null };
+  return { principal: { issuer: iss, subject: sub, clientId: authInfo.clientId, scopes: authInfo.scopes, claims: claims ?? {}, ...(act && { actor: act }) } };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "holon-sh",
-  "version": "0.0.1-dev.5",
-  "description": "Typed MCP clients and app view resources for Node.js.",
+  "version": "0.0.1-dev.7",
+  "description": "Typed MCP clients and the caller of an MCP request, for Node.js.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/holon-sh/sdk-ts.git",
@@ -16,21 +16,16 @@
     "access": "public"
   },
   "holon": {
-    "slot": "generated",
-    "contractVersion": 1
+    "contractVersion": 2
   },
   "exports": {
-    ".": {
-      "types": "./generated/index.d.ts",
-      "import": "./generated/index.js"
-    },
     "./runtime": {
       "types": "./runtime.d.ts",
       "import": "./runtime.mjs"
     },
-    "./view": {
-      "types": "./view.d.ts",
-      "import": "./view.js"
+    "./context": {
+      "types": "./context.d.ts",
+      "import": "./context.mjs"
     },
     "./protocol": {
       "types": "./protocol.d.ts",
@@ -42,19 +37,14 @@
     "runtime.d.ts",
     "validate.mjs",
     "protocol.d.ts",
-    "view.js",
-    "view.d.ts",
-    "generated/",
-    "README.md"
+    "context.mjs",
+    "context.d.ts"
   ],
   "scripts": {
     "build": "node scripts/build.mjs",
-    "prepack": "npm run build",
-    "docs:build": "node scripts/build-reference.mjs"
+    "prepack": "npm run build"
   },
   "dependencies": {
-    "@modelcontextprotocol/client": "^2.3.1",
-    "ajv": "^8.20.0",
-    "ajv-formats": "^3.0.1"
+    "@modelcontextprotocol/client": "^2.3.1"
   }
 }

package/protocol.d.ts

@@ -1,16 +1,16 @@
-import type { CallToolRequest, CallToolResult, ClientCapabilities as McpClientCapabilities, ClientContext, ElicitRequest, ElicitResult, InputRequiredResult, InputResponses, ListToolsResult, RequestOptions } from "@modelcontextprotocol/client";
+import type { CallToolRequest, CallToolResult, ElicitRequestParams, ElicitResult, InputRequiredResult, InputResponses, ListToolsResult, RequestOptions } from "@modelcontextprotocol/client";
 
 /** Bearer-token or OAuth provider accepted by the MCP transport. */
 export type AuthProvider =
   | { token(): Promise<string | undefined>; onUnauthorized?(context: unknown): Promise<void> }
   | { tokens(): unknown; redirectUrl: unknown; clientMetadata: unknown };
-/** MCP client capabilities, such as `{ elicitation: { form: {} } }`. */
-export type ClientCapabilities = McpClientCapabilities;
-/** Answers a server's elicitation so the call that asked can complete. */
-export type ElicitHandler = (request: ElicitRequest, context: ClientContext) => ElicitResult | Promise<ElicitResult>;
+/** Answers a server's question so the call that asked can complete. `params.mode` tells a form from a URL to open. */
+export type ElicitHandler = (params: ElicitRequestParams) => ElicitResult | Promise<ElicitResult>;
 
-/** MCP request options, including AbortSignal and timeout in milliseconds. Input-required responses are enabled by the runtime. */
+/** MCP request options, including AbortSignal and timeout in milliseconds. A request without a timeout waits for its answer; progress from the server restarts a timeout. Input-required responses are enabled by the runtime. */
 export type CallOptions = Omit<RequestOptions, "allowInputRequired">;
+/** Call options for a tool. `elicit` answers its questions in place, so the call returns the completed result. */
+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 };
 /** @internal */
@@ -23,9 +23,13 @@ export type ToolResult<Output> =
   | (Omit<Fields<CallToolResult>, "structuredContent" | "isError"> & { resultType: "complete"; isError: true; structuredContent?: unknown })
   | InputRequiredResult;
 
-/** Error thrown by the tools convenience methods for error or input_required results. Inspect the original result; bind elicit to answer questions in place, or use callTool to continue later. */
+/** Error thrown by the tools convenience methods for error or input_required results. A failure's message carries its text; `data` is what the server said in a form to branch on. Pass elicit to answer questions in place, or continue later through callTool. */
 export declare class ToolCallError extends Error {
   readonly result: Extract<ToolResult<unknown>, { isError: true } | { resultType: "input_required" }>;
+  /** The failure's text content, its text blocks joined by newlines. Undefined for questions left unanswered. */
+  readonly text?: string;
+  /** The failure's structured content, or else its text parsed as JSON when that text is JSON. Its shape is the server's own. */
+  readonly data?: unknown;
   constructor(app: string, tool: string, result: ToolCallError["result"]);
 }
 
@@ -40,8 +44,8 @@ export interface ToolClient<I, O, R> {
     readonly read: (options?: CallOptions) => Promise<R[U]>;
     readonly watch: (onChange: (value: R[U]) => void | Promise<void>, options?: { signal?: AbortSignal }) => Promise<void>;
   } };
-  /** Convenience methods returning structured output, or the complete result for a tool without an output schema. Error results throw ToolCallError, as do input-required results when the binding has no elicit. Reserved object method names remain callable through callTool. */
-  readonly tools: { readonly [K in Exclude<keyof I, "then" | "toJSON" | "toString" | "valueOf" | "toLocaleString">]: (input: I[K], options?: CallOptions) => Promise<K extends keyof O ? O[K] : CompleteResult<unknown>> };
-  /** Return the full MCP result, preserving error results and, when the binding has no elicit, input-required results. Arguments and successful output are contract-validated. */
-  readonly callTool: <K extends keyof I & string>(request: CallMetadata & { name: K; arguments: I[K] }, options?: CallOptions) => Promise<ToolResult<K extends keyof O ? O[K] : unknown>>;
+  /** Convenience methods returning structured output, or the complete MCP result, with its content blocks typed, for a tool without an output schema. Error results throw ToolCallError, as do questions left unanswered. Reserved object method names remain callable through callTool. */
+  readonly tools: { readonly [K in Exclude<keyof I, "then" | "toJSON" | "toString" | "valueOf" | "toLocaleString">]: (input: I[K], options?: ToolCallOptions) => Promise<K extends keyof O ? O[K] : CompleteResult<unknown>> };
+  /** Return the full MCP result, preserving error results and questions left unanswered. Successful output is contract-validated; the server validates arguments. */
+  readonly callTool: <K extends keyof I & string>(request: CallMetadata & { name: K; arguments: I[K] }, options?: ToolCallOptions) => Promise<ToolResult<K extends keyof O ? O[K] : unknown>>;
 }

package/runtime.d.ts

@@ -1,6 +1,6 @@
-import type { AuthProvider, CallOptions, ClientCapabilities, ElicitHandler, ToolClient } from "./protocol.js";
+import type { AuthProvider, CallOptions, ToolClient } from "./protocol.js";
 export { ToolCallError } from "./protocol.js";
-export type { AuthProvider, CallOptions, CallMetadata, ClientCapabilities, ElicitHandler, ToolResult, ToolClient } from "./protocol.js";
+export type { AuthProvider, CallOptions, CallMetadata, ElicitHandler, ToolCallOptions, ToolResult, ToolClient } from "./protocol.js";
 
 /** Connection settings for an MCP endpoint. */
 export interface Binding {
@@ -14,10 +14,6 @@ export interface Binding {
   installationUID?: string;
   /** Close the session after every call instead of keeping one connection open. */
   scoped?: boolean;
-  /** Client capabilities declared to the server. On protocol 2026-07-28 every request carries them in `_meta["io.modelcontextprotocol/clientCapabilities"]` ([spec](https://modelcontextprotocol.io/specification/2026-07-28/client/elicitation#capabilities)); declare `{ elicitation: { form: {} } }` to receive form elicitations in input-required results, or set `elicit` to answer them. */
-  capabilities?: ClientCapabilities;
-  /** Answers elicitations in place, so `tools.x` and `callTool` return the completed result. Declares `{ elicitation: { form: {} } }` unless `capabilities` sets `elicitation`. */
-  elicit?: ElicitHandler;
 }
 /** Alias for an endpoint binding. */
 export type EndpointBinding = Binding;
@@ -45,9 +41,7 @@ export interface CreateOptions<B = Binding> {
   /** 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. */
+/** 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 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,32 +1,37 @@
-import { Client, MissingRequiredClientCapabilityError, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+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;
-}
+// Environment-bound calls reuse the last server/discover result for the same endpoint and token instead of discovering
+// the server on every call.
+const DISCOVERY = Symbol("discovery");
+const discovered = new Map();
 
 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.`);
+  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 json(text) {
+  try { return JSON.parse(text); } catch { return undefined; }
 }
 
 export class ToolCallError extends Error {
   constructor(app, tool, result) {
-    const detail = result.content?.find(part => part.type === "text")?.text;
-    const message = result.resultType === "input_required" ? "additional input required"
-      : detail ? `tool failed: ${detail}` : "tool failed";
-    super(`${app}.${tool}: ${message}`);
+    const asking = result.resultType === "input_required";
+    const text = result.content?.filter(part => part.type === "text").map(part => part.text).join("\n") || undefined;
+    const detail = asking
+      ? Object.values(result.inputRequests ?? {}).flatMap(({ params }) => [params?.message, params?.url]).filter(Boolean).join(" ")
+      : text;
+    super(`${app}.${tool}: ${asking ? "additional input required" : "tool failed"}${detail ? `: ${detail}` : ""}`);
     this.name = "ToolCallError";
     this.result = result;
+    this.text = text;
+    this.data = result.structuredContent ?? json(text);
   }
 }
 
@@ -43,6 +48,14 @@ function untilAborted(promise, signal) {
   });
 }
 
+// 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) {
+  return options?.timeout === undefined
+    ? { ...options, timeout: 2 ** 31 - 1 }
+    : { onprogress: () => {}, resetTimeoutOnProgress: true, ...options };
+}
+
 function delay(milliseconds, signal) {
   return new Promise(resolve => {
     const timer = setTimeout(resolve, milliseconds);
@@ -59,7 +72,7 @@ export function bindApps(identity, contracts, 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 { validator = defaultValidator, resolve = 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 };
@@ -68,18 +81,21 @@ export function createApps(identity, contracts, bindings, options) {
     // Without explicit bindings, the resolve hook supplies the binding on every call.
     const current = () => binding ?? (bindings ? undefined : resolve(name));
     let connection;
-    const connect = resolved => {
+    const connect = (resolved, discover) => {
+      // 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 capabilities = resolved.elicit ? { elicitation: { form: {} }, ...resolved.capabilities } : resolved.capabilities;
-      const client = new Client({ name: identity.name, version: identity.version }, { capabilities, versionNegotiation: { mode: "auto" } });
-      if (resolved.elicit) client.setRequestHandler("elicitation/create", resolved.elicit);
-      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 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: async (input, init) => {
+        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 } : {} } });
       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 => {
+      current.ready = client.connect(transport, discover && { prior: { kind: "modern", discover } }).catch(async error => {
         await transport.close();
         throw error;
       });
@@ -97,41 +113,47 @@ export function createApps(identity, contracts, bindings, options) {
       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));
+      const key = resolved[DISCOVERY];
+      const prior = discovered.get(key);
+      const active = scoped ? connect(resolved, prior) : (connection ??= connect(resolved));
       try {
         await untilAborted(active.ready, options?.signal);
-        return await run(active.client, resolved);
+        if (key) discovered.set(key, active.client.getDiscoverResult());
+        return await run(active.client);
+      } catch (error) {
+        // A server that no longer speaks the discovered protocol rejects the first request without running it.
+        if (!prior || active.answered || error?.status !== 400) throw error;
+        discovered.delete(key);
+        return session(options, run);
       } 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, options) => {
+    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}`);
-      }
-      // With a handler the MCP client answers input requests and retries; without one the caller gets the question.
-      const result = await session(options, (client, resolved) => client.callTool(request, {
-        ...options, allowInputRequired: !resolved?.elicit,
-        ...(tool && { toolDefinition: { ...tool.definition, outputSchema: undefined } }),
-      })).catch(error => {
-        if (error instanceof MissingRequiredClientCapabilityError) error.message = `${name}.${request.name}: ${error.message}. Set elicit or capabilities on the binding.`;
-        throw error;
+      const result = await session(options, async client => {
+        const send = request => client.callTool(request, {
+          ...patient(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}`);
+      // 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}`);
       }
       return { ...result, resultType: "complete" };
     };
-    const listTools = options => session(options, client => client.listTools(undefined, options));
+    const listTools = options => session(options, client => client.listTools(undefined, patient(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);
@@ -148,7 +170,7 @@ export function createApps(identity, contracts, bindings, options) {
         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 read = async options => parse(await session(options, client => client.readResource({ uri: resource.uri }, patient(options))));
       const watch = async (onChange, { signal } = {}) => {
         const resolved = current();
         if (!resolved?.endpoint) throw new Error(`Watching ${name} ${resource.uri} requires an endpoint binding.`);
@@ -160,7 +182,7 @@ export function createApps(identity, contracts, bindings, options) {
             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" }))))
+            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 });

package/validate.mjs

@@ -1,10 +1,12 @@
-import Ajv from "ajv";
-import { Ajv2020 } from "ajv/dist/2020.js";
-import addFormats from "ajv-formats";
+import { AjvJsonSchemaValidator } from "@modelcontextprotocol/client/validators/ajv";
 
+// The MCP client's own Ajv, one engine per schema so contracts that reuse an $id stay apart.
 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);
+  const validate = new AjvJsonSchemaValidator().getValidator(schema);
+  const check = value => {
+    const { valid, errorMessage } = validate(value);
+    check.errors = errorMessage;
+    return valid;
+  };
+  return check;
 }

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/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 {};

package/view.js

@@ -1,30 +0,0 @@
-import { readFile } from "node:fs/promises";
-/** MIME type of an MCP App HTML resource. */
-export const VIEW_MIME_TYPE = "text/html;profile=mcp-app";
-/**
- * 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 function appView(name, uri, file, options = {}) {
-    const csp = { connectDomains: [], resourceDomains: [], ...options.csp };
-    const page = readFile(file, "utf8");
-    page.catch(() => { });
-    return [
-        name,
-        uri,
-        { mimeType: VIEW_MIME_TYPE, _meta: { ui: { csp } } },
-        async () => ({
-            ttlMs: 0,
-            cacheScope: "private",
-            contents: [{ uri, mimeType: VIEW_MIME_TYPE, text: await page }],
-        }),
-    ];
-}