@narumitw/pi-chrome-devtools 0.52.1 → 0.52.3

package/README.md

@@ -1,37 +1,22 @@
-# 🌐 pi-chrome-devtools — Chrome DevTools Tools for Pi Agents
+# 🌐 pi-chrome-devtools — Inspect and Control Chrome from Pi
 
 [![npm](https://img.shields.io/npm/v/@narumitw/pi-chrome-devtools)](https://www.npmjs.com/package/@narumitw/pi-chrome-devtools) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 
-`@narumitw/pi-chrome-devtools` is a native [Pi coding agent](https://pi.dev) extension that exposes Chrome DevTools Protocol (CDP) automation as Pi tools.
+Let Pi inspect browser tabs, navigate pages, evaluate JavaScript, and capture screenshots through native Chrome DevTools Protocol tools.
 
-Use it to let the Pi agent inspect browser tabs, navigate pages, evaluate JavaScript, and capture screenshots while debugging web apps or validating UI behavior.
+Use it for web debugging, UI validation, and browser-assisted investigation without running an MCP server.
 
-This package is inspired by [`chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp), but it is implemented as native Pi tools instead of an MCP server.
+The design is inspired by [`chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp), not guaranteed to be compatible with it.
 
 ## ✨ Features
 
-- Lists inspectable Chrome tabs and pages.
-- Selects an active Chrome page for later tool calls.
-- Navigates Chrome to a target URL, creating an inspectable page when none exists.
-- Recovers from stale active page selections by falling back to an available page.
-- Evaluates JavaScript in the selected page.
-- Captures PNG screenshots, including optional full-page screenshots, and saves them to disk.
-- Renders compact tool results that expand/collapse with Pi's default output toggle (`Ctrl+O`).
-- Reuses an existing Chrome DevTools Protocol endpoint when one is already available.
-- Lazily auto-launches a Chromium-family browser for missing local endpoints, with Chrome,
-  Chromium, Brave, and Edge fallbacks.
-- Loads one or more user-approved unpacked extensions into an isolated managed Chrome for Testing
-  or Chromium browser.
-- Uses a dynamic managed DevTools port by default to avoid port conflicts, while preserving
-  explicit endpoint overrides.
-- Retries briefly while Chrome is starting and reports actionable endpoint errors.
-- Shows statusline activity only while Chrome DevTools tools are running.
-- Keeps one loader tool active and exposes matching browser capabilities only when the agent needs them.
-- Provides a state-first `/chrome-devtools` menu for tool availability, editable browser settings,
-  browser status, setup, and help.
-- Stages menu-based availability changes for exact review before one confirmed apply.
-- Uses `@narumitw/pi-tui-kit` for width-safe TUI menus and equivalent RPC dialogs.
-- Persists the Chrome DevTools lazy-load catalog across Pi restarts.
+- Lists and selects inspectable pages, navigates URLs, evaluates JavaScript, and captures PNG screenshots.
+- Reuses an existing CDP endpoint or lazily launches an isolated Chromium-family browser.
+- Recovers from stale page selections and reports actionable browser startup or endpoint errors.
+- Loads explicitly approved unpacked extensions only in an extension-owned Chrome for Testing or Chromium process.
+- Uses native deferred browser tools when supported and eager exposure otherwise, with availability, setup, status, and help through `/chrome-devtools`.
+- Shows compact expandable results and activity only while browser tools are running.
+- Persists reviewed tool availability while keeping browser connection settings machine-owned.
 
 ## 📦 Install
 
@@ -45,25 +30,28 @@ Try without installing permanently:
 pi -e npm:@narumitw/pi-chrome-devtools
 ```
 
-Try this package locally from the repository root:
+Build and try this package locally from the repository root:
 
 ```bash
+npm --workspace @narumitw/pi-chrome-devtools run build
 pi -e ./packages/pi-chrome-devtools
 ```
 
-The package declares `dist/index.ts`, so an unbuilt local checkout must run `npm --workspace @narumitw/pi-chrome-devtools run build` before Pi loads the package directory.
+The package declares `dist/index.ts`, so an unbuilt local checkout must run the build before Pi loads the package directory.
 
-`just try chrome-devtools` runs that build automatically.
+## 🚀 Quick start
 
-## 🚀 Browser startup
+Start Pi and ask the agent to load the Chrome DevTools capability needed for the task.
+The extension first tries `http://127.0.0.1:9222` and otherwise launches an isolated local Chromium-family browser by default.
+Run `/chrome-devtools` to review browser status, settings, help, and available tools.
 
-Without unpacked extensions, the extension first tries `browser.endpoint`, defaulting to
-`http://127.0.0.1:9222`. If that local endpoint is unavailable and `browser.autoLaunch` is `true`, it
-lazily launches an extension-owned Chromium-family browser with an isolated temp profile and retries
-the CDP request. Existing endpoints are reused and are never terminated by the extension.
+## 🌐 Browser setup
 
-Configure the canonical user file at
-`${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-chrome-devtools.json`:
+Without unpacked extensions, the extension first tries `browser.endpoint`, defaulting to `http://127.0.0.1:9222`.
+If that endpoint is unavailable and `browser.autoLaunch` is `true`, it lazily launches an extension-owned browser with an isolated temporary profile and retries the CDP request.
+Existing endpoints are reused and never terminated by the extension.
+
+Configure the canonical user file at `${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-chrome-devtools.json`:
 
 ```json
 {
@@ -75,21 +63,21 @@ Configure the canonical user file at
 }
 ```
 
-`browser.endpoint` must be an HTTP origin with an explicit port and no credentials, path, query, or
-fragment. Omitting it keeps attach-first behavior on `127.0.0.1:9222` and lets a managed launch use
-Chrome's dynamic DevTools port mode (`--remote-debugging-port=0`). Explicitly saving an endpoint pins
-managed launches to that port. `browser.autoLaunch` defaults to `true`. `browser.executablePath` is
-optional and must be an absolute path; when absent, normal browser discovery applies.
+`browser.endpoint` must be an HTTP origin with an explicit port and no credentials, path, query, or fragment.
+Omitting it keeps attach-first behavior on `127.0.0.1:9222` and lets a managed launch use Chrome's dynamic DevTools port mode (`--remote-debugging-port=0`).
+Explicitly saving an endpoint pins managed launches to that port.
+`browser.autoLaunch` defaults to `true`.
+`browser.executablePath` is optional and must be an absolute path; when absent, normal browser discovery applies.
 
-The configured endpoint must expose the standard CDP HTTP discovery routes such as `/json/version`
-and `/json/list`. Chrome's newer built-in permission flow can listen on port `9222` while returning
-`404` from those routes; setting the same HTTP origin does not by itself make that flow compatible.
+The configured endpoint must expose the standard CDP HTTP discovery routes such as `/json/version` and `/json/list`.
+Chrome's newer built-in permission flow can listen on port `9222` while returning `404` from those routes; setting the same HTTP origin does not by itself make that flow compatible.
 
 ### Unpacked extensions
 
 > [!WARNING]
-> An unpacked extension executes privileged browser code. Load only code you trust. Project settings
-> are honored only when Pi reports the project as trusted.
+> An unpacked extension executes privileged browser code.
+> Load only code you trust.
+> Project settings are honored only when Pi reports the project as trusted.
 
 Add trusted unpacked-extension paths to the same canonical user file:
 
@@ -105,14 +93,13 @@ Add trusted unpacked-extension paths to the same canonical user file:
 }
 ```
 
-Every user-file path must be absolute. Each extension path must resolve to a directory containing a
-valid `manifest.json` and cannot contain a comma because Chrome uses commas to separate multiple
-startup paths. For extension-configured sessions, `executablePath` must identify Chrome for
-Testing or Chromium. Branded Google Chrome is rejected because tested releases can silently ignore
-unpacked-extension startup flags.
+Every user-file path must be absolute.
+Each extension path must resolve to a directory containing a valid `manifest.json` and cannot contain a comma because Chrome uses commas to separate multiple startup paths.
+For extension-configured sessions, `executablePath` must identify Chrome for Testing or Chromium.
+Branded Google Chrome is rejected because tested releases can silently ignore unpacked-extension startup flags.
 
-A trusted project can replace the user extension list in
-`<workspace>/.pi/pi-chrome-devtools.json`. Relative paths resolve from the workspace (`ctx.cwd`):
+A trusted project can replace the user extension list in `<workspace>/.pi/pi-chrome-devtools.json`.
+Relative paths resolve from the workspace (`ctx.cwd`):
 
 ```json
 {
@@ -122,43 +109,37 @@ A trusted project can replace the user extension list in
 }
 ```
 
-Project `extensionPaths` replace, rather than append to, the user array. A project file cannot
-override `browser.endpoint`, `browser.autoLaunch`, or `browser.executablePath`; browser connection
-settings remain machine-owned user configuration. Effective precedence is defaults, user settings,
-trusted project extension paths, then deprecated environment overrides. No new environment variable
-is required.
+Project `extensionPaths` replace, rather than append to, the user array.
+A project file cannot override `browser.endpoint`, `browser.autoLaunch`, or `browser.executablePath`; browser connection settings remain machine-owned user configuration.
+Effective precedence is defaults, user settings, trusted project extension paths, then deprecated environment overrides.
+No new environment variable is required.
 
-When `extensionPaths` is non-empty, the extension skips attach-first behavior and starts an isolated,
-extension-owned managed browser with `--disable-extensions-except` and `--load-extension`. It fails
-before spawning when the endpoint is remote, auto-launch is disabled, an explicit port is occupied,
-the executable is missing, or the browser product is unsupported. It never adds extensions to,
-modifies, restarts, or closes an external browser.
+When `extensionPaths` is non-empty, the extension skips attach-first behavior and starts an isolated, extension-owned managed browser with `--disable-extensions-except` and `--load-extension`.
+It fails before spawning when the endpoint is remote, auto-launch is disabled, an explicit port is occupied, the executable is missing, or the browser product is unsupported.
+It never adds extensions to, modifies, restarts, or closes an external browser.
 
-Settings are loaded on session start. After editing JSON, use `/reload` or replace the session; the
-old managed browser is closed before the new configuration is applied. Missing files preserve the
-existing no-extension behavior. Invalid JSON, invalid browser values, and missing manifests are left
-unchanged and ignored with an actionable warning.
+Settings are loaded on session start.
+After editing JSON, use `/reload` or replace the session; the old managed browser is closed before the new configuration is applied.
+Missing files preserve the existing no-extension behavior.
+Invalid JSON, invalid browser values, and missing manifests are left unchanged and ignored with an actionable warning.
 
 ### Deprecated environment overrides and manual endpoints
 
-The existing `PI_CHROME_DEVTOOLS_HOST`, `PI_CHROME_DEVTOOLS_PORT`,
-`PI_CHROME_DEVTOOLS_AUTO_LAUNCH`, and `PI_CHROME_DEVTOOLS_BROWSER` variables remain temporary
-compatibility overrides. They still take precedence over JSON, but every session that sees one emits
-a deprecation warning. Move their values to `browser.endpoint`, `browser.autoLaunch`, and
-`browser.executablePath`; the variables will be removed in a future version.
+The existing `PI_CHROME_DEVTOOLS_HOST`, `PI_CHROME_DEVTOOLS_PORT`, `PI_CHROME_DEVTOOLS_AUTO_LAUNCH`, and `PI_CHROME_DEVTOOLS_BROWSER` variables remain temporary compatibility overrides.
+They still take precedence over JSON, but every session that sees one emits a deprecation warning.
+Move their values to `browser.endpoint`, `browser.autoLaunch`, and `browser.executablePath`; the variables will be removed in a future version.
 
-Without unpacked extensions, browser discovery still checks platform-specific Chrome, Chromium,
-Brave, and Microsoft Edge candidates. Manual launch remains available when no unpacked extensions are
-configured:
+Without unpacked extensions, browser discovery still checks platform-specific Chrome, Chromium, Brave, and Microsoft Edge candidates.
+Manual launch remains available when no unpacked extensions are configured:
 
 ```bash
 google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/pi-chrome-devtools
 ```
 
-On session shutdown, the extension terminates only browser processes it started and best-effort
-removes their temporary profiles. It never closes user-started browsers or remote endpoints.
+On session shutdown, the extension terminates only browser processes it started and best-effort removes their temporary profiles.
+It never closes user-started browsers or remote endpoints.
 
-## 🛠️ Pi tools
+## 🛠️ Tools
 
 - `chrome_devtools_load` — find and load browser capabilities relevant to a task.
 - `chrome_devtools_list_pages` — list inspectable Chrome tabs/pages.
@@ -167,28 +148,36 @@ removes their temporary profiles. It never closes user-started browsers or remot
 - `chrome_devtools_evaluate` — evaluate JavaScript in the selected page.
 - `chrome_devtools_screenshot` — capture a PNG screenshot and save it as a PNG file.
 
-### Lazy tool loading
+### Tool exposure
+
+All six tools are registered.
 
-All six tools are registered, but only `chrome_devtools_load` starts active for this extension.
+On a model/provider with native deferred-tool support, only `chrome_devtools_load` starts active for this extension.
 
 The loader accepts a task-oriented `query`, matches it against the five capability tools, and adds matching available tools without removing any active Pi tool.
 
 Loaded capability tools remain active for the rest of the session unless the user makes them unavailable through `/chrome-devtools`.
 
-Pi uses native deferred tool references on compatible Anthropic and OpenAI models.
+Pi uses native deferred tool references on compatible Anthropic models, native additional-tools or tool-search loading on compatible OpenAI and Codex Responses models, and native Kimi loading on compatible OpenAI Chat Completions models.
+
+Kimi-compatible models declare `compat.deferredToolsMode: "kimi"` in Pi's model metadata.
+
+`azure-openai-responses` remains eager because Pi's Azure adapter does not implement native deferred tool-search serialization.
 
-Other models receive Pi's safe fallback: the newly active definitions appear in the normal tool list on the next model request.
+When the selected model/provider lacks native deferred support, the extension activates every capability allowed by settings before the next model request instead of using Pi's cache-invalidating lazy-loading fallback.
 
-The capability tools omit active-only prompt snippets so a lazy load does not rebuild the system prompt prefix.
+After a session enters eager exposure, it stays eager across later model switches to avoid removing tool definitions within that session.
 
-The saved `tools` array controls which capabilities the loader may expose.
+The capability tools omit active-only prompt snippets so native deferred loading does not rebuild the system-prompt prefix.
+
+The saved `tools` array controls which capabilities the extension may expose.
 
 An empty array leaves the loader active but makes every browser capability unavailable.
 
 ### Screenshot files
 
-`chrome_devtools_screenshot` always saves the captured PNG to disk. If `savePath` is omitted,
-the extension writes a unique temp file such as:
+`chrome_devtools_screenshot` always saves the captured PNG to disk.
+If `savePath` is omitted, the extension writes a unique temp file such as:
 
 ```text
 /tmp/pi-chrome-devtools-screenshot-<uuid>.png
@@ -203,43 +192,35 @@ chrome_devtools_screenshot({
 });
 ```
 
-Relative `savePath` values resolve from Pi's current working directory. A single leading `@`
-is stripped to match Pi file-mention paths. Absolute paths are accepted only when they stay
-inside the current working directory or the OS temp directory. Paths containing `..` segments,
-NUL bytes, symlinked parent directories, directories as targets, final symbolic-link targets, or
-other non-regular file targets are rejected. Existing regular files at the target path are
-replaced. The tool result includes the resolved path, byte count, and an inline image block when
-the active model/provider can consume images. If the model cannot inspect the inline image, ask it
-to read the saved path, for example `read({ path: "artifacts/homepage.png" })`.
+Relative `savePath` values resolve from Pi's current working directory.
+A single leading `@` is stripped to match Pi file-mention paths.
+Absolute paths are accepted only when they stay inside the current working directory or the OS temp directory.
+Paths containing `..` segments, NUL bytes, symlinked parent directories, directories as targets, final symbolic-link targets, or other non-regular file targets are rejected.
+Existing regular files at the target path are replaced.
+The tool result includes the resolved path, byte count, and an inline image block when the active model/provider can consume images.
+If the model cannot inspect the inline image, ask it to read the saved path, for example `read({ path: "artifacts/homepage.png" })`.
 
-## 💬 Command
+## 💬 Commands
 
 ```text
 /chrome-devtools
 ```
 
-Opens a menu that shows the lazy catalog size, whether that catalog is saved, the configured
-endpoint, the observed managed-browser state, and any settings or launch warning before you choose
-an action. The five actions stay on one level:
-
-- **Choose available browser tools…** — stage any combination of the five capabilities, then review
-  the exact available/unavailable result before selecting **Apply tool changes**.
-- **Make all browser tools available…** or **Make all browser tools unavailable…** — preview the
-  context-appropriate bulk change before applying it.
-- **Browser status** — inspect runtime, endpoint, launch mode, and the last launch attempt without
-  probing the endpoint or starting Chrome.
-- **Browser settings** — immediately save the endpoint, auto-launch policy, or browser executable;
-  inspect unpacked-extension paths and effective sources. A deprecated environment override remains
-  effective until removed even when its underlying JSON value changes.
+Opens a menu that shows the tool catalog size, whether that catalog is saved, the configured endpoint, the observed managed-browser state, and any settings or launch warning before you choose an action.
+The five actions stay on one level:
+
+- **Choose available browser tools…** — stage any combination of the five capabilities, then review the exact available/unavailable result before selecting **Apply tool changes**.
+- **Make all browser tools available…** or **Make all browser tools unavailable…** — preview the context-appropriate bulk change before applying it.
+- **Browser status** — inspect runtime, endpoint, launch mode, and the last launch attempt without probing the endpoint or starting Chrome.
+- **Browser settings** — immediately save the endpoint, auto-launch policy, or browser executable.
+  Inspect unpacked-extension paths and effective sources.
+A deprecated environment override remains effective until removed even when its underlying JSON value changes.
 - **Help** — view command usage and return to the menu.
 
-In the tool screen, **Select all** and **Select none** are unambiguous shortcuts; individual rows use
-friendly task labels while retaining their raw `chrome_devtools_*` identity in the description.
-Toggles remain a command-local draft. **Review changes** previews the exact effect, **Apply tool
-changes** saves it, and Cancel, Escape, Ctrl+C, disposal, or session replacement discards an
-unconfirmed draft without changing runtime tools or settings. A failed apply restores the previous
-availability and loaded-tool state, preserves the settings file, retains the draft for retry, and
-reports how to recover.
+In the tool screen, **Select all** and **Select none** are unambiguous shortcuts; individual rows use friendly task labels while retaining their raw `chrome_devtools_*` identity in the description.
+Toggles remain a command-local draft.
+**Review changes** previews the exact effect, **Apply tool changes** saves it, and Cancel, Escape, Ctrl+C, disposal, or session replacement discards an unconfirmed draft without changing runtime tools or settings.
+A failed apply restores the previous availability and loaded-tool state, preserves the settings file, retains the draft for retry, and reports how to recover.
 
 Direct subcommands are also available:
 
@@ -254,28 +235,22 @@ Direct subcommands are also available:
 /chrome-devtools disable
 ```
 
-Compatibility aliases remain available: `toggle` and `select` mean `tools`, `on` means `enable`, and
-`off` means `disable`.
+Compatibility aliases remain available: `toggle` and `select` mean `tools`, `on` means `enable`, and `off` means `disable`.
 
 - `help` shows command usage.
-- `quickstart` shows the configured CDP endpoint, endpoint source, auto-launch mode, browser
-  candidates, last launch attempt, and launch hints.
-- `status` shows available and loaded capability counts, loader state, the persisted catalog,
-  settings file path, endpoint source, launch mode, last launch attempt, and active non-Chrome tool
-  count.
+- `quickstart` shows the configured CDP endpoint, endpoint source, auto-launch mode, browser candidates, last launch attempt, and launch hints.
+- `status` shows available and loaded capability counts, loader state, the persisted catalog, settings file path, endpoint source, launch mode, last launch attempt, and active non-Chrome tool count.
 - `settings` opens the same immediate-save browser settings flow used by the menu.
 - `tools` opens the same staged, width-safe availability and review flow used by the menu.
 - `toggle` and `select` are compatibility aliases for `tools`.
-- `enable` makes all five capability tools available to the loader and saves that catalog; `on` is a
-  compatibility alias.
-- `disable` makes all five capability tools unavailable and saves the empty catalog; `off` is a
-  compatibility alias. The slash command and `chrome_devtools_load` remain available.
+- `enable` makes all five capability tools available and follows the current native-deferred or eager exposure mode; `on` is a compatibility alias.
+- `disable` makes all five capability tools unavailable and saves the empty catalog; `off` is a compatibility alias.
+  The slash command and `chrome_devtools_load` remain available.
 
-The menu, `settings`, `tools`, `help`, `quickstart`, and `status` require TUI or RPC mode so their
-result is observable. TUI uses keyboard navigation and injected Pi keybindings; RPC receives
-equivalent standard dialogs. In print and JSON modes, interactive and informational routes reject
-explicitly instead of silently opening unavailable UI. The immediate `enable`/`disable` routes remain
-available for deterministic non-interactive use.
+The menu, `settings`, `tools`, `help`, `quickstart`, and `status` require TUI or RPC mode so their result is observable.
+TUI uses keyboard navigation and injected Pi keybindings; RPC receives equivalent standard dialogs.
+In print and JSON modes, interactive and informational routes reject explicitly instead of silently opening unavailable UI.
+The immediate `enable`/`disable` routes remain available for deterministic non-interactive use.
 
 ## ⚙️ Settings
 
@@ -285,25 +260,22 @@ The available capability names are saved to:
 ${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-chrome-devtools.json
 ```
 
-The same file owns `browser.endpoint`, `browser.autoLaunch`, `browser.executablePath`, and
-`browser.extensionPaths`. Browser connection fields are machine-owned user settings; trusted project
-files may replace only `browser.extensionPaths`. Confirmed menu changes apply before the next browser
-connection and close only an extension-owned managed browser. Manual JSON edits and unpacked-extension
-changes apply after `/reload` or session replacement.
-
-When the file is missing or invalid, the extension preserves Pi's current Chrome DevTools
-availability policy instead of replacing it. A valid saved catalog is restored on Pi startup and
-`/reload`, while its capability definitions remain deferred. A missing file is created by the first
-confirmed browser or tool setting. Within one Pi process, all browser and tool saves run in invocation
-order, reread the latest valid document, publish by temporary-file rename, and preserve unknown
-fields. Malformed JSON or invalid recognized fields make menu mutation unavailable and block direct
-saves without replacement; a failed save restores the prior displayed and effective state.
-
-Compatibility: older versions used `pi-chrome-devtools-settings.json`. A legacy-only file remains
-readable with a warning and is never modified automatically; rename it to
-`pi-chrome-devtools.json`. The first subsequent settings save writes the canonical file. If both
-files exist, `pi-chrome-devtools.json` wins and the legacy file is ignored. The legacy
-filename is deprecated and will be removed in a future major release.
+The same file owns `browser.endpoint`, `browser.autoLaunch`, `browser.executablePath`, and `browser.extensionPaths`.
+Browser connection fields are machine-owned user settings; trusted project files may replace only `browser.extensionPaths`.
+Confirmed menu changes apply before the next browser connection and close only an extension-owned managed browser.
+Manual JSON edits and unpacked-extension changes apply after `/reload` or session replacement.
+
+When the file is missing or invalid, the extension preserves Pi's current Chrome DevTools availability policy instead of replacing it.
+A valid saved catalog is restored on Pi startup and `/reload`, with capability definitions exposed natively deferred or eagerly according to model/provider support.
+A missing file is created by the first confirmed browser or tool setting.
+Within one Pi process, all browser and tool saves run in invocation order, reread the latest valid document, publish by temporary-file rename, and preserve unknown fields.
+Malformed JSON or invalid recognized fields make menu mutation unavailable and block direct saves without replacement; a failed save restores the prior displayed and effective state.
+
+Compatibility: older versions used `pi-chrome-devtools-settings.json`.
+A legacy-only file remains readable with a warning and is never modified automatically; rename it to `pi-chrome-devtools.json`.
+The first subsequent settings save writes the canonical file.
+If both files exist, `pi-chrome-devtools.json` wins and the legacy file is ignored.
+The legacy filename is deprecated and will be removed in a future major release.
 
 ## 🧠 Use cases
 
@@ -331,7 +303,8 @@ packages/pi-chrome-devtools/
 └── package.json
 ```
 
-`index.ts` is the Pi entrypoint and forwards to `chrome-devtools.ts`; the other source modules are internal. The package exposes its Pi extension through `package.json`:
+`index.ts` is the Pi entrypoint and forwards to `chrome-devtools.ts`; the other source modules are internal.
+The package exposes its Pi extension through `package.json`:
 
 ```json
 {
@@ -349,4 +322,5 @@ Pi extension, Pi coding agent, Chrome DevTools Protocol, CDP, browser automation
 
 ## 📄 License
 
-MIT. See [`LICENSE`](./LICENSE).
+MIT.
+See [`LICENSE`](./LICENSE).

package/dist/chunks/{browser-settings-menu-L4CZINWO.ts → browser-settings-menu-VWCNG4HB.js}

@@ -1,5 +1,5 @@
 // @generated by scripts/build-runtime.mjs; do not edit.
-// @ts-nocheck -- generated JavaScript uses a .ts extension for Pi's Jiti loader.
+// @ts-nocheck -- the generated entry uses a .ts extension for Pi's Jiti loader.
 import {
   applyRuntimeBrowserSettings,
   loadSettings,
@@ -8,7 +8,7 @@ import {
   saveBrowserSettings,
   shutdownManagedBrowser,
   state
-} from "./chunk-RM7OGXVL.js";
+} from "./chunk-RH6KESL3.js";
 
 // src/browser-settings-menu.ts
 import { isAbsolute } from "node:path";
@@ -263,4 +263,4 @@ function formatError(error) {
 export {
   showChromeDevtoolsBrowserSettings
 };
-//# sourceMappingURL=browser-settings-menu-L4CZINWO.ts.map
+//# sourceMappingURL=browser-settings-menu-VWCNG4HB.js.map

package/dist/chunks/{chunk-RM7OGXVL.ts → chunk-RH6KESL3.js}

@@ -1,5 +1,5 @@
 // @generated by scripts/build-runtime.mjs; do not edit.
-// @ts-nocheck -- generated JavaScript uses a .ts extension for Pi's Jiti loader.
+// @ts-nocheck -- the generated entry uses a .ts extension for Pi's Jiti loader.
 
 // src/tool-names.ts
 var CHROME_DEVTOOLS_TOOL_NAMES = [
@@ -1250,7 +1250,9 @@ var DevToolsEndpointError = class extends Error {
 };
 
 // src/lazy-tools.ts
-import { defineTool } from "@earendil-works/pi-coding-agent";
+import {
+  defineTool
+} from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 var CHROME_DEVTOOLS_LOAD_TOOL_NAME = "chrome_devtools_load";
 var AVAILABLE_TOOLS_STORE = /* @__PURE__ */ Symbol.for("@narumitw/pi-chrome-devtools.available-tools-store");
@@ -1258,6 +1260,7 @@ var sharedGlobal = globalThis;
 var existingAvailableToolsStore = sharedGlobal[AVAILABLE_TOOLS_STORE];
 var availableToolsByApi = existingAvailableToolsStore ?? /* @__PURE__ */ new WeakMap();
 if (!existingAvailableToolsStore) sharedGlobal[AVAILABLE_TOOLS_STORE] = availableToolsByApi;
+var lazyExposureByApi = /* @__PURE__ */ new WeakMap();
 var SEARCH_TEXT = {
   chrome_devtools_list_pages: "list open inspectable chrome browser pages tabs targets",
   chrome_devtools_select_page: "select choose active chrome browser page tab target",
@@ -1273,17 +1276,53 @@ function initializeAvailableChromeDevtoolsTools(pi) {
     CHROME_DEVTOOLS_TOOL_NAMES.filter((name) => activeTools.has(name))
   );
 }
-function configureLazyChromeDevtoolsTools(pi, availableTools) {
-  setAvailableTools(pi, availableTools);
+function configureChromeDevtoolsToolExposure(pi, availableTools, model) {
+  const available = setAvailableTools(pi, availableTools);
+  const lazyExposure = supportsNativeDeferredToolLoading(model);
+  lazyExposureByApi.set(pi, lazyExposure);
+  const exposedTools = lazyExposure ? [] : CHROME_DEVTOOLS_TOOL_NAMES.filter((name) => available.has(name));
   const nonCapabilityTools = pi.getActiveTools().filter((name) => !CHROME_DEVTOOLS_TOOL_NAMES.includes(name));
-  pi.setActiveTools(unique([...nonCapabilityTools, CHROME_DEVTOOLS_LOAD_TOOL_NAME]));
+  pi.setActiveTools(
+    unique([...nonCapabilityTools, CHROME_DEVTOOLS_LOAD_TOOL_NAME, ...exposedTools])
+  );
+}
+function requireEagerChromeDevtoolsToolExposure(pi) {
+  lazyExposureByApi.set(pi, false);
+  const active = pi.getActiveTools();
+  const available = availableChromeDevtoolsTools(pi);
+  pi.setActiveTools(unique([...active, CHROME_DEVTOOLS_LOAD_TOOL_NAME, ...available]));
 }
 function applyAvailableChromeDevtoolsTools(pi, availableTools) {
   const available = setAvailableTools(pi, availableTools);
+  const lazyExposure = lazyExposureByApi.get(pi) === true;
   const active = pi.getActiveTools().filter(
-    (name) => !CHROME_DEVTOOLS_TOOL_NAMES.includes(name) || available.has(name)
+    (name) => !CHROME_DEVTOOLS_TOOL_NAMES.includes(name) || lazyExposure && available.has(name)
   );
-  pi.setActiveTools(unique([...active, CHROME_DEVTOOLS_LOAD_TOOL_NAME]));
+  const eagerTools = lazyExposure ? [] : CHROME_DEVTOOLS_TOOL_NAMES.filter((name) => available.has(name));
+  pi.setActiveTools(unique([...active, CHROME_DEVTOOLS_LOAD_TOOL_NAME, ...eagerTools]));
+}
+function chromeDevtoolsToolExposureMode(pi) {
+  return lazyExposureByApi.get(pi) === true ? "native deferred" : "eager";
+}
+function supportsNativeDeferredToolLoading(model) {
+  if (!model) return false;
+  if (model.api === "anthropic-messages") {
+    const configured = compatBoolean(model.compat, "supportsToolReferences");
+    if (configured !== void 0) return configured;
+    if (model.provider !== "anthropic" || model.id.includes("haiku")) return false;
+    const version = model.id.match(/^claude-(?:opus|sonnet|fable)-(\d+)(?:-(\d+))?(?:-|$)/);
+    if (!version) return false;
+    const major = Number(version[1]);
+    const minor = version[2] && version[2].length < 8 ? Number(version[2]) : 0;
+    return major > 4 || major === 4 && minor >= 5;
+  }
+  if (model.api === "openai-completions") {
+    return compatString(model.compat, "deferredToolsMode") === "kimi";
+  }
+  if (model.api === "openai-responses" || model.api === "openai-codex-responses") {
+    return compatBoolean(model.compat, "supportsAdditionalTools") === true || compatBoolean(model.compat, "supportsToolSearch") === true;
+  }
+  return false;
 }
 function availableChromeDevtoolsTools(pi) {
   const available = availableToolsByApi.get(pi) ?? /* @__PURE__ */ new Set();
@@ -1343,6 +1382,16 @@ function setAvailableTools(pi, availableTools) {
   availableToolsByApi.set(pi, available);
   return available;
 }
+function compatBoolean(value, key) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+  const record = value;
+  return typeof record[key] === "boolean" ? record[key] : void 0;
+}
+function compatString(value, key) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+  const record = value;
+  return typeof record[key] === "string" ? record[key] : void 0;
+}
 function unique(values) {
   return [...new Set(values)];
 }
@@ -1361,7 +1410,7 @@ async function updateChromeDevtoolsTools(pi, ctx, selectedTools, action) {
   if (result !== "saved" || generation !== state.sessionGeneration) return;
   const status = await buildToolStatusMessage(pi);
   if (generation !== state.sessionGeneration) return;
-  ctx.ui.notify(`Chrome DevTools lazy catalog ${action}.
+  ctx.ui.notify(`Chrome DevTools tool catalog ${action}.
 
 ${status}`, "info");
 }
@@ -1411,7 +1460,8 @@ async function transactSelectedToolsNow(pi, ctx, selectedTools, expectedGenerati
       const previousLoadedChromeTools = previousActiveTools.filter(
         (name) => CHROME_DEVTOOLS_TOOL_NAMES.includes(name)
       );
-      pi.setActiveTools(unique2([...currentNonChromeTools, ...previousLoadedChromeTools]));
+      const restoredChromeTools = chromeDevtoolsToolExposureMode(pi) === "eager" ? previousAvailableTools : previousLoadedChromeTools;
+      pi.setActiveTools(unique2([...currentNonChromeTools, ...restoredChromeTools]));
     } catch (caught) {
       rollbackError = caught;
     }
@@ -1454,10 +1504,11 @@ async function buildToolStatusMessage(pi) {
   const persistedSetting = await persistedSettingLabel();
   return sanitizeChromeDevtoolsDisplay(
     [
-      `Chrome DevTools tools available to lazy-load: ${formatRuntimeStatus(summary)}`,
+      `Chrome DevTools tools available: ${formatRuntimeStatus(summary)}`,
+      `Tool exposure: ${chromeDevtoolsToolExposureMode(pi)}`,
       `Loaded capability tools this session: ${summary.loadedChromeToolCount}/${CHROME_DEVTOOLS_TOOL_NAMES.length}`,
       `Loader: ${pi.getActiveTools().includes(CHROME_DEVTOOLS_LOAD_TOOL_NAME) ? "active" : "inactive"}`,
-      `Persisted lazy catalog: ${persistedSetting}`,
+      `Persisted tool catalog: ${persistedSetting}`,
       ...browserSettingsStatusLines(),
       ...state.settingsNotice ? [`Settings note: ${state.settingsNotice}`] : [],
       `Other active tools preserved: ${summary.activeNonChromeToolCount}`,
@@ -1537,9 +1588,9 @@ function buildCommandGuide() {
     "/chrome-devtools quickstart \u2014 show endpoint and launch help",
     "/chrome-devtools status \u2014 show tool and settings status",
     "/chrome-devtools settings \u2014 edit browser connection settings",
-    "/chrome-devtools tools \u2014 choose tools available to lazy-load",
+    "/chrome-devtools tools \u2014 choose available Chrome DevTools tools",
     "/chrome-devtools toggle|select \u2014 compatibility aliases for tools",
-    "/chrome-devtools enable|on \u2014 make all Chrome DevTools tools available to lazy-load",
+    "/chrome-devtools enable|on \u2014 make all Chrome DevTools tools available",
     "/chrome-devtools disable|off \u2014 make all Chrome DevTools capability tools unavailable"
   ].join("\n");
 }
@@ -1591,7 +1642,9 @@ export {
   launchHint,
   formatPageListItem,
   initializeAvailableChromeDevtoolsTools,
-  configureLazyChromeDevtoolsTools,
+  configureChromeDevtoolsToolExposure,
+  requireEagerChromeDevtoolsToolExposure,
+  supportsNativeDeferredToolLoading,
   availableChromeDevtoolsTools,
   createChromeDevtoolsLoadTool,
   updateChromeDevtoolsTools,
@@ -1604,4 +1657,4 @@ export {
   buildCommandGuide,
   allChromeDevtoolsTools
 };
-//# sourceMappingURL=chunk-RM7OGXVL.ts.map
+//# sourceMappingURL=chunk-RH6KESL3.js.map