# wayfinder-pi

A [Pi](https://pi.dev/) extension that shows which model the
[Wayfinder](https://github.com/wyattjoh/wayfinder-router) 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:

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

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

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

### From npm

Once published to npm, install the same release with:

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

### From a local checkout

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

```sh
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`:

```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`:

```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.