Docs Overview

ContextOS is an open contract for reliable agent harnesses. Its decision-control and evidence specification defines what context enters a run, which authority permits an action, what evidence establishes the outcome, and how a team evaluates the next release.

Use it around an existing agent runtime, managed service, or application-owned loop. Start with one workflow whose accepted outcomes and prohibited effects you can test. Platform and product engineers implement the boundaries; security and operations teams inspect the same evidence. The current direction explains the compatibility and evidence requirements as execution systems evolve.

What you can use today

This repository publishes the specification and conformance reference. Schema validity establishes structure; it does not certify correct outcomes, secure infrastructure, or portability between untested runtimes. “Open contract” describes its public interface; the repository license retains all rights reserved.

Explore the five planes

Hover or click each plane to see its primitives and the typed contracts it owns.

The five planes

The planes are responsibilities, not a mandatory service topology. Add graph retrieval, promoted memory, specialist agents, or durable execution when workflow evidence justifies them. The required authority, context, effect, and outcome boundaries still apply to a small implementation.

┌───────────────────────────────────────────────────────────────┐
│  TRUST PLANE                                                  │
│  policy · ActionRisk · identity · evaluators · OTEL · replay  │
├───────────────────────────────────────────────────────────────┤
│  ACTION PLANE                                                 │
│  Tool Gateway · MCP · A2A · OpenAPI · idempotency             │
├───────────────────────────────────────────────────────────────┤
│  DECISION PLANE                                               │
│  cognitive loop · Planner / Executor / Critic · subagent lanes│
├───────────────────────────────────────────────────────────────┤
│  CONTEXT PLANE                                                │
│  Context Pack Compiler · token budgets · runtime controls     │
├───────────────────────────────────────────────────────────────┤
│  INTELLIGENCE PLANE                                           │
│  ontology · knowledge graph · memory · embeddings · identity  │
└───────────────────────────────────────────────────────────────┘

Improvement surfaces by plane

ContextOS treats the harness as a versioned artifact that can improve from traces, scorecards, corrections, and replay. The Improvement Loop may propose changes across all five planes, but each plane owns both a tunable surface and an invariant that the optimizer cannot relax.

This is the practical reading of “autotune” in ContextOS: search may discover better harness configurations, but every candidate remains a typed proposal that passes replay, review, and staged rollout before release.

Cross-cutting primitives

These primitives connect the appropriate boundaries; individual envelopes retain their declared required/optional fields:

• RunContext — run_id, trace_id, session_id, tenant_id, user (delegation), agent (workload identity), safety_mode, run_budget.
• ActionRisk — native effect, authority, reversibility, interaction, and data-scope vector.
• ApprovalMode — required v1 compatibility projection: read_only / local_write / network / delegated / destructive.
• ContextPack — versioned and immutable; signed when an adopted supply-chain profile requires it.
• CompiledContext — compiled_prompt, manifests, runtime_controls, budget_report.
• DecisionRecord — typed outcome with evidence_refs, approvals, controls_active, trace_id.
• ToolEnvelope — ToolCallEnvelope / ToolResultEnvelope with policy decision, native-risk fields where available, v1 mode projection, idempotency, evidence refs, and W3C trace context.
• Execution attachments — exact profile/control refs and features, ActionBinding, scoped authority and stored approval, boundary/data/memory checks, durable run/operation/checkpoint state, and aggregate reservations. They preserve the existing envelopes and Context Pack layout.

The canonical execution contract

invokeAgent(request_envelope, run_context)
  → admit(exact profiles, actual features, implementation support)
  → compile(packs, request, run_context) → CompiledContext
  → loop {
       planner(CompiledContext)         → Plan
       critic.verify(Plan)              → ok | replan | reject
       executor(Plan, ToolGateway)      → step_results, evidence
       critic.score(step_results)       → accept | retry | replan | escalate
       consolidate(effects, evidence)   → memory_proposals
     }
  → DecisionRecord(evidence_refs, approvals, controls_active, trace_id)

Every doc references back to this contract. Schemas and canonical types are authoritative at their published version. Prose examples are explanatory or deployment blueprints unless explicitly labeled normative.

At dispatch, recheck current authority, exact approval, actual boundary/data route and reserved budget. A provider timeout can leave an effect unknown; cancellation or checkpoint restore cannot turn it into absence, replenish budget or authorize blind retry. Personal/proactive, enterprise, durable/delegated and high-assurance profiles select exact cumulative requirements with workflow-specific evidence, rather than declaring universal readiness for every domain.

What is authoritative vs. blueprint

New patterns are validated against working systems before they land in the normative spec. The roadmap can describe candidates, but only versioned schemas and canonical types make them contract.

Reading paths

Platform engineers building the runtime → Adopt a Harness Contract → API Contracts → Context Pack → Reference Architecture. Consult the relevant foundations when implementing a boundary.

Product engineers building agents on top of the runtime → Adopt a Harness Contract → Quickstart → Decision Catalog → Decision Record → Workflow Examples.

Applied AI / ML integrating models and retrieval → Cognitive Core → Agentic Context Engineering → Knowledge Graph → Identity Layer → Evaluation and Observability.

Security / governance assessing the runtime → Control Profiles → Execution Contract → Conformance → Governance → Security and Compliance → High-Risk Workflow.

Executives evaluating the investment case → Adopt a Harness Contract → Invest Early in ContextOS → Evaluation and Observability. Ask for verified completion, intervention effort, prohibited effects, and cost on your workflow before expanding investment.

Document status

Every doc declares a status in its frontmatter. The badge identifies the page’s purpose, not the maturity of every statement on that page. Contract maturity is stated at the artifact or section level using the four layers at the top of this page: normative contract, conformance reference, integration or deployment profile, and planned evolution.

The test suite rejects unknown status values and requires an ISO last_reviewed date on every documentation page. Neither field by itself promotes an interface, example, or roadmap proposal into the canonical contract.

Quick links

• Soul, operating philosophy → The SOUL of ContextOS
• Overview, end-to-end → How It Works
• Adopt one workflow → Adoption guide
• Work through the contracts → Quickstart
• Architecture → Reference Architecture
• Glossary → Glossary
• Status, source of truth → schemas linked from each implementation doc