clawdie/colibri
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
colibri/docs/wiki/contracts.md
123kupola 789396e8bb
Some checks failed
CI / rust (pull_request) Has been cancelled
Details
CI / markdown (pull_request) Has been cancelled
Details
CI / port (pull_request) Has been cancelled
Details
CI / agent-jail-pkgs (pull_request) Has been cancelled
Details
fix: Layer 1 — contracts, MCP naming, lock contention 
1. contracts.md: add TaskCostSummary to active schemas table
2. MCP: rename colibri_get_task_cost → colibri_get_task
   (returns full task with cost, not just cost fields)
3. heartbeat: try_lock() instead of lock().unwrap()
   - WouldBlock → warn + defer to next tick
   - Poisoned → into_inner() recover (SQLite WAL protects data)

Sam & Hermes
2026-06-27 13:48:21 +02:00

2.3 KiB
Raw Blame History

Stable JSON contracts

← index

colibri-contracts holds the stable, language-agnostic wire shapes shared between Colibri (Rust) and Clawdie agents (TypeScript). It owns schemas and (De)serialize, not business logic.

Why a separate contracts crate

  • Prevent duplicated definitions between Rust and TypeScript lanes.
  • Keep committed manifests in manifests/ parseable by both sides.
  • Centralize schema strings, field renaming aliases, and backward-compat defaults.

Active schemas

Schema Rust struct Purpose
clawdie.interagent.run-manifest.v1 RunManifest Records a build/test run — role, agent, artifacts, summary.
clawdie.runtime-version-inventory.v1 RuntimeInventory Host runtime snapshot — OS, package versions, npm/node/zot/pi.
clawdie.provider-test.result.v1 ProviderSmokeResult DeepSeek cache-hit probe result and token accounting.
clawdie.task-cost-summary.v1 TaskCostSummary Per-task cost breakdown — input/output/cache tokens, cost_usd.

Schema constants and structs live in crates/colibri-contracts/src/lib.rs.

Evolution rules

  • The crate carries no logic — only serde structs and schema constants.
  • New fields are normally optional with #[serde(default)] so old manifests still parse.
  • RuntimeInventory.pi is optional because not every host installs pi or zot.
  • HostStatus.raw is a catch-all serde_json::Value so hostile collector output can be captured without forcing a schema bump.

Golden tests

crates/colibri-contracts/tests/golden.rs parses every committed manifest in manifests/ and asserts round-trip equality. The fixtures are intended to be cross-platform — if a manifest produced on Linux differs from one produced on FreeBSD 15, the difference must be understood and documented before it is merged.

See also