toolnexus 0.5.0 → 0.7.0

package/README.md

@@ -61,6 +61,41 @@ console.log(text)
 await tk.close()               // disconnect MCP servers
 ```
 
+## Suspension — login / approval / input (`Pending` / `waitFor`)
+
+Some tools can't finish in one shot: they need an **out-of-band, async resolution** — a human
+logs in, approves a trade, types a value. That's one idea, not one feature: *login* is just the
+`kind:"authorization"` case. A tool returns **`Pending(request)`**; the client calls your
+**`waitFor(request) → answer`**, then **retries the tool** with `ctx.answer`, and the model gets
+the real answer. Everything crossing a boundary is plain data, so it works the same across
+processes, agents, and restarts — and identically in all five language ports.
+
+```ts
+import { authRequired } from "toolnexus"
+
+// a tool that needs login the first time:
+defineTool({
+  name: "get_balance", description: "…", inputSchema: { type: "object", properties: {} },
+  run: (_args, ctx) =>
+    authed ? `balance: ₹67,417` : authRequired("https://example.com/login", "Log in to continue"),
+})
+
+// the host supplies ONE function — how the link reaches the human is your call:
+const agent = createClient({
+  baseUrl, style: "openai", model,
+  waitFor: async (request) => {          // interactive: open a browser + poll
+    open(request.url); await pollUntilLoggedIn(); return { id: request.id, ok: true }
+  },
+  // headless desk: waitFor = send request.url to your channel + poll
+  // another agent: waitFor = forward the request over A2A, await its answer
+})
+```
+
+Omit `waitFor` for a **durable** host: `run()` doesn't hang — it returns
+`{ status: "pending", pending: request }`, so you can deliver the link out-of-band (file, HTTP,
+channel) and resume later, even in another process. `stream()` emits a `{ type: "pending", request }`
+event so a channel can push the link in real time. Runnable demo: `examples/pending.ts`.
+
 ## Conversations / memory
 
 `run()` is stateless — each call starts fresh. To keep a thread's history, use `ask()` with an

package/dist/builtin.js

@@ -11,6 +11,7 @@ import { spawn } from "node:child_process";
 import fs from "node:fs/promises";
 import { existsSync, readdirSync } from "node:fs";
 import path from "node:path";
+import { pending } from "./types.js";
 /**
  * Whether the builtin source is on. Default ON. Same precedence as MCP:
  * `disabled:true` wins, else `enabled:false` disables, otherwise enabled.
@@ -388,8 +389,25 @@ function webfetchTool() {
         }
     });
 }
+/**
+ * Render the questions into a human-readable `Request.prompt` (§10). Byte-identical across ports:
+ * each question's text in order, `" (options: a, b, c)"` appended when it has non-empty options,
+ * joined by "\n" (no trailing newline). `header` is not rendered — it survives in `data.questions`.
+ */
+function renderQuestionPrompt(questions) {
+    return questions
+        .map((q) => {
+        const item = q;
+        let line = typeof item?.question === "string" ? item.question : "";
+        const opts = Array.isArray(item?.options) ? item.options : [];
+        if (opts.length > 0)
+            line += ` (options: ${opts.join(", ")})`;
+        return line;
+    })
+        .join("\n");
+}
 function questionTool() {
-    return builtin("question", "Ask the host one or more questions. Returns the questions as structured output for the host to answer.", {
+    return builtin("question", "Ask the host one or more questions. Suspends via a kind:\"question\" Request (§10); the host's waitFor resolves it and the answer is returned to the model.", {
         type: "object",
         properties: {
             questions: {
@@ -409,9 +427,14 @@ function questionTool() {
         },
         required: ["questions"],
         additionalProperties: false,
-    }, async (args) => {
+    }, async (args, ctx) => {
         const questions = Array.isArray(args.questions) ? args.questions : [];
-        return ok(JSON.stringify(questions), { questions });
+        // Re-executed after the host's waitFor resolved (§10 loop rule): the resolution IS the
+        // answer, as with kind:"input" — forward it verbatim to the model.
+        if (ctx?.answer)
+            return ok(JSON.stringify(ctx.answer.data ?? {}));
+        // First call: suspend. A question is just a §10 Request with kind:"question".
+        return pending({ kind: "question", prompt: renderQuestionPrompt(questions), data: { questions } });
     });
 }
 function todowriteTool() {

package/dist/client.d.ts

@@ -4,7 +4,7 @@
  * Toolkit. See ../../SPEC.md §8.
  */
 import type { Toolkit } from "./toolkit.js";
-import type { ToolResult } from "./types.js";
+import type { ToolResult, Request, Answer } from "./types.js";
 export type ClientStyle = "openai" | "anthropic";
 export interface ClientOptions {
     baseUrl: string;
@@ -27,6 +27,11 @@ export interface ClientOptions {
     /** Observability sink — receives semantic metric events ({event:"llm"|"tool"|"run"…}) as the
      * loop runs (§8 Observability). Forward to statsd/logs/OTel/anything. No cost when unset. */
     onMetric?: (ev: MetricEvent) => void;
+    /** §10 Suspension resolver. When a tool returns Pending (metadata.pending), the client calls
+     * this, then retries the tool with Context.answer = the resolution. Its interior is unconstrained
+     * (open a browser, message a channel, watch a file, forward to another agent). Omit for a durable
+     * host: run() does not hang — it returns { status:"pending", pending:request } to resume later. */
+    waitFor?: (request: Request) => Promise<Answer>;
 }
 /**
  * Semantic observability events (§8). NOT counter/histogram primitives — readable records the
@@ -46,6 +51,7 @@ export type MetricEvent = {
     source: string;
     isError: boolean;
     ms: number;
+    pending?: boolean;
 } | {
     event: "run";
     model: string;
@@ -148,6 +154,10 @@ export interface RunResult {
     usage: Usage;
     /** The model used. */
     model: string;
+    /** "done" normally; "pending" iff a tool suspended and no waitFor was configured (§10). */
+    status: "done" | "pending";
+    /** The unresolved suspension — present iff status === "pending" (§10). */
+    pending?: Request;
 }
 /** Events yielded by client.stream(). */
 export type StreamEvent = {
@@ -167,6 +177,9 @@ export type StreamEvent = {
 } | {
     type: "usage";
     usage: Usage;
+} | {
+    type: "pending";
+    request: Request;
 } | {
     type: "done";
     result: RunResult;
@@ -225,10 +238,20 @@ export declare class Client {
     private llmFetch;
     /** Run one tool through beforeTool/afterTool hooks (mutate args, short-circuit, transform result). */
     private runTool;
+    /** Emit the `tool` metric, classifying a §10 suspension as `pending` (isError:false), not a failure. */
+    private emitTool;
     /** One non-streaming LLM call, with an `llm` metric event (ok/error + per-call tokens + ms). */
     private llmCallJson;
     private runOpenAI;
     private result;
+    /** §10: a run halted because a tool suspended and no `waitFor` was configured. */
+    private pendingRun;
+    /**
+     * §10: resolve a suspended tool result. Calls `waitFor(request)`, and on `ok` re-executes the
+     * tool once with `Context.answer = answer`. Returns the resolved result, or `{ halted }` when
+     * no `waitFor` is configured (the run should stop and surface the request).
+     */
+    private resolvePending;
     private runAnthropic;
     private streamOpenAI;
     private streamAnthropic;

package/dist/client.js

@@ -1,3 +1,4 @@
+import { pendingOf } from "./types.js";
 /** Default conversation provider — keeps transcripts in memory for the client's lifetime. */
 export class InMemoryConversationStore {
     map = new Map();
@@ -97,7 +98,7 @@ class MetricsRegistry {
             observe(this.llmDuration, labelStr([["model", ev.model]]), ev.ms / 1000);
         }
         else if (ev.event === "tool") {
-            inc(this.toolCalls, labelStr([["tool", ev.tool], ["source", ev.source], ["is_error", String(ev.isError)]]));
+            inc(this.toolCalls, labelStr([["tool", ev.tool], ["source", ev.source], ["is_error", String(ev.isError)], ["pending", String(ev.pending ?? false)]]));
             observe(this.toolDuration, labelStr([["tool", ev.tool]]), ev.ms / 1000);
         }
         else if (ev.event === "run") {
@@ -269,22 +270,31 @@ export class Client {
         if (h?.beforeTool) {
             const ov = await h.beforeTool({ name, args: a, id, turn });
             if (ov?.result) {
-                // short-circuit (deny/cache/dry-run) — still a tool call for metrics purposes
-                this.emit({ event: "tool", tool: name, source, isError: ov.result.isError, ms: Date.now() - t0 });
+                // short-circuit (deny/cache/dry-run, or a guard-raised suspension — path B); still a tool
+                // call for metrics, but a suspension is classified pending, never an error.
+                this.emitTool(name, source, ov.result, t0);
                 return { args: a, result: ov.result };
             }
             if (ov?.args)
                 a = ov.args;
         }
         let result = await toolkit.execute(name, a);
-        if (h?.afterTool) {
+        // A suspension (§10) is not a real result: skip afterTool's failure path on it — the resolved
+        // result (post-waitFor) still flows through afterTool in resolvePending — and never count it as
+        // a tool error.
+        if (h?.afterTool && !pendingOf(result)) {
             const ov = await h.afterTool({ name, args: a, result, id, turn });
             if (ov?.result)
                 result = ov.result;
         }
-        this.emit({ event: "tool", tool: name, source, isError: result.isError, ms: Date.now() - t0 });
+        this.emitTool(name, source, result, t0);
         return { args: a, result };
     }
+    /** Emit the `tool` metric, classifying a §10 suspension as `pending` (isError:false), not a failure. */
+    emitTool(name, source, result, t0) {
+        const req = pendingOf(result);
+        this.emit({ event: "tool", tool: name, source, isError: req ? false : result.isError, ms: Date.now() - t0, ...(req ? { pending: true } : {}) });
+    }
     /** One non-streaming LLM call, with an `llm` metric event (ok/error + per-call tokens + ms). */
     async llmCallJson(url, init, signal, style) {
         const t0 = Date.now();
@@ -342,12 +352,26 @@ export class Client {
                 if (calls.length === 0)
                     return this.endRun(runStart, msg.content ?? "", messages, toolCalls, turns, usage);
                 // execute all tool calls in this turn concurrently (true parallel tool calling)
-                const results = await Promise.all(calls.map(async (call) => {
-                    const { args, result } = await this.runTool(toolkit, call.function.name, safeJson(call.function.arguments), call.id, turn);
-                    toolCalls.push({ name: call.function.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
-                    return { role: "tool", tool_call_id: call.id, content: result.output };
+                const settled = await Promise.all(calls.map(async (call) => {
+                    let { args, result } = await this.runTool(toolkit, call.function.name, safeJson(call.function.arguments), call.id, turn);
+                    let halted;
+                    const req = pendingOf(result);
+                    if (req) {
+                        const r = await this.resolvePending(toolkit, call.function.name, args, req, call.id, turn);
+                        result = r.result;
+                        halted = r.halted;
+                    }
+                    return { call, args, result, halted };
                 }));
-                messages.push(...results);
+                // Record in tool-call order; on the FIRST durable halt, surface it and stop — deterministic,
+                // and the later suspensions' placeholder results never enter the transcript (they re-suspend
+                // on resume). Mirrors the streaming path.
+                for (const s of settled) {
+                    toolCalls.push({ name: s.call.function.name, args: s.args, output: s.result.output, isError: s.result.isError, metadata: s.result.metadata });
+                    messages.push({ role: "tool", tool_call_id: s.call.id, content: s.result.output });
+                    if (s.halted)
+                        return this.pendingRun(runStart, s.halted, messages, toolCalls, turns, usage);
+                }
             }
             return this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage);
         }
@@ -357,7 +381,35 @@ export class Client {
         }
     }
     result(text, messages, toolCalls, turns, usage) {
-        return { text, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model };
+        return { text, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model, status: "done" };
+    }
+    /** §10: a run halted because a tool suspended and no `waitFor` was configured. */
+    pendingRun(runStart, request, messages, toolCalls, turns, usage) {
+        this.emit({ event: "run", model: this.opts.model, turns, toolCalls: toolCalls.length, totalTokens: usage.totalTokens, ms: Date.now() - runStart });
+        return { text: request.prompt, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model, status: "pending", pending: request };
+    }
+    /**
+     * §10: resolve a suspended tool result. Calls `waitFor(request)`, and on `ok` re-executes the
+     * tool once with `Context.answer = answer`. Returns the resolved result, or `{ halted }` when
+     * no `waitFor` is configured (the run should stop and surface the request).
+     */
+    async resolvePending(toolkit, name, args, request, id, turn) {
+        if (!this.opts.waitFor)
+            return { result: { output: request.prompt, isError: true }, halted: request };
+        const answer = await this.opts.waitFor(request);
+        if (!answer?.ok)
+            return { result: { output: `declined/expired: ${request.prompt}`, isError: true } };
+        const t0 = Date.now();
+        let result = await toolkit.execute(name, args, { answer });
+        if (this.opts.hooks?.afterTool) {
+            const ov = await this.opts.hooks.afterTool({ name, args, result, id, turn });
+            if (ov?.result)
+                result = ov.result;
+        }
+        this.emitTool(name, toolkit.get(name)?.source ?? "custom", result, t0);
+        if (pendingOf(result))
+            result = { output: `unresolved: ${request.prompt}`, isError: true }; // never loop forever
+        return { result };
     }
     // ---- Anthropic-style: POST {baseUrl}/messages ----
     async runAnthropic(prompt, toolkit, external, history) {
@@ -402,12 +454,33 @@ export class Client {
                     return this.endRun(runStart, text, messages, toolCalls, turns, usage);
                 }
                 // execute all tool_use blocks in this turn concurrently (true parallel tool calling)
-                const results = await Promise.all(uses.map(async (use) => {
-                    const { args, result } = await this.runTool(toolkit, use.name, use.input ?? {}, use.id, turn);
-                    toolCalls.push({ name: use.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
-                    return { type: "tool_result", tool_use_id: use.id, content: result.output, is_error: result.isError };
+                const settled = await Promise.all(uses.map(async (use) => {
+                    let { args, result } = await this.runTool(toolkit, use.name, use.input ?? {}, use.id, turn);
+                    let halted;
+                    const req = pendingOf(result);
+                    if (req) {
+                        const r = await this.resolvePending(toolkit, use.name, args, req, use.id, turn);
+                        result = r.result;
+                        halted = r.halted;
+                    }
+                    return { use, args, result, halted };
                 }));
-                messages.push({ role: "user", content: results });
+                // Record in tool-call order; on the FIRST durable halt, include that tool_result block, stop
+                // building the content, and surface it — deterministic (G3), later suspensions re-suspend on
+                // resume. Mirrors the OpenAI path and the streaming loops.
+                const content = [];
+                let halted;
+                for (const s of settled) {
+                    toolCalls.push({ name: s.use.name, args: s.args, output: s.result.output, isError: s.result.isError, metadata: s.result.metadata });
+                    content.push({ type: "tool_result", tool_use_id: s.use.id, content: s.result.output, is_error: s.result.isError });
+                    if (s.halted) {
+                        halted = s.halted;
+                        break;
+                    }
+                }
+                messages.push({ role: "user", content });
+                if (halted)
+                    return this.pendingRun(runStart, halted, messages, toolCalls, turns, usage);
             }
             return this.endRun(runStart, "", messages, toolCalls, turns, usage);
         }
@@ -500,7 +573,20 @@ export class Client {
                     yield { type: "tool_call", id: c.id, name: c.name, args: safeJson(c.args) };
                 const settled = await Promise.all(calls.map((c) => this.runTool(toolkit, c.name, safeJson(c.args), c.id, turn)));
                 for (let i = 0; i < calls.length; i++) {
-                    const c = calls[i], { args, result } = settled[i];
+                    const c = calls[i];
+                    let { args, result } = settled[i];
+                    const req = pendingOf(result);
+                    if (req) {
+                        yield { type: "pending", request: req }; // surface BEFORE waitFor so a channel can push the link
+                        const r = await this.resolvePending(toolkit, c.name, args, req, c.id, turn);
+                        result = r.result;
+                        if (r.halted) {
+                            toolCalls.push({ name: c.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
+                            messages.push({ role: "tool", tool_call_id: c.id, content: result.output });
+                            yield { type: "done", result: this.pendingRun(runStart, r.halted, messages, toolCalls, turns, usage) };
+                            return;
+                        }
+                    }
                     toolCalls.push({ name: c.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
                     messages.push({ role: "tool", tool_call_id: c.id, content: result.output });
                     yield { type: "tool_result", id: c.id, name: c.name, output: result.output, isError: result.isError };
@@ -594,7 +680,21 @@ export class Client {
                 const settled = await Promise.all(uses.map((u) => this.runTool(toolkit, u.name, u.input ?? {}, u.id, turn)));
                 const results = [];
                 for (let i = 0; i < uses.length; i++) {
-                    const u = uses[i], { args, result } = settled[i];
+                    const u = uses[i];
+                    let { args, result } = settled[i];
+                    const req = pendingOf(result);
+                    if (req) {
+                        yield { type: "pending", request: req };
+                        const r = await this.resolvePending(toolkit, u.name, args, req, u.id, turn);
+                        result = r.result;
+                        if (r.halted) {
+                            toolCalls.push({ name: u.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
+                            results.push({ type: "tool_result", tool_use_id: u.id, content: result.output, is_error: result.isError });
+                            messages.push({ role: "user", content: results });
+                            yield { type: "done", result: this.pendingRun(runStart, r.halted, messages, toolCalls, turns, usage) };
+                            return;
+                        }
+                    }
                     toolCalls.push({ name: u.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
                     results.push({ type: "tool_result", tool_use_id: u.id, content: result.output, is_error: result.isError });
                     yield { type: "tool_result", id: u.id, name: u.name, output: result.output, isError: result.isError };

package/dist/mcp.d.ts

@@ -1,4 +1,9 @@
-import { type Tool, type McpStatus } from "./types.js";
+import type { ElicitRequest, ElicitResult } from "@modelcontextprotocol/sdk/types.js";
+import { type Tool, type McpStatus, type Request, type Answer } from "./types.js";
+/** Map an MCP `elicitation/create` request onto a §10 `Request`. */
+export declare function elicitationToRequest(params: ElicitRequest["params"]): Request;
+/** Map a resolved §10 `Answer` back onto an MCP `ElicitResult`. ok→accept; declined→decline; else→cancel. */
+export declare function answerToElicitResult(answer: Answer): ElicitResult;
 export interface LocalServer {
     type?: "local";
     command: string[];
@@ -32,4 +37,6 @@ export interface McpSource {
     close(): Promise<void>;
 }
 /** Connect to every enabled server, list + convert tools. Failures are isolated. */
-export declare function loadMcp(input: string | object): Promise<McpSource>;
+export declare function loadMcp(input: string | object, opts?: {
+    waitFor?: (request: Request) => Promise<Answer>;
+}): Promise<McpSource>;

package/dist/mcp.js

@@ -8,7 +8,35 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { ElicitRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { sanitize } from "./types.js";
+// ---------------------------------------------------------------------------
+// MCP elicitation bridge (§10). A server can ask US for input mid-`tools/call`
+// (a reverse-request). We map it onto the one `waitFor`: form mode → kind:"input",
+// URL mode → kind:"authorization". The two mappings are pure + byte-parity-tested.
+// ---------------------------------------------------------------------------
+let _elcSeq = 0;
+/** Map an MCP `elicitation/create` request onto a §10 `Request`. */
+export function elicitationToRequest(params) {
+    const p = params;
+    const isUrl = p.mode === "url";
+    const req = {
+        id: `elc-${Date.now().toString(36)}-${++_elcSeq}`,
+        kind: isUrl ? "authorization" : "input",
+        prompt: String(p.message ?? ""),
+    };
+    if (isUrl && p.url)
+        req.url = p.url;
+    if (!isUrl && p.requestedSchema)
+        req.data = { schema: p.requestedSchema };
+    return req;
+}
+/** Map a resolved §10 `Answer` back onto an MCP `ElicitResult`. ok→accept; declined→decline; else→cancel. */
+export function answerToElicitResult(answer) {
+    if (answer.ok)
+        return { action: "accept", content: (answer.data ?? {}) };
+    return { action: answer.reason === "declined" ? "decline" : "cancel" };
+}
 const DEFAULT_TIMEOUT = 30_000;
 const MAX_LIST_PAGES = 1_000;
 function isRemote(cfg) {
@@ -117,18 +145,24 @@ function convertTool(server, def, client, timeout) {
     };
 }
 /** Connect to every enabled server, list + convert tools. Failures are isolated. */
-export async function loadMcp(input) {
+export async function loadMcp(input, opts) {
     const config = parseMcpConfig(input);
     const tools = [];
     const status = {};
     const clients = [];
+    const waitFor = opts?.waitFor;
     await Promise.all(Object.entries(config).map(async ([name, cfg]) => {
         if (!isEnabled(cfg)) {
             status[name] = "disabled";
             return;
         }
         const timeout = cfg.timeout ?? DEFAULT_TIMEOUT;
-        const client = new Client({ name: "toolnexus", version: "0.1.0" }, { capabilities: {} });
+        // Advertise elicitation + register the bridge ONLY when a waitFor exists to satisfy it —
+        // a waitFor-less host degrades cleanly (the server won't elicit). (§10 elicitation bridge)
+        const client = new Client({ name: "toolnexus", version: "0.1.0" }, { capabilities: waitFor ? { elicitation: {} } : {} });
+        if (waitFor) {
+            client.setRequestHandler(ElicitRequestSchema, async (request) => answerToElicitResult(await waitFor(elicitationToRequest(request.params))));
+        }
         try {
             if (isRemote(cfg)) {
                 const url = new URL(cfg.url);

package/dist/serve.js

@@ -239,12 +239,23 @@ async function fulfil(id, text, store, runTask, onTask, contextId) {
         // contextId groups a peer's turns into one conversation — thread it so the
         // client's ConversationStore remembers across tasks in the same context.
         result = await runTask(text, contextId);
-        const artifact = {
-            artifactId: randomUUID(),
-            parts: [{ kind: "text", text: result.text }],
-        };
-        task = { id, status: { state: "completed" }, artifacts: [artifact] };
-        state = "completed";
+        if (result.status === "pending" && result.pending) {
+            // §10 suspension over A2A: the run halted waiting on out-of-band input. Surface the
+            // protocol's `input-required` state carrying the request prompt — never a false `completed`.
+            task = {
+                id,
+                status: { state: "input-required", message: { role: "agent", parts: [{ kind: "text", text: result.pending.prompt }] } },
+            };
+            state = "input-required";
+        }
+        else {
+            const artifact = {
+                artifactId: randomUUID(),
+                parts: [{ kind: "text", text: result.text }],
+            };
+            task = { id, status: { state: "completed" }, artifacts: [artifact] };
+            state = "completed";
+        }
     }
     catch (e) {
         const detail = e instanceof Error ? e.message : String(e);

package/dist/toolkit.d.ts

@@ -16,6 +16,13 @@ export interface ToolkitOptions {
     builtins?: BuiltinsConfig;
     /** Remote A2A agents — each advertised skill becomes a tool (source:"a2a"). */
     agents?: Agent[];
+    /**
+     * Host resolver for out-of-band input (§10). When set, connected MCP servers may elicit input
+     * from the human mid-`tools/call` and it is bridged onto this `waitFor` (form→kind:"input",
+     * URL→kind:"authorization"). Typically the same function passed to the client. Omit ⇒ MCP
+     * elicitation is not advertised.
+     */
+    waitFor?: (request: import("./types.js").Request) => Promise<import("./types.js").Answer>;
 }
 export declare class Toolkit {
     private readonly mcp;

package/dist/toolkit.js

@@ -34,7 +34,7 @@ export class Toolkit {
         }
     }
     static async create(opts) {
-        const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig) : undefined;
+        const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig, { waitFor: opts.waitFor }) : undefined;
         const skill = opts.skillsDir !== undefined ? loadSkills(opts.skillsDir) : undefined;
         // The toggle comes from the `builtins` option, or a top-level `builtins`
         // key on a parsed config object — same precedence as MCP's isEnabled.

package/dist/types.d.ts

@@ -17,7 +17,41 @@ export interface ToolResult {
 export interface ToolContext {
     signal?: AbortSignal;
     timeout?: number;
+    /** Present ONLY on a post-waitFor retry (§10): the resolution of a prior suspension. */
+    answer?: Answer;
 }
+/**
+ * §10 Suspension. A tool that needs an out-of-band, async resolution (login, approval,
+ * input) returns a normal ToolResult carrying `metadata.pending = Request`. Byte-identical
+ * wire data — it crosses languages, processes, and agents unchanged.
+ */
+export interface Request {
+    id: string;
+    kind: string;
+    prompt: string;
+    url?: string;
+    data?: Record<string, unknown>;
+    expiresAt?: string;
+}
+export interface Answer {
+    id: string;
+    ok: boolean;
+    data?: Record<string, unknown>;
+    /**
+     * When `ok` is false, why (advisory — the loop rule branches only on `ok`). Distinguishes an
+     * explicit refusal from a dismissal/timeout; the MCP elicitation bridge maps `declined`→`decline`
+     * and everything else→`cancel`. (R1)
+     */
+    reason?: "declined" | "cancelled" | "expired";
+}
+/** Producer helper: return a suspension. A ToolResult with `metadata.pending` = a Request. */
+export declare function pending(request: Omit<Request, "id"> & {
+    id?: string;
+}): ToolResult;
+/** Sugar for the common case: `kind:"authorization"` at a login URL. */
+export declare function authRequired(url: string, prompt?: string): ToolResult;
+/** Read the suspension off a result, if any. */
+export declare function pendingOf(result: ToolResult): Request | undefined;
 export interface Tool {
     name: string;
     description: string;

package/dist/types.js

@@ -1,5 +1,24 @@
 /**
  * Shared contract types. See ../../SPEC.md.
  */
+let _pendingSeq = 0;
+/** Producer helper: return a suspension. A ToolResult with `metadata.pending` = a Request. */
+export function pending(request) {
+    const id = request.id ?? `pnd-${Date.now().toString(36)}-${++_pendingSeq}`;
+    const req = { ...request, id };
+    return {
+        output: req.prompt + (req.url ? `\n${req.url}` : ""),
+        isError: true,
+        metadata: { pending: req },
+    };
+}
+/** Sugar for the common case: `kind:"authorization"` at a login URL. */
+export function authRequired(url, prompt = "Authorization required to continue") {
+    return pending({ kind: "authorization", prompt, url });
+}
+/** Read the suspension off a result, if any. */
+export function pendingOf(result) {
+    return result.metadata?.pending;
+}
 /** Replace anything outside [a-zA-Z0-9_-] with "_" (same as opencode). */
 export const sanitize = (value) => value.replace(/[^a-zA-Z0-9_-]/g, "_");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",

package/src/builtin.ts

@@ -12,6 +12,7 @@ import fs from "node:fs/promises"
 import { existsSync, readdirSync } from "node:fs"
 import path from "node:path"
 import type { JSONSchema, Tool, ToolContext, ToolResult } from "./types.js"
+import { pending } from "./types.js"
 
 /** Config for the single global builtin toggle (mirrors MCP isEnabled precedence). */
 export type BuiltinsConfig =
@@ -412,10 +413,27 @@ function webfetchTool(): Tool {
   )
 }
 
+/**
+ * Render the questions into a human-readable `Request.prompt` (§10). Byte-identical across ports:
+ * each question's text in order, `" (options: a, b, c)"` appended when it has non-empty options,
+ * joined by "\n" (no trailing newline). `header` is not rendered — it survives in `data.questions`.
+ */
+function renderQuestionPrompt(questions: unknown[]): string {
+  return questions
+    .map((q) => {
+      const item = q as { question?: unknown; options?: unknown }
+      let line = typeof item?.question === "string" ? item.question : ""
+      const opts = Array.isArray(item?.options) ? item.options : []
+      if (opts.length > 0) line += ` (options: ${opts.join(", ")})`
+      return line
+    })
+    .join("\n")
+}
+
 function questionTool(): Tool {
   return builtin(
     "question",
-    "Ask the host one or more questions. Returns the questions as structured output for the host to answer.",
+    "Ask the host one or more questions. Suspends via a kind:\"question\" Request (§10); the host's waitFor resolves it and the answer is returned to the model.",
     {
       type: "object",
       properties: {
@@ -437,9 +455,13 @@ function questionTool(): Tool {
       required: ["questions"],
       additionalProperties: false,
     },
-    async (args) => {
+    async (args, ctx) => {
       const questions = Array.isArray(args.questions) ? args.questions : []
-      return ok(JSON.stringify(questions), { questions })
+      // Re-executed after the host's waitFor resolved (§10 loop rule): the resolution IS the
+      // answer, as with kind:"input" — forward it verbatim to the model.
+      if (ctx?.answer) return ok(JSON.stringify(ctx.answer.data ?? {}))
+      // First call: suspend. A question is just a §10 Request with kind:"question".
+      return pending({ kind: "question", prompt: renderQuestionPrompt(questions), data: { questions } })
     },
   )
 }

package/src/client.ts

@@ -4,7 +4,8 @@
  * Toolkit. See ../../SPEC.md §8.
  */
 import type { Toolkit } from "./toolkit.js"
-import type { ToolResult } from "./types.js"
+import type { ToolResult, Request, Answer } from "./types.js"
+import { pendingOf } from "./types.js"
 
 export type ClientStyle = "openai" | "anthropic"
 
@@ -29,6 +30,11 @@ export interface ClientOptions {
   /** Observability sink — receives semantic metric events ({event:"llm"|"tool"|"run"…}) as the
    * loop runs (§8 Observability). Forward to statsd/logs/OTel/anything. No cost when unset. */
   onMetric?: (ev: MetricEvent) => void
+  /** §10 Suspension resolver. When a tool returns Pending (metadata.pending), the client calls
+   * this, then retries the tool with Context.answer = the resolution. Its interior is unconstrained
+   * (open a browser, message a channel, watch a file, forward to another agent). Omit for a durable
+   * host: run() does not hang — it returns { status:"pending", pending:request } to resume later. */
+  waitFor?: (request: Request) => Promise<Answer>
 }
 
 /**
@@ -38,7 +44,7 @@ export interface ClientOptions {
  */
 export type MetricEvent =
   | { event: "llm"; model: string; status: "ok" | "error"; ms: number; promptTokens: number; completionTokens: number }
-  | { event: "tool"; tool: string; source: string; isError: boolean; ms: number }
+  | { event: "tool"; tool: string; source: string; isError: boolean; ms: number; pending?: boolean }
   | { event: "run"; model: string; turns: number; toolCalls: number; totalTokens: number; ms: number; error?: string }
 
 /**
@@ -117,6 +123,10 @@ export interface RunResult {
   usage: Usage
   /** The model used. */
   model: string
+  /** "done" normally; "pending" iff a tool suspended and no waitFor was configured (§10). */
+  status: "done" | "pending"
+  /** The unresolved suspension — present iff status === "pending" (§10). */
+  pending?: Request
 }
 
 /** Events yielded by client.stream(). */
@@ -125,6 +135,7 @@ export type StreamEvent =
   | { type: "tool_call"; id: string; name: string; args: Record<string, unknown> }
   | { type: "tool_result"; id: string; name: string; output: string; isError: boolean }
   | { type: "usage"; usage: Usage }
+  | { type: "pending"; request: Request }
   | { type: "done"; result: RunResult }
 
 function addUsage(acc: Usage, raw: any, style: ClientStyle): void {
@@ -216,7 +227,7 @@ class MetricsRegistry {
       }
       observe(this.llmDuration, labelStr([["model", ev.model]]), ev.ms / 1000)
     } else if (ev.event === "tool") {
-      inc(this.toolCalls, labelStr([["tool", ev.tool], ["source", ev.source], ["is_error", String(ev.isError)]]))
+      inc(this.toolCalls, labelStr([["tool", ev.tool], ["source", ev.source], ["is_error", String(ev.isError)], ["pending", String(ev.pending ?? false)]]))
       observe(this.toolDuration, labelStr([["tool", ev.tool]]), ev.ms / 1000)
     } else if (ev.event === "run") {
       if (ev.error) inc(this.runErrors, labelStr([["model", ev.model]]))
@@ -391,21 +402,31 @@ export class Client {
     if (h?.beforeTool) {
       const ov = await h.beforeTool({ name, args: a, id, turn })
       if (ov?.result) {
-        // short-circuit (deny/cache/dry-run) — still a tool call for metrics purposes
-        this.emit({ event: "tool", tool: name, source, isError: ov.result.isError, ms: Date.now() - t0 })
+        // short-circuit (deny/cache/dry-run, or a guard-raised suspension — path B); still a tool
+        // call for metrics, but a suspension is classified pending, never an error.
+        this.emitTool(name, source, ov.result, t0)
         return { args: a, result: ov.result }
       }
       if (ov?.args) a = ov.args
     }
     let result = await toolkit.execute(name, a)
-    if (h?.afterTool) {
+    // A suspension (§10) is not a real result: skip afterTool's failure path on it — the resolved
+    // result (post-waitFor) still flows through afterTool in resolvePending — and never count it as
+    // a tool error.
+    if (h?.afterTool && !pendingOf(result)) {
       const ov = await h.afterTool({ name, args: a, result, id, turn })
       if (ov?.result) result = ov.result
     }
-    this.emit({ event: "tool", tool: name, source, isError: result.isError, ms: Date.now() - t0 })
+    this.emitTool(name, source, result, t0)
     return { args: a, result }
   }
 
+  /** Emit the `tool` metric, classifying a §10 suspension as `pending` (isError:false), not a failure. */
+  private emitTool(name: string, source: string, result: ToolResult, t0: number) {
+    const req = pendingOf(result)
+    this.emit({ event: "tool", tool: name, source, isError: req ? false : result.isError, ms: Date.now() - t0, ...(req ? { pending: true } : {}) })
+  }
+
   /** One non-streaming LLM call, with an `llm` metric event (ok/error + per-call tokens + ms). */
   private async llmCallJson(url: string, init: RequestInit, signal: AbortSignal, style: ClientStyle): Promise<any> {
     const t0 = Date.now()
@@ -458,14 +479,27 @@ export class Client {
         const calls = msg.tool_calls ?? []
         if (calls.length === 0) return this.endRun(runStart, msg.content ?? "", messages, toolCalls, turns, usage)
         // execute all tool calls in this turn concurrently (true parallel tool calling)
-        const results = await Promise.all(
+        const settled = await Promise.all(
           calls.map(async (call: any) => {
-            const { args, result } = await this.runTool(toolkit, call.function.name, safeJson(call.function.arguments), call.id, turn)
-            toolCalls.push({ name: call.function.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
-            return { role: "tool", tool_call_id: call.id, content: result.output }
+            let { args, result } = await this.runTool(toolkit, call.function.name, safeJson(call.function.arguments), call.id, turn)
+            let halted: Request | undefined
+            const req = pendingOf(result)
+            if (req) {
+              const r = await this.resolvePending(toolkit, call.function.name, args, req, call.id, turn)
+              result = r.result
+              halted = r.halted
+            }
+            return { call, args, result, halted }
           }),
         )
-        messages.push(...results)
+        // Record in tool-call order; on the FIRST durable halt, surface it and stop — deterministic,
+        // and the later suspensions' placeholder results never enter the transcript (they re-suspend
+        // on resume). Mirrors the streaming path.
+        for (const s of settled) {
+          toolCalls.push({ name: s.call.function.name, args: s.args, output: s.result.output, isError: s.result.isError, metadata: s.result.metadata })
+          messages.push({ role: "tool", tool_call_id: s.call.id, content: s.result.output })
+          if (s.halted) return this.pendingRun(runStart, s.halted, messages, toolCalls, turns, usage)
+        }
       }
       return this.endRun(runStart, lastText(messages), messages, toolCalls, turns, usage)
     } catch (e) {
@@ -475,7 +509,35 @@ export class Client {
   }
 
   private result(text: string, messages: any[], toolCalls: ToolCallRecord[], turns: number, usage: Usage): RunResult {
-    return { text, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model }
+    return { text, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model, status: "done" }
+  }
+
+  /** §10: a run halted because a tool suspended and no `waitFor` was configured. */
+  private pendingRun(runStart: number, request: Request, messages: any[], toolCalls: ToolCallRecord[], turns: number, usage: Usage): RunResult {
+    this.emit({ event: "run", model: this.opts.model, turns, toolCalls: toolCalls.length, totalTokens: usage.totalTokens, ms: Date.now() - runStart })
+    return { text: request.prompt, messages, toolCalls, toolCallCount: toolCalls.length, turns, usage, model: this.opts.model, status: "pending", pending: request }
+  }
+
+  /**
+   * §10: resolve a suspended tool result. Calls `waitFor(request)`, and on `ok` re-executes the
+   * tool once with `Context.answer = answer`. Returns the resolved result, or `{ halted }` when
+   * no `waitFor` is configured (the run should stop and surface the request).
+   */
+  private async resolvePending(
+    toolkit: Toolkit, name: string, args: Record<string, unknown>, request: Request, id: string | undefined, turn: number,
+  ): Promise<{ result: ToolResult; halted?: Request }> {
+    if (!this.opts.waitFor) return { result: { output: request.prompt, isError: true }, halted: request }
+    const answer = await this.opts.waitFor(request)
+    if (!answer?.ok) return { result: { output: `declined/expired: ${request.prompt}`, isError: true } }
+    const t0 = Date.now()
+    let result = await toolkit.execute(name, args, { answer })
+    if (this.opts.hooks?.afterTool) {
+      const ov = await this.opts.hooks.afterTool({ name, args, result, id, turn })
+      if (ov?.result) result = ov.result
+    }
+    this.emitTool(name, toolkit.get(name)?.source ?? "custom", result, t0)
+    if (pendingOf(result)) result = { output: `unresolved: ${request.prompt}`, isError: true } // never loop forever
+    return { result }
   }
 
   // ---- Anthropic-style: POST {baseUrl}/messages ----
@@ -519,14 +581,31 @@ export class Client {
           return this.endRun(runStart, text, messages, toolCalls, turns, usage)
         }
         // execute all tool_use blocks in this turn concurrently (true parallel tool calling)
-        const results = await Promise.all(
+        const settled = await Promise.all(
           uses.map(async (use: any) => {
-            const { args, result } = await this.runTool(toolkit, use.name, use.input ?? {}, use.id, turn)
-            toolCalls.push({ name: use.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
-            return { type: "tool_result", tool_use_id: use.id, content: result.output, is_error: result.isError }
+            let { args, result } = await this.runTool(toolkit, use.name, use.input ?? {}, use.id, turn)
+            let halted: Request | undefined
+            const req = pendingOf(result)
+            if (req) {
+              const r = await this.resolvePending(toolkit, use.name, args, req, use.id, turn)
+              result = r.result
+              halted = r.halted
+            }
+            return { use, args, result, halted }
           }),
         )
-        messages.push({ role: "user", content: results })
+        // Record in tool-call order; on the FIRST durable halt, include that tool_result block, stop
+        // building the content, and surface it — deterministic (G3), later suspensions re-suspend on
+        // resume. Mirrors the OpenAI path and the streaming loops.
+        const content: any[] = []
+        let halted: Request | undefined
+        for (const s of settled) {
+          toolCalls.push({ name: s.use.name, args: s.args, output: s.result.output, isError: s.result.isError, metadata: s.result.metadata })
+          content.push({ type: "tool_result", tool_use_id: s.use.id, content: s.result.output, is_error: s.result.isError })
+          if (s.halted) { halted = s.halted; break }
+        }
+        messages.push({ role: "user", content })
+        if (halted) return this.pendingRun(runStart, halted, messages, toolCalls, turns, usage)
       }
       return this.endRun(runStart, "", messages, toolCalls, turns, usage)
     } catch (e) {
@@ -605,7 +684,20 @@ export class Client {
         for (const c of calls) yield { type: "tool_call", id: c.id, name: c.name, args: safeJson(c.args) }
         const settled = await Promise.all(calls.map((c) => this.runTool(toolkit, c.name, safeJson(c.args), c.id, turn)))
         for (let i = 0; i < calls.length; i++) {
-          const c = calls[i], { args, result } = settled[i]
+          const c = calls[i]
+          let { args, result } = settled[i]
+          const req = pendingOf(result)
+          if (req) {
+            yield { type: "pending", request: req } // surface BEFORE waitFor so a channel can push the link
+            const r = await this.resolvePending(toolkit, c.name, args, req, c.id, turn)
+            result = r.result
+            if (r.halted) {
+              toolCalls.push({ name: c.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
+              messages.push({ role: "tool", tool_call_id: c.id, content: result.output })
+              yield { type: "done", result: this.pendingRun(runStart, r.halted, messages, toolCalls, turns, usage) }
+              return
+            }
+          }
           toolCalls.push({ name: c.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
           messages.push({ role: "tool", tool_call_id: c.id, content: result.output })
           yield { type: "tool_result", id: c.id, name: c.name, output: result.output, isError: result.isError }
@@ -683,7 +775,21 @@ export class Client {
         const settled = await Promise.all((uses as any[]).map((u) => this.runTool(toolkit, u.name, u.input ?? {}, u.id, turn)))
         const results: any[] = []
         for (let i = 0; i < uses.length; i++) {
-          const u = uses[i] as any, { args, result } = settled[i]
+          const u = uses[i] as any
+          let { args, result } = settled[i]
+          const req = pendingOf(result)
+          if (req) {
+            yield { type: "pending", request: req }
+            const r = await this.resolvePending(toolkit, u.name, args, req, u.id, turn)
+            result = r.result
+            if (r.halted) {
+              toolCalls.push({ name: u.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
+              results.push({ type: "tool_result", tool_use_id: u.id, content: result.output, is_error: result.isError })
+              messages.push({ role: "user", content: results })
+              yield { type: "done", result: this.pendingRun(runStart, r.halted, messages, toolCalls, turns, usage) }
+              return
+            }
+          }
           toolCalls.push({ name: u.name, args, output: result.output, isError: result.isError, metadata: result.metadata })
           results.push({ type: "tool_result", tool_use_id: u.id, content: result.output, is_error: result.isError })
           yield { type: "tool_result", id: u.id, name: u.name, output: result.output, isError: result.isError }

package/src/mcp.ts

@@ -8,8 +8,36 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js"
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js"
-import type { Tool as McpToolDef } from "@modelcontextprotocol/sdk/types.js"
-import { type JSONSchema, type Tool, type ToolContext, type ToolResult, type McpStatus, sanitize } from "./types.js"
+import type { Tool as McpToolDef, ElicitRequest, ElicitResult } from "@modelcontextprotocol/sdk/types.js"
+import { ElicitRequestSchema } from "@modelcontextprotocol/sdk/types.js"
+import { type JSONSchema, type Tool, type ToolContext, type ToolResult, type McpStatus, type Request, type Answer, sanitize } from "./types.js"
+
+// ---------------------------------------------------------------------------
+// MCP elicitation bridge (§10). A server can ask US for input mid-`tools/call`
+// (a reverse-request). We map it onto the one `waitFor`: form mode → kind:"input",
+// URL mode → kind:"authorization". The two mappings are pure + byte-parity-tested.
+// ---------------------------------------------------------------------------
+
+let _elcSeq = 0
+/** Map an MCP `elicitation/create` request onto a §10 `Request`. */
+export function elicitationToRequest(params: ElicitRequest["params"]): Request {
+  const p = params as { message?: string; requestedSchema?: unknown; mode?: string; url?: string }
+  const isUrl = p.mode === "url"
+  const req: Request = {
+    id: `elc-${Date.now().toString(36)}-${++_elcSeq}`,
+    kind: isUrl ? "authorization" : "input",
+    prompt: String(p.message ?? ""),
+  }
+  if (isUrl && p.url) req.url = p.url
+  if (!isUrl && p.requestedSchema) req.data = { schema: p.requestedSchema }
+  return req
+}
+
+/** Map a resolved §10 `Answer` back onto an MCP `ElicitResult`. ok→accept; declined→decline; else→cancel. */
+export function answerToElicitResult(answer: Answer): ElicitResult {
+  if (answer.ok) return { action: "accept", content: (answer.data ?? {}) as ElicitResult["content"] }
+  return { action: answer.reason === "declined" ? "decline" : "cancel" }
+}
 
 const DEFAULT_TIMEOUT = 30_000
 const MAX_LIST_PAGES = 1_000
@@ -155,11 +183,12 @@ export interface McpSource {
 }
 
 /** Connect to every enabled server, list + convert tools. Failures are isolated. */
-export async function loadMcp(input: string | object): Promise<McpSource> {
+export async function loadMcp(input: string | object, opts?: { waitFor?: (request: Request) => Promise<Answer> }): Promise<McpSource> {
   const config = parseMcpConfig(input)
   const tools: Tool[] = []
   const status: Record<string, McpStatus> = {}
   const clients: Client[] = []
+  const waitFor = opts?.waitFor
 
   await Promise.all(
     Object.entries(config).map(async ([name, cfg]) => {
@@ -168,7 +197,14 @@ export async function loadMcp(input: string | object): Promise<McpSource> {
         return
       }
       const timeout = cfg.timeout ?? DEFAULT_TIMEOUT
-      const client = new Client({ name: "toolnexus", version: "0.1.0" }, { capabilities: {} })
+      // Advertise elicitation + register the bridge ONLY when a waitFor exists to satisfy it —
+      // a waitFor-less host degrades cleanly (the server won't elicit). (§10 elicitation bridge)
+      const client = new Client({ name: "toolnexus", version: "0.1.0" }, { capabilities: waitFor ? { elicitation: {} } : {} })
+      if (waitFor) {
+        client.setRequestHandler(ElicitRequestSchema, async (request) =>
+          answerToElicitResult(await waitFor(elicitationToRequest(request.params))),
+        )
+      }
       try {
         if (isRemote(cfg)) {
           const url = new URL(cfg.url)

package/src/serve.ts

@@ -331,12 +331,22 @@ async function fulfil(
     // contextId groups a peer's turns into one conversation — thread it so the
     // client's ConversationStore remembers across tasks in the same context.
     result = await runTask(text, contextId)
-    const artifact: A2AArtifact = {
-      artifactId: randomUUID(),
-      parts: [{ kind: "text", text: result.text }],
+    if (result.status === "pending" && result.pending) {
+      // §10 suspension over A2A: the run halted waiting on out-of-band input. Surface the
+      // protocol's `input-required` state carrying the request prompt — never a false `completed`.
+      task = {
+        id,
+        status: { state: "input-required", message: { role: "agent", parts: [{ kind: "text", text: result.pending.prompt }] } },
+      }
+      state = "input-required"
+    } else {
+      const artifact: A2AArtifact = {
+        artifactId: randomUUID(),
+        parts: [{ kind: "text", text: result.text }],
+      }
+      task = { id, status: { state: "completed" }, artifacts: [artifact] }
+      state = "completed"
     }
-    task = { id, status: { state: "completed" }, artifacts: [artifact] }
-    state = "completed"
   } catch (e) {
     const detail = e instanceof Error ? e.message : String(e)
     task = { id, status: { state: "failed", message: { role: "agent", parts: [{ kind: "text", text: detail }] } } }

package/src/toolkit.ts

@@ -20,6 +20,13 @@ export interface ToolkitOptions {
   builtins?: BuiltinsConfig
   /** Remote A2A agents — each advertised skill becomes a tool (source:"a2a"). */
   agents?: Agent[]
+  /**
+   * Host resolver for out-of-band input (§10). When set, connected MCP servers may elicit input
+   * from the human mid-`tools/call` and it is bridged onto this `waitFor` (form→kind:"input",
+   * URL→kind:"authorization"). Typically the same function passed to the client. Omit ⇒ MCP
+   * elicitation is not advertised.
+   */
+  waitFor?: (request: import("./types.js").Request) => Promise<import("./types.js").Answer>
 }
 
 export class Toolkit {
@@ -51,7 +58,7 @@ export class Toolkit {
   }
 
   static async create(opts: ToolkitOptions): Promise<Toolkit> {
-    const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig) : undefined
+    const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig, { waitFor: opts.waitFor }) : undefined
     const skill = opts.skillsDir !== undefined ? loadSkills(opts.skillsDir) : undefined
     // The toggle comes from the `builtins` option, or a top-level `builtins`
     // key on a parsed config object — same precedence as MCP's isEnabled.

package/src/types.ts

@@ -21,6 +21,56 @@ export interface ToolResult {
 export interface ToolContext {
   signal?: AbortSignal
   timeout?: number
+  /** Present ONLY on a post-waitFor retry (§10): the resolution of a prior suspension. */
+  answer?: Answer
+}
+
+/**
+ * §10 Suspension. A tool that needs an out-of-band, async resolution (login, approval,
+ * input) returns a normal ToolResult carrying `metadata.pending = Request`. Byte-identical
+ * wire data — it crosses languages, processes, and agents unchanged.
+ */
+export interface Request {
+  id: string
+  kind: string // "authorization" | "approval" | "input" | ... (open vocabulary)
+  prompt: string
+  url?: string
+  data?: Record<string, unknown>
+  expiresAt?: string
+}
+
+export interface Answer {
+  id: string
+  ok: boolean
+  data?: Record<string, unknown>
+  /**
+   * When `ok` is false, why (advisory — the loop rule branches only on `ok`). Distinguishes an
+   * explicit refusal from a dismissal/timeout; the MCP elicitation bridge maps `declined`→`decline`
+   * and everything else→`cancel`. (R1)
+   */
+  reason?: "declined" | "cancelled" | "expired"
+}
+
+let _pendingSeq = 0
+/** Producer helper: return a suspension. A ToolResult with `metadata.pending` = a Request. */
+export function pending(request: Omit<Request, "id"> & { id?: string }): ToolResult {
+  const id = request.id ?? `pnd-${Date.now().toString(36)}-${++_pendingSeq}`
+  const req: Request = { ...request, id }
+  return {
+    output: req.prompt + (req.url ? `\n${req.url}` : ""),
+    isError: true,
+    metadata: { pending: req },
+  }
+}
+
+/** Sugar for the common case: `kind:"authorization"` at a login URL. */
+export function authRequired(url: string, prompt = "Authorization required to continue"): ToolResult {
+  return pending({ kind: "authorization", prompt, url })
+}
+
+/** Read the suspension off a result, if any. */
+export function pendingOf(result: ToolResult): Request | undefined {
+  return (result.metadata as { pending?: Request } | undefined)?.pending
 }
 
 export interface Tool {