Metadata-Version: 2.4
Name: bifrost
Version: 1.1.5
Summary: MCP-in-reverse protocol for agent-platform ↔ consumer-tool integration.
Author: Vuong Hoang
License: Proprietary
Requires-Python: >=3.11
Requires-Dist: jsonschema>=4.21
Provides-Extra: dev
Requires-Dist: cryptography>=42; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: starlette>=0.37; extra == 'dev'
Provides-Extra: reference-server
Requires-Dist: cryptography>=42; extra == 'reference-server'
Requires-Dist: starlette>=0.37; extra == 'reference-server'
Requires-Dist: uvicorn>=0.30; extra == 'reference-server'
Description-Content-Type: text/markdown

# Bifrost

Wire protocol + reference implementations for **MCP-in-reverse**: a way
for consumer applications to expose tools to LLM agents running inside
[Worldtree](https://gitea.phasefinal.com/vh/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.py` inside 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](docs/adr/0006-wire-v0.6-stable-1.0-cut.md),
[ROADMAP](ROADMAP.md)). 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.x` dir 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](docs/adr/0006-wire-v0.6-stable-1.0-cut.md)).
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](https://gitea.phasefinal.com/vh/Worldtree) — multi-agent framework; first Bifrost consumer (MCP-client side)
- [Skaldsong](https://gitea.phasefinal.com/vh/skaldsong) — story-generation engine; Bifrost consumer (YAML-validation tools)
- [Vast Blue SEA](https://gitea.phasefinal.com/vh/vastai-app) — multi-agent web app; Bifrost consumer (enterprise orchestration tools)
- [Vor](https://gitea.phasefinal.com/vh/Vor) — pre-contract design partner; Bifrost consumer (frame-clarification tools in v2)
- [Sleipnir](https://gitea.phasefinal.com/vh/sleipnir) — AFK orchestrator
- [althing](https://gitea.phasefinal.com/vh/althing) — agent-to-agent message bus; Bifrost consumer (UI-state tools)
- [Galdrabok](https://gitea.phasefinal.com/vh/Galdrabok) — Sleipnir-preflight skill author
- [task-board](https://gitea.phasefinal.com/vh/task-board) — per-session web UI
- [corviduo-project-template](https://gitea.phasefinal.com/vh/corviduo-project-template) — canonical scaffold this repo seeded from
