{ "openapi": "3.1.0", "info": { "title": "Creasura Agentic OS Protocol (CAOP)", "version": "0.2", "description": "Lifecycle API for the Creasura Agentic OS Protocol v0.2 (current version). Builds on v0.1.2 (additive superset). v0.2 adds two-phase outcome verification, mid-flight approval steering (APPROVE_WITH_STEERING_DELTA), hierarchical sub-agent isolation, inner-loop context compaction, and lazy capability discovery to the compact binding." }, "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" }, { "name": "Compact binding" } ], "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" } } } } } } }, "/v1/compact/pulse": { "post": { "operationId": "compact.pulse", "summary": "Pulse", "description": "OBSERVE + REVIEW. Ingests unobserved events (which may supersede facts and trigger causal invalidation) and returns the zero-upload resume_brief: unsettled leases, stale commitments, unassigned blockers, ranked next actions, and system advisories (e.g. STAGE_UPGRADE_RECOMMENDED). Resets the dead-man heartbeat. v0.2: compaction_mode selects how session state is compacted (FACT_POINTERS_ONLY, SUMMARY_WITH_LINEAGE, FULL_RAW_ARTIFACTS); the response lists capability_stubs and hydrates full input schemas only for hydrate_capability_ids (returned as data; the host’s tool list does not change). In CAOP-STAGE-1 the pulse also runs deferred Phase-2 outcome checks that are due (outcome_verifications).", "tags": [ "Compact binding" ], "x-caop-stage": [ "Observe", "Review" ], "x-caop-binding": "compact", "x-caop-mcp-tool": "caop_pulse", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PulseInput" }, "example": { "scope_goal_ids": [ "goal_payment_ledger_v2" ], "unobserved_events": [ { "source": "benchmark_ci", "summary": "November p99 benchmark: 48ms at 15k TPS", "external_ref": "ci_run_5521", "supersedes_fact_id": "fct_bench_2026_10_p99" } ], "compaction_mode": "FACT_POINTERS_ONLY", "hydrate_capability_ids": [ "github.pulls.create" ] } } } }, "responses": { "200": { "description": "Resume brief", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PulseResponse" }, "example": { "pulse_timestamp": "2026-11-05T13:00:00Z", "workspace_stage_profile": "CAOP-STAGE-1", "resume_brief": { "unsettled_leases": [], "stale_commitments": [ { "work_id": "wrk_rfc_sharding_09", "fact_id": "fct_rfc_sharding_decision", "title": "Single-Region Hash Partitioning for Payment Ledger", "epistemic_status": "RATIFIED_COMMITMENT", "freshness": "STALE_UPSTREAM_PREMISE", "invalidated_by_fact_id": "fct_bench_2026_11_p99", "summary": "p99 latency spiked from 12ms to 48ms in November benchmark run, invalidating the 15k TPS single-region assumption." } ], "unassigned_blockers": [ { "work_id": "wrk_load_test_replay", "title": "Run shadow-traffic replay on Iceberg partition", "missing_hook": "REQUIRE_EXPLICIT_OWNER" } ], "ranked_next_actions": [ { "rank": 1, "work_id": "wrk_rfc_sharding_09", "action_type": "REPLAN_STALE_COMMITMENT", "blocking_dependents_count": 3, "recommended_prompt": "Re-evaluate partition strategy given fct_bench_2026_11_p99 (48ms p99) and stage an updated commitment." }, { "rank": 2, "work_id": "wrk_load_test_replay", "action_type": "ASSIGN_PRINCIPAL_OWNER", "blocking_dependents_count": 1, "recommended_prompt": "Assign an owner_principal_id to unblock shadow-traffic replay." } ], "system_advisories": [ { "code": "STAGE_UPGRADE_RECOMMENDED", "capability_id": "gmail.users.messages.send", "message": "2 host leases expired in the past 7 days. Connect Gmail OAuth to Creasura Vault to upgrade to CAOP-STAGE-2 (KERNEL_PROXIED)." } ] }, "capability_stubs": [ { "capability_id": "github.pulls.create", "summary": "Open a pull request in a connected repository." }, { "capability_id": "metrics.query", "summary": "Query a production metric over a time window." } ], "hydrated_capabilities": [ { "capability_id": "github.pulls.create", "input_schema": { "type": "object", "required": [ "repo", "title", "head", "base" ], "properties": { "repo": { "type": "string" }, "title": { "type": "string" }, "head": { "type": "string" }, "base": { "type": "string" }, "draft": { "type": "boolean" } } } } ], "outcome_verifications": [ { "work_id": "wrk_rfc_sharding_10", "invocation_id": "inv_99512C", "sub_state": "VERIFY_PHASE_2_DEFERRED", "verification_capability_id": "metrics.query", "success_predicate": "ledger.p99_latency_ms < 20 AND ledger.tps >= 15000", "check_due_at": "2026-11-06T13:40:00Z", "status": "PENDING" } ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Invalidation subgraph too large (CAOP_413_INVALIDATION_SUBGRAPH_TOO_LARGE); nothing was applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CAOP_413_INVALIDATION_SUBGRAPH_TOO_LARGE", "message": "Superseding fct_bench_2026_10_p99 would invalidate 1,284 dependents; the limit is 500. Nothing was applied.", "retryable": false, "details": { "superseded_fact_id": "fct_bench_2026_10_p99", "affected_subgraph_size": 1284, "max_invalidation_subgraph": 500 } }, "trace_id": "trace_7c41e4" } } } } } } }, "/v1/compact/stage-work": { "post": { "operationId": "compact.stage_work", "summary": "Stage work", "description": "UNDERSTAND → COMMIT → PLAN. Evaluates Policy pre-commit hooks and minimum_attestation, then halts at approval (COMMIT_AWAITING_APPROVAL) or at EXECUTE_PENDING. A failed hook keeps the work item in CANDIDATE_PROPOSAL and returns CAOP_422_PRECOMMIT_HOOK_FAILED with details.failed_hooks; unknown or cross-workspace fact IDs return CAOP_422_PRECOMMIT_UNKNOWN_FACT_ID. Rejected with CAOP_409_UNSETTLED_EXECUTION_LEASE while a lease is open. v0.2: parent_work_id and isolation_policy stage a child work scope; it inherits the parent’s authority and can only narrow it.", "tags": [ "Compact binding" ], "x-caop-stage": [ "Understand", "Commit", "Plan" ], "x-caop-binding": "compact", "x-caop-mcp-tool": "caop_stage_work", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StageWorkInput" }, "example": { "goal_id": "goal_q4_strategy", "parent_work_id": "wrk_q4_strategy_master", "isolation_policy": { "execution_scope": "ISOLATED_SUBAGENT_CONTEXT", "return_contract": "DISTILLED_FACTS_AND_ARTIFACT_REF_ONLY", "max_token_budget": 16000, "prune_raw_traces_on_record": true, "retention_policy": "retain_30_days" }, "understanding": { "intent_summary": "Benchmark vendor latency and pricing for the Q4 strategy RFC.", "derived_facts": [] }, "commitment": { "title": "Market benchmark matrix", "rationale": "The parent RFC needs verified latency and pricing comparisons.", "owner_principal_id": "user_123", "reversible": true }, "plan_steps": [ { "step_index": 1, "capability_id": "research.web", "arguments": { "query": "vendor p99 latency published benchmarks" } } ] } } } }, "responses": { "200": { "description": "Staged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StageWorkResult" }, "example": { "work_id": "wrk_rfc_sharding_10", "lifecycle_stage": "COMMIT", "sub_state": "COMMIT_AWAITING_APPROVAL", "epistemic_status": "CANDIDATE_PROPOSAL" } } } }, "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": "Unsettled execution lease (CAOP_409_UNSETTLED_EXECUTION_LEASE), invalid transition, or state version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CAOP_409_UNSETTLED_EXECUTION_LEASE", "message": "Settle the open execution lease (inv_99481A) via caop_settle_receipt before staging or dispatching new work.", "retryable": false, "details": { "blocking_work_id": "wrk_01J9Z8K4M2", "blocking_invocation_id": "inv_99481A", "required_nonce": "nnc_884920_x9" } }, "trace_id": "trace_7c41e3" } } } }, "422": { "description": "Pre-commit hook failed (CAOP_422_PRECOMMIT_*) or receipt nonce / artifact mismatch (CAOP_422_VERIFY_ARTIFACT_MISMATCH)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CAOP_422_PRECOMMIT_HOOK_FAILED", "message": "One or more Policy pre-commit hooks failed. The work item remains in CANDIDATE_PROPOSAL.", "retryable": false, "details": { "failed_hooks": [ { "hook_id": "REQUIRE_EXPLICIT_OWNER", "error_code": "CAOP_422_PRECOMMIT_MISSING_OWNER", "remediation": "Specify commitment.owner_principal_id (or ask the user to assign an owner) before committing this work plan." } ] } }, "trace_id": "trace_7c41e2" } } } } } } }, "/v1/compact/dispatch-work": { "post": { "operationId": "compact.dispatch_work", "summary": "Dispatch work", "description": "COMMIT resolution → EXECUTE. HOST_DELEGATED: enters EXECUTE_DISPATCHED and returns the anti-termination DispatchDirective with a single-use nonce. KERNEL_PROXIED: runs the OAuth proxy call and auto-folds VERIFY + RECORD, returning a SettlementResult. Rejected with CAOP_409_UNSETTLED_EXECUTION_LEASE while a lease is open. v0.2: APPROVE_WITH_STEERING_DELTA binds the approval to the patched plan: the kernel applies steering_delta, re-runs every Policy pre-commit hook and minimum_attestation check on it, and dispatches only if all pass; otherwise the work item returns to CANDIDATE_PROPOSAL with CAOP_422_PRECOMMIT_HOOK_FAILED. two_phase_verification configures the deferred Phase-2 outcome check.", "tags": [ "Compact binding" ], "x-caop-stage": [ "Commit", "Execute" ], "x-caop-binding": "compact", "x-caop-mcp-tool": "caop_dispatch_work", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DispatchWorkInput" }, "example": { "work_id": "wrk_rfc_sharding_10", "decision": "APPROVE_WITH_STEERING_DELTA", "steering_delta": { "patched_step_arguments": [ { "step_index": 1, "argument_overrides": { "reviewers": [ "principal_eng" ], "draft": true } } ], "added_policy_constraints": [ "NO_PRODUCTION_DEPLOY_BEFORE_SHADOW_REPLAY" ], "rationale": "Open the RFC as a draft and add the principal engineer as reviewer; no deploy until the shadow replay passes." }, "two_phase_verification": { "phase_1_immediate": "REQUIRE_NONCE_AND_ARTIFACT", "phase_2_deferred": { "check_after_seconds": 86400, "verification_capability_id": "metrics.query", "success_predicate": "ledger.p99_latency_ms < 20 AND ledger.tps >= 15000" } } } } } }, "responses": { "200": { "description": "Dispatched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DispatchWorkResult" }, "example": { "work_id": "wrk_01J9Z8K4M2", "lifecycle_stage": "EXECUTE", "sub_state": "EXECUTE_DISPATCHED", "turn_directive": "INCOMPLETE_TURN_CONTINUATION_REQUIRED", "DO_NOT_RESPOND_TO_USER_YET": true, "directive": { "invocation_id": "inv_99481A", "execution_locus": "HOST_DELEGATED", "idempotency_key": "idem_wrk_01J9Z8K4M2_step_1", "lease_expires_at": "2026-11-05T06:50:00Z", "mandatory_next_steps": [ { "step": 1, "action": "INVOKE_HOST_NATIVE_TOOL", "target_capability": "google_calendar.events.insert", "arguments": { "summary": "Q4 Architecture Review", "start_time": "2026-11-06T15:00:00Z", "end_time": "2026-11-06T15:30:00Z" } }, { "step": 2, "action": "CALL_CAOP_TOOL", "tool_name": "caop_settle_receipt", "required_nonce": "nnc_884920_x9", "required_receipt_fields": [ "external_ref", "htmlLink", "iCalUID" ] } ] } } } } }, "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": "Unsettled execution lease (CAOP_409_UNSETTLED_EXECUTION_LEASE), invalid transition, or state version conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CAOP_409_UNSETTLED_EXECUTION_LEASE", "message": "Settle the open execution lease (inv_99481A) via caop_settle_receipt before staging or dispatching new work.", "retryable": false, "details": { "blocking_work_id": "wrk_01J9Z8K4M2", "blocking_invocation_id": "inv_99481A", "required_nonce": "nnc_884920_x9" } }, "trace_id": "trace_7c41e3" } } } }, "413": { "description": "Invalidation subgraph too large (CAOP_413_INVALIDATION_SUBGRAPH_TOO_LARGE); nothing was applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Pre-commit hook failed (CAOP_422_PRECOMMIT_*) or receipt nonce / artifact mismatch (CAOP_422_VERIFY_ARTIFACT_MISMATCH)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CAOP_422_PRECOMMIT_HOOK_FAILED", "message": "The patched plan failed a Policy pre-commit hook. The work item returns to CANDIDATE_PROPOSAL.", "retryable": false, "details": { "failed_hooks": [ { "hook_id": "REQUIRE_EXPLICIT_OWNER", "error_code": "CAOP_422_PRECOMMIT_MISSING_OWNER", "remediation": "The steering delta cleared commitment.owner_principal_id. Keep an explicit owner and dispatch again." } ] } }, "trace_id": "trace_7c41e7" } } } } } } }, "/v1/compact/settle-receipt": { "post": { "operationId": "compact.settle_receipt", "summary": "Settle a receipt", "description": "VERIFY → RECORD → REVIEW. Verifies the nonce and required_receipt_fields, writes a HOST_ASSERTED fact, and unlocks the thread. For KERNEL_PROXIED work it is used only for manual USER_CONFIRMED overrides. v0.2: with a phase_2_deferred check, Phase 1 records the receipt as facts with their attestation tier and returns RECORDED_AWAITING_OUTCOME_VERIFY; the commitment stays open until the deferred check passes. A child work scope returns distilled_return_payload; its raw traces are pruned from the active context, not from provenance.", "tags": [ "Compact binding" ], "x-caop-stage": [ "Verify", "Record", "Review" ], "x-caop-binding": "compact", "x-caop-mcp-tool": "caop_settle_receipt", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettleReceiptInput" }, "example": { "work_id": "wrk_sub_market_scan", "invocation_id": "inv_99481A", "idempotency_key": "idem_wrk_01J9Z8K4M2_step_1", "nonce": "nnc_884920_x9", "status": "SUCCEEDED", "external_ref": "gcal_evt_8839201", "raw_output": { "external_ref": "gcal_evt_8839201", "htmlLink": "https://www.google.com/calendar/event?eid=ODgzOTIwMQ", "iCalUID": "8839201@google.com" }, "review_outcome": "GOAL_SATISFIED", "distilled_return_payload": { "artifact_ref": "art_market_benchmark_matrix_v1", "promoted_fact_ids": [ "fct_competitor_latency_p99", "fct_pricing_tier_delta" ], "compacted_summary": "Audited 18 vendor specs; isolated 2 verified latency bottlenecks linked to parent RFC.", "trace_hash": "sha256:9f2c4e7a1b03d58e6c2f9a4b7d1e0c35a8b6f2d4e9c17a0b3d5f8e2c6a4b19d7" } } } } }, "responses": { "200": { "description": "Settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementResult" }, "example": { "work_id": "wrk_rfc_sharding_10", "invocation_id": "inv_99512C", "lifecycle_stage": "RECORD", "sub_state": "RECORDED_AWAITING_OUTCOME_VERIFY", "attestation": "HOST_ASSERTED", "fact_ids": [ "fct_77311D" ], "thread_unlocked": true, "outcome_verification": { "work_id": "wrk_rfc_sharding_10", "invocation_id": "inv_99512C", "sub_state": "VERIFY_PHASE_2_DEFERRED", "verification_capability_id": "metrics.query", "success_predicate": "ledger.p99_latency_ms < 20 AND ledger.tps >= 15000", "check_due_at": "2026-11-06T13:40:00Z", "status": "PENDING" } } } } }, "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" } } } }, "413": { "description": "Invalidation subgraph too large (CAOP_413_INVALIDATION_SUBGRAPH_TOO_LARGE); nothing was applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Pre-commit hook failed (CAOP_422_PRECOMMIT_*) or receipt nonce / artifact mismatch (CAOP_422_VERIFY_ARTIFACT_MISMATCH)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "CAOP_422_VERIFY_ARTIFACT_MISMATCH", "message": "Receipt raw_output is missing required_receipt_fields: iCalUID.", "retryable": false, "details": { "work_id": "wrk_01J9Z8K4M2", "invocation_id": "inv_99481A", "missing_fields": [ "iCalUID" ] } }, "trace_id": "trace_7c41e5" } } } } } } } }, "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." }, "minimum_attestation": { "$ref": "#/components/schemas/AttestationTier" }, "pre_commit_hooks": { "type": "array", "items": { "$ref": "#/components/schemas/PreCommitHook" } } }, "additionalProperties": false, "required": [ "id", "scope", "condition", "effect", "version", "enforcement" ], "description": "A constraint governing execution. v0.1.2 adds minimum_attestation and pre_commit_hooks." }, "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" ] }, "execution_locus": { "$ref": "#/components/schemas/ExecutionLocus" }, "auth_custodian": { "$ref": "#/components/schemas/AuthCustodian" }, "receipt_lease_seconds": { "type": "integer", "minimum": 1, "description": "Maximum duration a HOST_DELEGATED invocation may remain uncommitted in EXECUTE_DISPATCHED before transitioning to EXECUTE_EXPIRED." }, "required_receipt_fields": { "type": "array", "items": { "type": "string" }, "description": "Provider-specific receipt verification keys that MUST be present in raw_output during VERIFY." }, "promotion_policy": { "$ref": "#/components/schemas/PromotionPolicy" } }, "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. v0.1.2 adds execution_locus, auth_custodian, receipt_lease_seconds, required_receipt_fields and promotion_policy." }, "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", "CAOP_409_UNSETTLED_EXECUTION_LEASE", "CAOP_413_INVALIDATION_SUBGRAPH_TOO_LARGE", "CAOP_422_VERIFY_ARTIFACT_MISMATCH", "CAOP_422_PRECOMMIT_HOOK_FAILED", "CAOP_422_PRECOMMIT_MISSING_OWNER", "CAOP_422_PRECOMMIT_MISSING_LINEAGE", "CAOP_422_PRECOMMIT_STALE_DEPENDENCY", "CAOP_422_PRECOMMIT_UNKNOWN_FACT_ID", "STAGE_UPGRADE_RECOMMENDED" ] }, "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" ], "description": "Standard error envelope (§7.1). v0.1.2 adds CAOP_409_UNSETTLED_EXECUTION_LEASE (HTTP 409), CAOP_413_INVALIDATION_SUBGRAPH_TOO_LARGE (HTTP 413), CAOP_422_VERIFY_ARTIFACT_MISMATCH and the CAOP_422_PRECOMMIT_* codes (HTTP 422; CAOP_422_PRECOMMIT_HOOK_FAILED carries details.failed_hooks), and STAGE_UPGRADE_RECOMMENDED (advisory code, used in resume_brief.system_advisories)." }, "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." }, "LoopDriver": { "type": "string", "enum": [ "CLIENT_POLLED", "KERNEL_MANAGED" ], "description": "Who drives the trigger loop: the conversational host (CLIENT_POLLED) or the Creasura kernel (KERNEL_MANAGED)." }, "ExecutionLocus": { "type": "string", "enum": [ "HOST_DELEGATED", "KERNEL_PROXIED" ], "description": "Whether EXECUTE returns a delegation directive to the calling host or executes server-side." }, "AuthCustodian": { "type": "string", "enum": [ "CLIENT_SESSION", "CREASURA_VAULT" ], "description": "Whether downstream OAuth tokens are held by the host client or stored in Creasura's vault." }, "AttestationTier": { "type": "string", "enum": [ "HOST_ASSERTED", "KERNEL_ATTESTED", "USER_CONFIRMED" ], "description": "provenance.attestation: how the execution evidence behind a fact was obtained. Field presence is evidence, not proof; hence HOST_ASSERTED." }, "ConformanceProfileId": { "type": "string", "enum": [ "CAOP-STAGE-1", "CAOP-STAGE-2", "CAOP-STAGE-3" ] }, "ConformanceProfile": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ConformanceProfileId" }, "loop_driver": { "$ref": "#/components/schemas/LoopDriver" }, "auth_custodian": { "$ref": "#/components/schemas/AuthCustodian" }, "execution_locus": { "$ref": "#/components/schemas/ExecutionLocus" }, "max_attestation": { "$ref": "#/components/schemas/AttestationTier" }, "v0_1_conformance_level": { "type": "string", "enum": [ "L2", "L3" ], "description": "CAOP-STAGE-1 and CAOP-STAGE-2 are variants of L2 (Stateful); CAOP-STAGE-3 corresponds to L3 (Autonomous)." } }, "additionalProperties": false, "required": [ "id", "loop_driver", "auth_custodian", "execution_locus", "max_attestation", "v0_1_conformance_level" ], "description": "A runtime conformance profile. Advancing from Stage 1 to Stage 3 requires no breaking change to Goals, the eight-stage lifecycle, or bitemporal State queries." }, "PromotionPolicy": { "type": "object", "properties": { "max_expired_leases_before_stage2_prompt": { "type": "integer", "minimum": 1 }, "rolling_window_days": { "type": "integer", "minimum": 1 } }, "additionalProperties": false, "required": [ "max_expired_leases_before_stage2_prompt", "rolling_window_days" ], "description": "Threshold at which repeated EXECUTE_EXPIRED leases trigger a recommendation to promote a capability from HOST_DELEGATED (Stage 1) to KERNEL_PROXIED (Stage 2)." }, "CapabilityRegistration": { "type": "object", "properties": { "capability_id": { "type": "string" }, "version": { "type": "string" }, "execution_locus": { "$ref": "#/components/schemas/ExecutionLocus" }, "auth_custodian": { "$ref": "#/components/schemas/AuthCustodian" }, "receipt_lease_seconds": { "type": "integer", "minimum": 1, "description": "Maximum duration a HOST_DELEGATED invocation may remain uncommitted in EXECUTE_DISPATCHED before transitioning to EXECUTE_EXPIRED." }, "required_receipt_fields": { "type": "array", "items": { "type": "string" }, "description": "Provider-specific receipt verification keys that MUST be present in raw_output during VERIFY." }, "promotion_policy": { "$ref": "#/components/schemas/PromotionPolicy" }, "input_schema": { "type": "object" }, "output_schema": { "type": "object" } }, "additionalProperties": false, "required": [ "capability_id", "version", "execution_locus", "auth_custodian", "receipt_lease_seconds", "required_receipt_fields", "promotion_policy" ], "description": "A capability as registered in the v0.1.2 Capability API. It MUST declare its execution locus, credential custodian, lease timeout, provider-specific receipt verification keys, and Stage-2 promotion thresholds." }, "EpistemicStatus": { "type": "string", "enum": [ "CANDIDATE_PROPOSAL", "RATIFIED_COMMITMENT", "VERIFIED_FACT" ], "description": "Adoption: CANDIDATE_PROPOSAL (UNDERSTAND or PLAN; excluded from default truth queries until ratified) → RATIFIED_COMMITMENT (passed pre-commit hooks and approval at COMMIT) → VERIFIED_FACT (promoted at RECORD once evidence passes VERIFY). Freshness is tracked separately." }, "Freshness": { "type": "string", "enum": [ "CURRENT", "STALE_UPSTREAM_PREMISE" ], "description": "Freshness, separate from adoption. STALE_UPSTREAM_PREMISE is assigned by the kernel when a required premise has no remaining CURRENT support. A stale VERIFIED_FACT keeps epistemic_status VERIFIED_FACT. Default truth queries flag, but do not hide, stale entries." }, "DependsOnAlternatives": { "type": "array", "items": { "type": "array", "items": { "type": "string" } }, "description": "Groups of interchangeable supporting Fact IDs. Each inner array is one required premise; it stays supported while ANY member is CURRENT." }, "InvalidationContext": { "type": "object", "properties": { "invalidated_by_fact_id": { "type": "string" }, "invalidated_at": { "type": "string", "format": "date-time" }, "reason": { "type": "string" } }, "additionalProperties": false, "required": [ "invalidated_by_fact_id", "invalidated_at" ], "description": "Why a dependent lost CURRENT support. Only freshness and invalidation_context change on dependents." }, "FactProvenance": { "type": "object", "properties": { "work_id": { "type": "string" }, "invocation_id": { "type": "string" }, "execution_locus": { "$ref": "#/components/schemas/ExecutionLocus" }, "attestation": { "$ref": "#/components/schemas/AttestationTier" }, "verified_fields": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "required": [ "work_id", "execution_locus", "attestation" ], "description": "Execution provenance of a fact. The attestation tier is immutable." }, "BitemporalFact": { "type": "object", "properties": { "fact_id": { "type": "string" }, "subject": { "$ref": "#/components/schemas/EntityRef" }, "predicate": { "type": "string" }, "object": {}, "epistemic_status": { "$ref": "#/components/schemas/EpistemicStatus" }, "freshness": { "$ref": "#/components/schemas/Freshness" }, "depends_on_fact_ids": { "type": "array", "items": { "type": "string" }, "description": "Upstream Fact IDs; each entry is a required premise on its own." }, "depends_on_alternatives": { "$ref": "#/components/schemas/DependsOnAlternatives" }, "invalidation_context": { "oneOf": [ { "$ref": "#/components/schemas/InvalidationContext" }, { "type": "null" } ] }, "valid_time": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false, "required": [ "start" ] }, "transaction_time": { "type": "object", "properties": { "recorded_at": { "type": "string", "format": "date-time" }, "superseded_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false, "required": [ "recorded_at" ] }, "provenance": { "$ref": "#/components/schemas/FactProvenance" } }, "additionalProperties": false, "required": [ "fact_id", "subject", "predicate", "object", "epistemic_status", "freshness", "depends_on_fact_ids", "valid_time", "transaction_time" ], "description": "A bitemporal fact (valid_time and transaction_time) with explicit upstream lineage and execution provenance. Superseded facts and their history are never rewritten." }, "StateConfig": { "type": "object", "properties": { "workspace_id": { "type": "string" }, "max_invalidation_subgraph": { "type": "integer", "minimum": 1, "description": "Largest affected subgraph one update may invalidate. Larger updates are rejected before commit with CAOP_413_INVALIDATION_SUBGRAPH_TOO_LARGE; nothing is partially applied." } }, "additionalProperties": false, "required": [ "workspace_id", "max_invalidation_subgraph" ], "description": "Workspace State API limits for synchronous causal invalidation." }, "PreCommitHook": { "type": "object", "properties": { "hook_id": { "type": "string", "description": "e.g. REQUIRE_EXPLICIT_OWNER, REQUIRE_EVIDENCE_LINEAGE, BLOCK_STALE_PREMISES" }, "target_path": { "type": "string", "description": "Path into the staged work, e.g. commitment.owner_principal_id" }, "condition": { "type": "string", "description": "e.g. NON_EMPTY_PRINCIPAL_REF, NON_EMPTY_ARRAY, ALL_UPSTREAM_FACTS_VERIFIED_ACTIVE (every upstream fact is VERIFIED_FACT with freshness CURRENT)" }, "error_code": { "type": "string", "description": "A CAOP_422_PRECOMMIT_* code reported in failed_hooks" } }, "additionalProperties": false, "required": [ "hook_id", "target_path", "condition", "error_code" ], "description": "A deterministic check evaluated at COMMIT before a plan may reach EXECUTE_PENDING or request approval." }, "PolicyRegistration": { "type": "object", "properties": { "policy_id": { "type": "string" }, "scope_goal_types": { "type": "array", "items": { "type": "string" } }, "minimum_attestation": { "$ref": "#/components/schemas/AttestationTier" }, "require_human_approval": { "type": "boolean" }, "pre_commit_hooks": { "type": "array", "items": { "$ref": "#/components/schemas/PreCommitHook" } } }, "additionalProperties": false, "required": [ "policy_id", "pre_commit_hooks" ], "description": "A Policy as registered in the v0.1.2 Policy API." }, "FailedHook": { "type": "object", "properties": { "hook_id": { "type": "string" }, "error_code": { "type": "string" }, "remediation": { "type": "string" } }, "additionalProperties": false, "required": [ "hook_id", "error_code", "remediation" ] }, "ExecuteSubState": { "type": "string", "enum": [ "EXECUTE_PENDING", "EXECUTE_DISPATCHED", "EXECUTE_COMPLETED", "EXECUTE_EXPIRED", "EXECUTE_FAILED" ], "description": "Sub-states of the EXECUTE lifecycle stage. They refine, not replace, the v0.1 execution states: EXECUTE_PENDING ↔ READY; EXECUTE_DISPATCHED ↔ RUNNING (host-delegated); EXECUTE_COMPLETED → VERIFYING; EXECUTE_EXPIRED ↔ EXPIRED; EXECUTE_FAILED ↔ FAILED." }, "CommitSubState": { "type": "string", "enum": [ "COMMIT_AWAITING_APPROVAL" ], "description": "Sub-state of the COMMIT lifecycle stage: pre-commit hooks passed, human approval required before dispatch. Maps to WAITING_APPROVAL / POLICY_APPROVAL_REQUIRED." }, "DispatchStep": { "type": "object", "properties": { "step": { "type": "integer", "minimum": 1 }, "action": { "type": "string", "enum": [ "INVOKE_HOST_NATIVE_TOOL", "CALL_CAOP_TOOL" ] }, "target_capability": { "type": "string" }, "arguments": { "type": "object" }, "tool_name": { "type": "string" }, "required_nonce": { "type": "string" }, "required_receipt_fields": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "required": [ "step", "action" ], "description": "One mandatory step the host must perform in the same turn." }, "DispatchDirective": { "type": "object", "properties": { "work_id": { "type": "string" }, "lifecycle_stage": { "type": "string", "enum": [ "EXECUTE" ] }, "sub_state": { "$ref": "#/components/schemas/ExecuteSubState" }, "turn_directive": { "type": "string", "enum": [ "INCOMPLETE_TURN_CONTINUATION_REQUIRED" ] }, "DO_NOT_RESPOND_TO_USER_YET": { "type": "boolean" }, "directive": { "type": "object", "properties": { "invocation_id": { "type": "string" }, "execution_locus": { "$ref": "#/components/schemas/ExecutionLocus" }, "idempotency_key": { "type": "string" }, "lease_expires_at": { "type": "string", "format": "date-time" }, "mandatory_next_steps": { "type": "array", "items": { "$ref": "#/components/schemas/DispatchStep" } } }, "additionalProperties": false, "required": [ "invocation_id", "execution_locus", "idempotency_key", "lease_expires_at", "mandatory_next_steps" ] } }, "additionalProperties": false, "required": [ "work_id", "lifecycle_stage", "sub_state", "turn_directive", "DO_NOT_RESPOND_TO_USER_YET", "directive" ], "description": "Normative Stage-1 dispatch response (anti-termination envelope). turn_directive and DO_NOT_RESPOND_TO_USER_YET are instructions to the host model; the enforceable guarantee is the lease lock (CAOP_409_UNSETTLED_EXECUTION_LEASE)." }, "GoalPulseSLA": { "type": "object", "properties": { "goal_id": { "type": "string" }, "loop_driver": { "$ref": "#/components/schemas/LoopDriver" }, "expected_pulse_interval_seconds": { "type": "integer", "minimum": 1 }, "grace_period_seconds": { "type": "integer", "minimum": 0 }, "last_pulse_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "required": [ "goal_id", "loop_driver", "expected_pulse_interval_seconds", "grace_period_seconds" ], "description": "Heartbeat SLA for a CLIENT_POLLED Goal (the dead-man’s switch). Requires a kernel-side timer and an out-of-band notification channel." }, "PulseInput": { "type": "object", "properties": { "scope_goal_ids": { "type": "array", "items": { "type": "string" } }, "unobserved_events": { "type": "array", "items": { "type": "object", "required": [ "source", "summary" ], "properties": { "source": { "type": "string" }, "summary": { "type": "string" }, "external_ref": { "type": "string" }, "supersedes_fact_id": { "type": "string" } } } }, "compaction_mode": { "$ref": "#/components/schemas/CompactionMode" }, "hydrate_capability_ids": { "type": "array", "items": { "type": "string" }, "description": "Lazy Capability Discovery: Pass specific capability IDs from the stub directory to load their full JSON input schemas." } }, "description": "v0.2 adds compaction_mode and hydrate_capability_ids (published inputSchema: PulseInputV02)." }, "StageWorkInput": { "type": "object", "required": [ "goal_id", "understanding", "commitment", "plan_steps" ], "properties": { "goal_id": { "type": "string" }, "supersedes_work_id": { "type": "string", "description": "Optional ID of a STALE_UPSTREAM_PREMISE work item being replaced." }, "understanding": { "type": "object", "required": [ "intent_summary", "derived_facts" ], "properties": { "intent_summary": { "type": "string" }, "derived_facts": { "type": "array", "items": { "type": "object", "required": [ "subject", "predicate", "object" ], "properties": { "subject": { "type": "string" }, "predicate": { "type": "string" }, "object": { "type": "object" }, "depends_on_fact_ids": { "type": "array", "items": { "type": "string" }, "description": "Upstream Fact IDs that this derived fact or decision relies upon. Omit if unknown; the REQUIRE_EVIDENCE_LINEAGE hook will reject commit and the host must ask the user." }, "depends_on_alternatives": { "type": "array", "items": { "type": "array", "items": { "type": "string" } }, "description": "Optional groups of interchangeable supporting Fact IDs. The premise stays supported while any member is CURRENT." }, "valid_from": { "type": "string", "format": "date-time" } } } } } }, "commitment": { "type": "object", "required": [ "title", "rationale", "reversible" ], "properties": { "title": { "type": "string" }, "rationale": { "type": "string" }, "owner_principal_id": { "type": "string", "description": "Explicit human or agent principal responsible for this commitment. Omit if unknown; the REQUIRE_EXPLICIT_OWNER hook will reject commit and the host must ask the user." }, "due_at": { "type": "string", "format": "date-time" }, "reversible": { "type": "boolean" } } }, "plan_steps": { "type": "array", "items": { "type": "object", "required": [ "step_index", "capability_id", "arguments" ], "properties": { "step_index": { "type": "integer" }, "capability_id": { "type": "string" }, "arguments": { "type": "object" } } } }, "parent_work_id": { "type": "string", "description": "Stages this work as a child work scope of the given parent (hierarchical sub-agent isolation)." }, "isolation_policy": { "$ref": "#/components/schemas/IsolationPolicy" } }, "description": "v0.2 adds parent_work_id and isolation_policy for child work scopes." }, "DispatchWorkInput": { "type": "object", "required": [ "work_id", "decision" ], "properties": { "work_id": { "type": "string" }, "decision": { "type": "string", "enum": [ "APPROVE_AND_DISPATCH", "APPROVE_WITH_STEERING_DELTA", "REJECT_WORK" ] }, "approval_note": { "type": "string" }, "steering_delta": { "$ref": "#/components/schemas/SteeringDelta" }, "two_phase_verification": { "$ref": "#/components/schemas/TwoPhaseVerification" } }, "description": "v0.2 adds APPROVE_WITH_STEERING_DELTA, steering_delta and two_phase_verification (published inputSchema: DispatchWorkInputV02)." }, "SettleReceiptInput": { "type": "object", "required": [ "work_id", "invocation_id", "idempotency_key", "nonce", "status" ], "properties": { "work_id": { "type": "string" }, "invocation_id": { "type": "string" }, "idempotency_key": { "type": "string" }, "nonce": { "type": "string", "description": "Exact required_nonce returned by caop_dispatch_work." }, "status": { "type": "string", "enum": [ "SUCCEEDED", "FAILED", "USER_CONFIRMED_OVERRIDE" ] }, "external_ref": { "type": "string" }, "raw_output": { "type": "object", "description": "Raw JSON output from the host native tool containing all required_receipt_fields." }, "error_detail": { "type": "string" }, "review_outcome": { "type": "string", "enum": [ "GOAL_SATISFIED", "PARTIAL_PROGRESS", "REPLAN_REQUIRED" ] }, "distilled_return_payload": { "$ref": "#/components/schemas/DistilledReturnPayload" } }, "description": "v0.2 adds distilled_return_payload, returned by a child work scope when it completes RECORD." }, "OpenLease": { "type": "object", "properties": { "work_id": { "type": "string" }, "invocation_id": { "type": "string" }, "sub_state": { "$ref": "#/components/schemas/ExecuteSubState" }, "required_nonce": { "type": "string" }, "lease_expires_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "required": [ "work_id", "invocation_id", "sub_state", "required_nonce" ], "description": "An unsettled EXECUTE_DISPATCHED or EXECUTE_EXPIRED invocation." }, "StaleCommitment": { "type": "object", "properties": { "work_id": { "type": "string" }, "fact_id": { "type": "string" }, "title": { "type": "string" }, "epistemic_status": { "$ref": "#/components/schemas/EpistemicStatus" }, "freshness": { "$ref": "#/components/schemas/Freshness" }, "invalidated_by_fact_id": { "type": "string" }, "summary": { "type": "string" } }, "additionalProperties": false, "required": [ "work_id", "fact_id", "title", "epistemic_status", "freshness" ], "description": "A commitment whose freshness is STALE_UPSTREAM_PREMISE; it keeps its adoption status." }, "UnassignedBlocker": { "type": "object", "properties": { "work_id": { "type": "string" }, "title": { "type": "string" }, "missing_hook": { "type": "string" } }, "additionalProperties": false, "required": [ "work_id", "title", "missing_hook" ] }, "RankedNextAction": { "type": "object", "properties": { "rank": { "type": "integer", "minimum": 1 }, "work_id": { "type": "string" }, "action_type": { "type": "string" }, "blocking_dependents_count": { "type": "integer", "minimum": 0 }, "recommended_prompt": { "type": "string" } }, "additionalProperties": false, "required": [ "rank", "work_id", "action_type" ] }, "SystemAdvisory": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "STAGE_UPGRADE_RECOMMENDED" ] }, "capability_id": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false, "required": [ "code", "message" ] }, "ResumeBrief": { "type": "object", "properties": { "unsettled_leases": { "type": "array", "items": { "$ref": "#/components/schemas/OpenLease" } }, "stale_commitments": { "type": "array", "items": { "$ref": "#/components/schemas/StaleCommitment" } }, "unassigned_blockers": { "type": "array", "items": { "$ref": "#/components/schemas/UnassignedBlocker" } }, "ranked_next_actions": { "type": "array", "items": { "$ref": "#/components/schemas/RankedNextAction" } }, "system_advisories": { "type": "array", "items": { "$ref": "#/components/schemas/SystemAdvisory" } } }, "additionalProperties": false, "required": [ "unsettled_leases", "stale_commitments", "unassigned_blockers", "ranked_next_actions", "system_advisories" ], "description": "Deterministic, ranked delta brief returned at the start of a session, without file uploads or chat history reconstruction." }, "PulseResponse": { "type": "object", "properties": { "pulse_timestamp": { "type": "string", "format": "date-time" }, "workspace_stage_profile": { "$ref": "#/components/schemas/ConformanceProfileId" }, "resume_brief": { "$ref": "#/components/schemas/ResumeBrief" }, "capability_stubs": { "type": "array", "items": { "$ref": "#/components/schemas/CapabilityStub" } }, "hydrated_capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/HydratedCapability" } }, "outcome_verifications": { "type": "array", "items": { "$ref": "#/components/schemas/OutcomeVerification" } } }, "additionalProperties": false, "required": [ "pulse_timestamp", "workspace_stage_profile", "resume_brief" ], "description": "Normative caop_pulse response payload. v0.2 adds capability_stubs, hydrated_capabilities and outcome_verifications." }, "StageWorkResult": { "type": "object", "properties": { "work_id": { "type": "string" }, "lifecycle_stage": { "type": "string", "enum": [ "COMMIT", "EXECUTE" ] }, "sub_state": { "type": "string", "enum": [ "COMMIT_AWAITING_APPROVAL", "EXECUTE_PENDING" ] }, "epistemic_status": { "$ref": "#/components/schemas/EpistemicStatus" } }, "additionalProperties": false, "required": [ "work_id", "lifecycle_stage", "sub_state" ], "description": "UNDERSTAND → COMMIT → PLAN: pre-commit hooks passed; halted at approval (COMMIT_AWAITING_APPROVAL) or at EXECUTE_PENDING." }, "SettlementResult": { "type": "object", "properties": { "work_id": { "type": "string" }, "invocation_id": { "type": "string" }, "lifecycle_stage": { "type": "string", "enum": [ "RECORD", "REVIEW" ] }, "attestation": { "$ref": "#/components/schemas/AttestationTier" }, "fact_ids": { "type": "array", "items": { "type": "string" } }, "thread_unlocked": { "type": "boolean" }, "review_outcome": { "type": "string", "enum": [ "GOAL_SATISFIED", "PARTIAL_PROGRESS", "REPLAN_REQUIRED" ] }, "sub_state": { "$ref": "#/components/schemas/RecordSubState" }, "outcome_verification": { "$ref": "#/components/schemas/OutcomeVerification" } }, "additionalProperties": false, "required": [ "work_id", "invocation_id", "lifecycle_stage", "attestation", "thread_unlocked" ], "description": "Result of VERIFY → RECORD (→ REVIEW): receipt verified, facts recorded with their attestation tier, thread lease released. v0.2: with a phase_2_deferred check, settlement records the receipt and returns sub_state RECORDED_AWAITING_OUTCOME_VERIFY." }, "DispatchWorkResult": { "oneOf": [ { "$ref": "#/components/schemas/DispatchDirective" }, { "$ref": "#/components/schemas/SettlementResult" } ], "description": "HOST_DELEGATED: the anti-termination DispatchDirective. KERNEL_PROXIED: executed via the vault with VERIFY + RECORD auto-folded, returning a SettlementResult." }, "SteeringDelta": { "type": "object", "description": "Non-destructive mid-flight overrides applied before EXECUTE without aborting the work lifecycle.", "properties": { "patched_step_arguments": { "type": "array", "items": { "type": "object", "required": [ "step_index", "argument_overrides" ], "properties": { "step_index": { "type": "integer" }, "argument_overrides": { "type": "object" } } } }, "added_policy_constraints": { "type": "array", "items": { "type": "string" } }, "rationale": { "type": "string" } } }, "Phase2DeferredCheck": { "type": "object", "required": [ "check_after_seconds", "verification_capability_id", "success_predicate" ], "properties": { "check_after_seconds": { "type": "integer" }, "verification_capability_id": { "type": "string" }, "success_predicate": { "type": "string" } } }, "TwoPhaseVerification": { "type": "object", "properties": { "phase_1_immediate": { "type": "string", "enum": [ "REQUIRE_NONCE_AND_ARTIFACT" ] }, "phase_2_deferred": { "$ref": "#/components/schemas/Phase2DeferredCheck" } } }, "VerifySubState": { "type": "string", "enum": [ "VERIFY_PHASE_1_IMMEDIATE", "VERIFY_PHASE_2_DEFERRED" ], "description": "Sub-states of the VERIFY lifecycle stage. VERIFY_PHASE_1_IMMEDIATE validates the execution receipt (nonce and artifact); VERIFY_PHASE_2_DEFERRED evaluates success_predicate with verification_capability_id once check_after_seconds has elapsed. Both map to the v0.1 VERIFYING state." }, "RecordSubState": { "type": "string", "enum": [ "RECORDED_AWAITING_OUTCOME_VERIFY" ], "description": "Receipts recorded in Phase 1 are written as facts with their attestation tier, and the commitment stays open until the deferred Phase-2 check passes. Maps to the v0.1 VERIFYING state: the execution reaches COMPLETED only after that check passes. In CAOP-STAGE-1 the check runs on the next caop_pulse after check_after_seconds, so it depends on the host pulsing." }, "OutcomeVerification": { "type": "object", "properties": { "work_id": { "type": "string" }, "invocation_id": { "type": "string" }, "sub_state": { "$ref": "#/components/schemas/VerifySubState" }, "verification_capability_id": { "type": "string" }, "success_predicate": { "type": "string" }, "check_due_at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "PENDING", "PASSED", "FAILED" ] }, "fact_ids": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false, "required": [ "work_id", "sub_state", "verification_capability_id", "success_predicate", "check_due_at", "status" ], "description": "A deferred Phase-2 outcome check as reported by caop_pulse." }, "IsolationPolicy": { "type": "object", "properties": { "execution_scope": { "type": "string", "enum": [ "ISOLATED_SUBAGENT_CONTEXT" ] }, "return_contract": { "type": "string", "enum": [ "DISTILLED_FACTS_AND_ARTIFACT_REF_ONLY" ] }, "max_token_budget": { "type": "integer", "minimum": 1, "description": "Enforced by the kernel only when it drives the model (CAOP-STAGE-3); advisory in CAOP-STAGE-1." }, "prune_raw_traces_on_record": { "type": "boolean" }, "trace_hash": { "type": "string", "description": "Content hash of the pruned raw trace, e.g. \"sha256:\". Promoted facts keep it as part of their provenance pointer." }, "retention_policy": { "type": "string", "description": "Declared retention policy under which raw traces MAY be deleted, e.g. \"retain_30_days\". Without one, pruned traces leave the active context but are not deleted." } }, "additionalProperties": false, "required": [ "execution_scope", "return_contract" ], "description": "How a child work scope is isolated from its parent. A child inherits the parent’s authority and can only narrow it." }, "DistilledReturnPayload": { "type": "object", "properties": { "artifact_ref": { "$ref": "#/components/schemas/ArtifactRef" }, "promoted_fact_ids": { "type": "array", "items": { "type": "string" } }, "compacted_summary": { "type": "string" }, "trace_hash": { "type": "string", "description": "Content hash of the pruned raw trace, e.g. \"sha256:\". Promoted facts keep it as part of their provenance pointer." }, "retention_policy": { "type": "string", "description": "Declared retention policy under which raw traces MAY be deleted, e.g. \"retain_30_days\". Without one, pruned traces leave the active context but are not deleted." } }, "additionalProperties": false, "required": [ "promoted_fact_ids", "compacted_summary" ], "description": "What a child work scope returns to its parent at RECORD: the ratified commitment and distilled facts only. Pruning removes raw traces from the active context, not from provenance: every promoted fact keeps a provenance pointer (child work_id, invocation IDs and trace_hash)." }, "ChildWork": { "type": "object", "properties": { "work_id": { "type": "string" }, "parent_work_id": { "type": "string" }, "isolation_policy": { "$ref": "#/components/schemas/IsolationPolicy" }, "distilled_return_payload": { "$ref": "#/components/schemas/DistilledReturnPayload" } }, "additionalProperties": false, "required": [ "work_id", "parent_work_id", "isolation_policy" ], "description": "A child work scope (hierarchical sub-agent isolation), as staged through caop_stage_work." }, "CompactionMode": { "type": "string", "enum": [ "FACT_POINTERS_ONLY", "SUMMARY_WITH_LINEAGE", "FULL_RAW_ARTIFACTS" ], "default": "SUMMARY_WITH_LINEAGE" }, "CapabilityStub": { "type": "object", "properties": { "capability_id": { "type": "string" }, "summary": { "type": "string" } }, "additionalProperties": false, "required": [ "capability_id", "summary" ], "description": "Compact directory entry returned by caop_pulse. Capabilities are not MCP tools: they are invoked through caop_stage_work plan_steps by capability_id." }, "HydratedCapability": { "type": "object", "properties": { "capability_id": { "type": "string" }, "input_schema": { "type": "object" } }, "additionalProperties": false, "required": [ "capability_id", "input_schema" ], "description": "A capability schema hydrated on request (hydrate_capability_ids). It is returned as data; it does not change the host’s tool list." }, "DispatchWorkInputV02": { "type": "object", "required": [ "work_id", "decision" ], "properties": { "work_id": { "type": "string" }, "decision": { "type": "string", "enum": [ "APPROVE_AND_DISPATCH", "APPROVE_WITH_STEERING_DELTA", "REJECT_WORK" ] }, "steering_delta": { "type": "object", "description": "Non-destructive mid-flight overrides applied before EXECUTE without aborting the work lifecycle.", "properties": { "patched_step_arguments": { "type": "array", "items": { "type": "object", "required": [ "step_index", "argument_overrides" ], "properties": { "step_index": { "type": "integer" }, "argument_overrides": { "type": "object" } } } }, "added_policy_constraints": { "type": "array", "items": { "type": "string" } }, "rationale": { "type": "string" } } }, "two_phase_verification": { "type": "object", "properties": { "phase_1_immediate": { "type": "string", "enum": [ "REQUIRE_NONCE_AND_ARTIFACT" ] }, "phase_2_deferred": { "type": "object", "required": [ "check_after_seconds", "verification_capability_id", "success_predicate" ], "properties": { "check_after_seconds": { "type": "integer" }, "verification_capability_id": { "type": "string" }, "success_predicate": { "type": "string" } } } } } } }, "PulseInputV02": { "type": "object", "properties": { "scope_goal_ids": { "type": "array", "items": { "type": "string" } }, "compaction_mode": { "type": "string", "enum": [ "FACT_POINTERS_ONLY", "SUMMARY_WITH_LINEAGE", "FULL_RAW_ARTIFACTS" ], "default": "SUMMARY_WITH_LINEAGE" }, "hydrate_capability_ids": { "type": "array", "items": { "type": "string" }, "description": "Lazy Capability Discovery: Pass specific capability IDs from the stub directory to load their full JSON input schemas." } } } } } }