{ "openapi": "3.1.0", "info": { "title": "Creasura Agentic OS Protocol (CAOP)", "version": "0.1", "description": "Lifecycle API for the Creasura Agentic OS Protocol v0.1. Every protected operation identifies the authenticated principal and workspace, is authorized server-side, and returns errors in the standard Error shape with a trace_id." }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "servers": [ { "url": "http://localhost:8787", "description": "Self-hosted runtime (e.g. on your Mac mini)" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Observe" }, { "name": "Understand" }, { "name": "Commit" }, { "name": "Plan" }, { "name": "Execute" }, { "name": "Verify" }, { "name": "Record" }, { "name": "Review" } ], "paths": { "/v1/observations": { "post": { "operationId": "observations.ingest", "summary": "Ingest an observation", "description": "Records something the OS learned from an external source. Replaying the same source event with the same idempotency_key returns the existing observation with duplicate: true.", "tags": [ "Observe" ], "x-caop-stage": "Observe", "x-caop-mcp-tool": "observe", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObservationCreate" }, "example": { "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" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObservationAccepted" }, "example": { "observation_id": "obs_123", "status": "accepted", "duplicate": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden or approval required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/context/resolve": { "post": { "operationId": "context.resolve", "summary": "Resolve context", "description": "Resolves observations against known state. Retrieved facts and inferred interpretations are returned separately.", "tags": [ "Understand" ], "x-caop-stage": "Understand", "x-caop-mcp-tool": "get_context", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextResolveRequest" }, "example": { "observation_ids": [ "obs_123" ], "scope": { "workspace_id": "personal", "project_ids": [ "mortgage-refinance" ] }, "include": [ "related_goals", "open_commitments", "relevant_policies", "prior_decisions" ] } } } }, "responses": { "200": { "description": "Context bundle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextBundle" }, "example": { "context_id": "ctx_123", "state_version": 42, "related_goals": [ "goal_refinance" ], "open_commitments": [ "commitment_12" ], "applicable_policies": [ "policy_financial_approval" ], "unresolved_questions": [] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden or approval required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/commitments": { "post": { "operationId": "commitments.create", "summary": "Create a commitment", "description": "Creates a durable obligation or objective. A commitment cannot be completed solely because an agent claims it is complete.", "tags": [ "Commit" ], "x-caop-stage": "Commit", "x-caop-mcp-tool": "create_commitment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitmentCreate" }, "example": { "goal_id": "goal_refinance", "objective": "Evaluate updated refinancing offer", "success_criteria": [ { "type": "artifact_exists", "artifact_type": "refinancing_comparison" } ], "deadline": "2026-11-05T23:59:00Z" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Commitment" }, "example": { "commitment_id": "com_123", "status": "open", "version": 1 } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden or approval required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "commitments.list", "summary": "List commitments", "description": "Returns outstanding and recent commitments for the caller’s workspace.", "tags": [ "Commit" ], "x-caop-stage": "Commit", "x-caop-mcp-tool": "list_commitments", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "completed", "failed", "cancelled", "expired" ] } }, { "name": "goal_id", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Commitments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitmentList" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/plans": { "post": { "operationId": "plans.create", "summary": "Create a plan", "description": "Produces an execution plan. The planner may use an LLM; the runtime validates the plan against schemas, dependencies, and policy.", "tags": [ "Plan" ], "x-caop-stage": "Plan", "x-caop-mcp-tool": "propose_plan", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanCreate" }, "example": { "commitment_id": "com_123", "constraints": { "require_approval_for_external_actions": true }, "preferred_capabilities": [ "document_analysis", "calculator", "research" ] } } } }, "responses": { "201": { "description": "Plan created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" }, "example": { "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" ] } ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden or approval required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/executions": { "post": { "operationId": "executions.start", "summary": "Start an execution", "description": "Starts an authorized execution of a plan. Execution is asynchronous; acceptance does not mean completion.", "tags": [ "Execute" ], "x-caop-stage": "Execute", "x-caop-mcp-tool": "start_work", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionCreate" }, "example": { "plan_id": "plan_123", "idempotency_key": "execute-plan-123-v1", "authorization_context": { "principal_id": "user_123" } } } } }, "responses": { "202": { "description": "Queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionAccepted" }, "example": { "execution_id": "exec_123", "status": "queued", "next_action": "await_execution" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden or approval required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/executions/{execution_id}": { "get": { "operationId": "executions.get", "summary": "Get execution status", "description": "Returns the current state of an execution.", "tags": [ "Execute" ], "x-caop-stage": "Execute", "x-caop-mcp-tool": "get_work_status", "parameters": [ { "name": "execution_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Execution" }, "example": { "execution_id": "exec_123", "plan_id": "plan_123", "state": "RUNNING", "state_version": 3, "correlation_id": "goal_refinance", "updated_at": "2026-11-01T14:05:00Z" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/executions/{execution_id}/results": { "post": { "operationId": "executions.submit_result", "summary": "Submit a result", "description": "Submits output and evidence for verification. Moves a RUNNING execution to VERIFYING.", "tags": [ "Execute" ], "x-caop-stage": "Execute", "x-caop-mcp-tool": "submit_result", "parameters": [ { "name": "execution_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultSubmission" }, "example": { "output": { "report": "artifact_789" }, "evidence_refs": [ "artifact_789" ], "idempotency_key": "submit-exec-123-v1" } } } }, "responses": { "202": { "description": "Accepted for verification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Execution" }, "example": { "execution_id": "exec_123", "plan_id": "plan_123", "state": "RUNNING", "state_version": 3, "correlation_id": "goal_refinance", "updated_at": "2026-11-01T14:05:00Z" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Invalid transition or state version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/executions/{execution_id}/transitions": { "post": { "operationId": "executions.transition", "summary": "Transition an execution", "description": "Moves an execution between states. Invalid transitions are rejected with INVALID_TRANSITION; a stale expected_state yields STATE_VERSION_CONFLICT.", "tags": [ "Execute" ], "x-caop-stage": "Execute", "parameters": [ { "name": "execution_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransitionRequest" }, "example": { "expected_state": "VERIFYING", "target_state": "COMPLETED", "verification_id": "verify_123" } } } }, "responses": { "200": { "description": "Transition accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transition" }, "example": { "transition_id": "tr_9", "execution_id": "exec_123", "from_state": "VERIFYING", "to_state": "COMPLETED", "state_version": 5, "actor": { "type": "service", "id": "caop-runtime" }, "reason": "verification passed", "correlation_id": "goal_refinance", "occurred_at": "2026-11-01T15:00:00Z" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden or approval required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Invalid transition or state version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/verifications": { "post": { "operationId": "verifications.evaluate", "summary": "Evaluate verification", "description": "Evaluates an execution result against criteria. The verdict lists every check performed and its kind.", "tags": [ "Verify" ], "x-caop-stage": "Verify", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationRequest" }, "example": { "execution_id": "exec_123", "criteria": [ "all_required_steps_completed", "result_has_supporting_evidence", "no_policy_violations" ] } } } }, "responses": { "200": { "description": "Verdict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" }, "example": { "verification_id": "verify_123", "verdict": "passed", "evidence_refs": [ "artifact_789" ], "checks": [ { "name": "all_required_steps_completed", "kind": "deterministic", "result": "pass" }, { "name": "result_has_supporting_evidence", "kind": "model_rubric", "result": "pass" }, { "name": "no_policy_violations", "kind": "deterministic", "result": "pass" } ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Verification failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/records/commit": { "post": { "operationId": "records.commit", "summary": "Commit a record", "description": "Persists facts, evidence, and outcomes with optimistic concurrency on expected_state_version.", "tags": [ "Record" ], "x-caop-stage": "Record", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordCommit" }, "example": { "execution_id": "exec_123", "verification_id": "verify_123", "expected_state_version": 42, "changes": [ { "entity_id": "com_123", "operation": "set_status", "value": "completed" } ] } } } }, "responses": { "200": { "description": "Committed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordCommitted" }, "example": { "transaction_id": "txn_123", "state_version": 43, "status": "committed" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden or approval required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Invalid transition or state version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reviews": { "post": { "operationId": "reviews.evaluate", "summary": "Evaluate a review", "description": "Evaluates progress toward a goal. Recommended actions are proposals, not authorized actions.", "tags": [ "Review" ], "x-caop-stage": "Review", "x-caop-mcp-tool": "review_goals", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewRequest" }, "example": { "goal_id": "goal_refinance", "review_type": "progress", "include": [ "outcomes", "unresolved_commitments", "failures", "next_actions" ] } } } }, "responses": { "200": { "description": "Review", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Review" }, "example": { "review_id": "review_123", "goal_status": "active", "recommended_actions": [ { "action": "request_final_offer", "requires_approval": true } ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/approvals/{approval_request_id}/decision": { "post": { "operationId": "approvals.decide", "summary": "Decide an approval request", "description": "Grants or denies a scoped, expiring authorization for a consequential action.", "tags": [ "Execute" ], "x-caop-stage": "Execute", "x-caop-mcp-tool": "approve_action", "parameters": [ { "name": "approval_request_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalDecision" }, "example": { "decision": "approve", "scope": { "document": "offer-v2", "max_price": 632000 }, "expires_at": "2026-11-02T22:00:00Z" } } } }, "responses": { "200": { "description": "Decision recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" }, "example": { "approval_id": "appr_301", "approval_request_id": "approval_123", "decision": "approve", "scope": { "document": "offer-v2" }, "approved_by": { "type": "user", "id": "user_123" }, "expires_at": "2026-11-02T22:00:00Z" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden or approval required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } }, "schemas": { "PrincipalRef": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "role", "agent", "service" ] }, "id": { "type": "string" } }, "additionalProperties": false, "required": [ "type", "id" ], "description": "An authenticated principal: a person, a role, an agent, or a service account." }, "EntityRef": { "type": "string", "description": "Identifier of any entity known to the OS, e.g. \"property/14-oak-lane\"." }, "EvidenceRef": { "type": "string", "description": "Identifier of a piece of evidence (an artifact, observation, or record) that supports a fact or outcome." }, "ArtifactRef": { "type": "string", "description": "Identifier of a stored artifact such as a document or report." }, "Expression": { "type": "string", "description": "A condition evaluated by the policy engine, e.g. \"recipient.type == 'client'\"." }, "Criterion": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": true, "required": [ "type" ], "description": "A success criterion. \"type\" selects the evaluator; other members are evaluator-specific." }, "Constraint": { "type": "object", "properties": { "type": { "type": "string" } }, "additionalProperties": true, "required": [ "type" ], "description": "A constraint on how a goal may be pursued." }, "AuthorizationPolicy": { "type": "object", "properties": { "requiredScopes": { "type": "array", "items": { "type": "string" } }, "policyIds": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "description": "What a caller must hold to invoke a capability." }, "Goal": { "type": "object", "properties": { "id": { "type": "string" }, "objective": { "type": "string" }, "owner": { "$ref": "#/components/schemas/PrincipalRef" }, "successCriteria": { "type": "array", "items": { "$ref": "#/components/schemas/Criterion" } }, "constraints": { "type": "array", "items": { "$ref": "#/components/schemas/Constraint" } }, "status": { "type": "string", "enum": [ "active", "paused", "achieved", "abandoned" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "required": [ "id", "objective", "owner", "successCriteria", "constraints", "status", "createdAt", "updatedAt" ], "description": "A desired outcome that persists beyond a single conversation." }, "WorkItem": { "type": "object", "properties": { "id": { "type": "string" }, "goalId": { "type": "string" }, "description": { "type": "string" }, "dependencies": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "pending", "ready", "running", "blocked", "completed", "failed", "cancelled" ] }, "assignedCapability": { "type": "string" }, "result": { "$ref": "#/components/schemas/ArtifactRef" }, "deadline": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "required": [ "id", "goalId", "description", "dependencies", "status" ], "description": "A bounded unit of execution that advances a goal." }, "Fact": { "type": "object", "properties": { "id": { "type": "string" }, "subject": { "$ref": "#/components/schemas/EntityRef" }, "predicate": { "type": "string" }, "object": {}, "source": { "$ref": "#/components/schemas/EvidenceRef" }, "observedAt": { "type": "string", "format": "date-time" }, "validFrom": { "type": "string", "format": "date-time" }, "validTo": { "type": "string", "format": "date-time" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 } }, "additionalProperties": false, "required": [ "id", "subject", "predicate", "object", "source", "observedAt" ], "description": "A durable, provenance-bearing statement in the OS state. Every material fact has a traceable source." }, "Capability": { "type": "object", "properties": { "id": { "type": "string" }, "operations": { "type": "array", "items": { "type": "string" } }, "inputSchema": { "type": "object" }, "outputSchema": { "type": "object" }, "authorization": { "$ref": "#/components/schemas/AuthorizationPolicy" }, "executionMode": { "type": "string", "enum": [ "interactive", "background", "scheduled" ] }, "provider": { "type": "string" } }, "additionalProperties": false, "required": [ "id", "operations", "inputSchema", "outputSchema", "authorization", "executionMode", "provider" ], "description": "Something the OS can invoke to perform work." }, "Policy": { "type": "object", "properties": { "id": { "type": "string" }, "scope": { "type": "string" }, "condition": { "$ref": "#/components/schemas/Expression" }, "effect": { "type": "string", "enum": [ "allow", "deny", "require_approval" ] }, "version": { "type": "string" }, "enforcement": { "type": "string", "enum": [ "advisory", "enforced" ], "description": "Advisory policies are instructions to a model. Enforced policies are checked by the runtime before an action executes." } }, "additionalProperties": false, "required": [ "id", "scope", "condition", "effect", "version", "enforcement" ], "description": "A constraint governing execution." }, "CapabilityDescriptor": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "operations": { "type": "array", "items": { "type": "string" } }, "inputSchema": { "type": "object" }, "outputSchema": { "type": "object" }, "supportsAsync": { "type": "boolean" }, "supportsResume": { "type": "boolean" }, "supportsCancellation": { "type": "boolean" }, "authorizationRequired": { "type": "boolean" }, "sideEffectLevel": { "type": "string", "enum": [ "none", "reversible", "irreversible" ] } }, "additionalProperties": false, "required": [ "id", "provider", "operations", "inputSchema", "outputSchema", "supportsAsync", "supportsResume", "supportsCancellation", "authorizationRequired", "sideEffectLevel" ], "description": "What an execution provider can do, independent of any one AI vendor." }, "CapabilityInvocation": { "type": "object", "properties": { "invocationId": { "type": "string" }, "capabilityId": { "type": "string" }, "input": {}, "contextRefs": { "type": "array", "items": { "type": "string" } }, "authorizationRef": { "type": "string" }, "idempotencyKey": { "type": "string" } }, "additionalProperties": false, "required": [ "invocationId", "capabilityId", "input", "contextRefs", "idempotencyKey" ], "description": "A request to a capability." }, "CapabilityResult": { "type": "object", "properties": { "invocationId": { "type": "string" }, "status": { "type": "string", "enum": [ "completed", "failed", "pending", "requires_approval" ] }, "output": {}, "evidenceRefs": { "type": "array", "items": { "type": "string" } }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "additionalProperties": false, "required": [ "code", "message", "retryable" ] } }, "additionalProperties": false, "required": [ "invocationId", "status", "evidenceRefs" ], "description": "The outcome of a capability invocation." }, "ExecutionState": { "type": "string", "enum": [ "CREATED", "READY", "RUNNING", "WAITING_APPROVAL", "BLOCKED", "VERIFYING", "FAILED", "COMPLETED", "CANCELLED", "EXPIRED" ], "description": "Execution states. COMPLETED, CANCELLED, and EXPIRED are terminal. Invalid transitions are rejected." }, "ObservationCreate": { "type": "object", "properties": { "source": { "type": "object", "properties": { "provider": { "type": "string" }, "resource_id": { "type": "string" } }, "additionalProperties": false, "required": [ "provider", "resource_id" ] }, "type": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "payload_ref": { "$ref": "#/components/schemas/ArtifactRef" }, "idempotency_key": { "type": "string" } }, "additionalProperties": false, "required": [ "source", "type", "occurred_at", "idempotency_key" ], "description": "Something the OS learned from an external source. Replaying the same source event must not create a duplicate." }, "ObservationAccepted": { "type": "object", "properties": { "observation_id": { "type": "string" }, "status": { "type": "string", "enum": [ "accepted" ] }, "duplicate": { "type": "boolean" } }, "additionalProperties": false, "required": [ "observation_id", "status", "duplicate" ] }, "ContextResolveRequest": { "type": "object", "properties": { "observation_ids": { "type": "array", "items": { "type": "string" } }, "goal_id": { "type": "string" }, "scope": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "project_ids": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "required": [ "workspace_id" ] }, "include": { "type": "array", "items": { "type": "string", "enum": [ "related_goals", "open_commitments", "relevant_policies", "prior_decisions" ] } } }, "additionalProperties": false, "required": [ "scope", "include" ] }, "ContextBundle": { "type": "object", "properties": { "context_id": { "type": "string" }, "state_version": { "type": "integer", "minimum": 0 }, "related_goals": { "type": "array", "items": { "type": "string" } }, "open_commitments": { "type": "array", "items": { "type": "string" } }, "applicable_policies": { "type": "array", "items": { "type": "string" } }, "unresolved_questions": { "type": "array", "items": { "type": "string" } }, "retrieved_facts": { "type": "array", "items": { "$ref": "#/components/schemas/Fact" } }, "inferences": { "type": "array", "items": { "type": "object", "properties": { "statement": { "type": "string" }, "based_on": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "required": [ "statement", "based_on" ] } } }, "additionalProperties": false, "required": [ "context_id", "state_version", "related_goals", "open_commitments", "applicable_policies", "unresolved_questions" ], "description": "Resolved context. Retrieved facts and inferred interpretations are kept separate." }, "CommitmentCreate": { "type": "object", "properties": { "goal_id": { "type": "string" }, "objective": { "type": "string" }, "success_criteria": { "type": "array", "items": { "$ref": "#/components/schemas/Criterion" } }, "deadline": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "required": [ "goal_id", "objective", "success_criteria" ] }, "Commitment": { "type": "object", "properties": { "commitment_id": { "type": "string" }, "goal_id": { "type": "string" }, "objective": { "type": "string" }, "success_criteria": { "type": "array", "items": { "$ref": "#/components/schemas/Criterion" } }, "deadline": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "open", "completed", "failed", "cancelled", "expired" ] }, "version": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "commitment_id", "status", "version" ], "description": "A durable obligation. It cannot be marked completed solely because an agent claims it is complete." }, "CommitmentList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Commitment" } }, "next_cursor": { "type": [ "string", "null" ] } }, "additionalProperties": false, "required": [ "data" ] }, "PlanCreate": { "type": "object", "properties": { "commitment_id": { "type": "string" }, "constraints": { "type": "object", "properties": { "require_approval_for_external_actions": { "type": "boolean" } }, "additionalProperties": true }, "preferred_capabilities": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "required": [ "commitment_id" ] }, "Plan": { "type": "object", "properties": { "plan_id": { "type": "string" }, "commitment_id": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "capability": { "type": "string" }, "depends_on": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "required": [ "id", "capability", "depends_on" ] } } }, "additionalProperties": false, "required": [ "plan_id", "steps" ], "description": "A validated proposal. The runtime checks it against schemas, dependencies, and policy before execution." }, "ExecutionCreate": { "type": "object", "properties": { "plan_id": { "type": "string" }, "idempotency_key": { "type": "string" }, "authorization_context": { "type": "object", "properties": { "principal_id": { "type": "string" } }, "additionalProperties": false, "required": [ "principal_id" ] } }, "additionalProperties": false, "required": [ "plan_id", "idempotency_key", "authorization_context" ] }, "ExecutionAccepted": { "type": "object", "properties": { "execution_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued" ] }, "next_action": { "type": "string" } }, "additionalProperties": false, "required": [ "execution_id", "status" ], "description": "Execution is asynchronous. Acceptance does not mean the work is complete." }, "Execution": { "type": "object", "properties": { "execution_id": { "type": "string" }, "plan_id": { "type": "string" }, "state": { "$ref": "#/components/schemas/ExecutionState" }, "state_version": { "type": "integer", "minimum": 0 }, "correlation_id": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "required": [ "execution_id", "state", "state_version" ] }, "TransitionRequest": { "type": "object", "properties": { "expected_state": { "$ref": "#/components/schemas/ExecutionState" }, "target_state": { "$ref": "#/components/schemas/ExecutionState" }, "verification_id": { "type": "string" }, "reason": { "type": "string" } }, "additionalProperties": false, "required": [ "expected_state", "target_state" ] }, "Transition": { "type": "object", "properties": { "transition_id": { "type": "string" }, "execution_id": { "type": "string" }, "from_state": { "$ref": "#/components/schemas/ExecutionState" }, "to_state": { "$ref": "#/components/schemas/ExecutionState" }, "state_version": { "type": "integer", "minimum": 0 }, "actor": { "$ref": "#/components/schemas/PrincipalRef" }, "reason": { "type": "string" }, "correlation_id": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "required": [ "transition_id", "execution_id", "from_state", "to_state", "state_version", "actor", "correlation_id", "occurred_at" ], "description": "Every accepted transition is persisted with an actor, timestamp, reason, and correlation ID." }, "ResultSubmission": { "type": "object", "properties": { "output": {}, "evidence_refs": { "type": "array", "items": { "type": "string" } }, "idempotency_key": { "type": "string" } }, "additionalProperties": false, "required": [ "evidence_refs", "idempotency_key" ] }, "VerificationRequest": { "type": "object", "properties": { "execution_id": { "type": "string" }, "criteria": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "required": [ "execution_id", "criteria" ] }, "Verification": { "type": "object", "properties": { "verification_id": { "type": "string" }, "verdict": { "type": "string", "enum": [ "passed", "failed" ] }, "evidence_refs": { "type": "array", "items": { "type": "string" } }, "checks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "deterministic", "model_rubric", "human" ] }, "result": { "type": "string", "enum": [ "pass", "fail" ] } }, "additionalProperties": false, "required": [ "name", "kind", "result" ] } } }, "additionalProperties": false, "required": [ "verification_id", "verdict", "evidence_refs", "checks" ], "description": "A verdict must identify which checks were performed." }, "RecordCommit": { "type": "object", "properties": { "execution_id": { "type": "string" }, "verification_id": { "type": "string" }, "expected_state_version": { "type": "integer", "minimum": 0 }, "changes": { "type": "array", "items": { "type": "object", "properties": { "entity_id": { "type": "string" }, "operation": { "type": "string" }, "value": {} }, "additionalProperties": false, "required": [ "entity_id", "operation" ] } } }, "additionalProperties": false, "required": [ "expected_state_version", "changes" ], "description": "A state mutation. A conflicting state version rejects the transaction or invokes a declared conflict policy." }, "RecordCommitted": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "state_version": { "type": "integer", "minimum": 0 }, "status": { "type": "string", "enum": [ "committed" ] } }, "additionalProperties": false, "required": [ "transaction_id", "state_version", "status" ] }, "ReviewRequest": { "type": "object", "properties": { "goal_id": { "type": "string" }, "review_type": { "type": "string", "enum": [ "progress", "outcome", "risk" ] }, "include": { "type": "array", "items": { "type": "string", "enum": [ "outcomes", "unresolved_commitments", "failures", "next_actions" ] } } }, "additionalProperties": false, "required": [ "goal_id", "review_type" ] }, "Review": { "type": "object", "properties": { "review_id": { "type": "string" }, "goal_status": { "type": "string", "enum": [ "active", "paused", "achieved", "abandoned" ] }, "recommended_actions": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "requires_approval": { "type": "boolean" } }, "additionalProperties": false, "required": [ "action", "requires_approval" ] } } }, "additionalProperties": false, "required": [ "review_id", "goal_status", "recommended_actions" ], "description": "Recommendations are proposals, not authorized actions." }, "ApprovalDecision": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approve", "deny" ] }, "scope": { "type": "object", "description": "What exactly is authorized, e.g. a document, amount, or recipient." }, "expires_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "required": [ "decision", "expires_at" ] }, "Approval": { "type": "object", "properties": { "approval_id": { "type": "string" }, "approval_request_id": { "type": "string" }, "decision": { "type": "string", "enum": [ "approve", "deny" ] }, "scope": { "type": "object" }, "approved_by": { "$ref": "#/components/schemas/PrincipalRef" }, "expires_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "required": [ "approval_id", "approval_request_id", "decision", "approved_by", "expires_at" ], "description": "A scoped, expiring authorization for a consequential action." }, "EventEnvelope": { "type": "object", "properties": { "event_id": { "type": "string" }, "event_type": { "type": "string", "description": "e.g. observation.received, commitment.created, plan.approved, execution.started, execution.blocked, approval.requested, approval.granted, execution.completed, verification.failed, record.committed, goal.achieved" }, "schema_version": { "type": "string" }, "occurred_at": { "type": "string", "format": "date-time" }, "workspace_id": { "type": "string" }, "subject_id": { "type": "string" }, "correlation_id": { "type": "string" }, "causation_id": { "type": "string" }, "payload": { "type": "object" } }, "additionalProperties": false, "required": [ "event_id", "event_type", "schema_version", "occurred_at", "workspace_id", "subject_id", "correlation_id", "payload" ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "INVALID_REQUEST", "UNAUTHENTICATED", "FORBIDDEN", "NOT_FOUND", "POLICY_APPROVAL_REQUIRED", "POLICY_DENIED", "INVALID_TRANSITION", "STATE_VERSION_CONFLICT", "VERIFICATION_FAILED", "RATE_LIMITED", "INTERNAL" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "details": { "type": "object" } }, "additionalProperties": false, "required": [ "code", "message", "retryable" ] }, "trace_id": { "type": "string" } }, "additionalProperties": false, "required": [ "error", "trace_id" ] }, "MetricNode": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "formula": { "type": "string" }, "parentMetricId": { "type": "string" }, "childMetricIds": { "type": "array", "items": { "type": "string" } }, "owner": { "$ref": "#/components/schemas/PrincipalRef" }, "baselineCadence": { "type": "string", "enum": [ "hourly", "daily", "weekly", "monthly" ] }, "varianceThresholds": { "type": "object", "properties": { "warningDeltaPct": { "type": "number" }, "criticalDeltaPct": { "type": "number" } }, "additionalProperties": false, "required": [ "warningDeltaPct", "criticalDeltaPct" ] } }, "additionalProperties": false, "required": [ "id", "name", "childMetricIds", "owner", "baselineCadence", "varianceThresholds" ], "description": "A node in a hierarchical KPI tree. Variance beyond thresholds triggers Understand or a Commitment." }, "ApprovalRoutingRule": { "type": "object", "properties": { "policyId": { "type": "string" }, "requiredRoles": { "type": "array", "items": { "type": "string" } }, "minQuorum": { "type": "integer", "minimum": 1 }, "expirationSeconds": { "type": "integer", "minimum": 1 }, "escalateToRoleOnTimeout": { "type": "string" } }, "additionalProperties": false, "required": [ "policyId", "requiredRoles", "minQuorum", "expirationSeconds" ], "description": "Delegation of Authority routing for a policy." } } } }