@code-yeongyu/senpi 2026.8.11 → 2026.8.12

package/dist/utils/version-check.d.ts

@@ -1,3 +1,6 @@
+import { type BrandUpdateChannel } from "../core/brand.ts";
+/** Reads the available version out of whichever registry document was fetched. */
+export declare function readAvailableVersion(payload: unknown, channel: BrandUpdateChannel | undefined): string | undefined;
 export interface LatestPiRelease {
     version: string;
     packageName?: string;

package/dist/utils/version-check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version-check.d.ts","sourceRoot":"","sources":["../../src/utils/version-check.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,eAAe;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAUD,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAoBpG;AAED,wBAAgB,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAM/F;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAI9D;AAED,wBAAsB,kBAAkB,CACvC,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAoBtC;AAED,wBAAsB,kBAAkB,CACvC,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAE7B;AAED,wBAAsB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAYvG"}
+{"version":3,"file":"version-check.d.ts","sourceRoot":"","sources":["../../src/utils/version-check.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,kBAAkB,EAA0B,MAAM,kBAAkB,CAAC;AAanF,kFAAkF;AAClF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,kBAAkB,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAKlH;AAMD,MAAM,WAAW,eAAe;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAUD,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAoBpG;AAED,wBAAgB,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAM/F;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQ9D;AAED,wBAAsB,kBAAkB,CACvC,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CA+BtC;AAED,wBAAsB,kBAAkB,CACvC,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAE7B;AAED,wBAAsB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAYvG"}

package/dist/utils/version-check.js

@@ -1,7 +1,23 @@
 import { compare, valid } from "semver";
 import { PACKAGE_NAME } from "../config.js";
+import { brandProfile, envValue } from "../core/brand.js";
 import { getPiUserAgent } from "./pi-user-agent.js";
-const LATEST_VERSION_URL = `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}/latest`;
+const REGISTRY_BASE_URL = "https://registry.npmjs.org";
+const LATEST_VERSION_URL = `${REGISTRY_BASE_URL}/${encodeURIComponent(PACKAGE_NAME)}/latest`;
+/** Registry endpoint answering "what version does this product publish right now?". */
+function latestVersionUrl(channel) {
+    return channel
+        ? `${REGISTRY_BASE_URL}/-/package/${encodeURIComponent(channel.packageName)}/dist-tags`
+        : LATEST_VERSION_URL;
+}
+/** Reads the available version out of whichever registry document was fetched. */
+export function readAvailableVersion(payload, channel) {
+    if (typeof payload !== "object" || payload === null)
+        return undefined;
+    const source = payload;
+    const raw = channel ? source[channel.distTag] : source.version;
+    return typeof raw === "string" && raw.trim() ? raw.trim() : undefined;
+}
 const DEFAULT_VERSION_CHECK_TIMEOUT_MS = 10000;
 const RELEASE_CHANGELOG_BASE_URL = "https://github.com/code-yeongyu/senpi/blob";
 const RELEASE_CHANGELOG_PATH = "packages/coding-agent/CHANGELOG.md";
@@ -42,13 +58,24 @@ export function isNewerPackageVersion(candidateVersion, currentVersion) {
 }
 export function getReleaseChangelogUrl(version) {
     const trimmedVersion = version.trim();
+    const channel = brandProfile()?.update;
+    if (channel?.changelogUrl) {
+        return channel.changelogUrl.replace("{version}", trimmedVersion);
+    }
     const tag = trimmedVersion.startsWith("v") ? trimmedVersion : `v${trimmedVersion}`;
     return `${RELEASE_CHANGELOG_BASE_URL}/${tag}/${RELEASE_CHANGELOG_PATH}`;
 }
 export async function getLatestPiRelease(currentVersion, options = {}) {
-    if (process.env.PI_OFFLINE)
+    if (envValue("OFFLINE"))
         return undefined;
-    const response = await fetch(LATEST_VERSION_URL, {
+    const brand = brandProfile();
+    const channel = brand?.update;
+    if (brand && !channel) {
+        // The engine's own releases are not installable from inside a branded distribution, so
+        // advertising them would send the user after an update they cannot apply.
+        return undefined;
+    }
+    const response = await fetch(latestVersionUrl(channel), {
         headers: {
             "User-Agent": getPiUserAgent(currentVersion),
             accept: "application/json",
@@ -58,18 +85,22 @@ export async function getLatestPiRelease(currentVersion, options = {}) {
     if (!response.ok)
         return undefined;
     const data = (await response.json());
-    if (typeof data.version !== "string" || !data.version.trim()) {
+    const availableVersion = readAvailableVersion(data, channel);
+    if (!availableVersion) {
         return undefined;
     }
+    if (channel) {
+        return { version: availableVersion, packageName: channel.packageName };
+    }
     const packageName = typeof data.packageName === "string" && data.packageName.trim() ? data.packageName.trim() : undefined;
     const note = typeof data.note === "string" && data.note.trim() ? data.note.trim() : undefined;
-    return { version: data.version.trim(), packageName, note };
+    return { version: availableVersion, packageName, note };
 }
 export async function getLatestPiVersion(currentVersion, options = {}) {
     return (await getLatestPiRelease(currentVersion, options))?.version;
 }
 export async function checkForNewPiVersion(currentVersion) {
-    if (process.env.PI_SKIP_VERSION_CHECK)
+    if (envValue("SKIP_VERSION_CHECK"))
         return undefined;
     try {
         const latestRelease = await getLatestPiRelease(currentVersion);

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 { PACKAGE_NAME } from \"../config.ts\";\nimport { getPiUserAgent } from \"./pi-user-agent.ts\";\n\nconst LATEST_VERSION_URL = `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}/latest`;\nconst DEFAULT_VERSION_CHECK_TIMEOUT_MS = 10000;\nconst RELEASE_CHANGELOG_BASE_URL = \"https://github.com/code-yeongyu/senpi/blob\";\nconst RELEASE_CHANGELOG_PATH = \"packages/coding-agent/CHANGELOG.md\";\nconst SENPI_CALVER_PATTERN = /^(\\d{4})\\.(\\d{1,2})\\.(\\d{1,2})(?:-([2-9]\\d*))?$/;\n\nexport interface LatestPiRelease {\n\tversion: string;\n\tpackageName?: string;\n\tnote?: string;\n}\n\nfunction parseSenpiCalVer(version: string): readonly [number, number, number, number] | undefined {\n\tconst match = SENPI_CALVER_PATTERN.exec(version);\n\tif (!match) {\n\t\treturn undefined;\n\t}\n\treturn [Number(match[1]), Number(match[2]), Number(match[3]), Number(match[4] ?? 1)];\n}\n\nexport function comparePackageVersions(leftVersion: string, rightVersion: string): number | undefined {\n\tconst leftTrimmed = leftVersion.trim();\n\tconst rightTrimmed = rightVersion.trim();\n\tconst leftCalVer = parseSenpiCalVer(leftTrimmed);\n\tconst rightCalVer = parseSenpiCalVer(rightTrimmed);\n\tif (leftCalVer && rightCalVer) {\n\t\tfor (let index = 0; index < leftCalVer.length; index++) {\n\t\t\tif (leftCalVer[index] !== rightCalVer[index]) {\n\t\t\t\treturn leftCalVer[index] < rightCalVer[index] ? -1 : 1;\n\t\t\t}\n\t\t}\n\t\treturn 0;\n\t}\n\n\tconst left = valid(leftTrimmed);\n\tconst right = valid(rightTrimmed);\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 function getReleaseChangelogUrl(version: string): string {\n\tconst trimmedVersion = version.trim();\n\tconst tag = trimmedVersion.startsWith(\"v\") ? trimmedVersion : `v${trimmedVersion}`;\n\treturn `${RELEASE_CHANGELOG_BASE_URL}/${tag}/${RELEASE_CHANGELOG_PATH}`;\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 { packageName?: unknown; version?: unknown; note?: unknown };\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 { version: data.version.trim(), packageName, note };\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(currentVersion: string): Promise<LatestPiRelease | undefined> {\n\tif (process.env.PI_SKIP_VERSION_CHECK) return undefined;\n\n\ttry {\n\t\tconst latestRelease = await getLatestPiRelease(currentVersion);\n\t\tif (latestRelease && isNewerPackageVersion(latestRelease.version, currentVersion)) {\n\t\t\treturn latestRelease;\n\t\t}\n\t\treturn undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\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 { PACKAGE_NAME } from \"../config.ts\";\nimport { type BrandUpdateChannel, brandProfile, envValue } from \"../core/brand.ts\";\nimport { getPiUserAgent } from \"./pi-user-agent.ts\";\n\nconst REGISTRY_BASE_URL = \"https://registry.npmjs.org\";\nconst LATEST_VERSION_URL = `${REGISTRY_BASE_URL}/${encodeURIComponent(PACKAGE_NAME)}/latest`;\n\n/** Registry endpoint answering \"what version does this product publish right now?\". */\nfunction latestVersionUrl(channel: BrandUpdateChannel | undefined): string {\n\treturn channel\n\t\t? `${REGISTRY_BASE_URL}/-/package/${encodeURIComponent(channel.packageName)}/dist-tags`\n\t\t: LATEST_VERSION_URL;\n}\n\n/** Reads the available version out of whichever registry document was fetched. */\nexport function readAvailableVersion(payload: unknown, channel: BrandUpdateChannel | undefined): string | undefined {\n\tif (typeof payload !== \"object\" || payload === null) return undefined;\n\tconst source = payload as Record<string, unknown>;\n\tconst raw = channel ? source[channel.distTag] : source.version;\n\treturn typeof raw === \"string\" && raw.trim() ? raw.trim() : undefined;\n}\nconst DEFAULT_VERSION_CHECK_TIMEOUT_MS = 10000;\nconst RELEASE_CHANGELOG_BASE_URL = \"https://github.com/code-yeongyu/senpi/blob\";\nconst RELEASE_CHANGELOG_PATH = \"packages/coding-agent/CHANGELOG.md\";\nconst SENPI_CALVER_PATTERN = /^(\\d{4})\\.(\\d{1,2})\\.(\\d{1,2})(?:-([2-9]\\d*))?$/;\n\nexport interface LatestPiRelease {\n\tversion: string;\n\tpackageName?: string;\n\tnote?: string;\n}\n\nfunction parseSenpiCalVer(version: string): readonly [number, number, number, number] | undefined {\n\tconst match = SENPI_CALVER_PATTERN.exec(version);\n\tif (!match) {\n\t\treturn undefined;\n\t}\n\treturn [Number(match[1]), Number(match[2]), Number(match[3]), Number(match[4] ?? 1)];\n}\n\nexport function comparePackageVersions(leftVersion: string, rightVersion: string): number | undefined {\n\tconst leftTrimmed = leftVersion.trim();\n\tconst rightTrimmed = rightVersion.trim();\n\tconst leftCalVer = parseSenpiCalVer(leftTrimmed);\n\tconst rightCalVer = parseSenpiCalVer(rightTrimmed);\n\tif (leftCalVer && rightCalVer) {\n\t\tfor (let index = 0; index < leftCalVer.length; index++) {\n\t\t\tif (leftCalVer[index] !== rightCalVer[index]) {\n\t\t\t\treturn leftCalVer[index] < rightCalVer[index] ? -1 : 1;\n\t\t\t}\n\t\t}\n\t\treturn 0;\n\t}\n\n\tconst left = valid(leftTrimmed);\n\tconst right = valid(rightTrimmed);\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 function getReleaseChangelogUrl(version: string): string {\n\tconst trimmedVersion = version.trim();\n\tconst channel = brandProfile()?.update;\n\tif (channel?.changelogUrl) {\n\t\treturn channel.changelogUrl.replace(\"{version}\", trimmedVersion);\n\t}\n\tconst tag = trimmedVersion.startsWith(\"v\") ? trimmedVersion : `v${trimmedVersion}`;\n\treturn `${RELEASE_CHANGELOG_BASE_URL}/${tag}/${RELEASE_CHANGELOG_PATH}`;\n}\n\nexport async function getLatestPiRelease(\n\tcurrentVersion: string,\n\toptions: { timeoutMs?: number } = {},\n): Promise<LatestPiRelease | undefined> {\n\tif (envValue(\"OFFLINE\")) return undefined;\n\n\tconst brand = brandProfile();\n\tconst channel = brand?.update;\n\tif (brand && !channel) {\n\t\t// The engine's own releases are not installable from inside a branded distribution, so\n\t\t// advertising them would send the user after an update they cannot apply.\n\t\treturn undefined;\n\t}\n\tconst response = await fetch(latestVersionUrl(channel), {\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 { packageName?: unknown; version?: unknown; note?: unknown };\n\tconst availableVersion = readAvailableVersion(data, channel);\n\tif (!availableVersion) {\n\t\treturn undefined;\n\t}\n\tif (channel) {\n\t\treturn { version: availableVersion, packageName: channel.packageName };\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 { version: availableVersion, packageName, note };\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(currentVersion: string): Promise<LatestPiRelease | undefined> {\n\tif (envValue(\"SKIP_VERSION_CHECK\")) return undefined;\n\n\ttry {\n\t\tconst latestRelease = await getLatestPiRelease(currentVersion);\n\t\tif (latestRelease && isNewerPackageVersion(latestRelease.version, currentVersion)) {\n\t\t\treturn latestRelease;\n\t\t}\n\t\treturn undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n"]}

package/dist/valid-cwd.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=valid-cwd.d.ts.map

package/dist/valid-cwd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"valid-cwd.d.ts","sourceRoot":"","sources":["../src/valid-cwd.ts"],"names":[],"mappings":""}

package/dist/valid-cwd.js

@@ -0,0 +1,14 @@
+import { homedir } from "node:os";
+// A shell whose working directory was deleted (a removed worktree or checkout) still starts this
+// process: Node boots with the stale handle and only throws `uv_cwd` when something evaluates
+// process.cwd(). The bundled agent SDK does that during module evaluation, before any user code
+// can recover, so the guard must run before every other import - keep it dependency-free.
+try {
+    process.cwd();
+}
+catch {
+    const fallback = homedir();
+    process.chdir(fallback);
+    console.error(`the current working directory no longer exists; continuing from ${fallback}`);
+}
+//# sourceMappingURL=valid-cwd.js.map

package/dist/valid-cwd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"valid-cwd.js","sourceRoot":"","sources":["../src/valid-cwd.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC,iGAAiG;AACjG,8FAA8F;AAC9F,gGAAgG;AAChG,0FAA0F;AAC1F,IAAI,CAAC;IACJ,OAAO,CAAC,GAAG,EAAE,CAAC;AACf,CAAC;AAAC,MAAM,CAAC;IACR,MAAM,QAAQ,GAAG,OAAO,EAAE,CAAC;IAC3B,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACxB,OAAO,CAAC,KAAK,CAAC,mEAAmE,QAAQ,EAAE,CAAC,CAAC;AAC9F,CAAC","sourcesContent":["import { homedir } from \"node:os\";\n\n// A shell whose working directory was deleted (a removed worktree or checkout) still starts this\n// process: Node boots with the stale handle and only throws `uv_cwd` when something evaluates\n// process.cwd(). The bundled agent SDK does that during module evaluation, before any user code\n// can recover, so the guard must run before every other import - keep it dependency-free.\ntry {\n\tprocess.cwd();\n} catch {\n\tconst fallback = homedir();\n\tprocess.chdir(fallback);\n\tconsole.error(`the current working directory no longer exists; continuing from ${fallback}`);\n}\n"]}

package/docs/environment-variables.md

@@ -79,11 +79,18 @@ These variables are read by Pi itself:
 | `PI_OFFLINE` | Disable startup network operations, including update checks, package updates, and install/update telemetry |
 | `PI_SKIP_VERSION_CHECK` | Disable the `pi.dev` 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_CACHE_RETENTION` | Set to `long` to opt into extended provider prompt caching where supported; direct Anthropic defaults to 5 minutes |
 | `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) |
 | `SENPI_RECOVER_INSPECTOR_VM_IMPORT` | Set to `1` at process start to keep the TUI running when a Node Inspector (`node inspect` / `--inspect`) eval uses dynamic `import()`, which Node rejects with `ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING`. Recovery applies only to that exact Inspector-originated rejection while an Inspector endpoint is active; all other uncaught errors remain fatal. Use `require()` or a target-side loader in Inspector evals instead |
 | `VISUAL`, `EDITOR` | External editor fallback when `externalEditor` is unset |
 | `HTTP_PROXY`, `HTTPS_PROXY` | Proxy outbound HTTP requests |
 
+### Image Generation
+
+| Variable | Description |
+|----------|-------------|
+| `PI_OPENAI_IMAGE_GEN` | Enable or disable native `image_generation` server-tool injection on OpenAI Responses models. Accepts `1`/`true`/`yes` (default) or `0`/`false`/`no`. When disabled, the client-side `generate_image` tool is used instead |
+| `PI_IMAGE_GEN_PROVIDER` | Pin a specific configured gateway provider for image generation (for example `quotio-openai`). The provider must have a resolvable API key and base URL in `models.json`. When unset, the credential resolver picks the best available source automatically |
+
 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

@@ -135,6 +135,16 @@ Run `/fallback` without arguments in the TUI for a menu that can:
 
 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.
 
+## Built-in Native Capabilities
+
+Senpi ships built-in extensions that inject provider-native server tools when the active model supports them. These run as ordinary extensions internally but are always loaded and require no user configuration beyond having valid credentials.
+
+**openai-image-gen** injects the OpenAI Responses `image_generation` server tool when the model uses `openai-responses` on `api.openai.com`. It arbitrates against the client-side `generate_image` function tool so exactly one image surface is offered per request. A `message_end` handler decodes completed image results, writes them to `generated-images/`, and replaces the provider-native block with a text path reference before session persistence, so base64 payloads never reach the session file. Set `PI_OPENAI_IMAGE_GEN=false` to force the client tool path. Azure Responses endpoints default to the client tool unless `compat.supportsImageGeneration` opts in.
+
+**openai-web-search** injects the OpenAI Responses `web_search_preview` server tool following the same pattern: credential-gated, stripped on unsupported endpoints, arbitrated against its client-side counterpart.
+
+Both builtins use `before_provider_request` to mutate the outgoing payload and re-evaluate their gate on every `model_select`, so mid-session model switches flip between native and client tools without a restart.
+
 ## Extension Locations
 
 > **Security:** Extensions run with your full system permissions and can execute arbitrary code. Only install from sources you trust.
@@ -1386,6 +1396,49 @@ export default function (pi: ExtensionAPI) {
 
 Subscribe to events. See [Events](#events) for event types and return values.
 
+### pi.rpc.emit(name, data)
+
+Publish an extension-owned event to RPC clients:
+
+```typescript
+pi.rpc.emit("acme.job.updated", {
+  jobId: "job-42",
+  status: "running",
+});
+```
+
+`name` must be non-empty and `data` must be JSON-serializable. Delivery is additive and
+fire-and-forget: RPC clients receive the event only when they advertise the `extension_events`
+capability. In multi-session mode the host adds the owning routing `sessionId` to the wire record.
+Unflagged clients and non-RPC modes do not receive a transport record.
+
+Use this for extension-to-client state such as progress snapshots. It is separate from
+extension-local event-bus communication and must not carry secrets, prompts, transcripts, or other
+data the client did not explicitly opt into receiving.
+
+### pi.rpc.handle(name, handler)
+
+Register one structured request handler that an RPC client can invoke without turning the request
+into a model prompt:
+
+```typescript
+pi.rpc.handle("acme.job.cancel", async (data) => {
+  const input = CancelJobInput.parse(data);
+  await cancelJob(input.jobId);
+  return { cancelled: true };
+});
+```
+
+`name` must be non-empty and unique across the loaded extension generation. The handler receives
+opaque `unknown` data and may return any JSON-serializable value synchronously or asynchronously.
+Extensions own validation for their request names; Senpi owns request correlation, multi-session
+routing, stale-generation rejection, and bounded unknown/duplicate-name errors.
+
+Use this for trusted RPC-client controls over extension-owned state. Do not use slash-command
+prompts as a control transport: `pi.rpc.handle` executes directly without invoking the model. An
+older Senpi host that does not expose `handle` can be supported by feature-detecting the method
+before registration.
+
 ### pi.registerTool(definition)
 
 Register a custom tool callable by the LLM. See [Custom Tools](#custom-tools) for full details.
@@ -2159,6 +2212,11 @@ pi.registerTool({
   name: "my_tool",
   label: "My Tool",
   description: "What this tool does (shown to LLM)",
+  exposure: "search",
+  searchText: "Look up items in the project todo list",
+  searchKeywords: ["todo", "task", "planning"],
+  searchGroup: "my_extension",
+  allowLazyActivation: true,
   promptSnippet: "List or add items in the project todo list",
   promptGuidelines: [
     "Use my_tool for todo planning instead of direct file edits when the user asks for a task list."
@@ -2559,19 +2617,43 @@ If a slot renderer is not defined or throws:
 
 ### Dynamic Tool Loading
 
-Extensions can register many tools while keeping only a small initial set active. A tool can then add more tools with `pi.setActiveTools()` during execution. Pi detects purely additive changes, records the newly available tool names on that tool result, and applies the updated active set before the next model request.
+Extensions can ship large tool catalogs without bloating the model's context window by opting into declarative search exposure. A tool declared with `exposure: "search"` is indexed in the shared `tool_search` catalog and remains inactive (costing zero prompt tokens) until the model searches for it.
+
+The declarative API handles the entire lifecycle:
+1. Register tools with `exposure: "search"`. The tools stay out of the initial active set.
+2. The shared `tool_search` builtin (always active) indexes their `name`, `label`, `description`, `searchText`, and `searchKeywords`.
+3. When the model needs a capability, it calls `tool_search`.
+4. Pi automatically promotes matching tools to the active set for the next model request.
+5. On supported models (Anthropic, OpenAI), this promotion uses native deferred loading protocols to preserve prompt cache stability.
+
+Tools promoted via search are tied to your extension's identity. If your extension is reloaded, they stay active; if your extension is removed, they are cleaned up.
 
-This works with every model. Models with native deferred-loading support preserve the stable prompt prefix and load the new definitions at the tool-result position. Other models use the fallback described below.
+#### Declarative Fields
 
-The lifecycle is:
+Add these fields to `pi.registerTool(...)`:
 
-1. Register every tool with `pi.registerTool()` so it appears in `pi.getAllTools()`.
-2. Keep loader tools, such as `search_tools`, active and leave searchable tools inactive.
-3. During loader execution, call `pi.setActiveTools([...currentTools, ...matchingTools])`. The change must be additive: do not remove currently active tools in the same call.
-4. Pi records which tools were added on the loader's tool result.
-5. Before the next model response, Pi exposes the added definitions using native deferred loading when supported, or the normal active tool list otherwise.
+- **`exposure`**: `"direct" | "search"`. Default is `"direct"` (tool is auto-activated immediately). Use `"search"` for large catalogs.
+- **`searchText`**: Supplemental text indexed by `tool_search`. Never sent to the model. Useful for domain terms that don't belong in the tool description.
+- **`searchKeywords`**: Synonyms or domain terms, indexed with the same weight as the tool name. Never sent to the model.
+- **`searchGroup`**: Organizational filter group. Defaults to your extension's label.
+- **`allowLazyActivation`**: Default `true`. If `false`, the tool is hidden from `tool_search` completely and cannot be lazily activated during code mode execution. Explicit activation via `pi.setActiveTools()` is still allowed.
 
-You do not need to return provider-specific tool references or mark the loader as a special search tool. The active-tool change is the signal. Names passed to `pi.setActiveTools()` must already be registered; unknown names are ignored.
+**Important:** You cannot register a tool named `tool_search` yourself; it is a reserved name.
+
+#### Prompt Cache Warning
+
+Activating a tool that includes `promptSnippet` or `promptGuidelines` rebuilds the system prompt. Even when the provider supports deferred schemas, changing the system prompt may invalidate the cached prefix. Lazily loaded tools should usually rely on their `description` and omit active-only prompt metadata to get the best cache performance.
+
+#### Advanced: DIY Dynamic Loading
+
+For advanced use cases like project-specific routing or custom remote catalogs, extensions can skip `exposure: "search"` and manage the active set imperatively. A tool can add more tools with `pi.setActiveTools()` during execution. Pi detects purely additive changes, records the newly available tool names on that tool result, and applies the updated active set before the next model request.
+
+The DIY lifecycle is:
+
+1. Register every tool with `exposure: "direct"` (or omit it) but explicitly remove them from the active set during `session_start` using `pi.setActiveTools()`.
+2. Keep your custom loader tool active.
+3. During loader execution, call `pi.setActiveTools([...currentTools, ...matchingTools])`. The change must be additive.
+4. Pi exposes the added definitions before the next model response.
 
 #### Models with native deferred loading
 
@@ -2590,11 +2672,9 @@ For all other models and providers, dynamic activation still works: Pi sends the
 
 Pi also uses this safe fallback when the active set is not purely additive, such as replacing one group of tools with another. Tool removals therefore work, but they do not use deferred loading.
 
-For the best cache behavior, keep the loader tool active for the whole session and add tools instead of replacing the active set. Also note that activating a tool with `promptSnippet` or `promptGuidelines` rebuilds the system prompt; that system-prompt change can invalidate the prefix even when the provider supports deferred schemas. Lazily loaded tools should usually rely on their tool `description` and omit active-only prompt metadata.
-
-#### Search tool example
+#### DIY Custom Search Tool Example
 
-The following extension registers two searchable tools, removes them from the initial active set, and keeps only `search_tools` as their loader. The example uses simple keyword matching, but the search implementation could use BM25, embeddings, a remote catalog, or project-specific routing.
+The following extension registers two tools, removes them from the initial active set, and keeps only a custom `search_tools` as their loader. The example uses simple keyword matching, but the search implementation could use embeddings or a remote catalog.
 
 ```typescript
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

package/docs/mcp.md

@@ -147,6 +147,8 @@ local `tool_search` for the session.
 
 ## Exposure tiers
 
+> **Note:** `tool_search` is a shared catalog tool that covers both MCP servers and native extension tools. When filtering searches, the legacy MCP `server` parameter is mapped to the shared `group` parameter.
+
 | Tier | When | Cost profile |
 |---|---|---|
 | direct | `exposure:"direct"`, `directTools:true`, or `auto` at/below `searchThreshold` | Every tool schema on every request |

package/docs/providers.md

@@ -93,11 +93,11 @@ If your Claude Pro/Max subscription usage through `claude-sdk-oauth` feels unexp
    | Lane | Effective TTL | Who controls it | How to override |
    | --- | --- | --- | --- |
    | Claude SDK OAuth (subscription, `claude-sdk-oauth`) | 5 minutes | The Claude SDK owns `cache_control`; senpi cannot add breakpoints. senpi reports 300s for this lane so cache-aware budgets (tool waits, goal timing) size themselves correctly. | Not overridable |
-   | Direct Anthropic API (`api.anthropic.com`, API key or OAuth token) | 1 hour | senpi defaults retention to `long` on this lane. Note: Anthropic's own API default is 5 minutes; the 1h TTL is senpi's choice, and 1h cache writes cost 2x base input vs 1.25x for 5m ([Anthropic prompt caching](https://docs.claude.com/en/docs/build-with-claude/prompt-caching)). | `PI_CACHE_RETENTION`, `cacheRetention` |
+   | Direct Anthropic API (`api.anthropic.com`, API key or OAuth token) | 5 minutes | senpi follows Anthropic's default cache retention. Opting into 1h retention makes cache writes cost 2x base input vs 1.25x for 5m ([Anthropic prompt caching](https://docs.claude.com/en/docs/build-with-claude/prompt-caching)). | Set `PI_CACHE_RETENTION=long` or `cacheRetention: "long"` |
    | Anthropic-compatible providers (kimi-coding, fireworks, gateways) | 5 minutes | The 1h TTL is gated on the native `api.anthropic.com` base URL, so these lanes stay short. | `cacheRetention` |
 
    Override precedence: `cacheRetention` in `models.json` / the model catalog wins over everything. `PI_CACHE_RETENTION=long` selects long; any other set value forces short; unset falls back to the lane default above.
-5. **Goal-monitor timing.** The goal monitor's continuation backstop is derived from the model's cache-safe wait (TTL minus `promptCache.safetyBufferSeconds`, default 30), capped by `promptCache.goalBackstopMaxSeconds` (default 3570), instead of a fixed 4 minutes. On 5m lanes that means wakes every ~4m30s; on the 1h direct-API lane, up to 59m30s. Cache-warm notices show which warm iteration you are on.
+5. **Goal-monitor timing.** The goal monitor's continuation backstop is derived from the model's cache-safe wait (TTL minus `promptCache.safetyBufferSeconds`, default 30), capped by `promptCache.goalBackstopMaxSeconds` (default 3570), instead of a fixed 4 minutes. The default 5m lanes wake every ~4m30s; a supported lane explicitly configured for 1h retention can wait up to 59m30s. Cache-warm notices show which warm iteration you are on.
 6. **Wake sources that hold the goal backstop.** Anything that can wake a parked session publishes a `wake_source_state` event (`{source, activeCount}`): terminal monitors (`terminal-monitors`), background bash sessions including auto-detached and killed ones (`terminal-background-sessions`), detached `eval` cells (`senpi-codemode`), and omo-senpi background task children plus owned team members (`senpi-task`). The goal extension sums every source, so a goal waits inside the prompt-cache TTL while ANY of them is on duty instead of continuing immediately. The legacy `terminal_monitor_state` event is still emitted for external consumers and is folded onto the same `terminal-monitors` count.
 7. **Directive-block deduplication.** As of v2026.8.4, the flatten serialization collapses repeated `<ultrawork-mode>` directive blocks to a single copy, preventing the issue-#494 scenario where duplicated ~17KB directive blocks consumed up to 73% of the re-sent prompt. The continuity observation reports how many were collapsed and the payload size.
 

package/docs/rpc.md

@@ -17,6 +17,20 @@ Common options:
 - `--no-session`: Disable session persistence
 - `--session-dir <path>`: Custom session storage directory
 
+### Client capabilities
+
+Optional additive records are enabled through the comma-separated
+`SENPI_RPC_CLIENT_CAPABILITIES` environment variable:
+
+```bash
+SENPI_RPC_CLIENT_CAPABILITIES=extension_events senpi --mode rpc
+```
+
+Rebranded distributions read the equivalent variable under their configured environment prefix
+(for example `OMO_RPC_CLIENT_CAPABILITIES`). Unknown capability names are ignored. Advertising
+`extension_events` opts the client into generic extension-owned event records; clients that omit it
+retain the previous wire stream unchanged.
+
 ## Multi-session mode (D1 wire protocol)
 
 Multi-session mode lets one `senpi --mode rpc` process serve several independent conversations concurrently over the same stdio JSONL stream. Classic single-session mode is byte-identical to today; the only additive classic-mode behavior is that `get_protocol_info` is answered.
@@ -889,6 +903,88 @@ Each command has:
 
 **Note**: Built-in TUI commands (`/settings`, `/hotkeys`, etc.) are not included. They are handled only in interactive mode and would not execute if sent via `prompt`.
 
+#### get_loaded_surfaces
+
+Get the extensions and MCP servers loaded by the active runtime. Skills remain available through `get_commands`, where each loaded skill is represented by one `source: "skill"` row.
+
+```json
+{"type": "get_loaded_surfaces"}
+```
+
+Response:
+
+```json
+{
+  "type": "response",
+  "command": "get_loaded_surfaces",
+  "success": true,
+  "data": {
+    "extensions": [
+      {
+        "name": "my-extension",
+        "path": "/home/user/.senpi/agent/extensions/my-extension.ts",
+        "sourceInfo": {
+          "path": "/home/user/.senpi/agent/extensions/my-extension.ts",
+          "source": "auto",
+          "scope": "user",
+          "origin": "top-level"
+        },
+        "enabled": true
+      }
+    ],
+    "mcpServers": [
+      {
+        "name": "filesystem",
+        "toolCount": 12,
+        "status": "connected",
+        "authStatus": "unsupported"
+      }
+    ]
+  }
+}
+```
+
+Extension rows come directly from the session's loaded resource inventory, not from registered slash commands. A commandless extension therefore appears once, and an extension registering several commands is not duplicated. MCP rows come from the live session-owned MCP service and expose its current server state, listed tool count, and non-secret auth status.
+
+In multi-session mode this is a session-scoped command and requires the routing `sessionId`.
+
+### extension_request
+
+Invoke a request handler registered by an extension through `pi.rpc.handle(name, handler)`:
+
+```json
+{
+  "id": "req-42",
+  "type": "extension_request",
+  "name": "acme.job.cancel",
+  "data": {
+    "jobId": "job-42"
+  }
+}
+```
+
+Success returns the extension-owned structured value:
+
+```json
+{
+  "id": "req-42",
+  "type": "response",
+  "command": "extension_request",
+  "success": true,
+  "data": {
+    "cancelled": true
+  }
+}
+```
+
+The request `name` must resolve to exactly one handler in the active extension generation.
+Unknown names, duplicate names, stale generations, handler failures, and empty names return the
+normal `{ type: "response", success: false, error }` envelope. Senpi treats request and response
+data as opaque; the owning extension and client must validate their payloads.
+
+In multi-session mode this command requires the owning routing `sessionId`. The response receives
+the same `sessionId`, and another session's extension handlers are never consulted.
+
 ## Events
 
 Events are streamed to stdout as JSON lines during agent operation. Events do not generally include an `id` field; `bash_execution_update` includes the `id` of its originating `bash` command when one was provided.
@@ -918,6 +1014,28 @@ Events are streamed to stdout as JSON lines during agent operation. Events do no
 | `summarization_retry_attempt_start` | Retried summarization request starts |
 | `summarization_retry_finished` | Summarization retry loop completes |
 | `extension_error` | Extension threw an error |
+| `extension_event` | Capability-gated extension-owned event (`extension_events` clients only) |
+| `loaded_surfaces_changed` | Loaded skills, extensions, or MCP inventory changed; re-read `get_commands` and `get_loaded_surfaces` |
+
+### extension_event
+
+Emitted when an extension calls `pi.rpc.emit(name, data)` and the client advertised
+`extension_events`:
+
+```json
+{
+  "type": "extension_event",
+  "name": "acme.job.updated",
+  "data": {
+    "jobId": "job-42",
+    "status": "running"
+  }
+}
+```
+
+`name` is extension-owned and `data` is opaque to Senpi. Consumers should validate the payload for
+the specific event name before applying it. In multi-session mode the record also includes the
+routing `sessionId`; delivery preserves the owning session and per-session event order.
 
 ### agent_start
 
@@ -1187,6 +1305,14 @@ For branch summaries, `source` is `"branchSummary"` and no `reason` is present.
 }
 ```
 
+### loaded_surfaces_changed
+
+Emitted without a request id when the loaded skill, extension, or MCP inventory changes. The event carries no inventory payload; clients re-read `get_commands` for skills and `get_loaded_surfaces` for extensions/MCP, mirroring the app-server `skills/changed` invalidation model.
+
+```json
+{"type": "loaded_surfaces_changed"}
+```
+
 ### extension_error
 
 Emitted when an extension throws an error.

package/docs/skills.md

@@ -254,6 +254,14 @@ cd /path/to/brave-search && npm install
 ```
 ````
 
+## Bundled Skills
+
+Senpi contributes built-in skills conditionally based on available credentials and capabilities.
+
+**gpt-image-gen** is contributed by the `imagegen` builtin extension when image-generation credentials exist (a stored OpenAI key, `OPENAI_API_KEY`, or a configured OpenAI-compatible gateway). It provides a prompt-crafting guide for `gpt-image-2`, covering detail-maxxing techniques, verbatim quoted render text, revised-prompt feedback loops, and routing guidance for the native server tool vs. the client `generate_image` tool. The skill is absent from `<available_skills>` when no credentials are configured.
+
+Skill visibility refreshes at startup and on `/reload`. Mid-session credential changes (login, environment variable updates) take effect on the tool and injector immediately but are reflected in the skill list only after the next reload.
+
 ## Skill Repositories
 
 - [Anthropic Skills](https://github.com/anthropics/skills) - Document processing (docx, pdf, pptx, xlsx), web development

package/examples/extensions/searchable-tools.ts

@@ -0,0 +1,49 @@
+/**
+ * Searchable Tools Example
+ * Demonstrates declarative search exposure for large tool catalogs.
+ */
+
+import { defineTool, type ExtensionAPI } from "@code-yeongyu/senpi";
+import { Type } from "typebox";
+
+const dictionaryLookup = defineTool({
+	name: "lookup_dictionary",
+	label: "Dictionary Lookup",
+	description: "Look up definitions of words",
+	exposure: "search",
+	searchText: "Find meanings and definitions of English words",
+	searchKeywords: ["dictionary", "meaning", "definition"],
+	allowLazyActivation: true,
+	parameters: Type.Object({
+		word: Type.String(),
+	}),
+	async execute(_id, params) {
+		return {
+			content: [{ type: "text", text: `Definition for ${params.word}: [example definition]` }],
+			details: {},
+		};
+	},
+});
+
+const privateDatabaseQuery = defineTool({
+	name: "query_private_db",
+	label: "Query Private DB",
+	description: "Query the sensitive private database",
+	exposure: "search",
+	searchText: "Access protected company records",
+	allowLazyActivation: false, // Cannot be lazily activated; must be explicitly enabled
+	parameters: Type.Object({
+		query: Type.String(),
+	}),
+	async execute(_id, params) {
+		return {
+			content: [{ type: "text", text: `Results for ${params.query}: [secret data]` }],
+			details: {},
+		};
+	},
+});
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool(dictionaryLookup);
+	pi.registerTool(privateDatabaseQuery);
+}