@oleg_tarasov/pi-websearch-manager

Pi extension that routes web search tools between Codex web_run plans and extension-provided web tools.

Packages

Package details

extension

Install @oleg_tarasov/pi-websearch-manager from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:@oleg_tarasov/pi-websearch-manager
Package
@oleg_tarasov/pi-websearch-manager
Version
0.4.1
Published
Nov 15, 2026
Downloads
331/mo · 234/wk
Author
oleg_tarasov
License
MIT
Types
extension
Size
39.4 KB
Dependencies
0 dependencies · 1 peer
Pi manifest JSON
{
  "extensions": [
    "./src/index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

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, Notebook, TypeScript, or QuickJS mode: use nested web__run through exec and hide managed extension-provider tools. Current conversion versions keep web_run active for Pi admission while hiding its top-level declaration.
  • 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

The router supports Pi 0.84.4 and newer. Development checks run against Pi 1.5.2, and the production source is also type-checked against the minimum Pi version. The current companion stack requires Pi 1.5.0 or newer because of the conversion extension's requirements; the router's lower minimum does not lower its companions' requirements.

Compatibility was reviewed against pi-codex-conversion 5.0.0, pi-codex-web-run 0.0.10, @juicesharp/rpiv-web-tools 2.15.0, and pi-web-access 0.47.0. Bridge regression tests exercise the real conversion implementation in both current and legacy versions; provider-selection tests use offline fixtures.

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.

Current Pi 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 the conversion extension's execution mode. Its current Code, Notebook, TypeScript, and QuickJS modes use exec; pi-codex-web-run integrates with them through the conversion 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

Recognized runtime Preferred search Search declarations excluded
Direct Codex model or active structured Codex adapter plan, with registered web_run web_run Managed extension-provider tools
Active Codex exec plan, with registered web_run Nested web__run through exec Top-level web_run (by conversion) and managed extension-provider tools
Any runtime without registered web_run Registered extension-provider tools None
Other models Registered extension-provider tools Top-level web_run

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 installations are recognized by their exact package identity. Git and local checkouts are recognized when their provenance retains the exact package directory name. An unrelated npm package cannot be matched by its installation directory alone. 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. Activating an exec route also refreshes the conversion bridge so switching from an extension route exposes nested web__run. The manager follows the bridge's accepted selection: current conversion retains active web_run admission and hides its declaration through Pi's loadout API; legacy conversion folds it out of the active selection. Preserving current admission keeps nested search available on later turns and during session restoration.

If conversion defers a refresh while Pi is busy, the manager preserves the accepted selection and waits for reconciliation before showing nested-search status.

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.

Hidden tools are never activated on Pi hosts with exposure metadata. Callable-only codemode/deferred tools are not automatically promoted to top-level declarations. Status and command output use Pi's accepted active selection rather than an attempted activation.

The manager controls active-tool selection; it cannot revoke independently callable deferred tools. Current pi-web-access supports optional deferred exposure, including toolActivation: "none". Those tools can remain callable on a Codex route even after the manager excludes their declarations. Use the provider's default direct exposure when search exclusivity must follow the active route.

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 search through the conversion extension's exec
  • 🔍 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 available search tool or loader. On a current conversion exec route, nested status requires active exec, active web_run admission, and a registered web__run bridge integration. Disabling web_run through /tools clears that status; /websearch-manager reapplies the route. These labels identify the route, which may be nested instead of a top-level declaration.

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 run typecheck:minimum
npm pack --dry-run

npm run check type-checks the extension and runs lifecycle, provenance, model-switch, conversion bridge, provider activation, exposure, provider-alias, and manual-tool-selection regressions. Bridge tests load real current and legacy conversion code and check nested search after pre-turn synchronization. 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.

npm run typecheck:minimum checks only the production source against an isolated Pi 0.84.4 installation; the SDK runtime tests target the current development host.

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, npm run typecheck:minimum, and npm pack --dry-run.
  3. Commit, tag vX.Y.Z, and push the commit and tag.
  4. Publish with npm publish --access public.