Creasura Agentic OS Protocol (CAOP) v0.1

1. Overview

For Creasura One OSS, an Agentic Operating System (Agentic OS) is:

A persistent, event-driven system that coordinates intelligent agents, tools, knowledge, and human decisions to achieve goals over time, while maintaining durable state, enforcing policies, verifying outcomes, and recovering from failures.

An agentic OS is not simply an agent, an agent framework, or an LLM with tools. It is the system responsible for managing the lifecycle of work performed by agents.

An agentic OS doesn’t need to implement its own LLM, browser, coding agent, or research engine. Those are execution capabilities. The OS manages how those capabilities are invoked, coordinated, supervised, and remembered. ChatGPT, Claude, and other providers can supply execution capabilities while Creasura provides a consistent operating model.

2. The five fundamental abstractions

Start with five abstractions rather than a large collection of specialized agents.

2.1 Goal

A desired outcome that persists beyond a single conversation, for example: reduce monthly household expenses, complete a software architecture proposal, plan a family vacation, launch a business. A goal has an owner, success criteria, constraints, and a lifecycle.

interface Goal {
  id: string;
  objective: string;
  owner: PrincipalRef;
  successCriteria: Criterion[];
  constraints: Constraint[];
  status: "active" | "paused" | "achieved" | "abandoned";
  createdAt: string;
  updatedAt: string;
}

2.2 Work

A bounded unit of execution that advances a goal. A goal may contain multiple work items. Work has dependencies, execution state, deadlines, and evidence of completion.

Goal: Plan family vacation
  |
  +-- Compare destinations
  +-- Find flights
  +-- Compare hotels
  +-- Review budget
  +-- Book approved itinerary

interface WorkItem {
  id: string;
  goalId: string;
  description: string;
  dependencies: string[];
  status: "pending" | "ready" | "running" | "blocked" | "completed" | "failed" | "cancelled";
  assignedCapability?: string;
  result?: ArtifactRef;
  deadline?: string;
}

2.3 State

The durable representation of what the OS knows: facts, goals, commitments, decisions, relationships, policies, execution history, and evidence. State is not equivalent to conversational memory.

interface Fact {
  id: string;
  subject: EntityRef;
  predicate: string;
  object: unknown;
  source: EvidenceRef;
  observedAt: string;
  validFrom?: string;
  validTo?: string;
  confidence?: number;
}

2.4 Capability

Something the OS can invoke to perform work: an AI assistant, a coding agent, email, calendar, GitHub, web research, a deterministic rules engine, or a human approval workflow.

interface Capability {
  id: string;
  operations: string[];
  inputSchema: object;
  outputSchema: object;
  authorization: AuthorizationPolicy;
  executionMode: "interactive" | "background" | "scheduled";
  provider: string;
}

A capability contract should describe what an operation can do, not merely what an agent is instructed to attempt.

2.5 Policy

An enforceable constraint governing execution. Examples: never send an external email without authorization; never spend money without approval; never expose employer-confidential information to a personal workspace; never mark work complete without supporting evidence.

interface Policy {
  id: string;
  scope: string;
  condition: Expression;
  effect: "allow" | "deny" | "require_approval";
  version: string;
}

3. The lifecycle

A canonical lifecycle with eight stages:

1. Observe
2. Understand
3. Commit
4. Plan
5. Execute
6. Verify
7. Record
8. Review
9. ↺ back to Observe

These are logical lifecycle stages, not a requirement that every request execute eight sequential LLM calls. A deterministic operation might bypass planning entirely. A failed verification might return work to planning. A blocked task might wait for an external event for several days.

4. Lifecycle API

The protocol has three interfaces: the Lifecycle API (how work progresses), the Capability API (how external executors perform work), and the State API (how knowledge, decisions, and outcomes persist).

These operations represent logical responsibilities. Implementations can combine them internally.

4.1 Observe

An observation represents something the OS has learned from an external source.

POST /v1/observations
{
  "source": { "provider": "gmail", "resource_id": "message_123" },
  "type": "message.received",
  "occurred_at": "2026-11-01T14:00:00Z",
  "payload_ref": "artifact_456",
  "idempotency_key": "gmail-message-123"
}

// Response
{ "observation_id": "obs_123", "status": "accepted", "duplicate": false }

4.2 Understand

The OS resolves the observation against known state.

POST /v1/context/resolve
{
  "observation_ids": ["obs_123"],
  "scope": { "workspace_id": "personal", "project_ids": ["mortgage-refinance"] },
  "include": ["related_goals", "open_commitments", "relevant_policies", "prior_decisions"]
}

// Response
{
  "context_id": "ctx_123",
  "state_version": 42,
  "related_goals": ["goal_refinance"],
  "open_commitments": ["commitment_12"],
  "applicable_policies": ["policy_financial_approval"],
  "unresolved_questions": []
}

This operation should distinguish retrieved facts from inferred interpretations.

4.3 Commit

Create a durable obligation or objective.

POST /v1/commitments
{
  "goal_id": "goal_refinance",
  "objective": "Evaluate updated refinancing offer",
  "success_criteria": [
    { "type": "artifact_exists", "artifact_type": "refinancing_comparison" }
  ],
  "deadline": "2026-11-05T23:59:00Z"
}

// Response
{ "commitment_id": "com_123", "status": "open", "version": 1 }

4.4 Plan

POST /v1/plans
{
  "commitment_id": "com_123",
  "constraints": { "require_approval_for_external_actions": true },
  "preferred_capabilities": ["document_analysis", "calculator", "research"]
}

// Response
{
  "plan_id": "plan_123",
  "steps": [
    { "id": "step_1", "capability": "document_analysis", "depends_on": [] },
    { "id": "step_2", "capability": "calculator", "depends_on": ["step_1"] },
    { "id": "step_3", "capability": "report_generation", "depends_on": ["step_2"] }
  ]
}

The planner may use an LLM. The runtime must still validate the generated plan against schemas, dependencies, and policy constraints.

4.5 Execute

POST /v1/executions
{
  "plan_id": "plan_123",
  "idempotency_key": "execute-plan-123-v1",
  "authorization_context": { "principal_id": "user_123" }
}

// Response
{ "execution_id": "exec_123", "status": "queued", "next_action": "await_execution" }

Execution is asynchronous. An accepted request does not mean the work has completed.

4.6 Verify

POST /v1/verifications
{
  "execution_id": "exec_123",
  "criteria": ["all_required_steps_completed", "result_has_supporting_evidence", "no_policy_violations"]
}

// Response
{ "verification_id": "verify_123", "verdict": "passed", "evidence_refs": ["artifact_789"] }

Verification can include deterministic checks, human approval, or model-based evaluation. The verdict must identify which checks were performed.

4.7 Record

POST /v1/records/commit
{
  "execution_id": "exec_123",
  "verification_id": "verify_123",
  "expected_state_version": 42,
  "changes": [ { "entity_id": "com_123", "operation": "set_status", "value": "completed" } ]
}

// Response
{ "transaction_id": "txn_123", "state_version": 43, "status": "committed" }

4.8 Review

POST /v1/reviews
{
  "goal_id": "goal_refinance",
  "review_type": "progress",
  "include": ["outcomes", "unresolved_commitments", "failures", "next_actions"]
}

// Response
{
  "review_id": "review_123",
  "goal_status": "active",
  "recommended_actions": [ { "action": "request_final_offer", "requires_approval": true } ]
}

Review recommendations are proposals, not automatically authorized actions.

5. Execution state machine

The eight lifecycle stages should not be confused with execution states.

CREATED
   |
   v
READY
   |
   v
RUNNING ---------> WAITING_APPROVAL
   |                     |
   |                     v
   |                   RUNNING
   |
   +------------------> BLOCKED
   |                     |
   |                     v
   |                   READY
   |
   v
VERIFYING
   |
   +------> FAILED
   |          |
   |          v
   |        READY (retry)
   |
   v
COMPLETED

Terminal states: COMPLETED, CANCELLED, EXPIRED

The API must reject invalid transitions.

POST /v1/executions/exec_123/transitions
{
  "expected_state": "VERIFYING",
  "target_state": "COMPLETED",
  "verification_id": "verify_123"
}

A transition from CREATED directly to COMPLETED should be rejected unless the work type explicitly supports that shortcut. The runtime persists each accepted transition with an actor, timestamp, reason, and correlation ID.

Try the state machine interactively ›

6. Capability API

The boundary between the OS and the assistants and services that do the work. The OS must not assume every provider supports the same features.

interface CapabilityDescriptor {
  id: string;
  provider: string;
  operations: string[];
  inputSchema: object;
  outputSchema: object;
  supportsAsync: boolean;
  supportsResume: boolean;
  supportsCancellation: boolean;
  authorizationRequired: boolean;
  sideEffectLevel: "none" | "reversible" | "irreversible";
}

interface CapabilityInvocation {
  invocationId: string;
  capabilityId: string;
  input: unknown;
  contextRefs: string[];
  authorizationRef?: string;
  idempotencyKey: string;
}

interface CapabilityResult {
  invocationId: string;
  status: "completed" | "failed" | "pending" | "requires_approval";
  output?: unknown;
  evidenceRefs: string[];
  error?: { code: string; message: string; retryable: boolean };
}

This makes the OS independent of a particular execution provider. A capability might be implemented through an AI assistant, a coding agent, an MCP tool, a deterministic function, or another provider.

6.1 Native assistant mapping

What a native ChatGPT setup can provide on its own, and what it guarantees:

7. Cross-cutting contracts

These matter more than adding dozens of specialized endpoints.

7.1 Error format

{
  "error": {
    "code": "POLICY_APPROVAL_REQUIRED",
    "message": "External action requires approval",
    "retryable": false,
    "details": { "approval_request_id": "approval_123" }
  },
  "trace_id": "trace_456"
}

8. Events

An agentic OS is event-driven rather than assuming every workflow starts with a user prompt.

{
  "event_id": "evt_123",
  "event_type": "commitment.deadline_approaching",
  "schema_version": "1.0",
  "occurred_at": "2026-11-01T14:00:00Z",
  "workspace_id": "personal",
  "subject_id": "com_123",
  "correlation_id": "goal_refinance",
  "causation_id": "evt_100",
  "payload": { "hours_remaining": 24 }
}

The event transport can start simple. For a single-user deployment of Creasura One OSS v0.1, an SQLite-backed event table and a scheduled processor are sufficient. No distributed broker is required.

9. Conformance levels

An assistant configured with projects and instructions can provide L1 immediately. L2 needs a persistent store outside conversational memory. L3 needs a lightweight execution controller that responds to events and enforces lifecycle transitions, delegating AI work to existing providers.

10. Minimum public API

Don’t expose all eight lifecycle stages as mandatory public tools. Expose a small set of outcome-oriented operations, mapped internally to the richer lifecycle API:

Assistants see a manageable set of tools with clear purposes, and the internal OS can evolve without forcing changes to every integration.

11. Reference architecture

                    USER
                     |
                     v
              +-------------+
              | AI assistant|
              | (ChatGPT,   |
              |  Claude...) |
              +------+------+
                     |  MCP
                     v
          +----------------------+
          | CREASURA OS PROTOCOL |
          | Goals & Commitments  |
          | State & Context      |
          | Plans & Executions   |
          | Policies & Approvals |
          | Verification         |
          +----------+-----------+
                     |
          +----------+----------+
          v                     v
   +-------------+       +-------------+
   | State Store |       | Event Loop  |
   | SQLite      |       | Scheduler   |
   +-------------+       +------+------+
                                |
                                v
                         +-------------+
                         | Capability  |
                         | Adapters    |
                         +------+------+
                                |
                 +--------------+--------------+
                 v              v              v
            Assistants    Coding agents    External services

12. Business Profile (CAOP-Biz)

An optional profile that scales the same kernel from a single-user personal OS to a business operating system, without changing the eight lifecycle stages or the public operations.

12.1 Metric trees and variance triggers

interface MetricNode {
  id: string;                 // e.g. "metric.net_contribution_margin"
  name: string;
  formula?: string;           // deterministic relation to child metrics
  parentMetricId?: string;
  childMetricIds: string[];
  owner: PrincipalRef;
  baselineCadence: "hourly" | "daily" | "weekly" | "monthly";
  varianceThresholds: {
    warningDeltaPct: number;  // e.g. -3.0% triggers Understand
    criticalDeltaPct: number; // e.g. -7.5% triggers Commitment
  };
}

On metric.variance_detected, context.resolve traverses the childMetricIds graph to isolate the driver before any commitment or plan is proposed.

12.2 Delegation of Authority

• Tier 1, autonomous: exposure under $1,000 and margin above threshold → allow under the agent’s service principal.
• Tier 2, single approver: $1,000–$25,000 → require_approval routed to a role, with an SLA escalation timer.
• Tier 3, quorum: over $25,000 or modifies a locked constraint → multi-party sign-off before WAITING_APPROVAL can move to RUNNING.

interface ApprovalRoutingRule {
  policyId: string;
  requiredRoles: string[];
  minQuorum: number;
  expirationSeconds: number;
  escalateToRoleOnTimeout?: string;
}

12.3 Bitemporal state

• Valid time (validFrom → validTo): the business period the fact describes.
• System time (observedAt → supersededAt): when the OS believed the fact to be true.
• Invariant: context.resolve accepts asOfSystemTime and asOfValidTime, separating decision quality from data latency.

12.4 Two-phase verification

POST /v1/commitments
{
  "goal_id": "goal_q4_efficiency",
  "objective": "Reallocate underperforming campaign spend to high-margin SKUs",
  "success_criteria": [
    { "phase": "immediate_verification", "type": "constraint_check",
      "rule": "total_daily_spend <= 10000 AND min_sku_roas >= 2.8" },
    { "phase": "outcome_realization", "evaluation_window_hours": 168,
      "type": "counterfactual_lift", "metric_id": "metric.net_contribution_margin",
      "expected_delta_pct": 4.5 }
  ]
}

Immediate criteria are evaluated at Verify. When Record commits, the outbox schedules commitment.outcome_window_elapsed; when it fires, Review compares realized metrics with the dry-run projection and writes a value-realization verdict.

12.5 Capability tiers

13. Machine-readable contracts

CAOP v0.1 is published in two machine-readable forms generated from the same definitions:

• OpenAPI 3.1 contract: every lifecycle operation, request, response, and error, with the MCP tool each one backs. YAML · JSON
• JSON Schema 2020-12: every object in this specification, in one bundle. caop-v0.1.schema.json