ummaya 0.2.4 → 0.2.5

package/tui/src/ipc/schema/frame.schema.json

@@ -1 +1 @@
-{"$defs": {"AdapterManifestEntry": {"additionalProperties": false, "description": "One adapter record inside an ``AdapterManifestSyncFrame.entries`` array.\n\nUsed by the TS-side cache to resolve ``tool_id`` and populate the citation\nslot in permission prompts.\n\nValidators:\n- ``policy_authority_url`` required (HTTPS) when ``source_mode`` is ``\"live\"``\n  or ``\"mock\"``; ``None`` only allowed when ``source_mode == \"internal\"`` (I4/I5).\n- ``tool_id`` matches ``^[a-z][a-z0-9_]*$`` (I7).", "properties": {"tool_id": {"description": "Globally unique adapter id within the registry, e.g. 'nmc_emergency_search'. Lowercase snake-case; validated by I7.", "minLength": 1, "title": "Tool Id", "type": "string"}, "name": {"description": "Human-readable display name; bilingual permitted.", "maxLength": 80, "minLength": 1, "title": "Name", "type": "string"}, "primitive": {"description": "Primitive verb the adapter is registered under (I6).", "enum": ["find", "send", "check", "locate"], "title": "Primitive", "type": "string"}, "policy_authority_url": {"anyOf": [{"maxLength": 2048, "type": "string"}, {"type": "null"}], "default": null, "description": "Agency-published policy URL (HTTPS). None only when source_mode == 'internal' (I4/I5).", "title": "Policy Authority Url"}, "source_mode": {"description": "Tag for the citation-rendering surface.", "enum": ["live", "mock", "internal"], "title": "Source Mode", "type": "string"}, "search_hint": {"anyOf": [{"maxLength": 4096, "minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "Bilingual adapter discovery phrase copied from the backend registry. Used by the TUI concrete tool surface and tool-search metadata.", "title": "Search Hint"}, "llm_description": {"anyOf": [{"maxLength": 20000, "minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "Backend-authored model-facing adapter usage prose. This is the same description the backend exposes in OpenAI/FriendliAI function metadata.", "title": "Llm Description"}, "input_schema_json": {"additionalProperties": true, "description": "Full backend Pydantic JSON Schema for adapter input parameters. Credential-only fields such as authKey must be omitted by adapters.", "title": "Input Schema Json", "type": "object"}, "output_schema_json": {"additionalProperties": true, "description": "Full backend Pydantic JSON Schema for adapter output data.", "title": "Output Schema Json", "type": "object"}}, "required": ["tool_id", "name", "primitive", "source_mode"], "title": "AdapterManifestEntry", "type": "object"}, "AdapterManifestSyncFrame": {"additionalProperties": false, "description": "Full registry snapshot emitted by the backend exactly once after boot.\n\n21st arm of the ``IPCFrame`` discriminated union (Epic \u03b5 #2296).\n\nInvariants enforced at construction:\n- I1: ``entries`` is non-empty.\n- I2: No two entries share the same ``tool_id``.\n- I3: ``manifest_hash == sha256(canonical_json(sorted(entries, key=tool_id)))``.\n- I4/I5/I6/I7: delegated to ``AdapterManifestEntry`` validators.\n\nOn invariant violation the Pydantic validator raises ``ValueError``; the\nbackend boot should catch this and exit with ``SystemExit(78)`` per\nConstitution \u00a7 II + Spec 1634 boot-validation pattern.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "adapter_manifest_sync", "default": "adapter_manifest_sync", "description": "Frame discriminator \u2014 21st arm of IPCFrame.", "title": "Kind", "type": "string"}, "entries": {"description": "Full registry snapshot. Non-empty (I1); no duplicate tool_id (I2).", "items": {"$ref": "#/$defs/AdapterManifestEntry"}, "minItems": 1, "title": "Entries", "type": "array"}, "manifest_hash": {"description": "Lowercase hex SHA-256 of canonical-JSON-serialised entries sorted by tool_id (I3). Cheap change-detection for hot-reload (future epic).", "maxLength": 64, "minLength": 64, "title": "Manifest Hash", "type": "string"}, "emitter_pid": {"description": "Python backend PID at boot. Useful for OTEL span cross-correlation.", "exclusiveMinimum": 0, "title": "Emitter Pid", "type": "integer"}}, "required": ["session_id", "correlation_id", "ts", "role", "entries", "manifest_hash", "emitter_pid"], "title": "AdapterManifestSyncFrame", "type": "object"}, "AssistantChunkFrame": {"additionalProperties": false, "description": "backend -> TUI: streaming assistant text delta.\n\nMirrors Anthropic's ``content_block_delta`` (CC reference at\n``ummaya/llm/_cc_reference/claude.ts:2053-2169``). The ``delta`` field\ncarries the visible answer text (``text_delta`` in CC nomenclature);\n``thinking`` carries the model's chain-of-thought (``thinking_delta``\non the Anthropic side, K-EXAONE's ``delta.reasoning_content`` on the\nOpenAI-compatible FriendliAI feed). Exactly one of ``delta`` /\n``thinking`` carries content per frame \u2014 the empty one is the\nbackward-compatible default. ``done`` terminates the message\nregardless of channel.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "assistant_chunk", "default": "assistant_chunk", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "message_id": {"description": "ULID of the assistant message this delta belongs to.", "title": "Message Id", "type": "string"}, "delta": {"default": "", "description": "UTF-8 text appended to the visible answer (text_delta channel).", "title": "Delta", "type": "string"}, "thinking": {"default": "", "description": "UTF-8 text appended to the model's chain-of-thought (thinking_delta channel \u2014 K-EXAONE delta.reasoning_content).", "title": "Thinking", "type": "string"}, "done": {"description": "True if this is the terminal chunk for this message_id.", "title": "Done", "type": "boolean"}}, "required": ["session_id", "correlation_id", "ts", "role", "message_id", "done"], "title": "AssistantChunkFrame", "type": "object"}, "BackpressureSignalFrame": {"additionalProperties": false, "description": "Emitted when outgoing queue crosses HWM or a 429 condition is detected.\n\nrole allow-list: tui (tui_reader), backend (backend_writer, upstream_429).\nFR-012, FR-015: hud_copy_ko/en MUST be non-empty (min_length=1).", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "backpressure", "default": "backpressure", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "signal": {"description": "Reader action. pause=stop emitting; resume=clear; throttle=slow down.", "enum": ["pause", "resume", "throttle"], "title": "Signal", "type": "string"}, "source": {"description": "Origin of the signal.", "enum": ["tui_reader", "backend_writer", "upstream_429"], "title": "Source", "type": "string"}, "queue_depth": {"description": "Current outbound queue size.", "minimum": 0, "title": "Queue Depth", "type": "integer"}, "hwm": {"description": "High-water mark threshold in effect (default 64).", "minimum": 1, "title": "Hwm", "type": "integer"}, "retry_after_ms": {"anyOf": [{"minimum": 0, "type": "integer"}, {"type": "null"}], "default": null, "description": "For throttle sourced from upstream_429; reflects Retry-After. ge=0.", "title": "Retry After Ms"}, "hud_copy_ko": {"description": "Korean HUD copy (civic-facing). Must be non-empty (FR-015).", "minLength": 1, "title": "Hud Copy Ko", "type": "string"}, "hud_copy_en": {"description": "English HUD copy (dev-facing). Must be non-empty (FR-015).", "minLength": 1, "title": "Hud Copy En", "type": "string"}}, "required": ["session_id", "correlation_id", "ts", "role", "signal", "source", "queue_depth", "hwm", "hud_copy_ko", "hud_copy_en"], "title": "BackpressureSignalFrame", "type": "object"}, "ChatMessage": {"additionalProperties": false, "description": "One conversation-history entry carried by ``ChatRequestFrame.messages``.\n\n``role=\"tool\"`` messages MUST also set ``name`` (the tool name that was\ninvoked) and ``tool_call_id`` (the originating ``tool_call`` envelope's\ncorrelation id). This is the data-model invariant D4 (tool message\nintegrity) enforced by the ``ChatRequestFrame`` validator below.\n\nLead-Diag-4 (2026-05-04): added optional ``tool_calls`` for ``role='assistant'``\nturns so assistant ``tool_use`` blocks survive the wire round-trip and the\nOpenAI Chat Completions multi-turn pairing invariant (every ``role='tool'``\nmessage MUST follow an assistant message whose ``tool_calls[i].id`` matches\nthe result's ``tool_call_id``) is satisfied. Backward compatible: legacy\nsenders that omit ``tool_calls`` are unaffected.", "properties": {"role": {"description": "Conversation turn author.", "enum": ["system", "user", "assistant", "tool"], "title": "Role", "type": "string"}, "content": {"description": "UTF-8 message body.", "title": "Content", "type": "string"}, "name": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Tool name when role='tool'; None otherwise.", "title": "Name"}, "tool_call_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Matching ``ToolCallFrame.call_id`` when role='tool'; None otherwise.", "title": "Tool Call Id"}, "tool_calls": {"anyOf": [{"items": {"$ref": "#/$defs/ChatMessageToolCall"}, "type": "array"}, {"type": "null"}], "default": null, "description": "OpenAI Chat Completions assistant-turn tool invocations. Set ONLY on role='assistant' messages that requested one or more tool calls. None for every other role. Each entry's ``id`` is the pairing key that the corresponding role='tool' result message MUST set as its ``tool_call_id``.", "title": "Tool Calls"}}, "required": ["role", "content"], "title": "ChatMessage", "type": "object"}, "ChatMessageFunctionCall": {"additionalProperties": false, "description": "OpenAI-spec ``function`` block carried inside ``ChatMessageToolCall``.\n\nMirrors ``ummaya.llm.models.FunctionCall`` (the LLM-client-internal model)\nbut lives on the *wire* so the TUI can transmit assistant ``tool_use``\nblocks across multi-turn boundaries (Lead-Diag-4, role='tool' wire fix).", "properties": {"name": {"description": "Function/tool name the model requested.", "title": "Name", "type": "string"}, "arguments": {"description": "JSON-serialised string of the function arguments (OpenAI spec).", "title": "Arguments", "type": "string"}}, "required": ["name", "arguments"], "title": "ChatMessageFunctionCall", "type": "object"}, "ChatMessageToolCall": {"additionalProperties": false, "description": "OpenAI-spec ``tool_calls[i]`` entry carried by an assistant ``ChatMessage``.\n\nOpenAI Chat Completions API spec: every ``role='tool'`` message MUST be\npaired (by ``tool_call_id``) with a ``tool_calls[i].id`` from a preceding\nassistant turn. The TUI carries this pairing across the wire so multi-turn\nconversations replay correctly to FriendliAI / OpenAI-compatible providers\n(Lead-Diag-4 fix, 2026-05-04).", "properties": {"id": {"description": "Matching ``ToolCallFrame.call_id`` / ``role='tool'.tool_call_id``.", "title": "Id", "type": "string"}, "type": {"const": "function", "default": "function", "description": "OpenAI tool envelope; only 'function' is currently supported.", "title": "Type", "type": "string"}, "function": {"$ref": "#/$defs/ChatMessageFunctionCall", "description": "Inner function name + JSON-serialised arguments."}}, "required": ["id", "function"], "title": "ChatMessageToolCall", "type": "object"}, "ChatRequestFrame": {"additionalProperties": false, "description": "TUI -> backend: tools-aware chat request (Spec 1978 ADR-0001).\n\nCoexists with ``UserInputFrame`` (which remains the echo / smoke-test path).\nThe backend treats a ``UserInputFrame{text=t}`` as\n``ChatRequestFrame{messages=[{role:'user', content:t}], tools=[]}``.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "chat_request", "default": "chat_request", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "messages": {"description": "Conversation history; tail message has role 'user' or 'tool'.", "items": {"$ref": "#/$defs/ChatMessage"}, "minItems": 1, "title": "Messages", "type": "array"}, "tools": {"description": "Tools available to the model this turn.", "items": {"$ref": "#/$defs/ToolDefinition"}, "title": "Tools", "type": "array"}, "system": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Effective system prompt (may be None if backend supplies its own).", "title": "System"}, "max_tokens": {"default": 8192, "description": "Maximum tokens for the assistant turn.", "maximum": 32000, "minimum": 1, "title": "Max Tokens", "type": "integer"}, "temperature": {"default": 1.0, "description": "Sampling temperature.", "maximum": 2.0, "minimum": 0.0, "title": "Temperature", "type": "number"}, "top_p": {"default": 0.95, "description": "Nucleus sampling threshold.", "maximum": 1.0, "minimum": 0.0, "title": "Top P", "type": "number"}, "reasoning_mode": {"anyOf": [{"enum": ["fast", "balanced", "deep", "diagnostic", "auto"], "type": "string"}, {"type": "null"}], "default": null, "description": "K-EXAONE/FriendliAI reasoning policy for this assistant turn.", "title": "Reasoning Mode"}}, "required": ["session_id", "correlation_id", "ts", "role", "messages"], "title": "ChatRequestFrame", "type": "object"}, "ConsentRevokeRequestFrame": {"additionalProperties": false, "description": "TUI -> backend: citizen requests revocation of a prior consent receipt.\n\narm 22 of the ``IPCFrame`` discriminated union (Epic 2).\n\nFields:\n- ``request_id``: UUIDv4 string; round-trips in the matching\n  ``consent_revoke_response`` frame.\n- ``receipt_id``: The ``rcpt-<id>`` value referencing the receipt file at\n  ``~/.ummaya/memdir/user/consent/<receipt_id>.json``.\n- ``scope``: ``\"once\"`` = revoke this single receipt only;\n  ``\"session-all\"`` = revoke all receipts for the current session.\n- ``reason``: Optional free-text reason logged to the audit ledger.\n\nrole allow-list: tui.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "consent_revoke_request", "default": "consent_revoke_request", "description": "Frame discriminator \u2014 arm 22 of IPCFrame.", "title": "Kind", "type": "string"}, "request_id": {"description": "UUIDv4 round-trip correlation ID; matched in consent_revoke_response.", "minLength": 1, "title": "Request Id", "type": "string"}, "receipt_id": {"description": "Target receipt identifier (rcpt-<id>). Must match an existing receipt file at ~/.ummaya/memdir/user/consent/<receipt_id>.json.", "minLength": 1, "title": "Receipt Id", "type": "string"}, "scope": {"description": "Revocation scope. 'once' revokes only this receipt; 'session-all' revokes all receipts in the current session.", "enum": ["once", "session-all"], "title": "Scope", "type": "string"}, "reason": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Optional citizen-provided reason logged to the ledger (PIPA \u00a736 citation).", "title": "Reason"}}, "required": ["session_id", "correlation_id", "ts", "role", "request_id", "receipt_id", "scope"], "title": "ConsentRevokeRequestFrame", "type": "object"}, "ConsentRevokeResponseFrame": {"additionalProperties": false, "description": "backend -> TUI: outcome of a consent_revoke_request.\n\narm 23 of the ``IPCFrame`` discriminated union (Epic 2).\n\nFields:\n- ``request_id``: Mirrors the originating consent_revoke_request.request_id.\n- ``ok``: True when at least one receipt was revoked; False on error or\n  not-found.\n- ``revoked_at``: ISO-8601 UTC timestamp of the revocation (when ok=True).\n- ``record_hash``: Ledger entry SHA-256 for audit chain verification\n  (when ok=True; omitted on error).\n- ``error``: Machine-readable error code on failure (``already_revoked``,\n  ``not_found``, ``io_error``); omitted on success.\n\nrole allow-list: backend.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "consent_revoke_response", "default": "consent_revoke_response", "description": "Frame discriminator \u2014 arm 23 of IPCFrame.", "title": "Kind", "type": "string"}, "request_id": {"description": "Mirrors consent_revoke_request.request_id for round-trip correlation.", "minLength": 1, "title": "Request Id", "type": "string"}, "ok": {"description": "True when at least one receipt was successfully revoked; False on error or not-found.", "title": "Ok", "type": "boolean"}, "revoked_at": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "ISO-8601 UTC timestamp of revocation. Populated when ok=True.", "title": "Revoked At"}, "record_hash": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Hex SHA-256 of the ledger withdrawal record. Populated when ok=True for audit-chain verification.", "title": "Record Hash"}, "error": {"anyOf": [{"enum": ["already_revoked", "not_found", "io_error"], "type": "string"}, {"type": "null"}], "default": null, "description": "Machine-readable error code when ok=False; None on success.", "title": "Error"}}, "required": ["session_id", "correlation_id", "ts", "role", "request_id", "ok"], "title": "ConsentRevokeResponseFrame", "type": "object"}, "CoordinatorPhaseFrame": {"additionalProperties": false, "description": "backend -> TUI: Spec 027 coordinator phase update.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "coordinator_phase", "default": "coordinator_phase", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "phase": {"description": "Current coordinator phase.", "enum": ["Research", "Synthesis", "Implementation", "Verification"], "title": "Phase", "type": "string"}}, "required": ["session_id", "correlation_id", "ts", "role", "phase"], "title": "CoordinatorPhaseFrame", "type": "object"}, "ErrorFrame": {"additionalProperties": false, "description": "backend -> TUI: a backend error surfaced to the TUI for rendering.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "error", "default": "error", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "code": {"description": "Machine-readable error code (e.g., 'backend_crash', 'protocol_mismatch').", "title": "Code", "type": "string"}, "message": {"description": "Human-readable short message. MUST NOT contain UMMAYA_*-prefixed env var values (FR-004 redaction rule).", "title": "Message", "type": "string"}, "details": {"additionalProperties": true, "description": "Structured error details. UMMAYA_* env var values MUST be redacted.", "title": "Details", "type": "object"}}, "required": ["session_id", "correlation_id", "ts", "role", "code", "message", "details"], "title": "ErrorFrame", "type": "object"}, "FrameTrailer": {"additionalProperties": false, "description": "Completion/validation metadata on terminal frames (FR-006).", "properties": {"final": {"description": "True when this frame terminates a logical payload/stream.", "title": "Final", "type": "boolean"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "Mirror of envelope transaction_id for trailer-only consumers. Non-empty when present (parity with codec.ts trailer schema \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "checksum_sha256": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Hex SHA-256 of the concatenated payload bytes for streamed payloads.", "title": "Checksum Sha256"}}, "required": ["final"], "title": "FrameTrailer", "type": "object"}, "HeartbeatFrame": {"additionalProperties": false, "description": "Emitted every 30 s (default) by both sides to prove liveness.\n\nNote: Heartbeat frames do NOT increment frame_seq \u2014 they use a dedicated\ncounter. This keeps ring-buffer economy tight.\nrole allow-list: tui, backend.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "heartbeat", "default": "heartbeat", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "direction": {"description": "ping from sender, pong from receiver.", "enum": ["ping", "pong"], "title": "Direction", "type": "string"}, "peer_frame_seq": {"description": "Sender's current outbound frame_seq high-water.", "minimum": 0, "title": "Peer Frame Seq", "type": "integer"}}, "required": ["session_id", "correlation_id", "ts", "role", "direction", "peer_frame_seq"], "title": "HeartbeatFrame", "type": "object"}, "NotificationPushFrame": {"additionalProperties": false, "description": "Push from app/phone notification surfaces.\n\nCarried over the same stdio channel to keep a single correlation plane.\nrole allow-list: notification.\n\nCC parity: NO equivalent \u2014 Claude Code's notification surface is\nterminal OSC sequences (iTerm2, Kitty, Ghostty, bell) emitted\nin-process from ``ink/useTerminalNotification.ts``. There is no\npush-based IPC notification arm in CC. UMMAYA adds this arm as a\nswap-2 addition for Korean civic push channels (KMA disaster CBS,\ngovernment newsroom alerts, hospital alerts) carried over the\nsame stdio plane to keep a single correlation plane. Spec 2642\nEpic F \u00b7 S7 audit recorded this finding (specs/cc-migration-audit/\nscope-S7-ipc-bridge.md \u00a7 5 Finding 3 \u2014 resolved as orthogonal\nUMMAYA swap-2 add-on, not a CC-divergence regression).", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "notification_push", "default": "notification_push", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "subscription_id": {"description": "Notification channel handle.", "title": "Subscription Id", "type": "string"}, "adapter_id": {"description": "e.g., disaster_alert_cbs_push, gov_newsroom_push.", "title": "Adapter Id", "type": "string"}, "event_guid": {"description": "RSS guid or CBS event hash for duplicate suppression.", "title": "Event Guid", "type": "string"}, "payload_content_type": {"description": "Inline payload MIME.", "enum": ["text/plain", "application/json"], "title": "Payload Content Type", "type": "string"}, "payload": {"description": "Inline notification content (Korean for civic users).", "title": "Payload", "type": "string"}}, "required": ["session_id", "correlation_id", "ts", "role", "subscription_id", "adapter_id", "event_guid", "payload_content_type", "payload"], "title": "NotificationPushFrame", "type": "object"}, "PayloadDeltaFrame": {"additionalProperties": false, "description": "One chunk of a streamed payload.\n\nrole allow-list: backend, tool, llm.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "payload_delta", "default": "payload_delta", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "delta_seq": {"description": "Monotonic within the payload (first delta = 0).", "minimum": 0, "title": "Delta Seq", "type": "integer"}, "payload": {"description": "UTF-8 text. If content-type is application/json, this is a JSON-encoded fragment string.", "title": "Payload", "type": "string"}}, "required": ["session_id", "correlation_id", "ts", "role", "delta_seq", "payload"], "title": "PayloadDeltaFrame", "type": "object"}, "PayloadEndFrame": {"additionalProperties": false, "description": "Terminates a streamed payload.\n\nMUST carry a trailer with final=True.\nrole allow-list: backend, tool, llm.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "payload_end", "default": "payload_end", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "delta_count": {"description": "Total number of payload_delta frames emitted.", "minimum": 0, "title": "Delta Count", "type": "integer"}, "status": {"description": "Terminal disposition.", "enum": ["ok", "aborted"], "title": "Status", "type": "string"}}, "required": ["session_id", "correlation_id", "ts", "role", "delta_count", "status"], "title": "PayloadEndFrame", "type": "object"}, "PayloadStartFrame": {"additionalProperties": false, "description": "Begins a streamed payload (assistant output, tool result chunking).\n\nSender MUST follow with >= 1 payload_delta and exactly one payload_end.\nrole allow-list: backend, tool, llm.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "payload_start", "default": "payload_start", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "content_type": {"description": "Payload MIME type.", "enum": ["text/markdown", "application/json", "text/plain"], "title": "Content Type", "type": "string"}, "estimated_bytes": {"anyOf": [{"minimum": 0, "type": "integer"}, {"type": "null"}], "default": null, "description": "Optional size hint for HUD progress bars.", "title": "Estimated Bytes"}}, "required": ["session_id", "correlation_id", "ts", "role", "content_type"], "title": "PayloadStartFrame", "type": "object"}, "PermissionRequestFrame": {"additionalProperties": false, "description": "backend -> TUI: a worker raises a permission request.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "permission_request", "default": "permission_request", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "request_id": {"description": "ULID; round-trips in the matching permission_response frame.", "title": "Request Id", "type": "string"}, "worker_id": {"description": "Worker requesting permission.", "title": "Worker Id", "type": "string"}, "primitive_kind": {"description": "The primitive the worker wants to invoke.", "enum": ["find", "locate", "send", "check"], "title": "Primitive Kind", "type": "string"}, "description_ko": {"description": "Korean-language description shown to the citizen.", "title": "Description Ko", "type": "string"}, "description_en": {"description": "English-language description shown alongside the Korean one.", "title": "Description En", "type": "string"}, "risk_level": {"description": "Risk classification of the requested operation.", "enum": ["low", "medium", "high"], "title": "Risk Level", "type": "string"}, "tool_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Fully-qualified adapter id (e.g. `mock_verify_mobile_id`). Falls back to worker_id || primitive_kind in the TUI when None. None for legacy callers that have not yet been updated.", "title": "Tool Id"}}, "required": ["session_id", "correlation_id", "ts", "role", "request_id", "worker_id", "primitive_kind", "description_ko", "description_en", "risk_level"], "title": "PermissionRequestFrame", "type": "object"}, "PermissionResponseFrame": {"additionalProperties": false, "description": "TUI -> backend: citizen's decision on a permission_request.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "permission_response", "default": "permission_response", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "request_id": {"description": "ULID matching the originating permission_request.request_id.", "title": "Request Id", "type": "string"}, "decision": {"description": "Citizen's permission decision.", "enum": ["granted", "allow_once", "allow_session", "denied", "deny"], "title": "Decision", "type": "string"}, "receipt_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Consent receipt UUID written to ~/.ummaya/memdir/user/consent/<id>.json on granted decisions. None on deny / timeout.", "title": "Receipt Id"}, "primitive_kind": {"anyOf": [{"enum": ["find", "locate", "send", "check"], "type": "string"}, {"type": "null"}], "default": null, "description": "The primitive that was authorised. The TUI feeds this into `aalToLayer(primitive, isIrreversible)` to recompute the gauntlet layer (1=green / 2=orange / 3=red) for the receipt row. None on deny / timeout / legacy backends.", "title": "Primitive Kind"}, "tool_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "The fully-qualified adapter id (e.g. `mock_verify_mobile_id`, `mock_submit_welfare_grant`) the citizen authorised. The TUI uses this to render the human-readable Korean adapter name in /consent list and the modal title. None for non-adapter primitives (rare) or legacy backends.", "title": "Tool Id"}}, "required": ["session_id", "correlation_id", "ts", "role", "request_id", "decision"], "title": "PermissionResponseFrame", "type": "object"}, "PluginOpFrame": {"additionalProperties": false, "description": "Plugin install / uninstall / list control-plane frame.\n\nSingle arm carrying the three operation states discriminated by the\ninner ``op`` field. Modelled as one ``kind`` so the IPC discriminator\nkeeps ``plugin_op`` as a single 20th arm \u2014 matching the migration\ntree's \"20th arm\" decision while preserving the per-phase shape\ndocumented in ``contracts/plugin-install.cli.md``.\n\nOp-specific shape rules (enforced by ``_v_plugin_op_shape``):\n\n* ``op=\"request\"``: ``name`` required when ``request_op`` is\n  ``\"install\"`` or ``\"uninstall\"``; ``progress_phase`` /\n  ``progress_message_ko`` / ``progress_message_en`` / ``result`` /\n  ``exit_code`` MUST be ``None``.\n* ``op=\"progress\"``: ``progress_phase`` (1-7), ``progress_message_ko``,\n  ``progress_message_en`` required; install-request fields must be\n  ``None``.\n* ``op=\"complete\"``: ``result`` + ``exit_code`` required; everything\n  else None except optional ``receipt_id``.\n\nrole allow-list: tui (request), backend (progress / complete).", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "plugin_op", "default": "plugin_op", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "op": {"description": "Operation phase. ``request`` = TUI initiates install/uninstall/list; ``progress`` = backend reports phase tick; ``complete`` = backend reports terminal outcome.", "enum": ["request", "progress", "complete"], "title": "Op", "type": "string"}, "request_op": {"anyOf": [{"enum": ["install", "uninstall", "list"], "type": "string"}, {"type": "null"}], "default": null, "description": "Sub-action when op='request'. Required for op='request'; None otherwise.", "title": "Request Op"}, "name": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Plugin catalog name (matches CatalogEntry.name). Required when request_op in {install, uninstall}; None otherwise.", "title": "Name"}, "requested_version": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Optional SemVer pin for op='request'/install. Renamed from `version` to avoid shadowing the envelope's protocol version.", "title": "Requested Version"}, "dry_run": {"anyOf": [{"type": "boolean"}, {"type": "null"}], "default": null, "description": "When True, install verifies but writes nothing (op='request').", "title": "Dry Run"}, "progress_phase": {"anyOf": [{"type": "integer"}, {"type": "null"}], "default": null, "description": "Install phase index 1-7 per contracts/plugin-install.cli.md. Required when op='progress'.", "title": "Progress Phase"}, "progress_message_ko": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Korean-primary progress message shown in the Ink overlay.", "title": "Progress Message Ko"}, "progress_message_en": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "English fallback progress message.", "title": "Progress Message En"}, "result": {"anyOf": [{"enum": ["success", "failure"], "type": "string"}, {"type": "null"}], "default": null, "description": "Terminal outcome. Required when op='complete'.", "title": "Result"}, "exit_code": {"anyOf": [{"type": "integer"}, {"type": "null"}], "default": null, "description": "Process exit code per contracts/plugin-install.cli.md exit-code table. Required when op='complete'.", "title": "Exit Code"}, "receipt_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Spec 035 consent receipt id when op='complete' AND result='success'.", "title": "Receipt Id"}, "error_kind": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Machine-readable failure kind (e.g. 'bundle_sha_mismatch', 'slsa_skip_in_production') when op='complete' AND result='failure'. Used by the TUI to map exit codes to citizen-friendly Korean messages.", "title": "Error Kind"}, "error_message": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Developer-facing English error detail when op='complete' AND result='failure'.", "title": "Error Message"}, "was_idempotent_noop": {"anyOf": [{"type": "boolean"}, {"type": "null"}], "default": null, "description": "True when op='complete' + result='success' but the operation was a no-op because the plugin was already in the target state (e.g. uninstall of a plugin that was never installed). TUI uses this to show '\uc774\ubbf8 \uc81c\uac70\ub428' instead of '\uc81c\uac70 \uc644\ub8cc'.", "title": "Was Idempotent Noop"}}, "required": ["session_id", "correlation_id", "ts", "role", "op"], "title": "PluginOpFrame", "type": "object"}, "ProgressEventFrame": {"additionalProperties": false, "description": "backend -> TUI: deterministic query-loop progress.\n\nThis is intentionally separate from ``AssistantChunkFrame.thinking``.\n``progress_event`` carries safe harness state such as analysis, tool\nselection, tool dispatch/result, and answer synthesis. Provider reasoning\nremains on the gated ``thinking_delta`` channel.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "progress_event", "default": "progress_event", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "phase": {"description": "Safe query-loop phase represented by this event.", "enum": ["analysis", "tool_selection", "tool_call", "tool_result", "answer_synthesis"], "title": "Phase", "type": "string"}, "message_ko": {"description": "Korean progress text for the TUI.", "minLength": 1, "title": "Message Ko", "type": "string"}, "message_en": {"description": "English fallback progress text.", "minLength": 1, "title": "Message En", "type": "string"}, "safe_to_persist": {"default": true, "description": "True because this channel never carries raw provider chain-of-thought.", "title": "Safe To Persist", "type": "boolean"}, "tool_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Concrete adapter/tool id when this event is tied to one.", "title": "Tool Id"}, "call_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Tool call id when this event is tied to a specific invocation.", "title": "Call Id"}}, "required": ["session_id", "correlation_id", "ts", "role", "phase", "message_ko", "message_en"], "title": "ProgressEventFrame", "type": "object"}, "ResumeRejectedFrame": {"additionalProperties": false, "description": "Backend cannot honor the resume request.\n\nTrailer with final=True MUST be set (E6).\nrole allow-list: backend.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "resume_rejected", "default": "resume_rejected", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "reason": {"description": "Machine-readable reason code.", "enum": ["ring_evicted", "session_unknown", "token_mismatch", "protocol_incompatible", "session_expired"], "title": "Reason", "type": "string"}, "detail": {"description": "Human-readable Korean/English detail for HUD.", "title": "Detail", "type": "string"}}, "required": ["session_id", "correlation_id", "ts", "role", "reason", "detail"], "title": "ResumeRejectedFrame", "type": "object"}, "ResumeRequestFrame": {"additionalProperties": false, "description": "Sent by the reconnecting TUI after a stdio drop.\n\nrole allow-list: tui.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "resume_request", "default": "resume_request", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "last_seen_correlation_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Last correlation_id the TUI successfully applied. None if no prior frame.", "title": "Last Seen Correlation Id"}, "last_seen_frame_seq": {"anyOf": [{"minimum": 0, "type": "integer"}, {"type": "null"}], "default": null, "description": "Last frame_seq applied. None if none.", "title": "Last Seen Frame Seq"}, "tui_session_token": {"description": "TUI-local session token for authenticity binding.", "minLength": 1, "title": "Tui Session Token", "type": "string"}}, "required": ["session_id", "correlation_id", "ts", "role", "tui_session_token"], "title": "ResumeRequestFrame", "type": "object"}, "ResumeResponseFrame": {"additionalProperties": false, "description": "Backend accepts the resume.\n\nMust be followed by replay of frames with frame_seq > last_seen_frame_seq.\nTrailer with final=True MUST be set (E6).\nrole allow-list: backend.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "resume_response", "default": "resume_response", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "resumed_from_frame_seq": {"description": "Inclusive lower bound of frames that will be replayed.", "minimum": 0, "title": "Resumed From Frame Seq", "type": "integer"}, "replay_count": {"description": "Total frames the backend will replay. Bounded by ring buffer size.", "minimum": 0, "title": "Replay Count", "type": "integer"}, "server_session_id": {"description": "Backend-assigned session id the TUI should use going forward.", "title": "Server Session Id", "type": "string"}, "heartbeat_interval_ms": {"description": "Negotiated heartbeat cadence (default 30000).", "minimum": 1000, "title": "Heartbeat Interval Ms", "type": "integer"}}, "required": ["session_id", "correlation_id", "ts", "role", "resumed_from_frame_seq", "replay_count", "server_session_id", "heartbeat_interval_ms"], "title": "ResumeResponseFrame", "type": "object"}, "SessionEventFrame": {"additionalProperties": false, "description": "Bidirectional: session lifecycle events.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "session_event", "default": "session_event", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "event": {"description": "Session lifecycle event type.", "enum": ["save", "load", "list", "resume", "new", "exit"], "title": "Event", "type": "string"}, "payload": {"additionalProperties": true, "description": "Event-specific payload. For list: {sessions: [{id, created_at, turn_count}]}. For resume: {id: str}. For others: {}.", "title": "Payload", "type": "object"}}, "required": ["session_id", "correlation_id", "ts", "role", "event", "payload"], "title": "SessionEventFrame", "type": "object"}, "ToolCallFrame": {"additionalProperties": false, "description": "backend -> TUI (display only): a tool invocation decision by the model.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "tool_call", "default": "tool_call", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "call_id": {"description": "ULID correlating this call to its subsequent tool_result.", "title": "Call Id", "type": "string"}, "name": {"description": "Concrete tool name selected by the model; root primitive names remain valid for legacy transcripts.", "minLength": 1, "title": "Name", "type": "string"}, "arguments": {"additionalProperties": true, "description": "Tool-specific arguments. Concrete adapter calls carry adapter schema fields directly.", "title": "Arguments", "type": "object"}}, "required": ["session_id", "correlation_id", "ts", "role", "call_id", "name", "arguments"], "title": "ToolCallFrame", "type": "object"}, "ToolDefinition": {"additionalProperties": false, "description": "OpenAI-style tool definition (function-calling).", "properties": {"type": {"const": "function", "default": "function", "description": "OpenAI tool envelope; only 'function' is currently supported.", "title": "Type", "type": "string"}, "function": {"$ref": "#/$defs/ToolDefinitionFunction", "description": "Inner function metadata."}}, "required": ["function"], "title": "ToolDefinition", "type": "object"}, "ToolDefinitionFunction": {"additionalProperties": false, "description": "Inner ``function`` block of an OpenAI-style tool definition.", "properties": {"name": {"description": "Tool name (matches the primitive registry id).", "title": "Name", "type": "string"}, "description": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Human-readable description shown to the model for tool selection.", "title": "Description"}, "parameters": {"additionalProperties": true, "description": "JSON Schema (Draft 2020-12) for the tool input. Pydantic accepts any dict shape; deeper schema validation is delegated to LLMClient.", "title": "Parameters", "type": "object"}}, "required": ["name"], "title": "ToolDefinitionFunction", "type": "object"}, "ToolResultEnvelope": {"additionalProperties": true, "description": "Active primitive discriminated union envelope (open schema).", "properties": {"kind": {"description": "Primitive kind discriminator per Spec 031.", "enum": ["find", "locate", "send", "check"], "title": "Kind", "type": "string"}}, "required": ["kind"], "title": "ToolResultEnvelope", "type": "object"}, "ToolResultFrame": {"additionalProperties": false, "description": "backend -> TUI (render): the output of a tool invocation.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "tool_result", "default": "tool_result", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "call_id": {"description": "ULID correlating this result to its originating tool_call.", "title": "Call Id", "type": "string"}, "envelope": {"$ref": "#/$defs/ToolResultEnvelope", "description": "Active primitive discriminated union. Unknown kind falls to UnrecognizedPayload."}}, "required": ["session_id", "correlation_id", "ts", "role", "call_id", "envelope"], "title": "ToolResultFrame", "type": "object"}, "UserInputFrame": {"additionalProperties": false, "description": "TUI -> backend: a citizen's typed input.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "user_input", "default": "user_input", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "text": {"description": "Raw user text in UTF-8 (may contain Korean, English, emoji).", "title": "Text", "type": "string"}}, "required": ["session_id", "correlation_id", "ts", "role", "text"], "title": "UserInputFrame", "type": "object"}, "WorkerStatusFrame": {"additionalProperties": false, "description": "backend -> TUI: per-worker status row update from Spec 027 swarm.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "worker_status", "default": "worker_status", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "worker_id": {"description": "Unique worker identifier.", "title": "Worker Id", "type": "string"}, "role_id": {"description": "Specialist label (e.g., transport-specialist, health-specialist).", "title": "Role Id", "type": "string"}, "current_primitive": {"description": "Primitive currently being invoked by this worker.", "enum": ["find", "locate", "send", "check"], "title": "Current Primitive", "type": "string"}, "status": {"description": "Worker execution status.", "enum": ["idle", "running", "waiting_permission", "error"], "title": "Status", "type": "string"}}, "required": ["session_id", "correlation_id", "ts", "role", "worker_id", "role_id", "current_primitive", "status"], "title": "WorkerStatusFrame", "type": "object"}}, "discriminator": {"mapping": {"adapter_manifest_sync": "#/$defs/AdapterManifestSyncFrame", "assistant_chunk": "#/$defs/AssistantChunkFrame", "backpressure": "#/$defs/BackpressureSignalFrame", "chat_request": "#/$defs/ChatRequestFrame", "consent_revoke_request": "#/$defs/ConsentRevokeRequestFrame", "consent_revoke_response": "#/$defs/ConsentRevokeResponseFrame", "coordinator_phase": "#/$defs/CoordinatorPhaseFrame", "error": "#/$defs/ErrorFrame", "heartbeat": "#/$defs/HeartbeatFrame", "notification_push": "#/$defs/NotificationPushFrame", "payload_delta": "#/$defs/PayloadDeltaFrame", "payload_end": "#/$defs/PayloadEndFrame", "payload_start": "#/$defs/PayloadStartFrame", "permission_request": "#/$defs/PermissionRequestFrame", "permission_response": "#/$defs/PermissionResponseFrame", "plugin_op": "#/$defs/PluginOpFrame", "progress_event": "#/$defs/ProgressEventFrame", "resume_rejected": "#/$defs/ResumeRejectedFrame", "resume_request": "#/$defs/ResumeRequestFrame", "resume_response": "#/$defs/ResumeResponseFrame", "session_event": "#/$defs/SessionEventFrame", "tool_call": "#/$defs/ToolCallFrame", "tool_result": "#/$defs/ToolResultFrame", "user_input": "#/$defs/UserInputFrame", "worker_status": "#/$defs/WorkerStatusFrame"}, "propertyName": "kind"}, "oneOf": [{"$ref": "#/$defs/UserInputFrame"}, {"$ref": "#/$defs/ChatRequestFrame"}, {"$ref": "#/$defs/AssistantChunkFrame"}, {"$ref": "#/$defs/ProgressEventFrame"}, {"$ref": "#/$defs/ToolCallFrame"}, {"$ref": "#/$defs/ToolResultFrame"}, {"$ref": "#/$defs/CoordinatorPhaseFrame"}, {"$ref": "#/$defs/WorkerStatusFrame"}, {"$ref": "#/$defs/PermissionRequestFrame"}, {"$ref": "#/$defs/PermissionResponseFrame"}, {"$ref": "#/$defs/SessionEventFrame"}, {"$ref": "#/$defs/ErrorFrame"}, {"$ref": "#/$defs/PayloadStartFrame"}, {"$ref": "#/$defs/PayloadDeltaFrame"}, {"$ref": "#/$defs/PayloadEndFrame"}, {"$ref": "#/$defs/BackpressureSignalFrame"}, {"$ref": "#/$defs/ResumeRequestFrame"}, {"$ref": "#/$defs/ResumeResponseFrame"}, {"$ref": "#/$defs/ResumeRejectedFrame"}, {"$ref": "#/$defs/HeartbeatFrame"}, {"$ref": "#/$defs/NotificationPushFrame"}, {"$ref": "#/$defs/PluginOpFrame"}, {"$ref": "#/$defs/AdapterManifestSyncFrame"}, {"$ref": "#/$defs/ConsentRevokeRequestFrame"}, {"$ref": "#/$defs/ConsentRevokeResponseFrame"}]}
+{"$defs": {"AdapterManifestEntry": {"additionalProperties": false, "description": "One adapter record inside an ``AdapterManifestSyncFrame.entries`` array.\n\nUsed by the TS-side cache to resolve ``tool_id`` and populate the citation\nslot in permission prompts.\n\nValidators:\n- ``policy_authority_url`` required (HTTPS) when ``source_mode`` is ``\"live\"``\n  or ``\"mock\"``; ``None`` only allowed when ``source_mode == \"internal\"`` (I4/I5).\n- ``tool_id`` matches ``^[a-z][a-z0-9_]*$`` (I7).", "properties": {"tool_id": {"description": "Globally unique adapter id within the registry, e.g. 'nmc_emergency_search'. Lowercase snake-case; validated by I7.", "minLength": 1, "title": "Tool Id", "type": "string"}, "name": {"description": "Human-readable display name; bilingual permitted.", "maxLength": 80, "minLength": 1, "title": "Name", "type": "string"}, "primitive": {"description": "Primitive verb the adapter is registered under (I6).", "enum": ["find", "send", "check", "locate", "document"], "title": "Primitive", "type": "string"}, "policy_authority_url": {"anyOf": [{"maxLength": 2048, "type": "string"}, {"type": "null"}], "default": null, "description": "Agency-published policy URL (HTTPS). None only when source_mode == 'internal' (I4/I5).", "title": "Policy Authority Url"}, "source_mode": {"description": "Tag for the citation-rendering surface.", "enum": ["live", "mock", "internal"], "title": "Source Mode", "type": "string"}, "search_hint": {"anyOf": [{"maxLength": 4096, "minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "Bilingual adapter discovery phrase copied from the backend registry. Used by the TUI concrete tool surface and tool-search metadata.", "title": "Search Hint"}, "llm_description": {"anyOf": [{"maxLength": 20000, "minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "Backend-authored model-facing adapter usage prose. This is the same description the backend exposes in OpenAI/FriendliAI function metadata.", "title": "Llm Description"}, "input_schema_json": {"additionalProperties": true, "description": "Full backend Pydantic JSON Schema for adapter input parameters. Credential-only fields such as authKey must be omitted by adapters.", "title": "Input Schema Json", "type": "object"}, "output_schema_json": {"additionalProperties": true, "description": "Full backend Pydantic JSON Schema for adapter output data.", "title": "Output Schema Json", "type": "object"}}, "required": ["tool_id", "name", "primitive", "source_mode"], "title": "AdapterManifestEntry", "type": "object"}, "AdapterManifestSyncFrame": {"additionalProperties": false, "description": "Full registry snapshot emitted by the backend exactly once after boot.\n\n21st arm of the ``IPCFrame`` discriminated union (Epic \u03b5 #2296).\n\nInvariants enforced at construction:\n- I1: ``entries`` is non-empty.\n- I2: No two entries share the same ``tool_id``.\n- I3: ``manifest_hash == sha256(canonical_json(sorted(entries, key=tool_id)))``.\n- I4/I5/I6/I7: delegated to ``AdapterManifestEntry`` validators.\n\nOn invariant violation the Pydantic validator raises ``ValueError``; the\nbackend boot should catch this and exit with ``SystemExit(78)`` per\nConstitution \u00a7 II + Spec 1634 boot-validation pattern.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "adapter_manifest_sync", "default": "adapter_manifest_sync", "description": "Frame discriminator \u2014 21st arm of IPCFrame.", "title": "Kind", "type": "string"}, "entries": {"description": "Full registry snapshot. Non-empty (I1); no duplicate tool_id (I2).", "items": {"$ref": "#/$defs/AdapterManifestEntry"}, "minItems": 1, "title": "Entries", "type": "array"}, "manifest_hash": {"description": "Lowercase hex SHA-256 of canonical-JSON-serialised entries sorted by tool_id (I3). Cheap change-detection for hot-reload (future epic).", "maxLength": 64, "minLength": 64, "title": "Manifest Hash", "type": "string"}, "emitter_pid": {"description": "Python backend PID at boot. Useful for OTEL span cross-correlation.", "exclusiveMinimum": 0, "title": "Emitter Pid", "type": "integer"}}, "required": ["session_id", "correlation_id", "ts", "role", "entries", "manifest_hash", "emitter_pid"], "title": "AdapterManifestSyncFrame", "type": "object"}, "AssistantChunkFrame": {"additionalProperties": false, "description": "backend -> TUI: streaming assistant text delta.\n\nMirrors Anthropic's ``content_block_delta`` (CC reference at\n``ummaya/llm/_cc_reference/claude.ts:2053-2169``). The ``delta`` field\ncarries the visible answer text (``text_delta`` in CC nomenclature);\n``thinking`` carries the model's chain-of-thought (``thinking_delta``\non the Anthropic side, K-EXAONE's ``delta.reasoning_content`` on the\nOpenAI-compatible FriendliAI feed). Exactly one of ``delta`` /\n``thinking`` carries content per frame \u2014 the empty one is the\nbackward-compatible default. ``done`` terminates the message\nregardless of channel.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "assistant_chunk", "default": "assistant_chunk", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "message_id": {"description": "ULID of the assistant message this delta belongs to.", "title": "Message Id", "type": "string"}, "delta": {"default": "", "description": "UTF-8 text appended to the visible answer (text_delta channel).", "title": "Delta", "type": "string"}, "thinking": {"default": "", "description": "UTF-8 text appended to the model's chain-of-thought (thinking_delta channel \u2014 K-EXAONE delta.reasoning_content).", "title": "Thinking", "type": "string"}, "done": {"description": "True if this is the terminal chunk for this message_id.", "title": "Done", "type": "boolean"}}, "required": ["session_id", "correlation_id", "ts", "role", "message_id", "done"], "title": "AssistantChunkFrame", "type": "object"}, "BackpressureSignalFrame": {"additionalProperties": false, "description": "Emitted when outgoing queue crosses HWM or a 429 condition is detected.\n\nrole allow-list: tui (tui_reader), backend (backend_writer, upstream_429).\nFR-012, FR-015: hud_copy_ko/en MUST be non-empty (min_length=1).", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "backpressure", "default": "backpressure", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "signal": {"description": "Reader action. pause=stop emitting; resume=clear; throttle=slow down.", "enum": ["pause", "resume", "throttle"], "title": "Signal", "type": "string"}, "source": {"description": "Origin of the signal.", "enum": ["tui_reader", "backend_writer", "upstream_429"], "title": "Source", "type": "string"}, "queue_depth": {"description": "Current outbound queue size.", "minimum": 0, "title": "Queue Depth", "type": "integer"}, "hwm": {"description": "High-water mark threshold in effect (default 64).", "minimum": 1, "title": "Hwm", "type": "integer"}, "retry_after_ms": {"anyOf": [{"minimum": 0, "type": "integer"}, {"type": "null"}], "default": null, "description": "For throttle sourced from upstream_429; reflects Retry-After. ge=0.", "title": "Retry After Ms"}, "hud_copy_ko": {"description": "Korean HUD copy (civic-facing). Must be non-empty (FR-015).", "minLength": 1, "title": "Hud Copy Ko", "type": "string"}, "hud_copy_en": {"description": "English HUD copy (dev-facing). Must be non-empty (FR-015).", "minLength": 1, "title": "Hud Copy En", "type": "string"}}, "required": ["session_id", "correlation_id", "ts", "role", "signal", "source", "queue_depth", "hwm", "hud_copy_ko", "hud_copy_en"], "title": "BackpressureSignalFrame", "type": "object"}, "ChatMessage": {"additionalProperties": false, "description": "One conversation-history entry carried by ``ChatRequestFrame.messages``.\n\n``role=\"tool\"`` messages MUST also set ``name`` (the tool name that was\ninvoked) and ``tool_call_id`` (the originating ``tool_call`` envelope's\ncorrelation id). This is the data-model invariant D4 (tool message\nintegrity) enforced by the ``ChatRequestFrame`` validator below.\n\nLead-Diag-4 (2026-05-04): added optional ``tool_calls`` for ``role='assistant'``\nturns so assistant ``tool_use`` blocks survive the wire round-trip and the\nOpenAI Chat Completions multi-turn pairing invariant (every ``role='tool'``\nmessage MUST follow an assistant message whose ``tool_calls[i].id`` matches\nthe result's ``tool_call_id``) is satisfied. Backward compatible: legacy\nsenders that omit ``tool_calls`` are unaffected.", "properties": {"role": {"description": "Conversation turn author.", "enum": ["system", "user", "assistant", "tool"], "title": "Role", "type": "string"}, "content": {"description": "UTF-8 message body.", "title": "Content", "type": "string"}, "name": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Tool name when role='tool'; None otherwise.", "title": "Name"}, "tool_call_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Matching ``ToolCallFrame.call_id`` when role='tool'; None otherwise.", "title": "Tool Call Id"}, "tool_calls": {"anyOf": [{"items": {"$ref": "#/$defs/ChatMessageToolCall"}, "type": "array"}, {"type": "null"}], "default": null, "description": "OpenAI Chat Completions assistant-turn tool invocations. Set ONLY on role='assistant' messages that requested one or more tool calls. None for every other role. Each entry's ``id`` is the pairing key that the corresponding role='tool' result message MUST set as its ``tool_call_id``.", "title": "Tool Calls"}}, "required": ["role", "content"], "title": "ChatMessage", "type": "object"}, "ChatMessageFunctionCall": {"additionalProperties": false, "description": "OpenAI-spec ``function`` block carried inside ``ChatMessageToolCall``.\n\nMirrors ``ummaya.llm.models.FunctionCall`` (the LLM-client-internal model)\nbut lives on the *wire* so the TUI can transmit assistant ``tool_use``\nblocks across multi-turn boundaries (Lead-Diag-4, role='tool' wire fix).", "properties": {"name": {"description": "Function/tool name the model requested.", "title": "Name", "type": "string"}, "arguments": {"description": "JSON-serialised string of the function arguments (OpenAI spec).", "title": "Arguments", "type": "string"}}, "required": ["name", "arguments"], "title": "ChatMessageFunctionCall", "type": "object"}, "ChatMessageToolCall": {"additionalProperties": false, "description": "OpenAI-spec ``tool_calls[i]`` entry carried by an assistant ``ChatMessage``.\n\nOpenAI Chat Completions API spec: every ``role='tool'`` message MUST be\npaired (by ``tool_call_id``) with a ``tool_calls[i].id`` from a preceding\nassistant turn. The TUI carries this pairing across the wire so multi-turn\nconversations replay correctly to FriendliAI / OpenAI-compatible providers\n(Lead-Diag-4 fix, 2026-05-04).", "properties": {"id": {"description": "Matching ``ToolCallFrame.call_id`` / ``role='tool'.tool_call_id``.", "title": "Id", "type": "string"}, "type": {"const": "function", "default": "function", "description": "OpenAI tool envelope; only 'function' is currently supported.", "title": "Type", "type": "string"}, "function": {"$ref": "#/$defs/ChatMessageFunctionCall", "description": "Inner function name + JSON-serialised arguments."}}, "required": ["id", "function"], "title": "ChatMessageToolCall", "type": "object"}, "ChatRequestFrame": {"additionalProperties": false, "description": "TUI -> backend: tools-aware chat request (Spec 1978 ADR-0001).\n\nCoexists with ``UserInputFrame`` (which remains the echo / smoke-test path).\nThe backend treats a ``UserInputFrame{text=t}`` as\n``ChatRequestFrame{messages=[{role:'user', content:t}], tools=[]}``.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "chat_request", "default": "chat_request", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "messages": {"description": "Conversation history; tail message has role 'user' or 'tool'.", "items": {"$ref": "#/$defs/ChatMessage"}, "minItems": 1, "title": "Messages", "type": "array"}, "tools": {"description": "Tools available to the model this turn.", "items": {"$ref": "#/$defs/ToolDefinition"}, "title": "Tools", "type": "array"}, "system": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Effective system prompt (may be None if backend supplies its own).", "title": "System"}, "max_tokens": {"default": 8192, "description": "Maximum tokens for the assistant turn.", "maximum": 32000, "minimum": 1, "title": "Max Tokens", "type": "integer"}, "temperature": {"default": 1.0, "description": "Sampling temperature.", "maximum": 2.0, "minimum": 0.0, "title": "Temperature", "type": "number"}, "top_p": {"default": 0.95, "description": "Nucleus sampling threshold.", "maximum": 1.0, "minimum": 0.0, "title": "Top P", "type": "number"}, "reasoning_mode": {"anyOf": [{"enum": ["fast", "balanced", "deep", "diagnostic", "auto"], "type": "string"}, {"type": "null"}], "default": null, "description": "K-EXAONE/FriendliAI reasoning policy for this assistant turn.", "title": "Reasoning Mode"}}, "required": ["session_id", "correlation_id", "ts", "role", "messages"], "title": "ChatRequestFrame", "type": "object"}, "ConsentRevokeRequestFrame": {"additionalProperties": false, "description": "TUI -> backend: citizen requests revocation of a prior consent receipt.\n\narm 22 of the ``IPCFrame`` discriminated union (Epic 2).\n\nFields:\n- ``request_id``: UUIDv4 string; round-trips in the matching\n  ``consent_revoke_response`` frame.\n- ``receipt_id``: The ``rcpt-<id>`` value referencing the receipt file at\n  ``~/.ummaya/memdir/user/consent/<receipt_id>.json``.\n- ``scope``: ``\"once\"`` = revoke this single receipt only;\n  ``\"session-all\"`` = revoke all receipts for the current session.\n- ``reason``: Optional free-text reason logged to the audit ledger.\n\nrole allow-list: tui.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "consent_revoke_request", "default": "consent_revoke_request", "description": "Frame discriminator \u2014 arm 22 of IPCFrame.", "title": "Kind", "type": "string"}, "request_id": {"description": "UUIDv4 round-trip correlation ID; matched in consent_revoke_response.", "minLength": 1, "title": "Request Id", "type": "string"}, "receipt_id": {"description": "Target receipt identifier (rcpt-<id>). Must match an existing receipt file at ~/.ummaya/memdir/user/consent/<receipt_id>.json.", "minLength": 1, "title": "Receipt Id", "type": "string"}, "scope": {"description": "Revocation scope. 'once' revokes only this receipt; 'session-all' revokes all receipts in the current session.", "enum": ["once", "session-all"], "title": "Scope", "type": "string"}, "reason": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Optional citizen-provided reason logged to the ledger (PIPA \u00a736 citation).", "title": "Reason"}}, "required": ["session_id", "correlation_id", "ts", "role", "request_id", "receipt_id", "scope"], "title": "ConsentRevokeRequestFrame", "type": "object"}, "ConsentRevokeResponseFrame": {"additionalProperties": false, "description": "backend -> TUI: outcome of a consent_revoke_request.\n\narm 23 of the ``IPCFrame`` discriminated union (Epic 2).\n\nFields:\n- ``request_id``: Mirrors the originating consent_revoke_request.request_id.\n- ``ok``: True when at least one receipt was revoked; False on error or\n  not-found.\n- ``revoked_at``: ISO-8601 UTC timestamp of the revocation (when ok=True).\n- ``record_hash``: Ledger entry SHA-256 for audit chain verification\n  (when ok=True; omitted on error).\n- ``error``: Machine-readable error code on failure (``already_revoked``,\n  ``not_found``, ``io_error``); omitted on success.\n\nrole allow-list: backend.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "consent_revoke_response", "default": "consent_revoke_response", "description": "Frame discriminator \u2014 arm 23 of IPCFrame.", "title": "Kind", "type": "string"}, "request_id": {"description": "Mirrors consent_revoke_request.request_id for round-trip correlation.", "minLength": 1, "title": "Request Id", "type": "string"}, "ok": {"description": "True when at least one receipt was successfully revoked; False on error or not-found.", "title": "Ok", "type": "boolean"}, "revoked_at": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "ISO-8601 UTC timestamp of revocation. Populated when ok=True.", "title": "Revoked At"}, "record_hash": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Hex SHA-256 of the ledger withdrawal record. Populated when ok=True for audit-chain verification.", "title": "Record Hash"}, "error": {"anyOf": [{"enum": ["already_revoked", "not_found", "io_error"], "type": "string"}, {"type": "null"}], "default": null, "description": "Machine-readable error code when ok=False; None on success.", "title": "Error"}}, "required": ["session_id", "correlation_id", "ts", "role", "request_id", "ok"], "title": "ConsentRevokeResponseFrame", "type": "object"}, "CoordinatorPhaseFrame": {"additionalProperties": false, "description": "backend -> TUI: Spec 027 coordinator phase update.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "coordinator_phase", "default": "coordinator_phase", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "phase": {"description": "Current coordinator phase.", "enum": ["Research", "Synthesis", "Implementation", "Verification"], "title": "Phase", "type": "string"}}, "required": ["session_id", "correlation_id", "ts", "role", "phase"], "title": "CoordinatorPhaseFrame", "type": "object"}, "ErrorFrame": {"additionalProperties": false, "description": "backend -> TUI: a backend error surfaced to the TUI for rendering.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "error", "default": "error", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "code": {"description": "Machine-readable error code (e.g., 'backend_crash', 'protocol_mismatch').", "title": "Code", "type": "string"}, "message": {"description": "Human-readable short message. MUST NOT contain UMMAYA_*-prefixed env var values (FR-004 redaction rule).", "title": "Message", "type": "string"}, "details": {"additionalProperties": true, "description": "Structured error details. UMMAYA_* env var values MUST be redacted.", "title": "Details", "type": "object"}}, "required": ["session_id", "correlation_id", "ts", "role", "code", "message", "details"], "title": "ErrorFrame", "type": "object"}, "FrameTrailer": {"additionalProperties": false, "description": "Completion/validation metadata on terminal frames (FR-006).", "properties": {"final": {"description": "True when this frame terminates a logical payload/stream.", "title": "Final", "type": "boolean"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "Mirror of envelope transaction_id for trailer-only consumers. Non-empty when present (parity with codec.ts trailer schema \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "checksum_sha256": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Hex SHA-256 of the concatenated payload bytes for streamed payloads.", "title": "Checksum Sha256"}}, "required": ["final"], "title": "FrameTrailer", "type": "object"}, "HeartbeatFrame": {"additionalProperties": false, "description": "Emitted every 30 s (default) by both sides to prove liveness.\n\nNote: Heartbeat frames do NOT increment frame_seq \u2014 they use a dedicated\ncounter. This keeps ring-buffer economy tight.\nrole allow-list: tui, backend.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "heartbeat", "default": "heartbeat", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "direction": {"description": "ping from sender, pong from receiver.", "enum": ["ping", "pong"], "title": "Direction", "type": "string"}, "peer_frame_seq": {"description": "Sender's current outbound frame_seq high-water.", "minimum": 0, "title": "Peer Frame Seq", "type": "integer"}}, "required": ["session_id", "correlation_id", "ts", "role", "direction", "peer_frame_seq"], "title": "HeartbeatFrame", "type": "object"}, "NotificationPushFrame": {"additionalProperties": false, "description": "Push from app/phone notification surfaces.\n\nCarried over the same stdio channel to keep a single correlation plane.\nrole allow-list: notification.\n\nCC parity: NO equivalent \u2014 Claude Code's notification surface is\nterminal OSC sequences (iTerm2, Kitty, Ghostty, bell) emitted\nin-process from ``ink/useTerminalNotification.ts``. There is no\npush-based IPC notification arm in CC. UMMAYA adds this arm as a\nswap-2 addition for Korean civic push channels (KMA disaster CBS,\ngovernment newsroom alerts, hospital alerts) carried over the\nsame stdio plane to keep a single correlation plane. Spec 2642\nEpic F \u00b7 S7 audit recorded this finding (specs/cc-migration-audit/\nscope-S7-ipc-bridge.md \u00a7 5 Finding 3 \u2014 resolved as orthogonal\nUMMAYA swap-2 add-on, not a CC-divergence regression).", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "notification_push", "default": "notification_push", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "subscription_id": {"description": "Notification channel handle.", "title": "Subscription Id", "type": "string"}, "adapter_id": {"description": "e.g., disaster_alert_cbs_push, gov_newsroom_push.", "title": "Adapter Id", "type": "string"}, "event_guid": {"description": "RSS guid or CBS event hash for duplicate suppression.", "title": "Event Guid", "type": "string"}, "payload_content_type": {"description": "Inline payload MIME.", "enum": ["text/plain", "application/json"], "title": "Payload Content Type", "type": "string"}, "payload": {"description": "Inline notification content (Korean for civic users).", "title": "Payload", "type": "string"}}, "required": ["session_id", "correlation_id", "ts", "role", "subscription_id", "adapter_id", "event_guid", "payload_content_type", "payload"], "title": "NotificationPushFrame", "type": "object"}, "PayloadDeltaFrame": {"additionalProperties": false, "description": "One chunk of a streamed payload.\n\nrole allow-list: backend, tool, llm.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "payload_delta", "default": "payload_delta", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "delta_seq": {"description": "Monotonic within the payload (first delta = 0).", "minimum": 0, "title": "Delta Seq", "type": "integer"}, "payload": {"description": "UTF-8 text. If content-type is application/json, this is a JSON-encoded fragment string.", "title": "Payload", "type": "string"}}, "required": ["session_id", "correlation_id", "ts", "role", "delta_seq", "payload"], "title": "PayloadDeltaFrame", "type": "object"}, "PayloadEndFrame": {"additionalProperties": false, "description": "Terminates a streamed payload.\n\nMUST carry a trailer with final=True.\nrole allow-list: backend, tool, llm.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "payload_end", "default": "payload_end", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "delta_count": {"description": "Total number of payload_delta frames emitted.", "minimum": 0, "title": "Delta Count", "type": "integer"}, "status": {"description": "Terminal disposition.", "enum": ["ok", "aborted"], "title": "Status", "type": "string"}}, "required": ["session_id", "correlation_id", "ts", "role", "delta_count", "status"], "title": "PayloadEndFrame", "type": "object"}, "PayloadStartFrame": {"additionalProperties": false, "description": "Begins a streamed payload (assistant output, tool result chunking).\n\nSender MUST follow with >= 1 payload_delta and exactly one payload_end.\nrole allow-list: backend, tool, llm.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "payload_start", "default": "payload_start", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "content_type": {"description": "Payload MIME type.", "enum": ["text/markdown", "application/json", "text/plain"], "title": "Content Type", "type": "string"}, "estimated_bytes": {"anyOf": [{"minimum": 0, "type": "integer"}, {"type": "null"}], "default": null, "description": "Optional size hint for HUD progress bars.", "title": "Estimated Bytes"}}, "required": ["session_id", "correlation_id", "ts", "role", "content_type"], "title": "PayloadStartFrame", "type": "object"}, "PermissionRequestFrame": {"additionalProperties": false, "description": "backend -> TUI: a worker raises a permission request.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "permission_request", "default": "permission_request", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "request_id": {"description": "ULID; round-trips in the matching permission_response frame.", "title": "Request Id", "type": "string"}, "worker_id": {"description": "Worker requesting permission.", "title": "Worker Id", "type": "string"}, "primitive_kind": {"description": "The primitive the worker wants to invoke.", "enum": ["find", "locate", "send", "check", "document"], "title": "Primitive Kind", "type": "string"}, "description_ko": {"description": "Korean-language description shown to the citizen.", "title": "Description Ko", "type": "string"}, "description_en": {"description": "English-language description shown alongside the Korean one.", "title": "Description En", "type": "string"}, "risk_level": {"description": "Risk classification of the requested operation.", "enum": ["low", "medium", "high"], "title": "Risk Level", "type": "string"}, "tool_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Fully-qualified adapter id (e.g. `mock_verify_mobile_id`). Falls back to worker_id || primitive_kind in the TUI when None. None for legacy callers that have not yet been updated.", "title": "Tool Id"}}, "required": ["session_id", "correlation_id", "ts", "role", "request_id", "worker_id", "primitive_kind", "description_ko", "description_en", "risk_level"], "title": "PermissionRequestFrame", "type": "object"}, "PermissionResponseFrame": {"additionalProperties": false, "description": "TUI -> backend: citizen's decision on a permission_request.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "permission_response", "default": "permission_response", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "request_id": {"description": "ULID matching the originating permission_request.request_id.", "title": "Request Id", "type": "string"}, "decision": {"description": "Citizen's permission decision.", "enum": ["granted", "allow_once", "allow_session", "denied", "deny"], "title": "Decision", "type": "string"}, "receipt_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Consent receipt UUID written to ~/.ummaya/memdir/user/consent/<id>.json on granted decisions. None on deny / timeout.", "title": "Receipt Id"}, "primitive_kind": {"anyOf": [{"enum": ["find", "locate", "send", "check", "document"], "type": "string"}, {"type": "null"}], "default": null, "description": "The primitive that was authorised. The TUI feeds this into `aalToLayer(primitive, isIrreversible)` to recompute the gauntlet layer (1=green / 2=orange / 3=red) for the receipt row. None on deny / timeout / legacy backends.", "title": "Primitive Kind"}, "tool_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "The fully-qualified adapter id (e.g. `mock_verify_mobile_id`, `mock_submit_welfare_grant`) the citizen authorised. The TUI uses this to render the human-readable Korean adapter name in /consent list and the modal title. None for non-adapter primitives (rare) or legacy backends.", "title": "Tool Id"}}, "required": ["session_id", "correlation_id", "ts", "role", "request_id", "decision"], "title": "PermissionResponseFrame", "type": "object"}, "PluginOpFrame": {"additionalProperties": false, "description": "Plugin install / uninstall / list control-plane frame.\n\nSingle arm carrying the three operation states discriminated by the\ninner ``op`` field. Modelled as one ``kind`` so the IPC discriminator\nkeeps ``plugin_op`` as a single 20th arm \u2014 matching the migration\ntree's \"20th arm\" decision while preserving the per-phase shape\ndocumented in ``contracts/plugin-install.cli.md``.\n\nOp-specific shape rules (enforced by ``_v_plugin_op_shape``):\n\n* ``op=\"request\"``: ``name`` required when ``request_op`` is\n  ``\"install\"`` or ``\"uninstall\"``; ``progress_phase`` /\n  ``progress_message_ko`` / ``progress_message_en`` / ``result`` /\n  ``exit_code`` MUST be ``None``.\n* ``op=\"progress\"``: ``progress_phase`` (1-7), ``progress_message_ko``,\n  ``progress_message_en`` required; install-request fields must be\n  ``None``.\n* ``op=\"complete\"``: ``result`` + ``exit_code`` required; everything\n  else None except optional ``receipt_id``.\n\nrole allow-list: tui (request), backend (progress / complete).", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "plugin_op", "default": "plugin_op", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "op": {"description": "Operation phase. ``request`` = TUI initiates install/uninstall/list; ``progress`` = backend reports phase tick; ``complete`` = backend reports terminal outcome.", "enum": ["request", "progress", "complete"], "title": "Op", "type": "string"}, "request_op": {"anyOf": [{"enum": ["install", "uninstall", "list"], "type": "string"}, {"type": "null"}], "default": null, "description": "Sub-action when op='request'. Required for op='request'; None otherwise.", "title": "Request Op"}, "name": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Plugin catalog name (matches CatalogEntry.name). Required when request_op in {install, uninstall}; None otherwise.", "title": "Name"}, "requested_version": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Optional SemVer pin for op='request'/install. Renamed from `version` to avoid shadowing the envelope's protocol version.", "title": "Requested Version"}, "dry_run": {"anyOf": [{"type": "boolean"}, {"type": "null"}], "default": null, "description": "When True, install verifies but writes nothing (op='request').", "title": "Dry Run"}, "progress_phase": {"anyOf": [{"type": "integer"}, {"type": "null"}], "default": null, "description": "Install phase index 1-7 per contracts/plugin-install.cli.md. Required when op='progress'.", "title": "Progress Phase"}, "progress_message_ko": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Korean-primary progress message shown in the Ink overlay.", "title": "Progress Message Ko"}, "progress_message_en": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "English fallback progress message.", "title": "Progress Message En"}, "result": {"anyOf": [{"enum": ["success", "failure"], "type": "string"}, {"type": "null"}], "default": null, "description": "Terminal outcome. Required when op='complete'.", "title": "Result"}, "exit_code": {"anyOf": [{"type": "integer"}, {"type": "null"}], "default": null, "description": "Process exit code per contracts/plugin-install.cli.md exit-code table. Required when op='complete'.", "title": "Exit Code"}, "receipt_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Spec 035 consent receipt id when op='complete' AND result='success'.", "title": "Receipt Id"}, "error_kind": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Machine-readable failure kind (e.g. 'bundle_sha_mismatch', 'slsa_skip_in_production') when op='complete' AND result='failure'. Used by the TUI to map exit codes to citizen-friendly Korean messages.", "title": "Error Kind"}, "error_message": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Developer-facing English error detail when op='complete' AND result='failure'.", "title": "Error Message"}, "was_idempotent_noop": {"anyOf": [{"type": "boolean"}, {"type": "null"}], "default": null, "description": "True when op='complete' + result='success' but the operation was a no-op because the plugin was already in the target state (e.g. uninstall of a plugin that was never installed). TUI uses this to show '\uc774\ubbf8 \uc81c\uac70\ub428' instead of '\uc81c\uac70 \uc644\ub8cc'.", "title": "Was Idempotent Noop"}}, "required": ["session_id", "correlation_id", "ts", "role", "op"], "title": "PluginOpFrame", "type": "object"}, "ProgressEventFrame": {"additionalProperties": false, "description": "backend -> TUI: deterministic query-loop progress.\n\nThis is intentionally separate from ``AssistantChunkFrame.thinking``.\n``progress_event`` carries safe harness state such as analysis, tool\nselection, tool dispatch/result, and answer synthesis. Provider reasoning\nremains on the gated ``thinking_delta`` channel.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "progress_event", "default": "progress_event", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "phase": {"description": "Safe query-loop phase represented by this event.", "enum": ["analysis", "tool_selection", "tool_call", "tool_result", "answer_synthesis"], "title": "Phase", "type": "string"}, "message_ko": {"description": "Korean progress text for the TUI.", "minLength": 1, "title": "Message Ko", "type": "string"}, "message_en": {"description": "English fallback progress text.", "minLength": 1, "title": "Message En", "type": "string"}, "safe_to_persist": {"default": true, "description": "True because this channel never carries raw provider chain-of-thought.", "title": "Safe To Persist", "type": "boolean"}, "tool_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Concrete adapter/tool id when this event is tied to one.", "title": "Tool Id"}, "call_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Tool call id when this event is tied to a specific invocation.", "title": "Call Id"}}, "required": ["session_id", "correlation_id", "ts", "role", "phase", "message_ko", "message_en"], "title": "ProgressEventFrame", "type": "object"}, "ResumeRejectedFrame": {"additionalProperties": false, "description": "Backend cannot honor the resume request.\n\nTrailer with final=True MUST be set (E6).\nrole allow-list: backend.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "resume_rejected", "default": "resume_rejected", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "reason": {"description": "Machine-readable reason code.", "enum": ["ring_evicted", "session_unknown", "token_mismatch", "protocol_incompatible", "session_expired"], "title": "Reason", "type": "string"}, "detail": {"description": "Human-readable Korean/English detail for HUD.", "title": "Detail", "type": "string"}}, "required": ["session_id", "correlation_id", "ts", "role", "reason", "detail"], "title": "ResumeRejectedFrame", "type": "object"}, "ResumeRequestFrame": {"additionalProperties": false, "description": "Sent by the reconnecting TUI after a stdio drop.\n\nrole allow-list: tui.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "resume_request", "default": "resume_request", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "last_seen_correlation_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Last correlation_id the TUI successfully applied. None if no prior frame.", "title": "Last Seen Correlation Id"}, "last_seen_frame_seq": {"anyOf": [{"minimum": 0, "type": "integer"}, {"type": "null"}], "default": null, "description": "Last frame_seq applied. None if none.", "title": "Last Seen Frame Seq"}, "tui_session_token": {"description": "TUI-local session token for authenticity binding.", "minLength": 1, "title": "Tui Session Token", "type": "string"}}, "required": ["session_id", "correlation_id", "ts", "role", "tui_session_token"], "title": "ResumeRequestFrame", "type": "object"}, "ResumeResponseFrame": {"additionalProperties": false, "description": "Backend accepts the resume.\n\nMust be followed by replay of frames with frame_seq > last_seen_frame_seq.\nTrailer with final=True MUST be set (E6).\nrole allow-list: backend.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "resume_response", "default": "resume_response", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "resumed_from_frame_seq": {"description": "Inclusive lower bound of frames that will be replayed.", "minimum": 0, "title": "Resumed From Frame Seq", "type": "integer"}, "replay_count": {"description": "Total frames the backend will replay. Bounded by ring buffer size.", "minimum": 0, "title": "Replay Count", "type": "integer"}, "server_session_id": {"description": "Backend-assigned session id the TUI should use going forward.", "title": "Server Session Id", "type": "string"}, "heartbeat_interval_ms": {"description": "Negotiated heartbeat cadence (default 30000).", "minimum": 1000, "title": "Heartbeat Interval Ms", "type": "integer"}}, "required": ["session_id", "correlation_id", "ts", "role", "resumed_from_frame_seq", "replay_count", "server_session_id", "heartbeat_interval_ms"], "title": "ResumeResponseFrame", "type": "object"}, "SessionEventFrame": {"additionalProperties": false, "description": "Bidirectional: session lifecycle events.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "session_event", "default": "session_event", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "event": {"description": "Session lifecycle event type.", "enum": ["save", "load", "list", "resume", "new", "exit"], "title": "Event", "type": "string"}, "payload": {"additionalProperties": true, "description": "Event-specific payload. For list: {sessions: [{id, created_at, turn_count}]}. For resume: {id: str}. For others: {}.", "title": "Payload", "type": "object"}}, "required": ["session_id", "correlation_id", "ts", "role", "event", "payload"], "title": "SessionEventFrame", "type": "object"}, "ToolCallFrame": {"additionalProperties": false, "description": "backend -> TUI (display only): a tool invocation decision by the model.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "tool_call", "default": "tool_call", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "call_id": {"description": "ULID correlating this call to its subsequent tool_result.", "title": "Call Id", "type": "string"}, "name": {"description": "Concrete tool name selected by the model; root primitive names remain valid for legacy transcripts.", "minLength": 1, "title": "Name", "type": "string"}, "arguments": {"additionalProperties": true, "description": "Tool-specific arguments. Concrete adapter calls carry adapter schema fields directly.", "title": "Arguments", "type": "object"}}, "required": ["session_id", "correlation_id", "ts", "role", "call_id", "name", "arguments"], "title": "ToolCallFrame", "type": "object"}, "ToolDefinition": {"additionalProperties": false, "description": "OpenAI-style tool definition (function-calling).", "properties": {"type": {"const": "function", "default": "function", "description": "OpenAI tool envelope; only 'function' is currently supported.", "title": "Type", "type": "string"}, "function": {"$ref": "#/$defs/ToolDefinitionFunction", "description": "Inner function metadata."}}, "required": ["function"], "title": "ToolDefinition", "type": "object"}, "ToolDefinitionFunction": {"additionalProperties": false, "description": "Inner ``function`` block of an OpenAI-style tool definition.", "properties": {"name": {"description": "Tool name (matches the primitive registry id).", "title": "Name", "type": "string"}, "description": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "description": "Human-readable description shown to the model for tool selection.", "title": "Description"}, "parameters": {"additionalProperties": true, "description": "JSON Schema (Draft 2020-12) for the tool input. Pydantic accepts any dict shape; deeper schema validation is delegated to LLMClient.", "title": "Parameters", "type": "object"}}, "required": ["name"], "title": "ToolDefinitionFunction", "type": "object"}, "ToolResultEnvelope": {"additionalProperties": true, "description": "Active primitive discriminated union envelope (open schema).", "properties": {"kind": {"description": "Primitive kind discriminator per Spec 031.", "enum": ["find", "locate", "send", "check", "document"], "title": "Kind", "type": "string"}}, "required": ["kind"], "title": "ToolResultEnvelope", "type": "object"}, "ToolResultFrame": {"additionalProperties": false, "description": "backend -> TUI (render): the output of a tool invocation.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "tool_result", "default": "tool_result", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "call_id": {"description": "ULID correlating this result to its originating tool_call.", "title": "Call Id", "type": "string"}, "envelope": {"$ref": "#/$defs/ToolResultEnvelope", "description": "Active primitive discriminated union. Unknown kind falls to UnrecognizedPayload."}}, "required": ["session_id", "correlation_id", "ts", "role", "call_id", "envelope"], "title": "ToolResultFrame", "type": "object"}, "UserInputFrame": {"additionalProperties": false, "description": "TUI -> backend: a citizen's typed input.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "user_input", "default": "user_input", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "text": {"description": "Raw user text in UTF-8 (may contain Korean, English, emoji).", "title": "Text", "type": "string"}}, "required": ["session_id", "correlation_id", "ts", "role", "text"], "title": "UserInputFrame", "type": "object"}, "WorkerStatusFrame": {"additionalProperties": false, "description": "backend -> TUI: per-worker status row update from Spec 027 swarm.", "properties": {"session_id": {"description": "Opaque session identifier.", "title": "Session Id", "type": "string"}, "correlation_id": {"description": "UUIDv7 string for new emissions; ULID accepted for back-compat. Non-empty; emitter SHOULD use UUIDv7. (E5)", "minLength": 1, "title": "Correlation Id", "type": "string"}, "ts": {"description": "ISO-8601 UTC timestamp with sub-ms precision.", "title": "Ts", "type": "string"}, "version": {"const": "1.0", "default": "1.0", "description": "Envelope version. Hard-fail on mismatch (E1, FR-001).", "title": "Version", "type": "string"}, "role": {"description": "Origin role. Validated against kind<->role allow-list (E3, FR-004).", "enum": ["tui", "backend", "tool", "llm", "notification"], "title": "Role", "type": "string"}, "frame_seq": {"default": 0, "description": "Per-session monotonic sequence number (ge=0). Gap detection uses this.", "minimum": 0, "title": "Frame Seq", "type": "integer"}, "transaction_id": {"anyOf": [{"minLength": 1, "type": "string"}, {"type": "null"}], "default": null, "description": "UUIDv7. Populated for idempotent state-change frames (irreversible tools). None for streaming chunks. (FR-026) Non-empty when present (parity with codec.ts ``z.string().min(1).nullable().optional()`` \u2014 Spec 2642 \u00a7 US3).", "title": "Transaction Id"}, "trailer": {"anyOf": [{"$ref": "#/$defs/FrameTrailer"}, {"type": "null"}], "default": null, "description": "Completion/validation metadata. Populated on terminal frames. (FR-006)"}, "kind": {"const": "worker_status", "default": "worker_status", "description": "Frame discriminator.", "title": "Kind", "type": "string"}, "worker_id": {"description": "Unique worker identifier.", "title": "Worker Id", "type": "string"}, "role_id": {"description": "Specialist label (e.g., transport-specialist, health-specialist).", "title": "Role Id", "type": "string"}, "current_primitive": {"description": "Primitive currently being invoked by this worker.", "enum": ["find", "locate", "send", "check", "document"], "title": "Current Primitive", "type": "string"}, "status": {"description": "Worker execution status.", "enum": ["idle", "running", "waiting_permission", "error"], "title": "Status", "type": "string"}}, "required": ["session_id", "correlation_id", "ts", "role", "worker_id", "role_id", "current_primitive", "status"], "title": "WorkerStatusFrame", "type": "object"}}, "discriminator": {"mapping": {"adapter_manifest_sync": "#/$defs/AdapterManifestSyncFrame", "assistant_chunk": "#/$defs/AssistantChunkFrame", "backpressure": "#/$defs/BackpressureSignalFrame", "chat_request": "#/$defs/ChatRequestFrame", "consent_revoke_request": "#/$defs/ConsentRevokeRequestFrame", "consent_revoke_response": "#/$defs/ConsentRevokeResponseFrame", "coordinator_phase": "#/$defs/CoordinatorPhaseFrame", "error": "#/$defs/ErrorFrame", "heartbeat": "#/$defs/HeartbeatFrame", "notification_push": "#/$defs/NotificationPushFrame", "payload_delta": "#/$defs/PayloadDeltaFrame", "payload_end": "#/$defs/PayloadEndFrame", "payload_start": "#/$defs/PayloadStartFrame", "permission_request": "#/$defs/PermissionRequestFrame", "permission_response": "#/$defs/PermissionResponseFrame", "plugin_op": "#/$defs/PluginOpFrame", "progress_event": "#/$defs/ProgressEventFrame", "resume_rejected": "#/$defs/ResumeRejectedFrame", "resume_request": "#/$defs/ResumeRequestFrame", "resume_response": "#/$defs/ResumeResponseFrame", "session_event": "#/$defs/SessionEventFrame", "tool_call": "#/$defs/ToolCallFrame", "tool_result": "#/$defs/ToolResultFrame", "user_input": "#/$defs/UserInputFrame", "worker_status": "#/$defs/WorkerStatusFrame"}, "propertyName": "kind"}, "oneOf": [{"$ref": "#/$defs/UserInputFrame"}, {"$ref": "#/$defs/ChatRequestFrame"}, {"$ref": "#/$defs/AssistantChunkFrame"}, {"$ref": "#/$defs/ProgressEventFrame"}, {"$ref": "#/$defs/ToolCallFrame"}, {"$ref": "#/$defs/ToolResultFrame"}, {"$ref": "#/$defs/CoordinatorPhaseFrame"}, {"$ref": "#/$defs/WorkerStatusFrame"}, {"$ref": "#/$defs/PermissionRequestFrame"}, {"$ref": "#/$defs/PermissionResponseFrame"}, {"$ref": "#/$defs/SessionEventFrame"}, {"$ref": "#/$defs/ErrorFrame"}, {"$ref": "#/$defs/PayloadStartFrame"}, {"$ref": "#/$defs/PayloadDeltaFrame"}, {"$ref": "#/$defs/PayloadEndFrame"}, {"$ref": "#/$defs/BackpressureSignalFrame"}, {"$ref": "#/$defs/ResumeRequestFrame"}, {"$ref": "#/$defs/ResumeResponseFrame"}, {"$ref": "#/$defs/ResumeRejectedFrame"}, {"$ref": "#/$defs/HeartbeatFrame"}, {"$ref": "#/$defs/NotificationPushFrame"}, {"$ref": "#/$defs/PluginOpFrame"}, {"$ref": "#/$defs/AdapterManifestSyncFrame"}, {"$ref": "#/$defs/ConsentRevokeRequestFrame"}, {"$ref": "#/$defs/ConsentRevokeResponseFrame"}]}

package/tui/src/keybindings/defaultBindings.ts

@@ -338,3 +338,7 @@ export const DEFAULT_BINDINGS: KeybindingBlock[] = [
     },
   },
 ]
+
+// Backwards-compatible name used by older focused TUI tests and snapshot
+// harnesses. The active runtime import remains DEFAULT_BINDINGS.
+export const DEFAULT_BINDING_BLOCKS = DEFAULT_BINDINGS