@woyxiang/pi-provider-volcengine-agent-plan 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# pi-provider-volcengine-agent-plan
+
+## 0.3.0 (2026-01-13)
+
+### Minor Changes
+
+- Forked from `zhcsyncer/pi-extensions` as independent repository `@woyxiang/pi-provider-volcengine-agent-plan`.
+- Add GLM 5.3 to the Volcengine Agent Plan catalog as a Small-tier, text-only Responses model with a 1,024,000-token context window and 128,000 max output tokens. Official Z.ai/Zhipu and Agent Plan docs say thinking cannot be disabled and only `low`/`high`/`max` effort is supported, so the card exposes those Pi thinking levels and copies GLM 5.2's public API reference rates. Live Agent Plan Responses checks accepted OpenAI `reasoning.effort` at `low`/`high`/`max`, streamed output text, and a full tool-result follow-up round through Pi; `thinking.type: disabled` is rejected with `InvalidParameter`. This package does not rewrite the request to Zhipu `thinking.type`. The 1M context window and 128k max output were not live-tested at their limits.
+
+## 0.2.0
+
+### Minor Changes
+
+- Declare image input for the 9 vision-capable Agent Plan models (Doubao Seed 2.0 Mini/Lite/Evolving/Code/Pro, MiniMax M3, Kimi K2.6/K2.7 Code/K3). MiniMax M2.7, GLM 5.2, and DeepSeek V4 Flash/Pro remain text-only because the Agent Plan gateway does not expose a multimodal path for them.
+
+## 0.1.1
+
+### Patch Changes
+
+- Correct Agent Plan model metadata by reporting public API reference cost estimates and exposing only the thinking levels supported by Kimi K3.
+
+## 0.1.0
+
+### Minor Changes
+
+- Publish the standalone Volcengine Ark Agent Plan provider with native Pi login, tier-aware static models, mixed Responses and Chat routing, reasoning and tool compatibility hooks, and zero-inference API key validation.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 woyxiang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+# pi-provider-volcengine-agent-plan
+
+[简体中文](./README.zh-CN.md)
+
+Unofficial [Pi](https://github.com/badlogic/pi-mono) provider extension for Volcengine Ark Agent Plan at `https://ark.cn-beijing.volces.com/api/plan/v3`.
+
+This community package is not affiliated with or endorsed by Volcengine.
+
+## Features
+
+- Native Pi provider registration and `/login` integration.
+- Static catalog for the 11 current Agent Plan chat models.
+- Image input for the 7 vision-capable models; text-only routing for DeepSeek V4 Flash/Pro, GLM 5.3, and Doubao Seed 2.1 Turbo.
+- Tier-aware availability for Small, Medium, Large, and Max plans.
+- OpenAI Responses by default, with Chat Completions routing for Kimi K2.7 Code.
+- Streaming, reasoning, and tool-call support tested through the Agent Plan gateway.
+- Documented `reasoning.effort` compatibility mapping per model family; GLM 5.3 stays limited to `low`/`high`/`max`.
+- Zero-inference API key validation before Pi persists a login credential.
+
+## Requirements
+
+- Node.js 22.19 or newer.
+- Pi and `@earendil-works/pi-ai` 0.84.0 or newer.
+- A dedicated Ark Agent Plan API key. A regular Volcengine Ark API key does not work with the Plan endpoint.
+
+## Install
+
+```bash
+pi install npm:@woyxiang/pi-provider-volcengine-agent-plan
+```
+
+Restart Pi or run `/reload`, then verify the catalog:
+
+```bash
+pi --list-models volcengine-agent-plan
+```
+
+## Login and credentials
+
+### Interactive login
+
+Run:
+
+```text
+/login volcengine-agent-plan
+```
+
+Pi prompts for the dedicated Agent Plan API key and the subscribed tier. The login flow sends an authenticated, intentionally incomplete Responses request. A valid key reaches `MissingParameter`; an invalid or unauthorized key returns 401/403 and is requested again. This validation does not start model inference.
+
+Pi stores the API key and selected tier in its standard credential file, normally `~/.pi/agent/auth.json`. The package does not read a custom key file.
+
+### Environment variables
+
+Interactive login is recommended. Ambient credentials remain available for automated environments:
+
+```bash
+export ARK_AGENT_PLAN_API_KEY='...'
+export ARK_AGENT_PLAN_TIER='medium'
+```
+
+`VOLCENGINE_ARK_PLAN_API_KEY` is also accepted as an API key fallback. Supported tier values are `small`, `medium`, `large`, and `max`; the default is `medium` when no tier is configured.
+
+## Models and tiers
+
+The current catalog contains:
+
+- Doubao Seed 2.0 Mini, Lite, and Evolving
+- Doubao Seed 2.1 Turbo
+- DeepSeek V4 Flash and Pro
+- MiniMax M3
+- GLM 5.3 Flash and GLM 5.3
+- Kimi K2.7 Code and Kimi K3
+
+Small exposes 10 models. Kimi K3 currently requires Medium or higher. Medium, Large, and Max expose all 11 current models.
+
+## Compatibility
+
+Kimi K2.7 Code uses Chat Completions because its Agent Plan Responses tool-call path returned repeated server errors during compatibility testing. Other catalog entries use Responses.
+
+Kimi K2.7 Code does not support disabling thinking through the current gateway. Selecting Pi's `off` level therefore avoids sending an unsupported disable control but cannot guarantee that the model stops internal reasoning.
+
+Kimi K3 inherits only model-intrinsic capabilities from Pi's Moonshot catalog. Agent Plan continues to own its protocol, limits, compatibility settings, and plan rules. Its available Pi thinking levels are `low`, `high`, and `max`.
+
+Reasoning effort follows Volcengine's documented `reasoning.effort` compatibility mapping. Doubao Seed models close thinking for `none`/`minimal` and collapse `xhigh`/`max` to `high`; DeepSeek V4 Flash/Pro additionally collapse `medium` to `low`. Every model card keeps all seven Pi levels selectable and Pi sends the mapped effort value.
+
+GLM 5.3 cannot disable thinking. Official Z.ai/Zhipu docs only allow `low`, `high`, and `max` effort, so those are the Pi thinking levels this card exposes. Pi sends OpenAI `reasoning.effort` and does not rewrite the request to Zhipu `thinking.type`.
+
+GLM 5.3 Flash accepts all seven effort levels, but thinking cannot be fully disabled: `none` falls back to `low`, `medium`/`high` become `high`, and `xhigh`/`max` become `max`.
+
+## Cost reporting
+
+The catalog retains public pay-as-you-go API reference rates in USD per million tokens, allowing Pi to estimate session cost from actual token usage. Models with an existing Pi upstream card selectively inherit its rates; the Doubao models use API estimates normalized from [Volcengine's public price table](https://www.volcengine.com/docs/82379/1544106). Doubao Seed 2.1 Turbo has no published pay-as-you-go reference rate yet, so its cost is a zero placeholder and Pi reports no spend for it.
+
+This value compares session resource usage; it is not the Agent Plan bill. Volcengine still calculates the subscription price, AFP usage, and remaining quota separately.
+
+## Security
+
+Pi's standard `auth.json` is protected by filesystem permissions but is not an operating-system keychain. Do not commit credentials, paste them into issue reports, or place them in project configuration.
+
+The API key validation request never logs the key or response body. Temporary network or service failures let the user retry, cancel, or explicitly save without validation.
+
+## Development
+
+```bash
+pnpm check
+pi --no-extensions -e . --list-models volcengine-agent-plan
+npm pack --dry-run --json .
+```
+
+Unit tests use mocked credentials and fetch responses. Real-key contract tests are intentionally excluded from normal CI.
+
+## Limitations
+
+Agent Plan does not expose a usable `/models` endpoint, so the catalog and model metadata are versioned statically. Volcengine may change aliases, protocol behavior, limits, or tier availability before this package is updated.
+
+The catalog declares image input for the 7 vision-capable models (Doubao Seed 2.0 Mini/Lite/Evolving, MiniMax M3, Kimi K2.7 Code/K3, and GLM 5.3 Flash). DeepSeek V4 Flash/Pro, GLM 5.3, and Doubao Seed 2.1 Turbo remain text-only. Extreme context windows, maximum-length output, concurrency, rate limits, and subscription quota reporting are not covered.
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,120 @@
+# pi-provider-volcengine-agent-plan
+
+[English](./README.md)
+
+用于火山方舟 Agent Plan `https://ark.cn-beijing.volces.com/api/plan/v3` 的非官方 [Pi](https://github.com/badlogic/pi-mono) provider 扩展。
+
+这是社区包，与火山引擎无隶属关系，也未获得火山引擎官方背书。
+
+## 功能
+
+- 原生注册 Pi provider，并集成 `/login`。
+- 静态维护当前 11 个 Agent Plan 文本生成模型。
+- 7 个支持视觉的模型可接收图片输入；DeepSeek V4 Flash/Pro、GLM 5.3、Doubao Seed 2.1 Turbo 仅文本。
+- 按 Small、Medium、Large 和 Max 套餐过滤可用模型。
+- 默认使用 OpenAI Responses；Kimi K2.7 Code 路由到 Chat Completions。
+- 已通过 Agent Plan 网关验证流式、reasoning 和工具调用。
+- 按模型族遵循官方 `reasoning.effort` 兼容映射；GLM 5.3 仍仅 `low`/`high`/`max`。
+- Pi 持久化登录凭证前执行零推理 API Key 校验。
+
+## 要求
+
+- Node.js 22.19 或更高版本。
+- Pi 和 `@earendil-works/pi-ai` 0.84.0 或更新版本。
+- Agent Plan 专属 API Key。普通火山方舟 API Key 不能用于 Plan 端点。
+
+## 安装
+
+```bash
+pi install npm:@woyxiang/pi-provider-volcengine-agent-plan
+```
+
+重启 Pi 或执行 `/reload`，然后检查模型目录：
+
+```bash
+pi --list-models volcengine-agent-plan
+```
+
+## 登录与凭证
+
+### 交互登录
+
+执行：
+
+```text
+/login volcengine-agent-plan
+```
+
+Pi 会提示输入 Agent Plan 专属 API Key 和已订阅套餐。登录流程会发送一个已鉴权但故意缺少参数的 Responses 请求：有效 Key 会到达 `MissingParameter`，无效或无权限的 Key 返回 401/403，并提示重新输入。该校验不会启动模型推理。
+
+Pi 将 API Key 和套餐保存到标准凭证文件，通常为 `~/.pi/agent/auth.json`。本包不会读取自定义 Key 文件。
+
+### 环境变量
+
+推荐使用交互登录。自动化环境也可以提供环境凭证：
+
+```bash
+export ARK_AGENT_PLAN_API_KEY='...'
+export ARK_AGENT_PLAN_TIER='medium'
+```
+
+也支持使用 `VOLCENGINE_ARK_PLAN_API_KEY` 作为 API Key fallback。套餐可取 `small`、`medium`、`large` 或 `max`；未配置套餐时默认使用 `medium`。
+
+## 模型与套餐
+
+当前目录包含：
+
+- Doubao Seed 2.0 Mini、Lite 和 Evolving
+- Doubao Seed 2.1 Turbo
+- DeepSeek V4 Flash 和 Pro
+- MiniMax M3
+- GLM 5.3 Flash 和 GLM 5.3
+- Kimi K2.7 Code 和 Kimi K3
+
+Small 展示 10 个模型。Kimi K3 当前要求 Medium 或更高套餐。Medium、Large 和 Max 展示当前全部 11 个模型。
+
+## 兼容性
+
+Kimi K2.7 Code 使用 Chat Completions，因为兼容性测试中它通过 Agent Plan Responses 执行工具调用会重复返回服务端错误。其余目录模型使用 Responses。
+
+当前网关不支持关闭 Kimi K2.7 Code 的 thinking。Pi 选择 `off` 时，本包不会发送不受支持的禁用参数，但无法保证模型停止内部推理。
+
+Kimi K3 只从 Pi 的 Moonshot 模型目录继承模型固有能力，并继续使用 Agent Plan 自己的协议、限额、兼容配置和套餐规则。Pi 中可选的 thinking 档位为 `low`、`high` 和 `max`。
+
+reasoning effort 遵循火山官方 `reasoning.effort` 兼容映射。Doubao Seed 模型传入 `none`/`minimal` 会关闭思考，`xhigh`/`max` 折叠为 `high`；DeepSeek V4 Flash/Pro 的 `medium` 还会折叠为 `low`。每个模型卡都保留 Pi 全部 7 个档位，Pi 发送映射后的 effort 值。
+
+GLM 5.3 不能关闭 thinking。智谱 / Z.ai 官方只允许 `low`、`high`、`max` 三档 effort，因此本卡只向 Pi 暴露这些档位。Pi 发送 OpenAI `reasoning.effort`，不会改写成智谱 `thinking.type`。
+
+GLM 5.3 Flash 接受全部 7 个 effort 档位，但无法完全关闭思考：`none` 会回退为 `low`，`medium`/`high` 变成 `high`，`xhigh`/`max` 变成 `max`。
+
+## 费用显示
+
+模型目录保留公共按量 API 的美元/百万 token 参考单价，因此 Pi 会根据实际 token usage 在 session 级估算费用。已有 Pi 上游模型卡的模型选择性继承其价格；Doubao 模型使用从[火山方舟公开价格表](https://www.volcengine.com/docs/82379/1544106)标准化得到的 API 估价。Doubao Seed 2.1 Turbo 暂无公开按量参考价，其价格为 0 占位，Pi 不会为其估算费用。
+
+这个数值用于比较会话资源消耗，并不是 Agent Plan 的实际账单；套餐价格、AFP 消耗和剩余额度仍由火山方舟单独计算。
+
+## 安全
+
+Pi 标准 `auth.json` 由文件系统权限保护，但不是操作系统 Keychain。请勿提交凭证、将凭证粘贴到 issue，或把凭证写入项目配置。
+
+API Key 校验请求不会记录 Key 或响应正文。遇到临时网络或服务错误时，用户可以重试、取消，或明确选择未经验证仍然保存。
+
+## 开发
+
+```bash
+pnpm check
+pi --no-extensions -e . --list-models volcengine-agent-plan
+npm pack --dry-run --json .
+```
+
+单元测试使用模拟凭证和 fetch 响应。需要真实 Key 的契约测试不会进入普通 CI。
+
+## 限制
+
+Agent Plan 没有可用的 `/models` 端点，因此模型目录和元数据采用静态版本维护。火山引擎可能在本包更新前修改别名、协议行为、限制或套餐权限。
+
+目录为 7 个支持视觉的模型（Doubao Seed 2.0 Mini/Lite/Evolving、MiniMax M3、Kimi K2.7 Code/K3、GLM 5.3 Flash）声明图片输入；DeepSeek V4 Flash/Pro、GLM 5.3、Doubao Seed 2.1 Turbo 仍仅文本。极限上下文、最大长度输出、并发、限流和套餐余量展示不在当前覆盖范围内。
+
+## 许可证
+
+MIT

package/index.ts

@@ -0,0 +1,552 @@
+import {
+	createProvider,
+	openAICompletionsApi,
+	openAIResponsesApi,
+	type ApiKeyCredential,
+	type AuthContext,
+	type AuthInteraction,
+	type Credential,
+	type Model,
+	type ThinkingLevelMap,
+} from "@earendil-works/pi-ai";
+import { getBuiltinModel } from "@earendil-works/pi-ai/providers/all";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const PROVIDER_ID = "volcengine-agent-plan";
+const BASE_URL = "https://ark.cn-beijing.volces.com/api/plan/v3";
+const TIER_ENV = "ARK_AGENT_PLAN_TIER";
+const KEY_ENV_NAMES = ["ARK_AGENT_PLAN_API_KEY", "VOLCENGINE_ARK_PLAN_API_KEY"] as const;
+const KEY_VALIDATION_URL = `${BASE_URL}/responses`;
+const KEY_VALIDATION_TIMEOUT_MS = 12_000;
+
+const RESPONSES_COMPAT = {
+	supportsDeveloperRole: true,
+	supportsLongCacheRetention: true,
+};
+
+const KIMI_CHAT_COMPAT = {
+	supportsDeveloperRole: false,
+	supportsReasoningEffort: true,
+	supportsStore: true,
+	supportsUsageInStreaming: true,
+	supportsLongCacheRetention: false,
+	maxTokensField: "max_completion_tokens" as const,
+	requiresReasoningContentOnAssistantMessages: true,
+};
+
+type ArkApi = "openai-responses" | "openai-completions";
+type PlanTier = "small" | "medium" | "large" | "max";
+
+type CatalogEntry = Omit<Model<ArkApi>, "provider" | "baseUrl"> & {
+	minimumTier: PlanTier;
+};
+
+type EstimatedApiCost = Model<ArkApi>["cost"];
+
+type InheritedModelCapabilities = Pick<
+	Model<ArkApi>,
+	"name" | "reasoning" | "thinkingLevelMap" | "input" | "cost" | "contextWindow" | "maxTokens"
+>;
+
+type RouteCapabilityLimits = Pick<Model<ArkApi>, "input" | "contextWindow" | "maxTokens">;
+
+function copyEstimatedApiCost(cost: EstimatedApiCost): EstimatedApiCost {
+	return {
+		...cost,
+		...(cost.tiers ? { tiers: cost.tiers.map((tier) => ({ ...tier })) } : {}),
+	};
+}
+
+function inheritModelCapabilities(
+	upstream: InheritedModelCapabilities,
+	routeLimits: RouteCapabilityLimits,
+): InheritedModelCapabilities {
+	return {
+		name: upstream.name,
+		reasoning: upstream.reasoning,
+		...(upstream.thinkingLevelMap
+			? { thinkingLevelMap: { ...upstream.thinkingLevelMap } }
+			: {}),
+		input: upstream.input.filter((modality) => routeLimits.input.includes(modality)),
+		cost: copyEstimatedApiCost(upstream.cost),
+		contextWindow: Math.min(upstream.contextWindow, routeLimits.contextWindow),
+		maxTokens: Math.min(upstream.maxTokens, routeLimits.maxTokens),
+	};
+}
+
+// Pi has no native Doubao Seed catalog yet. These USD-per-million-token
+// estimates follow public API listings normalized from Volcengine's price table.
+// Doubao Seed 2.1 Turbo has no published pay-as-you-go reference rate yet, so its
+// cost stays a zero placeholder and Pi does not estimate spend for it.
+const DOUBAO_API_COSTS = {
+	"doubao-seed-2.0-mini": { input: 0.03, output: 0.28, cacheRead: 0.01, cacheWrite: 0.0024 },
+	"doubao-seed-2.0-lite": { input: 0.09, output: 0.51, cacheRead: 0.02, cacheWrite: 0.0024 },
+	"doubao-seed-evolving": { input: 0.9, output: 4.5, cacheRead: 0.18, cacheWrite: 0 },
+	"doubao-seed-2.1-turbo": { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+} satisfies Record<string, EstimatedApiCost>;
+
+// Volcengine's reasoning_effort compatibility mapping (official docs). Every model
+// below accepts all seven levels; some values auto-map to an equivalent level.
+// Doubao Seed family: `none`/`minimal` close thinking, `xhigh`/`max` collapse to `high`.
+const DOUBAO_EFFORT_MAP = {
+	off: "none",
+	minimal: "minimal",
+	low: "low",
+	medium: "medium",
+	high: "high",
+	xhigh: "high",
+	max: "high",
+} satisfies ThinkingLevelMap;
+
+// DeepSeek V4 GA family: `none`/`minimal` close thinking, `medium` collapses to `low`,
+// `xhigh`/`max` collapse to `high`.
+const DEEPSEEK_GA_EFFORT_MAP = {
+	off: "none",
+	minimal: "minimal",
+	low: "low",
+	medium: "low",
+	high: "high",
+	xhigh: "high",
+	max: "high",
+} satisfies ThinkingLevelMap;
+
+// GLM 5.3 Flash accepts every level; thinking cannot be fully disabled and `none`
+// falls back to `low`. `medium`/`high` become `high`, `xhigh`/`max` become `max`.
+const GLM_53_FLASH_EFFORT_MAP = {
+	off: "none",
+	minimal: "low",
+	low: "low",
+	medium: "high",
+	high: "high",
+	xhigh: "max",
+	max: "max",
+} satisfies ThinkingLevelMap;
+
+// Only model capabilities and reference API pricing are inherited. Agent Plan
+// continues to own protocol, endpoint, compatibility, tier gating, and route limits.
+const KIMI_K3_CAPABILITIES = inheritModelCapabilities(getBuiltinModel("moonshotai", "kimi-k3"), {
+	input: ["text", "image"],
+	contextWindow: 1_024_000,
+	maxTokens: 128_000,
+});
+
+const TIER_RANK: Record<PlanTier, number> = {
+	small: 0,
+	medium: 1,
+	large: 2,
+	max: 3,
+};
+
+const CATALOG: CatalogEntry[] = [
+	{
+		id: "doubao-seed-2.0-mini",
+		name: "Doubao Seed 2.0 Mini",
+		api: "openai-responses",
+		minimumTier: "small",
+		reasoning: true,
+		thinkingLevelMap: DOUBAO_EFFORT_MAP,
+		input: ["text", "image"],
+		contextWindow: 256_000,
+		maxTokens: 128_000,
+		cost: copyEstimatedApiCost(DOUBAO_API_COSTS["doubao-seed-2.0-mini"]),
+		compat: RESPONSES_COMPAT,
+	},
+	{
+		id: "doubao-seed-2.0-lite",
+		name: "Doubao Seed 2.0 Lite",
+		api: "openai-responses",
+		minimumTier: "small",
+		reasoning: true,
+		thinkingLevelMap: DOUBAO_EFFORT_MAP,
+		input: ["text", "image"],
+		contextWindow: 256_000,
+		maxTokens: 128_000,
+		cost: copyEstimatedApiCost(DOUBAO_API_COSTS["doubao-seed-2.0-lite"]),
+		compat: RESPONSES_COMPAT,
+	},
+	{
+		id: "deepseek-v4-flash",
+		name: "DeepSeek V4 Flash",
+		api: "openai-responses",
+		minimumTier: "small",
+		reasoning: true,
+		thinkingLevelMap: DEEPSEEK_GA_EFFORT_MAP,
+		input: ["text"],
+		contextWindow: 1_024_000,
+		maxTokens: 384_000,
+		cost: copyEstimatedApiCost(getBuiltinModel("deepseek", "deepseek-v4-flash").cost),
+		compat: RESPONSES_COMPAT,
+	},
+	{
+		id: "doubao-seed-evolving",
+		name: "Doubao Seed Evolving",
+		api: "openai-responses",
+		minimumTier: "small",
+		reasoning: true,
+		thinkingLevelMap: DOUBAO_EFFORT_MAP,
+		input: ["text", "image"],
+		contextWindow: 1_024_000,
+		maxTokens: 256_000,
+		cost: copyEstimatedApiCost(DOUBAO_API_COSTS["doubao-seed-evolving"]),
+		compat: RESPONSES_COMPAT,
+	},
+	{
+		id: "doubao-seed-2.1-turbo",
+		name: "Doubao Seed 2.1 Turbo",
+		api: "openai-responses",
+		minimumTier: "small",
+		reasoning: true,
+		thinkingLevelMap: DOUBAO_EFFORT_MAP,
+		input: ["text"],
+		contextWindow: 256_000,
+		maxTokens: 256_000,
+		cost: copyEstimatedApiCost(DOUBAO_API_COSTS["doubao-seed-2.1-turbo"]),
+		compat: RESPONSES_COMPAT,
+	},
+	{
+		id: "minimax-m3",
+		name: "MiniMax M3",
+		api: "openai-responses",
+		minimumTier: "small",
+		reasoning: true,
+		input: ["text", "image"],
+		contextWindow: 1_024_000,
+		maxTokens: 128_000,
+		cost: copyEstimatedApiCost(getBuiltinModel("minimax", "MiniMax-M3").cost),
+		compat: RESPONSES_COMPAT,
+	},
+	{
+		id: "glm-5.3-flash",
+		name: "GLM 5.3 Flash",
+		api: "openai-responses",
+		minimumTier: "small",
+		reasoning: true,
+		thinkingLevelMap: GLM_53_FLASH_EFFORT_MAP,
+		input: ["text", "image"],
+		contextWindow: 1_024_000,
+		maxTokens: 128_000,
+		cost: copyEstimatedApiCost(getBuiltinModel("opencode-go", "glm-5.2").cost),
+		compat: RESPONSES_COMPAT,
+	},
+	{
+		id: "glm-5.3",
+		name: "GLM 5.3",
+		api: "openai-responses",
+		minimumTier: "small",
+		reasoning: true,
+		thinkingLevelMap: {
+			off: null,
+			minimal: null,
+			low: "low",
+			medium: null,
+			high: "high",
+			xhigh: null,
+			max: "max",
+		},
+		input: ["text"],
+		contextWindow: 1_024_000,
+		maxTokens: 128_000,
+		cost: copyEstimatedApiCost(getBuiltinModel("opencode-go", "glm-5.2").cost),
+		compat: RESPONSES_COMPAT,
+	},
+	{
+		id: "kimi-k2.7-code",
+		name: "Kimi K2.7 Code",
+		api: "openai-completions",
+		minimumTier: "small",
+		reasoning: true,
+		thinkingLevelMap: { off: null },
+		input: ["text", "image"],
+		contextWindow: 256_000,
+		maxTokens: 32_000,
+		cost: copyEstimatedApiCost(getBuiltinModel("moonshotai", "kimi-k2.7-code").cost),
+		compat: KIMI_CHAT_COMPAT,
+	},
+	{
+		id: "deepseek-v4-pro",
+		name: "DeepSeek V4 Pro",
+		api: "openai-responses",
+		minimumTier: "small",
+		reasoning: true,
+		thinkingLevelMap: DEEPSEEK_GA_EFFORT_MAP,
+		input: ["text"],
+		contextWindow: 1_024_000,
+		maxTokens: 384_000,
+		cost: copyEstimatedApiCost(getBuiltinModel("deepseek", "deepseek-v4-pro").cost),
+		compat: RESPONSES_COMPAT,
+	},
+	{
+		id: "kimi-k3",
+		...KIMI_K3_CAPABILITIES,
+		api: "openai-responses",
+		minimumTier: "medium",
+		compat: RESPONSES_COMPAT,
+	},
+];
+
+const MINIMUM_TIER = new Map(CATALOG.map((model) => [model.id, model.minimumTier]));
+const MODELS: Model<ArkApi>[] = CATALOG.map(({ minimumTier: _minimumTier, ...model }) => ({
+	...model,
+	provider: PROVIDER_ID,
+	baseUrl: BASE_URL,
+}));
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+type KeyValidationResult =
+	| { status: "valid" }
+	| { status: "invalid" }
+	| { status: "unavailable"; reason: string };
+
+interface KeyValidationOptions {
+	fetchImpl?: typeof fetch;
+	signal?: AbortSignal;
+	timeoutMs?: number;
+}
+
+async function responseErrorCode(response: Response): Promise<string | undefined> {
+	try {
+		const payload: unknown = await response.json();
+		if (!isRecord(payload)) return undefined;
+		const error = payload.error;
+		if (isRecord(error) && typeof error.code === "string") return error.code;
+		return typeof payload.code === "string" ? payload.code : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export async function validateAgentPlanKey(
+	key: string,
+	options: KeyValidationOptions = {},
+): Promise<KeyValidationResult> {
+	const fetchImpl = options.fetchImpl ?? fetch;
+	const controller = new AbortController();
+	let timedOut = false;
+	const timeout = setTimeout(() => {
+		timedOut = true;
+		controller.abort();
+	}, options.timeoutMs ?? KEY_VALIDATION_TIMEOUT_MS);
+	const abortFromLogin = () => controller.abort(options.signal?.reason);
+	if (options.signal?.aborted) abortFromLogin();
+	else options.signal?.addEventListener("abort", abortFromLogin, { once: true });
+
+	try {
+		// An authenticated empty request is rejected as MissingParameter before any
+		// model inference. Invalid credentials fail earlier with 401/403, allowing
+		// login validation without consuming Agent Plan tokens.
+		const response = await fetchImpl(KEY_VALIDATION_URL, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${key}`,
+				"Content-Type": "application/json",
+			},
+			body: "{}",
+			signal: controller.signal,
+		});
+		const errorCode = await responseErrorCode(response);
+
+		if (response.status === 401 || response.status === 403) return { status: "invalid" };
+		if (response.ok || (response.status === 400 && errorCode === "MissingParameter")) {
+			return { status: "valid" };
+		}
+		return {
+			status: "unavailable",
+			reason: `HTTP ${response.status}${errorCode ? ` (${errorCode})` : ""}`,
+		};
+	} catch (error) {
+		if (options.signal?.aborted) {
+			throw options.signal.reason instanceof Error
+				? options.signal.reason
+				: new Error("Agent Plan 登录已取消");
+		}
+		return {
+			status: "unavailable",
+			reason: timedOut
+				? "请求超时"
+				: error instanceof Error
+					? error.message
+					: "未知网络错误",
+		};
+	} finally {
+		clearTimeout(timeout);
+		options.signal?.removeEventListener("abort", abortFromLogin);
+	}
+}
+
+async function promptValidatedAgentPlanKey(
+	interaction: AuthInteraction,
+	fetchImpl: typeof fetch,
+): Promise<string> {
+	keyPrompt: while (true) {
+		const key = (
+			await interaction.prompt({
+				type: "secret",
+				message: "Agent Plan API Key",
+				placeholder: "输入后将安全保存到 Pi auth.json",
+			})
+		).trim();
+		if (!key) throw new Error("Agent Plan API Key 不能为空");
+
+		while (true) {
+			interaction.notify({ type: "progress", message: "正在验证 Agent Plan API Key…" });
+			const result = await validateAgentPlanKey(key, {
+				fetchImpl,
+				signal: interaction.signal,
+			});
+			if (result.status === "valid") {
+				interaction.notify({ type: "info", message: "Agent Plan API Key 验证通过。" });
+				return key;
+			}
+			if (result.status === "invalid") {
+				interaction.notify({
+					type: "info",
+					message: "API Key 无效或无权访问 Agent Plan，请重新输入。",
+				});
+				continue keyPrompt;
+			}
+
+			const action = await interaction.prompt({
+				type: "select",
+				message: `暂时无法验证 API Key：${result.reason}`,
+				options: [
+					{ id: "retry", label: "重试", description: "再次连接 Agent Plan 验证" },
+					{ id: "save", label: "仍然保存", description: "跳过验证并在首次请求时确认" },
+				],
+			});
+			if (action === "retry") continue;
+			return key;
+		}
+	}
+}
+
+function parsePlanTier(value: unknown): PlanTier | undefined {
+	if (typeof value !== "string") return undefined;
+	const normalized = value.trim().toLowerCase();
+	return normalized === "small" || normalized === "medium" || normalized === "large" || normalized === "max"
+		? normalized
+		: undefined;
+}
+
+function processPlanTier(): PlanTier {
+	return parsePlanTier(process.env[TIER_ENV]) ?? "medium";
+}
+
+function credentialPlanTier(credential: Credential | undefined): PlanTier {
+	if (credential?.type === "api_key") {
+		const stored = parsePlanTier(credential.env?.[TIER_ENV]);
+		if (stored) return stored;
+	}
+	return processPlanTier();
+}
+
+interface ResolvedKey {
+	key: string;
+	source: string;
+}
+
+async function resolveKey(ctx: AuthContext, credential?: ApiKeyCredential): Promise<ResolvedKey | undefined> {
+	const stored = credential?.key?.trim();
+	if (stored) return { key: stored, source: "Pi auth.json" };
+
+	for (const variable of KEY_ENV_NAMES) {
+		const value = (await ctx.env(variable))?.trim();
+		if (value) return { key: value, source: variable };
+	}
+
+	return undefined;
+}
+
+async function resolveTier(ctx: AuthContext, credential?: ApiKeyCredential): Promise<PlanTier> {
+	return (
+		parsePlanTier(credential?.env?.[TIER_ENV]) ??
+		parsePlanTier(await ctx.env(TIER_ENV)) ??
+		"medium"
+	);
+}
+
+function filterModelsByTier(models: readonly Model<ArkApi>[], tier: PlanTier): readonly Model<ArkApi>[] {
+	return models.filter((model) => {
+		const minimum = MINIMUM_TIER.get(model.id) ?? "small";
+		return TIER_RANK[tier] >= TIER_RANK[minimum];
+	});
+}
+
+export interface AgentPlanProviderOptions {
+	fetchImpl?: typeof fetch;
+}
+
+export function createAgentPlanProvider(options: AgentPlanProviderOptions = {}) {
+	return createProvider<ArkApi>({
+		id: PROVIDER_ID,
+		name: "Volcengine Ark Agent Plan",
+		baseUrl: BASE_URL,
+		auth: {
+			apiKey: {
+				name: "Ark Agent Plan API key",
+				async login(interaction) {
+					interaction.notify({
+						type: "info",
+						message: "请使用 Agent Plan 专属 API Key；普通方舟 API Key 不适用于该端点。",
+					});
+					const key = await promptValidatedAgentPlanKey(
+						interaction,
+						options.fetchImpl ?? fetch,
+					);
+
+					const tier = parsePlanTier(
+						await interaction.prompt({
+							type: "select",
+							message: "选择 Agent Plan 订阅级别",
+							options: [
+								{ id: "small", label: "Small", description: "隐藏 Medium 起可用的 Kimi K3" },
+								{ id: "medium", label: "Medium", description: "当前套餐；显示全部文本模型" },
+								{ id: "large", label: "Large", description: "显示全部文本模型" },
+								{ id: "max", label: "Max", description: "显示全部文本模型" },
+							],
+						}),
+					);
+					if (!tier) throw new Error("无效的 Agent Plan 订阅级别");
+
+					interaction.notify({
+						type: "progress",
+						message: "正在保存凭证并刷新 provider 状态，请稍候…",
+					});
+					return {
+						type: "api_key",
+						key,
+						env: { [TIER_ENV]: tier },
+					};
+				},
+				async check({ ctx, credential }) {
+					const resolved = await resolveKey(ctx, credential);
+					return resolved ? { type: "api_key", source: resolved.source } : undefined;
+				},
+				async resolve({ ctx, credential }) {
+					const resolved = await resolveKey(ctx, credential);
+					if (!resolved) return undefined;
+					const tier = await resolveTier(ctx, credential);
+					return {
+						auth: { apiKey: resolved.key },
+						env: { [TIER_ENV]: tier },
+						source: resolved.source,
+					};
+				},
+			},
+		},
+		models: MODELS,
+		filterModels(models, credential) {
+			return filterModelsByTier(models, credentialPlanTier(credential));
+		},
+		api: {
+			"openai-responses": openAIResponsesApi(),
+			"openai-completions": openAICompletionsApi(),
+		},
+	});
+}
+
+export default function volcengineAgentPlan(pi: ExtensionAPI) {
+	pi.registerProvider(createAgentPlanProvider());
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@woyxiang/pi-provider-volcengine-agent-plan",
+  "version": "0.3.0",
+  "description": "Unofficial Pi provider extension for Volcengine Ark Agent Plan.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-provider",
+    "volcengine",
+    "ark",
+    "agent-plan"
+  ],
+  "author": "woyxiang",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/woyxiang/pi-provider-volcengine-agent-plan.git"
+  },
+  "homepage": "https://github.com/woyxiang/pi-provider-volcengine-agent-plan#readme",
+  "bugs": {
+    "url": "https://github.com/woyxiang/pi-provider-volcengine-agent-plan/issues"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "index.ts",
+    "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.84.0",
+    "@earendil-works/pi-coding-agent": "0.84.0",
+    "@types/node": "25.6.0",
+    "jiti": "2.7.0",
+    "tsx": "4.22.4",
+    "typescript": "6.0.3"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "tsx --test \"test/**/*.test.ts\"",
+    "check": "pnpm typecheck && pnpm test"
+  }
+}