pidriver 0.0.2__tar.gz → 0.2.0__tar.gz

{pidriver-0.0.2 → pidriver-0.2.0}/.gitignore

@@ -28,3 +28,6 @@ uv.lock
 .pi/
 *.jsonl
 scratch/
+
+# Secrets (PyPI token, etc.)
+.env

pidriver-0.2.0/.sc/last-chat-settings.json

@@ -0,0 +1,4 @@
+{
+  "provider_key": "codex",
+  "reasoning_effort": "high"
+}

{pidriver-0.0.2 → pidriver-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pidriver
-Version: 0.0.2
+Version: 0.2.0
 Summary: Async Python driver for the pi coding agent (pi --mode rpc), built for isolated, headless project work.
 Project-URL: Homepage, https://github.com/bobuk/pidriver
 Project-URL: Repository, https://github.com/bobuk/pidriver
@@ -28,9 +28,10 @@ Async Python driver for the pi coding agent, built for **isolated, headless proj
 drives any `pi`-compatible CLI in `--mode rpc` over its JSONL stdin/stdout protocol and exposes a
 small, typed Python API — with no third-party dependencies.
 
-The recommended CLI is [**oh-my-pi**](https://bun.sh) (the `omp` binary); the original
-[`pi`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) also works. Which one runs
-is just a `PiConfig` field (`binary`), so the same code drives either.
+The default CLI is upstream [**pi**](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
+(the `pi` binary); the [oh-my-pi](https://github.com/can1357/oh-my-pi) fork (`omp`) also works (set
+`binary="omp"`, `mode="rpc-ui"`). Which one runs is just a `PiConfig` field, so the same code drives
+either.
 
 Embed an agent inside another application (a chat bot, a scheduler, a service) and have it
 develop a project autonomously, in an environment that is **isolated** from your personal pi
@@ -41,18 +42,11 @@ handling; drop to the [raw transport](#transport) only when you need it.
 
 ## Requirements
 
-- Python **3.12+**
-- A `pi`-compatible CLI on `PATH`. Recommended — **oh-my-pi** (the `omp` binary) via
-  [Bun](https://bun.sh), or the official installer:
-
-  ```sh
-  bun install -g @oh-my-pi/pi-coding-agent   # provides the `omp` binary
-  # or: curl -fsSL https://omp.sh/install | sh
-  omp --version
-  ```
-
-  The original `pi` CLI works too: `npm i -g @earendil-works/pi-coding-agent`. Tell `PiConfig`
-  which one to launch with `binary` (`"omp"` or `"pi"`); they share the `--mode rpc` protocol.
+- Python **3.12+** (no third-party runtime deps).
+- A `pi`-compatible CLI — but you usually **don't install one manually**: pidriver can
+  [auto-install](#auto-install) upstream `pi` via `npm` on first use (requires Node ≥22.19 + npm).
+  To use an existing CLI instead, put `pi` (or `omp`) on `PATH`, or point `PiConfig.binary` /
+  `install_dir` at it.
 - A provider API key — passed explicitly through `PiConfig`, see [Isolation](#isolation).
 
 ## Install
@@ -73,8 +67,7 @@ from pidriver import PiClient, PiConfig, AutoApprove, MessageDelta, ToolStart, A
 
 async def main():
     client = PiClient(PiConfig(
-        binary="omp",             # which CLI to launch (oh-my-pi); "pi" also works
-        provider="openai",
+        provider="openai",        # binary defaults to upstream "pi" (--mode rpc)
         model="gpt-4o",
         api_key=os.environ["OPENAI_API_KEY"],
         # Isolation defaults (scrubbed env, no host extensions/skills) are already on.
@@ -144,13 +137,24 @@ PiConfig(provider="anthropic", model="claude-sonnet-4-6",
          api_key="sk-...", workspace="/path/to/project")
 ```
 
-**Binary & workspace**
+**Binary, mode & workspace**
 
 | Field | Default | Purpose |
 | --- | --- | --- |
 | `binary` | `"pi"` | Which `pi`-compatible CLI to launch — set to `"omp"` for oh-my-pi. |
+| `mode` | `"rpc"` | Output mode → `--mode`. Upstream pi accepts `text`/`json`/`rpc`; `rpc` is the JSONL protocol this driver speaks. (`rpc-ui` is omp-only — set it explicitly when `binary="omp"`.) |
 | `workspace` | `None` | Project directory; becomes the subprocess `cwd`. |
 
+**Binary auto-install** — see [Auto-install](#auto-install).
+
+| Field | Default | Purpose |
+| --- | --- | --- |
+| `install_dir` | `None` | Where to `npm install`/look for a managed `pi` binary. |
+| `auto_install` | `True` | `npm install` `pi` into `install_dir` if the binary can't be resolved. |
+| `npm_package` | `"@earendil-works/pi-coding-agent"` | The npm package that provides `pi`. |
+| `pi_version` | `"0.78.1"` | Pinned pi version to install (overridable). |
+| `extensions` | `()` | Add-on sources (`npm:…`, `git:…`, path) installed via `pi install` before start. |
+
 **Model / provider**
 
 | Field | Default | Purpose |
@@ -164,22 +168,27 @@ PiConfig(provider="anthropic", model="claude-sonnet-4-6",
 Prefer a **fully-qualified** `model` id (e.g. `openai/gpt-4o`, `anthropic/claude-haiku-4-5`) —
 bare fuzzy names can mis-route to the wrong backend.
 
+**Approvals** — `auto_approve` (`--auto-approve`, run tools without asking), `approval_mode`
+(`--approval-mode <mode>`, e.g. `"always-ask"`). Leave both unset to let your
+[`InteractionHandler`](#answering-the-agent) decide.
+
 **Tools** — `tools` (`--tools` allowlist), `exclude_tools` (`--exclude-tools`), `no_tools`,
 `no_builtin_tools`.
 
 **Session** — `session` (False → `--no-session`), `session_id`, `session_path` (`--session`),
-`session_name` (`--name`), `continue_session` (`--continue`), `system_prompt`,
-`append_system_prompt`.
+`session_name` (`--name`), `continue_session` (`--continue`), `system_prompt`
+(`--system-prompt`), `append_system_prompt` (`--append-system-prompt`, repeatable).
 
-**Isolation** — see [Isolation](#isolation): `agent_dir`, `session_dir`, `no_extensions`,
-`no_skills`, `no_context_files`, `no_prompt_templates`, `no_themes`, `offline`,
-`skip_version_check`, `inherit_env`, `env_passthrough`.
+**Isolation** — see [Isolation](#isolation): `home_dir`, `agent_dir`, `session_dir`,
+`package_dir`, `no_extensions`, `no_skills`, `no_context_files`, `no_prompt_templates`,
+`no_themes`, `no_mcp`, `offline`, `skip_version_check`, `telemetry`, `inherit_env`,
+`env_passthrough`.
 
 **Escape hatches** — `extra_args` (appended to argv), `extra_env` (merged into the child env).
 
 Methods:
 
-- `to_argv() -> list[str]` — full command line, starting `[binary, "--mode", "rpc", ...]`.
+- `to_argv() -> list[str]` — full command line, starting `[binary, "--mode", mode, ...]`.
 - `to_env(base_environ=None) -> dict[str, str]` — the child environment (scrubbed by default).
 - `api_key_env_name() -> str | None` — which env var `api_key` resolves to (provider-mapped via
   `PROVIDER_API_KEY_ENV`, falling back to `<PROVIDER>_API_KEY`, then `ANTHROPIC_API_KEY`).
@@ -193,32 +202,68 @@ project from reading or mutating your global pi setup:
   environment plus only `env_passthrough` (`PATH`, `HOME`, `LANG`, `LC_ALL`, `TERM`, `TZ`) — so
   a stray `*_API_KEY` in your shell never leaks into the agent. The configured `api_key` is then
   injected under exactly one provider variable.
-- **Private agent dir.** `agent_dir` sets `PI_CODING_AGENT_DIR`, pointing pi at a private config
-  directory instead of `~/.pi`, so it loads no personal extensions/skills/settings.
+- **Private `HOME`.** `home_dir` overrides `HOME` for the child. This is the **load-bearing**
+  isolation lever: omp derives its config root *and logs* from `$HOME/.omp`, so `agent_dir`
+  alone isn't enough — without `home_dir` the agent still writes logs into your real `~/.omp`
+  (verified empirically against omp 15.7.3). Set `home_dir` and your personal setup stays
+  byte-for-byte untouched.
+- **Private state dirs.** `agent_dir` → `PI_CODING_AGENT_DIR` (config/extensions/skills),
+  `session_dir` → `PI_CODING_AGENT_SESSION_DIR` (session `.jsonl`s), `package_dir` →
+  `PI_PACKAGE_DIR` (installed packages) — each points pi at a private location instead of the
+  defaults under `~/.omp`.
 - **No host discovery** (all default **True**): `no_extensions`, `no_skills`,
   `no_context_files`, `no_prompt_templates`, `no_themes` give a clean, reproducible agent.
-- **Separate session storage.** `session_dir` (`--session-dir`) keeps session `.jsonl` files out
-  of the default location.
-- `offline` (`--offline` + `PI_OFFLINE=1`) and `skip_version_check` (`PI_SKIP_VERSION_CHECK=1`,
-  default True) round out a hermetic run.
+- **No MCP autoconnect** (`no_mcp=True`, default). Under `rpc-ui` the agent otherwise
+  auto-connects MCP servers it finds in the environment; `no_mcp` strips those trigger vars.
+- `offline` (`--offline` + `PI_OFFLINE=1`), `skip_version_check` (`PI_SKIP_VERSION_CHECK=1`,
+  default True) and `telemetry=False` (`PI_TELEMETRY=0`) round out a hermetic run.
 
 ```python
+home = Path("/var/lib/myapp/pi")
 cfg = PiConfig(
-    provider="anthropic", model="claude-sonnet-4-6", api_key=KEY,
+    provider="anthropic", model="anthropic/claude-haiku-4-5", api_key=KEY,
     workspace="/srv/projects/acme",
-    agent_dir="/var/lib/myapp/pi-home",     # private ~/.pi replacement
-    session_dir="/var/lib/myapp/pi-sessions",
-    extra_env={"HOME": "/var/lib/myapp"},   # see note below — also override HOME
-    # inherit_env=False and no_* discovery flags are already the defaults.
+    home_dir=home / "home",          # overrides $HOME — the key isolation lever
+    agent_dir=home / "agent",        # PI_CODING_AGENT_DIR
+    session_dir=home / "sessions",   # PI_CODING_AGENT_SESSION_DIR
+    package_dir=home / "packages",   # PI_PACKAGE_DIR
+    # inherit_env=False, no_* discovery, no_mcp, telemetry=False are already the defaults.
 )
 ```
 
-> **Override `HOME` for full isolation.** `agent_dir`/`PI_CODING_AGENT_DIR` alone is **not**
-> enough: omp derives its **log** root from `$HOME/.omp`, and the default `env_passthrough`
-> copies `HOME` from the host — so an agent can still write logs into your `~/.omp`. To leave
-> your personal setup byte-for-byte untouched, also point `HOME` at the private dir (via
-> `extra_env`, as above) or drop it from `env_passthrough`. (Verified empirically against
-> omp 15.7.3.)
+## Auto-install
+
+You don't have to install a CLI yourself. Upstream `pi` is an npm package, and pidriver can
+`npm install` it into a managed, isolated prefix on demand (requires **Node ≥22.19 + npm** on
+`PATH` — the `pi` bin is a Node shim, not a self-contained binary).
+
+When the transport starts, it resolves the binary in order — explicit `binary` path →
+`install_dir/bin/pi` → `PATH`. If none resolves and `auto_install=True` (default), it runs
+`npm install -g --prefix <install_dir> <npm_package>@<pi_version>` and runs `<install_dir>/bin/pi`.
+
+```python
+from pidriver import ensure_binary, install_pi, ensure_extensions  # also exported for explicit use
+```
+
+### Extensions / skills / packages
+
+Set `PiConfig.extensions` to a tuple of add-on sources and pidriver runs `pi install <source>`
+for each (into the **isolated** config dir, via `PI_CODING_AGENT_DIR`) before the agent starts —
+idempotently (sources already in the dir's `settings.json` are skipped; failures are logged, not
+fatal). Each source is one of `npm:<pkg>[@version]`, `git:github.com/<owner>/<repo>[@ref]`, an
+`https://`/`ssh://` git url, or a local `./path`. To actually load them, turn the relevant
+isolation flags off (e.g. `no_extensions=False`, `no_skills=False`).
+
+```python
+PiConfig(extensions=("npm:pi-web-access", "git:github.com/owner/repo"),
+         no_extensions=False, no_skills=False)
+```
+
+Notes:
+- First `npm install` takes a few seconds; subsequent runs reuse the managed copy.
+- Failures raise `PiInstallError` (missing npm/Node, install or version-verify failure).
+- To skip auto-install, set `auto_install=False` and provide `binary`/`install_dir` pointing at an
+  existing CLI.
 
 ## Transport
 
@@ -295,7 +340,8 @@ All exceptions derive from `PiDriverError`, so one `except` catches the family:
 | Exception | Raised when |
 | --- | --- |
 | `PiDriverError` | Base class for everything below. |
-| `PiNotFoundError` | The `pi` executable can't be found or run. |
+| `PiNotFoundError` | The `pi`/`omp` executable can't be found or run. |
+| `PiInstallError` | [Auto-install](#auto-install) failed (unsupported OS/arch, download/verify error). |
 | `PiStartError` | The `pi --mode rpc` process failed to start. |
 | `PiProtocolError` | A line from pi wasn't valid JSON / violated the contract (`.raw`). |
 | `PiCommandError` | An RPC command returned `success: false` (`.command`, `.error`, `.data`). |
@@ -476,6 +522,58 @@ handler = chain(
 )
 ```
 
+## Workspace jail
+
+Run an agent loose inside a project without letting it run anywhere on disk. `resolve_project`
+maps a user-supplied *name* to a real directory only if it is explicitly allow-listed and lives
+physically under `root` — rejecting path separators and symlink escapes.
+
+```python
+from pidriver import resolve_project, list_candidate_projects, ProjectError
+
+try:
+    cwd = resolve_project("myrepo", root=PROJECTS_ROOT, allowlist=("myrepo", "docs"))
+except ProjectError as exc:
+    ...  # empty / not allow-listed / not a dir / escapes root (incl. via symlink)
+
+# Offer a picker: every immediate sub-dir of a root, flagged git / selected.
+projects = list_candidate_projects(PROJECTS_ROOT, allowlist=("myrepo",))  # list[ProjectDir]
+```
+
+## Model discovery
+
+`list_models` runs `pi --list-models` under the same isolation env the agent uses and parses the
+table into typed `ModelInfo` rows; `parse_models` is the pure parser (handy for tests / cached
+output). When a provider is set the result is narrowed to it.
+
+```python
+from pidriver import list_models, parse_models
+
+models = await list_models(config, provider="anthropic")   # list[ModelInfo]
+for m in models:
+    print(m.id, m.context)        # "anthropic/claude-opus-4-8" "200K"
+```
+
+## Provider OAuth login
+
+Some providers authenticate via OAuth (Claude Pro/Max, Codex, …) instead of an API key. `PiOAuthLogin`
+drives a bundled Node helper that reuses pi's own `AuthStorage` (no version skew), writing
+credentials into the isolated `<agent_dir>/auth.json`. Requires `node` on PATH and a resolvable pi
+install.
+
+```python
+from pidriver import PiOAuthLogin
+
+login = PiOAuthLogin(config)                       # config.agent_dir receives auth.json
+info = await login.start("anthropic")              # {"session", "url", "instructions"}
+# user opens info["url"], authorizes, copies the code:
+await login.submit_code(info["session"], code)     # accepts a bare code or a callback URL
+```
+
+`valid_extension_source(src)` validates a `pi install` argument, and `resolve_node_modules(config)`
+locates pi's bundled Node libraries (package identity from `config.npm_package`, so the omp fork
+works too) — both exported for hosts building their own extension/auth tooling.
+
 ## Development
 
 ```sh

{pidriver-0.0.2 → pidriver-0.2.0}/README.md

@@ -4,9 +4,10 @@ Async Python driver for the pi coding agent, built for **isolated, headless proj
 drives any `pi`-compatible CLI in `--mode rpc` over its JSONL stdin/stdout protocol and exposes a
 small, typed Python API — with no third-party dependencies.
 
-The recommended CLI is [**oh-my-pi**](https://bun.sh) (the `omp` binary); the original
-[`pi`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) also works. Which one runs
-is just a `PiConfig` field (`binary`), so the same code drives either.
+The default CLI is upstream [**pi**](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
+(the `pi` binary); the [oh-my-pi](https://github.com/can1357/oh-my-pi) fork (`omp`) also works (set
+`binary="omp"`, `mode="rpc-ui"`). Which one runs is just a `PiConfig` field, so the same code drives
+either.
 
 Embed an agent inside another application (a chat bot, a scheduler, a service) and have it
 develop a project autonomously, in an environment that is **isolated** from your personal pi
@@ -17,18 +18,11 @@ handling; drop to the [raw transport](#transport) only when you need it.
 
 ## Requirements
 
-- Python **3.12+**
-- A `pi`-compatible CLI on `PATH`. Recommended — **oh-my-pi** (the `omp` binary) via
-  [Bun](https://bun.sh), or the official installer:
-
-  ```sh
-  bun install -g @oh-my-pi/pi-coding-agent   # provides the `omp` binary
-  # or: curl -fsSL https://omp.sh/install | sh
-  omp --version
-  ```
-
-  The original `pi` CLI works too: `npm i -g @earendil-works/pi-coding-agent`. Tell `PiConfig`
-  which one to launch with `binary` (`"omp"` or `"pi"`); they share the `--mode rpc` protocol.
+- Python **3.12+** (no third-party runtime deps).
+- A `pi`-compatible CLI — but you usually **don't install one manually**: pidriver can
+  [auto-install](#auto-install) upstream `pi` via `npm` on first use (requires Node ≥22.19 + npm).
+  To use an existing CLI instead, put `pi` (or `omp`) on `PATH`, or point `PiConfig.binary` /
+  `install_dir` at it.
 - A provider API key — passed explicitly through `PiConfig`, see [Isolation](#isolation).
 
 ## Install
@@ -49,8 +43,7 @@ from pidriver import PiClient, PiConfig, AutoApprove, MessageDelta, ToolStart, A
 
 async def main():
     client = PiClient(PiConfig(
-        binary="omp",             # which CLI to launch (oh-my-pi); "pi" also works
-        provider="openai",
+        provider="openai",        # binary defaults to upstream "pi" (--mode rpc)
         model="gpt-4o",
         api_key=os.environ["OPENAI_API_KEY"],
         # Isolation defaults (scrubbed env, no host extensions/skills) are already on.
@@ -120,13 +113,24 @@ PiConfig(provider="anthropic", model="claude-sonnet-4-6",
          api_key="sk-...", workspace="/path/to/project")
 ```
 
-**Binary & workspace**
+**Binary, mode & workspace**
 
 | Field | Default | Purpose |
 | --- | --- | --- |
 | `binary` | `"pi"` | Which `pi`-compatible CLI to launch — set to `"omp"` for oh-my-pi. |
+| `mode` | `"rpc"` | Output mode → `--mode`. Upstream pi accepts `text`/`json`/`rpc`; `rpc` is the JSONL protocol this driver speaks. (`rpc-ui` is omp-only — set it explicitly when `binary="omp"`.) |
 | `workspace` | `None` | Project directory; becomes the subprocess `cwd`. |
 
+**Binary auto-install** — see [Auto-install](#auto-install).
+
+| Field | Default | Purpose |
+| --- | --- | --- |
+| `install_dir` | `None` | Where to `npm install`/look for a managed `pi` binary. |
+| `auto_install` | `True` | `npm install` `pi` into `install_dir` if the binary can't be resolved. |
+| `npm_package` | `"@earendil-works/pi-coding-agent"` | The npm package that provides `pi`. |
+| `pi_version` | `"0.78.1"` | Pinned pi version to install (overridable). |
+| `extensions` | `()` | Add-on sources (`npm:…`, `git:…`, path) installed via `pi install` before start. |
+
 **Model / provider**
 
 | Field | Default | Purpose |
@@ -140,22 +144,27 @@ PiConfig(provider="anthropic", model="claude-sonnet-4-6",
 Prefer a **fully-qualified** `model` id (e.g. `openai/gpt-4o`, `anthropic/claude-haiku-4-5`) —
 bare fuzzy names can mis-route to the wrong backend.
 
+**Approvals** — `auto_approve` (`--auto-approve`, run tools without asking), `approval_mode`
+(`--approval-mode <mode>`, e.g. `"always-ask"`). Leave both unset to let your
+[`InteractionHandler`](#answering-the-agent) decide.
+
 **Tools** — `tools` (`--tools` allowlist), `exclude_tools` (`--exclude-tools`), `no_tools`,
 `no_builtin_tools`.
 
 **Session** — `session` (False → `--no-session`), `session_id`, `session_path` (`--session`),
-`session_name` (`--name`), `continue_session` (`--continue`), `system_prompt`,
-`append_system_prompt`.
+`session_name` (`--name`), `continue_session` (`--continue`), `system_prompt`
+(`--system-prompt`), `append_system_prompt` (`--append-system-prompt`, repeatable).
 
-**Isolation** — see [Isolation](#isolation): `agent_dir`, `session_dir`, `no_extensions`,
-`no_skills`, `no_context_files`, `no_prompt_templates`, `no_themes`, `offline`,
-`skip_version_check`, `inherit_env`, `env_passthrough`.
+**Isolation** — see [Isolation](#isolation): `home_dir`, `agent_dir`, `session_dir`,
+`package_dir`, `no_extensions`, `no_skills`, `no_context_files`, `no_prompt_templates`,
+`no_themes`, `no_mcp`, `offline`, `skip_version_check`, `telemetry`, `inherit_env`,
+`env_passthrough`.
 
 **Escape hatches** — `extra_args` (appended to argv), `extra_env` (merged into the child env).
 
 Methods:
 
-- `to_argv() -> list[str]` — full command line, starting `[binary, "--mode", "rpc", ...]`.
+- `to_argv() -> list[str]` — full command line, starting `[binary, "--mode", mode, ...]`.
 - `to_env(base_environ=None) -> dict[str, str]` — the child environment (scrubbed by default).
 - `api_key_env_name() -> str | None` — which env var `api_key` resolves to (provider-mapped via
   `PROVIDER_API_KEY_ENV`, falling back to `<PROVIDER>_API_KEY`, then `ANTHROPIC_API_KEY`).
@@ -169,32 +178,68 @@ project from reading or mutating your global pi setup:
   environment plus only `env_passthrough` (`PATH`, `HOME`, `LANG`, `LC_ALL`, `TERM`, `TZ`) — so
   a stray `*_API_KEY` in your shell never leaks into the agent. The configured `api_key` is then
   injected under exactly one provider variable.
-- **Private agent dir.** `agent_dir` sets `PI_CODING_AGENT_DIR`, pointing pi at a private config
-  directory instead of `~/.pi`, so it loads no personal extensions/skills/settings.
+- **Private `HOME`.** `home_dir` overrides `HOME` for the child. This is the **load-bearing**
+  isolation lever: omp derives its config root *and logs* from `$HOME/.omp`, so `agent_dir`
+  alone isn't enough — without `home_dir` the agent still writes logs into your real `~/.omp`
+  (verified empirically against omp 15.7.3). Set `home_dir` and your personal setup stays
+  byte-for-byte untouched.
+- **Private state dirs.** `agent_dir` → `PI_CODING_AGENT_DIR` (config/extensions/skills),
+  `session_dir` → `PI_CODING_AGENT_SESSION_DIR` (session `.jsonl`s), `package_dir` →
+  `PI_PACKAGE_DIR` (installed packages) — each points pi at a private location instead of the
+  defaults under `~/.omp`.
 - **No host discovery** (all default **True**): `no_extensions`, `no_skills`,
   `no_context_files`, `no_prompt_templates`, `no_themes` give a clean, reproducible agent.
-- **Separate session storage.** `session_dir` (`--session-dir`) keeps session `.jsonl` files out
-  of the default location.
-- `offline` (`--offline` + `PI_OFFLINE=1`) and `skip_version_check` (`PI_SKIP_VERSION_CHECK=1`,
-  default True) round out a hermetic run.
+- **No MCP autoconnect** (`no_mcp=True`, default). Under `rpc-ui` the agent otherwise
+  auto-connects MCP servers it finds in the environment; `no_mcp` strips those trigger vars.
+- `offline` (`--offline` + `PI_OFFLINE=1`), `skip_version_check` (`PI_SKIP_VERSION_CHECK=1`,
+  default True) and `telemetry=False` (`PI_TELEMETRY=0`) round out a hermetic run.
 
 ```python
+home = Path("/var/lib/myapp/pi")
 cfg = PiConfig(
-    provider="anthropic", model="claude-sonnet-4-6", api_key=KEY,
+    provider="anthropic", model="anthropic/claude-haiku-4-5", api_key=KEY,
     workspace="/srv/projects/acme",
-    agent_dir="/var/lib/myapp/pi-home",     # private ~/.pi replacement
-    session_dir="/var/lib/myapp/pi-sessions",
-    extra_env={"HOME": "/var/lib/myapp"},   # see note below — also override HOME
-    # inherit_env=False and no_* discovery flags are already the defaults.
+    home_dir=home / "home",          # overrides $HOME — the key isolation lever
+    agent_dir=home / "agent",        # PI_CODING_AGENT_DIR
+    session_dir=home / "sessions",   # PI_CODING_AGENT_SESSION_DIR
+    package_dir=home / "packages",   # PI_PACKAGE_DIR
+    # inherit_env=False, no_* discovery, no_mcp, telemetry=False are already the defaults.
 )
 ```
 
-> **Override `HOME` for full isolation.** `agent_dir`/`PI_CODING_AGENT_DIR` alone is **not**
-> enough: omp derives its **log** root from `$HOME/.omp`, and the default `env_passthrough`
-> copies `HOME` from the host — so an agent can still write logs into your `~/.omp`. To leave
-> your personal setup byte-for-byte untouched, also point `HOME` at the private dir (via
-> `extra_env`, as above) or drop it from `env_passthrough`. (Verified empirically against
-> omp 15.7.3.)
+## Auto-install
+
+You don't have to install a CLI yourself. Upstream `pi` is an npm package, and pidriver can
+`npm install` it into a managed, isolated prefix on demand (requires **Node ≥22.19 + npm** on
+`PATH` — the `pi` bin is a Node shim, not a self-contained binary).
+
+When the transport starts, it resolves the binary in order — explicit `binary` path →
+`install_dir/bin/pi` → `PATH`. If none resolves and `auto_install=True` (default), it runs
+`npm install -g --prefix <install_dir> <npm_package>@<pi_version>` and runs `<install_dir>/bin/pi`.
+
+```python
+from pidriver import ensure_binary, install_pi, ensure_extensions  # also exported for explicit use
+```
+
+### Extensions / skills / packages
+
+Set `PiConfig.extensions` to a tuple of add-on sources and pidriver runs `pi install <source>`
+for each (into the **isolated** config dir, via `PI_CODING_AGENT_DIR`) before the agent starts —
+idempotently (sources already in the dir's `settings.json` are skipped; failures are logged, not
+fatal). Each source is one of `npm:<pkg>[@version]`, `git:github.com/<owner>/<repo>[@ref]`, an
+`https://`/`ssh://` git url, or a local `./path`. To actually load them, turn the relevant
+isolation flags off (e.g. `no_extensions=False`, `no_skills=False`).
+
+```python
+PiConfig(extensions=("npm:pi-web-access", "git:github.com/owner/repo"),
+         no_extensions=False, no_skills=False)
+```
+
+Notes:
+- First `npm install` takes a few seconds; subsequent runs reuse the managed copy.
+- Failures raise `PiInstallError` (missing npm/Node, install or version-verify failure).
+- To skip auto-install, set `auto_install=False` and provide `binary`/`install_dir` pointing at an
+  existing CLI.
 
 ## Transport
 
@@ -271,7 +316,8 @@ All exceptions derive from `PiDriverError`, so one `except` catches the family:
 | Exception | Raised when |
 | --- | --- |
 | `PiDriverError` | Base class for everything below. |
-| `PiNotFoundError` | The `pi` executable can't be found or run. |
+| `PiNotFoundError` | The `pi`/`omp` executable can't be found or run. |
+| `PiInstallError` | [Auto-install](#auto-install) failed (unsupported OS/arch, download/verify error). |
 | `PiStartError` | The `pi --mode rpc` process failed to start. |
 | `PiProtocolError` | A line from pi wasn't valid JSON / violated the contract (`.raw`). |
 | `PiCommandError` | An RPC command returned `success: false` (`.command`, `.error`, `.data`). |
@@ -452,6 +498,58 @@ handler = chain(
 )
 ```
 
+## Workspace jail
+
+Run an agent loose inside a project without letting it run anywhere on disk. `resolve_project`
+maps a user-supplied *name* to a real directory only if it is explicitly allow-listed and lives
+physically under `root` — rejecting path separators and symlink escapes.
+
+```python
+from pidriver import resolve_project, list_candidate_projects, ProjectError
+
+try:
+    cwd = resolve_project("myrepo", root=PROJECTS_ROOT, allowlist=("myrepo", "docs"))
+except ProjectError as exc:
+    ...  # empty / not allow-listed / not a dir / escapes root (incl. via symlink)
+
+# Offer a picker: every immediate sub-dir of a root, flagged git / selected.
+projects = list_candidate_projects(PROJECTS_ROOT, allowlist=("myrepo",))  # list[ProjectDir]
+```
+
+## Model discovery
+
+`list_models` runs `pi --list-models` under the same isolation env the agent uses and parses the
+table into typed `ModelInfo` rows; `parse_models` is the pure parser (handy for tests / cached
+output). When a provider is set the result is narrowed to it.
+
+```python
+from pidriver import list_models, parse_models
+
+models = await list_models(config, provider="anthropic")   # list[ModelInfo]
+for m in models:
+    print(m.id, m.context)        # "anthropic/claude-opus-4-8" "200K"
+```
+
+## Provider OAuth login
+
+Some providers authenticate via OAuth (Claude Pro/Max, Codex, …) instead of an API key. `PiOAuthLogin`
+drives a bundled Node helper that reuses pi's own `AuthStorage` (no version skew), writing
+credentials into the isolated `<agent_dir>/auth.json`. Requires `node` on PATH and a resolvable pi
+install.
+
+```python
+from pidriver import PiOAuthLogin
+
+login = PiOAuthLogin(config)                       # config.agent_dir receives auth.json
+info = await login.start("anthropic")              # {"session", "url", "instructions"}
+# user opens info["url"], authorizes, copies the code:
+await login.submit_code(info["session"], code)     # accepts a bare code or a callback URL
+```
+
+`valid_extension_source(src)` validates a `pi install` argument, and `resolve_node_modules(config)`
+locates pi's bundled Node libraries (package identity from `config.npm_package`, so the omp fork
+works too) — both exported for hosts building their own extension/auth tooling.
+
 ## Development
 
 ```sh

{pidriver-0.0.2 → pidriver-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pidriver"
-version = "0.0.2"
+version = "0.2.0"
 description = "Async Python driver for the pi coding agent (pi --mode rpc), built for isolated, headless project work."
 readme = "README.md"
 license = { text = "MIT" }
@@ -36,6 +36,11 @@ build-backend = "hatchling.build"
 [tool.hatch.build.targets.wheel]
 packages = ["src/pidriver"]
 
+# Ship the Node OAuth helper (pidriver.auth loads it via importlib.resources). Explicit
+# so the data file lands in the wheel regardless of default file selection.
+[tool.hatch.build.targets.wheel.force-include]
+"src/pidriver/assets/pi_login.mjs" = "pidriver/assets/pi_login.mjs"
+
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]