pi-bedrouter 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Barry Melton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# pi-bedrouter
+
+A [Pi](https://pi.dev) extension for [bedrouter](https://github.com/bmelton/bedrouter), the cost-aware model router in front of AWS Bedrock. It makes the router a first-class part of a Pi session:
+
+- **finds bedrouter** (a configured checkout, or the npm dependency this package ships with) and installs or builds it when it is missing
+- **starts the server** when it is not already running, seeding `.env` and `bedrouter.json` from bedrouter's examples on first run
+- **registers a `bedrouter` provider** in Pi whose models come straight from `bedrouter.json`: the `auto` aliases (the router decides everything) plus each rung of each ladder
+- **switches the session to `bedrouter/auto`** when the server is healthy, so nobody has to pick a model
+- **shows what served each request in the footer**, live: routed model vs requested, class and deciding signal, the classifier's note, and the session's running cost against what the requested model would have cost
+- **`/bedrouter`** for everything else: status, start/stop/restart, doctor and the per-rung entitlement probe, the savings report, the last N decisions, pi-agents fit notes
+
+```
+⇄ gpt-oss-120b ≠ gpt-oss-20b  explore·clf:explore  $0.0412 saved $0.0188 (31%)  ↑1
+```
+
+## Install
+
+```sh
+pi install npm:pi-bedrouter          # once published
+# or, from a checkout:
+pi install /path/to/pi-bedrouter     # or add the path to "packages" in ~/.pi/agent/settings.json
+```
+
+The package depends on `bedrouter` (a git dependency with a build step), so `npm install` inside it produces a runnable `bedrouter` binary. If you already have a bedrouter checkout you'd rather use, point at it (below) and the dependency is ignored.
+
+Bedrouter needs AWS credentials that can call Bedrock; see its README for the `aws sso login` recipe. pi-bedrouter does not touch credentials, it just starts the server in a directory that has a `.env`.
+
+## Settings
+
+`~/.pi/agent/pi-bedrouter.json` (all optional; `/bedrouter config` creates it with defaults):
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `path` | the `bedrouter` dependency | A bedrouter checkout or install to use instead |
+| `home` | `path` if set, else `~/.bedrouter` | Working directory for the server: `.env`, `bedrouter.json`, `bedrouter.log.jsonl`, `server.log` |
+| `port` | `20129` | Port to run / expect the server on (`BEDROUTER_PORT` overrides) |
+| `autoStart` | `true` | Start the server on session start when it is not running |
+| `autoSelect` | `"auto"` | Model id to switch the session to when bedrouter is healthy (`"auto"`, `"auto-oss"`, a rung alias, or `false` to leave the model alone) |
+| `debug` | `false` | Start the server with `BEDROUTER_DEBUG=1` (per-request trace in `server.log`) |
+| `footer` | `true` | Show the routing status line in Pi's footer |
+| `providerName` | `"bedrouter"` | Provider name registered in Pi |
+| `healthPollS` | `15` | Seconds between background health checks. A dead server flips the footer to `bedrouter: DOWN` and, with `autoStart`, is restarted (at most once a minute); `0` disables the poll |
+
+Example for a developer with a checkout:
+
+```json
+{ "path": "~/projects/ai/bedrouter", "autoSelect": "auto-oss" }
+```
+
+## Commands
+
+| Command | Does |
+| --- | --- |
+| `/bedrouter` or `/bedrouter status` | Install location, server health (pid, version, region, classifier), registered models, current model, last decision |
+| `/bedrouter start` / `stop` / `restart` | Manage the server. It is shared by every Pi session, so `stop` affects all of them |
+| `/bedrouter install` | `npm install` the dependency, or `npm run build` a checkout that has no `dist/` |
+| `/bedrouter doctor` | Which credential source resolved, expiry, the loaded ladder |
+| `/bedrouter probe` | One 1-token request per rung: which models this AWS account can actually invoke |
+| `/bedrouter report [--since t] [--json]` | Savings report over the decision log |
+| `/bedrouter log [n]` | The last n routing decisions, one line each |
+| `/bedrouter models` | Re-read `bedrouter.json` and re-register the provider (after editing the ladder) |
+| `/bedrouter fitnotes` | Merge model notes into `~/.pi/agent/workflows.json` so the pi-agents planner defaults to `bedrouter/auto` and only pins premium rungs for planning/review |
+| `/bedrouter config` | Show (and create) the settings file |
+
+## How the footer works
+
+Bedrouter echoes every routing decision in response headers (`x-bedrouter-model`, `-requested`, `-class`, `-reason`, `-conversation`, `-classifier`). Pi hands extensions those headers in the `after_provider_response` event, so the status line updates the moment a response starts, before any tokens stream. When the turn ends, the extension asks bedrouter for the conversation's running totals (`GET /v1/conversations/:key`) and appends cost: spend so far (classifier calls included), what the same tokens would have cost on the model the client asked for, and the difference as a percentage. `↑n` counts escalations in this conversation. The line clears when you switch to a non-bedrouter model. A background health check (every `healthPollS` seconds) keeps it honest between turns: if the server dies the line reads `bedrouter: DOWN` and, with `autoStart` on, the extension restarts it and says so.
+
+Under a coding agent every request carries tools and a large system prompt, so you will see `execute` and `explore` decided by keywords or the classifier, then `sticky` for the rest of the session, `up:kw:explore` when an explicit design question moves the conversation up, and escalations after failures. `trivial` shows up for bare chat clients, not for Pi.
+
+## Model ids
+
+From bedrouter's example config: `auto` (Anthropic ladder, router decides), `auto-oss` (gpt-oss ladder), and the rungs `haiku`, `sonnet`, `opus`, `gpt-oss-20b`, `gpt-oss-120b`. Picking a rung is a floor: bedrouter may still go up (explore, escalation) but not below it. Picking `auto` hands it the whole decision. The `cost` Pi shows for `auto` is the family's execute rung; bedrouter's log and `/bedrouter report` have what was actually charged.
+
+If your `~/.pi/agent/settings.json` has an `enabledModels` allowlist, add `bedrouter/auto` (and any rungs you want visible) or the provider's models will be hidden.
+
+## Development
+
+```sh
+npm install
+npm run typecheck
+npm test                                        # pure tests
+BEDROUTER_TEST_PATH=~/projects/ai/bedrouter npm test   # also exercises locate/start against a built checkout
+```
+
+Layout: `extensions/index.ts` (the extension: events, provider registration, `/bedrouter`), `src/bedrouter.ts` (locate/install/start/stop/health/run), `src/models.ts` (config → Pi models, fit notes), `src/footer.ts` (headers → status line), `src/settings.ts`.
+
+## Publishing
+
+Both packages are on npm: `bedrouter` (the server, with the `bedrouter` binary) and `pi-bedrouter` (this extension, which depends on it). The `pi-package` keyword makes the extension discoverable at pi.dev/packages. Release order when both change: publish `bedrouter` first, bump the dependency range here, then publish `pi-bedrouter`.

package/extensions/index.ts

@@ -0,0 +1,257 @@
+// pi-bedrouter: run bedrouter (the cost-aware Bedrock model router) from inside Pi.
+//
+//  - finds the bedrouter install (settings.path or the npm dependency), installs/builds it when missing
+//  - starts the server when it is not running, seeding .env / bedrouter.json from the examples
+//  - registers a "bedrouter" provider whose models come from bedrouter.json (auto aliases + rungs)
+//  - optionally switches the session to bedrouter/auto so nobody has to pick a model
+//  - shows which model served each request in the footer, from bedrouter's x-bedrouter-* response headers,
+//    plus the running session cost against what the requested model would have cost
+//  - /bedrouter status|start|stop|restart|install|doctor|probe|report|log|models|fitnotes|config
+import fs from "node:fs";
+import path from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadSettings, saveSettings, settingsPath, agentDir, type Settings } from "../src/settings.js";
+import * as br from "../src/bedrouter.js";
+import { fitNotes, piModels } from "../src/models.js";
+import { fromHeaders, statusLine, type LastDecision } from "../src/footer.js";
+
+export default async function (pi: ExtensionAPI) {
+  let settings = loadSettings();
+  let last: LastDecision | null = null;
+  let stats: br.ConversationStats | null = null;
+  let registeredModelIds: string[] = [];
+  let lastCtx: ExtensionContext | null = null; // most recent context, for the background poll to update the footer
+  let serverUp: boolean | null = null;         // last known health; null = never checked
+  let restartAttemptAt = 0;                    // throttle auto-restarts to one per 60 s
+
+  const isOurs = (ctx: ExtensionContext) => ctx.model?.provider === settings.providerName;
+  const setStatus = (ctx: ExtensionContext, text: string | undefined) => { lastCtx = ctx; if (ctx.hasUI && settings.footer) ctx.ui.setStatus("bedrouter", text); };
+  const readyText = () => statusLine(last, stats);
+  const notify = (ctx: ExtensionContext, msg: string, type: "info" | "warning" | "error" = "info") => { if (ctx.hasUI) ctx.ui.notify(msg, type); };
+  /** Show multi-line output (doctor/report/log) as a visible message without adding it to the model's context. */
+  const show = (title: string, body: string) => pi.sendMessage({ customType: "bedrouter", content: `**${title}**\n\n\`\`\`\n${body}\n\`\`\``, display: true }, { triggerTurn: false });
+
+  /**
+   * Register (or re-register) the provider. Source, in order: the running server's /v1/models (always right for the
+   * ladder that is actually serving), then bedrouter.json (home dir, then the checkout), then the shipped default.
+   */
+  async function registerProvider(loc: br.Found | null): Promise<string> {
+    let cfg: br.BedrouterConfig | null = null;
+    let source = "";
+    const live = await br.liveConfig(settings);
+    if (live && Object.keys(live.families).length) { cfg = live; source = `${br.baseUrl(settings)}/v1/models`; }
+    if (!cfg) {
+      const file = br.readConfig(settings, loc);
+      if ("config" in file) { cfg = file.config; source = file.path; }
+    }
+    if (!cfg) { cfg = br.FALLBACK_CONFIG; source = "built-in default ladder (no server, no bedrouter.json yet)"; }
+    const models = piModels(cfg, br.baseUrl(settings));
+    pi.registerProvider(settings.providerName, {
+      name: "bedrouter (Bedrock, routed)",
+      baseUrl: br.baseUrl(settings),
+      apiKey: process.env.BEDROUTER_API_KEY || "bedrouter",
+      api: "anthropic-messages",
+      models,
+    });
+    registeredModelIds = models.map((m) => m.id);
+    return `registered ${models.length} models from ${source}: ${registeredModelIds.join(", ")}`;
+  }
+
+  /** Locate → (install) → start → register. Returns a human summary. Never throws. */
+  async function bringUp(ctx: ExtensionContext | null, opts: { install?: boolean; start?: boolean } = {}): Promise<{ ok: boolean; lines: string[] }> {
+    const lines: string[] = [];
+    let loc = br.locate(settings);
+    if (!loc.found && opts.install) {
+      lines.push(`bedrouter not found (${loc.reason}); installing…`);
+      const r = br.install(settings);
+      lines.push(r.log.trim().split("\n").slice(-6).join("\n"));
+      loc = br.locate(settings);
+    }
+    if (!loc.found) { lines.push(`bedrouter is not installed: ${loc.reason}. Run /bedrouter install (or: ${loc.installCmd}).`); return { ok: false, lines }; }
+    if (!loc.cli && opts.install) {
+      lines.push(`bedrouter at ${loc.dir} is not built; building…`);
+      const r = br.install(settings);
+      lines.push(r.log.trim().split("\n").slice(-6).join("\n"));
+      loc = br.locate(settings);
+    }
+    lines.push(await registerProvider(loc as br.Found));
+    if (opts.start) {
+      const r = await br.start(settings, loc as br.Found);
+      for (const f of r.created) lines.push(`created ${f} from the example; edit it for this machine (AWS_PROFILE, ladder)`);
+      if (r.ok) lines.push(`bedrouter ${r.health.version} up on ${br.baseUrl(settings)} (pid ${r.health.pid}, region ${r.health.region}, classifier ${r.health.classifier ?? "off"})`);
+      else { lines.push(r.error); return { ok: false, lines }; }
+    }
+    return { ok: true, lines };
+  }
+
+  async function autoSelect(ctx: ExtensionContext) {
+    if (settings.autoSelect === false || !ctx.hasUI) return;
+    if (isOurs(ctx)) return;
+    const want = registeredModelIds.includes(settings.autoSelect) ? settings.autoSelect : registeredModelIds.find((id) => id.startsWith("auto")) ?? registeredModelIds[0];
+    if (!want) return;
+    const model = ctx.modelRegistry.find(settings.providerName, want);
+    if (!model) return;
+    const ok = await pi.setModel(model);
+    if (ok) notify(ctx, `bedrouter: model set to ${settings.providerName}/${want} (bedrouter picks the rung per request; /model to change)`);
+  }
+
+  // ---- startup -----------------------------------------------------------------------------------------------
+  // The factory is async, so pi waits for this: the provider exists for `pi --list-models` and `--provider bedrouter`
+  // whether or not the server or a checkout is present yet.
+  {
+    const loc = br.locate(settings);
+    await registerProvider(loc.found ? loc : null);
+  }
+
+  pi.on("session_start", async (ev, ctx) => {
+    lastCtx = ctx;
+    if (ev.reason !== "startup" && ev.reason !== "new") { if (isOurs(ctx)) setStatus(ctx, statusLine(last, stats)); return; }
+    last = null; stats = null;
+    const h = await br.health(settings);
+    serverUp = !!h?.ok;
+    if (!h?.ok && settings.autoStart) {
+      const r = await bringUp(ctx, { install: true, start: true });
+      serverUp = r.ok;
+      if (!r.ok) { notify(ctx, `bedrouter: ${r.lines[r.lines.length - 1]}`, "warning"); setStatus(ctx, "bedrouter: DOWN · /bedrouter start"); return; }
+      const created = r.lines.filter((l) => l.startsWith("created "));
+      if (created.length) notify(ctx, created.join("\n"), "warning");
+    } else if (!h?.ok) { setStatus(ctx, "bedrouter: DOWN · /bedrouter start"); return; }
+    await autoSelect(ctx);
+    if (isOurs(ctx)) setStatus(ctx, "bedrouter: ready");
+  });
+
+  pi.on("model_select", async (ev, ctx) => {
+    if (ev.model.provider === settings.providerName) setStatus(ctx, statusLine(last, stats));
+    else setStatus(ctx, undefined);
+  });
+
+  // ---- live routing display ------------------------------------------------------------------------------------
+  pi.on("after_provider_response", async (ev, ctx) => {
+    if (!isOurs(ctx)) return;
+    const d = fromHeaders(ev.headers ?? {});
+    if (!d) return;
+    last = d;
+    serverUp = true;
+    setStatus(ctx, statusLine(last, stats));
+  });
+
+  pi.on("agent_end", async (_ev, ctx) => {
+    if (!isOurs(ctx) || !last?.conversation) return;
+    stats = await br.conversation(settings, last.conversation);
+    setStatus(ctx, statusLine(last, stats));
+  });
+
+  // ---- background health poll ----------------------------------------------------------------------------------
+  // Pi only tells us about responses; a server that dies between turns would leave the footer saying "ready".
+  let poll: NodeJS.Timeout | null = null;
+  async function checkHealth() {
+    const ctx = lastCtx;
+    if (!ctx || !isOurs(ctx)) return;
+    const h = await br.health(settings);
+    const up = !!h?.ok;
+    if (up === serverUp) return;
+    serverUp = up;
+    if (up) { setStatus(ctx, readyText()); if (last) notify(ctx, "bedrouter: back up"); return; }
+    setStatus(ctx, "bedrouter: DOWN" + (settings.autoStart ? " · restarting…" : " · /bedrouter start"));
+    if (!settings.autoStart || Date.now() - restartAttemptAt < 60_000) return;
+    restartAttemptAt = Date.now();
+    // same path as startup: locate, build/install if needed, start
+    const r = await bringUp(ctx, { install: true, start: true });
+    serverUp = r.ok;
+    if (r.ok) { setStatus(ctx, readyText()); notify(ctx, `bedrouter: restarted`); }
+    else { setStatus(ctx, "bedrouter: DOWN · /bedrouter start"); notify(ctx, `bedrouter: restart failed — ${r.lines[r.lines.length - 1].split("\n")[0]}`, "warning"); }
+  }
+  if (settings.healthPollS > 0) { poll = setInterval(() => void checkHealth(), settings.healthPollS * 1000); poll.unref(); }
+
+  pi.on("session_shutdown", async () => { if (poll) clearInterval(poll); /* the server is left running on purpose: other Pi sessions share it */ });
+
+  // ---- /bedrouter ------------------------------------------------------------------------------------------------
+  const SUB = ["status", "start", "stop", "restart", "install", "doctor", "probe", "report", "log", "models", "fitnotes", "config", "help"];
+  pi.registerCommand("bedrouter", {
+    description: "bedrouter router: status | start | stop | restart | install | doctor | probe | report | log [n] | models | fitnotes | config",
+    getArgumentCompletions: (prefix) => SUB.filter((s) => s.startsWith(prefix.trim())).map((value) => ({ value, label: value })),
+    handler: async (args, ctx) => {
+      const [sub = "status", ...rest] = args.trim().split(/\s+/).filter(Boolean);
+      settings = loadSettings();
+      const located = br.locate(settings);
+      const loc: br.Found | null = located.found ? located : null;
+      const need = (): boolean => { if (!loc) notify(ctx, `bedrouter is not installed: ${(located as { reason: string }).reason}. Run /bedrouter install.`, "error"); return !!loc; };
+      switch (sub) {
+        case "status": {
+          const h = await br.health(settings);
+          const lines = [
+            loc ? `install: ${loc.dir} (${loc.source}, v${loc.version}${loc.cli ? "" : ", NOT BUILT"})` : `install: missing (${(located as { reason: string }).reason})`,
+            `home:    ${br.homeDir(settings)}`,
+            `server:  ${h?.ok ? `up on ${br.baseUrl(settings)}, pid ${h.pid}, v${h.version}, region ${h.region}, routing ${h.routing ? "on" : "off"}, classifier ${h.classifier ?? "off"}, up ${h.uptimeS}s` : `down (${br.baseUrl(settings)})`}`,
+            `provider: ${settings.providerName} → ${registeredModelIds.length ? registeredModelIds.join(", ") : "(not registered)"}`,
+            `session:  ${isOurs(ctx) ? `using ${ctx.model?.id}` : `not using bedrouter (model ${ctx.model?.provider}/${ctx.model?.id})`}`,
+            `last:     ${last ? `${last.requested} → ${last.model}  ${last.cls} · ${last.reason}${last.classifier ? `  classifier: ${last.classifier}` : ""}` : "-"}`,
+            `settings: ${settingsPath()}${fs.existsSync(settingsPath()) ? "" : " (defaults; /bedrouter config to create)"}`,
+          ];
+          show("bedrouter status", lines.join("\n"));
+          break;
+        }
+        case "start": case "restart": {
+          if (sub === "restart") notify(ctx, await br.stop(settings));
+          const r = await bringUp(ctx, { install: false, start: true });
+          show(`bedrouter ${sub}`, r.lines.join("\n"));
+          serverUp = r.ok;
+          if (r.ok) { await autoSelect(ctx); setStatus(ctx, isOurs(ctx) ? readyText() : undefined); }
+          break;
+        }
+        case "stop": notify(ctx, await br.stop(settings)); serverUp = false; setStatus(ctx, isOurs(ctx) ? "bedrouter: DOWN · /bedrouter start" : undefined); break;
+        case "install": {
+          notify(ctx, "bedrouter: installing/building (this can take a minute)…");
+          const r = await bringUp(ctx, { install: true, start: false });
+          show("bedrouter install", r.lines.join("\n"));
+          break;
+        }
+        case "doctor": case "probe": {
+          if (!need() || !loc) break;
+          if (sub === "probe") notify(ctx, "bedrouter: probing every rung with a 1-token request…");
+          const r = br.run(settings, loc, sub === "probe" ? ["doctor", "--probe"] : ["doctor"]);
+          show(`bedrouter ${sub}`, r.out);
+          break;
+        }
+        case "report": {
+          if (!need() || !loc) break;
+          const r = br.run(settings, loc, ["report", ...rest]);
+          show("bedrouter report", r.out);
+          break;
+        }
+        case "log": {
+          const n = Number(rest[0]) || 15;
+          const raw = br.tail(br.decisionLog(settings), n);
+          const lines = raw.split("\n").map((l) => { try { const j = JSON.parse(l); return `${j.ts.slice(11, 19)} ${String(j.requestedModel ?? "-").padEnd(12)} → ${String(j.routedModel ?? "-").padEnd(12)} ${String(j.class ?? "-").padEnd(7)} ${String(j.classReason ?? "-").padEnd(22)} ${j.outputTokens ?? "-"} out  ${j.costUsd != null ? "$" + j.costUsd.toFixed(5) : "-"}${j.escalated ? "  ↑" + j.escalationReason : ""}${j.error ? "  ✗ " + j.error : ""}`; } catch { return l; } });
+          show(`bedrouter log (last ${n})`, lines.join("\n") || "(empty)");
+          break;
+        }
+        case "models": {
+          show("bedrouter models", await registerProvider(loc));
+          break;
+        }
+        case "fitnotes": {
+          const file = br.readConfig(settings, loc);
+          const cfg = "config" in file ? file.config : (await br.liveConfig(settings)) ?? br.FALLBACK_CONFIG;
+          const notes = fitNotes(cfg, settings.providerName);
+          const wf = path.join(agentDir(), "workflows.json");
+          let cur: { models?: Record<string, string> } = {};
+          try { cur = JSON.parse(fs.readFileSync(wf, "utf8")); } catch { /* none */ }
+          const preview = Object.entries(notes).map(([k, v]) => `${k}: ${v}`).join("\n");
+          const ok = !ctx.hasUI || (await ctx.ui.confirm("Write pi-agents model notes?", `Merge these into ${wf} → models:\n\n${preview}`));
+          if (!ok) break;
+          fs.writeFileSync(wf, JSON.stringify({ ...cur, models: { ...(cur.models ?? {}), ...notes } }, null, 2) + "\n");
+          notify(ctx, `bedrouter: wrote ${Object.keys(notes).length} model notes to ${wf}`);
+          break;
+        }
+        case "config": {
+          if (!fs.existsSync(settingsPath())) saveSettings(settings);
+          show("bedrouter settings", `${settingsPath()}\n\n${fs.readFileSync(settingsPath(), "utf8")}\nKeys: path, home, port, autoStart, autoSelect (model id or false), debug, footer, providerName. Edit the file, then /reload.`);
+          break;
+        }
+        default:
+          show("bedrouter", `/bedrouter ${SUB.join(" | ")}\n\nstatus    install, server, provider, current model, last decision\nstart     start the server if needed (seeds .env / bedrouter.json on first run)\nstop      stop the server (shared by all Pi sessions)\ninstall   npm install / build the bedrouter dependency\ndoctor    credential source + loaded ladder;  probe: 1-token call per rung\nreport    savings report over the decision log (args pass through: --since, --json)\nlog [n]   last n routing decisions\nmodels    re-read bedrouter.json and re-register the provider\nfitnotes  write pi-agents model notes so the planner defaults to the router\nconfig    show/create ${settingsPath()}`);
+      }
+    },
+  });
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "pi-bedrouter",
+  "version": "0.1.0",
+  "description": "Pi extension for bedrouter: starts the cost-aware Bedrock model router, registers it as a provider, and shows which model served each request",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "bedrock",
+    "aws",
+    "model-router",
+    "cost",
+    "claude",
+    "gpt-oss"
+  ],
+  "license": "MIT",
+  "author": "Barry Melton",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bmelton/pi-bedrouter.git"
+  },
+  "homepage": "https://github.com/bmelton/pi-bedrouter#readme",
+  "bugs": {
+    "url": "https://github.com/bmelton/pi-bedrouter/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "files": [
+    "extensions",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "prepublishOnly": "npm test && npm run typecheck"
+  },
+  "dependencies": {
+    "bedrouter": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.85.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.85.0",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}

package/src/bedrouter.ts

@@ -0,0 +1,181 @@
+// Everything about the bedrouter process and its HTTP API: locate, install, start, stop, health, config, models.
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createRequire } from "node:module";
+import type { Settings } from "./settings.js";
+
+export type Health = { ok: boolean; region: string; pid: number; version: string; routing: boolean; classifier: string | null; uptimeS: number };
+export type ConversationStats = { key: string; requests: number; costUsd: number; requestedCostUsd: number; classifierCostUsd: number; inputTokens: number; outputTokens: number; escalations: number; class: string | null; routedModel: string | null; requestedModel: string | null; lastTs: string };
+export type Rung = { alias: string; bedrockId: string; inputPerM: number; outputPerM: number };
+export type BedrouterConfig = { families: Record<string, Rung[]>; aliases?: Record<string, string>; routing?: { enabled?: boolean; classes?: Record<string, Record<string, string>>; classifier?: { enabled?: boolean; model?: string } } };
+
+export type Found = { found: true; dir: string; cli: string | null; source: "settings.path" | "dependency"; version: string };
+export type Install = Found | { found: false; reason: string; installCmd: string };
+
+const require_ = createRequire(import.meta.url);
+
+/** Where bedrouter lives: settings.path if set, else the `bedrouter` npm dependency of this package. */
+export function locate(s: Settings): Install {
+  const candidates: { dir: string; source: "settings.path" | "dependency" }[] = [];
+  if (s.path) candidates.push({ dir: s.path, source: "settings.path" as const });
+  try { candidates.push({ dir: path.dirname(require_.resolve("bedrouter/package.json")), source: "dependency" as const }); } catch { /* not installed */ }
+  for (const c of candidates) {
+    const pkgPath = path.join(c.dir, "package.json");
+    if (!fs.existsSync(pkgPath)) continue;
+    let version = "?";
+    try { version = JSON.parse(fs.readFileSync(pkgPath, "utf8")).version ?? "?"; } catch { /* ignore */ }
+    const dist = path.join(c.dir, "dist", "cli.js");
+    const cli = fs.existsSync(dist) ? dist : null;
+    return { found: true, dir: c.dir, cli, source: c.source, version };
+  }
+  const here = path.dirname(path.dirname(new URL(import.meta.url).pathname));
+  return { found: false, reason: s.path ? `no package.json at ${s.path}` : "the bedrouter dependency is not installed", installCmd: `npm install --no-audit --no-fund --prefix "${here}"` };
+}
+
+/** Install the dependency (npm install in this package's directory) or build dist/ in a checkout. Returns the log. */
+export function install(s: Settings): { ok: boolean; log: string } {
+  const loc = locate(s);
+  const here = path.dirname(path.dirname(new URL(import.meta.url).pathname));
+  const cwd = loc.found ? loc.dir : here;
+  const args = loc.found ? ["run", "build"] : ["install", "--no-audit", "--no-fund"];
+  const r = spawnSync("npm", args, { cwd, encoding: "utf8", timeout: 300_000, env: { ...process.env, npm_config_loglevel: "error" } });
+  const log = `$ npm ${args.join(" ")}  (in ${cwd})\n${r.stdout ?? ""}${r.stderr ?? ""}`;
+  if (r.status === 0 && loc.found && !fs.existsSync(path.join(loc.dir, "dist", "cli.js"))) return { ok: false, log: log + "\nbuild produced no dist/cli.js" };
+  if (r.status === 0 && !loc.found) {
+    // a git dependency runs its own `prepare` (build) during npm install; make sure it did
+    const again = locate(s);
+    if (!again.found) return { ok: false, log: log + "\nbedrouter still not resolvable after install" };
+    if (!again.cli) return install(s); // installed but not built (e.g. prepare skipped): build it
+  }
+  return { ok: r.status === 0, log };
+}
+
+export const homeDir = (s: Settings) => s.home ?? s.path ?? path.join(os.homedir(), ".bedrouter");
+export const baseUrl = (s: Settings) => `http://127.0.0.1:${s.port}`;
+
+/** Make sure the working directory has .env and bedrouter.json, seeding from the package's examples. Returns what was created. */
+export function ensureHome(s: Settings, loc: Found): string[] {
+  const home = homeDir(s);
+  fs.mkdirSync(home, { recursive: true });
+  const created: string[] = [];
+  const seed = (name: string, example: string) => {
+    const dst = path.join(home, name), src = path.join(loc.dir, example);
+    if (!fs.existsSync(dst) && fs.existsSync(src)) { fs.copyFileSync(src, dst); created.push(dst); }
+  };
+  seed(".env", ".env.example");
+  seed("bedrouter.json", "bedrouter.example.json");
+  return created;
+}
+
+export function readConfig(s: Settings, loc: Found | null): { path: string; config: BedrouterConfig } | { path: string; error: string } {
+  const home = homeDir(s);
+  const candidates = [path.join(home, "bedrouter.json"), ...(loc ? [path.join(loc.dir, "bedrouter.json"), path.join(loc.dir, "bedrouter.example.json")] : [])];
+  const p = candidates.find((c) => fs.existsSync(c));
+  if (!p) return { path: candidates[0], error: "no bedrouter.json found" };
+  try { return { path: p, config: JSON.parse(fs.readFileSync(p, "utf8")) }; } catch (e) { return { path: p, error: (e as Error).message }; }
+}
+
+async function getJson<T>(url: string, timeoutMs = 1500): Promise<T | null> {
+  try {
+    const r = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!r.ok) return null;
+    return (await r.json()) as T;
+  } catch { return null; }
+}
+
+export const health = (s: Settings) => getJson<Health>(`${baseUrl(s)}/health`);
+
+/** Reconstruct a BedrouterConfig from a running server's /v1/models, so the provider can be registered with no local files. */
+export async function liveConfig(s: Settings): Promise<BedrouterConfig | null> {
+  type M = { id: string; bedrock_id: string; bedrouter?: { family: string; rung: string; auto: boolean; inputPerM: number; outputPerM: number } };
+  const r = await getJson<{ data: M[] }>(`${baseUrl(s)}/v1/models`);
+  if (!r?.data) return null;
+  const families: Record<string, Rung[]> = {};
+  const aliases: Record<string, string> = {};
+  for (const m of r.data) {
+    const b = m.bedrouter;
+    if (!b) continue;
+    if (b.auto) { aliases[m.id] = `auto:${b.family}`; continue; }
+    const fam = (families[b.family] ??= []);
+    if (m.id === b.rung) { if (!fam.some((x) => x.alias === b.rung)) fam.push({ alias: b.rung, bedrockId: m.bedrock_id, inputPerM: b.inputPerM, outputPerM: b.outputPerM }); }
+    else aliases[m.id] = b.rung;
+  }
+  // /v1/models is a map, so ladder order is lost; restore cheapest-first by input price (what bedrouter's ladders are)
+  for (const fam of Object.values(families)) fam.sort((a, b) => a.inputPerM - b.inputPerM);
+  return { families, aliases };
+}
+
+/** Last resort when neither a server nor a config file is available: the shipped example ladder. */
+export const FALLBACK_CONFIG: BedrouterConfig = {
+  families: {
+    anthropic: [
+      { alias: "haiku", bedrockId: "us.anthropic.claude-haiku-4-5-20251001-v1:0", inputPerM: 1.1, outputPerM: 5.5 },
+      { alias: "sonnet", bedrockId: "us.anthropic.claude-sonnet-5", inputPerM: 2.2, outputPerM: 11 },
+      { alias: "opus", bedrockId: "us.anthropic.claude-opus-5", inputPerM: 5.5, outputPerM: 27.5 },
+    ],
+    openai: [
+      { alias: "gpt-oss-20b", bedrockId: "openai.gpt-oss-20b-1:0", inputPerM: 0.07, outputPerM: 0.2 },
+      { alias: "gpt-oss-120b", bedrockId: "openai.gpt-oss-120b-1:0", inputPerM: 0.15, outputPerM: 0.6 },
+    ],
+  },
+  aliases: { auto: "auto:anthropic", "auto-oss": "auto:openai" },
+  routing: { classes: { anthropic: { trivial: "haiku", execute: "sonnet", explore: "opus" }, openai: { execute: "gpt-oss-20b", explore: "gpt-oss-120b" } } },
+};
+export const conversation = (s: Settings, key: string) => getJson<ConversationStats>(`${baseUrl(s)}/v1/conversations/${key}`);
+
+export const serverLog = (s: Settings) => path.join(homeDir(s), "server.log");
+export const decisionLog = (s: Settings) => path.join(homeDir(s), "bedrouter.log.jsonl");
+
+/** Start the server detached; stdout/stderr go to server.log in the home dir. Resolves with health, or the log tail on failure. */
+export async function start(s: Settings, locIn: Found): Promise<{ ok: true; health: Health; created: string[] } | { ok: false; error: string; created: string[] }> {
+  let loc = locIn;
+  const already = await health(s);
+  if (already?.ok) return { ok: true, health: already, created: [] };
+  const created = ensureHome(s, loc);
+  const home = homeDir(s);
+  if (!loc.cli) {
+    // not built yet (fresh checkout, or a dependency whose prepare step did not run): build once, then continue
+    const b = install(s);
+    const again = locate(s);
+    if (!b.ok || !again.found || !again.cli) return { ok: false, error: `bedrouter at ${loc.dir} has no dist/cli.js and the build failed:\n${b.log.trim().split("\n").slice(-8).join("\n")}`, created };
+    loc = again;
+  }
+  const out = fs.openSync(serverLog(s), "a");
+  fs.writeSync(out, `\n--- pi-bedrouter start ${new Date().toISOString()} ---\n`);
+  const cli: string = loc.cli!;
+  const child = spawn(process.execPath, [cli, "serve"], {
+    cwd: home, detached: true, stdio: ["ignore", out, out],
+    env: { ...process.env, PORT: String(s.port), BEDROUTER_DEBUG: s.debug ? "1" : process.env.BEDROUTER_DEBUG ?? "", BEDROUTER_LOG: decisionLog(s) },
+  });
+  child.unref();
+  fs.closeSync(out);
+  const deadline = Date.now() + 12_000;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 250));
+    const h = await health(s);
+    if (h?.ok) return { ok: true, health: h, created };
+    if (child.exitCode !== null) break;
+  }
+  return { ok: false, error: `bedrouter did not come up on ${baseUrl(s)}:\n${tail(serverLog(s), 12)}`, created };
+}
+
+export async function stop(s: Settings): Promise<string> {
+  const h = await health(s);
+  if (!h?.ok) return "bedrouter is not running";
+  try { process.kill(h.pid, "SIGTERM"); } catch (e) { return `could not signal pid ${h.pid}: ${(e as Error).message}`; }
+  for (let i = 0; i < 20; i++) { await new Promise((r) => setTimeout(r, 150)); if (!(await health(s))) return `stopped bedrouter (pid ${h.pid})`; }
+  return `sent SIGTERM to pid ${h.pid} but it is still answering; check ${serverLog(s)}`;
+}
+
+export function tail(file: string, n: number): string {
+  try { const lines = fs.readFileSync(file, "utf8").trimEnd().split("\n"); return lines.slice(-n).join("\n"); } catch { return `(no ${file})`; }
+}
+
+/** Run a bedrouter subcommand (doctor/report/smoke) in the home dir and capture its output. */
+export function run(s: Settings, loc: Found, args: string[], timeoutMs = 120_000): { code: number; out: string } {
+  if (!loc.cli) return { code: 1, out: "bedrouter is not built; run /bedrouter install" };
+  const r = spawnSync(process.execPath, [loc.cli, ...args], { cwd: homeDir(s), encoding: "utf8", timeout: timeoutMs, env: { ...process.env, PORT: String(s.port), BEDROUTER_LOG: decisionLog(s), FORCE_COLOR: "0" } });
+  return { code: r.status ?? 1, out: `${r.stdout ?? ""}${r.stderr ?? ""}`.trim() || (r.error ? String(r.error) : "") };
+}

package/src/footer.ts

@@ -0,0 +1,27 @@
+// Footer status text: what served the last request and how the session is doing on cost.
+import type { ConversationStats } from "./bedrouter.js";
+
+export type LastDecision = { model: string; requested: string; cls: string; reason: string; conversation?: string; classifier?: string };
+
+export function fromHeaders(h: Record<string, string>): LastDecision | null {
+  const get = (k: string) => h[k] ?? h[k.toLowerCase()] ?? (Object.entries(h).find(([kk]) => kk.toLowerCase() === k)?.[1]);
+  const model = get("x-bedrouter-model");
+  if (!model) return null;
+  return { model, requested: get("x-bedrouter-requested") ?? "?", cls: get("x-bedrouter-class") ?? "-", reason: get("x-bedrouter-reason") ?? "-", conversation: get("x-bedrouter-conversation"), classifier: get("x-bedrouter-classifier") };
+}
+
+const usd = (n: number) => (n >= 1 ? `$${n.toFixed(2)}` : `$${n.toFixed(4)}`);
+const short = (reason: string) => reason.replace(/^keyword:/, "kw:").replace(/^classifier:/, "clf:").replace(/^upgrade:keyword:/, "up:kw:").replace(/^shape:/, "");
+
+export function statusLine(d: LastDecision | null, c: ConversationStats | null): string {
+  if (!d) return "bedrouter: ready";
+  const arrow = d.model === d.requested ? "=" : "≠";
+  let s = `⇄ ${d.model} ${arrow} ${d.requested}  ${d.cls}·${short(d.reason)}`;
+  if (c && c.requests > 0) {
+    const spend = c.costUsd + c.classifierCostUsd;
+    const diff = c.requestedCostUsd - spend;
+    const pct = c.requestedCostUsd > 0 ? Math.round((diff / c.requestedCostUsd) * 100) : 0;
+    s += `  ${usd(spend)}${diff >= 0 ? ` saved ${usd(diff)} (${pct}%)` : ` +${usd(-diff)} over asked-for`}${c.escalations ? `  ↑${c.escalations}` : ""}`;
+  }
+  return s;
+}

package/src/models.ts

@@ -0,0 +1,50 @@
+// Turn bedrouter's config into Pi provider model definitions.
+import type { BedrouterConfig, Rung } from "./bedrouter.js";
+
+export type PiModel = {
+  id: string; name: string; api: "anthropic-messages" | "openai-completions"; baseUrl: string; reasoning: boolean;
+  input: ("text" | "image")[]; cost: { input: number; output: number; cacheRead: number; cacheWrite: number }; contextWindow: number; maxTokens: number;
+};
+
+const FAMILY: Record<string, { api: PiModel["api"]; path: string; input: PiModel["input"]; contextWindow: number; maxTokens: number }> = {
+  anthropic: { api: "anthropic-messages", path: "", input: ["text", "image"], contextWindow: 200_000, maxTokens: 64_000 },
+  openai: { api: "openai-completions", path: "/v1", input: ["text"], contextWindow: 128_000, maxTokens: 32_000 },
+};
+
+const cost = (r: Rung) => ({ input: r.inputPerM, output: r.outputPerM, cacheRead: +(r.inputPerM * 0.1).toFixed(4), cacheWrite: +(r.inputPerM * 1.25).toFixed(4) });
+
+/** `auto` aliases first (what most people should pick), then each family's rungs. Client aliases (claude-sonnet-5 → sonnet) are omitted to keep /model short. */
+export function piModels(cfg: BedrouterConfig, base: string): PiModel[] {
+  const out: PiModel[] = [];
+  for (const [alias, target] of Object.entries(cfg.aliases ?? {})) {
+    const m = /^auto:(\w+)$/.exec(target);
+    if (!m) continue;
+    const family = m[1], rungs = cfg.families[family], f = FAMILY[family];
+    if (!rungs?.length || !f) continue;
+    const exec = cfg.routing?.classes?.[family]?.execute;
+    const rep = rungs.find((r) => r.alias === exec) ?? rungs[0];
+    out.push({ id: alias, name: `Auto · ${family} ladder (${rungs.map((r) => r.alias).join(" → ")})`, api: f.api, baseUrl: base + f.path, reasoning: true, input: f.input, cost: cost(rep), contextWindow: f.contextWindow, maxTokens: f.maxTokens });
+  }
+  for (const [family, rungs] of Object.entries(cfg.families)) {
+    const f = FAMILY[family];
+    if (!f) continue;
+    for (const r of rungs) out.push({ id: r.alias, name: `${r.alias} · ${family} (${r.bedrockId})`, api: f.api, baseUrl: base + f.path, reasoning: true, input: f.input, cost: cost(r), contextWindow: f.contextWindow, maxTokens: f.maxTokens });
+  }
+  return out;
+}
+
+/** pi-agents "fit notes" (~/.pi/agent/workflows.json → models) so the planner prefers the router and never pins premium rungs by default. */
+export function fitNotes(cfg: BedrouterConfig, provider: string): Record<string, string> {
+  const notes: Record<string, string> = {};
+  for (const [alias, target] of Object.entries(cfg.aliases ?? {})) {
+    if (/^auto:/.test(target)) notes[`${provider}/${alias}`] = "default for every node: bedrouter picks the cheapest adequate model per request and escalates on failure";
+  }
+  for (const [family, rungs] of Object.entries(cfg.families)) {
+    const classes = cfg.routing?.classes?.[family] ?? {};
+    for (const r of rungs) {
+      const cls = Object.entries(classes).find(([, a]) => a === r.alias)?.[0];
+      notes[`${provider}/${r.alias}`] = cls === "explore" ? "pin only for planning, final review, reduces" : cls === "trivial" ? "pin only for titles, summaries, extraction" : cls === "execute" ? "pin only when a node must not be routed; ordinary implementation" : "pinned rung, bypasses routing";
+    }
+  }
+  return notes;
+}

package/src/settings.ts

@@ -0,0 +1,48 @@
+// pi-bedrouter settings: ~/.pi/agent/pi-bedrouter.json (all keys optional).
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export type Settings = {
+  /** Path to a bedrouter checkout or install. Default: the `bedrouter` package this extension depends on. */
+  path?: string;
+  /** Working directory for the server: holds .env, bedrouter.json, bedrouter.log.jsonl, server.log. Default: `path` when set, else ~/.bedrouter. */
+  home?: string;
+  /** Port to run/expect bedrouter on. */
+  port: number;
+  /** Start the server on session start when it is not running. */
+  autoStart: boolean;
+  /** Model id (from bedrouter's aliases, e.g. "auto" or "auto-oss") to switch the session to when bedrouter is healthy; false to leave the model alone. */
+  autoSelect: string | false;
+  /** Start the server with BEDROUTER_DEBUG=1 (per-request trace in server.log). */
+  debug: boolean;
+  /** Show the routing status line in Pi's footer. */
+  footer: boolean;
+  /** Provider name registered in Pi. */
+  providerName: string;
+  /** Seconds between background health checks that keep the footer honest and restart a dead server (0 disables). */
+  healthPollS: number;
+};
+
+export const DEFAULTS: Settings = { port: 20129, autoStart: true, autoSelect: "auto", debug: false, footer: true, providerName: "bedrouter", healthPollS: 15 };
+
+export const agentDir = () => process.env.PI_CODING_AGENT_DIR ?? path.join(os.homedir(), ".pi", "agent");
+export const settingsPath = () => path.join(agentDir(), "pi-bedrouter.json");
+const expand = (p: string) => p.replace(/^~(?=$|\/)/, os.homedir());
+
+export function loadSettings(): Settings {
+  let user: Partial<Settings> = {};
+  try { user = JSON.parse(fs.readFileSync(settingsPath(), "utf8")); } catch { /* none yet */ }
+  const s: Settings = { ...DEFAULTS, ...user };
+  if (s.path) s.path = expand(s.path);
+  if (s.home) s.home = expand(s.home);
+  if (process.env.BEDROUTER_PORT) s.port = Number(process.env.BEDROUTER_PORT);
+  return s;
+}
+
+export function saveSettings(s: Partial<Settings>): void {
+  fs.mkdirSync(agentDir(), { recursive: true });
+  let cur: Partial<Settings> = {};
+  try { cur = JSON.parse(fs.readFileSync(settingsPath(), "utf8")); } catch { /* none */ }
+  fs.writeFileSync(settingsPath(), JSON.stringify({ ...cur, ...s }, null, 2) + "\n");
+}