@agent-os/runtime-protocol
Purpose
Section titled “Purpose”Serializable runtime vocabulary shared across runtime services, concrete backends, composers, and ops surfaces.
Invariant
Section titled “Invariant”Runtime protocol is vocabulary only. It owns submit DTOs, admission lease/projection DTOs, runtime ledger event schemas, runtime fact-owner identity, and ledger identity types. It does not own Effect services, runtime control flow, backend storage, transport wrapping, or provider implementations.
@agent-os/runtime consumes this package as an interpreter layer. Backends and composers import protocol-owned symbols directly from this package; runtime must not re-export them as a compatibility shim.
Minimal Usage
Section titled “Minimal Usage”Use this package when a value crosses runtime/backend/composer/ops boundaries or is persisted in ledger-visible state.
import type { SubmitSpec, SubmitResult } from "@agent-os/runtime-protocol";import { decodeRuntimeLedgerEvent } from "@agent-os/runtime-protocol";Use @agent-os/runtime for Effect services and execution:
import { Ledger, submitAgentEffect } from "@agent-os/runtime";Replay Stage
Section titled “Replay Stage”Replay stage 1 is complete for state replay from committed ledger facts: runtime-owned events are serializable protocol values, and projections can fold the ledger without calling runtime services or backend hosts.
This is ledger replay, not deterministic re-execution across external IO. A run that would call dispatch targets, LLM providers, or tools still needs an IO snapshot oracle before the replay mode can assert that live adapters are not invoked. Until dispatch, LLM, and tool snapshots all exist, replay claims stop at substrate state reconstruction.
Verification
Section titled “Verification”Run the package and graph gates:
cd packages/runtime-protocol && bun run testbun run typecheck