bifrost (1.1.5)
Installation
pip install --index-url https://gitea.phasefinal.com/api/packages/vh/pypi/simple/ --extra-index-url https://pypi.org/simple bifrostAbout this package
MCP-in-reverse protocol for agent-platform ↔ consumer-tool integration.
Bifrost
Wire protocol + reference implementations for MCP-in-reverse: a way for consumer applications to expose tools to LLM agents running inside Worldtree-style agent platforms.
In Norse mythology, Bifrost is the rainbow bridge connecting Asgard (the realm of the gods) to Midgard (the realm of mortals). Heimdall is its watchman. Both names map to existing Worldtree subsystems — Heimdall is the codebase's auth/access-control layer — so the mythology mirrors the architecture: Bifrost-routes-through-Heimdall is the natural shape.
What problem it solves
Today's LLM-agent platforms let agents call tools, but the tools live on the platform side. A platform that wants to support consumer-side tools (where the consumer owns the auth, the state, the business logic) has to either (a) absorb the tools into the platform (mission creep — the platform becomes a junkdrawer of consumer features) or (b) ship a separate sidecar protocol the platform has to maintain.
Bifrost is option (c): the consumer runs an MCP server (or an MCP-compatible endpoint), the platform connects to it on behalf of its agents, the agent invokes consumer tools through the standard MCP wire format. The platform never executes consumer code; the consumer never absorbs platform-specific tooling. The bridge is the trust boundary.
What lives here
| Path | Contents |
|---|---|
docs/bifrost-spec-v0.1.md … v0.6.md |
Canonical protocol docs; each wire version freezes its own (v0.6 = current STABLE). |
docs/handshake.md |
Capability negotiation deep-dive. |
docs/error-vocabulary.md |
Three-layer error taxonomy: Bifrost-level vs MCP-level vs consumer-tool errors. |
docs/lifecycle.md |
Session bind → MCP connect → tools → unbind. |
bifrost/schemas/{v0.1…v0.6, affect}/ |
JSON Schema files, one per message type, per wire version. Validated in CI. |
bifrost/reference_server/ |
Fork-able reference servers for all three planes (tool.* / memory.* / affect.*). |
conformance/ |
Test suite both sides run. server_conformance.py tests a consumer's MCP server; client_conformance.py tests a platform's MCP client. |
bifrost/consumer/ |
Depend-on consumer libraries: build_memory_app / build_affect_app / build_combined_app. (Client-side reference library parked — #8.) |
What does NOT live here
- Worldtree's MCP-client integration code — that's a Worldtree concern; lives in
core/transports/bifrost_client.pyinside Worldtree. - Heimdall integration on the Worldtree side.
- Worldtree's session-binding plumbing for Bifrost endpoints — Conversation API surface, lives in Worldtree.
- Consumer-specific tool implementations — each consumer's own repo.
Status
Bifrost 1.0.0 (2026-06-29) — first stable release. Wire v0.6 is
STABLE/FROZEN (ADR-0006,
ROADMAP). All three capability families ship with reference
server, schemas, conformance, and depend-on consumer libraries: tool.*
(v0.1–v0.3), memory.* (v0.4–v0.6), affect.* (emit v0.6 / fetch v0.9).
Cross-repo adoption proven (Worldtree #195/#289, ratatoskr #18).
Install (gitea PyPI index): bifrost==1.0.0.
Tracking issue (cross-repo origin): Worldtree #160 (frame-pass, 2026-05-09).
Versioning
Three independent semver tracks:
- Bifrost package (this repo) —
1.0.0. The spec doc is the source of truth; schemas + reference server + conformance ship in the same package. - Bifrost wire — versioned independently of the package (currently
v0.6, STABLE). New verbs / scope axes ride a new wire version
(v0.7+); each
v0.xdir is an immutable frozen snapshot, so a pinned consumer never changes under it. - Consumer applications — each consumer's own semver; they declare
the Bifrost package + wire version they implement (e.g.
bifrost==1.0.0, wire v0.6).
Post-1.0: a breaking wire change rides a new wire version AND a Bifrost package MAJOR (2.0+) — never a mutation of a frozen version, and no compat shims (ADR-0006). The wire otherwise evolves additively. (Pre-1.0, breaking changes were allowed at operator-approved minors; 1.0 closed that window.)
Why a separate repo
Bifrost is consumed by multiple independent applications (SEA, Skaldsong, Vor, Althing, Saga RPG, plus future siblings), none of which should pull all of Worldtree to use the protocol. Separating the repo at bootstrap is cheaper than extracting it later — different commit cadences, different release cycles, different audit boundaries, different consumer access models all converge cleanly when the boundary is real from the start, and degrade messily when it's bolted on later.
Sibling Corviduo projects (reference)
- Worldtree — multi-agent framework; first Bifrost consumer (MCP-client side)
- Skaldsong — story-generation engine; Bifrost consumer (YAML-validation tools)
- Vast Blue SEA — multi-agent web app; Bifrost consumer (enterprise orchestration tools)
- Vor — pre-contract design partner; Bifrost consumer (frame-clarification tools in v2)
- Sleipnir — AFK orchestrator
- althing — agent-to-agent message bus; Bifrost consumer (UI-state tools)
- Galdrabok — Sleipnir-preflight skill author
- task-board — per-session web UI
- corviduo-project-template — canonical scaffold this repo seeded from