pi-websearch-manager

A small Pi extension that keeps Codex web_run and extension-provided web-search tools from competing with each other.

It routes the recognized search capabilities for the current runtime:

• Codex structured mode: enable top-level web_run and hide managed extension-provider tools.
• Codex Code or Notebook mode: hide all managed top-level search tools because @howaboua/pi-codex-web-run exposes web__run through exec.
• Other models: hide top-level web_run and enable the tools from pi-web-access or @juicesharp/rpiv-web-tools.
• No registered web_run: keep extension-provider search available, including on Codex models.

This package does not implement web search. It only manages Pi's active tool list.

Install

Install the Codex adapter, its standalone web-search package, one extension web provider, and this manager:

pi install npm:@howaboua/pi-codex-conversion
pi install npm:@howaboua/pi-codex-web-run
pi install npm:@juicesharp/rpiv-web-tools
# or, instead of rpiv-web-tools:
# pi install npm:pi-web-access
pi install npm:@oleg_tarasov/pi-websearch-manager

pi-codex-conversion 3.0.24 removed its bundled web search. Current installations need the separate @howaboua/pi-codex-web-run package for web_run.

Recommended package order in ~/.pi/agent/settings.json:

{
  "packages": [
    "npm:@howaboua/pi-codex-conversion",
    "npm:@howaboua/pi-codex-web-run",
    "npm:@juicesharp/rpiv-web-tools",
    "npm:@oleg_tarasov/pi-websearch-manager"
  ]
}

Use npm:pi-web-access instead of npm:@juicesharp/rpiv-web-tools if preferred. Do not install both extension web providers unless you intentionally manage their name collision: both register web_search by default, and Pi keeps the first registration for a tool name.

Load the manager after the providers. Pi runs lifecycle handlers sequentially in extension order, so manager-last lets it reconcile the final tool plan without timing-based callbacks.

Prerequisites and configuration

This release supports Pi 0.84.4 and newer. Development checks run against Pi 0.99.2, and provider lifecycle smoke tests use pi-codex-conversion 3.0.42, pi-codex-web-run 0.0.5, @juicesharp/rpiv-web-tools 2.12.0, and pi-web-access 0.35.0. The production source is also type-checked against the minimum Pi version.

Authenticate the standalone Codex search route:

/login openai-codex

Compatible active Codex transports can use their own credentials. For renamed or proxied Responses providers, keep pi-codex-conversion's scope.additionalProviders aligned with the routes in ~/.pi/agent/pi-codex-tools.json; the active conversion plan is the manager's routing signal for those aliases.

Pi 0.99 also offers /login openai with a ChatGPT subscription. This does not by itself establish a Codex adapter plan or replace the standalone web-run package's authentication requirements. On openai, the manager follows an active conversion plan rather than treating every OpenAI model as a Codex route.

Configure the extension provider separately:

• Run /web-tools for @juicesharp/rpiv-web-tools.
• Configure ~/.pi/agent/web-search.json for pi-web-access when its defaults are not sufficient.

Keep Codex conversion scoped to Codex and explicitly configured providers unless broader adapter activation is intentional:

{
  "scope": {
    "allProviders": "off",
    "additionalProviders": []
  }
}

Use /codex to select normal, Code, or Notebook execution mode. pi-codex-web-run integrates with Code and Notebook mode through the conversion extension's bridge.

Provider-owned activation (optional)

The default remains eager, preserving the manager's existing behavior: session/model changes enable registered, declarable extension web tools. To respect current pi-web-access lazy activation and recorded selections, start Pi with:

pi --websearch-manager-activation provider

Accepted values are eager (default) and provider. In provider mode, a recognized pi-web-access web_enable loader signals provider-owned activation. The manager preserves the provider's loader-only, eager-auto, partial, or disabled selection instead of enabling every tool. It remembers that selection while hiding it on Codex and restores it when switching back. Session and tree restoration discard the previous session/branch's saved selection.

Legacy pi-web-access, or toolActivation: "eager" without a loader, and rpiv-web-tools retain eager routing. Codex conflict removal always includes web_enable, regardless of activation mode. To deliberately enable all declarable tools on the extension route in provider mode, run /websearch-manager enable.

Routing behavior

The manager recognizes direct Codex models from the current provider/API and configured provider aliases from active, conversion-owned structured or Code-mode tools. An active standalone web_run alone is deliberately not treated as a Codex-plan signal because the standalone package can execute while chatting with unrelated providers. Legacy conversion-owned web_run remains supported for pre-split installations.

Supported tools are identified using Pi's canonical sourceInfo provenance:

• @howaboua/pi-codex-web-run: web_run
• legacy @howaboua/pi-codex-conversion: web_run
• @juicesharp/rpiv-web-tools: web_search, web_fetch
• pi-web-access: its registered tools, including web_enable and configurable public names for web_search, source_check, fetch_content, and get_search_content

npm, Git, and local checkouts are recognized when their provenance retains the exact package directory name. Unrelated extensions that reuse generic names such as web_search or web_run are left untouched.

At session_start and model_select, the preferred route is applied using the activation policy above. Code/Notebook activation also refreshes the conversion bridge's projection so switching from an extension route exposes nested web__run, not just a status label. At session_tree and immediately before a turn, conflicts are removed without re-enabling preferred tools that the user disabled through /tools. Run /websearch-manager to reapply the route explicitly; provider mode still preserves provider-owned selection unless enable is supplied.

Pi 0.99 hidden tools are never activated. Callable-only codemode/deferred tools are not automatically promoted to top-level declarations. Status and command output use Pi's accepted active selection, not an attempted activation. The manager routes active declarations; it does not revoke independently callable deferred tools. Current managed providers register ordinary direct tools.

Pi's native codemode is distinct from conversion-owned exec. Native codemode-only can invoke the selected direct web tools inside its sandbox even when their top-level declarations are hidden. The manager leaves native codemode alone; Codex conversion handles suspending it in its own Code/Notebook modes.

The status line shows:

• 🔍 web_run for top-level Codex search
• 🔍 web__run for nested Code/Notebook search
• 🔍 rpiv-web-tools or 🔍 pi-web-access for a recognized extension provider
• 🔍 pi-web-access (lazy) when only its loader is selected
• 🔍 ext. search when multiple managed extension providers are active and no single label is unambiguous

No status is shown when the selected route has no active search tool or loader. These labels identify the route, not necessarily a top-level declaration when native codemode-only is in use.

Command

/websearch-manager [enable]

Shows the recognized runtime route and reapplies it immediately. enable explicitly expands provider-owned selection on the extension route; it never reopens extension search on a Codex route.

Development

npm install
npm run check
npm pack --dry-run

npm run check type-checks the extension and runs lifecycle, provenance, model-switch, Code/Notebook projection, provider activation, exposure, provider-alias, and manual-tool-selection regressions. SDK tests use real Pi model/lifecycle handling and a native codemode sandbox, with offline provider fixtures and an isolated authentication stub. No authenticated search is needed to validate this active-tool router.

To test a local checkout in Pi:

pi -e /Users/oleg/Projects/pi-websearch-manager

Versioning and release process

This package follows Semantic Versioning. For a release:

1. Update package.json and CHANGELOG.md.
2. Run npm run check and npm pack --dry-run.
3. Commit, tag vX.Y.Z, and push the commit and tag.
4. Publish with npm publish --access public.