wayfinder-pi

A Pi extension that shows which model the Wayfinder router chose (and how) after each routed turn.

• A compact footer status line updates after every routed response, for example wf scored → gpt-4o · 0.42.
• /wf prints the full last decision (mode, chose, served-by, score, request-id, flags).

How it works

Wayfinder sets x-wayfinder-router-* response headers on every routed request. The extension reads them from Pi's after_provider_response event. No extra HTTP requests are made.

Requirements

• Pi 0.67.6 or later, which added the after_provider_response extension hook.
• A Wayfinder gateway configured as Pi's openai-completions provider.

Install

From GitHub

After the first release, install a pinned version globally:

pi install git:github.com/wyattjoh/wayfinder-pi@v0.1.0

To install it for one project instead, add -l:

pi install git:github.com/wyattjoh/wayfinder-pi@v0.1.0 -l

From npm

Once published to npm, install the same release with:

pi install npm:@wyattjoh/wayfinder-pi@0.1.0

From a local checkout

For development, symlink the extension into Pi's global extension directory:

mkdir -p ~/.pi/agent/extensions
ln -sfn "$(pwd)/src/index.ts" ~/.pi/agent/extensions/wayfinder.ts

Auto-discovered extensions support /reload for quick iteration.

Alternatively, add the absolute repository path to the extensions array in ~/.pi/agent/settings.json:

{
  "extensions": ["/absolute/path/to/wayfinder-pi"]
}

Usage

After a routed response, Pi displays a compact footer line such as:

wf  scored → gpt-4o · 0.42

Run /wf to display the complete decision captured from the last routed response:

wayfinder - last decision
mode:        scored
chose:       gpt-4o
served by:   gpt-4o
score:       0.42
request-id:  req_a1b2c3
flags:       (none)

Provider Configuration

To route through a Wayfinder gateway, configure Pi with an openai-completions provider in ~/.pi/agent/models.json:

{
  "providers": {
    "wayfinder": {
      "baseUrl": "http://127.0.0.1:8088/v1",
      "apiKey": "local",
      "api": "openai-completions",
      "models": [{ "id": "auto", "name": "Wayfinder (auto)", "input": ["text"], "contextWindow": 131072, "maxTokens": 32768, "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 } }]
    }
  }
}

Then select the wayfinder provider and auto model (or set as defaultProvider and defaultModel in ~/.pi/agent/settings.json).

The example baseUrl assumes a local gateway; substitute your own host as needed. The apiKey can be any placeholder for the gateway's keyless local preset.

Fallbacks (not built)

If a future Pi provider does not expose response headers, two other read-paths exist on the Wayfinder side:

1. Send X-Wayfinder-Debug: true and parse the wayfinder block from the body.
2. Poll GET /router/recent, joining on x-wayfinder-router-request-id.

Neither is implemented; the header read-path is used exclusively and has been verified end-to-end against a live gateway on the openai-completions transport.