openapi.json
Rama main · réplica de lectura del repositorio original.
{
"components": {
"schemas": {
"AddCommentRequest": {
"description": "Request body for `POST /sessions/{id}/comments`.",
"properties": {
"anchor_content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Plain-text snapshot of the selected range, used to re-anchor the comment after file edits. `None` if not provided.",
"title": "Anchor Content"
},
"anchor_metadata": {
"title": "Anchor Metadata",
"type": "null"
},
"body": {
"description": "The comment text.",
"title": "Body",
"type": "string"
},
"end_index": {
"description": "0-based absolute character offset (exclusive) within the file where the anchor range ends.",
"format": "int64",
"title": "End Index",
"type": "integer"
},
"path": {
"description": "File path relative to workspace root, e.g. `\"src/App.tsx\"`.",
"title": "Path",
"type": "string"
},
"start_index": {
"description": "0-based absolute character offset (inclusive) within the file where the anchor range begins.",
"format": "int64",
"title": "Start Index",
"type": "integer"
}
},
"required": [
"path",
"body",
"start_index",
"end_index"
],
"title": "AddCommentRequest",
"type": "object"
},
"AgentConfigObject": {
"description": "Owner-only configuration read and PATCH result.",
"properties": {
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"harness": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Harness"
},
"id": {
"title": "Id",
"type": "string"
},
"instructions": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Instructions"
},
"mcp_servers": {
"additionalProperties": {
"$ref": "#/components/schemas/AgentMCPConfig"
},
"title": "Mcp Servers",
"type": "object"
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model"
},
"name": {
"title": "Name",
"type": "string"
},
"version": {
"format": "int64",
"title": "Version",
"type": "integer"
}
},
"required": [
"id",
"name",
"version"
],
"title": "AgentConfigObject",
"type": "object"
},
"AgentConfigPatch": {
"additionalProperties": false,
"description": "Merge-style update of an owned agent, with immutable identity.",
"properties": {
"description": {
"anyOf": [
{
"maxLength": 4096,
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"harness": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"title": "Harness"
},
"instructions": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Instructions"
},
"mcp_servers": {
"anyOf": [
{
"patternProperties": {
"^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,127}$": {
"anyOf": [
{
"$ref": "#/components/schemas/MCPServerPatch"
},
{
"type": "null"
}
]
}
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Mcp Servers"
},
"model": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"title": "Model"
}
},
"title": "AgentConfigPatch",
"type": "object"
},
"AgentDetailObject": {
"description": "Agent summary with caller ownership for management actions.",
"properties": {
"builtin": {
"default": false,
"title": "Builtin",
"type": "boolean"
},
"created_at": {
"format": "int64",
"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"
},
"loads_user_settings": {
"default": true,
"title": "Loads User Settings",
"type": "boolean"
},
"mcp_registry_editable": {
"default": false,
"title": "Mcp Registry Editable",
"type": "boolean"
},
"mcp_servers": {
"items": {
"$ref": "#/components/schemas/MCPServerSummary"
},
"title": "Mcp Servers",
"type": "array"
},
"mcp_servers_editable": {
"default": false,
"title": "Mcp Servers Editable",
"type": "boolean"
},
"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": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"title": "Updated At"
},
"user_owned": {
"title": "User Owned",
"type": "boolean"
},
"version": {
"default": 1,
"format": "int64",
"title": "Version",
"type": "integer"
}
},
"required": [
"id",
"name",
"created_at",
"user_owned"
],
"title": "AgentDetailObject",
"type": "object"
},
"AgentList": {
"description": "Paginated list of agents; `data` is a page of `AgentObject`.",
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/AgentObject"
},
"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"
},
"suppressed_agent_names": {
"description": "Packaged built-ins `OMNIGENT_SEEDED_AGENTS` trimmed from `data`. The web picker also discovers agents from a user's recent sessions, so it needs these names to keep a hidden built-in with prior sessions from resurfacing as a custom agent.",
"items": {
"type": "string"
},
"title": "Suppressed Agent Names",
"type": "array"
}
},
"title": "AgentList",
"type": "object"
},
"AgentMCPConfig": {
"description": "Editable MCP projection without credential values.",
"properties": {
"args": {
"items": {
"type": "string"
},
"title": "Args",
"type": "array"
},
"command": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Command"
},
"configured_env_names": {
"items": {
"type": "string"
},
"title": "Configured Env Names",
"type": "array"
},
"configured_header_names": {
"items": {
"type": "string"
},
"title": "Configured Header Names",
"type": "array"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"editable": {
"default": true,
"title": "Editable",
"type": "boolean"
},
"transport": {
"title": "Transport",
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Url"
}
},
"required": [
"transport"
],
"title": "AgentMCPConfig",
"type": "object"
},
"AgentObject": {
"description": "API representation of a registered agent.",
"properties": {
"builtin": {
"default": false,
"description": "Whether this is a server-*seeded* built-in agent (deterministic, name-derived id) as opposed to an operator/user-registered template (random id, e.g. via `omnigent server --agent`) or a session-scoped upload. The Web UI's new-session picker uses this to decide whether a same-named `omnigent run` upload may shadow the catalog entry: seeded built-ins are protected, while a user-registered template is superseded by a newer same-named upload. Always `False` for session-scoped agents.",
"title": "Builtin",
"type": "boolean"
},
"created_at": {
"description": "Unix epoch timestamp of creation.",
"format": "int64",
"title": "Created At",
"type": "integer"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional free-text description of the agent's purpose.",
"title": "Description"
},
"harness": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The agent's harness/kind, e.g. `\"codex\"`, `\"codex-native\"`, or `\"claude-native\"` for `executor.type: omnigent` agents, otherwise the executor type (`\"claude_sdk\"`, `\"agents_sdk\"`). `None` when the bundle cannot be loaded. Lets the Web UI Add Agent picker recognise an agent's kind (Codex vs Claude) without hardcoding by name slug.",
"title": "Harness"
},
"id": {
"description": "Unique agent identifier, e.g. `\"ag_abc123\"`.",
"title": "Id",
"type": "string"
},
"loads_user_settings": {
"default": true,
"description": "Whether a claude-sdk session for this agent loads the user's Claude settings and user-scope MCP servers. `False` when the spec's `skills: none` runs the CLI with no setting sources; `True` when the bundle cannot be loaded.",
"title": "Loads User Settings",
"type": "boolean"
},
"mcp_registry_editable": {
"default": false,
"description": "Whether this caller owns the session and can select managed MCP services independently of agent ownership.",
"title": "Mcp Registry Editable",
"type": "boolean"
},
"mcp_servers": {
"description": "MCP servers the agent is connected to (secret fields omitted). Empty list when the spec declares no MCP servers or when the bundle cannot be loaded.",
"items": {
"$ref": "#/components/schemas/MCPServerSummary"
},
"title": "Mcp Servers",
"type": "array"
},
"mcp_servers_editable": {
"default": false,
"description": "Whether the MCP list can be edited through the session UI by the authenticated caller. This requires ownership of both the effective session and its session-scoped agent; built-in template and native agents are read-only.",
"title": "Mcp Servers Editable",
"type": "boolean"
},
"name": {
"description": "Human-readable agent name, e.g. `\"research-agent\"`.",
"title": "Name",
"type": "string"
},
"object": {
"default": "agent",
"description": "Fixed resource type, always `\"agent\"`.",
"title": "Object",
"type": "string"
},
"policies": {
"description": "Guardrails policies declared on the agent. Each entry summarises the policy name, type, and phases. Empty list when the spec declares no policies or when the bundle cannot be loaded.",
"items": {
"$ref": "#/components/schemas/PolicySummary"
},
"title": "Policies",
"type": "array"
},
"skills": {
"description": "Skills bundled in the agent spec (`skills/<dir>/SKILL.md`). Lets the Web UI's new-session composer offer a slash-command menu before a session exists. `GET /skills` discovers host skills and, when given `session_id`, merges the session's bundled skills. Empty list when the spec bundles no skills or when the bundle cannot be loaded.",
"items": {
"$ref": "#/components/schemas/SkillSummary"
},
"title": "Skills",
"type": "array"
},
"terminals": {
"description": "Terminal names declared in the spec's `terminals:` block, in declaration order, e.g. `[\"shell\"]`. The Web UI gates its \"new terminal\" affordance on this list (creation is only offered for agents with terminal access) and offers these names as the launchable choices. Empty list when the spec declares no terminals or when the bundle cannot be loaded.",
"items": {
"type": "string"
},
"title": "Terminals",
"type": "array"
},
"updated_at": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"description": "Unix epoch timestamp of the last update, or `None` if never updated.",
"title": "Updated At"
},
"version": {
"default": 1,
"description": "Monotonic version counter. Starts at 1, incremented on each update.",
"format": "int64",
"title": "Version",
"type": "integer"
}
},
"required": [
"id",
"name",
"created_at"
],
"title": "AgentObject",
"type": "object"
},
"AutomaticSessionRenameRequest": {
"additionalProperties": false,
"description": "Proposed title for a framework or agent-initiated rename.",
"properties": {
"title": {
"maxLength": 100,
"minLength": 2,
"title": "Title",
"type": "string"
}
},
"required": [
"title"
],
"title": "AutomaticSessionRenameRequest",
"type": "object"
},
"AutomaticSessionRenameResponse": {
"description": "Result of a conditional automatic session rename.",
"properties": {
"reason": {
"anyOf": [
{
"enum": [
"not_top_level",
"no_seed",
"title_changed",
"generation_failed"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Reason"
},
"renamed": {
"title": "Renamed",
"type": "boolean"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Title"
}
},
"required": [
"renamed"
],
"title": "AutomaticSessionRenameResponse",
"type": "object"
},
"AutomationFailure": {
"description": "Latest sessionless failure, without prompts or raw error details.",
"properties": {
"error_code": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error Code"
},
"finished_at": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"title": "Finished At"
},
"run_id": {
"title": "Run Id",
"type": "string"
},
"scheduled_at": {
"format": "int64",
"title": "Scheduled At",
"type": "integer"
},
"task_id": {
"title": "Task Id",
"type": "string"
},
"task_name": {
"title": "Task Name",
"type": "string"
}
},
"required": [
"task_id",
"task_name",
"run_id",
"scheduled_at",
"finished_at",
"error_code"
],
"title": "AutomationFailure",
"type": "object"
},
"AutomationFailurePage": {
"description": "Failures from one bounded page of owned automations.",
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/AutomationFailure"
},
"title": "Data",
"type": "array"
},
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Next Cursor"
}
},
"required": [
"data",
"next_cursor"
],
"title": "AutomationFailurePage",
"type": "object"
},
"BackgroundTaskInfo": {
"description": "One still-running background shell or agent from the claude-native `Stop` hook.\n\nClaude Code leaves finished shells in the hook's `background_tasks`\narray, so the list surfaced here is filtered to the non-terminal ones \u2014\nits length matches the `background_task_count` tally. Every field is\nbest-effort: the hook shape is external, so an entry missing one field\nstill yields a usable row (e.g. a `description` with no `command`).",
"properties": {
"command": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Command the shell is running, e.g. `\"sleep 120\"`.",
"title": "Command"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Human-readable label, e.g. `\"Wait for CI\"`.",
"title": "Description"
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Opaque per-task identifier, e.g. `\"abc123\"`.",
"title": "Id"
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Per-task status, e.g. `\"running\"`.",
"title": "Status"
},
"type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Task kind, e.g. `\"shell\"` or `\"subagent\"`.",
"title": "Type"
}
},
"title": "BackgroundTaskInfo",
"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"
},
"Body_upload_session_github_attachment_v1_sessions__session_id__resources_github_attachments_post": {
"properties": {
"file": {
"contentMediaType": "application/octet-stream",
"title": "File",
"type": "string"
},
"pr_url": {
"title": "Pr Url",
"type": "string"
}
},
"required": [
"pr_url",
"file"
],
"title": "Body_upload_session_github_attachment_v1_sessions__session_id__resources_github_attachments_post",
"type": "object"
},
"BrandingInfo": {
"properties": {
"app_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "App Name"
},
"heading": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Heading"
},
"logos": {
"$ref": "#/components/schemas/BrandingLogosInfo"
},
"powered_by": {
"title": "Powered By",
"type": "boolean"
}
},
"required": [
"app_name",
"heading",
"logos",
"powered_by"
],
"title": "BrandingInfo",
"type": "object"
},
"BrandingLogosInfo": {
"properties": {
"favicon": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Favicon"
},
"loading": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Loading"
},
"main": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Main"
}
},
"required": [
"main",
"loading",
"favicon"
],
"title": "BrandingLogosInfo",
"type": "object"
},
"BrowserActionRequestEvent": {
"description": "Request that the desktop renderer perform one browser action.\n\nEmitted by the server `POST /v1/sessions/{id}/browser/action_request`\nroute when a runner-side `browser_*` tool dispatch needs the\nOmnigent desktop app's embedded browser to act. The event fans out\non the session stream to every subscribed renderer; each renderer\nfirst POSTs `/browser/action_claim/{action_id}` and only the\nwinning claimant executes the action and POSTs the result back to\n`/browser/action_result/{action_id}`. The claim lease prevents\ndouble execution when more than one renderer is subscribed.",
"properties": {
"action": {
"description": "The browser action to perform \u2014 the `browser_` tool name with the prefix stripped, e.g. `\"navigate\"`, `\"snapshot\"`, `\"click\"`, `\"type\"`, `\"screenshot\"`.",
"title": "Action",
"type": "string"
},
"action_id": {
"description": "Unique correlation id for this request, e.g. `\"baction_abc123\"`. Echoed on the claim and result routes.",
"title": "Action Id",
"type": "string"
},
"args": {
"additionalProperties": true,
"description": "Action arguments forwarded from the tool call, e.g. `{\"url\": \"https://example.com\"}`.",
"title": "Args",
"type": "object"
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "browser.action_request",
"description": "Always `\"browser.action_request\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"action_id",
"action",
"args"
],
"title": "BrowserActionRequestEvent",
"type": "object"
},
"CancelledEvent": {
"description": "Terminal event for a turn cancelled before completion.",
"properties": {
"response": {
"$ref": "#/components/schemas/ResponseObject",
"description": "The final response object with `status=\"cancelled\"`."
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "response.cancelled",
"description": "Always `\"response.cancelled\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"response"
],
"title": "CancelledEvent",
"type": "object"
},
"ChildSessionList": {
"description": "Paginated list of child sessions; `data` is a page of `ChildSessionSummary`.",
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/ChildSessionSummary"
},
"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": "ChildSessionList",
"type": "object"
},
"ChildSessionSummary": {
"description": "Summary of a sub-agent (child) session under a parent session.\n\nPowers `GET /v1/sessions/{id}/child_sessions`. Lets the web /\nREPL debug surface enumerate sub-agent calls spawned from a\nparent session without parsing parent `function_call_output`\nJSON handles (the legacy TUI Ctrl+O path). The endpoint is the\ncanonical \"historical truth\" source; the existing transient\n`session.created` SSE event handles live incremental updates.\n\nFields are derived from the child `Conversation` plus its\nlatest `Task` (newest by `created_at`).",
"properties": {
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Agent id recorded on the latest task, e.g. `\"ag_abc123\"`. `None` if the child has no tasks yet (rare \u2014 `_spawn_one` creates a task atomically with the conversation).",
"title": "Agent Id"
},
"agent_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Agent type recorded on the latest task, e.g. `\"researcher\"`. Mirrors the `tool` prefix in `title` and is provided alongside it because the title is a denormalized string while `agent_name` is the durable per-task value.",
"title": "Agent Name"
},
"busy": {
"default": false,
"description": "`True` when the child's session loop is live. Mirrors the algorithm used by `GET /v1/sessions/{id}` to compute `status`: read the live in-memory cache first (`\"running\"`/`\"waiting\"` \u2192 busy), and fall back to the latest task's status on cache miss (`\"queued\"` / `\"in_progress\"` \u2192 busy). For NO_DBOS sessions the tasks table is not populated during active runs, so the cache consult is what keeps the rail's \"Working\" badge correct.",
"title": "Busy",
"type": "boolean"
},
"created_at": {
"description": "Unix epoch timestamp of child creation.",
"format": "int64",
"title": "Created At",
"type": "integer"
},
"current_task_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Latest task id for the child (newest by `created_at`), e.g. `\"task_abc123\"`. `None` if no tasks exist.",
"title": "Current Task Id"
},
"current_task_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Status of the latest task, e.g. `\"completed\"`, `\"in_progress\"`, `\"failed\"`. `None` if no tasks exist.",
"title": "Current Task Status"
},
"depth": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"description": "Levels below the queried session, `1` for a direct child. Set only by `?descendants=true`, so a client can tell the server returned the whole subtree; `None` otherwise.",
"title": "Depth"
},
"id": {
"description": "Child conversation/session identifier, e.g. `\"conv_child123\"`.",
"title": "Id",
"type": "string"
},
"kind": {
"default": "sub_agent",
"description": "Conversation kind discriminator, always `\"sub_agent\"` for rows surfaced by this endpoint.",
"title": "Kind",
"type": "string"
},
"labels": {
"additionalProperties": {
"type": "string"
},
"description": "Session-scoped guardrails labels on the child conversation (mirrors `ConversationObject.labels`).",
"title": "Labels",
"type": "object"
},
"last_message_preview": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Single-line preview of the most recent message item in the child's conversation, truncated to ~150 chars with a trailing ellipsis when longer. `None` when the child has no message items yet (rare \u2014 the spawn tool immediately commits a user message). Lets the UI render a real-time \"what's the sub-agent saying right now\" line without fetching the child's full item history.",
"title": "Last Message Preview"
},
"last_task_error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"description": "Error details from the child's most recent failed run, e.g. `{\"code\": \"required_terminal_exited\", \"message\": \"...\"}`. `None` when the child has no durable failure detail. This is the typed projection of runner-owned failure labels; clients should not parse those labels directly.",
"title": "Last Task Error"
},
"object": {
"default": "child_session",
"description": "Fixed resource type, always `\"child_session\"`.",
"title": "Object",
"type": "string"
},
"parent_session_id": {
"description": "Parent conversation id (echo of the route's `session_id` path parameter), e.g. `\"conv_parent987\"`. Stable join key for clients that cache child rows across multiple parents.",
"title": "Parent Session Id",
"type": "string"
},
"pending_elicitations_count": {
"default": 0,
"description": "Number of approval / input prompts the child is currently blocked on, read from the server's `omnigent.runtime.pending_elicitations` index. `> 0` means the sub-agent is parked awaiting user input \u2014 the Agents rail renders an \"awaiting input\" badge so a fanned-out sub-agent that needs attention is visible without opening its chat. Mirrors `SessionListItem.pending_elicitations_count`.",
"format": "int64",
"title": "Pending Elicitations Count",
"type": "integer"
},
"routed_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Model this sub-agent runs on when one was pinned for it, e.g. `\"databricks-claude-opus-4-8\"`. Read from the child's `model_override` \u2014 the field intelligent routing writes when it picks a model for a spawned child. `None` when the child inherits the parent/spec model.",
"title": "Routed Model"
},
"routing_decision_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Identifier of the routing decision that produced `routed_model`, mirroring `RoutingDecisionData.decision_id`. Read from the child's `omnigent.routing.decision_id` label, stamped when routing pins the model. `None` when the child was not routed.",
"title": "Routing Decision Id"
},
"session_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Sub-agent instance name, the suffix of `title` after the first `\":\"`, e.g. `\"auth\"`. `None` if `title` is `None` or missing a colon.",
"title": "Session Name"
},
"task_summary": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Task Summary"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Sub-agent title, `\"{agent_type}:{session_name}\"` as written by `omnigent.tools.builtins.spawn._spawn_one`, e.g. `\"researcher:auth\"`. `None` only for legacy / malformed rows; the spawn path always sets it.",
"title": "Title"
},
"tool": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "UI-facing sub-agent label. For Omnigent-spawned children this is derived from the prefix of `title` before the first `\":\"`, e.g. `\"researcher\"`. For Codex-native children this is the Codex-assigned `agent_nickname` when available, then `agent_role`, then `\"Codex\"`. Falls back to the raw title for legacy / malformed rows; `None` only when `title` itself is `None` or empty.",
"title": "Tool"
},
"updated_at": {
"description": "Unix epoch timestamp of the child's most recent update.",
"format": "int64",
"title": "Updated At",
"type": "integer"
}
},
"required": [
"id",
"parent_session_id",
"created_at",
"updated_at"
],
"title": "ChildSessionSummary",
"type": "object"
},
"ClearCodexGoalResponse": {
"description": "Response body for `DELETE /v1/sessions/{id}/codex_goal`.",
"properties": {
"cleared": {
"description": "`True` when Codex removed an existing goal; `False` when no goal was present.",
"title": "Cleared",
"type": "boolean"
}
},
"required": [
"cleared"
],
"title": "ClearCodexGoalResponse",
"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`.",
"properties": {
"call_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Synthetic `call_id` the SDK uses to reconcile the local task; `None` when no pending tool call row exists for the task.",
"title": "Call Id"
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"task_id": {
"description": "Identifier of the client-side task being cancelled, e.g. `\"resp_async_abc\"`.",
"title": "Task Id",
"type": "string"
},
"type": {
"const": "response.client_task.cancel",
"description": "Always `\"response.client_task.cancel\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"task_id"
],
"title": "ClientTaskCancelEvent",
"type": "object"
},
"CodexGoalObject": {
"description": "Current Codex goal state for a Codex-native session.\n\nMirrors Codex app-server's `ThreadGoal` shape using Omnigent's\nsnake-case API convention. `created_at` and `updated_at` are optional\nbecause older app-server documentation examples omit them even though the\ncurrent protocol includes them.",
"properties": {
"created_at": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"description": "Unix timestamp when the goal was created, e.g. `1776272400`. `None` when not provided by Codex.",
"title": "Created At"
},
"objective": {
"description": "Goal objective text, e.g. `\"Finish the migration and keep tests green\"`.",
"title": "Objective",
"type": "string"
},
"status": {
"description": "Raw Codex goal lifecycle status, e.g. `\"active\"`.",
"title": "Status",
"type": "string"
},
"thread_id": {
"description": "Codex app-server thread id, e.g. `\"thr_123\"`.",
"title": "Thread Id",
"type": "string"
},
"time_used_seconds": {
"description": "Wall-clock seconds spent on this goal, e.g. `60`.",
"format": "int64",
"minimum": 0.0,
"title": "Time Used Seconds",
"type": "integer"
},
"token_budget": {
"anyOf": [
{
"exclusiveMinimum": 0.0,
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"description": "Optional token budget, e.g. `40000`. `None` means no explicit budget is set.",
"title": "Token Budget"
},
"tokens_used": {
"description": "Tokens spent while pursuing this goal, e.g. `1024`.",
"format": "int64",
"minimum": 0.0,
"title": "Tokens Used",
"type": "integer"
},
"updated_at": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"description": "Unix timestamp when the goal was last updated, e.g. `1776272460`. `None` when not provided by Codex.",
"title": "Updated At"
}
},
"required": [
"thread_id",
"objective",
"status",
"tokens_used",
"time_used_seconds"
],
"title": "CodexGoalObject",
"type": "object"
},
"CodexGoalResponse": {
"description": "Response body for reading or setting a Codex-native session goal.",
"properties": {
"goal": {
"anyOf": [
{
"$ref": "#/components/schemas/CodexGoalObject"
},
{
"type": "null"
}
],
"description": "Current goal state, or `None` when the session has no persisted Codex goal."
}
},
"required": [
"goal"
],
"title": "CodexGoalResponse",
"type": "object"
},
"CompactionCompletedEvent": {
"description": "Conversation history compaction has finished.\n\nEmitted after compaction completes \u2014 either by the server after\n`compact_conversation_now()` (explicit `/compact`), or by a\nharness that compacted its own internal context. Clients that\nrendered a \"Compacting\u2026\" spinner on\n`CompactionInProgressEvent` should upgrade it to the\npermanent \"Conversation compacted\" marker on this event.\n\nWhen emitted by a harness, `summary` and `summary_model`\nare populated so the runner can persist a compaction item for\nsession resume. When emitted by the server's explicit\n`/compact` path, those fields are `None`.",
"properties": {
"compacted_messages": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Compacted Messages"
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"summary": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Text summary of the compacted conversation, or `None` for server-side compaction (already persisted).",
"title": "Summary"
},
"summary_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Model used for summarization, or `None` if truncation-based or server-side.",
"title": "Summary Model"
},
"total_tokens": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Tiktoken estimate of the post-compaction message context size, e.g. `8421`. Used by clients to update the context-ring immediately without waiting for the next `response.completed` usage report. `None` when token counting is unavailable.",
"title": "Total Tokens"
},
"type": {
"const": "response.compaction.completed",
"description": "Always `\"response.compaction.completed\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type"
],
"title": "CompactionCompletedEvent",
"type": "object"
},
"CompactionData": {
"description": "Data payload for a compaction summary item.\n\nStored as a conversation item of `type=\"compaction\"`.\nThe summary covers all items from the start of the\nconversation (or the previous compaction item) through\nthe item identified by `last_item_id`.",
"properties": {
"compacted_messages": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Compacted Messages"
},
"last_item_id": {
"description": "The item ID (inclusive) of the last conversation item covered by this summary, e.g. `\"msg_abc123\"`. Items at positions <= this item are summarized and do not need to be loaded for prompt construction.",
"title": "Last Item Id",
"type": "string"
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The model used to generate the summary, e.g. `\"openai/gpt-4o\"`.",
"title": "Model"
},
"summary": {
"description": "The LLM-generated summary text covering all conversation items up through `last_item_id`, e.g. `\"User asked to analyze a dataset. Agent loaded data.csv and computed statistics.\"`.",
"title": "Summary",
"type": "string"
},
"token_count": {
"description": "Approximate token count of the summary text, for budget tracking, e.g. `342`.",
"format": "int64",
"title": "Token Count",
"type": "integer"
},
"window_id": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Opaque vendor compaction-window identifier. Current Codex writes a UUID string to `payload.window_id` on its `type == \"compacted\"` rollout JSONL record; older Codex rollouts used integer counters there.",
"title": "Window Id"
}
},
"required": [
"summary",
"last_item_id",
"token_count"
],
"title": "CompactionData",
"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 `CompactionInProgressEvent`\nshould dismiss it without leaving a permanent marker, since the\nconversation history was not modified.",
"properties": {
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "response.compaction.failed",
"description": "Always `\"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\nA long compaction is announced repeatedly (once per status poll), so\nclients must treat every event carrying the same `started_at` as one\ncompaction \u2014 refreshing their indicator rather than stacking another.",
"properties": {
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"started_at": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Unix epoch timestamp (seconds) when this compaction was first reported in progress. Stable across repeated progress events for the same compaction, so clients can anchor an elapsed counter to the true start \u2014 including after a page reload. `None` when the emitter does not track it.",
"title": "Started At"
},
"type": {
"const": "response.compaction.in_progress",
"description": "Always `\"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`omnigent.server.schemas.ResponseObject`.",
"properties": {
"response": {
"$ref": "#/components/schemas/ResponseObject",
"description": "The final response object with `status=\"completed\"`."
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "response.completed",
"description": "Always `\"response.completed\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"response"
],
"title": "CompletedEvent",
"type": "object"
},
"ConversationDeleted": {
"description": "Confirmation payload returned after deleting a conversation.",
"properties": {
"deleted": {
"default": true,
"description": "Always `True`.",
"title": "Deleted",
"type": "boolean"
},
"id": {
"description": "ID of the deleted conversation, e.g. `\"conv_abc123\"`.",
"title": "Id",
"type": "string"
},
"object": {
"default": "conversation.deleted",
"description": "Fixed resource type, always `\"conversation.deleted\"`.",
"title": "Object",
"type": "string"
}
},
"required": [
"id"
],
"title": "ConversationDeleted",
"type": "object"
},
"ConversationItem": {
"description": "A persisted item with a store-assigned ID.",
"properties": {
"created_at": {
"description": "Unix epoch timestamp of creation.",
"format": "int64",
"title": "Created At",
"type": "integer"
},
"created_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Identity of the human actor who authored this item, or `None` for agent/tool/system items and single-user mode. Lets owner and collaborator messages be distinguished.",
"title": "Created By"
},
"data": {
"anyOf": [
{
"$ref": "#/components/schemas/MessageData"
},
{
"$ref": "#/components/schemas/FunctionCallData"
},
{
"$ref": "#/components/schemas/FunctionCallOutputData"
},
{
"$ref": "#/components/schemas/ErrorData"
},
{
"$ref": "#/components/schemas/ReasoningData"
},
{
"$ref": "#/components/schemas/CompactionData"
},
{
"$ref": "#/components/schemas/NativeToolData"
},
{
"$ref": "#/components/schemas/ResourceEventData"
},
{
"$ref": "#/components/schemas/RoutingDecisionData"
},
{
"$ref": "#/components/schemas/SlashCommandData"
},
{
"$ref": "#/components/schemas/TerminalCommandData"
}
],
"description": "The typed data payload (MessageData, etc.).",
"title": "Data"
},
"id": {
"description": "Store-assigned item ID, e.g. `\"msg_abc123\"`.",
"title": "Id",
"type": "string"
},
"response_id": {
"description": "The task/response ID this item belongs to.",
"title": "Response Id",
"type": "string"
},
"status": {
"description": "Item status, e.g. `\"completed\"`.",
"title": "Status",
"type": "string"
},
"type": {
"description": "Item type, e.g. `\"message\"`, `\"function_call\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"id",
"type",
"status",
"response_id",
"created_at",
"data"
],
"title": "ConversationItem",
"type": "object"
},
"ConversationRef": {
"description": "Lightweight reference to a conversation, used in request and\nresponse bodies where only the conversation ID is needed.",
"properties": {
"id": {
"description": "Conversation identifier, e.g. `\"conv_abc123\"`.",
"title": "Id",
"type": "string"
}
},
"required": [
"id"
],
"title": "ConversationRef",
"type": "object"
},
"CopyFilesRequest": {
"description": "Request to copy files from a lineage ancestor into a session.\n\nThe destination session is the path parameter; `source_session_id`\nmust be a STRICT ancestor of the destination up its\n`parent_conversation_id` chain (spawn lineage) \u2014 the destination may\nnot name itself as the source. The copy creates new child-scoped rows \u2014\nit does not grant cross-session read access.",
"properties": {
"file_ids": {
"description": "Non-empty, unique ids of the source-owned files to copy, e.g. `[\"file_abc123\"]`.",
"items": {
"minLength": 1,
"type": "string"
},
"minItems": 1,
"title": "File Ids",
"type": "array",
"uniqueItems": true
},
"source_session_id": {
"description": "Session that owns the source files, e.g. `\"conv_parent\"`. Must be a strict ancestor of the destination.",
"title": "Source Session Id",
"type": "string"
}
},
"required": [
"source_session_id",
"file_ids"
],
"title": "CopyFilesRequest",
"type": "object"
},
"CreateDefaultPolicyRequest": {
"description": "Request body for `POST /v1/policies`.",
"properties": {
"factory_params": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"description": "Optional dict of kwargs passed to the handler when it is a factory function. Only valid for `type=\"python\"`, e.g. `{\"limit\": 10}`.",
"title": "Factory Params"
},
"handler": {
"description": "Dotted import path (python) or HTTPS URL (url), e.g. `\"github_mcp_policy.block_non_misc_push\"` or `\"https://example.com/policies/eval\"`.",
"title": "Handler",
"type": "string"
},
"name": {
"description": "Human-readable policy name. Must be globally unique, e.g. `\"block_non_feature_branch_push\"`.",
"title": "Name",
"type": "string"
},
"type": {
"description": "Handler discriminator: `\"python\"`, `\"url\"`,",
"title": "Type",
"type": "string"
}
},
"required": [
"name",
"type",
"handler"
],
"title": "CreateDefaultPolicyRequest",
"type": "object"
},
"CreateDirectoryRequest": {
"description": "Request body for `POST /v1/hosts/{host_id}/directories`.",
"properties": {
"path": {
"description": "Absolute path of the directory to create on the host machine, e.g. `\"/Users/corey/projects/new-app\"`, or a tilde-prefixed path (`\"~/scratch\"`) the host expands against its own process owner. Missing parents are created.",
"title": "Path",
"type": "string"
}
},
"required": [
"path"
],
"title": "CreateDirectoryRequest",
"type": "object"
},
"CreateProjectRequest": {
"additionalProperties": false,
"description": "Request body for `POST /v1/projects`.",
"properties": {
"config": {
"additionalProperties": true,
"description": "Optional default session settings (opaque JSON object). Omitted / empty stores no defaults.",
"title": "Config",
"type": "object"
},
"name": {
"description": "Human-readable project name. Trimmed; must be non-empty and at most 100 characters; unique among the caller's projects.",
"title": "Name",
"type": "string"
}
},
"required": [
"name"
],
"title": "CreateProjectRequest",
"type": "object"
},
"CreateScheduledTaskRequest": {
"additionalProperties": false,
"description": "Body for `POST /v1/scheduled-tasks`.",
"properties": {
"agent_id": {
"title": "Agent Id",
"type": "string"
},
"base_branch": {
"anyOf": [
{
"maxLength": 255,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"title": "Base Branch"
},
"execution_target": {
"default": "connected_host",
"title": "Execution Target",
"type": "string"
},
"host_id": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"title": "Host Id"
},
"max_cost_usd": {
"anyOf": [
{
"exclusiveMinimum": 0.0,
"format": "double",
"type": "number"
},
{
"type": "null"
}
],
"title": "Max Cost Usd"
},
"model_override": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model Override"
},
"name": {
"title": "Name",
"type": "string"
},
"permission_mode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Permission Mode"
},
"project_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Project Id"
},
"prompt": {
"title": "Prompt",
"type": "string"
},
"reasoning_effort": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Reasoning Effort"
},
"rrule": {
"title": "Rrule",
"type": "string"
},
"session_id": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"title": "Session Id"
},
"session_mode": {
"default": "new",
"enum": [
"new",
"continue"
],
"title": "Session Mode",
"type": "string"
},
"source_session_id": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Session Id"
},
"timezone": {
"default": "UTC",
"title": "Timezone",
"type": "string"
},
"workspace": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"title": "Workspace"
}
},
"required": [
"name",
"prompt",
"rrule",
"agent_id"
],
"title": "CreateScheduledTaskRequest",
"type": "object"
},
"CreateSessionPolicyRequest": {
"description": "Request body for `POST /v1/sessions/{session_id}/policies`.",
"properties": {
"factory_params": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"description": "Optional dict of kwargs passed to the handler when it is a factory function. Only valid for `type=\"python\"`, e.g. `{\"limit\": 10}`.",
"title": "Factory Params"
},
"handler": {
"description": "Dotted import path (python) or HTTPS URL (url), e.g. `\"github_mcp_policy.block_non_misc_push\"` or `\"https://example.com/policies/eval\"`.",
"title": "Handler",
"type": "string"
},
"name": {
"description": "Human-readable policy name. Must be unique within the session, e.g. `\"block_non_feature_branch_push\"`.",
"title": "Name",
"type": "string"
},
"type": {
"description": "Handler discriminator: `\"python\"` or `\"url\"`.",
"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`omnigent.server.schemas.ResponseObject` (status will\nbe `\"queued\"` or `\"in_progress\"` depending on whether the\ntask started immediately).",
"properties": {
"response": {
"$ref": "#/components/schemas/ResponseObject",
"description": "The newly-allocated response object."
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "response.created",
"description": "Always `\"response.created\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"response"
],
"title": "CreatedEvent",
"type": "object"
},
"DailyCost": {
"description": "One day's LLM spend for the daily timeline chart.",
"properties": {
"cost_usd": {
"default": 0.0,
"format": "double",
"title": "Cost Usd",
"type": "number"
},
"day": {
"title": "Day",
"type": "string"
}
},
"required": [
"day"
],
"title": "DailyCost",
"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`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`.",
"properties": {
"elicitation_id": {
"description": "Unique correlation id for this request \u2014 appears in the consumer's approval event payload, e.g. `\"elicit_abc123\"`.",
"title": "Elicitation Id",
"type": "string"
},
"method": {
"const": "elicitation/create",
"default": "elicitation/create",
"description": "MCP method literal \u2014 always `\"elicitation/create\"` (the value of `_MCP_ELICITATION_METHOD` in `omnigent/runtime/policies/approval.py`).",
"title": "Method",
"type": "string"
},
"params": {
"$ref": "#/components/schemas/ElicitationRequestParams",
"description": "The MCP-shaped params block carrying the prompt and (form-mode only) the requested schema."
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "response.elicitation_request",
"description": "Always `\"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 `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`.",
"properties": {
"content_preview": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Truncated preview of the underlying request payload (\u22641024 chars in current AP), for the consumer's renderer.",
"title": "Content Preview"
},
"message": {
"description": "Human-readable prompt the consumer renders, e.g. `\"Approve running 'rm -rf /tmp/cache'?\"`.",
"title": "Message",
"type": "string"
},
"mode": {
"default": "form",
"description": "MCP-standard discriminator. `\"form\"` collects structured input via `requestedSchema`; `\"url\"` directs upstream to an external URL for OAuth / out-of-band interaction.",
"enum": [
"form",
"url"
],
"title": "Mode",
"type": "string"
},
"phase": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Omnigent policy-engine phase the elicitation belongs to, e.g. `\"pre_tool_use\"`.",
"title": "Phase"
},
"policy_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Omnigent policy that triggered the elicitation, e.g. `\"approve_shell_commands\"`.",
"title": "Policy Name"
},
"requestedSchema": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "JSON-Schema dict for form mode (or `None` for url mode). camelCase preserved per MCP spec, e.g. `{\"type\": \"object\", \"properties\": {\"approve\": {\"type\": \"boolean\"}}}`.",
"title": "Requestedschema"
},
"target_session_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "AP session whose resolve endpoint owns this elicitation, e.g. `\"conv_child123\"`. Present when a child/sub-agent prompt is mirrored into an ancestor stream; `None` means resolve against the current session.",
"title": "Target Session Id"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "External URL for url mode (or `None` for form mode), e.g. `\"https://oauth.example.com/authorize?...\"`.",
"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 `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.",
"properties": {
"action": {
"anyOf": [
{
"enum": [
"accept",
"decline",
"cancel"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional MCP verdict recorded when the resolution carried a human decision (`\"accept\"` / `\"decline\"` / `\"cancel\"`). `None` for resolutions without a verdict \u2014 timeout, severed wait, or a runner that predates verdict carriage \u2014 so consumers can say \"no verdict was recorded\" rather than guessing one.",
"title": "Action"
},
"elicitation_id": {
"description": "Correlation id of the elicitation being cleared, e.g. `\"elicit_abc123\"`. Must match the id of a prior `ElicitationRequestEvent`.",
"title": "Elicitation Id",
"type": "string"
},
"reason": {
"anyOf": [
{
"const": "unanswered",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Why a verdict-less resolution happened, when known. `\"unanswered\"`: the hook stopped waiting (a severed poll never re-parked, the ask timed out) before anyone answered, so the prompt is gone rather than decided and the UI can say so instead of implying it was resolved elsewhere. `None` when a verdict is present or the reason is unknown.",
"title": "Reason"
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "response.elicitation_resolved",
"description": "Always `\"response.elicitation_resolved\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"elicitation_id"
],
"title": "ElicitationResolvedEvent",
"type": "object"
},
"ErrorData": {
"description": "Data for a persisted error banner item.\n\nThese items mirror `response.error` events so clients can render\nthe same error banner after reconnect / refresh. They are listed in\n`NON_CONTENT_ITEM_TYPES` because they are operator-visible\ntranscript metadata, not content the next agent turn should receive.",
"properties": {
"cause": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional one or two sentences explaining why it failed.",
"title": "Cause"
},
"code": {
"description": "Stable error classifier, e.g. `\"native_terminal_start_failed\"`.",
"title": "Code",
"type": "string"
},
"level": {
"anyOf": [
{
"enum": [
"error",
"info"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Rendering level. `\"info\"` renders the banner as a neutral notice (e.g. codex started a fresh thread) rather than a failure; `None` / `\"error\"` is the destructive default and is omitted from the wire so existing error items are unchanged.",
"title": "Level"
},
"message": {
"description": "Human-readable error message, e.g. `\"Native Codex requires the 'codex' CLI on PATH.\"`.",
"title": "Message",
"type": "string"
},
"remediation": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional concrete next step, e.g. the sign-in link and code; the card offers it as an action.",
"title": "Remediation"
},
"source": {
"description": "Error source, e.g. `\"execution\"`.",
"enum": [
"llm",
"execution",
"tool",
"harness"
],
"title": "Source",
"type": "string"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional short headline naming the failure, e.g. `\"Codex can't start until you sign in to Databricks\"`. Kept so the card reads the same after a reload as it did live.",
"title": "Title"
}
},
"required": [
"source",
"code",
"message"
],
"title": "ErrorData",
"type": "object"
},
"ErrorDetail": {
"description": "Machine-readable error information attached to a failed response.",
"properties": {
"cause": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional one/two-sentence explanation of why it failed. Paired with `title`.",
"title": "Cause"
},
"code": {
"description": "Error code string, e.g. `\"server_error\"`, `\"invalid_input\"`.",
"title": "Code",
"type": "string"
},
"message": {
"description": "Human-readable error description. Always populated; older clients render this verbatim.",
"title": "Message",
"type": "string"
},
"remediation": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional concrete next step to fix it, e.g. a command to run. `None` when there is no single clear fix.",
"title": "Remediation"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional short headline naming what went wrong, e.g. `\"Claude Code can't run as root\"`. Present when the runner recognized the failure (see `omnigent.runner.launch_failure`); lets the UI show a clear card title instead of the raw `code`.",
"title": "Title"
},
"undelivered": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "`True` when the harness reports it never received the message this turn carried (it failed before delivery), so the sender's queued copy is the only record of it; absent otherwise.",
"title": "Undelivered"
}
},
"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.",
"properties": {
"error": {
"$ref": "#/components/schemas/RetryErrorDetail",
"description": "Classified error description."
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"source": {
"description": "Origin of the error -- `\"llm\"` for LLM-call failures, `\"execution\"` for timeouts, `\"tool\"` for tool failures, `\"harness\"` for harness process failures.",
"enum": [
"llm",
"execution",
"tool",
"harness"
],
"title": "Source",
"type": "string"
},
"tool_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Tool identifier when `source == \"tool\"`; `None` for the other sources.",
"title": "Tool Name"
},
"type": {
"const": "response.error",
"description": "Always `\"response.error\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"source",
"error"
],
"title": "ErrorEvent",
"type": "object"
},
"ErrorResponse": {
"description": "The body every failed request carries: a single `error` object.\n\nMirrors what the FastAPI exception handler emits for an\n`~omnigent.errors.OmnigentError`, so documented error responses\nand the runtime envelope stay the same shape.",
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorDetail",
"description": "Machine-readable detail about the failure."
}
},
"required": [
"error"
],
"title": "ErrorResponse",
"type": "object"
},
"ExtensionAssetErrorResponse": {
"description": "Concise diagnostic for one unresolved browser bundle.",
"properties": {
"error": {
"title": "Error",
"type": "string"
},
"extension_id": {
"title": "Extension Id",
"type": "string"
},
"status": {
"const": "unresolved",
"default": "unresolved",
"title": "Status",
"type": "string"
}
},
"required": [
"extension_id",
"error"
],
"title": "ExtensionAssetErrorResponse",
"type": "object"
},
"ExtensionBrowserBundleResponse": {
"description": "Opaque browser-bundle availability and content-addressed asset URLs.",
"properties": {
"declared": {
"title": "Declared",
"type": "boolean"
},
"digest": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Digest"
},
"has_styles": {
"title": "Has Styles",
"type": "boolean"
},
"script_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Script Url"
},
"style_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Style Url"
}
},
"required": [
"declared",
"has_styles"
],
"title": "ExtensionBrowserBundleResponse",
"type": "object"
},
"ExtensionDiagnosticsResponse": {
"description": "Administrator view of accepted and rejected extensions.",
"properties": {
"asset_errors": {
"items": {
"$ref": "#/components/schemas/ExtensionAssetErrorResponse"
},
"title": "Asset Errors",
"type": "array"
},
"extensions": {
"items": {
"$ref": "#/components/schemas/ExtensionResponse"
},
"title": "Extensions",
"type": "array"
},
"load_errors": {
"items": {
"$ref": "#/components/schemas/ExtensionLoadErrorResponse"
},
"title": "Load Errors",
"type": "array"
},
"object": {
"const": "extension_diagnostics",
"default": "extension_diagnostics",
"title": "Object",
"type": "string"
}
},
"required": [
"extensions",
"load_errors",
"asset_errors"
],
"title": "ExtensionDiagnosticsResponse",
"type": "object"
},
"ExtensionListResponse": {
"description": "Public catalog of accepted extensions.",
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/ExtensionResponse"
},
"title": "Data",
"type": "array"
},
"object": {
"const": "list",
"default": "list",
"title": "Object",
"type": "string"
}
},
"required": [
"data"
],
"title": "ExtensionListResponse",
"type": "object"
},
"ExtensionLoadErrorResponse": {
"description": "Concise diagnostic for one rejected entry point.",
"properties": {
"entry_point": {
"title": "Entry Point",
"type": "string"
},
"error": {
"title": "Error",
"type": "string"
},
"status": {
"const": "rejected",
"default": "rejected",
"title": "Status",
"type": "string"
}
},
"required": [
"entry_point",
"error"
],
"title": "ExtensionLoadErrorResponse",
"type": "object"
},
"ExtensionPageResponse": {
"description": "One namespaced page contribution.",
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"route": {
"title": "Route",
"type": "string"
},
"title": {
"title": "Title",
"type": "string"
},
"view": {
"title": "View",
"type": "string"
}
},
"required": [
"id",
"title",
"route",
"view"
],
"title": "ExtensionPageResponse",
"type": "object"
},
"ExtensionPrimaryNavigationResponse": {
"description": "One primary-sidebar navigation contribution.",
"properties": {
"icon": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Icon"
},
"id": {
"title": "Id",
"type": "string"
},
"label": {
"title": "Label",
"type": "string"
},
"order": {
"format": "int64",
"title": "Order",
"type": "integer"
},
"page": {
"title": "Page",
"type": "string"
},
"when": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "When"
}
},
"required": [
"id",
"label",
"page",
"icon",
"order",
"when"
],
"title": "ExtensionPrimaryNavigationResponse",
"type": "object"
},
"ExtensionResponse": {
"description": "Public metadata for one accepted extension.",
"properties": {
"browser": {
"$ref": "#/components/schemas/ExtensionBrowserBundleResponse"
},
"display_name": {
"title": "Display Name",
"type": "string"
},
"distribution": {
"title": "Distribution",
"type": "string"
},
"extension_api": {
"format": "int64",
"title": "Extension Api",
"type": "integer"
},
"id": {
"title": "Id",
"type": "string"
},
"object": {
"const": "extension",
"default": "extension",
"title": "Object",
"type": "string"
},
"pages": {
"items": {
"$ref": "#/components/schemas/ExtensionPageResponse"
},
"title": "Pages",
"type": "array"
},
"permissions": {
"items": {
"type": "string"
},
"title": "Permissions",
"type": "array"
},
"primary_navigation": {
"items": {
"$ref": "#/components/schemas/ExtensionPrimaryNavigationResponse"
},
"title": "Primary Navigation",
"type": "array"
},
"status": {
"enum": [
"enabled",
"unavailable"
],
"title": "Status",
"type": "string"
},
"version": {
"title": "Version",
"type": "string"
}
},
"required": [
"id",
"display_name",
"distribution",
"version",
"extension_api",
"status",
"permissions",
"pages",
"primary_navigation",
"browser"
],
"title": "ExtensionResponse",
"type": "object"
},
"FailedEvent": {
"description": "Terminal event for a turn that ended with an error.\n\nCarries a `omnigent.server.schemas.FailedResponseObject`\nwhose `error` field describes the failure. Response metadata may\nbe absent when the failure occurs before response allocation.",
"properties": {
"response": {
"anyOf": [
{
"$ref": "#/components/schemas/ResponseObject"
},
{
"$ref": "#/components/schemas/FailedResponseObject"
}
],
"description": "The failure response object with `status=\"failed\"` and `error` populated.",
"title": "Response"
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"source": {
"default": "execution",
"description": "Where the fault originated -- `\"llm\"` for inference/context errors, `\"harness\"` for Claude Code/harness process failures, `\"execution\"` for runner configuration or infrastructure failures.",
"enum": [
"llm",
"execution",
"tool",
"harness"
],
"title": "Source",
"type": "string"
},
"type": {
"const": "response.failed",
"description": "Always `\"response.failed\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"response"
],
"title": "FailedEvent",
"type": "object"
},
"FailedResponseObject": {
"description": "Response payload for failures raised before response allocation.\n\nTransport and setup failures can terminate a turn before the harness has\nassigned the metadata required by `ResponseObject`. The remaining\nfields mirror that model so fully allocated failures retain their complete\nwire representation.",
"properties": {
"background": {
"default": false,
"description": "Whether the response was created as a background task.",
"title": "Background",
"type": "boolean"
},
"completed_at": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Unix epoch timestamp of completion, or `None`.",
"title": "Completed At"
},
"conversation": {
"anyOf": [
{
"$ref": "#/components/schemas/ConversationRef"
},
{
"type": "null"
}
],
"default": null,
"description": "Reference to the owning conversation, or `None`."
},
"created_at": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Unix epoch timestamp of creation, or `None` when the response failed before creation.",
"title": "Created At"
},
"error": {
"anyOf": [
{
"$ref": "#/components/schemas/ErrorDetail"
},
{
"type": "null"
}
],
"default": null,
"description": "Error details describing the failure, or `None`."
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Unique response identifier, e.g. `\"resp_abc123\"`, or `None` when allocation did not complete.",
"title": "Id"
},
"incomplete_details": {
"anyOf": [
{
"$ref": "#/components/schemas/IncompleteDetails"
},
{
"type": "null"
}
],
"default": null,
"description": "Incomplete-response details, or `None`."
},
"instructions": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Per-request instructions override, or `None`.",
"title": "Instructions"
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Agent name that produced the response, e.g. `\"research-agent\"`, or `None` when resolution did not complete.",
"title": "Model"
},
"object": {
"default": "response",
"description": "Fixed resource type, always `\"response\"`.",
"title": "Object",
"type": "string"
},
"output": {
"description": "Heterogeneous serialized output items accumulated before failure.",
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Output",
"type": "array"
},
"previous_response_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ID of the prior response, or `None`.",
"title": "Previous Response Id"
},
"reasoning": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Reasoning configuration, or `None`.",
"title": "Reasoning"
},
"status": {
"description": "Lifecycle status, normally `\"failed\"`.",
"title": "Status",
"type": "string"
},
"store": {
"default": true,
"description": "Whether the response is persisted.",
"title": "Store",
"type": "boolean"
},
"usage": {
"anyOf": [
{
"$ref": "#/components/schemas/Usage"
},
{
"type": "null"
}
],
"default": null,
"description": "Token usage statistics, or `None` when unavailable."
}
},
"required": [
"status"
],
"title": "FailedResponseObject",
"type": "object"
},
"FilesystemAttachmentsInfo": {
"description": "Which uploads native sessions receive as files, for client-side checks.",
"properties": {
"all_types": {
"title": "All Types",
"type": "boolean"
},
"extensions": {
"items": {
"type": "string"
},
"title": "Extensions",
"type": "array"
}
},
"required": [
"extensions",
"all_types"
],
"title": "FilesystemAttachmentsInfo",
"type": "object"
},
"FunctionCallData": {
"description": "Data for a function_call item.\n\n**Parameters**\n\n- `agent` \u2014 Agent name. Serialized as `\"model\"` in JSON.",
"properties": {
"arguments": {
"description": "JSON-encoded arguments string.",
"title": "Arguments",
"type": "string"
},
"call_id": {
"description": "Unique call identifier from the LLM, e.g. `\"call_abc123\"`.",
"title": "Call Id",
"type": "string"
},
"model": {
"title": "Model",
"type": "string"
},
"name": {
"description": "Tool function name, e.g. `\"search.web\"`.",
"title": "Name",
"type": "string"
},
"namespace": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Tool namespace the model emitted the call under, e.g. `\"container\"`. `None` for the default namespace. Harnesses that replay history must round-trip it with the call.",
"title": "Namespace"
}
},
"required": [
"model",
"name",
"arguments",
"call_id"
],
"title": "FunctionCallData",
"type": "object"
},
"FunctionCallOutputData": {
"description": "Data for a function_call_output item.",
"properties": {
"call_id": {
"description": "The call_id this output corresponds to, e.g. `\"call_abc123\"`.",
"title": "Call Id",
"type": "string"
},
"output": {
"description": "The tool's string result.",
"title": "Output",
"type": "string"
},
"subagent_return_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Native task id of an explicitly completed child.",
"title": "Subagent Return Id"
}
},
"required": [
"call_id",
"output"
],
"title": "FunctionCallOutputData",
"type": "object"
},
"GrantPermissionRequest": {
"description": "Request body for `PUT /v1/sessions/{id}/permissions`.",
"properties": {
"level": {
"description": "Numeric permission level: `1` = read, `2` = edit, `3` = manage.",
"format": "int64",
"maximum": 3.0,
"minimum": 1.0,
"title": "Level",
"type": "integer"
},
"user_id": {
"description": "The user to grant access to, e.g. `\"alice@example.com\"` or `\"__public__\"` for public access subject to the server's public permission ceiling.",
"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"
},
"HarnessEnvironment": {
"properties": {
"inherit": {
"title": "Inherit",
"type": "boolean"
},
"unset": {
"items": {
"type": "string"
},
"title": "Unset",
"type": "array"
},
"variables": {
"additionalProperties": {
"type": "string"
},
"title": "Variables",
"type": "object"
}
},
"required": [
"inherit",
"variables",
"unset"
],
"title": "HarnessEnvironment",
"type": "object"
},
"HarnessStartup": {
"description": "Launch metadata returned through the owner-only host API.",
"properties": {
"arg_count": {
"format": "int64",
"minimum": 0.0,
"title": "Arg Count",
"type": "integer"
},
"args": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Args"
},
"command": {
"title": "Command",
"type": "string"
},
"command_source": {
"enum": [
"env",
"config",
"default"
],
"title": "Command Source",
"type": "string"
},
"configured_args": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Configured Args"
},
"configured_command": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Configured Command"
},
"environment": {
"anyOf": [
{
"$ref": "#/components/schemas/HarnessEnvironment"
},
{
"type": "null"
}
]
},
"resolved_path": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Resolved Path"
}
},
"required": [
"command",
"resolved_path",
"command_source",
"arg_count"
],
"title": "HarnessStartup",
"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.",
"properties": {
"last_event_seq": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Sequence number of the last non- heartbeat event seen on the same stream, e.g. `42`. `None` before any user-visible event has fired (first heartbeat of the turn, before deltas land), or when the producer chose not to populate it.",
"title": "Last Event Seq"
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"server_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO 8601 UTC timestamp at emission, e.g. `\"2026-04-27T15:30:00Z\"`. `None` when the producer chose not to populate it (legacy emitters).",
"title": "Server Time"
},
"type": {
"const": "response.heartbeat",
"description": "Always `\"response.heartbeat\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type"
],
"title": "HeartbeatEvent",
"type": "object"
},
"HostModelOptionsResponse": {
"description": "Pre-launch model choices resolved by a host harness.\n\n`error` carries the host's reason for an empty catalog \u2014 a probe that\nfailed on the host is not a transport failure, so the request still\nsucceeds and the picker can say WHY it is empty instead of a generic\n\"Models unavailable\".",
"properties": {
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"models": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Models",
"type": "array"
},
"routable_models": {
"items": {
"type": "string"
},
"title": "Routable Models",
"type": "array"
}
},
"required": [
"models",
"routable_models"
],
"title": "HostModelOptionsResponse",
"type": "object"
},
"ImportFailureRef": {
"description": "One session that could not be imported, with a user-facing reason.\n\n`external_session_id` / `source` name the source session when known (a\nhost that reports only a count leaves them `None`); `reason` explains the\nfailure so the UI can show it instead of an anonymous \"N failed\". Also the\nshape of each `{\"event\": \"failed\", ...}` line on the stream endpoint.",
"properties": {
"external_session_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "External Session Id"
},
"reason": {
"title": "Reason",
"type": "string"
},
"source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source"
}
},
"required": [
"reason"
],
"title": "ImportFailureRef",
"type": "object"
},
"ImportItemInput": {
"description": "One normalized existing Omnigent item received from the CLI.",
"properties": {
"data": {
"additionalProperties": true,
"title": "Data",
"type": "object"
},
"response_id": {
"maxLength": 64,
"minLength": 1,
"title": "Response Id",
"type": "string"
},
"type": {
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"response_id",
"data"
],
"title": "ImportItemInput",
"type": "object"
},
"ImportSessionRequest": {
"description": "Request body for importing one local harness session.\n\n`project_id` files the imported session into a first-class project the\ncaller owns, with the same ownership, default-fill, and mismatch-warning\nsemantics as `POST /v1/sessions`.",
"properties": {
"archived": {
"default": false,
"title": "Archived",
"type": "boolean"
},
"external_session_id": {
"maxLength": 128,
"minLength": 1,
"title": "External Session Id",
"type": "string"
},
"force": {
"default": false,
"title": "Force",
"type": "boolean"
},
"host_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Host Id"
},
"items": {
"items": {
"$ref": "#/components/schemas/ImportItemInput"
},
"maxItems": 100000,
"minItems": 1,
"title": "Items",
"type": "array"
},
"project_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Project Id"
},
"source": {
"enum": [
"claude",
"codex",
"kimi",
"kiro",
"opencode",
"pi",
"qwen"
],
"title": "Source",
"type": "string"
},
"title": {
"anyOf": [
{
"maxLength": 512,
"type": "string"
},
{
"type": "null"
}
],
"title": "Title"
},
"workspace": {
"anyOf": [
{
"maxLength": 2048,
"type": "string"
},
{
"type": "null"
}
],
"title": "Workspace"
}
},
"required": [
"source",
"external_session_id",
"items"
],
"title": "ImportSessionRequest",
"type": "object"
},
"ImportSessionResponse": {
"description": "Result of importing or locating one source session.",
"properties": {
"item_count": {
"format": "int64",
"title": "Item Count",
"type": "integer"
},
"session_id": {
"title": "Session Id",
"type": "string"
},
"status": {
"const": "imported",
"title": "Status",
"type": "string"
}
},
"required": [
"session_id",
"status",
"item_count"
],
"title": "ImportSessionResponse",
"type": "object"
},
"ImportedSessionRef": {
"description": "One freshly imported session: its new id plus display title.\n\n`title` is `None` when the session has no native title and no first user\nmessage to synthesize from; the UI falls back to a placeholder. Also the\nshape of each `{\"event\": \"session\", ...}` line the\n`/imports/local/stream` endpoint emits.",
"properties": {
"session_id": {
"title": "Session Id",
"type": "string"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Title"
}
},
"required": [
"session_id"
],
"title": "ImportedSessionRef",
"type": "object"
},
"InProgressEvent": {
"description": "Event emitted once the task transitions to in-progress.\n\nAlways follows `response.created` (and `response.queued`\nfor background tasks).",
"properties": {
"response": {
"$ref": "#/components/schemas/ResponseObject",
"description": "The response object with `status=\"in_progress\"`."
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "response.in_progress",
"description": "Always `\"response.in_progress\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"response"
],
"title": "InProgressEvent",
"type": "object"
},
"IncompleteDetails": {
"description": "Details explaining why a response is incomplete.",
"properties": {
"reason": {
"description": "Reason the response stopped early, e.g. `\"max_output_tokens\"`, `\"max_tool_calls\"`.",
"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).",
"properties": {
"response": {
"$ref": "#/components/schemas/ResponseObject",
"description": "The final response object with `status=\"incomplete\"` and `incomplete_details` populated describing the reason."
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "response.incomplete",
"description": "Always `\"response.incomplete\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"response"
],
"title": "IncompleteEvent",
"type": "object"
},
"LaunchRunnerRequest": {
"description": "Request body for `POST /v1/hosts/{host_id}/runners`.",
"properties": {
"git": {
"anyOf": [
{
"$ref": "#/components/schemas/SessionGitOptions"
},
{
"type": "null"
}
],
"description": "Optional git worktree options. In create mode the server creates a worktree for a new branch off `workspace` on the host and binds the runner to it (the fork-resume path; mirrors `POST /v1/sessions`). In bind mode (`existing_worktree=True`) `workspace` already IS a worktree \u2014 no worktree is created; `branch_name` is recorded as the session's `git_branch` for display and opt-in cleanup. `None` binds `workspace` directly. `host_id` is always present (it is in the path), so no host check is needed here."
},
"session_env_handoff_id": {
"anyOf": [
{
"maxLength": 64,
"pattern": "^[A-Za-z0-9_-]+$",
"type": "string"
},
{
"type": "null"
}
],
"description": "Opaque, non-secret ID of the launching CLI's local forwarded-environment file, relayed to the host so only this launch's runner consumes it. `None` when nothing is forwarded.",
"title": "Session Env Handoff Id"
},
"session_id": {
"description": "Session to bind the new runner to, e.g. `\"conv_abc123\"`.",
"title": "Session Id",
"type": "string"
},
"workspace": {
"description": "Absolute path on the host machine to use as the runner's working directory, e.g. `\"/Users/corey/projects/frontend\"`. When `git` is set, this is interpreted as the source repository directory and the runner starts in the created worktree instead.",
"title": "Workspace",
"type": "string"
}
},
"required": [
"session_id",
"workspace"
],
"title": "LaunchRunnerRequest",
"type": "object"
},
"LiveMCPServerStatus": {
"description": "One MCP server's connection inside a session's running harness.",
"properties": {
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The harness's reason for a failed connection, or `None`.",
"title": "Error"
},
"name": {
"description": "Server name as the harness reports it, e.g. `\"docs\"` or `\"plugin:tools:docs\"`.",
"title": "Name",
"type": "string"
},
"scope": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Where the harness loaded the server from, e.g. `\"user\"`.",
"title": "Scope"
},
"status": {
"description": "`\"connected\"`, `\"failed\"`, `\"needs-auth\"`, `\"pending\"`, or `\"disabled\"`; other harness values pass through.",
"title": "Status",
"type": "string"
}
},
"required": [
"name",
"status"
],
"title": "LiveMCPServerStatus",
"type": "object"
},
"LocalImportRequest": {
"description": "Request to import local harness sessions from a host.\n\nUnlike `/imports` (the CLI posts already-normalized items), the server\nasks the chosen host to read + normalize its own transcripts over the\ntunnel \u2014 the transcripts live on the caller's machine, not the server. A\nsupplied `session_id` loads that exact session without enumerating local\nhistory.",
"properties": {
"host_id": {
"title": "Host Id",
"type": "string"
},
"limit": {
"default": 10,
"format": "int64",
"maximum": 1000.0,
"minimum": 1.0,
"title": "Limit",
"type": "integer"
},
"session_id": {
"anyOf": [
{
"maxLength": 128,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"title": "Session Id"
},
"source": {
"anyOf": [
{
"enum": [
"claude",
"codex",
"kimi",
"kiro",
"opencode",
"pi",
"qwen"
],
"type": "string"
},
{
"const": "all",
"type": "string"
}
],
"title": "Source"
}
},
"required": [
"host_id",
"source"
],
"title": "LocalImportRequest",
"type": "object"
},
"LocalImportResponse": {
"description": "Buffered batch result for `POST /v1/imports/local`.\n\nThe streaming `/imports/local/stream` endpoint carries the same tally on\nits terminal `{\"event\": \"done\", ...}` line instead.",
"properties": {
"already_imported": {
"format": "int64",
"title": "Already Imported",
"type": "integer"
},
"failed": {
"format": "int64",
"title": "Failed",
"type": "integer"
},
"failures": {
"items": {
"$ref": "#/components/schemas/ImportFailureRef"
},
"title": "Failures",
"type": "array"
},
"imported": {
"format": "int64",
"title": "Imported",
"type": "integer"
},
"sessions": {
"items": {
"$ref": "#/components/schemas/ImportedSessionRef"
},
"title": "Sessions",
"type": "array"
}
},
"required": [
"imported",
"already_imported",
"failed",
"sessions"
],
"title": "LocalImportResponse",
"type": "object"
},
"MCPServerPatch": {
"additionalProperties": false,
"description": "Partial MCP declaration; omitted fields and credential keys are preserved.",
"properties": {
"args": {
"anyOf": [
{
"items": {
"type": "string"
},
"maxItems": 64,
"type": "array"
},
{
"type": "null"
}
],
"title": "Args"
},
"command": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Command"
},
"description": {
"anyOf": [
{
"maxLength": 512,
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"env": {
"anyOf": [
{
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Env"
},
"headers": {
"anyOf": [
{
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Headers"
},
"transport": {
"anyOf": [
{
"enum": [
"http",
"stdio"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Transport"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Url"
}
},
"title": "MCPServerPatch",
"type": "object"
},
"MCPServerSummary": {
"description": "Safe subset of an MCP server's configuration for API exposure.\n\nHeader values are redacted (`\"[REDACTED]\"`) so callers can see\nwhich headers are configured without leaking the actual secrets.\n`env` is still fully excluded.",
"properties": {
"args": {
"description": "Command-line arguments for `transport=\"stdio\"` servers, e.g. `[\"mcp-server-github\"]`. Empty list when unset.",
"items": {
"type": "string"
},
"title": "Args",
"type": "array"
},
"command": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Executable path for `transport=\"stdio\"` servers, e.g. `\"uvx\"`. `None` for http servers.",
"title": "Command"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional free-text description from the spec, e.g. `\"GitHub MCP server\"`. `None` when unset.",
"title": "Description"
},
"headers": {
"additionalProperties": {
"type": "string"
},
"description": "HTTP headers for `transport=\"http\"` servers. Values are always `\"[REDACTED]\"`; only the key names are exposed.",
"title": "Headers",
"type": "object"
},
"name": {
"description": "Server name as declared in the agent spec, e.g. `\"github\"`.",
"title": "Name",
"type": "string"
},
"transport": {
"description": "Transport type \u2014 `\"stdio\"` or `\"http\"`.",
"title": "Transport",
"type": "string"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "HTTP(S) endpoint URL for `transport=\"http\"` servers, e.g. `\"https://mcp.example.com/sse\"`. `None` for stdio servers.",
"title": "Url"
}
},
"required": [
"name",
"transport"
],
"title": "MCPServerSummary",
"type": "object"
},
"McpServerEnabledRequest": {
"properties": {
"enabled": {
"title": "Enabled",
"type": "boolean"
},
"harness": {
"enum": [
"claude",
"codex"
],
"title": "Harness",
"type": "string"
},
"plugin": {
"anyOf": [
{
"maxLength": 1024,
"type": "string"
},
{
"type": "null"
}
],
"title": "Plugin"
},
"server": {
"maxLength": 1024,
"minLength": 1,
"title": "Server",
"type": "string"
},
"source_id": {
"anyOf": [
{
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Id"
}
},
"required": [
"harness",
"server",
"enabled"
],
"title": "McpServerEnabledRequest",
"type": "object"
},
"McpServerEnabledResponse": {
"properties": {
"server": {
"$ref": "#/components/schemas/McpServerSummary"
}
},
"required": [
"server"
],
"title": "McpServerEnabledResponse",
"type": "object"
},
"McpServerStartup": {
"description": "One MCP server's startup state within a `session.mcp_startup` event.",
"properties": {
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Failure detail when `status == \"failed\"`, e.g. `\"handshaking with MCP server failed\"`. `None` otherwise.",
"title": "Error"
},
"status": {
"description": "Latest startup state reported by the harness, mirroring Codex's `McpServerStartupState` enum.",
"enum": [
"starting",
"ready",
"failed",
"cancelled"
],
"title": "Status",
"type": "string"
}
},
"required": [
"status"
],
"title": "McpServerStartup",
"type": "object"
},
"McpServerSummary": {
"description": "An MCP server a harness loads on the host, without secrets.",
"properties": {
"auth_status": {
"anyOf": [
{
"enum": [
"connected",
"sign_in_required"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Account state reported by the host's sign-in manager: `connected` or `sign_in_required`; `None` when nothing reports one.",
"title": "Auth Status"
},
"enabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enabled"
},
"harness": {
"description": "Harness family that loads it: `claude`, `codex`, `cursor`, or `pi`.",
"title": "Harness",
"type": "string"
},
"locked": {
"default": false,
"title": "Locked",
"type": "boolean"
},
"managed": {
"default": false,
"description": "Whether an organization pins this server for every user on the host (Claude Code's enterprise MCP config), so it is not the user's to edit.",
"title": "Managed",
"type": "boolean"
},
"name": {
"description": "Server name as configured, e.g. `\"github\"`.",
"title": "Name",
"type": "string"
},
"plugin": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Plugin that bundles the server, e.g. `\"figma\"`.",
"title": "Plugin"
},
"scope": {
"const": "user",
"description": "Config scope; always `user` today.",
"title": "Scope",
"type": "string"
},
"sign_in_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Where the user finishes signing in; only with `sign_in_required`, and only an http(s) URL carrying no credentials.",
"title": "Sign In Url"
},
"source_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Id"
},
"transport": {
"description": "`stdio` for a local process, `http` for a remote server.",
"enum": [
"stdio",
"http"
],
"title": "Transport",
"type": "string"
},
"url_host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Hostname of a remote server, e.g. `\"mcp.linear.app\"`.",
"title": "Url Host"
}
},
"required": [
"name",
"harness",
"transport",
"scope"
],
"title": "McpServerSummary",
"type": "object"
},
"McpServersResponse": {
"description": "User-level MCP servers discovered on a host.",
"properties": {
"mcp_servers": {
"items": {
"$ref": "#/components/schemas/McpServerSummary"
},
"title": "Mcp Servers",
"type": "array"
}
},
"required": [
"mcp_servers"
],
"title": "McpServersResponse",
"type": "object"
},
"McpToolSummary": {
"properties": {
"description": {
"anyOf": [
{
"maxLength": 300,
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"name": {
"maxLength": 256,
"title": "Name",
"type": "string"
}
},
"required": [
"name"
],
"title": "McpToolSummary",
"type": "object"
},
"McpToolsRequest": {
"properties": {
"harness": {
"enum": [
"claude",
"codex",
"cursor"
],
"title": "Harness",
"type": "string"
},
"plugin": {
"anyOf": [
{
"maxLength": 1024,
"type": "string"
},
{
"type": "null"
}
],
"title": "Plugin"
},
"server": {
"maxLength": 1024,
"minLength": 1,
"title": "Server",
"type": "string"
},
"source_id": {
"anyOf": [
{
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Id"
}
},
"required": [
"harness",
"server"
],
"title": "McpToolsRequest",
"type": "object"
},
"McpToolsResponse": {
"properties": {
"connection": {
"enum": [
"connected",
"needs_auth",
"unreachable",
"timeout",
"unsupported"
],
"title": "Connection",
"type": "string"
},
"tools": {
"items": {
"$ref": "#/components/schemas/McpToolSummary"
},
"maxItems": 500,
"title": "Tools",
"type": "array"
},
"truncated": {
"title": "Truncated",
"type": "boolean"
}
},
"required": [
"tools",
"connection",
"truncated"
],
"title": "McpToolsResponse",
"type": "object"
},
"MessageData": {
"description": "Data for a message item (user or assistant).\n\n**Parameters**\n\n- `agent` \u2014 Agent name (required for assistant messages, absent for user). Serialized as `\"model\"` in JSON.",
"properties": {
"content": {
"description": "Heterogeneous content blocks, e.g. `[{\"type\": \"input_text\", \"text\": \"Hello\"}]`.",
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Content",
"type": "array"
},
"interrupted": {
"default": false,
"description": "`True` when an assistant message is a durable partial response from an interrupted external-native turn, e.g. Codex `turn/completed` with status `\"interrupted\"`. Defaults to `False` and is omitted from serialized payloads in that case.",
"title": "Interrupted",
"type": "boolean"
},
"is_meta": {
"default": false,
"description": "`True` for durable context that must be replayed to agents but hidden from user-facing transcripts, e.g. injected skill instructions. Defaults to `False` and is omitted from serialized payloads in that case.",
"title": "Is Meta",
"type": "boolean"
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model"
},
"phase": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Assistant-only harness label for the message, e.g. Codex `\"commentary\"` (progress), `\"partial_answer\"` or `\"final_answer\"`. Stored as given so clients can act on values added later; `None` when unset, not a string, or longer than 64 characters.",
"title": "Phase"
},
"role": {
"description": "`\"user\"` or `\"assistant\"`.",
"enum": [
"user",
"assistant"
],
"title": "Role",
"type": "string"
},
"startup_options": {
"anyOf": [
{
"$ref": "#/components/schemas/StartupInputOptions"
},
{
"type": "null"
}
]
},
"stream_message_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Native live-preview stream finalized by this assistant message. Persisted so reconnect snapshots can suppress delayed preview chunks after the authoritative item.",
"title": "Stream Message Id"
},
"subagent_return_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Native task id of an explicitly completed child.",
"title": "Subagent Return Id"
},
"user_authored": {
"default": false,
"description": "Originated from an explicit user action; may be server-expanded, e.g. skill instructions. Independent of `is_meta`; client-settable by convention, not a trust signal. Also exempts the message from legacy markup cleanup on import.",
"title": "User Authored",
"type": "boolean"
}
},
"required": [
"role",
"content"
],
"title": "MessageData",
"type": "object"
},
"ModelUsage": {
"description": "Cumulative token/cost usage attributed to a single LLM model.\n\nOne value in the `usage_by_model` map on `SessionResponse` /\n`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.",
"properties": {
"cache_creation_input_tokens": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"description": "Cumulative tokens written to the prompt cache, e.g. `2000`. `None` when not recorded.",
"title": "Cache Creation Input Tokens"
},
"cache_read_input_tokens": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"description": "Cumulative tokens read from the prompt cache, e.g. `8000`. `None` when not recorded.",
"title": "Cache Read Input Tokens"
},
"input_tokens": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"description": "Cumulative non-cached input (prompt) tokens for this model over the subtree, e.g. `12000`. `None` when not recorded.",
"title": "Input Tokens"
},
"output_tokens": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"description": "Cumulative output (completion) tokens, e.g. `3400`. `None` when not recorded.",
"title": "Output Tokens"
},
"total_cost_usd": {
"anyOf": [
{
"format": "double",
"type": "number"
},
{
"type": "null"
}
],
"description": "Cumulative USD spend attributed to this model, e.g. `0.42`. Present **only when this model's turns were priced** (same \"priced \u27fa key present\" contract as the session total); `None` when the model is unpriced, so the sum of priced per-model costs equals the session `total_cost_usd`.",
"title": "Total Cost Usd"
},
"total_tokens": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"description": "Cumulative total tokens (counts cache buckets too, as the harness reports), e.g. `15400`. `None` when not recorded.",
"title": "Total Tokens"
}
},
"title": "ModelUsage",
"type": "object"
},
"NativeModelOption": {
"additionalProperties": true,
"description": "One runner-owned native model-picker row.",
"properties": {
"defaultReasoningEffort": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Defaultreasoningeffort"
},
"displayName": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Displayname"
},
"id": {
"title": "Id",
"type": "string"
},
"isDefault": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Isdefault"
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model"
},
"supportedReasoningEfforts": {
"items": {
"$ref": "#/components/schemas/NativeReasoningEffortOption"
},
"title": "Supportedreasoningefforts",
"type": "array"
}
},
"required": [
"id"
],
"title": "NativeModelOption",
"type": "object"
},
"NativeReasoningEffortOption": {
"additionalProperties": true,
"description": "Reasoning-effort metadata advertised by a native model catalog.",
"properties": {
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"reasoningEffort": {
"title": "Reasoningeffort",
"type": "string"
}
},
"required": [
"reasoningEffort"
],
"title": "NativeReasoningEffortOption",
"type": "object"
},
"NativeToolData": {
"description": "A provider-native tool output item (e.g. `web_search_call`).\n\nThese are executed server-side by the LLM provider and returned\nas opaque dicts. Agent-plane persists and replays them so the\nLLM sees its own tool results on subsequent iterations.",
"properties": {
"item": {
"additionalProperties": true,
"description": "The raw dict from the Responses API output, e.g. `{\"type\": \"web_search_call\", \"id\": \"ws_abc\", \"status\": \"completed\", \"action\": {...}}`.",
"title": "Item",
"type": "object"
}
},
"required": [
"item"
],
"title": "NativeToolData",
"type": "object"
},
"NativeUsageBaseline": {
"description": "Own-session cumulative usage for resuming a native usage reporter.\n\nExcludes spawned sessions. Input includes cache reads, matching the native\nusage event contract rather than the display's separate token buckets.",
"properties": {
"cumulative_cache_read_input_tokens": {
"default": 0,
"format": "int64",
"minimum": 0.0,
"title": "Cumulative Cache Read Input Tokens",
"type": "integer"
},
"cumulative_cost_usd": {
"anyOf": [
{
"format": "double",
"minimum": 0.0,
"type": "number"
},
{
"type": "null"
}
],
"title": "Cumulative Cost Usd"
},
"cumulative_input_tokens": {
"default": 0,
"format": "int64",
"minimum": 0.0,
"title": "Cumulative Input Tokens",
"type": "integer"
},
"cumulative_output_tokens": {
"default": 0,
"format": "int64",
"minimum": 0.0,
"title": "Cumulative Output Tokens",
"type": "integer"
}
},
"title": "NativeUsageBaseline",
"type": "object"
},
"OpenFileRequest": {
"additionalProperties": false,
"description": "A workspace-relative file to show, without reading or modifying it.",
"properties": {
"path": {
"description": "Workspace-relative file path.",
"maxLength": 4096,
"minLength": 1,
"title": "Path",
"type": "string"
}
},
"required": [
"path"
],
"title": "OpenFileRequest",
"type": "object"
},
"OpenFileResponse": {
"description": "Delivery to live streams is not an acknowledgement from a file viewer.",
"properties": {
"subscribers": {
"format": "int64",
"title": "Subscribers",
"type": "integer"
}
},
"required": [
"subscribers"
],
"title": "OpenFileResponse",
"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.",
"properties": {
"content_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "MIME content type if the annotation supplied one, e.g. `\"application/pdf\"`. `None` otherwise.",
"title": "Content Type"
},
"file_id": {
"description": "Identifier of the materialized file, e.g. `\"file_abc123\"`.",
"title": "File Id",
"type": "string"
},
"filename": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Original filename if the annotation supplied one, e.g. `\"report.pdf\"`. `None` otherwise.",
"title": "Filename"
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "response.output_file.done",
"description": "Always `\"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}`.",
"properties": {
"item": {
"additionalProperties": true,
"description": "The completed item dict. Heterogeneous and item-type-specific; see `omnigent/entities/conversation.py` for the per-type `*Data` shapes that drive serialization. Example for a function_call item: `{\"id\": \"fc_abc123\", \"type\": \"function_call\", \"status\": \"action_required\", \"name\": \"search.web\", \"arguments\": \"{\\\"q\\\": \\\"foo\\\"}\", \"call_id\": \"call_xyz\"}`.",
"title": "Item",
"type": "object"
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "response.output_item.done",
"description": "Always `\"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`.",
"properties": {
"delta": {
"description": "The text fragment for this chunk, e.g. `\"Hello\"`.",
"title": "Delta",
"type": "string"
},
"final": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional provider completion marker for the message.",
"title": "Final"
},
"index": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "0-based chunk order within the message, e.g. `3`. Used to suppress repeated chunks; `None` for in-process streaming.",
"title": "Index"
},
"message_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "For native terminal streaming, the provider's stable per-message id, e.g. `\"2ca51d97-2f0f-493a-aed7-85a5b56c5747\"`. `None` for ordinary in-process task streaming, where deltas group by the active response.",
"title": "Message Id"
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "response.output_text.delta",
"description": "Always `\"response.output_text.delta\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"delta"
],
"title": "OutputTextDeltaEvent",
"type": "object"
},
"PermissionObject": {
"description": "API representation of a session permission grant.",
"properties": {
"conversation_id": {
"description": "The session, e.g. `\"conv_abc123\"`.",
"title": "Conversation Id",
"type": "string"
},
"level": {
"description": "Numeric permission level (1=read, 2=edit, 3=manage).",
"format": "int64",
"title": "Level",
"type": "integer"
},
"user_id": {
"description": "The grantee, e.g. `\"alice@example.com\"`.",
"title": "User Id",
"type": "string"
}
},
"required": [
"user_id",
"conversation_id",
"level"
],
"title": "PermissionObject",
"type": "object"
},
"PickerInfo": {
"description": "How a deployment curates what the New Chat picker shows.\n\nDisplay only: it narrows the picker, never what exists. Every agent stays\nseeded, forkable and reachable through the API.",
"properties": {
"default_agent_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Name a fresh New Chat starts on, or `None`. A user's remembered pick wins over it.",
"title": "Default Agent Name"
},
"restrict_to_agent_names": {
"default": [],
"description": "Names the picker may offer; empty means the full roster.",
"items": {
"type": "string"
},
"title": "Restrict To Agent Names",
"type": "array"
}
},
"title": "PickerInfo",
"type": "object"
},
"PluginAsset": {
"properties": {
"id": {
"pattern": "^[0-9a-f]{64}$",
"title": "Id",
"type": "string"
},
"name": {
"maxLength": 256,
"title": "Name",
"type": "string"
}
},
"required": [
"id",
"name"
],
"title": "PluginAsset",
"type": "object"
},
"PluginSummary": {
"description": "Installed Claude plugin metadata, without paths or executable configuration.",
"properties": {
"description": {
"anyOf": [
{
"maxLength": 1000,
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"enabled": {
"title": "Enabled",
"type": "boolean"
},
"harness": {
"const": "claude",
"title": "Harness",
"type": "string"
},
"has_commands": {
"title": "Has Commands",
"type": "boolean"
},
"has_hooks": {
"title": "Has Hooks",
"type": "boolean"
},
"id": {
"anyOf": [
{
"pattern": "^[0-9a-f]{64}$",
"type": "string"
},
{
"type": "null"
}
],
"title": "Id"
},
"marketplace": {
"maxLength": 256,
"title": "Marketplace",
"type": "string"
},
"mcp_entries": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/PluginAsset"
},
"maxItems": 128,
"type": "array"
},
{
"type": "null"
}
],
"title": "Mcp Entries"
},
"mcp_servers": {
"items": {
"maxLength": 256,
"type": "string"
},
"maxItems": 128,
"title": "Mcp Servers",
"type": "array"
},
"name": {
"maxLength": 256,
"minLength": 1,
"title": "Name",
"type": "string"
},
"skill_entries": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/PluginAsset"
},
"maxItems": 128,
"type": "array"
},
{
"type": "null"
}
],
"title": "Skill Entries"
},
"skills": {
"items": {
"maxLength": 256,
"type": "string"
},
"maxItems": 128,
"title": "Skills",
"type": "array"
},
"version": {
"anyOf": [
{
"maxLength": 256,
"type": "string"
},
{
"type": "null"
}
],
"title": "Version"
}
},
"required": [
"harness",
"name",
"marketplace",
"enabled",
"skills",
"mcp_servers",
"has_hooks",
"has_commands"
],
"title": "PluginSummary",
"type": "object"
},
"PluginsResponse": {
"description": "Installed plugins reported by the host (Claude only).",
"properties": {
"plugins": {
"items": {
"$ref": "#/components/schemas/PluginSummary"
},
"maxItems": 128,
"title": "Plugins",
"type": "array"
}
},
"required": [
"plugins"
],
"title": "PluginsResponse",
"type": "object"
},
"PolicyDeniedEvent": {
"description": "Signal that a policy DENY was enforced on a native harness turn.\n\nA native harness (Claude Code, Codex, ...) routes each tool call and\nprompt through Omnigent's policy engine via the vendor command-hook\n(`POST /v1/sessions/{id}/policies/evaluate`). The DENY verdict is\nreturned synchronously to that hook, so unlike the SDK/wrap path there is\nno stream-visible signal that a native action was blocked \u2014 only the\n*effect* (the blocked tool never runs). This event surfaces the decision\nitself on the session stream so observers (the web UI, the capability\nbench) can see a native DENY as a positive signal rather than infer it\nfrom an absence.\n\nFire-and-forget and observational: it does not gate the turn (the hook\nresponse already did that) and carries no correlation id.",
"properties": {
"conversation_id": {
"description": "Session/conversation id the DENY applies to, e.g. `\"conv_abc123\"`.",
"title": "Conversation Id",
"type": "string"
},
"phase": {
"default": "",
"description": "The policy phase the DENY landed on, e.g. `\"tool_call\"`.",
"title": "Phase",
"type": "string"
},
"reason": {
"default": "",
"description": "Human-readable deny reason from the deciding policy, e.g. `\"Blocked by policy.\"`.",
"title": "Reason",
"type": "string"
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "response.policy_denied",
"description": "Always `\"response.policy_denied\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"conversation_id"
],
"title": "PolicyDeniedEvent",
"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.",
"properties": {
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Short detail string about the policy implementation. For function policies: the callable dotted path. For prompt policies: the first line of the prompt. `None` when not available.",
"title": "Description"
},
"name": {
"description": "Policy name as declared in the agent spec, e.g. `\"block_long_sleep\"`.",
"title": "Name",
"type": "string"
},
"on": {
"description": "List of phase selectors the policy fires on, e.g. `[\"tool_call\"]` or `[\"request\", \"response\"]`.",
"items": {
"type": "string"
},
"title": "On",
"type": "array"
},
"type": {
"description": "Policy type discriminator \u2014 `\"function\"` or `\"prompt\"`.",
"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).",
"properties": {
"idle": {
"default": false,
"description": "Whether every stream the user holds reports an idle (backgrounded) tab. The web greys idle viewers' avatars.",
"title": "Idle",
"type": "boolean"
},
"joined_at": {
"description": "ISO 8601 UTC timestamp of when the user joined, e.g. `\"2026-06-10T17:00:00Z\"`. Stable across reconnects within the server's leave-grace window.",
"title": "Joined At",
"type": "string"
},
"user_id": {
"description": "The viewer's authenticated identity, e.g. `\"alice@example.com\"`. Never the reserved single-user `\"local\"` sentinel \u2014 presence only tracks distinct human actors (see `attribution_user`).",
"title": "User Id",
"type": "string"
}
},
"required": [
"user_id",
"joined_at"
],
"title": "PresenceViewer",
"type": "object"
},
"ProjectOrderRequest": {
"description": "Rank owned project IDs; unranked projects append in discovery order.\n\nNull selects alphabetical mode without erasing the remembered manual IDs.\nThe serialized preference must fit in 65,535 bytes after compression and\nframing; lists below the 10,000-ID limit can still exceed this byte limit.",
"properties": {
"ordered_project_ids": {
"anyOf": [
{
"items": {
"maxLength": 32,
"minLength": 32,
"pattern": "^[0-9a-f]{32}$",
"type": "string"
},
"maxItems": 10000,
"type": "array"
},
{
"type": "null"
}
],
"title": "Ordered Project Ids"
}
},
"required": [
"ordered_project_ids"
],
"title": "ProjectOrderRequest",
"type": "object"
},
"ProjectOrderResponse": {
"description": "Current sorting mode and the manual order retained in either mode.",
"properties": {
"ordered_project_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Ordered Project Ids"
},
"sort_mode": {
"enum": [
"alphabetical",
"manual"
],
"title": "Sort Mode",
"type": "string"
}
},
"required": [
"sort_mode",
"ordered_project_ids"
],
"title": "ProjectOrderResponse",
"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.",
"properties": {
"response": {
"$ref": "#/components/schemas/ResponseObject",
"description": "The response object with `status=\"queued\"`."
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "response.queued",
"description": "Always `\"response.queued\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"response"
],
"title": "QueuedEvent",
"type": "object"
},
"ReadStatePutRequest": {
"additionalProperties": false,
"description": "Request body for `PUT /v1/sessions/{session_id}/read-state`.\n\nSets the *calling user's* read tracking for one session. Mirrors the\ntwo values the web client keeps per session: a \"last seen\" wall-clock\nbaseline (seconds since epoch) and an explicit \"marked unread\"\noverride. The unread dot shows when `updated_at > last_seen` and the\nsession is finished; `unread` separately pins the override so the\nthread the user is *viewing* (or a running one) still surfaces the dot\nwhere the automatic \"seen\" logic would otherwise suppress it.",
"properties": {
"last_seen": {
"description": "Wall-clock baseline in seconds, e.g. `1717000000`. Marking seen sets this to \"now\"; marking unread pins it to `updated_at - 1` so the row reads unseen.",
"format": "int64",
"title": "Last Seen",
"type": "integer"
},
"unread": {
"description": "Whether this session is explicitly flagged unread for the caller.",
"title": "Unread",
"type": "boolean"
}
},
"required": [
"last_seen",
"unread"
],
"title": "ReadStatePutRequest",
"type": "object"
},
"ReasoningData": {
"description": "Data for a reasoning item.\n\n**Parameters**\n\n- `agent` \u2014 Agent name. Serialized as `\"model\"` in JSON.",
"properties": {
"content": {
"anyOf": [
{
"items": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Raw reasoning content blocks, or `None` if redacted.",
"title": "Content"
},
"encrypted_content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Encrypted reasoning content, or `None`.",
"title": "Encrypted Content"
},
"model": {
"title": "Model",
"type": "string"
},
"summary": {
"description": "Summary text blocks, e.g. `[{\"type\": \"summary_text\", \"text\": \"...\"}]`.",
"items": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"title": "Summary",
"type": "array"
}
},
"required": [
"model",
"summary"
],
"title": "ReasoningData",
"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`.",
"properties": {
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "response.reasoning.started",
"description": "Always `\"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`.",
"properties": {
"delta": {
"description": "The summary text fragment, e.g. `\"Will use the search tool to gather context.\"`.",
"title": "Delta",
"type": "string"
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "response.reasoning_summary_text.delta",
"description": "Always `\"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`.",
"properties": {
"delta": {
"description": "The reasoning text fragment, e.g. `\"Considering the user's intent...\"`.",
"title": "Delta",
"type": "string"
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "response.reasoning_text.delta",
"description": "Always `\"response.reasoning_text.delta\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"delta"
],
"title": "ReasoningTextDeltaEvent",
"type": "object"
},
"ReconnectLiveMCPServerRequest": {
"additionalProperties": false,
"description": "Body for reconnecting one MCP server in a session's running harness.",
"properties": {
"name": {
"maxLength": 256,
"minLength": 1,
"pattern": "\\S",
"title": "Name",
"type": "string"
}
},
"required": [
"name"
],
"title": "ReconnectLiveMCPServerRequest",
"type": "object"
},
"ResetSessionModelOverrideRequest": {
"additionalProperties": false,
"description": "Reset a launch-time model selection only while that selection is current.",
"properties": {
"expected_model_override": {
"minLength": 1,
"title": "Expected Model Override",
"type": "string"
}
},
"required": [
"expected_model_override"
],
"title": "ResetSessionModelOverrideRequest",
"type": "object"
},
"ResetSessionModelOverrideResponse": {
"description": "Whether the launch-time selection was still current and was cleared.",
"properties": {
"reset": {
"title": "Reset",
"type": "boolean"
}
},
"required": [
"reset"
],
"title": "ResetSessionModelOverrideResponse",
"type": "object"
},
"ResourceEventData": {
"description": "Data payload for a persisted resource lifecycle event.\n\nThese items are written to the conversation store when a\nsession resource is created or deleted, so reconnecting\nclients can discover resource history without replaying the\nlive SSE stream. The agent loop filters them out of the\nLLM's message context (they are metadata, not conversation\ncontent).",
"properties": {
"event_type": {
"description": "The SSE event type literal, e.g. `\"session.resource.created\"` or `\"session.resource.deleted\"`.",
"title": "Event Type",
"type": "string"
},
"resource": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"description": "Full resource object dict for `created` events. `None` for `deleted` events.",
"title": "Resource"
},
"resource_id": {
"description": "Opaque id of the affected resource, e.g. `\"terminal_bash_s1\"` or `\"file_abc123\"`.",
"title": "Resource Id",
"type": "string"
},
"resource_type": {
"description": "Kind of resource, e.g. `\"terminal\"`, `\"file\"`, `\"environment\"`.",
"title": "Resource Type",
"type": "string"
}
},
"required": [
"event_type",
"resource_id",
"resource_type"
],
"title": "ResourceEventData",
"type": "object"
},
"ResponseObject": {
"description": "API representation of a response (task execution result).",
"properties": {
"background": {
"default": false,
"description": "Whether this response was created as a background task.",
"title": "Background",
"type": "boolean"
},
"completed_at": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Unix epoch timestamp of completion, or `None` if not yet complete.",
"title": "Completed At"
},
"conversation": {
"anyOf": [
{
"$ref": "#/components/schemas/ConversationRef"
},
{
"type": "null"
}
],
"default": null,
"description": "Reference to the owning conversation."
},
"created_at": {
"description": "Unix epoch timestamp of creation.",
"format": "int64",
"title": "Created At",
"type": "integer"
},
"error": {
"anyOf": [
{
"$ref": "#/components/schemas/ErrorDetail"
},
{
"type": "null"
}
],
"default": null,
"description": "Error details if the response failed."
},
"id": {
"description": "Unique response identifier, e.g. `\"resp_abc123\"`.",
"title": "Id",
"type": "string"
},
"incomplete_details": {
"anyOf": [
{
"$ref": "#/components/schemas/IncompleteDetails"
},
{
"type": "null"
}
],
"default": null,
"description": "Details if the response is incomplete (e.g. hit token limit)."
},
"instructions": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Per-request system instructions composed additively with the agent's own, or `None`.",
"title": "Instructions"
},
"model": {
"description": "Agent name that produced this response, e.g. `\"research-agent\"`.",
"title": "Model",
"type": "string"
},
"object": {
"default": "response",
"description": "Fixed resource type, always `\"response\"`.",
"title": "Object",
"type": "string"
},
"output": {
"description": "Heterogeneous output items (messages, reasoning, function_calls) serialized as dicts; shape varies by item type. Empty for non-completed responses.",
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Output",
"type": "array"
},
"previous_response_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ID of the prior response in the conversation thread, or `None` for the first turn.",
"title": "Previous Response Id"
},
"reasoning": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Reasoning configuration, e.g. `{\"effort\": \"medium\"}`.",
"title": "Reasoning"
},
"status": {
"description": "Lifecycle status, one of `\"queued\"`, `\"in_progress\"`, `\"completed\"`, `\"failed\"`, `\"incomplete\"`, `\"cancelled\"`.",
"title": "Status",
"type": "string"
},
"store": {
"default": true,
"description": "Whether this response is persisted. Always `True`.",
"title": "Store",
"type": "boolean"
},
"usage": {
"anyOf": [
{
"$ref": "#/components/schemas/Usage"
},
{
"type": "null"
}
],
"default": null,
"description": "Token usage statistics, or `None` if not yet available."
}
},
"required": [
"id",
"status",
"model",
"created_at"
],
"title": "ResponseObject",
"type": "object"
},
"RetryErrorDetail": {
"description": "Error block carried by `RetryEvent` and `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.",
"properties": {
"code": {
"description": "Stable error classifier, e.g. `\"timeout\"`, `\"rate_limit\"`.",
"title": "Code",
"type": "string"
},
"detail": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional provider-specific structured fields (e.g. `{\"status_code\": 429, \"retry_after\": 5}`); `None` when the classifier had no extra context.",
"title": "Detail"
},
"message": {
"description": "Human-readable summary, e.g. `\"Connection timed out after 30s\"`.",
"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`.",
"properties": {
"attempt": {
"description": "1-based count of the upcoming attempt (i.e. attempt that will run AFTER this delay), e.g. `2` for the first retry.",
"format": "int64",
"title": "Attempt",
"type": "integer"
},
"delay_seconds": {
"description": "Seconds the producer will sleep before retrying, rounded to two decimals, e.g. `1.5`.",
"format": "double",
"title": "Delay Seconds",
"type": "number"
},
"error": {
"$ref": "#/components/schemas/RetryErrorDetail",
"description": "Classified error description for the failure being retried."
},
"max_attempts": {
"description": "Total tries allowed by the retry policy, e.g. `3`. Lets clients render \"attempt 2 of 3\".",
"format": "int64",
"title": "Max Attempts",
"type": "integer"
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"source": {
"description": "Origin of the retried failure \u2014 `\"llm\"` for LLM-call retries, `\"tool\"` for tool-call retries.",
"enum": [
"llm",
"tool"
],
"title": "Source",
"type": "string"
},
"tool_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Tool identifier when `source == \"tool\"`, e.g. `\"search.web\"`. `None` for LLM retries.",
"title": "Tool Name"
},
"type": {
"const": "response.retry",
"description": "Always `\"response.retry\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"source",
"attempt",
"max_attempts",
"delay_seconds",
"error"
],
"title": "RetryEvent",
"type": "object"
},
"RoutingDecisionData": {
"description": "Data payload for an intelligent model-router decision item.\n\nEmitted by the server-side smart routing path at the START of an\nadvised turn and persisted\nas a display-only transcript item so the model the router chose shows\nin the conversation flow the moment the turn begins. Listed in\n`NON_CONTENT_ITEM_TYPES` so the agent loop's history filter\nskips it \u2014 the brain never sees (or answers) its own router note. The\nrunner's harness-input builder also drops every non\nmessage/function_call type, a second guarantee it stays out of the\nmodel's context.",
"properties": {
"agent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Agent"
},
"applied": {
"description": "`True` when the brain actually ran on `model` this turn (optimize mode, no user pin); `False` when the router only WOULD have picked it (advise/shadow mode, or a user model pin won) \u2014 the UI renders \"would have picked\".",
"title": "Applied",
"type": "boolean"
},
"attempted_override": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Model the spawning agent asked for and the router overrode, e.g. `\"databricks-gpt-5-5\"` \u2014 an LLM-supplied `args.model` on a child session, or a native spawn's own `requested_model`. `None` when nothing was asked for, or when the router's pick names the same arm as the ask.",
"title": "Attempted Override"
},
"decision_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Router decision identifier, e.g. `\"3f1c\u2026\"`. Correlates the transcript item with the routing telemetry event and the child-sessions API row. `None` for decisions made before decision ids existed.",
"title": "Decision Id"
},
"harness": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Harness the decision applies to, e.g. `\"claude-native\"` or `\"codex\"`. `None` when the decision picked a model only (no harness dimension).",
"title": "Harness"
},
"model": {
"description": "The concrete brain model the router chose, e.g. `\"databricks-claude-opus-4-8\"`.",
"title": "Model",
"type": "string"
},
"rationale": {
"description": "The router's one-line explanation, shown as muted secondary text, e.g. `\"Multi-file refactor needs deep reasoning.\"`.",
"title": "Rationale",
"type": "string"
},
"raw_model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The router-vocabulary pick before resolution to a servable catalog id, e.g. `\"gpt-5-6-sol\"`. `None` when the pick needed no resolution.",
"title": "Raw Model"
},
"router_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Which router produced the decision \u2014 `\"databricks-aigw\"` for the external AI-Gateway `task_v1` service, `\"oss-llm\"` for the built-in judge. Deliberately a plain `str` rather than a `Literal`: a source added later must still round-trip through stored rows and the wire instead of failing validation. `None` on rows written before the field existed.",
"title": "Router Source"
},
"scope": {
"default": "turn",
"description": "What the decision governs \u2014 `\"session\"` (auto-harness session routing), `\"turn\"` (per-turn routing), `\"child_session\"` (an Omnigent-spawned sub-agent) or `\"native_subagent\"` (a Task / `spawn_agent` spawn routed inside the harness). Defaults to `\"turn\"` so rows persisted before this field deserialize.",
"enum": [
"session",
"turn",
"child_session",
"native_subagent"
],
"title": "Scope",
"type": "string"
},
"task_description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Human label of the task/spawn this decision governed, e.g. `\"Research auth flows\"` \u2014 what ties a fan-out's decision to its sub-agent when every spawn shares one `agent` type. `None` when the spawn carried none, and on rows written before the field existed.",
"title": "Task Description"
}
},
"required": [
"model",
"applied",
"rationale"
],
"title": "RoutingDecisionData",
"type": "object"
},
"SandboxProfileSummary": {
"additionalProperties": false,
"description": "Public session/host reference; execution identity stays on the server.",
"properties": {
"description": {
"default": "",
"maxLength": 500,
"title": "Description",
"type": "string"
},
"id": {
"pattern": "^[a-z0-9][a-z0-9_-]{0,63}$",
"title": "Id",
"type": "string"
},
"name": {
"maxLength": 100,
"minLength": 1,
"title": "Name",
"type": "string"
},
"provider": {
"maxLength": 32,
"minLength": 1,
"title": "Provider",
"type": "string"
},
"revision": {
"maxLength": 64,
"minLength": 1,
"title": "Revision",
"type": "string"
}
},
"required": [
"id",
"name",
"revision",
"provider"
],
"title": "SandboxProfileSummary",
"type": "object"
},
"SandboxProfilesResponse": {
"properties": {
"default_profile_ids": {
"additionalProperties": {
"type": "string"
},
"default": {},
"title": "Default Profile Ids",
"type": "object"
},
"managed_providers": {
"items": {
"type": "string"
},
"title": "Managed Providers",
"type": "array"
},
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Next Cursor"
},
"profiles": {
"items": {
"$ref": "#/components/schemas/SandboxProfileSummary"
},
"title": "Profiles",
"type": "array"
}
},
"required": [
"profiles",
"managed_providers",
"next_cursor"
],
"title": "SandboxProfilesResponse",
"type": "object"
},
"SandboxStatus": {
"description": "Managed-sandbox launch progress for a `host_type=\"managed\"` session.\n\nCarried on the session snapshot only while the session's\nbackground sandbox launch is in flight or has failed; `None`\nfor sessions without a managed launch and once the launch\nsucceeds (the session then looks like any host-bound session).",
"properties": {
"details": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "What the user needs to do when `stage == \"action_required\"`, e.g. `\"Sign in on your laptop.\"`. `None` otherwise.",
"title": "Details"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Failure detail when `stage == \"failed\"`, e.g. `\"managed sandbox launch failed: spend limit reached\"`. `None` otherwise.",
"title": "Error"
},
"provider": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Sandbox provider being launched, e.g. `\"arclet\"`, or `None` when unknown.",
"title": "Provider"
},
"stage": {
"description": "Current launch stage, e.g. `\"provisioning\"` \u2014 one of `SandboxLaunchStage`, in pipeline order: `provisioning` (creating the sandbox; `action_required` while it also needs the user to act) \u2192 `cloning` (cloning the repository workspace; skipped when the session has none) \u2192 `starting` (starting the in-sandbox host) \u2192 `connecting` (launching the agent runner) \u2192 `ready` / `failed`.",
"enum": [
"provisioning",
"action_required",
"cloning",
"starting",
"connecting",
"ready",
"failed"
],
"title": "Stage",
"type": "string"
}
},
"required": [
"stage"
],
"title": "SandboxStatus",
"type": "object"
},
"ScheduledRunLogContext": {
"description": "Occurrence identity retained with a saved prompt across replica changes.",
"properties": {
"run_id": {
"title": "Run Id",
"type": "string"
},
"scheduled_at": {
"format": "int64",
"title": "Scheduled At",
"type": "integer"
},
"session_mode": {
"title": "Session Mode",
"type": "string"
},
"target": {
"title": "Target",
"type": "string"
},
"task_id": {
"title": "Task Id",
"type": "string"
},
"task_workspace_id": {
"format": "int64",
"title": "Task Workspace Id",
"type": "integer"
},
"trigger_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Trigger Key"
}
},
"required": [
"task_id",
"run_id",
"task_workspace_id",
"scheduled_at",
"target",
"session_mode"
],
"title": "ScheduledRunLogContext",
"type": "object"
},
"SendCommentsRequest": {
"description": "Request body for `POST .../comments/send`.",
"properties": {
"comment_ids": {
"description": "IDs of comments to send.",
"items": {
"type": "string"
},
"title": "Comment Ids",
"type": "array"
},
"instruction": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional custom instruction prefix; defaults to the standard \"Please address the following file review comments.\" header.",
"title": "Instruction"
}
},
"required": [
"comment_ids"
],
"title": "SendCommentsRequest",
"type": "object"
},
"ServerInfoResponse": {
"properties": {
"accounts_enabled": {
"title": "Accounts Enabled",
"type": "boolean"
},
"agent_config_edit": {
"default": false,
"title": "Agent Config Edit",
"type": "boolean"
},
"agent_detail": {
"default": false,
"title": "Agent Detail",
"type": "boolean"
},
"agent_install": {
"default": false,
"title": "Agent Install",
"type": "boolean"
},
"archive_worktree_cleanup": {
"default": true,
"title": "Archive Worktree Cleanup",
"type": "boolean"
},
"automation_trigger_poll_minutes": {
"default": 10,
"format": "int64",
"title": "Automation Trigger Poll Minutes",
"type": "integer"
},
"automations_enabled": {
"default": false,
"title": "Automations Enabled",
"type": "boolean"
},
"branding": {
"$ref": "#/components/schemas/BrandingInfo"
},
"databricks_features": {
"title": "Databricks Features",
"type": "boolean"
},
"dictation_available": {
"title": "Dictation Available",
"type": "boolean"
},
"durable_initial_input": {
"default": false,
"title": "Durable Initial Input",
"type": "boolean"
},
"enabled_connections": {
"items": {
"type": "string"
},
"title": "Enabled Connections",
"type": "array"
},
"features": {
"additionalProperties": {
"type": "boolean"
},
"title": "Features",
"type": "object"
},
"filesystem_attachments": {
"anyOf": [
{
"$ref": "#/components/schemas/FilesystemAttachmentsInfo"
},
{
"type": "null"
}
]
},
"harness_install_enabled": {
"title": "Harness Install Enabled",
"type": "boolean"
},
"installable_harnesses": {
"items": {
"type": "string"
},
"title": "Installable Harnesses",
"type": "array"
},
"login_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Login Url"
},
"managed_sandboxes_enabled": {
"title": "Managed Sandboxes Enabled",
"type": "boolean"
},
"needs_setup": {
"title": "Needs Setup",
"type": "boolean"
},
"picker": {
"$ref": "#/components/schemas/PickerInfo",
"default": {
"restrict_to_agent_names": []
}
},
"public_sharing_enabled": {
"title": "Public Sharing Enabled",
"type": "boolean"
},
"public_sharing_max_level": {
"default": "read",
"enum": [
"read",
"edit"
],
"title": "Public Sharing Max Level",
"type": "string"
},
"request_managed_sandbox_host_id": {
"default": true,
"title": "Request Managed Sandbox Host Id",
"type": "boolean"
},
"sandbox_provider": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Sandbox Provider"
},
"sandbox_provider_capabilities": {
"additionalProperties": {
"additionalProperties": {
"type": "boolean"
},
"type": "object"
},
"default": {},
"title": "Sandbox Provider Capabilities",
"type": "object"
},
"sandbox_providers": {
"items": {
"type": "string"
},
"title": "Sandbox Providers",
"type": "array"
},
"scheduled_task_approval_skipping_modes": {
"default": true,
"title": "Scheduled Task Approval Skipping Modes",
"type": "boolean"
},
"scheduled_task_harness_settings": {
"default": true,
"title": "Scheduled Task Harness Settings",
"type": "boolean"
},
"scheduled_task_inbox": {
"default": false,
"title": "Scheduled Task Inbox",
"type": "boolean"
},
"scheduled_task_projects": {
"default": false,
"title": "Scheduled Task Projects",
"type": "boolean"
},
"scheduled_task_sandbox_workspaces": {
"default": true,
"title": "Scheduled Task Sandbox Workspaces",
"type": "boolean"
},
"scheduled_task_session_modes": {
"default": true,
"title": "Scheduled Task Session Modes",
"type": "boolean"
},
"scheduled_task_source_sessions": {
"default": true,
"title": "Scheduled Task Source Sessions",
"type": "boolean"
},
"scheduled_task_subhour": {
"default": true,
"title": "Scheduled Task Subhour",
"type": "boolean"
},
"scheduled_task_worktrees": {
"default": true,
"title": "Scheduled Task Worktrees",
"type": "boolean"
},
"server_version": {
"title": "Server Version",
"type": "string"
},
"session_bundle_model_override": {
"default": true,
"title": "Session Bundle Model Override",
"type": "boolean"
},
"session_bundle_workspaces": {
"default": true,
"title": "Session Bundle Workspaces",
"type": "boolean"
},
"session_claude_sdk_clear": {
"default": false,
"title": "Session Claude Sdk Clear",
"type": "boolean"
},
"session_event_types": {
"default": [],
"items": {
"type": "string"
},
"title": "Session Event Types",
"type": "array"
},
"session_fork_workspaces": {
"default": true,
"title": "Session Fork Workspaces",
"type": "boolean"
},
"session_list_scoped_archives": {
"default": true,
"title": "Session List Scoped Archives",
"type": "boolean"
},
"session_move_source_checks": {
"default": false,
"title": "Session Move Source Checks",
"type": "boolean"
},
"session_pull_requests": {
"default": false,
"title": "Session Pull Requests",
"type": "boolean"
},
"session_search_scope": {
"default": true,
"title": "Session Search Scope",
"type": "boolean"
},
"session_title_instructions": {
"default": false,
"title": "Session Title Instructions",
"type": "boolean"
},
"sharing_mode": {
"enum": [
"on",
"read_only",
"restricted_read_only",
"off"
],
"title": "Sharing Mode",
"type": "string"
},
"sibling_session_destinations": {
"default": "any_host",
"enum": [
"current_host",
"current_host_or_new_sandbox",
"any_host"
],
"title": "Sibling Session Destinations",
"type": "string"
},
"sibling_sessions": {
"default": false,
"title": "Sibling Sessions",
"type": "boolean"
},
"single_user": {
"title": "Single User",
"type": "boolean"
},
"smart_routing_enabled": {
"title": "Smart Routing Enabled",
"type": "boolean"
},
"smart_routing_sources": {
"$ref": "#/components/schemas/SmartRoutingSourcesInfo"
}
},
"required": [
"accounts_enabled",
"single_user",
"login_url",
"needs_setup",
"databricks_features",
"managed_sandboxes_enabled",
"sandbox_provider",
"sandbox_providers",
"enabled_connections",
"sharing_mode",
"public_sharing_enabled",
"server_version",
"smart_routing_enabled",
"smart_routing_sources",
"features",
"harness_install_enabled",
"installable_harnesses",
"dictation_available",
"branding"
],
"title": "ServerInfoResponse",
"type": "object"
},
"ServerStreamEvent": {
"discriminator": {
"mapping": {
"browser.action_request": "#/components/schemas/BrowserActionRequestEvent",
"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.function_call_output.delta": "#/components/schemas/ToolOutputDeltaEvent",
"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.policy_denied": "#/components/schemas/PolicyDeniedEvent",
"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.background_tasks": "#/components/schemas/SessionBackgroundTasksEvent",
"session.btw_sidechat": "#/components/schemas/SessionBtwSidechatEvent",
"session.changed_files.invalidated": "#/components/schemas/SessionChangedFilesInvalidatedEvent",
"session.child_session.updated": "#/components/schemas/SessionChildSessionUpdatedEvent",
"session.codex_approval_mode": "#/components/schemas/SessionCodexApprovalModeEvent",
"session.collaboration_mode": "#/components/schemas/SessionCollaborationModeEvent",
"session.created": "#/components/schemas/SessionCreatedEvent",
"session.heartbeat": "#/components/schemas/SessionHeartbeatEvent",
"session.input.consumed": "#/components/schemas/SessionInputConsumedEvent",
"session.interrupted": "#/components/schemas/SessionInterruptedEvent",
"session.mcp_startup": "#/components/schemas/SessionMcpStartupEvent",
"session.model": "#/components/schemas/SessionModelEvent",
"session.model_options": "#/components/schemas/SessionModelOptionsEvent",
"session.permission_mode": "#/components/schemas/SessionPermissionModeEvent",
"session.presence": "#/components/schemas/SessionPresenceEvent",
"session.reasoning_effort": "#/components/schemas/SessionReasoningEffortEvent",
"session.resource.created": "#/components/schemas/SessionResourceCreatedEvent",
"session.resource.deleted": "#/components/schemas/SessionResourceDeletedEvent",
"session.sandbox_status": "#/components/schemas/SessionSandboxStatusEvent",
"session.status": "#/components/schemas/SessionStatusEvent",
"session.superseded": "#/components/schemas/SessionSupersededEvent",
"session.terminal.activity": "#/components/schemas/SessionTerminalActivityEvent",
"session.terminal_pending": "#/components/schemas/SessionTerminalPendingEvent",
"session.title": "#/components/schemas/SessionTitleEvent",
"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",
"ui.open_file": "#/components/schemas/UiOpenFileEvent"
},
"propertyName": "type"
},
"oneOf": [
{
"$ref": "#/components/schemas/SessionStatusEvent"
},
{
"$ref": "#/components/schemas/SessionUsageEvent"
},
{
"$ref": "#/components/schemas/SessionModelEvent"
},
{
"$ref": "#/components/schemas/SessionTitleEvent"
},
{
"$ref": "#/components/schemas/SessionReasoningEffortEvent"
},
{
"$ref": "#/components/schemas/SessionCollaborationModeEvent"
},
{
"$ref": "#/components/schemas/SessionPermissionModeEvent"
},
{
"$ref": "#/components/schemas/SessionCodexApprovalModeEvent"
},
{
"$ref": "#/components/schemas/SessionBackgroundTasksEvent"
},
{
"$ref": "#/components/schemas/SessionAgentChangedEvent"
},
{
"$ref": "#/components/schemas/SessionTodosEvent"
},
{
"$ref": "#/components/schemas/SessionTerminalPendingEvent"
},
{
"$ref": "#/components/schemas/SessionSandboxStatusEvent"
},
{
"$ref": "#/components/schemas/SessionMcpStartupEvent"
},
{
"$ref": "#/components/schemas/SessionModelOptionsEvent"
},
{
"$ref": "#/components/schemas/SessionInputConsumedEvent"
},
{
"$ref": "#/components/schemas/SessionInterruptedEvent"
},
{
"$ref": "#/components/schemas/SessionCreatedEvent"
},
{
"$ref": "#/components/schemas/SessionSupersededEvent"
},
{
"$ref": "#/components/schemas/SessionBtwSidechatEvent"
},
{
"$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/ToolOutputDeltaEvent"
},
{
"$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/BrowserActionRequestEvent"
},
{
"$ref": "#/components/schemas/UiOpenFileEvent"
},
{
"$ref": "#/components/schemas/PolicyDeniedEvent"
},
{
"$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": "The session's bound agent changed.\n\nEmitted after a session's MCP servers are edited (the agent's bundle\nis rewritten). Connected clients re-derive their cached session state\n(bound agent, harness presentation labels) from a fresh snapshot.",
"properties": {
"agent_id": {
"description": "The agent bound to the session, e.g. `\"ag_abc123\"`.",
"title": "Agent Id",
"type": "string"
},
"agent_name": {
"description": "Display name of that agent, e.g. `\"claude-native-ui\"`. Category: **transient** (SSE-only). The change is persisted, so on reconnect clients read it from the session snapshot.",
"title": "Agent Name",
"type": "string"
},
"conversation_id": {
"description": "Session identifier, e.g. `\"conv_abc123\"`.",
"title": "Conversation Id",
"type": "string"
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "session.agent_changed",
"description": "Always `\"session.agent_changed\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"conversation_id",
"agent_id",
"agent_name"
],
"title": "SessionAgentChangedEvent",
"type": "object"
},
"SessionBackgroundTasksEvent": {
"description": "Background tasks of a session changed between its turns.\n\nEmitted when a codex-native forwarder's listing of its thread's background\nterminals changes. Claude's shells ride on its turn's `session.status`\nedge instead, because Claude reports them only when a turn ends.",
"properties": {
"background_task_count": {
"description": "Background tasks still running, e.g. `1`. `0` clears the composer's indicator.",
"format": "int64",
"title": "Background Task Count",
"type": "integer"
},
"background_tasks": {
"description": "Detail for each counted task, e.g. its command. Category: **transient** (SSE-only). The session snapshot carries the same tally, so reconnecting clients restore it.",
"items": {
"$ref": "#/components/schemas/BackgroundTaskInfo"
},
"title": "Background Tasks",
"type": "array"
},
"conversation_id": {
"description": "Session identifier, e.g. `\"conv_abc123\"`.",
"title": "Conversation Id",
"type": "string"
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "session.background_tasks",
"description": "Always `\"session.background_tasks\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"conversation_id",
"background_task_count"
],
"title": "SessionBackgroundTasksEvent",
"type": "object"
},
"SessionBtwSidechatEvent": {
"description": "A Claude Code `/btw` side-chat exchange to show transiently.\n\n`/btw` opens an ephemeral side conversation whose answer Claude Code\nkeeps only in its in-TUI overlay \u2014 it is never written to the session\ntranscript. The claude-native forwarder scrapes the settled overlay\nfrom the pane and emits this event so the managed web UI can show the\nsame ephemeral overlay (dismissed with Escape), WITHOUT adding a\npersisted side-chat turn to the main conversation.\n\nCategory: **transient** (SSE-only), live-only by design. Nothing is\npersisted and there is no SSE replay, so a reload drops the overlay \u2014\nmatching the terminal, where Escape closes it and leaves no history.\n\nThe wire shape is FLAT (not enveloped):\n`{\"type\": \"session.btw_sidechat\", \"conversation_id\": <id>, \"question\": <str>, \"answer\": <str>, \"truncated\": <bool>}`.",
"properties": {
"answer": {
"description": "The side-chat answer text.",
"title": "Answer",
"type": "string"
},
"conversation_id": {
"description": "The conversation whose stream this rides.",
"title": "Conversation Id",
"type": "string"
},
"question": {
"description": "The `/btw` request line as typed, e.g. `\"/btw is this backward compatible?\"`.",
"title": "Question",
"type": "string"
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"truncated": {
"default": false,
"description": "True when the pane clipped a longer answer; the web overlay notes it and points at the terminal for the full text.",
"title": "Truncated",
"type": "boolean"
},
"type": {
"const": "session.btw_sidechat",
"description": "Always `\"session.btw_sidechat\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"conversation_id",
"question",
"answer"
],
"title": "SessionBtwSidechatEvent",
"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).",
"properties": {
"environment_id": {
"default": "default",
"description": "Environment whose changes were invalidated, e.g. `\"default\"`.",
"title": "Environment Id",
"type": "string"
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"session_id": {
"description": "Owning session/conversation id.",
"title": "Session Id",
"type": "string"
},
"type": {
"const": "session.changed_files.invalidated",
"description": "Always `\"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`ChildSessionSummary` so the web patches its cache directly.",
"properties": {
"child": {
"additionalProperties": true,
"description": "A PARTIAL `ChildSessionSummary` \u2014 the snapshot-on-connect sends the full summary, while live runner deltas carry only the fields that changed (a status delta omits `last_message_preview`; a preview delta carries only it). The web merges present fields over the cached row, so the payload is an open dict rather than the strict model.",
"title": "Child",
"type": "object"
},
"child_session_id": {
"description": "The child session id, e.g. `\"conv_child_abc123\"`.",
"title": "Child Session Id",
"type": "string"
},
"conversation_id": {
"description": "The PARENT (carrier) session id.",
"title": "Conversation Id",
"type": "string"
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "session.child_session.updated",
"description": "Always `\"session.child_session.updated\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"conversation_id",
"child_session_id",
"child"
],
"title": "SessionChildSessionUpdatedEvent",
"type": "object"
},
"SessionCodexApprovalModeEvent": {
"description": "Active approval/sandbox-mode update from a codex-native session.\n\nEmitted after the web UI switches the mode, and after the Codex forwarder\nobserves a `thread/settings/updated` notification \u2014 an approval change the\nuser made inside Codex's `/permissions` popup, which Omnigent has no other\nway to see. Lets the composer's approval picker track the thread without a\nreload.",
"properties": {
"approval_mode": {
"description": "The active mode, one of `\"ask-for-approval\"`, `\"approve-for-me\"`, `\"full-access\"`, `\"read-only\"`. Category: **transient** (SSE-only). The server also writes `omnigent.codex_native.approval_mode` on the conversation labels (and `terminal_launch_args`), so reconnecting clients restore the same state from the session snapshot.",
"title": "Approval Mode",
"type": "string"
},
"conversation_id": {
"description": "Session identifier, e.g. `\"conv_abc123\"`.",
"title": "Conversation Id",
"type": "string"
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "session.codex_approval_mode",
"description": "Always `\"session.codex_approval_mode\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"conversation_id",
"approval_mode"
],
"title": "SessionCodexApprovalModeEvent",
"type": "object"
},
"SessionCollaborationModeEvent": {
"description": "Active collaboration-mode update from a Codex-native session.\n\nEmitted after the web UI toggles Codex collaboration mode, and after the\nCodex forwarder observes a `thread/settings/updated` notification from\nthe native Codex TUI. Lets connected clients show a clear Plan-mode\nindicator without a reload.",
"properties": {
"conversation_id": {
"description": "Session identifier, e.g. `\"conv_abc123\"`.",
"title": "Conversation Id",
"type": "string"
},
"mode": {
"description": "The active collaboration mode string, e.g. `\"plan\"` or `\"default\"`. Category: **transient** (SSE-only). The server also writes `omnigent.codex_native.collaboration_mode` on the conversation labels, so reconnect clients restore the same state from the session snapshot.",
"title": "Mode",
"type": "string"
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "session.collaboration_mode",
"description": "Always `\"session.collaboration_mode\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"conversation_id",
"mode"
],
"title": "SessionCollaborationModeEvent",
"type": "object"
},
"SessionCompactionItem": {
"description": "`compaction` item: common fields plus `CompactionData`.",
"properties": {
"compacted_messages": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Compacted Messages"
},
"created_at": {
"description": "Unix epoch seconds of creation.",
"format": "int64",
"title": "Created At",
"type": "integer"
},
"created_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Identity of the human author; omitted for agent, tool, and system items.",
"title": "Created By"
},
"id": {
"description": "Store-assigned item ID, e.g. `\"msg_abc123\"`.",
"title": "Id",
"type": "string"
},
"last_item_id": {
"title": "Last Item Id",
"type": "string"
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model"
},
"response_id": {
"description": "ID of the task/response that produced this item.",
"title": "Response Id",
"type": "string"
},
"status": {
"description": "Item status, e.g. `\"completed\"`.",
"title": "Status",
"type": "string"
},
"summary": {
"title": "Summary",
"type": "string"
},
"token_count": {
"format": "int64",
"title": "Token Count",
"type": "integer"
},
"type": {
"const": "compaction",
"title": "Type",
"type": "string"
},
"window_id": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Window Id"
}
},
"required": [
"summary",
"last_item_id",
"token_count",
"id",
"response_id",
"status",
"created_at",
"type"
],
"title": "SessionCompactionItem",
"type": "object"
},
"SessionContentBlock": {
"additionalProperties": true,
"description": "One `content` or `summary` block of a message or reasoning item.\n\nBlocks are heterogeneous (`input_text`, `output_text`,\n`input_image`, `summary_text`, ...), so kinds other than text\ncarry extra keys.",
"properties": {
"text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Text body of a text block; absent for other kinds.",
"title": "Text"
},
"type": {
"description": "Block kind, e.g. `\"input_text\"` or `\"output_text\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type"
],
"title": "SessionContentBlock",
"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>, \"child_session_id\": <child>, \"agent_id\": <agent or None>, \"parent_session_id\": <parent>, \"sequence_number\": null}`.\n\nThe existing tunneled `function_call` ConversationItem\n(carried inside `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.",
"properties": {
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Registered agent id the child runs as, e.g. `\"agent_xyz\"`. `None` is permitted only for legacy spawn paths that did not record an agent id; new code MUST set it.",
"title": "Agent Id"
},
"child_session_id": {
"description": "The newly-created child session id, e.g. `\"conv_child456\"`. Same as `conversation_id` on the child's own stream when consumers pivot to it.",
"title": "Child Session Id",
"type": "string"
},
"conversation_id": {
"description": "The PARENT session/conversation id \u2014 this event rides the parent's stream, e.g. `\"conv_parent123\"`.",
"title": "Conversation Id",
"type": "string"
},
"parent_session_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Echo of `conversation_id` for consumers that key on a dedicated \"parent\" field rather than the carrier `conversation_id`. Always equal to `conversation_id`; included for forward-compat with clients that may relay these events across stream boundaries. Category: **transient** (SSE-only). The corresponding durable record of \"a child session exists\" lives in the conversation store as the child conversation row itself (`parent_conversation_id` foreign key) and the parent's tunneled `function_call` item \u2014 reconnecting clients discover children by walking the parent's persisted history, not by replaying this event.",
"title": "Parent Session Id"
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "session.created",
"description": "Always `\"session.created\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"conversation_id",
"child_session_id"
],
"title": "SessionCreatedEvent",
"type": "object"
},
"SessionErrorItem": {
"description": "`error` item: common fields plus `ErrorData`.",
"properties": {
"cause": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Cause"
},
"code": {
"title": "Code",
"type": "string"
},
"created_at": {
"description": "Unix epoch seconds of creation.",
"format": "int64",
"title": "Created At",
"type": "integer"
},
"created_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Identity of the human author; omitted for agent, tool, and system items.",
"title": "Created By"
},
"id": {
"description": "Store-assigned item ID, e.g. `\"msg_abc123\"`.",
"title": "Id",
"type": "string"
},
"level": {
"anyOf": [
{
"enum": [
"error",
"info"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Level"
},
"message": {
"title": "Message",
"type": "string"
},
"remediation": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Remediation"
},
"response_id": {
"description": "ID of the task/response that produced this item.",
"title": "Response Id",
"type": "string"
},
"source": {
"enum": [
"llm",
"execution",
"tool",
"harness"
],
"title": "Source",
"type": "string"
},
"status": {
"description": "Item status, e.g. `\"completed\"`.",
"title": "Status",
"type": "string"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Title"
},
"type": {
"const": "error",
"title": "Type",
"type": "string"
}
},
"required": [
"source",
"code",
"message",
"id",
"response_id",
"status",
"created_at",
"type"
],
"title": "SessionErrorItem",
"type": "object"
},
"SessionFamily": {
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"pinned": {
"default": false,
"title": "Pinned",
"type": "boolean"
},
"pinned_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Pinned At"
},
"representative_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Representative Id"
}
},
"required": [
"id",
"representative_id"
],
"title": "SessionFamily",
"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.",
"properties": {
"agent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Built-in agent to bind the fork to, switching it away from the source's agent/harness (e.g. fork a Claude session into a Codex one, or a Claude-SDK session into Claude Code). When `None`, the fork keeps the source's agent. Must be a built-in agent (one listed by `GET /v1/agents`).",
"title": "Agent Id"
},
"codex_bypass_sandbox": {
"default": false,
"description": "Opt-in for the DANGEROUS codex-native full-bypass (`--dangerously-bypass-approvals-and-sandbox`) on the fork. The source's bypass label is ALWAYS dropped on a fork (a bypass-armed source can never silently re-arm its clone), so this is the only way a fork enables it \u2014 an explicit, banner-gated opt-in from the dialog, mirroring the new-session approval selector. `True` stamps `omnigent.codex_native.bypass_sandbox` on the fork; `False` / omitted leaves the fork in Codex's normal approval/sandbox stance. Only meaningful for a codex-native target; ignored otherwise.",
"title": "Codex Bypass Sandbox",
"type": "boolean"
},
"host_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Id for the fork's new sandbox host, with the same shape, capability gate, label and `409` as a managed create's `host_id`. `None` lets the server mint one. Only valid with `host_type: \"managed\"`.",
"title": "Host Id"
},
"host_type": {
"default": "external",
"description": "How the fork's host is obtained \u2014 `\"external\"` (the default: the caller binds one afterwards, via `POST /v1/hosts/{host_id}/runners` from the web dialog or `PATCH /v1/sessions/{id}` from the REPL) or `\"managed\"` (the server provisions a sandbox host for the fork, the same background launch a `host_type: \"managed\"` create schedules).",
"enum": [
"external",
"managed"
],
"title": "Host Type",
"type": "string"
},
"model_override": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Per-session LLM model override to apply to the fork, e.g. `\"claude-opus-4-7\"`. **Omitting** the field inherits the source's model (same as today, within the same provider family); an explicit value overrides it, and a clear alias (`\"default\"`, `\"off\"`, `\"reset\"`) resets the fork to the bound agent's default. Validated against a conservative model-id charset. Set by the web fork dialog's model picker.",
"title": "Model Override"
},
"reasoning_effort": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Per-session reasoning-effort override to apply to the fork, e.g. `\"high\"`. **Omitting** the field inherits the source's effort; an explicit value overrides it, and a clear alias (`\"default\"`, `\"off\"`, `\"reset\"`) resets it. Validated against the shared effort vocabulary; provider support is enforced at launch. Set by the web fork dialog's effort picker.",
"title": "Reasoning Effort"
},
"sandbox_profile_id": {
"anyOf": [
{
"maxLength": 64,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"title": "Sandbox Profile Id"
},
"sandbox_profile_revision": {
"anyOf": [
{
"maxLength": 64,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"title": "Sandbox Profile Revision"
},
"sandbox_provider": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Which configured sandbox provider to provision on `host_type: \"managed\"` (one of the server's `sandbox_providers`); `None` takes the server's first. Only valid with `host_type: \"managed\"`.",
"title": "Sandbox Provider"
},
"side_chat": {
"default": false,
"title": "Side Chat",
"type": "boolean"
},
"terminal_launch_args": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Per-session native-terminal pass-through args to apply to the fork, e.g. `[\"--permission-mode\", \"auto\"]` (the fork dialog's permission-/approval-mode selector). **Omitting** the field keeps today's behavior \u2014 the source's args are carried on a same-agent fork and dropped on an agent switch. A list (including `[]`, which clears them) replaces them wholesale. Bounds (count / length) are validated server-side.",
"title": "Terminal Launch Args"
},
"title": {
"anyOf": [
{
"maxLength": 200,
"type": "string"
},
{
"type": "null"
}
],
"description": "Title for the forked session. When `None`, the server derives `\"Fork of <source_title>\"`.",
"title": "Title"
},
"up_to_response_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Truncation point for the copied history, e.g. `\"resp_abc123\"`. When set, only items up to and including the last item of that response are copied \u2014 items after it are dropped from the fork. When `None` (default), the full history is copied.",
"title": "Up To Response Id"
},
"workspace": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Git repository URL (optionally `#<branch>`) the server clones into the fork's sandbox as its working directory, e.g. `\"https://github.com/org/repo#release-1.2\"`. **Omitting** both workspace fields inherits all repositories the source session recorded, so cloning a sandbox session preserves its checkouts; an explicit value overrides it and an explicit `null` gives the fork an empty sandbox. Only valid with `host_type: \"managed\"` \u2014 an external fork's directory is chosen when it binds a host.",
"title": "Workspace"
},
"workspaces": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Repository URLs (each optionally `#<branch>`) to clone into the fork's sandbox, replacing the source's repositories. Send only when `GET /v1/info` reports `session_fork_workspaces`. Several repositories require a provider with `multi_repo` support. Mutually exclusive with `workspace`; explicitly sending `[]` or `null` gives the fork an empty sandbox. Only valid with `host_type: \"managed\"`.",
"title": "Workspaces"
}
},
"title": "SessionForkRequest",
"type": "object"
},
"SessionFunctionCallItem": {
"description": "`function_call` item: common fields plus `FunctionCallData`.",
"properties": {
"arguments": {
"title": "Arguments",
"type": "string"
},
"call_id": {
"title": "Call Id",
"type": "string"
},
"created_at": {
"description": "Unix epoch seconds of creation.",
"format": "int64",
"title": "Created At",
"type": "integer"
},
"created_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Identity of the human author; omitted for agent, tool, and system items.",
"title": "Created By"
},
"id": {
"description": "Store-assigned item ID, e.g. `\"msg_abc123\"`.",
"title": "Id",
"type": "string"
},
"model": {
"title": "Model",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"namespace": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Namespace"
},
"response_id": {
"description": "ID of the task/response that produced this item.",
"title": "Response Id",
"type": "string"
},
"status": {
"description": "Item status, e.g. `\"completed\"`.",
"title": "Status",
"type": "string"
},
"type": {
"const": "function_call",
"title": "Type",
"type": "string"
}
},
"required": [
"model",
"name",
"arguments",
"call_id",
"id",
"response_id",
"status",
"created_at",
"type"
],
"title": "SessionFunctionCallItem",
"type": "object"
},
"SessionFunctionCallOutputItem": {
"description": "`function_call_output` item: common fields plus `FunctionCallOutputData`.",
"properties": {
"call_id": {
"title": "Call Id",
"type": "string"
},
"created_at": {
"description": "Unix epoch seconds of creation.",
"format": "int64",
"title": "Created At",
"type": "integer"
},
"created_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Identity of the human author; omitted for agent, tool, and system items.",
"title": "Created By"
},
"id": {
"description": "Store-assigned item ID, e.g. `\"msg_abc123\"`.",
"title": "Id",
"type": "string"
},
"output": {
"title": "Output",
"type": "string"
},
"response_id": {
"description": "ID of the task/response that produced this item.",
"title": "Response Id",
"type": "string"
},
"status": {
"description": "Item status, e.g. `\"completed\"`.",
"title": "Status",
"type": "string"
},
"subagent_return_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Subagent Return Id"
},
"type": {
"const": "function_call_output",
"title": "Type",
"type": "string"
}
},
"required": [
"call_id",
"output",
"id",
"response_id",
"status",
"created_at",
"type"
],
"title": "SessionFunctionCallOutputItem",
"type": "object"
},
"SessionGitOptions": {
"description": "Git worktree options for `POST /v1/sessions`.\n\nRequires `host_id` to be set (and therefore `workspace`, which\nis interpreted as the source repository directory). Two modes,\nselected by `existing_worktree`:\n\n- **create** (default): the server creates a git worktree on the\n host for a new branch and starts the runner in that worktree\n instead of the picked directory.\n- **bind** (`existing_worktree=True`): `workspace` already IS a\n pre-existing worktree; no worktree is created. `branch_name` is\n recorded as the session's `git_branch` for display and opt-in\n cleanup, and `base_branch` must not be set.\n\nSee designs/SESSION_GIT_WORKTREE.md.",
"properties": {
"base_branch": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional base ref to branch from, e.g. `\"main\"` or `\"origin/main\"`. `None` branches from the source repository's current `HEAD`. Create mode only \u2014 invalid with `existing_worktree`.",
"title": "Base Branch"
},
"branch_name": {
"description": "In create mode, the new branch to create and check out, e.g. `\"feature/login\"`. In bind mode, the branch already checked out in the existing worktree. Validated against git ref-format rules; invalid names fail with `invalid_input`.",
"title": "Branch Name",
"type": "string"
},
"existing_branch": {
"default": false,
"description": "When `True`, `branch_name` already exists and the host checks it out into a fresh worktree (the deleted-worktree recreate path) instead of creating a new branch. Create mode only; invalid with `existing_worktree` and with `base_branch` (an existing branch has no base to fork).",
"title": "Existing Branch",
"type": "boolean"
},
"existing_worktree": {
"default": false,
"description": "When `True`, bind to the pre-existing worktree at `workspace` instead of creating one (see above).",
"title": "Existing Worktree",
"type": "boolean"
}
},
"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 `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`HeartbeatEvent` for symmetry and debugging.",
"properties": {
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"server_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "ISO 8601 UTC timestamp at emission, e.g. `\"2026-05-25T10:30:00Z\"`. `None` when the producer chose not to populate it.",
"title": "Server Time"
},
"type": {
"const": "session.heartbeat",
"description": "Always `\"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\": <SessionInputConsumedPayload>, \"sequence_number\": null}`.\n\nThe event name is **provisional** \u2014 it may be renamed in a\nfuture revision. Consumers should reference\n`SessionInputConsumedEvent` (or its `type` literal)\nrather than hardcoding the wire string.",
"properties": {
"data": {
"$ref": "#/components/schemas/SessionInputConsumedPayload",
"description": "The decoded queued-item payload \u2014 see `SessionInputConsumedPayload`."
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "session.input.consumed",
"description": "Always `\"session.input.consumed\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"data"
],
"title": "SessionInputConsumedEvent",
"type": "object"
},
"SessionInputConsumedPayload": {
"description": "Inner payload of a `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.",
"properties": {
"cleared_pending_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "When this consumed message drains a `omnigent.runtime.pending_inputs` entry (a native- terminal web message round-tripping back from the transcript), the drained entry's id, e.g. `\"pending_a1b2c3\"`. Lets a client drop the matching optimistic bubble by id instead of by position. `None` for non-native messages and for messages that matched no pending entry (e.g. typed directly in the TUI).",
"title": "Cleared Pending Id"
},
"created_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Email of the human actor who posted the item, e.g. `\"alice@example.com\"`. `None` for agent/tool/system items and single-user mode. Mirrors `ConversationItem.to_api_dict` for live attribution.",
"title": "Created By"
},
"data": {
"additionalProperties": true,
"description": "Decoded item payload, e.g. `{\"role\": \"user\", \"content\": [{\"type\": \"input_text\", \"text\": \"Hello\"}]}`. Heterogeneous and `type`-specific.",
"title": "Data",
"type": "object"
},
"item_id": {
"description": "Stable identifier of the conversation item just persisted, e.g. `\"item_abc123\"`.",
"title": "Item Id",
"type": "string"
},
"type": {
"description": "The item type discriminator \u2014 `\"message\"` for user messages, `\"function_call_output\"` for tool results, etc. Mirrors `omnigent.server.schemas.SessionEventInput`'s `type` field.",
"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 /v1/sessions/{id}/events`. Co-emitted with\n`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.",
"properties": {
"data": {
"$ref": "#/components/schemas/SessionInterruptedPayload",
"description": "The interrupt metadata \u2014 see `SessionInterruptedPayload`."
},
"sequence_number": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Sequence Number"
},
"type": {
"const": "session.interrupted",
"description": "Always `\"session.interrupted\"`.",
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"data"
],
"title": "SessionInterruptedEvent",
"type": "object"
},
"SessionInterruptedPayload": {
"description": "Inner payload of a `SessionInterruptedEvent`.\n\nBuilt by `_publish_interrupted` in\n`omnigent/server/routes/sessions.py`.",
"properties": {
"requested_at": {
"description": "Unix epoch seconds when the interrupt request reached the server, e.g. `1704067200`.",
"format": "int64",
"title": "Requested At",
"type": "integer"
},
"response_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional active response id for terminal-backed integrations, e.g. `\"codex_turn_abc123\"`.",
"title": "Response Id"
}
},
"required": [
"requested_at"
],
"title": "SessionInterruptedPayload",
"type": "object"
},
"SessionItem": {
"description": "One record of `GET /v1/sessions/{id}/items`; `type` selects the variant.",
"discriminator": {
"mapping": {
"compaction": "#/components/schemas/SessionCompactionItem",
"error": "#/components/schemas/SessionErrorItem",
"function_call": "#/components/schemas/SessionFunctionCallItem",
"function_call_output": "#/components/schemas/SessionFunctionCallOutputItem",
"message": "#/components/schemas/SessionMessageItem",
"native_tool": "#/components/schemas/SessionNativeToolItem",
"reasoning": "#/components/schemas/SessionReasoningItem",
"resource_event": "#/components/schemas/SessionResourceEventItem",
"routing_decision": "#/components/schemas/SessionRoutingDecisionItem",
"slash_command": "#/components/schemas/SessionSlashCommandItem",
"terminal_command": "#/components/schemas/SessionTerminalCommandItem"
},
"propertyName": "type"
},
"oneOf": [
{
"$ref": "#/components/schemas/SessionMessageItem"
},
{
"$ref": "#/components/schemas/SessionFunctionCallItem"
},
{
"$ref": "#/components/schemas/SessionFunctionCallOutputItem"
},
{
"$ref": "#/components/schemas/SessionErrorItem"
},
{
"$ref": "#/components/schemas/SessionReasoningItem"
},
{
"$ref": "#/components/schemas/SessionCompactionItem"
},
{
"$ref": "#/components/schemas/SessionNativeToolItem"
},
{
"$ref": "#/components/schemas/SessionResourceEventItem"
},
{
"$ref": "#/components/schemas/SessionRoutingDecisionItem"
},
{
"$ref": "#/components/schemas/SessionSlashCommandItem"
},
{
"$ref": "#/components/schemas/SessionTerminalCommandItem"
}
],
"title": "SessionItem"
},
"SessionItemList": {
"description": "Paginated list of session items; `data` is a page of `SessionItem`.",
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/SessionItem"
},
"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": "SessionItemList",
"type": "object"
},
"SessionLabelsResponse": {
"description": "Lightweight response body for `GET /v1/sessions/{id}/labels`.",
"properties": {
"id": {
"description": "Session identifier, e.g. `\"conv_abc123\"`.",
"title": "Id",
"type": "string"
},
"labels": {
"additionalProperties": {
"type": "string"
},
"description": "Session-scoped guardrails labels. Empty dict when no labels have been written.",
"title": "Labels",
"type": "object"
}
},
"required": [
"id"
],
"title": "SessionLabelsResponse",
"type": "object"
},
"SessionList": {
"description": "Paginated list of sessions; `data` is a page of `SessionListItem`.",
"properties": {
"data": {
"items": {
"$ref": "#/components/schemas/SessionListItem"
},
"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"
},
"page_boundary": {
"anyOf": [
{
"$ref": "#/components/schemas/SessionPageBoundary"
},
{
"type": "null"
}
]
}
},
"title": "SessionList",
"type": "object"
},
"SessionListItem": {
"description": "Lightweight session summary for `GET /v1/sessions` list responses.\n\nSame shape as `SessionResponse` minus `items`.",
"properties": {
"agent_id": {
"description": "Durable identifier of the bound agent.",
"title": "Agent Id",
"type": "string"
},
"agent_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Human-readable name of the bound agent, e.g. `\"research-agent\"`. `None` when the agent row cannot be found.",
"title": "Agent Name"
},
"archived": {
"default": false,
"description": "Whether the session is archived. Archived sessions are returned by `GET /v1/sessions` only when the request passes `include_archived=true`; the sidebar groups them into a dedicated \"Archived\" section. `False` for normal sessions.",
"title": "Archived",
"type": "boolean"
},
"background_work_running": {
"default": false,
"description": "`True` while work outlives the session's ended turn, such as a background shell or a Codex goal that keeps running between turns. The sidebar shows such a session as working; `status` stays as reported, so the session still takes a new message. `False` while the session's runner is offline.",
"title": "Background Work Running",
"type": "boolean"
},
"blocked_on": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Why the session's agent is parked on a terminal prompt, e.g. `\"permission prompt\"`, from the last status edge, truncated to 128 characters. The sidebar shows such a session as needing input even when no web card exists for the prompt. `None` when it is not parked or its runner is offline.",
"title": "Blocked On"
},
"comments_count": {
"default": 0,
"description": "Total number of review comments (any status) on this session. Together with `comments_updated_at` it forms a change fingerprint: an add or edit bumps the timestamp, a delete changes the count, so the web client can invalidate its cached comment list when either field changes in a `WS /v1/sessions/updates` frame. `0` when the session has no comments or the server has no comment store wired.",
"format": "int64",
"title": "Comments Count",
"type": "integer"
},
"comments_updated_at": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"description": "Unix epoch **microseconds** of the most recently mutated comment on this session (max `updated_at` across its comments). Microsecond precision keeps back-to-back mutations within one second distinguishable while staying an exact integer in JavaScript; clients only compare it for change. `None` when the session has no comments or the server has no comment store wired.",
"title": "Comments Updated At"
},
"created_at": {
"description": "Unix epoch seconds of creation.",
"format": "int64",
"title": "Created At",
"type": "integer"
},
"external_session_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Runtime-native session id this conversation wraps, e.g. a Claude Code session uuid for `omnigent claude` sessions. `None` for regular AP-only conversations. Lets the sidebar / picker render a runtime badge without a follow-up GET.",
"title": "External Session Id"
},
"family": {
"anyOf": [
{
"$ref": "#/components/schemas/SessionFamily"
},
{
"type": "null"
}
]
},
"git_branch": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Git branch checked out in the session's worktree, e.g. `\"feature/login\"`. Set only when the session was created with a server-created git worktree; `None` otherwise. The Web UI uses a non-`None` value to offer the \"delete local branch\" cleanup checkbox on session delete. See designs/SESSION_GIT_WORKTREE.md.",
"title": "Git Branch"
},
"harness": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Canonical effective harness, including per-session overrides.",
"title": "Harness"
},
"host_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Host that launched the runner for this session.",
"title": "Host Id"
},
"host_online": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "Whether the session's host tunnel is live (status online and fresh within the host liveness TTL). `None` when the session has no `host_id` (CLI/local). Distinguishes \"runner down but host can relaunch\" from \"host offline\" for the open-session view; not used by the sidebar.",
"title": "Host Online"
},
"id": {
"description": "Session/conversation identifier, e.g. `\"conv_abc123\"`.",
"title": "Id",
"type": "string"
},
"labels": {
"additionalProperties": {
"type": "string"
},
"description": "Session-scoped guardrails labels.",
"title": "Labels",
"type": "object"
},
"owner": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The user_id of the session owner, or `None` when permissions are disabled. Included so the sidebar can display the owner without a separate API call.",
"title": "Owner"
},
"parent_session_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Parent Session Id"
},
"pending_elicitations_count": {
"default": 0,
"description": "Number of approval prompts currently waiting on this session. Powers the sidebar's \"needs attention\" badge so a user with several sessions running can tell which ones are blocked on them without opening each chat. Sourced from the Omnigent server's in-memory `omnigent.runtime.pending_elicitations` index, which mirrors every `response.elicitation_request` event passing through `session_stream` and decrements when a verdict is dispatched. `0` when the session has no outstanding elicitations.",
"format": "int64",
"title": "Pending Elicitations Count",
"type": "integer"
},
"permission_level": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"description": "The requesting user's numeric permission level on this session: `1` = read, `2` = edit, `3` = manage. `None` when permissions are disabled.",
"title": "Permission Level"
},
"project_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Project Id"
},
"pull_request": {
"anyOf": [
{
"$ref": "#/components/schemas/SessionPullRequestSummary"
},
{
"type": "null"
}
],
"description": "The session's first linked pull request, or `None` when it has none."
},
"pull_requests_synced": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "Whether the server has imported the session's PRs from its host, so a missing `pull_request` means \"none\" rather than \"not known yet\". `None` on servers without PR storage.",
"title": "Pull Requests Synced"
},
"reasoning_effort": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Per-session reasoning-effort hint.",
"title": "Reasoning Effort"
},
"runner_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Runner currently bound to the session.",
"title": "Runner Id"
},
"runner_online": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "Strict runner liveness \u2014 `True` iff a runner tunnel is currently registered for this session. Matches `GET /health`'s `runner_online` value. Strict: a dead runner on a live host reads `False` here (no host-relaunch optimism folded in), unlike the legacy conflated value. `None` when the server has no runner liveness lookup wired.",
"title": "Runner Online"
},
"search_snippet": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Excerpt of the chat content that matched the request's `search_query`, centered on the match with `\u2026` marking elided ends, so the search UI can show *where* a session matched in its body. Present whenever the query hit an item body (even if the title also matched); `None` on non-search reads and when only the title matched.",
"title": "Search Snippet"
},
"shared_with_others": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"description": "Whether the requesting user owns this session and has granted access to another user (the public link alone doesn't count). `None` when the requester isn't the owner or permissions are disabled, so the grant list never leaks to non-owners.",
"title": "Shared With Others"
},
"status": {
"description": "Derived session lifecycle status.",
"enum": [
"idle",
"running",
"waiting",
"failed"
],
"title": "Status",
"type": "string"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional human-readable title.",
"title": "Title"
},
"updated_at": {
"description": "Unix epoch seconds of last update.",
"format": "int64",
"title": "Updated At",
"type": "integer"
},
"viewer_last_seen": {
"anyOf": [
{
"format": "int64",
"type": "integer"
},
{
"type": "null"
}
],
"description": "The *requesting user's* \"last seen\" wall-clock baseline in seconds for this session, or `None` when they have never seen it. Per-viewer (built from the server's in-memory per-user read-state, written by `PUT /v1/sessions/{id}/read-state`); the unread dot shows when `updated_at > viewer_last_seen` and the session is finished. In-memory only \u2014 resets on a server restart.",
"title": "Viewer Last Seen"
},
"viewer_unread": {
"default": false,
"description": "Whether the *requesting user* explicitly marked this session unread. Per-viewer; lifts the active-row dot suppression on the client. `False` by default.",
"title": "Viewer Unread",
"type": "boolean"
},
"workspace": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Absolute path on disk where the runner cd's, e.g. `\"/Users/corey/universe/src/foo\"`. `None` for sessions that haven't been bound to a host workspace.",
"title": "Workspace"
}
},
"required": [
"id",
"agent_id",
"status",
"created_at",
"updated_at"
],
"title": "SessionListItem",
"type": "object"
},
"SessionLiveMCPServers": {
"description": "The MCP connections a session's running harness reports.",
"properties": {
"detail": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Readable explanation for `\"unavailable\"`, or `None`.",
"title": "Detail"
},
"live": {
"description": "`True` when the harness answered; `servers` is then current.",
"title": "Live",
"type": "boolean"
},
"reason": {
"anyOf": [
{
"enum": [
"not_running",
"unsupported",
"unavailable"
],
"type": "string"
},
{
"type": "null"
}
],
"description": "Why there is no live answer: `\"not_running\"` (no harness process yet; it starts with the next message), `\"unsupported\"` (the harness cannot report MCP status), or `\"unavailable\"` (the harness did not answer). `None` when `live` is true.",
"title": "Reason"
},
"reconnect_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "On a reconnect response, the harness's reason the reconnect failed, or `None` when it succeeded.",
"title": "Reconnect Error"
},
"servers": {
"description": "The harness's servers; empty unless `live`.",
"items": {
"$ref": "#/components/schemas/LiveMCPServerStatus"
},
"tit