pi-firecode 0.8.0

package/master/prompt.ts

@@ -0,0 +1,26 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PROMPTS_DIR = join(dirname(fileURLToPath(import.meta.url)), "prompts");
+
+export type MasterPromptKind = "master" | "worker";
+
+export function readMasterPrompt(kind: MasterPromptKind): string {
+	let prompt: string;
+	try {
+		prompt = readFileSync(join(PROMPTS_DIR, `${kind}.zh.md`), "utf8");
+	} catch (error) {
+		throw new Error(`Master ${kind} prompt 读取失败：${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!prompt.trim()) throw new Error(`Master ${kind} prompt 为空`);
+	return prompt.trim();
+}
+
+export function assembleMasterPrompt(prompt: string, roster: string): string {
+	return `${prompt}\n\n角色表：${roster}。`;
+}
+
+export function assembleWorkerPrompt(prompt: string, name: string): string {
+	return `<firecode_worker name="${name}">\n${prompt}\n</firecode_worker>`;
+}

package/master/prompts/master.zh.md

@@ -0,0 +1,17 @@
+subagents 激活时，你是唯一的指挥官（Master），负责委派与最终验收，把任务推进到交付完成。
+
+- 派发：role 只使用调研员、工程师、全栈、架构师、设计师、哨兵六个固定词；start 按已配置角色表显式传 role，send 需要换职能时也传 role；thinking 仅在用户明确要求时覆盖角色原子档。供应商额度或计费耗尽、模型不可用、宿主重试用尽的持续 5xx 会自动按该角色 fallback 降级并回报；架构师费用高，启用前必须先征求用户确认。以等待为主的盯守（CI、部署、长测试）使用哨兵。
+- 动手边界：短小明确的活亲手做——单文件小改、数条命令内可完成并验证的任务，委派开销大于任务本身就不委派。委派用于长时间运行、可并行、产生大量中间输出、需要干净上下文或独立验证的任务。终审 diff 与交付裁决始终亲手。
+- 并行：并行实现前先冻结共享边界——接口、共享类型、注册表、schema 由你亲手或单一 Worker 先行落地，其余 Worker 按路径划界同时开跑，每个共享文件只有一个写者，工作说明写明各自路径；集成以测试门裁决。
+- 工单：项目存在工单库时，每次派发前按约定认领工单、对齐他人工单状态，并基于最新代码开工；新问题由你决策开新工单或交给上下文合适的在场 Worker 顺手解决，Worker 不开单。无工单库则以用户验收为交付边界。
+- 实现标准：实现类工作说明要求 Worker 先读 implement 技能（~/.agents/skills/matt/implement）再动手；你终审时按同一标准裁决。
+- 收割：调研与盯守 Worker 收割要点后立即 kill；实现 Worker 保留到收口。计划产物存在时，其维护责任随指挥权归你。
+- 调研衔接：执行档模型的聚焦探索（读代码定位、方案设计）直接 send 续派原 Worker 执行，现场就是工作上下文。廉价档或高噪声调研（大量搜索、日志、死路）只收割结构化线索（事实、路径、候选、证据来源、未决问题），核实后另派执行 Worker，不复用 transcript。
+- 投递：Worker 结果、中断与审查终态会自动送达；tail 仅用于按需读取执行细节。
+- 何时审查：复杂且影响大的实现，以及无法靠窄测可靠验收的任务，需要对抗性审查，在 start 时传 review:true；其余任务省略。
+- 如何启动：review:true 只是在任务开始时标记“这个任务完成后需要审查”，不会自动启动审查。这个标记不会因 send、reload、中断或失败而丢失，审查结束前不能 ack。Worker 返回结果并完成验证后，指挥官主动执行 review，才会开始对抗性审查。任务开始时没有标记 review:true，也可以在 Worker 空闲后主动执行 review；如果整个任务已经放弃，直接 kill。
+- 审查过程：review 会在原 Worker 会话中启动。独立模型读取 Worker 的工作记录，核对相关文件和验证结果。发现问题时，审查意见会交回同一个 Worker 核实和修复，然后再次审查；审查通过、顾问决定停止或达到最大轮数后结束。审查通过时仍可能附带不阻塞交付的建议，由指挥官判断是否需要继续处理。
+- 审查收尾：审查通过但附带的非阻塞建议确有必要解决时，在原 Worker 会话收口干净再 ack。
+- 交付：终审 diff 后，重要改动亲手 dogfood 试用；完全符合原则才 PR 与合并，看到发布成功后关闭工单并同步状态。合并冲突按 resolving-merge-conflicts 技能处理。
+
+调用样板：start {"worker":"fix-auth","role":"工程师","prompt":"自包含工作说明"}；send {"worker":"fix-auth","role":"架构师","prompt":"自包含工作说明"}。

package/master/prompts/worker.zh.md

@@ -0,0 +1 @@
+你是指挥官委派的 Worker，只在当前 checkout 内完成工作说明。验证改动并报告结果、证据与遗留风险；无法完成或验证时如实报告阻塞原因和现场，不得假成功。Git 操作限于本地且仅覆盖自己修改的路径。

package/master/role.ts

@@ -0,0 +1,13 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export type SubsessionRole = "worker" | "observer" | "reviewer" | "advisor";
+
+const ROLE = new AsyncLocalStorage<SubsessionRole>();
+
+export function currentSubsessionRole(): SubsessionRole | undefined {
+	return ROLE.getStore();
+}
+
+export function withSubsessionRole<T>(role: SubsessionRole, run: () => Promise<T>): Promise<T> {
+	return ROLE.run(role, run);
+}

package/master/spawn.ts

@@ -0,0 +1,193 @@
+import { existsSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import type { Model } from "@earendil-works/pi-ai";
+import {
+	createAgentSession,
+	DefaultResourceLoader,
+	getAgentDir,
+	ModelRuntime,
+	SessionManager,
+	type AgentSession,
+	type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { withSubsessionRole, type SubsessionRole } from "./role.js";
+import type { WorkerThinking } from "./state.js";
+
+export const IDLE_SESSION_TIMEOUT_MS = 10 * 60_000;
+
+export type SessionPersistence =
+	| { type: "memory" }
+	| { type: "file"; sessionPath: string; resume?: boolean };
+
+export interface SpawnSessionOptions {
+	cwd: string;
+	model: Model<any>;
+	role: SubsessionRole;
+	thinking: WorkerThinking;
+	tools: string[];
+	/** 只属于本子会话的工具（如观察员的 advise）；名字仍要出现在 tools 里才激活。 */
+	customTools?: ToolDefinition[];
+	excludeExtensions?: string[];
+	systemPrompt: { mode: "append" | "replace"; text: string };
+	contextFiles: boolean;
+	persistence: SessionPersistence;
+	/** 审查会话关闭自动扩展、Skill 与模板，保持评判政策不受被审项目改写。 */
+	isolated?: boolean;
+}
+
+export interface SpawnedSession {
+	readonly session: AgentSession;
+	readonly sessionPath?: string;
+	prompt(text: string): Promise<void>;
+	dispose(): void;
+}
+
+interface HeldSession {
+	key: string;
+	session: AgentSession;
+	sessionPath?: string;
+	timer?: NodeJS.Timeout;
+	unsubscribe?: () => void;
+	disposed: boolean;
+}
+
+const SESSION_WRITERS = new Set<string>();
+
+/** 全插件唯一的进程内子会话入口；池同时是 JSONL 单写者登记。 */
+export class InProcessSessionPool {
+	private readonly held = new Map<string, HeldSession>();
+
+	constructor(private readonly environment: {
+		agentDir?: string;
+		modelRuntime?: ModelRuntime;
+		idleTimeoutMs?: number;
+	} = {}) {}
+
+	async spawn(options: SpawnSessionOptions): Promise<SpawnedSession> {
+		const sessionPath = options.persistence.type === "file" ? options.persistence.sessionPath : undefined;
+		if (sessionPath && SESSION_WRITERS.has(sessionPath))
+			throw new Error(`sessionPath 已有进程内会话持有：${sessionPath}`);
+		if (options.persistence.type === "file" && options.persistence.resume && !existsSync(sessionPath!))
+			throw new Error(`无法恢复子代理：会话文件不存在：${sessionPath}`);
+		if (sessionPath) SESSION_WRITERS.add(sessionPath);
+
+		let created: AgentSession;
+		try {
+			const loader = new DefaultResourceLoader({
+				cwd: options.cwd,
+				agentDir: this.environment.agentDir ?? getAgentDir(),
+				noContextFiles: !options.contextFiles,
+				noExtensions: options.isolated,
+				noSkills: options.isolated,
+				noPromptTemplates: options.isolated,
+				...(options.systemPrompt.mode === "replace"
+					? { systemPrompt: options.systemPrompt.text }
+					: { appendSystemPrompt: [options.systemPrompt.text] }),
+				extensionsOverride: (base) => ({
+					...base,
+					extensions: base.extensions.filter((extension) =>
+						!matchesExtension(extension.path, options.excludeExtensions ?? [])),
+				}),
+			});
+			await withSubsessionRole(options.role, () => loader.reload());
+			if (loader.getExtensions().errors.length)
+				throw new Error(`子会话扩展加载失败：${JSON.stringify(loader.getExtensions().errors)}`);
+			const sessionManager = makeSessionManager(options.persistence, options.cwd);
+			const result = await createAgentSession({
+				cwd: options.cwd,
+				agentDir: this.environment.agentDir,
+				modelRuntime: this.environment.modelRuntime,
+				model: options.model,
+				thinkingLevel: options.thinking,
+				tools: options.tools,
+				...(options.customTools ? { customTools: options.customTools } : {}),
+				resourceLoader: loader,
+				sessionManager,
+			});
+			await result.session.bindExtensions({ mode: "print" });
+			created = result.session;
+		} catch (error) {
+			if (sessionPath) SESSION_WRITERS.delete(sessionPath);
+			throw error;
+		}
+
+		const key = sessionPath ?? `memory:${crypto.randomUUID()}`;
+		const held: HeldSession = { key, session: created, sessionPath, disposed: false };
+		this.held.set(key, held);
+		held.unsubscribe = created.subscribe((event) => {
+			if (event.type === "agent_start") this.clearTimer(held);
+			if (event.type === "agent_settled") this.armIdleDisposal(held);
+		});
+		return {
+			session: created,
+			sessionPath,
+			prompt: (text) => created.prompt(text),
+			dispose: () => this.release(held),
+		};
+	}
+
+	has(sessionPath: string): boolean {
+		return this.held.has(sessionPath);
+	}
+
+	getSession(sessionPath: string): AgentSession | undefined {
+		const held = this.held.get(sessionPath);
+		if (!held) return undefined;
+		this.clearTimer(held);
+		return held.session;
+	}
+
+	markIdle(sessionPath: string): void {
+		const held = this.held.get(sessionPath);
+		if (held) this.armIdleDisposal(held);
+	}
+
+	dispose(sessionPath: string): boolean {
+		const held = this.held.get(sessionPath);
+		if (!held) return false;
+		this.release(held);
+		return true;
+	}
+
+	disposeAll(): void {
+		for (const held of [...this.held.values()]) this.release(held);
+	}
+
+	private armIdleDisposal(held: HeldSession): void {
+		this.clearTimer(held);
+		held.timer = setTimeout(() => {
+			if (!held.session.isStreaming) this.release(held);
+		}, this.environment.idleTimeoutMs ?? IDLE_SESSION_TIMEOUT_MS);
+		held.timer.unref?.();
+	}
+
+	private release(held: HeldSession): void {
+		if (held.disposed) return;
+		held.disposed = true;
+		held.unsubscribe?.();
+		this.clearTimer(held);
+		held.session.dispose();
+		if (this.held.get(held.key) === held) this.held.delete(held.key);
+		if (held.sessionPath) SESSION_WRITERS.delete(held.sessionPath);
+	}
+
+	private clearTimer(held: HeldSession): void {
+		if (held.timer) clearTimeout(held.timer);
+		held.timer = undefined;
+	}
+}
+
+export function preallocateWorkerSession(mainSessionPath: string, cwd: string): string {
+	const sessionPath = SessionManager.create(cwd, `${dirname(mainSessionPath)}/subagents`).getSessionFile();
+	if (!sessionPath) throw new Error("无法为子代理预分配 Pi session 路径");
+	return sessionPath;
+}
+
+function makeSessionManager(persistence: SessionPersistence, cwd: string): SessionManager {
+	if (persistence.type === "memory") return SessionManager.inMemory(cwd);
+	return SessionManager.open(persistence.sessionPath, dirname(persistence.sessionPath), cwd);
+}
+
+function matchesExtension(path: string, exclusions: string[]): boolean {
+	return exclusions.some((excluded) => excluded === path || excluded === basename(path));
+}

package/master/state.ts

@@ -0,0 +1,201 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const STATE_VERSION = 8;
+
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export type WorkerThinking = (typeof THINKING_LEVELS)[number];
+export type WorkerStatus = "working" | "idle" | "reviewing";
+export type WorkerDisposition = "pending" | "reminded";
+
+export interface WorkerRef {
+	name: string;
+	role: string;
+	model: string;
+	thinking: WorkerThinking;
+	status: WorkerStatus;
+	sessionPath: string;
+	cwd?: string;
+	interruptedAt?: number;
+	reviewNeeded?: boolean;
+	disposition?: WorkerDisposition;
+}
+
+export interface MasterState {
+	version: typeof STATE_VERSION;
+	workers: WorkerRef[];
+}
+
+export type MasterEvent =
+	| { type: "UPSERT_WORKER"; worker: WorkerRef }
+	| { type: "REMOVE_WORKER"; name: string }
+	| { type: "CLEAR" };
+
+export function initialMasterState(): MasterState {
+	return { version: STATE_VERSION, workers: [] };
+}
+
+export function reduceMaster(state: MasterState, event: MasterEvent): MasterState {
+	switch (event.type) {
+		case "UPSERT_WORKER":
+			return { ...state, workers: upsertWorker(state.workers, event.worker) };
+		case "REMOVE_WORKER": {
+			const workers = state.workers.filter((worker) => worker.name !== event.name);
+			return workers.length === state.workers.length ? state : { ...state, workers };
+		}
+		case "CLEAR":
+			return initialMasterState();
+	}
+}
+
+export function recoverMasterState(state: MasterState, interruptedAt = Date.now()): MasterState {
+	let changed = false;
+	const workers = state.workers.map((worker) => {
+		if (worker.status === "idle") return worker;
+		changed = true;
+		return { ...worker, status: "idle" as const, interruptedAt };
+	});
+	return changed ? { ...state, workers } : state;
+}
+
+export function restoreMasterState(data: unknown): MasterState | undefined {
+	if (!data || typeof data !== "object" || Array.isArray(data)) return undefined;
+	const record = data as Record<string, unknown>;
+	if (record.version !== STATE_VERSION || !Array.isArray(record.workers) || !record.workers.every(isWorker))
+		return undefined;
+	const workers = record.workers as WorkerRef[];
+	if (new Set(workers.map((worker) => worker.name)).size !== workers.length) return undefined;
+	if (new Set(workers.map((worker) => worker.sessionPath)).size !== workers.length) return undefined;
+	return { version: STATE_VERSION, workers };
+}
+
+export class LegacyMasterStateError extends Error {
+	constructor(readonly version: number) {
+		super(
+			`Master Worker Pool 状态是旧版 v${version}（当前 v${STATE_VERSION}），不再读取；`
+			+ "重新启动指挥官模式会从空池重建，旧运行时进程不会纳入新池，需要手动清理",
+		);
+	}
+}
+
+export function masterStatePath(sessionId: string): string {
+	const safeId = sessionId.replace(/[^a-zA-Z0-9_-]/gu, "-");
+	return join(homedir(), ".pi", "agent", "tmp", `firecode-master-${safeId}.json`);
+}
+
+export function loadMasterState(path: string): MasterState | undefined {
+	let raw: string;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+	let data: unknown;
+	try {
+		data = JSON.parse(raw);
+	} catch {
+		throw new Error(`Master Worker Pool 状态不是合法 JSON：${path}`);
+	}
+	const version = (data as { version?: unknown } | null)?.version;
+	if (typeof version === "number" && version !== STATE_VERSION) throw new LegacyMasterStateError(version);
+	const state = restoreMasterState(data);
+	if (!state) throw new Error(`Master Worker Pool 状态结构无效：${path}`);
+	return state;
+}
+
+export class MasterStore {
+	private stateValue: MasterState;
+	private readonly path: string;
+	private readonly onChange?: () => void;
+	readonly discardedLegacyVersion?: number;
+
+	constructor(path: string, restored?: MasterState, onChange?: () => void) {
+		this.path = path;
+		this.onChange = onChange;
+		if (restored) this.stateValue = restored;
+		else {
+			const loaded = this.loadOwnedState();
+			this.stateValue = loaded.state;
+			this.discardedLegacyVersion = loaded.discardedLegacyVersion;
+		}
+	}
+
+	get state(): MasterState {
+		return this.stateValue;
+	}
+
+	dispatch(event: MasterEvent): MasterState {
+		const next = reduceMaster(this.stateValue, event);
+		if (next === this.stateValue) return next;
+		if (event.type === "CLEAR") rmSync(this.path, { force: true });
+		else writeState(this.path, next);
+		this.stateValue = next;
+		this.onChange?.();
+		return next;
+	}
+
+	private loadOwnedState(): { state: MasterState; discardedLegacyVersion?: number } {
+		try {
+			return { state: loadMasterState(this.path) ?? initialMasterState() };
+		} catch (error) {
+			if (!(error instanceof LegacyMasterStateError)) throw error;
+			rmSync(this.path, { force: true });
+			return { state: initialMasterState(), discardedLegacyVersion: error.version };
+		}
+	}
+}
+
+export function requireWorker(state: MasterState, name: string): WorkerRef {
+	const worker = state.workers.find((candidate) => candidate.name === name);
+	if (!worker) throw new Error(`子代理不存在：${name}`);
+	return worker;
+}
+
+function writeState(path: string, state: MasterState): void {
+	mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+	const temporary = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+	try {
+		writeFileSync(temporary, `${JSON.stringify(state)}\n`, { encoding: "utf8", mode: 0o600 });
+		renameSync(temporary, path);
+	} catch (error) {
+		rmSync(temporary, { force: true });
+		throw error;
+	}
+}
+
+function upsertWorker(workers: WorkerRef[], worker: WorkerRef): WorkerRef[] {
+	const index = workers.findIndex((candidate) => candidate.name === worker.name);
+	const sessionOwner = workers.find((candidate) => candidate.sessionPath === worker.sessionPath);
+	if (sessionOwner && sessionOwner.name !== worker.name)
+		throw new Error(`sessionPath 已被占用：${worker.sessionPath}`);
+	if (index < 0) return [...workers, worker];
+	if (workers[index].sessionPath !== worker.sessionPath)
+		throw new Error(`子代理 ${worker.name} 不能更换 sessionPath`);
+	return workers.map((candidate, position) => (position === index ? worker : candidate));
+}
+
+function isWorker(value: unknown): value is WorkerRef {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const record = value as Record<string, unknown>;
+	if (
+		typeof record.name !== "string" || !/^[a-z][a-z0-9_-]{0,31}$/u.test(record.name) ||
+		typeof record.role !== "string" || !record.role ||
+		typeof record.model !== "string" || !record.model ||
+		typeof record.thinking !== "string" || !THINKING_LEVELS.includes(record.thinking as WorkerThinking) ||
+		typeof record.status !== "string" || !isStatus(record.status) ||
+		typeof record.sessionPath !== "string" || !record.sessionPath
+	) return false;
+	if (record.cwd !== undefined && (typeof record.cwd !== "string" || !record.cwd)) return false;
+	if (record.interruptedAt !== undefined && (typeof record.interruptedAt !== "number" || record.interruptedAt <= 0))
+		return false;
+	if (record.reviewNeeded !== undefined && typeof record.reviewNeeded !== "boolean") return false;
+	if (record.disposition !== undefined && record.disposition !== "pending" && record.disposition !== "reminded")
+		return false;
+	return true;
+}
+
+function isStatus(value: string): value is WorkerStatus {
+	return value === "working" || value === "idle" || value === "reviewing";
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "pi-firecode",
+  "version": "0.8.0",
+  "description": "A modular Pi extension for terminal UI, session workflows, adversarial review, and delegated agents",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Suge8/firecode.git"
+  },
+  "homepage": "https://github.com/Suge8/firecode#readme",
+  "bugs": {
+    "url": "https://github.com/Suge8/firecode/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension"
+  ],
+  "files": [
+    "*.ts",
+    "config.example.jsonc",
+    "master/*.ts",
+    "master/prompts/*.md",
+    "provider/claude-sub.ts",
+    "provider/openai-native/index.ts",
+    "provider/openai-native/src/compact-client.ts",
+    "provider/openai-native/src/config.ts",
+    "provider/openai-native/src/extension.ts",
+    "provider/openai-native/src/native-compaction.ts",
+    "provider/openai-native/src/native-details.ts",
+    "provider/openai-native/src/native-replay.ts",
+    "provider/openai-native/src/native-runtime.ts",
+    "provider/openai-native/src/options.ts",
+    "provider/openai-native/src/request-pipeline.ts",
+    "provider/openai-native/src/responses-input.ts",
+    "!provider/openai-native/src/*.test.ts",
+    "review/*.ts",
+    "review/prompts/*.md",
+    "session/*.ts",
+    "statusbar/*.ts",
+    "tools/*.ts",
+    "watcher/*.ts",
+    "watcher/prompts/*.md"
+  ],
+  "scripts": {
+    "test": "bun test"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  }
+}

package/provider/claude-sub.ts

@@ -0,0 +1,129 @@
+/**
+ * Anthropic OAuth 会话按 Claude Code 的归因格式发请求：补 user-agent 与
+ * 系统提示词首块的 billing header，缺失时注入，已存在则原样通过。
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const BILLING_PREFIX = "x-anthropic-billing-header:";
+const FALLBACK_CLAUDE_CODE_VERSION = "2.1.229";
+const DEFAULT_ENTRYPOINT = "cli";
+const BILLING_SALT = "59cf53e54c78";
+
+type TextBlock = {
+	type: "text";
+	text: string;
+	cache_control?: { type: "ephemeral"; ttl?: "1h" };
+};
+
+interface PayloadLike {
+	system?: unknown;
+	messages?: unknown;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function isTextBlock(value: unknown): value is TextBlock {
+	return isObject(value) && value.type === "text" && typeof value.text === "string";
+}
+
+function shouldApply(ctx: ExtensionContext): boolean {
+	const model = ctx.model;
+	return !!model && model.provider === "anthropic" && ctx.modelRegistry.isUsingOAuth(model);
+}
+
+function detectClaudeCodeVersion(): string {
+	const explicit = process.env.PI_CLAUDE_CODE_VERSION;
+	if (explicit) return explicit;
+
+	try {
+		const output = execFileSync("claude", ["--version"], {
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+			timeout: 1000,
+		});
+		const match = output.match(/\b\d+\.\d+\.\d+\b/);
+		if (match) return match[0];
+	} catch {
+		// 本地未装 Claude Code 时用回退版本号，不阻塞启动。
+	}
+
+	return FALLBACK_CLAUDE_CODE_VERSION;
+}
+
+const claudeCodeVersion = detectClaudeCodeVersion();
+
+function textOf(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.filter(isTextBlock)
+		.map((block) => block.text)
+		.join("\n");
+}
+
+function firstUserText(messages: unknown): string {
+	const list = Array.isArray(messages) ? messages : [];
+	const firstUser = list.find((message) => isObject(message) && message.role === "user");
+	return isObject(firstUser) ? textOf(firstUser.content) : "";
+}
+
+function versionSuffix(messageText: string): string {
+	const explicit = process.env.PI_CLAUDE_CODE_VERSION_SUFFIX;
+	if (explicit) return explicit;
+
+	const sampled = [4, 7, 20].map((index) => messageText[index] ?? "0").join("");
+	return createHash("sha256")
+		.update(`${BILLING_SALT}${sampled}${claudeCodeVersion}`)
+		.digest("hex")
+		.slice(0, 3);
+}
+
+function buildBillingHeader(messages: unknown): string {
+	const version = `${claudeCodeVersion}.${versionSuffix(firstUserText(messages))}`;
+	const entrypoint =
+		process.env.PI_CLAUDE_CODE_ENTRYPOINT ?? process.env.CLAUDE_CODE_ENTRYPOINT ?? DEFAULT_ENTRYPOINT;
+	const workload = process.env.PI_CLAUDE_CODE_WORKLOAD ?? process.env.CLAUDE_CODE_WORKLOAD;
+	const workloadPart = workload ? ` cc_workload=${workload};` : "";
+	return `${BILLING_PREFIX} cc_version=${version}; cc_entrypoint=${entrypoint}; cch=00000;${workloadPart}`;
+}
+
+function log(details: Record<string, unknown>): void {
+	const logFile = process.env.PI_CLAUDE_OAUTH_LOG_FILE;
+	if (!logFile) return;
+
+	const path = resolve(logFile);
+	try {
+		mkdirSync(dirname(path), { recursive: true });
+		appendFileSync(path, `${JSON.stringify({ timestamp: new Date().toISOString(), ...details })}\n`, "utf8");
+	} catch {
+		// 调试日志是可选的。
+	}
+}
+
+export function registerClaudeSub(pi: ExtensionAPI): void {
+	pi.registerProvider("anthropic", {
+		headers: {
+			"user-agent": `claude-cli/${claudeCodeVersion} (external, cli)`,
+			"x-app": "cli",
+		},
+	});
+
+	pi.on("before_provider_request", (event, ctx) => {
+		const payload = event.payload;
+		if (!shouldApply(ctx) || !isObject(payload)) return;
+
+		const { system, messages } = payload as PayloadLike;
+		const blocks = Array.isArray(system) ? system : [];
+		if (blocks.some((block) => isTextBlock(block) && block.text.startsWith(BILLING_PREFIX))) return;
+
+		const header: TextBlock = { type: "text", text: buildBillingHeader(messages) };
+		log({ event: "billing_header_injected", header: header.text });
+		return { ...payload, system: [header, ...blocks] };
+	});
+}

package/provider/openai-native/index.ts

@@ -0,0 +1,8 @@
+/** OpenAI / Codex 请求层：verbosity、Fast（priority）、可选原生压缩。 */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { CONFIG_PATH, loadConfig } from "../../config.js";
+import openAINativeExtension from "./src/extension.ts";
+
+export function registerOpenAINative(pi: ExtensionAPI): void {
+	openAINativeExtension(pi, CONFIG_PATH, loadConfig().config.keys.fast);
+}