@wallbreakerno4/opencode-commandcode 0.1.0

package/dist/protocol/envelope.d.ts

@@ -0,0 +1,118 @@
+/**
+ * 协议核心·请求方向：把 AI SDK 标准调用（LanguageModelV3CallOptions）翻译成
+ * `/alpha/generate` 的 CLI 信封（契约：docs/spec/protocol.md §1）。
+ *
+ * 伪装字段只留填充点：`config` 块与顶层 `permissionMode` 由伪装模块提供（disguise.md
+ * §9），本模块对其内容零知识、原样搬运；`memory` / `taste` / `skills` 是官方 CLI
+ * 硬编码的 null 死键（#25 源码定案），在此写死；`threadId` 与 `x-session-id` 同值，
+ * 由调用方从伪装模块的会话身份取。
+ *
+ * 越权参数策略（§1.3）：信封 `params` 没有的调用参数既不塞进信封也不静默吞掉，
+ * 一律以 AI SDK call warnings 上报，由调用方在结果中可见。
+ */
+import type { LanguageModelV3CallOptions, LanguageModelV3Prompt, SharedV3Warning } from "@ai-sdk/provider";
+/** provider 唯一标识：v2 插件 id、v1 config 注入键、integrationID、模型 id 前缀四处同名 */
+export declare const PROVIDER_ID = "commandcode-go";
+/** 模型 reference（`provider/wire`）解析：按首个 `/` 切分，wire id 可含 `/` 原样透传 */
+export declare function splitModelReference(reference: string): {
+    providerId: string;
+    wireId: string;
+};
+export interface EnvelopeTool {
+    type: "function";
+    name: string;
+    description?: string;
+    input_schema: Record<string, unknown>;
+}
+export type EnvelopeToolChoice = {
+    type: "auto";
+} | {
+    type: "none";
+} | {
+    type: "any";
+} | {
+    type: "tool";
+    name: string;
+};
+export type EnvelopeTextBlock = {
+    type: "text";
+    text: string;
+};
+export type EnvelopeImageBlock = {
+    type: "image";
+    image: string;
+};
+export type EnvelopeAssistantBlock = EnvelopeTextBlock | {
+    type: "reasoning";
+    text: string;
+} | {
+    type: "tool-call";
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+};
+export type EnvelopeToolResultBlock = {
+    type: "tool-result";
+    toolCallId: string;
+    toolName: string;
+    output: {
+        type: "text" | "error-text";
+        value: string;
+    };
+};
+export type EnvelopeMessage = {
+    role: "user";
+    content: Array<EnvelopeTextBlock | EnvelopeImageBlock>;
+} | {
+    role: "assistant";
+    content: EnvelopeAssistantBlock[];
+} | {
+    role: "tool";
+    content: EnvelopeToolResultBlock[];
+};
+export interface EnvelopeParams {
+    model: string;
+    messages: EnvelopeMessage[];
+    system?: string;
+    tools?: EnvelopeTool[];
+    tool_choice?: EnvelopeToolChoice;
+    max_tokens: number;
+    stream: true;
+    temperature?: number;
+    top_p?: number;
+    top_k?: number;
+    reasoning_effort?: string;
+}
+/** 七键骨架；键序即规格 §1 列举序，构造时按此序赋值保持 wire 形状稳定 */
+export interface CommandCodeEnvelope {
+    config: Record<string, unknown>;
+    memory: null;
+    taste: null;
+    skills: null;
+    permissionMode: string;
+    threadId: string;
+    params: EnvelopeParams;
+}
+/** 协议核心之外的调用上下文：模型管线与伪装模块的输入 */
+export interface EnvelopeCallContext {
+    /** wire id（provider 前缀剥除后），原样进 `params.model` */
+    modelId: string;
+    /** 模型管线级联 `maxOutput`：`max_tokens` 的裁剪参考（models.dev 第三方视角值，
+     * 非网关真值；仅当小于官方缺省 64e3 时生效，§1.2 / ADR 0002） */
+    maxOutput: number;
+    /** 与 `x-session-id` 同值（伪装模块会话身份） */
+    threadId: string;
+    /** 伪装模块提供的填充点内容，本模块零知识 */
+    disguise: {
+        config: Record<string, unknown>;
+        permissionMode: string;
+    };
+}
+export declare function buildEnvelope(options: LanguageModelV3CallOptions, context: EnvelopeCallContext): {
+    body: CommandCodeEnvelope;
+    warnings: SharedV3Warning[];
+};
+export declare function convertPrompt(prompt: LanguageModelV3Prompt, warnings: SharedV3Warning[]): {
+    system: string | undefined;
+    messages: EnvelopeMessage[];
+};

package/dist/protocol/envelope.js

@@ -0,0 +1,331 @@
+/**
+ * 协议核心·请求方向：把 AI SDK 标准调用（LanguageModelV3CallOptions）翻译成
+ * `/alpha/generate` 的 CLI 信封（契约：docs/spec/protocol.md §1）。
+ *
+ * 伪装字段只留填充点：`config` 块与顶层 `permissionMode` 由伪装模块提供（disguise.md
+ * §9），本模块对其内容零知识、原样搬运；`memory` / `taste` / `skills` 是官方 CLI
+ * 硬编码的 null 死键（#25 源码定案），在此写死；`threadId` 与 `x-session-id` 同值，
+ * 由调用方从伪装模块的会话身份取。
+ *
+ * 越权参数策略（§1.3）：信封 `params` 没有的调用参数既不塞进信封也不静默吞掉，
+ * 一律以 AI SDK call warnings 上报，由调用方在结果中可见。
+ */
+import { asRecord } from "./json.js";
+/** provider 唯一标识：v2 插件 id、v1 config 注入键、integrationID、模型 id 前缀四处同名 */
+export const PROVIDER_ID = "commandcode-go";
+/** 模型 reference（`provider/wire`）解析：按首个 `/` 切分，wire id 可含 `/` 原样透传 */
+export function splitModelReference(reference) {
+    const slash = reference.indexOf("/");
+    if (slash === -1)
+        return { providerId: PROVIDER_ID, wireId: reference };
+    return { providerId: reference.slice(0, slash), wireId: reference.slice(slash + 1) };
+}
+// ---------------------------------------------------------------------------
+// 信封构造
+// ---------------------------------------------------------------------------
+export function buildEnvelope(options, context) {
+    const warnings = [];
+    warnUnsupportedCallParams(options, warnings);
+    const { system, messages } = convertPrompt(options.prompt, warnings);
+    const tools = convertTools(options.tools, warnings);
+    const toolChoice = resolveToolChoice(options.toolChoice, tools !== undefined);
+    const reasoningEffort = resolveReasoningEffort(options.providerOptions);
+    const params = {
+        model: context.modelId,
+        messages,
+        ...(system !== undefined ? { system } : {}),
+        ...(tools !== undefined ? { tools } : {}),
+        ...(toolChoice !== undefined ? { tool_choice: toolChoice } : {}),
+        max_tokens: resolveMaxTokens(options.maxOutputTokens, context.maxOutput),
+        stream: true,
+        ...(options.temperature != null ? { temperature: options.temperature } : {}),
+        ...(options.topP != null ? { top_p: options.topP } : {}),
+        ...(options.topK != null ? { top_k: options.topK } : {}),
+        ...(reasoningEffort !== undefined ? { reasoning_effort: reasoningEffort } : {}),
+    };
+    const body = {
+        config: context.disguise.config,
+        memory: null,
+        taste: null,
+        skills: null,
+        permissionMode: context.disguise.permissionMode,
+        threadId: context.threadId,
+        params,
+    };
+    return { body, warnings };
+}
+/** `max_tokens` 缺省：官方 CLI 主对话路径常量 `tk = 64e3`（command-code 1.49.1
+ * `dist/cli.mjs`，`max_tokens: t.maxOutputTokens ?? tk`），与 capture/samples/generate.json
+ * 抓包（deepseek-v4-flash 实发 64000）互证（ADR 0002）。 */
+const OFFICIAL_DEFAULT_MAX_TOKENS = 64_000;
+/** 网关对 `params.max_tokens` 的 zod 校验硬上限：#42 冒烟 400 实证
+ * `Too big: expected number to be <=200000`；官方 CLI 缺省 64e3 永不触及，故线上未暴露。 */
+const GATEWAY_MAX_TOKENS_CAP = 200_000;
+/** `max_tokens` = min(调用方值 ?? 官方缺省 64e3, 级联 maxOutput, 网关墙 200000)
+ * （§1.2 / ADR 0002）：缺省复刻官方 CLI（伪装口径——官方从不发 models.dev 理论值）；
+ * 级联值降级为裁剪参考（models.dev 第三方视角值，非网关真值）；墙防调用方显式
+ * 传大值撞 400。 */
+function resolveMaxTokens(callerValue, maxOutput) {
+    return Math.min(callerValue ?? OFFICIAL_DEFAULT_MAX_TOKENS, maxOutput, GATEWAY_MAX_TOKENS_CAP);
+}
+/** `tool_choice` 四态映射；tools 非空且调用方未指定时显式发 `{type:"auto"}`
+ * （MAXeaglet 抓包验证的信封形状，不赌网关默认值）；无 tools 则不发。 */
+function resolveToolChoice(choice, hasTools) {
+    if (choice !== undefined) {
+        switch (choice.type) {
+            case "auto":
+                return { type: "auto" };
+            case "none":
+                return { type: "none" };
+            case "required":
+                return { type: "any" };
+            case "tool":
+                return { type: "tool", name: choice.toolName };
+        }
+    }
+    return hasTools ? { type: "auto" } : undefined;
+}
+/** `reasoning_effort` 仅变体被选中时发送；接收通道为 `providerOptions.reasoningEffort`
+ * ——OpenCode 把 variant 档位合并进 providerOptions 传入 LanguageModel（协议唯一路径）。
+ * 命名空间键随宿主而异（本插件为 commandcode-go，官方 CLI 抓包里出现过 deepseek /
+ * openaiCompatible 等），故按确定性优先序全命名空间扫描。 */
+function resolveReasoningEffort(providerOptions) {
+    if (providerOptions === undefined)
+        return undefined;
+    const namespaces = Object.keys(providerOptions).sort((a, b) => {
+        if (a === PROVIDER_ID)
+            return -1;
+        if (b === PROVIDER_ID)
+            return 1;
+        return 0;
+    });
+    for (const namespace of namespaces) {
+        const value = providerOptions[namespace]?.["reasoningEffort"];
+        if (typeof value === "string" && value.length > 0)
+            return value;
+    }
+    return undefined;
+}
+/** §1.3：OpenCode 实证当前不传这些参数；真传来时不塞信封、不吞，warnings 上报 */
+function warnUnsupportedCallParams(options, warnings) {
+    const unsupported = [
+        ["stopSequences", options.stopSequences],
+        ["presencePenalty", options.presencePenalty],
+        ["frequencyPenalty", options.frequencyPenalty],
+        ["seed", options.seed],
+        ["responseFormat", options.responseFormat],
+    ];
+    for (const [feature, value] of unsupported) {
+        if (value == null)
+            continue;
+        warnings.push({
+            type: "unsupported",
+            feature,
+            details: `CommandCode 网关信封不接收 ${feature}，已按协议忽略`,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// 消息转换（§1.1 全表）
+// ---------------------------------------------------------------------------
+export function convertPrompt(prompt, warnings) {
+    const systemParts = [];
+    const messages = [];
+    for (const message of prompt) {
+        if (message.role === "system") {
+            if (message.content.length > 0)
+                systemParts.push(message.content);
+            continue;
+        }
+        if (message.role === "user") {
+            const content = [];
+            for (const part of message.content) {
+                if (part.type === "text") {
+                    content.push({ type: "text", text: part.text });
+                    continue;
+                }
+                const image = convertImageFilePart(part, warnings);
+                if (image !== null)
+                    content.push(image);
+            }
+            if (content.length > 0)
+                messages.push({ role: "user", content });
+            continue;
+        }
+        if (message.role === "assistant") {
+            const assistantBlocks = [];
+            const toolResults = [];
+            for (const part of message.content) {
+                if (part.type === "text") {
+                    assistantBlocks.push({ type: "text", text: part.text });
+                }
+                else if (part.type === "reasoning") {
+                    assistantBlocks.push({ type: "reasoning", text: part.text });
+                }
+                else if (part.type === "tool-call") {
+                    assistantBlocks.push({
+                        type: "tool-call",
+                        toolCallId: part.toolCallId,
+                        toolName: part.toolName,
+                        input: normalizeToolCallInput(part.input),
+                    });
+                }
+                else if (part.type === "tool-result") {
+                    toolResults.push(convertToolResult(part, warnings));
+                }
+                else {
+                    warnUnsupportedPart(part.type, warnings);
+                }
+            }
+            if (assistantBlocks.length > 0)
+                messages.push({ role: "assistant", content: assistantBlocks });
+            if (toolResults.length > 0)
+                messages.push({ role: "tool", content: toolResults });
+            continue;
+        }
+        // role: "tool"
+        const blocks = [];
+        for (const part of message.content) {
+            if (part.type === "tool-result") {
+                blocks.push(convertToolResult(part, warnings));
+            }
+            else {
+                warnUnsupportedPart(part.type, warnings);
+            }
+        }
+        if (blocks.length > 0)
+            messages.push({ role: "tool", content: blocks });
+    }
+    return { system: systemParts.length > 0 ? systemParts.join("\n\n") : undefined, messages };
+}
+/** 图片 part → `data:<mediaType>;base64,...` data URL（§1.1 / §5 上游格式）。
+ * 二进制与 base64 串同步可转；`data:` URL 原样透传；URL 引用无法同步转成 base64
+ * data URL，按 §1.3 走 warnings 通道，不静默吞。 */
+function convertImageFilePart(part, warnings) {
+    if (part.data instanceof Uint8Array) {
+        return { type: "image", image: `data:${part.mediaType};base64,${bytesToBase64(part.data)}` };
+    }
+    if (typeof part.data === "string") {
+        if (part.data.startsWith("data:"))
+            return { type: "image", image: part.data };
+        if (/^https?:\/\//i.test(part.data)) {
+            warnUnsupportedImageSource(warnings);
+            return null;
+        }
+        return { type: "image", image: `data:${part.mediaType};base64,${part.data}` };
+    }
+    warnUnsupportedImageSource(warnings);
+    return null;
+}
+function warnUnsupportedImageSource(warnings) {
+    warnings.push({
+        type: "unsupported",
+        feature: "image URL input",
+        details: "以 URL 引用的图片无法直接放入信封的 base64 data URL，已丢弃",
+    });
+}
+function bytesToBase64(bytes) {
+    let binary = "";
+    const chunkSize = 0x8000;
+    for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+        binary += String.fromCharCode(...bytes.subarray(offset, offset + chunkSize));
+    }
+    return btoa(binary);
+}
+/** 信封 tool-call 的 `input` 为对象；宿主传 JSON 字符串时解析还原，解析失败保留原串 */
+function normalizeToolCallInput(input) {
+    if (typeof input !== "string")
+        return input;
+    try {
+        return JSON.parse(input);
+    }
+    catch {
+        return input;
+    }
+}
+function convertToolResult(part, warnings) {
+    return { type: "tool-result", toolCallId: part.toolCallId, toolName: part.toolName, output: convertToolResultOutput(part.output, warnings) };
+}
+/** AI SDK 六种 tool 输出 → 信封二态（text / error-text）。
+ * `isError` 语义（error-text / error-json / execution-denied）一律 `error-text`；
+ * json 类输出序列化为文本进信封。 */
+function convertToolResultOutput(output, warnings) {
+    switch (output.type) {
+        case "text":
+            return { type: "text", value: output.value };
+        case "json":
+            return { type: "text", value: safeStringify(output.value) };
+        case "error-text":
+            return { type: "error-text", value: output.value };
+        case "error-json":
+            return { type: "error-text", value: safeStringify(output.value) };
+        case "execution-denied":
+            return { type: "error-text", value: output.reason ?? "Execution denied" };
+        case "content": {
+            const hasNonText = output.value.some((block) => block.type !== "text");
+            if (hasNonText) {
+                warnings.push({
+                    type: "unsupported",
+                    feature: "tool result content blocks",
+                    details: "信封 tool 结果仅支持文本，非文本块已丢弃",
+                });
+            }
+            return {
+                type: "text",
+                value: output.value
+                    .filter((block) => block.type === "text")
+                    .map((block) => block.text)
+                    .join("\n"),
+            };
+        }
+    }
+}
+/** tools 定义 → Anthropic 风格 `{type:"function", name, description, input_schema}`；
+ * provider 工具无信封表达，warnings 上报后略去 */
+function convertTools(tools, warnings) {
+    if (tools === undefined || tools.length === 0)
+        return undefined;
+    const converted = [];
+    for (const tool of tools) {
+        if (tool.type !== "function") {
+            warnings.push({
+                type: "unsupported",
+                feature: `${tool.type} tool "${tool.name}"`,
+                details: "信封 tools 仅支持 function 定义，该工具已略去",
+            });
+            continue;
+        }
+        converted.push({
+            type: "function",
+            name: tool.name,
+            ...(tool.description !== undefined ? { description: tool.description } : {}),
+            input_schema: canonicalizeJson(asRecord(tool.inputSchema) ?? {}),
+        });
+    }
+    converted.sort((left, right) => left.name.localeCompare(right.name));
+    return converted.length > 0 ? converted : undefined;
+}
+function warnUnsupportedPart(partType, warnings) {
+    warnings.push({
+        type: "unsupported",
+        feature: partType,
+        details: `信封消息不支持 ${partType} 内容块，已丢弃`,
+    });
+}
+function canonicalizeJson(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalizeJson);
+    if (typeof value !== "object" || value === null)
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, canonicalizeJson(item)]));
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}

package/dist/protocol/errors.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 协议核心·错误映射（契约：docs/spec/protocol.md §3 十一行表）。
+ *
+ * 错误对象一律是 AI SDK `APICallError` 形态：透传/合成 statusCode、标注
+ * isRetryable（重试由 OpenCode 决定，provider 不自行重试）、message 含
+ * model id 与上游 message。宿主对 provider 错误的分类靠
+ * `APICallError.isInstance`——AI SDK 用全局 Symbol 标记跨副本识别
+ * （`Symbol.for("vercel.ai.error.AI_APICallError")`，provider 3.0.8 实测），
+ * 本模块零运行时依赖，只按同款机制在实例上打标记，宿主即可正确分类
+ * （测试用 devDep @ai-sdk/provider 的 isInstance 断言验证）。
+ *
+ * 错误信封统一按 `{"error":{"message":"..."}}` 解析，兜底 `parsed.message`
+ * （brent 实证），两处都拿不到时回退 HTTP 状态文本。
+ */
+/** AI SDK APICallError 的公开字段（provider 3.0.8 形状，零依赖复刻） */
+export interface ApiCallErrorFields {
+    /** 人类可读错误消息：必含 model id，尽量含上游 message（§3 总则） */
+    message: string;
+    url?: string;
+    requestBodyValues?: unknown;
+    statusCode?: number;
+    responseHeaders?: Record<string, string>;
+    responseBody?: string;
+    isRetryable: boolean;
+    /** 本插件附加：合成错误的推荐退避秒数（调用方/宿主可读） */
+    retryAfterSeconds?: number;
+    cause?: unknown;
+}
+/** 十一行表错误信封载体：AI SDK APICallError 形态（含跨包识别标记） */
+export declare class CommandCodeApiCallError extends Error implements ApiCallErrorFields {
+    readonly url?: string;
+    readonly requestBodyValues?: unknown;
+    readonly statusCode?: number;
+    readonly responseHeaders?: Record<string, string>;
+    readonly responseBody?: string;
+    readonly isRetryable: boolean;
+    readonly retryAfterSeconds?: number;
+    /** 合成错误的语义码（如零输出/看门狗超时），透传错误时为 undefined */
+    readonly code?: string;
+    constructor(fields: ApiCallErrorFields & {
+        code?: string;
+    });
+}
+/** 十一行表行 7：零输出合成 429（retry-after 10s），防白跑一回合 */
+export declare function zeroOutputError(modelId: string, url: string, requestBodyValues: unknown): CommandCodeApiCallError;
+/** 看门狗到点（§4）：上游 300s 无事件 = 失联，可重试（retry-after 5s） */
+export declare function watchdogTimeoutError(modelId: string, url: string, requestBodyValues: unknown): CommandCodeApiCallError;
+/** 行 11：响应前网络错误（DNS / 连接拒绝 / TLS），可重试 */
+export declare function networkError(modelId: string, url: string, requestBodyValues: unknown, cause: unknown): CommandCodeApiCallError;
+/**
+ * 流内错误（无 HTTP 状态可透传）：可重试性由错误自身语义决定（行 8 截断可
+ * 重试；行 9 error 事件交 OpenCode 判断）。错误对象同为 APICallError 形态，
+ * 宿主 fromError 分类与 message/responseBody 匹配照常生效。
+ */
+export declare function streamError(modelId: string, message: string, opts?: {
+    isRetryable?: boolean;
+    code?: string;
+    cause?: unknown;
+}): CommandCodeApiCallError;
+/**
+ * 流关闭但未收到 `finish-step`：无法确认回复完整（§3 行 8，jiesou 的
+ * STREAM_CLOSED）。APICallError 形态、可重试；`partialLine` 供排查。
+ * （ndjson.ts re-export 本类，流解析层错误统一由此构造。）
+ */
+export declare class StreamTruncatedError extends CommandCodeApiCallError {
+    /** 早期解析层消费者读取的兼容别名（与 isRetryable 同值） */
+    readonly retriable = true;
+    /** EOF 时未完结的半行残片，并入错误供排查 */
+    readonly partialLine: string;
+    constructor(partialLine: string, modelId: string);
+}
+/**
+ * 十一行表行 1–6 的 HTTP 层映射：把非 2xx 响应翻译成 APICallError 形态。
+ * 401/403 按 body 是否含 MODEL_NOT_IN_PLAN 区分「模型不在套餐」与认证错误；
+ * 402 按配额窗口假设合成 retry-after 60s；429 透传上游 retry-after（缺省不合成）；
+ * 400 命中上下文超限特征时明确报「上下文窗口超限」；5xx 透传状态码。
+ * 表外状态码：4xx 透传不可重试，5xx 可重试（真变更走规格修订，不在此发散）。
+ */
+export declare function apiCallErrorFromHttpResponse(input: {
+    modelId: string;
+    url: string;
+    requestBodyValues: unknown;
+    status: number;
+    responseHeaders: Headers;
+    responseBody: string;
+}): CommandCodeApiCallError;
+/** 错误信封解析：`{"error":{"message":...}}` 优先，兜底 `parsed.message`，再兜底截断原文 */
+export declare function extractErrorMessage(responseBody: string): string;
+/**
+ * 上下文超限特征（400 body 文本判定）：命中即行 5「上下文窗口超限」。
+ * 词表覆盖网关常见表达（context length / window / token limit / prompt 过长等），
+ * 从 jiesou/brent 的判据与宿主 opencode 的 isContextOverflow 词表归纳。
+ * 收敛到与「上下文容量」强相关的短语：宽泛的 413 类文案（request entity too
+ * large 等）不放进来——图片超限的 400 不该被误报成上下文超限（§5 提示用户
+ * 该缩图而非压缩上下文）。
+ */
+export declare function isContextOverflowText(bodyText: string): boolean;