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

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.
@@ -65,7 +65,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,20 +78,15 @@ 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>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "holon-sh",
-  "version": "0.0.1-dev.5",
+  "version": "0.0.1-dev.6",
   "description": "Typed MCP clients and app view resources for Node.js.",
   "repository": {
     "type": "git",

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. */
 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,7 +23,7 @@ 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. Inspect the original result; 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" }>;
   constructor(app: string, tool: string, result: ToolCallError["result"]);
@@ -40,8 +40,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 result 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. Arguments and successful output are contract-validated. */
+  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;

package/runtime.mjs

@@ -1,4 +1,4 @@
-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.
@@ -21,10 +21,11 @@ function environment(identity, name) {
 
 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 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;
   }
@@ -69,10 +70,9 @@ export function createApps(identity, contracts, bindings, options) {
     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 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 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();
@@ -100,12 +100,12 @@ export function createApps(identity, contracts, bindings, options) {
       const active = scoped ? connect(resolved) : (connection ??= connect(resolved));
       try {
         await untilAborted(active.ready, options?.signal);
-        return await run(active.client, resolved);
+        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, 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;
@@ -117,13 +117,19 @@ export function createApps(identity, contracts, bindings, options) {
         };
         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, {
+          ...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) {