pi-model-manager 0.1.0

package/README.en.md

@@ -0,0 +1,206 @@
+# pi-model-manager
+
+English · [简体中文](./README.md)
+
+[![Pi](https://img.shields.io/badge/Pi-%3E%3D0.82.0-6f42c1)](https://github.com/earendil-works/pi)
+[![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](./LICENSE)
+[![Version](https://img.shields.io/badge/version-0.1.0-2f81f7.svg)](https://www.npmjs.com/package/pi-model-manager)
+
+A TUI model and provider manager for [Pi](https://github.com/earendil-works/pi). It keeps Pi's native `models.json` as the single source of truth for model configuration while adding provider/model editing, client-header identities, proxy routing, and protocol compatibility controls.
+
+> The current stable version is `0.1.0` and requires Pi `>=0.82.0`.
+
+## Interface preview
+
+![pi-model-manager interface overview](https://raw.githubusercontent.com/Qihuanxishini/pi-model-manager/main/assets/pi-model-manager-preview.png)
+
+<details>
+<summary>View all four full-size screenshots</summary>
+
+### Provider setup
+
+![Provider setup](https://raw.githubusercontent.com/Qihuanxishini/pi-model-manager/main/assets/screenshots/provider-setup.png)
+
+### Model discovery
+
+![Model discovery](https://raw.githubusercontent.com/Qihuanxishini/pi-model-manager/main/assets/screenshots/model-discovery.png)
+
+### Provider and model overview
+
+![Provider and model overview](https://raw.githubusercontent.com/Qihuanxishini/pi-model-manager/main/assets/screenshots/provider-models.png)
+
+### Model capabilities
+
+![Model capabilities](https://raw.githubusercontent.com/Qihuanxishini/pi-model-manager/main/assets/screenshots/model-editor.png)
+
+</details>
+## Features
+
+- Create, edit, and delete providers and models from the `/model-manager` TUI.
+- Supports `openai-completions`, `openai-responses`, `anthropic-messages`, and `google-generative-ai`.
+- Fetch model IDs from compatible upstream APIs or enter them manually.
+- Configure context window, maximum output, vision input, and reasoning support.
+- Choose Anthropic Adaptive Thinking or Legacy Thinking.
+- Enable `service_tier=priority` (Fast mode) per OpenAI Responses model.
+- Route each provider directly or through its own HTTP(S) proxy.
+- Use recommended, disabled, Claude Code, Codex, or custom client-header profiles.
+- Reference API keys as literals, `$ENV_VAR` / `${ENV_VAR}`, or Pi `!command` values.
+- Persist configuration atomically and re-register managed providers after saving.
+
+## Installation
+
+### Install from GitHub (recommended for now)
+
+```bash
+pi install git:github.com/Qihuanxishini/pi-model-manager
+```
+
+Try it for the current run without adding it to Pi's package settings:
+
+```bash
+pi -e git:github.com/Qihuanxishini/pi-model-manager
+```
+
+Update Git-installed extensions with:
+
+```bash
+pi update --extensions
+```
+
+### Install from npm
+
+`pi-model-manager` is published as a public npm package:
+
+```bash
+pi install npm:pi-model-manager
+```
+
+## Quick start
+
+1. Start the Pi TUI.
+2. Run:
+
+   ```text
+   /model-manager
+   ```
+
+3. Manage providers from the dashboard:
+
+   | Key | Action |
+   | --- | --- |
+   | `Enter` | Open the selected provider and manage its models |
+   | `n` | Create a provider and its first model |
+   | `d` | Delete the selected provider |
+   | `h` | Manage reusable header profiles |
+   | `Esc` | Go back or exit |
+
+4. In an editor, use the arrow keys to select a field and press `Enter` to edit it. Toggle supported fields with `←` / `→`, then press `Ctrl+S` to save.
+
+Saving updates and enables the model, but it does not force the current session to switch models.
+
+## Provider and model configuration
+
+Each provider can define:
+
+- API protocol and base URL
+- API key and authorization-header behavior
+- Client-header identity
+- Provider-specific HTTP(S) proxy
+- One or more models
+
+When adding a model, the extension attempts to fetch the upstream model list with a 10-second timeout. You can still enter a model ID manually if discovery fails.
+
+Model capabilities include:
+
+- Display name
+- Text or text-and-image input
+- Reasoning support
+- Anthropic Adaptive/Legacy Thinking
+- OpenAI Responses Fast mode
+- Context window and maximum output tokens
+
+## Client-header profiles
+
+| Profile | Behavior |
+| --- | --- |
+| Recommended | Claude Code for Anthropic Messages, Codex for OpenAI Completions/Responses, and no identity headers for other protocols |
+| Disabled | Adds no extension-managed client identity headers |
+| Claude Code | Uses the built-in Claude Code compatibility headers and adds required Anthropic request metadata |
+| Codex | Uses the built-in Codex TUI compatibility headers |
+| Custom | Uses a reusable JSON header set created in the header-profile panel |
+
+The current built-in values were derived from real client requests with authentication fields removed:
+
+- Claude Code `2.1.219`
+- Codex TUI `0.145.0`
+
+These headers only help API gateways that require a recognized client identity; they do not replace an API key. The public repository and npm package contain **no request-capture tooling, user captures, authentication headers, or machine-local state**. Disable identity headers or create a custom profile if a built-in profile does not fit your endpoint.
+
+Custom profiles reject authentication-related sensitive headers. Put authentication material in the provider's API-key setting instead.
+
+## Configuration files
+
+| Path | Purpose |
+| --- | --- |
+| `~/.pi/agent/models.json` | Native Pi provider and model definitions; the single source of truth for model configuration |
+| `~/.pi/agent/extensions/pi-model-manager/state.json` | Extension metadata such as header choices, custom profiles, proxy switches, and Fast mode |
+
+The extension preserves native `models.json` fields that are outside the TUI's editing scope whenever possible. Avoid modifying the same configuration file from multiple processes at once.
+
+## Secrets and security
+
+Pi extensions run with the current user's permissions and have full system access. Review the source before installing any third-party extension.
+
+Prefer environment-variable or command references over plaintext secrets in `models.json`:
+
+```text
+$OPENAI_API_KEY
+${ANTHROPIC_API_KEY}
+!your-secret-command
+```
+
+Additional considerations:
+
+- Custom client headers are not a credential store.
+- Enabling a provider proxy routes that provider's requests through the configured proxy URL.
+- Model discovery sends a network request to the configured upstream endpoint.
+- The repository ignores `state.json`, runtime logs, request captures, and other machine-specific files.
+
+## Compatibility
+
+| Component | Requirement |
+| --- | --- |
+| `@earendil-works/pi-coding-agent` | `>=0.82.0` |
+| `@earendil-works/pi-tui` | `>=0.75.0` |
+| Runtime mode | `/model-manager` requires the Pi TUI |
+
+The current TUI copy is Simplified Chinese.
+
+## Local development
+
+```bash
+git clone https://github.com/Qihuanxishini/pi-model-manager.git
+cd pi-model-manager
+npm install
+pi -e .
+```
+
+Pi loads the TypeScript entry point directly; no separate build step is required. Do not commit `state.json`, `bootstrap-meta.json`, `node_modules`, or request-capture data.
+
+Inspect the public package contents with:
+
+```bash
+npm pack --dry-run
+```
+
+## Reporting issues
+
+Open a reproducible report in [GitHub Issues](https://github.com/Qihuanxishini/pi-model-manager/issues). Remove API keys, authentication headers, proxy credentials, and private endpoints before sharing configuration or logs.
+
+## Acknowledgements
+
+Thanks to the [LINUX DO](https://linux.do/) community for discussion, sharing, and feedback.
+
+## License
+
+Official releases from `v0.1.0` onward are licensed under the [GNU Affero General Public License v3.0 only](./LICENSE). Modified distributions must provide the corresponding source, remain under AGPL-3.0, and identify their changes; they must not represent themselves as official releases. See [NOTICE](./NOTICE).

package/README.md

@@ -0,0 +1,210 @@
+# pi-model-manager
+
+[English](./README.en.md) · 简体中文
+
+[![Pi](https://img.shields.io/badge/Pi-%3E%3D0.82.0-6f42c1)](https://github.com/earendil-works/pi)
+[![License](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](./LICENSE)
+[![Version](https://img.shields.io/badge/version-0.1.0-2f81f7.svg)](https://www.npmjs.com/package/pi-model-manager)
+
+一个面向 [Pi](https://github.com/earendil-works/pi) 的 TUI 模型与接入管理扩展。它以 Pi 原生 `models.json` 为模型配置的唯一权威来源，并提供接入/模型编辑、请求头身份、代理路由和协议兼容配置。
+
+> 当前稳定版为 `0.1.0`，要求 Pi `>=0.82.0`。
+
+## 界面预览
+
+![pi-model-manager 界面总览](https://raw.githubusercontent.com/Qihuanxishini/pi-model-manager/main/assets/pi-model-manager-preview.png)
+
+<details>
+<summary>查看四张完整截图</summary>
+
+### 接入配置
+
+![接入配置](https://raw.githubusercontent.com/Qihuanxishini/pi-model-manager/main/assets/screenshots/provider-setup.png)
+
+### 模型发现
+
+![模型发现](https://raw.githubusercontent.com/Qihuanxishini/pi-model-manager/main/assets/screenshots/model-discovery.png)
+
+### 接入与模型总览
+
+![接入与模型总览](https://raw.githubusercontent.com/Qihuanxishini/pi-model-manager/main/assets/screenshots/provider-models.png)
+
+### 模型能力
+
+![模型能力](https://raw.githubusercontent.com/Qihuanxishini/pi-model-manager/main/assets/screenshots/model-editor.png)
+
+</details>
+## 功能
+
+- 在 `/model-manager` TUI 中新增、编辑和删除接入与模型。
+- 原生支持 `openai-completions`、`openai-responses`、`anthropic-messages` 和 `google-generative-ai`。
+- 从兼容上游拉取模型 ID，也可手动填写模型。
+- 配置上下文窗口、最大输出、视觉输入和 Thinking。
+- 支持 Anthropic Adaptive Thinking 与 Legacy Thinking。
+- 可为 OpenAI Responses 模型启用 `service_tier=priority`（Fast mode）。
+- 为每个接入单独配置直连或 HTTP(S) 代理。
+- 提供自动推荐、禁用、Claude Code、Codex 和自定义请求头模式。
+- API key 支持字面值、`$ENV_VAR` / `${ENV_VAR}` 和 Pi 的 `!command` 引用。
+- 原子写入配置，并在保存后重新注册受管理的 Provider，无需手工编辑多处分散状态。
+
+## 安装
+
+### 从 GitHub 安装（当前推荐）
+
+```bash
+pi install git:github.com/Qihuanxishini/pi-model-manager
+```
+
+也可以先临时试用，不写入 Pi 的包配置：
+
+```bash
+pi -e git:github.com/Qihuanxishini/pi-model-manager
+```
+
+更新 Git 安装的扩展：
+
+```bash
+pi update --extensions
+```
+
+### 从 npm 安装
+
+`pi-model-manager` 已发布为公开 npm 包：
+
+```bash
+pi install npm:pi-model-manager
+```
+
+## 快速开始
+
+1. 启动 Pi TUI。
+2. 执行：
+
+   ```text
+   /model-manager
+   ```
+
+3. 在主面板中管理接入：
+
+   | 按键 | 操作 |
+   | --- | --- |
+   | `Enter` | 进入所选接入并管理模型 |
+   | `n` | 新建接入及其第一个模型 |
+   | `d` | 删除所选接入 |
+   | `h` | 管理可复用请求头 |
+   | `Esc` | 返回或退出 |
+
+4. 在编辑器中使用方向键选择字段，按 `Enter` 编辑；支持切换的字段可用 `←` / `→` 调整；按 `Ctrl+S` 保存。
+
+保存会更新并启用模型，但不会强制切换当前会话正在使用的模型。
+
+## 配置模型
+
+### 接入配置
+
+每个接入可以配置：
+
+- API 协议与 Base URL
+- API key 与认证头行为
+- 请求头身份
+- 接入级 HTTP(S) 代理
+- 一个或多个模型
+
+新建模型时，扩展会尝试在 10 秒内从上游读取模型列表；失败后仍可手动输入模型 ID。
+
+### 模型能力
+
+模型编辑器支持：
+
+- 显示名称
+- 文本或文本+图像输入
+- Thinking 开关
+- Anthropic Adaptive/Legacy Thinking 协议
+- OpenAI Responses Fast mode
+- Context window 与最大输出 token
+
+## 请求头模式
+
+| 模式 | 行为 |
+| --- | --- |
+| 自动推荐 | Anthropic Messages 使用 Claude Code；OpenAI Completions/Responses 使用 Codex；其他协议不附加身份头 |
+| 不添加 | 不添加扩展管理的客户端身份请求头 |
+| Claude Code | 使用内置 Claude Code 兼容请求头，并为 Anthropic 请求补充必要的兼容 metadata |
+| Codex | 使用内置 Codex TUI 兼容请求头 |
+| 自定义 | 使用在请求头面板中创建的可复用 JSON 请求头集合 |
+
+当前内置值来自真实客户端请求并已移除认证信息：
+
+- Claude Code `2.1.219`
+- Codex TUI `0.145.0`
+
+这些值只用于兼容需要识别客户端身份的 API 中转，不代替 API key。公开仓库和 npm 包**不包含请求捕获工具、用户抓包、认证头或本机状态**。如果内置值不适合你的服务，请关闭身份头或创建自定义请求头。
+
+自定义请求头会拒绝认证类敏感字段；认证信息应放在接入的 API key 配置中。
+
+## 配置文件
+
+| 路径 | 用途 |
+| --- | --- |
+| `~/.pi/agent/models.json` | Pi 原生接入与模型定义；模型配置的唯一权威来源 |
+| `~/.pi/agent/extensions/pi-model-manager/state.json` | 请求头选择、自定义请求头、代理开关和 Fast mode 等扩展私有元数据 |
+
+扩展会尽量保留 `models.json` 中不由 TUI 编辑的原生字段。不要同时让多个进程修改同一配置文件。
+
+## 密钥与安全
+
+Pi 扩展以当前用户权限运行并拥有完整系统访问能力。安装任何第三方扩展前都应审阅源码。
+
+推荐通过环境变量或命令引用 API key，避免把密钥明文写入 `models.json`：
+
+```text
+$OPENAI_API_KEY
+${ANTHROPIC_API_KEY}
+!your-secret-command
+```
+
+其他注意事项：
+
+- 自定义请求头不是保存认证凭据的位置。
+- 启用接入代理后，该接入的请求会经过你填写的代理地址。
+- 拉取模型列表会向所配置的上游地址发起网络请求。
+- 仓库忽略 `state.json`、运行日志、请求捕获数据和其他机器专属文件。
+
+## 兼容性
+
+| 组件 | 要求 |
+| --- | --- |
+| `@earendil-works/pi-coding-agent` | `>=0.82.0` |
+| `@earendil-works/pi-tui` | `>=0.75.0` |
+| 运行模式 | `/model-manager` 需要 Pi TUI |
+
+当前 TUI 文案为简体中文。
+
+## 本地开发
+
+```bash
+git clone https://github.com/Qihuanxishini/pi-model-manager.git
+cd pi-model-manager
+npm install
+pi -e .
+```
+
+扩展由 Pi 直接加载 TypeScript 入口，不需要单独构建步骤。开发时请勿提交 `state.json`、`bootstrap-meta.json`、`node_modules` 或任何请求捕获数据。
+
+验证公开包内容：
+
+```bash
+npm pack --dry-run
+```
+
+## 问题反馈
+
+请通过 [GitHub Issues](https://github.com/Qihuanxishini/pi-model-manager/issues) 提交可复现的问题。报告配置问题时，请删除 API key、认证头、代理凭据和私有 endpoint。
+
+## 致谢
+
+感谢 [LINUX DO](https://linux.do/) 社区的讨论、分享和反馈。
+
+## 许可证
+
+`v0.1.0` 及后续官方版本采用 [GNU Affero General Public License v3.0 only](./LICENSE)。分发修改版本时必须公开对应源码、继续使用 AGPL-3.0，并明确标注改动；修改版不得冒充官方发行。详见 [NOTICE](./NOTICE)。

package/atomic-write.ts

@@ -0,0 +1,100 @@
+// Windows 友好的配置文件持久化写入。
+//
+// 目标文件可能被正在运行的 pi、编辑器、杀软或索引器短暂占用。
+// 直接 rename(tmp, target) 在 Windows 上会留下 tmp 且正式配置不变；这里统一
+// 处理重试、降级覆盖与失败时的可恢复临时文件提示。
+
+import { randomUUID } from "node:crypto";
+import { copyFile, mkdir, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+const REPLACE_RETRY_DELAYS_MS = [25, 50, 100, 200, 400, 800] as const;
+const TRANSIENT_REPLACE_ERROR_CODES = new Set(["EACCES", "EPERM", "EBUSY", "ENOTEMPTY"]);
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function getErrorCode(error: unknown): string | undefined {
+	return error instanceof Error && "code" in error
+		? String((error as NodeJS.ErrnoException).code)
+		: undefined;
+}
+
+function isTransientReplaceError(error: unknown): boolean {
+	const code = getErrorCode(error);
+	return code !== undefined && TRANSIENT_REPLACE_ERROR_CODES.has(code);
+}
+
+function formatError(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+async function removeTempFile(path: string): Promise<void> {
+	try {
+		await unlink(path);
+	} catch {
+		// 清理失败不应掩盖真实保存结果；失败场景会把 tmp 路径报告给用户用于恢复。
+	}
+}
+
+async function renameWithRetry(sourcePath: string, targetPath: string): Promise<void> {
+	let lastError: unknown;
+	for (let attempt = 0; attempt <= REPLACE_RETRY_DELAYS_MS.length; attempt += 1) {
+		try {
+			await rename(sourcePath, targetPath);
+			return;
+		} catch (error) {
+			lastError = error;
+			if (!isTransientReplaceError(error) || attempt === REPLACE_RETRY_DELAYS_MS.length) break;
+			await sleep(REPLACE_RETRY_DELAYS_MS[attempt]!);
+		}
+	}
+	throw lastError;
+}
+
+async function copyOverTargetWithRetry(sourcePath: string, targetPath: string): Promise<void> {
+	let lastError: unknown;
+	for (let attempt = 0; attempt <= REPLACE_RETRY_DELAYS_MS.length; attempt += 1) {
+		try {
+			await copyFile(sourcePath, targetPath);
+			await removeTempFile(sourcePath);
+			return;
+		} catch (error) {
+			lastError = error;
+			if (!isTransientReplaceError(error) || attempt === REPLACE_RETRY_DELAYS_MS.length) break;
+			await sleep(REPLACE_RETRY_DELAYS_MS[attempt]!);
+		}
+	}
+	throw lastError;
+}
+
+async function replaceTargetFile(sourcePath: string, targetPath: string): Promise<void> {
+	try {
+		await renameWithRetry(sourcePath, targetPath);
+	} catch (renameError) {
+		if (process.platform !== "win32" || !isTransientReplaceError(renameError)) throw renameError;
+		// [喵喵喵]: Windows 上 rename 覆盖会被短暂文件锁拦截；重试后降级 copyFile，避免配置保存停留在 tmp (2026-06-21)
+		try {
+			await copyOverTargetWithRetry(sourcePath, targetPath);
+		} catch (copyError) {
+			throw new Error(`rename 失败：${formatError(renameError)}；copy 覆盖也失败：${formatError(copyError)}`);
+		}
+	}
+}
+
+export async function atomicWriteText(targetPath: string, content: string): Promise<void> {
+	await mkdir(dirname(targetPath), { recursive: true });
+	const tempPath = `${targetPath}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
+	let tempHasCompleteContent = false;
+
+	try {
+		await writeFile(tempPath, content, "utf8");
+		tempHasCompleteContent = true;
+		await replaceTargetFile(tempPath, targetPath);
+	} catch (error) {
+		if (!tempHasCompleteContent) await removeTempFile(tempPath);
+		const recoveryNote = tempHasCompleteContent ? `；完整内容已保留在临时文件：${tempPath}` : "";
+		throw new Error(`写入 ${targetPath} 失败${recoveryNote}：${formatError(error)}`);
+	}
+}

package/builtin-model-catalog.ts

@@ -0,0 +1,92 @@
+// Pi 内置模型 catalog 边界。
+//
+// [喵喵喵]: Pi 0.80.8 移除 AuthStorage 且目录运行时异步化，必须隔离读取内置目录 (2026-07-17)
+// 仅为读取 Pi 内置目录创建运行时，不读取用户 auth.json/models.json，
+// 也不允许目录读取触发模型网络请求。
+
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import type { ApiKind } from "./types.ts";
+
+interface BuiltinProviderDefaults {
+	api?: ApiKind;
+	baseUrl?: string;
+}
+
+interface BuiltinCatalogModel {
+	provider: string;
+	api: string;
+	baseUrl: string;
+}
+
+const SUPPORTED_API_KINDS = new Set<ApiKind>([
+	"openai-completions",
+	"openai-responses",
+	"anthropic-messages",
+	"google-generative-ai",
+]);
+
+const emptyCredentialStore = {
+	async read(): Promise<undefined> {
+		return undefined;
+	},
+	async list(): Promise<readonly []> {
+		return [];
+	},
+	async modify(): Promise<undefined> {
+		return undefined;
+	},
+	async delete(): Promise<void> {
+		return undefined;
+	},
+};
+
+let builtinModelsPromise: Promise<readonly BuiltinCatalogModel[]> | undefined;
+let builtinProviderIdsPromise: Promise<ReadonlySet<string>> | undefined;
+
+function getBuiltinModels(): Promise<readonly BuiltinCatalogModel[]> {
+	builtinModelsPromise ??= ModelRuntime.create({
+		credentials: emptyCredentialStore,
+		modelsPath: null,
+		allowModelNetwork: false,
+	}).then((runtime) =>
+		runtime.getModels().map((model) => ({
+			provider: String(model.provider),
+			api: String(model.api),
+			baseUrl: model.baseUrl,
+		})),
+	);
+
+	return builtinModelsPromise;
+}
+
+export function getBuiltinProviderIds(): Promise<ReadonlySet<string>> {
+	builtinProviderIdsPromise ??= getBuiltinModels().then(
+		(models) => new Set(models.map((model) => model.provider)),
+	);
+
+	return builtinProviderIdsPromise;
+}
+
+export async function isBuiltinProviderId(providerId: string): Promise<boolean> {
+	return (await getBuiltinProviderIds()).has(providerId);
+}
+
+function asSupportedApiKind(value: string | undefined): ApiKind | undefined {
+	return value && SUPPORTED_API_KINDS.has(value as ApiKind)
+		? (value as ApiKind)
+		: undefined;
+}
+
+export async function getBuiltinProviderDefaults(
+	providerId: string,
+): Promise<BuiltinProviderDefaults | undefined> {
+	const firstModel = (await getBuiltinModels()).find(
+		(model) => model.provider === providerId,
+	);
+	if (!firstModel) return undefined;
+
+	return {
+		api: asSupportedApiKind(firstModel.api),
+		baseUrl: firstModel.baseUrl,
+	};
+}

package/claude-code-compat.ts

@@ -0,0 +1,56 @@
+// ClaudeCode 客户端兼容增强：让选择 ClaudeCode 请求头 profile 的 Anthropic 接入
+// 同时具备 Snow CLI/ClaudeCode 中转常见的 body metadata 信号。
+
+import { createHash, randomUUID } from "node:crypto";
+import { isObjectRecord } from "./common.ts";
+import { resolveClientHeaderProfile } from "./presets/client-headers.ts";
+import type { StateDocument } from "./types.ts";
+
+type ActiveModelRef = {
+	provider: string;
+	id: string;
+	api: string;
+};
+
+type PayloadRecord = Record<string, unknown>;
+
+let currentClaudeCodeUserId = createClaudeCodeUserId();
+
+function createClaudeCodeUserId(): string {
+	const sessionId = randomUUID();
+	const hash = createHash("sha256").update(`anthropic_user_${sessionId}`).digest("hex");
+	return `user_${hash}_account__session_${sessionId}`;
+}
+
+export function resetClaudeCodeMetadataSession(): void {
+	currentClaudeCodeUserId = createClaudeCodeUserId();
+}
+
+function isPayloadRecord(payload: unknown): payload is PayloadRecord {
+	return isObjectRecord(payload);
+}
+
+export function injectClaudeCodeMetadata(
+	payload: unknown,
+	model: ActiveModelRef | undefined,
+	state: StateDocument,
+): PayloadRecord | undefined {
+	if (!model || model.api !== "anthropic-messages") return undefined;
+	if (!isPayloadRecord(payload)) return undefined;
+	if (payload.model !== model.id) return undefined;
+
+	const provider = state.providers[model.provider];
+	if (!provider) return undefined;
+	if (resolveClientHeaderProfile(provider.clientHeaderProfile, "anthropic-messages") !== "claude-code") return undefined;
+
+	const metadata = isObjectRecord(payload.metadata) ? payload.metadata : {};
+	return {
+		...payload,
+		// ARN/new-api 的 ClaudeCode-only 限制会检查 body 信号；只补 metadata，
+		// 不改写 system prompt，避免降低 Pi 系统提示词优先级。
+		metadata: {
+			...metadata,
+			user_id: currentClaudeCodeUserId,
+		},
+	};
+}