@code-yeongyu/senpi 2026.7.4 → 2026.7.9-2

package/docs/mcp.md

@@ -0,0 +1,205 @@
+# MCP (Model Context Protocol)
+
+senpi ships a built-in MCP client. Servers you configure expose their tools,
+resources, and prompts to the agent with context-efficient defaults: a large
+catalog costs almost nothing until the model actually needs it.
+
+## Quickstart
+
+1. Add a server to `<agentDir>/mcp.json` (global), `.senpi/mcp.json`
+   (project), or import from `.mcp.json` (Claude format, via
+   `settings.importConfigs`):
+
+```json
+{
+  "mcpServers": {
+    "docs": {
+      "command": "npx",
+      "args": ["-y", "@example/docs-mcp"],
+      "env": { "DOCS_TOKEN": "${DOCS_TOKEN}" }
+    }
+  }
+}
+```
+
+2. Start senpi. Run `/mcp` for the status panel, `/mcp status` for a one-line
+   summary, `/mcp add <name> <command...>` to add servers interactively.
+3. Servers needing OAuth: `/mcp login <name>` (see [Auth](#auth)).
+4. Use it: small catalogs register directly; big ones surface through
+   `mcp_search` (see [Exposure tiers](#exposure-tiers)).
+
+## Configuration reference
+
+Top-level shape: `{ "settings": { ... }, "mcpServers": { "<name>": { ... } } }`.
+
+### Server fields (`mcpServers.<name>`)
+
+### `type`
+`"stdio" | "http"`. Default: inferred — `http` when `url` is set, else `stdio`.
+
+### `url`
+HTTP(S) endpoint for `type:"http"` servers (Streamable HTTP with SSE fallback).
+
+### `command`
+Executable for `type:"stdio"` servers. Never passed through a shell.
+
+### `args`
+Argument array for `command`. Default `[]`.
+
+### `env`
+Extra environment variables for the child process. Values support `${VAR}`
+expansion from the trusted parent environment.
+
+### `cwd`
+Working directory for the child process. Default: the session cwd.
+
+### `headers`
+Extra HTTP headers for `type:"http"` servers.
+
+### `auth`
+`"bearer" | "oauth" | false`. Default: autodetected — `bearerTokenEnv` or an
+`Authorization` header implies `bearer`; a 401 from an HTTP server triggers the
+OAuth flow. `false` disables auth entirely.
+
+### `bearerTokenEnv`
+Name of the environment variable holding a bearer token (the value itself
+never lives in config; literal-looking tokens in config produce a warning).
+
+### `oauth`
+OAuth tuning: `clientId`, `callbackPort` (default: ephemeral),
+`scopes`, `clientMetadataUrl`, `flow` (`"code"` default, or
+`"client_credentials"` for headless machine-to-machine).
+
+### `enabled`
+Default `true`. Disabled servers stay in config but never spawn.
+
+### `lifecycle`
+`"lazy"` (default: connect on first use), `"eager"` (connect at session start),
+`"keep-alive"` (eager + 30s pings + automatic reconnect; never idles out).
+
+### `idleTimeoutMin`
+Minutes of zero in-flight calls before a connected server is shut down (its
+tools stay registered; the next call reconnects transparently). Default `10`.
+
+### `requestTimeoutMs`
+Per-request timeout. Default `30000`.
+
+### `connectTimeoutMs`
+Connect + initialize handshake timeout. Default `15000`.
+
+### `includeTools`
+Glob allowlist (`*` wildcards) over server-side tool names. Default: all.
+
+### `excludeTools`
+Glob denylist applied after `includeTools`.
+
+### `directTools`
+`true` = every filtered tool active immediately; or an array of names/globs
+that stay active while the rest goes behind `mcp_search`. Default: none.
+
+### `exposure`
+`"auto"` (default), `"direct"`, `"search"`, or `"proxy"`. See
+[Exposure tiers](#exposure-tiers). `auto` never selects `proxy`.
+
+### `logLevel`
+Minimum RFC-5424 level (`debug`…`emergency`) for the server's
+`notifications/message` log stream. Default: record everything (rate-capped).
+
+### Settings fields (`settings`)
+
+### `toolPrefix`
+Prefix for registered tool names (`<prefix>_<server>_<tool>`). Default `"mcp"`.
+
+### `searchThreshold`
+Filtered-tool count above which `auto` switches a server to search mode.
+Default `10`.
+
+### `outputGuard`
+Caps on tool/resource output: `maxBytes` (default 51200), `maxLines`
+(default 2000), `maxTokens`. Oversized output is truncated with a notice and
+the full artifact is written to disk.
+
+### `importConfigs`
+`["claude"]` imports `.mcp.json` (Claude Code format) from the project root.
+Imported servers require project trust.
+
+### `oauthCallbackUrl`
+Override the OAuth loopback callback URL (e.g. behind port forwarding).
+
+### `stubSwap`
+Opt-in prompt-cache mitigation for search mode: every inactive tool registers
+as a 30-70-token stub so the tools array stays length-stable; activation swaps
+the stub for the full schema in place. Default `false`.
+
+### `nativeToolSearch`
+`"auto"` (default) | `true` | `false`. On Anthropic models, defers inactive
+MCP tools to the provider's native tool-search; any 400 falls back to the
+local `mcp_search` for the session.
+
+## Exposure tiers
+
+| Tier | When | Cost profile |
+|---|---|---|
+| direct | `exposure:"direct"`, `directTools:true`, or `auto` at/below `searchThreshold` | Every tool schema on every request |
+| search (Tier-B) | `exposure:"search"` or `auto` above the threshold | Full catalog registered, ~135 tokens resident (`mcp_search` only); matches promote next turn; promotions survive resume/compaction |
+| proxy (Tier-C) | `exposure:"proxy"` only — never `auto` | One `mcp_<server>` gateway tool (`search`/`describe`/`call` with JSON-string args); cheapest, but no provider-side argument validation |
+
+Skills can carry MCP servers too (an `mcp.json` sidecar next to SKILL.md, or a
+`mcp:` frontmatter block): those servers register with zero active tools and
+reveal their `includeTools` matches when the skill loads. A name collision
+with a configured server resolves in favor of your config.
+
+## Resources and prompts
+
+- `mcp_list_resources` / `mcp_read_resource` register automatically when a
+  connected server lists resources.
+- Mention `@mcp:<server>/<uri>` in your prompt to inline a resource's content
+  into the message; unknown or failing mentions are left untouched with a
+  notice.
+- Every server prompt registers as `/mcp:<server>:<prompt>`; invoking it
+  collects the prompt's arguments and drops the rendered text into the editor.
+- Servers may ask questions mid-call (elicitation, form mode): senpi walks the
+  requested fields through input dialogs; in non-interactive runs the request
+  is declined cleanly.
+
+## Auth
+
+- **Bearer**: set `bearerTokenEnv` (recommended) or an `Authorization` header.
+- **OAuth (interactive)**: `/mcp login <name>` runs the authorization-code +
+  PKCE flow with a loopback callback; tokens persist under `<agentDir>` with
+  `0600` permissions and refresh automatically (single-flight across
+  processes).
+- **OAuth (headless)**: `flow:"client_credentials"` for machine-to-machine, or
+  `/mcp login <name> --paste` to complete the code flow by pasting the
+  redirect URL from another browser/machine.
+- `/mcp logout <name>` clears stored tokens.
+
+## Troubleshooting
+
+| Symptom (`/mcp status`) | Meaning | Fix |
+|---|---|---|
+| `needs_auth` | 401 and no usable token | `/mcp login <name>` |
+| `suspended` | reconnect circuit breaker opened (5 failures/30s) | fix the server, then `/mcp reconnect <name>` |
+| `degraded` | transient failure; auto-reconnect with backoff is running | wait, or `/mcp reconnect <name>` |
+| tools missing | server filtered/disabled, or hidden behind search | check `includeTools`/`excludeTools`, ask the model to `mcp_search` |
+| child exits at spawn (EOF) | bad `command`/`args`/`env` | `/mcp logs <name>` shows the captured stderr |
+| slow first call | lazy server cold boot | use `lifecycle:"eager"` or `"keep-alive"` |
+
+## Security notes
+
+- Config values never pass through a shell; `${VAR}` expansion only reads the
+  trusted parent environment.
+- Project-level and imported configs require project trust before servers
+  spawn; untrusted entries are listed but inert.
+- Tokens are stored `0600` and never logged; server log streams and tool
+  output are redacted by the same secret scrubber as the rest of senpi and
+  capped by `outputGuard`.
+
+## Disabling MCP entirely
+
+Add the builtin to your settings' disabled list — no other configuration is
+needed:
+
+```json
+{ "disabledBuiltinExtensions": ["mcp"] }
+```

package/docs/models.md

@@ -139,7 +139,7 @@ Set `api` at provider level (default for all models) or model level (override pe
 | `headers` | Custom headers (see value resolution below) |
 | `authHeader` | Set `true` to add `Authorization: Bearer <apiKey>` automatically |
 | `models` | Array of model configurations |
-| `modelOverrides` | Per-model overrides for built-in models on this provider |
+| `modelOverrides` | Per-model overrides for built-in or extension-registered models on this provider |
 
 For providers with `models`, non-built-in provider configs need `baseUrl` and an `api` value at either provider or model level. `apiKey` is not required to load the file: models become available when auth is configured through `/login`/`auth.json`, CLI `--api-key`, or provider `apiKey`. If no auth is configured, the models load but stay unavailable in `/model` and `--list-models`.
 
@@ -295,7 +295,7 @@ Merge semantics:
 
 ## Per-model Overrides
 
-Use `modelOverrides` to customize specific built-in models without replacing the provider's full model list.
+Use `modelOverrides` to customize built-in models and matching extension-registered models without replacing the provider's full model list.
 
 ```json
 {
@@ -316,10 +316,10 @@ Use `modelOverrides` to customize specific built-in models without replacing the
 }
 ```
 
-`modelOverrides` supports these fields per model: `name`, `reasoning`, `input`, `cost` (partial), `contextWindow`, `maxTokens`, `headers`, `compat`.
+`modelOverrides` supports these fields per model: `name`, `reasoning`, `thinkingLevelMap`, `input`, `cost` (partial), `contextWindow`, `maxTokens`, `headers`, `compat`.
 
 Behavior notes:
-- `modelOverrides` are applied to built-in provider models.
+- `modelOverrides` are applied to built-in provider models and matching extension-registered provider models.
 - Unknown model IDs are ignored.
 - You can combine provider-level `baseUrl`/`headers` with `modelOverrides`.
 - Overriding `name` changes model matching and secondary detail text only; the footer and primary model lists continue to show the model `id`.

package/docs/neo.md

@@ -0,0 +1,110 @@
+# neo (Go TUI) — coding-agent integration notes
+
+> Minimal scaffold. Expanded by plan task 22 (docs + infra-sync). This file
+> currently covers only the pieces landed by task 15 (the TypeScript daemon).
+
+## Overview
+
+`senpi --neo` launches a Go-native terminal UI that drives the existing agent
+runtime over the JSONL RPC protocol. Multiple neo windows in the SAME cwd share
+one backend via a small TypeScript **daemon**, instead of each spawning its own
+runtime. `--neo-isolated` opts out of sharing (per-instance stdio backend).
+
+## Daemon architecture (task 15)
+
+### Process model
+
+- `senpi --listen <socket>` runs the daemon **supervisor**. It binds the socket,
+  self-registers, and serves connections. It does NOT construct an
+  `AgentSessionRuntime` in the supervisor process.
+- Each accepted connection is served by its own child `senpi --mode rpc`
+  **worker** process, spawned with the connection's cwd and its own
+  `SENPI_CODING_AGENT_DIR`. The worker is a standard single-connection rpc
+  runtime with its own module state and its own `AuthStorage`.
+
+### Why one worker process per connection (isolation)
+
+Running N `createAgentSessionRuntime` instances concurrently in ONE node process
+is not safe: pi-ai keeps a **process-global provider registry** that
+`ModelRegistry.refresh()` / `AgentSession.reload()` reset
+(`resetApiProviders()` / `resetOAuthProviders()`), and pi-agent-core mints entry
+IDs from a **module-level UUIDv7 counter**. Two concurrent in-process runtimes
+would cross-talk through both. Both live in shared libraries that are out of
+scope to change, so the daemon uses child-process workers instead — real
+concurrency, full isolation, and `--api-key` that can never leak across
+connections. See `.omo/evidence/task-15-neo-go-tui.md` §1 for the full spike.
+
+### Handshake
+
+A connection's first line is a `hello`:
+
+```json
+{"type":"hello","token":"<registry token>","version":1,"capabilities":[],"runtimeOptions":{...}}
+```
+
+The daemon replies `{"type":"welcome","version":1}` or
+`{"type":"refuse","code":"bad_token|version_mismatch|unsupported_options|malformed_hello","reason":"..."}`.
+`runtimeOptions` is the typed `NeoRuntimeOptions` payload (every classic runtime
+flag: provider/model/models/thinking/api-key, session selection, approval, tool
+scoping, resource loading, extension flags, and raw initial inputs). Its field
+set is generated from the classic runtime-construction path by an extraction
+test — a new consumer of a `parsed.*` field fails the test until it is threaded
+through the payload or documented as a carve-out.
+
+**Carve-out:** piped-stdin input never reaches the daemon — a TTY-less
+`senpi --neo` falls back to classic print-mode in the launcher.
+
+### Registry / race protocol
+
+- The daemon binds the socket FIRST — the bind is the mutex. The race loser gets
+  `EADDRINUSE` and its client attaches to the winner.
+- After a successful `listen`, and only with `--register`, the daemon atomically
+  writes `~/.senpi/agent/neo-daemon/<cwd-key>.json` (temp file + `rename`, mode
+  `0600`) as the LAST listen step. `<cwd-key>` uses the same safe-path scheme as
+  the session manager. Clients NEVER write the registry.
+- On spawn, a stale record (dead pid) and its leftover socket file are cleaned up
+  before binding.
+
+### Connection lifecycle
+
+There is no live-reattach lease. A socket disconnect aborts that connection's
+in-flight turn and disposes its worker. Sessions persist incrementally to disk,
+so recovery is resume-from-file (the Go client reloads via `get_state` +
+`get_entries{since}`). The daemon shuts down after a configurable no-connection
+idle period (`neoDaemon.idleShutdownMs` setting, default 30 minutes; `0`
+disables). The last client does NOT kill the daemon — the idle timer owns
+lifecycle.
+
+## Project-trust semantics in the daemon
+
+Each worker runs `--mode rpc`, which is **non-interactive**. In rpc mode the
+project-trust context has `hasUI: false`, so `resolveProjectTrusted` returns
+`false` for project-local resources unless:
+
+- the global `defaultProjectTrust` setting is `"always"`, or
+- the connection passes `--approve` (`projectTrustOverride: true`) in its
+  `runtimeOptions`.
+
+This is the same behavior as classic `senpi --mode rpc` today (the daemon adds no
+new trust surface). The classic **interactive** TUI prompts for trust; the neo
+client is responsible for surfacing an equivalent confirm through the
+extension-UI bridge and forwarding the user's choice as `--approve`/`--no-approve`
+(wired in plan task 13). No project-local code is trusted implicitly by the
+daemon.
+
+## cwd-threading audit (per-user-daemon safety)
+
+Verdict: **per-cwd, child-per-connection is safe** with respect to cwd.
+
+- There are **zero** `process.chdir()` calls in `packages/coding-agent/src`.
+- Tool execution is closure-captured: each tool is created with an explicit
+  `cwd` (from `AgentSession.config.cwd`) and threads it to every spawn/path call.
+  The bash tool passes `cwd` explicitly to `spawn(...)`; it never inherits
+  `process.cwd()`.
+- `resolvePath()` / `SessionManager` fall back to `process.cwd()` only as a
+  default when no explicit base/cwd is given; the runtime path always passes one.
+- Because each connection is its own child process spawned with an explicit
+  `cwd`, the child's `process.cwd()` is already the client's directory, so even
+  the fallback paths resolve correctly. No cross-connection cwd hazard remains.
+
+Per-cwd remains the default regardless (one daemon serves one cwd).

package/docs/packages.md

@@ -1,8 +1,8 @@
-> pi can help you create pi packages. Ask it to bundle your extensions, skills, prompt templates, themes, or hook configs.
+> pi can help you create pi packages. Ask it to bundle your extensions, skills, prompt templates, or themes.
 
 # Pi Packages
 
-Pi packages bundle extensions, skills, prompt templates, themes, and hook configs so you can share them through npm or git. A package can declare resources in `package.json` under the `pi` key, or use conventional directories.
+Pi packages bundle extensions, skills, prompt templates, and themes so you can share them through npm or git. A package can declare resources in `package.json` under the `pi` key, or use conventional directories.
 
 ## Table of Contents
 
@@ -124,8 +124,7 @@ Add a `pi` manifest to `package.json` or use conventional directories. Include t
     "extensions": ["./extensions"],
     "skills": ["./skills"],
     "prompts": ["./prompts"],
-    "themes": ["./themes"],
-    "hooks": ["./hooks"]
+    "themes": ["./themes"]
   }
 }
 ```
@@ -163,11 +162,10 @@ If no `pi` manifest is present, pi auto-discovers resources from these directori
 - `skills/` recursively finds `SKILL.md` folders and loads top-level `.md` files as skills
 - `prompts/` loads `.md` files
 - `themes/` loads `.json` files
-- `hooks/` loads `.json` files
 
 ## Dependencies
 
-Third party runtime dependencies belong in `dependencies` in `package.json`. Dependencies that do not register extensions, skills, prompt templates, themes, or hook configs also belong in `dependencies`. When pi installs a package from npm or git, it runs `npm install`, so those dependencies are installed automatically.
+Third party runtime dependencies belong in `dependencies` in `package.json`. Dependencies that do not register extensions, skills, prompt templates, or themes also belong in `dependencies`. When pi installs a package from npm or git, it runs `npm install`, so those dependencies are installed automatically.
 
 Pi bundles core packages for extensions and skills. If you import any of these, list them in `peerDependencies` with a `"*"` range and do not bundle them: `@earendil-works/pi-ai`, `@earendil-works/pi-agent-core`, `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`, `typebox`.
 
@@ -201,8 +199,7 @@ Filter what a package loads using the object form in settings:
       "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
       "skills": [],
       "prompts": ["prompts/review.md"],
-      "themes": ["+themes/legacy.json"],
-      "hooks": ["hooks/pretool.json"]
+      "themes": ["+themes/legacy.json"]
     }
   ]
 }
@@ -219,11 +216,11 @@ Filter what a package loads using the object form in settings:
 
 ## Enable and Disable Resources
 
-Use `pi config` to enable or disable extensions, skills, prompt templates, themes, and hook configs from installed packages and local directories. Works for both global (`~/.pi/agent`) and project (`.pi/`) scopes.
+Use `pi config` to enable or disable extensions, skills, prompt templates, and themes from installed packages and local directories. `pi config` starts in global settings (`~/.pi/agent/settings.json`); press Tab to switch between global and project-local modes. Use `pi config -l` to start in project overrides (`.pi/settings.json`) with inherited global resources dimmed.
 
 ## Scope and Deduplication
 
-Packages can appear in both global and project settings. If the same package appears in both, the project entry wins. Identity is determined by:
+Packages can appear in both global and project settings. If the same package appears in both, the project entry wins unless the project entry has `autoload: false`, in which case it is applied as a delta over the global entry. Identity is determined by:
 
 - npm: package name
 - git: repository URL without ref

package/docs/rpc.md

@@ -809,7 +809,8 @@ Events are streamed to stdout as JSON lines during agent operation. Events do NO
 | Event | Description |
 |-------|-------------|
 | `agent_start` | Agent begins processing |
-| `agent_end` | Agent completes (includes all generated messages) |
+| `agent_end` | One low-level agent run completes (may still be followed by retry, compaction, or queued continuations) |
+| `agent_settled` | Agent run is fully settled; no automatic retry, compaction retry, or queued continuation remains |
 | `turn_start` | New turn begins |
 | `turn_end` | Turn completes (includes assistant message and tool results) |
 | `message_start` | Message begins |
@@ -835,15 +836,24 @@ Emitted when the agent begins processing a prompt.
 
 ### agent_end
 
-Emitted when the agent completes. Contains all messages generated during this run.
+Emitted when one low-level agent run completes. Contains all messages generated during this run. If `willRetry` is true, an automatic retry will follow.
 
 ```json
 {
   "type": "agent_end",
-  "messages": [...]
+  "messages": [...],
+  "willRetry": false
 }
 ```
 
+### agent_settled
+
+Emitted after the full session-level run settles. At this point Pi will not continue automatically through retry, compaction retry, or queued follow-up messages.
+
+```json
+{"type": "agent_settled"}
+```
+
 ### turn_start / turn_end
 
 A turn consists of one assistant response plus any resulting tool calls and results.

package/docs/sdk.md

@@ -605,6 +605,27 @@ const { session } = await createAgentSession({ resourceLoader: loader });
 
 Extensions can register tools, subscribe to events, add commands, and more. See [extensions.md](extensions.md) for the full API.
 
+**Named inline extensions:** By default, inline factories display as `<inline:1>`, `<inline:2>`, etc. in the startup Extensions list. To show a descriptive name instead, wrap the factory:
+
+```typescript
+import type { InlineExtension } from "@earendil-works/pi-coding-agent";
+
+const myProvider: InlineExtension = {
+  name: "my-provider",
+  factory: (pi) => {
+    pi.on("agent_start", () => {
+      console.log("[my-provider] Agent starting");
+    });
+  },
+};
+
+const loader = new DefaultResourceLoader({
+  extensionFactories: [myProvider],
+});
+```
+
+This displays as `<inline:my-provider>` instead of `<inline:1>`. Bare factory functions are still accepted for backward compatibility.
+
 **Event Bus:** Extensions can communicate via `pi.events`. Pass a shared `eventBus` to `DefaultResourceLoader` if you need to emit or listen from outside:
 
 ```typescript
@@ -1101,6 +1122,17 @@ await runRpcMode(runtime);
 
 See [RPC documentation](rpc.md) for the JSON protocol.
 
+### App Server Mode
+
+App Server mode is a CLI run mode for Codex-compatible app and editor integrations. Use it when a client expects the Codex app-server JSON-RPC method names, notification stream, and thread lifecycle instead of senpi's SDK object model.
+
+```bash
+senpi app-server --listen ws://127.0.0.1:18990
+senpi app-server --listen stdio://
+```
+
+See [App Server documentation](app-server.md) for activation, framing, method coverage, and compatibility notes.
+
 ## RPC Mode Alternative
 
 For subprocess-based integration without building with the SDK, use the CLI directly:
@@ -1166,6 +1198,7 @@ createGrepTool, createFindTool, createLsTool
 type CreateAgentSessionOptions
 type CreateAgentSessionResult
 type ExtensionFactory
+type InlineExtension
 type ExtensionAPI
 type ToolDefinition
 type Skill

package/docs/settings.md

@@ -86,6 +86,7 @@ Permission rules are a confirmation policy, not a sandbox. Senpi, extensions, pa
 | `defaultThinkingLevel` | string | - | `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"` |
 | `promptPreset` | string | `"auto"` | Force a system prompt preset: `"auto"`, `"kimi-k2-6"`, `"kimi-k2-7"`, `"glm-5.2"`, `"claude-fable-5"`, `"claude-opus-4-5"`, `"claude-opus-4-6"`, `"claude-opus-4-7"`, `"claude-opus-4-8"`, `"gpt-5"`, `"gpt-5.2"`, `"gpt-5.3-codex"`, `"gpt-5.4"`, or `"gpt-5.5"` |
 | `hideThinkingBlock` | boolean | `false` | Hide thinking blocks in output |
+| `showCacheMissNotices` | boolean | `false` | Show transcript notices for significant prompt-cache misses |
 | `thinkingBudgets` | object | - | Custom token budgets per thinking level |
 
 #### promptPreset

package/docs/terminal-tools.md

@@ -0,0 +1,69 @@
+# Persistent terminal tools
+
+Senpi's `bash` tool is backed by a real PTY, and ships four companion tools for
+long-lived, interactive shell sessions. This is the built-in `terminal` extension,
+powered by the in-house `@earendil-works/pi-pty` native module (with a
+`child_process` pipe fallback when no native prebuild is available for your
+platform/runtime).
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `bash` | Run a command in a PTY. `run_in_background: true` starts a persistent session and returns a `bash_id` immediately. Foreground `timeout` (seconds) is a kill deadline. |
+| `bash_output` | Read new output from a session, or `wait_for` a regex / exit / timeout. `filter` regex-filters lines; `view: "screen"` returns the rendered xterm grid. |
+| `bash_input` | Send stdin (`input`) or named keys (`keys: ["ctrl+c"]`, `["enter"]`, `["up"]`) to steer a REPL or interrupt a process. |
+| `bash_resize` | Resize a session's PTY (`cols`, `rows`) so full-screen TUIs reflow. |
+| `kill_bash` | Tree-kill one session (`bash_id`) or all (`all: true`), leaving no orphans. |
+
+Background sessions are NEVER killed by `timeout` (they live until they exit or you
+call `kill_bash`), even though the bash-timeout extension injects a default `timeout`
+into every `bash` call. Foreground calls behave like the classic `bash` tool.
+
+Typical flow: start with `run_in_background: true`, subscribe with `bash_output`
+(`wait_for`), steer with `bash_input`, then `kill_bash` when done.
+
+## Mutual exclusion with native Anthropic bash
+
+When `PI_ANTHROPIC_BASH` is enabled and the active model uses the
+`anthropic-messages` API, senpi injects Anthropic's native, stateless `bash` tool.
+In that mode the four persistent companions step aside (they are deactivated so none
+dangle without a usable persistent `bash`), and a one-line notice is shown. Disable
+`PI_ANTHROPIC_BASH` or switch to a non-Anthropic model to re-enable persistent
+sessions.
+
+## Settings
+
+Configure the suite under `terminal` in `settings.json` (global
+`~/.senpi/agent/settings.json` or project `.senpi/settings.json`):
+
+```json
+{
+  "terminal": {
+    "defaultCols": 120,
+    "defaultRows": 40,
+    "scrollback": 10000,
+    "maxSessions": 32,
+    "timeoutAction": "background",
+    "notify": "wake"
+  }
+}
+```
+
+- `defaultCols` / `defaultRows` — PTY size for new sessions (default 120 x 40).
+- `scrollback` — xterm scrollback lines per session (default 10000).
+- `maxSessions` — concurrent sessions before least-recently-used exited sessions are pruned (default 32).
+- `timeoutAction` — fate of a foreground timeout (default `background`).
+- `notify` — async completion behavior: `wake` (wake an idle interactive agent once), `next-turn`, or `off` (default `wake`). Non-interactive `-p` / `--print` / `--mode json` runs never wake.
+
+## Windows
+
+The PTY runs natively on Windows via ConPTY. Shell resolution:
+
+- Set `SENPI_GIT_BASH_PATH` to point at a specific `bash.exe` — it wins over the
+  Git Bash auto-detection.
+- An explicit shell path (`shellPath` in settings, or `SENPI_GIT_BASH_PATH`) is
+  resolved by kind: `cmd.exe` uses `/c`, PowerShell/`pwsh` use `-NoProfile -Command`,
+  and bash/sh use `-c` (or WSL bash `-s` via stdin).
+
+No shell is bundled; install Git for Windows or point senpi at your shell.

package/docs/usage.md

@@ -52,7 +52,7 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/export [file]` | Export session to HTML or JSONL |
 | `/import <file>` | Import and resume a session from a JSONL file |
 | `/share` | Upload as private GitHub gist with shareable HTML link |
-| `/reload` | Reload keybindings, extensions, skills, prompts, and context files |
+| `/reload` | Reload keybindings, extensions, skills, prompts, themes, and context files |
 | `/hotkeys` | Show all keyboard shortcuts |
 | `/changelog` | Display version history |
 | `/quit` | Quit pi |

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "0.80.3",
+  "version": "0.80.5",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "0.80.3",
+      "version": "0.80.5",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-anthropic",
   "private": true,
-  "version": "0.80.3",
+  "version": "0.80.5",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-gitlab-duo",
   "private": true,
-  "version": "0.80.3",
+  "version": "0.80.5",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/gondolin/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-gondolin",
-	"version": "0.80.3",
+	"version": "0.80.5",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-gondolin",
-			"version": "0.80.3",
+			"version": "0.80.5",
 			"dependencies": {
 				"@earendil-works/gondolin": "0.12.0"
 			}

package/examples/extensions/gondolin/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-gondolin",
 	"private": true,
-	"version": "0.80.3",
+	"version": "0.80.5",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/reload-runtime.ts

@@ -12,7 +12,7 @@ export default function (pi: ExtensionAPI) {
 	// Command entrypoint for reload.
 	// Treat reload as terminal for this handler.
 	pi.registerCommand("reload-runtime", {
-		description: "Reload extensions, skills, prompts, and themes",
+		description: "Reload extensions, skills, prompts, themes, and context files",
 		handler: async (_args, ctx) => {
 			await ctx.reload();
 			return;
@@ -24,7 +24,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "reload_runtime",
 		label: "Reload Runtime",
-		description: "Reload extensions, skills, prompts, and themes",
+		description: "Reload extensions, skills, prompts, themes, and context files",
 		parameters: Type.Object({}),
 		async execute() {
 			pi.sendUserMessage("/reload-runtime", { deliverAs: "followUp" });