toolnexus 0.18.1 → 0.20.0

package/dist/classifier.js

@@ -1,3 +1,4 @@
+import { redactErrorBody, capErrorBody } from "./client.js";
 import { retryAfterMs, isRetryableStatus } from "./retry.js";
 // ---------------------------------------------------------------- constants
 /** The System One endpoint base. */
@@ -8,6 +9,11 @@ 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;
+/** 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 },
+    openrouter: { baseUrl: "https://openrouter.ai/api/v1", model: "typesafe/jev-1.13", apiKeyEnv: "OPENROUTER_API_KEY" },
+};
 /** Client-side cap on a choice's named options (§8B). */
 export const MAX_CHOICE_OPTIONS = 255;
 /** Bounds of a score rubric (§8B). */
@@ -261,9 +267,13 @@ export class Classifier {
     constructor(opts) {
         this.opts = opts;
         this.style = opts.style ?? "systemone";
-        this.baseUrl = opts.baseUrl ?? DEFAULT_CLASSIFIER_BASE_URL;
-        this.model = opts.model ?? DEFAULT_CLASSIFIER_MODEL;
-        this.apiKeyEnv = opts.apiKeyEnv ?? DEFAULT_CLASSIFIER_API_KEY_ENV;
+        const preset = CLASSIFIER_BACKENDS[opts.backend ?? "typesafe"];
+        this.baseUrl = opts.baseUrl ?? preset.baseUrl;
+        this.model = opts.model ?? preset.model;
+        this.apiKeyEnv = opts.apiKeyEnv ?? preset.apiKeyEnv;
+        const mismatch = backendMismatch(this.baseUrl, this.model);
+        if (mismatch)
+            throw new Error(mismatch);
         this.timeoutMs = opts.timeoutMs ?? DEFAULT_CLASSIFIER_TIMEOUT_MS;
         switch (this.style) {
             case "systemone":
@@ -433,8 +443,10 @@ export class Classifier {
         let lastErr;
         for (let attempt = 0;; attempt++) {
             const timer = new AbortController();
+            // NOT unref'd: this watchdog is the only thing that will end a request an
+            // injected `fetch` never settles, and an unref'd timer cannot keep the
+            // loop alive long enough to fire. It is cleared on every exit path below.
             const t = setTimeout(() => timer.abort(new Error(`classifier: request timeout after ${this.timeoutMs}ms`)), this.timeoutMs);
-            t.unref?.();
             const onOuter = () => timer.abort(signal.reason);
             if (signal) {
                 if (signal.aborted) {
@@ -512,7 +524,8 @@ export class Classifier {
             '{"type":"choice","choice":"<one offered option id>","probabilities":{"<every offered option id>":<0..1>},"confidence":<0..1>}. ' +
             'A "score" answer is {"type":"score","score":<a number within the rubric bounds, fractional allowed>,' +
             '"legend":{"0":"<level 0>",…},"probabilities":{"0":<0..1>,…},"confidence":<0..1>}.';
-        const run = await this.opts.client.run(prompt, { toolkit: EMPTY_TOOLKIT, signal });
+        // No toolkit at all: a classifier has no loop and executes nothing (SPEC §0.10, ADR 0023).
+        const run = await this.opts.client.run(prompt, { signal });
         const payload = firstJsonObject(run.text);
         let parsed;
         try {
@@ -579,10 +592,22 @@ export function degenerateCriteria(criteria) {
 function cause(status, body) {
     if (status === 401 || status === 403)
         return "";
-    const s = body.trim();
-    if (!s)
+    // ONE policy, now shared with the §8 client path: redact account identifiers, then cap.
+    const s = capErrorBody(redactErrorBody(body));
+    return s ? ": " + s : "";
+}
+/**
+ * The one mixture known to fail, caught before the wire: TypeSafe's unqualified `jev-*` model id
+ * pointed at the OpenRouter gateway, which has never heard of it. Returns the message to fail
+ * with, or `""` when the pairing is fine.
+ */
+export function backendMismatch(baseUrl, model) {
+    const host = baseUrl.replace(/^[a-z]+:\/\//i, "").split("/")[0].split(":")[0].toLowerCase();
+    if (host !== "openrouter.ai" && !host.endsWith(".openrouter.ai"))
+        return "";
+    if (!/^jev-/.test(model))
         return "";
-    return ": " + (s.length > 200 ? s.slice(0, 200) + "…" : s);
+    return `classifier: model "${model}" is TypeSafe's spelling; on openrouter.ai use "${CLASSIFIER_BACKENDS.openrouter.model}"`;
 }
 /** `${ENV_VAR}` expands at call time; an unset var expands to the empty string, as §2. */
 function expandEnv(value) {
@@ -611,20 +636,3 @@ function sleep(ms) {
         setTimeout(resolve, ms);
     });
 }
-/**
- * The `llm` style declares no tools — a classifier has no loop and executes nothing. The §8
- * `run` takes a Toolkit, so this is the empty one; the cast is the price of not exposing a
- * public "no tools" Toolkit constructor just for this path.
- */
-const EMPTY_TOOLKIT = {
-    skillsPrompt: () => "",
-    toOpenAI: () => [],
-    toAnthropic: () => [],
-    toGemini: () => [],
-    get: () => undefined,
-    list: () => [],
-    execute: async () => {
-        throw new Error("classifier: the llm style declares no tools");
-    },
-    close: async () => { },
-};

package/dist/client.d.ts

@@ -41,7 +41,18 @@ export interface ClientOptions {
     /** §10 Suspension resolver. When a tool returns Pending (metadata.pending), the client calls
      * this, then retries the tool with Context.answer = the resolution. Its interior is unconstrained
      * (open a browser, message a channel, watch a file, forward to another agent). Omit for a durable
-     * host: run() does not hang — it returns { status:"pending", pending:request } to resume later. */
+     * host: run() does not hang — it returns { status:"pending", pending:request } to resume later.
+     *
+     * IDEMPOTENCY CONTRACT (SPEC §7D rewind-to-checkpoint). A durable resume REPLAYS the suspended
+     * turn from its PRE-TURN checkpoint: "continues from its checkpoint" means the transcript is
+     * REWOUND, not carried. EVERY tool that ran in that turn RUNS AGAIN, and the suspended tool
+     * itself is always re-executed (with `ctx.answer`) — that is §10's resolution mechanism, not a
+     * bug. Reattachment by task key makes a re-run `task` call idempotent; a leaf agent's own
+     * side-effecting tools (`git push`, a charge, a delete) have NO equivalent and are the host's
+     * responsibility. Any tool reachable in a suspendable turn must be idempotent.
+     * 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>;
     /** §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
@@ -68,6 +79,60 @@ export interface ClientOptions {
      * text placeholder. Unset ⇒ attached parts error, derived parts degrade. */
     onUnsupportedPart?: UnsupportedPartMode;
 }
+/**
+ * The §8 CLIENT status vocabulary, as a value. It is a DIFFERENT, smaller closed set than the
+ * §7D AGENT vocabulary (`agents.TASK_STATUSES`), which also contains `"timeout"`, `"closed"`,
+ * `"interrupted"` and `"error"`. Two fields are called `status`; they are not interchangeable.
+ * A run that fails at a deadline THROWS here — it never comes back as a `RunResult`.
+ */
+export declare const RUN_STATUSES: readonly ["done", "pending", "incomplete"];
+export type RunStatus = (typeof RUN_STATUSES)[number];
+/** Account-identifier keys blanked out of a provider error body before it reaches a message,
+ *  a log or a metric. The shape survives; the value does not (ADR 0027 D3.2). */
+export declare const REDACTED_BODY_KEYS: readonly ["user_id", "account_id", "org_id", "organization"];
+/** What a redacted value is replaced with — identical in all seven ports. */
+export declare const REDACTION_PLACEHOLDER = "\u00ABredacted\u00BB";
+/** A redacted body is capped at this many characters IN THE MESSAGE ONLY. The typed `body`
+ *  field carries the full redacted body — a host that opted into a typed error asked for the
+ *  whole thing (ADR 0027 D3 / addendum A5). */
+export declare const ERROR_BODY_CAP = 200;
+/**
+ * Redact known account identifiers, then cap. A CAP IS NOT REDACTION: the body that leaked
+ * `user_2…` in issue #92 was 96 bytes, well inside the cap, so both steps are needed and
+ * redaction runs FIRST (capping first could split a key/value pair and hide it from the regex).
+ */
+export declare function redactErrorBody(body: string): string;
+/** Cap a already-redacted body for interpolation into a MESSAGE. Redaction is not a cap and a
+ *  cap is not redaction: they are independent and both are needed. */
+export declare function capErrorBody(body: string): string;
+/**
+ * A provider failure carried as a VALUE, not a sentence (ADR 0027 D3.1). A host that must
+ * decide what to log can read `status` / `retryAfter` instead of parsing a message.
+ *
+ * `body` is ALREADY redacted and capped, and is `""` on 401/403 — an auth body routinely
+ * reflects the credential or the header that was sent. `rawBody` is never populated by the
+ * library; the SPEC credentials guarantee now covers error messages too.
+ */
+export declare class LlmHttpError extends Error {
+    /** The HTTP status the provider answered with. */
+    readonly status: number;
+    /** The provider's FULL redacted body; `""` on 401/403 and when empty. Uncapped — the cap
+     *  applies to `message` only. */
+    readonly body: string;
+    /** The `Retry-After` header verbatim, when the provider sent one. */
+    readonly retryAfter?: string | undefined;
+    readonly name = "LlmHttpError";
+    constructor(
+    /** The HTTP status the provider answered with. */
+    status: number, 
+    /** The provider's FULL redacted body; `""` on 401/403 and when empty. Uncapped — the cap
+     *  applies to `message` only. */
+    body: string, 
+    /** The `Retry-After` header verbatim, when the provider sent one. */
+    retryAfter?: string | undefined);
+}
+/** Build the typed error from a non-2xx provider response (reads the body once). */
+export declare function llmHttpError(res: Response): Promise<LlmHttpError>;
 /** §8 Resilience. What to do with a failed LLM call. */
 export type ErrorTier = "retry" | "fail";
 /** §8 Resilience. Context passed to `onError` for each failed LLM attempt. */
@@ -284,8 +349,14 @@ export declare class Client {
     private endRun;
     /** Emit a `run` error metric event (once, on a thrown run). */
     private emitRunError;
-    run(prompt: PromptInput, ctx: {
-        toolkit: Toolkit;
+    /**
+     * Run the loop. `ctx` — and `ctx.toolkit` inside it — are OPTIONAL: an absent toolkit is a
+     * COMPLETION (SPEC §0.10). The system message is then the system prompt alone, and the
+     * request body carries no `tools` and no `tool_choice` key (not an empty array). An empty
+     * toolkit and no toolkit are observably identical on the wire.
+     */
+    run(prompt: PromptInput, ctx?: {
+        toolkit?: Toolkit;
         signal?: AbortSignal;
         history?: any[];
     }): Promise<RunResult>;
@@ -317,15 +388,15 @@ export declare class Client {
      * the answer — so the next `ask` with the same `id` continues it. Without an
      * `id` it is a stateless one-shot (identical to `run`).
      */
-    ask(prompt: PromptInput, ctx: {
-        toolkit: Toolkit;
+    ask(prompt: PromptInput, ctx?: {
+        toolkit?: Toolkit;
         id?: string;
         on_text?: (delta: string) => void;
         signal?: AbortSignal;
     }): Promise<RunResult>;
     /** A stateful multi-turn conversation that retains history across sends. */
-    conversation(ctx: {
-        toolkit: Toolkit;
+    conversation(ctx?: {
+        toolkit?: Toolkit;
         signal?: AbortSignal;
     }): Conversation;
     /**
@@ -333,13 +404,25 @@ export declare class Client {
      * With an `id`, it is stateful (like `ask`): the thread's transcript is loaded as history before
      * streaming, and saved back to the ConversationStore on the terminal `done` event. No `id` ⇒ stateless.
      */
-    stream(prompt: PromptInput, ctx: {
-        toolkit: Toolkit;
+    stream(prompt: PromptInput, ctx?: {
+        toolkit?: Toolkit;
         id?: string;
         signal?: AbortSignal;
     }): AsyncGenerator<StreamEvent, void, unknown>;
+    /** §0.10 system message. The toolkit is OPTIONAL — with none there is no skills prompt and
+     *  the system message is the system prompt alone. This deref was issue #86 (ADR 0023). */
     private system;
-    /** Build a run-scoped abort signal from the optional run-level timeout + an external signal. */
+    /** Run-scoped timeout timers, cleared by `releaseSignal` when the run settles. */
+    private readonly runTimers;
+    /** Drop a run's timeout timer. Idempotent, and safe on a signal that never had one. */
+    private releaseSignal;
+    /** Build a run-scoped abort signal from the optional run-level timeout + an external signal.
+     *
+     * The timer is deliberately NOT `unref()`d. An unref'd timer cannot keep the event loop
+     * alive, so a run whose only pending work is a request that never settles — an injected
+     * `fetch`, an in-process transport, a stalled stream — drains the loop and the timeout never
+     * fires at all, which is the one case `timeoutMs` exists for. It is RELEASED instead: the
+     * caller clears it however the run leaves, so a finished run holds nothing open. */
     private makeSignal;
     /** fetch with retry + exponential backoff on the default retryable set (429/500/502/503/504/529)
      * plus network errors and anything `retryableStatuses` added, honoring Retry-After; aborts via signal.
@@ -352,6 +435,10 @@ export declare class Client {
     /** One non-streaming LLM call, with an `llm` metric event (ok/error + per-call tokens + ms). */
     private llmCallJson;
     private runOpenAI;
+    private runAnthropic;
+    private streamOpenAI;
+    private streamAnthropic;
+    private runOpenAIWithSignal;
     private result;
     /** §10: a run halted because a tool suspended and no `waitFor` was configured. */
     private pendingRun;
@@ -361,9 +448,9 @@ export declare class Client {
      * no `waitFor` is configured (the run should stop and surface the request).
      */
     private resolvePending;
-    private runAnthropic;
-    private streamOpenAI;
-    private streamAnthropic;
+    private runAnthropicWithSignal;
+    private streamOpenAIWithSignal;
+    private streamAnthropicWithSignal;
 }
 export declare function createClient(opts: ClientOptions): Client;
 /** One tool call an in-process model asks for. Flat on purpose: the nested
@@ -400,6 +487,17 @@ export type InProcessOptions = Omit<ClientOptions, "baseUrl" | "apiKey" | "style
     /** Your model. Receives the assembled request, returns one assistant message. */
     generate: (request: InProcessRequest) => InProcessResponse | Promise<InProcessResponse>;
 };
+/**
+ * Build a `fetch`-shaped adapter over a semantic `generate` function (ADR 0030):
+ * the reusable piece of {@link createInProcessClient} — assembles the wire request,
+ * calls `generate`, and re-encodes its answer as an OpenAI-shaped `Response`. Every
+ * caller that wants an in-process model behind a `fetch` slot (the top-level client,
+ * 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.
+ */
+export declare function createInProcessFetch(generate: (request: InProcessRequest) => InProcessResponse | Promise<InProcessResponse>): typeof fetch;
 /**
  * A client backed by a model running IN THIS PROCESS — no server, no socket, and no
  * HTTP types to construct.
@@ -407,18 +505,20 @@ export type InProcessOptions = Omit<ClientOptions, "baseUrl" | "apiKey" | "style
  * This is a second constructor, not a second seam: it builds on the same injectable
  * transport that `fetch`/`httpClient` uses, so the tool-calling loop, MCP servers,
  * skills, sub-agents, hooks, metrics and the completion gate all behave identically.
+ * 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 the thrown error.
+ * Streaming is refused rather than faked — see {@link createInProcessFetch}.
  */
 export declare function createInProcessClient(opts: InProcessOptions): Client;
 /** Stateful multi-turn conversation: each send() continues the same transcript (memory). */
 export declare class Conversation {
     private readonly client;
-    private readonly toolkit;
+    private readonly toolkit?;
     private readonly signal?;
     /** Full running transcript (system + user + assistant + tool messages). */
     messages: any[];
-    constructor(client: Client, toolkit: Toolkit, signal?: AbortSignal | undefined);
+    constructor(client: Client, toolkit?: Toolkit | undefined, signal?: AbortSignal | undefined);
     /** Send the next user turn; prior history is retained automatically. */
     send(prompt: PromptInput): Promise<RunResult>;
     /** Reset the conversation memory. */