Skip to content
Press / to search

Runtime API Schemas

Published JSON Schema artifacts for ContextOS runtime contracts: RunContext, invokeAgent, agent delegation, 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
AgentDelegationEnvelopeParent-issued child-run authority, scope, budget, expiry, and effect-isolation contract./schemas/agent-delegation.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.
AgentDelegationEnvelope.scopeMust be a subset of the parent run’s intents, capabilities, data ceiling, and authority.
AgentDelegationEnvelope.sub_budgetIs reserved from the parent budget; delegation cannot reset or mint capacity.
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.action_risk_requested / action_risk_effectiveAdditive v1 fields that separate effect, authority, reversibility, interaction, and data scope; policy resolves them independently.
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.

ApprovalMode remains required in the v1 ToolEnvelope for compatibility. ActionRisk is optional in v1 so existing consumers continue to validate; new adapters should emit both. A future major envelope may require the native vector after migration telemetry shows that all active capabilities have a conservative projection.

Relationship to docs