@code-yeongyu/senpi 2026.7.17 → 2026.7.20-2

package/dist/utils/child-process.js

@@ -1,6 +1,7 @@
 import { spawn as nodeSpawn, spawnSync as nodeSpawnSync, } from "node:child_process";
 import crossSpawn from "cross-spawn";
 const EXIT_STDIO_GRACE_MS = 250;
+const ABORT_EXIT_GRACE_MS = 5000;
 export function spawnProcess(command, args, options) {
     return process.platform === "win32" ? crossSpawn(command, args, options) : nodeSpawn(command, args, options);
 }
@@ -19,13 +20,20 @@ export function spawnProcessSync(command, args, options) {
  * the grace timer is re-armed on every chunk, so an actively writing descendant keeps
  * us reading, while a quiet inherited handle (e.g. a Windows daemonized descendant
  * that never lets `close` fire) still releases us after the grace elapses.
+ *
+ * When `options.signal` aborts, the caller has killed the process and
+ * abandoned its output: tail preservation ends, the pipes are destroyed, and
+ * the wait resolves on `exit` — or after `abortExitGraceMs` when the kill
+ * never lands (uninterruptible IO, failed taskkill).
  */
-export function waitForChildProcess(child) {
+export function waitForChildProcess(child, options) {
     return new Promise((resolve, reject) => {
         let settled = false;
         let exited = false;
         let exitCode = null;
         let postExitTimer;
+        let abortGraceTimer;
+        let detachAbortListener;
         let stdoutEnded = child.stdout === null;
         let stderrEnded = child.stderr === null;
         const cleanup = () => {
@@ -33,6 +41,14 @@ export function waitForChildProcess(child) {
                 clearTimeout(postExitTimer);
                 postExitTimer = undefined;
             }
+            if (abortGraceTimer) {
+                clearTimeout(abortGraceTimer);
+                abortGraceTimer = undefined;
+            }
+            if (detachAbortListener) {
+                detachAbortListener();
+                detachAbortListener = undefined;
+            }
             child.removeListener("error", onError);
             child.removeListener("exit", onExit);
             child.removeListener("close", onClose);
@@ -94,6 +110,20 @@ export function waitForChildProcess(child) {
         const onClose = (code) => {
             finalize(code);
         };
+        const onAbortRelease = () => {
+            // The caller killed the process and abandoned its output: destroy our
+            // read ends so surviving descendants cannot re-arm the idle grace
+            // forever, then wait only for `exit`, bounded by the abort grace.
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            stdoutEnded = true;
+            stderrEnded = true;
+            if (exited) {
+                maybeFinalizeAfterExit();
+                return;
+            }
+            abortGraceTimer = setTimeout(() => finalize(exitCode), options?.abortExitGraceMs ?? ABORT_EXIT_GRACE_MS);
+        };
         child.stdout?.once("end", onStdoutEnd);
         child.stderr?.once("end", onStderrEnd);
         child.stdout?.on("data", onData);
@@ -101,6 +131,16 @@ export function waitForChildProcess(child) {
         child.once("error", onError);
         child.once("exit", onExit);
         child.once("close", onClose);
+        const abortSignal = options?.signal;
+        if (abortSignal) {
+            if (abortSignal.aborted) {
+                onAbortRelease();
+            }
+            else {
+                abortSignal.addEventListener("abort", onAbortRelease, { once: true });
+                detachAbortListener = () => abortSignal.removeEventListener("abort", onAbortRelease);
+            }
+        }
     });
 }
 //# sourceMappingURL=child-process.js.map

package/dist/utils/child-process.js.map

@@ -1 +1 @@
-{"version":3,"file":"child-process.js","sourceRoot":"","sources":["../../src/utils/child-process.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\ttype ChildProcess,\n\ttype ChildProcessByStdio,\n\tspawn as nodeSpawn,\n\tspawnSync as nodeSpawnSync,\n\ttype SpawnOptions,\n\ttype SpawnOptionsWithStdioTuple,\n\ttype SpawnSyncOptionsWithStringEncoding,\n\ttype SpawnSyncReturns,\n\ttype StdioNull,\n\ttype StdioPipe,\n} from \"node:child_process\";\nimport type { Readable } from \"node:stream\";\nimport crossSpawn from \"cross-spawn\";\n\nconst EXIT_STDIO_GRACE_MS = 250;\n\nexport function spawnProcess(\n\tcommand: string,\n\targs: string[],\n\toptions: SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioPipe>,\n): ChildProcessByStdio<null, Readable, Readable>;\nexport function spawnProcess(command: string, args: string[], options: SpawnOptions): ChildProcess;\nexport function spawnProcess(command: string, args: string[], options: SpawnOptions): ChildProcess {\n\treturn process.platform === \"win32\" ? crossSpawn(command, args, options) : nodeSpawn(command, args, options);\n}\n\nexport function spawnProcessSync(\n\tcommand: string,\n\targs: string[],\n\toptions: SpawnSyncOptionsWithStringEncoding,\n): SpawnSyncReturns<string> {\n\treturn process.platform === \"win32\"\n\t\t? crossSpawn.sync(command, args, options)\n\t\t: nodeSpawnSync(command, args, options);\n}\n\n/**\n * Wait for a child process to terminate without hanging on inherited stdio handles.\n *\n * A short-lived child can `exit` while a detached descendant keeps its stdout/stderr\n * pipe open. We must not resolve and destroy the streams on a fixed deadline measured\n * from `exit`, or output still being written past that deadline is silently lost\n * (earendil-works/pi#5303). Instead, after `exit` we wait for the pipes to fall idle:\n * the grace timer is re-armed on every chunk, so an actively writing descendant keeps\n * us reading, while a quiet inherited handle (e.g. a Windows daemonized descendant\n * that never lets `close` fire) still releases us after the grace elapses.\n */\nexport function waitForChildProcess(child: ChildProcess): Promise<number | null> {\n\treturn new Promise((resolve, reject) => {\n\t\tlet settled = false;\n\t\tlet exited = false;\n\t\tlet exitCode: number | null = null;\n\t\tlet postExitTimer: NodeJS.Timeout | undefined;\n\t\tlet stdoutEnded = child.stdout === null;\n\t\tlet stderrEnded = child.stderr === null;\n\n\t\tconst cleanup = () => {\n\t\t\tif (postExitTimer) {\n\t\t\t\tclearTimeout(postExitTimer);\n\t\t\t\tpostExitTimer = undefined;\n\t\t\t}\n\t\t\tchild.removeListener(\"error\", onError);\n\t\t\tchild.removeListener(\"exit\", onExit);\n\t\t\tchild.removeListener(\"close\", onClose);\n\t\t\tchild.stdout?.removeListener(\"end\", onStdoutEnd);\n\t\t\tchild.stderr?.removeListener(\"end\", onStderrEnd);\n\t\t\tchild.stdout?.removeListener(\"data\", onData);\n\t\t\tchild.stderr?.removeListener(\"data\", onData);\n\t\t};\n\n\t\tconst finalize = (code: number | null) => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tcleanup();\n\t\t\tchild.stdout?.destroy();\n\t\t\tchild.stderr?.destroy();\n\t\t\tresolve(code);\n\t\t};\n\n\t\tconst maybeFinalizeAfterExit = () => {\n\t\t\tif (!exited || settled) return;\n\t\t\tif (stdoutEnded && stderrEnded) {\n\t\t\t\tfinalize(exitCode);\n\t\t\t}\n\t\t};\n\n\t\tconst armIdleTimer = () => {\n\t\t\tif (postExitTimer) clearTimeout(postExitTimer);\n\t\t\tpostExitTimer = setTimeout(() => finalize(exitCode), EXIT_STDIO_GRACE_MS);\n\t\t};\n\n\t\tconst onData = () => {\n\t\t\t// Output is still arriving after exit; defer finalizing so we don't\n\t\t\t// destroy the stream mid-write and truncate the tail.\n\t\t\tif (exited && !settled) armIdleTimer();\n\t\t};\n\n\t\tconst onStdoutEnd = () => {\n\t\t\tstdoutEnded = true;\n\t\t\tmaybeFinalizeAfterExit();\n\t\t};\n\n\t\tconst onStderrEnd = () => {\n\t\t\tstderrEnded = true;\n\t\t\tmaybeFinalizeAfterExit();\n\t\t};\n\n\t\tconst onError = (err: Error) => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tcleanup();\n\t\t\treject(err);\n\t\t};\n\n\t\tconst onExit = (code: number | null) => {\n\t\t\texited = true;\n\t\t\texitCode = code;\n\t\t\tmaybeFinalizeAfterExit();\n\t\t\tif (!settled) {\n\t\t\t\tarmIdleTimer();\n\t\t\t}\n\t\t};\n\n\t\tconst onClose = (code: number | null) => {\n\t\t\tfinalize(code);\n\t\t};\n\n\t\tchild.stdout?.once(\"end\", onStdoutEnd);\n\t\tchild.stderr?.once(\"end\", onStderrEnd);\n\t\tchild.stdout?.on(\"data\", onData);\n\t\tchild.stderr?.on(\"data\", onData);\n\t\tchild.once(\"error\", onError);\n\t\tchild.once(\"exit\", onExit);\n\t\tchild.once(\"close\", onClose);\n\t});\n}\n"]}
+{"version":3,"file":"child-process.js","sourceRoot":"","sources":["../../src/utils/child-process.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\ttype ChildProcess,\n\ttype ChildProcessByStdio,\n\tspawn as nodeSpawn,\n\tspawnSync as nodeSpawnSync,\n\ttype SpawnOptions,\n\ttype SpawnOptionsWithStdioTuple,\n\ttype SpawnSyncOptionsWithStringEncoding,\n\ttype SpawnSyncReturns,\n\ttype StdioNull,\n\ttype StdioPipe,\n} from \"node:child_process\";\nimport type { Readable } from \"node:stream\";\nimport crossSpawn from \"cross-spawn\";\n\nconst EXIT_STDIO_GRACE_MS = 250;\nconst ABORT_EXIT_GRACE_MS = 5000;\n\nexport interface WaitForChildProcessOptions {\n\t/**\n\t * Abort when the caller has killed the process and no longer needs its\n\t * output. The wait then stops preserving stdio tails (descendants that\n\t * survived the kill can no longer hold it open) and resolves as soon as\n\t * the process exits, or after `abortExitGraceMs` if it never does.\n\t */\n\tsignal?: AbortSignal;\n\t/** Post-abort deadline for `exit` before resolving anyway. Default 5s. */\n\tabortExitGraceMs?: number;\n}\n\nexport function spawnProcess(\n\tcommand: string,\n\targs: string[],\n\toptions: SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioPipe>,\n): ChildProcessByStdio<null, Readable, Readable>;\nexport function spawnProcess(command: string, args: string[], options: SpawnOptions): ChildProcess;\nexport function spawnProcess(command: string, args: string[], options: SpawnOptions): ChildProcess {\n\treturn process.platform === \"win32\" ? crossSpawn(command, args, options) : nodeSpawn(command, args, options);\n}\n\nexport function spawnProcessSync(\n\tcommand: string,\n\targs: string[],\n\toptions: SpawnSyncOptionsWithStringEncoding,\n): SpawnSyncReturns<string> {\n\treturn process.platform === \"win32\"\n\t\t? crossSpawn.sync(command, args, options)\n\t\t: nodeSpawnSync(command, args, options);\n}\n\n/**\n * Wait for a child process to terminate without hanging on inherited stdio handles.\n *\n * A short-lived child can `exit` while a detached descendant keeps its stdout/stderr\n * pipe open. We must not resolve and destroy the streams on a fixed deadline measured\n * from `exit`, or output still being written past that deadline is silently lost\n * (earendil-works/pi#5303). Instead, after `exit` we wait for the pipes to fall idle:\n * the grace timer is re-armed on every chunk, so an actively writing descendant keeps\n * us reading, while a quiet inherited handle (e.g. a Windows daemonized descendant\n * that never lets `close` fire) still releases us after the grace elapses.\n *\n * When `options.signal` aborts, the caller has killed the process and\n * abandoned its output: tail preservation ends, the pipes are destroyed, and\n * the wait resolves on `exit` — or after `abortExitGraceMs` when the kill\n * never lands (uninterruptible IO, failed taskkill).\n */\nexport function waitForChildProcess(child: ChildProcess, options?: WaitForChildProcessOptions): Promise<number | null> {\n\treturn new Promise((resolve, reject) => {\n\t\tlet settled = false;\n\t\tlet exited = false;\n\t\tlet exitCode: number | null = null;\n\t\tlet postExitTimer: NodeJS.Timeout | undefined;\n\t\tlet abortGraceTimer: NodeJS.Timeout | undefined;\n\t\tlet detachAbortListener: (() => void) | undefined;\n\t\tlet stdoutEnded = child.stdout === null;\n\t\tlet stderrEnded = child.stderr === null;\n\n\t\tconst cleanup = () => {\n\t\t\tif (postExitTimer) {\n\t\t\t\tclearTimeout(postExitTimer);\n\t\t\t\tpostExitTimer = undefined;\n\t\t\t}\n\t\t\tif (abortGraceTimer) {\n\t\t\t\tclearTimeout(abortGraceTimer);\n\t\t\t\tabortGraceTimer = undefined;\n\t\t\t}\n\t\t\tif (detachAbortListener) {\n\t\t\t\tdetachAbortListener();\n\t\t\t\tdetachAbortListener = undefined;\n\t\t\t}\n\t\t\tchild.removeListener(\"error\", onError);\n\t\t\tchild.removeListener(\"exit\", onExit);\n\t\t\tchild.removeListener(\"close\", onClose);\n\t\t\tchild.stdout?.removeListener(\"end\", onStdoutEnd);\n\t\t\tchild.stderr?.removeListener(\"end\", onStderrEnd);\n\t\t\tchild.stdout?.removeListener(\"data\", onData);\n\t\t\tchild.stderr?.removeListener(\"data\", onData);\n\t\t};\n\n\t\tconst finalize = (code: number | null) => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tcleanup();\n\t\t\tchild.stdout?.destroy();\n\t\t\tchild.stderr?.destroy();\n\t\t\tresolve(code);\n\t\t};\n\n\t\tconst maybeFinalizeAfterExit = () => {\n\t\t\tif (!exited || settled) return;\n\t\t\tif (stdoutEnded && stderrEnded) {\n\t\t\t\tfinalize(exitCode);\n\t\t\t}\n\t\t};\n\n\t\tconst armIdleTimer = () => {\n\t\t\tif (postExitTimer) clearTimeout(postExitTimer);\n\t\t\tpostExitTimer = setTimeout(() => finalize(exitCode), EXIT_STDIO_GRACE_MS);\n\t\t};\n\n\t\tconst onData = () => {\n\t\t\t// Output is still arriving after exit; defer finalizing so we don't\n\t\t\t// destroy the stream mid-write and truncate the tail.\n\t\t\tif (exited && !settled) armIdleTimer();\n\t\t};\n\n\t\tconst onStdoutEnd = () => {\n\t\t\tstdoutEnded = true;\n\t\t\tmaybeFinalizeAfterExit();\n\t\t};\n\n\t\tconst onStderrEnd = () => {\n\t\t\tstderrEnded = true;\n\t\t\tmaybeFinalizeAfterExit();\n\t\t};\n\n\t\tconst onError = (err: Error) => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tcleanup();\n\t\t\treject(err);\n\t\t};\n\n\t\tconst onExit = (code: number | null) => {\n\t\t\texited = true;\n\t\t\texitCode = code;\n\t\t\tmaybeFinalizeAfterExit();\n\t\t\tif (!settled) {\n\t\t\t\tarmIdleTimer();\n\t\t\t}\n\t\t};\n\n\t\tconst onClose = (code: number | null) => {\n\t\t\tfinalize(code);\n\t\t};\n\n\t\tconst onAbortRelease = () => {\n\t\t\t// The caller killed the process and abandoned its output: destroy our\n\t\t\t// read ends so surviving descendants cannot re-arm the idle grace\n\t\t\t// forever, then wait only for `exit`, bounded by the abort grace.\n\t\t\tchild.stdout?.destroy();\n\t\t\tchild.stderr?.destroy();\n\t\t\tstdoutEnded = true;\n\t\t\tstderrEnded = true;\n\t\t\tif (exited) {\n\t\t\t\tmaybeFinalizeAfterExit();\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tabortGraceTimer = setTimeout(() => finalize(exitCode), options?.abortExitGraceMs ?? ABORT_EXIT_GRACE_MS);\n\t\t};\n\n\t\tchild.stdout?.once(\"end\", onStdoutEnd);\n\t\tchild.stderr?.once(\"end\", onStderrEnd);\n\t\tchild.stdout?.on(\"data\", onData);\n\t\tchild.stderr?.on(\"data\", onData);\n\t\tchild.once(\"error\", onError);\n\t\tchild.once(\"exit\", onExit);\n\t\tchild.once(\"close\", onClose);\n\n\t\tconst abortSignal = options?.signal;\n\t\tif (abortSignal) {\n\t\t\tif (abortSignal.aborted) {\n\t\t\t\tonAbortRelease();\n\t\t\t} else {\n\t\t\t\tabortSignal.addEventListener(\"abort\", onAbortRelease, { once: true });\n\t\t\t\tdetachAbortListener = () => abortSignal.removeEventListener(\"abort\", onAbortRelease);\n\t\t\t}\n\t\t}\n\t});\n}\n"]}

package/docs/AGENTS.md

@@ -0,0 +1,70 @@
+# packages/coding-agent/docs/
+
+Public documentation for `@code-yeongyu/senpi`. Shipped inside the npm package: `package.json`
+`files` array includes `"docs"`, so every file here lands in the published tarball.
+
+## Navigation manifest
+
+`docs.json` has two top-level keys: `navigation` (ordered section and page list) and `redirects`.
+Page paths are relative to this directory.
+
+- Every new `.md` file needs an entry in `docs.json` under `navigation`.
+- Renamed or moved pages need a `redirects` entry to avoid broken links.
+- Navigation-only stubs without real content belong in `redirects`, not `navigation`.
+
+## Landing page and images
+
+`index.md` is the landing page. Images live under `docs/images/`:
+`doom-extension.png`, `exy.png`, `interactive-mode.png`, `tree-view.png`.
+
+New images go in `docs/images/`. Don't reference images by absolute URL when a relative path works.
+
+## Protocol and reference pages
+
+These pages must track their implementation counterparts. Treat them as specs, not tutorials.
+
+| Page | Tracks |
+|------|--------|
+| `rpc.md` | `packages/coding-agent/src/modes/rpc/` |
+| `app-server.md` | `packages/coding-agent/src/modes/app-server/` |
+| `json.md` | JSONL wire format and record shapes |
+| `session-format.md` | Session file structure and field types |
+
+Preserve LF line endings and exact field names in these pages. Field spellings and JSONL record
+structures are asserted by tests; prose-only rewording can still break them.
+
+## Validators
+
+- `scripts/check-mcp-docs.test.mjs`: Parses `config-schema.ts` key names as raw text and
+  checks that every field has a `### \`field\`` heading in `mcp.md`. Runs under
+  `npm run test:scripts`. Schema additions without a matching doc heading break CI.
+
+- `packages/coding-agent/test/qa/app-server/task20-doc-example-check.ts`: Spins up a live
+  app-server process and validates that JSON examples in `app-server.md` match actual server
+  behavior. Prose edits to `app-server.md` that change JSON shapes will fail this test.
+
+## Terminology
+
+Docs mix `senpi` and upstream `Pi` branding in legacy text. Don't do broad rebrand sweeps
+during focused edits; update only the immediate context you're working in.
+
+Consistent names: CLI binary is `senpi`, config directory is `.senpi`, npm package is
+`@code-yeongyu/senpi`. Don't use `codex`, `pi`, or `openai-codex` in new prose.
+
+## Security rules
+
+- `bearerTokenEnv` names an environment variable, not a token value. Examples must never put
+  a literal token in the JSON config; the implementation warns when it detects one.
+- OAuth tokens persist under the agent directory at runtime. Don't surface them in doc examples
+  or log snippets.
+- MCP config values are not shell-expanded. Don't document or imply `$VAR` substitution in
+  JSON config examples.
+- `mcp.md` must not advertise URL-mode elicitation; it's not a shipped feature.
+
+## Anti-patterns
+
+- No new `.md` file without a `docs.json` entry.
+- Don't edit protocol page prose without checking whether `task20-doc-example-check.ts` or
+  `check-mcp-docs.test.mjs` would break.
+- Don't copy claims from upstream Pi docs without verifying they apply to the senpi fork.
+- Don't embed bearer tokens, session IDs, or raw API keys in example output.

package/docs/custom-provider.md

@@ -30,10 +30,38 @@ See these complete provider examples:
 
 ## Quick Reference
 
+Extensions can register either a complete pi-ai `Provider` or use the legacy provider-config form. Prefer a complete provider when custom authentication, filtering, refresh, or streaming behavior is required. Pi composes `models.json` overrides above registered native providers.
+
 ```typescript
+import { createProvider, openAICompletionsApi } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@code-yeongyu/senpi";
 
 export default function (pi: ExtensionAPI) {
+  pi.registerProvider(createProvider({
+    id: "native-local",
+    name: "Native Local",
+    baseUrl: "http://localhost:8080/v1",
+    auth: {
+      apiKey: {
+        name: "Local server API key",
+        async login(interaction) {
+          return {
+            type: "api_key",
+            key: await interaction.prompt({ type: "secret", message: "API key" })
+          };
+        },
+        async resolve({ credential }) {
+          return credential?.key
+            ? { auth: { apiKey: credential.key }, source: "stored API key" }
+            : undefined;
+        }
+      }
+    },
+    models: [],
+    api: openAICompletionsApi()
+  }));
+
+  // Legacy provider-config form:
   // Override baseUrl for existing provider
   pi.registerProvider("anthropic", {
     baseUrl: "https://proxy.example.com"

package/docs/extensions.md

@@ -12,6 +12,7 @@ Extensions are TypeScript modules that extend pi's behavior. They can subscribe
 - **User interaction** - Prompt users via `ctx.ui` (select, confirm, input, notify)
 - **Custom UI components** - Full TUI components with keyboard input via `ctx.ui.custom()` for complex interactions
 - **Custom commands** - Register commands like `/mycommand` via `pi.registerCommand()`
+- **Model fallback** - The bundled [`/fallback`](#bundled-fallback-command) command manages global per-model retry chains. Use `/fallback <target> <fallback1> [fallback2 ...]` for scripts, or `/fallback` in the TUI to view and edit chains. `--no-model-fallback` and `SENPI_NO_FALLBACK=1` disable it for one run.
 - **Session persistence** - Store state that survives restarts via `pi.appendEntry()`
 - **Custom rendering** - Control how tool calls/results and messages appear in TUI
 
@@ -31,6 +32,7 @@ See [examples/extensions/](../examples/extensions/) for working implementations.
 ## Table of Contents
 
 - [Quick Start](#quick-start)
+- [Bundled /fallback Command](#bundled-fallback-command)
 - [Extension Locations](#extension-locations)
 - [Available Imports](#available-imports)
 - [Writing an Extension](#writing-an-extension)
@@ -106,6 +108,32 @@ Test with `--extension` (or `-e`) flag:
 pi -e ./my-extension.ts
 ```
 
+## Bundled /fallback Command
+
+The bundled `model-fallback` extension registers `/fallback` to manage global per-model retry fallback chains. The command writes through the active session settings manager, so a saved chain is available to the current session's next retry without restarting Senpi. See [Settings](settings.md#model-fallback-chains) for selector syntax and runtime behavior.
+
+Use the quick-set form in scripts or any non-TUI mode:
+
+```text
+/fallback anthropic/claude-fable-5 ccapi/kimi-k3:max
+```
+
+The first argument is the exact primary model selector; each later argument is an ordered fallback selector. Quick-set validates selectors before saving. At least one fallback is required:
+
+```text
+/fallback <target> <fallback1> [fallback2 ...]
+```
+
+Run `/fallback` without arguments in the TUI for a menu that can:
+
+- show configured chains and live fallback state;
+- add or edit a chain by choosing the target, each fallback, and either an explicit or inherited thinking level;
+- remove a chain;
+- toggle `retry.modelFallback`; and
+- choose `retry.fallbackRevertPolicy` (`cooldown-expiry` or `never`).
+
+Use quick-set in non-TUI modes; the no-argument menu requires interactive UI. Pass `--no-model-fallback` or set `SENPI_NO_FALLBACK=1` to disable fallback for that process without modifying saved settings.
+
 ## Extension Locations
 
 > **Security:** Extensions run with your full system permissions and can execute arbitrary code. Only install from sources you trust.
@@ -977,7 +1005,7 @@ ctx.sessionManager.getLeafId()              // Current leaf entry ID
 
 ### ctx.modelRegistry / ctx.model
 
-Access to models and API keys.
+Access to models, providers, and resolved authentication. `ctx.modelRegistry.getProvider(id)` returns the effective pi-ai provider, while `getProviderAuth(id)` resolves its current API key, headers, base URL, and provider-scoped environment without requiring a loaded model. `ctx.model` is the active model.
 
 ### ctx.signal
 
@@ -1376,6 +1404,52 @@ pi.registerTool({
 });
 ```
 
+### pi.registerMcpServer(name, config)
+
+Register an MCP server that the agent can use. This is a **factory-time only**
+API: it must be called inside the extension factory before the factory returns.
+Calling it after startup throws because registration is tied to extension load.
+
+`config` accepts the same fields as `mcpServers.<name>` in `mcp.json` (see the
+[MCP server fields reference](mcp.md#server-fields-mcpserversname)): `type`,
+`command`, `args`, `env`, `cwd`, `url`, `headers`, `auth`, `enabled`,
+`lifecycle`, timeouts, `includeTools`, `excludeTools`, `directTools`,
+`exposure`, and `logLevel`.
+
+```typescript
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerMcpServer("docs", {
+    type: "stdio",
+    command: "npx",
+    args: ["-y", "@example/docs-mcp"],
+    env: { DOCS_TOKEN: "${DOCS_TOKEN}" },
+  });
+}
+```
+
+Validation runs synchronously when you call `registerMcpServer`. An invalid
+declaration (unknown fields, a stdio server without `command`, an http server
+without `url`, etc.) throws an error and fails **only** the declaring extension;
+other extensions still load.
+
+Same-name precedence:
+
+- User config from `mcp.json` (`global`, imported `claude`, or trusted
+  `project`) wins over an extension-declared server, including `enabled: false`.
+- An extension-declared server replaces an untrusted placeholder from an
+  untrusted project config and records a diagnostic.
+- Across extensions, the first loaded extension wins; later collisions log a
+  warning naming both extension paths.
+
+A stdio declaration that omits `cwd` defaults to the extension's registration
+cwd (the cwd passed to the factory), not the ambient `process.cwd()`.
+
+Extension factories re-run on `/reload`, so declarations are refreshed then.
+In-process senpi-task children load no extensions, so they see no
+extension-declared MCP servers.
+
 ### pi.sendMessage(message, options?)
 
 Inject a custom message into the session. Custom messages participate in LLM context. For durable TUI-only content that should not be sent to the LLM, use [`pi.appendEntry()`](#piappendentrycustomtype-data) with [`pi.registerEntryRenderer()`](#piregisterentryrenderercustomtype-renderer).
@@ -1679,7 +1753,37 @@ Calls made during the extension factory function are queued and applied once the
 
 Dynamic providers can implement `refreshModels`. Pi calls it during model refresh, publishes the returned list synchronously through the provider, and passes the canonical credential/store/network/signal context. The extension decides whether to persist the catalog through `context.store`; live servers such as llama.cpp can ignore it.
 
+Extensions that need native provider auth, filtering, refresh, or stream behavior can register a complete `Provider` from `@earendil-works/pi-ai`. The provider becomes the composition base and `models.json` overrides still apply above it.
+
 ```typescript
+import { createProvider, openAICompletionsApi } from "@earendil-works/pi-ai";
+
+const provider = createProvider({
+  id: "local-server",
+  name: "Local Server",
+  baseUrl: "http://localhost:8080/v1",
+  auth: {
+    apiKey: {
+      name: "Local server setup",
+      async login(interaction) {
+        return {
+          type: "api_key",
+          key: await interaction.prompt({ type: "secret", message: "API key" }),
+        };
+      },
+      async resolve({ credential }) {
+        return credential?.key
+          ? { auth: { apiKey: credential.key }, source: "stored API key" }
+          : undefined;
+      },
+    },
+  },
+  models: [],
+  api: openAICompletionsApi(),
+});
+
+pi.registerProvider(provider);
+
 // Register a new provider with custom models
 pi.registerProvider("my-proxy", {
   name: "My Proxy",
@@ -1748,7 +1852,9 @@ pi.registerProvider("corporate-ai", {
 });
 ```
 
-**Config options:**
+The object form accepts a complete pi-ai `Provider`, including native `auth`, `getModels`, `refreshModels`, `filterModels`, `stream`, and `streamSimple` behavior.
+
+**Legacy config options:**
 - `name` - Display name for the provider in UI such as `/login`.
 - `baseUrl` - API endpoint URL. Required when defining models.
 - `apiKey` - API key literal, environment interpolation (`$ENV_VAR` or `${ENV_VAR}`), or leading `!command`. Required when defining models (unless `oauth` provided). `$$` escapes `$`, and `$!` escapes a literal `!` without triggering command execution.
@@ -2708,8 +2814,8 @@ class VimEditor extends CustomEditor {
 
 export default function (pi: ExtensionAPI) {
   pi.on("session_start", (_event, ctx) => {
-    ctx.ui.setEditorComponent((_tui, theme, keybindings) =>
-      new VimEditor(theme, keybindings)
+    ctx.ui.setEditorComponent((tui, theme, keybindings) =>
+      new VimEditor(tui, theme, keybindings)
     );
   });
 }
@@ -2718,7 +2824,7 @@ export default function (pi: ExtensionAPI) {
 **Key points:**
 - Extend `CustomEditor` (not base `Editor`) to get app keybindings (escape to abort, ctrl+d, model switching)
 - Call `super.handleInput(data)` for keys you don't handle
-- Factory receives `theme` and `keybindings` from the app
+- Factory receives `tui`, `theme`, and `keybindings` from the app
 - Use `ctx.ui.getEditorComponent()` before `setEditorComponent()` to wrap the previously configured custom editor
 - Pass `undefined` to restore default: `ctx.ui.setEditorComponent(undefined)`
 

package/docs/index.md

@@ -33,6 +33,7 @@ For the full first-run flow, see [Quickstart](quickstart.md).
 - [Quickstart](quickstart.md) - install, authenticate, and run a first session.
 - [Using Senpi](usage.md) - interactive mode, slash commands, context files, and CLI reference.
 - [Providers](providers.md) - subscription and API-key setup for built-in providers.
+- [llama.cpp](llama-cpp.md) - run a local router and manage models with `/llama`.
 - [Security](security.md) - project trust, sandbox boundaries, and vulnerability reporting.
 - [Containerization](containerization.md) - sandbox senpi with Gondolin, Docker, or OpenShell.
 - [Settings](settings.md) - global and project settings.

package/docs/llama-cpp.md

@@ -0,0 +1,99 @@
+# llama.cpp
+
+Pi supports the [llama.cpp](https://github.com/ggml-org/llama.cpp) router server. The router discovers multiple GGUF models and loads or unloads them on demand.
+
+Use a current llama.cpp build with router support. Follow the [build instructions](https://github.com/ggml-org/llama.cpp/blob/master/docs/build.md) or install a [prebuilt release](https://github.com/ggml-org/llama.cpp/releases) for your platform.
+
+## Start the router
+
+Start `llama-server` without `--model` or `-m`. Passing a model starts single-model mode instead of router mode.
+
+```bash
+llama-server \
+  --models-dir ~/models \
+  --no-models-autoload \
+  --jinja \
+  --host 127.0.0.1 \
+  --port 8080 \
+  -ngl 999 \
+  -c 32768
+```
+
+Important options:
+
+- `--models-dir ~/models` discovers local GGUF files.
+- `--no-models-autoload` keeps loading explicit through `/llama`.
+- `--jinja` enables compatible chat templates and tool calling.
+- `-ngl 999` offloads as many layers as possible to the GPU.
+- `-c 32768` sets the context window for each loaded model. Omit it to use the model's native context, which may require substantially more memory.
+
+A single-file model can sit directly in the model directory. Put multimodal and multi-shard models in separate subdirectories:
+
+```text
+~/models/
+├── llama-3.2-1b-Q4_K_M.gguf
+├── gemma-3-4b-it-Q4_K_M/
+│   ├── gemma-3-4b-it-Q4_K_M.gguf
+│   └── mmproj-F16.gguf
+└── large-model-Q4_K_M/
+    ├── large-model-Q4_K_M-00001-of-00003.gguf
+    ├── large-model-Q4_K_M-00002-of-00003.gguf
+    └── large-model-Q4_K_M-00003-of-00003.gguf
+```
+
+Restart the router after manually adding files. For per-model context sizes and other options, use [llama.cpp model presets](https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md#model-presets).
+
+## Configure Pi
+
+Start Pi and configure the provider:
+
+```text
+/login llama.cpp
+```
+
+Enter the router URL and optional API key. The default URL is `http://127.0.0.1:8080`.
+
+Environment variables can configure the same values without `/login`:
+
+```bash
+export LLAMA_BASE_URL=http://127.0.0.1:8080
+export LLAMA_API_KEY=optional-secret
+pi
+```
+
+If the server uses an API key, start `llama-server` with the matching `--api-key` value. Keep `--host 127.0.0.1` for local-only access.
+
+## Manage models
+
+Run:
+
+```text
+/llama
+```
+
+- Select an unloaded model to load it.
+- Select a loaded model to unload it.
+- Select **Download model…**, search Hugging Face, then choose a repository and quantization. Exact `owner/repository[:quant]` values also work.
+- Press Escape during a load or download to confirm cancellation.
+
+Hugging Face search uses `HF_TOKEN` when set, then checks `$HF_TOKEN_PATH`, `$HF_HOME/token`, `$XDG_CACHE_HOME/huggingface/token`, and `~/.cache/huggingface/token`. Search also works without authentication, subject to lower rate limits. Pi warns before downloading gated repositories and links to their access page. The llama.cpp server performs the download, so its process must also have `HF_TOKEN` when the selected repository requires access.
+
+If other models are loaded, Pi asks whether to unload them first or keep them loaded. Pi does not silently unload models and never deletes model files. The router may be shared with other clients, so `/llama` always displays the router's current state.
+
+Only loaded models appear in `/model`. After loading a model, run `/model` to select it for the current Pi session.
+
+If the router disconnects, `/llama` shows **Retry** and **Close**. Retry reconnects and refreshes model state without replaying the interrupted operation.
+
+## Troubleshooting
+
+Check that the router is reachable:
+
+```bash
+curl http://127.0.0.1:8080/health
+curl http://127.0.0.1:8080/models
+```
+
+- **No models in `/llama`:** Check `--models-dir`, the directory layout, and restart the router.
+- **Model missing from `/model`:** Load it with `/llama` first.
+- **Load fails or uses too much memory:** Lower `-c` or unload another model.
+- **Server is not in router mode:** Start it without `--model`, `-m`, or `-hf`.

package/docs/mcp.md

@@ -26,7 +26,7 @@ catalog costs almost nothing until the model actually needs it.
    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)).
+   `tool_search` (see [Exposure tiers](#exposure-tiers)).
 
 ## Configuration reference
 
@@ -95,7 +95,7 @@ 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.
+that stay active while the rest goes behind `tool_search`. Default: none.
 
 ### `exposure`
 `"auto"` (default), `"direct"`, `"search"`, or `"proxy"`. See
@@ -134,14 +134,14 @@ 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.
+local `tool_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 |
+| search (Tier-B) | `exposure:"search"` or `auto` above the threshold | Full catalog registered, ~135 tokens resident (`tool_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
@@ -149,6 +149,22 @@ Skills can carry MCP servers too (an `mcp.json` sidecar next to SKILL.md, or a
 reveal their `includeTools` matches when the skill loads. A name collision
 with a configured server resolves in favor of your config.
 
+### Server sources
+
+Servers are merged from these sources, in precedence order:
+
+- `global` — `<agentDir>/mcp.json`
+- `claude` — imported `.mcp.json` (requires project trust)
+- `project` — `.senpi/mcp.json` (requires project trust)
+- `extension` — declared by an extension via `pi.registerMcpServer()` during
+  factory load (see [extensions.md](extensions.md#piregistermcpservername-config))
+- `skill` — declared in a skill's `mcp.json` sidecar or SKILL.md frontmatter
+
+A name collision resolves as follows: trusted user config (including an
+`enabled: false` entry) wins over extension declarations; an extension
+declaration replaces an untrusted placeholder and records a diagnostic.
+Extension-declared servers use bare names (no prefix).
+
 ## Resources and prompts
 
 - `mcp_list_resources` / `mcp_read_resource` register automatically when a
@@ -181,7 +197,7 @@ with a configured server resolves in favor of your config.
 | `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` |
+| tools missing | server filtered/disabled, or hidden behind search | check `includeTools`/`excludeTools`, ask the model to `tool_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"` |
 

package/docs/neo.md

@@ -46,7 +46,8 @@ 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
+scoping, resource loading, system prompt overrides, 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.

package/docs/prompt-templates.md

@@ -69,6 +69,7 @@ Templates support positional arguments, defaults, and simple slicing:
 - `$1`, `$2`, ... positional args
 - `$@` or `$ARGUMENTS` for all args joined
 - `${1:-default}` uses arg 1 when present/non-empty, otherwise `default`
+- `${@:-default}` or `${ARGUMENTS:-default}` uses all arguments when present/non-empty, otherwise `default`
 - `${@:N}` for args from the Nth position (1-indexed)
 - `${@:N:L}` for `L` args starting at N
 

package/docs/providers.md

@@ -8,6 +8,7 @@ Pi supports subscription-based providers via OAuth and API key providers via env
 - [API Keys](#api-keys)
 - [Auth File](#auth-file)
 - [Cloud Providers](#cloud-providers)
+- [llama.cpp](#llamacpp)
 - [Custom Providers](#custom-providers)
 - [Resolution Order](#resolution-order)
 
@@ -274,6 +275,12 @@ export GOOGLE_CLOUD_LOCATION=us-central1
 
 Or set `GOOGLE_APPLICATION_CREDENTIALS` to a service account key file.
 
+## llama.cpp
+
+Pi supports the llama.cpp router server. Configure it with `/login llama.cpp`, manage loaded models with `/llama`, and select a loaded model with `/model`.
+
+See [llama.cpp](llama-cpp.md) for server setup, model directory layout, environment variables, and command usage.
+
 ## Custom Providers
 
 **Via models.json:** Add Ollama, LM Studio, vLLM, or any provider that speaks a supported API (OpenAI Completions, OpenAI Responses, Anthropic Messages, Google Generative AI). See [models.md](models.md).