@velocirouter/pi 1.0.0

package/README.md

@@ -0,0 +1,51 @@
+# @velocirouter/pi
+
+[Pi](https://pi.dev) package for [VelociRouter](https://velocirouter.site).
+It registers VelociRouter as a provider and loads the model catalog from the
+API.
+
+Requires **Pi 0.85.1 or later** from `@earendil-works/pi-coding-agent`.
+The older `@mariozechner/pi-coding-agent` distribution does not support this
+package's catalog refresh. Upgrade Pi before installing the package:
+
+```bash
+npm uninstall -g @mariozechner/pi-coding-agent
+npm install -g @earendil-works/pi-coding-agent@latest
+pi install npm:@velocirouter/pi
+```
+
+Then run `/login` inside pi, pick **VelociRouter**, and paste your `rt-…` key.
+Pi refreshes the catalog right after login, so the models show up in `/model`
+straight away.
+
+## What it registers
+
+- **Provider** — `velocirouter`, an `openai-completions` endpoint.
+- **Login** — pi's built-in API-key login under `/login`.
+- **Models** — fetched from `/v1/models` and cached in pi's model store, so new
+  models appear without upgrading this package. Image support and the
+  reasoning-effort ladder come from the API; levels a model does not support
+  are hidden from pi's thinking picker. The context window is the API's
+  combined window minus the output reservation: pi compacts once accumulated
+  tokens pass it, and those tokens are the next request's input, so the
+  combined figure would let a long session overshoot the input ceiling.
+
+Costs are reported as zero: VelociRouter bills your account directly, so pi's
+per-session cost estimate would double-count.
+
+The catalog is fetched when an interactive session starts, after `/login`, and
+from the `/model` picker. `pi -p` and `pi --list-models` read the cached copy,
+so open pi interactively once before using them.
+
+## Environment variables
+
+| Variable | Effect |
+| --- | --- |
+| `VELOCIROUTER_API_KEY` | Used when no key was stored by `/login`. Set this in CI. |
+| `VELOCIROUTER_BASE_URL` | Override the API host (default `https://api.velocirouter.site`). |
+
+## Publishing
+
+```bash
+npm publish --access public
+```

package/index.js

@@ -0,0 +1,86 @@
+const PROVIDER = "velocirouter"
+const API = "openai-completions"
+const DEFAULT_BASE_URL = "https://api.velocirouter.site"
+const DEFAULT_CONTEXT_WINDOW = 128_000
+const NO_COST = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }
+const THINKING_LEVELS = ["minimal", "low", "medium", "high", "xhigh", "max"]
+
+function baseUrl() {
+  const configured = process.env.VELOCIROUTER_BASE_URL || DEFAULT_BASE_URL
+  return `${configured.trim().replace(/\/+$/, "")}/v1`
+}
+
+async function getJson(url, apiKey, signal) {
+  const response = await fetch(url, {
+    headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}` },
+    signal,
+  })
+  if (!response.ok) {
+    throw new Error(`VelociRouter returned HTTP ${response.status} for ${url}`)
+  }
+  return response.json()
+}
+
+// pi hides xhigh/max unless mapped and treats null as unsupported. The relay
+// spells thinking-off as "none", which pi only sends when `off` is mapped.
+function thinkingLevelMap(efforts) {
+  const supported = new Set(efforts)
+  const map = Object.fromEntries(THINKING_LEVELS.map((level) => [level, supported.has(level) ? level : null]))
+  map.off = supported.has("none") ? "none" : null
+  return map
+}
+
+function toModel(row) {
+  const totalWindow = row.context_length || row.context_window || DEFAULT_CONTEXT_WINDOW
+  const maxTokens = row.max_output_tokens || Math.min(totalWindow, DEFAULT_CONTEXT_WINDOW)
+  const efforts = row.reasoning_efforts ?? []
+  const input = (row.input_modalities ?? []).filter((modality) => modality === "text" || modality === "image")
+  return {
+    id: row.id,
+    name: row.display_name || row.id,
+    reasoning: Boolean(row.reasoning),
+    ...(row.reasoning && efforts.length ? { thinkingLevelMap: thinkingLevelMap(efforts) } : {}),
+    input: input.length ? input : ["text"],
+    cost: { ...NO_COST },
+    // pi compacts once accumulated tokens pass contextWindow, and those tokens
+    // are the next request's input. The API reports the combined window, so
+    // reserve the output share or a long session overshoots the input ceiling.
+    contextWindow: totalWindow > maxTokens ? totalWindow - maxTokens : totalWindow,
+    maxTokens,
+  }
+}
+
+// Stored models carry the baseUrl they were fetched from; dropping it lets
+// the provider-level one win when VELOCIROUTER_BASE_URL changes.
+function restore(stored) {
+  return stored?.models.filter((model) => model.provider === PROVIDER).map(({ baseUrl, ...model }) => model)
+}
+
+async function refreshModels({ credential, stored, publish, allowNetwork, signal }) {
+  if (!allowNetwork || !credential?.key) {
+    return restore(stored)
+  }
+  const payload = await getJson(`${baseUrl()}/models`, credential.key, signal)
+  const rows = Array.isArray(payload?.data) ? payload.data : []
+  const models = rows.filter((row) => typeof row?.id === "string" && row.id).map(toModel)
+  // An empty catalog would wipe the cache; keep what was there.
+  if (!models.length) {
+    return restore(stored)
+  }
+  const persisted = models.map((model) => ({ ...model, api: API, provider: PROVIDER, baseUrl: baseUrl() }))
+  await publish({ persist: { models: persisted, checkedAt: Date.now() } })
+  return models
+}
+
+export default function velocirouter(pi) {
+  pi.registerProvider(PROVIDER, {
+    name: "VelociRouter",
+    baseUrl: baseUrl(),
+    api: API,
+    apiKey: "$VELOCIROUTER_API_KEY",
+    // pi's User-Agent is "pi (linux ...)", so the relay cannot identify the
+    // app without these.
+    headers: { "HTTP-Referer": "https://pi.dev", "X-Title": "Pi" },
+    refreshModels,
+  })
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@velocirouter/pi",
+  "version": "1.0.0",
+  "description": "Pi coding agent package for VelociRouter — registers the provider and its model catalog.",
+  "type": "module",
+  "main": "index.js",
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "pi": {
+    "extensions": [
+      "index.js"
+    ]
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "velocirouter"
+  ],
+  "homepage": "https://velocirouter.site/docs/coding-agents/pi"
+}