@wallbreakerno4/opencode-commandcode 0.1.0

package/dist/protocol/json.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 协议核心内部共用的 JSON 结构小工具。上游 wire 数据一律经 `JSON.parse` 到达，
+ * 这里只做形状守卫，不做语义解释。
+ */
+/** 宽松对象守卫：非 null 非 数组的对象才可按字段读取 */
+export declare function asRecord(value: unknown): Record<string, unknown> | null;
+/**
+ * 注入式 fetch 接缝类型（工厂 options.fetch 实例；不用 `typeof fetch`——
+ * bun 的 fetch 带 preconnect 静态属性，mock 实例难以满足其完整签名）。
+ */
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;

package/dist/protocol/json.js

@@ -0,0 +1,8 @@
+/**
+ * 协议核心内部共用的 JSON 结构小工具。上游 wire 数据一律经 `JSON.parse` 到达，
+ * 这里只做形状守卫，不做语义解释。
+ */
+/** 宽松对象守卫：非 null 非 数组的对象才可按字段读取 */
+export function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}

package/dist/protocol/ndjson.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 协议核心·响应方向：`/alpha/generate` 的 NDJSON 事件流 → AI SDK stream part
+ * （契约：docs/spec/protocol.md §2）。
+ *
+ * 严格 NDJSON：按行切分、逐行 `JSON.parse`；跳过空行与 `:` 注释行。不做 SSE 双兼容
+ * （不剥 `data:`、不认 `[DONE]`、不做 `\r\n` 归一——§6 否决项：上游格式真变更时
+ * 错误浮出、修改本项目适配，不预做兼容）。
+ *
+ * 事件消费全表：`start`/`start-step`（流开始，由 head 的 stream-start 承担）、
+ * text/reasoning/tool-input 三组块生命周期（`tool-input-*` 增量必做）、
+ * `tool-call`（字段名兼容 `input│args│arguments` 与 `toolCallId│id`）、
+ * `finish-step` 收据、`finish` 总账单、`response-metadata` 照收、
+ * `error` 不吞错、未知 type 静默忽略。
+ *
+ * 半行残片两结局（§2 / §3 行 8）：EOF 时已收 `finish-step` 则忽略残片并补发收据
+ * finish part；未收到则并入截断错误（errors.ts 的 StreamTruncatedError，APICallError
+ * 形态、可重试，本模块 re-export 保持消费面）。
+ */
+import type { LanguageModelV3FinishReason, LanguageModelV3StreamPart, LanguageModelV3Usage, SharedV3Warning } from "@ai-sdk/provider";
+export { StreamTruncatedError } from "./errors.js";
+export interface NdjsonStreamContext {
+    /** wire id——错误 message 需含 model id（§3） */
+    modelId: string;
+    /** 调用 warnings（buildEnvelope 产出），随首个 stream-start part 上报 */
+    warnings: SharedV3Warning[];
+}
+export interface NdjsonEventStream {
+    /** 流的第一个 part：`stream-start`（AI SDK 约定 warnings 随首个 part 交给调用方）。
+     * 仅首次调用产出，之后返回空。 */
+    head(): LanguageModelV3StreamPart[];
+    /** 喂一段响应体字节（UTF-8 解码可跨 chunk、按 `\n` 切行、逐行翻译） */
+    push(chunk: Uint8Array): LanguageModelV3StreamPart[];
+    /** EOF：已收 finish-step → 补发收据 finish part；未收 → 截断错误 part */
+    end(): LanguageModelV3StreamPart[];
+}
+export declare function createNdjsonEventStream(context: NdjsonStreamContext): NdjsonEventStream;
+/** usage 双 case 兼容（camelCase / snake_case，brent 实证两种都出现过）。
+ * AI SDK `inputTokens.noCache` 取 `noCacheTokens` 优先、否则 total − cacheRead
+ * （jiesou 规则）；cacheRead / reasoning 映射到对应字段；原始对象进 `raw` 保真。 */
+export declare function normalizeUsage(raw: unknown): LanguageModelV3Usage;
+export declare function normalizeFinishReason(raw: string | undefined): LanguageModelV3FinishReason;

package/dist/protocol/ndjson.js

@@ -0,0 +1,321 @@
+/**
+ * 协议核心·响应方向：`/alpha/generate` 的 NDJSON 事件流 → AI SDK stream part
+ * （契约：docs/spec/protocol.md §2）。
+ *
+ * 严格 NDJSON：按行切分、逐行 `JSON.parse`；跳过空行与 `:` 注释行。不做 SSE 双兼容
+ * （不剥 `data:`、不认 `[DONE]`、不做 `\r\n` 归一——§6 否决项：上游格式真变更时
+ * 错误浮出、修改本项目适配，不预做兼容）。
+ *
+ * 事件消费全表：`start`/`start-step`（流开始，由 head 的 stream-start 承担）、
+ * text/reasoning/tool-input 三组块生命周期（`tool-input-*` 增量必做）、
+ * `tool-call`（字段名兼容 `input│args│arguments` 与 `toolCallId│id`）、
+ * `finish-step` 收据、`finish` 总账单、`response-metadata` 照收、
+ * `error` 不吞错、未知 type 静默忽略。
+ *
+ * 半行残片两结局（§2 / §3 行 8）：EOF 时已收 `finish-step` 则忽略残片并补发收据
+ * finish part；未收到则并入截断错误（errors.ts 的 StreamTruncatedError，APICallError
+ * 形态、可重试，本模块 re-export 保持消费面）。
+ */
+import { asRecord } from "./json.js";
+import { streamError, StreamTruncatedError } from "./errors.js";
+export { StreamTruncatedError } from "./errors.js";
+export function createNdjsonEventStream(context) {
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let receipt = null;
+    let headEmitted = false;
+    let finishEmitted = false;
+    let abortedByError = false;
+    function errorPart(error) {
+        return { type: "error", error };
+    }
+    /**
+     * §3 总则：流内错误一律 APICallError 形态。`streamError` 工厂负责打形态标记
+     * 与拼 model id 前缀，本层只供错误正文。
+     */
+    function streamErrorPart(message, opts) {
+        return errorPart(streamError(context.modelId, message, opts));
+    }
+    function translateLine(line) {
+        if (line === "" || line.startsWith(":"))
+            return [];
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (error) {
+            abortedByError = true;
+            const reason = error instanceof Error ? error.message : String(error);
+            return [streamErrorPart(`上游 NDJSON 行无法解析：${clip(line, 200)}（${reason}）`)];
+        }
+        const record = asRecord(parsed);
+        const type = record === null ? undefined : str(record["type"]);
+        if (record === null || type === undefined) {
+            // 无事件形状的 JSON（数组、标量、缺 type 的对象）：严格 NDJSON 下视为行级损坏
+            abortedByError = true;
+            return [streamErrorPart(`上游 NDJSON 行不是事件对象：${clip(line, 200)}`)];
+        }
+        switch (type) {
+            // 流开始由 head() 的 stream-start 承担（AI SDK 契约：warnings 必须随首个 part）
+            case "start":
+            case "start-step":
+                return [];
+            case "text-start":
+                return [{ type: "text-start", id: str(record["id"]) ?? "", ...providerMeta(record) }];
+            case "text-delta":
+                return [{ type: "text-delta", id: str(record["id"]) ?? "", delta: str(record["text"]) ?? "", ...providerMeta(record) }];
+            case "text-end":
+                return [{ type: "text-end", id: str(record["id"]) ?? "", ...providerMeta(record) }];
+            case "reasoning-start":
+                return [{ type: "reasoning-start", id: str(record["id"]) ?? "", ...providerMeta(record) }];
+            case "reasoning-delta":
+                return [{ type: "reasoning-delta", id: str(record["id"]) ?? "", delta: str(record["text"]) ?? "", ...providerMeta(record) }];
+            case "reasoning-end":
+                return [{ type: "reasoning-end", id: str(record["id"]) ?? "", ...providerMeta(record) }];
+            case "tool-input-start":
+                return [
+                    {
+                        type: "tool-input-start",
+                        id: str(record["id"]) ?? "",
+                        toolName: str(record["toolName"]) ?? str(record["name"]) ?? "",
+                        ...providerMeta(record),
+                    },
+                ];
+            case "tool-input-delta":
+                return [
+                    {
+                        type: "tool-input-delta",
+                        id: str(record["id"]) ?? "",
+                        delta: str(record["delta"]) ?? str(record["text"]) ?? "",
+                        ...providerMeta(record),
+                    },
+                ];
+            case "tool-input-end":
+                return [{ type: "tool-input-end", id: str(record["id"]) ?? "", ...providerMeta(record) }];
+            case "tool-call": {
+                // 字段名兼容（§2）：input│args│arguments 与 toolCallId│id
+                const input = record["input"] ?? record["args"] ?? record["arguments"];
+                return [
+                    {
+                        type: "tool-call",
+                        toolCallId: str(record["toolCallId"]) ?? str(record["id"]) ?? "",
+                        toolName: str(record["toolName"]) ?? str(record["name"]) ?? "",
+                        input: toolCallInputToString(input),
+                        ...providerMeta(record),
+                    },
+                ];
+            }
+            case "finish-step": {
+                receipt = {
+                    finishReason: str(record["finishReason"]) ?? str(record["rawFinishReason"]),
+                    usage: record["usage"],
+                    providerMetadata: providerMetaOf(record),
+                };
+                const parts = [];
+                const responseMetadata = responseMetadataPart(record["response"]);
+                if (responseMetadata !== null)
+                    parts.push(responseMetadata);
+                return parts;
+            }
+            case "finish": {
+                if (finishEmitted)
+                    return [];
+                finishEmitted = true;
+                const usage = normalizeUsage(record["totalUsage"] ?? receipt?.usage);
+                const finishReason = normalizeFinishReason(str(record["finishReason"]) ?? str(record["rawFinishReason"]) ?? receipt?.finishReason);
+                const providerMetadata = providerMetaOf(record) ?? receipt?.providerMetadata;
+                return [{ type: "finish", usage, finishReason, ...(providerMetadata !== undefined ? { providerMetadata } : {}) }];
+            }
+            case "response-metadata": {
+                const part = responseMetadataPart(record);
+                return part === null ? [] : [part];
+            }
+            case "error": {
+                // §3 行 9：流中 error 事件不吞错，已收 delta 保留，错误浮出后终止翻译
+                abortedByError = true;
+                return [streamErrorPart(extractErrorMessage(record))];
+            }
+            default:
+                // 未知 type 静默忽略——消费端向前兼容基本功（§2）
+                return [];
+        }
+    }
+    function extractErrorMessage(record) {
+        const error = record["error"];
+        const errorRecord = asRecord(error);
+        if (errorRecord !== null && typeof errorRecord["message"] === "string")
+            return errorRecord["message"];
+        if (typeof error === "string" && error)
+            return error;
+        const message = record["message"];
+        if (typeof message === "string" && message)
+            return message;
+        return "上游流中报告了 error 事件，但未携带可读信息";
+    }
+    return {
+        head() {
+            if (headEmitted)
+                return [];
+            headEmitted = true;
+            return [{ type: "stream-start", warnings: context.warnings }];
+        },
+        push(chunk) {
+            if (abortedByError)
+                return [];
+            buffer += decoder.decode(chunk, { stream: true });
+            const parts = [];
+            let newline;
+            while ((newline = buffer.indexOf("\n")) !== -1) {
+                const line = buffer.slice(0, newline);
+                buffer = buffer.slice(newline + 1);
+                parts.push(...translateLine(line));
+                if (abortedByError)
+                    break;
+            }
+            return parts;
+        },
+        end() {
+            if (abortedByError)
+                return [];
+            buffer += decoder.decode();
+            const partial = /\S/.test(buffer) ? buffer : "";
+            buffer = "";
+            if (receipt === null)
+                return [errorPart(new StreamTruncatedError(partial, context.modelId))];
+            // 已收 finish-step：半行残片按规格忽略，流视为完整收尾，补发收据 finish part
+            if (finishEmitted)
+                return [];
+            finishEmitted = true;
+            return [finishPartFromReceipt(receipt)];
+        },
+    };
+}
+function finishPartFromReceipt(receipt) {
+    const providerMetadata = receipt.providerMetadata;
+    return {
+        type: "finish",
+        usage: normalizeUsage(receipt.usage),
+        finishReason: normalizeFinishReason(receipt.finishReason),
+        ...(providerMetadata !== undefined ? { providerMetadata } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// usage 与 finishReason 归一
+// ---------------------------------------------------------------------------
+/** usage 双 case 兼容（camelCase / snake_case，brent 实证两种都出现过）。
+ * AI SDK `inputTokens.noCache` 取 `noCacheTokens` 优先、否则 total − cacheRead
+ * （jiesou 规则）；cacheRead / reasoning 映射到对应字段；原始对象进 `raw` 保真。 */
+export function normalizeUsage(raw) {
+    const record = asRecord(raw);
+    if (record === null)
+        return zeroUsage();
+    const num = (...values) => {
+        for (const value of values) {
+            if (typeof value === "number" && Number.isFinite(value))
+                return value;
+        }
+        return undefined;
+    };
+    // 每个槽位按「camelCase 细节 → snake_case 细节 → 顶层 camelCase → 顶层 snake_case」取第一个数值
+    const pick = (source, ...keys) => {
+        if (source === null)
+            return undefined;
+        for (const key of keys) {
+            const value = source[key];
+            if (value !== undefined)
+                return value;
+        }
+        return undefined;
+    };
+    const inputDetails = asRecord(record["inputTokenDetails"]) ?? asRecord(record["input_token_details"]) ?? asRecord(record["prompt_tokens_details"]);
+    const outputDetails = asRecord(record["outputTokenDetails"]) ?? asRecord(record["output_token_details"]) ?? asRecord(record["completion_tokens_details"]);
+    const inputTotal = num(pick(record, "inputTokens", "input_tokens", "prompt_tokens", "totalTokens", "total_tokens"));
+    const cacheRead = num(pick(inputDetails, "cacheReadTokens", "cache_read_tokens"), pick(record, "cachedInputTokens", "cached_input_tokens"), pick(inputDetails, "cached_tokens"), record["prompt_cache_hit_tokens"]);
+    const noCacheExplicit = num(pick(inputDetails, "noCacheTokens", "no_cache_tokens"), record["prompt_cache_miss_tokens"]);
+    return {
+        inputTokens: {
+            total: inputTotal,
+            noCache: noCacheExplicit ?? (inputTotal !== undefined ? inputTotal - (cacheRead ?? 0) : undefined),
+            cacheRead,
+            cacheWrite: num(pick(inputDetails, "cacheWriteTokens", "cache_write_tokens")),
+        },
+        outputTokens: {
+            total: num(pick(record, "outputTokens", "output_tokens", "completion_tokens")),
+            text: num(pick(outputDetails, "textTokens", "text_tokens")),
+            reasoning: num(pick(outputDetails, "reasoningTokens", "reasoning_tokens"), pick(record, "reasoningTokens", "reasoning_tokens")),
+        },
+        raw: record,
+    };
+}
+function zeroUsage() {
+    return {
+        inputTokens: { total: undefined, noCache: undefined, cacheRead: undefined, cacheWrite: undefined },
+        outputTokens: { total: undefined, text: undefined, reasoning: undefined },
+    };
+}
+/** finishReason 词表归一（§2）：`stop│end_turn`、`tool_calls│tool-calls`、
+ * `length│max_tokens│max_output_tokens`；表外值归 other、原文进 raw 不丢失 */
+const FINISH_REASON_VOCABULARY = {
+    stop: "stop",
+    end_turn: "stop",
+    tool_calls: "tool-calls",
+    "tool-calls": "tool-calls",
+    length: "length",
+    max_tokens: "length",
+    max_output_tokens: "length",
+};
+export function normalizeFinishReason(raw) {
+    const unified = (raw !== undefined ? FINISH_REASON_VOCABULARY[raw] : undefined) ?? "other";
+    return { unified, raw };
+}
+// ---------------------------------------------------------------------------
+// 小工具
+// ---------------------------------------------------------------------------
+/** 信封 tool-call 的 `input`（AI SDK 要求 JSON 字符串）：对象序列化、字符串原样 */
+function toolCallInputToString(input) {
+    if (input == null)
+        return "{}";
+    if (typeof input === "string")
+        return input;
+    try {
+        return JSON.stringify(input);
+    }
+    catch {
+        return "{}";
+    }
+}
+function responseMetadataPart(value) {
+    const record = asRecord(value);
+    if (record === null)
+        return null;
+    const id = str(record["id"]);
+    const timestamp = toDate(record["timestamp"]);
+    const modelId = str(record["modelId"]);
+    if (id === undefined && timestamp === undefined && modelId === undefined)
+        return null;
+    return {
+        type: "response-metadata",
+        ...(id !== undefined ? { id } : {}),
+        ...(timestamp !== undefined ? { timestamp } : {}),
+        ...(modelId !== undefined ? { modelId } : {}),
+    };
+}
+function providerMetaOf(record) {
+    return asRecord(record["providerMetadata"]) !== null ? record["providerMetadata"] : undefined;
+}
+function providerMeta(record) {
+    const providerMetadata = providerMetaOf(record);
+    return providerMetadata !== undefined ? { providerMetadata } : {};
+}
+function toDate(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? undefined : date;
+}
+function str(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function clip(text, max) {
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+}

package/dist/protocol/watchdog.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 协议核心·超时与取消（契约：docs/spec/protocol.md §4）。
+ *
+ * - 300 秒空闲看门狗（常量，暂不配置化）：持续未收到任何新事件即判定上游
+ *   失联 → abort 上游 + 抛可重试错误（retry-after 5s，见 errors.ts
+ *   `watchdogTimeoutError`）。连接阶段计入空闲（「连首字节都没等到」本身
+ *   就是最大的空闲），因此看门狗从 fetch 发起前启动。
+ * - 无总超时——健康长回合不被固定时限误杀，只有真失联才断开。本模块只有
+ *   「空闲计时」，不累计任何总时长。
+ * - 取消合并由调用方用 `AbortSignal.any([watchdog.signal, 调用方 abortSignal])`
+ *   完成（本文件导出 `mergeCancellation` 辅助，谁先响都生效）。
+ *
+ * 实现用 setTimeout + AbortController 而非 `AbortSignal.timeout`：看门狗要
+ * 「每次收到事件重置计时」，timeout 信号是一次性的、无法重置。
+ */
+/** 空闲看门狗时长：300 秒（§4 常量，暂不配置化） */
+export declare const IDLE_WATCHDOG_TIMEOUT_MS = 300000;
+export interface IdleWatchdog {
+    /** abort 时置位；调用方经 `AbortSignal.any` 与自己的取消信号合并后控制上游 fetch */
+    readonly signal: AbortSignal;
+    /** 是否已到点触发（区分「看门狗断开」与「调用方取消」两条 abort 路径） */
+    readonly fired: boolean;
+    /** 每次收到上游新事件调用：重置空闲计时 */
+    reset(): void;
+    /** 流正常收尾后调用：停止计时并释放定时器（避免残留 timer 悬挂进程） */
+    clear(): void;
+}
+/** 到点触发时 abort 的 reason 标识：fetch 侧据此可区分失联断开 */
+export declare const WATCHDOG_ABORT_REASON: unique symbol;
+/** 创建空闲看门狗；创建即开始计时（连接阶段计入空闲，§4）。时长即常量。 */
+export declare function createIdleWatchdog(): IdleWatchdog;
+/**
+ * 取消合并：`AbortSignal.any` 的封装——看门狗 signal 与调用方 abortSignal
+ * 谁先 abort 谁生效（§4 取消合并条款；两路信号的行为差异见执行层：
+ * 看门狗到点 → 合成可重试错误，调用方取消 → 传播 abort 不合成错误）。
+ */
+export declare function mergeCancellation(watchdog: IdleWatchdog, callerSignal?: AbortSignal): AbortSignal;

package/dist/protocol/watchdog.js

@@ -0,0 +1,61 @@
+/**
+ * 协议核心·超时与取消（契约：docs/spec/protocol.md §4）。
+ *
+ * - 300 秒空闲看门狗（常量，暂不配置化）：持续未收到任何新事件即判定上游
+ *   失联 → abort 上游 + 抛可重试错误（retry-after 5s，见 errors.ts
+ *   `watchdogTimeoutError`）。连接阶段计入空闲（「连首字节都没等到」本身
+ *   就是最大的空闲），因此看门狗从 fetch 发起前启动。
+ * - 无总超时——健康长回合不被固定时限误杀，只有真失联才断开。本模块只有
+ *   「空闲计时」，不累计任何总时长。
+ * - 取消合并由调用方用 `AbortSignal.any([watchdog.signal, 调用方 abortSignal])`
+ *   完成（本文件导出 `mergeCancellation` 辅助，谁先响都生效）。
+ *
+ * 实现用 setTimeout + AbortController 而非 `AbortSignal.timeout`：看门狗要
+ * 「每次收到事件重置计时」，timeout 信号是一次性的、无法重置。
+ */
+/** 空闲看门狗时长：300 秒（§4 常量，暂不配置化） */
+export const IDLE_WATCHDOG_TIMEOUT_MS = 300_000;
+/** 到点触发时 abort 的 reason 标识：fetch 侧据此可区分失联断开 */
+export const WATCHDOG_ABORT_REASON = Symbol("commandcode.idle-watchdog");
+/** 创建空闲看门狗；创建即开始计时（连接阶段计入空闲，§4）。时长即常量。 */
+export function createIdleWatchdog() {
+    const controller = new AbortController();
+    let timer;
+    let fired = false;
+    function arm() {
+        clear();
+        timer = setTimeout(() => {
+            fired = true;
+            controller.abort(WATCHDOG_ABORT_REASON);
+        }, IDLE_WATCHDOG_TIMEOUT_MS);
+    }
+    function clear() {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+    }
+    arm();
+    return {
+        signal: controller.signal,
+        get fired() {
+            return fired;
+        },
+        reset() {
+            if (fired)
+                return;
+            arm();
+        },
+        clear() {
+            clear();
+        },
+    };
+}
+/**
+ * 取消合并：`AbortSignal.any` 的封装——看门狗 signal 与调用方 abortSignal
+ * 谁先 abort 谁生效（§4 取消合并条款；两路信号的行为差异见执行层：
+ * 看门狗到点 → 合成可重试错误，调用方取消 → 传播 abort 不合成错误）。
+ */
+export function mergeCancellation(watchdog, callerSignal) {
+    return callerSignal === undefined ? watchdog.signal : AbortSignal.any([watchdog.signal, callerSignal]);
+}

package/dist/provider/model.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 工厂装配（#35 弹道合拢点）：协议核心（执行内核 generate.ts）× 伪装模块
+ * （会话身份 / config 块 / 版本头 / 伪装头）× 模型管线（级联 limit 数据）组装成
+ * 包导出的 `createCommandCode({name, apiKey, headers, fetch})` 工厂，内部实现
+ * LanguageModelV3（契约形状：docs/research/v2-provider-contract.md §2 实测——
+ * `finishReason` 为 `{unified, raw}` 对象、`usage` 嵌套结构、上游恒为流式 NDJSON、
+ * `doGenerate` = `doStream` 聚合）。
+ *
+ * 工厂签名四键无 body；宿主按「模块第一个 `create*` 前缀导出」判据发现（v1/v2
+ * 共用），返回 `{ languageModel(modelID) → LanguageModelV3 }`。模型 reference 按
+ * 首个 `/` 切分 provider 与 wire id——wire id 自身可含 `/`（如
+ * `deepseek/deepseek-v4-flash`），故仅 provider 段与本插件同名时才剥前缀，无前缀
+ * reference 原样透传。
+ *
+ * doStream 主路径：预请求惰性检查（到点后台发射，主请求零等待）→ 会话身份派生
+ * （从调用 headers 的 OpenCode 会话头确定性派生，缺失落 per-key 回退轮换）→ 图片
+ * 预处理（模态过滤 + 外链下载）→ config 块与版本头并行就绪 → 信封构造（伪装字段
+ * 填充点）→ 伪装头组装（`threadId` 与 `x-session-id` 同值）→ 300s 看门狗执行内核。
+ * HTTP 层错误（非 2xx / 响应前网络错误 / 看门狗连接期到点）在 doStream await 时
+ * 抛出（AI SDK 惯例，宿主 catch 分类）；流内错误（截断 / error 事件 / 零输出 /
+ * 流中看门狗到点）以 error part 浮现（protocol.md §3）。
+ *
+ * 运行时共享：宿主每次模型请求都会重新调用工厂（v2 实测两遍/请求），预请求节奏
+ * （D2 每进程一次）与模型管线刷新节奏（model-pipeline.md §4 TTL）必须跨工厂调用
+ * 存活——伪装状态与管线为模块级单例；宿主逐次注入的 fetch / 自定义头 / logger 经
+ * 接缝重指向最新值；key 相关状态（回退会话、预请求退避）由 DisguiseState 内部
+ * per-key Map 承载。调用 headers 只作会话派生种子、不透传上游（`X-Session-Id` 等
+ * 是宿主内部头，非 CLI 指纹）；工厂 options.headers（用户显式配置）透传且被伪装
+ * 键覆盖防冲突。
+ */
+import type { LanguageModelV3 } from "@ai-sdk/provider";
+import { type DisguiseLogger } from "../disguise/logger.js";
+import { type CascadeResult } from "../models/cascade.js";
+import type { FetchLike } from "../protocol/json.js";
+/**
+ * 工厂入参：宿主调工厂时注入的 options（v2-provider-contract.md §1 实测形状）。
+ * `fetch` 是宿主包装过的实例（超时与 chunk 处理由宿主侧完成），全部出网路径——
+ * generate、models、产物 URL、版本查询、预请求——统一经它注入（testing.md §2）。
+ */
+export interface CommandCodeFactoryOptions {
+    /** 宿主传入的 provider id；本插件四处同名常量（PROVIDER_ID），不用此值 */
+    readonly name?: string;
+    readonly apiKey?: string;
+    /** 宿主/用户显式配置的 provider 级请求头，逐请求透传（伪装键优先，防冲突覆盖） */
+    readonly headers?: Record<string, string>;
+    /** 出网接缝（json.ts FetchLike 形状，bun fetch 带 preconnect 静态属性、mock 实例难以满足其完整签名）；缺省 globalThis.fetch */
+    readonly fetch?: FetchLike;
+    /**
+     * modelsUrls 覆盖通道原样值（model-pipeline.md §1.3）：v1 `options.modelsUrls` /
+     * v2 `settings.modelsUrls` 经宿主透传后在工厂 options 中以顶层键出现。构造时作
+     * 初值；其后的调用经管线 rebindModelsUrls 重绑定（v2 的 config settings 首次
+     * 工厂调用才可见，#36）。
+     */
+    readonly modelsUrls?: unknown;
+    /**
+     * 注入式 logger（disguise.md §7 官方接缝；通道结论以 logger.ts 头注为准）。
+     * 逐次工厂调用重指向最新注入值。
+     */
+    readonly logger?: DisguiseLogger;
+}
+/** 工厂返回形状（v2-provider-contract.md §1：宿主经 languageModel(modelID) 取模型实例） */
+export interface CommandCodeProvider {
+    languageModel(modelID: string): LanguageModelV3;
+}
+/** 运行时构造参数：全部仅首次构造生效（幂等构造，后续调用忽略）；fetch/headers/
+ * logger 构造后仍有逐次调用重指向的活接缝，modelsUrls 没有（管线构造时解析一次） */
+export interface RuntimeInit {
+    /** modelsUrls 的 config 通道原样值（v2 = settings.modelsUrls，glue 从 transform 捕获） */
+    readonly modelsUrls?: unknown;
+    readonly fetch?: FetchLike;
+    readonly headers?: Record<string, string>;
+    readonly logger?: DisguiseLogger;
+    /** 模型数据变更回调（v2 glue 接 catalog.reload()）；不受幂等构造限制，任意时刻可重设 */
+    readonly onModelDataChange?: (cascade: CascadeResult) => void;
+}
+/**
+ * v2 glue（#36）的运行时入口：幂等构造 + 变更回调注册。setup 语义下 modelsUrls
+ * 的 config 通道（settings.modelsUrls）由 glue 在 transform 内捕获后传入；工厂侧
+ * 宿主透传值只在工厂先行构造（独立调用 / v1 形态）时作构造初值。
+ */
+export declare function ensureProviderRuntime(init: RuntimeInit): void;
+/**
+ * v1 glue（#37）的运行时入口：v1 启动协商——幂等构造（不预启动）+ 启动拉取一次
+ *（15s 总预算、失败用快照、此后无后台刷新，model-pipeline.md §4）。v1 config hook
+ * 在注入模型清单前 await 本函数；运行时已被先行构造时（v2 setup / 工厂独立调用），
+ * initializeOnce 的幂等守卫使本调用退化为「返回当前级联」。
+ */
+export declare function ensureV1ProviderRuntime(init: RuntimeInit): Promise<CascadeResult>;
+/**
+ * 当前级联（v2 glue 的 transform 回放数据源）：运行时已构造时读管线实时值（读时
+ * 惰性检查 TTL，reload 回放顺带充当显式到期触发点）；未构造时为纯快照层——启动
+ * 零阻塞的注册序：transform 先注册快照，后台拉取的变更经 reload 回放本函数更新。
+ */
+export declare function latestCascade(): CascadeResult;
+export declare function createCommandCode(options: CommandCodeFactoryOptions): CommandCodeProvider;