pi-custom-provider-model 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pi Custom Provider contributors
+
+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,175 @@
+# Pi Provider Manager
+
+A small, local browser panel for configuring custom providers in [Pi](https://pi.dev). English and Indonesian UI. Built against the official **Pi 0.85.1** public extension and SDK APIs.
+
+**v0.1.0 — local prototype.** npm publication and package scope are not configured yet. `private: true` is intentional during development.
+
+## What works
+
+- Add, edit and remove custom providers using OpenAI Chat Completions, OpenAI Responses or Anthropic Messages.
+- Enter a base URL and API key; preview the actual endpoint paths.
+- Test the model-list endpoint; fetch all advertised pages with deduplication and explicit partial-result reporting.
+- Select discovered models or add model IDs manually.
+- Edit context window, output limit, input modalities and reasoning metadata.
+- Fill context/output defaults from endpoint metadata or exact, unambiguous Pi catalog matches, with source labels and manual overrides.
+- Run streaming chat, tool calling, reasoning and image-input checks through **Pi's SDK**, with results inline beneath each model.
+- Save provider/model definitions to `models.json`, API keys through Pi's native `auth.json` handling, and startup defaults to `settings.json`.
+- Preserve existing unknown settings/model overrides and JSON comments when editing; detect stale writes and retain the last 10 `models.json` backups.
+- Show credential source without returning saved keys or headers to the browser.
+
+## Try the prototype
+
+Requires Node **22.19+** and Pi **0.85.1+**. Compatibility is currently tested with 0.85.1 on Windows/Edge; other versions/platforms need verification before release.
+
+From this project directory:
+
+```powershell
+npm install --ignore-scripts
+pi -e ./src/index.ts
+```
+
+Inside Pi:
+
+```text
+/custom-provider
+```
+
+A browser opens on a random loopback port. If it does not, copy the URL printed by Pi. The command can open before any model is authenticated.
+
+```text
+/custom-provider --no-browser
+/custom-provider stop
+```
+
+For ongoing local use, run this in your terminal:
+
+```powershell
+pi install "C:\SERVER\pi-custom-provider"
+```
+
+Then `/reload` in Pi and use `/custom-provider`. Local installation references this folder in place. The panel stops when Pi exits, reloads, or switches sessions.
+
+### Standalone development
+
+```powershell
+npm run dev
+```
+
+Open the printed URL. By default this uses **`.sandbox/agent`**, an isolated configuration directory. The backend prints which directory it is managing.
+
+To manage your actual Pi configuration instead:
+
+```powershell
+npm run dev -- --real-config
+```
+
+Or select a directory explicitly:
+
+```powershell
+npm run dev -- --agent-dir "C:\path\to\agent"
+```
+
+The extension uses Pi's `getAgentDir()`, including `PI_CODING_AGENT_DIR`. It does not hardcode a Windows profile path.
+
+## First provider
+
+1. Click **Add provider** and choose a unique ID such as `my-gateway`.
+2. Select the API protocol and enter the **Pi-native** base URL.
+3. Enter an API key. The field is literal; leaving it empty on an existing provider preserves its credentials.
+4. Click **Test connection**, then **Fetch models**.
+5. Select the models you want to save, or use **Manual model** if listing is unavailable.
+6. Use **Test chat** for a quick streaming check, or **Check capabilities** for chat, tools, reasoning and image input. Progress and results appear directly under that model; **Stop tests** cancels the remaining work.
+7. Click **Save provider**, then select it in Pi's `/model` picker. **Set default** applies to future Pi launches.
+
+### Base URL examples
+
+| Protocol | Base URL | Model list | Chat |
+| --- | --- | --- | --- |
+| OpenAI Chat | `https://gateway.example/v1` | `/v1/models` | `/v1/chat/completions` |
+| OpenAI Responses | `https://gateway.example/v1` | `/v1/models` | `/v1/responses` |
+| Anthropic Messages | `https://api.anthropic.com` | `/v1/models` | `/v1/messages` |
+| Anthropic gateway | `https://gateway.example/anthropic` | `/anthropic/v1/models` | `/anthropic/v1/messages` |
+
+Pi's Anthropic SDK appends `/v1/messages` itself. For a gateway advertising `/anthropic/v1/messages`, enter a base URL ending in `/anthropic`. Path prefixes are never silently stripped. SDK-added query parameters can appear in actual test results.
+
+**Test connection is not a chat test.** A provider can expose `/models` without authorizing inference, or support chat without supporting `/models`. API protocol selection does not restrict the model's brand: a gateway may serve Claude through OpenAI-compatible transport.
+
+Unknown model metadata remains absent from the saved JSON. The UI labels Pi defaults (128000 context, 16384 output, text-only, reasoning off). A model ID alone does not verify capabilities. Fetch adds new IDs and fills missing context/output values without deleting models or overwriting saved/manual settings. Unchecking a saved model and saving explicitly removes it.
+
+### Automatic context and output defaults
+
+The panel fills known limits into the draft instead of using the same generic numbers for every model:
+
+1. **Endpoint metadata** takes priority. Anthropic uses `max_input_tokens` and `max_tokens`. OpenAI-compatible lists may supply `context_length`, `context_window` / `contextWindow`, `max_output_tokens`, `max_completion_tokens` / `maxTokens`, or OpenRouter-style `top_provider` limits. Explicit `per_request_limits` also constrain the values. When several applicable bounds are supplied, the smallest positive integer is used.
+2. **Pi catalog reference** fills missing fields using the installed Pi SDK's bundled catalog through its public exports. The ID must match exactly, and all matching catalog entries must agree on that field. There are no fuzzy aliases, guessed model-family limits, or background network catalog requests. This is the catalog's configured limit, which may differ from a model's theoretical maximum or your gateway's limit.
+3. **Maximum unknown** remains on Pi's fallback (128000 context / 16384 output). Conflicting catalog entries are labelled explicitly. Standard OpenAI `/models` returns IDs/ownership, not token limits; generic `max_tokens` alone is ambiguous and is not interpreted as an output maximum.
+
+Use **Fetch models** to obtain endpoint metadata and fill existing empty values as well as new models. Existing saved values and manual edits win. Endpoint metadata can replace an unsaved catalog default. Opening an existing provider also fills empty fields from the local catalog into its draft. **Fill missing limits** fills known empty fields across the current provider; **Use detected limits** in a model's editor explicitly replaces that model's context/output values with the available metadata. Manual model entry looks up the exact ID in the local catalog without consuming API tokens.
+
+Both context and maximum output are visible in each model row. Source labels distinguish endpoint, catalog, saved/custom and manual values. Metadata hints are browser/session information only: **Save provider** persists just the numeric native `contextWindow` / `maxTokens` fields. Reading metadata does not save configuration or verify the maximum through inference. Changing the connection clears endpoint hints and unsaved endpoint defaults; saved/manual values are kept. Model-specific endpoint/API overrides do not inherit metadata from a different provider endpoint.
+
+The maximum output is a ceiling, not a requested answer length. A request may have a lower effective ceiling due to remaining context, provider routing, account limits, or Pi's request settings. Capability probes retain their small test budgets regardless of the configured maximum.
+
+### Per-model capability checks
+
+| Check | Evidence required for “Verified” |
+| --- | --- |
+| Chat / streaming | Pi parses a streaming text response. |
+| Tool calling | Pi receives one schema-valid `provider_probe` call, supplies a generated receipt as its tool result, and the model repeats that receipt in a second turn. |
+| Reasoning | With reasoning requested, Pi receives a thinking block (including opaque/redacted thinking) or positive reasoning-token usage. A normal text answer alone is insufficient. |
+| Image input | The model correctly identifies the four quadrant colors in a fresh, locally generated PNG. Accepting an image parameter alone is insufficient. |
+
+Checks send only short synthetic prompts, including a system prompt serialized by Pi, the harmless test-tool schema/result and a generated image. They do not use project files, session history or executable tools. A full run makes up to **5 requests**, sequentially. Each request asks for at most **256 output tokens**, except reasoning which uses a **2,048-token ceiling** and a 1,024-token thinking budget where supported. Existing Pi compatibility settings still apply; gateways may ignore token caps. Chat times out after 30 seconds; each other check after 60 seconds, including both tool turns. Retries are disabled.
+
+**Unconfirmed** means the expected evidence was absent; **Test failed** means a request/transport error. Neither proves that the model lacks the capability. Gateways may hide reasoning, need different compatibility parameters, or require larger budgets. Checks validate this endpoint/configuration on a small sample, not every possible workload. Context-window limits, structured output, audio and combined reasoning-plus-tool behavior are not tested.
+
+The panel shows HTTP status, duration, request count, token usage and endpoint for each check, without exposing raw answers, thinking, arguments or upstream errors. Results remain in browser memory during editing/saving and are cleared when the connection or model settings change, when switching/reloading providers, or when reloading the page.
+
+**Apply verified capabilities** enables only successfully verified vision/reasoning in the draft. Click **Save provider** to persist those settings. Tests alone never alter model metadata, and failed checks never disable existing settings. Pi has no model-level tool-support switch; the tool result remains diagnostic information rather than an invented `models.json` field.
+
+### Gateway rejects the `developer` role (HTTP 400/422)
+
+Pi may serialize the system prompt as a `developer` message for reasoning-capable OpenAI models. Some gateways accept only `system`, `user`, `assistant` and `tool`. Chat working in another client does not guarantee identical Pi request compatibility.
+
+1. In **Connection**, set **Default system prompt role — this provider** to **system — compatible gateways**.
+2. Run **Test chat** / **Check capabilities**, then **Save provider**.
+3. If upgrading the extension, run `/reload` in Pi and reopen `/custom-provider` to load the new controls.
+
+This saves `"compat": { "supportsDeveloperRole": false }` on the provider, covering existing and newly added models that inherit its settings. Model rows show whether a role comes from the provider default or an individual override. You do not need to edit every model.
+
+For an individual exception, click **Edit** on the model and set **System prompt role (OpenAI)**. Model overrides take priority over the provider default. **Follow Pi / provider settings** removes only that model's role override and restores inheritance. **Pi automatic detection** removes the provider's role override. These controls keep reasoning and other compatibility settings intact and apply to OpenAI Chat Completions and Responses; Anthropic has its own system-prompt format.
+
+Saving through the extension refreshes the registry and reselects the current model with its updated configuration when Pi is idle. If an agent run is active, synchronization waits until it settles. `/reload` also refreshes the active model, so a previously cached model object does not retain the old role setting. In standalone mode, reopen `/model` in Pi and select the saved provider/model after saving.
+
+All probes include a synthetic system prompt so they exercise Pi's role serialization. Recognized developer-role rejections show a specific repair hint without displaying the raw upstream error. HTTP 5xx (including 502 Bad Gateway) remains a separate gateway/upstream failure, not evidence of this particular role mismatch. Role rejections and 5xx stop the remaining capability checks; retry explicitly after adjusting the configuration or waiting.
+
+## Configuration and credentials
+
+The panel binds to `127.0.0.1`. It uses a per-launch token, same-origin requests and no external frontend assets. Entered keys are sent to the local backend and the selected upstream; existing saved keys are never returned to the browser. Test errors do not echo raw upstream bodies.
+
+Provider-scoped API keys use Pi's public `ModelRuntime.login()` / `logout()` and native credential store. Native API-key precedence and existing environment-variable references are respected. OAuth is managed by Pi's `/login` and `/logout`. Providers defined only by other extensions and built-in provider overrides are outside the v0.1 editor.
+
+Replacing a credential with provider-scoped `env` settings is currently refused to avoid losing that advanced state through Pi's login replacement behavior. Use Pi's native auth configuration for those entries. Deleting a provider retains its key; remove the key first if desired. Removing an `auth.json` key does not remove a fallback key from `models.json` or the environment.
+
+Backups live in `<agentDir>/provider-manager-backups/`. To restore, stop the panel and copy the desired backup over `models.json`, then reopen `/model`. Backups can contain pre-existing secrets from models.json and are created with owner-only permissions where supported. Only `models.json` is backed up; authentication and defaults use Pi's own writers. A partial save reports which operation needs attention.
+
+## Development and verification
+
+```powershell
+npm run verify
+npm run pack:check
+```
+
+- TypeScript type checking.
+- Mock HTTP tests for three protocols, pagination, credentials, preservation of config and stale-write handling.
+- Test through Pi's official extension loader, including asset resolution and shutdown.
+- Playwright browser workflow (installed Microsoft Edge on Windows; run `npx playwright install chromium` first on other platforms).
+- Screenshots are produced under `test-results/` and excluded from the npm package.
+
+Tests use isolated temporary directories and mock endpoints. Real gateway compatibility and RAM footprint have not been benchmarked yet.
+
+See [`docs/design.md`](docs/design.md) for the version-pinned official documentation and publication plan. Future distribution will be `pi install npm:@your-scope/package-name`, with a `pi` manifest and the `pi-package` keyword for the Pi catalog.
+
+## License
+
+MIT. Independent community project; not an official Pi product.

package/docs/design.md

@@ -0,0 +1,54 @@
+# v0.1 design and reference map
+
+Status: local prototype. Pi compatibility baseline: 0.85.1. Package name/scope and public repository have not been chosen. `private: true` prevents accidental publication while retaining local/git installation and tarball inspection.
+
+## Official Pi sources (version pinned)
+
+- [Custom models](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/models.md): providers, baseUrl, api, models, defaults, compat, model overrides, key references.
+- [Authentication](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/providers.md): auth.json credential format, key resolution and precedence.
+- [Extensions](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/extensions.md): registerCommand, modelRegistry.refresh, getAgentDir, deferred resources and session_shutdown.
+- [SDK](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/sdk.md): ModelRuntime and configurable credentials.
+- [Pi AI SDK](https://github.com/earendil-works/pi/blob/v0.85.1/packages/ai/README.md): tools, `validateToolCall`, tool results, image input and `completeSimple` reasoning options. Public types define thinking blocks and `usage.reasoning`.
+- [Settings](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/settings.md): defaultProvider/defaultModel.
+- [Packages](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/packages.md): pi manifest, pi-package keyword, npm/git installs and peer dependencies.
+
+API discovery complements Pi's documentation with [OpenAI Models](https://developers.openai.com/api/reference/resources/models/methods/list), [Anthropic Models](https://platform.claude.com/docs/en/api/models/list), and [OpenRouter model metadata](https://openrouter.ai/docs/api/api-reference/models/get-models). Local catalog lookup uses public `getBuiltinProviders()` / `getBuiltinModels()` exports from `@earendil-works/pi-ai/providers/all`.
+
+## One vertical workflow
+
+`/custom-provider` opens a local browser panel. Enter a custom provider ID, base URL, API protocol and key. Preview request endpoints, test connectivity, fetch all advertised model pages, select models, save, then select via Pi `/model`. Per-model SDK probes check streaming text, a harmless two-turn tool call, reasoning evidence and a generated image. Progress and results are displayed inline below each model.
+
+- APIs: openai-completions, openai-responses, anthropic-messages.
+- Base URL is Pi-native: OpenAI normally ends in `/v1`; Anthropic normally has no trailing `/v1` because its SDK appends `/v1/messages`. A gateway prefix such as `/anthropic` is preserved. Do not rewrite arbitrary URL paths. Show the resulting URLs before requesting.
+- Discovery is additive: refresh never automatically deletes a locally configured model. Show all IDs (including non-chat models) and allow manual IDs when listing is unavailable. Anthropic pagination follows last_id/has_more. Bounded pagination/timeouts explicitly report incomplete lists.
+- Absent metadata stays absent in models.json. Label Pi fallback values (128000 context, 16384 output, text-only, reasoning false). Never infer capabilities from a model name.
+- Context/output defaults: endpoint-declared positive integer limits first, then exact-ID catalog matches with consensus per field. Never normalize aliases or take the largest of conflicting catalog values. Label catalog values as references rather than verified gateway maxima. Explicit per-request caps constrain endpoint values. Metadata-only reads make no inference calls.
+- Fill missing limits in the draft during provider load, discovery and manual-ID entry. Preserve saved/manual values; endpoint metadata may supersede an unsaved catalog default. Both numeric fields and their sources appear per model; hints/sources are not serialized into native configuration. Unknown fields remain absent. Explicit “Use detected limits” replaces a model's limits; “Fill missing limits” does not replace existing values.
+- Capability probes use temporary model copies to enable reasoning/image transport without saving inferred settings. Only evidence earns “Verified”; absent evidence is inconclusive, and request errors are failures rather than unsupported declarations. Optional application updates only successful vision/reasoning flags in the draft. Pi has no tool-support model flag.
+- A full probe run is sequential (up to five requests); each result is returned separately so the UI can show progress and cancel. Use 256 output tokens per request, 2048 for reasoning, 30s for chat and 60s for other probes. Never return raw model text/thinking/tool arguments. Tool calls are schema-validated and receive an in-memory receipt, never arbitrary execution.
+- Every probe includes a synthetic system prompt to exercise Pi's system/developer serialization. Recognize explicit developer-role rejection in 400/422 SDK errors using fixed diagnostics; distinguish HTTP 5xx gateway errors. Do not silently retry or infer role rejection from a generic 422/502.
+- The provider and model editors expose only `compat.supportsDeveloperRole` from compatibility metadata. False forces `system` for OpenAI APIs without disabling reasoning. Provider defaults cover existing and future models; model overrides take priority and are labelled in model rows. Undefined edits preserve saved overrides; an explicit null edit removes this one field and restores provider/Pi inheritance. Merge other compat fields and preserve comments; never return arbitrary compat/header data to the browser.
+- Registry refresh alone does not replace Pi's active model object. After panel saves and on `session_start` with reason `reload`, refresh without network and use public `pi.setModel()` for changed active-model metadata. Defer selection while busy until `agent_settled`; avoid reselecting unchanged metadata.
+- API keys go through the public ModelRuntime login/logout interface using its native authPath-backed credential store. This keeps key interpolation and locking in Pi itself. No imports of private AuthStorage internals. API-key replacement follows Pi's /login semantics; unrelated providers and OAuth entries are preserved.
+- All configuration updates merge into the latest document under lock, check revisions, keep unknown fields/comments, and back up models.json. Conflicting external edits return a conflict instead of replacing the latest version. Native OAuth entries remain managed by Pi /login.
+- Existing built-in provider overrides are displayed read-only in v0.1. Manage custom provider definitions here.
+
+## Components
+
+- `src/index.ts`: Pi command and lifecycle integration.
+- `src/server.ts`: on-demand localhost HTTP service and browser-safe endpoints.
+- `src/service.ts`: provider workflow and native runtime adapter.
+- `src/storage.ts`: comment-preserving configuration and credential storage.
+- `src/discovery.ts`: protocol URL previews and remote catalog discovery.
+- `src/limits.ts`: endpoint token-limit parsing, duplicate reconciliation, exact-ID local catalog references.
+- `src/probes.ts`: Pi-native capability probes, synthetic PNG generation and evidence-based results.
+- `web/`: dependency-free browser UI; English and Indonesian.
+- `test/`: isolated mock-server integration and browser workflow checks.
+
+## Local transport
+
+Bind to 127.0.0.1 on a random port. A session token in the URL fragment is exchanged for request headers, never sent upstream. Validate Host/Origin and do not enable cross-origin access. Do not return credential values or provider/model headers in browser state. Test/discovery requests use only the endpoint explicitly selected by the user; redirects do not forward keys to another location.
+
+## Publication checklist
+
+Choose an available npm scope/name and repository; add repository metadata and changelog; verify Windows and CI on Linux/macOS; run tests and inspect npm pack; remove private only for an intentional public release. Include the prebuilt web assets (this prototype needs no frontend build). Gallery indexing uses npm's pi-package keyword; listing timing is outside this project's control.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "pi-custom-provider-model",
+  "version": "0.1.1",
+  "description": "A local browser-based custom provider and API-key manager for Pi.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "providers",
+    "models"
+  ],
+  "files": [
+    "src/",
+    "web/",
+    "README.md",
+    "LICENSE",
+    "docs/"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "dev": "tsx src/standalone.ts",
+    "check": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "test:ui": "tsx --test test/browser.e2e.ts",
+    "verify": "npm run check && npm test && npm run test:ui",
+    "pack:check": "npm pack --dry-run"
+  },
+  "dependencies": {
+    "jsonc-parser": "^3.3.1",
+    "proper-lockfile": "^4.1.2"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-ai": "0.85.1",
+    "@types/node": "^22.19.0",
+    "@types/proper-lockfile": "^4.1.4",
+    "playwright": "^1.58.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/discovery.ts

@@ -0,0 +1,124 @@
+import { AppError, object, type Protocol } from "./types.ts";
+import { endpointLimits, LIMIT_FIELDS, mergeEndpointLimits, type ListedModel } from "./limits.ts";
+
+export function endpointUrls(baseUrl: string, api: Protocol) {
+  const root = baseUrl.replace(/\/+$/, "");
+  // Matches the SDK URL concatenation. Explicit prefixes are preserved.
+  return api === "anthropic-messages"
+    ? { models: `${root}/v1/models`, chat: `${root}/v1/messages` }
+    : { models: `${root}/models`, chat: `${root}/${api === "openai-responses" ? "responses" : "chat/completions"}` };
+}
+
+export function requestHeaders(api: Protocol, apiKey?: string, extra?: Record<string, string | null>): Headers {
+  const headers = new Headers({ Accept: "application/json" });
+  if (api === "anthropic-messages") {
+    headers.set("anthropic-version", "2023-06-01");
+    if (apiKey) headers.set("x-api-key", apiKey);
+  } else if (apiKey) headers.set("Authorization", `Bearer ${apiKey}`);
+  for (const [key, value] of Object.entries(extra ?? {})) {
+    if (value === null) headers.delete(key); else headers.set(key, value);
+  }
+  return headers;
+}
+
+export function statusMessage(status: number): string {
+  if (status === 401 || status === 403) return "Endpoint refused access. Check the API key and account permissions.";
+  if (status === 404 || status === 405) return "Model-list endpoint is unavailable. Verify the URL or add models manually; chat may still work.";
+  if (status === 429) return "Provider rate or concurrency limit reached. Try again after active requests finish.";
+  if (status >= 500) return "Provider returned a server error. Try again later.";
+  if (status >= 300 && status < 400) return "Endpoint redirected. Enter the final base URL explicitly.";
+  return `Endpoint returned HTTP ${status}.`;
+}
+
+async function readLimited(response: Response, maxBytes = 8_000_000): Promise<unknown> {
+  if (!response.body) throw new AppError("Endpoint returned an empty response.", 502);
+  const reader = response.body.getReader();
+  let bytes = 0;
+  const chunks: Uint8Array[] = [];
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      bytes += value.byteLength;
+      if (bytes > maxBytes) throw new AppError("Model-list response is too large.", 502);
+      chunks.push(value);
+    }
+  } finally { await reader.cancel().catch(() => {}); }
+  try { return JSON.parse(Buffer.concat(chunks).toString("utf8")); }
+  catch { throw new AppError("Expected a JSON model list; the endpoint returned another format.", 502); }
+}
+
+export interface DiscoveryOptions {
+  api: Protocol;
+  baseUrl: string;
+  headers: Headers;
+  allPages: boolean;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+}
+
+export async function discover(options: DiscoveryOptions) {
+  const started = Date.now();
+  const signal = AbortSignal.any([AbortSignal.timeout(options.timeoutMs ?? 30000), ...(options.signal ? [options.signal] : [])]);
+  const target = endpointUrls(options.baseUrl, options.api).models;
+  const models = new Map<string, ListedModel>();
+  const cursors = new Set<string>();
+  let cursor: string | undefined;
+  let pages = 0;
+  let complete = false;
+  let warning: string | undefined;
+  try {
+    while (pages < 100 && models.size < 10000) {
+      const url = new URL(target);
+      if (options.api === "anthropic-messages") {
+        url.searchParams.set("limit", "100");
+        if (cursor) url.searchParams.set("after_id", cursor);
+      } else if (cursor) url.searchParams.set("after", cursor);
+      const response = await fetch(url, { headers: options.headers, signal, redirect: "manual" });
+      if (!response.ok) {
+        await response.body?.cancel();
+        throw new AppError(statusMessage(response.status), response.status);
+      }
+      const data = await readLimited(response);
+      if (!object(data) || !Array.isArray(data.data)) throw new AppError("Response must contain a data array of models.", 502);
+      pages++;
+      let truncated = false;
+      for (const entry of data.data) {
+        if (!object(entry) || typeof entry.id !== "string" || !entry.id.trim() || entry.id.length > 300 || /[\x00-\x1f]/.test(entry.id)) continue;
+        const model: ListedModel = { ...models.get(entry.id.trim()), id: entry.id.trim() };
+        if (typeof entry.display_name === "string" && entry.display_name) model.name = entry.display_name;
+        model.limitHints = mergeEndpointLimits(model.limitHints, endpointLimits(entry, options.api));
+        for (const field of LIMIT_FIELDS) if (model.limitHints[field]) model[field] = model.limitHints[field]!.value;
+        // Only map documented capability fields; IDs alone imply no capabilities.
+        if (options.api === "anthropic-messages") {
+          if (typeof entry.capabilities?.thinking?.supported === "boolean") model.reasoning = entry.capabilities.thinking.supported;
+          if (typeof entry.capabilities?.image_input?.supported === "boolean") model.input = entry.capabilities.image_input.supported ? ["text", "image"] : ["text"];
+        }
+        if (!models.has(model.id) && models.size >= 10000) { truncated = true; break; }
+        models.set(model.id, model);
+      }
+      if (truncated) { warning = "Discovery limit reached. Results are incomplete."; break; }
+      if (data.has_more !== true) {
+        // Do not silently claim completeness for alternate pagination formats.
+        if (data.links?.next || (Number.isSafeInteger(data.total_count) && data.total_count > models.size)) {
+          warning = "Endpoint reports additional results using unsupported pagination. Results are incomplete.";
+        } else complete = true;
+        break;
+      }
+      if (!options.allPages) { warning = "Connection verified. Fetch models to retrieve remaining pages."; break; }
+      const next = data.last_id;
+      if (typeof next !== "string" || !next || cursors.has(next)) {
+        warning = "Endpoint indicates more models but has no usable pagination cursor. Results are incomplete.";
+        break;
+      }
+      cursors.add(next);
+      cursor = next;
+    }
+    if (!complete && !warning) warning = "Discovery limit reached. Results are incomplete.";
+  } catch (error) {
+    const message = error instanceof AppError ? error.message : signal.aborted ? "Request cancelled or timed out." : "Cannot reach the endpoint. Check URL, DNS, TLS and network access.";
+    if (!pages) throw error instanceof AppError ? error : new AppError(message, 502);
+    warning = `${message} Results are incomplete.`;
+  }
+  return { ok: true, url: target, status: 200, durationMs: Date.now() - started, pages, complete, warning, models: [...models.values()] };
+}

package/src/index.ts

@@ -0,0 +1,63 @@
+import { spawn } from "node:child_process";
+import { getAgentDir, VERSION, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { startManager } from "./server.ts";
+
+function openBrowser(url: string) {
+  const [program, args] = process.platform === "win32"
+    ? ["rundll32.exe", ["url.dll,FileProtocolHandler", url]]
+    : process.platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+  const child = spawn(program, args, { detached: true, stdio: "ignore", windowsHide: true });
+  child.on("error", () => {});
+  child.unref();
+}
+
+export default function (pi: ExtensionAPI) {
+  let manager: Awaited<ReturnType<typeof startManager>> | undefined;
+  let starting: Promise<Awaited<ReturnType<typeof startManager>>> | undefined;
+  let pendingModelSync = false;
+  const syncActiveModel = async (ctx: ExtensionContext) => {
+    if (!pendingModelSync || !ctx.isIdle()) return;
+    const current = ctx.model;
+    const fresh = current && ctx.modelRegistry.find(current.provider, current.id);
+    if (fresh && JSON.stringify(fresh) !== JSON.stringify(current) && !await pi.setModel(fresh)) {
+      throw new Error("Reselect the saved model using Pi /model.");
+    }
+    pendingModelSync = false;
+  };
+  const refreshModels = async (ctx: ExtensionContext) => {
+    await ctx.modelRegistry.refresh({ allowNetwork: false });
+    pendingModelSync = true;
+    await syncActiveModel(ctx);
+  };
+  pi.on("session_start", async (event, ctx) => {
+    if (event.reason === "reload") await refreshModels(ctx);
+  });
+  pi.on("agent_settled", async (_event, ctx) => {
+    if (pendingModelSync) await syncActiveModel(ctx);
+  });
+  pi.registerCommand("custom-provider", {
+    description: "Manage custom providers, API keys and models in a local browser",
+    handler: async (args, ctx) => {
+      if (args.trim() === "stop") {
+        if (starting) await starting;
+        await manager?.close(); manager = undefined;
+        ctx.ui.notify("Provider manager stopped.", "info"); return;
+      }
+      const [major, minor, patch] = VERSION.split(".").map(Number);
+      if (major === 0 && (minor < 85 || (minor === 85 && patch < 1))) {
+        ctx.ui.notify("Pi Custom Provider requires Pi 0.85.1 or later.", "error"); return;
+      }
+      if (!manager) {
+        starting ??= startManager(getAgentDir(), () => refreshModels(ctx));
+        try { manager = await starting; } finally { starting = undefined; }
+      }
+      ctx.ui.notify(`Provider manager: ${manager.url}`, "info");
+      if (!args.includes("--no-browser")) openBrowser(manager.url);
+    },
+  });
+  pi.on("session_shutdown", async () => {
+    pendingModelSync = false;
+    if (starting) await starting.catch(() => {});
+    await manager?.close(); manager = undefined;
+  });
+}

package/src/limits.ts

@@ -0,0 +1,75 @@
+import { getBuiltinModels, getBuiltinProviders } from "@earendil-works/pi-ai/providers/all";
+import type { JsonObject, ModelInput, Protocol } from "./types.ts";
+
+export const LIMIT_FIELDS = ["contextWindow", "maxTokens"] as const;
+export type LimitField = typeof LIMIT_FIELDS[number];
+export interface LimitValue {
+  value: number;
+  source: "endpoint" | "catalog";
+  field?: string;
+}
+export interface LimitHints {
+  contextWindow?: LimitValue;
+  maxTokens?: LimitValue;
+  ambiguous?: LimitField[];
+}
+export interface ListedModel extends ModelInput { limitHints?: LimitHints }
+const positiveInteger = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+
+function smallest(fields: [string, unknown][]): LimitValue | undefined {
+  const valid = fields.filter((entry): entry is [string, number] => positiveInteger(entry[1]));
+  valid.sort((a, b) => a[1] - b[1]);
+  return valid.length ? { value: valid[0][1], source: "endpoint", field: valid[0][0] } : undefined;
+}
+
+export function endpointLimits(entry: JsonObject, api: Protocol): LimitHints {
+  if (api === "anthropic-messages") return {
+    contextWindow: smallest([["max_input_tokens", entry.max_input_tokens]]),
+    maxTokens: smallest([["max_tokens", entry.max_tokens]]),
+  };
+  // Explicit metadata fields only. Bare max_tokens is ambiguous on generic gateways.
+  return {
+    contextWindow: smallest([
+      ["context_length", entry.context_length], ["context_window", entry.context_window], ["contextWindow", entry.contextWindow],
+      ["top_provider.context_length", entry.top_provider?.context_length],
+      ["per_request_limits.prompt_tokens", entry.per_request_limits?.prompt_tokens],
+    ]),
+    maxTokens: smallest([
+      ["max_output_tokens", entry.max_output_tokens], ["max_completion_tokens", entry.max_completion_tokens], ["maxTokens", entry.maxTokens],
+      ["top_provider.max_completion_tokens", entry.top_provider?.max_completion_tokens],
+      ["per_request_limits.completion_tokens", entry.per_request_limits?.completion_tokens],
+    ]),
+  };
+}
+
+export function mergeEndpointLimits(previous: LimitHints = {}, next: LimitHints = {}): LimitHints {
+  const result: LimitHints = {};
+  for (const field of LIMIT_FIELDS) {
+    const a = previous[field], b = next[field];
+    if (a || b) result[field] = a && b ? a.value <= b.value ? a : b : a ?? b;
+  }
+  return result;
+}
+
+// The bundled public catalog is read without network, credentials, or user overrides.
+export class LimitCatalog {
+  private entries = new Map<string, Pick<ModelInput, "id" | LimitField>[]>();
+  constructor(models: readonly Pick<ModelInput, "id" | LimitField>[] = getBuiltinProviders().flatMap((provider) => getBuiltinModels(provider))) {
+    for (const model of models) {
+      const entries = this.entries.get(model.id) ?? [];
+      entries.push(model); this.entries.set(model.id, entries);
+    }
+  }
+
+  lookup(id: string, endpoint: LimitHints = {}): LimitHints {
+    const result: LimitHints = {};
+    const matches = this.entries.get(id) ?? [];
+    for (const field of LIMIT_FIELDS) {
+      if (endpoint[field]) { result[field] = endpoint[field]; continue; }
+      const values = new Set(matches.map((m) => m[field]).filter(positiveInteger));
+      if (values.size === 1) result[field] = { value: [...values][0], source: "catalog" };
+      else if (values.size > 1) (result.ambiguous ??= []).push(field);
+    }
+    return result;
+  }
+}