Skip to content
Press / to search

Runtime API Schemas

Published JSON Schema artifacts for ContextOS runtime contracts: RunContext, invokeAgent, CompiledContext, ToolEnvelope, DecisionRecord, and ReplayPacket.

Reference DesignLast reviewed: Edit on GitHub
At a glance

Reference Architecture

This page is the routing table for executable runtime schemas. Earlier versions of this page embedded compact illustrative snippets; the published /schemas/*.json artifacts below are now the validation surface.

Published schemas

ContractPurposeSchema
RunContextPer-run identity, tenant, authority, safety mode, and budget./schemas/run-context.v1.schema.json
invokeAgentEntry request envelope for stream, batch, and long-running execution./schemas/invoke-agent.v1.schema.json
ContextPackVersioned deployable contract for the Context plane./schemas/context-pack.v2.schema.json
CompiledContextCompiler output: prompt, manifests, runtime controls, budget report, and context ledger./schemas/compiled-context.v1.schema.json
ToolEnvelopeToolCallEnvelope and ToolResultEnvelope for governed capability invocation and result audit./schemas/tool-envelope.v1.schema.json
DecisionRecordReplayable audit receipt emitted by governed decision checkpoints./schemas/decision-record.v1.schema.json
ReplayPacketPortable replay input for audit replay, regression replay, environment replay, and source-pressure closure./schemas/replay-packet.v1.schema.json

Canonical flow

invokeAgent(request_envelope, run_context)
  -> compile(packs, request, run_context) -> CompiledContext
  -> loop {
       planner(CompiledContext) -> Plan
       critic.verify(Plan) -> ok | replan | reject
       executor(Plan, ToolGateway) -> ToolEnvelope[]
       critic.score(step_results) -> accept | retry | replan | escalate
       consolidate(effects, evidence) -> memory_proposals
     }
  -> DecisionRecord
  -> ReplayPacket when sampled, failed, corrected, or promoted

Field invariants

SurfaceInvariant
RunContext.trace_idPropagates to compiled context, tool envelopes, decision records, and replay packets.
RunContext.safety_modeFilters surfaced tools by maximum approval mode before the planner can select them.
CompiledContext.context_ledger.compiled_context_hashHashes the compiled prompt, manifests, runtime controls, and budget report for replay.
ToolCallEnvelope.policy_decision_idBinds a capability invocation to the deterministic policy decision that allowed, blocked, or gated it.
ToolCallEnvelope.idempotency_keyRequired for non-idempotent or irreversible capabilities where duplicate execution would be harmful.
ToolResultEnvelope.mutations[]Names side effects or mutation refs; replay consumes transcripts instead of re-executing live side effects.
DecisionRecord.evidence_refs[]Must resolve to evidence, tool result, policy, or artifact refs available to the replay harness.
DecisionRecord.replayCarries replay handle and hashes; it is not a substitute for the trace or tool transcripts.
ReplayPacket.side_effect_policyDeclares whether replay is transcript-only, sandboxed, or explicitly live-disallowed.

Naming rules

Naming must stay consistent across examples:

NameMeaning
R_HIGH_VALUE_REQUIRES_APPROVALA policy rule_id.
GATE_FINANCE_APPROVALAn approval gate_id referenced by a rule or tool invocation.
pol_...A runtime policy decision id emitted when policy evaluates.
tool_...A tool call id shared by call and result envelopes.
rp_...A replay packet id.

Do not record the approval gate id as a policy rule id. Do not treat model-routing records as business decision records; routing decisions can appear in DecisionRecord.lineage, but the governed business outcome is still the DecisionRecord.

Relationship to docs