@wallbreakerno4/opencode-commandcode 0.1.0

package/dist/disguise/state.js

@@ -0,0 +1,157 @@
+/**
+ * 伪装模块的状态与调度门面（disguise.md §1/§3/§5，#33）：
+ *
+ * - **per-key 内存 KeyState**（`Map<apiKey, KeyState>`，key 为 Map 键原文、绝不
+ *   落盘绝不进日志——日志一律经 redactApiKey 短哈希）：指纹、回退会话、预请求
+ *   调度；全局内存态（ccVersion、config 冻结）收在对应子模块；
+ * - **指纹进程内稳定（D1）**：KeyState 只增不删，会话轮换只换 session 不删指纹，
+ *   进程重启 = Map 清空、首见 key 重新采集并立即重报（MAXeaglet 同款重启语义）；
+ * - **会话身份主路径（D3）**：doStream 调用 headers 中 `X-Session-Id` /
+ *   `x-session-affinity`（v2 另有同值 `x-opencode-session`）任一存在即确定性派生
+ *   `x-session-id`（session.ts 纯函数）——无需存储即保证同会话同 id、跨重启同 id；
+ *   多头同场值不一致 warn（「值漂移打日志」的落地；跨请求漂移无法与正常的新会话
+ *   区分，不告警防噪音）。全部缺失才落回退路径：per-key 随机 uuid v4、12h +
+ *   0~1h 抖动惰性轮换；
+ * - **预请求调度（D2/D5）**：startPreflight 对齐真实 CLI「每进程启动发一次」
+ *   （幂等守卫）；主请求前 maybeRunPreflight 做惰性补发/退避重试检查，到点后台
+ *   发射，主请求永不等待；
+ * - 全部出网与采集依赖经构造 options 注入（工厂 options.fetch、注入式 logger、
+ *   ConfigRuntime、兜底链 getter），测试零后门。
+ */
+import { randomUUID } from "node:crypto";
+import { initialPreflightState } from "./backoff.js";
+import { createFrozenConfigProvider } from "./config-freeze.js";
+import { buildFingerprintBody, collectFingerprintComponents } from "./fingerprint.js";
+import { consoleLogger } from "./logger.js";
+import { runPreflight } from "./preflight.js";
+import { deriveSessionId } from "./session.js";
+import { redactIdentifier } from "./redact.js";
+import { createVersionResolver } from "./version-runtime.js";
+import { generateTraceparent } from "./traceparent.js";
+/** 会话头查找优先级（session-visibility.md §6：v1 两键 + v2 同值第三键） */
+const SESSION_HEADERS = ["X-Session-Id", "x-session-affinity", "x-opencode-session"];
+/** 回退路径会话寿命：12h + 0~1h 抖动（§11 参数速查，惰性轮换） */
+export const SESSION_TTL_BASE_MS = 12 * 60 * 60 * 1000;
+export const SESSION_TTL_JITTER_MS = 60 * 60 * 1000;
+/** 大小写不敏感收集会话头；返回按优先级的种子与去重后的命中值（值漂移告警用） */
+function collectSessionSeeds(headers) {
+    const lower = new Map();
+    if (headers !== undefined) {
+        for (const [key, value] of Object.entries(headers)) {
+            if (typeof value === "string" && value.length > 0)
+                lower.set(key.toLowerCase(), value);
+        }
+    }
+    const values = [];
+    for (const name of SESSION_HEADERS) {
+        const value = lower.get(name.toLowerCase());
+        if (value !== undefined && !values.includes(value))
+            values.push(value);
+    }
+    return { seed: values[0], values };
+}
+export function createDisguiseState(options = {}) {
+    const logger = options.logger ?? consoleLogger();
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const versionResolver = createVersionResolver({
+        fetch: fetchImpl,
+        logger,
+        artifactSourceCliVersion: options.artifactSourceCliVersion,
+        snapshotSourceCliVersion: options.snapshotSourceCliVersion,
+    });
+    const configProvider = createFrozenConfigProvider({
+        runtime: options.configRuntime,
+        logger,
+    });
+    const keys = new Map();
+    function ensureKeyState(apiKey) {
+        let state = keys.get(apiKey);
+        if (state === undefined) {
+            state = {
+                fingerprintBody: undefined,
+                session: undefined,
+                preflight: initialPreflightState(),
+                preflightInFlight: false,
+                startupPreflightStarted: false,
+                traceContexts: new Map(),
+            };
+            keys.set(apiKey, state);
+        }
+        return state;
+    }
+    function ensureFingerprintBody(state) {
+        state.fingerprintBody ??= collectFingerprintComponents()
+            .then(buildFingerprintBody)
+            .catch((error) => {
+            // 采集承诺内部全降级；真 reject 时清槽允许下轮重试，本轮按瞬时失败推进
+            state.fingerprintBody = undefined;
+            throw error;
+        });
+        return state.fingerprintBody;
+    }
+    function launchPreflight(state, apiKey) {
+        if (state.preflightInFlight)
+            return;
+        state.preflightInFlight = true;
+        void runPreflight({
+            apiKey,
+            preflight: state.preflight,
+            fetchImpl,
+            logger,
+            getVersion: () => versionResolver.getVersion(),
+            ensureFingerprintBody: () => ensureFingerprintBody(state),
+        }).finally(() => {
+            state.preflightInFlight = false;
+        });
+    }
+    return {
+        startPreflight(apiKey) {
+            const state = ensureKeyState(apiKey);
+            if (state.startupPreflightStarted)
+                return;
+            state.startupPreflightStarted = true;
+            launchPreflight(state, apiKey);
+        },
+        maybeRunPreflight(apiKey) {
+            const state = ensureKeyState(apiKey);
+            // 未到点（8–10h 补发窗口 / 退避与冷却未过）零开销返回；到点后台发射
+            if (Date.now() < state.preflight.nextAttemptAt)
+                return;
+            launchPreflight(state, apiKey);
+        },
+        resolveSessionId(apiKey, headers) {
+            const state = ensureKeyState(apiKey);
+            const { seed, values } = collectSessionSeeds(headers);
+            if (seed !== undefined) {
+                if (values.length > 1) {
+                    // 主路径命中但多头值不一致（宿主改头名/漂移的异常信号），脱敏告警
+                    logger.warn(`会话头取值不一致，按 ${SESSION_HEADERS[0]} 优先取用 ${values.map(redactIdentifier).join(" / ")}`);
+                }
+                return deriveSessionId(seed);
+            }
+            // 回退路径：无法区分会话边界，per-key 随机 uuid + 12h + 0~1h 抖动惰性轮换（尽力而为）
+            const existing = state.session;
+            if (existing !== undefined && Date.now() < existing.expiresAt)
+                return existing.id;
+            const next = {
+                id: randomUUID(),
+                expiresAt: Date.now() + SESSION_TTL_BASE_MS + Math.floor(Math.random() * SESSION_TTL_JITTER_MS),
+            };
+            state.session = next;
+            return next.id;
+        },
+        resolveTraceparent(apiKey, sessionId, turnKey) {
+            const state = ensureKeyState(apiKey);
+            const previous = state.traceContexts.get(sessionId);
+            const traceId = previous?.turnKey === turnKey ? previous.traceId : generateTraceparent().slice(3, 35);
+            state.traceContexts.set(sessionId, { turnKey, traceId });
+            return generateTraceparent(traceId);
+        },
+        getCommandCodeVersion() {
+            return versionResolver.getVersion();
+        },
+        getConfigBlock() {
+            return configProvider.get();
+        },
+    };
+}

package/dist/disguise/traceparent.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `traceparent` 头（disguise.md §10 照抄清单，#9 抓包实测吻合）：
+ * `00-<32hex>-<16hex>-01`——版本恒 `00`（W3C Trace Context 当前版本）、
+ * trace-id 16 随机字节、parent-span-id 8 随机字节、flag 恒 `01`。
+ * 逐请求新造、跨请求零复用；只进 generate 主请求，不进预请求与 models。
+ */
+export declare function generateTraceparent(traceId?: string): string;

package/dist/disguise/traceparent.js

@@ -0,0 +1,10 @@
+/**
+ * `traceparent` 头（disguise.md §10 照抄清单，#9 抓包实测吻合）：
+ * `00-<32hex>-<16hex>-01`——版本恒 `00`（W3C Trace Context 当前版本）、
+ * trace-id 16 随机字节、parent-span-id 8 随机字节、flag 恒 `01`。
+ * 逐请求新造、跨请求零复用；只进 generate 主请求，不进预请求与 models。
+ */
+import { randomBytes } from "node:crypto";
+export function generateTraceparent(traceId) {
+    return `00-${traceId ?? randomBytes(16).toString("hex")}-${randomBytes(8).toString("hex")}-01`;
+}

package/dist/disguise/version-cache.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 版本缓存落盘（disguise.md §6 / D1）：伪装模块**唯一**的磁盘 IO。
+ * 路径 `<XDG_CACHE_HOME 或 ~/.cache>/opencode-commandcode/version-cache.json`，
+ * 内容 `{version, fetchedAt}`；写经临时文件 + rename 原子替换，读失败与损坏一律
+ * 视为无值（ENOENT 是首次运行的正常态，静默；其余异常按「落盘异常」warn）。
+ * key 与其他伪装状态与本文件无关——它们只活在内存（D1）。
+ */
+import type { DisguiseLogger } from "./logger.js";
+/** version-cache.json 的一行：上次成功拉取的 CLI 版本与拉取时刻（ISO 8601） */
+export interface VersionCacheEntry {
+    readonly version: string;
+    readonly fetchedAt: string;
+}
+/** 缓存目录解析：XDG_CACHE_HOME 非空优先（含测试重定向，testing.md §3 认可的标准行为），否则 ~/.cache */
+export declare function resolveVersionCacheDir(): string;
+/** 缓存文件完整路径；env 每次现读（不缓存），重定向后同进程即刻生效 */
+export declare function resolveVersionCachePath(): string;
+/**
+ * 原子写：先落同目录临时文件再 rename（同目录保证同一文件系统，rename 原子）。
+ * 失败向上抛给调用方——缓存写失败不构成伪装失败，调用方降兜底 + warn。
+ */
+export declare function writeVersionCache(entry: VersionCacheEntry): Promise<void>;
+/**
+ * 读取上次成功拉取值；ENOENT（首次运行）静默返回 undefined，其余异常与损坏形状
+ * warn 后返回 undefined。日志经注入式 logger（§7），无 logger 时静默。
+ */
+export declare function readVersionCache(logger?: DisguiseLogger): Promise<VersionCacheEntry | undefined>;

package/dist/disguise/version-cache.js

@@ -0,0 +1,69 @@
+/**
+ * 版本缓存落盘（disguise.md §6 / D1）：伪装模块**唯一**的磁盘 IO。
+ * 路径 `<XDG_CACHE_HOME 或 ~/.cache>/opencode-commandcode/version-cache.json`，
+ * 内容 `{version, fetchedAt}`；写经临时文件 + rename 原子替换，读失败与损坏一律
+ * 视为无值（ENOENT 是首次运行的正常态，静默；其余异常按「落盘异常」warn）。
+ * key 与其他伪装状态与本文件无关——它们只活在内存（D1）。
+ */
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/** 缓存目录解析：XDG_CACHE_HOME 非空优先（含测试重定向，testing.md §3 认可的标准行为），否则 ~/.cache */
+export function resolveVersionCacheDir() {
+    return process.env["XDG_CACHE_HOME"] || join(homedir(), ".cache");
+}
+/** 缓存文件完整路径；env 每次现读（不缓存），重定向后同进程即刻生效 */
+export function resolveVersionCachePath() {
+    return join(resolveVersionCacheDir(), "opencode-commandcode", "version-cache.json");
+}
+/**
+ * 原子写：先落同目录临时文件再 rename（同目录保证同一文件系统，rename 原子）。
+ * 失败向上抛给调用方——缓存写失败不构成伪装失败，调用方降兜底 + warn。
+ */
+export async function writeVersionCache(entry) {
+    const path = resolveVersionCachePath();
+    const tmp = `${path}.tmp`;
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(tmp, JSON.stringify(entry), "utf8");
+    await rename(tmp, path);
+}
+/** 缓存形状守卫：{version, fetchedAt} 双非空字符串才可信，其余（损坏/缺字段）视同无值 */
+function parseEntry(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return undefined;
+    const record = parsed;
+    const version = record["version"];
+    const fetchedAt = record["fetchedAt"];
+    if (typeof version !== "string" || version.length === 0)
+        return undefined;
+    if (typeof fetchedAt !== "string" || fetchedAt.length === 0)
+        return undefined;
+    return { version, fetchedAt };
+}
+/**
+ * 读取上次成功拉取值；ENOENT（首次运行）静默返回 undefined，其余异常与损坏形状
+ * warn 后返回 undefined。日志经注入式 logger（§7），无 logger 时静默。
+ */
+export async function readVersionCache(logger) {
+    let raw;
+    try {
+        raw = await readFile(resolveVersionCachePath(), "utf8");
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return undefined;
+        logger?.warn(`版本缓存读取失败，视同无值：${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+    const entry = parseEntry(raw);
+    if (entry === undefined)
+        logger?.warn(`版本缓存形状损坏，视同无值：${resolveVersionCachePath()}`);
+    return entry;
+}

package/dist/disguise/version-runtime.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 版本头 `x-command-code-version` 状态机（disguise.md §6）：
+ *
+ * - **数据源顺序**：npm registry 直连 → jsDelivr 镜像，各挂 1.5s 超时
+ *   （`AbortSignal.timeout`），任一成功即为一手拉取值；
+ * - **初解析（D6b）**：进程内首次取值时启动拉取链并只等 1.5s——抢到用新值，
+ *   抢不到先用兜底值放行、链转后台跑完；修 fire-and-forget「初期请求带陈旧值」
+ *   的同时不让被墙的 npm 拖住首请求；
+ * - **24h 惰性刷新（D6c）**：每次取值比对「距上次**成功**拉取是否超 24h」，到点
+ *   后台触发拉取链。不挂 `setInterval`、不加抖动。全源失败时按字面语义每次取值
+ *   都会重试——全断即 fail-fast（fetch 即刻 reject），fire-and-forget 无主请求
+ *   代价，换网络恢复后的即时校准；
+ * - **重估时刻（#19）**：版本值只在初解析与 24h 刷新两处重算，兜底链的
+ *   artifact/snapshot 层此刻才被读取——期间模型管线产物刷新不引起版本头翻转；
+ * - **兜底链**：竞速值（内存）→ 落盘缓存 → 产物 `sourceCliVersion`（只读内存
+ *   getter，不触发拉取不等待）→ 包内快照 `sourceCliVersion`（version.ts 纯函数）。
+ *   一手拉取成功才写落盘缓存（③ 的值不回写，§6）；写失败降兜底 + warn。
+ *
+ * 出网统一走注入的 fetch 接缝（testing.md §2：全部出网路径经工厂 options.fetch 注 mock）。
+ */
+import type { FetchLike } from "../protocol/json.js";
+import { type DisguiseLogger } from "./logger.js";
+/** 初解析限时等待：超过即用兜底值放行，拉取链转后台 */
+export declare const VERSION_RACE_MS = 1500;
+/** 单一数据源（npm / jsDelivr）的超时上限 */
+export declare const VERSION_SOURCE_TIMEOUT_MS = 1500;
+/** 惰性刷新间隔（§11 参数速查：24h，无抖动） */
+export declare const VERSION_REFRESH_INTERVAL_MS: number;
+export interface VersionResolverOptions {
+    /** 出网接缝（工厂 options.fetch；缺省 globalThis.fetch） */
+    fetch?: FetchLike;
+    logger?: DisguiseLogger;
+    /** 兜底链 ③：模型管线内存中已拉取产物的 sourceCliVersion（不触发拉取、不等待） */
+    artifactSourceCliVersion?: () => string | undefined;
+    /** 兜底链 ④：包内快照的 sourceCliVersion（随插件发版更新） */
+    snapshotSourceCliVersion?: () => string | undefined;
+}
+export interface VersionResolver {
+    /** 当前版本值；初解析未完成时等待（≤1.5s 竞速），四层皆空返回 undefined（调用方决定放行形态） */
+    getVersion(): Promise<string | undefined>;
+}
+export declare function createVersionResolver(options?: VersionResolverOptions): VersionResolver;

package/dist/disguise/version-runtime.js

@@ -0,0 +1,137 @@
+/**
+ * 版本头 `x-command-code-version` 状态机（disguise.md §6）：
+ *
+ * - **数据源顺序**：npm registry 直连 → jsDelivr 镜像，各挂 1.5s 超时
+ *   （`AbortSignal.timeout`），任一成功即为一手拉取值；
+ * - **初解析（D6b）**：进程内首次取值时启动拉取链并只等 1.5s——抢到用新值，
+ *   抢不到先用兜底值放行、链转后台跑完；修 fire-and-forget「初期请求带陈旧值」
+ *   的同时不让被墙的 npm 拖住首请求；
+ * - **24h 惰性刷新（D6c）**：每次取值比对「距上次**成功**拉取是否超 24h」，到点
+ *   后台触发拉取链。不挂 `setInterval`、不加抖动。全源失败时按字面语义每次取值
+ *   都会重试——全断即 fail-fast（fetch 即刻 reject），fire-and-forget 无主请求
+ *   代价，换网络恢复后的即时校准；
+ * - **重估时刻（#19）**：版本值只在初解析与 24h 刷新两处重算，兜底链的
+ *   artifact/snapshot 层此刻才被读取——期间模型管线产物刷新不引起版本头翻转；
+ * - **兜底链**：竞速值（内存）→ 落盘缓存 → 产物 `sourceCliVersion`（只读内存
+ *   getter，不触发拉取不等待）→ 包内快照 `sourceCliVersion`（version.ts 纯函数）。
+ *   一手拉取成功才写落盘缓存（③ 的值不回写，§6）；写失败降兜底 + warn。
+ *
+ * 出网统一走注入的 fetch 接缝（testing.md §2：全部出网路径经工厂 options.fetch 注 mock）。
+ */
+import { consoleLogger } from "./logger.js";
+import { resolveCommandCodeVersion } from "./version.js";
+import { readVersionCache, writeVersionCache } from "./version-cache.js";
+/** 初解析限时等待：超过即用兜底值放行，拉取链转后台 */
+export const VERSION_RACE_MS = 1500;
+/** 单一数据源（npm / jsDelivr）的超时上限 */
+export const VERSION_SOURCE_TIMEOUT_MS = 1500;
+/** 惰性刷新间隔（§11 参数速查：24h，无抖动） */
+export const VERSION_REFRESH_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const NPM_REGISTRY_URL = "https://registry.npmjs.org/command-code/latest";
+const JSDELIVR_URL = "https://cdn.jsdelivr.net/npm/command-code/package.json";
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function createVersionResolver(options = {}) {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const logger = options.logger ?? consoleLogger();
+    // 全部状态收在本闭包（§10 修写表：单一模块 state，非散装全局变量）
+    let raced;
+    let cachedEntry;
+    let resolved;
+    let cacheRead;
+    let initialResolution;
+    let chainInFlight;
+    /** 上次成功拉取的时刻（epoch ms）；0 = 从未成功（D6c 字面语义：此时每次取值都视为到期） */
+    let lastFetchedAt = 0;
+    function recompute() {
+        resolved = resolveCommandCodeVersion({
+            raced,
+            cached: cachedEntry?.version,
+            artifact: options.artifactSourceCliVersion?.(),
+            snapshot: options.snapshotSourceCliVersion?.(),
+        });
+    }
+    function readCacheOnce() {
+        cacheRead ??= readVersionCache(logger).then((entry) => {
+            cachedEntry = entry;
+        });
+        return cacheRead;
+    }
+    /** 单一数据源拉取：GET packument/package.json 取 `version`；非 2xx / 形状不对 / 超时一律 reject */
+    async function fetchSourceVersion(url) {
+        const response = await fetchImpl(url, {
+            headers: { accept: "application/json" },
+            signal: AbortSignal.timeout(VERSION_SOURCE_TIMEOUT_MS),
+        });
+        if (!response.ok)
+            throw new Error(`HTTP ${response.status}`);
+        const body = await response.json();
+        const version = asRecord(body)?.["version"];
+        if (typeof version !== "string" || version.length === 0)
+            throw new Error("响应缺少 version 字段");
+        return version;
+    }
+    /**
+     * 拉取链：npm 直连 → jsDelivr 镜像，先到者胜。成功即更新内存与兜底链并重估
+     * （24h 刷新是规格允许的第二个重估时刻）；写缓存失败只 warn，不影响内存值。
+     * 整体绝不 reject（调用方均为 fire-and-forget 或竞速等待，无 await 侧异常路径）。
+     */
+    function refreshChain() {
+        if (chainInFlight)
+            return chainInFlight;
+        const task = (async () => {
+            try {
+                let version;
+                try {
+                    version = await fetchSourceVersion(NPM_REGISTRY_URL);
+                }
+                catch {
+                    version = await fetchSourceVersion(JSDELIVR_URL).catch(() => undefined);
+                }
+                if (version === undefined)
+                    return;
+                raced = version;
+                recompute(); // 内存值先行更新（主请求永不等待磁盘）；落盘只服务下次进程的兜底链
+                const entry = { version, fetchedAt: new Date().toISOString() };
+                try {
+                    await writeVersionCache(entry);
+                    cachedEntry = entry;
+                }
+                catch (error) {
+                    logger.warn(`版本缓存写入失败，降兜底值：${error instanceof Error ? error.message : String(error)}`);
+                }
+                lastFetchedAt = Date.now(); // D6c 字面：成功拉取才记账
+                logger.debug(`x-command-code-version 更新为 ${version}`);
+            }
+            finally {
+                chainInFlight = undefined;
+            }
+        })();
+        chainInFlight = task;
+        return task;
+    }
+    /** 初解析（仅一次）：读盘与竞速并行，1.5s 限时等链，超时落兜底链取值放行 */
+    function resolveInitial() {
+        return (async () => {
+            await Promise.race([refreshChain(), delay(VERSION_RACE_MS)]);
+            await readCacheOnce();
+            recompute();
+        })();
+    }
+    return {
+        async getVersion() {
+            // 24h 惰性刷新（D6c 字面）：距上次成功拉取超 24h 即后台触发；失败链在下次
+            // 取值时照常重试（全断即 fail-fast，无主请求代价）；chainInFlight 去重保证
+            // 初解析期间与并发取值不重复发起
+            if (Date.now() - lastFetchedAt >= VERSION_REFRESH_INTERVAL_MS)
+                void refreshChain();
+            initialResolution ??= resolveInitial();
+            await initialResolution;
+            return resolved;
+        },
+    };
+}

package/dist/disguise/version.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 版本头 `x-command-code-version` 兜底链取值（disguise.md §6，#19 修订全链序）：
+ * ① npm/jsDelivr 竞速成功值（内存）→ ② 落盘缓存值 → ③ 运行时已拉取构建产物的
+ * `sourceCliVersion`（只读内存，不触发额外拉取、不等待，也不回写落盘缓存）→
+ * ④ 包内快照 `sourceCliVersion`。
+ *
+ * 本模块只定取值顺序；竞速、24h 惰性刷新与落盘读写归状态层（#33）。
+ * 空串视同无值——竞速失败或损坏缓存可能残留空串，不应短路后面的层。
+ */
+export interface CommandCodeVersionChain {
+    /** ① npm/jsDelivr 竞速成功值（进程内存） */
+    raced?: string | undefined;
+    /** ② 落盘的「上次成功拉取值」（version-cache.json） */
+    cached?: string | undefined;
+    /** ③ 运行时已拉取构建产物的 sourceCliVersion（模型管线内存中已有才有值） */
+    artifact?: string | undefined;
+    /** ④ 包内快照的 sourceCliVersion（随插件发版更新） */
+    snapshot?: string | undefined;
+}
+/** 按兜底链序返回首个非空版本；四层皆空时 undefined（调用方决定放行形态） */
+export declare function resolveCommandCodeVersion(chain: CommandCodeVersionChain): string | undefined;

package/dist/disguise/version.js

@@ -0,0 +1,17 @@
+/**
+ * 版本头 `x-command-code-version` 兜底链取值（disguise.md §6，#19 修订全链序）：
+ * ① npm/jsDelivr 竞速成功值（内存）→ ② 落盘缓存值 → ③ 运行时已拉取构建产物的
+ * `sourceCliVersion`（只读内存，不触发额外拉取、不等待，也不回写落盘缓存）→
+ * ④ 包内快照 `sourceCliVersion`。
+ *
+ * 本模块只定取值顺序；竞速、24h 惰性刷新与落盘读写归状态层（#33）。
+ * 空串视同无值——竞速失败或损坏缓存可能残留空串，不应短路后面的层。
+ */
+/** 按兜底链序返回首个非空版本；四层皆空时 undefined（调用方决定放行形态） */
+export function resolveCommandCodeVersion(chain) {
+    for (const value of [chain.raced, chain.cached, chain.artifact, chain.snapshot]) {
+        if (typeof value === "string" && value.length > 0)
+            return value;
+    }
+    return undefined;
+}

package/dist/host/constants.d.ts

@@ -0,0 +1,14 @@
+/**
+ * v1/v2 glue 共享的宿主面常量（单源防漂移——v1 与 v2 宿主各自独立消费同一批
+ * 注册字段，复制粘贴会让「多处同名」不变量悄悄分叉）。
+ *
+ * 同名约束出处：CONTEXT.md——provider 显示名在 v1 /connect 列表项、v2 目录与
+ * provider 列表、v2 integration name 同用；认证方法 label 固定「Command Code
+ * API Key」，v1 auth hook 与 v2 integration key method 同文案。
+ */
+/** provider 显示名「Command Code (Go)」（CONTEXT.md，两宿主同用） */
+export declare const PROVIDER_DISPLAY_NAME = "Command Code (Go)";
+/** 认证方法 label：「Command Code API Key」，/connect 认证输入框标题（CONTEXT.md） */
+export declare const API_KEY_METHOD_LABEL = "Command Code API Key";
+/** env 认证通道扫描的环境变量（与 .env.example 清单一致） */
+export declare const API_KEY_ENV_VAR = "COMMANDCODE_API_KEY";

package/dist/host/constants.js

@@ -0,0 +1,14 @@
+/**
+ * v1/v2 glue 共享的宿主面常量（单源防漂移——v1 与 v2 宿主各自独立消费同一批
+ * 注册字段，复制粘贴会让「多处同名」不变量悄悄分叉）。
+ *
+ * 同名约束出处：CONTEXT.md——provider 显示名在 v1 /connect 列表项、v2 目录与
+ * provider 列表、v2 integration name 同用；认证方法 label 固定「Command Code
+ * API Key」，v1 auth hook 与 v2 integration key method 同文案。
+ */
+/** provider 显示名「Command Code (Go)」（CONTEXT.md，两宿主同用） */
+export const PROVIDER_DISPLAY_NAME = "Command Code (Go)";
+/** 认证方法 label：「Command Code API Key」，/connect 认证输入框标题（CONTEXT.md） */
+export const API_KEY_METHOD_LABEL = "Command Code API Key";
+/** env 认证通道扫描的环境变量（与 .env.example 清单一致） */
+export const API_KEY_ENV_VAR = "COMMANDCODE_API_KEY";

package/dist/host/v1.d.ts

@@ -0,0 +1,85 @@
+/**
+ * v1 宿主接线（#37；实测定案 #11，原型证据在弃用分支 prototype/v1-host-loading）。
+ *
+ * 用户 config 只写一行 `plugin: ["@wallbreakerno4/opencode-commandcode"]`，其余全部
+ * 自举（与 v2 glue #36 共用工厂与运行时，宿主形态互不干扰）：
+ *
+ * - **三合一入口**：`server(input, options)` 由 v1 加载器消费（default 带 id 时
+ *   server 必须在场，否则整模块跳过，#11 实测），返回 `{config, auth}` hooks。
+ *   v1.18.x 是双轨宿主——内嵌 v2 运行时也会以嵌入式 ctx 调 default.setup，但它
+ *   懒加载且晚于 v1 config hook（1.18.25 真宿主探针实测），管线模式由先到的 v1
+ *   config hook 协商为 v1，setup 的构造调用幂等落空。
+ * - **config hook**：注入 `provider.commandcode-go = {npm, name, env, models}`。
+ *   npm 指向本包安装 spec（推导方式见 selfNpmSpec——注入裸包名会装出第二个模块
+ *   实例）；宿主经 arborist 缓存命中后 import 同一模块实例（目录存在即缓存命中，
+ *   #11 实测），按「第一个 create* 导出」判得与 v2 共用的工厂。注入前先以用户
+ *   已写的 `options.modelsUrls` 做 v1 启动协商（拉取一次，15s 总预算，失败用快照，
+ *   此后无后台刷新——v1 无 reload 机制），模型清单 = 协商后的级联。
+ * - **非破坏合并**：用户已写键一律优先（npm/name/env 整键、options 整块、models
+ *   逐 id）——插件只补缺，绝不覆盖用户显式配置；`options` 全权归用户（modelsUrls
+ *   通道所在），插件不注入任何默认值。
+ * - **auth hook**：注册 `/connect` 登录项（label 固定「Command Code API Key」，
+ *   CONTEXT.md）；loader 仅在 auth.json 有该 provider 凭证记录时被宿主调用（无凭证
+ *   不触发，#11 实测），把凭证翻译成工厂 `apiKey`；优先级 auth > env 由宿主保证
+ *   （与 v2 credential > env 一致）。
+ * - **测试边界**（testing.md §4 定案）：hook 的宿主交互行为不入 bun test——mock
+ *   宿主 = 重写宿主，验证 = 真宿主 v1（latest 1.18.x）验证，全程 XDG 隔离；
+ *   hooks 静态形状与 selfNpmSpec 纯函数推导在 bun test 内（testing.md §1.4）。
+ *
+ * 零依赖纪律（入口既定）：不 import `@opencode-ai/plugin`，宿主对象以本模块的
+ * 最小结构类型承接——字段名按 v1.18.25 真宿主探针收窄到 glue 触达的域，宿主漂移
+ * 时真宿主验证即暴露，不为漂移预付兼容成本。
+ */
+/**
+ * config hook 注入的 npm spec：从入口模块自身的加载路径推导（#37 真宿主验证定案）。
+ * v1 宿主对 plugin 列表的裸包名会归一化为 `<name>@latest` 再定 arborist 缓存目录，
+ * 而 provider 的 `npm` spec **原样**定目录——注入裸包名会装出第二个模块实例，
+ * 伪装状态与模型管线全部翻倍（违背「v1 无后台刷新」与伪装 per-key 状态的进程内
+ * 单例前提）。因此 spec 不能写死包名，按 v1 缓存目录布局
+ * `…/opencode/packages/<spec>/node_modules/…` 从实际加载路径提取：
+ * - 正常安装形态（plugin 裸包名 → @latest 归一化、版本钉死等）：提取出的 `<spec>`
+ *   使 provider 解析命中同一缓存目录（目录存在即缓存命中，#11 实测）——同一模块
+ *   实例。
+ * - 其余形态（本地 file:// 直载开发、缓存布局漂移）：回退入口自身 URL，免安装
+ *   直接 import（#11 实测 file:// 绝对路径形态可用；file: 相对路径残缺不可用，
+ *   不产出）。
+ * 推导在 server() 调用时进行（ENTRY_URL 此时必已初始化，规避环导 TDZ）。
+ */
+export declare function selfNpmSpec(entryUrl: string): string;
+/** v1 provider config 块：注入字段 + 用户可能已写的任意字段 */
+export interface V1ProviderConfig {
+    npm?: string;
+    name?: string;
+    env?: string[];
+    /** options 块全权归用户（modelsUrls 通道所在）；插件不注入、不合并、原样保留 */
+    options?: Record<string, unknown>;
+    models?: Record<string, unknown>;
+}
+/** v1 config hook 收到的宿主 config 对象：只触达 provider 域，其余字段零知识 */
+export interface V1ConfigObject {
+    provider?: Record<string, V1ProviderConfig | undefined>;
+}
+/** v1 auth hook 的登录方式：/connect 列表项（api 类型 + label） */
+export interface V1AuthMethod {
+    readonly type: "api";
+    readonly label: string;
+}
+/** v1 auth hook：provider 凭证通道注册（#11 实测消费行为；宿主以 (auth, provider) 调用） */
+export interface V1AuthHook {
+    readonly provider: string;
+    /** 仅在 auth.json 有该 provider 凭证记录时被调；auth 参数可能是懒加载函数 */
+    readonly loader: (auth: unknown) => Promise<{
+        apiKey: string;
+    }>;
+    readonly methods: readonly V1AuthMethod[];
+}
+/** server() 返回的 v1 hooks（v1 加载器消费的全部面） */
+export interface V1Hooks {
+    config: (config: V1ConfigObject) => Promise<void>;
+    auth: V1AuthHook;
+}
+/**
+ * v1 插件入口（default.server）：返回 config / auth hooks。纯函数——宿主可能在
+ * config 重载或 auth login 等场景重复调用，重放注入幂等（同级联 → 同块）。
+ */
+export declare function serverV1(_input: unknown, _options: unknown): Promise<V1Hooks>;