Reference Architecture

Executive summary

ContextOS is an open contract for reliable agent harnesses, formalized as a portable decision-control and evidence specification. It defines reproducible controls around probabilistic model behavior: context selection, capability exposure, policy and risk evaluation, budget checks, threshold comparisons, evidence capture, decision records, replay inputs, and change promotion. This repository supplies schemas, a deterministic compiler, execution validators and synthetic workflow references; production enforcement belongs to the implementing deployment. Public interface availability does not change the repository’s all-rights-reserved license.

Adopt the smallest workflow that can demonstrate accepted outcomes, denied effects, and inspectable evidence. The planes below are logical responsibilities, not a requirement to deploy five services or three specialist agents. A managed provider may implement execution or persistence while application-owned tools enforce authorization and outcome acceptance. Map those owners explicitly before claiming conformance.

The architecture decomposes the runtime into five planes:

The model sits inside this architecture. It is not the architecture. Model calls cross the AI Gateway / LLM Router; external effects still cross the Tool Gateway.

The same plane boundaries also define the improvement surface. Autotune and reviewer agents may search over harness variants, but only within the fields each plane declares tunable:

This is why improvement is a control-plane concern, not a model-side feature. A candidate can be generated automatically; promotion is still a governed release.

What this architecture is for

This reference is written for platform teams building or evaluating a ContextOS-conforming runtime implementation. It answers six questions:

This page is not a tutorial. For a step-by-step MVP, start with Quickstart. For one request end-to-end, read How It Works.

Architectural thesis

When context, reasoning, tools and governance are collapsed into one prompt, the organization can lose the evidence needed to answer:

• Which facts did the agent rely on?
• Which policies were evaluated?
• Which tools were exposed, and why?
• Which human or system identity authorized the action?
• What exactly would happen if we replay the run?
• Which change caused a regression?

ContextOS separates those concerns into typed planes and turns every important boundary into a contract.

High-level architecture

                         TRUST PLANE
 Policy Engine | Identity | Approvals | Evaluators | OTEL | Replay | Improvement
--------------------------------------------------------------------------------
                         ACTION PLANE
       Tool Gateway | MCP | A2A | OpenAPI | custom adapters | idempotency
--------------------------------------------------------------------------------
                         DECISION PLANE
       Planner | Executor | Critic | AI Gateway | LLM Router | sessions | Decision Catalog
--------------------------------------------------------------------------------
                         CONTEXT PLANE
       Context Pack | Compiler | token budgets | manifests | runtime controls
--------------------------------------------------------------------------------
                       INTELLIGENCE PLANE
       Ontology | Identity Layer | Knowledge Graph | GraphRAG | Memory Fabric

The planes are stacked by dependency direction. Higher planes may constrain lower-plane behavior; lower planes must not bypass higher-plane controls. For example, an adapter cannot self-authorize a destructive action, and a Planner cannot introduce a tool that the Compiler did not surface.

The three ledgers

A production agent run should leave three ledgers. If any ledger is missing, the run is not auditable.

The DecisionRecord indexes all three. It is the durable audit artifact, not a decorative log line.

These are audit views, not an exhaustive count of runtime stores. Durable run/checkpoint state and the aggregate BudgetLedger retain ownership, limits, reservations and uncertainty needed for safe recovery; a decision receipt cannot replace them.

Core invariants

These invariants are more important than any individual component implementation.

Cross-cutting contracts

This is a field-oriented architecture sketch, not a replacement schema; optional fields retain their published optionality.

RunContext
  run_id
  trace_id
  session_id
  tenant_id
  user.delegation
  agent.workload_identity
  intent
  locale
  safety_mode
  run_budget
 
RunBudget
  total_tokens
  bucket_tokens{business,policy,tool,evidence,memory,session}
  max_tool_calls
  max_replan_attempts
  wall_clock_ms
  max_cost_cents
  tokens_used
  tool_calls_used
  latency_ms_used
  cost_cents_used
 
ApprovalMode
  read_only | local_write | network | delegated | destructive
  required v1 compatibility projection and RunContext ceiling
 
ActionRisk
  effect{none,local_state,external_state,physical_world}
  authority{agent,service,user_delegated,human_approved}
  reversibility{read_only,reversible,compensatable,irreversible}
  interaction{api,browser,computer,agent_to_agent,human_handoff}
  data_scope{PUBLIC,INTERNAL,CONFIDENTIAL,RESTRICTED}
  decision_ttl_seconds?
 
ContextPack
  contract_meta
  pack_meta
  intelligence_refs
  business_context
  policy_layer
  tooling_layer
  decision_layer
  memory_layer
  evaluation_layer
  tone_and_comms
 
CompiledContext
  compiled_prompt
  manifests{policy,tool,evidence}
  runtime_controls{must_refuse,must_escalate,approval_gates_active,redaction_rules_active}
  budget_report
  context_ledger
 
ToolEnvelope
  ToolCallEnvelope{tool_call_id,run_id,capability_id,args,trace_id,idempotency_key,evidence_refs}
  ToolResultEnvelope{tool_call_id,capability_id,status,output,error,citations,mutations,policy_decision_id,latency_ms}
 
DecisionRecord
  record_id
  decision_key
  decision_version
  status
  actor
  subject_ids
  outputs
  evidence_refs
  policy_decisions
  approvals
  controls_active
  budget_usage
  trace_id
  replay?

Contracts move across planes. Components do not reach into each other’s private state.

The separate Execution Contract preserves those base shapes and Context Pack v2. Its attachment families cover exact profile/feature support, full ActionBinding, current scoped authority and stored approval, boundary/data/memory lifecycle validation, run/operation/checkpoint transitions, aggregate reservations and evidence assessment. The five immutable control profiles compose requirements for personal/proactive, enterprise, durable/delegated and high-assurance workflows. They are neither certification tiers nor proof of universal domain readiness.

Canonical execution contract

invokeAgent(request_envelope, run_context)
  -> resolve pack refs, tenant, identity, intent, safety mode
  -> admit exact profiles, actual workflow features and implementation support
  -> compile(packs, request, run_context) -> CompiledContext
  -> bind DecisionSpec
  -> route model judgment through AI Gateway / LLM Router
  -> loop {
       planner(CompiledContext)         -> Plan
       critic.verify(Plan)              -> ok | replan | reject | escalate
       executor(Plan, ToolGateway)      -> step_results + evidence_refs
       critic.score(step_results)       -> accept | retry | replan | escalate
       consolidate(effects, evidence)   -> memory_proposals
     }
  -> emit DecisionRecord
  -> emit replay packet and scorecard

Every component is either a participant in this loop, a registry consulted by a participant, or an operator surface over the artifacts the loop emits.

Runtime topology

ContextOS separates authoring and control concerns from hot-path execution.

Deployment rule

Do not deploy the Compiler, AI Gateway, Tool Gateway, and Policy Engine as optional libraries inside agent code. They are platform services or platform-controlled modules because they enforce the boundary. Agent code may call them; it must not replace them.

Tool Gateway names the Action-plane pattern. Tool Manager is the concrete component implementation.

Plane responsibilities

Intelligence plane

The Intelligence plane owns durable meaning. It turns enterprise data into stable identities, typed relationships, evidence refs, and memory that can be safely reused.

Owns:

• canonical entity identity,
• evidence provenance,
• knowledge snapshots,
• memory promotion state.

Does not own:

• deciding which facts enter a specific prompt,
• authorizing external actions,
• final decision outcomes.

Context plane

The Context plane owns per-request compilation. It converts a pinned Context Pack plus RunContext into a CompiledContext envelope.

Owns:

• policy/tool/evidence manifests,
• prompt assembly,
• context budget accounting,
• truncation visibility.

Does not own:

• live tool execution,
• approval decisions,
• memory promotion.

Decision plane

The Decision plane owns the bounded loop. It turns CompiledContext into a plan, verifies it, executes approved steps, scores the result, and emits a typed decision.

Owns:

• plan structure,
• Critic verdicts,
• loop control,
• terminal DecisionRecord emission.

Does not own:

• direct API calls,
• policy truth,
• graph mutation.

Action plane

The Action plane owns external effects. It converts tool intents into validated, authorized, traced calls.

Owns:

• schema validation for tool args and results,
• credential exchange,
• tool transcript capture,
• provider-specific idempotency/recovery validation, stable operations and honest effect uncertainty.

Does not own:

• deciding that a risky action is allowed,
• inventing capabilities outside the registry,
• storing final business decisions.

Trust plane

The Trust plane owns control over the other four planes. It makes the runtime governable.

Owns:

• policy decisions,
• approval state,
• scorecards and release gates,
• trace and replay requirements,
• promotion of improvement proposals.

Does not own:

• arbitrary business logic hidden in prompts,
• unreviewed automatic self-modification.

Plane dependency rules

Reference flow: support refund

The refund workflow is the reference example because it exercises all production boundaries:

1. User request enters with a RunContext.
2. Context Pack ctxpack.support@x.y.z and graph snapshot are pinned.
3. Compiler emits CompiledContext with policy, tool, and evidence manifests.
4. Planner proposes lookup, policy eval, and refund steps.
5. Critic verifies tool availability, args, native action risk, v1 projection, policy obligations, and required evidence.
6. Tool Gateway executes read tools and freezes evidence for the risky write.
7. The policy-required approval gate authorizes or denies the refund against the frozen evidence snapshot.
8. The Gateway rechecks current authority, exact stored approval and atomic redemption, active boundary/data route and budget reservation, then dispatches the stable operation through the payment adapter.
9. Verified provider observations and postconditions establish completion before the Critic scores; a missing acknowledgement leaves the effect unknown and enters bounded reconciliation.
10. Runtime emits DecisionRecord, replay packet, and memory proposals.

For the complete transcript, see Workflow Examples and How It Works.

Trust architecture

Tenant boundary
  storage, graph, memory, pack registry, traces, and tool credentials are tenant scoped
 
Identity boundary
  agent workload identity is required; user delegation is present when authority is user_delegated
 
Policy boundary
  policy decisions are evaluated before compile exposure and before tool execution
 
Approval boundary
  exact actions with an approval obligation bind evidence/policy/profile/release pins and current eligible approvers; dispatch revalidates and atomically redeems the approval
 
Execution boundary
  actual code, processes, filesystem, network, credentials and resources match current observed containment requirements
 
Data boundary
  source labels, purpose, recipients, processors, residency and approved transformations are verified across every enabled stage
 
Recovery boundary
  run/operation/checkpoint stores enforce ownership generation, target fencing where required and original aggregate limits
 
Audit boundary
  policy decisions, approvals, tool transcripts, scorecards, and traces bind to one trace_id
 
Replay boundary
  request, pack, policy, graph snapshot, model profile, route decision, tool transcripts, evaluator set, and model config are pinned

See Security and Compliance for the detailed control map.

Failure semantics

Failures must be typed. Silent fallback is a production bug.

Observability and AgentOps

Every production run should be observable at four levels.

Recommended span attributes:

contextos.run_id
contextos.session_id
contextos.tenant_id
contextos.intent
contextos.context_pack_ref
contextos.policy_bundle_ids
contextos.action.effect
contextos.action.authority
contextos.action.reversibility
contextos.action.interaction
contextos.action.data_scope
contextos.approval_mode_required
contextos.approval_mode_effective
contextos.decision_key
contextos.decision_record_id
contextos.replay_id

Tail sampling should force retention for runs that cross approval gates, fail evaluator thresholds, produce incidents, or affect durable business state.

Retention remains bounded by authorized privacy/incident policy. Refs, hashes, prompts, caches, telemetry and reviewer exports are data flows with actual readers/processors and lifecycle obligations. Minimize sensitive content and expose unavailable or uncertain evidence explicitly. A scorecard or correlated trace is not runtime conformance; assess the exact workflow, release and environment against every required useful/denied case and current independent evidence.

Standards alignment

ContextOS uses existing standards where they fit and adds only the agent-runtime contracts those standards do not define.

Alignment does not mean delegation. MCP or OpenAPI can describe a tool. ContextOS still decides whether that tool is exposed, whether it can execute, which identity it uses, which evidence it must cite, and how the action is replayed.

Control-plane lifecycle

Multi-tenant isolation

Tenant isolation is not only a database filter. It applies to every artifact:

Reference contracts

Implementation checklist

For a new tenant or workflow, review the applicable requirements below and the exact admitted profiles. This checklist alone cannot establish production readiness; add domain obligations, threat/failure assumptions and measured deployment evidence.

Anti-patterns

Roadmap notes

• Plane primitives are stable contracts; individual services may evolve.
• New patterns should be validated against working systems before promotion into this reference.
• Major changes follow the same change-control process as Context Packs, policy bundles, DecisionSpecs, and evaluator sets.

Appendix A: Component inventory

Appendix B: Naming conventions

• Planes: Intelligence, Context, Decision, Action, Trust.
• Primitives: PascalCase (RunContext, ContextPack, CompiledContext, DecisionRecord, ToolEnvelope).
• Enum values: snake_case (read_only, local_write, network, delegated, destructive).
• Identifiers: <scope>:<type>:<id> when human-readable (order:ord_881, customer:cus_77).
• Trace attributes: contextos.<plane>.<attribute> when plane-specific; contextos.run_id and contextos.decision_record_id when global.
• Version refs: <artifact_id>@<semver> for Context Packs, policy bundles, evaluator sets, and DecisionSpecs.