pi-volcengine-provider

Pi Coding Agent extension for Volcengine Coding Plan models.

What it adds

This package registers one Pi provider:

• volcengine-codingplan → https://ark.cn-beijing.volces.com/api/coding/v3

Primary model:

• ark-code-latest

Additional models:

• doubao-seed-2.0-code
• doubao-seed-code
• glm-4.7
• deepseek-v3.2
• kimi-k2.5
• minimax-m2.5

Install

Pi settings.json

{
  "packages": [
    "git:github.com/gistman/pi-volcengine-provider"
  ]
}

Reload Pi after updating settings.

Pi CLI

pi install git:github.com/gistman/pi-volcengine-provider

Local checkout

git clone https://github.com/gistman/pi-volcengine-provider.git
cd pi-volcengine-provider
npm install
npm run build
pi -e ./dist/index.js

Configure

API key resolution order (first match wins):

1. Pi auth storage (~/.pi/agent/auth.json)
2. Environment variable (VOLCENGINE_API_KEY)

Option 1: Pi auth storage (recommended)

Use Pi's built-in auth system:

pi auth add volcengine-codingplan <your-api-key>

To remove:

pi auth remove volcengine-codingplan

Option 2: Environment variable

export VOLCENGINE_API_KEY="your-api-key-here"

Volcengine console: https://console.volcengine.com/ark/

Use

Select the provider model in Pi:

/model volcengine-codingplan/ark-code-latest

You can also inspect available models with /model.

Programmatic API

import { registerVolcengine, getVolcengineApiKey } from "pi-volcengine-provider";

// Register with custom config
// Returns true if registered, false if no API key available (fail-closed)
const registered = await registerVolcengine(pi, {
  apiKey: "explicit-key",
  // or usePiAuthStorage: false to skip auth.json
});

if (!registered) {
  console.log("Provider not registered - no API key available");
}

// Get API key manually (checks auth.json then env)
const apiKey = await getVolcengineApiKey();

Fail-closed behavior: If no API key is available (via explicit config, Pi auth.json, or environment variable), the provider is NOT registered. This prevents accidental use with a missing or invalid key.

Behavior and limits

• Fail-closed auth: Provider is NOT registered if no API key is available
• Transport: custom volcengine-codingplan-openai-completions stream wrapper built on Pi's openai-completions
• Auth: Authorization: Bearer <key> (key from auth.json or VOLCENGINE_API_KEY)
• Thinking/reasoning control surface: use Pi's native thinking setting (off|minimal|low|medium|high|xhigh).
• The provider maps that Pi-native setting to Volcengine request fields:
  • Pi off -> thinking: { type: "disabled" } + reasoning_effort: "minimal"
  • Pi minimal -> thinking: { type: "enabled" } + reasoning_effort: "minimal"
  • Pi low|medium|high -> thinking: { type: "enabled" } + same reasoning_effort
  • Pi xhigh -> degraded/clamped to reasoning_effort: "high" with thinking: { type: "enabled" } (backend ceiling; not equivalent)
  • Guardrail: thinking.type="disabled" with reasoning_effort other than "minimal" throws
• supportsDeveloperRole is set conservatively to false
• supportsReasoningEffort is intentionally false in model metadata; mapping is handled by provider transport logic
• Non-primary models are marked isProvisional: true
• Cost fields are placeholders (0) until verified
• Capability metadata remains conservative where official behavior is not yet verified

Maintainers

Before publishing changes:

npm install
npm run typecheck
npm run test
npm run build

Keep claims conservative and implementation-aligned. If a capability is not verified, do not advertise it.

See research.md for design notes.

License

MIT