Metadata-Version: 2.4
Name: bifrost
Version: 0.6.4
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-v1.md` | Canonical protocol doc, frozen at each major version. |
| `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. |
| `schemas/v1/` | JSON Schema files, one per message type. Validated in CI. |
| `reference_server/` | Small Python module consumers vendor or fork as their starting MCP server. |
| `conformance/` | Test suite both sides run. `server_conformance.py` tests a consumer's MCP server; `client_conformance.py` tests a platform's MCP client. |
| `clients/` | Canonical client libraries for non-Worldtree consumers. Deferred to v0.2. |

## 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

Pre-1.0. Architectural calls locked in via Worldtree issue
[#160](https://gitea.phasefinal.com/vh/Worldtree/issues/160)'s
frame-pass comment (2026-05-09). Sub-questions pending `/vor 160`.
Reference server, schemas, and conformance suite to be authored
after that resolves.

Tracking issue (cross-repo): Worldtree #160.

## Versioning

Three independent semver tracks once 1.0 ships:

- **Bifrost protocol** (this repo) — spec doc is the source of
  truth; schemas + reference server + conformance suite carry the
  same major version.
- **Worldtree** — declares which Bifrost protocol version range it
  supports in its release notes (`Bifrost: ^1.0`).
- **Consumer applications** — each consumer's own semver; they
  declare the Bifrost protocol version they implement.

Pre-1.0: breaking changes allowed. Post-1.0: strict semver with
deprecation windows. Once any non-Worldtree-team consumer ships
against 1.0.0, breaking changes require 2.0.0 + a deprecation period.

## 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
