@sigrun/provider-bifrost 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-18
+### Changed
+- Renamed to `@sigrun/provider-bifrost` for the 0.1.0 release (GitHub
+  repo `sigrun-ai/sigrun-provider-bifrost`): published package metadata
+  (`publishConfig` access/provenance), host modules
+  (`@earendil-works/pi-ai`, `@earendil-works/pi-durable`, `typebox`)
+  moved to `peerDependencies` mirrored in `devDependencies` at exact
+  pins, CHANGELOG.md joined the files whitelist, and a manifest hygiene
+  check wired into `npm test`. The contributor identity follows the
+  package slug: the factory result's `name` becomes `provider-bifrost`
+  and the scoped settings file `settings/provider-bifrost.json` (the
+  loader pre-keys the two-phase host from the package name; a stale
+  declared name would split the factory-time settings scope).
+### Added
+- Sigrun provider plugin for a Bifrost LLM gateway, ported from
+  pi-bifrost-gateway 0.3.0 (`5d15a28`): provider-only contributor
+  (`{ name: "provider-bifrost", providers: [{ provider, readiness }],
+  health }`), `provider: "bifrost"` stamped on every published model so
+  persisted catalogs survive cold-boot restore.
+- Two discovery modes: member-only (default, `publishChains: false` —
+  single `/v1/models` fetch, ZERO management-plane calls, stock-gateway
+  compatible) and chains (`publishChains: true` — VK self-identification
+  via `/api/governance/virtual-keys` + chain rules via
+  `/api/routing/rules`, chains published as `bifrost/<chain>` with
+  min-member context windows and cost 0).
+- Scoped-settings configuration (`settings/provider-bifrost.json`), read
+  once at factory time (restart-required): `baseUrl`, `publishChains`
+  (default false), `publishUpstream` (default true),
+  `managementApiKey`, `thinkingOverrides`, `nativeProtocols`
+  (`responses`/`messages` toggles + exact-name lists replacing the
+  built-in family heuristic; both default false — chat completions
+  everywhere). No /login flow.
+- Native protocol surfaces ported exactly: model NAME decides the family
+  (never the serving prefix); claude → `anthropic-messages` at
+  `<gateway-root>/anthropic` with the `forceAdaptiveThinking` pin and
+  `off: null` ladder; gpt(?!-oss)/o\d/codex → `openai-responses` with
+  `off: "none"`; everything else chat completions with `off: "off"`.
+- TEXT_ONLY denylist ported (glm-5.3, deepseek-v4-flash/pro + snapshot
+  ids; exact bare-name matching so vision-capable siblings keep image
+  input).
+- Credentials through sigrun's auth.json bridge with `BIFROST_API_KEY`
+  as the ambient fallback; base URL settings-first with
+  `BIFROST_BASE_URL` ambient fallback (env reads via the injected seam,
+  never `process.env`).
+- `fetchModels` throws on unconfigured / VK mismatch / zero chains /
+  both-flags-off / discovery failure — never returns `[]` (an empty
+  array would publish and wipe the persisted catalog).
+- Three-state readiness tracker (`not_configured` / `degraded` /
+  `ready`) seeded from credential resolution and updated per refresh
+  outcome; `console.warn` on state transitions only. `health()` maps
+  `not_configured` to `"ok"` and configured-and-failing to `"degraded"`.

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,152 @@
-# Temporary Holding Version
+# @sigrun/provider-bifrost
 
-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.
+A [sigrun](https://github.com/sigrun-ai) provider plugin: a
+[Bifrost](https://github.com/maximhq/bifrost) LLM gateway as one dynamic
+chat provider. Ported from
+[pi-bifrost-gateway](https://github.com/MacLeodMike/pi-bifrost-gateway)
+0.3.0 (`5d15a28`). All failover, key selection, and routing happens in
+Bifrost — this plugin never routes anything itself.
+
+## What it contributes
+
+A **provider-only contributor** — the default export is a factory
+returning `{ name: "provider-bifrost", providers: [{ provider, readiness }],
+health }` with no pi-durable extension surface. Sigrun's loader merges
+the provider into its `Models` store at boot.
+
+- **Provider** `bifrost` — dynamic catalog over `openai-completions`
+  (plus optional per-family native surfaces, below). Two discovery
+  modes, picked by the settings `publishChains` flag:
+  - **member-only mode (default, `publishChains: false`)** — a single
+    `GET <base>/models` with the virtual key, publishing every upstream
+    as a direct-selectable `provider/model` entry with real per-member
+    rates. **Zero management-plane calls** — works against a stock
+    gateway with governance disabled entirely.
+  - **chains mode (`publishChains: true`)** — the management plane is
+    queried too: the VK self-identifies against
+    `/api/governance/virtual-keys` (the credential value matched to VK
+    rows), then `/api/routing/rules?scope=virtual_key&scope_id=<vk>`
+    yields the chain rules; every usable chain publishes as
+    `bifrost/<chain>` (min-member context window, cost 0 by design —
+    the gateway's own `/api/logs` is the billing system of record),
+    optionally followed by the upstream catalog (`publishUpstream`,
+    default true).
+- **Readiness** (`not_configured` / `degraded` / `ready`, surfaced on
+  sigrun's `/v1/auth/check`) — seeded from credential resolution and
+  updated per refresh outcome; state transitions log via `console.warn`
+  (transitions only, never per failure).
+- **Health** — `degraded` only when the provider is configured and its
+  last refresh failed; an unconfigured optional plugin reports `ok`.
+
+## Settings
+
+Read **once at factory time** from the plugin's scoped settings —
+`settings/provider-bifrost.json` in the sigrun config dir — and **baked
+into the provider**; applying a change requires a restart (sigrun's
+loader pre-keys the factory host on the provisional slug, so the
+factory-time read resolves this file). Absent file = defaults.
+Wrong-typed values and unknown keys warn and fall back — never fatal.
+
+```jsonc
+// settings/provider-bifrost.json
+{
+	"baseUrl": "https://your-bifrost.example/v1", // settings wins, then BIFROST_BASE_URL
+	"publishChains": false,   // chains mode when true (needs management plane)
+	"publishUpstream": true,  // upstream catalog entries (both modes)
+	"managementApiKey": "…",  // /api/* bearer; falls back to the VK
+	"thinkingOverrides": {    // per-member ladders keyed "provider/model";
+		"acme/model-x": ["low", "high"] // replaces the full default ladder
+	},
+	"nativeProtocols": {      // both default false = chat completions everywhere
+		"responses": true,   // gpt-family → openai-responses
+		"messages": true,    // claude-family → anthropic-messages at <root>/anthropic
+		"responsesModels": ["gpt-6-luna"], // exact-name lists REPLACE the heuristic
+		"messagesModels": ["claude-sonnet-5-5"]
+	}
+}
+```
+
+**Plaintext caveat:** this settings file is plain JSON — it has none of
+`auth.json`'s `0600` discipline. That is consistent with sigrun's
+operator-provisioned-plaintext posture: `managementApiKey` is
+provisioned by the operator into the config dir exactly like
+`settings.json` itself, and anything needing secret-handling semantics
+belongs in the VK (`auth.json` / `BIFROST_API_KEY`) instead — the
+management plane deliberately falls back to the VK when no separate key
+is set.
+
+### Native protocol surfaces
+
+With both `nativeProtocols` toggles off (the default), every model
+publishes chat completions — the only wire every Bifrost serves. With a
+toggle on, the model **NAME** (never the serving prefix) picks the
+wire: `claude-*` → `anthropic-messages` at `<gateway-root>/anthropic`
+(the Anthropic SDK appends `/v1/messages` itself), `gpt(?!-oss)`/`o\d`/
+`codex` → `openai-responses` on the `/v1` base, everything else —
+including `gpt-oss`, an open-weight model — stays completions. Setting
+the paired exact-name list replaces the built-in heuristic for that
+surface. Per-surface thinking-compat pins ship as in the pi port
+(`off: null` + `forceAdaptiveThinking` on anthropic, `off: "none"` on
+responses, `off: "off"` on completions).
+
+## Credentials
+
+Resolved per request through sigrun's auth.json bridge, falling back to
+the ambient environment:
+
+1. the bridged auth.json credential (`"default"` entry, then the
+   `"bifrost"` entry), then
+2. `BIFROST_API_KEY`.
+
+The base URL resolves settings-`baseUrl` first, then the ambient
+`BIFROST_BASE_URL`. Both env reads go through sigrun's env seam — the
+plugin never reads auth.json or `process.env` itself. There is **no
+/login flow** (the pi port's interactive login has no sigrun analog);
+rotating the key or the env URL applies on the next resolution — no
+restart. Settings changes DO need a restart (baked at factory time).
+
+`managementApiKey` comes from scoped settings only and is used as the
+bearer on `/api/*` (VK lookup + routing rules); the inference catalog
+always uses the VK itself. When unset, the VK serves the management
+plane too — the right shape for dashboard-auth-disabled deployments.
+
+## Failure semantics
+
+`fetchModels` **throws** — it never returns an empty array, which pi-ai
+would publish and persist, wiping the catalog — on: unconfigured (no
+key or no base URL), a credential matching no VK (chains mode), zero
+usable chain rules (chains mode), both publish flags off, and any
+discovery failure (unreachable gateway, schema mismatch). A failed
+refresh retains the previous catalog and records a per-provider error;
+the provider still boots unconfigured with an empty baseline catalog
+and `not_configured` readiness.
+
+## Install
+
+```jsonc
+// settings.json (sigrun config dir) — the UNIFIED extensions list:
+// install + load in one place; npm and git specifiers are the same list
+// npm ("@sigrun/provider-bifrost@^0.1.0"), git
+// ("git:github.com/sigrun-ai/sigrun-provider-bifrost", or any
+// https git URL with an optional @ref), or the file: form below.
+{
+	"extensions": ["file:/path/to/sigrun-bifrost"]
+}
+```
+
+The committed `dist/` is the load target for git installs; pi-ai and
+pi-durable are peerDependencies (sigrun supplies them at runtime);
+they are mirrored in devDependencies for this repo's own build and tests.
+
+## Development
+
+```sh
+npm install        # also builds dist/ via prepare
+npm test           # vitest — hermetic fixture gateway server, no network
+npm run typecheck
+npm run build
+```
+
+## License
+
+MIT

package/dist/catalog.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Catalog composition (ported from pi-bifrost-gateway 0.3.0 @ 5d15a28,
+ * `src/catalog.ts` + the constants of its `src/bifrost.ts`): wire schemas
+ * and fetching, chain decoding from routing-rule CELs, native-family
+ * surface selection, TEXT_ONLY denylist scoping, and the pure model
+ * builders. Every published model is stamped `provider: "bifrost"` —
+ * pi-ai's restore path drops stored models whose `provider` differs from
+ * the registered id, so an unstamped catalog silently vanishes on cold
+ * boot (restore-filter spike, Review Focus #3).
+ */
+import type { Model } from "@earendil-works/pi-ai";
+import { Type } from "@earendil-works/pi-ai";
+import { type FetchJsonOptions } from "./http.js";
+import type { NativeProtocols } from "./config.js";
+/** The provider id models are registered (and stamped) under. */
+export declare const PROVIDER_ID = "bifrost";
+export declare const PROVIDER_DISPLAY_NAME = "Bifrost Gateway";
+/** Different relative to the configured /v1 base URL. */
+export declare const INFERENCE_PATH_MODELS = "models";
+/** Management API paths (live-verified on Bifrost v2.2.x, 2026-10-08). */
+export declare const MANAGEMENT_PATH_VIRTUAL_KEYS = "/api/governance/virtual-keys";
+export declare const MANAGEMENT_PATH_ROUTING_RULES = "/api/routing/rules";
+/**
+ * Neutral createProvider-shape baseUrl used before a URL exists from any
+ * source. NEVER requested: every published model carries its own
+ * discovery-time baseUrl, and discovery refuses to run without a real URL
+ * (unconfigured throws). An install in this state publishes zero models.
+ */
+export declare const UNRESOLVED_BASE_URL = "http://localhost:8080/v1";
+/** Model apis this plugin publishes, keyed to pi-ai's registered implementations. */
+export type SurfaceApi = "openai-completions" | "openai-responses" | "anthropic-messages";
+export type GatewayModel = Model<"openai-completions"> | Model<"openai-responses"> | Model<"anthropic-messages">;
+/**
+ * Which native wire a model NAME speaks (pi-inferhub nativeFamily, ported).
+ * BUILT-IN heuristic — the user-facing gates live in settings
+ * (nativeProtocols.responses/messages toggles, plus exact-name lists that
+ * replace this heuristic when set). Family of the model NAME (last path
+ * segment), never the serving prefix: the live catalog has `kiro/` serving
+ * both claude-* and gpt-* rows. `gpt-oss` is an open-weight model, not an
+ * [OI] native one, so it stays other; `o\d` catches o3/o4-style rows,
+ * `codex` the codex family.
+ */
+export type NativeFamily = "anthropic" | "openai" | "other";
+export declare function nativeFamily(id: string): NativeFamily;
+/**
+ * Client wire + base URL for one model id, per settings:
+ * - nativeProtocols.messages on + (name in messagesModels list, or built-in
+ *   claude heuristic when no list) → anthropic-messages at the gateway's
+ *   /anthropic integration prefix (pi-ai's Anthropic SDK appends /v1/messages
+ *   itself; x-api-key VK auth verified live).
+ * - nativeProtocols.responses on + (responsesModels list, or built-in gpt
+ *   heuristic) → openai-responses on the /v1 base.
+ * - otherwise openai-completions — the only wire every Bifrost serves, and
+ *   the gateway translates at the boundary anyway.
+ */
+export declare function surfaceFor(id: string, baseUrl: string, native?: NativeProtocols): {
+    api: SurfaceApi;
+    baseUrl: string;
+};
+export declare const CatalogModelSchema: Type.TObject<{
+    id: Type.TString;
+    owned_by: Type.TOptional<Type.TString>;
+    context_length: Type.TOptional<Type.TNumber>;
+    max_output_limit: Type.TOptional<Type.TNumber>;
+    pricing: Type.TOptional<Type.TObject<{
+        prompt: Type.TString;
+        completion: Type.TString;
+        input_cache_read: Type.TOptional<Type.TString>;
+        input_cache_write: Type.TOptional<Type.TString>;
+    }>>;
+}>;
+export declare const ModelsEnvelopeSchema: Type.TObject<{
+    data: Type.TArray<Type.TObject<{
+        id: Type.TString;
+        owned_by: Type.TOptional<Type.TString>;
+        context_length: Type.TOptional<Type.TNumber>;
+        max_output_limit: Type.TOptional<Type.TNumber>;
+        pricing: Type.TOptional<Type.TObject<{
+            prompt: Type.TString;
+            completion: Type.TString;
+            input_cache_read: Type.TOptional<Type.TString>;
+            input_cache_write: Type.TOptional<Type.TString>;
+        }>>;
+    }>>;
+}>;
+export declare const RoutingTargetSchema: Type.TObject<{
+    provider: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+    model: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+    weight: Type.TNumber;
+}>;
+export declare const RoutingRuleSchema: Type.TObject<{
+    id: Type.TString;
+    name: Type.TString;
+    enabled: Type.TOptional<Type.TBoolean>;
+    cel_expression: Type.TString;
+    targets: Type.TArray<Type.TObject<{
+        provider: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+        model: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+        weight: Type.TNumber;
+    }>>;
+    fallbacks: Type.TOptional<Type.TArray<Type.TString>>;
+    scope: Type.TString;
+    scope_id: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+    priority: Type.TOptional<Type.TNumber>;
+}>;
+export declare const RulesEnvelopeSchema: Type.TObject<{
+    rules: Type.TArray<Type.TObject<{
+        id: Type.TString;
+        name: Type.TString;
+        enabled: Type.TOptional<Type.TBoolean>;
+        cel_expression: Type.TString;
+        targets: Type.TArray<Type.TObject<{
+            provider: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+            model: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+            weight: Type.TNumber;
+        }>>;
+        fallbacks: Type.TOptional<Type.TArray<Type.TString>>;
+        scope: Type.TString;
+        scope_id: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+        priority: Type.TOptional<Type.TNumber>;
+    }>>;
+}>;
+export declare const VirtualKeySchema: Type.TObject<{
+    id: Type.TString;
+    name: Type.TOptional<Type.TString>;
+    value: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+}>;
+/**
+ * Wire envelope as observed 2026-10-08: GET /api/governance/virtual-keys
+ * returns `{virtual_keys: [...], count, ...}` with the full VK rows
+ * INCLUDING their secret values. Unknown extra fields pass validation.
+ */
+export declare const VirtualKeysEnvelopeSchema: Type.TObject<{
+    virtual_keys: Type.TArray<Type.TObject<{
+        id: Type.TString;
+        name: Type.TOptional<Type.TString>;
+        value: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+    }>>;
+}>;
+export type CatalogModel = {
+    id: string;
+    owned_by?: string;
+    context_length?: number;
+    max_output_limit?: number;
+    pricing?: {
+        prompt: string;
+        completion: string;
+        input_cache_read?: string;
+        input_cache_write?: string;
+    };
+};
+export type RoutingRule = {
+    id: string;
+    name: string;
+    enabled?: boolean;
+    cel_expression: string;
+    targets: Array<{
+        provider?: string | null;
+        model?: string | null;
+        weight: number;
+    }>;
+    fallbacks?: string[];
+    scope: string;
+    scope_id?: string | null;
+    priority?: number;
+};
+export type VirtualKey = {
+    id: string;
+    name?: string;
+    value?: string | null;
+};
+export type Chain = {
+    /** Chain model name extracted from the routing rule (e.g. "glm-5.3-flash"). */
+    name: string;
+    /** Primary member id, "provider/model". */
+    primary: string;
+    /** Fallback member ids, in order. */
+    fallbacks: string[];
+};
+/** Decode an OpenAI-shaped /v1/models wire envelope into member entries. */
+export declare function wireCatalogToModels(envelope: {
+    data: CatalogModel[];
+}): CatalogModel[];
+/** GET gateway /v1/models with the VK — the full member catalog with pricing. */
+export declare function wireCatalog(token: string, baseUrl: string, signal?: AbortSignal, opts?: FetchJsonOptions): Promise<CatalogModel[]>;
+/** Resolve the management-plane base URL from the inference /v1 base URL. */
+export declare function managementBase(baseUrl: string): string;
+/**
+ * GET /api/governance/virtual-keys and match the INFERENCE credential value
+ * (the VK) against VK values to discover this plugin's VK id (the scope_id
+ * for routing-rule filtering). AUTH on the call is the MANAGEMENT token
+ * (settings managementApiKey, falling back to the VK — the split matters on
+ * deployments whose management plane expects a different credential than
+ * inference). Returns undefined when no VK row's value matches vkValue.
+ */
+export declare function wireScopeId(managementToken: string, vkValue: string, baseUrl: string, signal?: AbortSignal, opts?: FetchJsonOptions): Promise<string | undefined>;
+/**
+ * GET /api/routing/rules?scope=virtual_key&scope_id=<id> and decode the
+ * chain rules. AUTH is the MANAGEMENT token (see wireScopeId). Throws when
+ * Bifrost responds with an error envelope (schema mismatch or HTTP error
+ * surfaced by fetchJson).
+ */
+export declare function wireRules(managementToken: string, baseUrl: string, scopeId: string, signal?: AbortSignal, opts?: FetchJsonOptions): Promise<RoutingRule[]>;
+/** Full discovery: catalog + rules for the VK, in parallel where possible.
+ * AUTH: management plane (VK lookup + rules) uses managementToken; the
+ * inference catalog uses the VK itself. */
+export declare function wireDiscovery(managementToken: string, vkValue: string, baseUrl: string, scopeId: string, signal?: AbortSignal, opts?: FetchJsonOptions): Promise<{
+    catalog: CatalogModel[];
+    rules: RoutingRule[];
+}>;
+/**
+ * Extract a chain model name from a routing rule's CEL expression.
+ * Recognizes `model == "x"` arms and strips managed prefixes (`bifrost/`,
+ * legacy `gateway/`) from each name. Every arm must reduce to one canonical
+ * bare name — the chains-first convention. Anything else is not a chain rule.
+ */
+export declare function chainNameFromCel(cel: string): string | undefined;
+/** Decode enabled, unambiguous chain rules. Order follows rule priority. */
+export declare function wireRulesToChains(rules: RoutingRule[]): Chain[];
+/** Convert a $/token wire string to pi's $/Mtok rate. */
+export declare function perMtok(dollarsPerToken: string): number | undefined;
+/**
+ * Build one bifrost/<chain> chat model per chain. Cost is 0 by design. The
+ * wire follows the chain's model-family (native protocol end to end): the
+ * chain name decides — fallback legs of a chain are same-model by
+ * construction, and the gateway translates any client wire for legs that
+ * differ.
+ */
+export declare function buildChainModels(chains: Chain[], catalog: CatalogModel[], providerSlug: string, baseUrl: string, native?: NativeProtocols): GatewayModel[];
+/**
+ * Build direct-selectable models for the /v1/models catalog with real
+ * per-member pricing, ordered with chain members first.
+ */
+export declare function buildMemberModels(chains: Chain[], catalog: CatalogModel[], providerSlug: string, baseUrl: string, thinkingOverrides?: Record<string, string[]>, native?: NativeProtocols): GatewayModel[];
+/** Chains first, then upstream models (deduped by id — chain ids are namespaced). */
+export declare function buildAllModels(chains: Chain[], catalog: CatalogModel[], providerSlug: string, baseUrl: string, publishChains: boolean, publishUpstream: boolean, thinkingOverrides?: Record<string, string[]>, native?: NativeProtocols): GatewayModel[];