toolnexus 0.16.0 → 0.18.0

package/dist/client.d.ts

@@ -5,6 +5,7 @@
  */
 import type { Toolkit } from "./toolkit.js";
 import type { ToolResult, Request, Answer } from "./types.js";
+import type { PromptInput, UnsupportedPartMode } from "./content.js";
 import type { TranslateRequest, TranslateResult } from "./translate.js";
 export type ClientStyle = "openai" | "anthropic";
 export interface ClientOptions {
@@ -16,10 +17,19 @@ export interface ClientOptions {
     systemPrompt?: string;
     maxTurns?: number;
     hooks?: Hooks;
-    /** Retries on transient LLM errors (429/5xx/network). Default 2. */
+    /** Retries on transient LLM errors (`429`/`500`/`502`/`503`/`504`/`529` + network). Default 2.
+     * Widen the status set with `retryableStatuses`. */
     retries?: number;
     /** Base backoff in ms (exponential + jitter). Default 500. */
     retryBaseMs?: number;
+    /**
+     * Extra HTTP statuses to treat as retryable, ADDED to the default set
+     * (`429`/`500`/`502`/`503`/`504`/`529`). It can only widen: a host cannot remove `429` and
+     * lose `Retry-After` handling with it. This sets the DEFAULT classification; `onError` still
+     * runs per attempt and has the final say, so `onError` returning `"fail"` overrides a status
+     * listed here. Example: a Cloudflare-fronted origin that answers `520`–`527`.
+     */
+    retryableStatuses?: readonly number[];
     /** Whole-run deadline in ms; aborts the run (and its in-flight request) when exceeded. */
     timeoutMs?: number;
     /** Conversation provider for `ask(prompt, { id })`. Default: in-memory (process lifetime).
@@ -50,6 +60,13 @@ export interface ClientOptions {
      * today. A "retry" is always bounded by `retries`; the classifier cannot loop unbounded.
      * There is no "suspend" tier — suspension (§10) stays a user-action pause, not an error path. */
     onError?: (info: ErrorInfo) => ErrorTier;
+    /** §1B. Reject a content part carrying more than this many **decoded** bytes (never the
+     * +33% base64 string). Unset ⇒ no limit, as today. */
+    maxPartBytes?: number;
+    /** §8A. Overrides the provenance rule uniformly: `"error"` fails on any part the style
+     * cannot represent (attached or tool-derived), `"text"` degrades every one of them to a
+     * text placeholder. Unset ⇒ attached parts error, derived parts degrade. */
+    onUnsupportedPart?: UnsupportedPartMode;
 }
 /** §8 Resilience. What to do with a failed LLM call. */
 export type ErrorTier = "retry" | "fail";
@@ -61,7 +78,8 @@ export interface ErrorInfo {
     status?: number;
     /** Zero-based attempt index (0 = first try). */
     attempt: number;
-    /** Whether `status`/the error is in the default retryable set (429/5xx/network). */
+    /** Whether `status`/the error is in the default retryable set
+     * (429/500/502/503/504/529/network, plus anything `retryableStatuses` added). */
     retryable: boolean;
 }
 /**
@@ -91,6 +109,18 @@ export type MetricEvent = {
     totalTokens: number;
     ms: number;
     error?: string;
+} | {
+    event: "classifier.evaluate";
+    model: string;
+    status: "ok" | "error";
+    ms: number;
+    promptTokens: number;
+    completionTokens: number;
+    error?: string;
+} | {
+    event: "classifier.warning";
+    question: string;
+    warning: string;
 };
 /**
  * Where `ask()` conversations are remembered — two methods. Ship the in-memory
@@ -243,6 +273,8 @@ export declare class Client {
     private openaiBody;
     /** §8 Gap 5. Anthropic-style body; omits tools when the tool list is empty. */
     private anthropicBody;
+    /** The §8A/§1B shaping options every wire build shares. */
+    private wireOpts;
     /** Prometheus text exposition of cumulative metrics (§8). Always valid, empty-but-valid before activity. */
     metrics(): string;
     /** Feed a semantic metric event to the built-in registry and the optional onMetric sink. */
@@ -252,7 +284,7 @@ export declare class Client {
     private endRun;
     /** Emit a `run` error metric event (once, on a thrown run). */
     private emitRunError;
-    run(prompt: string, ctx: {
+    run(prompt: PromptInput, ctx: {
         toolkit: Toolkit;
         signal?: AbortSignal;
         history?: any[];
@@ -285,7 +317,7 @@ 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: string, ctx: {
+    ask(prompt: PromptInput, ctx: {
         toolkit: Toolkit;
         id?: string;
         on_text?: (delta: string) => void;
@@ -301,7 +333,7 @@ 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: string, ctx: {
+    stream(prompt: PromptInput, ctx: {
         toolkit: Toolkit;
         id?: string;
         signal?: AbortSignal;
@@ -309,7 +341,8 @@ export declare class Client {
     private system;
     /** Build a run-scoped abort signal from the optional run-level timeout + an external signal. */
     private makeSignal;
-    /** fetch with retry + exponential backoff on 429/5xx/network, honoring Retry-After; aborts via signal.
+    /** 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.
      * The retry-vs-fail decision is the host's `onError` (default: retryable-within-budget ⇒ retry). */
     private llmFetch;
     /** Run one tool through beforeTool/afterTool hooks (mutate args, short-circuit, transform result). */
@@ -387,7 +420,7 @@ export declare class Conversation {
     messages: any[];
     constructor(client: Client, toolkit: Toolkit, signal?: AbortSignal | undefined);
     /** Send the next user turn; prior history is retained automatically. */
-    send(prompt: string): Promise<RunResult>;
+    send(prompt: PromptInput): Promise<RunResult>;
     /** Reset the conversation memory. */
     reset(): void;
 }

package/dist/client.js

@@ -1,4 +1,6 @@
 import { pendingOf } from "./types.js";
+import { isRetryableStatus, retryAfterMs } from "./retry.js";
+import { toOpenAIWire, toAnthropicWire, checkPromptParts } from "./wire.js";
 import { finishReasonFor, argsString, openAIMessagesToAnthropic, openAIToolsToAnthropic, openAIToolChoiceToAnthropic, hasSystemMessage, } from "./translate.js";
 /** Default conversation provider — keeps transcripts in memory for the client's lifetime. */
 export class InMemoryConversationStore {
@@ -11,29 +13,6 @@ export class InMemoryConversationStore {
         this.map.set(id, [...messages]);
     }
 }
-const RETRYABLE = new Set([429, 500, 502, 503, 504]);
-/** ~68 years; the widest whole-second count all seven ports represent exactly. */
-const RETRY_AFTER_MAX_SECONDS = 2147483647;
-/**
- * Honour `Retry-After` only in its delay-seconds form: a run of ASCII digits
- * (RFC 9110 §10.2.3) in 0…2147483647, returned in milliseconds.
- *
- * `Number()` is far too permissive for this — it accepts `"0.5"`, `"-5"`, `"1e3"`
- * and `" "` (as 0), which is how this port came to wait for fractional seconds
- * that five of the other six rejected outright. Fractional, signed, HTTP-date and
- * out-of-range values are not delays we can honour, so the caller falls back to
- * backoff rather than guessing. `0` is a real answer, so it returns `0`, not
- * `null`, and callers must use `??` rather than `||`.
- */
-function retryAfterMs(raw) {
-    if (raw == null)
-        return null;
-    const s = raw.trim();
-    if (!/^[0-9]+$/.test(s))
-        return null;
-    const secs = Number(s);
-    return secs <= RETRY_AFTER_MAX_SECONDS ? secs * 1000 : null;
-}
 function delay(ms, signal) {
     return new Promise((resolve, reject) => {
         const t = setTimeout(resolve, ms);
@@ -207,7 +186,7 @@ export class Client {
     /** §8 Gap 5. OpenAI-style body; omits tools/tool_choice when the tool list is empty. Key order
      * matches the pre-change body so a no-options call is byte-identical. */
     openaiBody(messages, tools, stream) {
-        const b = { model: this.opts.model, messages };
+        const b = { model: this.opts.model, messages: toOpenAIWire(messages, this.wireOpts()) };
         if (tools.length) {
             b.tools = tools;
             b.tool_choice = "auto";
@@ -220,13 +199,17 @@ export class Client {
     }
     /** §8 Gap 5. Anthropic-style body; omits tools when the tool list is empty. */
     anthropicBody(system, messages, tools, stream) {
-        const b = { model: this.opts.model, max_tokens: 4096, system, messages };
+        const b = { model: this.opts.model, max_tokens: 4096, system, messages: toAnthropicWire(messages, this.wireOpts()) };
         if (tools.length)
             b.tools = tools;
         if (stream)
             b.stream = true;
         return this.finalizeBody(b);
     }
+    /** The §8A/§1B shaping options every wire build shares. */
+    wireOpts() {
+        return { onUnsupportedPart: this.opts.onUnsupportedPart, maxPartBytes: this.opts.maxPartBytes };
+    }
     /** Prometheus text exposition of cumulative metrics (§8). Always valid, empty-but-valid before activity. */
     metrics() {
         return this.registry.render();
@@ -247,6 +230,7 @@ export class Client {
         this.emit({ event: "run", model: this.opts.model, turns, toolCalls: toolCalls.length, totalTokens: usage.totalTokens, ms: Date.now() - runStart, error: e instanceof Error ? e.message : String(e) });
     }
     async run(prompt, ctx) {
+        checkPromptParts(prompt, this.wireOpts());
         return this.opts.style === "anthropic"
             ? this.runAnthropic(prompt, ctx.toolkit, ctx.signal, ctx.history)
             : this.runOpenAI(prompt, ctx.toolkit, ctx.signal, ctx.history);
@@ -433,6 +417,7 @@ export class Client {
      * streaming, and saved back to the ConversationStore on the terminal `done` event. No `id` ⇒ stateless.
      */
     async *stream(prompt, ctx) {
+        checkPromptParts(prompt, this.wireOpts());
         const history = ctx.id ? (await this.store.get(ctx.id)) ?? [] : undefined;
         const gen = this.opts.style === "anthropic"
             ? this.streamAnthropic(prompt, ctx.toolkit, ctx.signal, history)
@@ -461,7 +446,8 @@ export class Client {
         }
         return ctrl.signal;
     }
-    /** fetch with retry + exponential backoff on 429/5xx/network, honoring Retry-After; aborts via signal.
+    /** 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.
      * The retry-vs-fail decision is the host's `onError` (default: retryable-within-budget ⇒ retry). */
     async llmFetch(url, init, signal) {
         const retries = this.opts.retries ?? 2;
@@ -475,7 +461,7 @@ export class Client {
                 const res = await (this.opts.fetch ?? fetch)(url, { ...init, signal });
                 if (res.ok)
                     return res;
-                const retryable = RETRYABLE.has(res.status);
+                const retryable = isRetryableStatus(res.status, this.opts.retryableStatuses);
                 const tier = classify({ status: res.status, attempt, retryable });
                 if (tier === "fail" || attempt === retries)
                     return res; // caller surfaces the non-ok status
@@ -602,7 +588,7 @@ export class Client {
                 // on resume). Mirrors the streaming path.
                 for (const s of settled) {
                     toolCalls.push({ name: s.call.function.name, args: s.args, output: s.result.output, isError: s.result.isError, metadata: s.result.metadata });
-                    messages.push({ role: "tool", tool_call_id: s.call.id, content: s.result.output });
+                    messages.push(toolMessage(s.call.id, s.call.function.name, s.result));
                     if (s.halted)
                         return this.pendingRun(runStart, s.halted, messages, toolCalls, turns, usage);
                 }
@@ -710,7 +696,7 @@ export class Client {
                 let halted;
                 for (const s of settled) {
                     toolCalls.push({ name: s.use.name, args: s.args, output: s.result.output, isError: s.result.isError, metadata: s.result.metadata });
-                    content.push({ type: "tool_result", tool_use_id: s.use.id, content: s.result.output, is_error: s.result.isError });
+                    content.push(toolResultBlock(s.use.id, s.result));
                     if (s.halted) {
                         halted = s.halted;
                         break;
@@ -820,13 +806,13 @@ export class Client {
                         result = r.result;
                         if (r.halted) {
                             toolCalls.push({ name: c.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
-                            messages.push({ role: "tool", tool_call_id: c.id, content: result.output });
+                            messages.push(toolMessage(c.id, c.name, result));
                             yield { type: "done", result: this.pendingRun(runStart, r.halted, messages, toolCalls, turns, usage) };
                             return;
                         }
                     }
                     toolCalls.push({ name: c.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
-                    messages.push({ role: "tool", tool_call_id: c.id, content: result.output });
+                    messages.push(toolMessage(c.id, c.name, result));
                     yield { type: "tool_result", id: c.id, name: c.name, output: result.output, isError: result.isError };
                 }
             }
@@ -927,14 +913,14 @@ export class Client {
                         result = r.result;
                         if (r.halted) {
                             toolCalls.push({ name: u.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
-                            results.push({ type: "tool_result", tool_use_id: u.id, content: result.output, is_error: result.isError });
+                            results.push(toolResultBlock(u.id, result));
                             messages.push({ role: "user", content: results });
                             yield { type: "done", result: this.pendingRun(runStart, r.halted, messages, toolCalls, turns, usage) };
                             return;
                         }
                     }
                     toolCalls.push({ name: u.name, args, output: result.output, isError: result.isError, metadata: result.metadata });
-                    results.push({ type: "tool_result", tool_use_id: u.id, content: result.output, is_error: result.isError });
+                    results.push(toolResultBlock(u.id, result));
                     yield { type: "tool_result", id: u.id, name: u.name, output: result.output, isError: result.isError };
                 }
                 messages.push({ role: "user", content: results });
@@ -1086,6 +1072,26 @@ function safeJson(s) {
         return {};
     }
 }
+/**
+ * A canonical `tool` turn. With no parts this is byte-identical to the pre-0.17 message;
+ * with parts it also carries them (and the tool `name` the §8A relocation header needs) —
+ * both consumed and stripped by the wire build, so neither reaches OpenAI.
+ */
+function toolMessage(id, name, result) {
+    const m = { role: "tool", tool_call_id: id, content: result.output };
+    if (result.parts?.length) {
+        m.name = name;
+        m.parts = result.parts;
+    }
+    return m;
+}
+/** A canonical Anthropic `tool_result` block; parts ride along and are emitted natively. */
+function toolResultBlock(id, result) {
+    const b = { type: "tool_result", tool_use_id: id, content: result.output, is_error: result.isError };
+    if (result.parts?.length)
+        b.parts = result.parts;
+    return b;
+}
 function lastText(messages) {
     for (let i = messages.length - 1; i >= 0; i--) {
         if (messages[i].role === "assistant" && typeof messages[i].content === "string")

package/dist/content.d.ts

@@ -0,0 +1,158 @@
+export type ContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    mimeType: string;
+    data?: string;
+    url?: string;
+} | {
+    type: "file";
+    mimeType: string;
+    data?: string;
+    url?: string;
+    name?: string;
+} | {
+    type: "audio";
+    mimeType: string;
+    data?: string;
+    url?: string;
+};
+/** A prompt is a string or an ordered list of parts — ordering is semantic to a model. */
+export type PromptInput = string | ContentPart[];
+/** The two provider styles that have a request path (`toGemini` is declarations only). */
+export type PartStyle = "openai" | "anthropic";
+/** How a part got here. Drives the unsupported-part rule (§8A): the caller asked for an
+ *  attached part, so silently changing it is the betrayal; nobody asked for a part an MCP
+ *  server volunteered, so failing the run over it is a regression. */
+export type PartProvenance = "attached" | "derived";
+/** What to do with a part the style cannot represent; overrides provenance uniformly. */
+export type UnsupportedPartMode = "error" | "text";
+/** Why a part could not be constructed or sent (§1B / §8A). `code` is the machine-readable half. */
+export declare class ContentPartError extends Error {
+    readonly code: "source-conflict" | "source-missing" | "unknown-extension" | "too-large" | "unsupported";
+    constructor(message: string, code: "source-conflict" | "source-missing" | "unknown-extension" | "too-large" | "unsupported");
+}
+/**
+ * The media extension table (§6 `read`) — fixed, shared with the edge constructors,
+ * identical in every port. No magic-byte sniffing and no platform mime database:
+ * `/etc/mime.types` varies per machine and would break cross-port parity.
+ */
+export declare const MEDIA_TYPES: Record<string, {
+    mimeType: string;
+    type: "image" | "file" | "audio";
+}>;
+/** Lower-cased extension without the dot, or "" when there is none. */
+export declare function extensionOf(p: string): string;
+/** The table entry for a path/URL, or undefined when the extension is not media. */
+export declare function mediaTypeFor(p: string): {
+    mimeType: string;
+    type: "image" | "file" | "audio";
+} | undefined;
+/** Part kind for a mime type: `image/*` ⇒ image, `audio/*` ⇒ audio, everything else ⇒ file. */
+export declare function partTypeForMime(mimeType: string): "image" | "file" | "audio";
+/** Decoded byte length of standard, padded base64 — without decoding it (RFC 4648 §4:
+ *  `floor(len/4)*3 - padCount`). `<bytes>` in every rendered string is a plain integer, never
+ *  a fraction, so this floors the group count rather than assuming `len` is a multiple of 4. */
+export declare function base64Bytes(b64: string): number;
+/** Decoded byte length of a part's payload; a url-only part carries no bytes here. */
+export declare function partBytes(part: ContentPart): number;
+/** §1B token estimate for a part, from its decoded byte count: `max(85, floor(bytes/750))`.
+ *  Measured against real providers: image cost is not proportional to bytes, so this is an
+ *  explicit estimate, not a count — but it is normative and lives with the part logic so a
+ *  budgeting helper (e.g. `agents.estimateTokens`) cannot silently diverge from it. */
+export declare const PART_BYTES_PER_TOKEN = 750;
+export declare const MIN_PART_TOKENS = 85;
+export declare function partTokens(bytes: number): number;
+/**
+ * How a part appears in a log line or a §9 event: `{type, mimeType, bytes}` — never `data`.
+ * Same rule as never-log-headers: part payloads are user content.
+ */
+export declare function describePart(part: ContentPart): Record<string, unknown>;
+/** A one-line, payload-free rendering of a part — for `output` text and placeholders. */
+export declare function summarizePart(part: ContentPart): string;
+/** Validate the §1B invariant: exactly one of `data` / `url`. */
+export declare function validatePart(part: ContentPart, maxPartBytes?: number): ContentPart;
+/** True when a value looks like a `ContentPart` (as opposed to a provider-native block). */
+export declare function isContentPart(v: unknown): v is ContentPart;
+/** A text part. */
+export declare function text(value: string): ContentPart;
+/** Options for {@link attach}. */
+export interface AttachOptions {
+    /** Overrides the extension table; **required** for raw bytes and for an unlisted extension. */
+    mimeType?: string;
+    /** Filename carried on a `file` part (OpenAI's `file.filename`). Defaults to the basename. */
+    name?: string;
+    /** Reject a payload over this many **decoded** bytes (never the +33% base64 string). */
+    maxPartBytes?: number;
+}
+/** Everything the edge constructor accepts (§1B): a path / `data:` / `https:` string, native
+ *  bytes in any of their JS spellings, or the host's own file object. Whatever comes in, only
+ *  `mimeType` + base64 `data` (or a `url`) lands in the part — accept broadly, store narrowly. */
+export type AttachSource = string | Uint8Array | ArrayBuffer | ArrayBufferView | Blob;
+/**
+ * The edge constructor: hand it whatever you actually have and get a path-free part.
+ *
+ * | given | becomes |
+ * |---|---|
+ * | a filesystem path | bytes read now, base64d now; mime from the fixed extension table |
+ * | native bytes (`Uint8Array`/`Buffer`/`ArrayBuffer`/any `ArrayBufferView`) | base64d now; `mimeType` required |
+ * | a `Blob` / `File` | read to bytes **now**; mime from `blob.type`, else the extension table via `File.name` |
+ * | `data:<mime>;base64,<b64>` | parsed into `{mimeType, data}` — never stored as a url |
+ * | an `http(s):` URL | kept as `url` |
+ */
+export declare function attach(source: AttachSource, opts?: AttachOptions): Promise<ContentPart>;
+/**
+ * Build a part from a `Blob` or `File`, consuming it **eagerly** — a part holding a half-read
+ * stream would not survive the transcript boundary any better than a path does (§1B).
+ *
+ * Mime comes from `blob.type` when it is non-empty, else from the fixed extension table applied
+ * to `File.name`; an explicit `opts.mimeType` beats both. A `File`'s name is carried onto a
+ * `file` part unless `opts.name` overrides it.
+ */
+export declare function fromBlob(blob: Blob, opts?: AttachOptions): Promise<ContentPart>;
+/** Build a part from in-memory bytes. `mimeType` is required — bytes carry no extension. */
+export declare function fromBytes(bytes: Uint8Array | ArrayBuffer | ArrayBufferView, mimeType: string, opts?: AttachOptions): ContentPart;
+/** Read a file now and base64 it now, so the part never carries the path (§1B). */
+export declare function fromPath(p: string, opts?: AttachOptions): Promise<ContentPart>;
+/** Parse `data:<mime>;base64,<b64>` into `{mimeType, data}`, so two spellings of the same
+ *  bytes cannot diverge downstream. */
+export declare function fromDataUrl(url: string, opts?: AttachOptions): ContentPart;
+/** Keep an `http(s):` URL as a url part; mime comes from the table or an explicit override. */
+export declare function fromUrl(url: string, opts?: AttachOptions): ContentPart;
+/**
+ * Encode one part into its provider block, or `undefined` when the style defines no shape
+ * for it. Refusals are explicit, never a fall-through: `openai × file+url` (Chat Completions
+ * has no URL form for a file) and `anthropic × audio` (the provider defines no audio block).
+ */
+export declare function encodePart(part: ContentPart, style: PartStyle): Record<string, any> | undefined;
+/** Context for {@link encodeParts}: which wire, who asked for the part, and the override. */
+export interface EncodeOptions {
+    style: PartStyle;
+    provenance: PartProvenance;
+    onUnsupportedPart?: UnsupportedPartMode;
+    maxPartBytes?: number;
+}
+/** Test seam: forget which unsupported (style, type) pairs have already been warned about. */
+export declare function resetUnsupportedWarnings(): void;
+/** The text a degraded (non-failing) unsupported part leaves behind — never silence. */
+export declare function unsupportedPlaceholder(part: ContentPart): string;
+/**
+ * Encode a list of parts for one style, applying the §8A rules:
+ * an **attached** part the style cannot represent raises before any HTTP call; a **derived**
+ * part degrades to a text placeholder and warns once. `onUnsupportedPart` overrides both.
+ * Every emitted block is asserted against the style's allowlist.
+ *
+ * `maxPartBytes` (§1B) is enforced here too, at assembly, over EVERY part regardless of
+ * provenance — a part that arrived from an MCP server never passed through an edge
+ * constructor, so a limit it can walk around is not a limit. Going over follows the exact
+ * same provenance split as an unsupported block: an attached part errors, a derived one
+ * degrades to the placeholder so a remote server still cannot fail the run.
+ */
+export declare function encodeParts(parts: readonly ContentPart[], opts: EncodeOptions): Record<string, any>[];
+/**
+ * Read an inbound OpenAI-shaped content block back into a `ContentPart` (§11). Accepts both
+ * a `ContentPart` written literally and the provider-native block the same part encodes to,
+ * so a caller's own OpenAI messages translate as faithfully as ours do.
+ */
+export declare function inboundPart(block: unknown): ContentPart | undefined;