@selesai/code 0.5.28 → 0.6.1

package/dist/utils/version-check.js.map

@@ -1 +1 @@
-{"version":3,"file":"version-check.js","sourceRoot":"","sources":["../../src/utils/version-check.ts"],"names":[],"mappings":"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","sourcesContent":["import { compare, valid } from \"semver\";\nimport { getPiUserAgent } from \"./pi-user-agent.ts\";\n\nconst LATEST_VERSION_URL = \"https://pi.dev/api/latest-version\";\nconst NPM_REGISTRY_URL = \"https://registry.npmjs.org\";\nconst DEFAULT_VERSION_CHECK_TIMEOUT_MS = 10000;\nconst PACKAGE_NAME: string = \"@selesai/code\";\n\nexport interface LatestPiRelease {\n\tversion: string;\n\tpackageName?: string;\n\tnote?: string;\n}\n\nexport function comparePackageVersions(leftVersion: string, rightVersion: string): number | undefined {\n\tconst left = valid(leftVersion.trim());\n\tconst right = valid(rightVersion.trim());\n\tif (!left || !right) {\n\t\treturn undefined;\n\t}\n\treturn compare(left, right);\n}\n\nexport function isNewerPackageVersion(candidateVersion: string, currentVersion: string): boolean {\n\tconst comparison = comparePackageVersions(candidateVersion, currentVersion);\n\tif (comparison !== undefined) {\n\t\treturn comparison > 0;\n\t}\n\treturn candidateVersion.trim() !== currentVersion.trim();\n}\n\nexport async function getLatestPiRelease(\n\tcurrentVersion: string,\n\toptions: { timeoutMs?: number } = {},\n): Promise<LatestPiRelease | undefined> {\n\tif (process.env.PI_SKIP_VERSION_CHECK || process.env.PI_OFFLINE) return undefined;\n\n\tconst response = await fetch(LATEST_VERSION_URL, {\n\t\theaders: {\n\t\t\t\"User-Agent\": getPiUserAgent(currentVersion),\n\t\t\taccept: \"application/json\",\n\t\t},\n\t\tsignal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_VERSION_CHECK_TIMEOUT_MS),\n\t});\n\tif (!response.ok) return undefined;\n\n\tconst data = (await response.json()) as {\n\t\tpackageName?: unknown;\n\t\tversion?: unknown;\n\t\tnote?: unknown;\n\t};\n\tif (typeof data.version !== \"string\" || !data.version.trim()) {\n\t\treturn undefined;\n\t}\n\tconst packageName =\n\t\ttypeof data.packageName === \"string\" && data.packageName.trim() ? data.packageName.trim() : undefined;\n\tconst note = typeof data.note === \"string\" && data.note.trim() ? data.note.trim() : undefined;\n\treturn {\n\t\tversion: data.version.trim(),\n\t\tpackageName,\n\t\t...(note ? { note } : {}),\n\t};\n}\n\nexport async function getLatestPackageRelease(\n\tpackageName: string,\n\tcurrentVersion: string,\n\toptions: { timeoutMs?: number } = {},\n): Promise<LatestPiRelease | undefined> {\n\tif (process.env.PI_SKIP_VERSION_CHECK || process.env.PI_OFFLINE) return undefined;\n\n\tconst response = await fetch(`${NPM_REGISTRY_URL}/${encodeURIComponent(packageName)}`, {\n\t\theaders: {\n\t\t\t\"User-Agent\": getPiUserAgent(currentVersion),\n\t\t\taccept: \"application/json\",\n\t\t},\n\t\tsignal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_VERSION_CHECK_TIMEOUT_MS),\n\t});\n\tif (!response.ok) return undefined;\n\n\tconst data = (await response.json()) as { \"dist-tags\"?: { latest?: unknown } };\n\tconst version = data[\"dist-tags\"]?.latest;\n\tif (typeof version !== \"string\" || !version.trim()) return undefined;\n\treturn { version: version.trim(), packageName };\n}\n\nexport async function getLatestPiVersion(\n\tcurrentVersion: string,\n\toptions: { timeoutMs?: number } = {},\n): Promise<string | undefined> {\n\treturn (await getLatestPiRelease(currentVersion, options))?.version;\n}\n\nexport async function checkForNewPiVersion(\n\tcurrentVersion: string,\n\tpackageName: string = PACKAGE_NAME,\n\toptions: { timeoutMs?: number } = {},\n): Promise<LatestPiRelease | undefined> {\n\tconst release = await getLatestPackageRelease(packageName, currentVersion, options);\n\tif (!release) return undefined;\n\treturn isNewerPackageVersion(release.version, currentVersion) ? release : undefined;\n}\n"]}
+{"version":3,"file":"version-check.js","sourceRoot":"","sources":["../../src/utils/version-check.ts"],"names":[],"mappings":"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","sourcesContent":["import { compare, valid } from \"semver\";\nimport { getPiUserAgent } from \"./pi-user-agent.ts\";\n\nconst LATEST_VERSION_URL = \"https://pi.dev/api/latest-version\";\nconst NPM_REGISTRY_URL = \"https://registry.npmjs.org\";\nconst DEFAULT_VERSION_CHECK_TIMEOUT_MS = 10000;\nconst PACKAGE_NAME: string = \"@selesai/code\";\n\nexport interface LatestPiRelease {\n\tversion: string;\n\tpackageName?: string;\n\tnote?: string;\n}\n\nexport function comparePackageVersions(leftVersion: string, rightVersion: string): number | undefined {\n\tconst left = valid(leftVersion.trim());\n\tconst right = valid(rightVersion.trim());\n\tif (!left || !right) {\n\t\treturn undefined;\n\t}\n\treturn compare(left, right);\n}\n\nexport function isNewerPackageVersion(candidateVersion: string, currentVersion: string): boolean {\n\tconst comparison = comparePackageVersions(candidateVersion, currentVersion);\n\tif (comparison !== undefined) {\n\t\treturn comparison > 0;\n\t}\n\treturn candidateVersion.trim() !== currentVersion.trim();\n}\n\nexport async function getLatestPiRelease(\n\tcurrentVersion: string,\n\toptions: { timeoutMs?: number } = {},\n): Promise<LatestPiRelease | undefined> {\n\tif (process.env.PI_OFFLINE) return undefined;\n\n\tconst response = await fetch(LATEST_VERSION_URL, {\n\t\theaders: {\n\t\t\t\"User-Agent\": getPiUserAgent(currentVersion),\n\t\t\taccept: \"application/json\",\n\t\t},\n\t\tsignal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_VERSION_CHECK_TIMEOUT_MS),\n\t});\n\tif (!response.ok) return undefined;\n\n\tconst data = (await response.json()) as {\n\t\tpackageName?: unknown;\n\t\tversion?: unknown;\n\t\tnote?: unknown;\n\t};\n\tif (typeof data.version !== \"string\" || !data.version.trim()) {\n\t\treturn undefined;\n\t}\n\tconst packageName =\n\t\ttypeof data.packageName === \"string\" && data.packageName.trim() ? data.packageName.trim() : undefined;\n\tconst note = typeof data.note === \"string\" && data.note.trim() ? data.note.trim() : undefined;\n\treturn {\n\t\tversion: data.version.trim(),\n\t\tpackageName,\n\t\t...(note ? { note } : {}),\n\t};\n}\n\nexport async function getLatestPackageRelease(\n\tpackageName: string,\n\tcurrentVersion: string,\n\toptions: { timeoutMs?: number } = {},\n): Promise<LatestPiRelease | undefined> {\n\tif (process.env.PI_SKIP_VERSION_CHECK || process.env.PI_OFFLINE) return undefined;\n\n\tconst response = await fetch(`${NPM_REGISTRY_URL}/${encodeURIComponent(packageName)}`, {\n\t\theaders: {\n\t\t\t\"User-Agent\": getPiUserAgent(currentVersion),\n\t\t\taccept: \"application/json\",\n\t\t},\n\t\tsignal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_VERSION_CHECK_TIMEOUT_MS),\n\t});\n\tif (!response.ok) return undefined;\n\n\tconst data = (await response.json()) as { \"dist-tags\"?: { latest?: unknown } };\n\tconst version = data[\"dist-tags\"]?.latest;\n\tif (typeof version !== \"string\" || !version.trim()) return undefined;\n\treturn { version: version.trim(), packageName };\n}\n\nexport async function getLatestPiVersion(\n\tcurrentVersion: string,\n\toptions: { timeoutMs?: number } = {},\n): Promise<string | undefined> {\n\treturn (await getLatestPiRelease(currentVersion, options))?.version;\n}\n\nexport async function checkForNewPiVersion(\n\tcurrentVersion: string,\n\tpackageName: string = PACKAGE_NAME,\n\toptions: { timeoutMs?: number } = {},\n): Promise<LatestPiRelease | undefined> {\n\tconst release = await getLatestPackageRelease(packageName, currentVersion, options);\n\tif (!release) return undefined;\n\treturn isNewerPackageVersion(release.version, currentVersion) ? release : undefined;\n}\n"]}

package/docs/compaction.md

@@ -20,7 +20,7 @@ Pi has two summarization mechanisms:
 | Compaction | Context exceeds threshold, or `/compact` | Summarize old messages to free up context |
 | Branch summarization | `/tree` navigation | Preserve context when switching branches |
 
-Both use the same structured summary format and track file operations cumulatively.
+Both use the same structured summary format and track file operations cumulatively. Compaction and branch-summary requests use fresh routing session IDs and, where supported by the provider, disable prompt-cache writes because these one-off prompts are unlikely to be reused.
 
 ## Compaction
 

package/docs/custom-provider.md

@@ -230,7 +230,7 @@ models: [{
 ```
 
 Use `openrouter` for OpenRouter-style `reasoning: { effort }` controls. Use `together` for Together-style `reasoning: { enabled }` controls; with `supportsReasoningEffort`, it also sends `reasoning_effort`. Use `qwen-chat-template` for local Qwen-compatible servers that read `chat_template_kwargs.enable_thinking` and need `preserve_thinking`.
-Use `cacheControlFormat: "anthropic"` for OpenAI-compatible providers that expose Anthropic-style prompt caching via `cache_control` on the system prompt, last tool definition, and last user/assistant text content.
+Use `cacheControlFormat: "anthropic"` for OpenAI-compatible providers that expose Anthropic-style prompt caching via `cache_control` on the system prompt, last tool definition, and last user, assistant, or tool-result text content.
 
 For Anthropic-compatible providers using `api: "anthropic-messages"`, set `compat.forceAdaptiveThinking: true` on models or providers whose upstream model requires adaptive thinking (`thinking.type: "adaptive"` plus `output_config.effort`). Built-in adaptive Claude models set this automatically. Set `compat.allowEmptySignature: true` only for providers that emit empty thinking signatures and expect `signature: ""` on replay.
 
@@ -417,7 +417,7 @@ function streamMyProvider(
         totalTokens: 0,
         cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
       },
-      stopReason: "stop",
+      stopReason: "pending",
       timestamp: Date.now(),
     };
 
@@ -426,12 +426,18 @@ function streamMyProvider(
       stream.push({ type: "start", partial: output });
 
       // Make API request and process response...
-      // Push content events as they arrive...
+      // Push content events as they arrive and set stopReason from the terminal event.
+      if (output.stopReason === "pending") {
+        throw new Error("Provider stream ended without a stop reason");
+      }
+      if (output.stopReason === "error" || output.stopReason === "aborted") {
+        throw new Error(output.errorMessage || "An unknown error occurred");
+      }
 
       // Push done event
       stream.push({
         type: "done",
-        reason: output.stopReason as "stop" | "length" | "toolUse",
+        reason: output.stopReason,
         message: output
       });
       stream.end();
@@ -713,6 +719,8 @@ interface ProviderModelConfig {
     supportsDeveloperRole?: boolean;
     supportsReasoningEffort?: boolean;
     supportsUsageInStreaming?: boolean;
+    supportsStrictMode?: boolean;
+    supportsOpenAIGrammarTools?: boolean; // openai-completions/openai-responses; false falls back to normal function tools
     maxTokensField?: "max_completion_tokens" | "max_tokens";
     requiresToolResultName?: boolean;
     requiresAssistantAfterToolResult?: boolean;
@@ -729,9 +737,10 @@ interface ProviderModelConfig {
     supportsCacheControlOnTools?: boolean;
     forceAdaptiveThinking?: boolean;
     allowEmptySignature?: boolean;
+    supportsStrictTools?: boolean;
   };
 }
 ```
 
 `openrouter` sends `reasoning: { effort }`. `deepseek` sends `thinking: { type: "enabled" | "disabled" }` and `reasoning_effort` when enabled. `together` sends `reasoning: { enabled }` and also `reasoning_effort` when `supportsReasoningEffort` is enabled. `qwen` is for DashScope-style top-level `enable_thinking`. Use `qwen-chat-template` for local Qwen-compatible servers that read `chat_template_kwargs.enable_thinking` and need `preserve_thinking`. Use `chat-template` for configurable `chat_template_kwargs`, for example DeepSeek V3.x behind vLLM with `chatTemplateKwargs: { "thinking": { "$var": "thinking.enabled" } }`.
-`cacheControlFormat: "anthropic"` applies Anthropic-style `cache_control` markers to the system prompt, last tool definition, and last user/assistant text content.
+`cacheControlFormat: "anthropic"` applies Anthropic-style `cache_control` markers to the system prompt, last tool definition, and last user, assistant, or tool-result text content.

package/docs/environment-variables.md

@@ -0,0 +1,86 @@
+# Environment Variables
+
+Selesai uses environment variables in three ways:
+
+- Selesai-specific variables configure its config and session directories.
+- Inherited `PI_*` protocol variables configure shared Pi runtime behavior.
+- Commands run by the LLM-callable bash tool receive `PI_*` variables describing the current session.
+
+Provider API-key variables are documented separately in [Providers](providers.md#environment-variables-or-auth-file).
+
+## Process Marker
+
+The CLI and RPC entry points set `PI_CODING_AGENT=true`. Child processes inherit it and can use it to detect a Pi-compatible coding-agent runtime. It is not session-specific and is not set automatically when Selesai is embedded through the SDK.
+
+## Bash Tool Session Environment
+
+Commands run by the bash tool receive the current Selesai session state:
+
+| Variable | Description |
+|----------|-------------|
+| `PI_SESSION_ID` | Current session ID |
+| `PI_SESSION_FILE` | Absolute path to the current session JSONL file; unset for ephemeral sessions |
+| `PI_PROVIDER` | Currently selected model provider |
+| `PI_MODEL` | Currently selected model ID |
+| `PI_REASONING_LEVEL` | Current effective reasoning level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` |
+
+The values are resolved when each command starts. Switching models or changing the reasoning level affects the next bash command without restarting Selesai. `PI_PROVIDER` and `PI_MODEL` identify the selected model, not a different upstream model that a router may choose internally.
+
+When asked which model or provider is running, inspect these variables instead of inferring the answer from the system prompt:
+
+```bash
+printf '%s/%s\n' "$PI_PROVIDER" "$PI_MODEL"
+printf 'reasoning=%s session=%s\n' "$PI_REASONING_LEVEL" "$PI_SESSION_ID"
+```
+
+The session file can be inspected directly when the session is persistent:
+
+```bash
+if [ -n "$PI_SESSION_FILE" ]; then
+  tail -n 1 "$PI_SESSION_FILE"
+fi
+```
+
+These variables are injected into the LLM-callable bash tool. They are not injected into user-entered `!` or `!!` commands.
+
+### Custom Bash Tools
+
+Bash tools created with `createBashTool()` expose the session environment by default when registered with Selesai. Injection happens before `spawnHook`, so a hook receives the variables in `ctx.env`:
+
+```typescript
+const bashTool = createBashTool(cwd, {
+  spawnHook: (ctx) => ({
+    ...ctx,
+    env: { ...ctx.env, CI: "1" },
+  }),
+});
+```
+
+Disable session metadata independently of the spawn hook:
+
+```typescript
+const bashTool = createBashTool(cwd, {
+  exposeSessionEnvironment: false,
+  spawnHook: (ctx) => ctx,
+});
+```
+
+When disabled, Selesai removes inherited values for these variables so nested coding-agent processes do not expose stale parent-session metadata.
+
+## Selesai Process Configuration
+
+| Variable | Description |
+|----------|-------------|
+| `SELESAI_CODING_AGENT_DIR` | Override the config directory; default is `~/.selesai/agent` |
+| `SELESAI_CODING_AGENT_SESSION_DIR` | Override session storage; overridden by `--session-dir` |
+| `PI_PACKAGE_DIR` | Override the package directory, useful for Nix/Guix store paths |
+| `PI_OFFLINE` | Disable startup network operations, including update checks, package updates, and install/update telemetry |
+| `PI_SKIP_VERSION_CHECK` | Disable the latest-version request |
+| `PI_TELEMETRY` | Override install/update telemetry and provider attribution headers: `1`/`true`/`yes` or `0`/`false`/`no` |
+| `PI_CACHE_RETENTION` | Set to `long` for extended provider prompt caching where supported |
+| `PI_SHARE_VIEWER_URL` | Override the base URL used by `/share` |
+| `PI_HARDWARE_CURSOR` | Set to `1` to show the hardware cursor; see [Terminal setup](terminal-setup.md) |
+| `VISUAL`, `EDITOR` | External editor fallback when `externalEditor` is unset |
+| `HTTP_PROXY`, `HTTPS_PROXY` | Proxy outbound HTTP requests |
+
+Provider credentials such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and cloud-provider configuration are listed in [Providers](providers.md#environment-variables-or-auth-file).

package/docs/extensions.md

@@ -937,9 +937,11 @@ ctx.sessionManager.getBranch()        // Current branch
 ctx.sessionManager.getLeafId()        // Current leaf entry ID
 ```
 
-### ctx.modelRegistry / ctx.model
+### ctx.modelRegistry / ctx.model / ctx.thinkingLevel / ctx.scopedModels
 
-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, and `ctx.thinkingLevel` is its current effective thinking level.
+
+`ctx.scopedModels` is the read-only list of models scoped to the current session — the same set the `/scoped-models` command shows. It is resolved at session start from the `--models` CLI flag and the `enabledModels` setting (matched against the available catalogue with minimatch on `provider/modelId` or a bare `modelId`). It is empty when no scoping is configured, meaning every available model is usable. Each entry is `{ model, thinkingLevel? }`, where `thinkingLevel` is set only when a pattern pinned it (e.g. `anthropic/*:high`). Use it to populate a model picker that mirrors the built-in one instead of enumerating the whole catalogue via `ctx.modelRegistry.getAvailable()`.
 
 ### ctx.signal
 
@@ -1974,7 +1976,15 @@ const bashTool = createBashTool(cwd, {
 });
 ```
 
-See [examples/extensions/ssh.ts](../examples/extensions/ssh.ts) for a complete SSH example with `--ssh` flag.
+`createBashTool()` exposes the current session to commands through `PI_SESSION_ID`, `PI_SESSION_FILE`, `PI_PROVIDER`, `PI_MODEL`, and `PI_REASONING_LEVEL`. Injection happens before `spawnHook`, so hooks receive these values in `env` and preserve them when they spread the existing environment as above. Set `exposeSessionEnvironment: false` to disable them:
+
+```typescript
+const bashTool = createBashTool(cwd, {
+  exposeSessionEnvironment: false,
+});
+```
+
+See [Bash tool session environment](environment-variables.md#bash-tool-session-environment) for variable semantics. See [examples/extensions/ssh.ts](../examples/extensions/ssh.ts) for a complete SSH example with `--ssh` flag.
 
 ### Output Truncation
 
@@ -2524,7 +2534,7 @@ Register a custom renderer for messages with your `customType`:
 import { Text } from "@earendil-works/pi-tui";
 
 pi.registerMessageRenderer("my-extension", (message, options, theme) => {
-  const { expanded } = options;
+  const { expanded, outputPad } = options;
   let text = theme.fg("accent", `[${message.customType}] `);
   text += message.content;
 
@@ -2532,7 +2542,7 @@ pi.registerMessageRenderer("my-extension", (message, options, theme) => {
     text += "\n" + theme.fg("dim", JSON.stringify(message.details, null, 2));
   }
 
-  return new Text(text, 0, 0);
+  return new Text(text, outputPad, 0);
 });
 ```
 

package/docs/index.md

@@ -67,6 +67,7 @@ For the full first-run flow, see [Quickstart](quickstart.md).
 
 ## Reference
 
+- [Environment variables](environment-variables.md) - Pi process configuration and session metadata available to bash tools.
 - [Session format](session-format.md) - JSONL session file format, entry types, and SessionManager API.
 
 ## Platform setup

package/docs/models.md

@@ -333,6 +333,8 @@ Some Anthropic models require adaptive thinking (`thinking.type: "adaptive"` plu
 
 Some Anthropic-compatible providers emit thinking blocks with empty signatures and still expect them on replay. Set `allowEmptySignature` to `true` only for those providers; real Anthropic rejects empty thinking signatures.
 
+Built-in Anthropic models enable `supportsStrictTools` in their model metadata. Custom Anthropic-compatible models must set it to `true` when their endpoint accepts strict JSON-schema tool definitions.
+
 ```json
 {
   "providers": {
@@ -366,6 +368,7 @@ Some Anthropic-compatible providers emit thinking blocks with empty signatures a
 | `supportsCacheControlOnTools` | Whether the provider accepts Anthropic-style `cache_control` markers on tool definitions. Default: `true`. |
 | `forceAdaptiveThinking` | Whether to send adaptive thinking (`thinking.type: "adaptive"` plus `output_config.effort`) for this model. Built-in adaptive models set this automatically. Default: `false`. |
 | `allowEmptySignature` | Whether to replay empty thinking signatures as `signature: ""` instead of converting thinking to text. Default: `false`. |
+| `supportsStrictTools` | Whether the provider accepts strict JSON-schema tool definitions. Default: `false`; built-in Anthropic models enable it in generated metadata. |
 
 ## OpenAI Compatibility
 
@@ -403,8 +406,12 @@ For providers with partial OpenAI compatibility, use the `compat` field.
 | `requiresReasoningContentOnAssistantMessages` | Include empty `reasoning_content` on all replayed assistant messages when reasoning is enabled |
 | `thinkingFormat` | Use `reasoning_effort`, `openrouter`, `deepseek`, `together`, `zai`, `qwen`, `chat-template`, or `qwen-chat-template` thinking parameters |
 | `chatTemplateKwargs` | `chat_template_kwargs` values for `thinkingFormat: "chat-template"`; use `{ "$var": "thinking.enabled" }` or `{ "$var": "thinking.effort" }` for pi-controlled thinking values |
-| `cacheControlFormat` | Use Anthropic-style `cache_control` markers on the system prompt, last tool definition, and last user/assistant text content. Currently only `anthropic` is supported. |
-| `supportsStrictMode` | Include the `strict` field in tool definitions |
+| `cacheControlFormat` | Use Anthropic-style `cache_control` markers on the system prompt, last tool definition, and last user, assistant, or tool-result text content. Currently only `anthropic` is supported. |
+| `sendSessionAffinityHeaders` | For `openai-completions`, send session-affinity headers from the session id when caching is enabled. Default: `false`. |
+| `sessionAffinityFormat` | For `openai-completions` and `openai-responses`, the session-affinity header format: `openai` sends `session_id`/`x-client-request-id` (completions also `x-session-affinity`), `openai-nosession` omits the underscore-containing `session_id` header, `openrouter` sends `x-session-id`. Does not affect the `prompt_cache_key` body param. Default: auto-detected. |
+| `supportsStrictMode` | Whether the provider accepts strict JSON-schema function tool definitions. Defaults depend on the API; built-in OpenAI models carry explicit capability metadata. |
+| `supportsOpenAIGrammarTools` | Whether OpenAI-compatible APIs emit custom Lark/regex grammar tools. When `false`, grammar-constrained tools fall back to normal function tools. Default: `false`; the built-in model catalog enables it for GPT-5+ models on OpenAI, OpenAI Codex, Azure OpenAI, GitHub Copilot, opencode, and Cloudflare AI Gateway. |
+| `deferredToolsMode` | Use provider-specific deferred tool serialization. Currently only `"kimi"` is supported for Kimi's OpenAI-compatible Chat Completions format. |
 | `supportsLongCacheRetention` | Whether the provider accepts long cache retention when cache retention is `long`: `prompt_cache_retention: "24h"` for OpenAI prompt caching, or `cache_control.ttl: "1h"` when `cacheControlFormat` is `anthropic`. Default: `true`. |
 | `openRouterRouting` | OpenRouter provider routing preferences. This object is sent as-is in the `provider` field of the [OpenRouter API request](https://openrouter.ai/docs/guides/routing/provider-selection). |
 | `vercelGatewayRouting` | Vercel AI Gateway routing config for provider selection (`only`, `order`) |

package/docs/plans/subagent-delegation/phase-0-correctness.md

@@ -0,0 +1,265 @@
+# Phase 0 Plan — Correctness Cleanup Before Delegation Changes
+
+## Objective
+
+Correct stale bundled-agent documentation and impossible builtin-agent contracts without changing intended delegation policy. Keep current runtime defaults authoritative: only `architect` and `recapper` fork by default; the other four builtins are fresh-context.
+
+## Non-goals
+
+- Do not redesign delegation behavior, context policy, model routing, or orchestration.
+- Do not grant `commentator` write tools.
+- Do not make `researcher` portable by adding new extension/package dependencies.
+- Do not alter user settings, user-home skills, `.selesai/`, `.pi-subagents/`, or unrelated dirty changes.
+- Do not run `npm run build`: it cleans `dist/` and can destroy unrelated dirty generated artifacts.
+
+## Review findings
+
+- **High — stale/mangled role docs:** `src/extensions/pi-subagents/skills/pi-subagents/references/prompting-and-roles.md:14,176-192,269` and `README.md:105-116,407` duplicate roles, omit `recapper`, and contain a false self-alias.
+- **High — context contradiction:** `constraints-and-recipes.md:8-9,106,141` and `execution-controls.md:363,369-376` claim `builder`/`commentator` fork by default; their frontmatter declares `fresh`.
+- **High — stale discovery paths:** `execution-controls.md:9-22` and additional README discovery/settings text describe `.pi`, although runtime discovers `.selesai` and legacy `.agents`.
+- **Medium — impossible/unsafe role contracts:** `agents/architect.md:38` tells a child without `question` or `subagent` access to use them; `agents/builder.md:7,21` requires bridge-only `contact_supervisor`; `agents/researcher.md:4` misclassifies MCP tools as builtin tools.
+- **Medium — output/tool-description drift:** role tables say read-only agents write output files and that `commentator` can receive edit/write tools from an explicit fix pass. Neither is true.
+
+## Discovery and baseline preservation
+
+1. From repository root, run:
+   ```bash
+   git status --short
+   git diff --check
+   git diff -- src/extensions/pi-subagents dist/extensions/pi-subagents
+   ```
+2. Record every pre-existing dirty path and hunk. Treat them as owned by another change.
+3. Before touching an affected `dist/extensions/pi-subagents/**` file, inspect its existing diff. If it is already dirty, manually merge only the Phase 0 documentation/agent hunk; never reset, checkout, clean, or overwrite unrelated content.
+4. Confirm these runtime facts before editing:
+   - `src/extensions/pi-subagents/src/agents/agents.ts`: `BUILTIN_AGENT_NAMES` is exactly `architect`, `builder`, `commentator`, `explorer`, `recapper`, `researcher`; discovery uses `.selesai/agents` plus legacy `.agents`.
+   - `src/extensions/pi-subagents/agents/*.md`: only `architect` and `recapper` have `defaultContext: fork`.
+   - `src/extensions/pi-subagents/src/intercom/intercom-bridge.ts:applyIntercomBridgeToAgent`: bridge tools are appended only when the bridge is active.
+   - `src/extensions/pi-subagents/src/runs/shared/pi-args.ts:resolvePiLaunchToolPlan` and `tool-availability.ts`: `tools` is a strict allowlist and `mcp:` values become direct MCP selections.
+
+## Files and ownership
+
+### Source files to modify
+
+| File | Ownership / required change |
+|---|---|
+| `src/extensions/pi-subagents/agents/architect.md` | Builtin planner’s executable prompt; remove unavailable-tool instructions. |
+| `src/extensions/pi-subagents/agents/builder.md` | Builtin writer’s declared tool contract and escalation instruction. |
+| `src/extensions/pi-subagents/agents/researcher.md` | Builtin researcher’s MCP-tool declaration. |
+| `src/extensions/pi-subagents/skills/pi-subagents/references/prompting-and-roles.md` | Canonical parent-skill role routing/table guidance. |
+| `src/extensions/pi-subagents/skills/pi-subagents/references/constraints-and-recipes.md` | Canonical default-context/workflow guidance. |
+| `src/extensions/pi-subagents/skills/pi-subagents/references/execution-controls.md` | Canonical discovery, context, and commentator-workflow guidance. |
+| `src/extensions/pi-subagents/README.md` | Public package documentation for builtin roles, paths, and defaults. |
+| `src/extensions/pi-subagents/test/unit/agent-frontmatter.test.ts` | Existing runtime-discovery test seam for builtin frontmatter. |
+| `src/extensions/pi-subagents/test/unit/builtin-agent-documentation.test.ts` (new) | Narrow regression test for six unique builtin roles in both public role tables. |
+
+### Generated package mirrors to synchronize
+
+Mirror only corresponding changed source assets into:
+
+- `dist/extensions/pi-subagents/agents/architect.md`
+- `dist/extensions/pi-subagents/agents/builder.md`
+- `dist/extensions/pi-subagents/agents/researcher.md`
+- `dist/extensions/pi-subagents/README.md`
+- `dist/extensions/pi-subagents/skills/pi-subagents/references/prompting-and-roles.md`
+- `dist/extensions/pi-subagents/skills/pi-subagents/references/constraints-and-recipes.md`
+- `dist/extensions/pi-subagents/skills/pi-subagents/references/execution-controls.md`
+
+Do **not** modify runtime TypeScript, user settings, skill installations, or unrelated `dist` output.
+
+## Ordered implementation tasks
+
+### 1. Correct impossible builtin-agent instructions
+
+1. In `agents/architect.md`, replace the sentence that says the architect should use an explorer agent and a “questions tool.”
+   - New instruction: inspect the repository directly with its available read/search tools.
+   - For unresolved user-owned decisions, require the architect to list them explicitly in the returned plan rather than trying to ask questions or launch a child.
+   - Do not add `question`, `interview`, `subagent`, or `contact_supervisor` to architect’s allowlist.
+
+2. In `agents/builder.md`:
+   - Remove `contact_supervisor` from the static `tools:` frontmatter list.
+   - Replace the unconditional instruction to call it with a conditional rule:
+     - when injected bridge instructions make `contact_supervisor` available, use it for unapproved decisions and wait;
+     - otherwise stop, do not guess, and report the exact blocking decision.
+   - Keep all existing core writer tools and the single-writer role unchanged.
+
+3. In `agents/researcher.md`, prefix `grep_app_search` and `grep_app_fetch` with `mcp:` in `tools:`.
+   - Preserve `read` and `web_explore`.
+   - Do not add `extensions` or `subagentOnlyExtensions`; that would introduce a separate dependency/policy decision.
+
+### 2. Repair role, output, capability, and specialty documentation
+
+1. In `prompting-and-roles.md`:
+   - Change “use `explorer` or `explorer`” to one `explorer`.
+   - Replace the malformed Builtin Agents table with exactly one row for each canonical builtin:
+     `architect`, `builder`, `commentator`, `explorer`, `recapper`, `researcher`.
+   - Describe outputs as final responses/artifacts only when caller-configured output persistence is used; never claim read-only agents write project files such as `context.md`, `plan.md`, or `research.md`.
+   - Describe `commentator` as review-only and `builder` as the writer. Remove the claim that a fix pass automatically grants commentator `edit`/`write`.
+   - Include `recapper` as the fork-context handoff specialist.
+   - Replace the false strict-isolation statement with: explicit `tools` is an allowlist, but ambient extension discovery remains possible unless `extensions`, `subagentOnlyExtensions`, or a capability ceiling constrains it; naming a tool alone does not load its provider.
+   - Remove duplicate `builder` in model-tier examples; use real builtins only.
+
+2. In `README.md`:
+   - Replace “Builtin agents in plain English” with the same six unique roles and accurate specialties.
+   - Update the rule of thumb to use `recapper` for a clean current-state handoff, rather than repeating `commentator`.
+   - Remove stale claims that `commentator` is an alias or can make small fixes, and remove obsolete researcher tool names/install guidance.
+   - Correct `.pi` project path/root references to `.selesai`, retaining `.agents` only where runtime actually supports legacy discovery.
+   - State the true context defaults: `architect` and `recapper` fork; `builder`, `commentator`, `explorer`, and `researcher` are fresh.
+   - Remove duplicate/nonexistent “lightweight builder” examples from model-tier text.
+
+### 3. Align context and discovery references with runtime
+
+1. In `constraints-and-recipes.md`:
+   - Replace all duplicated context-default lists with the actual six-agent split.
+   - Change builder guidance from “defaults to fork; pass fresh” to “defaults to fresh; pass fork only when inherited parent context is intentionally required.”
+   - Correct duplicate `explorer` references in Fable/clarify workflow prose.
+   - Keep explicit fresh-context review guidance unchanged.
+
+2. In `execution-controls.md`:
+   - Replace canonical `.pi/agents` and `.pi/chains` paths with `.selesai/agents` and `.selesai/chains`.
+   - State that `.agents` is legacy agent discovery only; do not invent legacy chain discovery.
+   - Replace nearest-root `.pi` wording with `.selesai` or `.agents`.
+   - Rewrite the commentator workflow to show fresh context as the default and an explicit `context: "fork"` only when a branched advisory thread is intended.
+   - Correct builder example prose to state that builder is fresh by default and fork is explicit.
+   - Keep the bridge-injection caveat for `contact_supervisor`; it is accurate once the builder prompt becomes conditional.
+
+### 4. Add focused regression coverage
+
+1. Extend `agent-frontmatter.test.ts`:
+   - Replace the partial fork assertion with a complete expected map for all six builtins:
+     - `architect`, `recapper` → `fork`
+     - `builder`, `commentator`, `explorer`, `researcher` → `fresh`
+   - Assert builder’s static builtin tools do not include `contact_supervisor`.
+   - Assert researcher discovery produces:
+     - builtin tools: `read`, `web_explore`
+     - `mcpDirectTools`: `grep_app_search`, `grep_app_fetch`.
+
+2. Add `builtin-agent-documentation.test.ts`:
+   - Read source `README.md` and `skills/pi-subagents/references/prompting-and-roles.md`.
+   - Extract the first-column agent names from each respective builtin-role table.
+   - Assert each table has exactly the six names in `BUILTIN_AGENT_NAMES`, with no duplicates and no aliases.
+   - Do not test generated `dist` here; generated-copy equality is verified in Task 5.
+
+### 5. Synchronize package copies safely
+
+1. After source tests pass, copy or manually merge only the listed changed source asset files into their matching `dist/extensions/pi-subagents/` paths.
+2. Do not run root `npm run build`.
+3. Do not run broad `npm run copy-assets` if it would overwrite pre-existing dirty generated files.
+4. Verify every changed source asset is byte-identical to its matching `dist` copy:
+   ```bash
+   cmp -s src/extensions/pi-subagents/README.md dist/extensions/pi-subagents/README.md
+   # Repeat for each changed agents/ and skills/ asset listed above.
+   ```
+
+## Decisions requiring approval (do not implement in Phase 0)
+
+1. **Change builtin context defaults rather than docs:**  
+   Recommended Phase 0 action is docs-only alignment with current frontmatter/tests. Changing `builder` or `commentator` to fork would be a delegation-policy change and belongs in a later phase.
+
+2. **Give `commentator` edit/write capability:**  
+   Recommended Phase 0 action is to remove stale documentation only. If fix-pass reviewers should edit, explicitly redesign its frontmatter, acceptance semantics, single-writer guarantees, and tests later.
+
+3. **Make researcher tool providers self-contained:**  
+   Prefixing the grep.app tools as MCP tools is a correctness fix. Adding a web-agent extension path or packaging/configuring a grep.app provider is dependency/routing work and needs approval.
+
+## Verification
+
+### Commands
+
+```bash
+cd src/extensions/pi-subagents
+node --experimental-strip-types --test \
+  test/unit/agent-frontmatter.test.ts \
+  test/unit/builtin-agent-documentation.test.ts
+
+npm run test:unit
+```
+
+From repository root:
+
+```bash
+git diff --check
+git diff -- src/extensions/pi-subagents dist/extensions/pi-subagents
+cmp -s src/extensions/pi-subagents/README.md dist/extensions/pi-subagents/README.md
+```
+
+Repeat `cmp -s` for every changed mirrored asset.
+
+### Success cases
+
+- Discovery returns exactly six builtins with documented specialties.
+- Only architect and recapper resolve to fork context without an explicit run context.
+- Builder launches without requiring bridge-only tools when the bridge is inactive.
+- Builder still receives `contact_supervisor` when the bridge is active.
+- Researcher’s grep.app tools are parsed into `mcpDirectTools`.
+- Both role tables list all six roles exactly once.
+- Source and `dist` copies are identical for every changed package asset.
+
+### Failure cases
+
+- Missing MCP/provider registration still fails with the existing clear missing-tool diagnostic.
+- A builder blocked without a bridge does not guess or attempt an unavailable tool.
+- A forked run without a persisted parent session continues to fail as documented.
+
+### Regression checks
+
+- Explicit `context: "fresh"` and `context: "fork"` overrides retain precedence.
+- `commentator` remains read-only.
+- `architect`, `explorer`, `recapper`, and `researcher` remain non-writing.
+- Legacy `.agents` agent discovery remains supported.
+- Existing user model overrides and user-home skills remain untouched.
+
+## Compatibility, dependencies, risks, rollback
+
+- **Compatibility:** This preserves existing intended frontmatter behavior; only malformed tool routing and bridge-inactive builder startup are corrected.
+- **Dependencies:** existing Node test runtime with `--experimental-strip-types`; no new npm packages.
+- **Risks:** manually generated `dist` copies can conflict with current dirty artifacts; preserve/merge baseline hunks instead of regenerating broad output.
+- **Rollback:** revert only the Phase 0 source, test, and matching `dist` hunks. Do not revert baseline dirty hunks recorded before work began.
+
+```acceptance-report
+{
+  "criteriaSatisfied": [
+    {
+      "id": "criterion-1",
+      "status": "satisfied",
+      "evidence": "Concrete findings and planned fixes identify exact source paths, generated mirror paths, severity, runtime ownership, test seams, and residual risks."
+    }
+  ],
+  "changedFiles": [],
+  "testsAddedOrUpdated": [],
+  "commandsRun": [
+    {
+      "command": "read/grep inspection of recon, builtin agent markdown, runtime discovery/tool planning code, package scripts, README, skill references, and unit tests",
+      "result": "passed",
+      "summary": "Verified Phase 0 ownership, current defaults, strict tool behavior, bridge injection, test runner, and generated-asset copy mechanism."
+    },
+    {
+      "command": "git status --short / git diff",
+      "result": "not-run",
+      "summary": "No shell tool is available in this planning session; the plan requires a baseline dirty-diff capture before implementation."
+    }
+  ],
+  "validationOutput": [
+    "BUILTIN_AGENT_NAMES contains architect, builder, commentator, explorer, recapper, and researcher.",
+    "Only architect and recapper currently declare defaultContext: fork.",
+    "Builder statically requires contact_supervisor even though the bridge appends it only when active.",
+    "Researcher currently declares grep.app tools without the parser-required mcp: prefix.",
+    "Root copy-assets copies src/extensions into dist/extensions, while root build cleans dist and is unsafe for preserving existing dirty generated output."
+  ],
+  "residualRisks": [
+    "Current dirty artifacts and unrelated edits were not inspectable through git in this session; implementation must baseline and preserve them.",
+    "Researcher still depends on host MCP/web extension availability after the prefix correction.",
+    "Changing context defaults or granting commentator write capability requires separate product/architecture approval."
+  ],
+  "noStagedFiles": false,
+  "diffSummary": "No implementation was performed; this artifact is an implementation-ready Phase 0 plan.",
+  "reviewFindings": [
+    "high: skills/pi-subagents/references/prompting-and-roles.md and README.md contain duplicated/missing builtin roles and false output/capability descriptions.",
+    "high: constraints-and-recipes.md and execution-controls.md contradict builtin defaultContext frontmatter.",
+    "high: execution-controls.md and README.md contain stale .pi project discovery/root claims despite .selesai runtime configuration.",
+    "medium: agents/architect.md, agents/builder.md, and agents/researcher.md contain impossible or incorrectly routed tool instructions."
+  ],
+  "manualNotes": "Phase 0 is intentionally limited to correctness cleanup and synchronization. Policy-level delegation behavior changes are explicitly deferred."
+}
+```
+
+⧉ copy assistant: /cp e225dd