pi-bifrost-gateway 0.0.0-stage → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions respect
+[SemVer](https://semver.org/).
+
+## [0.3.0] — 2026-10-18
+
+### Changed
+
+- **BREAKING** `publishChains` now defaults to `false`. Chains mode fails
+  discovery loud when no usable routing rules exist — the conservative
+  default publishes only the upstream catalog and needs no governance.
+  Installs that want chain models set `publishChains: true` explicitly.
+
+### Added
+
+- Member-catalog-only mode: with `publishChains: false`, discovery uses the
+  inference plane alone (`GET /v1/models`) — no management-API access — so
+  the full upstream catalogue publishes against a stock gateway with
+  governance disabled entirely. Previously discovery required chains and
+  management access unconditionally.
+- `nativeProtocols` config (`responses` / `messages` toggles, both default
+  `false`): publish matching models as `openai-responses` /
+  `anthropic-messages` so claude-family and gpt-family chains talk their
+  native wire end to end through a gateway that serves the Responses API
+  and the Anthropic integration route. Optional `responsesModels` /
+  `messagesModels` exact-name lists replace the built-in family heuristic
+  for that surface.
+- `managementApiKey` config: separate bearer for the management plane
+  (`/api/governance/*`, `/api/routing/rules`), for deployments whose
+  management API does not accept the inference virtual key. Defaults to the
+  VK; virtual-key self-identification always matches the inference
+  credential regardless.
+
+### Fixed
+
+- History scrub: no personal paths anywhere in the repository tree or git
+  history.
+
+## [0.2.0] — never published
+
+Prepared (files whitelist, repository/engines metadata, install docs) but
+superseded by 0.3.0 before release; the version number was never occupied on
+the registry.
+
+## [0.1.0] — 2026-10-08 (unpublished same day)
+
+Initial release: chain models from VK routing rules, upstream member
+catalog, `/login bifrost`, `/bifrost` status command, one-time
+`gateway` → `bifrost` credential migration. Unpublished shortly after
+release because its default gateway URL baked in a private address; replaced
+by config/env-only URL resolution before any later publish.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael MacLeod
+
+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

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+# pi-bifrost-gateway
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pi extension for a [Bifrost](https://github.com/maximhq/bifrost) LLM gateway:
+publishes the gateway's models as first-class pi models — chain models from
+the VK's routing rules, the full upstream model catalogue, or both — instead
+of a hand-maintained `models.json` block. Optional per-family native
+protocol surfaces let OpenAI-family models speak the Responses API and
+Anthropic-family models speak Messages end to end.
+
+Companion-package note: this is the management-API flavor (governance-aware:
+virtual-key discovery and routing-rule chains). It fills the same provider
+slot as [lxdlam/pi-bifrost-provider](https://github.com/lxdlam/pi-bifrost-provider)
+(standalone-instance flavor) — install one OR the other, not both.
+
+## Install
+
+From npm:
+
+```sh
+pi install npm:pi-bifrost-gateway
+```
+
+Or from a local checkout:
+
+```sh
+pi install ~/repos/pi-bifrost-gateway
+```
+
+Then configure it (`~/.pi/agent/pi-bifrost-gateway.json`) — there is **no
+built-in gateway URL**, so an unconfigured install registers zero models:
+
+```json
+{
+  "baseUrl": "https://your-bifrost.example/v1",
+  "publishChains": true,
+  "publishUpstream": false
+}
+```
+
+Auth: `/login bifrost` (stores the virtual key AND the gateway URL on the
+credential in `auth.json` — sufficient on its own) or the `BIFROST_API_KEY`
+env var.
+
+## How it works
+
+Two publishing modes, selectable independently:
+
+**Chains mode** (`publishChains: true`) — requires a gateway with
+chains-first routing rules. `fetchModels` (runs on startup, `/model`,
+`/reload`, `/login`) does, live:
+
+1. `GET /v1/models` (your VK Bearer) — member catalog with per-member pricing
+   and context windows.
+2. `GET /api/governance/virtual-keys` — matches your stored credential value
+   to discover which virtual key you are (the rule filter's `scope_id`).
+3. `GET /api/routing/rules?scope=virtual_key&scope_id=<vk>` — the VK's chain
+   rules; CEL `model == "x"` pairs give chain names, targets + `fallbacks[]`
+   give member ids.
+
+From that it emits one pi model per chain (`bifrost/<chain>`, e.g.
+`bifrost/glm-5.3-flash`), with `contextWindow` = min member window. A rules
+set with no usable chains fails discovery loud.
+
+**Member-only mode** (`publishChains: false`, the default) — the inference
+plane alone: one `GET /v1/models` and the **full upstream catalogue** is
+published as direct-selectable models (`provider/model`, e.g.
+`hyper/glm-5.3-flash`) with real per-member pricing and context windows. No
+management-API access at all, so it works against a stock gateway with
+governance disabled entirely. Both modes can be combined (`publishChains:
+true` + `publishUpstream: true`) — chains first, then the catalogue.
+
+In both modes, `nativeProtocols` (see Configuration) can switch matching
+model families from chat completions to their native wire — `openai-responses`
+for the gpt family, `anthropic-messages` for the claude family — so the
+client protocol matches what your gateway/upstream speaks.
+
+## Auth
+
+`/login bifrost` prompts for **both** the gateway URL and the virtual key and
+stores them together on the credential in `auth.json` (URL in the
+credential's `BIFROST_URL` env slot) — after login no config file is needed.
+Alternatively set `baseUrl` via config/`BIFROST_BASE_URL` env and `/login`
+with the URL left blank to keep that ambient resolution.
+
+URL precedence: login-stored credential URL → config-file `baseUrl` →
+`BIFROST_BASE_URL` env. Key: stored credential → `BIFROST_API_KEY` env.
+A stored credential under the legacy `gateway` provider id is migrated to
+`bifrost` on load; re-running `/login bifrost` upgrades an old key-only
+credential to carry its URL.
+
+## Configuration
+
+`~/.pi/agent/pi-bifrost-gateway.json` (all keys optional). Defaults are
+CONSERVATIVE — `publishChains` false, chat completions everywhere:
+
+```json
+{
+  "publishChains": true,
+  "publishUpstream": true,
+  "nativeProtocols": { "responses": true, "messages": true }
+}
+```
+
+- `publishChains` (default **false**): emit the `bifrost/<chain>` models
+  from the VK's routing rules. Requires a gateway with chains-first
+  routing rules for the credential's VK; a rules set without usable
+  chains fails discovery loud. Leave it off (the default) for a stock
+  gateway — member-only mode needs no governance at all.
+- `publishUpstream: false` hides the direct-selectable upstream catalog
+  (`hyper/glm-5.3-flash`, `pareto/glm-5.3-flash`, …) with real per-member
+  pricing. `publishMembers` is accepted as a legacy alias.
+- `baseUrl` (optional) gateway `/v1` URL; then env `BIFROST_BASE_URL`. There
+  is NO built-in default URL: with neither set (and no URL stored by
+  `/login bifrost`), the plugin registers zero models.
+- `managementApiKey` (optional) bearer for the management plane
+  (`/api/governance/virtual-keys`, `/api/routing/rules`). Defaults to the
+  inference credential (the VK) — correct for dashboard-auth-disabled
+  deployments that accept the VK on `/api/*`. Set it when the management
+  plane expects a different credential than inference. The VK-value match
+  (VK self-identification) always uses the INFERENCE credential, never
+  this key.
+- `nativeProtocols` (optional; both toggles default **false**) selects the
+  client wire per model family:
+  - `responses: true` — models matching the built-in [OI]-native family
+    heuristic (`gpt-*` except `gpt-oss*`, `o<n>`, `codex*`) publish as
+    `openai-responses`. Requires a gateway serving `POST /v1/responses`.
+  - `messages: true` — models matching the built-in Anthropic family
+    heuristic (`claude-*` in the NAME) publish as `anthropic-messages`,
+    pointed at the gateway's `/anthropic` integration route. Requires a
+    gateway with the Anthropic integration prefix registered.
+  - `responsesModels` / `messagesModels` (optional arrays of exact bare
+    model names, e.g. `["gpt-6-luna"]`): when set, the list REPLACES the
+    built-in heuristic for that surface — list membership is the only path
+    to the native wire. Name matching is case-insensitive, last path
+    segment (the serving prefix never decides).
+  - Both off (default): every model publishes chat completions — the only
+    wire every Bifrost serves; the gateway translates at the boundary.
+
+## Cost
+
+Chain models carry **zero** cost by design: pi recomputes cost from catalog
+rates and cannot know which member actually served a chain request. Bifrost
+`/api/logs` (cost + cost_breakdown per request) remains the system of record.
+Upstream catalogue models carry real `$/Mtok` rates from `/v1/models`.
+
+## Commands
+
+`/bifrost` — auth, baseUrl, config, and loaded-model status.

package/package.json

@@ -1,6 +1,57 @@
 {
-  "name": "pi-bifrost-gateway",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "pi-bifrost-gateway",
+	"version": "0.3.0",
+	"description": "Pi extension for a Bifrost LLM gateway: chain models from VK routing rules and/or the full upstream model catalogue, with optional per-family native protocol surfaces",
+	"license": "MIT",
+	"keywords": [
+		"pi-package"
+	],
+	"type": "module",
+	"pi": {
+		"extensions": [
+			"./src/index.ts"
+		]
+	},
+	"scripts": {
+		"test": "vitest run",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"typebox": "*"
+	},
+	"peerDependenciesMeta": {
+		"@earendil-works/pi-ai": {
+			"optional": false
+		},
+		"@earendil-works/pi-coding-agent": {
+			"optional": false
+		},
+		"typebox": {
+			"optional": false
+		}
+	},
+	"devDependencies": {
+		"@earendil-works/pi-ai": "^1.0.4",
+		"@earendil-works/pi-coding-agent": "^1.0.4",
+		"@types/node": "^24.0.0",
+		"typebox": "^1.3.36",
+		"typescript": "^6.0.3",
+		"vitest": "^5.0.3"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE",
+		"CHANGELOG.md"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/MacLeodMike/pi-bifrost-gateway.git"
+	},
+	"engines": {
+		"node": ">=22"
+	}
+}

package/src/bifrost.ts

@@ -0,0 +1,31 @@
+/** Gateway constants: model id / endpoints. */
+
+export const PROVIDER_ID = "bifrost";
+export const PROVIDER_DISPLAY_NAME = "Bifrost Gateway";
+
+/** Different relative to the configured /v1 base URL. */
+export const INFERENCE_PATH_MODELS = "models";
+
+/**
+ * No built-in default URL. The gateway address comes from /login (stored on
+ * the credential), the config file, or BIFROST_BASE_URL env. An install in
+ * none of those states must resolve to zero models (no network), never to a
+ * baked-in deployment address that would silently route another user's
+ * inference through a gateway they don't own.
+ */
+
+/**
+ * Neutral createProvider-shape baseUrl used before a URL exists from any
+ * source above. NEVER requested: every published model carries its own
+ * discovery-time baseUrl, and discovery resolves the URL from
+ * credential-env → config → env before any fetch. An install in this state
+ * publishes zero models.
+ */
+export const UNRESOLVED_BASE_URL = "http://localhost:8080/v1";
+
+/** Management API paths (2026-10-08 live-verified on Bifrost v2.2.x). */
+export const MANAGEMENT_PATH_VIRTUAL_KEYS = "/api/governance/virtual-keys";
+export const MANAGEMENT_PATH_ROUTING_RULES = "/api/routing/rules";
+
+/** Auth: env var for the virtual keys value; /login bifrost is the fallback. */
+export const AUTH_ENV_KEYS = ["BIFROST_API_KEY"] as const;