@workweave/router 0.1.8 → 0.2.0

package/install.sh

@@ -1,35 +1,42 @@
 #!/usr/bin/env bash
 #
-# Weave Router installer for Claude Code, Codex, and opencode.
+# Weave Router installer for Claude Code, Codex, opencode, and pi.
 #
-# Configures Claude Code (default), the OpenAI Codex CLI (`--codex`), or
-# opencode (`--opencode`) to permanently route through the Weave Router.
-# For Claude Code this writes the router base URL, router auth header,
-# and a status line into Claude Code's settings.json. For Codex it writes
-# a `model_providers.weave` entry plus `model_provider = "weave"` into
+# Configures Claude Code (default), the OpenAI Codex CLI (`--codex`),
+# opencode (`--opencode`), or pi (`--pi`) to permanently route through the
+# Weave Router. For Claude Code this writes the router base URL, router auth
+# header, and a status line into Claude Code's settings.json. For Codex it
+# writes a `model_providers.weave` entry plus `model_provider = "weave"` into
 # ~/.codex/config.toml (managed block delimited by markers). For opencode
 # it merges a `provider.weave` block (anthropic-compatible) into
 # opencode.json — since the file is JSON, install/uninstall are structural
-# (jq) rather than marker-delimited.
+# (jq) rather than marker-delimited. For pi it merges a `weave` provider into
+# ~/.pi/agent/models.json, sets it as the default in settings.json, and adds
+# the @workweave/router extension (which also adds a parallel subagent
+# `dispatch` tool) — all structural (jq) merges.
 #
 # Two scopes (apply to all targets):
 #   - user (default):  ~/.claude/settings.json  + ~/.weave/cc-statusline.sh
 #                      ~/.codex/config.toml                       (with --codex)
 #                      ~/.config/opencode/opencode.json           (with --opencode)
+#                      ~/.pi/agent/{models,settings}.json         (with --pi)
 #   - project:         <repo>/.claude/settings.json + <repo>/.claude/cc-statusline.sh
 #                      <repo>/.codex/config.toml                  (with --codex)
 #                      <repo>/opencode.json                       (with --opencode)
+#                      <repo>/.pi/ (run: PI_CODING_AGENT_DIR=<repo>/.pi pi)  (with --pi)
 #
 # Or pass --dir to install into any directory:
 #   - dir:              <dir>/.claude/settings.json + <dir>/.claude/cc-statusline.sh
 #                       <dir>/.codex/config.toml                  (with --codex)
 #                       <dir>/opencode.json                       (with --opencode)
+#                       <dir>/.pi/ (run: PI_CODING_AGENT_DIR=<dir>/.pi pi)   (with --pi)
 #
 # Usage:
 #   npx @workweave/router                                  # interactive picker (Claude Code, Codex, opencode)
 #   npx @workweave/router --claude                         # skip the picker, target Claude Code
 #   npx @workweave/router --codex                          # skip the picker, target the OpenAI Codex CLI
 #   npx @workweave/router --opencode                       # skip the picker, target opencode
+#   npx @workweave/router --pi                              # skip the picker, target pi
 #   npx @workweave/router --scope project                  # commit-with-team install
 #   npx @workweave/router --dir /tmp/my-sandbox            # isolated throwaway install
 #   npx @workweave/router --local                          # local router on localhost:8080
@@ -124,6 +131,7 @@ uninstall_cmd() {
   case "$target" in
     codex)    cmd="$cmd --codex" ;;
     opencode) cmd="$cmd --opencode" ;;
+    pi)       cmd="$cmd --pi" ;;
   esac
   [ "$scope" = "project" ] && cmd="$cmd --scope project"
   [ -n "$install_dir" ] && cmd="$cmd --dir $(printf '%q' "$install_dir")"
@@ -149,6 +157,7 @@ print_banner() {
   case "$target" in
     codex)    target_label="Codex installer" ;;
     opencode) target_label="opencode installer" ;;
+    pi)       target_label="pi installer" ;;
     *)        target_label="Claude Code installer" ;;
   esac
   printf '\n'
@@ -567,6 +576,12 @@ write_opencode_config() {
   # a startup error before the router ever sees a request. The router itself
   # ignores the value (auth runs off X-Weave-Router-Key); apiKey here is just
   # a placeholder that satisfies the SDK's "is auth configured" check.
+  # baseURL KEEPS its /v1 here — do NOT align it with the pi block, which is
+  # root. opencode's @ai-sdk/anthropic (Vercel) appends only /messages to
+  # baseURL (its default is api.anthropic.com/v1), so /v1 yields the correct
+  # /v1/messages. Dropping it would hit /messages and 404. (pi uses the official
+  # @anthropic-ai/sdk, which appends /v1/messages to a root baseURL — opposite
+  # convention.) Verified by install/pi-router/test/opencode_smoke.sh.
   local block
   block="$(jq -n \
     --arg url "$block_url/v1" \
@@ -611,6 +626,117 @@ write_opencode_config() {
   chmod 600 "$config_file"
 }
 
+# write_pi_models_config merges a managed `weave` provider into pi's
+# models.json (anthropic-compatible — the router speaks Anthropic Messages
+# natively). The header set carries identity plus the main-loop routing knobs
+# (quality bias); the @workweave/router extension re-registers the provider
+# per process to flip those knobs for subagents/compaction. apiKey is the
+# router key as well as a header — pi treats apiKey as required to consider auth
+# configured, but the router authenticates off X-Weave-Router-Key
+# (authHeader:false keeps Authorization free for BYOK). Re-running rewrites
+# `.providers.weave` in place; uninstall strips it. chmod 600 — holds the key.
+#
+# Usage: write_pi_models_config <models_file> <base_url> <api_key> [user_email] [user_name]
+write_pi_models_config() {
+  local config_file="$1"
+  local block_url="$2"
+  local block_key="$3"
+  local block_email="${4:-}"
+  local block_name="${5:-}"
+
+  # Identity + the main-loop (quality) routing knobs. Built piecewise so an
+  # empty email/name vanishes from the JSON entirely.
+  local headers_json
+  headers_json="$(jq -n \
+    --arg key   "$block_key" \
+    --arg email "$block_email" \
+    --arg name  "$block_name" '
+    {
+      "X-Weave-Router-Key": $key,
+      "X-App": "pi",
+      "x-weave-routing-marker": "off",
+      "x-weave-routing-alpha": "0.8",
+      "x-weave-routing-speed-weight": "0.05",
+      "x-weave-routing-output-cost-ratio": "0.5",
+      "x-weave-routing-expected-output-tokens": "3000"
+    }
+    | (if $email != "" then . + {"X-Weave-User-Email": $email} else . end)
+    | (if $name  != "" then . + {"X-Weave-User-Name":  $name } else . end)
+  ')"
+
+  # Headline models surfaced in pi's /model picker. The router re-routes every
+  # request regardless, so this list is UX; keep it Anthropic-shaped and in
+  # sync with @workweave/router's WEAVE_MODELS constant.
+  #
+  # baseUrl is the router ROOT (no /v1): pi's anthropic-messages provider uses
+  # @anthropic-ai/sdk, which appends /v1/messages itself. Unlike the codex block
+  # above (OpenAI-style, base ends in /v1), a /v1 suffix here would produce
+  # /v1/v1/messages and 404.
+  local block
+  block="$(jq -n \
+    --arg url "$block_url" \
+    --arg key "$block_key" \
+    --argjson headers "$headers_json" '
+    {
+      baseUrl: $url,
+      api: "anthropic-messages",
+      apiKey: $key,
+      authHeader: false,
+      headers: $headers,
+      models: [
+        { id: "claude-opus-4-8",   name: "Claude Opus 4.8 (via Weave Router)",   reasoning: true, input: ["text","image"], contextWindow: 200000, maxTokens: 64000 },
+        { id: "claude-opus-4-7",   name: "Claude Opus 4.7 (via Weave Router)",   reasoning: true, input: ["text","image"], contextWindow: 200000, maxTokens: 64000 },
+        { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6 (via Weave Router)", reasoning: true, input: ["text","image"], contextWindow: 200000, maxTokens: 64000 },
+        { id: "claude-haiku-4-5",  name: "Claude Haiku 4.5 (via Weave Router)",  reasoning: true, input: ["text","image"], contextWindow: 200000, maxTokens: 32000 }
+      ]
+    }
+  ')"
+
+  # Overwrite provider.weave only; leave any other providers/models the user
+  # added untouched.
+  local merged
+  if [ -f "$config_file" ]; then
+    merged="$(jq --argjson block "$block" '.providers = ((.providers // {}) | .weave = $block)' "$config_file")"
+  else
+    merged="$(jq -n --argjson block "$block" '{ providers: { weave: $block } }')"
+  fi
+  printf '%s\n' "$merged" >"$config_file"
+  # 0600: the headers + apiKey hold the router key.
+  chmod 600 "$config_file"
+}
+
+# write_pi_settings_config makes the `weave` provider pi's default and loads the
+# @workweave/router extension. defaultProvider/defaultModel are set only when
+# unset (don't clobber a user's pick); the npm package source is appended to
+# `packages` idempotently — pi auto-installs missing packages on startup, so the
+# source entry is enough — and the legacy `npm:@workweave/pi-router` id (from
+# before the extension was folded into @workweave/router) is dropped so a config
+# from the old layout can't keep a dangling/duplicate entry. No secret lives
+# here, so no chmod 600.
+#
+# Usage: write_pi_settings_config <settings_file>
+write_pi_settings_config() {
+  local settings_file="$1"
+  local pkg="npm:@workweave/router"
+  local merged
+  if [ -f "$settings_file" ]; then
+    merged="$(jq --arg pkg "$pkg" '
+      (.packages //= [])
+      | (.packages -= ["npm:@workweave/pi-router"])
+      | (if (.packages | index($pkg)) then . else .packages += [$pkg] end)
+      | (if (.defaultProvider // "") == "" then .defaultProvider = "weave" else . end)
+      | (if (.defaultModel // "") == "" then .defaultModel = "claude-sonnet-4-6" else . end)
+    ' "$settings_file")"
+  else
+    merged="$(jq -n --arg pkg "$pkg" '{
+      defaultProvider: "weave",
+      defaultModel: "claude-sonnet-4-6",
+      packages: [$pkg]
+    }')"
+  fi
+  printf '%s\n' "$merged" >"$settings_file"
+}
+
 # resolve_user_name mirrors resolve_user_email but for display name. Priority:
 # WEAVE_USER_NAME env override → git config user.name → empty. We don't
 # prompt for name independently: if email prompting yielded nothing, name
@@ -716,6 +842,9 @@ while [ $# -gt 0 ]; do
     --opencode)
       target="opencode"; target_explicit="true"; shift
       ;;
+    --pi)
+      target="pi"; target_explicit="true"; shift
+      ;;
     --claude)
       # No-op selector for symmetry with --codex / --opencode. Useful in
       # pipelines that want to skip the interactive picker without depending
@@ -747,6 +876,14 @@ if [ "$mode" != "install" ]; then
   fi
 fi
 
+# Toggle verbs (off/on/status) aren't implemented for pi — its config is a
+# structural models.json/settings.json merge, reversed by the uninstaller
+# rather than a single env/key line we can park and restore.
+if [ "$mode" != "install" ] && [ "$target" = "pi" ]; then
+  err "toggle verbs (off/on/status) aren't supported for --pi. Use 'npx @workweave/router --uninstall --pi' to remove, or re-run the installer to refresh."
+  exit 2
+fi
+
 if [ -z "$base_url" ]; then
   base_url="$DEFAULT_BASE_URL"
 fi
@@ -766,12 +903,14 @@ if [ "$target_explicit" = "false" ] && [ "$non_interactive" = "false" ] && [ -r
   printf "  %s1)%s Claude Code  %s— patches ~/.claude/settings.json (or <repo>/.claude/)%s\n" "$C_BRAND" "$C_RESET" "$C_DIM" "$C_RESET"
   printf "  %s2)%s Codex        %s— patches ~/.codex/config.toml (or <repo>/.codex/)%s\n" "$C_BRAND" "$C_RESET" "$C_DIM" "$C_RESET"
   printf "  %s3)%s opencode     %s— patches ~/.config/opencode/opencode.json (or <repo>/opencode.json)%s\n" "$C_BRAND" "$C_RESET" "$C_DIM" "$C_RESET"
-  printf "Choose %s[1/2/3]%s (default %s1%s): " "$C_BOLD" "$C_RESET" "$C_BOLD" "$C_RESET"
+  printf "  %s4)%s pi           %s— patches ~/.pi/agent/models.json + settings.json (or <repo>/.pi/)%s\n" "$C_BRAND" "$C_RESET" "$C_DIM" "$C_RESET"
+  printf "Choose %s[1/2/3/4]%s (default %s1%s): " "$C_BOLD" "$C_RESET" "$C_BOLD" "$C_RESET"
   read -r target_choice </dev/tty || target_choice=""
   case "${target_choice:-1}" in
     1|""|claude|c|C)  target="claude" ;;
     2|codex|x|X)      target="codex" ;;
     3|opencode|o|O)   target="opencode" ;;
+    4|pi|p|P)         target="pi" ;;
     *) err "invalid choice: $target_choice"; exit 2 ;;
   esac
 fi
@@ -809,6 +948,11 @@ if [ -z "$install_dir" ] && [ "$scope_explicit" = "false" ] && [ "$non_interacti
       scope_project_path="<repo>/opencode.json"
       scope_cli_label="opencode"
       ;;
+    pi)
+      scope_user_path="~/.pi/agent/"
+      scope_project_path="<repo>/.pi/"
+      scope_cli_label="pi"
+      ;;
     *)
       scope_user_path="~/.claude/"
       scope_project_path="<repo>/.claude/"
@@ -859,7 +1003,7 @@ fi
 # Claude Code's settings.json and opencode's opencode.json patching both use
 # jq to deep-merge / structurally rewrite JSON. Toggling those clients reads
 # and rewrites the same JSON, so jq is required there too.
-if [ "$target" = "claude" ] || [ "$target" = "opencode" ]; then
+if [ "$target" = "claude" ] || [ "$target" = "opencode" ] || [ "$target" = "pi" ]; then
   require_cmd jq    "macOS: 'brew install jq' · Debian/Ubuntu: 'sudo apt install jq'"
 fi
 # curl is only used by the install path's health/validate probes; toggles never
@@ -885,6 +1029,12 @@ case "$target" in
       warn "Continuing — opencode.json will be written and will take effect once opencode is installed."
     fi
     ;;
+  pi)
+    if ! command -v pi >/dev/null 2>&1; then
+      warn "'pi' not found on PATH. Install with 'npm install -g @mariozechner/pi-coding-agent', then re-run this script."
+      warn "Continuing — models.json/settings.json will be written and take effect once pi is installed."
+    fi
+    ;;
 esac
 
 script_dir="$(cd "$(dirname "$0")" 2>/dev/null && pwd || true)"
@@ -970,6 +1120,31 @@ elif [ "$target" = "codex" ]; then
   fi
 
   mkdir -p "$codex_dir"
+elif [ "$target" = "pi" ]; then
+  # pi reads ~/.pi/agent/ by default, so a plain `pi` picks up a user-scope
+  # install with no env var. models.json is global-only in pi (there is no
+  # project-level models file), so for project/--dir scope we point
+  # PI_CODING_AGENT_DIR at a repo-local .pi that holds the whole config
+  # (models.json + settings.json + key) — the same shape as Codex's CODEX_HOME.
+  # The router key is embedded, so .pi goes in .gitignore for project scope.
+  case "$scope" in
+    user)    pi_dir="$settings_base/.pi/agent" ;;
+    project) pi_dir="$settings_base/.pi" ;;
+  esac
+  # --dir is a self-contained sandbox: flat .pi, launched via PI_CODING_AGENT_DIR.
+  [ -n "$install_dir" ] && pi_dir="$install_dir/.pi"
+  pi_models_file="$pi_dir/models.json"
+  pi_settings_file="$pi_dir/settings.json"
+  pi_key_file="$pi_dir/.weave_router_key"
+
+  if [ "$scope" = "project" ] || [ -n "$install_dir" ]; then
+    refuse_if_symlink "$pi_dir"
+    refuse_if_symlink "$pi_models_file"
+    refuse_if_symlink "$pi_settings_file"
+    refuse_if_symlink "$pi_key_file"
+  fi
+
+  mkdir -p "$pi_dir"
 else
   # opencode discovers config in this order: $XDG_CONFIG_HOME/opencode/opencode.json
   # (or ~/.config/opencode/opencode.json) for user scope, and opencode.json /
@@ -1581,6 +1756,74 @@ if [ "$target" = "opencode" ]; then
   exit 0
 fi
 
+# ---------- pi install path (dispatch + exit before the Claude-only writes) ----------
+
+if [ "$target" = "pi" ]; then
+  write_pi_models_config "$pi_models_file" "$base_url" "$api_key" "$user_email" "$user_name"
+  ok "pi models config written to $pi_models_file"
+  write_pi_settings_config "$pi_settings_file"
+  ok "pi settings written to $pi_settings_file (provider weave + @workweave/router)"
+
+  if [ -n "$api_key" ]; then
+    printf '%s\n' "$api_key" >"$pi_key_file"
+    chmod 600 "$pi_key_file"
+    ok "Router key written to $pi_key_file"
+  fi
+
+  # Project scope: the repo-local .pi carries the router key, so keep it out of
+  # git. Same reasoning as the Codex/opencode paths — base URL is shared, the
+  # key is per-person.
+  if [ "$scope" = "project" ] && [ -z "$install_dir" ] && [ -n "${git_root:-}" ]; then
+    # Write the .gitignore in the directory that CONTAINS .pi (the chosen project
+    # dir), not the git root: gitignore entries with a slash are anchored to the
+    # .gitignore's own location, so a root-level ".pi/models.json" would NOT match
+    # a nested <subdir>/.pi/ — leaking the router key. dirname "$pi_dir" == the
+    # project dir (== git root when they're the same).
+    gitignore="$(dirname "$pi_dir")/.gitignore"
+    refuse_if_symlink "$gitignore"
+    for entry in \
+      ".pi/models.json" \
+      ".pi/settings.json" \
+      ".pi/.weave_router_key"
+    do
+      if [ ! -f "$gitignore" ] || ! grep -qxF "$entry" "$gitignore"; then
+        printf '%s\n' "$entry" >>"$gitignore"
+      fi
+    done
+    ok "Updated $gitignore (ignored repo-local .pi router config)"
+  fi
+
+  # Post-install verification: same probes the Claude/Codex/opencode paths run.
+  if [ "$quiet" != "true" ]; then
+    if ! spin "Pinging $base_url/health" curl -fsS --max-time 5 "$base_url/health"; then
+      warn "Could not reach $base_url/health within 5s. Settings are written; verify the router is running."
+    fi
+  fi
+
+  if [ -n "$api_key" ]; then
+    validate_pi_key() {
+      printf '%s: %s\n' "$router_key_header" "$api_key" \
+        | curl -fsS --max-time 5 --header @- "$base_url/validate"
+    }
+    if ! spin "Validating API key" validate_pi_key; then
+      warn "Router rejected the API key (check it matches the dashboard at $base_url/ui/)."
+    fi
+  fi
+
+  printf "\n"
+  printf "%s✓%s %s%sWeave Router installed for pi.%s\n" \
+    "$C_GREEN" "$C_RESET" "$C_BOLD" "$C_BRAND" "$C_RESET"
+  # Billing note: pi normally draws on a Claude subscription (OAuth); routing
+  # through the router switches to per-token billing on the router deployment
+  # key (or BYOK). Surface it at install so the change isn't a surprise.
+  info "pi now bills per token on the Weave Router key, not your Claude subscription."
+  if [ "$scope" = "project" ] || [ -n "$install_dir" ]; then
+    info "Run pi with PI_CODING_AGENT_DIR=$pi_dir pi so it picks up this config."
+  fi
+  print_uninstall_hint
+  exit 0
+fi
+
 # ---------- write the statusline script ----------
 
 cat > "$statusline_file" << 'STATUSLINE_EOF'

package/package.json

@@ -1,16 +1,22 @@
 {
   "name": "@workweave/router",
-  "version": "0.1.8",
-  "description": "One-command installer that points Claude Code at the Weave Router.",
+  "version": "0.2.0",
+  "description": "One-command installer that points Claude Code, Codex, opencode, or pi at the Weave Router. For pi it also ships the routing extension, loaded via pi.extensions.",
   "bin": {
     "weave-router": "bin.js"
   },
+  "pi": {
+    "extensions": [
+      "./pi-router/src/index.ts"
+    ]
+  },
   "files": [
     "bin.js",
     "install.sh",
     "uninstall.sh",
     "cc-statusline.sh",
     "commands/",
+    "pi-router/",
     "README.md",
     "LICENSE"
   ],
@@ -20,6 +26,20 @@
   "engines": {
     "node": ">=18"
   },
+  "peerDependencies": {
+    "@mariozechner/pi-agent-core": "*",
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@mariozechner/pi-agent-core": { "optional": true },
+    "@mariozechner/pi-ai": { "optional": true },
+    "@mariozechner/pi-coding-agent": { "optional": true },
+    "@mariozechner/pi-tui": { "optional": true },
+    "typebox": { "optional": true }
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/workweave/router.git",
@@ -33,6 +53,8 @@
     "claude",
     "claude-code",
     "anthropic",
-    "llm-router"
+    "llm-router",
+    "pi",
+    "pi-package"
   ]
 }

package/pi-router/README.md

@@ -0,0 +1,70 @@
+# Weave Router pi extension
+
+> Bundled inside the [`@workweave/router`](https://www.npmjs.com/package/@workweave/router) package — not published separately. `src/` here is the source of truth; `npm run prepack` copies it into the package.
+
+A [pi](https://pi.dev) extension that routes every request through the
+[WorkWeave Router](https://github.com/workweave/router) — a trained, per-request
+LLM proxy that picks the most cost-efficient model that still solves each task.
+
+Installed automatically by the Weave Router installer:
+
+```bash
+WEAVE_ROUTER_KEY=rk_… npx -y @workweave/router --pi          # user scope
+WEAVE_ROUTER_KEY=rk_… npx -y @workweave/router --pi --local  # local router (http://localhost:8080)
+```
+
+That writes `~/.pi/agent/models.json` (the `weave` provider), adds
+`npm:@workweave/router` to `~/.pi/agent/settings.json` `packages`, and stores
+the key in `~/.pi/agent/.weave_router_key`. pi auto-installs `@workweave/router`
+from npm on next start and loads this extension via its `pi.extensions` field.
+
+## What it does
+
+- **Automatic model selection.** All pi traffic flows through the router, which
+  selects the model per request. You don't pick a model — the router does.
+- **Per-process routing bias.** Static `x-weave-routing-*` knob headers bias the
+  router: quality on the main loop, speed + cheap on subagents, cheapest on
+  compaction.
+- **Sticky sessions.** `metadata.user_id = "pi:<sessionId>"` pins the main loop
+  to one model for the session; subagents get their own pins.
+- **`dispatch` tool — parallel, context-isolated subagents.** pi has none
+  natively. `dispatch` spawns child `pi` processes (read-only by default), runs
+  them concurrently, and returns only each subagent's final answer — intermediate
+  tool output stays in the child, so the main context stays small.
+- **Routed-model display.** Shows the model the router actually chose
+  (`x-router-model`) in the status bar, and opts the request out of the router's
+  in-band routing badge (`X-Weave-Routing-Marker: off`) — pi can't render that
+  separate marker text block inline, and the status bar already conveys the model.
+- **Safety backstop.** Blocks a few catastrophic shell commands (`rm -rf /`,
+  `mkfs`, `dd of=/dev/…`, fork bombs, force-push to main). Disable with
+  `WEAVE_NO_SAFETY=1`.
+
+## Configuration (environment)
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `WEAVE_ROUTER_URL` | `http://localhost:8080` | Router base URL (children inherit it) |
+| `WEAVE_ROUTER_KEY` | — | Router key (else read from `.weave_router_key`) |
+| `WEAVE_ROUTER_KEY_FILE` | `<agentDir>/.weave_router_key` | Override key file path |
+| `WEAVE_USER_EMAIL` / `WEAVE_USER_NAME` | from `git config` | Identity headers for attribution |
+| `WEAVE_PI_SUBAGENT_MODEL` | `claude-sonnet-4-6` | `weave/<model>` handle children launch with (router re-routes) |
+| `WEAVE_PI_DISPATCH_CONCURRENCY` | `4` | Max concurrent subagents |
+| `WEAVE_PI_SUBAGENT_TIMEOUT_MS` | `600000` | Per-subagent timeout |
+| `WEAVE_PI_ALLOW_SUBAGENT_TOOLS` | unset | `1` lets `dispatch` grant subagents write/exec tools (bash, write, edit); default strips them |
+| `WEAVE_ROUTING_ALPHA` / `…_SPEED_WEIGHT` / `…_OUTPUT_COST_RATIO` / `…_EXPECTED_OUTPUT_TOKENS` | role preset | Override individual routing knobs (main process only — children always use their role preset) |
+| `WEAVE_NO_SAFETY` | unset | `1` disables the catastrophic-bash gate |
+| `WEAVE_CHEAP_COMPACTION` | unset | `1` enables the (experimental) cheap-compaction path |
+
+Internal: `WEAVE_PI_SUBAGENT=1` and `WEAVE_PI_SUBAGENT_ID` are set by `dispatch`
+on child processes; don't set them yourself.
+
+## Billing
+
+Routing through the router switches pi from Claude **subscription OAuth** to
+**per-token** billing on the router deployment's key (or your BYOK key). BYOK
+skips cross-provider failover; deployment-key billing is the default.
+
+## Notes
+
+- Cheap compaction is currently a reserved flag — the handler defers to pi's
+  built-in compaction until the router-routed path is validated end-to-end.

package/pi-router/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@workweave/router-pi-extension",
+  "private": true,
+  "type": "module",
+  "description": "The pi routing extension bundled into @workweave/router. NOT published separately: src/ is copied into the @workweave/router package at prepack and loaded via that package's pi.extensions. This manifest just marks the sources as ESM and declares the pi peer deps for local typecheck.",
+  "peerDependencies": {
+    "@mariozechner/pi-agent-core": "*",
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "typebox": "*"
+  }
+}

package/pi-router/src/compaction.ts

@@ -0,0 +1,26 @@
+/**
+ * EXPERIMENTAL, off by default (enable with WEAVE_CHEAP_COMPACTION=1).
+ *
+ * Intent: run context compaction through the cheapest routing knobs. The
+ * catch is that compaction bypasses provider hooks and reuses the session's
+ * static provider headers (the main loop's quality knobs), and
+ * `session_before_compact` is the only per-turn lever. Producing a fully
+ * router-routed cheap CompactionResult here is not yet validated, so this
+ * handler currently defers to pi's built-in compaction (returns no override)
+ * and only reserves the flag + surfaces that it's active. Promote to a real
+ * cheap path once validated end-to-end.
+ */
+
+import type { ExtensionAPI, ExtensionContext, SessionBeforeCompactEvent } from "@mariozechner/pi-coding-agent";
+
+export function registerCheapCompaction(pi: ExtensionAPI): void {
+	let announced = false;
+	pi.on("session_before_compact", (_event: SessionBeforeCompactEvent, ctx: ExtensionContext) => {
+		if (ctx.hasUI && !announced) {
+			announced = true;
+			ctx.ui.setStatus("weave-compaction", "cheap compaction: experimental (using built-in)");
+		}
+		// Defer to built-in compaction until the router-routed cheap path is validated.
+		return undefined;
+	});
+}