toolnexus 0.15.0 → 0.17.0

package/dist/client.js

@@ -1,4 +1,5 @@
 import { pendingOf } from "./types.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 {
@@ -207,7 +208,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 +221,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 +252,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 +439,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)
@@ -602,7 +609,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 +717,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 +827,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 +934,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 });
@@ -950,6 +957,84 @@ export class Client {
 export function createClient(opts) {
     return new Client(opts);
 }
+/** The sentinel base URL. Never dialled — the transport below answers every request
+ *  before the network is reached — but the client builds a URL string internally, so
+ *  it must be syntactically valid. `.invalid` is reserved by RFC 2606 precisely so a
+ *  name can never resolve. */
+const IN_PROCESS_BASE_URL = "http://in-process.invalid/v1";
+/**
+ * A client backed by a model running IN THIS PROCESS — no server, no socket, and no
+ * HTTP types to construct.
+ *
+ * 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.
+ *
+ * Streaming is refused rather than faked — see the thrown error.
+ */
+export function createInProcessClient(opts) {
+    const { generate, ...rest } = opts;
+    if (typeof generate !== "function") {
+        throw new Error("toolnexus: createInProcessClient requires a `generate` function");
+    }
+    const inProcessFetch = async (_url, init) => {
+        const body = JSON.parse(String(init?.body ?? "{}"));
+        // A generate() returns a whole answer, so a stream would be one chunk pretending
+        // to be many. Content and delta-count assertions cannot tell that from a real
+        // stream, so refuse instead of degrading silently.
+        if (body.stream) {
+            throw new Error("toolnexus: createInProcessClient does not support streaming — `generate` returns a " +
+                "complete answer. Use the non-streaming run, or supply a `fetch`/transport that streams.");
+        }
+        const answer = await generate({
+            messages: body.messages ?? [],
+            tools: body.tools,
+            model: body.model,
+            body,
+        });
+        const message = { role: "assistant" };
+        if (answer.toolCalls && answer.toolCalls.length > 0) {
+            message.tool_calls = answer.toolCalls.map((c, i) => ({
+                id: c.id ?? `call_${i}`,
+                type: "function",
+                function: {
+                    name: c.name,
+                    // A string is already encoded; anything else is encoded here so a model
+                    // author never has to think about the wire.
+                    arguments: typeof c.arguments === "string" ? c.arguments : JSON.stringify(c.arguments ?? {}),
+                },
+            }));
+        }
+        else {
+            message.content = answer.content ?? "";
+        }
+        const u = answer.usage ?? {};
+        const prompt = u.promptTokens ?? 0;
+        const completion = u.completionTokens ?? 0;
+        return new Response(JSON.stringify({
+            choices: [{ index: 0, message, finish_reason: message.tool_calls ? "tool_calls" : "stop" }],
+            usage: {
+                prompt_tokens: prompt,
+                completion_tokens: completion,
+                total_tokens: u.totalTokens ?? prompt + completion,
+            },
+        }), { status: 200, headers: { "content-type": "application/json" } });
+    };
+    return new Client({
+        // Retries default to ZERO here, unlike a network client. There is no wire, so
+        // there is no transient failure to ride out: whatever `generate` throws will
+        // throw again. Retrying it only buys backoff before the user sees their own bug —
+        // measured at 3.7s for the streaming refusal before this default. A host whose
+        // model really is flaky (a GPU that OOMs, say) can still set `retries`.
+        retries: 0,
+        ...rest,
+        baseUrl: IN_PROCESS_BASE_URL,
+        style: "openai",
+        // An in-process model has no endpoint to authenticate to, so the host must never need a key — but the client resolves one from the environment and fails when it finds none. A sentinel keeps that resolution from ever running. Caught by CI, which has no OPENROUTER_API_KEY; every local run passed because a developer shell has one.
+        apiKey: "in-process",
+        fetch: inProcessFetch,
+    });
+}
 /** Stateful multi-turn conversation: each send() continues the same transcript (memory). */
 export class Conversation {
     client;
@@ -1008,6 +1093,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;