toolnexus 0.19.0 → 0.21.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/home.js

@@ -188,9 +188,11 @@ export function startAgent(a, run, hb) {
                 });
             }
         }
-        cancel = runtime.clock.setTimeout(beat, hb.everyMs); // self-reschedule → one live timer
+        // keepAlive:false — a heartbeat is housekeeping and must never be the reason
+        // a host process stays up.
+        cancel = runtime.clock.setTimeout(beat, hb.everyMs, { keepAlive: false }); // self-reschedule → one live timer
     };
-    cancel = runtime.clock.setTimeout(beat, hb.everyMs);
+    cancel = runtime.clock.setTimeout(beat, hb.everyMs, { keepAlive: false });
     return {
         runtime,
         beats,

package/dist/agents/runtime.d.ts

@@ -22,10 +22,19 @@ import type { Answer, Request, Tool } from "../types.js";
 export interface Clock {
     /** Current time in ms (epoch or virtual). */
     now(): number;
-    /** Schedule `fn` after `ms`; returns a cancel function. */
-    setTimeout(fn: () => void, ms: number): () => void;
+    /** Schedule `fn` after `ms`; returns a cancel function.
+     *
+     * `keepAlive` defaults to TRUE, and the default is the important half: a timer
+     * that cannot hold the event loop open never fires when it is the only thing
+     * left to do — which is precisely a deadline whose promise nothing else will
+     * settle. Background housekeeping that should never hold a process open (a
+     * heartbeat) passes `false` explicitly. A host's own Clock may ignore the
+     * option; it then behaves as that host's timers always have. */
+    setTimeout(fn: () => void, ms: number, opts?: {
+        keepAlive?: boolean;
+    }): () => void;
 }
-/** The real clock (default). Timers are unref'd so they never hold the process open. */
+/** The real clock (default). See `Clock.setTimeout` for why `keepAlive` defaults to true. */
 export declare const systemClock: Clock;
 /** §7D hierarchical budget. Carved at spawn (`min(own, parent remaining)`) and
  * live-enforced against the whole ancestor chain before each turn and spawn.

package/dist/agents/runtime.js

@@ -2,12 +2,13 @@ import { createClient, createInProcessFetch, InMemoryConversationStore, } from "
 import { runGated } from "./loop.js";
 import { createToolkit } from "../toolkit.js";
 import { defineTool } from "../native.js";
-/** The real clock (default). Timers are unref'd so they never hold the process open. */
+/** The real clock (default). See `Clock.setTimeout` for why `keepAlive` defaults to true. */
 export const systemClock = {
     now: () => Date.now(),
-    setTimeout(fn, ms) {
+    setTimeout(fn, ms, opts) {
         const t = setTimeout(fn, ms);
-        t.unref?.();
+        if (opts?.keepAlive === false)
+            t.unref?.();
         return () => clearTimeout(t);
     },
 };

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 {};