@celestea/llm 2.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mcd0LUO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# @celestea/llm — OpenAI-compatible LLM provider (P2a)
+
+Parity target: `celestea_harness/crates/llm` (+ `crates/runtime/src/compose.rs`
+for profile resolution). Raw SSE transport, usage/cache-hit parsing, three
+timeout tiers, free-form `reasoning_effort` passthrough.
+
+## 职责
+
+* **请求构造** — `POST {base_url}/chat/completions`，体为
+  `{model, messages, tools?, reasoning_effort?, max_tokens?, temperature?, stream:true}`。
+  `reasoning_effort` 是**自由字符串**，原样透传（`"max"` 就是 `"max"`，不改名、不折叠、不裁剪）；
+  请求的 `max_tokens` 优先，缺省回落到配置的 `max_output_tokens`。
+* **SSE 解析** — 逐行 `data:`、空行分帧；跳过注释/keepalive/空帧/非 JSON；`[DONE]` 结束；
+  `reasoning_content` → `thinking` 增量（实时 CoT），`content` → `text` 增量，
+  `tool_calls` 按 index 分片累积，`usage` 帧（含“只有 usage 的尾帧”）在终态事件前下发。
+* **用量解析** — `Usage{prompt_tokens, completion_tokens, total_tokens, cache_read, reasoning_tokens}`；
+  `cache_read` 兼容三种键：`prompt_cache_hit_tokens` / `cache_read_input_tokens` /
+  `prompt_tokens_details.cached_tokens`（前两者优先），
+  `reasoning_tokens` 取 `completion_tokens_details.reasoning_tokens`。
+* **三档超时（无总请求超时）** — connect 15s、响应头 60s、流空闲 90s；
+  0 = 关闭该档；长生成只靠“帧间隔”判活，永不因总时长被杀。
+* **错误语义** — 响应头超时抛
+  `llm timeout: response headers not received within {N}ms ({url})`（`kind="generate"`）；
+  connect 超时抛 `llm timeout: connect timeout: ...`；
+  流空闲 → 终态事件 `failed{kindOf:"timeout"}`；流中途解码/传输错误 → `failed{kindOf:"stream"}`；
+  未收到 `[DONE]` 而流结束 → `interrupted`；HTTP 非 2xx → `stream request failed: {status}: {片段}`。
+  **任何路径都不会伪造 done**（R1）。
+* **密钥安全** — API key 只从运行时 profile / 环境变量读取（`api_key_env`，默认
+  `DEEPSEEK_API_KEY`），只作为 `Authorization: Bearer` 头发送；不落盘、不写日志、
+  不进入错误文案，`describe()` 视图也不含 key。
+
+## 公开 API（唯一出口：`src/index.ts`）
+
+| 分类 | 导出 |
+|---|---|
+| seam 类型（re-export core） | `Llm`, `LlmStream`, `StreamEvent`, `Message`, `Content`, `TextContent`, `ToolCallContent`, `ToolCall`, `Role`, `ROLES`, `ToolSpec`, `ModelRequest`, `ModelRequestDraft`, `LlmError` |
+| seam 工具（re-export core，除 helper） | `userMessage`, `systemMessage`, `assistantText`, `assistantToolCall`, `toolResultMessage`, `collectMessageText`, `messageToolCalls`, `collectStream` |
+| 用量 | `Usage`, `parseUsage`, `usageFromObject`, `usageIsEmpty`, `zeroUsage`, `ZERO_USAGE`, `cacheHitRatio`, `USAGE_REQUIRED_KEYS`, `CACHE_READ_FLAT_KEYS`, `CACHE_READ_NESTED`, `REASONING_TOKENS_NESTED` |
+| 错误 | `LlmError`, `LlmErrorKind`, `TimeoutStage`, `TIMEOUT_ERROR_PREFIX`, `timeoutError`, `responseHeaderTimeoutError`, `connectTimeoutError`, `streamIdleTimeoutMessage`, `isTimeoutError`, `errorKind` |
+| 超时三档 | `TimeoutTiers`, `TimeoutProfile`, `DEFAULT_TIMEOUTS`, `DEFAULT_*_TIMEOUT_MS`, `CONNECT_TIMEOUT_ENV`, `RESPONSE_TIMEOUT_ENV`, `STREAM_IDLE_TIMEOUT_ENV`, `PROFILE_TIMEOUT_KEYS`, `resolveTimeoutMs`, `resolveTimeoutTiers`, `readTimeoutProfile`, `isTimeoutMs`, `EnvLike` |
+| profile→配置 | `LlmProfile`, `ResolvedClientConfig`, `resolveClientConfig`, `resolveApiKey`, `tiersFromConfig`, `normalizeReasoningEffort`, `validateModel`, `API_KEY_ENV`, `BASE_URL_ENV`, `DEFAULT_BASE_URL`, `DEFAULT_MODEL` |
+| 适配器 | `OpenAiCompatClient`（实现 `Llm`）, `OpenAiCompatOptions`, `createDeepSeekLlm`, `LlmRegistry`, `createDeepSeekRegistry`, `DEEPSEEK_PROVIDER_NAME` |
+
+调用方只依赖 `Llm` seam 与上面的类型；SSE 分帧、wire 映射、HTTP 传输是包内实现，
+**不从 index.ts 导出**（`packages/llm/src/sse/*`、`wire.ts`、`transport.ts`、`stream.ts`）。
+
+## 超时契约
+
+| 档位 | 默认 | profile 键 | 环境变量 | 语义 |
+|---|---|---|---|---|
+| connect | 15000 ms | `llm_connect_timeout_ms` | `CELESTEA_LLM_CONNECT_TIMEOUT_MS` | TCP/TLS 握手 |
+| response | 60000 ms | `llm_response_timeout_ms` | `CELESTEA_LLM_RESPONSE_TIMEOUT_MS` | `send()` → 响应头 |
+| stream idle | 90000 ms | `llm_stream_idle_timeout_ms` | `CELESTEA_LLM_STREAM_IDLE_TIMEOUT_MS` | 相邻两个数据帧的间隔（含首帧等待） |
+
+优先级 **env > profile 键 > 内置默认**；`0` 关闭该档；env 空白/不可解析则回落到 profile 键
+（与 `crates/runtime/src/config.rs::resolve_llm_timeout_ms` 一致）。
+**不存在总请求超时**：只有“响应头没来”和“帧间隔断了”会触发，长时间生成不会被杀。
+
+## 用量契约
+
+`Usage` 五个扁平计数即 `statusline.usage` 的字段（`prompt_tokens` / `completion_tokens` /
+`total_tokens` / `cache_read` / `reasoning_tokens`）；`cache_hit_ratio = clamp(cache_read /
+prompt_tokens, 0, 1)`，4 位小数。全零 usage 视为“没有 usage 帧”（`undefined`），
+非数字/负数/小数一律按 0 处理（对齐 serde `as_u64`）。
+
+## 扩展点：新增一个 provider
+
+1. 若新 provider 也讲 OpenAI `chat/completions`（仅 base_url / 模型名不同），直接复用
+   `OpenAiCompatClient`，用 profile 覆盖 `base_url` / `model` / `reasoning_effort` / 超时键即可。
+2. 若请求体或流格式不同（例如 `responses` / `anthropic_messages`），实现 `Llm` seam：
+
+   ```ts
+   class MyProvider implements Llm {
+     async generate(req: ModelRequest): Promise<LlmStream> { /* 自己的 wire + SSE */ }
+   }
+   ```
+
+   复用 `timeouts.ts`（三档解析）、`usage.ts`（用量解析）、`errors.ts`（超时前缀/kind 映射）
+   与 `stream.ts` 的 `TurnAccumulator`，即可继承同样的超时/用量/终态语义。
+3. 注册：`registry.register("myprovider", new MyProvider(...))`。
+   `crates/llm/src/registry.rs` 的对应物是 `createDeepSeekRegistry(llm)`。
+
+## core seam（A1 / W746：已收口）
+
+`packages/llm` 以**插件**形式实现 `packages/core` 的 LLM seam，只依赖 `packages/core`
+（不依赖 session / tools / agent-loop / runtime）。W746 之前本包自带 `src/seam.ts` 这份与 core
+同名的词汇表（`src/*.ts` 对 core 的 import 数为 **0**）；现在词汇表**就是 core 的**：
+
+```ts
+// seam.ts：直接 re-export core（值也 re-export，`LlmError` 因此跨包 instanceof 一致）
+export { assistantText, messageToolCalls, userMessage, ROLES, … } from "@celestea/core";
+export type { Content, LlmError, Message, ModelRequest, Role, StreamEvent, … } from "@celestea/core";
+```
+
+- **零重复定义**：`Message` / `Content` / `Role` / `ToolCall` / `ToolSpec` / `ModelRequest` /
+  `Usage` / `LlmError` / `LlmRegistry` 全部来自 core（`seam.ts` / `usage.ts` / `errors.ts` /
+  `provider.ts` 只保留「解析」「构造器」「provider 注册」这类 provider 侧代码）。
+- **`instanceof` 跨包一致**：`LlmError` 类本体在 `packages/core/src/stream.ts`，本包
+  `statusError()` / `timeoutError()` 造出的错误在 core 侧同样是 `instanceof LlmError`
+  （`src/seam.test.ts` 断言类对象同一性，不是结构相同）。
+- **`LlmRegistry`**：删除本包同名最小实现，`createDeepSeekRegistry` 改用 core 的
+  `LlmRegistry<Llm>`（core 的注册表加了带默认值的类型参数，见 `core/src/llm.ts`）。
+
+### 唯一保留的差异（`StreamEvent.failed.kindOf`）
+
+| 项 | core | 本包 | 处置 |
+|---|---|---|---|
+| `StreamEvent.failed.kindOf` | `"generate" \| "stream"` | `"generate" \| "stream" \| "timeout"` | **本包唯一放宽的成员**（SSE 空闲守卫 → `"timeout"`，旧实现侧 `Failed{kind}` 本是自由字符串）。其余成员由 core 的联合类型派生（`Exclude<CoreStreamEvent, {kind:"failed"}>`），core 新增变体会自动出现。见 `src/seam.ts` 的 `TODO(core-timeout-kind)` |
+| `ModelRequest` | 全字段必填 | `ModelRequest` 照旧 re-export；另有 `ModelRequestDraft = Partial<ModelRequest> & { messages }` 作为**直连调用**的入参 | 引擎交给本包的一定是全字段 core `ModelRequest`（可直接当 draft 用）；一次性调用只给 `messages` 也合法，wire 映射的「缺省即空」回退语义未变 |
+| `LlmError` | 结构化类（`kind`/`isTimeout`/`timeoutStage`/`httpStatus`/`retryable`） | 同一个类 | 类本体已在 core，本包只留 `TIMEOUT_ERROR_PREFIX` 与构造器 |
+| seam 词汇（`Role`/`Content`/`ToolCall`/`Message`/`ToolSpec`/`Usage`） | `message.ts` + `types.ts` | re-export | 无差异 |
+| `Llm` service token | `LLM_SERVICE` / `LLM_REGISTRY_SERVICE` | 无 | 组合期（compose）由 runtime 侧使用；本包不涉及 |
+
+**为什么放宽没进 core**（选择理由）：要放宽 `kindOf` 就必须同时放宽 core 的
+`TurnOutcome.error.kind`，因为 `packages/agent-loop/src/step.ts:49` 把 `kindOf` 原样写进
+`TurnOutcome.error.kind`；而 `TurnOutcome.error.kind` 的取值被冻结契约
+`contracts/session-event.schema.json` 钉成 `["generate","stream"]`，且 W744 起该 schema 会被
+`tests/contract-parity.test.ts` 真实执行（第 68 / 119 行）——放宽 core 会让引擎能产出契约拒绝
+的行。契约冻结 + agent-loop 不在本刀范围内，所以本刀选择「保留一层最小适配」：差异只此一个
+成员，有损降级点收敛在唯一的 host 适配器
+（`apps/studio/src/runtime/llm-assembly.ts:69-96`，`kindOf: "timeout"` → `"stream"`，
+`llm timeout:` 前缀保住细节）。真正放宽需要 契约 + agent-loop + 本包 三处一起动。
+
+## 目录
+
+| 文件 | 行数(约) | 职责 |
+|---|---|---|
+| `src/index.ts` | 127 | 唯一公开出口 |
+| `src/seam.ts` | 125 | core 词汇表的 re-export + `Llm` 接口（唯一放宽）+ 消息/流 helper |
+| `src/client.ts` | 176 | `OpenAiCompatClient`（实现 `Llm`）与 HTTP 错误包装 |
+| `src/transport.ts` | 150 | HTTP 传输 + connect/响应头两档超时 + 错误体片段 + 脱敏 |
+| `src/stream.ts` | 246 | 流空闲超时读体 + `TurnAccumulator` + 终态事件（done/failed/interrupted） |
+| `src/sse/frames.ts` | 98 | 增量 SSE 分帧器 |
+| `src/sse/chunks.ts` | 151 | chunk 视图、`reasoning_content`、tool-call 分片、参数解析 |
+| `src/wire.ts` | 135 | 消息/工具映射与请求体构造 |
+| `src/usage.ts` | 107 | 用量与三种 cache 键解析（`Usage`/`zeroUsage`/`usageIsEmpty` re-export core） |
+| `src/errors.ts` | 108 | 超时前缀 + 结构化错误构造器（`LlmError` 类本体在 core） |
+| `src/timeouts.ts` | 153 | 三档超时解析（profile 键 + env + 默认） |
+| `src/profile.ts` | 121 | profile→配置、api key 只从 env、effort 直通 |
+| `src/provider.ts` | 48 | provider 注册与 from-env 构造（用 core 的 `LlmRegistry`） |
+| `src/*.test.ts`, `src/mock-upstream.test-util.ts` | — | 本地 mock HTTP server 测试（无网络）；`seam.test.ts` 锁 A1 不变量 |

package/dist/client.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The OpenAI-compatible provider client (P2a).
+ *
+ * Implements the `Llm` seam on top of the pieces of this package:
+ * wire.ts (request body), transport.ts (connect + response-header guards),
+ * stream.ts (idle-guarded SSE decoding), usage.ts (usage/cache parsing).
+ *
+ * Error semantics:
+ *   * response-header timeout -> LlmError `llm timeout: response headers not
+ *     received within {N}ms ({url})`, kind "generate";
+ *   * connect timeout         -> LlmError `llm timeout: connect timeout: ...`;
+ *   * non-2xx                 -> LlmError `stream request failed: <status>:
+ *     <body snippet>` (no API key);
+ *   * stream idle stall       -> stream event failed{kind:"timeout"};
+ *   * mid-stream decode error -> stream event failed{kind:"stream"};
+ *   * missing [DONE]          -> stream event interrupted.
+ *
+ * The API key lives in a private field, is sent only as a Bearer header, and
+ * is never logged, serialized or echoed into an error message.
+ */
+import { type LlmProfile, type ResolvedClientConfig } from "./profile.js";
+import { type ChatCompletionsBody } from "./wire.js";
+import type { Llm, LlmStream, ModelRequestDraft } from "./seam.js";
+import { type EnvLike, type TimeoutTiers } from "./timeouts.js";
+/** Constructor options. Timeout fields: 0 = disabled (`ms_to_duration`). */
+export interface OpenAiCompatOptions {
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    /** Free-form tier string; passed through verbatim, never folded/renamed. */
+    reasoningEffort?: string | null;
+    maxOutputTokens?: number | null;
+    connectTimeoutMs?: number | null;
+    responseTimeoutMs?: number | null;
+    streamIdleTimeoutMs?: number | null;
+}
+export declare class OpenAiCompatClient implements Llm {
+    #private;
+    constructor(options: OpenAiCompatOptions);
+    /** The configured model (used when a request leaves its model empty). */
+    get model(): string;
+    /** Effective timeouts (null = that stage is disabled). */
+    timeouts(): TimeoutTiers;
+    /** Secret-free view of the configuration (safe to log/serialize). */
+    describe(): {
+        baseUrl: string;
+        model: string;
+        reasoningEffort: string | null;
+        maxOutputTokens: number | null;
+        timeouts: TimeoutTiers;
+    };
+    /** The endpoint this client posts to. */
+    endpoint(): string;
+    /** Request model wins; the configured model is the fallback. */
+    effectiveModel(req: ModelRequestDraft): string;
+    /** Serialized request body (reasoning_effort injected verbatim). */
+    requestBody(req: ModelRequestDraft, model?: string): ChatCompletionsBody;
+    /**
+     * Start a streaming turn. Pre-stream failures (model validation, connect /
+     * response-header timeout, transport error, non-2xx status) reject with an
+     * LlmError; the returned stream then carries the terminal state as an event.
+     */
+    generate(req: ModelRequestDraft): Promise<LlmStream>;
+    /** Build a client from a resolved configuration. */
+    static fromConfig(config: ResolvedClientConfig): OpenAiCompatClient;
+    /** Options from a runtime profile + environment (api key from env only). */
+    static fromProfile(profile?: LlmProfile | null, env?: EnvLike): OpenAiCompatClient;
+}

package/dist/client.js

@@ -0,0 +1,141 @@
+/**
+ * The OpenAI-compatible provider client (P2a).
+ *
+ * Implements the `Llm` seam on top of the pieces of this package:
+ * wire.ts (request body), transport.ts (connect + response-header guards),
+ * stream.ts (idle-guarded SSE decoding), usage.ts (usage/cache parsing).
+ *
+ * Error semantics:
+ *   * response-header timeout -> LlmError `llm timeout: response headers not
+ *     received within {N}ms ({url})`, kind "generate";
+ *   * connect timeout         -> LlmError `llm timeout: connect timeout: ...`;
+ *   * non-2xx                 -> LlmError `stream request failed: <status>:
+ *     <body snippet>` (no API key);
+ *   * stream idle stall       -> stream event failed{kind:"timeout"};
+ *   * mid-stream decode error -> stream event failed{kind:"stream"};
+ *   * missing [DONE]          -> stream event interrupted.
+ *
+ * The API key lives in a private field, is sent only as a Bearer header, and
+ * is never logged, serialized or echoed into an error message.
+ */
+import { ImageUnsupportedError, isImageUnsupportedBody, parseRetryAfterHeader, setRetryAfterMs, statusError, } from "./errors.js";
+import { resolveClientConfig, validateModel, } from "./profile.js";
+import { buildRequestBody, chatCompletionsUrl, } from "./wire.js";
+import { httpStatusLabel, readBodySnippet, redact, sendChatRequest } from "./transport.js";
+import { streamEvents } from "./stream.js";
+import { DEFAULT_TIMEOUTS, timeoutMsOf } from "./timeouts.js";
+export class OpenAiCompatClient {
+    #baseUrl;
+    #apiKey;
+    #model;
+    #reasoningEffort;
+    #maxOutputTokens;
+    #connectMs;
+    #responseMs;
+    #idleMs;
+    constructor(options) {
+        this.#baseUrl = options.baseUrl;
+        this.#apiKey = options.apiKey;
+        this.#model = options.model;
+        this.#reasoningEffort = options.reasoningEffort ?? null;
+        // W835 (R3 batch D / P2-2): 0 = "clear cap" (contracts/endpoints.json:540),
+        // never a literal max_tokens:0 on the wire.
+        const maxOut = options.maxOutputTokens;
+        this.#maxOutputTokens = typeof maxOut === "number" && Number.isFinite(maxOut) && maxOut > 0 ? Math.floor(maxOut) : null;
+        this.#connectMs = timeoutMsOf(options.connectTimeoutMs, DEFAULT_TIMEOUTS.connectMs);
+        this.#responseMs = timeoutMsOf(options.responseTimeoutMs, DEFAULT_TIMEOUTS.responseMs);
+        this.#idleMs = timeoutMsOf(options.streamIdleTimeoutMs, DEFAULT_TIMEOUTS.idleMs);
+    }
+    /** The configured model (used when a request leaves its model empty). */
+    get model() {
+        return this.#model;
+    }
+    /** Effective timeouts (null = that stage is disabled). */
+    timeouts() {
+        return { connectMs: this.#connectMs, responseMs: this.#responseMs, idleMs: this.#idleMs };
+    }
+    /** Secret-free view of the configuration (safe to log/serialize). */
+    describe() {
+        return {
+            baseUrl: this.#baseUrl,
+            model: this.#model,
+            reasoningEffort: this.#reasoningEffort,
+            maxOutputTokens: this.#maxOutputTokens,
+            timeouts: this.timeouts(),
+        };
+    }
+    /** The endpoint this client posts to. */
+    endpoint() {
+        return chatCompletionsUrl(this.#baseUrl);
+    }
+    /** Request model wins; the configured model is the fallback. */
+    effectiveModel(req) {
+        return req.model === undefined || req.model === "" ? this.#model : req.model;
+    }
+    /** Serialized request body (reasoning_effort injected verbatim). */
+    requestBody(req, model = this.effectiveModel(req)) {
+        return buildRequestBody(req, {
+            model,
+            reasoningEffort: this.#reasoningEffort,
+            maxOutputTokens: this.#maxOutputTokens,
+        });
+    }
+    /**
+     * Start a streaming turn. Pre-stream failures (model validation, connect /
+     * response-header timeout, transport error, non-2xx status) reject with an
+     * LlmError; the returned stream then carries the terminal state as an event.
+     */
+    async generate(req) {
+        const model = this.effectiveModel(req);
+        validateModel(model);
+        const body = this.requestBody(req, model);
+        const url = this.endpoint();
+        const response = await sendChatRequest({
+            url,
+            apiKey: this.#apiKey,
+            body: JSON.stringify(body),
+            connectMs: this.#connectMs,
+            responseMs: this.#responseMs,
+        });
+        await assertSuccess(response, this.#apiKey);
+        return streamEvents(response, this.#idleMs);
+    }
+    /** Build a client from a resolved configuration. */
+    static fromConfig(config) {
+        return new OpenAiCompatClient({
+            baseUrl: config.baseUrl,
+            apiKey: config.apiKey,
+            model: config.model,
+            reasoningEffort: config.reasoningEffort,
+            maxOutputTokens: config.maxOutputTokens,
+            connectTimeoutMs: config.connectTimeoutMs,
+            responseTimeoutMs: config.responseTimeoutMs,
+            streamIdleTimeoutMs: config.streamIdleTimeoutMs,
+        });
+    }
+    /** Options from a runtime profile + environment (api key from env only). */
+    static fromProfile(profile, env = process.env) {
+        return OpenAiCompatClient.fromConfig(resolveClientConfig(profile, env));
+    }
+}
+/** Reject with a status-bearing error when the response is not 2xx. */
+async function assertSuccess(response, apiKey) {
+    const status = response.statusCode ?? 0;
+    if (status >= 200 && status < 300)
+        return;
+    const text = await readBodySnippet(response);
+    response.destroy();
+    const label = httpStatusLabel(status, response.statusMessage);
+    // W804 section 7.6: a 4xx whose body names the image modality is classified
+    // BEFORE the generic status error, so the downgrade decorator can react.
+    // W824 N2: also replace this client's own key literally - an upstream may
+    // echo an arbitrary provider key that matches no token shape.
+    const body = redact(text, [apiKey]);
+    const error = status >= 400 && status < 500 && isImageUnsupportedBody(text)
+        ? new ImageUnsupportedError(status, label, body)
+        : statusError(status, label, body);
+    // E §4.2.2 P1: the header is captured here, where the response is still in
+    // hand; the P0 error object and its message stay byte-for-byte unchanged.
+    setRetryAfterMs(error, parseRetryAfterHeader(response.headers["retry-after"]));
+    throw error;
+}

package/dist/errors.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Structured LLM errors (P2a; status/retryability fields: iteration E §4 P0).
+ *
+ * A1 (W746): the `LlmError` class and its `LlmErrorKind` / `TimeoutStage` /
+ * `LlmErrorOptions` vocabulary live in `@celestea/core` (`core/src/stream.ts`)
+ * and are re-exported here — this package no longer owns a second `LlmError`,
+ * so `instanceof LlmError` and `isTimeoutError` agree across packages. What
+ * stays here is provider-side and cannot move to core: the canonical timeout
+ * prefix and the error builders.
+ *
+ * The semantics ride the canonical `llm timeout` message prefix: an error
+ * thrown out of `generate` maps to `TurnOutcome::Error { kind: "generate" }`, a
+ * stalled stream maps to `kind: "timeout"`, a mid-stream decode failure to
+ * `kind: "stream"`. TypeScript can also carry that distinction explicitly, so
+ * `LlmError` exposes `kind` (the turn-outcome kind a caller should report) plus
+ * `isTimeout` and the stage that tripped.
+ *
+ * Iteration E §4 P0 adds the machine-readable *failure cause* on top of the
+ * message text: `httpStatus` (the status of the response that failed, `null`
+ * when no response ever arrived) and `retryable` (whether another attempt or
+ * another target could plausibly succeed). The defaults are the conservative
+ * pair `(null, false)`: a failure carrying no evidence of being transient is
+ * treated as a local/configuration problem, not as something to retry.
+ * Nothing reads these fields yet — P0 is observability only, so every message,
+ * throw site, SSE frame and statusline field is byte-for-byte unchanged.
+ */
+import { LlmError, type LlmErrorKind, type LlmErrorOptions, type TimeoutStage } from "@celestea/core";
+export { LlmError };
+export type { LlmErrorKind, LlmErrorOptions, TimeoutStage };
+/** Canonical prefix of every timeout error (`TIMEOUT_ERROR_PREFIX`). */
+export declare const TIMEOUT_ERROR_PREFIX = "llm timeout";
+/**
+ * Non-5xx statuses worth retrying (§4.2.2 `retryableStatuses`): request
+ * timeout, too early, rate limited. Every 5xx counts as retryable as well.
+ */
+export declare const RETRYABLE_HTTP_STATUSES: readonly number[];
+/** Would another attempt / another target help, judged from the status alone? */
+export declare function isRetryableStatus(status: number | null): boolean;
+/**
+ * Build the non-2xx error. The message format is unchanged from W511
+ * (`stream request failed: <label>: <body snippet>`): the status becomes
+ * machine-readable *in addition* to the text, never instead of it.
+ */
+export declare function statusError(status: number, label: string, bodySnippet?: string): LlmError;
+/**
+ * W804 (section 7.6): the upstream report patterns that mean "this model cannot
+ * take an image". ONLY known patterns are classified; anything else stays an
+ * ordinary status error (we never guess).
+ */
+export declare const IMAGE_UNSUPPORTED_MARKERS: readonly string[];
+/** True when an upstream error body carries a known image-unsupported marker. */
+export declare function isImageUnsupportedBody(body: string): boolean;
+/**
+ * A 4xx whose body proves the model rejected image input (section 7.6). It is an
+ * LlmError (kind "generate", httpStatus set, NOT retryable to another target)
+ * and carries `imageUnsupported = true` so the downgrade decorator recognises it.
+ */
+export declare class ImageUnsupportedError extends LlmError {
+    readonly imageUnsupported = true;
+    constructor(status: number, label: string, bodySnippet: string);
+}
+/** Recognise an [ImageUnsupportedError] across a structural (re-boxed) boundary. */
+export declare function isImageUnsupportedError(e: unknown): e is ImageUnsupportedError;
+/** Transport failure before any response (DNS/TCP/TLS/socket): retryable. */
+export declare function networkError(message: string): LlmError;
+/**
+ * The caller aborted the turn. Cooperative cancellation does not normally
+ * reach this package (the runner resolves it as the `cancelled` outcome), so
+ * this is the structured vocabulary for an aborted request rather than a new
+ * throw site; an abort is never retryable (§4.2.2).
+ */
+export declare function cancelledError(message?: string): LlmError;
+/** Build a structured timeout error with the canonical prefix. */
+export declare function timeoutError(detail: string, stage?: TimeoutStage | null): LlmError;
+/** Response headers never arrived: `llm timeout: response headers ... (url)`. */
+export declare function responseHeaderTimeoutError(ms: number, url: string): LlmError;
+/** TCP/TLS connect never completed within the connect timeout. */
+export declare function connectTimeoutError(ms: number, url: string): LlmError;
+/** Message of a stalled-stream failure (yielded as failed{kind:"timeout"}). */
+export declare function streamIdleTimeoutMessage(ms: number): string;
+/** Attach a parsed `Retry-After` (ms) to the error that carries it. */
+export declare function setRetryAfterMs(error: unknown, ms: number | null): void;
+/** The parsed `Retry-After` of an error, or null when it carried none. */
+export declare function retryAfterMsOf(error: unknown): number | null;
+/**
+ * `Retry-After` -> milliseconds. Both forms of RFC 9110 are accepted: a
+ * delta-seconds value and an HTTP-date. An unparsable header (or a date in the
+ * past) is "no wait", never a thrown error.
+ */
+export declare function parseRetryAfterHeader(value: string | string[] | undefined, now?: number): number | null;
+/** True for timeout errors (these map to kind "generate" out of generate()). */
+export declare function isTimeoutError(e: unknown): boolean;
+/** The turn-outcome kind an error maps to (defaults to "generate"). */
+export declare function errorKind(e: unknown): LlmErrorKind;

package/dist/errors.js

@@ -0,0 +1,169 @@
+/**
+ * Structured LLM errors (P2a; status/retryability fields: iteration E §4 P0).
+ *
+ * A1 (W746): the `LlmError` class and its `LlmErrorKind` / `TimeoutStage` /
+ * `LlmErrorOptions` vocabulary live in `@celestea/core` (`core/src/stream.ts`)
+ * and are re-exported here — this package no longer owns a second `LlmError`,
+ * so `instanceof LlmError` and `isTimeoutError` agree across packages. What
+ * stays here is provider-side and cannot move to core: the canonical timeout
+ * prefix and the error builders.
+ *
+ * The semantics ride the canonical `llm timeout` message prefix: an error
+ * thrown out of `generate` maps to `TurnOutcome::Error { kind: "generate" }`, a
+ * stalled stream maps to `kind: "timeout"`, a mid-stream decode failure to
+ * `kind: "stream"`. TypeScript can also carry that distinction explicitly, so
+ * `LlmError` exposes `kind` (the turn-outcome kind a caller should report) plus
+ * `isTimeout` and the stage that tripped.
+ *
+ * Iteration E §4 P0 adds the machine-readable *failure cause* on top of the
+ * message text: `httpStatus` (the status of the response that failed, `null`
+ * when no response ever arrived) and `retryable` (whether another attempt or
+ * another target could plausibly succeed). The defaults are the conservative
+ * pair `(null, false)`: a failure carrying no evidence of being transient is
+ * treated as a local/configuration problem, not as something to retry.
+ * Nothing reads these fields yet — P0 is observability only, so every message,
+ * throw site, SSE frame and statusline field is byte-for-byte unchanged.
+ */
+import { LlmError } from "@celestea/core";
+export { LlmError };
+/** Canonical prefix of every timeout error (`TIMEOUT_ERROR_PREFIX`). */
+export const TIMEOUT_ERROR_PREFIX = "llm timeout";
+/**
+ * Non-5xx statuses worth retrying (§4.2.2 `retryableStatuses`): request
+ * timeout, too early, rate limited. Every 5xx counts as retryable as well.
+ */
+export const RETRYABLE_HTTP_STATUSES = [408, 425, 429];
+/** Would another attempt / another target help, judged from the status alone? */
+export function isRetryableStatus(status) {
+    if (status === null)
+        return false;
+    return status >= 500 || RETRYABLE_HTTP_STATUSES.includes(status);
+}
+/**
+ * Build the non-2xx error. The message format is unchanged from W511
+ * (`stream request failed: <label>: <body snippet>`): the status becomes
+ * machine-readable *in addition* to the text, never instead of it.
+ */
+export function statusError(status, label, bodySnippet = "") {
+    return new LlmError(`stream request failed: ${label}: ${bodySnippet}`, "generate", {
+        httpStatus: status,
+        retryable: isRetryableStatus(status),
+    });
+}
+/**
+ * W804 (section 7.6): the upstream report patterns that mean "this model cannot
+ * take an image". ONLY known patterns are classified; anything else stays an
+ * ordinary status error (we never guess).
+ */
+export const IMAGE_UNSUPPORTED_MARKERS = [
+    "multimodal input is not supported",
+    "model only supports text input",
+    "unsupported content type 'image_url'",
+    "unsupported content type image_url",
+];
+/** True when an upstream error body carries a known image-unsupported marker. */
+export function isImageUnsupportedBody(body) {
+    const text = body.toLowerCase();
+    return IMAGE_UNSUPPORTED_MARKERS.some((marker) => text.includes(marker));
+}
+/**
+ * A 4xx whose body proves the model rejected image input (section 7.6). It is an
+ * LlmError (kind "generate", httpStatus set, NOT retryable to another target)
+ * and carries `imageUnsupported = true` so the downgrade decorator recognises it.
+ */
+export class ImageUnsupportedError extends LlmError {
+    imageUnsupported = true;
+    constructor(status, label, bodySnippet) {
+        super(`stream request failed: ${label}: ${bodySnippet}`, "generate", { httpStatus: status, retryable: false });
+        this.name = "ImageUnsupportedError";
+    }
+}
+/** Recognise an [ImageUnsupportedError] across a structural (re-boxed) boundary. */
+export function isImageUnsupportedError(e) {
+    if (e instanceof ImageUnsupportedError)
+        return true;
+    return typeof e === "object" && e !== null && e["imageUnsupported"] === true;
+}
+/** Transport failure before any response (DNS/TCP/TLS/socket): retryable. */
+export function networkError(message) {
+    return new LlmError(message, "generate", { retryable: true });
+}
+/**
+ * The caller aborted the turn. Cooperative cancellation does not normally
+ * reach this package (the runner resolves it as the `cancelled` outcome), so
+ * this is the structured vocabulary for an aborted request rather than a new
+ * throw site; an abort is never retryable (§4.2.2).
+ */
+export function cancelledError(message = "turn cancelled by the caller") {
+    return new LlmError(message, "generate", { retryable: false });
+}
+/** Build a structured timeout error with the canonical prefix. */
+export function timeoutError(detail, stage = null) {
+    return new LlmError(`${TIMEOUT_ERROR_PREFIX}: ${detail}`, "generate", {
+        isTimeout: true,
+        timeoutStage: stage,
+        retryable: true,
+    });
+}
+/** Response headers never arrived: `llm timeout: response headers ... (url)`. */
+export function responseHeaderTimeoutError(ms, url) {
+    return timeoutError(`response headers not received within ${ms}ms (${url})`, "response");
+}
+/** TCP/TLS connect never completed within the connect timeout. */
+export function connectTimeoutError(ms, url) {
+    return timeoutError(`connect timeout: no TCP connection within ${ms}ms (${url})`, "connect");
+}
+/** Message of a stalled-stream failure (yielded as failed{kind:"timeout"}). */
+export function streamIdleTimeoutMessage(ms) {
+    return `stream idle timeout: no data chunk for ${ms}ms`;
+}
+/**
+ * `Retry-After` of a failed response, kept OUT of `LlmError`.
+ *
+ * E §4.2.2 P1 honours the header, but `LlmError` lives in `@celestea/core` and
+ * K7/§4.6 forbid widening it for a host-side policy detail. The header is
+ * therefore attached on a side channel keyed by the error object: still
+ * zero-copy, still invisible to every existing reader (`errors.test.ts` asserts
+ * the core fields, which are unchanged), and it never leaks into a message.
+ */
+const RETRY_AFTER_MS = new WeakMap();
+/** Attach a parsed `Retry-After` (ms) to the error that carries it. */
+export function setRetryAfterMs(error, ms) {
+    if (ms === null || !Number.isFinite(ms) || ms < 0)
+        return;
+    if (typeof error === "object" && error !== null)
+        RETRY_AFTER_MS.set(error, Math.floor(ms));
+}
+/** The parsed `Retry-After` of an error, or null when it carried none. */
+export function retryAfterMsOf(error) {
+    if (typeof error !== "object" || error === null)
+        return null;
+    return RETRY_AFTER_MS.get(error) ?? null;
+}
+/**
+ * `Retry-After` -> milliseconds. Both forms of RFC 9110 are accepted: a
+ * delta-seconds value and an HTTP-date. An unparsable header (or a date in the
+ * past) is "no wait", never a thrown error.
+ */
+export function parseRetryAfterHeader(value, now = Date.now()) {
+    const raw = Array.isArray(value) ? value[0] : value;
+    if (raw === undefined)
+        return null;
+    const text = raw.trim();
+    if (text === "")
+        return null;
+    if (/^\d+$/.test(text))
+        return Number.parseInt(text, 10) * 1000;
+    const at = Date.parse(text);
+    if (Number.isNaN(at))
+        return null;
+    return Math.max(0, at - now);
+}
+/** True for timeout errors (these map to kind "generate" out of generate()). */
+export function isTimeoutError(e) {
+    return e instanceof LlmError && e.isTimeout;
+}
+/** The turn-outcome kind an error maps to (defaults to "generate"). */
+export function errorKind(e) {
+    return e instanceof LlmError ? e.kind : "generate";
+}