openapi.json

{
  "components": {
    "schemas": {
      "AddCommentRequest": {
        "description": "Request body for ``POST /sessions/{id}/comments``.\n\n:param path: File path relative to workspace root,\n    e.g. ``\"src/App.tsx\"``.\n:param body: The comment text.\n:param start_index: 0-based absolute character offset (inclusive)\n    within the file where the anchor range begins.\n:param end_index: 0-based absolute character offset (exclusive)\n    within the file where the anchor range ends.\n:param anchor_content: Plain-text snapshot of the selected range, used\n    to re-anchor the comment after file edits. ``None`` if not provided.",
        "properties": {
          "anchor_content": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Anchor Content"
          },
          "body": {
            "title": "Body",
            "type": "string"
          },
          "end_index": {
            "title": "End Index",
            "type": "integer"
          },
          "path": {
            "title": "Path",
            "type": "string"
          },
          "start_index": {
            "title": "Start Index",
            "type": "integer"
          }
        },
        "required": [
          "path",
          "body",
          "start_index",
          "end_index"
        ],
        "title": "AddCommentRequest",
        "type": "object"
      },
      "AgentObject": {
        "description": "API representation of a registered agent.\n\n:param id: Unique agent identifier, e.g. ``\"ag_abc123\"``.\n:param object: Fixed resource type, always ``\"agent\"``.\n:param name: Human-readable agent name,\n    e.g. ``\"research-agent\"``.\n:param version: Monotonic version counter. Starts at 1,\n    incremented on each update.\n:param description: Optional free-text description of the\n    agent's purpose.\n:param created_at: Unix epoch timestamp of creation.\n:param updated_at: Unix epoch timestamp of the last update,\n    or ``None`` if never updated.\n:param harness: The agent's harness/kind, e.g. ``\"codex\"``,\n    ``\"codex-native\"``, or ``\"claude-native\"`` for\n    ``executor.type: omnigent`` agents, otherwise the executor\n    type (``\"claude_sdk\"``, ``\"agents_sdk\"``). ``None`` when the\n    bundle cannot be loaded. Lets the Web UI Add Agent picker\n    recognise an agent's kind (Codex vs Claude) without\n    hardcoding by name slug.\n:param mcp_servers: MCP servers the agent is connected to\n    (secret fields omitted). Empty list when the spec\n    declares no MCP servers or when the bundle cannot be\n    loaded.\n:param policies: Guardrails policies declared on the agent.\n    Each entry summarises the policy name, type, and\n    phases. Empty list when the spec declares no policies\n    or when the bundle cannot be loaded.\n:param skills: Skills bundled in the agent spec\n    (``skills/<name>/SKILL.md``). Lets the Web UI's\n    new-session composer offer a slash-command menu before a\n    session (and its runner) exists. Host-discovered skills\n    are runner-owned, so they are NOT listed here \u2014 the\n    session snapshot's ``skills`` field carries the merged\n    set once a runner is bound. Empty list when the spec\n    bundles no skills or when the bundle cannot be loaded.\n:param terminals: Terminal names declared in the spec's\n    ``terminals:`` block, in declaration order, e.g.\n    ``[\"shell\"]``. The Web UI gates its \"new terminal\"\n    affordance on this list (creation is only offered for\n    agents with terminal access) and offers these names as\n    the launchable choices. Empty list when the spec\n    declares no terminals or when the bundle cannot be\n    loaded.",
        "properties": {
          "created_at": {
            "title": "Created At",
            "type": "integer"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description"
          },
          "harness": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Harness"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "mcp_servers": {
            "items": {
              "$ref": "#/components/schemas/MCPServerSummary"
            },
            "title": "Mcp Servers",
            "type": "array"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "object": {
            "default": "agent",
            "title": "Object",
            "type": "string"
          },
          "policies": {
            "items": {
              "$ref": "#/components/schemas/PolicySummary"
            },
            "title": "Policies",
            "type": "array"
          },
          "skills": {
            "items": {
              "$ref": "#/components/schemas/SkillSummary"
            },
            "title": "Skills",
            "type": "array"
          },
          "terminals": {
            "items": {
              "type": "string"
            },
            "title": "Terminals",
            "type": "array"
          },
          "updated_at": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Updated At"
          },
          "version": {
            "default": 1,
            "title": "Version",
            "type": "integer"
          }
        },
        "required": [
          "id",
          "name",
          "created_at"
        ],
        "title": "AgentObject",
        "type": "object"
      },
      "Body_update_session_agent_v1_sessions__session_id__agent_put": {
        "properties": {
          "bundle": {
            "contentMediaType": "application/octet-stream",
            "title": "Bundle",
            "type": "string"
          }
        },
        "required": [
          "bundle"
        ],
        "title": "Body_update_session_agent_v1_sessions__session_id__agent_put",
        "type": "object"
      },
      "Body_upload_session_file_v1_sessions__session_id__resources_files_post": {
        "properties": {
          "file": {
            "contentMediaType": "application/octet-stream",
            "title": "File",
            "type": "string"
          }
        },
        "required": [
          "file"
        ],
        "title": "Body_upload_session_file_v1_sessions__session_id__resources_files_post",
        "type": "object"
      },
      "CancelledEvent": {
        "description": "Terminal event for a turn cancelled before completion.\n\n:param type: Always ``\"response.cancelled\"``.\n:param response: The final response object with\n    ``status=\"cancelled\"``.",
        "properties": {
          "response": {
            "$ref": "#/components/schemas/ResponseObject"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "response.cancelled",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "response"
        ],
        "title": "CancelledEvent",
        "type": "object"
      },
      "ClientTaskCancelEvent": {
        "description": "Server-side request that the client cancel a tunneled tool call.\n\nEmitted by ``omnigent/runtime/workflow.py`` when a parent\ncancellation needs to propagate to a long-running async client\ntool. Wire shape matches ``workflow.py:4258-4266``.\n\n:param type: Always ``\"response.client_task.cancel\"``.\n:param task_id: Identifier of the client-side task being\n    cancelled, e.g. ``\"resp_async_abc\"``.\n:param call_id: Synthetic ``call_id`` the SDK uses to\n    reconcile the local task; ``None`` when no pending tool\n    call row exists for the task.",
        "properties": {
          "call_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Call Id"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "task_id": {
            "title": "Task Id",
            "type": "string"
          },
          "type": {
            "const": "response.client_task.cancel",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "task_id"
        ],
        "title": "ClientTaskCancelEvent",
        "type": "object"
      },
      "CompactionCompletedEvent": {
        "description": "Conversation history compaction has finished.\n\nEmitted by ``omnigent/server/routes/sessions.py`` after\n``compact_conversation_now()`` returns successfully. Clients\nthat rendered a \"Compacting\u2026\" spinner on\n:class:`CompactionInProgressEvent` should upgrade it to the\npermanent \"Conversation compacted\" marker on this event.\n\n:param type: Always ``\"response.compaction.completed\"``.\n:param total_tokens: Tiktoken estimate of the post-compaction\n    message context size, e.g. ``8421``. Used by clients to\n    update the context-ring immediately without waiting for the\n    next ``response.completed`` usage report. ``None`` when\n    token counting is unavailable.",
        "properties": {
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "total_tokens": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Total Tokens"
          },
          "type": {
            "const": "response.compaction.completed",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type"
        ],
        "title": "CompactionCompletedEvent",
        "type": "object"
      },
      "CompactionFailedEvent": {
        "description": "Conversation history compaction failed.\n\nEmitted by ``omnigent/server/routes/sessions.py`` when\n``compact_conversation_now()`` raises. Clients that rendered a\n\"Compacting\u2026\" spinner on :class:`CompactionInProgressEvent`\nshould dismiss it without leaving a permanent marker, since the\nconversation history was not modified.\n\n:param type: Always ``\"response.compaction.failed\"``.",
        "properties": {
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "response.compaction.failed",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type"
        ],
        "title": "CompactionFailedEvent",
        "type": "object"
      },
      "CompactionInProgressEvent": {
        "description": "Conversation history is being compacted.\n\nEmitted by ``omnigent/runtime/compaction.py`` while a\ncompaction step runs so clients can render a \"summarizing\nhistory\u2026\" indicator. Wire shape matches ``compaction.py:765``.\n\n:param type: Always ``\"response.compaction.in_progress\"``.",
        "properties": {
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "response.compaction.in_progress",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type"
        ],
        "title": "CompactionInProgressEvent",
        "type": "object"
      },
      "CompletedEvent": {
        "description": "Terminal event for a successfully completed turn.\n\nCarries the final\n:class:`omnigent.server.schemas.ResponseObject`.\n\n:param type: Always ``\"response.completed\"``.\n:param response: The final response object with\n    ``status=\"completed\"``.",
        "properties": {
          "response": {
            "$ref": "#/components/schemas/ResponseObject"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "response.completed",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "response"
        ],
        "title": "CompletedEvent",
        "type": "object"
      },
      "ConversationRef": {
        "description": "Lightweight reference to a conversation, used in request and\nresponse bodies where only the conversation ID is needed.\n\n:param id: Conversation identifier, e.g. ``\"conv_abc123\"``.",
        "properties": {
          "id": {
            "title": "Id",
            "type": "string"
          }
        },
        "required": [
          "id"
        ],
        "title": "ConversationRef",
        "type": "object"
      },
      "CreateDefaultPolicyRequest": {
        "description": "Request body for ``POST /v1/policies``.\n\n:param name: Human-readable policy name. Must be globally\n    unique, e.g. ``\"block_non_feature_branch_push\"``.\n:param type: Handler discriminator: ``\"python\"``, ``\"url\"``,\n:param handler: Dotted import path (python) or HTTPS URL\n    (url), e.g.\n    ``\"github_mcp_policy.block_non_misc_push\"``\n    or ``\"https://example.com/policies/eval\"``.\n:param factory_params: Optional dict of kwargs passed to the\n    handler when it is a factory function. Only valid for\n    ``type=\"python\"``, e.g. ``{\"limit\": 10}``.",
        "properties": {
          "factory_params": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Factory Params"
          },
          "handler": {
            "title": "Handler",
            "type": "string"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "name",
          "type",
          "handler"
        ],
        "title": "CreateDefaultPolicyRequest",
        "type": "object"
      },
      "CreateSessionPolicyRequest": {
        "description": "Request body for ``POST /v1/sessions/{session_id}/policies``.\n\n:param name: Human-readable policy name. Must be unique\n    within the session, e.g.\n    ``\"block_non_feature_branch_push\"``.\n:param type: Handler discriminator: ``\"python\"`` or\n    ``\"url\"``.\n:param handler: Dotted import path (python) or HTTPS URL\n    (url), e.g.\n    ``\"github_mcp_policy.block_non_misc_push\"``\n    or ``\"https://example.com/policies/eval\"``.\n:param factory_params: Optional dict of kwargs passed to the\n    handler when it is a factory function. Only valid for\n    ``type=\"python\"``, e.g. ``{\"limit\": 10}``.",
        "properties": {
          "factory_params": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Factory Params"
          },
          "handler": {
            "title": "Handler",
            "type": "string"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "name",
          "type",
          "handler"
        ],
        "title": "CreateSessionPolicyRequest",
        "type": "object"
      },
      "CreatedEvent": {
        "description": "Initial event emitted at the start of every streaming response.\n\nCarries the freshly-allocated\n:class:`omnigent.server.schemas.ResponseObject` (status will\nbe ``\"queued\"`` or ``\"in_progress\"`` depending on whether the\ntask started immediately).\n\n:param type: Always ``\"response.created\"``.\n:param response: The newly-allocated response object.",
        "properties": {
          "response": {
            "$ref": "#/components/schemas/ResponseObject"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "response.created",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "response"
        ],
        "title": "CreatedEvent",
        "type": "object"
      },
      "ElicitationRequestEvent": {
        "description": "Synchronous request for a decision from upstream.\n\nEmitted by Omnigent (or, under the new contract, by a harness)\nwhen the LLM / a tool / a policy needs a verdict before\nproceeding. The consumer replies via\n``POST /v1/sessions/{session_id}/events`` with\n``type == \"approval\"`` and\n:class:`omnigent.server.schemas.ElicitationResult` fields in\n``data``. This preserves MCP request/reply correlation by id\nwithout threading elicitations through PATCH.\n\nWire shape matches the existing emit at\n``omnigent/runtime/policies/approval.py:175``.\n\n:param type: Always ``\"response.elicitation_request\"``.\n:param elicitation_id: Unique correlation id for this\n    request \u2014 appears in the consumer's approval event payload,\n    e.g. ``\"elicit_abc123\"``.\n:param method: MCP method literal \u2014 always\n    ``\"elicitation/create\"`` (the value of\n    ``_MCP_ELICITATION_METHOD`` in\n    ``omnigent/runtime/policies/approval.py``).\n:param params: The MCP-shaped params block carrying the\n    prompt and (form-mode only) the requested schema.",
        "properties": {
          "elicitation_id": {
            "title": "Elicitation Id",
            "type": "string"
          },
          "method": {
            "const": "elicitation/create",
            "default": "elicitation/create",
            "title": "Method",
            "type": "string"
          },
          "params": {
            "$ref": "#/components/schemas/ElicitationRequestParams"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "response.elicitation_request",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "elicitation_id",
          "params"
        ],
        "title": "ElicitationRequestEvent",
        "type": "object"
      },
      "ElicitationRequestParams": {
        "additionalProperties": true,
        "description": "Inner ``params`` block of a :class:`ElicitationRequestEvent`.\n\nThe standard fields (``mode``, ``message``, ``requestedSchema``,\n``url``) mirror MCP's ``ElicitRequestFormParams`` /\n``ElicitRequestUrlParams`` byte-for-byte (Principle 8 \u2014 adopt\nMCP's wire shape verbatim where it overlaps). The\nAP-specific extensions (``phase``, ``policy_name``,\n``content_preview``, ``target_session_id``) carry policy-engine\ncontext and mirrored-child routing for the consumer's renderer;\nMCP's ``extra=\"allow\"`` config permits them under the same params\nblock. Wire shape matches\n``omnigent/runtime/policies/approval.py:175``.\n\n:param mode: MCP-standard discriminator. ``\"form\"`` collects\n    structured input via ``requestedSchema``; ``\"url\"``\n    directs upstream to an external URL for OAuth /\n    out-of-band interaction.\n:param message: Human-readable prompt the consumer renders,\n    e.g. ``\"Approve running 'rm -rf /tmp/cache'?\"``.\n:param requestedSchema: JSON-Schema dict for form mode (or\n    ``None`` for url mode). camelCase preserved per MCP\n    spec, e.g.\n    ``{\"type\": \"object\", \"properties\": {\"approve\":\n    {\"type\": \"boolean\"}}}``.\n:param url: External URL for url mode (or ``None`` for form\n    mode), e.g. ``\"https://oauth.example.com/authorize?...\"``.\n:param phase: Omnigent policy-engine phase the elicitation\n    belongs to, e.g. ``\"pre_tool_use\"``.\n:param policy_name: Omnigent policy that triggered the\n    elicitation, e.g. ``\"approve_shell_commands\"``.\n:param content_preview: Truncated preview of the underlying\n    request payload (\u22641024 chars in current AP), for the\n    consumer's renderer.\n:param target_session_id: AP session whose resolve endpoint owns\n    this elicitation, e.g. ``\"conv_child123\"``. Present when a\n    child/sub-agent prompt is mirrored into an ancestor stream;\n    ``None`` means resolve against the current session.",
        "properties": {
          "content_preview": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Content Preview"
          },
          "message": {
            "title": "Message",
            "type": "string"
          },
          "mode": {
            "default": "form",
            "enum": [
              "form",
              "url"
            ],
            "title": "Mode",
            "type": "string"
          },
          "phase": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Phase"
          },
          "policy_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Policy Name"
          },
          "requestedSchema": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Requestedschema"
          },
          "target_session_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Target Session Id"
          },
          "url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Url"
          }
        },
        "required": [
          "message"
        ],
        "title": "ElicitationRequestParams",
        "type": "object"
      },
      "ElicitationResolvedEvent": {
        "description": "Signal that a previously-published elicitation is no longer\noutstanding, even though no UI ``approval`` verdict was\ndelivered through ``POST /v1/sessions/{id}/events``.\n\nEmitted by the runner when its own ``_pending_approvals``\nFuture is popped without a verdict (the runner's wait timed\nout, the turn was cancelled, the harness exited) so the AP\nserver's :mod:`omnigent.runtime.pending_elicitations`\nindex can decrement the sidebar badge in lockstep with the\nunderlying awaiter's lifecycle. Without this signal, the AP\nserver has no way to learn that the prompt is dead and the\nbadge stays stuck.\n\nIdempotent on the consumer side: the Omnigent server's index\ndecrement is a no-op when the id isn't tracked, so the\nrunner can fire-and-forget on every Future cleanup.\n\n:param type: Always ``\"response.elicitation_resolved\"``.\n:param elicitation_id: Correlation id of the elicitation\n    being cleared, e.g. ``\"elicit_abc123\"``. Must match the\n    id of a prior :class:`ElicitationRequestEvent`.",
        "properties": {
          "elicitation_id": {
            "title": "Elicitation Id",
            "type": "string"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "response.elicitation_resolved",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "elicitation_id"
        ],
        "title": "ElicitationResolvedEvent",
        "type": "object"
      },
      "ElicitationResult": {
        "description": "Consumer reply to an outstanding elicitation.\n\nField names + semantics mirror MCP's ``ElicitResult`` verbatim.\nOmnigent clients deliver this shape inside the session-scoped\n``approval`` event body, alongside the ``elicitation_id``\ncorrelation key.\n\n:param action: User action per MCP semantics. ``\"accept\"`` =\n    approved (form submitted / confirmation given).\n    ``\"decline\"`` = explicit refusal. ``\"cancel\"`` = dismissed\n    without an explicit choice (also the verdict the server\n    synthesizes on elicitation timeout).\n:param content: Form data when ``action == \"accept\"`` and the\n    ``requestedSchema`` had fields. ``None`` (or omitted) for\n    binary approve/reject elicitations and for ``decline`` /\n    ``cancel`` actions. Values are restricted to JSON scalars\n    and string lists per the MCP spec.",
        "properties": {
          "action": {
            "enum": [
              "accept",
              "decline",
              "cancel"
            ],
            "title": "Action",
            "type": "string"
          },
          "content": {
            "anyOf": [
              {
                "additionalProperties": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "integer"
                    },
                    {
                      "type": "number"
                    },
                    {
                      "type": "boolean"
                    },
                    {
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Content"
          }
        },
        "required": [
          "action"
        ],
        "title": "ElicitationResult",
        "type": "object"
      },
      "ErrorDetail": {
        "description": "Machine-readable error information attached to a failed response.\n\n:param code: Error code string, e.g. ``\"server_error\"``,\n    ``\"invalid_input\"``.\n:param message: Human-readable error description.",
        "properties": {
          "code": {
            "title": "Code",
            "type": "string"
          },
          "message": {
            "title": "Message",
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorEvent": {
        "description": "Non-recoverable error reported during the turn.\n\nEmitted from multiple sites in\n``omnigent/runtime/workflow.py`` \u2014 terminal LLM failures\n(``_emit_llm_error_event``), execution timeouts\n(``_handle_execution_timeout``), and the agent-loop catch-all\n(``except Exception``). Wire shape matches those emits.\n\n:param type: Always ``\"response.error\"``.\n:param source: Origin of the error \u2014 ``\"llm\"`` for LLM-call\n    failures, ``\"execution\"`` for timeouts, ``\"tool\"`` for\n    tool failures (currently emitted by retry exhaustion paths).\n:param tool_name: Tool identifier when ``source == \"tool\"``;\n    ``None`` for the other sources.\n:param error: Classified error description.",
        "properties": {
          "error": {
            "$ref": "#/components/schemas/RetryErrorDetail"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "source": {
            "enum": [
              "llm",
              "execution",
              "tool"
            ],
            "title": "Source",
            "type": "string"
          },
          "tool_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Tool Name"
          },
          "type": {
            "const": "response.error",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "source",
          "error"
        ],
        "title": "ErrorEvent",
        "type": "object"
      },
      "FailedEvent": {
        "description": "Terminal event for a turn that ended with an error.\n\nCarries the final\n:class:`omnigent.server.schemas.ResponseObject` whose\n``error`` field describes the failure.\n\n:param type: Always ``\"response.failed\"``.\n:param response: The final response object with\n    ``status=\"failed\"`` and ``error`` populated.",
        "properties": {
          "response": {
            "$ref": "#/components/schemas/ResponseObject"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "response.failed",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "response"
        ],
        "title": "FailedEvent",
        "type": "object"
      },
      "GrantPermissionRequest": {
        "description": "Request body for ``PUT /v1/sessions/{id}/permissions``.\n\n:param user_id: The user to grant access to, e.g.\n    ``\"alice@example.com\"`` or ``\"__public__\"`` for public\n    read access.\n:param level: Numeric permission level: ``1`` = read,\n    ``2`` = edit, ``3`` = manage.",
        "properties": {
          "level": {
            "maximum": 3.0,
            "minimum": 1.0,
            "title": "Level",
            "type": "integer"
          },
          "user_id": {
            "title": "User Id",
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "level"
        ],
        "title": "GrantPermissionRequest",
        "type": "object"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "title": "HTTPValidationError",
        "type": "object"
      },
      "HeartbeatEvent": {
        "description": "Keepalive event emitted on a fixed cadence during streaming.\n\nLets consumers detect stalled producers via missed-interval\ntiming. Cadence is set by ``_HEARTBEAT_INTERVAL_S`` in\n``omnigent/runtime/workflow.py`` (15 seconds at the time of\nwriting). Wire shape matches the existing emit at\n``omnigent/runtime/workflow.py:4636-4639``.\n\nPer ``designs/SERVER_HARNESS_CONTRACT.md`` \u00a7Heartbeats, the\nevent MAY carry timing metadata so consumers can do richer\ndead-detection than \"did anything arrive\":\n\n- ``server_time`` is the producer's wall-clock at emission,\n  letting consumers detect clock drift between producer and\n  consumer.\n- ``last_event_seq`` is the ``sequence_number`` of the most\n  recent NON-heartbeat event (or ``None`` when this is the\n  first heartbeat before any user-visible event), letting\n  consumers detect dropped events on reconnect.\n\nBoth fields are optional on the wire (``None`` round-trips as\nomitted) so older AP\u2192harness pairs that pre-date the field\naddition still parse cleanly.\n\n:param type: Always ``\"response.heartbeat\"``.\n:param server_time: ISO 8601 UTC timestamp at emission, e.g.\n    ``\"2026-04-27T15:30:00Z\"``. ``None`` when the producer\n    chose not to populate it (legacy emitters).\n:param last_event_seq: Sequence number of the last non-\n    heartbeat event seen on the same stream, e.g. ``42``.\n    ``None`` before any user-visible event has fired (first\n    heartbeat of the turn, before deltas land), or when the\n    producer chose not to populate it.",
        "properties": {
          "last_event_seq": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Last Event Seq"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "server_time": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Server Time"
          },
          "type": {
            "const": "response.heartbeat",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type"
        ],
        "title": "HeartbeatEvent",
        "type": "object"
      },
      "InProgressEvent": {
        "description": "Event emitted once the task transitions to in-progress.\n\nAlways follows ``response.created`` (and ``response.queued``\nfor background tasks).\n\n:param type: Always ``\"response.in_progress\"``.\n:param response: The response object with\n    ``status=\"in_progress\"``.",
        "properties": {
          "response": {
            "$ref": "#/components/schemas/ResponseObject"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "response.in_progress",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "response"
        ],
        "title": "InProgressEvent",
        "type": "object"
      },
      "IncompleteDetails": {
        "description": "Details explaining why a response is incomplete.\n\n:param reason: Reason the response stopped early, e.g.\n    ``\"max_output_tokens\"``, ``\"max_tool_calls\"``.",
        "properties": {
          "reason": {
            "title": "Reason",
            "type": "string"
          }
        },
        "required": [
          "reason"
        ],
        "title": "IncompleteDetails",
        "type": "object"
      },
      "IncompleteEvent": {
        "description": "Terminal event for a turn that ended without completing\n(e.g. hit the iteration cap or token budget).\n\n:param type: Always ``\"response.incomplete\"``.\n:param response: The final response object with\n    ``status=\"incomplete\"`` and ``incomplete_details``\n    populated describing the reason.",
        "properties": {
          "response": {
            "$ref": "#/components/schemas/ResponseObject"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "response.incomplete",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "response"
        ],
        "title": "IncompleteEvent",
        "type": "object"
      },
      "LaunchRunnerRequest": {
        "description": "Request body for ``POST /v1/hosts/{host_id}/runners``.\n\n:param session_id: Session to bind the new runner to, e.g.\n    ``\"conv_abc123\"``.\n:param workspace: Absolute path on the host machine to use\n    as the runner's working directory, e.g.\n    ``\"/Users/corey/projects/frontend\"``. When ``git`` is set,\n    this is interpreted as the source repository directory and\n    the runner starts in the created worktree instead.\n:param git: Optional git worktree options. When set, the server\n    creates a worktree for a new branch off ``workspace`` on the\n    host and binds the runner to it (the fork-resume path; mirrors\n    ``POST /v1/sessions``). ``None`` binds ``workspace`` directly.\n    ``host_id`` is always present (it is in the path), so no\n    host requirement check is needed here.",
        "properties": {
          "git": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/SessionGitOptions"
              },
              {
                "type": "null"
              }
            ]
          },
          "session_id": {
            "title": "Session Id",
            "type": "string"
          },
          "workspace": {
            "title": "Workspace",
            "type": "string"
          }
        },
        "required": [
          "session_id",
          "workspace"
        ],
        "title": "LaunchRunnerRequest",
        "type": "object"
      },
      "MCPServerSummary": {
        "description": "Safe subset of an MCP server's configuration for API exposure.\n\nSecret-bearing fields (``headers``, ``env``) are intentionally\nexcluded. This model is the wire shape returned inside\n:class:`AgentObject` so clients can display which MCP servers\nan agent is connected to without leaking credentials.\n\n:param name: Server name as declared in the agent spec,\n    e.g. ``\"github\"``.\n:param transport: Transport type \u2014 ``\"stdio\"`` or ``\"http\"``.\n:param description: Optional free-text description from the\n    spec, e.g. ``\"GitHub MCP server\"``. ``None`` when unset.\n:param url: HTTP(S) endpoint URL for ``transport=\"http\"``\n    servers, e.g. ``\"https://mcp.example.com/sse\"``. ``None``\n    for stdio servers.\n:param command: Executable path for ``transport=\"stdio\"``\n    servers, e.g. ``\"uvx\"``. ``None`` for http servers.\n:param args: Command-line arguments for ``transport=\"stdio\"``\n    servers, e.g. ``[\"mcp-server-github\"]``. Empty list\n    when unset.",
        "properties": {
          "args": {
            "items": {
              "type": "string"
            },
            "title": "Args",
            "type": "array"
          },
          "command": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Command"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "transport": {
            "title": "Transport",
            "type": "string"
          },
          "url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Url"
          }
        },
        "required": [
          "name",
          "transport"
        ],
        "title": "MCPServerSummary",
        "type": "object"
      },
      "ModelUsage": {
        "description": "Cumulative token/cost usage attributed to a single LLM model.\n\nOne value in the ``usage_by_model`` map on :class:`SessionResponse` /\n:class:`SessionUsageEvent`, keyed by the raw harness-reported model id\n(e.g. ``\"claude-sonnet-4-6\"``, ``\"databricks-gpt-5-5\"``). Counts are\nsummed over the session's subtree (itself + sub-agent descendants), so a\nparent folds in sub-agents that ran a different model. Token buckets\nmirror the flat per-session breakdown.\n\n:param input_tokens: Cumulative non-cached input (prompt) tokens for this\n    model over the subtree, e.g. ``12000``. ``None`` when not recorded.\n:param output_tokens: Cumulative output (completion) tokens, e.g.\n    ``3400``. ``None`` when not recorded.\n:param total_tokens: Cumulative total tokens (counts cache buckets too,\n    as the harness reports), e.g. ``15400``. ``None`` when not recorded.\n:param cache_read_input_tokens: Cumulative tokens read from the prompt\n    cache, e.g. ``8000``. ``None`` when not recorded.\n:param cache_creation_input_tokens: Cumulative tokens written to the\n    prompt cache, e.g. ``2000``. ``None`` when not recorded.\n:param total_cost_usd: Cumulative USD spend attributed to this model,\n    e.g. ``0.42``. Present **only when this model's turns were priced**\n    (same \"priced \u27fa key present\" contract as the session total); ``None``\n    when the model is unpriced, so the sum of priced per-model costs\n    equals the session ``total_cost_usd``.",
        "properties": {
          "cache_creation_input_tokens": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Cache Creation Input Tokens"
          },
          "cache_read_input_tokens": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Cache Read Input Tokens"
          },
          "input_tokens": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Input Tokens"
          },
          "output_tokens": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Output Tokens"
          },
          "total_cost_usd": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Total Cost Usd"
          },
          "total_tokens": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Total Tokens"
          }
        },
        "title": "ModelUsage",
        "type": "object"
      },
      "OutputFileDoneEvent": {
        "description": "A streamed file output completed materializing.\n\nEmitted by ``_emit_file_annotation_events`` in\n``omnigent/runtime/workflow.py`` once per file annotation in\nthe assistant's output. ``filename`` and ``content_type`` are\nonly populated when the originating annotation carried them.\n\n:param type: Always ``\"response.output_file.done\"``.\n:param file_id: Identifier of the materialized file,\n    e.g. ``\"file_abc123\"``.\n:param filename: Original filename if the annotation supplied\n    one, e.g. ``\"report.pdf\"``. ``None`` otherwise.\n:param content_type: MIME content type if the annotation\n    supplied one, e.g. ``\"application/pdf\"``. ``None``\n    otherwise.",
        "properties": {
          "content_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Content Type"
          },
          "file_id": {
            "title": "File Id",
            "type": "string"
          },
          "filename": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Filename"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "response.output_file.done",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "file_id"
        ],
        "title": "OutputFileDoneEvent",
        "type": "object"
      },
      "OutputItemDoneEvent": {
        "description": "A conversation output item completed during the turn.\n\nCarries any item type the conversation persists (message,\nfunction_call, function_call_output, reasoning, compaction,\nnative_tool, \u2026). The ``item`` payload's wire shape merges\ncommon fields (``id``, ``type``, ``status``) with the\ntype-specific data fields \u2014 it is NOT nested as\n``{type, data}``.\n\n:param type: Always ``\"response.output_item.done\"``.\n:param item: The completed item dict. Heterogeneous and\n    item-type-specific; see\n    ``omnigent/entities/conversation.py`` for the\n    per-type ``*Data`` shapes that drive serialization.\n    Example for a function_call item: ``{\"id\": \"fc_abc123\",\n    \"type\": \"function_call\", \"status\": \"action_required\",\n    \"name\": \"search.web\", \"arguments\": \"{\\\"q\\\": \\\"foo\\\"}\",\n    \"call_id\": \"call_xyz\"}``.",
        "properties": {
          "item": {
            "additionalProperties": true,
            "title": "Item",
            "type": "object"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "response.output_item.done",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "item"
        ],
        "title": "OutputItemDoneEvent",
        "type": "object"
      },
      "OutputTextDeltaEvent": {
        "description": "Incremental assistant-text token emitted during streaming.\n\nWire shape matches the existing raw-dict emit at\n``omnigent/runtime/workflow.py:1352-1356``.\n\n:param type: Always ``\"response.output_text.delta\"``.\n:param delta: The text fragment for this chunk, e.g.\n    ``\"Hello\"``.\n:param message_id: For terminal-observed streaming (claude-native),\n    the vendor's stable per-message id, e.g.\n    ``\"2ca51d97-2f0f-493a-aed7-85a5b56c5747\"``. Lets the web UI scope\n    an in-flight buffer to one assistant message and reconcile it\n    against the final item. ``None`` for ordinary in-process task\n    streaming, where deltas already group by the active response.\n:param index: 0-based chunk order within the message, e.g. ``3``.\n    ``None`` when not terminal-observed streaming.\n:param final: ``True`` on the last chunk of a terminal-observed\n    message; ``None`` otherwise. Signals the web UI that no further\n    chunks for ``message_id`` will arrive.",
        "properties": {
          "delta": {
            "title": "Delta",
            "type": "string"
          },
          "final": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Final"
          },
          "index": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Index"
          },
          "message_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Message Id"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "response.output_text.delta",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "delta"
        ],
        "title": "OutputTextDeltaEvent",
        "type": "object"
      },
      "PaginatedList": {
        "description": "A paginated list response following cursor-based pagination.\n\n:param object: Fixed resource type, always ``\"list\"``.\n:param data: Page of results. Items are heterogeneous\n    (``ResponseObject``, ``ConversationObject``, ``FileObject``,\n    or dicts) and list is invariant, so no single concrete type\n    satisfies all callers.\n:param first_id: ID of the first item in the page, or ``None``\n    if the page is empty, e.g. ``\"resp_abc123\"``.\n:param last_id: ID of the last item in the page, or ``None``\n    if the page is empty, e.g. ``\"resp_xyz789\"``.\n:param has_more: Whether more items exist beyond this page.",
        "properties": {
          "data": {
            "items": {},
            "title": "Data",
            "type": "array"
          },
          "first_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "First Id"
          },
          "has_more": {
            "default": false,
            "title": "Has More",
            "type": "boolean"
          },
          "last_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Last Id"
          },
          "object": {
            "default": "list",
            "title": "Object",
            "type": "string"
          }
        },
        "title": "PaginatedList",
        "type": "object"
      },
      "PolicySummary": {
        "description": "Safe subset of a policy's spec for API exposure.\n\nExposes the policy name, type, and phases so the UI can\ndisplay which guardrails are active on an agent. The full\npolicy body (prompt text, callable path, label conditions)\nis intentionally excluded \u2014 this is a summary for display,\nnot a full spec.\n\n:param name: Policy name as declared in the agent spec,\n    e.g. ``\"block_long_sleep\"``.\n:param type: Policy type discriminator \u2014 ``\"function\"``\n    or ``\"prompt\"``.\n:param on: List of phase selectors the policy fires on,\n    e.g. ``[\"tool_call\"]`` or ``[\"request\", \"response\"]``.\n:param description: Short detail string about the policy\n    implementation. For function policies: the callable\n    dotted path. For prompt policies: the first line of\n    the prompt. ``None`` when not available.",
        "properties": {
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "on": {
            "items": {
              "type": "string"
            },
            "title": "On",
            "type": "array"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "name",
          "type",
          "on"
        ],
        "title": "PolicySummary",
        "type": "object"
      },
      "PresenceViewer": {
        "description": "One user currently viewing a session (holding its SSE stream open).\n\n:param user_id: The viewer's authenticated identity,\n    e.g. ``\"alice@example.com\"``. Never the reserved single-user\n    ``\"local\"`` sentinel \u2014 presence only tracks distinct human\n    actors (see ``attribution_user``).\n:param joined_at: ISO 8601 UTC timestamp of when the user joined,\n    e.g. ``\"2026-06-10T17:00:00Z\"``. Stable across reconnects\n    within the server's leave-grace window.\n:param idle: Whether every stream the user holds reports an idle\n    (backgrounded) tab. The web greys idle viewers' avatars.",
        "properties": {
          "idle": {
            "default": false,
            "title": "Idle",
            "type": "boolean"
          },
          "joined_at": {
            "title": "Joined At",
            "type": "string"
          },
          "user_id": {
            "title": "User Id",
            "type": "string"
          }
        },
        "required": [
          "user_id",
          "joined_at"
        ],
        "title": "PresenceViewer",
        "type": "object"
      },
      "QueuedEvent": {
        "description": "Optional event emitted between ``created`` and ``in_progress``\nfor background tasks that are queued before they start.\n\nForeground streaming responses skip this event.\n\n:param type: Always ``\"response.queued\"``.\n:param response: The response object with\n    ``status=\"queued\"``.",
        "properties": {
          "response": {
            "$ref": "#/components/schemas/ResponseObject"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "response.queued",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "response"
        ],
        "title": "QueuedEvent",
        "type": "object"
      },
      "ReasoningStartedEvent": {
        "description": "Marker emitted once when a reasoning block begins.\n\nFired even when the reasoning content itself is encrypted /\nredacted (so no delta events follow), letting clients render\na \"thinking\u2026\" indicator regardless of provider verification\nstatus. Wire shape matches ``omnigent/runtime/workflow.py:1350``.\n\n:param type: Always ``\"response.reasoning.started\"``.",
        "properties": {
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "response.reasoning.started",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type"
        ],
        "title": "ReasoningStartedEvent",
        "type": "object"
      },
      "ReasoningSummaryTextDeltaEvent": {
        "description": "Incremental reasoning-summary token.\n\nEmitted when ``reasoning.summary`` is configured on the\nrequest. Wire shape matches\n``omnigent/runtime/workflow.py:1370-1373``.\n\n:param type: Always ``\"response.reasoning_summary_text.delta\"``.\n:param delta: The summary text fragment, e.g. ``\"Will use\n    the search tool to gather context.\"``.",
        "properties": {
          "delta": {
            "title": "Delta",
            "type": "string"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "response.reasoning_summary_text.delta",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "delta"
        ],
        "title": "ReasoningSummaryTextDeltaEvent",
        "type": "object"
      },
      "ReasoningTextDeltaEvent": {
        "description": "Incremental reasoning-text token (full chain-of-thought).\n\nOnly emitted by providers that surface reasoning content\n(e.g. OpenAI o-series with appropriate verification). Wire\nshape matches ``omnigent/runtime/workflow.py:1358-1364``.\n\n:param type: Always ``\"response.reasoning_text.delta\"``.\n:param delta: The reasoning text fragment, e.g.\n    ``\"Considering the user's intent...\"``.",
        "properties": {
          "delta": {
            "title": "Delta",
            "type": "string"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "response.reasoning_text.delta",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "delta"
        ],
        "title": "ReasoningTextDeltaEvent",
        "type": "object"
      },
      "ResponseObject": {
        "description": "API representation of a response (task execution result).\n\n:param id: Unique response identifier, e.g.\n    ``\"resp_abc123\"``.\n:param object: Fixed resource type, always ``\"response\"``.\n:param status: Lifecycle status, one of ``\"queued\"``,\n    ``\"in_progress\"``, ``\"completed\"``, ``\"failed\"``,\n    ``\"incomplete\"``, ``\"cancelled\"``.\n:param model: Agent name that produced this response,\n    e.g. ``\"research-agent\"``.\n:param created_at: Unix epoch timestamp of creation.\n:param completed_at: Unix epoch timestamp of completion, or\n    ``None`` if not yet complete.\n:param output: Heterogeneous output items (messages,\n    reasoning, function_calls) serialized as dicts; shape\n    varies by item type. Empty for non-completed responses.\n:param background: Whether this response was created as a\n    background task.\n:param store: Whether this response is persisted. Always\n    ``True``.\n:param usage: Token usage statistics, or ``None`` if not\n    yet available.\n:param previous_response_id: ID of the prior response in\n    the conversation thread, or ``None`` for the first turn.\n:param conversation: Reference to the owning conversation.\n:param instructions: Per-request system instructions\n    override, or ``None``.\n:param reasoning: Reasoning configuration,\n    e.g. ``{\"effort\": \"medium\"}``.\n:param error: Error details if the response failed.\n:param incomplete_details: Details if the response is\n    incomplete (e.g. hit token limit).",
        "properties": {
          "background": {
            "default": false,
            "title": "Background",
            "type": "boolean"
          },
          "completed_at": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Completed At"
          },
          "conversation": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ConversationRef"
              },
              {
                "type": "null"
              }
            ],
            "default": null
          },
          "created_at": {
            "title": "Created At",
            "type": "integer"
          },
          "error": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ErrorDetail"
              },
              {
                "type": "null"
              }
            ],
            "default": null
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "incomplete_details": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/IncompleteDetails"
              },
              {
                "type": "null"
              }
            ],
            "default": null
          },
          "instructions": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Instructions"
          },
          "model": {
            "title": "Model",
            "type": "string"
          },
          "object": {
            "default": "response",
            "title": "Object",
            "type": "string"
          },
          "output": {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "title": "Output",
            "type": "array"
          },
          "previous_response_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Previous Response Id"
          },
          "reasoning": {
            "anyOf": [
              {
                "additionalProperties": {
                  "type": "string"
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Reasoning"
          },
          "status": {
            "title": "Status",
            "type": "string"
          },
          "store": {
            "default": true,
            "title": "Store",
            "type": "boolean"
          },
          "usage": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Usage"
              },
              {
                "type": "null"
              }
            ],
            "default": null
          }
        },
        "required": [
          "id",
          "status",
          "model",
          "created_at"
        ],
        "title": "ResponseObject",
        "type": "object"
      },
      "RetryErrorDetail": {
        "description": "Error block carried by :class:`RetryEvent` and :class:`ErrorEvent`.\n\nMirrors the shape that ``llm_retry.py`` and ``tool_retry.py``\nemit today \u2014 flat ``code`` / ``message`` plus an optional\n``detail`` for provider-specific structured fields.\n\n:param code: Stable error classifier, e.g. ``\"timeout\"``,\n    ``\"rate_limit\"``.\n:param message: Human-readable summary, e.g.\n    ``\"Connection timed out after 30s\"``.\n:param detail: Optional provider-specific structured fields\n    (e.g. ``{\"status_code\": 429, \"retry_after\": 5}``);\n    ``None`` when the classifier had no extra context.",
        "properties": {
          "code": {
            "title": "Code",
            "type": "string"
          },
          "detail": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Detail"
          },
          "message": {
            "title": "Message",
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "title": "RetryErrorDetail",
        "type": "object"
      },
      "RetryEvent": {
        "description": "A retryable failure was caught and a retry is scheduled.\n\nEmitted by ``omnigent/runtime/llm_retry.py`` (LLM calls)\nand ``omnigent/runtime/tool_retry.py`` (tool calls) before\nsleeping for the backoff delay. Wire shape matches\n``llm_retry.py:329-340`` and ``tool_retry.py:168-180``.\n\n:param type: Always ``\"response.retry\"``.\n:param source: Origin of the retried failure \u2014 ``\"llm\"`` for\n    LLM-call retries, ``\"tool\"`` for tool-call retries.\n:param tool_name: Tool identifier when ``source == \"tool\"``,\n    e.g. ``\"search.web\"``. ``None`` for LLM retries.\n:param attempt: 1-based count of the upcoming attempt\n    (i.e. attempt that will run AFTER this delay), e.g.\n    ``2`` for the first retry.\n:param max_attempts: Total tries allowed by the retry policy,\n    e.g. ``3``. Lets clients render \"attempt 2 of 3\".\n:param delay_seconds: Seconds the producer will sleep before\n    retrying, rounded to two decimals, e.g. ``1.5``.\n:param error: Classified error description for the failure\n    being retried.",
        "properties": {
          "attempt": {
            "title": "Attempt",
            "type": "integer"
          },
          "delay_seconds": {
            "title": "Delay Seconds",
            "type": "number"
          },
          "error": {
            "$ref": "#/components/schemas/RetryErrorDetail"
          },
          "max_attempts": {
            "title": "Max Attempts",
            "type": "integer"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "source": {
            "enum": [
              "llm",
              "tool"
            ],
            "title": "Source",
            "type": "string"
          },
          "tool_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Tool Name"
          },
          "type": {
            "const": "response.retry",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "source",
          "attempt",
          "max_attempts",
          "delay_seconds",
          "error"
        ],
        "title": "RetryEvent",
        "type": "object"
      },
      "SendCommentsRequest": {
        "description": "Request body for ``POST .../comments/send``.\n\n:param comment_ids: IDs of comments to send.\n:param instruction: Optional custom instruction prefix; defaults\n    to the standard \"Please address the following file review\n    comments.\" header.",
        "properties": {
          "comment_ids": {
            "items": {
              "type": "string"
            },
            "title": "Comment Ids",
            "type": "array"
          },
          "instruction": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Instruction"
          }
        },
        "required": [
          "comment_ids"
        ],
        "title": "SendCommentsRequest",
        "type": "object"
      },
      "ServerStreamEvent": {
        "discriminator": {
          "mapping": {
            "response.cancelled": "#/components/schemas/CancelledEvent",
            "response.client_task.cancel": "#/components/schemas/ClientTaskCancelEvent",
            "response.compaction.completed": "#/components/schemas/CompactionCompletedEvent",
            "response.compaction.failed": "#/components/schemas/CompactionFailedEvent",
            "response.compaction.in_progress": "#/components/schemas/CompactionInProgressEvent",
            "response.completed": "#/components/schemas/CompletedEvent",
            "response.created": "#/components/schemas/CreatedEvent",
            "response.elicitation_request": "#/components/schemas/ElicitationRequestEvent",
            "response.elicitation_resolved": "#/components/schemas/ElicitationResolvedEvent",
            "response.error": "#/components/schemas/ErrorEvent",
            "response.failed": "#/components/schemas/FailedEvent",
            "response.heartbeat": "#/components/schemas/HeartbeatEvent",
            "response.in_progress": "#/components/schemas/InProgressEvent",
            "response.incomplete": "#/components/schemas/IncompleteEvent",
            "response.output_file.done": "#/components/schemas/OutputFileDoneEvent",
            "response.output_item.done": "#/components/schemas/OutputItemDoneEvent",
            "response.output_text.delta": "#/components/schemas/OutputTextDeltaEvent",
            "response.queued": "#/components/schemas/QueuedEvent",
            "response.reasoning.started": "#/components/schemas/ReasoningStartedEvent",
            "response.reasoning_summary_text.delta": "#/components/schemas/ReasoningSummaryTextDeltaEvent",
            "response.reasoning_text.delta": "#/components/schemas/ReasoningTextDeltaEvent",
            "response.retry": "#/components/schemas/RetryEvent",
            "session.agent_changed": "#/components/schemas/SessionAgentChangedEvent",
            "session.changed_files.invalidated": "#/components/schemas/SessionChangedFilesInvalidatedEvent",
            "session.child_session.updated": "#/components/schemas/SessionChildSessionUpdatedEvent",
            "session.created": "#/components/schemas/SessionCreatedEvent",
            "session.heartbeat": "#/components/schemas/SessionHeartbeatEvent",
            "session.input.consumed": "#/components/schemas/SessionInputConsumedEvent",
            "session.interrupted": "#/components/schemas/SessionInterruptedEvent",
            "session.model": "#/components/schemas/SessionModelEvent",
            "session.presence": "#/components/schemas/SessionPresenceEvent",
            "session.resource.created": "#/components/schemas/SessionResourceCreatedEvent",
            "session.resource.deleted": "#/components/schemas/SessionResourceDeletedEvent",
            "session.sandbox_status": "#/components/schemas/SessionSandboxStatusEvent",
            "session.skills": "#/components/schemas/SessionSkillsEvent",
            "session.status": "#/components/schemas/SessionStatusEvent",
            "session.terminal.activity": "#/components/schemas/SessionTerminalActivityEvent",
            "session.terminal_pending": "#/components/schemas/SessionTerminalPendingEvent",
            "session.todos": "#/components/schemas/SessionTodosEvent",
            "session.usage": "#/components/schemas/SessionUsageEvent",
            "turn.cancelled": "#/components/schemas/TurnCancelledEvent",
            "turn.completed": "#/components/schemas/TurnCompletedEvent",
            "turn.failed": "#/components/schemas/TurnFailedEvent",
            "turn.started": "#/components/schemas/TurnStartedEvent"
          },
          "propertyName": "type"
        },
        "oneOf": [
          {
            "$ref": "#/components/schemas/SessionStatusEvent"
          },
          {
            "$ref": "#/components/schemas/SessionUsageEvent"
          },
          {
            "$ref": "#/components/schemas/SessionModelEvent"
          },
          {
            "$ref": "#/components/schemas/SessionAgentChangedEvent"
          },
          {
            "$ref": "#/components/schemas/SessionTodosEvent"
          },
          {
            "$ref": "#/components/schemas/SessionTerminalPendingEvent"
          },
          {
            "$ref": "#/components/schemas/SessionSandboxStatusEvent"
          },
          {
            "$ref": "#/components/schemas/SessionSkillsEvent"
          },
          {
            "$ref": "#/components/schemas/SessionInputConsumedEvent"
          },
          {
            "$ref": "#/components/schemas/SessionInterruptedEvent"
          },
          {
            "$ref": "#/components/schemas/SessionCreatedEvent"
          },
          {
            "$ref": "#/components/schemas/SessionPresenceEvent"
          },
          {
            "$ref": "#/components/schemas/SessionResourceCreatedEvent"
          },
          {
            "$ref": "#/components/schemas/SessionResourceDeletedEvent"
          },
          {
            "$ref": "#/components/schemas/SessionChildSessionUpdatedEvent"
          },
          {
            "$ref": "#/components/schemas/SessionChangedFilesInvalidatedEvent"
          },
          {
            "$ref": "#/components/schemas/SessionTerminalActivityEvent"
          },
          {
            "$ref": "#/components/schemas/OutputTextDeltaEvent"
          },
          {
            "$ref": "#/components/schemas/ReasoningStartedEvent"
          },
          {
            "$ref": "#/components/schemas/ReasoningTextDeltaEvent"
          },
          {
            "$ref": "#/components/schemas/ReasoningSummaryTextDeltaEvent"
          },
          {
            "$ref": "#/components/schemas/OutputItemDoneEvent"
          },
          {
            "$ref": "#/components/schemas/OutputFileDoneEvent"
          },
          {
            "$ref": "#/components/schemas/HeartbeatEvent"
          },
          {
            "$ref": "#/components/schemas/SessionHeartbeatEvent"
          },
          {
            "$ref": "#/components/schemas/ElicitationRequestEvent"
          },
          {
            "$ref": "#/components/schemas/ElicitationResolvedEvent"
          },
          {
            "$ref": "#/components/schemas/CreatedEvent"
          },
          {
            "$ref": "#/components/schemas/QueuedEvent"
          },
          {
            "$ref": "#/components/schemas/InProgressEvent"
          },
          {
            "$ref": "#/components/schemas/CompletedEvent"
          },
          {
            "$ref": "#/components/schemas/FailedEvent"
          },
          {
            "$ref": "#/components/schemas/CancelledEvent"
          },
          {
            "$ref": "#/components/schemas/IncompleteEvent"
          },
          {
            "$ref": "#/components/schemas/RetryEvent"
          },
          {
            "$ref": "#/components/schemas/ErrorEvent"
          },
          {
            "$ref": "#/components/schemas/CompactionInProgressEvent"
          },
          {
            "$ref": "#/components/schemas/CompactionCompletedEvent"
          },
          {
            "$ref": "#/components/schemas/CompactionFailedEvent"
          },
          {
            "$ref": "#/components/schemas/ClientTaskCancelEvent"
          },
          {
            "$ref": "#/components/schemas/TurnStartedEvent"
          },
          {
            "$ref": "#/components/schemas/TurnCompletedEvent"
          },
          {
            "$ref": "#/components/schemas/TurnFailedEvent"
          },
          {
            "$ref": "#/components/schemas/TurnCancelledEvent"
          }
        ]
      },
      "SessionAgentChangedEvent": {
        "description": "Bound-agent change on a live session.\n\nEmitted by the switch-agent route after the session's agent binding\nis rewritten in place. Connected clients re-derive their cached\nsession state (harness presentation labels, bound agent id/name)\nfrom a fresh snapshot \u2014 the chat UI's native-vs-SDK message\nlifecycle depends on those labels, so a stale cache drops the first\npost-switch message (it reappears only when the transcript\nround-trip lands).\n\n:param type: Always ``\"session.agent_changed\"``.\n:param conversation_id: Session identifier, e.g. ``\"conv_abc123\"``.\n:param agent_id: The session-scoped clone now bound to the session,\n    e.g. ``\"ag_abc123\"``.\n:param agent_name: Display name of the agent the session now runs,\n    e.g. ``\"claude-native-ui\"``. Deliberately the clean target-agent\n    name \u2014 not the clone row's ``\"\u2026 (switch ag_\u2026)\"`` disambiguation\n    name \u2014 because clients render it verbatim.\n\nCategory: **transient** (SSE-only). The switch is persisted on the\nconversation row, so on reconnect clients read the new binding from\nthe session snapshot rather than from a replayed event.",
        "properties": {
          "agent_id": {
            "title": "Agent Id",
            "type": "string"
          },
          "agent_name": {
            "title": "Agent Name",
            "type": "string"
          },
          "conversation_id": {
            "title": "Conversation Id",
            "type": "string"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "session.agent_changed",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "conversation_id",
          "agent_id",
          "agent_name"
        ],
        "title": "SessionAgentChangedEvent",
        "type": "object"
      },
      "SessionChangedFilesInvalidatedEvent": {
        "description": "The session's changed-files list may have changed \u2014 refetch it.\n\nA coarse \"something changed\" signal (per-file events aren't available\nfor git-mode workspaces) emitted by the runner after a file-mutating\ntool. The web treats it as a refetch trigger for the changed-files\npanel; transient (not persisted \u2014 the REST list is source of truth).\n\n:param type: Always ``\"session.changed_files.invalidated\"``.\n:param session_id: Owning session/conversation id.\n:param environment_id: Environment whose changes were invalidated,\n    e.g. ``\"default\"``.",
        "properties": {
          "environment_id": {
            "default": "default",
            "title": "Environment Id",
            "type": "string"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "session_id": {
            "title": "Session Id",
            "type": "string"
          },
          "type": {
            "const": "session.changed_files.invalidated",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "session_id"
        ],
        "title": "SessionChangedFilesInvalidatedEvent",
        "type": "object"
      },
      "SessionChildSessionUpdatedEvent": {
        "description": "A child (sub-agent) session's status changed \u2014 pushed to the PARENT.\n\nLets the parent's resource rail update a child's status without\npolling ``GET \u2026/child_sessions``. Carries the full\n:class:`ChildSessionSummary` so the web patches its cache directly.\n\n:param type: Always ``\"session.child_session.updated\"``.\n:param conversation_id: The PARENT (carrier) session id.\n:param child_session_id: The child session id, e.g.\n    ``\"conv_child_abc123\"``.\n:param child: A PARTIAL :class:`ChildSessionSummary` \u2014 the\n    snapshot-on-connect sends the full summary, while live runner\n    deltas carry only the fields that changed (a status delta omits\n    ``last_message_preview``; a preview delta carries only it). The\n    web merges present fields over the cached row, so the payload is\n    an open dict rather than the strict model.",
        "properties": {
          "child": {
            "additionalProperties": true,
            "title": "Child",
            "type": "object"
          },
          "child_session_id": {
            "title": "Child Session Id",
            "type": "string"
          },
          "conversation_id": {
            "title": "Conversation Id",
            "type": "string"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "session.child_session.updated",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "conversation_id",
          "child_session_id",
          "child"
        ],
        "title": "SessionChildSessionUpdatedEvent",
        "type": "object"
      },
      "SessionCreatedEvent": {
        "description": "A child (sub-agent) session was spawned from this session.\n\nEmitted by ``omnigent/tools/builtins/spawn.py:_spawn_one``\nonto the **parent** session's conversation stream after the\nchild conversation row is created and the child task has been\nstarted. Per the session-rearchitecture spec \u00a73 (\"Event types\nand direction\") and \u00a77 (\"Flow: client interacts with\nsub-agent\"), this lets clients watching the parent session's\nSSE subscribe directly to the child's stream without polling\nhistory for the tunneled ``function_call`` item.\n\nThe wire shape is FLAT (not enveloped):\n``{\"type\": \"session.created\", \"conversation_id\": <parent>,\n\"child_session_id\": <child>, \"agent_id\": <agent or None>,\n\"parent_session_id\": <parent>, \"sequence_number\": null}``.\n\nThe existing tunneled ``function_call`` ConversationItem\n(carried inside :class:`OutputItemDoneEvent`) is retained\nfor compatibility \u2014 clients that don't yet implement the\n\"subscribe to child stream\" pattern can keep rendering sub-\nagent calls from the parent's persistent history.\n\n:param type: Always ``\"session.created\"``.\n:param conversation_id: The PARENT session/conversation id \u2014\n    this event rides the parent's stream, e.g.\n    ``\"conv_parent123\"``.\n:param child_session_id: The newly-created child session id,\n    e.g. ``\"conv_child456\"``. Same as ``conversation_id`` on\n    the child's own stream when consumers pivot to it.\n:param agent_id: Registered agent id the child runs as,\n    e.g. ``\"agent_xyz\"``. ``None`` is permitted only for\n    legacy spawn paths that did not record an agent id;\n    new code MUST set it.\n:param parent_session_id: Echo of ``conversation_id`` for\n    consumers that key on a dedicated \"parent\" field rather\n    than the carrier ``conversation_id``. Always equal to\n    ``conversation_id``; included for forward-compat with\n    clients that may relay these events across stream\n    boundaries.\n\nCategory: **transient** (SSE-only). The corresponding durable\nrecord of \"a child session exists\" lives in the conversation\nstore as the child conversation row itself\n(``parent_conversation_id`` foreign key) and the parent's\ntunneled ``function_call`` item \u2014 reconnecting clients\ndiscover children by walking the parent's persisted history,\nnot by replaying this event.",
        "properties": {
          "agent_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Agent Id"
          },
          "child_session_id": {
            "title": "Child Session Id",
            "type": "string"
          },
          "conversation_id": {
            "title": "Conversation Id",
            "type": "string"
          },
          "parent_session_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Parent Session Id"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "session.created",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "conversation_id",
          "child_session_id"
        ],
        "title": "SessionCreatedEvent",
        "type": "object"
      },
      "SessionEventInput": {
        "description": "A single client-submitted event/input item for a session.\n\nUsed both as an element of ``initial_items`` on session\ncreation and as the body of ``POST /v1/sessions/{id}/events``.\nCarries a discriminator (``type``) and a free-form ``data``\npayload whose shape is interpreted by the route layer based\non ``type`` (e.g. user message, function-call output,\napproval, interrupt).\n\n:param model_override: Optional per-event LLM model override\n    used when this event starts a fresh agent turn. Distinct\n    from the session's bound agent; it substitutes for the\n    agent spec's ``llm.model`` for that turn.\n:param type: Discriminator for the event/input kind, e.g.\n    ``\"message\"``, ``\"function_call_output\"``, ``\"interrupt\"``.\n:param data: Type-specific payload. Shape varies by ``type``;\n    for ``\"message\"`` this looks like\n    ``{\"role\": \"user\", \"content\": [{\"type\": \"input_text\",\n    \"text\": \"Hello\"}]}``. For ``\"interrupt\"`` this is\n    typically ``{}``.\n:param tools: Optional OpenAI function-tool dicts registered\n    when this event creates a new task. Mirrors\n    :attr:`CreateResponseRequest.tools`, e.g. ``[{\"type\":\n    \"function\", \"function\": {\"name\": \"get_weather\",\n    \"description\": \"...\", \"parameters\": {...}}}]``. Ignored\n    when the event steers into an active task: that task's\n    tools are fixed at start time.",
        "properties": {
          "data": {
            "additionalProperties": true,
            "title": "Data",
            "type": "object"
          },
          "model_override": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Model Override"
          },
          "tools": {
            "anyOf": [
              {
                "items": {
                  "additionalProperties": true,
                  "type": "object"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Tools"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type"
        ],
        "title": "SessionEventInput",
        "type": "object"
      },
      "SessionForkRequest": {
        "additionalProperties": false,
        "description": "Request body for ``POST /v1/sessions/{source_id}/fork``.\n\nCreates a deep copy of an existing session's items into a new\nsession. All fields are optional.\n\n:param title: Title for the forked session. When ``None``, the\n    server derives ``\"Fork of <source_title>\"``.\n:param agent_id: Built-in agent to bind the fork to, switching it\n    away from the source's agent/harness (e.g. fork a Claude session\n    into a Codex one, or a Claude-SDK session into Claude Code). When\n    ``None``, the fork keeps the source's agent. Must be a built-in\n    agent (one listed by ``GET /v1/agents``).\n:param up_to_response_id: Truncation point for the copied history,\n    e.g. ``\"resp_abc123\"``. When set, only items up to and including\n    the last item of that response are copied \u2014 items after it are\n    dropped from the fork. When ``None`` (default), the full history\n    is copied.",
        "properties": {
          "agent_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Agent Id"
          },
          "title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Title"
          },
          "up_to_response_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Up To Response Id"
          }
        },
        "title": "SessionForkRequest",
        "type": "object"
      },
      "SessionGitOptions": {
        "description": "Git worktree options for ``POST /v1/sessions``.\n\nWhen present, the server creates a git worktree on the host for a\nnew branch and starts the runner in that worktree instead of the\npicked directory. Requires ``host_id`` to be set (and therefore\n``workspace``, which is interpreted as the source repository\ndirectory). See designs/SESSION_GIT_WORKTREE.md.\n\n:param branch_name: Name of the new branch to create and check\n    out in the worktree, e.g. ``\"feature/login\"``. Validated\n    against git ref-format rules; invalid names fail with\n    ``invalid_input``.\n:param base_branch: Optional base ref to branch from, e.g.\n    ``\"main\"`` or ``\"origin/main\"``. ``None`` branches from the\n    source repository's current ``HEAD``.",
        "properties": {
          "base_branch": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Base Branch"
          },
          "branch_name": {
            "title": "Branch Name",
            "type": "string"
          }
        },
        "required": [
          "branch_name"
        ],
        "title": "SessionGitOptions",
        "type": "object"
      },
      "SessionHeartbeatEvent": {
        "description": "Idle-stream keepalive on ``GET /v1/sessions/{id}/stream``.\n\nEmitted by the session-stream route on a fixed cadence whenever\nthe underlying publish queue has been quiet (no turn in flight,\nno resource events). Distinct from :class:`HeartbeatEvent`\n(``response.heartbeat``), which is per-turn and is driven by\nthe runtime workflow while a response is producing output.\n\nWhy this exists: the session stream stays open across many turns\nand through idle periods (waiting for the user to type). Without\na periodic emit, intermediate proxies, OS-level sockets, and the\nclient's SSE read-timeout can leave a half-open stream\nundetected for minutes after a network event (laptop sleep,\nWi-Fi handoff). The heartbeat puts a regular byte on the wire\nso the client's read-timeout and the server's\n``request.is_disconnected()`` check both fire promptly.\n\nConsumers MAY ignore the payload entirely (the bytes crossing\nthe wire are sufficient). The optional ``server_time`` mirrors\n:class:`HeartbeatEvent` for symmetry and debugging.\n\n:param type: Always ``\"session.heartbeat\"``.\n:param server_time: ISO 8601 UTC timestamp at emission, e.g.\n    ``\"2026-05-25T10:30:00Z\"``. ``None`` when the producer\n    chose not to populate it.",
        "properties": {
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "server_time": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Server Time"
          },
          "type": {
            "const": "session.heartbeat",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type"
        ],
        "title": "SessionHeartbeatEvent",
        "type": "object"
      },
      "SessionInputConsumedEvent": {
        "description": "A queued input item was materialized into conversation history.\n\nEmitted by ``POST /v1/sessions/{id}/events`` once per accepted\ninput item at the moment it is persisted into conversation\nhistory (either onto a steered active turn or as the seed item\nof a freshly-started one). Wire shape uses the NESTED envelope:\n``{\"type\": \"session.input.consumed\", \"data\":\n<:class:`SessionInputConsumedPayload`>, \"sequence_number\":\nnull}``.\n\nThe event name is **provisional** \u2014 it may be renamed in a\nfuture revision. Consumers should reference\n:data:`SessionInputConsumedEvent` (or its ``type`` literal)\nrather than hardcoding the wire string.\n\n:param type: Always ``\"session.input.consumed\"``.\n:param data: The decoded queued-item payload \u2014 see\n    :class:`SessionInputConsumedPayload`.",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/SessionInputConsumedPayload"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "session.input.consumed",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "data"
        ],
        "title": "SessionInputConsumedEvent",
        "type": "object"
      },
      "SessionInputConsumedPayload": {
        "description": "Inner payload of a :class:`SessionInputConsumedEvent`.\n\nEmitted by the sessions route handler at the moment a client\ninput is persisted into ``conversation_items``. Carries the\npersisted-item shape so clients can render the input (e.g.\nthe user's message bubble) at the moment of acceptance.\n\n:param item_id: Stable identifier of the conversation item\n    just persisted, e.g. ``\"item_abc123\"``.\n:param type: The item type discriminator \u2014 ``\"message\"`` for\n    user messages, ``\"function_call_output\"`` for tool\n    results, etc. Mirrors\n    :class:`omnigent.server.schemas.SessionEventInput`'s\n    ``type`` field.\n:param data: Decoded item payload, e.g.\n    ``{\"role\": \"user\", \"content\": [{\"type\": \"input_text\",\n    \"text\": \"Hello\"}]}``. Heterogeneous and ``type``-specific.\n:param created_by: Email of the human actor who posted the item,\n    e.g. ``\"alice@example.com\"``. ``None`` for agent/tool/system\n    items and single-user mode. Mirrors\n    :meth:`ConversationItem.to_api_dict` for live attribution.\n:param cleared_pending_id: When this consumed message drains a\n    :mod:`omnigent.runtime.pending_inputs` entry (a native-\n    terminal web message round-tripping back from the transcript),\n    the drained entry's id, e.g. ``\"pending_a1b2c3\"``. Lets a\n    client drop the matching optimistic bubble by id instead of\n    by position. ``None`` for non-native messages and for messages\n    that matched no pending entry (e.g. typed directly in the TUI).",
        "properties": {
          "cleared_pending_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Cleared Pending Id"
          },
          "created_by": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Created By"
          },
          "data": {
            "additionalProperties": true,
            "title": "Data",
            "type": "object"
          },
          "item_id": {
            "title": "Item Id",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "item_id",
          "type",
          "data"
        ],
        "title": "SessionInputConsumedPayload",
        "type": "object"
      },
      "SessionInterruptedEvent": {
        "description": "User-triggered cancel reached the loop.\n\nEmitted by ``_publish_interrupted`` in\n``omnigent/server/routes/sessions.py`` when a client posts\na ``{\"type\": \"interrupt\"}`` to ``POST\n/v1/sessions/{id}/events``. Co-emitted with\n:class:`IncompleteEvent` (with the underlying response carrying\n``incomplete_details.reason == \"user_interrupt\"``) so off-the-\nshelf Responses parsers still close cleanly. Wire shape uses\nthe NESTED envelope verbatim from the existing emit site.\n\n:param type: Always ``\"session.interrupted\"``.\n:param data: The interrupt metadata \u2014 see\n    :class:`SessionInterruptedPayload`.",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/SessionInterruptedPayload"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "session.interrupted",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "data"
        ],
        "title": "SessionInterruptedEvent",
        "type": "object"
      },
      "SessionInterruptedPayload": {
        "description": "Inner payload of a :class:`SessionInterruptedEvent`.\n\nBuilt by ``_publish_interrupted`` in\n``omnigent/server/routes/sessions.py``.\n\n:param requested_at: Unix epoch seconds when the interrupt\n    request reached the server, e.g. ``1704067200``.\n:param response_id: Optional active response id for terminal-backed\n    integrations, e.g. ``\"codex_turn_abc123\"``.",
        "properties": {
          "requested_at": {
            "title": "Requested At",
            "type": "integer"
          },
          "response_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Response Id"
          }
        },
        "required": [
          "requested_at"
        ],
        "title": "SessionInterruptedPayload",
        "type": "object"
      },
      "SessionLabelsResponse": {
        "description": "Lightweight response body for ``GET /v1/sessions/{id}/labels``.\n\n:param id: Session identifier, e.g. ``\"conv_abc123\"``.\n:param labels: Session-scoped guardrails labels. Empty dict when\n    no labels have been written.",
        "properties": {
          "id": {
            "title": "Id",
            "type": "string"
          },
          "labels": {
            "additionalProperties": {
              "type": "string"
            },
            "title": "Labels",
            "type": "object"
          }
        },
        "required": [
          "id"
        ],
        "title": "SessionLabelsResponse",
        "type": "object"
      },
      "SessionModelEvent": {
        "description": "Active-model update from a terminal-backed integration.\n\nEmitted after an ``external_model_change`` POST from the\n``omnigent claude`` transcript forwarder when the model is\nswitched inside the Claude Code terminal (a ``/model`` command or\nthe in-TUI picker). Lets the web model picker reflect a TUI-side\nswitch without a reload.\n\n:param type: Always ``\"session.model\"``.\n:param conversation_id: Session identifier, e.g. ``\"conv_abc123\"``.\n:param model: Tier alias the session is now on, e.g. ``\"opus\"`` \u2014\n    Claude Code's version-agnostic alias, matching the picker's\n    vocabulary (not a pinned ``\"claude-opus-4-8\"`` id).\n\nCategory: **transient** (SSE-only). The server also writes\n``model_override`` on the conversation, so on reconnect clients\nrestore the selection from the snapshot's ``model_override`` rather\nthan from a replayed event.",
        "properties": {
          "conversation_id": {
            "title": "Conversation Id",
            "type": "string"
          },
          "model": {
            "title": "Model",
            "type": "string"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "session.model",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "conversation_id",
          "model"
        ],
        "title": "SessionModelEvent",
        "type": "object"
      },
      "SessionPresenceEvent": {
        "description": "The session's viewer list changed \u2014 full state, not a delta.\n\nEmitted on ``GET /v1/sessions/{id}/stream`` whenever a user\njoins, leaves (after the server-side grace window absorbs\nreconnect churn), or flips their idle aggregate, and once to\neach newly-connected stream as a snapshot-on-connect. Every\nevent carries the COMPLETE viewer list so clients replace their\nstate wholesale \u2014 missed events self-heal on the next event or\nreconnect. Viewers are scoped to the session *tree* (the root\nconversation and every sub-agent conversation under it), so a\nuser on a sub-agent page and a user on the root page appear in\neach other's lists. See ``omnigent/server/presence.py`` and\n``designs/UI/PRESENCE.md``.\n\n:param type: Always ``\"session.presence\"``.\n:param conversation_id: The conversation whose stream delivered\n    this event \u2014 the root or a sub-agent conversation, e.g.\n    ``\"conv_abc123\"``. Matches the streamed conversation (not\n    necessarily the tree's root) so clients can guard events by\n    the conversation they are viewing.\n:param viewers: All users currently viewing any conversation in\n    the session tree (including the receiving user \u2014 the web\n    filters self out for display), ordered by join time.",
        "properties": {
          "conversation_id": {
            "title": "Conversation Id",
            "type": "string"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "session.presence",
            "title": "Type",
            "type": "string"
          },
          "viewers": {
            "items": {
              "$ref": "#/components/schemas/PresenceViewer"
            },
            "title": "Viewers",
            "type": "array"
          }
        },
        "required": [
          "type",
          "conversation_id",
          "viewers"
        ],
        "title": "SessionPresenceEvent",
        "type": "object"
      },
      "SessionResourceCreatedEvent": {
        "description": "A session resource was created.\n\nEmitted when a terminal is launched, a file is uploaded, or\nany other resource is materialized under a session. Wire shape\nis FLAT: ``{\"type\": \"session.resource.created\",\n\"resource\": <SessionResourceObject-like dict>}``.\n\n:param type: Always ``\"session.resource.created\"``.\n:param resource: The newly created resource object.",
        "properties": {
          "resource": {
            "additionalProperties": true,
            "title": "Resource",
            "type": "object"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "session.resource.created",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "resource"
        ],
        "title": "SessionResourceCreatedEvent",
        "type": "object"
      },
      "SessionResourceDeletedEvent": {
        "description": "A session resource was deleted.\n\nEmitted when a terminal is closed, a file is deleted, or\nany other resource is removed from a session.\n\n:param type: Always ``\"session.resource.deleted\"``.\n:param resource_id: Opaque id of the deleted resource.\n:param resource_type: Type of the deleted resource,\n    e.g. ``\"terminal\"``, ``\"file\"``.\n:param session_id: Owning session/conversation id.",
        "properties": {
          "resource_id": {
            "title": "Resource Id",
            "type": "string"
          },
          "resource_type": {
            "title": "Resource Type",
            "type": "string"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "session_id": {
            "title": "Session Id",
            "type": "string"
          },
          "type": {
            "const": "session.resource.deleted",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "resource_id",
          "resource_type",
          "session_id"
        ],
        "title": "SessionResourceDeletedEvent",
        "type": "object"
      },
      "SessionResourceObject": {
        "additionalProperties": false,
        "description": "API representation of a session-scoped resource handle.\n\n:param id: Opaque resource identifier, e.g. ``\"default\"`` or\n    ``\"terminal_bash_s1\"``.\n:param object: Fixed resource type, always ``\"session.resource\"``.\n:param type: Resource kind, initially ``\"environment\"``,\n    ``\"terminal\"``, or ``\"file\"``.\n:param session_id: Owning session/conversation id.\n:param name: Human-readable display name. Not required to be\n    globally unique.\n:param metadata: Resource-type-specific metadata.\n:param environment: For terminal resources, the environment id the\n    terminal actually runs in. Omitted for non-terminal resources.",
        "properties": {
          "environment": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Environment"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "metadata": {
            "additionalProperties": true,
            "title": "Metadata",
            "type": "object"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "object": {
            "const": "session.resource",
            "title": "Object",
            "type": "string"
          },
          "session_id": {
            "title": "Session Id",
            "type": "string"
          },
          "type": {
            "enum": [
              "environment",
              "terminal",
              "file"
            ],
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "id",
          "object",
          "type",
          "session_id",
          "name"
        ],
        "title": "SessionResourceObject",
        "type": "object"
      },
      "SessionResourcePaginatedList": {
        "description": "Public paginated list of session resources.",
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/SessionResourceObject"
            },
            "title": "Data",
            "type": "array"
          },
          "first_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "First Id"
          },
          "has_more": {
            "default": false,
            "title": "Has More",
            "type": "boolean"
          },
          "last_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Last Id"
          },
          "object": {
            "const": "list",
            "default": "list",
            "title": "Object",
            "type": "string"
          }
        },
        "title": "SessionResourcePaginatedList",
        "type": "object"
      },
      "SessionSandboxStatusEvent": {
        "description": "Managed-sandbox launch progress for a ``host_type=\"managed\"`` session.\n\nA managed create returns before its sandbox exists; the Omnigent\nserver emits this event as the background launch pipeline advances\nso the Web UI can show live provisioning progress on the session\npage instead of a silent dead chat: sandbox provision \u2192 repository\nclone \u2192 host startup \u2192 runner connect \u2192 ready, or a terminal\nfailure with the reason.\n\n:param type: Always ``\"session.sandbox_status\"``.\n:param conversation_id: Session identifier,\n    e.g. ``\"conv_abc123\"``.\n:param stage: The launch stage just entered, e.g.\n    ``\"provisioning\"`` \u2014 see :class:`SandboxStatus` for the full\n    pipeline order.\n:param error: Failure detail when ``stage == \"failed\"``, e.g.\n    ``\"managed sandbox launch failed: spend limit reached\"``.\n    ``None`` otherwise.\n\nCategory: **transient** (SSE-only). On reconnect, clients seed the\nprogress indicator from the session snapshot's ``sandbox_status``\nfield, which is populated by ``_session_sandbox_status_cache`` at\nsnapshot build time.",
        "properties": {
          "conversation_id": {
            "title": "Conversation Id",
            "type": "string"
          },
          "error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Error"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "stage": {
            "enum": [
              "provisioning",
              "cloning",
              "starting",
              "connecting",
              "ready",
              "failed"
            ],
            "title": "Stage",
            "type": "string"
          },
          "type": {
            "const": "session.sandbox_status",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "conversation_id",
          "stage"
        ],
        "title": "SessionSandboxStatusEvent",
        "type": "object"
      },
      "SessionSkillsEvent": {
        "description": "Signal that a session's runner-owned skills have resolved.\n\nSkills are discovered against the bound runner's filesystem and\nfetched off the session-snapshot hot path: the snapshot kicks a\nsingle background fetch (``_load_runner_skills`` in\n``omnigent/server/routes/sessions.py``) and serves ``[]`` until\nit lands. This event fires the moment that background fetch\npopulates the per-session skills cache, so a connected web client\ncan re-read the snapshot and fill its slash-command menu instead\nof waiting for the next bind.\n\nCarries no payload beyond the conversation id \u2014 it is a \"skills\nare ready, re-read the snapshot\" nudge, mirroring the\ninvalidate-then-refetch shape used by\n:class:`SessionChangedFilesInvalidatedEvent`. The snapshot's\n``skills`` field (now cache-backed) stays the source of truth.\n\n:param type: Always ``\"session.skills\"``.\n:param conversation_id: Session identifier,\n    e.g. ``\"conv_abc123\"``.\n\nCategory: **transient** (SSE-only). On reconnect, clients seed\nthe menu from the session snapshot's ``skills`` field, which is\npopulated by the runner-skills cache at snapshot build time.",
        "properties": {
          "conversation_id": {
            "title": "Conversation Id",
            "type": "string"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "session.skills",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "conversation_id"
        ],
        "title": "SessionSkillsEvent",
        "type": "object"
      },
      "SessionStatusEvent": {
        "description": "Session lifecycle status transition.\n\nEmitted by the runtime / session route handler at every\ntransition between ``running`` / ``waiting`` / ``idle`` /\n``failed``. Wire shape is\nFLAT (not enveloped): ``{\"type\": \"session.status\",\n\"conversation_id\": \"...\", \"status\": \"...\",\n\"sequence_number\": null}``.\n\nThe ``waiting`` value is emitted by the runtime's parent agent\nloop when it parks on the ``async_work_complete`` drain\n(``_drain_async_completions(block_for_one=True)`` in\n``omnigent/runtime/workflow.py``) \u2014 i.e. while the parent\nturn is suspended waiting for background tools or sub-agents\nto complete. Per the session-rearchitecture spec \u00a73\n(\"Event types and direction\"), ``waiting`` is the\nsession-status companion of the spec's ``turn.waiting``\ntransient \u2014 clients should render the session as actively\nblocked-on-async-work, distinct from ``running``. When the\ndrain wakes (a child completed), the runtime emits a follow-up\n``running`` to resume.\n\n:param type: Always ``\"session.status\"``.\n:param conversation_id: The conversation/session identifier\n    whose status changed, e.g. ``\"conv_abc123\"``.\n:param status: New session status. ``\"idle\"`` (no loop\n    running), ``\"running\"`` (loop executing), ``\"waiting\"``\n    (parent turn parked on the async-work drain), or\n    ``\"failed\"`` (terminal failure).\n:param response_id: Optional active response id for terminal-backed\n    integrations, e.g. ``\"codex_turn_abc123\"``. Clients use it to\n    associate coarse session status edges with the assistant bubble\n    they describe. ``None`` for ordinary in-process runtime edges.\n:param error: Machine-readable failure detail, present only\n    when ``status == \"failed\"``. Carries the message the\n    runner attached when a turn died \u2014 most importantly a\n    SETUP-phase failure (spec resolution, spawn-env build)\n    that ends the turn before any ``response.failed`` event\n    is emitted. ``None`` for every non-failed transition.\n    Clients render ``error.message`` as the terminal error\n    line; without it a setup failure shows as a silent end.\n\nCategory: **transient** (SSE-only). Status is rederived on\nreconnect from the cached last-relayed turn lifecycle event\nor by re-querying the runner; not persisted by the runtime.",
        "properties": {
          "conversation_id": {
            "title": "Conversation Id",
            "type": "string"
          },
          "error": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ErrorDetail"
              },
              {
                "type": "null"
              }
            ],
            "default": null
          },
          "response_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Response Id"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "status": {
            "enum": [
              "idle",
              "running",
              "waiting",
              "failed"
            ],
            "title": "Status",
            "type": "string"
          },
          "type": {
            "const": "session.status",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "conversation_id",
          "status"
        ],
        "title": "SessionStatusEvent",
        "type": "object"
      },
      "SessionSwitchAgentRequest": {
        "additionalProperties": false,
        "description": "Request body for ``POST /v1/sessions/{id}/switch-agent``.\n\nRebinds an existing session in place to a different agent/harness,\nkeeping the same session (transcript, comments, files, workspace).\nUnlike fork, no new session is created.\n\n:param agent_id: Built-in agent to switch the session to, e.g.\n    ``\"ag_builtin_codex\"``. Must be a built-in agent (one listed by\n    ``GET /v1/agents``) and different from the session's current\n    agent.",
        "properties": {
          "agent_id": {
            "title": "Agent Id",
            "type": "string"
          }
        },
        "required": [
          "agent_id"
        ],
        "title": "SessionSwitchAgentRequest",
        "type": "object"
      },
      "SessionTerminalActivityEvent": {
        "description": "A terminal's pane produced output (runner-determined activity pulse).\n\nPowers the web \"active\" badge for any terminal without a client PTY\nattach \u2014 the runner's per-terminal pane watcher emits this when the\npane content changes. Transient (a live pulse; not persisted, not in\nthe connect snapshot).\n\n:param type: Always ``\"session.terminal.activity\"``.\n:param session_id: Owning session/conversation id.\n:param terminal_id: Opaque terminal resource id, e.g.\n    ``\"terminal_zsh_s1\"``.",
        "properties": {
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "session_id": {
            "title": "Session Id",
            "type": "string"
          },
          "terminal_id": {
            "title": "Terminal Id",
            "type": "string"
          },
          "type": {
            "const": "session.terminal.activity",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "session_id",
          "terminal_id"
        ],
        "title": "SessionTerminalActivityEvent",
        "type": "object"
      },
      "SessionTerminalPendingEvent": {
        "description": "Terminal spin-up status for a terminal-first session.\n\nTwo sources emit this event:\n\n1. The Omnigent server at ``POST /v1/sessions`` for host-launched\n   terminal-first sessions \u2014 the earliest possible point, before\n   the runner even starts, so the spinner appears immediately on\n   session create rather than after the runner boots.\n2. The Omnigent relay when the runner's ``session.terminal_pending`` frame\n   arrives \u2014 covers non-host-launched sessions (e.g. server-dispatched\n   sub-agents) and carries the authoritative ``pending=False`` clear\n   emitted by the runner's ``finally`` block.\n\nTogether they allow ap-web to show a spinner on the Terminal pill\nwhile the backend boots the terminal instead of a silent greyed-out\nbutton, and to distinguish \"still starting up\" from \"no terminal\"\n(killed or never created).\n\n:param type: Always ``\"session.terminal_pending\"``.\n:param conversation_id: Session identifier,\n    e.g. ``\"conv_abc123\"``.\n:param pending: ``True`` while the terminal is being created;\n    ``False`` once it lands or auto-create fails.\n\nCategory: **transient** (SSE-only). On reconnect, clients seed the\nspinner from the session snapshot's ``terminal_pending`` field,\nwhich is populated by ``_session_terminal_pending_cache`` at\nsnapshot build time.",
        "properties": {
          "conversation_id": {
            "title": "Conversation Id",
            "type": "string"
          },
          "pending": {
            "title": "Pending",
            "type": "boolean"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "type": {
            "const": "session.terminal_pending",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "conversation_id",
          "pending"
        ],
        "title": "SessionTerminalPendingEvent",
        "type": "object"
      },
      "SessionTodosEvent": {
        "description": "Todo-list update from a Claude Code terminal-backed session.\n\nEmitted after an ``external_session_todos`` POST from the\n``omnigent claude`` transcript forwarder, which captures todo\nupdates via ``PostToolUse``/``TodoWrite`` hook events from Claude\nCode and forwards them to the Omnigent server. Lets ap-web render a\nlive todo panel in the right column without polling.\n\n:param type: Always ``\"session.todos\"``.\n:param conversation_id: Session identifier,\n    e.g. ``\"conv_abc123\"``.\n:param todos: Current todo items read from Claude's todo file.\n    Each entry is a raw dict with ``content`` (str),\n    ``status`` (``\"pending\"`` | ``\"in_progress\"`` |\n    ``\"completed\"``), and ``activeForm`` (str, the gerund form)\n    keys, e.g. ``[{\"content\": \"Fix the bug\", \"status\":\n    \"in_progress\", \"activeForm\": \"Fixing the bug\"}]``.\n\nCategory: **transient** (SSE-only). On reconnect, clients seed\nthe panel from the session snapshot's ``todos`` field, which is\npopulated by ``_session_todos_cache`` at snapshot build time.",
        "properties": {
          "conversation_id": {
            "title": "Conversation Id",
            "type": "string"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "todos": {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "title": "Todos",
            "type": "array"
          },
          "type": {
            "const": "session.todos",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "conversation_id",
          "todos"
        ],
        "title": "SessionTodosEvent",
        "type": "object"
      },
      "SessionUsageEvent": {
        "description": "Token-usage update from a terminal-backed integration.\n\nEmitted after an ``external_session_usage`` POST from an\nout-of-AP runtime (e.g. the ``omnigent claude`` transcript\nforwarder). Either field may be absent; clients should leave\ncached values untouched for missing fields.\n\n:param type: Always ``\"session.usage\"``.\n:param conversation_id: Session identifier.\n:param context_tokens: ``input + cache_creation + cache_read``\n    from the latest assistant ``message.usage``. ``None`` on a\n    window-only broadcast.\n:param context_window: Resolved window in tokens (e.g. 200_000\n    normally, 1_000_000 with ``opus[1m]`` / ``sonnet[1m]``).\n    ``None`` on a tokens-only broadcast.\n:param total_cost_usd: Cumulative session spend in USD after this\n    update, e.g. ``0.42`` \u2014 the server-computed total the\n    cost-budget policy gates on. Present **only when the session\n    is priced**; omitted (``None``, stripped by ``exclude_none``)\n    when unpriced or on a broadcast that carries no cost change,\n    so the client keeps its prior value (the snapshot seeds the\n    initial \"\u2014\" for an unpriced session). Once a session is priced\n    the total only grows, so it never reverts to unpriced.\n:param usage_by_model: Per-model breakdown of the same subtree usage\n    after this update, keyed by raw harness model id, e.g.\n    ``{\"claude-sonnet-4-6\": ModelUsage(input_tokens=12000, ...)}``.\n    ``None`` (stripped by ``exclude_none``) on a broadcast that carries\n    no per-model change, so the client keeps its cached map.\n\nCategory: **transient** (SSE-only). On reconnect, clients seed\nthe ring from the session snapshot's ``last_total_tokens`` and\n``context_window``, the cost indicator from ``total_cost_usd``,\nand the per-model token breakdown from ``usage_by_model``.",
        "properties": {
          "context_tokens": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Context Tokens"
          },
          "context_window": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Context Window"
          },
          "conversation_id": {
            "title": "Conversation Id",
            "type": "string"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "total_cost_usd": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Total Cost Usd"
          },
          "type": {
            "const": "session.usage",
            "title": "Type",
            "type": "string"
          },
          "usage_by_model": {
            "anyOf": [
              {
                "additionalProperties": {
                  "$ref": "#/components/schemas/ModelUsage"
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Usage By Model"
          }
        },
        "required": [
          "type",
          "conversation_id"
        ],
        "title": "SessionUsageEvent",
        "type": "object"
      },
      "SkillSummary": {
        "description": "Safe subset of a discovered skill for API exposure.\n\nSurfaces the skill name and one-line description so clients\n(e.g. the web composer's slash-command menu) can list which\nskills the session has access to. The full skill ``content``\nis intentionally omitted \u2014 it's only loaded server-side when\nthe harness invokes the skill, and it can be large.\n\n:param name: Skill identifier as parsed from the SKILL.md\n    frontmatter, e.g. ``\"triage-issues\"``. Lowercase\n    kebab-case.\n:param description: One-line summary from the SKILL.md\n    frontmatter, e.g. ``\"Triage open GitHub issues in the\n    repo.\"``.",
        "properties": {
          "description": {
            "title": "Description",
            "type": "string"
          },
          "name": {
            "title": "Name",
            "type": "string"
          }
        },
        "required": [
          "name",
          "description"
        ],
        "title": "SkillSummary",
        "type": "object"
      },
      "TurnCancelledEvent": {
        "description": "Emitted when a turn is interrupted by the user or system.\n\n:param type: Fixed literal ``\"turn.cancelled\"``.\n:param session_id: Session/conversation identifier,\n    e.g. ``\"conv_abc123\"``.",
        "properties": {
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "session_id": {
            "title": "Session Id",
            "type": "string"
          },
          "type": {
            "const": "turn.cancelled",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "session_id"
        ],
        "title": "TurnCancelledEvent",
        "type": "object"
      },
      "TurnCompletedEvent": {
        "description": "Emitted when a turn finishes successfully with no pending work.\n\n:param type: Fixed literal ``\"turn.completed\"``.\n:param session_id: Session/conversation identifier,\n    e.g. ``\"conv_abc123\"``.",
        "properties": {
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "session_id": {
            "title": "Session Id",
            "type": "string"
          },
          "type": {
            "const": "turn.completed",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "session_id"
        ],
        "title": "TurnCompletedEvent",
        "type": "object"
      },
      "TurnFailedEvent": {
        "description": "Emitted when a turn fails due to an LLM error, timeout, or crash.\n\n:param type: Fixed literal ``\"turn.failed\"``.\n:param session_id: Session/conversation identifier,\n    e.g. ``\"conv_abc123\"``.\n:param error: Error details, e.g.\n    ``{\"message\": \"LLM timeout\", \"type\": \"TimeoutError\"}``.",
        "properties": {
          "error": {
            "additionalProperties": true,
            "title": "Error",
            "type": "object"
          },
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "session_id": {
            "title": "Session Id",
            "type": "string"
          },
          "type": {
            "const": "turn.failed",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "session_id"
        ],
        "title": "TurnFailedEvent",
        "type": "object"
      },
      "TurnStartedEvent": {
        "description": "Emitted when the runner starts a new turn for a session.\n\n:param type: Fixed literal ``\"turn.started\"``.\n:param session_id: Session/conversation identifier,\n    e.g. ``\"conv_abc123\"``.",
        "properties": {
          "sequence_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Sequence Number"
          },
          "session_id": {
            "title": "Session Id",
            "type": "string"
          },
          "type": {
            "const": "turn.started",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "session_id"
        ],
        "title": "TurnStartedEvent",
        "type": "object"
      },
      "UpdateCommentRequest": {
        "description": "Request body for ``PATCH /sessions/{id}/comments/{comment_id}``.\n\n:param status: New status, e.g. ``\"addressed\"``. ``None`` leaves\n    it unchanged.\n:param body: New comment body. ``None`` leaves it unchanged.",
        "properties": {
          "body": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Body"
          },
          "status": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Status"
          }
        },
        "title": "UpdateCommentRequest",
        "type": "object"
      },
      "UpdateDefaultPolicyRequest": {
        "additionalProperties": false,
        "description": "Request body for ``PATCH /v1/policies/{policy_id}``.\n\nAll fields are optional; ``None`` fields are left unchanged.\nUnknown fields (including ``type``, which is immutable) are\nrejected with ``422``.\n\n:param name: New policy name. ``None`` leaves it unchanged.\n:param handler: New handler path or URL. ``None`` leaves it\n    unchanged.\n:param enabled: New enabled flag. ``None`` leaves it\n    unchanged.",
        "properties": {
          "enabled": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Enabled"
          },
          "handler": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Handler"
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Name"
          }
        },
        "title": "UpdateDefaultPolicyRequest",
        "type": "object"
      },
      "UpdateSessionPolicyRequest": {
        "additionalProperties": false,
        "description": "Request body for ``PATCH /v1/sessions/{session_id}/policies/{policy_id}``.\n\nAll fields are optional; ``None`` fields are left unchanged.\nUnknown fields (including ``type``, which is immutable) are\nrejected with ``422``.\n\n:param name: New policy name. ``None`` leaves it unchanged.\n:param handler: New handler path or URL. ``None`` leaves it\n    unchanged.\n:param enabled: New enabled flag. ``None`` leaves it\n    unchanged.",
        "properties": {
          "enabled": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Enabled"
          },
          "handler": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Handler"
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Name"
          }
        },
        "title": "UpdateSessionPolicyRequest",
        "type": "object"
      },
      "UpdateSessionRequest": {
        "additionalProperties": false,
        "description": "Request body for ``PATCH /v1/sessions/{id}``.\n\nThe Alpha runner-state pivot makes this endpoint the mutable\nsession affinity primitive when ``runner_id`` is provided. The\nserver validates that the runner is online, then replaces\n``conversations.runner_id``. Existing session metadata updates\nremain supported for clients that update title, labels, or\nreasoning effort through the sessions API.\n\n:param runner_id: Identifier of a registered runner, e.g.\n    ``\"runner_abc123\"``. ``None`` leaves runner binding\n    unchanged.\n:param title: New title, e.g. ``\"debugging auth flow\"``.\n    ``None`` leaves unchanged.\n:param labels: Guardrails labels to upsert. Merges with existing\n    labels; keys not present are left untouched.\n:param reasoning_effort: Per-session reasoning-effort hint.\n    Accepted metadata values are ``\"none\"``, ``\"minimal\"``,\n    ``\"low\"``, ``\"medium\"``, ``\"high\"``, ``\"xhigh\"``, and\n    ``\"max\"``. Provider-specific support is validated when a\n    turn executes. Clear aliases such as ``\"default\"`` remove\n    the session override. ``None`` leaves unchanged.\n:param model_override: Per-session LLM model override, e.g.\n    ``\"claude-opus-4-7\"``. The value is forwarded as-is to the\n    executor at turn start; the server does not enumerate valid\n    models. Clear aliases such as ``\"default\"``, ``\"off\"``, or\n    ``\"reset\"`` remove the override (matching the REPL's\n    ``/model`` semantics). ``None`` leaves unchanged.\n:param cost_control_mode_override: Per-session cost-control\n    switch: ``\"on\"`` activates the spec's configured cost-control\n    mode, ``\"off\"`` disables cost control for this session.\n    Explicit JSON ``null`` clears the override back to the spec\n    default; omitting the field leaves it unchanged (``\"off\"`` is\n    a real value here, so the field's *presence* \u2014 not a clear\n    alias \u2014 is the clear signal, unlike ``model_override``).\n:param external_session_id: Runtime-native session id captured\n    by a wrapper bridge (e.g. Claude Code's session uuid for\n    ``omnigent claude`` sessions). Idempotent on same-value\n    writes; the server rejects attempts to overwrite an\n    already-set different value with ``invalid_input`` to\n    surface programmer errors. ``None`` leaves unchanged.\n:param terminal_launch_args: Per-session native-terminal\n    pass-through args, e.g. ``[\"--dangerously-skip-permissions\"]``.\n    A list (including ``[]``) replaces the stored value wholesale\n    \u2014 resume is last-write-wins, never an append. Bounds (count /\n    length) are validated server-side. ``None`` leaves unchanged.\n:param silent: When ``True``, persist metadata changes but skip\n    the runner-side side effects \u2014 specifically the\n    claude-native ``/effort`` and ``/model`` slash-command\n    forwards into the tmux pane. Used by automatic bind-time\n    handoffs (ap-web's sticky-pref apply on session switch, the\n    REPL's pre-create ``/model`` snapshot) where injecting a\n    visible slash command into a freshly-spawned pane would\n    render as an unexpected \"Command model X\" item before the\n    user has sent anything. Default ``False`` preserves the\n    user-driven picker / ``/model`` behaviour where the live\n    forward IS the desired feedback.\n:param archived: New archived state. ``True`` archives (hides the\n    session from the default sidebar listing), ``False`` unarchives,\n    ``None`` leaves unchanged. Owner-only (unlike ``title``, which\n    needs only edit access).",
        "properties": {
          "archived": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Archived"
          },
          "cost_control_mode_override": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Cost Control Mode Override"
          },
          "external_session_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "External Session Id"
          },
          "labels": {
            "anyOf": [
              {
                "additionalProperties": {
                  "type": "string"
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Labels"
          },
          "model_override": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Model Override"
          },
          "reasoning_effort": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Reasoning Effort"
          },
          "runner_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Runner Id"
          },
          "silent": {
            "default": false,
            "title": "Silent",
            "type": "boolean"
          },
          "terminal_launch_args": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Terminal Launch Args"
          },
          "title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Title"
          }
        },
        "title": "UpdateSessionRequest",
        "type": "object"
      },
      "Usage": {
        "description": "Token usage statistics for a response.\n\n:param input_tokens: Number of input (prompt) tokens consumed.\n:param output_tokens: Number of output (completion) tokens\n    generated.\n:param output_tokens_details: Breakdown of output token usage\n    (e.g. reasoning tokens).\n:param total_tokens: Sum of input and output tokens across all\n    LLM sub-calls for this turn (billing total).\n:param context_tokens: Context-fill estimate for the next turn \u2014\n    set only by executors that make multiple LLM sub-calls per\n    turn (e.g. ``openai-agents``).  For single-call executors\n    this is absent and ``total_tokens`` serves the same purpose.\n    The toolbar context ring and ``/context`` command use this\n    field when present, falling back to ``total_tokens``.\n:param cache_read_input_tokens: Prompt tokens served from a\n    provider prompt cache (cache hit), billed at a reduced rate.\n    Reported by Anthropic-style providers as a count *separate*\n    from ``input_tokens`` (which carries only the non-cached\n    portion); ``0`` when the provider does not break out cache\n    usage. Consumed by the cache-aware server-side cost path.\n:param cache_creation_input_tokens: Prompt tokens written to the\n    provider prompt cache (cache creation), billed at a premium\n    rate. Like ``cache_read_input_tokens``, this is separate from\n    ``input_tokens``; ``0`` when not reported.\n:param model: The LLM model the harness actually used for this\n    turn, e.g. ``\"claude-opus-4-8\"`` or ``\"databricks-gpt-5-5\"``.\n    Reported by relay executors so the server-side cost path can\n    price the turn even when the agent spec pins no ``llm.model``\n    (e.g. supervisors that delegate / use the harness default).\n    ``None`` when the executor doesn't report it; the cost path\n    then falls back to the session override / spec model.",
        "properties": {
          "cache_creation_input_tokens": {
            "default": 0,
            "title": "Cache Creation Input Tokens",
            "type": "integer"
          },
          "cache_read_input_tokens": {
            "default": 0,
            "title": "Cache Read Input Tokens",
            "type": "integer"
          },
          "context_tokens": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Context Tokens"
          },
          "input_tokens": {
            "default": 0,
            "title": "Input Tokens",
            "type": "integer"
          },
          "model": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "title": "Model"
          },
          "output_tokens": {
            "default": 0,
            "title": "Output Tokens",
            "type": "integer"
          },
          "output_tokens_details": {
            "$ref": "#/components/schemas/UsageDetails"
          },
          "total_tokens": {
            "default": 0,
            "title": "Total Tokens",
            "type": "integer"
          }
        },
        "title": "Usage",
        "type": "object"
      },
      "UsageDetails": {
        "description": "Breakdown of output token usage.\n\n:param reasoning_tokens: Number of tokens consumed by\n    chain-of-thought reasoning.",
        "properties": {
          "reasoning_tokens": {
            "default": 0,
            "title": "Reasoning Tokens",
            "type": "integer"
          }
        },
        "title": "UsageDetails",
        "type": "object"
      },
      "ValidationError": {
        "properties": {
          "ctx": {
            "title": "Context",
            "type": "object"
          },
          "input": {
            "title": "Input"
          },
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "title": "Location",
            "type": "array"
          },
          "msg": {
            "title": "Message",
            "type": "string"
          },
          "type": {
            "title": "Error Type",
            "type": "string"
          }
        },
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError",
        "type": "object"
      }
    }
  },
  "info": {
    "title": "Omnigent Server",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/version": {
      "get": {
        "description": "Return the installed omnigent package version.\n\nUsed by the web UI to include version info in bug reports.\n\n:returns: ``{\"version\": \"<semver string>\"}``,\n    e.g. ``{\"version\": \"0.1.0\"}``.",
        "operationId": "version_api_version_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "title": "Response Version Api Version Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Version"
      }
    },
    "/health": {
      "get": {
        "description": "Liveness check with optional session-scoped runner status.\n\nWithout session params, returns ``{\"status\": \"ok\"}`` (bare\nliveness). With ``session_id``, adds a single ``session``\nobject. With ``session_ids`` (comma-separated), adds a\n``sessions`` dict keyed by id \u2014 used by the sidebar to\nbatch-check all visible sessions in one request. The batch\npath runs a single SQL ``IN`` query, not N per-id round-trips.\n\nEach per-session object carries both ``runner_online`` (strict\nrunner reachability) and ``host_online`` (host tunnel live, or\n``None`` when the session has no host binding) \u2014 see\n:class:`~omnigent.server.routes.sessions.SessionLiveness`.\n\n:param session_id: Optional single session id, e.g.\n    ``\"conv_abc123\"``.\n:param session_ids: Optional comma-separated session ids\n    for batch lookup, e.g.\n    ``\"conv_abc,conv_def,conv_ghi\"``.\n:returns: ``{\"status\": \"ok\"}`` with optional ``session``\n    and/or ``sessions`` fields. Each session object has shape\n    ``{\"runner_online\": bool, \"host_online\": bool | None}``\n    (the single ``session`` object also includes its ``id``).",
        "operationId": "health_health_get",
        "parameters": [
          {
            "in": "query",
            "name": "session_id",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Session Id"
            }
          },
          {
            "in": "query",
            "name": "session_ids",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Session Ids"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Health Health Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Health"
      }
    },
    "/v1/agents": {
      "get": {
        "description": "List built-in agents with cursor-based pagination.\n\nReturns only built-in agents \u2014 ``agent_store.list()`` filters\n``session_id IS NULL`` \u2014 so session-scoped agents never appear.\n\n:param request: The incoming FastAPI request (for auth).\n:param limit: Maximum number of agents to return (1-1000).\n:param after: Cursor \u2014 return agents after this id.\n:param before: Cursor \u2014 return agents before this id.\n:param order: Sort order, ``\"asc\"`` or ``\"desc\"``.\n:returns: A :class:`PaginatedList` of built-in agents.",
        "operationId": "list_builtin_agents_v1_agents_get",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 20,
              "maximum": 1000,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "After"
            }
          },
          {
            "in": "query",
            "name": "before",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Before"
            }
          },
          {
            "in": "query",
            "name": "order",
            "required": false,
            "schema": {
              "default": "desc",
              "pattern": "^(asc|desc)$",
              "title": "Order",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedList"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "List Builtin Agents",
        "tags": [
          "agents"
        ]
      }
    },
    "/v1/hosts": {
      "get": {
        "description": "List all hosts owned by the authenticated user.\n\nReturns both online and offline hosts, with live runner\ninformation for online hosts.\n\n:param request: The incoming request (for auth).\n:returns: ``{\"hosts\": [...]}`` with host details.",
        "operationId": "list_hosts_v1_hosts_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "items": {
                      "additionalProperties": true,
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "title": "Response List Hosts V1 Hosts Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "List Hosts",
        "tags": [
          "hosts"
        ]
      }
    },
    "/v1/hosts/{host_id}": {
      "get": {
        "description": "Get details for a single host.\n\n:param request: The incoming request (for auth).\n:param host_id: Host identifier, e.g.\n    ``\"host_a1b2c3d4...\"``.\n:returns: Host details dict.\n:raises HTTPException: 404 if the host does not exist.",
        "operationId": "get_host_v1_hosts__host_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "host_id",
            "required": true,
            "schema": {
              "title": "Host Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Get Host V1 Hosts  Host Id  Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get Host",
        "tags": [
          "hosts"
        ]
      }
    },
    "/v1/hosts/{host_id}/filesystem": {
      "get": {
        "description": "List the contents of the host daemon's home directory.\n\nEmpty trailing path \u2192 forward ``~`` to the host (the host\nexpands against its own process owner). Used by the\nWeb UI's directory picker to show the \"root\" view.\n\n:param request: FastAPI request (for auth).\n:param host_id: Host identifier, e.g.\n    ``\"host_a1b2c3d4...\"``.\n:param limit: Max entries per page.\n:param after: Optional forward pagination cursor (entry\n    path), e.g. ``\"/Users/corey/projects/m\"``.\n:param before: Optional backward pagination cursor.\n:returns: ``{\"object\": \"list\", \"data\": [...], \"has_more\": bool}``\n    mirroring the existing session-scoped filesystem\n    endpoint shape.\n:raises HTTPException: 404 if host not found, 403 if not\n    owned by caller, 409 if host is offline, 504 on host\n    timeout, 502 on host I/O failure.",
        "operationId": "list_host_filesystem_root_v1_hosts__host_id__filesystem_get",
        "parameters": [
          {
            "in": "path",
            "name": "host_id",
            "required": true,
            "schema": {
              "title": "Host Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 20,
              "maximum": 1000,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "After"
            }
          },
          {
            "in": "query",
            "name": "before",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Before"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response List Host Filesystem Root V1 Hosts  Host Id  Filesystem Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "List Host Filesystem Root",
        "tags": [
          "hosts"
        ]
      }
    },
    "/v1/hosts/{host_id}/filesystem/{path}": {
      "get": {
        "description": "List the contents of a directory on a host.\n\nUsed by the Web UI's directory picker (and stat-style\nexistence checks) to render the host's filesystem before\nany runner exists. Owner-scoped: only the host owner can\nbrowse. NOT scoped to a session \u2014 this endpoint exposes\nthe entire host filesystem to the authenticated host owner\nper ``designs/SESSION_WORKSPACE_SELECTION.md`` \"Security\nsurface\".\n\n:param request: FastAPI request (for auth).\n:param host_id: Host identifier.\n:param path: Absolute path on the host (e.g.\n    ``\"/Users/corey/universe\"``) OR a tilde-prefixed\n    path (``\"~/foo\"``). The host expands ``~`` itself.\n    FastAPI's ``:path`` converter strips the leading\n    ``/`` from the URL, so we re-add it for absolute paths.\n:param limit: Max entries per page.\n:param after: Optional forward pagination cursor.\n:param before: Optional backward pagination cursor.\n:returns: ``{\"object\": \"list\", \"data\": [...], \"has_more\": bool}``.\n:raises HTTPException: 404 (host or path missing), 403\n    (not owner), 409 (offline), 400 (path validation),\n    504 (timeout), 502 (host I/O).",
        "operationId": "list_host_filesystem_v1_hosts__host_id__filesystem__path__get",
        "parameters": [
          {
            "in": "path",
            "name": "host_id",
            "required": true,
            "schema": {
              "title": "Host Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "path",
            "required": true,
            "schema": {
              "title": "Path",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 20,
              "maximum": 1000,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "After"
            }
          },
          {
            "in": "query",
            "name": "before",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Before"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response List Host Filesystem V1 Hosts  Host Id  Filesystem  Path  Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "List Host Filesystem",
        "tags": [
          "hosts"
        ]
      }
    },
    "/v1/hosts/{host_id}/runners": {
      "post": {
        "description": "Launch a runner on a host for a session.\n\nGenerates a binding token, writes the expected runner_id\nto the session row, sends the launch command to the host,\nand waits for the host's acknowledgement.\n\n:param request: The incoming request (for auth).\n:param host_id: Target host, e.g. ``\"host_a1b2c3d4...\"``.\n:param body: Launch request with ``session_id`` and\n    ``workspace``.\n:returns: ``{\"runner_id\": ..., \"status\": \"launching\"}``.\n:raises HTTPException: 404 if host not found, 409 if host\n    offline, 403 if caller doesn't own the host, 400 if\n    session already has a runner.",
        "operationId": "launch_runner_v1_hosts__host_id__runners_post",
        "parameters": [
          {
            "in": "path",
            "name": "host_id",
            "required": true,
            "schema": {
              "title": "Host Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LaunchRunnerRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Launch Runner V1 Hosts  Host Id  Runners Post",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Launch Runner",
        "tags": [
          "hosts"
        ]
      }
    },
    "/v1/info": {
      "get": {
        "description": "Runtime capabilities probe for the SPA + CLI.\n\nReturned at app boot by the frontend (and by ``omnigent\nlogin`` when it needs to choose between flows). Drives\nconditional route registration and chrome on the SPA side\n\u2014 when ``accounts_enabled`` is false, the SPA never\nregisters ``/login``, ``/register``, ``/members`` and\nnever renders the AccountMenu, so the bundle behaves\nidentically to a pre-PR-2008 build for header / OIDC\ndeploys (in particular, the internal hosted product that\nsyncs from this repo).\n\nAuthentication: this endpoint is intentionally UNAUTHED\nso the SPA can probe it before holding a session cookie.\nIt exposes no sensitive state \u2014 only the active auth\nsource, the login URL, whether first-run admin setup is\nstill pending (``needs_setup``), coarse capability\nbooleans (``databricks_features``,\n``managed_sandboxes_enabled``), and the short sandbox\nprovider name (``sandbox_provider``) the web UI labels the\nnew-session sandbox option with.",
        "operationId": "info_v1_info_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "anyOf": [
                      {
                        "type": "boolean"
                      },
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "title": "Response Info V1 Info Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Info"
      }
    },
    "/v1/me": {
      "get": {
        "description": "Return the current user's identity.\n\nReads the user from the auth provider (same logic that\nsession routes use). The frontend calls this on load to\ndiscover who it is.\n\nWhen OIDC is active and the user is unauthenticated,\nreturns 401 with a ``login_url`` so the frontend knows\nwhere to redirect.\n\n:param request: The incoming FastAPI request.\n:returns: ``{\"user_id\": \"alice@example.com\"}``,\n    ``{\"user_id\": null}`` if unauthenticated in header\n    mode, or 401 with ``login_url`` in OIDC mode.",
        "operationId": "me_v1_me_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Me"
      }
    },
    "/v1/policies": {
      "get": {
        "description": "List all default policies.\n\nRequires authentication in multi-user mode.\n\n:param request: The incoming request, used to extract the\n    user identity.\n:returns: ``{\"object\": \"list\", \"data\": [...]}``.\n:raises OmnigentError: 401 if unauthenticated in\n    multi-user mode.",
        "operationId": "list_policies_v1_policies_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response List Policies V1 Policies Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "List Policies",
        "tags": [
          "default_policies"
        ]
      },
      "post": {
        "description": "Create a new default policy.\n\nRequires admin privileges in multi-user mode.\n\n:param request: The incoming request, used to extract the\n    user identity.\n:param body: Policy payload including name, type, and\n    handler.\n:returns: The created policy as a serialized dict.\n:raises OmnigentError: 401/403 if the user lacks admin\n    privileges, or 409 if a policy with the same name\n    already exists.",
        "operationId": "create_policy_v1_policies_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDefaultPolicyRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Create Policy V1 Policies Post",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Create Policy",
        "tags": [
          "default_policies"
        ]
      }
    },
    "/v1/policies/{policy_id}": {
      "delete": {
        "description": "Delete a default policy.\n\nIdempotent \u2014 deleting a missing policy returns 204.\nRequires admin privileges.\n\n:param request: The incoming request, used to extract the\n    user identity.\n:param policy_id: The policy to delete, e.g.\n    ``\"pol_abc123\"``.\n:returns: ``{\"deleted\": true}``.\n:raises OmnigentError: 401/403 if the user lacks admin\n    privileges.",
        "operationId": "delete_policy_v1_policies__policy_id__delete",
        "parameters": [
          {
            "in": "path",
            "name": "policy_id",
            "required": true,
            "schema": {
              "title": "Policy Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Delete Policy V1 Policies  Policy Id  Delete",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Delete Policy",
        "tags": [
          "default_policies"
        ]
      },
      "get": {
        "description": "Get a single default policy.\n\nRequires authentication in multi-user mode.\n\n:param request: The incoming request, used to extract the\n    user identity.\n:param policy_id: The policy to retrieve, e.g.\n    ``\"pol_abc123\"``.\n:returns: The policy as a serialized dict.\n:raises OmnigentError: 401 if unauthenticated, or\n    404 if the policy is not found.",
        "operationId": "get_policy_v1_policies__policy_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "policy_id",
            "required": true,
            "schema": {
              "title": "Policy Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Get Policy V1 Policies  Policy Id  Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get Policy",
        "tags": [
          "default_policies"
        ]
      },
      "patch": {
        "description": "Update a default policy's mutable fields.\n\n``type`` is immutable \u2014 the caller must delete and\nre-create to change it. Requires admin privileges.\n\n:param request: The incoming request, used to extract the\n    user identity.\n:param policy_id: The policy to update, e.g.\n    ``\"pol_abc123\"``.\n:param body: Fields to update; ``None`` fields are left\n    unchanged.\n:returns: The updated policy as a serialized dict.\n:raises OmnigentError: 401/403 if the user lacks admin\n    privileges, or 404 if the policy is not found.",
        "operationId": "update_policy_v1_policies__policy_id__patch",
        "parameters": [
          {
            "in": "path",
            "name": "policy_id",
            "required": true,
            "schema": {
              "title": "Policy Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateDefaultPolicyRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Update Policy V1 Policies  Policy Id  Patch",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Update Policy",
        "tags": [
          "default_policies"
        ]
      }
    },
    "/v1/policy-registry": {
      "get": {
        "description": "List all registered policy functions.\n\nReturns the full catalog of built-in policy callables\nwith their handler paths, descriptions, and parameter\nschemas.\n\n:param request: The incoming request, used to extract\n    the user identity for authentication.\n:returns: ``{\"object\": \"list\", \"data\": [...]}``.",
        "operationId": "list_registry_v1_policy_registry_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response List Registry V1 Policy Registry Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "List Registry",
        "tags": [
          "policy_registry"
        ]
      }
    },
    "/v1/runners": {
      "get": {
        "description": "Return currently online runners owned by the requesting user.\n\nWhen auth is active, only runners whose tunnel was\nestablished by the same user are returned. Without auth,\nall online runners are listed (single-user / dev mode).\n\n:param request: The incoming FastAPI request (for auth).\n:returns: A ``{\"data\": [...]}`` list with runner ids and\n    advertised harnesses.",
        "operationId": "list_runners_v1_runners_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "items": {
                      "additionalProperties": true,
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "title": "Response List Runners V1 Runners Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "List Runners",
        "tags": [
          "runners"
        ]
      }
    },
    "/v1/runners/{runner_id}/status": {
      "get": {
        "description": "Return whether a runner currently has an open tunnel.\n\nWhen auth is active, a runner owned by a different user\nappears as offline to prevent enumeration.\n\n:param request: The incoming FastAPI request (for auth).\n:param runner_id: Stable runner id, e.g.\n    ``\"runner_0123456789abcdef\"``.\n:returns: A JSON object with ``runner_id`` and ``online``.",
        "operationId": "runner_status_v1_runners__runner_id__status_get",
        "parameters": [
          {
            "in": "path",
            "name": "runner_id",
            "required": true,
            "schema": {
              "title": "Runner Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "boolean"
                      }
                    ]
                  },
                  "title": "Response Runner Status V1 Runners  Runner Id  Status Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Runner Status",
        "tags": [
          "runners"
        ]
      }
    },
    "/v1/sessions": {
      "get": {
        "description": "List sessions with cursor-based pagination.\n\nSessions are conversations with a non-``None`` ``agent_id``\n\u2014 i.e. those created via ``POST /v1/sessions``.\nConversations without an agent binding are excluded.\n\n:param limit: Maximum number of sessions to return\n    (1-1000, default 20).\n:param after: Cursor \u2014 return sessions after this\n    session ID in sort order, e.g. ``\"conv_abc123\"``.\n:param before: Cursor \u2014 return sessions before this\n    session ID.\n:param agent_id: When set, only return sessions bound\n    to this agent, e.g. ``\"ag_abc123\"``. ``None``\n    returns sessions across all agents.\n:param agent_name: When set, only return sessions whose\n    bound agent row has this name. This intentionally\n    includes session-scoped agents that share a name but\n    have distinct bundles. ``None`` disables the filter.\n:param order: Sort direction, ``\"desc\"`` (newest-first)\n    or ``\"asc\"`` (oldest-first).\n:param sort_by: Column to sort on, ``\"created_at\"`` or\n    ``\"updated_at\"``.\n:param search_query: Case-insensitive substring filter on\n    the session title or conversation content. ``None``\n    or empty string disables the filter. A session\n    matches if its title contains the query or any of\n    its conversation items' text does. Powers the\n    sidebar's session search.\n:param include_archived: When ``False`` (default), archived\n    sessions are omitted. When ``True``, archived sessions\n    are returned alongside active ones (the sidebar groups\n    them into an \"Archived\" section). Powers the sidebar's\n    \"Show archived\" toggle.\n:param kind: Conversation kind to return. ``\"default\"``\n    (the default) returns only top-level user-initiated\n    sessions \u2014 the sidebar's view. ``\"sub_agent\"`` returns\n    only sub-agent child sessions. ``\"any\"`` returns both;\n    this lets the new-session agent picker discover agents\n    that are only bound to sub-agent sessions (e.g. ones\n    uploaded via ``sys_session_create``).\n:returns: A :class:`PaginatedList` of\n    :class:`SessionListItem`.",
        "operationId": "list_sessions_v1_sessions_get",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 20,
              "maximum": 1000,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "After"
            }
          },
          {
            "in": "query",
            "name": "before",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Before"
            }
          },
          {
            "in": "query",
            "name": "agent_id",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Agent Id"
            }
          },
          {
            "in": "query",
            "name": "agent_name",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Agent Name"
            }
          },
          {
            "in": "query",
            "name": "order",
            "required": false,
            "schema": {
              "default": "desc",
              "pattern": "^(asc|desc)$",
              "title": "Order",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "sort_by",
            "required": false,
            "schema": {
              "default": "created_at",
              "pattern": "^(created_at|updated_at)$",
              "title": "Sort By",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "search_query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Search Query"
            }
          },
          {
            "in": "query",
            "name": "include_archived",
            "required": false,
            "schema": {
              "default": false,
              "title": "Include Archived",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "kind",
            "required": false,
            "schema": {
              "default": "default",
              "pattern": "^(default|sub_agent|any)$",
              "title": "Kind",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "List Sessions",
        "tags": [
          "sessions"
        ]
      },
      "post": {
        "description": "Create a session.\n\n``application/json`` preserves the existing contract: bind to\nan already-registered agent by ``agent_id`` and return the full\nsession snapshot. ``multipart/form-data`` is the Alpha\nrunner-state create path: the request carries a JSON\n``metadata`` part and a ``bundle`` file part, then the server\nstores the bundle and creates the conversation row plus\nsession-scoped agent row in one database transaction.\n\n:param request: FastAPI request containing either JSON or\n    multipart form data.\n:returns: :class:`SessionResponse` for JSON create, or\n    :class:`CreatedSessionResponse` for bundled create.\n:raises OmnigentError: If metadata, bundle, or agent lookup\n    validation fails, artifact storage is unavailable, or\n    database creation fails.",
        "operationId": "create_session_v1_sessions_post",
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          }
        },
        "summary": "Create Session",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}": {
      "delete": {
        "description": "Delete a session and all associated resources.\n\nRequires owner-level access. Tears down tasks, runner-side\nresources (environments, terminals), session files, and the\nconversation row.\n\n:param request: The incoming FastAPI request (for auth).\n:param session_id: Session/conversation identifier,\n    e.g. ``\"conv_abc123\"``.\n:param delete_branch: Opt-in git cleanup, as a query param\n    (``?delete_branch=true``). When ``True`` and the session\n    has a server-created worktree (``git_branch`` set), the\n    host removes the worktree directory and deletes its branch\n    (``git worktree remove --force`` then ``git branch -D``).\n    Ignored for sessions with no worktree. Best-effort: a\n    cleanup failure does not block the delete. Defaults to\n    ``False`` (worktree and branch left untouched). See\n    designs/SESSION_GIT_WORKTREE.md.\n:returns: A :class:`ConversationDeleted` confirmation.\n:raises OmnigentError: 404 if no session or no access,\n    403 if insufficient permissions.",
        "operationId": "delete_session_v1_sessions__session_id__delete",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "delete_branch",
            "required": false,
            "schema": {
              "default": false,
              "title": "Delete Branch",
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Delete Session",
        "tags": [
          "sessions"
        ]
      },
      "get": {
        "description": "Return a session snapshot: identity, status, and committed\nitems.\n\n:param request: The incoming FastAPI request (for auth).\n:param response: The FastAPI response (for cache headers).\n:param session_id: Session/conversation identifier,\n    e.g. ``\"conv_abc123\"``.\n:param include_items: When ``False``, skip the committed-items\n    read and return ``items=[]``. The web chat surface passes\n    ``False`` because it hydrates the transcript via the\n    paginated ``GET /sessions/{id}/items`` endpoint in parallel\n    and never reads the snapshot's copy; the items read is the\n    single most expensive step of the snapshot build.\n:param include_liveness: When ``False``, skip the runner/host\n    liveness lookup and return ``runner_online``/``host_online``\n    as ``None``. The web chat surface passes ``False`` because\n    it sources liveness from the ``/health`` poll and the WS\n    stream, not the snapshot.\n:returns: The matching :class:`SessionResponse`.\n:raises OmnigentError: 404 if no session exists.",
        "operationId": "get_session_v1_sessions__session_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "include_items",
            "required": false,
            "schema": {
              "default": true,
              "title": "Include Items",
              "type": "boolean"
            }
          },
          {
            "in": "query",
            "name": "include_liveness",
            "required": false,
            "schema": {
              "default": true,
              "title": "Include Liveness",
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get Session",
        "tags": [
          "sessions"
        ]
      },
      "patch": {
        "description": "Update a session's mutable fields. When ``runner_id`` is\nprovided, this is the mutable affinity primitive for the Alpha\nrunner-state pivot: create-bind, resume-bind, and recover-bind\nall send the currently registered runner id, and the server\natomically replaces ``conversations.runner_id`` with that\nvalue using last-write-wins semantics. Title, labels, and\nreasoning-effort updates remain supported for existing\nsessions clients.\n\n:param request: The incoming FastAPI request (for auth).\n:param session_id: Session/conversation identifier,\n    e.g. ``\"conv_abc123\"``.\n:param body: The validated :class:`UpdateSessionRequest`.\n:returns: The updated :class:`SessionResponse` snapshot.\n:raises OmnigentError: 400 if the runner is not\n    registered; 404 if no session exists.",
        "operationId": "update_session_v1_sessions__session_id__patch",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateSessionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Update Session",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/agent": {
      "get": {
        "description": "Return the :class:`AgentObject` for the session's bound agent.\n\nReplaces the standalone ``GET /api/agents/{id}`` endpoint by\nresolving the agent through the session's ``agent_id`` foreign\nkey. The caller only needs to know the session id.\n\n:param request: The incoming FastAPI request.\n:param session_id: Session identifier, e.g.\n    ``\"conv_abc123\"``.\n:returns: The bound agent's :class:`AgentObject`.\n:raises OmnigentError: If the session or agent is not found.",
        "operationId": "get_session_agent_v1_sessions__session_id__agent_get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentObject"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get Session Agent",
        "tags": [
          "sessions"
        ]
      },
      "put": {
        "description": "Replace the session's agent bundle with a new upload.\n\nValidates the new bundle, checks that the spec name matches\nthe existing agent, stores the bundle under a\ncontent-addressed key, updates the agent row, and warm-swaps\nthe cache. Idempotent when the bundle content is unchanged.\n\n:param request: The incoming FastAPI request.\n:param session_id: Session identifier, e.g.\n    ``\"conv_abc123\"``.\n:param bundle: Uploaded ``.tar.gz`` agent bundle file.\n:returns: The updated :class:`AgentObject`.\n:raises OmnigentError: If the session or agent is not found,\n    the bundle is invalid, or the spec name doesn't match.",
        "operationId": "update_session_agent_v1_sessions__session_id__agent_put",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_update_session_agent_v1_sessions__session_id__agent_put"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentObject"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Update Session Agent",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/agent/contents": {
      "get": {
        "description": "Download the raw ``.tar.gz`` agent bundle for the session's\nbound agent.\n\nReplaces ``GET /api/agents/{id}/contents``. Runners call this\non cache miss to fetch the spec + bundled files.\n\n:param request: The incoming FastAPI request.\n:param session_id: Session identifier, e.g.\n    ``\"conv_abc123\"``.\n:returns: Raw bundle bytes as ``application/gzip``.\n:raises OmnigentError: If the session, agent, or bundle is\n    not found.",
        "operationId": "get_session_agent_contents_v1_sessions__session_id__agent_contents_get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/gzip": {}
            },
            "description": "Successful Response"
          },
          "404": {
            "description": "Session or agent not found"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get Session Agent Contents",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/child_sessions": {
      "get": {
        "description": "List sub-agent (child) sessions under a parent session.\n\nReturns a page of :class:`ChildSessionSummary` objects\nderived from child conversations (``kind=\"sub_agent\"``,\n``parent_conversation_id=session_id``) plus each child's\nlatest task. Powers the web / REPL debug surfaces' \"child\nsessions\" panel without parsing parent\n``function_call_output`` JSON handles. Pagination contract\nmatches :func:`list_session_items` so existing client code\ncan reuse the same cursor logic.\n\n:param request: Inbound HTTP request; carries the caller\n    identity used to authorize READ on the parent session.\n:param session_id: Parent session/conversation identifier,\n    e.g. ``\"conv_abc123\"``.\n:param limit: Maximum number of children to return\n    (1-1000, default 20 \u2014 sub-agent fan-out is typically\n    sparse compared to conversation items).\n:param after: Cursor \u2014 return children whose id appears\n    after this one in sort order,\n    e.g. ``\"conv_child123\"``.\n:param before: Cursor \u2014 return children before this one.\n:param order: Sort direction, ``\"desc\"`` (newest-first,\n    default) or ``\"asc\"``. Sort column is ``created_at``.\n:returns: A :class:`PaginatedList` of\n    :class:`ChildSessionSummary` objects.\n:raises OmnigentError: 403 if the caller lacks READ on\n    ``session_id``; 404 if no session exists there.",
        "operationId": "list_child_sessions_v1_sessions__session_id__child_sessions_get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 20,
              "maximum": 1000,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "After"
            }
          },
          {
            "in": "query",
            "name": "before",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Before"
            }
          },
          {
            "in": "query",
            "name": "order",
            "required": false,
            "schema": {
              "default": "desc",
              "pattern": "^(asc|desc)$",
              "title": "Order",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "List Child Sessions",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/comments": {
      "get": {
        "description": "List comments for a session, optionally filtered by file.\n\nRequires ``LEVEL_READ`` on the session in multi-user mode.\n\n:param request: The incoming request, used to extract the user identity.\n:param session_id: The session to query, e.g. ``\"conv_abc123\"``.\n:param path: When provided, only return comments for this file,\n    e.g. ``\"src/App.tsx\"``.\n:returns: List of serialized comment dicts.\n:raises OmnigentError: 401/403/404 if the user lacks read permission.",
        "operationId": "list_comments_v1_sessions__session_id__comments_get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "path",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Path"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "additionalProperties": true,
                    "type": "object"
                  },
                  "title": "Response List Comments V1 Sessions  Session Id  Comments Get",
                  "type": "array"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "List Comments",
        "tags": [
          "comments"
        ]
      },
      "post": {
        "description": "Create a new review comment.\n\nRequires ``LEVEL_EDIT`` on the session in multi-user mode.\n\n:param request: The incoming request, used to extract the user identity.\n:param session_id: The owning session, e.g. ``\"conv_abc123\"``.\n:param body: Comment payload including path, body text, and the\n    two range fields (start_index, end_index).\n:returns: The created comment as a serialized dict.\n:raises OmnigentError: 401/403/404 if the user lacks edit permission.",
        "operationId": "add_comment_v1_sessions__session_id__comments_post",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddCommentRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Add Comment V1 Sessions  Session Id  Comments Post",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Add Comment",
        "tags": [
          "comments"
        ]
      }
    },
    "/v1/sessions/{session_id}/comments/send": {
      "post": {
        "description": "Mark comments as addressed and format them into an agent message.\n\nFetches each requested comment, marks it ``addressed``,\nand formats the full set into a grouped, sorted message string\nsuitable for pasting into the chat composer.\n\nRequires ``LEVEL_EDIT`` on the session in multi-user mode because\nit transitions comment status from ``draft`` to ``addressed``.\n\n:param request: The incoming request, used to extract the user identity.\n:param session_id: The owning session, e.g. ``\"conv_abc123\"``.\n:param body: List of comment IDs to send, with an optional\n    custom instruction prefix.\n:returns: ``{\"formatted_message\": str, \"sent_comment_ids\": list[str]}``.\n:raises OmnigentError: 401/403/404 if the user lacks edit permission,\n    or 404 if any requested comment is not found or does not belong to\n    this session.",
        "operationId": "send_to_agent_v1_sessions__session_id__comments_send_post",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SendCommentsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Send To Agent V1 Sessions  Session Id  Comments Send Post",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Send To Agent",
        "tags": [
          "comments"
        ]
      }
    },
    "/v1/sessions/{session_id}/comments/{comment_id}": {
      "delete": {
        "description": "Delete a comment.\n\nRequires ``LEVEL_EDIT`` on the session in multi-user mode, and\nadditionally that the caller is the comment's author \u2014 one\ncollaborator may not delete another user's comment.\n\n:param request: The incoming request, used to extract the user identity.\n:param session_id: The owning session, e.g. ``\"conv_abc123\"``.\n:param comment_id: The comment to delete, e.g. ``\"a1b2c3d4-...\"``.\n:returns: ``{\"deleted\": true}``.\n:raises OmnigentError: 401/403/404 if the user lacks edit permission,\n    403 if the caller is not the comment's author, or 404 if the\n    comment is not found or does not belong to this session.",
        "operationId": "delete_comment_v1_sessions__session_id__comments__comment_id__delete",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "comment_id",
            "required": true,
            "schema": {
              "title": "Comment Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Delete Comment V1 Sessions  Session Id  Comments  Comment Id  Delete",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Delete Comment",
        "tags": [
          "comments"
        ]
      },
      "patch": {
        "description": "Update a comment's status and/or body text.\n\nRequires ``LEVEL_EDIT`` on the session in multi-user mode.\nEditing the ``body`` additionally requires the caller to be the\ncomment's author: rewriting another user's comment is forbidden,\nwhile changing only the ``status`` (e.g. marking it ``\"addressed\"``)\nstays open to any editor as a shared review-workflow action.\n\n:param request: The incoming request, used to extract the user identity.\n:param session_id: The owning session, e.g. ``\"conv_abc123\"``.\n:param comment_id: The comment to update, e.g. ``\"a1b2c3d4-...\"``.\n:param body: Fields to update; ``None`` fields are left unchanged.\n:returns: The updated serialized comment.\n:raises OmnigentError: 401/403/404 if the user lacks edit permission,\n     403 if a body edit is attempted on another user's comment,\n    or 404 if the comment is not found.",
        "operationId": "update_comment_v1_sessions__session_id__comments__comment_id__patch",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "comment_id",
            "required": true,
            "schema": {
              "title": "Comment Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateCommentRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Update Comment V1 Sessions  Session Id  Comments  Comment Id  Patch",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Update Comment",
        "tags": [
          "comments"
        ]
      }
    },
    "/v1/sessions/{session_id}/elicitations/{elicitation_id}": {
      "get": {
        "description": "Return the state of a pending elicitation as JSON.\n\nUsed by the frontend's standalone approval page\n(``/approve/:sessionId/:elicitationId``) to fetch the\nelicitation prompt and render approve/reject controls.\nThe payload is read from the in-memory\n:mod:`omnigent.runtime.pending_elicitations` index \u2014 no\ndatabase persistence required.\n\n:param request: The inbound request, used for identity\n    extraction.\n:param session_id: Session/conversation identifier,\n    e.g. ``\"conv_abc123\"``.\n:param elicitation_id: Correlation id of the elicitation,\n    e.g. ``\"elicit_abc123\"``.\n:returns: JSON with ``status`` (``\"pending\"`` or\n    ``\"resolved\"``), and when pending: ``message``,\n    ``phase``, ``policy_name``, ``content_preview``.\n:raises OmnigentError: 404 if the session does not exist.",
        "operationId": "get_elicitation_v1_sessions__session_id__elicitations__elicitation_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "elicitation_id",
            "required": true,
            "schema": {
              "title": "Elicitation Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get Elicitation",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/elicitations/{elicitation_id}/resolve": {
      "post": {
        "description": "Resolve an outstanding elicitation by its URL (URL-based\nelicitation).\n\nThe dedicated, RESTful counterpart to delivering a verdict\nvia the ``type == \"approval\"`` event on\n``POST /v1/sessions/{id}/events``. An elicitation request\npublished in ``mode == \"url\"`` carries this endpoint's path\nas its ``params.url``; the client hits it directly with the\nMCP :class:`ElicitationResult` body instead of POSTing a\ngeneric approval event. The verdict routes through the\nshared :func:`_resolve_elicitation`, so resolution semantics\nare identical to the event path.\n\nThe ``elicitation_id`` is taken from the URL rather than the\nbody, so the unguessable id (``secrets.token_hex(16)``) is\nthe capability scoping the resolution \u2014 combined with the\nsession-owner ``LEVEL_EDIT`` gate below and the server-side\nownership check inside :func:`_resolve_elicitation`.\n\n:param request: The inbound request, used for identity\n    extraction.\n:param session_id: Session/conversation identifier,\n    e.g. ``\"conv_abc123\"``.\n:param elicitation_id: Correlation id of the elicitation to\n    resolve, e.g. ``\"elicit_abc123\"``. Taken from the URL\n    path, not the body.\n:param body: The MCP-shaped verdict \u2014 ``action``\n    (``\"accept\"`` / ``\"decline\"`` / ``\"cancel\"``) plus\n    optional form ``content``.\n:returns: ``{\"queued\": False}`` \u2014 resolution is synchronous\n    and persists no conversation item.\n:raises OmnigentError: 404 if no session exists.",
        "operationId": "resolve_elicitation_v1_sessions__session_id__elicitations__elicitation_id__resolve_post",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "elicitation_id",
            "required": true,
            "schema": {
              "title": "Elicitation Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ElicitationResult"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Resolve Elicitation",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/events": {
      "post": {
        "description": "Submit a session event (input message, tool output,\napproval, or interrupt).\n\nDispatches on ``body.type``:\n\n- ``\"interrupt\"`` cancels any active task and publishes a\n  ``session.interrupted`` event. Bypasses item persistence.\n- ``\"approval\"`` resolves an outstanding elicitation\n  in-band (see :func:`_dispatch_approval`).\n- ``\"external_assistant_message\"`` appends and streams an\n  assistant message observed outside the Omnigent task runtime,\n  without starting or steering a task.\n- ``\"external_conversation_item\"`` appends and streams a\n  completed item observed outside the Omnigent task runtime,\n  without starting or steering a task.\n- ``\"external_output_text_delta\"`` publishes a transient\n  ``response.output_text.delta`` event observed outside the\n  Omnigent task runtime, without persisting an item or starting /\n  steering a task.\n- ``\"external_session_interrupted\"`` publishes a\n  ``session.interrupted`` event observed outside the Omnigent task\n  runtime, without persisting an item or starting / steering a\n  task.\n- ``\"external_elicitation_resolved\"`` marks a native\n  harness-originated elicitation as resolved elsewhere so\n  subscribed clients clear the pending approval card.\n- ``\"external_session_status\"`` publishes a terminal-observed\n  ``session.status`` edge without persisting an item or\n  starting/steering a task.\n- ``\"external_model_change\"`` persists a terminal-observed\n  model switch to ``model_override`` and publishes a\n  ``session.model`` SSE event so the web picker reflects it.\n- ``\"stop_session\"`` terminates the live session without\n  deleting the conversation (owner-only). Forwarded\n  harness-agnostically to the runner, which hard-kills the\n  external process for harnesses that have one (claude-native\n  kills its tmux pane) and 204s otherwise. Stop is non-sticky:\n  it writes no persistent marker, so the next message\n  auto-relaunches the session on its (still-online) host via\n  the normal message-dispatch relaunch path.\n- ``\"message\"`` on an ``omnigent claude`` terminal session\n  is forwarded to the bound runner for tmux injection only;\n  the accepted prompt is persisted later when Claude records\n  it in the terminal transcript.\n- Any other (item-typed) event is persisted into\n  ``conversation_items`` via the legacy create-or-steer path\n  (legacy persist path): if an active\n  task is present, the item is delivered into its inbox;\n  otherwise a new task is created and started. In both\n  cases ``session.input.consumed`` fires with the persisted\n  item's id.\n\n:param session_id: Session/conversation identifier.\n:param body: The validated :class:`SessionEventInput`.\n:returns: ``{\"queued\": True, \"item_id\": \"...\"}`` for\n    item-typed events, where ``item_id`` is the persisted\n    conversation item id also emitted by\n    ``session.input.consumed``; ``{\"queued\": False}`` for\n    control and internal transient events.\n:raises OmnigentError: 404 if no session exists.",
        "operationId": "post_event_v1_sessions__session_id__events_post",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SessionEventInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Post Event",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/hooks/codex-elicitation-request": {
      "post": {
        "description": "Codex app-server elicitation request endpoint.\n\nReceives server-to-client JSON-RPC request envelopes forwarded\nby ``omnigent codex`` (for example\n``mcpServer/elicitation/request`` and\n``item/tool/requestUserInput``), publishes the standard\n``response.elicitation_request`` session event for the web UI,\nthen waits for the session-scoped ``approval`` reply. This uses\nthe same registry / publish / cleanup path as the Claude-native\n``PermissionRequest`` hook so pending badges and disconnect\nhandling stay consistent across native harnesses.\n\n:param request: FastAPI request carrying the Codex JSON-RPC\n    request envelope.\n:param session_id: Omnigent conversation id from the URL path.\n:returns: Codex JSON-RPC ``result`` payload for the forwarded\n    request, or ``200`` with empty body on timeout/disconnect.\n:raises OmnigentError: 404 if the session does not exist,\n    400 if the request envelope is malformed or unsupported.",
        "operationId": "codex_elicitation_request_hook_v1_sessions__session_id__hooks_codex_elicitation_request_post",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Codex Elicitation Request Hook",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/hooks/permission-request": {
      "post": {
        "description": "Claude Code ``PermissionRequest`` HTTP hook endpoint.\n\nReceives Claude Code's PermissionRequest hook payload (tool\nname + input the user would otherwise see a TUI prompt for),\npublishes a ``response.elicitation_request`` SSE event on the\nsession stream so the web UI's :file:`ApprovalCard` renders\ninline, and long-polls until the verdict arrives via the\nsession ``approval`` event path.\n\nResponse shape follows Claude Code's PermissionRequest hook\ncontract: ``hookSpecificOutput.decision.behavior`` is\n``\"allow\"`` or ``\"deny\"``. On timeout the endpoint returns\n``200`` with an empty body \u2014 Claude Code treats that as\n\"defer to the TUI prompt\", which matches the wrapper's\nfail-ask contract (UI unreachable / unattended \u2192 fall back\nto terminal-side approval).\n\nAuth: standard session ACL \u2014 the wrapper's outbound headers\n(``ap_auth_headers`` in :func:`build_hook_settings`) carry\nthe same Bearer token used for every other Omnigent request. For\nlocal-server mode (no auth provider), unauth'd calls are\nallowed.\n\n:param request: FastAPI request \u2014 body is Claude Code's\n    PermissionRequest payload as JSON.\n:param session_id: Omnigent conversation id from the URL path.\n:returns: Claude PermissionRequest hookSpecificOutput JSON,\n    or ``200`` with empty body on timeout (fail-ask).\n:raises OmnigentError: 404 if the session doesn't exist,\n    400 if the body fails JSON parse or is missing\n    ``tool_name``.",
        "operationId": "claude_permission_request_hook_v1_sessions__session_id__hooks_permission_request_post",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Claude Permission Request Hook",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/items": {
      "get": {
        "description": "List items in a session with cursor-based pagination.\n\nDelegates to the conversation items store \u2014 session_id is\nthe conversation_id. Same pagination contract as\n``GET /v1/conversations/{id}/items``.\n\n:param session_id: Session/conversation identifier,\n    e.g. ``\"conv_abc123\"``.\n:param limit: Maximum number of items to return\n    (1-1000, default 100).\n:param after: Cursor \u2014 return items after this item ID,\n    e.g. ``\"msg_abc123\"``.\n:param before: Cursor \u2014 return items before this item ID.\n:param order: Sort order, ``\"asc\"`` (chronological,\n    default) or ``\"desc\"``.\n:returns: A :class:`PaginatedList` of conversation items.\n:raises OmnigentError: 404 if no session exists.",
        "operationId": "list_session_items_v1_sessions__session_id__items_get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "maximum": 1000,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "After"
            }
          },
          {
            "in": "query",
            "name": "before",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Before"
            }
          },
          {
            "in": "query",
            "name": "order",
            "required": false,
            "schema": {
              "default": "asc",
              "pattern": "^(asc|desc)$",
              "title": "Order",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "List Session Items",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/labels": {
      "get": {
        "description": "Return only the labels for a session.\n\nNative runner bridge setup needs labels during harness spawn,\nbut the full session snapshot also loads history, skills,\nrunner status, and agent metadata. This endpoint keeps that\nspawn-time dependency to one authorized conversation read.\n\n:param request: The incoming FastAPI request (for auth).\n:param response: The FastAPI response (for cache headers).\n:param session_id: Session/conversation identifier,\n    e.g. ``\"conv_abc123\"``.\n:returns: The session id and labels.\n:raises OmnigentError: 404 if no session exists.",
        "operationId": "get_session_labels_v1_sessions__session_id__labels_get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionLabelsResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get Session Labels",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/mcp": {
      "post": {
        "description": "MCP Streamable HTTP proxy endpoint.\n\nImplements the MCP JSON-RPC 2.0 protocol over HTTP.  The AP\nserver owns policy enforcement (TOOL_CALL / TOOL_RESULT); the\nrunner owns execution via ``POST /v1/sessions/{id}/mcp/execute``\n(reached through the WS tunnel the runner opened at startup).\nThis split ensures:\n\n- Policy runs on the Omnigent server where the ConversationStore and\n  label state live.\n- Stdio MCP subprocesses spawn on the runner's machine with the\n  correct ``cwd``, environment, and installed tooling.\n\nSupported methods:\n\n- ``initialize`` \u2014 capability negotiation.\n- ``tools/list`` \u2014 list all tools; delegated to runner execute.\n- ``tools/call`` \u2014 policy eval on AP, execution on runner.\n\n:param session_id: Session whose agent's MCP servers to proxy,\n    e.g. ``\"conv_abc123\"``.\n:param request: The incoming FastAPI request. Body must be a\n    JSON-RPC 2.0 object.\n:returns: A ``application/json`` JSON-RPC 2.0 response.\n:raises HTTPException: 503 when no ``runner_router`` is configured.",
        "operationId": "mcp_proxy_v1_sessions__session_id__mcp_post",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Mcp Proxy",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/owner": {
      "get": {
        "description": "Return the owner of a session.\n\nRequires read-level access.\n\n:param request: The incoming FastAPI request (for auth).\n:param session_id: Session to look up,\n    e.g. ``\"conv_abc123\"``.\n:returns: ``{\"owner\": \"<user_id>\"}`` or\n    ``{\"owner\": null}``.",
        "operationId": "get_session_owner_v1_sessions__session_id__owner_get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get Session Owner",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/permissions": {
      "get": {
        "description": "List all permission grants on a session.\n\nRequires manage-level access.\n\n:param request: The incoming FastAPI request (for auth).\n:param session_id: Session to list grants for,\n    e.g. ``\"conv_abc123\"``.\n:returns: List of :class:`PermissionObject`.\n:raises OmnigentError: 404 if no session or no access.",
        "operationId": "list_permissions_v1_sessions__session_id__permissions_get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "List Permissions",
        "tags": [
          "sessions"
        ]
      },
      "put": {
        "description": "Grant or update a permission on a session.\n\nRequires manage-level access. Upserts the grant \u2014 can\nupgrade or downgrade an existing level. Auto-creates the\ngrantee user if they don't exist yet.\n\n:param request: The incoming FastAPI request (for auth).\n:param session_id: Session to grant access to,\n    e.g. ``\"conv_abc123\"``.\n:param body: The grant request with ``user_id`` and ``level``.\n:returns: The resulting :class:`PermissionObject`.\n:raises OmnigentError: 404 if no session or no access,\n    401 if unauthenticated.",
        "operationId": "grant_permission_v1_sessions__session_id__permissions_put",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GrantPermissionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Grant Permission",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/permissions/{target_user_id}": {
      "delete": {
        "description": "Revoke a user's permission on a session.\n\nRequires manage-level access. Cannot revoke your own\nmanage grant (prevents orphaned sessions). Returns 204\nwhether or not the grant existed (idempotent).\n\n:param request: The incoming FastAPI request (for auth).\n:param session_id: Session to revoke access from,\n    e.g. ``\"conv_abc123\"``.\n:param target_user_id: User whose grant to revoke,\n    e.g. ``\"alice@example.com\"``.\n:returns: 204 No Content.\n:raises OmnigentError: 404 if no session or no access,\n    403 if attempting to revoke own manage grant.",
        "operationId": "revoke_permission_v1_sessions__session_id__permissions__target_user_id__delete",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "target_user_id",
            "required": true,
            "schema": {
              "title": "Target User Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Revoke Permission",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/policies": {
      "get": {
        "description": "List all policies for a session.\n\nReturns both store-persisted (``source=\"session\"``) and\nspec-declared (``source=\"spec\"``) policies. Spec policies\nhave ``id=None`` and cannot be patched or deleted.\n\nRequires ``LEVEL_READ`` on the session in multi-user mode.\n\n:param request: The incoming request, used to extract the\n    user identity.\n:param session_id: The session to query, e.g.\n    ``\"conv_abc123\"``.\n:returns: ``{\"object\": \"list\", \"data\": [...]}``.\n:raises OmnigentError: 401/403 if the user lacks read\n    permission, 404 if the session is not found.",
        "operationId": "list_policies_v1_sessions__session_id__policies_get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response List Policies V1 Sessions  Session Id  Policies Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "List Policies",
        "tags": [
          "session_policies"
        ]
      },
      "post": {
        "description": "Create a new session policy.\n\nRequires ``LEVEL_EDIT`` on the session in multi-user mode.\n\n:param request: The incoming request, used to extract the\n    user identity.\n:param session_id: The owning session, e.g.\n    ``\"conv_abc123\"``.\n:param body: Policy payload including name, type, and\n    handler.\n:returns: The created policy as a serialized dict.\n:raises OmnigentError: 401/403 if the user lacks edit\n    permission, 404 if the session is not found, or 409\n    if a policy with the same name already exists.",
        "operationId": "create_policy_v1_sessions__session_id__policies_post",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSessionPolicyRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Create Policy V1 Sessions  Session Id  Policies Post",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Create Policy",
        "tags": [
          "session_policies"
        ]
      }
    },
    "/v1/sessions/{session_id}/policies/evaluate": {
      "post": {
        "description": "Generic policy evaluation endpoint (proto-compatible).\n\nAccepts an ``EvaluationRequest`` JSON body whose ``event``\nfield carries the phase (``PHASE_TOOL_CALL``,\n``PHASE_TOOL_RESULT``, ``PHASE_LLM_REQUEST``,\n``PHASE_LLM_RESPONSE``), the event data, and optional\ncontext. Returns an ``EvaluationResponse`` with the policy\nverdict (``result``), an optional ``reason``, and optional\n``data`` for content-rewriting policies.\n\nUsed by Claude Code's ``PreToolUse`` and ``PostToolUse``\ncommand hooks (via ``omnigent.claude_native_hook``) to\nevaluate admin policies on native tool calls. Also usable\nby any client that speaks the proto-compatible JSON schema.\n\n:param request: FastAPI request \u2014 body is the\n    ``EvaluationRequest`` JSON envelope.\n:param session_id: Omnigent conversation id from the URL path.\n:returns: ``EvaluationResponse`` JSON with ``result``,\n    ``reason``, and optional ``data``.\n:raises OmnigentError: 404 if the session doesn't exist,\n    400 if the body is malformed.",
        "operationId": "evaluate_policy_v1_sessions__session_id__policies_evaluate_post",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Evaluate Policy",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/policies/{policy_id}": {
      "delete": {
        "description": "Delete a session policy.\n\nIdempotent \u2014 deleting a missing policy returns 204.\nRequires ``LEVEL_EDIT``.\n\n:param request: The incoming request, used to extract the\n    user identity.\n:param session_id: The owning session, e.g.\n    ``\"conv_abc123\"``.\n:param policy_id: The policy to delete, e.g.\n    ``\"pol_abc123\"``.\n:returns: ``{\"deleted\": true}``.\n:raises OmnigentError: 401/403 if the user lacks edit\n    permission.",
        "operationId": "delete_policy_v1_sessions__session_id__policies__policy_id__delete",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "policy_id",
            "required": true,
            "schema": {
              "title": "Policy Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Delete Policy V1 Sessions  Session Id  Policies  Policy Id  Delete",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Delete Policy",
        "tags": [
          "session_policies"
        ]
      },
      "get": {
        "description": "Get a single session policy.\n\nRequires ``LEVEL_READ`` on the session in multi-user mode.\n\n:param request: The incoming request, used to extract the\n    user identity.\n:param session_id: The owning session, e.g.\n    ``\"conv_abc123\"``.\n:param policy_id: The policy to retrieve, e.g.\n    ``\"pol_abc123\"``.\n:returns: The policy as a serialized dict.\n:raises OmnigentError: 401/403 if the user lacks read\n    permission, or 404 if the policy is not found.",
        "operationId": "get_policy_v1_sessions__session_id__policies__policy_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "policy_id",
            "required": true,
            "schema": {
              "title": "Policy Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Get Policy V1 Sessions  Session Id  Policies  Policy Id  Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get Policy",
        "tags": [
          "session_policies"
        ]
      },
      "patch": {
        "description": "Update a session policy's mutable fields.\n\n``type`` is immutable \u2014 the caller must delete and\nre-create to change it. Requires ``LEVEL_EDIT``.\n\n:param request: The incoming request, used to extract the\n    user identity.\n:param session_id: The owning session, e.g.\n    ``\"conv_abc123\"``.\n:param policy_id: The policy to update, e.g.\n    ``\"pol_abc123\"``.\n:param body: Fields to update; ``None`` fields are left\n    unchanged.\n:returns: The updated policy as a serialized dict.\n:raises OmnigentError: 401/403 if the user lacks edit\n    permission, or 404 if the policy is not found.",
        "operationId": "update_policy_v1_sessions__session_id__policies__policy_id__patch",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "policy_id",
            "required": true,
            "schema": {
              "title": "Policy Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateSessionPolicyRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Update Policy V1 Sessions  Session Id  Policies  Policy Id  Patch",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Update Policy",
        "tags": [
          "session_policies"
        ]
      }
    },
    "/v1/sessions/{session_id}/resources": {
      "get": {
        "description": "Return the runner-authoritative resource inventory for a session.\n\nRequires the session to be bound to a runner via\n``PATCH /v1/sessions/{id}``; raises ``conflict`` otherwise.\nThe server validates the session exists, then proxies to the\nrunner's ``GET /v1/sessions/{id}/resources`` endpoint. In\nunit-test / in-process setups with no runner router/client, the\nroute falls back to adapting the local terminal registry.\n\n:param request: The incoming FastAPI request (for auth).\n:param session_id: Session/conversation identifier,\n    e.g. ``\"conv_abc123\"``.\n:param type: Optional resource-type filter, e.g.\n    ``\"environment\"`` / ``\"terminal\"`` / ``\"file\"``. Forwarded\n    to the runner (its registry applies it) and honored by the\n    local-registry fallback and the file-store merge below.",
        "operationId": "list_session_resources_v1_sessions__session_id__resources_get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "type",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Type"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionResourcePaginatedList"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "List Session Resources",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/resources/environments": {
      "get": {
        "description": "Return only environment resources for a session.\n\n:param request: The incoming FastAPI request (for auth).\n:param session_id: Session/conversation identifier.\n:returns: ``PaginatedList`` of environment resources.",
        "operationId": "list_session_environments_v1_sessions__session_id__resources_environments_get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "List Session Environments",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/resources/environments/{environment_id}": {
      "get": {
        "description": "Return a single environment resource by id.\n\n:param request: The incoming FastAPI request (for auth).\n:param session_id: Session/conversation identifier.\n:param environment_id: Opaque environment resource id,\n    e.g. ``\"default\"``.\n:returns: The environment resource object.",
        "operationId": "get_session_environment_v1_sessions__session_id__resources_environments__environment_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "environment_id",
            "required": true,
            "schema": {
              "title": "Environment Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get Session Environment",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/resources/environments/{environment_id}/changes": {
      "get": {
        "description": "List all files changed since session start (flat, registry-backed).\n\nReturns the watchdog change set for the session \u2014 every file\ncreated, modified, or deleted since the session began, regardless\nof directory depth.  Use for the flat \"changed files\" view.\n\n:param request: The incoming FastAPI request (for auth).\n:param session_id: Session/conversation identifier.\n:param environment_id: Environment resource id.\n:returns: Flat list of changed filesystem entries with ``status``.",
        "operationId": "list_environment_filesystem_changes_v1_sessions__session_id__resources_environments__environment_id__changes_get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "environment_id",
            "required": true,
            "schema": {
              "title": "Environment Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "List Environment Filesystem Changes",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/resources/environments/{environment_id}/diff/{relative_path}": {
      "get": {
        "description": "Return before/after diff content for a changed file.\n\nProxies to the runner's diff endpoint and returns before/after\ncontent strings so the UI can render a diff view.  Returns 404 when\nthe file has not been modified this session.\n\n:param request: The incoming FastAPI request (for auth).\n:param session_id: Session/conversation identifier.\n:param environment_id: Environment resource id.\n:param relative_path: Path relative to environment root.\n:returns: JSON with ``before`` and ``after`` content strings.",
        "operationId": "read_environment_file_diff_v1_sessions__session_id__resources_environments__environment_id__diff__relative_path__get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "environment_id",
            "required": true,
            "schema": {
              "title": "Environment Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "relative_path",
            "required": true,
            "schema": {
              "title": "Relative Path",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Read Environment File Diff",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/resources/environments/{environment_id}/filesystem": {
      "get": {
        "description": "List root directory of an environment.\n\n:param request: The incoming FastAPI request (for auth).\n:param session_id: Session/conversation identifier.\n:param environment_id: Environment resource id.\n:param limit: Maximum number of entries to return (1-1000, default 20).\n:param after: Cursor entry id for forward pagination.\n:param before: Cursor entry id for backward pagination.\n:param order: Sort order, ``\"asc\"`` or ``\"desc\"``.\n:returns: PaginatedList of filesystem entries.",
        "operationId": "list_environment_root_v1_sessions__session_id__resources_environments__environment_id__filesystem_get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "environment_id",
            "required": true,
            "schema": {
              "title": "Environment Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 20,
              "maximum": 1000,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "After"
            }
          },
          {
            "in": "query",
            "name": "before",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Before"
            }
          },
          {
            "in": "query",
            "name": "order",
            "required": false,
            "schema": {
              "default": "desc",
              "pattern": "^(asc|desc)$",
              "title": "Order",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "List Environment Root",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/resources/environments/{environment_id}/filesystem/{relative_path}": {
      "delete": {
        "description": "Delete a file or directory in an environment.\n\n:param request: The incoming FastAPI request (for auth).\n:param session_id: Session/conversation identifier.\n:param environment_id: Environment resource id.\n:param relative_path: Path relative to environment root.\n:returns: Delete result.",
        "operationId": "delete_environment_path_v1_sessions__session_id__resources_environments__environment_id__filesystem__relative_path__delete",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "environment_id",
            "required": true,
            "schema": {
              "title": "Environment Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "relative_path",
            "required": true,
            "schema": {
              "title": "Relative Path",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Delete Environment Path",
        "tags": [
          "sessions"
        ]
      },
      "get": {
        "description": "Read a file or list a directory in an environment.\n\n:param request: The incoming FastAPI request (for auth).\n:param session_id: Session/conversation identifier.\n:param environment_id: Environment resource id.\n:param relative_path: Path relative to environment root.\n:param limit: Maximum number of entries to return for directory\n    listings (1-1000, default 20). Ignored for file reads.\n:param after: Cursor entry id for forward pagination.\n:param before: Cursor entry id for backward pagination.\n:param order: Sort order, ``\"asc\"`` or ``\"desc\"``.\n:returns: File content or directory listing.",
        "operationId": "read_or_list_environment_path_v1_sessions__session_id__resources_environments__environment_id__filesystem__relative_path__get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "environment_id",
            "required": true,
            "schema": {
              "title": "Environment Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "relative_path",
            "required": true,
            "schema": {
              "title": "Relative Path",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 20,
              "maximum": 1000,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "After"
            }
          },
          {
            "in": "query",
            "name": "before",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Before"
            }
          },
          {
            "in": "query",
            "name": "order",
            "required": false,
            "schema": {
              "default": "desc",
              "pattern": "^(asc|desc)$",
              "title": "Order",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Read Or List Environment Path",
        "tags": [
          "sessions"
        ]
      },
      "patch": {
        "description": "Edit a file in an environment via text replacement.\n\n:param session_id: Session/conversation identifier.\n:param environment_id: Environment resource id.\n:param relative_path: Path relative to environment root.\n:param request: JSON body with ``old_text`` and ``new_text``.\n:returns: Edit result.",
        "operationId": "edit_environment_file_v1_sessions__session_id__resources_environments__environment_id__filesystem__relative_path__patch",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "environment_id",
            "required": true,
            "schema": {
              "title": "Environment Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "relative_path",
            "required": true,
            "schema": {
              "title": "Relative Path",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Edit Environment File",
        "tags": [
          "sessions"
        ]
      },
      "put": {
        "description": "Write/replace a file in an environment.\n\n:param session_id: Session/conversation identifier.\n:param environment_id: Environment resource id.\n:param relative_path: Path relative to environment root.\n:param request: JSON body with ``content``.\n:returns: Write result.",
        "operationId": "write_environment_file_v1_sessions__session_id__resources_environments__environment_id__filesystem__relative_path__put",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "environment_id",
            "required": true,
            "schema": {
              "title": "Environment Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "relative_path",
            "required": true,
            "schema": {
              "title": "Relative Path",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Write Environment File",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/resources/environments/{environment_id}/search": {
      "get": {
        "description": "Search for files recursively by name/path substring and glob filters.\n\nProxies to the runner's search endpoint.  Returns a flat list of\nmatching file entries (not directories) whose name or relative path\ncontains ``q`` (case-insensitive), optionally scoped by ``include`` /\n``exclude`` globs.  Requires at least one non-whitespace character in\n``q`` to prevent accidental full-tree scans.\n\n:param request: The incoming FastAPI request (for auth).\n:param session_id: Session/conversation identifier,\n    e.g. ``\"conv_abc123\"``.\n:param environment_id: Environment resource id,\n    e.g. ``\"default\"``.\n:param q: Case-insensitive search substring, e.g. ``\"test.md\"``.\n    Must contain at least one non-whitespace character.\n:param include: Comma-separated glob patterns scoping which files are\n    returned, e.g. ``\"*.ts,src/**\"``.\n:param exclude: Comma-separated glob patterns for files to drop,\n    e.g. ``\"**/node_modules,*.test.ts\"``.\n:param limit: Maximum number of results (1-500, default 500).\n:returns: JSON list response with matching filesystem entries.",
        "operationId": "search_environment_files_v1_sessions__session_id__resources_environments__environment_id__search_get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "environment_id",
            "required": true,
            "schema": {
              "title": "Environment Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "q",
            "required": true,
            "schema": {
              "minLength": 1,
              "pattern": ".*\\S.*",
              "title": "Q",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "include",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Include"
            }
          },
          {
            "in": "query",
            "name": "exclude",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Exclude"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 500,
              "maximum": 500,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Search Environment Files",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/resources/environments/{environment_id}/shell": {
      "post": {
        "description": "Execute a shell command in an environment.\n\n:param session_id: Session/conversation identifier.\n:param environment_id: Environment resource id.\n:param request: JSON body with ``command`` and optional\n    ``timeout``.\n:returns: Shell result.",
        "operationId": "run_environment_shell_v1_sessions__session_id__resources_environments__environment_id__shell_post",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "environment_id",
            "required": true,
            "schema": {
              "title": "Environment Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Run Environment Shell",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/resources/files": {
      "get": {
        "description": "List files owned by a session.\n\n:param session_id: Session/conversation identifier.\n:param limit: Maximum number of files to return.\n:param after: Cursor file ID for forward pagination.\n:param before: Cursor file ID for backward pagination.\n:param order: Sort direction, ``\"desc\"`` or ``\"asc\"``.\n:returns: ``PaginatedList`` of session file resources.",
        "operationId": "list_session_files_v1_sessions__session_id__resources_files_get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 20,
              "maximum": 1000,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "after",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "After"
            }
          },
          {
            "in": "query",
            "name": "before",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Before"
            }
          },
          {
            "in": "query",
            "name": "order",
            "required": false,
            "schema": {
              "default": "desc",
              "pattern": "^(asc|desc)$",
              "title": "Order",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "List Session Files",
        "tags": [
          "sessions"
        ]
      },
      "post": {
        "description": "Upload a file into the session file namespace.\n\nAccepts the multipart upload shape used by session file resources.\n\n:param request: The incoming FastAPI request (for auth).\n:param session_id: Session/conversation identifier.\n:param file: The uploaded file (multipart form data).\n:returns: The session file resource object.",
        "operationId": "upload_session_file_v1_sessions__session_id__resources_files_post",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Body_upload_session_file_v1_sessions__session_id__resources_files_post"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Upload Session File",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/resources/files/{file_id}": {
      "delete": {
        "description": "Delete a session file resource and its artifact bytes.\n\n:param session_id: Session/conversation identifier.\n:param file_id: Unique file identifier.\n:returns: Deletion confirmation object.",
        "operationId": "delete_session_file_v1_sessions__session_id__resources_files__file_id__delete",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "file_id",
            "required": true,
            "schema": {
              "title": "File Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Delete Session File",
        "tags": [
          "sessions"
        ]
      },
      "get": {
        "description": "Retrieve metadata for a session file resource.\n\nVerifies that ``file_id`` belongs to ``session_id``.\n\n:param request: The incoming FastAPI request (for auth).\n:param session_id: Session/conversation identifier.\n:param file_id: Unique file identifier.\n:returns: The session file resource object.",
        "operationId": "get_session_file_v1_sessions__session_id__resources_files__file_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "file_id",
            "required": true,
            "schema": {
              "title": "File Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get Session File",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/resources/files/{file_id}/content": {
      "get": {
        "description": "Download raw content of a session file resource.\n\n:param session_id: Session/conversation identifier.\n:param file_id: Unique file identifier.\n:returns: Response with file bytes and Content-Type.",
        "operationId": "get_session_file_content_v1_sessions__session_id__resources_files__file_id__content_get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "file_id",
            "required": true,
            "schema": {
              "title": "File Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get Session File Content",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/resources/terminals": {
      "get": {
        "description": "Return only terminal resources for a session.\n\nThe runner endpoint's pagination params (``limit`` / ``after`` /\n``before`` / ``order``) are forwarded from the incoming query\nstring \u2014 without this, a client-requested ``order=asc`` (the web\nterminal tabs rely on creation order to keep the session's own\nterminal first) would be silently dropped and the runner's\n``desc`` default would apply.\n\n:param request: The incoming FastAPI request (for auth and the\n    forwarded query params).\n:param session_id: Session/conversation identifier.\n:returns: ``PaginatedList`` of terminal resources.",
        "operationId": "list_session_terminals_v1_sessions__session_id__resources_terminals_get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "List Session Terminals",
        "tags": [
          "sessions"
        ]
      },
      "post": {
        "description": "Launch or return an existing terminal resource.\n\nPreserves ``sys_terminal_launch`` idempotency: an\nalready-running ``(terminal, session_key)`` returns the\nexisting resource.\n\nUser-initiated creates are gated on the agent's terminal\naccess: the requested ``terminal`` must be one of the names\ndeclared in the agent spec's ``terminals:`` block. Native\nharness bootstrap requests (marked ``ensure_native_terminal``\nor ``bridge_inject_dir`` \u2014 the ``omnigent claude`` / ``codex``\nwrappers launching the session's own CLI terminal) are exempt:\nthey launch undeclared names via the runner's\nsynthesize-from-body path and predate the gate. The markers\nare client-controlled, so the exemption is narrowed to the\nexact shape those wrappers send \u2014 ``terminal`` of ``\"claude\"``\nor ``\"codex\"`` with ``session_key`` ``\"main\"`` \u2014 anything else\ncarrying a marker still goes through the declared-name gate\n(it would otherwise be an arbitrary-terminal bypass).\n\n:param session_id: Session/conversation identifier.\n:param request: JSON body with ``terminal`` and\n    ``session_key``.\n:returns: The terminal resource object.\n:raises OmnigentError: 400 when the requested terminal is not\n    declared by the agent spec (or the agent has no\n    ``terminals:`` block at all).",
        "operationId": "create_session_terminal_v1_sessions__session_id__resources_terminals_post",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Create Session Terminal",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/resources/terminals/{terminal_id}": {
      "delete": {
        "description": "Close a terminal resource.\n\nDelegates to ``TerminalRegistry.close()`` on the runner.\nReturns 404 for unknown terminals.\n\n:param request: The incoming FastAPI request (for auth).\n:param session_id: Session/conversation identifier.\n:param terminal_id: Opaque terminal resource id.\n:returns: Deletion confirmation object.",
        "operationId": "delete_session_terminal_v1_sessions__session_id__resources_terminals__terminal_id__delete",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "terminal_id",
            "required": true,
            "schema": {
              "title": "Terminal Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Delete Session Terminal",
        "tags": [
          "sessions"
        ]
      },
      "get": {
        "description": "Return a single terminal resource by id.\n\n:param request: The incoming FastAPI request (for auth).\n:param session_id: Session/conversation identifier.\n:param terminal_id: Opaque terminal resource id.\n:returns: The terminal resource object.",
        "operationId": "get_session_terminal_v1_sessions__session_id__resources_terminals__terminal_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "terminal_id",
            "required": true,
            "schema": {
              "title": "Terminal Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get Session Terminal",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/resources/terminals/{terminal_id}/transfer": {
      "post": {
        "description": "Move a terminal resource to another session without closing it.\n\nUsed by native Claude ``/clear`` rotation: ownership changes\nfrom the previous conversation to the fresh one while the tmux\npane keeps running.\n\n:param request: The incoming FastAPI request (for auth) with\n    JSON body ``{\"target_session_id\": \"conv_new\"}``.\n:param session_id: Current owning session/conversation id,\n    e.g. ``\"conv_old\"``.\n:param terminal_id: Opaque terminal resource id,\n    e.g. ``\"terminal_claude_main\"``.\n:returns: The terminal resource object under the target session.",
        "operationId": "transfer_session_terminal_v1_sessions__session_id__resources_terminals__terminal_id__transfer_post",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "terminal_id",
            "required": true,
            "schema": {
              "title": "Terminal Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Transfer Session Terminal",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/resources/{resource_id}": {
      "get": {
        "description": "Return a single resource by id from the unified inventory.\n\n:param session_id: Session/conversation identifier.\n:param resource_id: Opaque resource id.\n:returns: The resource object regardless of type.",
        "operationId": "get_session_resource_v1_sessions__session_id__resources__resource_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "resource_id",
            "required": true,
            "schema": {
              "title": "Resource Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Get Session Resource",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/stream": {
      "get": {
        "description": "Subscribe to the session's live SSE event stream.\n\nDoes NOT replay history; clients reconcile via the snapshot\nendpoint. The generator handles disconnects via a\n``try/finally`` that emits the ``[DONE]`` sentinel in all\nexit paths \u2014 see :func:`_stream_live_events`.\n\nHolding this stream open registers the caller as a session\n*viewer* (presence): co-viewers' streams receive\n``session.presence`` events on join/leave/idle edges, and\nthis stream's snapshot-on-connect includes the current\nviewer list. Presence is scoped to the session tree's root\nconversation, so viewers of different agents/sub-agents in\none session see each other. See\n``omnigent/server/presence.py``.\n\n:param request: The FastAPI request, used to detect\n    disconnect.\n:param session_id: Session/conversation identifier,\n    e.g. ``\"conv_abc123\"``.\n:param idle: Presence idle flag computed by the web client\n    at connect time (tab backgrounded \u2265 its debounce). An\n    idle *flip* mid-view arrives as a reconnect carrying the\n    new value \u2014 there is no separate update endpoint.\n:returns: An SSE :class:`StreamingResponse`.\n:raises OmnigentError: 404 if no session exists.",
        "operationId": "stream_session_v1_sessions__session_id__stream_get",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "idle",
            "required": false,
            "schema": {
              "default": false,
              "title": "Idle",
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              },
              "text/event-stream": {
                "itemSchema": {
                  "$ref": "#/components/schemas/ServerStreamEvent"
                }
              }
            },
            "description": "SSE stream of :data:`ServerStreamEvent` frames for the session."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Stream Session",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{session_id}/switch-agent": {
      "post": {
        "description": "Switch an existing session in place to a different agent/harness.\n\nUnlike fork, this keeps the SAME session \u2014 transcript, comments,\nfiles, host, and workspace are untouched; only the agent/harness\nchanges. The current session-scoped agent is replaced by a clone\nof the target built-in, model settings carry over only within the\nsame provider family (a model id is provider-bound), the native\nruntime session id is cleared, and the harness-presentation labels\nare recomputed for the target. The next turn cold-starts the new\nharness (rebuilding the native transcript from this session's own\nitems for a same-family native target). Only built-in agents are\nbindable, and only while the session is idle.\n\n:param request: The incoming FastAPI request (for auth).\n:param session_id: Session/conversation identifier to switch,\n    e.g. ``\"conv_abc123\"``.\n:param body: The validated :class:`SessionSwitchAgentRequest`.\n:returns: A :class:`SessionResponse` describing the session after\n    the switch (status ``\"idle\"``).\n:raises OmnigentError: 404 if the session or target agent does\n    not exist or the target is not a bindable built-in; 403 if the\n    caller lacks edit access; 400 if the session is a sub-agent,\n    has no agent binding, or the target bundle can't be loaded;\n    409 if a turn is currently running.",
        "operationId": "switch_session_agent_v1_sessions__session_id__switch_agent_post",
        "parameters": [
          {
            "in": "path",
            "name": "session_id",
            "required": true,
            "schema": {
              "title": "Session Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SessionSwitchAgentRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Switch Session Agent",
        "tags": [
          "sessions"
        ]
      }
    },
    "/v1/sessions/{source_id}/fork": {
      "post": {
        "description": "Fork an existing session into a new session.\n\nDeep-copies the source session's conversation items and\nclones the agent into a new session. When ``body.agent_id``\nis set, the fork binds that built-in agent instead of the\nsource's \u2014 switching harness (e.g. Claude-SDK \u2192 Claude Code,\nor Claude \u2192 Codex). The source's model settings carry over\nonly within the same provider family; a same-family native\ntarget also carries conversation history (the runner rebuilds\nits transcript). The REPL/CLI binds the fork to its runner via\n``PATCH /v1/sessions/{id}`` after creation.\n\nWhen ``body.up_to_response_id`` is set, only history up to and\nincluding that response is copied into the fork (a \"fork from\nthis response\"); a native target then rebuilds its transcript\nfrom the truncated items instead of resuming the source's full\nnative transcript.\n\n:param request: The incoming FastAPI request (for auth).\n:param source_id: Session/conversation identifier of the\n    source session to fork, e.g. ``\"conv_abc123\"``.\n:param body: The validated :class:`SessionForkRequest`.\n:returns: A :class:`SessionResponse` describing the newly\n    created fork (status ``\"idle\"``).\n:raises OmnigentError: 404 if *source_id* does not exist\n    or ``body.agent_id`` is not a bindable built-in agent;\n    403 if the caller lacks read access; 400 if the source\n    is a sub-agent session, has no agent binding, or\n    ``body.up_to_response_id`` names no response in the\n    source session.",
        "operationId": "fork_session_v1_sessions__source_id__fork_post",
        "parameters": [
          {
            "in": "path",
            "name": "source_id",
            "required": true,
            "schema": {
              "title": "Source Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SessionForkRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "summary": "Fork Session",
        "tags": [
          "sessions"
        ]
      }
    }
  }
}