toolnexus 0.20.0 → 0.22.0

package/dist/builtin_extras.js

@@ -0,0 +1,248 @@
+/**
+ * Opt-in builtins for coding-agent hosts (SPEC §4C): background shells (`bash`
+ * run_in_background + `bash_output` + `kill_shell`), `websearch` over a host-supplied provider,
+ * and `notebook_edit`. None is on by default: a host that sets nothing sees the same ten builtins.
+ */
+import { spawn, spawnSync } from "node:child_process";
+const err = (output, metadata) => ({ output, isError: true, metadata });
+const ok = (output, metadata) => ({ output, isError: false, metadata });
+/**
+ * Owns the commands `bash` started with `run_in_background`. Pass one as
+ * `builtins.background`, and call `closeAll()` when the host shuts down — a background command
+ * is NOT tied to the turn that started it, so nothing else stops it.
+ */
+export class BackgroundShells {
+    next = 0;
+    jobs = new Map();
+    /** @internal Start `command` under `argv` in its own process group. */
+    start(argv, command, workdir, grace) {
+        const child = spawn(argv[0], [...argv.slice(1), command], { cwd: workdir, detached: process.platform !== "win32" });
+        let resolveDone;
+        const done = new Promise((r) => (resolveDone = r));
+        const j = {
+            id: `bg${++this.next}`, command, started: new Date(), child, pgid: child.pid, grace,
+            out: "", read: 0, running: true, exitCode: 0, killed: false, done,
+        };
+        child.stdout?.on("data", (d) => (j.out += d.toString()));
+        child.stderr?.on("data", (d) => (j.out += d.toString()));
+        const finish = (code) => {
+            if (!j.running)
+                return;
+            j.running = false;
+            j.exitCode = code ?? -1;
+            resolveDone();
+        };
+        child.on("error", (e) => {
+            j.out += `bash: ${e.message}\n`;
+            finish(-1);
+        });
+        child.on("close", (code) => finish(code));
+        // A background job must never keep the host's event loop alive on its own.
+        child.unref();
+        child.stdout?.unref?.();
+        child.stderr?.unref?.();
+        this.jobs.set(j.id, j);
+        return j;
+    }
+    /** @internal */
+    get(id) {
+        return this.jobs.get(id);
+    }
+    signal(j, graceful) {
+        const pgid = j.pgid;
+        if (typeof pgid !== "number" || pgid <= 1 || !j.running)
+            return;
+        try {
+            if (process.platform === "win32")
+                spawnSync("taskkill", ["/T", "/F", "/PID", String(pgid)]);
+            else
+                process.kill(-pgid, graceful ? "SIGTERM" : "SIGKILL");
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    /** @internal Stop the job's whole process group: SIGTERM, the grace window, SIGKILL.
+     * Resolves whether it was still running. */
+    async kill(j) {
+        if (!j.running)
+            return false;
+        j.killed = true;
+        // The child and its pipes are unref'd so an idle job never pins the host. While we are
+        // WAITING on it, though, they must be ref'd: otherwise, once the grace timer is cleared,
+        // nothing holds the event loop open until 'close' fires and Node exits with this promise
+        // still pending (seen on Linux, where 'close' lands an iteration later than on macOS).
+        j.child.ref();
+        j.child.stdout?.ref?.();
+        j.child.stderr?.ref?.();
+        this.signal(j, true);
+        let t;
+        const timedOut = await Promise.race([j.done.then(() => false), new Promise((r) => (t = setTimeout(() => r(true), j.grace)))]);
+        if (t)
+            clearTimeout(t);
+        if (timedOut) {
+            this.signal(j, false);
+            await j.done;
+        }
+        return true;
+    }
+    static info(j) {
+        return { id: j.id, command: j.command, started: j.started, running: j.running, exitCode: j.exitCode, killed: j.killed };
+    }
+    /** Every background command, oldest first. */
+    list() {
+        return [...this.jobs.values()].sort((a, b) => a.started.getTime() - b.started.getTime()).map(BackgroundShells.info);
+    }
+    /** Stop one background command's process group. Unknown id ⇒ throws. */
+    async killShell(id) {
+        const j = this.jobs.get(id);
+        if (!j)
+            throw new Error(`no background shell "${id}"`);
+        await this.kill(j);
+    }
+    /** Stop every background command still running, concurrently. */
+    async closeAll() {
+        await Promise.all([...this.jobs.values()].map((j) => this.kill(j)));
+    }
+}
+export function bgStatus(i) {
+    if (i.running)
+        return "running";
+    if (i.killed)
+        return "killed";
+    return `exited with code ${i.exitCode}`;
+}
+/** `bash_output(id)`. */
+export function bashOutput(bg, id) {
+    const j = bg.get(id);
+    if (!j)
+        return err(`bash_output: no background shell "${id}"`);
+    const fresh = j.out.slice(j.read);
+    j.read = j.out.length;
+    const info = BackgroundShells.info(j);
+    const status = bgStatus(info);
+    const meta = { id, status: status.split(" ")[0] };
+    if (!info.running && !info.killed)
+        meta.exitCode = info.exitCode;
+    return ok(`${fresh}\n[status: ${status}]`, meta);
+}
+/** `kill_shell(id)`. */
+export async function killShell(bg, id) {
+    const j = bg.get(id);
+    if (!j)
+        return err(`kill_shell: no background shell "${id}"`);
+    if (!(await bg.kill(j))) {
+        return ok(`Background shell ${id} had already ${bgStatus(BackgroundShells.info(j))}`, { id, killed: false });
+    }
+    return ok(`Killed background shell ${id}`, { id, killed: true });
+}
+export async function runWebSearch(search, args, signal) {
+    const q = typeof args.query === "string" ? args.query : "";
+    if (!q.trim())
+        return err("websearch: query is required");
+    const limit = typeof args.limit === "number" && args.limit >= 1 ? Math.trunc(args.limit) : 5;
+    let results;
+    try {
+        results = await search(q, limit, { signal });
+    }
+    catch (e) {
+        return err(`websearch: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    results = (results ?? []).slice(0, limit);
+    if (results.length === 0)
+        return ok("No results.", { count: 0 });
+    const text = results
+        .map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}` + (r.snippet ? `\n   ${r.snippet}` : ""))
+        .join("\n\n");
+    return ok(text, { count: results.length, results: results.map((r) => ({ title: r.title, url: r.url, snippet: r.snippet ?? "" })) });
+}
+// ---------------------------------------------------------------------------
+// notebook_edit
+// ---------------------------------------------------------------------------
+/** Split text into nbformat's list of lines, each keeping its "\n". */
+export function notebookSource(s) {
+    if (!s)
+        return [];
+    return s.split(/(?<=\n)/).filter((p) => p !== "");
+}
+/** Go's json.MarshalIndent(v, "", " ") with sorted keys, plus Go's HTML escaping. */
+export function goJsonIndent(v) {
+    const sort = (x) => {
+        if (Array.isArray(x))
+            return x.map(sort);
+        if (x && typeof x === "object") {
+            const out = {};
+            for (const k of Object.keys(x).sort())
+                out[k] = sort(x[k]);
+            return out;
+        }
+        return x;
+    };
+    return JSON.stringify(sort(v), null, " ")
+        .replace(/</g, "\\u003c")
+        .replace(/>/g, "\\u003e")
+        .replace(/&/g, "\\u0026")
+        .replace(new RegExp(String.fromCharCode(0x2028), "g"), "\\u2028")
+        .replace(new RegExp(String.fromCharCode(0x2029), "g"), "\\u2029");
+}
+/** Apply one notebook_edit to the parsed notebook, in place. Returns the summary, or an error result. */
+export function editNotebook(nb, args, p) {
+    let cells = Array.isArray(nb.cells) ? nb.cells : [];
+    const mode = typeof args.edit_mode === "string" && args.edit_mode ? args.edit_mode : "replace";
+    let idx = -1;
+    if (typeof args.cell_id === "string" && args.cell_id) {
+        idx = cells.findIndex((c) => c && typeof c === "object" && c.id === args.cell_id);
+        if (idx < 0)
+            return err(`notebook_edit: no cell with id "${args.cell_id}"`);
+    }
+    else if (typeof args.cell_index === "number") {
+        idx = Math.trunc(args.cell_index);
+        if (idx < 0 || idx >= cells.length)
+            return err(`notebook_edit: cell_index ${idx} out of range (0-${cells.length - 1})`);
+    }
+    else if (mode !== "insert") {
+        return err("notebook_edit: cell_id or cell_index is required");
+    }
+    const src = typeof args.new_source === "string" ? args.new_source : "";
+    let cellType = typeof args.cell_type === "string" ? args.cell_type : "";
+    let summary;
+    switch (mode) {
+        case "replace": {
+            const cm = cells[idx];
+            cm.source = notebookSource(src);
+            if (cellType)
+                cm.cell_type = cellType;
+            if (cm.cell_type === "code") {
+                cm.outputs = [];
+                cm.execution_count = null;
+            }
+            else {
+                delete cm.outputs;
+                delete cm.execution_count;
+            }
+            summary = `Replaced cell ${idx} in ${p}`;
+            break;
+        }
+        case "insert": {
+            if (!cellType)
+                cellType = "code";
+            const cell = { cell_type: cellType, metadata: {}, source: notebookSource(src) };
+            if (cellType === "code") {
+                cell.outputs = [];
+                cell.execution_count = null;
+            }
+            const at = idx + 1;
+            cells = [...cells.slice(0, at), cell, ...cells.slice(at)];
+            summary = `Inserted ${cellType} cell at ${at} in ${p}`;
+            break;
+        }
+        case "delete":
+            cells = [...cells.slice(0, idx), ...cells.slice(idx + 1)];
+            summary = `Deleted cell ${idx} from ${p}`;
+            break;
+        default:
+            return err(`notebook_edit: unknown edit_mode "${mode}"`);
+    }
+    nb.cells = cells;
+    return { summary };
+}

package/dist/classifier.d.ts

@@ -19,6 +19,8 @@ export declare const DEFAULT_CLASSIFIER_MODEL = "jev-latest";
 export declare const DEFAULT_CLASSIFIER_API_KEY_ENV = "TYPESAFE_API_KEY";
 /** Bounds ONE request; a classifier has no loop to bound. */
 export declare const DEFAULT_CLASSIFIER_TIMEOUT_MS = 10000;
+/** `evaluateBatch`: at most this many states in flight by default. */
+export declare const DEFAULT_BATCH_CONCURRENCY = 16;
 /**
  * A named BACKEND: `baseUrl`, `model` and `apiKeyEnv` are only jointly valid, so they travel as
  * a UNIT (ADR 0027 D1). `jev-latest` is TypeSafe's spelling; the gateway spells the same model
@@ -95,6 +97,8 @@ export declare function score(instructions: string, criteria: string[]): ScoreQu
  * obligation on `ChoiceQuestion`.
  */
 export declare function choiceOver(instructions: string, items: Record<string, string>): ChoiceQuestion;
+/** The wire form of one question — the object itself, minus an absent `criteria`. */
+export declare function questionWire(q: Question): Record<string, unknown>;
 /**
  * Canonical JSON: object keys sorted recursively in CODE-UNIT (ASCII) order, arrays NEVER
  * reordered, compact separators, and `<>&'"` plus non-ASCII transmitted raw.
@@ -298,6 +302,16 @@ export declare class Classifier {
      * INDEPENDENT — one answer is never context for another.
      */
     evaluate(state: unknown, questions: Record<string, Question>, signal?: AbortSignal): Promise<Decision>;
+    /**
+     * The same questions over many states (SPEC §8B "Batch"). Each state goes through
+     * `evaluate`, at most `concurrency` (default 16) in flight; decisions come back in STATE
+     * order. Fails closed: the first failing state's index is named and no decisions return.
+     * No states is an error and sends nothing.
+     */
+    evaluateBatch(states: readonly unknown[], questions: Record<string, Question>, opts?: {
+        signal?: AbortSignal;
+        concurrency?: number;
+    }): Promise<Decision[]>;
     /**
      * Emits ONE warning per degenerate question key per classifier, naming the key, and changes
      * nothing about the request. Repairing would invent option descriptions the caller did not

package/dist/classifier.js

@@ -9,6 +9,8 @@ export const DEFAULT_CLASSIFIER_MODEL = "jev-latest";
 export const DEFAULT_CLASSIFIER_API_KEY_ENV = "TYPESAFE_API_KEY";
 /** Bounds ONE request; a classifier has no loop to bound. */
 export const DEFAULT_CLASSIFIER_TIMEOUT_MS = 10_000;
+/** `evaluateBatch`: at most this many states in flight by default. */
+export const DEFAULT_BATCH_CONCURRENCY = 16;
 /** The two servable pairings, as configurations rather than six independently-choosable cells. */
 export const CLASSIFIER_BACKENDS = {
     typesafe: { baseUrl: DEFAULT_CLASSIFIER_BASE_URL, model: DEFAULT_CLASSIFIER_MODEL, apiKeyEnv: DEFAULT_CLASSIFIER_API_KEY_ENV },
@@ -45,7 +47,7 @@ export function choiceOver(instructions, items) {
     return choice(instructions, items);
 }
 /** The wire form of one question — the object itself, minus an absent `criteria`. */
-function questionWire(q) {
+export function questionWire(q) {
     switch (q.type) {
         case "noul":
             return q.criteria === undefined
@@ -362,6 +364,37 @@ export class Classifier {
         });
         return decision;
     }
+    /**
+     * The same questions over many states (SPEC §8B "Batch"). Each state goes through
+     * `evaluate`, at most `concurrency` (default 16) in flight; decisions come back in STATE
+     * order. Fails closed: the first failing state's index is named and no decisions return.
+     * No states is an error and sends nothing.
+     */
+    async evaluateBatch(states, questions, opts = {}) {
+        if (!states || states.length === 0)
+            throw new Error("classifier: no states to evaluate");
+        const limit = Math.max(1, opts.concurrency ?? DEFAULT_BATCH_CONCURRENCY);
+        const out = new Array(states.length);
+        const errs = new Array(states.length);
+        let next = 0;
+        const worker = async () => {
+            while (next < states.length) {
+                const i = next++;
+                try {
+                    out[i] = await this.evaluate(states[i], questions, opts.signal);
+                }
+                catch (e) {
+                    errs[i] = e;
+                }
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(limit, states.length) }, worker));
+        for (let i = 0; i < states.length; i++) {
+            if (i in errs)
+                throw new Error(`classifier: state ${i}: ${errText(errs[i])}`, { cause: errs[i] });
+        }
+        return out;
+    }
     // ---------------------------------------------------------------- degenerate
     /**
      * Emits ONE warning per degenerate question key per classifier, naming the key, and changes

package/dist/client.d.ts

@@ -4,7 +4,9 @@
  * Toolkit. See ../../SPEC.md §8.
  */
 import type { Toolkit } from "./toolkit.js";
-import type { ToolResult, Request, Answer } from "./types.js";
+import type { ToolHints, ToolResult, Request, Answer } from "./types.js";
+import { type PromptCacheOptions } from "./promptcache.js";
+import { type ToolTier, type ToolTierOptions } from "./tooltiers.js";
 import type { PromptInput, UnsupportedPartMode } from "./content.js";
 import type { TranslateRequest, TranslateResult } from "./translate.js";
 export type ClientStyle = "openai" | "anthropic";
@@ -12,7 +14,15 @@ export interface ClientOptions {
     baseUrl: string;
     style: ClientStyle;
     model: string;
+    /** The key, used as-is. Absent => `apiKeyEnv`, else ONLY the env var that belongs to the
+     * `baseUrl` host over https: api.openai.com -> OPENAI_API_KEY, api.anthropic.com ->
+     * ANTHROPIC_API_KEY, openrouter.ai (and subdomains) -> OPENROUTER_API_KEY. Any other host (or
+     * plain http) needs `apiKey` or `apiKeyEnv` - a key is never sent to a host it does not belong
+     * to (SPEC 4C). Never logged. */
     apiKey?: string;
+    /** The NAME of the env var to read the key from when `apiKey` is absent - for a host not in
+     * the table above. Read at call time; the value is never logged. */
+    apiKeyEnv?: string;
     headers?: Record<string, string>;
     systemPrompt?: string;
     maxTurns?: number;
@@ -53,7 +63,19 @@ export interface ClientOptions {
      * Replaying the leaf's stored transcript instead is DEFERRED to its own change; it would not
      * remove this requirement anyway.
      */
-    waitFor?: (request: Request) => Promise<Answer>;
+    /** The second argument carries the turn's abort signal (SPEC 4C), so a pending ask can end
+     * when the turn is cancelled: settle once `ctx.signal` aborts. */
+    waitFor?: (request: Request, ctx: {
+        signal: AbortSignal;
+    }) => Promise<Answer>;
+    /** Prompt caching (SPEC 8): anthropic `cache_control` breakpoints on the last tool, the system
+     * prompt and the latest message; openai `prompt_cache_key`. Applied before `requestParams`
+     * and `bodyTransform`, so both can still override it. Absent => body byte-identical. */
+    promptCache?: PromptCacheOptions;
+    /** Tool tiers (SPEC 8): send only core tool schemas plus a `tool_search` tool that loads the
+     * rest on demand (and `call_tool`). The plan is frozen per toolkit until `resetToolTiers`.
+     * Absent => every tool is sent, as before. */
+    toolTiers?: ToolTierOptions;
     /** §8 Gap 1. Extra top-level keys shallow-merged into EVERY LLM body after the client builds
      * its own — a requestParams key WINS on collision (e.g. max_tokens overrides the anthropic
      * default). `messages`/`tools`/`stream` are forbidden here (stripped + warned) — rewrite
@@ -200,27 +222,43 @@ export interface ConversationStore {
 /** Default conversation provider — keeps transcripts in memory for the client's lifetime. */
 export declare class InMemoryConversationStore implements ConversationStore {
     private readonly map;
+    private readonly updated;
     get(id: string): Promise<any[] | undefined>;
     save(id: string, messages: any[]): Promise<void>;
+    /** Every stored conversation, newest first (ties by id ascending). */
+    list(): Promise<ConversationEntry[]>;
+    /** Remove a conversation; absent ids are not an error. */
+    delete(id: string): Promise<void>;
 }
+/** One `list()` row of a shipped conversation store. */
+export interface ConversationEntry {
+    id: string;
+    updatedAt: Date;
+}
+/** @internal Newest first, ties by id ascending (SPEC.md "Conversation memory"). */
+export declare function sortEntries(entries: ConversationEntry[]): ConversationEntry[];
 /**
  * Lifecycle hooks around the agent loop. Each may observe, and (where noted)
  * mutate or short-circuit. All may be async.
  */
+/** The `beforeLLM` hook event. */
+export interface BeforeLLMEvent {
+    messages: any[];
+    tools: any[];
+    model: string;
+    turn: number;
+}
+/** What a `beforeLLM` hook may return. `model` (non-empty) applies to that turn only. */
+export interface LLMOverride {
+    messages?: any[];
+    tools?: any[];
+    model?: string | null;
+}
 export interface Hooks {
-    /** Before each model call. Return { messages?, tools? } to replace them. */
-    beforeLLM?(ev: {
-        messages: any[];
-        tools: any[];
-        model: string;
-        turn: number;
-    }): void | {
-        messages?: any[];
-        tools?: any[];
-    } | Promise<void | {
-        messages?: any[];
-        tools?: any[];
-    }>;
+    /** Before each model call. Return { messages?, tools? } to replace them, and { model } to send a
+     * different model for THIS turn only (request body + afterLLM event); absent/null/empty keeps the
+     * configured model verbatim (SPEC §8, e.g. a ModelRouterClassifier). */
+    beforeLLM?(ev: BeforeLLMEvent): void | LLMOverride | Promise<void | LLMOverride>;
     /** After each model call (observe: logging, cost, tracing). */
     afterLLM?(ev: {
         response: any;
@@ -233,6 +271,7 @@ export interface Hooks {
         args: Record<string, unknown>;
         id?: string;
         turn: number;
+        hints?: ToolHints;
     }): void | {
         args?: Record<string, unknown>;
         result?: ToolResult;
@@ -266,6 +305,14 @@ export interface Usage {
     promptTokens: number;
     completionTokens: number;
     totalTokens: number;
+    /** Prompt tokens served from the provider's prompt cache (anthropic cache_read_input_tokens;
+     * openai prompt_tokens_details.cached_tokens). Present once a provider reports any.
+     * Under anthropic `promptTokens` EXCLUDES cached tokens: the context sent is
+     * promptTokens + cacheReadTokens + cacheWriteTokens. Under openai `promptTokens` already
+     * includes cacheReadTokens. */
+    cacheReadTokens?: number;
+    /** Tokens written to the prompt cache (anthropic cache_creation_input_tokens). */
+    cacheWriteTokens?: number;
 }
 export interface RunResult {
     text: string;
@@ -298,12 +345,15 @@ export type StreamEvent = {
     id: string;
     name: string;
     args: Record<string, unknown>;
+    via?: "call_tool";
 } | {
     type: "tool_result";
     id: string;
     name: string;
     output: string;
     isError: boolean;
+    metadata?: Record<string, unknown>;
+    via?: "call_tool";
 } | {
     type: "usage";
     usage: Usage;
@@ -314,12 +364,22 @@ export type StreamEvent = {
     type: "done";
     result: RunResult;
 };
+/**
+ * Pick the API key (SPEC 4C, security). An explicit `apiKey` is used as-is; else `apiKeyEnv`;
+ * else ONLY the env var that belongs to the `baseUrl` host. There is no cross-provider fallback:
+ * any other host needs `apiKey` or `apiKeyEnv`. The value is never logged.
+ */
+export declare function resolveKey(opts: Pick<ClientOptions, "apiKey" | "apiKeyEnv" | "baseUrl">): string;
+/** The env var whose key may be sent to `baseUrl`'s host, or "" when none may. */
+export declare function keyEnvForBaseUrl(baseUrl: string): string;
 export declare class Client {
     private readonly opts;
     /** Conversation provider for `ask()` — from opts.store, else in-memory. */
     private readonly store;
     /** Cumulative Prometheus registry fed by the same events `onMetric` sees. */
     private readonly registry;
+    /** The frozen ToolTiers plan per toolkit (SPEC 8 Tool tiers). */
+    private tierPlans;
     constructor(opts: ClientOptions);
     /**
      * §8 Gap 4. The client's conversation store — the exact instance passed in `opts.store`, else
@@ -430,6 +490,22 @@ export declare class Client {
     private llmFetch;
     /** Run one tool through beforeTool/afterTool hooks (mutate args, short-circuit, transform result). */
     private runTool;
+    private runToolDirect;
+    /** ToolTiers `call_tool {name, arguments}` -> the real call; undefined when tiers are off. */
+    private unwrapCall;
+    /** The stream's tool_call event, naming the real tool for a `call_tool` call. */
+    private callEvent;
+    private resultEvent;
+    private plan;
+    /** The tools array for a request: core tools (sorted) then tool_search and call_tool. Without
+     * tiers it is every tool, as before. */
+    private requestTools;
+    /** The frozen tier plan for `toolkit` (built on first use): tool name -> tier. Undefined when
+     * `toolTiers` is not set. For a host UI or log. */
+    toolTierPlan(toolkit: Toolkit): Record<string, ToolTier> | undefined;
+    /** Forget `toolkit`'s plan so the next request rebuilds it - call at a new session start.
+     * Mid-session it breaks the cached prefix. */
+    resetToolTiers(toolkit: Toolkit): void;
     /** 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). */