diff --git a/.corviduo-canonicals.toml b/.corviduo-canonicals.toml index de41e75..def0adc 100644 --- a/.corviduo-canonicals.toml +++ b/.corviduo-canonicals.toml @@ -89,3 +89,37 @@ canonical_path = "scripts/contract_drift_check.py" consumer_path = "scripts/contract_drift_check.py" pinned_sha256_16 = "23271287ac488da4" pinned_at = "2026-05-17T05:30:00+00:00" + +# --------------------------------------------------------------------------- +# Worldtree Conversation-API surface (vendored from ~/development/Worldtree). +# The v1 wire is FROZEN (Worldtree #326 / v1-schema-freeze-manifest.md). The +# machine-readable OpenAPI + SSE schema are the authoritative drift GATES; the +# prose markdown is the human reference and is allowed to lag (tolerate_drift). +# These are what ratatoskr's v1 coverage map (docs/coverage-map.md) audits +# against. Pin target: Worldtree 5810a26 (v1.0.0b2). +# --------------------------------------------------------------------------- + +[[pins]] +id = "worldtree-conversation-api-openapi-v2" +canonical_source = "Worldtree" +canonical_path = "docs/conversation-api-openapi.json" +consumer_path = "docs/conversation-api-openapi.json" +pinned_sha256_16 = "dbdf4e24c8b06c92" +pinned_at = "2026-06-30T22:25:56+00:00" + +[[pins]] +id = "worldtree-conversation-api-sse-events-v1" +canonical_source = "Worldtree" +canonical_path = "docs/conversation-api-sse-events.schema.json" +consumer_path = "docs/conversation-api-sse-events.schema.json" +pinned_sha256_16 = "9deeebf404d72f9a" +pinned_at = "2026-06-30T22:25:56+00:00" + +[[pins]] +id = "worldtree-conversation-api-spec-v1" +canonical_source = "Worldtree" +canonical_path = "docs/conversation-api-spec.md" +consumer_path = "docs/conversation-api-spec.md" +pinned_sha256_16 = "2d111a3b8322b7d1" +pinned_at = "2026-06-30T22:25:56+00:00" +tolerate_drift = true # prose reference; OpenAPI+SSE are the gates diff --git a/docs/SPEC-PIN.md b/docs/SPEC-PIN.md index 3a6056e..26b9b8e 100644 --- a/docs/SPEC-PIN.md +++ b/docs/SPEC-PIN.md @@ -7,24 +7,32 @@ documents the pin, the vendored artifacts, and the bump procedure. | Field | Value | |---|---| -| Worldtree git SHA | `f1b59f8cd6fe41e497d0be9dad9d3110451f0d9a` | -| Worldtree HEAD message | `Merge #299: adopt bifrost v0.6 memory scope wire (scope_any/scope_all)` | -| Pinned on | 2026-06-17 | -| Pinned by | ratatoskr-dev (bump for #297/#298 — cold recall closed end-to-end) | -| Worldtree version at pin | `v0.35.16` | +| Worldtree git SHA | `5810a26b38a5ea6630892f9a39756f57c5b7b41e` | +| Worldtree HEAD message | `memory: snapshot — v1.0.0b2 shipped complete (demo + personal green); consumer loop closed` | +| Pinned on | 2026-06-30 | +| Pinned by | ratatoskr-dev (v1 coverage-audit — re-pin to the FROZEN OpenAPI 2.2.0 + SSE schema) | +| Worldtree version at pin | `v1.0.0b2` | ## Pin history | Date | SHA | Version | Notable deltas consumed | |---|---|---|---| +| 2026-06-30 | `5810a26` | v1.0.0b2 | **Re-pin to Worldtree's FROZEN v1 surface (#326), as part of the v1 coverage-audit.** Vendored the machine-readable artifacts — `conversation-api-openapi.json` (OpenAPI **2.2.0**, 40 path-groups) + `conversation-api-sse-events.schema.json` (11 events) — now the **authoritative drift gates** (pinned in `.corviduo-canonicals.toml`, CI-checked by `canonical_drift.py`). The prose `conversation-api-spec.md` is **byte-identical** to the v0.35.16 pin (last WT markdown edit 2026-05-31), kept as the human reference (`tolerate_drift`). b2 deltas already consumed in code: 409/503 eager turn-launch statuses (#331, v0.18.3/.4) + the unified error envelope (#328). 7 endpoints documented only in the OpenAPI, not the prose, all classified in `docs/coverage-map.md`: `admin/keys/bulk`, `admin/persona/{archive,erase}`, `admin/usage`, `embed`, `judgments`, `me/usage`. No client-breaking change — `pin:`-only, no version bump. | | 2026-06-17 | `f1b59f8` | v0.35.16 | **#297 + #298/#299 — Worldtree adopts the bifrost v0.6 scope wire (emits `scope_any`/`scope_all`) + client-side per-scope-value union recall. With our v0.17.6 provider this closes cold cross-session recall end-to-end.** Catch-up bump (v0.29.0→v0.35.16). Intervening client-facing deltas reviewed, none break our consumer: #211 agent rename (`saga`→`echo`, `actor`→`mask` — slugs only); #245 `end_user_id` persistence + memory-scope resolver; #187/#188/#219 Tier-3 define/PATCH policy (additive); `bifrost` binding field + `ephemeral_does_not_accept_bifrost` 422 now documented (the #17 surface). Error codes stable; no ratatoskr code change required. | | 2026-05-25 | `da93ca7` | v0.28.0 | #204 — new SSE event `affect_update` (current/scheduled), new endpoint `GET /agents/{id}/persona_state`, auth-model doc edits | | 2026-05-20 | `55101e9` | v0.19.0 | initial scaffold pin | ## Vendored artifacts -- `docs/conversation-api-spec.md` — copy of `Worldtree/docs/conversation-api-spec.md` at the pinned SHA. This is the **client-facing interface contract** Ratatoskr is built against. -- `docs/conversation_api.contract.md` — copy of `Worldtree/docs/contracts/conversation_api.contract.md` at the pinned SHA. The **server-side contract** including INV-001..INV-052 and amendments. Useful for understanding load-bearing server invariants (e.g., INV-014 turn-id-public, INV-046 admin-events-envelope-stable, INV-049 admin-events-pii-discipline) when designing client behavior against them. +**Authoritative (FROZEN, machine-readable — the drift gates):** + +- `docs/conversation-api-openapi.json` — copy of `Worldtree/docs/conversation-api-openapi.json` (OpenAPI `info.version` **2.2.0**). The frozen v1 REST wire (40 path-groups). Pinned `worldtree-conversation-api-openapi-v2` in `.corviduo-canonicals.toml`; drift gated by `canonical_drift.py`. +- `docs/conversation-api-sse-events.schema.json` — copy of `Worldtree/docs/conversation-api-sse-events.schema.json`. The frozen SSE event schema (11 discriminated event types). Pinned `worldtree-conversation-api-sse-events-v1`. + +**Reference (prose; allowed to lag — `tolerate_drift`):** + +- `docs/conversation-api-spec.md` — copy of `Worldtree/docs/conversation-api-spec.md` at the pinned SHA. The **client-facing prose narrative**. Byte-frozen at v0.35.16-era content (last WT edit 2026-05-31); the OpenAPI/SSE JSON above are the source of truth where they diverge. Pinned `worldtree-conversation-api-spec-v1` (tolerate_drift). +- `docs/conversation_api.contract.md` — copy of `Worldtree/docs/contracts/conversation_api.contract.md` at the pinned SHA (byte-identical at b2 — server contract unchanged since the v0.35.16 pin). The **server-side contract** including INV-001..INV-052 and amendments. Useful for understanding load-bearing server invariants (e.g., INV-014 turn-id-public, INV-046 admin-events-envelope-stable, INV-049 admin-events-pii-discipline) when designing client behavior against them. Not in the canonical manifest (reference-only). Both files are vendored — they reflect Worldtree at the pinned SHA, not the live `~/development/Worldtree` checkout. Update them only when diff --git a/docs/conversation-api-openapi.json b/docs/conversation-api-openapi.json new file mode 100644 index 0000000..7bd3024 --- /dev/null +++ b/docs/conversation-api-openapi.json @@ -0,0 +1,8015 @@ +{ + "components": { + "schemas": { + "BifrostBindingRequest": { + "additionalProperties": false, + "description": "Bifrost binding parameters for session-create (issue #160).", + "properties": { + "endpoint_url": { + "title": "Endpoint Url", + "type": "string" + }, + "scope": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Scope" + } + }, + "required": [ + "endpoint_url" + ], + "title": "BifrostBindingRequest", + "type": "object" + }, + "BifrostEndpointOverride": { + "description": "Per-message Bifrost endpoint override (issue #166, bifrost v0.2 spec § 9).\n\nEnables stateless one-off consumer-MCP calls without binding a Bifrost\nendpoint to the whole session. A new BifrostClient is instantiated per\nmessage; state never bleeds into the session-bound client.", + "properties": { + "consumer_id": { + "description": "Heimdall user_id whose registered key + algorithm to use", + "minLength": 1, + "title": "Consumer Id", + "type": "string" + }, + "endpoint_url": { + "description": "https URL of the override target's MCP server", + "title": "Endpoint Url", + "type": "string" + }, + "scope": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Scope" + } + }, + "required": [ + "endpoint_url", + "consumer_id" + ], + "title": "BifrostEndpointOverride", + "type": "object" + }, + "BifrostInspectionResponse": { + "additionalProperties": false, + "properties": { + "capabilities_granted": { + "items": { + "type": "string" + }, + "title": "Capabilities Granted", + "type": "array" + }, + "connected": { + "title": "Connected", + "type": "boolean" + }, + "consumer_id": { + "title": "Consumer Id", + "type": "string" + }, + "endpoint_url": { + "title": "Endpoint Url", + "type": "string" + }, + "tools": { + "items": { + "additionalProperties": true, + "type": "object" + }, + "title": "Tools", + "type": "array" + } + }, + "required": [ + "endpoint_url", + "consumer_id", + "connected", + "capabilities_granted", + "tools" + ], + "title": "BifrostInspectionResponse", + "type": "object" + }, + "Body_create_upload_uploads_post": { + "properties": { + "file": { + "contentMediaType": "application/octet-stream", + "title": "File", + "type": "string" + } + }, + "required": [ + "file" + ], + "title": "Body_create_upload_uploads_post", + "type": "object" + }, + "BulkIssueRequest": { + "additionalProperties": false, + "properties": { + "issuances": { + "items": { + "$ref": "#/components/schemas/IssueKeyRequest" + }, + "title": "Issuances", + "type": "array" + } + }, + "required": [ + "issuances" + ], + "title": "BulkIssueRequest", + "type": "object" + }, + "BulkRevokeRequest": { + "additionalProperties": false, + "properties": { + "key_ids": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Key Ids" + }, + "user_prefix": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "User Prefix" + } + }, + "title": "BulkRevokeRequest", + "type": "object" + }, + "BulkRotateRequest": { + "additionalProperties": false, + "properties": { + "grace_seconds": { + "anyOf": [ + { + "maximum": 86400.0, + "minimum": 0.0, + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Grace Seconds" + }, + "key_ids": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Key Ids" + }, + "user_prefix": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "User Prefix" + } + }, + "title": "BulkRotateRequest", + "type": "object" + }, + "ConsumerAgentCreateRequest": { + "additionalProperties": false, + "description": "POST /agents/define payload (#181).\n\nLayer fields (``persona`` / ``motivational`` / ``valence`` /\n``memory``) are schema-reserved with ``null`` default. Non-null\nvalues return 422 ``layer_deferred`` so consumers can code against\nthe final shape; Phase 2.1+ flips activations on without a\nschema-breaking change.", + "properties": { + "agent_name": { + "title": "Agent Name", + "type": "string" + }, + "memory": { + "anyOf": [ + {}, + { + "type": "null" + } + ], + "title": "Memory" + }, + "motivational": { + "anyOf": [ + {}, + { + "type": "null" + } + ], + "title": "Motivational" + }, + "persona": { + "anyOf": [ + {}, + { + "type": "null" + } + ], + "title": "Persona" + }, + "role": { + "title": "Role", + "type": "string" + }, + "system_prompt": { + "title": "System Prompt", + "type": "string" + }, + "valence": { + "anyOf": [ + {}, + { + "type": "null" + } + ], + "title": "Valence" + } + }, + "required": [ + "agent_name", + "system_prompt", + "role" + ], + "title": "ConsumerAgentCreateRequest", + "type": "object" + }, + "CreateCharacterRequest": { + "description": "Issue #153: POST /characters body — character + optional initial state.", + "properties": { + "character": { + "additionalProperties": true, + "title": "Character", + "type": "object" + }, + "state": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "State" + } + }, + "required": [ + "character" + ], + "title": "CreateCharacterRequest", + "type": "object" + }, + "CreateSessionRequest": { + "additionalProperties": false, + "properties": { + "agent_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Agent Id" + }, + "bifrost": { + "anyOf": [ + { + "$ref": "#/components/schemas/BifrostBindingRequest" + }, + { + "type": "null" + } + ] + }, + "character_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Character Id" + }, + "config": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Config" + }, + "end_user_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "End User Id" + }, + "persona_seed": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Persona Seed" + }, + "record_tool_intermediates": { + "default": false, + "title": "Record Tool Intermediates", + "type": "boolean" + } + }, + "title": "CreateSessionRequest", + "type": "object" + }, + "ErrorCode": { + "enum": [ + "auth_missing", + "auth_invalid", + "auth_user_disabled", + "auth_key_disabled", + "auth_key_superseded", + "auth_scope_denied", + "user_suspended", + "user_not_found", + "invalid_tier", + "session_not_found", + "session_not_bifrost_bound", + "session_retired", + "agent_not_available", + "turn_not_found", + "turn_finished", + "key_not_found", + "key_revoked", + "key_already_superseded", + "last_event_id_invalid", + "buffer_expired", + "cursor_invalid", + "rate_limited", + "validation_failed", + "content_too_long", + "not_ready", + "method_not_allowed", + "malformed_request", + "search_query_invalid", + "upload_too_large", + "quota_exceeded", + "mime_type_disallowed", + "upload_expired", + "upload_not_found", + "agent_lacks_upload_support", + "character_not_found", + "ttl_too_large", + "state_schema_outdated", + "llm_output_truncated", + "context_overflow", + "model_unavailable", + "provider_timeout", + "llm_output_invalid", + "bifrost_handshake_failed", + "bifrost_consumer_not_found", + "tier_mismatch", + "invalid_judgment_kind", + "bin_unsupported_v1", + "max_tokens_too_low_for_gap_list", + "selene_unreachable", + "agent_name_invalid", + "agent_name_taken", + "agent_quota_exceeded", + "system_prompt_too_large", + "model_not_available", + "layer_deferred", + "field_not_mutable", + "tier3_user_id_unsupported", + "end_user_id_required", + "end_user_id_reserved", + "auth_revoked", + "persona_ocean_required", + "persona_ocean_out_of_range", + "persona_notes_too_large", + "persona_seed_invalid", + "memory_stm_capacity_out_of_range", + "memory_stm_token_budget_out_of_range", + "embedder_version_mismatch", + "embed_batch_too_large", + "persona_layer_inactive", + "memory_context_embedding_dim_mismatch", + "motivational_id_collision", + "motivational_goal_invalid_type", + "motivational_salience_out_of_range", + "motivational_description_too_short", + "motivational_missing_required_field", + "persona_not_configured", + "bulk_prefix_too_short", + "bulk_batch_too_large", + "internal_error" + ], + "title": "ErrorCode", + "type": "string" + }, + "ErrorDetail": { + "description": "The `detail` object every Conversation-API error response carries.", + "properties": { + "error_code": { + "$ref": "#/components/schemas/ErrorCode", + "description": "Stable snake_case error identifier (errors.ErrorCode)." + }, + "errors": { + "anyOf": [ + { + "items": {}, + "type": "array" + }, + { + "type": "null" + } + ], + "default": null, + "description": "Per-field validation errors; present only on validation_failed (422).", + "title": "Errors" + }, + "message": { + "description": "Human-readable error message.", + "title": "Message", + "type": "string" + } + }, + "required": [ + "error_code", + "message" + ], + "title": "ErrorDetail", + "type": "object" + }, + "ErrorResponse": { + "description": "The unified error body for every 4xx/5xx Conversation-API response.", + "properties": { + "detail": { + "$ref": "#/components/schemas/ErrorDetail" + } + }, + "required": [ + "detail" + ], + "title": "ErrorResponse", + "type": "object" + }, + "HTTPValidationError": { + "properties": { + "detail": { + "items": { + "$ref": "#/components/schemas/ValidationError" + }, + "title": "Detail", + "type": "array" + } + }, + "title": "HTTPValidationError", + "type": "object" + }, + "IssueKeyRequest": { + "additionalProperties": false, + "properties": { + "label": { + "title": "Label", + "type": "string" + }, + "tier": { + "anyOf": [ + { + "enum": [ + "user", + "free", + "pro", + "admin", + "readonly-admin" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Tier" + }, + "user_id": { + "title": "User Id", + "type": "string" + } + }, + "required": [ + "user_id", + "label" + ], + "title": "IssueKeyRequest", + "type": "object" + }, + "JudgmentRequest": { + "description": "Request body for POST /judgments.", + "properties": { + "bible": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Bible" + }, + "composite_token_count": { + "description": "Caller-estimated composite token count", + "minimum": 0.0, + "title": "Composite Token Count", + "type": "integer" + }, + "has_bible": { + "default": false, + "title": "Has Bible", + "type": "boolean" + }, + "instruction": { + "default": "", + "title": "Instruction", + "type": "string" + }, + "judgment_kind": { + "description": "pairwise | binary | likert | scalar | gap_list", + "title": "Judgment Kind", + "type": "string" + }, + "max_tokens": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Max Tokens" + }, + "response_a": { + "default": "", + "title": "Response A", + "type": "string" + }, + "response_b": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Response B" + }, + "rubric": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Rubric" + } + }, + "required": [ + "judgment_kind", + "composite_token_count" + ], + "title": "JudgmentRequest", + "type": "object" + }, + "PersonaLifecycleRequest": { + "description": "Body for POST /admin/persona/{archive,erase} (#215).\n\n``agent_id`` truthiness selects the target: a non-empty agent_id operates on\nthe single ``(agent_id, end_user_id)`` partition; absent / null / empty-string\noperates on all agents for the user (INV-215-2 / INV-MODEL-2).", + "properties": { + "agent_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Agent Id" + }, + "end_user_id": { + "minLength": 1, + "title": "End User Id", + "type": "string" + } + }, + "required": [ + "end_user_id" + ], + "title": "PersonaLifecycleRequest", + "type": "object" + }, + "RotateKeyRequest": { + "properties": { + "grace_seconds": { + "anyOf": [ + { + "maximum": 86400.0, + "minimum": 0.0, + "type": "integer" + }, + { + "type": "null" + } + ], + "description": "Grace window in seconds. None uses the server default (300). 0 = hard cut; 86400 = 24h max.", + "title": "Grace Seconds" + } + }, + "title": "RotateKeyRequest", + "type": "object" + }, + "SendMessageRequest": { + "additionalProperties": false, + "properties": { + "bifrost": { + "anyOf": [ + { + "$ref": "#/components/schemas/BifrostEndpointOverride" + }, + { + "type": "null" + } + ] + }, + "content": { + "title": "Content", + "type": "string" + }, + "memory_context": { + "anyOf": [ + { + "items": { + "additionalProperties": true, + "type": "object" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Memory Context" + }, + "role": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Role" + }, + "sender_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Sender Id" + }, + "upload_ids": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Upload Ids" + } + }, + "required": [ + "content" + ], + "title": "SendMessageRequest", + "type": "object" + }, + "SessionToolsResponse": { + "additionalProperties": false, + "properties": { + "agent_id": { + "title": "Agent Id", + "type": "string" + }, + "bifrost_tools": { + "items": { + "additionalProperties": true, + "type": "object" + }, + "title": "Bifrost Tools", + "type": "array" + }, + "builtin_tools": { + "items": { + "additionalProperties": true, + "type": "object" + }, + "title": "Builtin Tools", + "type": "array" + } + }, + "required": [ + "agent_id", + "builtin_tools", + "bifrost_tools" + ], + "title": "SessionToolsResponse", + "type": "object" + }, + "UpdateSessionRequest": { + "additionalProperties": false, + "properties": { + "archived": { + "default": false, + "title": "Archived", + "type": "boolean" + }, + "metadata": { + "additionalProperties": true, + "default": {}, + "title": "Metadata", + "type": "object" + }, + "name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Name" + }, + "tags": { + "default": [], + "items": { + "type": "string" + }, + "title": "Tags", + "type": "array" + } + }, + "title": "UpdateSessionRequest", + "type": "object" + }, + "UserTierChangeRequest": { + "description": "Issue #174: body for POST /admin/users/{user_id}/tier.", + "properties": { + "reason": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Reason" + }, + "tier": { + "title": "Tier", + "type": "string" + } + }, + "required": [ + "tier" + ], + "title": "UserTierChangeRequest", + "type": "object" + }, + "ValidationError": { + "properties": { + "ctx": { + "title": "Context", + "type": "object" + }, + "input": { + "title": "Input" + }, + "loc": { + "items": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "integer" + } + ] + }, + "title": "Location", + "type": "array" + }, + "msg": { + "title": "Message", + "type": "string" + }, + "type": { + "title": "Error Type", + "type": "string" + } + }, + "required": [ + "loc", + "msg", + "type" + ], + "title": "ValidationError", + "type": "object" + } + }, + "securitySchemes": { + "HTTPBearer": { + "scheme": "bearer", + "type": "http" + } + } + }, + "info": { + "description": "Multi-turn conversation interface for Worldtree agents.", + "title": "Worldtree Conversation API", + "version": "2.2.0" + }, + "openapi": "3.1.0", + "paths": { + "/admin/events": { + "get": { + "description": "SSE stream broadcasting all conv-api lifecycle events to admin consumers.\n\nRequires admin.events.read scope. Last-Event-ID header resumes from\na buffered offset; out-of-buffer reconnects receive system.replay_gap.", + "operationId": "admin_events_admin_events_get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": {} + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Admin Events" + } + }, + "/admin/keys": { + "get": { + "description": "List all API keys (active + revoked), sorted by created_at desc.\n\nNever includes the cleartext key value.", + "operationId": "list_keys_admin_keys_get", + "parameters": [ + { + "in": "query", + "name": "user_prefix", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "User Prefix" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "items": { + "additionalProperties": true, + "type": "object" + }, + "title": "Response List Keys Admin Keys Get", + "type": "array" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "List Keys" + }, + "post": { + "description": "Issue a new API key for a user.\n\nReturns the cleartext key exactly once — it is NEVER re-derivable.\nCaller is responsible for securing the response body; configure\nreverse proxy log redaction for this endpoint.", + "operationId": "issue_key_admin_keys_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/IssueKeyRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Issue Key Admin Keys Post", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Issue Key" + } + }, + "/admin/keys/bulk": { + "delete": { + "operationId": "bulk_revoke_keys_admin_keys_bulk_delete", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BulkRevokeRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Bulk Revoke Keys Admin Keys Bulk Delete", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Bulk Revoke Keys" + }, + "post": { + "operationId": "bulk_issue_keys_admin_keys_bulk_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BulkIssueRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Bulk Issue Keys Admin Keys Bulk Post", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Bulk Issue Keys" + } + }, + "/admin/keys/bulk/rotate": { + "post": { + "operationId": "bulk_rotate_keys_admin_keys_bulk_rotate_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BulkRotateRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Bulk Rotate Keys Admin Keys Bulk Rotate Post", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Bulk Rotate Keys" + } + }, + "/admin/keys/{key_id}": { + "delete": { + "description": "Revoke an API key by key_id.\n\nIdempotent: revoking an already-revoked key returns 200 with outcome=no_op.\nReturns 404 if key_id never existed.", + "operationId": "revoke_key_admin_keys__key_id__delete", + "parameters": [ + { + "in": "path", + "name": "key_id", + "required": true, + "schema": { + "title": "Key Id", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Revoke Key Admin Keys Key Id Delete", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Revoke Key" + } + }, + "/admin/keys/{key_id}/rotate": { + "post": { + "description": "Atomically rotate an API key, issuing a new key while the old one\nremains valid for a configurable grace window.\n\nReturns the cleartext of the new key exactly once — configure reverse-proxy\nlog redaction for this endpoint, same as POST /admin/keys.\n\ngrace_seconds=0 is \"compromise mode\" — the old key is immediately invalid\non its next auth attempt. In-flight SSE/WebSocket streams are NOT\nforce-disconnected (auth is enforced at request boundary only).", + "operationId": "rotate_key_admin_keys__key_id__rotate_post", + "parameters": [ + { + "in": "path", + "name": "key_id", + "required": true, + "schema": { + "title": "Key Id", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/RotateKeyRequest" + }, + { + "type": "null" + } + ], + "title": "Body" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Rotate Key Admin Keys Key Id Rotate Post", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Rotate Key" + } + }, + "/admin/persona/archive": { + "post": { + "description": "Archive persona state for one (agent, user) pair or all agents for a\nuser (#215). Forward-only: no thaw endpoint (archived->active deferred).", + "operationId": "admin_persona_archive_admin_persona_archive_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PersonaLifecycleRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Admin Persona Archive Admin Persona Archive Post", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Admin Persona Archive" + } + }, + "/admin/persona/erase": { + "post": { + "description": "Hard-erase persona state for one (agent, user) pair or all agents for a\nuser (#215). Terminal — INV-172-12.", + "operationId": "admin_persona_erase_admin_persona_erase_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PersonaLifecycleRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Admin Persona Erase Admin Persona Erase Post", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Admin Persona Erase" + } + }, + "/admin/sessions/{session_id}/bifrost": { + "get": { + "description": "Inspect a Bifrost-bound session's connection state + post-filter tool list.\n\nReturns 404 ``session_not_found`` for a missing session and 404\n``session_not_bifrost_bound`` for an existing session with no live\n``_bifrost_clients`` entry (covers never-bound sessions AND restored\nsessions whose live client is gone post-restart — the connection\nmetadata fields cannot be reconstructed from persisted state alone).\n\nGraceful-on-stale: when a live client is registered but its TCP\nconnection has died, ``connected: false`` with the cached\npost-filter tool list is returned. No re-handshake is attempted —\nthis endpoint is read-only.", + "operationId": "admin_session_bifrost_admin_sessions__session_id__bifrost_get", + "parameters": [ + { + "in": "path", + "name": "session_id", + "required": true, + "schema": { + "title": "Session Id", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BifrostInspectionResponse" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Admin Session Bifrost" + } + }, + "/admin/sessions/{session_id}/retire": { + "post": { + "operationId": "admin_session_retire_admin_sessions__session_id__retire_post", + "parameters": [ + { + "in": "path", + "name": "session_id", + "required": true, + "schema": { + "title": "Session Id", + "type": "string" + } + } + ], + "responses": { + "202": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Admin Session Retire Admin Sessions Session Id Retire Post", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Admin Session Retire" + } + }, + "/admin/sessions/{session_id}/tools": { + "get": { + "description": "Inspect the full post-merge tool list the agent sees at turn-fire time.\n\n``bifrost_tools`` mirrors the actual turn-time merge predicate at\n``service.py:1743`` (live client AND persisted tools); otherwise ``[]``.\nPer-message override tools (#166) are turn-scoped and never appear here.", + "operationId": "admin_session_tools_admin_sessions__session_id__tools_get", + "parameters": [ + { + "in": "path", + "name": "session_id", + "required": true, + "schema": { + "title": "Session Id", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionToolsResponse" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Admin Session Tools" + } + }, + "/admin/usage": { + "get": { + "operationId": "admin_usage_admin_usage_get", + "parameters": [ + { + "in": "query", + "name": "window", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Window" + } + }, + { + "in": "query", + "name": "user_id", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "User Id" + } + }, + { + "in": "query", + "name": "user_prefix", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "User Prefix" + } + }, + { + "in": "query", + "name": "breakdown", + "required": false, + "schema": { + "default": false, + "title": "Breakdown", + "type": "boolean" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Admin Usage Admin Usage Get", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Admin Usage" + } + }, + "/admin/users/{user_id}/tier": { + "post": { + "description": "Mutate a user's tier (issue #174).\n\nDrives license-state transitions: `user → suspended` denies access via\nempty-scope policy; `suspended → user` (or whatever prior tier) restores\nit. Tier history is in the audit log; the user record carries only the\ncurrent tier (no previous_tier column — INV-174-8).\n\nClosed-set validation per INV-174-1 — hard-coded vocabulary so a typo\nin policies.yaml can't silently expand the accepted set.", + "operationId": "change_user_tier_admin_users__user_id__tier_post", + "parameters": [ + { + "in": "path", + "name": "user_id", + "required": true, + "schema": { + "title": "User Id", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UserTierChangeRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Change User Tier Admin Users User Id Tier Post", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Change User Tier" + } + }, + "/agents": { + "get": { + "description": "List all available agents.", + "operationId": "list_agents_agents_get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "items": { + "additionalProperties": true, + "type": "object" + }, + "title": "Response List Agents Agents Get", + "type": "array" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "List Agents" + } + }, + "/agents/define": { + "post": { + "description": "Create a Tier 3 consumer-defined agent (#181).\n\nPersists to the ``consumer_agents`` table with the calling key's\n``owner_key_hash``; grants the owner the per-resource\n``agents.call::`` scope; emits an\n``agents.define`` audit event. 422/403/409/429 paths per contract.", + "operationId": "define_consumer_agent_agents_define_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConsumerAgentCreateRequest" + } + } + }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Define Consumer Agent Agents Define Post", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Define Consumer Agent" + } + }, + "/agents/{agent_id}": { + "delete": { + "description": "Owner-initiated hard-delete of a Tier 3 agent (#181).\n\nBypasses the 24h grace (operator intent explicit) — distinct from\nthe key-revocation cascade which uses soft-delete-with-grace.", + "operationId": "delete_consumer_agent_agents__agent_id__delete", + "parameters": [ + { + "in": "path", + "name": "agent_id", + "required": true, + "schema": { + "title": "Agent Id", + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Delete Consumer Agent" + }, + "get": { + "description": "Get a single agent's info by id (#169).\n\nPolymorphic response shape:\n\n* Tier 1/2 agents (no colon in agent_id) → AgentInfoResponse\n (identity + persona + ui_hints).\n* Tier 3 consumer-defined agents (``:``) →\n ConsumerAgentResponse (the same shape POST /agents/define returns).\n Gated on caller ownership of the row; non-owners receive 404 to\n avoid leaking existence across users.\n\nContract anchor: INV-181-12 forbids LISTING Tier 3 agents via\nGET /agents (plural). The by-id endpoint here is a LOOKUP, not a\nlisting, so owner-scoped Tier 3 access is permitted. Surfaced by\nskaldsong-dev's bootstrap flow (althing thread 01KSF23CEW8AEK7WHH55YDZM2W,\n2026-05-25): the prior over-application of the listing filter to\nthe by-id endpoint left consumers without a way to verify their\nown Tier 3 agent's existence.", + "operationId": "get_agent_agents__agent_id__get", + "parameters": [ + { + "in": "path", + "name": "agent_id", + "required": true, + "schema": { + "title": "Agent Id", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Get Agent Agents Agent Id Get", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Get Agent" + }, + "patch": { + "description": "PATCH a Tier 3 agent (#181, Phase 2.0 minimal).\n\nOnly ``system_prompt`` and ``model`` are mutable. Payload-shape\nvalidation (extra=forbid + layer-field check) runs BEFORE the DB\nlookup so an immutable-field PATCH against a missing agent still\nsurfaces 422 ``field_not_mutable`` (not 404). Active sessions\ncontinue using their cached AgentContext.", + "operationId": "patch_consumer_agent_agents__agent_id__patch", + "parameters": [ + { + "in": "path", + "name": "agent_id", + "required": true, + "schema": { + "title": "Agent Id", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Patch Consumer Agent Agents Agent Id Patch", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Patch Consumer Agent" + } + }, + "/agents/{agent_id}/persona_state": { + "get": { + "description": "Return the agent's current persona snapshot (issue #204).\n\nRoute ordering per INV-204-7: auth -> Tier 3 short-circuit ->\nTier 1/2 existence -> persona-enabled -> snapshot.", + "operationId": "get_agent_persona_state_agents__agent_id__persona_state_get", + "parameters": [ + { + "in": "path", + "name": "agent_id", + "required": true, + "schema": { + "title": "Agent Id", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Get Agent Persona State Agents Agent Id Persona State Get", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Get Agent Persona State" + } + }, + "/capabilities": { + "get": { + "description": "Return per-template metadata for ephemeral templates.\n\nCallable by any authenticated user (not gated on instantiate:echo scope).\nThe response is forward-compatible — additional templates appear as sibling\nkeys under ephemeral_templates.", + "operationId": "get_capabilities_capabilities_get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Get Capabilities Capabilities Get", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Get Capabilities" + } + }, + "/characters": { + "post": { + "description": "Create a transient character (issue #153). Character lives in-memory\nonly; consumer owns the canonical character JSON.", + "operationId": "create_character_characters_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateCharacterRequest" + } + } + }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Create Character Characters Post", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Create Character" + } + }, + "/characters/{character_id}": { + "delete": { + "description": "Delete a transient character (issue #153). Binding sessions detach.", + "operationId": "delete_character_characters__character_id__delete", + "parameters": [ + { + "in": "path", + "name": "character_id", + "required": true, + "schema": { + "title": "Character Id", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Delete Character Characters Character Id Delete", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Delete Character" + } + }, + "/characters/{character_id}/state": { + "get": { + "description": "Export a character's runtime state (issue #153).", + "operationId": "get_character_state_characters__character_id__state_get", + "parameters": [ + { + "in": "path", + "name": "character_id", + "required": true, + "schema": { + "title": "Character Id", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Get Character State Characters Character Id State Get", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Get Character State" + } + }, + "/embed": { + "post": { + "description": "Phase 2.1 (#186 INV-186-19, #189 INV-189-10) — embed text(s) with the\npinned embedder.\n\nThe response carries the embedder version in BOTH the body\n(`embedder_version`) and the `X-Worldtree-Embedder-Version` response\nheader; the two MUST agree per turn. 503 if the embedder is not wired\non this service (deployment hasn't completed the Phase 2.1 wiring yet).", + "operationId": "embed_embed_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Payload", + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": {} + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Embed" + } + }, + "/healthz": { + "get": { + "description": "Liveness probe — always 200 if the request reaches the handler.", + "operationId": "healthz_healthz_get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": { + "type": "string" + }, + "title": "Response Healthz Healthz Get", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "summary": "Healthz" + } + }, + "/judgments": { + "post": { + "description": "Synchronous judgment endpoint for cross-process consumers.\n\nRequires Heimdall scope `domari:invoke`. Returns DomariResponse JSON.\nNo session lifecycle — request-response semantics only.", + "operationId": "post_judgment_judgments_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/JudgmentRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Post Judgment Judgments Post", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Post Judgment" + } + }, + "/me": { + "get": { + "description": "Return the authenticated principal's identity and key metadata.\n\nNo rate-limit check (naturally exempt — the per-user budget check is a\nper-handler call inside send_message, not middleware). No audit emission.", + "operationId": "me_me_get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Me Me Get", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Me" + } + }, + "/me/usage": { + "get": { + "operationId": "me_usage_me_usage_get", + "parameters": [ + { + "in": "query", + "name": "window", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Window" + } + }, + { + "in": "query", + "name": "breakdown", + "required": false, + "schema": { + "default": false, + "title": "Breakdown", + "type": "boolean" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Me Usage Me Usage Get", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Me Usage" + } + }, + "/models/available-for-characters": { + "get": { + "description": "Return the catalog ids bound to the character model role.", + "operationId": "list_models_available_for_characters_models_available_for_characters_get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response List Models Available For Characters Models Available For Characters Get", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "List Models Available For Characters" + } + }, + "/pending": { + "get": { + "description": "List active Bus-v2 pending tasks across all sessions for the authenticated user.\n\nRate-limit exempt (INV-068). Requires ``pending.read`` scope.\nTasks with no originator_user_id are excluded. Cross-user data\nis filtered at the bus layer — only tasks submitted with the\ncaller's user_id appear.", + "operationId": "user_pending_pending_get", + "parameters": [ + { + "in": "query", + "name": "limit", + "required": false, + "schema": { + "default": 50, + "maximum": 200, + "minimum": 1, + "title": "Limit", + "type": "integer" + } + }, + { + "in": "query", + "name": "cursor", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Cursor" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response User Pending Pending Get", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "User Pending" + } + }, + "/readyz": { + "get": { + "description": "Readiness probe — 200 when ready, 503 with reason otherwise.", + "operationId": "readyz_readyz_get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": { + "type": "string" + }, + "title": "Response Readyz Readyz Get", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "summary": "Readyz" + } + }, + "/search": { + "get": { + "description": "Cross-session full-text message search backed by SQLite FTS5.", + "operationId": "search_messages_search_get", + "parameters": [ + { + "in": "query", + "name": "q", + "required": true, + "schema": { + "maxLength": 200, + "minLength": 1, + "title": "Q", + "type": "string" + } + }, + { + "in": "query", + "name": "limit", + "required": false, + "schema": { + "default": 50, + "maximum": 200, + "minimum": 1, + "title": "Limit", + "type": "integer" + } + }, + { + "in": "query", + "name": "cursor", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Cursor" + } + }, + { + "in": "query", + "name": "session_id", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Session Id" + } + }, + { + "in": "query", + "name": "after", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "After" + } + }, + { + "in": "query", + "name": "before", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Before" + } + }, + { + "in": "query", + "name": "role", + "required": false, + "schema": { + "anyOf": [ + { + "enum": [ + "user", + "assistant" + ], + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Role" + } + }, + { + "in": "query", + "name": "include_archived", + "required": false, + "schema": { + "default": true, + "title": "Include Archived", + "type": "boolean" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Search Messages Search Get", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Search Messages" + } + }, + "/sessions": { + "get": { + "description": "List sessions (scoped to authenticated user), paginated by cursor.", + "operationId": "list_sessions_sessions_get", + "parameters": [ + { + "in": "query", + "name": "include_archived", + "required": false, + "schema": { + "default": false, + "title": "Include Archived", + "type": "boolean" + } + }, + { + "in": "query", + "name": "limit", + "required": false, + "schema": { + "default": 50, + "maximum": 200, + "minimum": 1, + "title": "Limit", + "type": "integer" + } + }, + { + "in": "query", + "name": "cursor", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Cursor" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response List Sessions Sessions Get", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "List Sessions" + }, + "post": { + "description": "Create a new conversation session.", + "operationId": "create_session_sessions_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateSessionRequest" + } + } + }, + "required": true + }, + "responses": { + "201": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Create Session Sessions Post", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Create Session" + } + }, + "/sessions/{session_id}": { + "delete": { + "description": "End a session.", + "operationId": "delete_session_sessions__session_id__delete", + "parameters": [ + { + "in": "path", + "name": "session_id", + "required": true, + "schema": { + "title": "Session Id", + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Delete Session" + }, + "get": { + "description": "Get session info.", + "operationId": "get_session_sessions__session_id__get", + "parameters": [ + { + "in": "path", + "name": "session_id", + "required": true, + "schema": { + "title": "Session Id", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Get Session Sessions Session Id Get", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Get Session" + }, + "patch": { + "description": "Update one or more fields on a session. Empty body is a no-op. Returns updated to_info().", + "operationId": "update_session_sessions__session_id__patch", + "parameters": [ + { + "in": "path", + "name": "session_id", + "required": true, + "schema": { + "title": "Session Id", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateSessionRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Update Session Sessions Session Id Patch", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Update Session" + } + }, + "/sessions/{session_id}/messages": { + "get": { + "description": "Return paginated message history for a session.", + "operationId": "get_messages_sessions__session_id__messages_get", + "parameters": [ + { + "in": "path", + "name": "session_id", + "required": true, + "schema": { + "title": "Session Id", + "type": "string" + } + }, + { + "in": "query", + "name": "limit", + "required": false, + "schema": { + "default": 50, + "maximum": 200, + "minimum": 1, + "title": "Limit", + "type": "integer" + } + }, + { + "in": "query", + "name": "cursor", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Cursor" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Get Messages Sessions Session Id Messages Get", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Get Messages" + }, + "post": { + "description": "Send a message and stream the agent's response as SSE.\n\nEach SSE ``data`` field is a JSON object with a ``type`` key.\nThe stream ends after a ``done`` or ``error`` event.\n\nIf ``Last-Event-ID`` header is present, resumes an in-flight turn\n(replay + live drain) instead of starting a new one.", + "operationId": "send_message_sessions__session_id__messages_post", + "parameters": [ + { + "in": "path", + "name": "session_id", + "required": true, + "schema": { + "title": "Session Id", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SendMessageRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": {} + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Send Message" + } + }, + "/sessions/{session_id}/pending": { + "get": { + "description": "List active Bus-v2 pending tasks for a session (INV-065..INV-071).\n\nRate-limit exempt (INV-068). Requires ``pending.read`` scope.\nReturns ``{items, next_cursor}`` — ``next_cursor`` is null on the last page.", + "operationId": "session_pending_sessions__session_id__pending_get", + "parameters": [ + { + "in": "path", + "name": "session_id", + "required": true, + "schema": { + "title": "Session Id", + "type": "string" + } + }, + { + "in": "query", + "name": "limit", + "required": false, + "schema": { + "default": 50, + "maximum": 200, + "minimum": 1, + "title": "Limit", + "type": "integer" + } + }, + { + "in": "query", + "name": "cursor", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Cursor" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Session Pending Sessions Session Id Pending Get", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Session Pending" + } + }, + "/sessions/{session_id}/persona_state": { + "post": { + "description": "Phase 2.1 (#186 INV-186-7, #189 INV-189-9) — set per-session persona baseline.\n\nCross-owner sessions 404 (existence-hiding per #183 INV-183-1). Success\nreturns 204 No Content with NO audit emission — operator-set baselines\nare session-scoped runtime overlays, not security-relevant events.", + "operationId": "set_persona_state_sessions__session_id__persona_state_post", + "parameters": [ + { + "in": "path", + "name": "session_id", + "required": true, + "schema": { + "title": "Session Id", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Payload", + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "204": { + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Set Persona State" + } + }, + "/sessions/{session_id}/tool-events": { + "get": { + "description": "Issue #123: paginated tool-call metadata for sessions opted-in via record_tool_intermediates.", + "operationId": "list_tool_events_sessions__session_id__tool_events_get", + "parameters": [ + { + "in": "path", + "name": "session_id", + "required": true, + "schema": { + "title": "Session Id", + "type": "string" + } + }, + { + "in": "query", + "name": "limit", + "required": false, + "schema": { + "default": 50, + "maximum": 200, + "minimum": 1, + "title": "Limit", + "type": "integer" + } + }, + { + "in": "query", + "name": "cursor", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Cursor" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response List Tool Events Sessions Session Id Tool Events Get", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "List Tool Events" + } + }, + "/sessions/{session_id}/tools": { + "get": { + "description": "Issue #183: owner-scoped session-tools introspection. Same response\nshape as ``/admin/sessions//tools`` and same merge predicate;\nowner-gated (``session.user_id == ctx.user_id``) rather than admin-\nscope-gated so Tier 3 owners can debug their own sessions without\nneeding admin keys. INV-183-1 / INV-183-3 / INV-183-4 / INV-183-6.", + "operationId": "get_session_tools_sessions__session_id__tools_get", + "parameters": [ + { + "in": "path", + "name": "session_id", + "required": true, + "schema": { + "title": "Session Id", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionToolsResponse" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Get Session Tools" + } + }, + "/sessions/{session_id}/turns/{turn_id}/cancel": { + "post": { + "description": "Cancel an in-flight turn (idempotent; ≤100ms p99 per INV-010..014).\n\nReturns 200 with ``{turn_id, cancelled, reason, partial_message_id}``\non success and idempotent no-ops. Maps unknown sessions, unknown\nturns, and ownership mismatches to 404 (INV-009 — never leak existence).", + "operationId": "cancel_turn_endpoint_sessions__session_id__turns__turn_id__cancel_post", + "parameters": [ + { + "in": "path", + "name": "session_id", + "required": true, + "schema": { + "title": "Session Id", + "type": "string" + } + }, + { + "in": "path", + "name": "turn_id", + "required": true, + "schema": { + "title": "Turn Id", + "type": "integer" + } + }, + { + "in": "query", + "name": "persist_partial", + "required": false, + "schema": { + "default": false, + "title": "Persist Partial", + "type": "boolean" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Cancel Turn Endpoint Sessions Session Id Turns Turn Id Cancel Post", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Cancel Turn Endpoint" + } + }, + "/uploads": { + "get": { + "description": "List uploads for the authenticated user (paginated).", + "operationId": "list_uploads_uploads_get", + "parameters": [ + { + "in": "query", + "name": "limit", + "required": false, + "schema": { + "default": 50, + "maximum": 200, + "minimum": 1, + "title": "Limit", + "type": "integer" + } + }, + { + "in": "query", + "name": "cursor", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Cursor" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response List Uploads Uploads Get", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "List Uploads" + }, + "post": { + "description": "Upload a file. Returns the upload metadata envelope.", + "operationId": "create_upload_uploads_post", + "requestBody": { + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/Body_create_upload_uploads_post" + } + } + }, + "required": true + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Create Upload Uploads Post", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Create Upload" + } + }, + "/uploads/{upload_id}": { + "delete": { + "description": "Revoke an upload (idempotent soft-delete).", + "operationId": "delete_upload_uploads__upload_id__delete", + "parameters": [ + { + "in": "path", + "name": "upload_id", + "required": true, + "schema": { + "title": "Upload Id", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Delete Upload Uploads Upload Id Delete", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Delete Upload" + }, + "get": { + "description": "Return upload metadata (not content bytes).", + "operationId": "get_upload_uploads__upload_id__get", + "parameters": [ + { + "in": "path", + "name": "upload_id", + "required": true, + "schema": { + "title": "Upload Id", + "type": "string" + } + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "additionalProperties": true, + "title": "Response Get Upload Uploads Upload Id Get", + "type": "object" + } + } + }, + "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "405": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "412": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Error — unified envelope (detail.error_code is the stable identifier)." + } + }, + "security": [ + { + "HTTPBearer": [] + } + ], + "summary": "Get Upload" + } + } + } +} diff --git a/docs/conversation-api-sse-events.schema.json b/docs/conversation-api-sse-events.schema.json new file mode 100644 index 0000000..de07b15 --- /dev/null +++ b/docs/conversation-api-sse-events.schema.json @@ -0,0 +1,265 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "Server-Sent Events emitted on POST /sessions/{id}/messages. Each event is an object discriminated on `type`; all carry `turn_id`.", + "discriminator": { + "propertyName": "type" + }, + "oneOf": [ + { + "additionalProperties": true, + "properties": { + "phase": { + "enum": [ + "BuildingPrompt", + "CallingLLM", + "ProcessingTools", + "Streaming", + "Finishing" + ], + "type": "string" + }, + "turn_id": { + "description": "The turn this event belongs to.", + "type": [ + "integer", + "string" + ] + }, + "type": { + "const": "worker_phase" + } + }, + "required": [ + "type", + "turn_id" + ], + "type": "object" + }, + { + "additionalProperties": true, + "properties": { + "turn_id": { + "description": "The turn this event belongs to.", + "type": [ + "integer", + "string" + ] + }, + "type": { + "const": "awaiting_llm_first_token" + } + }, + "required": [ + "type", + "turn_id" + ], + "type": "object" + }, + { + "additionalProperties": true, + "properties": { + "content": { + "type": "string" + }, + "turn_id": { + "description": "The turn this event belongs to.", + "type": [ + "integer", + "string" + ] + }, + "type": { + "const": "thinking" + } + }, + "required": [ + "type", + "turn_id" + ], + "type": "object" + }, + { + "additionalProperties": true, + "properties": { + "content": { + "type": "string" + }, + "turn_id": { + "description": "The turn this event belongs to.", + "type": [ + "integer", + "string" + ] + }, + "type": { + "const": "text" + } + }, + "required": [ + "type", + "turn_id" + ], + "type": "object" + }, + { + "additionalProperties": true, + "properties": { + "turn_id": { + "description": "The turn this event belongs to.", + "type": [ + "integer", + "string" + ] + }, + "type": { + "const": "text_boundary" + } + }, + "required": [ + "type", + "turn_id" + ], + "type": "object" + }, + { + "additionalProperties": true, + "properties": { + "name": { + "type": "string" + }, + "turn_id": { + "description": "The turn this event belongs to.", + "type": [ + "integer", + "string" + ] + }, + "type": { + "const": "tool_start" + } + }, + "required": [ + "type", + "turn_id" + ], + "type": "object" + }, + { + "additionalProperties": true, + "properties": { + "name": { + "type": "string" + }, + "result": {}, + "turn_id": { + "description": "The turn this event belongs to.", + "type": [ + "integer", + "string" + ] + }, + "type": { + "const": "tool_result" + } + }, + "required": [ + "type", + "turn_id" + ], + "type": "object" + }, + { + "additionalProperties": true, + "properties": { + "turn_id": { + "description": "The turn this event belongs to.", + "type": [ + "integer", + "string" + ] + }, + "type": { + "const": "affect_update" + } + }, + "required": [ + "type", + "turn_id" + ], + "type": "object" + }, + { + "additionalProperties": true, + "properties": { + "turn_id": { + "description": "The turn this event belongs to.", + "type": [ + "integer", + "string" + ] + }, + "type": { + "const": "done" + } + }, + "required": [ + "type", + "turn_id" + ], + "type": "object" + }, + { + "additionalProperties": true, + "properties": { + "phase": { + "type": "string" + }, + "reason": { + "type": "string" + }, + "turn_id": { + "description": "The turn this event belongs to.", + "type": [ + "integer", + "string" + ] + }, + "type": { + "const": "cancelled" + } + }, + "required": [ + "type", + "turn_id" + ], + "type": "object" + }, + { + "additionalProperties": true, + "properties": { + "error_code": { + "type": "string" + }, + "message": { + "type": "string" + }, + "turn_id": { + "description": "The turn this event belongs to.", + "type": [ + "integer", + "string" + ] + }, + "type": { + "const": "error" + } + }, + "required": [ + "type", + "turn_id" + ], + "type": "object" + } + ], + "title": "Worldtree Conversation API — SSE turn-stream events" +} diff --git a/docs/coverage-map.md b/docs/coverage-map.md index 65e19a9..ebe462f 100644 --- a/docs/coverage-map.md +++ b/docs/coverage-map.md @@ -23,14 +23,15 @@ anchors against the frozen machine-readable artifacts, NOT the prose markdown: | Conversation SSE events | `conversation-api-sse-events.schema.json` (sha `9deeebf4…`) — **11 discriminated event types** | **client** | | Bifrost wire (consumer protocol) | wire **v0.6** STABLE/FROZEN (`bifrost==1.0.0`) — memory + affect planes | **provider** (Worldtree dispatches into us) | -> **Pin drift (finding P-1).** Ratatoskr vendors the **prose markdown** -> (`docs/conversation-api-spec.md`), which is **byte-identical to live -> Worldtree's markdown** but frozen at v0.35.16-era content (last WT edit -> 2026-05-31). The markdown does **not** document the b2 surface: 7 endpoints -> (below), the 409/503 on messages-POST (#331), the unified error envelope -> (#328), or the SSE schema. **Worldtree's authoritative v1 truth is now the -> OpenAPI 2.2.0 + SSE schema JSON**, which ratatoskr does not vendor. See -> § Pin remediation. +> **Pin drift (finding P-1) — REMEDIATED 2026-06-30.** Ratatoskr formerly +> vendored only the **prose markdown** (`docs/conversation-api-spec.md`), which +> is byte-identical to live Worldtree's but frozen at v0.35.16-era content (last +> WT edit 2026-05-31) and does **not** document the b2 surface (7 endpoints +> below, the 409/503 on messages-POST #331, the unified error envelope #328, the +> SSE schema). Remediated: the **OpenAPI 2.2.0 + SSE-schema JSON are now vendored +> and pinned** (`.corviduo-canonicals.toml` → `canonical_drift.py` gate); the +> prose markdown is the `tolerate_drift` reference. Spec pin advanced to +> 5810a26 (v1.0.0b2). See § Pin remediation. **7 endpoints new in b2 OpenAPI, absent from our vendored markdown:** `/admin/keys/bulk`, `/admin/persona/archive`, `/admin/persona/erase`, @@ -219,18 +220,16 @@ starts exercising them. --- -## Pin remediation (finding P-1) +## Pin remediation (finding P-1) — DONE 2026-06-30 -The vendored prose markdown is stale against the frozen OpenAPI 2.2.0. Options -(operator-owned; see § Open decision item 2): - -- **Re-pin to the frozen machine-readable artifacts.** Vendor - `conversation-api-openapi.json` (2.2.0) + `conversation-api-sse-events.schema.json`, - add `.corviduo-canonicals.toml` pins (drift-checkable via `canonical_drift.py`), - keep the markdown as prose reference. Makes this coverage map reproducible - against a frozen, diffable target — the OpenAPI is the v1 truth. -- **Re-vendor the markdown only.** Near-no-op (content identical); leaves the - b2 surface undocumented in our pin. Not recommended. +Re-pinned to the frozen machine-readable artifacts (the chosen option): +`conversation-api-openapi.json` (2.2.0) + `conversation-api-sse-events.schema.json` +are vendored under `docs/` and pinned in `.corviduo-canonicals.toml` +(`worldtree-conversation-api-openapi-v2`, `-sse-events-v1`), drift-gated by +`canonical_drift.py`. The prose markdown stays as a `tolerate_drift` reference +(`-spec-v1`). `pyproject.toml` spec pin advanced f1b59f8 → 5810a26 (v1.0.0b2); +`docs/SPEC-PIN.md` records the bump. This map now audits a frozen, diffable +target — re-running the audit is a `canonical_drift.py` check away. --- @@ -240,8 +239,9 @@ The vendored prose markdown is stale against the frozen OpenAPI 2.2.0. Options frozen I/O point classified, zero unaccounted; NOT feature-complete client. The ⬜-vs-🚫 line for the 11 formerly-pending rows is locked above (§ Scope-resolution record). -2. **Pin remediation (P-1) — PENDING.** Re-pin to the frozen OpenAPI 2.2.0 + - SSE-schema JSON (recommended; drift-checkable via `canonical_drift.py`) vs - re-vendor markdown only (near-no-op). Adds vendored artifacts + a - canonical-sync pin → deferred to an explicit operator nod (substrate change - with CI-gating reach). +2. **Pin remediation (P-1) — RESOLVED 2026-06-30 (re-pin to machine-readable).** + Vendored `conversation-api-openapi.json` (2.2.0) + `conversation-api-sse-events.schema.json` + as the authoritative drift gates (pinned in `.corviduo-canonicals.toml`, + `canonical_drift.py` green); prose markdown kept as `tolerate_drift` + reference. Spec pin advanced f1b59f8 (v0.35.16) → 5810a26 (v1.0.0b2). This + map now audits against a frozen, diffable target. diff --git a/persistent-memory.md b/persistent-memory.md index 3cd4a0e..b451a1f 100644 --- a/persistent-memory.md +++ b/persistent-memory.md @@ -146,7 +146,7 @@ decision. Captures rationale that won't be obvious from code alone. - `[2026-06-30]` **regard is a DEAD AXIS in Worldtree's emitted affect (caught provider-side; worldtree-dev confirmed + escalated to Vuong).** Across all our affect snapshots, `valence[].regard` is EXACTLY 0.15 regardless of agent/end_user/interaction_count, while familiarity accumulates (vuong 0.18→0.69 over 14 turns). Root cause (worldtree-dev, code-grounded): 0.15 = `base_regard = agreeableness*0.3` (sindra A=0.5); regard's only human-writer `update_regard` early-returns unless an emotion is `about="other"`, but the Vili appraiser's `ViliResponse` schema has NO directedness axis (everything hardcoded `about="situation"`) — producer side lost in the #265 Vili rework; consumer machinery intact. NOT WAD; the fix (reintroduce other-directed classification) is an affect-model change touching every agent + a directedness-classification design call → worldtree-dev filing an issue to Vuong. [the consumer/provider thesis paying off again] - `[2026-06-30]` **v1 coverage-audit kicked off; coverage ledger written (`docs/coverage-map.md`) — the first one.** Every Worldtree v1-FROZEN I/O point × ratatoskr status. Anchored on WT's frozen machine-readable artifacts (OpenAPI **2.2.0** `conversation-api-openapi.json` = 40 REST path-groups + SSE schema = 11 events + bifrost wire v0.6), NOT the stale vendored prose markdown. Result: **SSE 11/11 ✅; Bifrost provider planes 8/8 ✅ live-proven** (covers the full `bifrost.memory.MemoryDataStore` protocol = describe_store/get/get_many/search/upsert_many + delete_many, and affect emit/fetch; **`health` is extended-reference-store-only, NOT in the base protocol → correctly deferred, NOT a gap** — settles the prior "health" ambiguity); **client REST 7/40 ✅ live, 11 ⬜ in-scope, 22 🚫 excluded.** - `[2026-06-30]` **Scope mandate A locked (operator): v1 "done" = every frozen I/O point CLASSIFIED (covered-or-excluded-with-rationale), zero unaccounted — NOT a feature-complete client.** The coverage map is a LEDGER, not a build-everything mandate. Reconciles the 2026-06-19 "consume all I/O" reframe with the 2026-05-20 design-brief's "NOT an admin tool" + deferral negative clauses (which predate both the provider identity and the reframe). Resolved the 11 design-brief-vs-reframe ❓ rows via the debug-observability test (*does a turn flow through it?*): 🚫 search / uploads / pending / embed / judgments (consumer-product + eval utilities); ⬜ transient-characters routing (4) + persona_state-write (Tier-2 frontier). **Frontier Tier 1 (all unblocked except #11):** session-picker + SSE-resume (wrappers `list_sessions`/`reconnect_turn` exist with NO caller — presenter-wiring only) → `GET /capabilities` + `GET /me` → BifrostState/Tools widgets (`GET /admin/sessions/{id}/{bifrost,tools}`, admin-key) → **#11 AdminEvents BLOCKED on `admin.events.read` scope**. The 3 admin-observability widgets + picker + resume were design-brief §5/§4/§8d v1 items that **were never built**. -- `[2026-06-30]` **Finding P-1 (pin drift) + pin-remediation PENDING.** We vendor the PROSE markdown (`docs/conversation-api-spec.md`), which is **byte-identical to live WT's** but frozen at v0.35.16-era content (last WT edit 2026-05-31) — it does NOT capture b2: 7 new endpoints (admin/keys/bulk, admin/persona/{archive,erase}, admin/usage, embed, judgments, me/usage), the 409/503 on messages-POST (#331), the unified error envelope (#328), or the SSE schema. **WT's authoritative v1 truth is now the FROZEN OpenAPI 2.2.0 + SSE-schema JSON** (`Worldtree/docs/v1-schema-freeze-manifest.md`). So the previously-deferred "re-vendor markdown to b2" is a **near-no-op** (markdown content identical). **Pending operator nod:** re-pin to the machine-readable artifacts (recommended — drift-checkable via `canonical_drift.py`, makes the coverage map reproducible vs a frozen diffable target) vs markdown-only. Deferred (not auto-applied) because it adds vendored artifacts + a canonical-sync pin = substrate change with CI-gating reach. +- `[2026-06-30]` **Finding P-1 (pin drift) + pin-remediation PENDING.** We vendor the PROSE markdown (`docs/conversation-api-spec.md`), which is **byte-identical to live WT's** but frozen at v0.35.16-era content (last WT edit 2026-05-31) — it does NOT capture b2: 7 new endpoints (admin/keys/bulk, admin/persona/{archive,erase}, admin/usage, embed, judgments, me/usage), the 409/503 on messages-POST (#331), the unified error envelope (#328), or the SSE schema. **WT's authoritative v1 truth is now the FROZEN OpenAPI 2.2.0 + SSE-schema JSON** (`Worldtree/docs/v1-schema-freeze-manifest.md`). So the previously-deferred "re-vendor markdown to b2" is a **near-no-op** (markdown content identical). **Pending operator nod:** re-pin to the machine-readable artifacts (recommended — drift-checkable via `canonical_drift.py`, makes the coverage map reproducible vs a frozen diffable target) vs markdown-only. Deferred (not auto-applied) because it adds vendored artifacts + a canonical-sync pin = substrate change with CI-gating reach. **→ RESOLVED 2026-06-30 (operator: "a then b").** Vendored `conversation-api-openapi.json` (2.2.0) + `conversation-api-sse-events.schema.json` + re-copied the prose markdown; pinned all three in `.corviduo-canonicals.toml` (OpenAPI+SSE = strict drift gates, markdown = `tolerate_drift` reference); advanced `worldtree-spec-rev` f1b59f8→5810a26 + `worldtree-version` v0.29.0(STALE, never bumped from the v0.35.16 pin)→v1.0.0b2 + `pinned-on`→2026-06-30; SPEC-PIN.md history row added. `canonical_drift.py` green (10/10). `pin:`-only, no version bump (no client-facing code change; the b2 409/503 + error-envelope were already consumed in v0.18.3/.4). _41 older entries (2026-05-* — the original debug-TUI/web build era) archived to archival-memory.md._ diff --git a/pyproject.toml b/pyproject.toml index a265393..a1b7c1b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -60,9 +60,9 @@ Repository = "https://gitea.phasefinal.com/vh/ratatoskr" # Ratatoskr is built against Worldtree at this commit; the vendored # spec snapshot in docs/ reflects that SHA. [tool.ratatoskr.spec-pin] -worldtree-spec-rev = "f1b59f8cd6fe41e497d0be9dad9d3110451f0d9a" -worldtree-version = "v0.29.0" -pinned-on = "2026-05-26" +worldtree-spec-rev = "5810a26b38a5ea6630892f9a39756f57c5b7b41e" +worldtree-version = "v1.0.0b2" +pinned-on = "2026-06-30" # Bifrost lives on the auth-gated gitea PyPI index (not public PyPI). # uv reads the credential from UV_INDEX_GITEA_USERNAME / _PASSWORD or ~/.netrc.