pi-codex-search 0.1.1 → 0.1.2

package/README.md

@@ -3,90 +3,223 @@
 [![npm](https://img.shields.io/npm/v/pi-codex-search)](https://www.npmjs.com/package/pi-codex-search)
 [![license](https://img.shields.io/npm/l/pi-codex-search)](./LICENSE)
 
-Pi extension that adds a `web_search` tool backed by the ChatGPT Codex backend.
+**Search the web in Pi through your Codex subscription.**
 
-It reuses the `openai-codex` subscription already configured in pi-coding-agent. The extension does not read `ACCESS_TOKEN` during normal pi usage and does not start a separate login flow.
+Pi keeps the harness small. Codex already has a ChatGPT-backed search path. This package connects the two: it adds a `codex_search` tool to Pi and uses the same `openai-codex` login Pi already knows about.
+
+No `ACCESS_TOKEN` env var. No separate login flow. If Pi can use your Codex subscription, this extension can use the same auth.
+
+## Why this exists
+
+Web search does not have to be built into Pi. It can be a tool.
+
+This extension is for Pi workflows that need fresh or source-backed information:
+
+- **Look up current docs and release notes.** Ask the model to check things that changed after its training cutoff.
+- **Get sources with the answer.** Search results include citations when Codex returns them.
+- **Reuse your Codex login.** The tool uses Pi's existing `openai-codex` OAuth credential instead of asking you to paste tokens.
+- **Batch related searches.** One tool call can run up to five related queries in parallel and return the results grouped by query.
+- **Keep projects in control.** Rename the tool, change defaults, or disable it per project.
+
+## What this package adds
+
+- A `codex_search` Pi tool.
+- 1–5 search queries per call, run in parallel.
+- `live` or `cached` freshness, plus `low` / `medium` / `high` search context size.
+- Streaming progress while Codex responds.
+- Collapsed result previews in the TUI, with full text and sources available when expanded.
+- Structured details: model, citations, search calls, response ids, usage, and per-query failures.
+- Config files for home and project defaults.
+- `/codex-search-settings` for status, editing, reset, rename, and disable.
 
 ## Install
 
-Local checkout:
+From npm:
+
+```bash
+pi install npm:pi-codex-search
+```
+
+Or load a local checkout without installing:
 
 ```bash
 pi -e /path/to/pi-codex-search
 ```
 
-After publishing, the package can be installed through pi's npm package path:
+### Install from GitHub Release tarball
+
+If you prefer not to use npm, download the tarball from the [latest release](https://github.com/Leechael/pi-codex-search/releases/latest), extract it, and install from the local path:
 
 ```bash
-pi install npm:pi-codex-search
+curl -L https://github.com/Leechael/pi-codex-search/releases/latest/download/pi-codex-search.tar.gz | tar -xz -C /tmp
+pi install /tmp/pi-codex-search
 ```
 
-The package manifest exposes the extension through:
+## Sign in
+
+Inside Pi, run:
+
+```text
+/login openai-codex
+```
+
+Choose `ChatGPT Plus/Pro (Codex Subscription)` if Pi asks which provider to use. Pi stores and refreshes the credential.
+
+The tool is registered by default. If Pi has no `openai-codex` token, or if the ChatGPT account id cannot be found from the stored OAuth credential or decoded access token, the first `codex_search` call fails with an `auth` error that points back to `/login openai-codex`.
+
+Set `enabled: false` if you want the extension installed but hidden for a project.
+
+## Tool
+
+Default tool name:
+
+```text
+codex_search
+```
+
+Example call:
 
 ```json
 {
-  "pi": {
-    "extensions": ["./index.ts"]
+  "name": "codex_search",
+  "arguments": {
+    "queries": ["latest OpenAI Codex release notes"],
+    "search_context_size": "medium",
+    "freshness": "live"
   }
 }
 ```
 
-## Authentication
+Arguments:
+
+- `queries` — required array of 1–5 search questions. Queries run in parallel; results are grouped by query.
+- `search_context_size` — optional, one of `low`, `medium`, `high`; defaults to `medium`.
+- `freshness` — optional, `live` or `cached`; defaults to `live`.
+
+The tool returns text. When citations are available, the text includes a `Sources:` section.
+
+The structured `details` object includes:
+
+- `model`
+- `freshness` / `searchContextSize`
+- `queryCount` / `failedQueryCount`
+- `successes`: per-query `{ query, text, citations, searchCalls, responseId?, usage? }`
+- `failures`: per-query `{ query, kind, message }`
+
+Failure `kind` is one of `auth`, `rate_limit`, `transport`, `timeout`, `schema`, or `unknown`.
+
+## Model used for search
+
+The search request needs a Codex model id. The extension chooses it in this order:
+
+1. `model` from env / project / home config, if set.
+2. The active Pi model, if it comes from the `openai-codex` provider.
+3. The default model from Codex's `/codex/models` response.
 
-Inside `pi`, run:
+Most users do not need to set this.
+
+## Settings
+
+Most users only need `/login openai-codex`. Use settings when you want to rename the tool, disable it for a project, pin a model, or change defaults.
+
+Open the interactive settings dialog:
 
 ```text
-/login openai-codex
+/codex-search-settings
+```
+
+Useful subcommands:
+
+```text
+/codex-search-settings status
+/codex-search-settings reset
 ```
 
-Choose `ChatGPT Plus/Pro (Codex Subscription)` if pi prompts for a provider. Credentials are stored in pi's auth file and refreshed by pi.
+Settings are merged from three layers, highest precedence first:
 
-At `session_start`, this extension calls `ctx.modelRegistry.getApiKeyForProvider("openai-codex")`. If no token is available, or if the account id cannot be found from the stored OAuth credential or decoded access token, it does not register `web_search`. In that case the model will not see the tool.
+1. Environment variables.
+2. Project file: `<cwd>/.pi/pi-codex-search.json`.
+3. Home file: `~/.pi/pi-codex-search.json`.
 
-## Usage
+Each layer is optional. Missing files are skipped. Malformed JSON or invalid values fail fast so you do not silently run with the wrong tool settings.
 
-When Codex auth is available at session start, the extension registers:
+Full schema, all fields optional:
 
 ```json
 {
-  "name": "web_search",
-  "arguments": {
-    "query": "latest OpenAI Codex release notes",
-    "search_context_size": "medium",
-    "live": true
-  }
+  "enabled": true,
+  "toolName": "codex_search",
+  "model": "gpt-5-codex",
+  "baseUrl": "https://chatgpt.com/backend-api",
+  "clientVersion": "1.0.0",
+  "searchContextSize": "medium",
+  "freshness": "live"
 }
 ```
 
-Parameters:
+`enabled: false` skips tool registration entirely. The model will not see `codex_search` at all.
 
-- `query`: required search question.
-- `search_context_size`: optional, one of `low`, `medium`, `high`.
-- `live`: optional boolean. Defaults to live web access.
+`toolName` lets you avoid conflicts with another extension. Tool names must match `[a-zA-Z_][a-zA-Z0-9_]{0,63}`.
 
-Model selection:
+Environment variable equivalents:
 
-- If `PI_CODEX_WEB_SEARCH_MODEL` is set, that model id is used.
-- Otherwise, if the active pi model provider is `openai-codex`, the active model id is used.
-- Otherwise, the extension fetches `/codex/models?client_version=...` and uses the default model from that response.
+| Field               | Env var                              |
+| ------------------- | ------------------------------------ |
+| `enabled`           | `PI_CODEX_WEB_SEARCH_ENABLED`        |
+| `toolName`          | `PI_CODEX_WEB_SEARCH_TOOL_NAME`      |
+| `model`             | `PI_CODEX_WEB_SEARCH_MODEL`          |
+| `baseUrl`           | `PI_CODEX_WEB_SEARCH_BASE_URL`       |
+| `clientVersion`     | `PI_CODEX_WEB_SEARCH_CLIENT_VERSION` |
+| `searchContextSize` | `PI_CODEX_WEB_SEARCH_CONTEXT_SIZE`   |
+| `freshness`         | `PI_CODEX_WEB_SEARCH_FRESHNESS`      |
 
-The tool returns text content. Its structured `details` include:
+`PI_CODEX_WEB_SEARCH_ENABLED` accepts `true` / `false` (case-insensitive). Any other value fails config loading.
 
-- `model`
-- `responseId`
-- `searchCalls`
-- `citations`
-- `usage`
+Interactive edits write the selected config file immediately. When you close the dialog, Pi reloads so the new tool name and defaults apply without restarting the whole terminal.
+
+## Notes
+
+### Codex search vs model search
+
+This does not add browsing to the model provider itself. It adds a Pi tool. The model decides when to call `codex_search`, just like any other tool.
+
+### Account id
+
+Codex requests need both the access token and the ChatGPT account id. The extension first checks Pi's stored OAuth credential. If that does not include an account id, it tries to extract one from the access token.
+
+## Troubleshooting
+
+### `codex_search` fails with an `auth` error
+
+Run:
 
-## Configuration
+```text
+/login openai-codex
+```
+
+If Pi asks for a provider, choose `ChatGPT Plus/Pro (Codex Subscription)`. The extension picks up the refreshed credential on the next call.
+
+### `codex_search` says the account id was not found
+
+The stored OAuth credential did not include an account id, and the extension could not decode one from the access token. Re-run `/login openai-codex` so Pi refreshes the credential.
+
+### The model does not see `codex_search`
+
+Check whether `enabled` is false in env, project config, or home config:
+
+```text
+/codex-search-settings status
+```
+
+Remember that env overrides project, and project overrides home.
+
+### Search uses the wrong model
 
-- `PI_CODEX_WEB_SEARCH_MODEL`: override the Codex model used by the tool.
-- `PI_CODEX_WEB_SEARCH_BASE_URL`: override the Codex backend base URL.
-- `PI_CODEX_WEB_SEARCH_CLIENT_VERSION`: override the `client_version` sent to `/codex/models`.
-- `PI_CODEX_WEB_SEARCH_CONTEXT_SIZE`: default search context size: `low`, `medium`, or `high`.
-- `PI_CODEX_WEB_SEARCH_LIVE`: set to `false` to use cached web access.
+Set `model` in your config file, or set `PI_CODEX_WEB_SEARCH_MODEL`, to the Codex model id you want. If unset, the extension uses the active Codex model when possible, then falls back to the default model from `/codex/models`.
 
-The request headers are built by the extension. They include `Authorization`, `chatgpt-account-id`, `originator: pi`, `OpenAI-Beta: responses=experimental`, `accept`, and `content-type` for streaming response requests.
+### A different extension already registers `codex_search`
+
+Use `/codex-search-settings` to rename this extension's tool, or set `toolName` in `~/.pi/pi-codex-search.json`. Tool renames apply after the settings dialog reloads Pi.
 
 ## Development
 
@@ -107,16 +240,9 @@ This repository follows the same release shape as `pi-provider-kimi-code`:
 - `.github/workflows/release-command.yml` creates release commits and tags.
 - `.github/workflows/release-on-tag.yml` publishes to npm with provenance and attaches `pi-codex-search.tar.gz` to the GitHub release.
 
-GitHub release tarball installs from the extracted directory:
-
-```bash
-curl -L https://github.com/Leechael/pi-codex-search/releases/latest/download/pi-codex-search.tar.gz | tar -xz -C /tmp
-pi install /tmp/pi-codex-search
-```
-
 ## References
 
-- Upstream harness: [earendil-works/pi](https://github.com/earendil-works/pi) · [pi-coding-agent](https://github.com/earendil-works/pi/tree/main/packages/coding-agent)
+- Pi: [earendil-works/pi](https://github.com/earendil-works/pi)
 
 ## License