toolnexus 0.24.0 → 0.26.0

package/dist/client.d.ts

@@ -208,6 +208,12 @@ export type MetricEvent = {
     promptTokens: number;
     completionTokens: number;
     error?: string;
+    /** L1: how many questions were asked. */
+    questions: number;
+    /** L1: sha256 hex of `canonicalRequest(model, questions)` ("" when unencodable). */
+    questionsHash: string;
+    /** True when the decision came from the classifier cache and no request was sent. */
+    cached: boolean;
 } | {
     event: "classifier.warning";
     question: string;
@@ -358,12 +364,21 @@ export interface RunResult {
 export type StreamEvent = {
     type: "text";
     delta: string;
-} | {
+}
+/** Model reasoning narration (e.g. an ACP agent's `agent_thought_chunk`). Never part of
+ *  the answer text or the RunResult. */
+ | {
+    type: "thought";
+    delta: string;
+    via?: "acp";
+}
+/** `via: "acp"` marks a tool the ACP agent ran itself: reported, never executed by the loop. */
+ | {
     type: "tool_call";
     id: string;
     name: string;
     args: Record<string, unknown>;
-    via?: "call_tool";
+    via?: "call_tool" | "acp";
 } | {
     type: "tool_result";
     id: string;
@@ -371,7 +386,7 @@ export type StreamEvent = {
     output: string;
     isError: boolean;
     metadata?: Record<string, unknown>;
-    via?: "call_tool";
+    via?: "call_tool" | "acp";
 } | {
     type: "usage";
     usage: Usage;
@@ -582,11 +597,22 @@ export interface InProcessResponse {
         totalTokens?: number;
     };
 }
+/** A streaming in-process model: `emit` each event as it happens — `text` deltas become
+ *  the streamed answer as they arrive; any other event (thought, an agent's own tool_call /
+ *  tool_result) goes straight to the stream consumer and is never executed by the loop.
+ *  Return the whole message when done (its `toolCalls`, if any, are what the loop runs). */
+export type InProcessGenerateStream = (request: InProcessRequest, emit: (event: StreamEvent) => void) => InProcessResponse | Promise<InProcessResponse>;
+type InProcessGenerate = (request: InProcessRequest) => InProcessResponse | Promise<InProcessResponse>;
 /** Options for {@link createInProcessClient}: every client option EXCEPT the three
- *  that describe a wire — `baseUrl`, `apiKey` and `style` — plus `generate`. */
+ *  that describe a wire — `baseUrl`, `apiKey` and `style` — plus `generate` and/or
+ *  `generateStream` (at least one). */
 export type InProcessOptions = Omit<ClientOptions, "baseUrl" | "apiKey" | "style" | "fetch"> & {
     /** Your model. Receives the assembled request, returns one assistant message. */
-    generate: (request: InProcessRequest) => InProcessResponse | Promise<InProcessResponse>;
+    generate?: InProcessGenerate;
+    /** Your model, streaming for real. With it, `stream()` is incremental; without it a
+     *  `stream()` on a plain `generate` is refused. When both are set, `generate` serves
+     *  non-streaming calls; alone, it serves them too (with a no-op `emit`). */
+    generateStream?: InProcessGenerateStream;
 };
 /**
  * Build a `fetch`-shaped adapter over a semantic `generate` function (ADR 0030):
@@ -596,9 +622,11 @@ export type InProcessOptions = Omit<ClientOptions, "baseUrl" | "apiKey" | "style
  * or the agent runtime's `inProcess` option) goes through this ONE function, so there
  * is no second copy of the request/response assembly to drift.
  *
- * Streaming is refused rather than faked — see the thrown error.
+ * Streaming with only a plain `generate` is refused rather than faked — see the thrown
+ * error. With `generateStream` it streams for real: each text event is written to the
+ * SSE body the moment it is emitted.
  */
-export declare function createInProcessFetch(generate: (request: InProcessRequest) => InProcessResponse | Promise<InProcessResponse>): typeof fetch;
+export declare function createInProcessFetch(generate?: InProcessGenerate, generateStream?: InProcessGenerateStream): typeof fetch;
 /**
  * A client backed by a model running IN THIS PROCESS — no server, no socket, and no
  * HTTP types to construct.
@@ -609,7 +637,8 @@ export declare function createInProcessFetch(generate: (request: InProcessReques
  * The `fetch`-shaped adapter itself is {@link createInProcessFetch} — this function
  * is just that adapter wired into a `Client`.
  *
- * Streaming is refused rather than faked — see {@link createInProcessFetch}.
+ * Streaming is refused rather than faked for a plain `generate`; with `generateStream`
+ * it streams for real — see {@link createInProcessFetch}.
  */
 export declare function createInProcessClient(opts: InProcessOptions): Client;
 /** Stateful multi-turn conversation: each send() continues the same transcript (memory). */
@@ -625,3 +654,4 @@ export declare class Conversation {
     /** Reset the conversation memory. */
     reset(): void;
 }
+export {};

package/dist/client.js

@@ -1132,6 +1132,13 @@ export class Client {
                         if (payload === "[DONE]")
                             break;
                         const j = safeParse(payload);
+                        // A non-text event from an in-process streaming generate rides in-band so it keeps
+                        // its order and arrives as it happens; it goes straight to the consumer and is never
+                        // executed. Honoured only on the in-process sentinel URL, never from a real server.
+                        if (j && j[IN_PROCESS_SIDE_KEY] && this.opts.baseUrl === IN_PROCESS_BASE_URL) {
+                            yield j[IN_PROCESS_SIDE_KEY];
+                            continue;
+                        }
                         if (j?.usage)
                             addUsage(usage, j.usage, "openai");
                         const choice = j?.choices?.[0];
@@ -1336,6 +1343,9 @@ export function createClient(opts) {
  *  it must be syntactically valid. `.invalid` is reserved by RFC 2606 precisely so a
  *  name can never resolve. */
 const IN_PROCESS_BASE_URL = "http://in-process.invalid/v1";
+/** The in-band SSE key that carries a non-text stream event from an in-process
+ *  streaming generate to the consumer (honoured only on {@link IN_PROCESS_BASE_URL}). */
+const IN_PROCESS_SIDE_KEY = "toolnexus_event";
 /**
  * Build a `fetch`-shaped adapter over a semantic `generate` function (ADR 0030):
  * the reusable piece of {@link createInProcessClient} — assembles the wire request,
@@ -1344,14 +1354,19 @@ const IN_PROCESS_BASE_URL = "http://in-process.invalid/v1";
  * or the agent runtime's `inProcess` option) goes through this ONE function, so there
  * is no second copy of the request/response assembly to drift.
  *
- * Streaming is refused rather than faked — see the thrown error.
+ * Streaming with only a plain `generate` is refused rather than faked — see the thrown
+ * error. With `generateStream` it streams for real: each text event is written to the
+ * SSE body the moment it is emitted.
  */
-export function createInProcessFetch(generate) {
-    if (typeof generate !== "function") {
-        throw new Error("toolnexus: createInProcessFetch requires a `generate` function");
+export function createInProcessFetch(generate, generateStream) {
+    if (typeof generate !== "function" && typeof generateStream !== "function") {
+        throw new Error("toolnexus: createInProcessFetch requires a `generate` (or `generateStream`) function");
     }
     const inProcessFetch = async (_url, init) => {
         const body = JSON.parse(String(init?.body ?? "{}"));
+        const request = { messages: body.messages ?? [], tools: body.tools, model: body.model, body };
+        if (body.stream && generateStream)
+            return inProcessStream(generateStream, request);
         // A generate() returns a whole answer, so a stream would be one chunk pretending
         // to be many. Content and delta-count assertions cannot tell that from a real
         // stream, so refuse instead of degrading silently.
@@ -1359,24 +1374,10 @@ export function createInProcessFetch(generate) {
             throw new Error("toolnexus: createInProcessClient does not support streaming — `generate` returns a " +
                 "complete answer. Use the non-streaming run, or supply a `fetch`/transport that streams.");
         }
-        const answer = await generate({
-            messages: body.messages ?? [],
-            tools: body.tools,
-            model: body.model,
-            body,
-        });
+        const answer = generate ? await generate(request) : await generateStream(request, () => { });
         const message = { role: "assistant" };
         if (answer.toolCalls && answer.toolCalls.length > 0) {
-            message.tool_calls = answer.toolCalls.map((c, i) => ({
-                id: c.id ?? `call_${i}`,
-                type: "function",
-                function: {
-                    name: c.name,
-                    // A string is already encoded; anything else is encoded here so a model
-                    // author never has to think about the wire.
-                    arguments: typeof c.arguments === "string" ? c.arguments : JSON.stringify(c.arguments ?? {}),
-                },
-            }));
+            message.tool_calls = wireToolCalls(answer.toolCalls, false);
         }
         else {
             message.content = answer.content ?? "";
@@ -1395,6 +1396,80 @@ export function createInProcessFetch(generate) {
     };
     return inProcessFetch;
 }
+function wireToolCalls(calls, indexed) {
+    return calls.map((c, i) => ({
+        ...(indexed ? { index: i } : {}),
+        id: c.id ?? `call_${i}`,
+        type: "function",
+        function: {
+            name: c.name,
+            // A string is already encoded; anything else is encoded here so a model
+            // author never has to think about the wire.
+            arguments: typeof c.arguments === "string" ? c.arguments : JSON.stringify(c.arguments ?? {}),
+        },
+    }));
+}
+/** Runs a streaming generate and answers with an OpenAI SSE body written AS EVENTS ARRIVE:
+ *  text → a content delta; any other event → an in-band side chunk for the consumer; then
+ *  (tool calls as one delta | the content as one delta when no text was emitted), the
+ *  finish_reason chunk, usage, and [DONE]. */
+function inProcessStream(generateStream, request) {
+    const enc = new TextEncoder();
+    let open = true;
+    const sse = new ReadableStream({
+        start(controller) {
+            const chunk = (v) => {
+                if (open)
+                    controller.enqueue(enc.encode(`data: ${JSON.stringify(v)}\n\n`));
+            };
+            let sawText = false;
+            void (async () => {
+                try {
+                    const answer = await generateStream(request, (ev) => {
+                        if (!ev || typeof ev !== "object")
+                            return;
+                        if (ev.type === "text") {
+                            if (ev.delta) {
+                                sawText = true;
+                                chunk({ choices: [{ index: 0, delta: { content: ev.delta } }] });
+                            }
+                            return;
+                        }
+                        chunk({ [IN_PROCESS_SIDE_KEY]: ev });
+                    });
+                    let finish = "stop";
+                    if (answer.toolCalls && answer.toolCalls.length > 0) {
+                        chunk({ choices: [{ index: 0, delta: { tool_calls: wireToolCalls(answer.toolCalls, true) } }] });
+                        finish = "tool_calls";
+                    }
+                    else if (!sawText && answer.content) {
+                        chunk({ choices: [{ index: 0, delta: { content: answer.content } }] });
+                    }
+                    chunk({ choices: [{ index: 0, delta: {}, finish_reason: finish }] });
+                    const u = answer.usage;
+                    if (u) {
+                        const p = u.promptTokens ?? 0, c = u.completionTokens ?? 0;
+                        chunk({ choices: [], usage: { prompt_tokens: p, completion_tokens: c, total_tokens: u.totalTokens || p + c } });
+                    }
+                    if (open)
+                        controller.enqueue(enc.encode("data: [DONE]\n\n"));
+                    open = false;
+                    controller.close();
+                }
+                catch (e) {
+                    if (open) {
+                        open = false;
+                        controller.error(e);
+                    }
+                }
+            })();
+        },
+        cancel() {
+            open = false;
+        },
+    });
+    return new Response(sse, { status: 200, headers: { "content-type": "text/event-stream" } });
+}
 /**
  * A client backed by a model running IN THIS PROCESS — no server, no socket, and no
  * HTTP types to construct.
@@ -1405,11 +1480,15 @@ export function createInProcessFetch(generate) {
  * The `fetch`-shaped adapter itself is {@link createInProcessFetch} — this function
  * is just that adapter wired into a `Client`.
  *
- * Streaming is refused rather than faked — see {@link createInProcessFetch}.
+ * Streaming is refused rather than faked for a plain `generate`; with `generateStream`
+ * it streams for real — see {@link createInProcessFetch}.
  */
 export function createInProcessClient(opts) {
-    const { generate, ...rest } = opts;
-    const inProcessFetch = createInProcessFetch(generate);
+    const { generate, generateStream, ...rest } = opts;
+    if (typeof generate !== "function" && typeof generateStream !== "function") {
+        throw new Error("toolnexus: createInProcessClient requires a `generate` (or `generateStream`) function");
+    }
+    const inProcessFetch = createInProcessFetch(generate, generateStream);
     return new Client({
         // Retries default to ZERO here, unlike a network client. There is no wire, so
         // there is no transient failure to ride out: whatever `generate` throws will

package/dist/index.d.ts

@@ -10,6 +10,8 @@ export * from "./a2a.js";
 export * from "./acp.js";
 export * from "./serve.js";
 export * from "./mcpserve.js";
+export * from "./mcphandler.js";
+export * from "./mcpserverauth.js";
 export * from "./adapters.js";
 export * from "./translate.js";
 export * from "./toolkit.js";

package/dist/index.js

@@ -10,6 +10,8 @@ export * from "./a2a.js";
 export * from "./acp.js";
 export * from "./serve.js";
 export * from "./mcpserve.js";
+export * from "./mcphandler.js";
+export * from "./mcpserverauth.js";
 export * from "./adapters.js";
 export * from "./translate.js";
 export * from "./toolkit.js";

package/dist/judge.d.ts

@@ -7,12 +7,12 @@
  *
  * A gate never authorises; it only declines to decide.
  */
-import { Classifier, Decision, type DecisionAnswer, type NoulCriteria, type Question, type RecordedDecision } from "./classifier.js";
+import { Classifier, Decision, type DecisionAnswer, type NoulCriteria, type AnyQuestion, type RecordedDecision } from "./classifier.js";
 import type { Request } from "./types.js";
 /** One named question of an ordered question list. */
 export interface NamedQuestion {
     name: string;
-    question: Question;
+    question: AnyQuestion;
 }
 /** `noul` question with a name. Name the state field it judges in `instructions`. */
 export declare function noul(name: string, instructions: string, criteria?: NoulCriteria): NamedQuestion;
@@ -20,8 +20,11 @@ export declare function noul(name: string, instructions: string, criteria?: Noul
 export declare function choice(name: string, instructions: string, options: Record<string, string>): NamedQuestion;
 /** `score` question with a name; `levels` is the ordered rubric. */
 export declare function score(name: string, instructions: string, levels: string[]): NamedQuestion;
+/** A raw question with a name: a System One type the library does not model (e.g. `box`), sent
+ * as written. Its answer decodes to a raw answer `{type, value}`. */
+export declare function raw(name: string, type: string, instructions: string, criteria?: unknown): NamedQuestion;
 /** Ordered list -> the §8B questions map. A duplicate name is an error naming it. */
-export declare function questionMap(questions: readonly NamedQuestion[]): Record<string, Question>;
+export declare function questionMap(questions: readonly NamedQuestion[]): Record<string, AnyQuestion>;
 /** `role` next to the data's fields; a non-object value goes under `data`. */
 export declare function State(role: string, data: unknown): Record<string, unknown>;
 /** Sugar: `{context, message, ...extra}`. */

package/dist/judge.js

@@ -7,7 +7,7 @@
  *
  * A gate never authorises; it only declines to decide.
  */
-import { Classifier, noul as noulQ, choice as choiceQ, score as scoreQ, } from "./classifier.js";
+import { Classifier, isRawAnswer, raw as rawQ, noul as noulQ, choice as choiceQ, score as scoreQ, } from "./classifier.js";
 /** `noul` question with a name. Name the state field it judges in `instructions`. */
 export function noul(name, instructions, criteria) {
     return { name, question: noulQ(instructions, criteria) };
@@ -20,6 +20,11 @@ export function choice(name, instructions, options) {
 export function score(name, instructions, levels) {
     return { name, question: scoreQ(instructions, levels) };
 }
+/** A raw question with a name: a System One type the library does not model (e.g. `box`), sent
+ * as written. Its answer decodes to a raw answer `{type, value}`. */
+export function raw(name, type, instructions, criteria) {
+    return { name, question: rawQ(type, instructions, criteria) };
+}
 /** Ordered list -> the §8B questions map. A duplicate name is an error naming it. */
 export function questionMap(questions) {
     const out = {};
@@ -47,6 +52,13 @@ function noulBand(p, b) {
     return p < b.low ? "no" : p > b.high ? "yes" : "uncertain";
 }
 function wrap(a, b) {
+    if (isRawAnswer(a)) {
+        // An unmodelled answer type is never sure: there is no number to band.
+        const out = { ...a, sure: false };
+        Object.defineProperty(out, "value", { value: () => 0, enumerable: false });
+        Object.defineProperty(out, "pick", { value: () => "", enumerable: false });
+        return out;
+    }
     const extra = a.type === "noul"
         ? { band: noulBand(a.noul, b) }
         : { sure: a.confidence > b.high && !(a.type === "choice" && a.nearUniform) };

package/dist/mcp.d.ts

@@ -1,6 +1,11 @@
 import type { ElicitRequest, ElicitResult } from "@modelcontextprotocol/sdk/types.js";
-import { type JSONSchema, type Tool, type ToolHints, type McpStatus, type Request, type Answer } from "./types.js";
+import { type JSONSchema, type Tool, type ToolHints, type ToolResult, type McpStatus, type Request, type Answer } from "./types.js";
 import { type ContentPart } from "./content.js";
+import type { SkillDef } from "./skill.js";
+import { type AuthConfig } from "./mcp2026/source.js";
+import { type TokenStore } from "./mcp2026/auth.js";
+export { Token, MemoryTokenStore, type TokenStore } from "./mcp2026/auth.js";
+export type { AuthConfig } from "./mcp2026/source.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. */
@@ -18,6 +23,10 @@ export interface LocalServer {
      * builtins/skills filter (nil/empty ⇒ all; ≥1 true ⇒ allowlist; only-false ⇒ drop-list; unknown
      * ⇒ ignore+warn). Applied to the listed defs before sanitize/prefix. */
     tools?: Record<string, boolean>;
+    /** §2.8 lazy tool search: expose `<server>_search_tools` + `<server>_call_tool` instead of every tool. */
+    toolSearch?: boolean;
+    /** §2.8 what this server is for (shown by search_tools). */
+    description?: string;
 }
 export interface RemoteServer {
     type?: "remote";
@@ -28,6 +37,11 @@ export interface RemoteServer {
     timeout?: number;
     /** §2 Gap 7. Per-server tool allowlist (see LocalServer.tools). */
     tools?: Record<string, boolean>;
+    /** §2.8 lazy tool search (see LocalServer.toolSearch). */
+    toolSearch?: boolean;
+    description?: string;
+    /** §2A OAuth 2.1 client settings. Absent ⇒ a 401 still triggers the flow (CIMD if the AS supports it). */
+    auth?: AuthConfig;
 }
 export type ServerConfig = LocalServer | RemoteServer;
 export type McpConfig = Record<string, ServerConfig>;
@@ -46,6 +60,8 @@ export declare function expandEnvHeaders(headers?: Record<string, string>): Reco
  * takes it there.
  */
 export declare function mcpContentToParts(content: unknown): ContentPart[] | undefined;
+/** §2 `tools/call` result → ToolResult (shared by the 2026 path and the frozen fallback). */
+export declare function mapCallToolResult(result: any, server: string): ToolResult;
 export interface McpSource {
     tools: Tool[];
     status: Record<string, McpStatus>;
@@ -56,6 +72,8 @@ export interface McpSource {
      * source is closed.
      */
     resourceTools(): Tool[];
+    /** §2.7 skills served by 2026 servers (skills extension); the toolkit adds them to the `skill` tool. */
+    skills: SkillDef[];
 }
 /** One server's outcome, reported by `loadMcp`'s `onServer` the moment that server finishes. */
 export interface McpServerResult {
@@ -75,12 +93,21 @@ export declare function mcpHints(a: {
     destructiveHint?: boolean;
     openWorldHint?: boolean;
 } | undefined): ToolHints | undefined;
+/** Options shared by loadMcp / listMcpTools for the 2026 path and OAuth (§2A.1a). */
+export interface McpLoadOptions {
+    waitFor?: (request: Request) => Promise<Answer>;
+    signal?: AbortSignal;
+    /** Where OAuth tokens live (default: in memory, per load). */
+    tokenStore?: TokenStore;
+    /** How `auto` OAuth mode opens the authorization URL (default: the OS opener). */
+    openUrl?: (url: string) => unknown | Promise<unknown>;
+    /** Final exposed names to drop; on a tool-search server they are also hidden from search/call. */
+    disableTools?: string[];
+}
 /** Connect to every enabled server, list + convert tools. Failures are isolated.
  *  §2 Gap 3: an optional `signal` bounds each connect/list by the server timeout and aborts the
  *  whole load promptly on parent cancellation. */
-export declare function loadMcp(input: string | object, opts?: {
-    waitFor?: (request: Request) => Promise<Answer>;
-    signal?: AbortSignal;
+export declare function loadMcp(input: string | object, opts?: McpLoadOptions & {
     /**
      * Called once per server the moment it is connected, failed or found disabled (SPEC §4C),
      * so a host can register a fast server's tools while a slow one is still connecting.
@@ -105,6 +132,4 @@ export interface McpInventory {
  * §2 Gap 6. Connect to every enabled server, list tool definitions, and DISCONNECT before
  * returning — no toolkit, no execute wiring, nothing left running. Failure isolation as in loadMcp.
  */
-export declare function listMcpTools(input: string | object, opts?: {
-    signal?: AbortSignal;
-}): Promise<McpInventory>;
+export declare function listMcpTools(input: string | object, opts?: McpLoadOptions): Promise<McpInventory>;