toolnexus 0.6.0 → 0.8.0

package/dist/toolkit.d.ts

@@ -3,6 +3,7 @@
  * single uniform list, with provider adapters and a single execute() router.
  */
 import { type Tool, type ToolContext, type ToolResult, type McpStatus } from "./types.js";
+import { type SkillDef } from "./skill.js";
 import { type BuiltinsConfig } from "./builtin.js";
 import { type Agent } from "./a2a.js";
 import { type A2AConfig, type OnTask, type ServeHandle } from "./serve.js";
@@ -11,11 +12,26 @@ import type { Client } from "./client.js";
 export interface ToolkitOptions {
     mcpConfig?: string | object;
     skillsDir?: string | string[];
+    /** Skills supplied as data, bypassing the filesystem (§3, S1). */
+    skills?: SkillDef[];
+    /** Lazy provider of data-supplied skills, resolved once at toolkit build (§3, S1). */
+    skillProvider?: () => SkillDef[] | Promise<SkillDef[]>;
+    /** Per-agent skill allowlist keyed on name; same semantics as the MCP tools filter (§3, S2). */
+    skillsFilter?: Record<string, boolean>;
+    /** Sibling-file sample cap: 0 ⇒ default 10, n>0 ⇒ cap, -1 ⇒ omit <skill_files> (§3, S5). */
+    skillSampleLimit?: number;
     extraTools?: Tool[];
     /** Built-in tools (§4A). On by default. false | { disabled:true } | { enabled:false } ⇒ off. */
     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,8 +34,30 @@ export class Toolkit {
         }
     }
     static async create(opts) {
-        const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig) : undefined;
-        const skill = opts.skillsDir !== undefined ? loadSkills(opts.skillsDir) : undefined;
+        const mcp = opts.mcpConfig !== undefined ? await loadMcp(opts.mcpConfig, { waitFor: opts.waitFor }) : undefined;
+        // Skills come from directories, in-memory data, and/or a lazy provider (§3,
+        // S1). The provider is resolved here (create() is async) and merged with the
+        // data list; a provider failure is isolated so other sources still load.
+        let skill;
+        if (opts.skillsDir !== undefined || opts.skills !== undefined || opts.skillProvider !== undefined) {
+            let providerDefs = [];
+            if (opts.skillProvider) {
+                try {
+                    providerDefs = await opts.skillProvider();
+                }
+                catch (e) {
+                    console.warn(`[toolnexus] skill provider failed: ${e instanceof Error ? e.message : String(e)}`);
+                    providerDefs = [];
+                }
+            }
+            const dataDefs = [...(opts.skills ?? []), ...providerDefs];
+            skill = loadSkills({
+                dirs: opts.skillsDir,
+                skills: dataDefs.length > 0 ? dataDefs : undefined,
+                filter: opts.skillsFilter,
+                sampleLimit: opts.skillSampleLimit,
+            });
+        }
         // The toggle comes from the `builtins` option, or a top-level `builtins`
         // key on a parsed config object — same precedence as MCP's isEnabled.
         let builtinsCfg = opts.builtins;

package/dist/types.d.ts

@@ -37,6 +37,12 @@ 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"> & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.6.0",
+  "version": "0.8.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

@@ -44,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 }
 
 /**
@@ -227,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]]))
@@ -402,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()
@@ -469,22 +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)
-        let halted: Request | undefined
-        const results = await Promise.all(
+        const settled = await Promise.all(
           calls.map(async (call: any) => {
             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
-              if (r.halted) halted = r.halted
+              halted = r.halted
             }
-            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 }
+            return { call, args, result, halted }
           }),
         )
-        messages.push(...results)
-        if (halted) return this.pendingRun(runStart, halted, messages, toolCalls, turns, usage)
+        // 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) {
@@ -520,7 +535,7 @@ export class Client {
       const ov = await this.opts.hooks.afterTool({ name, args, result, id, turn })
       if (ov?.result) result = ov.result
     }
-    this.emit({ event: "tool", tool: name, source: toolkit.get(name)?.source ?? "custom", isError: result.isError, ms: Date.now() - t0 })
+    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 }
   }
@@ -566,21 +581,30 @@ 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)
-        let halted: Request | undefined
-        const results = await Promise.all(
+        const settled = await Promise.all(
           uses.map(async (use: any) => {
             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
-              if (r.halted) halted = r.halted
+              halted = r.halted
             }
-            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 }
+            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)

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

@@ -62,7 +62,13 @@ export class FileTaskStore implements TaskStore {
     }
   }
   async save(task: A2ATask): Promise<void> {
-    fs.writeFileSync(this.file(task.id), JSON.stringify(task))
+    // Atomic write: a concurrent get() must never read a half-written file (that
+    // would surface as a spurious "Task not found" mid-poll). Write a temp file in
+    // the same dir, then rename over the target.
+    const target = this.file(task.id)
+    const tmp = `${target}.tmp`
+    fs.writeFileSync(tmp, JSON.stringify(task))
+    fs.renameSync(tmp, target)
   }
 }
 
@@ -331,12 +337,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 }] } } }