@celestea/llm 2.7.1

package/dist/usage.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Token-usage parsing for the OpenAI-compatible stream (P2a).
+ *
+ * Mirrors `crates/llm/src/client.rs::extract_usage` 1:1: usage arrives either
+ * in a usage-only final frame or attached to the last chunk; cache-hit prompt
+ * tokens use three different provider key shapes and all of them are probed.
+ * The statusline reads exactly these five flat counters.
+ *
+ * A1 (W746): the `Usage` shape itself (and `zeroUsage` / `usageIsEmpty`) is
+ * core's `message.rs` port — re-exported here, not redeclared. What is
+ * provider-specific stays: the three provider key shapes and the parser.
+ */
+import { usageIsEmpty, zeroUsage, type Usage } from "@celestea/core";
+export { usageIsEmpty, zeroUsage };
+export type { Usage };
+/** P0 placeholder name, kept as an alias of the real Usage shape. */
+export type LlmUsageFrame = Usage;
+/** The three required keys (usage_json, src/main.rs:575-600). */
+export declare const USAGE_REQUIRED_KEYS: readonly ["prompt_tokens", "completion_tokens", "total_tokens"];
+/** Flat cache-read keys, probed in order (DeepSeek, then Anthropic-style). */
+export declare const CACHE_READ_FLAT_KEYS: readonly ["prompt_cache_hit_tokens", "cache_read_input_tokens"];
+/** Nested cache-read key (OpenAI): usage.prompt_tokens_details.cached_tokens. */
+export declare const CACHE_READ_NESTED: {
+    readonly outer: "prompt_tokens_details";
+    readonly inner: "cached_tokens";
+};
+/** Nested reasoning key: usage.completion_tokens_details.reasoning_tokens. */
+export declare const REASONING_TOKENS_NESTED: {
+    readonly outer: "completion_tokens_details";
+    readonly inner: "reasoning_tokens";
+};
+/** An all-zero usage block (constant; do not mutate). */
+export declare const ZERO_USAGE: Usage;
+/**
+ * Parse a raw `usage` object into Usage. Returns undefined when no token
+ * counter is present at all (an empty usage object is not a usage frame).
+ */
+export declare function usageFromObject(usage: Record<string, unknown>): Usage | undefined;
+/**
+ * Extract usage from a decoded chat-completions chunk (the whole chunk JSON,
+ * not just the usage object). Returns undefined when the chunk carries none.
+ */
+export declare function parseUsage(chunk: unknown): Usage | undefined;
+/**
+ * cache_read / prompt_tokens, clamped to [0,1] and rounded to 4 decimals.
+ *
+ * NOTE (A1): this is the PROVIDER-side reading of the ratio, and it is
+ * deliberately not core's `cacheHitRatio(u)` (unclamped, unrounded, the
+ * `message.rs` port). `packages/runtime` has a third spelling
+ * (`cacheHitRatioRounded`). Unifying the three is queued, not done here:
+ * every one of them is asserted by its own test, so folding them is a
+ * behaviour change, not a move.
+ */
+export declare function cacheHitRatio(u: Usage): number;

package/dist/usage.js

@@ -0,0 +1,92 @@
+/**
+ * Token-usage parsing for the OpenAI-compatible stream (P2a).
+ *
+ * Mirrors `crates/llm/src/client.rs::extract_usage` 1:1: usage arrives either
+ * in a usage-only final frame or attached to the last chunk; cache-hit prompt
+ * tokens use three different provider key shapes and all of them are probed.
+ * The statusline reads exactly these five flat counters.
+ *
+ * A1 (W746): the `Usage` shape itself (and `zeroUsage` / `usageIsEmpty`) is
+ * core's `message.rs` port — re-exported here, not redeclared. What is
+ * provider-specific stays: the three provider key shapes and the parser.
+ */
+import { usageIsEmpty, zeroUsage } from "@celestea/core";
+export { usageIsEmpty, zeroUsage };
+/** The three required keys (usage_json, src/main.rs:575-600). */
+export const USAGE_REQUIRED_KEYS = ["prompt_tokens", "completion_tokens", "total_tokens"];
+/** Flat cache-read keys, probed in order (DeepSeek, then Anthropic-style). */
+export const CACHE_READ_FLAT_KEYS = ["prompt_cache_hit_tokens", "cache_read_input_tokens"];
+/** Nested cache-read key (OpenAI): usage.prompt_tokens_details.cached_tokens. */
+export const CACHE_READ_NESTED = { outer: "prompt_tokens_details", inner: "cached_tokens" };
+/** Nested reasoning key: usage.completion_tokens_details.reasoning_tokens. */
+export const REASONING_TOKENS_NESTED = {
+    outer: "completion_tokens_details",
+    inner: "reasoning_tokens",
+};
+/** An all-zero usage block (constant; do not mutate). */
+export const ZERO_USAGE = zeroUsage();
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** serde_json `as_u64` equivalent: JSON numbers only, non-negative integers. */
+function asU64(v) {
+    return typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : undefined;
+}
+function topLevel(usage, keys) {
+    for (const key of keys) {
+        const n = asU64(usage[key]);
+        if (n !== undefined)
+            return n;
+    }
+    return undefined;
+}
+function nested(usage, outer, inner) {
+    const obj = usage[outer];
+    if (!isRecord(obj))
+        return undefined;
+    return asU64(obj[inner]);
+}
+/**
+ * Parse a raw `usage` object into Usage. Returns undefined when no token
+ * counter is present at all (an empty usage object is not a usage frame).
+ */
+export function usageFromObject(usage) {
+    const parsed = {
+        prompt_tokens: topLevel(usage, ["prompt_tokens"]) ?? 0,
+        completion_tokens: topLevel(usage, ["completion_tokens"]) ?? 0,
+        total_tokens: topLevel(usage, ["total_tokens"]) ?? 0,
+        cache_read: topLevel(usage, CACHE_READ_FLAT_KEYS) ??
+            nested(usage, CACHE_READ_NESTED.outer, CACHE_READ_NESTED.inner) ??
+            0,
+        reasoning_tokens: nested(usage, REASONING_TOKENS_NESTED.outer, REASONING_TOKENS_NESTED.inner) ?? 0,
+    };
+    return usageIsEmpty(parsed) ? undefined : parsed;
+}
+/**
+ * Extract usage from a decoded chat-completions chunk (the whole chunk JSON,
+ * not just the usage object). Returns undefined when the chunk carries none.
+ */
+export function parseUsage(chunk) {
+    if (!isRecord(chunk))
+        return undefined;
+    const usage = chunk["usage"];
+    if (!isRecord(usage))
+        return undefined;
+    return usageFromObject(usage);
+}
+/**
+ * cache_read / prompt_tokens, clamped to [0,1] and rounded to 4 decimals.
+ *
+ * NOTE (A1): this is the PROVIDER-side reading of the ratio, and it is
+ * deliberately not core's `cacheHitRatio(u)` (unclamped, unrounded, the
+ * `message.rs` port). `packages/runtime` has a third spelling
+ * (`cacheHitRatioRounded`). Unifying the three is queued, not done here:
+ * every one of them is asserted by its own test, so folding them is a
+ * behaviour change, not a move.
+ */
+export function cacheHitRatio(u) {
+    if (u.prompt_tokens <= 0)
+        return 0;
+    const ratio = u.cache_read / u.prompt_tokens;
+    return Math.round(Math.min(1, Math.max(0, ratio)) * 10_000) / 10_000;
+}

package/dist/wire.d.ts

@@ -0,0 +1,103 @@
+/**
+ * OpenAI-compatible request wire mapping (P2a).
+ *
+ * Mirrors `crates/llm/src/client.rs::{build_request, request_body, map_message,
+ * map_tool, collect_text}`:
+ *
+ *   POST {base_url}/chat/completions
+ *   { model, messages, tools?, reasoning_effort?, max_tokens?, temperature?,
+ *     stream: true }
+ *
+ * The output cap is the request's explicit max_tokens, else the configured
+ * max_output_tokens. `reasoning_effort` is injected verbatim as a free-form
+ * string — never folded onto an enum, never renamed ("max" stays "max").
+ *
+ * W804 (multimodal P0 section 3): an image-bearing message becomes an OpenAI
+ * content array, `content: [{type:"text",text}, {type:"image_url",image_url:{url:DATA}}]`.
+ * The bytes are a REQUEST-TIME projection: the host resolves them into the
+ * `images` table carried on the request (attachment_id -> data URL); they NEVER
+ * live in a Message or the session log. A tool message with images is split into
+ * the tool text message followed by a user message carrying the images (shape B,
+ * section 3.3), because some providers silently drop tool-role images.
+ */
+import { type Content, type ImageRef, type Message, type ModelRequestDraft, type ToolSpec } from "./seam.js";
+export interface WireToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/** One text part of an OpenAI content array. */
+export interface WireTextPart {
+    type: "text";
+    text: string;
+}
+/** One image part; the url is always a `data:` URL (section 3.1: remote URLs denied). */
+export interface WireImagePart {
+    type: "image_url";
+    image_url: {
+        url: string;
+    };
+}
+export type WireContentPart = WireTextPart | WireImagePart;
+/** Request-scoped resolution table: attachment_id -> data URL. */
+export type ResolvedImages = Readonly<Record<string, string>>;
+export interface WireMessage {
+    role: string;
+    /** A plain string for text-only messages; an array ONLY when it carries images. */
+    content: string | WireContentPart[] | null;
+    tool_calls?: WireToolCall[];
+    tool_call_id?: string;
+}
+export interface WireTool {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+/** The chat-completions request body (field presence mirrors serde skip_if). */
+export interface ChatCompletionsBody {
+    model: string;
+    messages: WireMessage[];
+    stream: true;
+    tools?: WireTool[];
+    reasoning_effort?: string;
+    max_tokens?: number;
+    temperature?: number;
+}
+/** Read the host-resolved image table off a request (absent = empty). */
+export declare function resolvedImagesOf(req: unknown): ResolvedImages;
+/** `data:<mime>;base64,<...>` for one attachment's bytes. */
+export declare function dataUrlFor(mediaType: string, bytes: Uint8Array): string;
+/** The image references one message carries (its image content blocks). */
+export declare function messageImageRefs(msg: Message): ImageRef[];
+/** True when ANY message of the request carries an image block. */
+export declare function messagesHaveImages(messages: readonly Message[]): boolean;
+/** Content parts of ONE message; every image must resolve or this throws. */
+export declare function collectMessageParts(content: readonly Content[], images: ResolvedImages): WireContentPart[];
+/**
+ * Wire messages for ONE seam message (section 3.3): a tool message with images
+ * expands to [tool text, user images]. The split lives HERE and nowhere else, so
+ * a future provider that accepts tool-role images changes one branch.
+ */
+export declare function wireMessagesFor(msg: Message, images?: ResolvedImages): WireMessage[];
+/** Map one seam Message onto an OpenAI-compatible chat message. */
+export declare function mapMessage(msg: Message, images?: ResolvedImages): WireMessage;
+/** Map a seam ToolSpec onto an OpenAI-compatible function tool. */
+export declare function mapTool(spec: ToolSpec): WireTool;
+export interface BuildBodyOptions {
+    /** Effective model (the request's model wins over the configured one). */
+    model: string;
+    /** Free-form tier string injected verbatim; null/undefined = omit. */
+    reasoningEffort?: string | null;
+    /** Configured output cap used when the request leaves max_tokens empty. */
+    maxOutputTokens?: number | null;
+}
+/** Build the serialized chat-completions body for one request draft. */
+export declare function buildRequestBody(req: ModelRequestDraft, opts: BuildBodyOptions): ChatCompletionsBody;
+/** chat-completions endpoint for a base URL (trailing slashes tolerated). */
+export declare function chatCompletionsUrl(baseUrl: string): string;

package/dist/wire.js

@@ -0,0 +1,190 @@
+/**
+ * OpenAI-compatible request wire mapping (P2a).
+ *
+ * Mirrors `crates/llm/src/client.rs::{build_request, request_body, map_message,
+ * map_tool, collect_text}`:
+ *
+ *   POST {base_url}/chat/completions
+ *   { model, messages, tools?, reasoning_effort?, max_tokens?, temperature?,
+ *     stream: true }
+ *
+ * The output cap is the request's explicit max_tokens, else the configured
+ * max_output_tokens. `reasoning_effort` is injected verbatim as a free-form
+ * string — never folded onto an enum, never renamed ("max" stays "max").
+ *
+ * W804 (multimodal P0 section 3): an image-bearing message becomes an OpenAI
+ * content array, `content: [{type:"text",text}, {type:"image_url",image_url:{url:DATA}}]`.
+ * The bytes are a REQUEST-TIME projection: the host resolves them into the
+ * `images` table carried on the request (attachment_id -> data URL); they NEVER
+ * live in a Message or the session log. A tool message with images is split into
+ * the tool text message followed by a user message carrying the images (shape B,
+ * section 3.3), because some providers silently drop tool-role images.
+ */
+import { LlmError } from "./errors.js";
+import { collectMessageText, isImageContent, } from "./seam.js";
+/** Read the host-resolved image table off a request (absent = empty). */
+export function resolvedImagesOf(req) {
+    if (typeof req !== "object" || req === null)
+        return {};
+    const table = req["images"];
+    if (typeof table !== "object" || table === null || Array.isArray(table))
+        return {};
+    return table;
+}
+/** `data:<mime>;base64,<...>` for one attachment's bytes. */
+export function dataUrlFor(mediaType, bytes) {
+    return `data:${mediaType};base64,${Buffer.from(bytes).toString("base64")}`;
+}
+function imageBytesUnavailable(id) {
+    return new LlmError(`attachment ${id} has no resolvable bytes for this request`, "generate", { retryable: false });
+}
+/** The image references one message carries (its image content blocks). */
+export function messageImageRefs(msg) {
+    const out = [];
+    for (const part of msg.content)
+        if (isImageContent(part))
+            out.push(part.content);
+    return out;
+}
+/** True when ANY message of the request carries an image block. */
+export function messagesHaveImages(messages) {
+    for (const msg of messages)
+        if (msg.content.some(isImageContent))
+            return true;
+    return false;
+}
+/** Content parts of ONE message; every image must resolve or this throws. */
+export function collectMessageParts(content, images) {
+    const parts = [];
+    for (const part of content) {
+        if (part.type === "text") {
+            if (part.content !== "")
+                parts.push({ type: "text", text: part.content });
+        }
+        else if (part.type === "image") {
+            const url = images[part.content.attachment_id];
+            if (url === undefined)
+                throw imageBytesUnavailable(part.content.attachment_id);
+            parts.push({ type: "image_url", image_url: { url } });
+        }
+    }
+    return parts;
+}
+/** A system/assistant image block is a wiring bug: report it, never drop it. */
+function assertNoImages(msg) {
+    if (messageImageRefs(msg).length === 0)
+        return;
+    throw new LlmError(`W804: a ${msg.role} message must not carry an image block`, "generate", { retryable: false });
+}
+function userWire(msg, images) {
+    if (messageImageRefs(msg).length === 0)
+        return { role: "user", content: collectMessageText(msg.content) };
+    return { role: "user", content: collectMessageParts(msg.content, images) };
+}
+function assistantWire(msg) {
+    const text = collectMessageText(msg.content);
+    const toolCalls = msg.content
+        .filter((part) => part.type === "tool_call")
+        .map((part) => ({
+        id: part.content.id,
+        type: "function",
+        function: {
+            name: part.content.name,
+            arguments: JSON.stringify(part.content.args ?? null),
+        },
+    }));
+    const out = { role: "assistant", content: text === "" ? null : text };
+    if (toolCalls.length > 0)
+        out.tool_calls = toolCalls;
+    return out;
+}
+/**
+ * Wire messages for ONE seam message (section 3.3): a tool message with images
+ * expands to [tool text, user images]. The split lives HERE and nowhere else, so
+ * a future provider that accepts tool-role images changes one branch.
+ */
+export function wireMessagesFor(msg, images = {}) {
+    switch (msg.role) {
+        case "system":
+            assertNoImages(msg);
+            return [{ role: "system", content: collectMessageText(msg.content) }];
+        case "user":
+            return [userWire(msg, images)];
+        case "tool": {
+            const tool = {
+                role: "tool",
+                content: collectMessageText(msg.content),
+                tool_call_id: msg.tool_call_id ?? "",
+            };
+            const refs = messageImageRefs(msg);
+            if (refs.length === 0)
+                return [tool];
+            const parts = [];
+            for (const ref of refs) {
+                const url = images[ref.attachment_id];
+                if (url === undefined)
+                    throw imageBytesUnavailable(ref.attachment_id);
+                parts.push({ type: "image_url", image_url: { url } });
+            }
+            return [tool, { role: "user", content: parts }];
+        }
+        case "assistant":
+            assertNoImages(msg);
+            return [assistantWire(msg)];
+        default: {
+            // W835 (R3 batch E / P2-3): a role outside the union must be a structured
+            // LlmError, never the `...undefined` spread that panicked the turn.
+            const role = msg.role;
+            throw new LlmError("unsupported message role '" + String(role) + "'", "generate", { retryable: false });
+        }
+    }
+}
+/** Map one seam Message onto an OpenAI-compatible chat message. */
+export function mapMessage(msg, images = {}) {
+    const out = wireMessagesFor(msg, images);
+    const first = out[0];
+    if (out.length !== 1 || first === undefined) {
+        throw new LlmError("W804: a tool message with images must be split by buildRequestBody", "generate", { retryable: false });
+    }
+    return first;
+}
+/** Map a seam ToolSpec onto an OpenAI-compatible function tool. */
+export function mapTool(spec) {
+    return {
+        type: "function",
+        function: {
+            name: spec.name,
+            description: spec.description,
+            parameters: spec.parameters,
+        },
+    };
+}
+/** Build the serialized chat-completions body for one request draft. */
+export function buildRequestBody(req, opts) {
+    const images = resolvedImagesOf(req);
+    const messages = [];
+    if (req.system !== null && req.system !== undefined && req.system !== "") {
+        messages.push({ role: "system", content: req.system });
+    }
+    for (const message of req.messages ?? [])
+        messages.push(...wireMessagesFor(message, images));
+    const tools = (req.tools ?? []).map(mapTool);
+    const maxTokens = req.max_tokens ?? opts.maxOutputTokens ?? null;
+    const body = { model: opts.model, messages, stream: true };
+    if (tools.length > 0)
+        body.tools = tools;
+    // W835 (R3 batch D / P2-2): 0/negative = "no cap" (the field is omitted).
+    if (maxTokens !== null && maxTokens > 0)
+        body.max_tokens = maxTokens;
+    if (req.temperature !== null && req.temperature !== undefined) {
+        body.temperature = req.temperature;
+    }
+    if (opts.reasoningEffort !== null && opts.reasoningEffort !== undefined) {
+        body.reasoning_effort = opts.reasoningEffort;
+    }
+    return body;
+}
+/** chat-completions endpoint for a base URL (trailing slashes tolerated). */
+export function chatCompletionsUrl(baseUrl) {
+    return `${baseUrl.trimEnd().replace(/\/+$/, "")}/chat/completions`;
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@celestea/llm",
+  "version": "2.7.1",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@celestea/core": "2.7.1"
+  },
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "build": "tsc -p tsconfig.build.json"
+  }
+}