pi-sub2api-provider

A standalone pi package that reads OpenAI-compatible / sub2api provider config from ~/.pi/agent/models.json and ~/.pi/agent/auth.json, registers providers, and shows quota usage in the pi status bar and via the /quota command.

Part of the pi-extensions monorepo.

中文文档

Features

• Scans providers in ~/.pi/agent/models.json.
• Reads the matching key or access from ~/.pi/agent/auth.json.
• Auto-detects the usage endpoint:
  • ${baseUrl}/usage
  • ${root}/v1/usage
• Fetches and caches rate limit / daily usage.
• Pulls ${baseUrl}/models and prefers the remote model list, falling back to locally configured models only when the remote endpoint is unavailable.
• Reads remote model limit metadata when present (context_window, max_tokens, and common aliases), with conservative built-in fallbacks for endpoints that only return id / display_name.
• Registers providers via pi.registerProvider().
• Refreshes / displays quota on session_start, model_select, and turn_end.
• Registers a /quota command that shows detailed billing and quota for the current provider.

Installation

Option 1: From npm (recommended)

pi install npm:pi-sub2api-provider

Or add it to ~/.pi/agent/settings.json:

{
  "packages": ["npm:pi-sub2api-provider"]
}

Option 2: From git

pi install git:github.com/dereknex/pi-extensions

Option 3: As a local package

pi install ./packages/pi-sub2api-provider

Option 4: Load temporarily for testing

pi -e /Users/derek/workspaces/pi-extensions/packages/pi-sub2api-provider

Option 5: Keep using the global extensions directory

If you do not want to switch installation methods yet, copy the entry back to the global extension:

cp /Users/derek/workspaces/pi-extensions/packages/pi-sub2api-provider/src/index.ts ~/.pi/agent/extensions/sub2api-quota.ts

Requirements

You need the following files in place:

• ~/.pi/agent/models.json with provider connection settings; the per-model models array is optional.
• ~/.pi/agent/auth.json

Example structure:

// ~/.pi/agent/models.json
{
  "providers": {
    "my-sub2api": {
      "baseUrl": "https://example.com/v1",
      "api": "openai-completions"
    }
  }
}

// ~/.pi/agent/auth.json
{
  "my-sub2api": {
    "type": "api-key",
    "key": "..."
  }
}

Security note: this repository never stores or copies any API key or auth file.

API adapter

The provider defaults to openai-completions. To opt into Pi's generic OpenAI Responses adapter, set api explicitly:

{
  "providers": {
    "my-sub2api": {
      "baseUrl": "https://example.com/v1",
      "api": "openai-responses"
    }
  }
}

openai-responses uses the HTTP/SSE Responses API in this integration. It does not enable WebSocket transport or websocket-cached; a Sub2API WebSocket adapter is not included.

Anthropic Messages (anthropic-messages)

Set api to anthropic-messages to talk to an upstream that exposes the Anthropic Messages route. This adapter is supported as long as the upstream actually answers on {baseUrl}/v1/messages; a gateway that only exposes OpenAI-compatible routes still returns 404.

The base URL convention differs per adapter, and this package normalizes it for you:

| api | Request path | baseUrl in models.json | |---|---|---| | openai-completions / openai-responses | {baseUrl}/v1/chat/completions, {baseUrl}/v1/responses | with or without /v1 — /v1 is appended when missing | | anthropic-messages | {baseUrl}/v1/messages | with or without /v1 — a trailing /v1 is stripped, because the Anthropic SDK adds it |

{
  "providers": {
    "stepfun": {
      "baseUrl": "https://api.stepfun.com/step_plan",
      "api": "anthropic-messages",
      "models": [{ "id": "step-5-preview", "reasoning": true }]
    }
  }
}

Without that stripping the request was sent to https://api.stepfun.com/step_plan/v1/v1/messages and the router answered 404. Both baseUrl spellings now register the same, correct endpoint.

A model entry may also carry its own api / baseUrl override; a baseUrl written there is used verbatim (no /v1 adjustment).

What this package overrides

registerProvider outranks both models.json and Pi's built-in catalog, so this package only takes over a provider when Pi cannot resolve it on its own:

| Provider | Registration | Why | |---|---|---| | Custom id, api-key credential in auth.json | Full (name, api, baseUrl, apiKey, authHeader, models) | Pi reports credentials_not_configured for a custom id whose only credential lives in auth.json | | oauth credential in auth.json | Models only | Pi owns the OAuth refresh and native stream; the raw access token is never sent as a Bearer key | | models.json declares its own apiKey / headers | Models only | Pi resolves those natively | | Built-in provider id (anthropic, openai, xai, …) | Models only | Pi owns the catalog definition: api, baseUrl, auth and model list |

In “models only” mode name, api, baseUrl, apiKey and authHeader are all omitted so they fall back to Pi's own layers. Model discovery still happens: if Pi cannot infer api / baseUrl for the models (it raises that error before touching any stored config), the registration escalates to the full form.

Run pi auth check --provider <id> --json to see which form applies in practice.

Settings

Configure the status bar usage display style in global ~/.pi/agent/settings.json or project .pi/settings.json:

{
  "sub2api": {
    "statusBarUsage": "progress"
  }
}

Supported options for statusBarUsage (or usageDisplay):

| Value | Description | Example | |---|---|---| | "progress" / "bar" | Progress bar (default) | ● my-sub2api d [⣿⣀⡀⡀⡀] · w [⣤⡀⡀⡀⡀] | | "numeric" / "percent" | Percentage numbers | ● my-sub2api d 25% · w 50% | | "none" / false | Hide usage from status bar | (cleared) |

You can also override this with the SUB2API_STATUS_BAR_USAGE environment variable.

Development

From the monorepo root (installs all packages and runs checks for all of them):

cd /Users/derek/workspaces/pi-extensions
npm install
npm test
npm run check
npm run pack:dry-run

Or scoped to this package only:

npm test -w pi-sub2api-provider
npm run check -w pi-sub2api-provider

Release

This package is versioned and released through the pi-extensions monorepo. Every user-facing change needs a changeset:

cd /Users/derek/workspaces/pi-extensions
npm run changeset

Merging the release PR publishes this package to npm automatically.

See docs/RELEASE.md for details.

Usage

Inside pi:

/model
/quota

The status bar will show something like:

• Progress bar (default):

  ● my-sub2api d [⣿⣀⡀⡀⡀] · w [⣤⡀⡀⡀⡀]

• Numeric mode ("statusBarUsage": "numeric"):

  ● my-sub2api d 25% · w 50%

License

MIT © dereknex