mirror of
https://github.com/badlogic/pi-mono.git
synced 2026-11-05 23:37:25 +00:00
docs: fix provider checklist, MCP anchors, and missing commands/settings (#11338)
Fix docs and `--help` drift: update the provider checklist to the `src/api` layout, fix broken MCP anchors, and document `/mcp`, `pi mcp add|remove`, `PI_CLEAR_ON_SHRINK`, and `"disabled"` timeouts. closes #11243
This commit is contained in:
Christian Klotz
GitHub
parent
36be9c612e
commit
ede2c9b468
8 changed files with 35 additions and 35 deletions
|
|
@ -9,32 +9,33 @@ A new provider touches multiple files. Work through these steps in order.
|
|||
|
||||
## 1. Core Types (`packages/ai/src/types.ts`)
|
||||
|
||||
- Add API identifier to `Api` type union (e.g. `"bedrock-converse-stream"`).
|
||||
- Create options interface extending `StreamOptions`.
|
||||
- Add mapping to `ApiOptionsMap`.
|
||||
- Add provider name to `KnownProvider` type union.
|
||||
- Add the provider name to the `KnownProvider` union.
|
||||
- Only for a new API: add the API identifier to `KnownApi` (e.g. `"bedrock-converse-stream"`) and its options type to `ApiOptionsMap`.
|
||||
|
||||
## 2. Provider Implementation (`packages/ai/src/providers/`)
|
||||
## 2. API Implementation (`packages/ai/src/api/`, only for a new API)
|
||||
|
||||
Create a provider file exporting:
|
||||
Most providers reuse an existing API such as `openai-completions`; skip this step then.
|
||||
|
||||
- `stream<Provider>()` returning `AssistantMessageEventStream`.
|
||||
- `streamSimple<Provider>()` for `SimpleStreamOptions` mapping.
|
||||
- Provider-specific options interface.
|
||||
- Message/tool conversion functions.
|
||||
- Response parsing that emits standardized events (`text`, `tool_call`, `thinking`, `usage`, `stop`).
|
||||
- `src/api/<api-id>.ts` exports exactly `stream` and `streamSimple`, plus an options interface extending `StreamOptions`.
|
||||
- Convert messages and tools to the provider format. Read the prompt and tools from the transcript with `getInitialSystemMessage()`, `getCurrentTools()`, and `resolveTranscript()`.
|
||||
- Parse responses into standardized events (`text`, `tool_call`, `thinking`, `usage`, `stop`).
|
||||
- Add a lazy wrapper `src/api/<api-id>.lazy.ts` (`<name>Api()` via `lazyApi()`) so providers can reference the implementation without importing its SDK.
|
||||
- Register the lazy wrapper in the builtin API list in `src/compat.ts`.
|
||||
- Add `export type` re-exports in `src/index.ts` for option types that should be available from the root entry. The `./api/*` subpath export in `package.json` already covers the new module.
|
||||
|
||||
## 3. Provider Exports and Lazy Registration
|
||||
|
||||
- Add a package subpath export in `packages/ai/package.json` pointing at `./dist/providers/<provider>.js`.
|
||||
- Add `export type` re-exports in `packages/ai/src/index.ts` for provider option types that should remain available from the root entry.
|
||||
- Register the provider in `packages/ai/src/providers/register-builtins.ts` via lazy loader wrappers; do not statically import provider implementation modules there.
|
||||
- Add credential detection in `packages/ai/src/env-api-keys.ts`.
|
||||
|
||||
## 4. Model Generation (`packages/ai/scripts/generate-models.ts`)
|
||||
## 3. Model Generation (`packages/ai/scripts/generate-models.ts`)
|
||||
|
||||
- Add logic to fetch/parse models from the provider source.
|
||||
- Map to the standardized `Model` interface.
|
||||
- Regenerate. This writes the stable catalog wrapper `src/providers/<id>.models.ts` (exporting `<ID>_MODELS`) that the provider factory imports, and updates `src/models.generated.ts`.
|
||||
|
||||
## 4. Provider Factory and Auth (`packages/ai/src/providers/`)
|
||||
|
||||
- Create `src/providers/<id>.ts` exporting `<id>Provider()`, which calls `createProvider({ id, name, baseUrl, auth, models, api })`. `name` is the display name shown by `/login` and related UI. See `deepseek.ts` for a minimal example.
|
||||
- Auth: `envApiKeyAuth()` for standard API keys, a custom `ApiKeyAuth` for ambient credentials (AWS profiles, ADC), `lazyOAuth()` where an OAuth flow exists.
|
||||
- Pass the lazy API wrapper (e.g. `openAICompletionsApi()`) as `api`; do not statically import API implementation modules.
|
||||
- Register the factory in `src/providers/all.ts`.
|
||||
- Add the env var to `src/env-api-keys.ts` so the compat `getEnvApiKey()` finds it.
|
||||
|
||||
## 5. Tests (`packages/ai/test/`)
|
||||
|
||||
|
|
@ -46,9 +47,7 @@ Create a provider file exporting:
|
|||
## 6. Coding Agent (`packages/coding-agent/`)
|
||||
|
||||
- `src/core/model-resolver.ts`: add default model ID to `defaultModelPerProvider`.
|
||||
- `src/core/provider-display-names.ts`: add API-key login display name so `/login` and related UI show the provider for built-in API-key auth.
|
||||
- `src/cli/args.ts`: add env var documentation.
|
||||
- `README.md`: add provider setup instructions.
|
||||
- `docs/providers.md`: add setup instructions, env var, and `auth.json` key.
|
||||
|
||||
## 7. Documentation
|
||||
|
|
|
|||
|
|
@ -1940,7 +1940,7 @@ Add a lazy wrapper `src/api/<api-id>.lazy.ts` (`<name>Api()` via `lazyApi()`) so
|
|||
- `createProvider()` wiring catalog + auth + the lazy API wrapper
|
||||
- Auth: `envApiKeyAuth` for standard key providers, a custom `ApiKeyAuth` for ambient auth (AWS profiles, ADC), `lazyOAuth` where an OAuth flow exists
|
||||
- Register the factory in `src/providers/all.ts`
|
||||
- If it is a new API: register it in the builtin list in `src/compat.ts` and add the package subpath export in `package.json`
|
||||
- If it is a new API: register it in the builtin list in `src/compat.ts`; the `./api/*` subpath export in `package.json` already covers the new module
|
||||
|
||||
#### 5. Tests (`test/`)
|
||||
|
||||
|
|
@ -1951,7 +1951,6 @@ Create or update test files to cover the new provider:
|
|||
- `abort.test.ts` - Request cancellation
|
||||
- `empty.test.ts` - Empty message handling
|
||||
- `context-overflow.test.ts` - Context limit errors
|
||||
- `image-limits.test.ts` - Image support (if applicable)
|
||||
- `unicode-surrogate.test.ts` - Unicode handling
|
||||
- `tool-call-without-result.test.ts` - Orphaned tool calls
|
||||
- `image-tool-result.test.ts` - Images in tool results
|
||||
|
|
@ -1967,15 +1966,15 @@ For providers with non-standard auth (AWS, Google Vertex), create a utility like
|
|||
|
||||
Update `src/core/model-resolver.ts`:
|
||||
|
||||
- Add a default model ID for the provider in `DEFAULT_MODELS`
|
||||
- Add a default model ID for the provider in `defaultModelPerProvider`
|
||||
|
||||
Update `src/cli/args.ts`:
|
||||
|
||||
- Add environment variable documentation in the help text
|
||||
|
||||
Update `README.md`:
|
||||
Update `docs/providers.md`:
|
||||
|
||||
- Add the provider to the providers section with setup instructions
|
||||
- Add setup instructions, the environment variable, and the `auth.json` key
|
||||
|
||||
#### 7. Documentation
|
||||
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ pi update [target] [options]
|
|||
pi list
|
||||
pi config [options]
|
||||
pi auth <check|print-api-key|print-bearer-token> [options]
|
||||
pi mcp <list|login|logout> [options]
|
||||
pi mcp <add|remove|list|login|logout> [options]
|
||||
```
|
||||
|
||||
<a id="modes"></a>
|
||||
|
|
@ -148,7 +148,7 @@ The MCP resource tools (`list_mcp_resources`, `list_mcp_resource_templates`, `re
|
|||
| `find` | Find paths using glob patterns |
|
||||
| `ls` | List directory contents |
|
||||
|
||||
Built-in extensions add two more tools. They are off by default; the MCP extension turns them on when an MCP server needs them (see [MCP](mcp.md#exposure)). To enable them yourself, name them in `--tools` or `defaultTools`.
|
||||
Built-in extensions add two more tools. They are off by default; the MCP extension turns them on when an MCP server needs them (see [MCP](mcp.md#control-tool-exposure)). To enable them yourself, name them in `--tools` or `defaultTools`.
|
||||
|
||||
| Built-in extension | Purpose |
|
||||
|---|---|
|
||||
|
|
@ -328,6 +328,6 @@ These commands work outside a session, so agents can run them through `bash`. Se
|
|||
| `pi mcp login <server> [--timeout <seconds>]` | Sign in to an OAuth server: open the authorization page and wait for the browser; a terminal also accepts the pasted redirect URL. `--timeout` limits the whole sign-in, including requests to the authorization server (default 300 seconds) |
|
||||
| `pi mcp logout <server>` | Delete the stored OAuth credentials of a server |
|
||||
|
||||
`add` and `remove` change `~/.pi/agent/mcp.json`, or `.pi/mcp.json` in the current directory with `--local` (`-l`). `add` also takes `--exposure <mode>` (see [Exposure](mcp.md#exposure)) and `--description <text>` and does not connect; run `pi mcp list` to check the server.
|
||||
`add` and `remove` change `~/.pi/agent/mcp.json`, or `.pi/mcp.json` in the current directory with `--local` (`-l`). `add` also takes `--exposure <mode>` (see [Exposure](mcp.md#control-tool-exposure)) and `--description <text>` and does not connect; run `pi mcp list` to check the server.
|
||||
|
||||
Project `.pi/mcp.json` files are only read for projects that are already trusted.
|
||||
|
|
|
|||
|
|
@ -88,6 +88,7 @@ These variables are read by Pi itself:
|
|||
| `PI_CACHE_RETENTION` | Set to `long` for extended provider prompt caching where supported |
|
||||
| `PI_SHARE_VIEWER_URL` | Override the base URL used by `/share` |
|
||||
| `PI_RADIUS_GATEWAY` | Override the Radius gateway origin used by `/bug` uploads |
|
||||
| `PI_CLEAR_ON_SHRINK` | Set to `1` to clear empty rows when rendered content shrinks; the `terminal.clearOnShrink` setting takes precedence. See [Settings](settings.md) |
|
||||
| `PI_HARDWARE_CURSOR` | Set to `1` to show the hardware cursor; see [Terminal setup](terminal-setup.md) |
|
||||
| `PI_CLIPBOARD_OSC52` | Set to `1` to also send copied text to the terminal with OSC 52 after the local clipboard write, as Pi does over SSH. Use it when a remote client reaches Pi without SSH variables, such as a multiplexer attached from another machine or a remote IDE daemon |
|
||||
| `PI_HYPERLINKS` | Override OSC 8 hyperlink detection with `1`, `0`, or `auto` |
|
||||
|
|
|
|||
|
|
@ -315,7 +315,7 @@ pi.unregisterMcpServer("jira");
|
|||
|
||||
Servers registered while the extension loads connect when the session starts, together with the `mcp.json` servers; servers registered later connect right away, and `pi.unregisterMcpServer()` closes the connection and makes the server's tools unreachable. Registrations are not saved: register again on every load, for example based on the extension's own settings. A server in `mcp.json` with the same name takes precedence, and `/mcp` shows the override. Registering the same name again replaces the extension's earlier registration; names registered by another extension, invalid names, and invalid configs throw.
|
||||
|
||||
The built-in MCP support connects registered servers. When nothing does, because another extension replaced it (see [MCP](mcp.md#other-mcp-extensions)), each registration is reported as an extension error. Other MCP extensions can connect registered servers too: read them with `pi.getMcpServers()` on `session_start` and handle the `mcp_servers_change` event for later changes.
|
||||
The built-in MCP support connects registered servers. When nothing does, because another extension replaced it (see [MCP](mcp.md#replace-the-built-in-mcp-support)), each registration is reported as an extension error. Other MCP extensions can connect registered servers too: read them with `pi.getMcpServers()` on `session_start` and handle the `mcp_servers_change` event for later changes.
|
||||
|
||||
<a id="extensioncontext"></a>
|
||||
<a id="extensioncommandcontext"></a>
|
||||
|
|
|
|||
|
|
@ -105,7 +105,7 @@ See [Compaction Reference](compaction.md) for trigger, summarization, and valida
|
|||
| `showHardwareCursor` | boolean | `false` | Use the terminal cursor instead of Pi's drawn cursor. Pi still positions it for input methods. |
|
||||
| `terminal.showImages` | boolean | `true` | Display inline images when supported. |
|
||||
| `terminal.imageWidthCells` | number | `60` | Preferred inline image width in terminal cells. |
|
||||
| `terminal.clearOnShrink` | boolean | `false` | Clear empty rows when rendered content shrinks. |
|
||||
| `terminal.clearOnShrink` | boolean | `false` | Clear empty rows when rendered content shrinks. When unset, `PI_CLEAR_ON_SHRINK=1` enables it. |
|
||||
| `terminal.showTerminalProgress` | boolean | `false` | Show OSC 9;4 progress in the terminal tab. |
|
||||
| `terminal.hyperlinks` | `boolean \| "auto"` | `"auto"` | Override OSC 8 hyperlink detection. |
|
||||
| `terminal.images` | `"kitty" \| "iterm2" \| "auto" \| false` | `"auto"` | Override inline-image protocol detection. |
|
||||
|
|
@ -123,8 +123,8 @@ See [Themes](themes.md) and [Terminal Setup](terminal-setup.md) for format and p
|
|||
|---|---|---|---|
|
||||
| `transport` | `"auto" \| "sse" \| "websocket" \| "websocket-cached"` | `"auto"` | Preferred transport for AI providers that support multiple transports. |
|
||||
| `httpProxy` | string | None | Proxy URL applied as `HTTP_PROXY` and `HTTPS_PROXY` for Pi-managed HTTP clients. **Can only be set in agent-directory settings.** |
|
||||
| `httpIdleTimeoutMs` | number | `300000` | HTTP header and body idle timeout in milliseconds. Set to `0` to disable. |
|
||||
| `websocketConnectTimeoutMs` | number | `15000` | WebSocket connection timeout in milliseconds. Set to `0` to disable. |
|
||||
| `httpIdleTimeoutMs` | number \| `"disabled"` | `300000` | HTTP header and body idle timeout in milliseconds. Set to `0` or `"disabled"` to disable. |
|
||||
| `websocketConnectTimeoutMs` | number \| `"disabled"` | `15000` | WebSocket connection timeout in milliseconds. Set to `0` or `"disabled"` to disable. |
|
||||
| `retry.enabled` | boolean | `true` | Enable automatic agent-level retry for transient failures. |
|
||||
| `retry.maxRetries` | number | `3` | Maximum agent-level retry attempts. |
|
||||
| `retry.baseDelayMs` | number | `2000` | Initial exponential-backoff delay in milliseconds. |
|
||||
|
|
|
|||
|
|
@ -46,6 +46,7 @@ Review a session before exporting or sharing it. Sessions can contain prompts, t
|
|||
| Command | Description |
|
||||
|---|---|
|
||||
| `/trust` | Save a project trust decision for future Pi processes |
|
||||
| `/mcp` | Manage MCP servers: sign in, reconnect, enable or disable, and change exposure |
|
||||
| `/reload` | Reload keybindings, extensions, skills, templates, themes, and context files |
|
||||
| `/hotkeys` | Show active keyboard shortcuts |
|
||||
| `/changelog` | Show changelog entries |
|
||||
|
|
|
|||
|
|
@ -294,7 +294,7 @@ ${chalk.bold("Commands:")}
|
|||
${APP_NAME} list List installed extensions from settings
|
||||
${APP_NAME} config [-l] Open TUI to enable/disable package resources (Tab switches scope)
|
||||
${APP_NAME} auth <command> Print credentials or check provider readiness
|
||||
${APP_NAME} mcp <command> Check MCP servers, sign in to or out of OAuth servers
|
||||
${APP_NAME} mcp <command> Manage MCP servers
|
||||
${APP_NAME} <command> --help Show help for install/remove/uninstall/update/list/config/auth/mcp
|
||||
|
||||
${chalk.bold("Options:")}
|
||||
|
|
@ -334,7 +334,7 @@ ${chalk.bold("Options:")}
|
|||
--use-theme <name[/name]> Set the initial interactive theme for this run
|
||||
--no-themes Disable theme discovery and loading
|
||||
--no-context-files, -nc Disable AGENTS.md and CLAUDE.md discovery and loading
|
||||
--export <file> Export session file to HTML and exit
|
||||
--export <file> [output] Export session file to HTML and exit
|
||||
--list-models [search] List available models (with optional fuzzy search)
|
||||
--verbose Force verbose startup (overrides quietStartup setting)
|
||||
--tui-mode <mode> TUI mode: fullscreen (default) or regular
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue