toolnexus 0.20.0 → 0.22.0

package/README.md

@@ -49,6 +49,46 @@ const tk = await createToolkit({ mcp: "mcp.json", skills: ["skills"] })
 - `skills/` is a folder of `**/SKILL.md` files, loaded on demand through one `skill` tool.
 - Remote MCP `headers` values expand `${ENV_VAR}` at call time and are never logged.
 
+## Simple judgments
+
+A thin layer over any `Classifier` (SPEC.md §8B); the wire request is byte-identical to
+hand-written maps.
+
+```ts
+import { createClassifier, judge, State, ask, gate } from "toolnexus"
+
+const c = createClassifier() // reads TYPESAFE_API_KEY by name at call time
+const d = await ask(c, State("You are Donkey Kong, you want to win.", { message_received: "jump off the stage" }), [
+  judge.noul("is_appropriate", "Does `message_received` contain inappropriate language?"),
+  judge.noul("does_this_help", "Does `message_received` help donkey kong win?"),
+])
+d.is_appropriate.band    // "yes" | "no" | "uncertain"   (cut-points 0.30 / 0.70, exclusive)
+d.does_this_help.value() // the one number
+
+const out = await gate(c, state, questions, [
+  { question: "fixable", below: 0.3, action: "fail" },
+  { question: "component", is: "pricing", action: "skip_to", target: "fix-pricing" },
+])
+// unsure or missing answer -> { action: "needs_input", escalated: true, request: <§10 input Request> }
+```
+
+- The role goes in the state (`State(role, data)`), never into question text; each question
+  names the state field it judges.
+- `decide(c, state, questions, { rules, default, bands, skipUncertain })` — a `Policy` with a
+  declared fall-through (empty `default` escalates "no rule fired").
+- `new Tape(live).classifier("plan")` records; `Tape.replay(entries).classifier("plan")` replays offline.
+- `staticClassifier(recorded)` — one-line hermetic classifier; `c.evaluateBatch(states, questions)`
+  — same questions over many states, in order, fail-closed, 16 in flight.
+- JS naming: the named builders live under `judge.` (bare `noul/choice/score` stay the §8B wire
+  builders); a choice answer keeps its `choice` string field, so the picked-option method is `pick()`.
+- Batteries (§8B *Batteries*): `ToolGuardClassifier`, `ToolRelevanceClassifier`,
+  `SkillRelevanceClassifier`, `ToolResultFilterClassifier`, `IsCompleteClassifier`,
+  `ContentGuardClassifier` (all take a required `onError: "open" | "closed"`),
+  `AgentRouterClassifier` and the opt-in `ModelRouterClassifier(c, [{ id, description }])`.
+  Methods `check` / `select` / `filter` / `pick`; `asHook(next?)` plugs the guard, relevance,
+  filter, content and model batteries into `hooks`. A `beforeLLM` hook may return `{ model }` to
+  send another model for that turn only.
+
 ## Documentation
 
 Everything else — the full surface, with runnable examples — lives on the docs site:

package/dist/agents/agent.d.ts

@@ -8,7 +8,7 @@
  * Everything compiles down to the six host verbs in runtime.ts.
  */
 import type { PromptInput } from "../content.js";
-import type { Answer, Request, Tool } from "../types.js";
+import type { Answer, Request, Tool, ToolContext } from "../types.js";
 import { AgentRuntime, type AgentDef, type Budget, type RuntimeOptions, type TaskResult } from "./runtime.js";
 import { Loop, type Completion, type Guardrail } from "./loop.js";
 import type { ClientOptions } from "../client.js";
@@ -93,6 +93,8 @@ export declare class Agent {
      * case the tree stays parked and `result.runtime.resume(answer)` continues it.
      */
     run(prompt: PromptInput, opts?: AgentRunOptions): Promise<AgentRunResult>;
+    /** `run` that interrupts the child when `signal` aborts. */
+    private runSignal;
     /**
      * The bridge: an Agent IS a Tool. Drop the result into the classic API's
      * `extraTools`; the agent's own loop runs in isolation and the classic run
@@ -100,6 +102,15 @@ export declare class Agent {
      * `{agent, turns, totalTokens}`.
      */
     asTool(opts?: AgentRunOptions): Tool;
+    /**
+     * `asTool` with options built per call from the calling tool's context (SPEC §4C), so the
+     * child runs under the parent turn's gates: set `hooks` (the same beforeTool permission gate —
+     * it also sees the child's tool calls), `waitFor` (the same ask bridge) and `onMetric`. A
+     * `hooks` on the agent's own spec replaces `opts.hooks` for that agent, so leave it unset when
+     * the gate must hold. When the calling turn is cancelled (`ctx.signal`), the child is
+     * interrupted and the tool returns a `cancelled:` error result.
+     */
+    asToolWith(per: (ctx?: ToolContext) => AgentRunOptions): Tool;
 }
 /** The one new noun: define an agent. */
 export declare function agent(name: string, spec: AgentSpec): Agent;

package/dist/agents/agent.js

@@ -73,6 +73,32 @@ export class Agent {
             await runtime.close(runtime.root);
         return { ...r, runtime };
     }
+    /** `run` that interrupts the child when `signal` aborts. */
+    async runSignal(prompt, opts, signal) {
+        if (!signal)
+            return this.run(prompt, opts);
+        const reason = () => (signal.reason instanceof Error ? signal.reason.message : String(signal.reason ?? "aborted"));
+        if (signal.aborted)
+            return { text: reason(), isError: true, turns: 0, totalTokens: 0, cancelled: true };
+        const runtime = this.createRuntime(opts);
+        const h = runtime.spawn(runtime.root, this.name);
+        if (isVerbError(h))
+            return { text: h.error, isError: true, turns: 0, totalTokens: 0 };
+        const onAbort = () => void runtime.close(runtime.root, { force: true }).catch(() => { });
+        signal.addEventListener("abort", onAbort, { once: true });
+        try {
+            const woke = runtime.wake(h, prompt);
+            const r = await runtime.wait(h);
+            if (signal.aborted)
+                return { text: reason(), isError: true, turns: r.turns, totalTokens: r.totalTokens, cancelled: true };
+            if (woke.ok && r.status !== "pending")
+                await runtime.close(runtime.root);
+            return r;
+        }
+        finally {
+            signal.removeEventListener("abort", onAbort);
+        }
+    }
     /**
      * The bridge: an Agent IS a Tool. Drop the result into the classic API's
      * `extraTools`; the agent's own loop runs in isolation and the classic run
@@ -80,6 +106,17 @@ export class Agent {
      * `{agent, turns, totalTokens}`.
      */
     asTool(opts = {}) {
+        return this.asToolWith(() => opts);
+    }
+    /**
+     * `asTool` with options built per call from the calling tool's context (SPEC §4C), so the
+     * child runs under the parent turn's gates: set `hooks` (the same beforeTool permission gate —
+     * it also sees the child's tool calls), `waitFor` (the same ask bridge) and `onMetric`. A
+     * `hooks` on the agent's own spec replaces `opts.hooks` for that agent, so leave it unset when
+     * the gate must hold. When the calling turn is cancelled (`ctx.signal`), the child is
+     * interrupted and the tool returns a `cancelled:` error result.
+     */
+    asToolWith(per) {
         return defineTool({
             name: this.name,
             description: this.spec.does,
@@ -88,13 +125,12 @@ export class Agent {
                 properties: { prompt: { type: "string", description: "The task for this agent" } },
                 required: ["prompt"],
             },
-            run: async (args) => {
-                const r = await this.run(String(args.prompt), opts);
-                return {
-                    output: r.text,
-                    isError: r.isError,
-                    metadata: { agent: this.name, turns: r.turns, totalTokens: r.totalTokens },
-                };
+            run: async (args, ctx) => {
+                const r = await this.runSignal(String(args.prompt), per(ctx), ctx?.signal);
+                const metadata = { agent: this.name, turns: r.turns, totalTokens: r.totalTokens };
+                if (r.cancelled)
+                    return { output: `cancelled: ${r.text}`, isError: true, metadata };
+                return { output: r.text, isError: r.isError, metadata };
             },
         });
     }

package/dist/agents/compaction.d.ts

@@ -32,6 +32,25 @@ export interface CompactorOptions {
      * default. Composes with the memory builtin.
      */
     flushToMemory?: boolean;
+    /**
+     * Called after each compaction with what changed, so a host can tell its UI or log (SPEC §4C).
+     * Never called on a no-op. Awaited before the next model call.
+     */
+    onCompact?: (info: CompactInfo) => void | Promise<void>;
+}
+/** One compaction, for {@link CompactorOptions.onCompact}. Token counts come from `countTokens`. */
+export interface CompactInfo {
+    tokensBefore: number;
+    tokensAfter: number;
+    messagesBefore: number;
+    messagesAfter: number;
+    /** How many messages were folded into the summary. */
+    summarized: number;
+    /** The text `summarize` returned (without the header line). */
+    summary: string;
+    /** The summarized messages, verbatim, so a host can persist them (the loop saves only the
+     * compacted transcript). */
+    folded: Message[];
 }
 /** The event a `beforeLLM` hook receives (§8). */
 export interface BeforeLLMEvent {

package/dist/agents/compaction.js

@@ -89,7 +89,8 @@ export function compactor(opts) {
     const keepTail = opts.keepTail ?? Math.floor(opts.maxTokens / 2);
     return async (ev) => {
         const msgs = ev.messages;
-        if (count(msgs) <= opts.maxTokens)
+        const before = count(msgs);
+        if (before <= opts.maxTokens)
             return undefined; // under budget → no-op
         // Preserve a leading system prompt verbatim (identity / soul / skills — never summarized).
         const headEnd = msgs[0]?.role === "system" ? 1 : 0;
@@ -97,16 +98,37 @@ export function compactor(opts) {
         const split = findTailStart(msgs, headEnd, keepTail, count);
         if (split <= headEnd)
             return undefined; // nothing safely compactible
-        const older = msgs.slice(headEnd, split);
+        let older = msgs.slice(headEnd, split);
+        const tail = msgs.slice(split);
+        // The latest user prompt is never summarized away. When the only clean boundary is the first
+        // message after the system prompt (one prompt followed by a long agentic run), keep that
+        // prompt verbatim and summarize the work after it: [system, prompt, summary].
+        let pinned = [];
+        if (split === msgs.length && headEnd < msgs.length && isBoundary(msgs[headEnd])) {
+            pinned = msgs.slice(headEnd, headEnd + 1);
+            older = msgs.slice(headEnd + 1);
+        }
         if (older.length === 0)
             return undefined;
-        const tail = msgs.slice(split);
         const flushNote = opts.flushToMemory
             ? [{ role: "system", content: FLUSH_TO_MEMORY_REMINDER }]
             : [];
         const summary = await opts.summarize(older);
         const summaryMsg = { role: "system", content: `${SUMMARY_PREFIX}${summary}` };
-        return { messages: [...system, summaryMsg, ...flushNote, ...tail] };
+        const out = [...system, ...pinned, summaryMsg, ...flushNote, ...tail];
+        const after = count(out);
+        if (after >= before)
+            return undefined; // compaction would not shrink the transcript → no-op
+        await opts.onCompact?.({
+            tokensBefore: before,
+            tokensAfter: after,
+            messagesBefore: msgs.length,
+            messagesAfter: out.length,
+            summarized: older.length,
+            summary,
+            folded: older,
+        });
+        return { messages: out };
     };
 }
 /**

package/dist/agents/runtime.d.ts

@@ -293,6 +293,11 @@ export interface RuntimeOptions {
     /** §8 observability sink applied to EVERY agent's client, unless that agent's def
      * sets its own `onMetric`. Resolves independently of `hooks`. Forwarded verbatim. */
     onMetric?: (ev: MetricEvent) => void;
+    /** The runtime-level §10 interpreter (SPEC §4C): answers a suspension when no agent on the
+     * handle's chain has its own `waitFor`. Absent ⇒ unchanged (the suspension goes durable). A
+     * host running an agent as a tool (`asToolWith`) sets it so the child's asks reach the same
+     * bridge as the parent turn. */
+    waitFor?: (request: Request) => Promise<Answer>;
 }
 /**
  * The §7D agent runtime: six host verbs over a tree of Handles, three loud

package/dist/agents/runtime.js

@@ -595,12 +595,23 @@ export class AgentRuntime {
      * escalation traced (nearest interpreter wins; the Request's `data.path` names
      * the suspended subtree that is asking). */
     wrapWaitFor(h) {
-        const waitFor = h.def.waitFor;
+        const own = h.def.waitFor;
+        let waitFor = own;
+        if (!waitFor && this.opts.waitFor) {
+            // The runtime-level bridge answers only when NO agent on the chain has its own waitFor;
+            // otherwise the ask escalates to that nearest interpreter, as before.
+            let a = h.parent;
+            while (a && !a.def.waitFor)
+                a = a.parent;
+            if (!a)
+                waitFor = this.opts.waitFor;
+        }
         if (!waitFor)
             return undefined;
+        const answerer = own ? h.id : this.root.id;
         return async (req) => {
             const path = Array.isArray(req.data?.path) ? req.data.path.join("/") : h.id;
-            this.t(`${path}: escalate → ${h.id} answers ("nearest interpreter")`);
+            this.t(`${path}: escalate → ${answerer} answers ("nearest interpreter")`);
             return waitFor(req);
         };
     }

package/dist/batteries.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Judge batteries (SPEC.md §8B "Batteries", change `add-judge-batteries`, ADR 0035 D3): eight
+ * `*Classifier` values built on the simple-judgment layer (`judge.ts`). Each has a standalone
+ * method returning a typed verdict and, where a seam exists, `asHook(next?)`. They are advisory:
+ * nothing here is a security control. Default role and question text is contract, pinned
+ * byte-for-byte by `examples/judge/batteries/`.
+ *
+ * A classifier error never propagates from a standalone method: the verdict carries `error` (the
+ * message) and `calibrated: false`.
+ */
+import type { Classifier } from "./classifier.js";
+import { type Bands } from "./judge.js";
+import type { Hooks } from "./client.js";
+/** The host's required decision for a classifier error. */
+export type OnError = "open" | "closed";
+/** Default role sentences (contract). */
+export declare const ROLE_TOOL_GUARD = "You review one tool call an AI agent is about to make and rate how risky it is to run it without a human approving it.";
+export declare const ROLE_TOOL_RELEVANCE = "You decide which tools an AI agent needs for the user's request, so the tools it does not need can be left out.";
+export declare const ROLE_SKILL_RELEVANCE = "You decide which agent skills are relevant to the user's request, so the skills it does not need can be left out.";
+export declare const ROLE_TOOL_RESULT_FILTER = "You decide which parts of a tool's output are relevant to the query, so the irrelevant parts can be dropped.";
+export declare const ROLE_IS_COMPLETE = "You check whether an AI agent's final answer completes the task it was given.";
+export declare const ROLE_AGENT_ROUTER = "You route a task to the agent best suited to do it.";
+export declare const ROLE_CONTENT_GUARD = "You screen text that is about to enter or leave an AI agent.";
+export declare const ROLE_MODEL_ROUTER = "You pick the cheapest model that can handle the user's request well.";
+type BeforeLLMHook = NonNullable<Hooks["beforeLLM"]>;
+type BeforeToolHook = NonNullable<Hooks["beforeTool"]>;
+type AfterToolHook = NonNullable<Hooks["afterTool"]>;
+/** Common options. `bands` defaults to 0.30 / 0.70; `role` overrides the default role sentence. */
+export interface BatteryOptions {
+    bands?: Bands;
+    role?: string;
+}
+/** Options for a battery whose error outcome is a policy choice: `onError` is REQUIRED. */
+export interface PolicyBatteryOptions extends BatteryOptions {
+    onError: OnError;
+}
+/** What ToolGuard rates. */
+export interface GuardedCall {
+    name: string;
+    arguments?: Record<string, unknown>;
+    description?: string;
+}
+export interface ToolGuardOptions extends PolicyBatteryOptions {
+    /** Default 1.5. */
+    askAt?: number;
+    /** Default 2.5. */
+    denyAt?: number;
+}
+export interface ToolGuardVerdict {
+    action: "allow" | "ask" | "deny";
+    /** `low risk` | `medium risk` | `high risk` | `uncertain` | `missing answer` | `classifier error`. */
+    reason: string;
+    risk: number | null;
+    sure: boolean;
+    calibrated: boolean;
+    error?: string;
+}
+/** The default 4-level risk rubric (contract). */
+export declare const RISK_RUBRIC: readonly string[];
+/** Rates one tool call's risk: allow | ask | deny. Thresholds are compared in code. */
+export declare class ToolGuardClassifier {
+    private readonly classifier;
+    private readonly opts;
+    private readonly onError;
+    private readonly askAt;
+    private readonly denyAt;
+    constructor(classifier: Classifier, opts: ToolGuardOptions);
+    check(call: GuardedCall): Promise<ToolGuardVerdict>;
+    /**
+     * A `beforeTool` hook: allow delegates to `next`; deny short-circuits with an error result; ask
+     * short-circuits with a §10 `approval` Request (path B). `next` is not called on deny or ask.
+     */
+    asHook(next?: BeforeToolHook): BeforeToolHook;
+}
+/** A named, described candidate (a tool or a skill). */
+export interface Item {
+    name: string;
+    description?: string;
+}
+export interface RelevanceVerdict {
+    selected: string[];
+    dropped: string[];
+    calibrated: boolean;
+    error?: string;
+}
+/** Drops the tools the classifier is confident a request does not need. */
+export declare class ToolRelevanceClassifier {
+    private readonly r;
+    constructor(classifier: Classifier, opts: PolicyBatteryOptions);
+    select(prompt: string, tools: readonly Item[]): Promise<RelevanceVerdict>;
+    /**
+     * A `beforeLLM` hook judging the latest user text: overrides `tools` (the kept provider entries,
+     * original order) only when it dropped one. No text or no tools ⇒ plain delegation.
+     */
+    asHook(next?: BeforeLLMHook): BeforeLLMHook;
+}
+/**
+ * Drops the skills the classifier is confident a request does not need. No hook: feed `selected`
+ * into the S2 skill allowlist — and never pass an EMPTY `selected` (empty ⇒ all).
+ */
+export declare class SkillRelevanceClassifier {
+    private readonly r;
+    constructor(classifier: Classifier, opts: PolicyBatteryOptions);
+    select(prompt: string, skills: readonly Item[]): Promise<RelevanceVerdict>;
+}
+export interface FilterVerdict {
+    kept: number[];
+    dropped: number[];
+    calibrated: boolean;
+    error?: string;
+}
+/** Keeps the chunks of a tool's output not confidently irrelevant to the query. */
+export declare class ToolResultFilterClassifier {
+    private readonly classifier;
+    private readonly opts;
+    private readonly onError;
+    constructor(classifier: Classifier, opts: PolicyBatteryOptions);
+    /** `query` is a string or an object. Indices in order. */
+    filter(query: unknown, chunks: readonly string[]): Promise<FilterVerdict>;
+    /**
+     * An `afterTool` hook: a non-error text result with >= 2 `"\n\n"` chunks (and no non-text
+     * parts) keeps only the relevant chunks. `next` sees the filtered result; its override wins.
+     */
+    asHook(next?: AfterToolHook): AfterToolHook;
+}
+export interface CompleteVerdict {
+    complete: boolean;
+    p: number | null;
+    band: "yes" | "no" | "uncertain";
+    calibrated: boolean;
+    error?: string;
+}
+/** Whether an agent's final answer completes its task. No hook (ADR 0035). */
+export declare class IsCompleteClassifier {
+    private readonly classifier;
+    private readonly opts;
+    private readonly onError;
+    constructor(classifier: Classifier, opts: PolicyBatteryOptions);
+    check(task: string, answer: string): Promise<CompleteVerdict>;
+}
+/** An agent, or a group of agents when `agents` is non-empty. */
+export interface AgentNode {
+    name: string;
+    description: string;
+    agents?: AgentNode[];
+}
+export interface AgentVerdict {
+    agent: string;
+    path: string[];
+    sure: boolean;
+    probabilities: Record<string, number> | null;
+    calibrated: boolean;
+    error?: string;
+}
+/** Routes a task through the host's agent tree, one choice per level. No hook: the host dispatches. */
+export declare class AgentRouterClassifier {
+    private readonly classifier;
+    private readonly opts;
+    constructor(classifier: Classifier, opts?: BatteryOptions);
+    /** An unsure, missing or failed level returns `fallback`. */
+    pick(task: string, agents: readonly AgentNode[], fallback: string): Promise<AgentVerdict>;
+}
+/** One ContentGuard question. */
+export interface Dimension {
+    name: string;
+    instructions: string;
+}
+/** The default dimensions (contract). */
+export declare const DEFAULT_DIMENSIONS: readonly Dimension[];
+export interface ContentGuardOptions extends PolicyBatteryOptions {
+    dimensions?: Dimension[];
+}
+export interface ContentVerdict {
+    action: "allow" | "review" | "block";
+    flagged: string[];
+    uncertain: string[];
+    scores: Record<string, number>;
+    calibrated: boolean;
+    error?: string;
+}
+/** Screens text: any yes ⇒ block; else any uncertain/missing ⇒ review; else allow. */
+export declare class ContentGuardClassifier {
+    private readonly classifier;
+    private readonly opts;
+    private readonly onError;
+    private readonly dimensions;
+    constructor(classifier: Classifier, opts: ContentGuardOptions);
+    check(text: string): Promise<ContentVerdict>;
+    /** A `beforeLLM` hook on the latest user text: block throws; allow and review delegate to `next`. */
+    asHook(next?: BeforeLLMHook): BeforeLLMHook;
+}
+/** One user-supplied model: an id and a prose description of what it is good for (ADR 0021). */
+export interface ModelOption {
+    id: string;
+    description: string;
+}
+export interface ModelVerdict {
+    model: string;
+    routed: boolean;
+    sure: boolean;
+    probabilities: Record<string, number> | null;
+    calibrated: boolean;
+    error?: string;
+}
+/**
+ * OPT-IN per-query model routing (SPEC §8 "Right-size routing"). `models` is the user's ordered
+ * option list; anything but a sure pick falls back.
+ */
+export declare class ModelRouterClassifier {
+    private readonly classifier;
+    private readonly opts;
+    private readonly models;
+    constructor(classifier: Classifier, models: readonly ModelOption[], opts?: BatteryOptions);
+    pick(prompt: string, fallback: string): Promise<ModelVerdict>;
+    /** A `beforeLLM` hook: overrides `model` only when routed to a model other than the turn's configured one. */
+    asHook(next?: BeforeLLMHook): BeforeLLMHook;
+}
+/**
+ * The text of the last user message that has text: string content, or every `{type:"text"}` part
+ * joined with `"\n"`. A tool_result-only user message is skipped. `""` when there is none.
+ */
+export declare function latestUserText(messages: readonly any[] | undefined): string;
+export {};