pi-bifrost-provider-enriched0.2.0

pi-bifrost-provider-enriched

pi-bifrost-provider-enriched is a composite Pi extension. It adds missing reasoning effort metadata to models from provider bifrost.

The package loads pi-bifrost-provider version 0.2.0 as a runtime dependency. It registers providers bifrost and bifrost-enriched before Pi selects the initial model.

Requirements

Version 0.2.0 uses this tested version baseline:

• @earendil-works/pi-coding-agent 1.5.2.
• @earendil-works/pi-ai 1.5.2.
• pi-bifrost-provider 0.2.0.
• Bifrost transport 2.4.0.
• Node.js 22.19.0 or newer.

The package does not claim support for other versions.

Installation

Install only this Pi package. npm installs pi-bifrost-provider version 0.2.0 as its dependency.

pi install npm:pi-bifrost-provider-enriched@0.2.0

A separate pi-bifrost-provider installation is not a supported configuration.

Pi packages run with your user permissions. Review the source before installation.

Environment

Set BIFROST_URL to load models and send requests through Bifrost. The provider pair still registers when this variable is absent, but its source catalog is empty.

You can also set these authentication variables:

• BIFROST_API_KEY supplies the Bifrost API key.
• BIFROST_VIRTUAL_KEY supplies the Bifrost virtual key.

For example:

export BIFROST_URL=http://127.0.0.1:8080
export BIFROST_API_KEY=your-api-key
export BIFROST_VIRTUAL_KEY=your-virtual-key
pi

You can omit either key when your Bifrost configuration does not require it. Virtual key authentication does not add an authorization value.

Provider selection

Start Pi after the package loads. Run /model, then select a model under provider bifrost-enriched.

If both providers contain the same exact model ID, the normal model list shows only the bifrost-enriched entry. A source-only model stays visible under provider bifrost.

You can also start Pi with the provider and an existing Bifrost model ID:

pi --provider bifrost-enriched --model openai/gpt-5

The extension preserves the original model ID. It delegates each enriched request to provider bifrost.

You can select a hidden paired source model directly:

pi --provider bifrost --model openai/gpt-5

Pi also restores a hidden source model from a saved default or a resumed session. Use direct source selection when you do not want fallback effort metadata.

Credentials

The extension uses the public authentication resolver from provider bifrost. It passes the authentication context and abort signal to that resolver.

The extension does not read auth.json. It also ignores a stored credential for provider bifrost-enriched and provides no login flow.

The extension does not copy, log, or cache Bifrost credentials. Provider bifrost remains responsible for request authentication.

Metadata and cache

The extension uses source model metadata when that metadata is complete. It uses models.dev only when source effort metadata is absent.

After startup, the extension sends one HTTPS request to this fixed endpoint:

https://models.dev/api.json

The request contains no Bifrost credential, header, provider configuration, or model request. It has a ten second timeout and a 25 MiB response limit.

The extension stores public metadata in this file under XDG_CACHE_HOME:

$XDG_CACHE_HOME/pi-bifrost-provider-enriched/models-dev-v1.json

If XDG_CACHE_HOME is absent, the extension uses this file:

~/.cache/pi-bifrost-provider-enriched/models-dev-v1.json

A fresh cache is valid for 24 hours. If the network request fails, the extension can use an older valid cache.

The extension makes sure that remote and cached data are valid before use. Invalid data does not replace the active model catalog.

Architecture

The factory loads the upstream extension and captures its unchanged bifrost provider. It registers the source availability wrapper and the enriched provider before session creation.

The session lifecycle starts metadata work, the source watcher, and offline refresh coordination. It stops those resources during session shutdown.

The enrichment layer performs provider scoped matching. It creates new model values and does not mutate source models.

The metadata layer validates the fixed models.dev response and manages the local cache. The refresh layer publishes complete catalogs and keeps the last good catalog after failure.

A five second in memory watcher detects source catalog changes. It performs no network request and does not keep Node.js running.

Development

Run these commands from the repository root:

npm install
npm run build
npm run typecheck
npm run format

The build writes JavaScript and type declarations to dist. The type analysis command does not write output.

Testing

Run the complete current test suite from the repository root:

npm test

The suite compiles tests before it runs them. It covers contracts, enrichment, matching, cache access, network limits, provider behavior, refreshes, lifecycle events, and data protection.

The acceptance baseline uses the exact versions in the Requirements section. Do not use a passing test on another version as a compatibility claim.

Security

The extension treats all remote and cached JSON as untrusted data. It does not execute metadata values.

The extension loads the public package entry point from pi-bifrost-provider. It uses public Pi provider and lifecycle APIs.

The extension writes no Pi setting and changes no default model. It creates no command or prompt and writes nothing directly to the terminal.

The package owns the supported registration path for bifrost and bifrost-enriched. Routine enrichment failure registers the unchanged source provider and leaves bifrost available.

Removal

Remove the package from the same Pi scope that contains the installation:

pi remove npm:pi-bifrost-provider-enriched@0.2.0

Removal removes both provider registrations. You can delete the extension cache separately because it contains only public metadata.

Removal does not delete Pi settings or Bifrost credentials. Stop selecting either package-owned provider after removal.

Retirement

Retire this package when Bifrost and pi-bifrost-provider expose complete tested effort metadata through provider bifrost.

First, make sure that the supported test matrix passes with the source metadata. Then install pi-bifrost-provider directly:

pi install npm:pi-bifrost-provider@0.2.0

Select provider bifrost, then remove pi-bifrost-provider-enriched. The direct upstream installation keeps provider bifrost available after removal.

Release inspection

Review the package file list before publication:

npm pack --dry-run

The release review must inspect the tarball and make sure that npm access works. It must select the version and tag and prepare recovery steps.