@celestea/llm 2.7.1

package/dist/profile.js

@@ -0,0 +1,82 @@
+/**
+ * Provider profile -> client configuration (P2a).
+ *
+ * Mirrors `crates/runtime/src/compose.rs` (the DeepSeekConfig assembly):
+ * base_url = profile > DEEPSEEK_BASE_URL env > default; model from the profile;
+ * reasoning_effort passed through verbatim; timeouts resolved from the profile
+ * keys with the CELESTEA_LLM_* env vars taking precedence.
+ *
+ * The API key is read from the runtime configuration / environment ONLY. It is
+ * never written to disk, never logged, and never echoed into an error message
+ * or a serialized view (see OpenAiCompatClient.describe()).
+ */
+import { LlmError } from "./errors.js";
+import { resolveTimeoutTiers, timeoutMsOf, } from "./timeouts.js";
+/** Environment variable holding the provider API key. */
+export const API_KEY_ENV = "DEEPSEEK_API_KEY";
+/** Environment variable overriding the provider base URL. */
+export const BASE_URL_ENV = "DEEPSEEK_BASE_URL";
+export const DEFAULT_BASE_URL = "https://api.deepseek.com";
+export const DEFAULT_MODEL = "deepseek-chat";
+/** The tiers as configured (null = disabled), derived from resolved ms values. */
+export function tiersFromConfig(config) {
+    // W835 (R3 batch D / P2-6): route the 0 -> null mapping through the SAME
+    // helper the client constructor uses.
+    return {
+        connectMs: timeoutMsOf(config.connectTimeoutMs, null),
+        responseMs: timeoutMsOf(config.responseTimeoutMs, null),
+        idleMs: timeoutMsOf(config.streamIdleTimeoutMs, null),
+    };
+}
+function nonEmpty(v) {
+    return typeof v === "string" && v.trim() !== "" ? v.trim() : undefined;
+}
+/**
+ * Resolve the API key from the environment ONLY (`api_key_env` names the var).
+ * Returns null when unset/blank. This package never reads key files: that is
+ * the runtime's job (`resolve_api_key` in crates/runtime).
+ */
+export function resolveApiKey(profile, env = process.env) {
+    const name = nonEmpty(profile?.api_key_env) ?? API_KEY_ENV;
+    const value = env[name];
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed === "" ? null : trimmed;
+}
+/** Compose the effective client config from a runtime profile + environment. */
+export function resolveClientConfig(profile, env = process.env) {
+    const tiers = resolveTimeoutTiers(profile, env);
+    const maxOut = profile?.max_output_tokens;
+    return {
+        baseUrl: nonEmpty(profile?.base_url) ?? nonEmpty(env[BASE_URL_ENV]) ?? DEFAULT_BASE_URL,
+        apiKey: resolveApiKey(profile, env) ?? "",
+        model: nonEmpty(profile?.model) ?? DEFAULT_MODEL,
+        reasoningEffort: typeof profile?.reasoning_effort === "string" ? profile.reasoning_effort : null,
+        // W835 (R3 batch D / P2-2): 0 means "clear the cap" (endpoints.json:540),
+        // so it resolves to null (the wire then omits max_tokens) rather than 0.
+        maxOutputTokens: typeof maxOut === "number" && Number.isInteger(maxOut) && maxOut > 0 ? maxOut : null,
+        connectTimeoutMs: tiers.connectMs ?? 0,
+        responseTimeoutMs: tiers.responseMs ?? 0,
+        streamIdleTimeoutMs: tiers.idleMs ?? 0,
+    };
+}
+/**
+ * reasoning_effort is a FREE STRING: user-defined tiers ("max",
+ * "xhigh-custom", provider-specific labels) reach the upstream exactly as
+ * written. Only null/undefined means "not configured" — no trimming, no
+ * folding onto an enum, no renaming.
+ */
+export function normalizeReasoningEffort(v) {
+    return v === null || v === undefined ? null : v;
+}
+/**
+ * Model names are free-form: the OpenAI-compatible endpoint decides its own
+ * catalog (a local shim may expose deepseek-v4-flash), so the only hard rule is
+ * that a model must be supplied.
+ */
+export function validateModel(model) {
+    if (model.trim() === "") {
+        throw new LlmError("model must not be empty", "generate");
+    }
+}

package/dist/provider.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Provider registration (P2a).
+ *
+ * Mirrors `crates/llm/src/registry.rs` (+ `DeepSeekLlm::from_env`): the
+ * DeepSeek adapter is registered under the canonical name "deepseek", and the
+ * from-env path requires a non-empty API key.
+ *
+ * A1 (W746): the registry is CORE's `LlmRegistry` (the `llm.rs` port) — the
+ * local `Map`-based copy is deleted, so registration/resolution semantics are
+ * the seam's, not a second implementation's.
+ */
+import { LlmRegistry } from "@celestea/core";
+import { OpenAiCompatClient } from "./client.js";
+import { type LlmProfile } from "./profile.js";
+import type { Llm } from "./seam.js";
+import type { EnvLike } from "./timeouts.js";
+/** Canonical provider name (mirrors `deepseek_registry`). */
+export declare const DEEPSEEK_PROVIDER_NAME = "deepseek";
+export { LlmRegistry };
+/**
+ * Build the DeepSeek provider from a runtime profile + environment. The API key
+ * is read from the environment only; a missing key is an error, never a silent
+ * unauthenticated request.
+ */
+export declare function createDeepSeekLlm(profile?: LlmProfile | null, env?: EnvLike): OpenAiCompatClient;
+/** A registry holding `llm` under the canonical "deepseek" name. */
+export declare function createDeepSeekRegistry(llm: Llm): LlmRegistry<Llm>;

package/dist/provider.js

@@ -0,0 +1,37 @@
+/**
+ * Provider registration (P2a).
+ *
+ * Mirrors `crates/llm/src/registry.rs` (+ `DeepSeekLlm::from_env`): the
+ * DeepSeek adapter is registered under the canonical name "deepseek", and the
+ * from-env path requires a non-empty API key.
+ *
+ * A1 (W746): the registry is CORE's `LlmRegistry` (the `llm.rs` port) — the
+ * local `Map`-based copy is deleted, so registration/resolution semantics are
+ * the seam's, not a second implementation's.
+ */
+import { LlmRegistry } from "@celestea/core";
+import { OpenAiCompatClient } from "./client.js";
+import { LlmError } from "./errors.js";
+import { resolveApiKey } from "./profile.js";
+import { resolveClientConfig } from "./profile.js";
+/** Canonical provider name (mirrors `deepseek_registry`). */
+export const DEEPSEEK_PROVIDER_NAME = "deepseek";
+export { LlmRegistry };
+/**
+ * Build the DeepSeek provider from a runtime profile + environment. The API key
+ * is read from the environment only; a missing key is an error, never a silent
+ * unauthenticated request.
+ */
+export function createDeepSeekLlm(profile, env = process.env) {
+    if (resolveApiKey(profile, env) === null) {
+        const name = profile?.api_key_env ?? "DEEPSEEK_API_KEY";
+        throw new LlmError(`${name} is not set`, "generate");
+    }
+    return OpenAiCompatClient.fromConfig(resolveClientConfig(profile, env));
+}
+/** A registry holding `llm` under the canonical "deepseek" name. */
+export function createDeepSeekRegistry(llm) {
+    const registry = new LlmRegistry();
+    registry.register(DEEPSEEK_PROVIDER_NAME, llm);
+    return registry;
+}

package/dist/seam.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The LLM seam — the vocabulary a provider adapter and its callers share.
+ *
+ * A1 (W746): the seam vocabulary is CORE's. `@celestea/core` is the single
+ * source of `Llm` / `Message` / `Content` / `Role` / `ToolCall` / `ToolSpec` /
+ * `ModelRequest` / `Usage` / `LlmError`, and this module re-exports it instead
+ * of redeclaring a second, structurally-identical universe. The old
+ * `TODO(core-seam)` ("core's seam is still in flight") is discharged: core has
+ * exported all of these since W271, and `packages/llm` now imports core.
+ *
+ * Field names and content tag names are contract, not style (`type` +
+ * `content`, `tool_call_id`, flat usage counters): do not rename anything.
+ *
+ * ONE member cannot be a pure re-export — see [StreamEvent].
+ */
+import type { Content, Message, ModelRequest, StreamEvent as CoreStreamEvent } from "@celestea/core";
+export { assistantText, assistantToolCall, attachmentRefsOfValue, IMAGE_MEDIA_TYPES, imageContent, isImageContent, isImageMediaType, isImageRef, messageImages, messageToolCalls, normalizeImageRef, ROLES, systemMessage, toolResultMessage, toolResultWithImages, userMessage, userMessageWithImages, } from "@celestea/core";
+export type { AttachmentRef, Content, ImageContent, ImageMediaType, ImageRef, LlmError, LlmErrorKind, LlmErrorOptions, Message, ModelRequest, Role, TextContent, TimeoutStage, ToolCall, ToolCallContent, ToolSpec, Usage, } from "@celestea/core";
+/**
+ * `StreamEvent` — core's streamed-turn union with exactly ONE member widened.
+ *
+ * A provider's SSE idle guard is a terminal `failed{kindOf:"timeout"}` (the
+ * legacy engine's `StreamEvent::Failed { kind, .. }` carried a free-form kind,
+ * whose live values were "stream" and "timeout"), while core's union lists
+ * "generate" | "stream".
+ *
+ * TODO(core-timeout-kind) — why the widening stays HERE for now: folding it
+ * into core needs three files this cut may not touch or must not change:
+ *   1. `contracts/session-event.schema.json` freezes `TurnOutcome.error.kind`
+ *      to exactly ["generate","stream"], and W744 EXECUTES that schema
+ *      (`tests/contract-parity.test.ts:68,119`): widening core's
+ *      `TurnOutcome.error.kind` would let the engine mint rows the frozen
+ *      contract rejects;
+ *   2. `packages/agent-loop/src/step.ts:49` forwards `kindOf` into
+ *      `TurnOutcome.error.kind` verbatim, so `StreamEvent.failed.kindOf`
+ *      cannot be widened alone (agent-loop is W747's file);
+ *   3. `contracts/` is frozen — a real widening is a contract change with a
+ *      decision record, not a worker's bounded cut.
+ * Until then the delta is this single member: everything else is derived from
+ * core's union, so a variant added in core appears here automatically.
+ */
+export type StreamEvent = Exclude<CoreStreamEvent, {
+    kind: "failed";
+}> | {
+    kind: "failed";
+    kindOf: "generate" | "stream" | "timeout";
+    message: string;
+};
+/**
+ * A request DRAFT — what a DIRECT caller of this provider may pass: every field
+ * of core's `ModelRequest` optional except `messages`.
+ *
+ * The engine always hands over a fully-filled core `ModelRequest` (which IS a
+ * draft: it is assignable to this type), but the provider is also driven
+ * one-shot (`packages/llm/**` tests, an embedding host), where `model` /
+ * `system` / `tools` / `max_tokens` / `temperature` are simply absent — the
+ * wire mapper's documented "absent == empty" fallbacks handle exactly that, and
+ * have always handled it. Keeping the permissive form HERE (instead of
+ * loosening core's `ModelRequest`, which `apps/studio` reads as a fully-filled
+ * shape) is what makes the shared seam strict and the provider usable.
+ */
+export type ModelRequestDraft = Partial<ModelRequest> & {
+    messages: Message[];
+    /**
+     * W804: the REQUEST-scoped image resolution table (attachment_id -> data URL)
+     * the host fills before the wire mapper runs. It is not part of core's
+     * `ModelRequest` (the log never carries bytes); the wire layer reads it and
+     * emits an OpenAI content array. Absent = no image table.
+     */
+    images?: ResolvedImages;
+};
+/** attachment_id -> data URL, resolved for ONE request. */
+export type ResolvedImages = Readonly<Record<string, string>>;
+/** The streamed turn: an async iterable of events. */
+export type LlmStream = AsyncIterable<StreamEvent>;
+/**
+ * The `Llm` seam every provider adapter implements: core's `Llm` with the
+ * [StreamEvent] widening above (hence not a re-export — the return type is the
+ * provider's stream). A provider stream is therefore NOT assignable to core's
+ * `Llm`; the single host adapter converts it (and drops "timeout" to "stream"
+ * for the frozen contract): `apps/studio/src/runtime/llm-assembly.ts:69-96`.
+ */
+export interface Llm {
+    /** Start a streaming turn; pre-stream failures reject with an LlmError. */
+    generate(req: ModelRequestDraft): Promise<LlmStream>;
+}
+/** Concatenate the text parts of a message's content (joined with "\n"). */
+export declare function collectMessageText(content: readonly Content[]): string;
+/** Drain a stream into an array (helper for tests/CLI; consumers stream live). */
+export declare function collectStream(stream: LlmStream): Promise<StreamEvent[]>;

package/dist/seam.js

@@ -0,0 +1,35 @@
+/**
+ * The LLM seam — the vocabulary a provider adapter and its callers share.
+ *
+ * A1 (W746): the seam vocabulary is CORE's. `@celestea/core` is the single
+ * source of `Llm` / `Message` / `Content` / `Role` / `ToolCall` / `ToolSpec` /
+ * `ModelRequest` / `Usage` / `LlmError`, and this module re-exports it instead
+ * of redeclaring a second, structurally-identical universe. The old
+ * `TODO(core-seam)` ("core's seam is still in flight") is discharged: core has
+ * exported all of these since W271, and `packages/llm` now imports core.
+ *
+ * Field names and content tag names are contract, not style (`type` +
+ * `content`, `tool_call_id`, flat usage counters): do not rename anything.
+ *
+ * ONE member cannot be a pure re-export — see [StreamEvent].
+ */
+// The seam vocabulary, verbatim from core (values keep their identity too, so
+// `userMessage(...)` here IS core's `userMessage(...)`).
+export { assistantText, assistantToolCall, attachmentRefsOfValue, IMAGE_MEDIA_TYPES, imageContent, isImageContent, isImageMediaType, isImageRef, messageImages, messageToolCalls, normalizeImageRef, ROLES, systemMessage, toolResultMessage, toolResultWithImages, userMessage, userMessageWithImages, } from "@celestea/core";
+// ---------------------------------------------------------------------------
+// Message helpers over core's shapes (convenience, not seam vocabulary)
+// ---------------------------------------------------------------------------
+/** Concatenate the text parts of a message's content (joined with "\n"). */
+export function collectMessageText(content) {
+    return content
+        .filter((part) => part.type === "text")
+        .map((part) => part.content)
+        .join("\n");
+}
+/** Drain a stream into an array (helper for tests/CLI; consumers stream live). */
+export async function collectStream(stream) {
+    const events = [];
+    for await (const event of stream)
+        events.push(event);
+    return events;
+}

package/dist/sse/chunks.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Raw chat-completions chunk parsing (P2a).
+ *
+ * Mirrors `crates/llm/src/client.rs`:
+ *   parse_raw_chunk   — delta view of one SSE data payload;
+ *   extract_reasoning — choices[].delta.reasoning_content, joined in wire order;
+ *   thinking_event    — blank-gated thinking event for a reasoning delta;
+ *   parse_arguments   — tool-call arguments (malformed JSON kept raw).
+ *
+ * Non-JSON payloads (heartbeats, noise) and payloads carrying neither a delta
+ * nor usage (e.g. `{"choices":[]}`) return undefined, so the caller skips them.
+ */
+import { type Usage } from "../usage.js";
+import type { StreamEvent } from "../seam.js";
+/** One streamed tool-call fragment (id/name/arguments arrive piecemeal). */
+export interface RawToolCallDelta {
+    index: number;
+    id?: string;
+    name?: string;
+    arguments?: string;
+}
+/** The content + tool_calls part of a single choice's delta. */
+export interface RawChoiceDelta {
+    text?: string;
+    toolCalls: RawToolCallDelta[];
+}
+/** One decoded chat-completions stream chunk (raw wire shape). */
+export interface RawChunk {
+    /** Joined reasoning_content across choices (absent when none). */
+    reasoning?: string;
+    /** Per-choice content / tool-call deltas, in wire order. */
+    choices: RawChoiceDelta[];
+    /** Provider-reported usage, when the chunk carries some. */
+    usage?: Usage;
+}
+/**
+ * Extract chain-of-thought text: DeepSeek streams the CoT in
+ * choices[].delta.reasoning_content (absent for non-reasoning models);
+ * multi-choice deltas join in wire order.
+ */
+export declare function extractReasoning(chunk: unknown): string | undefined;
+/**
+ * Parse one SSE data payload into the delta view. Returns undefined for
+ * non-JSON payloads, `[DONE]`, and JSON payloads without deltas or usage.
+ */
+export declare function parseRawChunk(data: string): RawChunk | undefined;
+/**
+ * The upstream-reported error message of one SSE payload, or undefined when the
+ * payload carries none (W835 R3 batch C / P1-1).
+ *
+ * OpenAI-compatible gateways report a failed generation as a 200 SSE frame
+ * whose body is `{"error":{...}}` (some send `{"message":"..."}`). Such a frame
+ * carries no choices/usage, so [parseRawChunk] returns undefined; without this
+ * check it was silently dropped and a following `[DONE]` could even turn it
+ * into a "successful" empty reply. Recognising it lets the stream terminate as
+ * `failed{kindOf:"stream"}` instead.
+ */
+export declare function parseStreamError(data: string): string | undefined;
+/** Build a thinking event for a non-blank reasoning delta (blank-gated). */
+export declare function thinkingEvent(reasoning: string): StreamEvent | null;
+/** Parse accumulated tool-call arguments; malformed JSON is preserved raw. */
+export declare function parseArguments(raw: string): unknown;

package/dist/sse/chunks.js

@@ -0,0 +1,178 @@
+/**
+ * Raw chat-completions chunk parsing (P2a).
+ *
+ * Mirrors `crates/llm/src/client.rs`:
+ *   parse_raw_chunk   — delta view of one SSE data payload;
+ *   extract_reasoning — choices[].delta.reasoning_content, joined in wire order;
+ *   thinking_event    — blank-gated thinking event for a reasoning delta;
+ *   parse_arguments   — tool-call arguments (malformed JSON kept raw).
+ *
+ * Non-JSON payloads (heartbeats, noise) and payloads carrying neither a delta
+ * nor usage (e.g. `{"choices":[]}`) return undefined, so the caller skips them.
+ */
+import { parseUsage } from "../usage.js";
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function str(v) {
+    return typeof v === "string" ? v : undefined;
+}
+function choiceIndex(v) {
+    return typeof v === "number" && Number.isInteger(v) && v >= 0 ? v : 0;
+}
+/**
+ * Extract chain-of-thought text: DeepSeek streams the CoT in
+ * choices[].delta.reasoning_content (absent for non-reasoning models);
+ * multi-choice deltas join in wire order.
+ */
+export function extractReasoning(chunk) {
+    if (!isRecord(chunk))
+        return undefined;
+    const choices = chunk["choices"];
+    if (!Array.isArray(choices))
+        return undefined;
+    const parts = [];
+    for (const choice of choices) {
+        if (!isRecord(choice))
+            continue;
+        const delta = choice["delta"];
+        if (!isRecord(delta))
+            continue;
+        const reasoning = str(delta["reasoning_content"]);
+        if (reasoning !== undefined && reasoning !== "")
+            parts.push(reasoning);
+    }
+    return parts.length === 0 ? undefined : parts.join("");
+}
+/** Parse one tool_calls array entry into a fragment. */
+function parseToolCallDelta(call) {
+    if (!isRecord(call))
+        return undefined;
+    const fn = isRecord(call["function"]) ? call["function"] : {};
+    const fragment = { index: choiceIndex(call["index"]) };
+    const id = str(call["id"]);
+    const name = str(fn["name"]);
+    const args = str(fn["arguments"]);
+    if (id !== undefined)
+        fragment.id = id;
+    if (name !== undefined)
+        fragment.name = name;
+    if (args !== undefined)
+        fragment.arguments = args;
+    return fragment;
+}
+/** Parse one choices[] entry into its delta view, or undefined when empty. */
+function parseChoiceDelta(choice) {
+    if (!isRecord(choice))
+        return undefined;
+    const delta = choice["delta"];
+    if (!isRecord(delta))
+        return undefined;
+    const rawText = str(delta["content"]);
+    const toolCalls = [];
+    const rawCalls = delta["tool_calls"];
+    if (Array.isArray(rawCalls)) {
+        for (const call of rawCalls) {
+            const fragment = parseToolCallDelta(call);
+            if (fragment !== undefined)
+                toolCalls.push(fragment);
+        }
+    }
+    const out = { toolCalls };
+    if (rawText !== undefined && rawText !== "")
+        out.text = rawText;
+    if (out.text === undefined && toolCalls.length === 0)
+        return undefined;
+    return out;
+}
+/**
+ * Parse one SSE data payload into the delta view. Returns undefined for
+ * non-JSON payloads, `[DONE]`, and JSON payloads without deltas or usage.
+ */
+export function parseRawChunk(data) {
+    let value;
+    try {
+        value = JSON.parse(data);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(value))
+        return undefined;
+    const reasoning = extractReasoning(value);
+    const usage = parseUsage(value);
+    const choices = [];
+    const rawChoices = value["choices"];
+    if (Array.isArray(rawChoices)) {
+        for (const choice of rawChoices) {
+            const delta = parseChoiceDelta(choice);
+            if (delta !== undefined)
+                choices.push(delta);
+        }
+    }
+    if (reasoning === undefined && choices.length === 0 && usage === undefined)
+        return undefined;
+    const chunk = { choices };
+    if (reasoning !== undefined)
+        chunk.reasoning = reasoning;
+    if (usage !== undefined)
+        chunk.usage = usage;
+    return chunk;
+}
+/**
+ * The upstream-reported error message of one SSE payload, or undefined when the
+ * payload carries none (W835 R3 batch C / P1-1).
+ *
+ * OpenAI-compatible gateways report a failed generation as a 200 SSE frame
+ * whose body is `{"error":{...}}` (some send `{"message":"..."}`). Such a frame
+ * carries no choices/usage, so [parseRawChunk] returns undefined; without this
+ * check it was silently dropped and a following `[DONE]` could even turn it
+ * into a "successful" empty reply. Recognising it lets the stream terminate as
+ * `failed{kindOf:"stream"}` instead.
+ */
+export function parseStreamError(data) {
+    let value;
+    try {
+        value = JSON.parse(data);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(value))
+        return undefined;
+    const error = value["error"];
+    if (error !== undefined && error !== null) {
+        const text = errorText(error);
+        if (text !== undefined)
+            return text;
+    }
+    const message = str(value["message"]);
+    return message !== undefined && message.trim() !== "" ? message : undefined;
+}
+/** Best-effort text of an `error` payload (string, or a nested message/detail). */
+function errorText(error) {
+    if (typeof error === "string")
+        return error.trim() === "" ? undefined : error;
+    if (!isRecord(error))
+        return undefined;
+    for (const key of ["message", "detail"]) {
+        const text = str(error[key]);
+        if (text !== undefined && text.trim() !== "")
+            return text;
+    }
+    const json = JSON.stringify(error);
+    return json === undefined || json === "{}" ? undefined : json;
+}
+/** Build a thinking event for a non-blank reasoning delta (blank-gated). */
+export function thinkingEvent(reasoning) {
+    return reasoning.trim() === "" ? null : { kind: "thinking", text: reasoning };
+}
+/** Parse accumulated tool-call arguments; malformed JSON is preserved raw. */
+export function parseArguments(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+}

package/dist/sse/frames.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Incremental SSE frame decoder (P2a).
+ *
+ * Mirrors the `eventsource-stream` layer used by
+ * `crates/llm/src/client.rs::raw_chunk_stream`: frames are newline-terminated
+ * and dispatched by a blank line, comment lines (`: keepalive`) and unknown
+ * fields are ignored, and an unterminated trailing frame at EOF is dropped.
+ *
+ * The decoder is incremental on purpose: bytes may arrive split anywhere —
+ * inside a frame, between CR and LF, or inside a multi-byte UTF-8 character
+ * (the byte-level driver feeds it decoded text via a StringDecoder).
+ */
+/**
+ * Hard cap on the decoded, not-yet-framed buffer (W835 R3 batch E / P2-5).
+ *
+ * A stream that never emits a newline would otherwise grow the buffer without
+ * bound (the idle guard only fires when NO bytes arrive). 4 MiB is ~8x the
+ * largest plausible single frame: providers chunk output deltas, and even a
+ * full 128k-token answer delivered as one frame stays below ~0.5 MiB.
+ * Exceeding it is a terminal failed{kindOf:"stream"} on the stream path.
+ */
+export declare const MAX_SSE_BUFFER_BYTES: number;
+/** The decoder's newline-less buffer exceeded [MAX_SSE_BUFFER_BYTES]. */
+export declare class SseBufferOverflowError extends Error {
+    readonly limit: number;
+    constructor(limit: number);
+}
+/** One fully decoded SSE frame (blank-line terminated). */
+export interface SseFrame {
+    /** Event name; "message" when the frame carried no `event:` field. */
+    event: string;
+    /** Joined `data:` lines (never "" — empty frames are not dispatched). */
+    data: string;
+}
+export declare class SseDecoder {
+    #private;
+    /** Feed decoded text; returns the frames that completed on this input. */
+    push(text: string): SseFrame[];
+    /** End of input: flush complete lines, drop the torn remainder. */
+    flush(): SseFrame[];
+}

package/dist/sse/frames.js

@@ -0,0 +1,122 @@
+/**
+ * Incremental SSE frame decoder (P2a).
+ *
+ * Mirrors the `eventsource-stream` layer used by
+ * `crates/llm/src/client.rs::raw_chunk_stream`: frames are newline-terminated
+ * and dispatched by a blank line, comment lines (`: keepalive`) and unknown
+ * fields are ignored, and an unterminated trailing frame at EOF is dropped.
+ *
+ * The decoder is incremental on purpose: bytes may arrive split anywhere —
+ * inside a frame, between CR and LF, or inside a multi-byte UTF-8 character
+ * (the byte-level driver feeds it decoded text via a StringDecoder).
+ */
+/**
+ * Hard cap on the decoded, not-yet-framed buffer (W835 R3 batch E / P2-5).
+ *
+ * A stream that never emits a newline would otherwise grow the buffer without
+ * bound (the idle guard only fires when NO bytes arrive). 4 MiB is ~8x the
+ * largest plausible single frame: providers chunk output deltas, and even a
+ * full 128k-token answer delivered as one frame stays below ~0.5 MiB.
+ * Exceeding it is a terminal failed{kindOf:"stream"} on the stream path.
+ */
+export const MAX_SSE_BUFFER_BYTES = 4 * 1024 * 1024;
+/** The decoder's newline-less buffer exceeded [MAX_SSE_BUFFER_BYTES]. */
+export class SseBufferOverflowError extends Error {
+    limit;
+    constructor(limit) {
+        super("SSE decoder buffer exceeded " + limit + " bytes without a frame boundary");
+        this.limit = limit;
+        this.name = "SseBufferOverflowError";
+    }
+}
+export class SseDecoder {
+    #buffer = "";
+    #event = "";
+    #data = [];
+    #bytes = 0;
+    /** Feed decoded text; returns the frames that completed on this input. */
+    push(text) {
+        this.#buffer += text;
+        this.#bytes += Buffer.byteLength(text, "utf8");
+        const frames = this.#drain(false);
+        // Check AFTER draining: a big batch of COMPLETE frames is fine; only a
+        // buffer that cannot be framed within the cap is a runaway (P2-5).
+        if (this.#bytes > MAX_SSE_BUFFER_BYTES)
+            throw new SseBufferOverflowError(MAX_SSE_BUFFER_BYTES);
+        return frames;
+    }
+    /** End of input: flush complete lines, drop the torn remainder. */
+    flush() {
+        const frames = this.#drain(true);
+        this.#buffer = "";
+        this.#bytes = 0;
+        return frames;
+    }
+    #drain(final) {
+        const frames = [];
+        for (;;) {
+            const line = this.#nextLine(final);
+            if (line === null)
+                break;
+            if (line === "") {
+                const frame = this.#dispatch();
+                if (frame !== null)
+                    frames.push(frame);
+                continue;
+            }
+            if (line.startsWith(":"))
+                continue; // comment / keepalive line
+            this.#consumeField(line);
+        }
+        return frames;
+    }
+    /** Next complete line, or null when more bytes are needed. */
+    #nextLine(final) {
+        const buf = this.#buffer;
+        const lf = buf.indexOf("\n");
+        const cr = buf.indexOf("\r");
+        let at;
+        let len = 1;
+        if (lf !== -1 && (cr === -1 || lf < cr)) {
+            at = lf;
+        }
+        else if (cr !== -1) {
+            // A trailing CR may be the first half of CRLF: wait for more bytes.
+            if (cr === buf.length - 1 && !final)
+                return null;
+            at = cr;
+            if (buf.charAt(cr + 1) === "\n")
+                len = 2;
+        }
+        else {
+            return null;
+        }
+        const line = buf.slice(0, at);
+        const consumed = buf.slice(0, at + len);
+        this.#buffer = buf.slice(at + len);
+        this.#bytes -= Buffer.byteLength(consumed, "utf8");
+        return line;
+    }
+    #consumeField(line) {
+        const colon = line.indexOf(":");
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let value = colon === -1 ? "" : line.slice(colon + 1);
+        if (value.startsWith(" "))
+            value = value.slice(1);
+        if (field === "event")
+            this.#event = value;
+        else if (field === "data")
+            this.#data.push(value);
+        // id / retry / unknown fields: not part of this contract, ignored.
+    }
+    #dispatch() {
+        const event = this.#event;
+        const data = this.#data;
+        this.#event = "";
+        this.#data = [];
+        // Per the SSE spec an empty data buffer dispatches nothing.
+        if (data.length === 0)
+            return null;
+        return { event: event === "" ? "message" : event, data: data.join("\n") };
+    }
+}