{ "openapi": "3.1.0", "info": { "title": "nac-web HTTP API", "description": "Live OpenAPI 3.1 contract for nac-web's REST and SSE surface. nac-web binds to loopback by default. Non-loopback binds require --allow-remote and an authenticated, encrypted network boundary; every reachable client receives control equivalent to the local user because the API has no client authentication. IP-literal Host values bypass only the DNS-name allowlist, not authentication. DNS names must be listed in NAC_ALLOWED_HOSTS. Cross-origin browser control remains denied unless the operator explicitly lists each trusted application origin in NAC_ALLOWED_ORIGINS; that does not replace ingress authentication. Finite JSON responses may be gzip-compressed. The SSE stream is text/event-stream and is never gzip-compressed. Credential values are write-only. /mcp is streamable-HTTP MCP (JSON-RPC), not REST, and is intentionally out of band.", "license": { "name": "" }, "version": "0.1.4" }, "paths": { "/attention/events": { "get": { "tags": [ "native" ], "operationId": "get_attention_events", "parameters": [ { "name": "Last-Event-ID", "in": "header", "description": "Engine UUID:projection UUID:sequence cursor", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "X-NAC-Completion-Cursor", "in": "header", "description": "Native semantic replay: new cutoff or stable store UUID:sequence; independent from current-state baseline", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Native-only bounded metadata SSE; baseline is silent", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/AttentionFrame" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/auth": { "get": { "tags": [ "auth" ], "operationId": "get_auth", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAuthListResponse" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/auth/{provider}": { "delete": { "tags": [ "auth" ], "operationId": "delete_auth_provider", "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedAuthStatusResponse" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/auth/{provider}/login": { "post": { "tags": [ "auth" ], "operationId": "post_auth_provider_login", "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceLoginStartedResponse" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/auth/{provider}/login/{login_id}": { "get": { "tags": [ "auth" ], "operationId": "get_auth_provider_login_login_id", "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "login_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceLoginStateResponse" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "delete": { "tags": [ "auth" ], "operationId": "delete_auth_provider_login_login_id", "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "login_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success with no response body" }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/commands": { "get": { "tags": [ "system" ], "operationId": "get_commands", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SlashCommandDefinition" } } } } } } } }, "/credentials": { "get": { "tags": [ "credentials" ], "summary": "Stored credentials are write-only over HTTP: only redacted metadata leaves\nthe process.", "operationId": "get_credentials", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoredCredentialList" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "post": { "tags": [ "credentials" ], "operationId": "post_credentials", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCredentialRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneratedCredential" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/credentials/{name}": { "put": { "tags": [ "credentials" ], "operationId": "put_credentials_name", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCredentialRequest" } } }, "required": true }, "responses": { "204": { "description": "Success with no response body" }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "delete": { "tags": [ "credentials" ], "operationId": "delete_credentials_name", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success with no response body" }, "400": { "description": "Path extraction failed", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/fs/browse": { "get": { "tags": [ "filesystem" ], "summary": "The picker starts wherever the caller last was; with no path yet it opens on\nthe server root the session would default to anyway.", "operationId": "get_fs_browse", "parameters": [ { "name": "path", "in": "query", "description": "Absolute path to list. A leading `~` expands to the home directory.", "required": false, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/BrowseKind" } }, { "name": "hidden", "in": "query", "description": "Dot-prefixed names are hidden unless explicitly requested.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowseListing" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "403": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/health": { "get": { "tags": [ "system" ], "operationId": "get_health", "responses": { "200": { "description": "Session store ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } }, "503": { "description": "Session store unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/healthz": { "get": { "tags": [ "system" ], "operationId": "get_healthz", "responses": { "200": { "description": "Server event loop is responsive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/heartbeats": { "get": { "tags": [ "sessions" ], "operationId": "get_heartbeats", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HeartbeatSchedule" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/managed/github": { "get": { "tags": [ "managed" ], "operationId": "get_managed_github", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubStatusResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "delete": { "tags": [ "managed" ], "operationId": "delete_managed_github", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubStatusResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/managed/github/clone-operations": { "post": { "tags": [ "managed" ], "operationId": "post_managed_github_clone_operation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartManagedCloneRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedCloneOperation" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/managed/github/clone-operations/{operation_id}": { "get": { "tags": [ "managed" ], "operationId": "get_managed_github_clone_operation", "parameters": [ { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedCloneOperation" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "delete": { "tags": [ "managed" ], "operationId": "delete_managed_github_clone_operation", "parameters": [ { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedCloneOperation" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/managed/github/git-identity": { "get": { "tags": [ "managed" ], "operationId": "get_managed_github_git_identity", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitIdentityResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "put": { "tags": [ "managed" ], "operationId": "put_managed_github_git_identity", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGitIdentityRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitIdentityResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/managed/github/login": { "post": { "tags": [ "managed" ], "operationId": "post_managed_github_login", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubLoginStartedResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/managed/github/login/{login_id}": { "get": { "tags": [ "managed" ], "operationId": "get_managed_github_login_login_id", "parameters": [ { "name": "login_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubLoginStateResponse" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "delete": { "tags": [ "managed" ], "operationId": "delete_managed_github_login_login_id", "parameters": [ { "name": "login_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/managed/github/repositories": { "get": { "tags": [ "managed" ], "operationId": "get_managed_github_repositories", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubRepositoryListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/managed/github/repositories/{owner}/{repository}/branches": { "get": { "tags": [ "managed" ], "operationId": "get_managed_github_repository_branches", "parameters": [ { "name": "owner", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "repository", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GitHubBranchListResponse" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "502": { "description": "Bad Gateway", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/managed/secrets": { "get": { "tags": [ "managed" ], "operationId": "get_managed_secrets", "responses": { "200": { "description": "Write-only managed host secret metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedSecretList" } } } }, "404": { "description": "Managed NAC is not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Secret store unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/managed/secrets/{name}": { "put": { "tags": [ "managed" ], "operationId": "put_managed_secrets_name", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutManagedSecretRequest" } } }, "required": true }, "responses": { "200": { "description": "Secret created or replaced without returning its value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedSecretSummary" } } } }, "400": { "description": "Invalid or reserved secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Managed NAC is not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Secret store unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "delete": { "tags": [ "managed" ], "operationId": "delete_managed_secrets_name", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Secret removed from future command environments" }, "404": { "description": "Managed NAC or secret not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Secret store unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/managed/status": { "get": { "tags": [ "managed" ], "operationId": "get_managed_status", "responses": { "200": { "description": "Owner-facing managed host status without credential values", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedHostStatusResponse" } } } }, "404": { "description": "Managed NAC is not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/mcp_library/library": { "get": { "tags": [ "mcp-library" ], "summary": "The embedded catalog, extended by verified servers from the Smithery\nregistry when it answers in time.", "operationId": "get_mcp_library_library", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpLibraryResponse" } } } } } } }, "/mcp_library/servers": { "get": { "tags": [ "mcp-library" ], "operationId": "get_mcp_library_servers", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerList" } } } }, "409": { "description": "Configuration recovery is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "post": { "tags": [ "mcp-library" ], "operationId": "post_mcp_library_servers", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMcpServerRequest" } } }, "required": true }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerView" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/mcp_library/servers/status": { "get": { "tags": [ "mcp-library" ], "operationId": "get_mcp_library_servers_status", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpRuntimeStatusList" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/mcp_library/servers/test": { "post": { "tags": [ "mcp-library" ], "operationId": "post_mcp_library_servers_test", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestMcpServerRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestMcpServerResponse" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Configuration recovery is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/mcp_library/servers/{server_name}": { "delete": { "tags": [ "mcp-library" ], "operationId": "delete_mcp_library_servers_server_name", "parameters": [ { "name": "server_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success with no response body" }, "400": { "description": "Path extraction failed", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Configuration recovery is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "patch": { "tags": [ "mcp-library" ], "operationId": "patch_mcp_library_servers_server_name", "parameters": [ { "name": "server_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMcpServerRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerView" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/mcp_library/servers/{server_name}/connect": { "post": { "tags": [ "mcp-library" ], "operationId": "post_mcp_library_servers_server_name_connect", "parameters": [ { "name": "server_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpRuntimeStatus" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/mcp_library/servers/{server_name}/disconnect": { "post": { "tags": [ "mcp-library" ], "operationId": "post_mcp_library_servers_server_name_disconnect", "parameters": [ { "name": "server_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpRuntimeStatus" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/mcp_library/servers/{server_name}/oauth/authenticate": { "post": { "tags": [ "mcp-library" ], "operationId": "post_mcp_library_servers_server_name_oauth_authenticate", "parameters": [ { "name": "server_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticateMcpOAuthRequest" } } }, "required": true }, "responses": { "200": { "description": "OAuth browser authorization ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticateMcpOAuthResponse" } } } }, "400": { "description": "Authentication could not start", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Loopback callback is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/mcp_library/servers/{server_name}/oauth/callback": { "get": { "tags": [ "mcp-library" ], "operationId": "get_mcp_library_servers_server_name_oauth_callback", "parameters": [ { "name": "server_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OAuth authorization complete", "content": { "text/plain": {} } }, "400": { "description": "OAuth callback rejected", "content": { "text/plain": {} } } } } }, "/mcp_library/servers/{server_name}/oauth/configure": { "post": { "tags": [ "mcp-library" ], "operationId": "post_mcp_library_servers_server_name_oauth_configure", "parameters": [ { "name": "server_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigureMcpOAuthRequest" } } }, "required": true }, "responses": { "200": { "description": "OAuth configuration saved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthStatusResponse" } } } }, "400": { "description": "Configuration rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "MCP server not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/mcp_library/servers/{server_name}/oauth/logout": { "post": { "tags": [ "mcp-library" ], "operationId": "post_mcp_library_servers_server_name_oauth_logout", "parameters": [ { "name": "server_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OAuth credentials cleared", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthStatusResponse" } } } }, "404": { "description": "MCP server not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/mcp_library/servers/{server_name}/oauth/status": { "get": { "tags": [ "mcp-library" ], "operationId": "get_mcp_library_servers_server_name_oauth_status", "parameters": [ { "name": "server_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OAuth status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthStatusResponse" } } } }, "404": { "description": "MCP server not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/mcp_library/servers/{server_name}/reload": { "post": { "tags": [ "mcp-library" ], "operationId": "post_mcp_library_servers_server_name_reload", "parameters": [ { "name": "server_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpRuntimeStatus" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/model-configs": { "get": { "tags": [ "model-configs" ], "operationId": "get_model_configs", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelConfigurationList" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "post": { "tags": [ "model-configs" ], "operationId": "post_model_configs", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateModelConfigurationRequest" } } }, "required": true }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelConfigurationRecord" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/model-configs/from-file": { "post": { "tags": [ "model-configs" ], "operationId": "post_model_configs_from_file", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelConfigFromFileRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvedModelConfiguration" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "502": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/model-configs/{config_id}": { "delete": { "tags": [ "model-configs" ], "operationId": "delete_model_configs_config_id", "parameters": [ { "name": "config_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success with no response body" }, "400": { "description": "Path extraction failed", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Configuration is a project default", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "patch": { "tags": [ "model-configs" ], "operationId": "patch_model_configs_config_id", "parameters": [ { "name": "config_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateModelConfigurationRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelConfigurationRecord" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/model-configs/{config_id}/models": { "post": { "tags": [ "model-configs" ], "operationId": "post_model_configs_config_id_models", "parameters": [ { "name": "config_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvedModelConfiguration" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "502": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/models": { "get": { "tags": [ "models" ], "summary": "The model catalog listing for the frontend picker: every provider with\nauth requirements, managed base URL, catalog endpoint default,\n`_default` limits and real entries. Reads the process-global catalog;\nsynchronous, local-only, never fails. `auth_status`/`auth_hint` are\ncomputed per request from the process environment and the managed\ncredential files.", "operationId": "get_models", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelListing" } } } } } } }, "/product-context": { "get": { "operationId": "get_product_context", "parameters": [ { "name": "session_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "X-NAC-Presentation-Incarnation", "in": "header", "description": "Optional standalone presentation lifetime fence; grants no authority", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Sanitized passive product facts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductContext" } } } }, "404": { "description": "Context unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/product-destinations/resolve": { "post": { "operationId": "resolve_product_destination", "parameters": [ { "name": "X-NAC-Presentation-Incarnation", "in": "header", "description": "Optional standalone presentation lifetime fence; grants no authority", "required": false, "schema": { "type": [ "string", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductNavigationRequest" } } }, "required": true }, "responses": { "200": { "description": "Validated logical destination; no browser action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductNavigationResolution" } } } }, "400": { "description": "Destination unavailable or stale", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/projects": { "get": { "tags": [ "projects" ], "operationId": "get_projects", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectList" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "post": { "tags": [ "projects" ], "operationId": "post_projects", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectRequest" } } }, "required": true }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRecord" } } } }, "400": { "description": "Invalid project metadata or location", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "403": { "description": "Remote directory is unreadable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Directory or default model configuration was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "A project already uses this canonical location", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "502": { "description": "Remote host or command failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/projects/order": { "put": { "tags": [ "projects" ], "summary": "Rewrite the order of one pin group.", "operationId": "put_projects_order", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderProjectsRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderProjectsResponse" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/projects/{project_id}": { "delete": { "tags": [ "projects" ], "summary": "Remove a project, by default without touching the work done inside it.", "description": "Its sessions are released rather than deleted, so they reappear in the\nlisting as unassigned and can be assigned somewhere else. Pass\n`?sessions=delete` to take them down with the project instead.", "operationId": "delete_projects_project_id", "parameters": [ { "name": "sessions", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/DeleteProjectSessions" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteProjectResponse" } } } }, "400": { "description": "Bad request or rejected path/query extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Project was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "patch": { "tags": [ "projects" ], "operationId": "patch_projects_project_id", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRecord" } } } }, "400": { "description": "Invalid project metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Project or default model configuration was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/projects/{project_id}/sessions": { "post": { "tags": [ "projects" ], "summary": "Attach an existing session to a project.", "description": "Membership is set once: an already-assigned session conflicts, and so does a\nsession whose working directory is not the project's location.", "operationId": "post_projects_project_id_sessions", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignSessionRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectRecord" } } } }, "400": { "description": "Bad request or rejected path/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Project or session was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Session is already assigned or runs elsewhere", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/projects/{project_id}/task-launch-source": { "get": { "tags": [ "projects" ], "operationId": "source_info", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskLaunchSourceInfo" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/projects/{project_id}/task-launches": { "get": { "tags": [ "projects" ], "operationId": "inventory", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaskLaunchRecord" } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/projects/{project_id}/task-schedules": { "get": { "tags": [ "projects" ], "operationId": "get_project_task_schedules", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/HeartbeatSchedule" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/projects/{project_id}/task-schedules/control": { "post": { "tags": [ "projects" ], "operationId": "control_project_task_schedule", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshTaskScheduleControlRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeartbeatReceipt" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/projects/{project_id}/task-schedules/retained-allowance": { "post": { "tags": [ "projects" ], "operationId": "change_project_task_retained_allowance", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshTaskRetainedAllowanceChange" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshTaskRetainedAllowanceReceipt" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/projects/{project_id}/task-schedules/{schedule_id}": { "get": { "tags": [ "projects" ], "operationId": "get_project_task_schedule", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "schedule_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FreshTaskScheduleInspection" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/providers/models": { "post": { "tags": [ "models" ], "summary": "Validate a credential by asking its provider which models it may use.", "description": "A key arrives in the request body and is forwarded once; it is never stored\nby this route. The destination goes through the same URL validation as a\nsession launch. A provider signed in through the browser has no key to send,\nso the stored login answers instead — and its answer is the same evidence\nthe launch UI needs that the login still works.", "operationId": "post_providers_models", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderModelsRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderModelList" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "502": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/readyz": { "get": { "tags": [ "system" ], "operationId": "get_readyz", "responses": { "200": { "description": "Durable store and selected runtime are ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessResponse" } } } }, "503": { "description": "A required readiness check failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadinessResponse" } } } } } } }, "/sandbox/activity": { "get": { "tags": [ "system" ], "operationId": "get_sandbox_activity", "parameters": [ { "name": "key", "in": "query", "description": "The activity key the create request carried (`sandbox.activity_key`).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SandboxActivity" }, { "type": "null" } ] } } } } } } }, "/sandbox/availability": { "get": { "tags": [ "system" ], "summary": "Whether this host can run sandboxed sessions right now. The launch UI\nqueries this only when the user picks sandbox mode, so the probe's\nsubprocess cost is paid on demand rather than on every page load.", "operationId": "get_sandbox_availability", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxAvailability" } } } } } } }, "/sessions": { "get": { "tags": [ "sessions" ], "operationId": "get_sessions", "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "workspace_stats", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedSessionSummary" } } } } }, "400": { "description": "Query extraction failed", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "post": { "tags": [ "sessions" ], "operationId": "post_sessions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionRequest" } } }, "required": true }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionFrontendSnapshot" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/launch-defaults": { "post": { "tags": [ "sessions" ], "operationId": "post_sessions_launch_defaults", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchModelDefaultsRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchModelDefaults" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/order": { "put": { "tags": [ "sessions" ], "operationId": "put_sessions_order", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderSessionsRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderSessionsResponse" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}": { "get": { "tags": [ "sessions" ], "operationId": "get_sessions_session_id", "parameters": [ { "name": "message_limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "thread_event_limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "include_sessions", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "include_system", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionSnapshotResponse" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "delete": { "tags": [ "sessions" ], "operationId": "delete_sessions_session_id", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success with no response body" }, "400": { "description": "Path extraction failed", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/cancel-active-run": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_cancel_active_run", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Success with no response body" }, "400": { "description": "Path extraction failed", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "501": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/children": { "get": { "tags": [ "conversation" ], "operationId": "get_sessions_session_id_children", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Traditional children", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TraditionalChildRecord" } } } } }, "400": { "description": "Direct behavior required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_children", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartTraditionalChildRequest" } } }, "required": true }, "responses": { "201": { "description": "Child created, continued, or steered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraditionalChildRecord" } } } }, "400": { "description": "Invalid child request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Child concurrency or run conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/children/{child_session_id}": { "get": { "tags": [ "conversation" ], "operationId": "get_sessions_session_id_children_child_session_id", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "child_session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Traditional child status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraditionalChildRecord" } } } }, "404": { "description": "Child not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/children/{child_session_id}/cancel": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_children_child_session_id_cancel", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "child_session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Traditional child cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraditionalChildRecord" } } } }, "404": { "description": "Child not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Child run is remote or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/children/{child_session_id}/permissions/reviews/{review_id}/authorize-retry": { "post": { "tags": [ "permissions" ], "operationId": "post_sessions_session_id_children_child_session_id_permissions_reviews_review_id_authorize_retry", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "child_session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "review_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Parent authorized a fresh review of the child's blocked action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionReview" } } } }, "404": { "description": "Child or blocked review not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Primary direct parent required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/commands": { "get": { "tags": [ "sessions" ], "operationId": "get_sessions_session_id_commands", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SlashCommandDefinition" } } } } }, "400": { "description": "Path extraction failed", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/compact": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_compact", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompactSessionResponse" } } } }, "400": { "description": "Path extraction failed", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/config": { "get": { "tags": [ "sessions" ], "operationId": "get_sessions_session_id_config", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RawSessionConfig" } } } }, "400": { "description": "Path extraction failed", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "patch": { "tags": [ "sessions" ], "operationId": "patch_sessions_session_id_config", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConfigRequest" } } }, "required": true }, "responses": { "200": { "description": "Success with no response body" }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/events": { "get": { "tags": [ "events" ], "operationId": "get_sessions_session_id_events", "parameters": [ { "name": "after_epoch_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "after_sequence_id", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecentEventsResponse" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/events/stream": { "get": { "tags": [ "events" ], "operationId": "get_sessions_session_id_events_stream", "parameters": [ { "name": "after_epoch_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "after_sequence_id", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Server-sent events. Event names and JSON data schemas: replay_boundary (ReplayBoundaryEvent), replay_gap (ReplayGapEvent), session_event (SessionEventEnvelope), assistant_delta (AssistantStreamDelta), and lagged (LaggedEvent). Only session_event carries an SSE id. This response is never gzip-compressed.", "content": { "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/executions": { "get": { "tags": [ "conversation" ], "operationId": "get_sessions_session_id_executions", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Existing current-chat executions without attachment or recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionListResponse" } } } }, "404": { "description": "Session unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Owner unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/executions/history": { "get": { "tags": [ "conversation" ], "operationId": "get_sessions_session_id_executions_history", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bounded existing activity and canonical command previews without recovery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionHistoryResponse" } } } }, "404": { "description": "Session unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Owner unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/executions/{execution_id}/input": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_executions_execution_id_input", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "execution_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControlledTerminalInputRequest" } } }, "required": true }, "responses": { "200": { "description": "Explicit written, rejected-before-write or accepted-unconfirmed receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputDeliveryReceipt" } } } }, "400": { "description": "Malformed or over-limit input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Session unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Stale controller, read-only source or uncertain delivery; never replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/executions/{execution_id}/input-control": { "get": { "tags": [ "conversation" ], "operationId": "get_sessions_session_id_executions_execution_id_input_control", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "execution_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current input owner and exact decimal revision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputControlStatus" } } } }, "404": { "description": "Session unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Read-only or unavailable incarnation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_executions_execution_id_input_control", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "execution_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferTerminalControlRequest" } } }, "required": true }, "responses": { "200": { "description": "Controller revision advanced; an in-flight write may require acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InputControlStatus" } } } }, "400": { "description": "Invalid version or revision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Session unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Controller changed or execution read-only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/executions/{execution_id}/observers": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_executions_execution_id_observers", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "execution_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachUserTerminalRequest" } } }, "required": true }, "responses": { "200": { "description": "Attach observer to same existing execution", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserTerminalObserverResponse" } } } }, "400": { "description": "Invalid protocol/bounds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Session unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Execution unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "429": { "description": "Observer capacity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/executions/{execution_id}/observers/{observer_id}": { "delete": { "tags": [ "conversation" ], "operationId": "delete_sessions_session_id_executions_execution_id_observers_observer_id", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "execution_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "observer_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Detach observation only" }, "400": { "description": "Invalid observer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/executions/{execution_id}/observers/{observer_id}/read": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_executions_execution_id_observers_observer_id_read", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "execution_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "observer_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PullUserTerminalRequest" } } }, "required": true }, "responses": { "200": { "description": "Immutable sanitized frame until render ACK; gap needs reset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionFrameResponse" } } } }, "400": { "description": "Invalid acknowledgement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Session unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Observer unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "429": { "description": "Concurrent read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/executions/{execution_id}/stop": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_executions_execution_id_stop", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "execution_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Stop only the selected owned execution" }, "404": { "description": "Session unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Execution unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/fork": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_fork", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForkSessionRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForkSessionResponse" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "413": { "description": "Request body too large", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "Unsupported media type", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "JSON body validation failed", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/forks/{fork_id}": { "delete": { "tags": [ "conversation" ], "operationId": "delete_sessions_session_id_forks_fork_id", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "fork_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success" }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/goal": { "get": { "tags": [ "conversation" ], "operationId": "get_sessions_session_id_goal", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current goal or null", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SessionGoalRecord" }, { "type": "null" } ] } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_goal", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGoalRequest" } } }, "required": true }, "responses": { "201": { "description": "Goal created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionGoalRecord" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/goal/{goal_id}": { "delete": { "tags": [ "conversation" ], "operationId": "delete_sessions_session_id_goal_goal_id", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "goal_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClearGoalRequest" } } }, "required": true }, "responses": { "204": { "description": "Goal cleared" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "patch": { "tags": [ "conversation" ], "operationId": "patch_sessions_session_id_goal_goal_id", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "goal_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGoalRequest" } } }, "required": true }, "responses": { "200": { "description": "Goal updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionGoalRecord" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/heartbeats/attention": { "post": { "tags": [ "sessions" ], "operationId": "acknowledge", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeartbeatAttentionAcknowledgement" } } }, "required": true }, "responses": { "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/heartbeats/control": { "post": { "tags": [ "sessions" ], "operationId": "control", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeartbeatControlRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeartbeatReceipt" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/heartbeats/preview": { "post": { "tags": [ "sessions" ], "operationId": "preview", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeartbeatPreviewRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeartbeatCalendarPreview" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/heartbeats/{schedule_id}": { "get": { "tags": [ "sessions" ], "operationId": "inspect", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "schedule_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HeartbeatInspection" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/inbox": { "get": { "tags": [ "conversation" ], "operationId": "get_sessions_session_id_inbox", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InboxItemResponse" } } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_inbox", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInboxItemRequest" } } }, "required": true }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxItemResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/inbox/{item_id}": { "delete": { "tags": [ "conversation" ], "operationId": "delete_sessions_session_id_inbox_item_id", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelInboxItemRequest" } } }, "required": true }, "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxItemResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "patch": { "tags": [ "conversation" ], "operationId": "patch_sessions_session_id_inbox_item_id", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "item_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInboxItemRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxItemResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/integrations": { "get": { "tags": [ "conversation" ], "operationId": "get_sessions_session_id_integrations", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Durable requested revision and process-local application status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionMcpRefreshStatus" } } } }, "404": { "description": "Session unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/integrations/refresh": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_integrations_refresh", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshSessionIntegrationsRequest" } } }, "required": true }, "responses": { "200": { "description": "Refresh scheduled at each affected agent's next model boundary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionMcpRefreshStatus" } } } }, "400": { "description": "Invalid revision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Session unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Revision changed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/messages": { "get": { "tags": [ "conversation" ], "operationId": "get_sessions_session_id_messages", "parameters": [ { "name": "before", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "include_system", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessagesPageResponse" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/orchestrators": { "get": { "tags": [ "conversation" ], "operationId": "get_sessions_session_id_orchestrators", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Managed orchestrators", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedOrchestratorRecord" } } } } }, "400": { "description": "Direct-with-orchestrator behavior required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_orchestrators", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartManagedOrchestratorRequest" } } }, "required": true }, "responses": { "201": { "description": "Orchestrator created, continued, or steered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedOrchestratorRecord" } } } }, "400": { "description": "Invalid orchestrator request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Orchestrator concurrency or run conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/orchestrators/{orchestrator_session_id}": { "get": { "tags": [ "conversation" ], "operationId": "get_sessions_session_id_orchestrators_orchestrator_session_id", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "orchestrator_session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Managed orchestrator status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedOrchestratorRecord" } } } }, "404": { "description": "Orchestrator not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/orchestrators/{orchestrator_session_id}/cancel": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_orchestrators_orchestrator_session_id_cancel", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "orchestrator_session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Managed orchestrator cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagedOrchestratorRecord" } } } }, "404": { "description": "Orchestrator not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Orchestrator run unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/permissions": { "get": { "tags": [ "permissions" ], "operationId": "get_sessions_session_id_permissions", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionStateResponse" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/permissions/grants/{grant_id}": { "delete": { "tags": [ "permissions" ], "operationId": "delete_sessions_session_id_permissions_grants_grant_id", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "grant_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Remembered grant removed" }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/permissions/mode": { "put": { "tags": [ "permissions" ], "operationId": "put_sessions_session_id_permissions_mode", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePermissionApprovalModeRequest" } } }, "required": true }, "responses": { "204": { "description": "Permission approval mode updated" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Concurrent permission approval mode update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/permissions/reviews/{review_id}/authorize-retry": { "post": { "tags": [ "permissions" ], "operationId": "post_sessions_session_id_permissions_reviews_review_id_authorize_retry", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "review_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Retry authorized; the model is asked to retry and the retry is reviewed again", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PermissionReview" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Blocked review not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/permissions/{request_id}": { "post": { "tags": [ "permissions" ], "operationId": "post_sessions_session_id_permissions_request_id", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyPermissionRequest" } } }, "required": true }, "responses": { "204": { "description": "Permission request answered" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/presentation": { "put": { "tags": [ "sessions" ], "operationId": "put_sessions_session_id_presentation", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSessionPresentationRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionSummarySnapshot" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/questions": { "get": { "tags": [ "conversation" ], "operationId": "get_sessions_session_id_questions", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/QuestionRecord" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/questions/{request_id}": { "get": { "tags": [ "conversation" ], "operationId": "get_sessions_session_id_questions_request_id", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionRecord" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/questions/{request_id}/answer": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_questions_request_id_answer", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionAnswer" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionAnswerReceipt" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/questions/{request_id}/cancel": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_questions_request_id_cancel", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelQuestionRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionRecord" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/regenerate": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_regenerate", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegenerateSessionRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitPromptResponse" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "413": { "description": "Request body too large", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "Unsupported media type", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "JSON body validation failed", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/revert": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_revert", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevertSessionRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevertSessionResponse" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "413": { "description": "Request body too large", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "Unsupported media type", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "JSON body validation failed", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/runs": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_runs", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitPromptRequest" } } }, "required": true }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitPromptResponse" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "413": { "description": "Request body too large", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "Unsupported media type", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "JSON body validation failed", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "501": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/runs/{run_id}/cancel": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_runs_run_id_cancel", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "The exact run was cancelled or was already inactive" }, "400": { "description": "Path extraction or run identity validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Session was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Cancellation is owned by another process", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Cancellation cleanup failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/skills": { "get": { "tags": [ "sessions" ], "operationId": "get_sessions_session_id_skills", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SkillCatalogEntry" } } } } }, "400": { "description": "Path extraction failed", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/steering": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_steering", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrchestratorSteeringRequest" } } }, "required": true }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrchestratorSteeringResponse" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/task-followup-delegations": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_task_followup_delegations", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskFollowupDelegationRequest" } } }, "required": true }, "responses": { "200": { "description": "Exact human delegation issued or original request reconciled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskFollowupDelegation" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "403": { "description": "Policy or scope denies delegation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Caller unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Conflicting identity or current caller owner unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Unknown commit outcome; retry identical request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/task-followup-delegations/{delegation_id}": { "get": { "tags": [ "conversation" ], "operationId": "get_sessions_session_id_task_followup_delegations_delegation_id", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "delegation_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Passive exact delegation evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskFollowupDelegation" } } } }, "400": { "description": "Invalid identifier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Delegation unavailable to this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "delete": { "tags": [ "conversation" ], "operationId": "delete_sessions_session_id_task_followup_delegations_delegation_id", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "delegation_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delegation revoked; accepted input and audit evidence retained", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskFollowupDelegation" } } } }, "400": { "description": "Invalid identifier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Delegation unavailable to this caller", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Admission is stopping", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/terminals/{terminal_id}": { "delete": { "tags": [ "conversation" ], "operationId": "delete_sessions_session_id_terminals_terminal_id", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "terminal_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Terminal stopped; repeated requests for the same current-service handle are safe" }, "400": { "description": "Path extraction or terminal identity validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Session or terminal was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Terminal belongs to another or previous service owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Terminal cleanup failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/threads/{thread_name}/events": { "get": { "tags": [ "conversation" ], "operationId": "get_sessions_session_id_threads_thread_name_events", "parameters": [ { "name": "before_id", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "thread_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadEventPage" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/threads/{thread_name}/steering": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_threads_thread_name_steering", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "thread_name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadSteeringRequest" } } }, "required": true }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadSteeringResponse" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/tool-calls/{call_id}": { "get": { "tags": [ "conversation" ], "operationId": "get_sessions_session_id_tool_calls_call_id", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "call_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolCallContentResponse" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Session or tool call not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/user-commands": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_user_commands", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShellCommandRequest" } } }, "required": true }, "responses": { "200": { "description": "Identical request reconciled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShellCommandSnapshot" } } } }, "202": { "description": "Durable command accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShellCommandSnapshot" } } } }, "400": { "description": "Invalid or unsupported command", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Busy or conflicting identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Command admission failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/user-commands/{request_id}": { "get": { "tags": [ "conversation" ], "operationId": "get_sessions_session_id_user_commands_request_id", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Durable command outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShellCommandSnapshot" } } } }, "404": { "description": "Command not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Lookup failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/user-commands/{request_id}/cancel": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_user_commands_request_id_cancel", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancellation requested or already settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShellCommandSnapshot" } } } }, "404": { "description": "Command not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Cancellation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/user-commands/{request_id}/output": { "get": { "tags": [ "conversation" ], "operationId": "get_sessions_session_id_user_commands_request_id_output", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "stream", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "Page of redacted retained output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShellOutputPage" } } } }, "410": { "description": "Output not retained or not yet settled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Output lookup failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/user-terminals": { "get": { "tags": [ "conversation" ], "operationId": "get_sessions_session_id_user_terminals", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Live and bounded completed human terminals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserTerminalListResponse" } } } }, "404": { "description": "Session unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_user_terminals", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenUserTerminalRequest" } } }, "required": true }, "responses": { "200": { "description": "Session-owned shell opened or live launch retried", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserTerminalResponse" } } } }, "400": { "description": "Malformed request/version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Session unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Launch rejected by policy, ownership, configuration or capacity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/user-terminals/{terminal_id}": { "get": { "tags": [ "conversation" ], "operationId": "get_sessions_session_id_user_terminals_terminal_id", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "terminal_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Process and output completion are distinct", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserTerminalResponse" } } } }, "404": { "description": "Session unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Terminal unavailable for this owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/user-terminals/{terminal_id}/input": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_user_terminals_terminal_id_input", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "terminal_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserTerminalInputRequest" } } }, "required": true }, "responses": { "204": { "description": "Literal bytes delivered; no key-name or Enter policy parsing" }, "400": { "description": "Malformed request/version or input exceeds 16 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Session unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Input unavailable, queue full, or accepted delivery unconfirmed; never automatically retry bytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/user-terminals/{terminal_id}/observers": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_user_terminals_terminal_id_observers", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "terminal_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachUserTerminalRequest" } } }, "required": true }, "responses": { "200": { "description": "Independent observer attached; no shell creation or lifetime change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserTerminalObserverResponse" } } } }, "400": { "description": "Malformed request/version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Session unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Terminal unavailable for this owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "429": { "description": "Observer capacity reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/user-terminals/{terminal_id}/observers/{observer_id}": { "delete": { "tags": [ "conversation" ], "operationId": "delete_sessions_session_id_user_terminals_terminal_id_observers_observer_id", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "terminal_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "observer_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Observation detached idempotently; shell and agent remain live" }, "400": { "description": "Malformed observer identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/user-terminals/{terminal_id}/observers/{observer_id}/read": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_user_terminals_terminal_id_observers_observer_id_read", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "terminal_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "observer_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PullUserTerminalRequest" } } }, "required": true }, "responses": { "200": { "description": "One immutable sanitized frame; pending frames replay until renderer acknowledgement. Gaps carry no bytes and require a reset acknowledgement.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserTerminalFrameResponse" } } } }, "400": { "description": "Malformed version/acknowledgement/bounds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Session unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Terminal/observer unavailable for this owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "429": { "description": "Concurrent observer request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/user-terminals/{terminal_id}/resize": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_user_terminals_terminal_id_resize", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "terminal_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResizeUserTerminalRequest" } } }, "required": true }, "responses": { "204": { "description": "Geometry applied to the owned PTY" }, "400": { "description": "Malformed request/version or geometry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Session unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Terminal mutation unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/user-terminals/{terminal_id}/selection-preview": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_user_terminals_terminal_id_selection_preview", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "terminal_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalSelectionPreviewRequest" } } }, "required": true }, "responses": { "200": { "description": "Finite source-bound preview; no durable input or model run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalSelectionPreviewResponse" } } } }, "400": { "description": "Malformed version/identity/time or text exceeds bounds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Source/session unavailable for this process owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/user-terminals/{terminal_id}/selection-submissions": { "post": { "tags": [ "conversation" ], "operationId": "post_sessions_session_id_user_terminals_terminal_id_selection_submissions", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "terminal_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalSelectionSubmissionRequest" } } }, "required": true }, "responses": { "200": { "description": "Durable intent receipt; replay never wakes or re-delivers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalSelectionSubmissionResponse" } } } }, "400": { "description": "Invalid version, identity, text or delivery contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Source, preview, delivery or immutable identity conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Persistence failure; reconcile the same identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/workspace/branches": { "get": { "tags": [ "workspace" ], "operationId": "get_sessions_session_id_workspace_branches", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchList" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "post": { "tags": [ "workspace" ], "operationId": "post_sessions_session_id_workspace_branches", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwitchBranchRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchList" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/workspace/commit": { "post": { "tags": [ "workspace" ], "operationId": "post_sessions_session_id_workspace_commit", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitWorkspaceRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommitOutcome" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/workspace/diff": { "get": { "tags": [ "workspace" ], "operationId": "get_sessions_session_id_workspace_diff", "parameters": [ { "name": "path", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "stage", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "context", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "revision", "in": "query", "description": "Look at a captured revision instead of the working tree.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceFileDiff" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/workspace/file": { "get": { "tags": [ "workspace" ], "operationId": "get_sessions_session_id_workspace_file", "parameters": [ { "name": "path", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "revision", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceFileContent" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/workspace/files": { "get": { "tags": [ "workspace" ], "operationId": "get_sessions_session_id_workspace_files", "parameters": [ { "name": "revision", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceFileList" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/workspace/open": { "post": { "tags": [ "workspace" ], "operationId": "post_sessions_session_id_workspace_open", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenWorkspacePathRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenLocalPathResult" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "501": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/workspace/reveal": { "post": { "tags": [ "workspace" ], "operationId": "post_sessions_session_id_workspace_reveal", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevealWorkspacePathRequest" } } }, "required": true }, "responses": { "200": { "description": "Existing Local path revealed in Finder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenLocalPathResult" } } } }, "400": { "description": "Invalid or stale workspace path", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Session or target unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Reveal rejected or unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/workspace/revisions": { "get": { "tags": [ "workspace" ], "operationId": "get_sessions_session_id_workspace_revisions", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceRevisionRecord" } } } } }, "400": { "description": "Path extraction failed", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/sessions/{session_id}/workspace/revisions/{revision_id}/changes": { "get": { "tags": [ "workspace" ], "operationId": "get_sessions_session_id_workspace_revisions_revision_id_changes", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "revision_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceRevisionChanges" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/ssh-configs": { "get": { "tags": [ "ssh-configs" ], "operationId": "get_ssh_configs", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SshConfigurationList" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "post": { "tags": [ "ssh-configs" ], "operationId": "post_ssh_configs", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSshConfigurationRequest" } } }, "required": true }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SshConfigurationRecord" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/ssh-configs/{config_id}": { "delete": { "tags": [ "ssh-configs" ], "operationId": "delete_ssh_configs_config_id", "parameters": [ { "name": "config_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Success with no response body" }, "400": { "description": "Path extraction failed", "content": { "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "patch": { "tags": [ "ssh-configs" ], "operationId": "patch_ssh_configs_config_id", "parameters": [ { "name": "config_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSshConfigurationRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SshConfigurationRecord" } } } }, "400": { "description": "Bad request or rejected path/query/body extraction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } }, "text/plain": { "schema": { "type": "string" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/ssh/browse": { "post": { "tags": [ "filesystem" ], "summary": "The same listing for a directory on an SSH host, which is also how the launch\nform tests the connection before it offers the rest of the form.", "operationId": "post_ssh_browse", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SshBrowseRequest" } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowseListing" } } } }, "400": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "403": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "502": { "description": "Request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/store": { "get": { "tags": [ "system" ], "operationId": "get_store", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreInfo" } } } } } } }, "/task-launches": { "post": { "tags": [ "sessions" ], "operationId": "start", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskLaunchRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskLaunchRecord" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/task-launches/{request_id}": { "get": { "tags": [ "sessions" ], "operationId": "status", "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskLaunchRecord" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/task-launches/{request_id}/cancel": { "post": { "tags": [ "sessions" ], "operationId": "cancel", "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskLaunchRecord" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/ui-config": { "get": { "operationId": "get_ui_configuration", "responses": { "200": { "description": "Runtime browser presentation policy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UiConfiguration" } } } } } } } }, "components": { "schemas": { "ActiveCompactionSnapshot": { "type": "object", "required": [ "compaction_id", "started_at_epoch_ms" ], "properties": { "client_id": { "oneOf": [ { "$ref": "#/components/schemas/SessionClientId" }, { "type": "null" } ] }, "compaction_id": { "type": "string", "format": "uuid" }, "started_at_epoch_ms": { "type": "integer", "format": "int64", "minimum": 0 } } }, "ActiveRunSnapshot": { "type": "object", "required": [ "run_id", "prompt_preview", "started_at_epoch_ms" ], "properties": { "client_id": { "oneOf": [ { "$ref": "#/components/schemas/SessionClientId" }, { "type": "null" } ] }, "prompt_preview": { "type": "string" }, "run_id": { "$ref": "#/components/schemas/SessionRunId" }, "started_at_epoch_ms": { "type": "integer", "format": "int64", "minimum": 0 }, "submitted_user_message": { "oneOf": [ { "$ref": "#/components/schemas/SubmittedUserMessageSnapshot" }, { "type": "null" } ] } } }, "AgentEvent": { "oneOf": [ { "type": "object", "required": [ "prompt_preview", "type" ], "properties": { "prompt_preview": { "type": "string" }, "thread_name": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "run_started" ] } } }, { "type": "object", "required": [ "iteration", "type" ], "properties": { "iteration": { "type": "integer", "minimum": 0 }, "thread_name": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "model_call_started" ] } } }, { "type": "object", "required": [ "usage", "type" ], "properties": { "thread_name": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "token_usage_updated" ] }, "usage": { "$ref": "#/components/schemas/TokenUsage" } } }, { "type": "object", "required": [ "call_id", "name", "args_preview", "type" ], "properties": { "args_detail": { "type": [ "string", "null" ] }, "args_preview": { "type": "string" }, "call_id": { "type": "string" }, "key_arg_preview": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "thread_name": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "tool_call_started" ] } } }, { "type": "object", "required": [ "call_id", "name", "content_preview", "is_error", "type" ], "properties": { "call_id": { "type": "string" }, "cleanup_duration_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "command_status": { "oneOf": [ { "$ref": "#/components/schemas/CommandStatus" }, { "type": "null" } ] }, "completion_status": { "oneOf": [ { "$ref": "#/components/schemas/ToolCompletionStatus" }, { "type": "null" } ] }, "content_preview": { "type": "string" }, "effective_timeout_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "execution_duration_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "exit_code": { "type": [ "integer", "null" ], "format": "int32" }, "is_error": { "type": "boolean" }, "name": { "type": "string" }, "remote_outcome_uncertain": { "type": "boolean" }, "thread_name": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "tool_call_finished" ] } } }, { "type": "object", "required": [ "name", "action", "source_threads", "type" ], "properties": { "action": { "type": "string" }, "name": { "type": "string" }, "source_threads": { "type": "array", "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "thread_started" ] } } }, { "type": "object", "required": [ "name", "line", "type" ], "properties": { "line": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "thread_log" ] } } }, { "type": "object", "required": [ "name", "steering_id", "instruction_preview", "type" ], "properties": { "instruction_preview": { "type": "string" }, "name": { "type": "string" }, "steering_id": { "type": "integer", "format": "int64" }, "type": { "type": "string", "enum": [ "thread_steering_queued" ] } } }, { "type": "object", "required": [ "name", "steering_id", "instruction_preview", "type" ], "properties": { "instruction_preview": { "type": "string" }, "name": { "type": "string" }, "steering_id": { "type": "integer", "format": "int64" }, "type": { "type": "string", "enum": [ "thread_steering_delivered" ] } } }, { "type": "object", "required": [ "name", "steering_id", "instruction_preview", "type" ], "properties": { "instruction_preview": { "type": "string" }, "name": { "type": "string" }, "steering_id": { "type": "integer", "format": "int64" }, "type": { "type": "string", "enum": [ "thread_steering_expired" ] } } }, { "type": "object", "required": [ "steering_id", "instruction_preview", "type" ], "properties": { "instruction_preview": { "type": "string" }, "steering_id": { "type": "integer", "format": "int64" }, "type": { "type": "string", "enum": [ "orchestrator_steering_queued" ] } } }, { "type": "object", "required": [ "steering_id", "instruction_preview", "type" ], "properties": { "instruction_preview": { "type": "string" }, "steering_id": { "type": "integer", "format": "int64" }, "type": { "type": "string", "enum": [ "orchestrator_steering_delivered" ] } } }, { "type": "object", "required": [ "steering_id", "instruction_preview", "type" ], "properties": { "instruction_preview": { "type": "string" }, "steering_id": { "type": "integer", "format": "int64" }, "type": { "type": "string", "enum": [ "orchestrator_steering_expired" ] } } }, { "type": "object", "required": [ "compaction_id", "reason", "type" ], "properties": { "compaction_id": { "type": "string", "format": "uuid" }, "reason": { "$ref": "#/components/schemas/CompactionReason" }, "type": { "type": "string", "enum": [ "orchestrator_compaction_started" ] } } }, { "type": "object", "required": [ "compaction_id", "reason", "type" ], "properties": { "compaction_id": { "type": "string", "format": "uuid" }, "reason": { "$ref": "#/components/schemas/CompactionReason" }, "type": { "type": "string", "enum": [ "orchestrator_compaction_completed" ] } } }, { "type": "object", "required": [ "compaction_id", "reason", "cause", "type" ], "properties": { "cause": { "$ref": "#/components/schemas/CompactionSkipReason" }, "compaction_id": { "type": "string", "format": "uuid" }, "reason": { "$ref": "#/components/schemas/CompactionReason" }, "type": { "type": "string", "enum": [ "orchestrator_compaction_skipped" ] } } }, { "type": "object", "required": [ "compaction_id", "reason", "failure", "type" ], "properties": { "compaction_id": { "type": "string", "format": "uuid" }, "failure": { "$ref": "#/components/schemas/CompactionFailure" }, "reason": { "$ref": "#/components/schemas/CompactionReason" }, "type": { "type": "string", "enum": [ "orchestrator_compaction_failed" ] } } }, { "type": "object", "required": [ "name", "exit_code", "timed_out", "type" ], "properties": { "exit_code": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "timed_out": { "type": "boolean" }, "timeout_reason": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "thread_finished" ] }, "usage": { "oneOf": [ { "$ref": "#/components/schemas/TokenUsage" }, { "type": "null" } ] } } }, { "type": "object", "required": [ "content", "type" ], "properties": { "content": { "type": "string" }, "thread_name": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "assistant_message" ] }, "usage": { "oneOf": [ { "$ref": "#/components/schemas/TokenUsage" }, { "type": "null" } ] } } }, { "type": "object", "required": [ "message", "type" ], "properties": { "message": { "type": "string" }, "thread_name": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "error" ] } } }, { "type": "object", "description": "A configured MCP server that could not be loaded for a worker, reported\nwith a bounded, credential-redacted reason so the user can see why the\nserver's tools are missing.", "required": [ "server_name", "reason", "type" ], "properties": { "reason": { "type": "string" }, "server_name": { "type": "string" }, "thread_name": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "mcp_server_skipped" ] } } }, { "type": "object", "description": "Bounded, credential-redacted MCP server activity. These notifications\nare live-only because older durable event readers do not know this\nvocabulary and catalog state is reconstructed from the server.", "required": [ "server_name", "kind", "message", "type" ], "properties": { "kind": { "$ref": "#/components/schemas/McpNotificationKind" }, "message": { "type": "string" }, "server_name": { "type": "string" }, "thread_name": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "mcp_notification" ] } } }, { "type": "object", "description": "A model call the provider itself refused, reported with credentials\nredacted.\n\nOrdinary errors are reduced to a constant before they leave the process,\nbecause their text can carry paths and tool output. What a provider says\nabout its own API — no credits, bad key, rate limit, context too long —\ncarries none of that and is the one thing the user has to see to act, so\nit travels intact apart from credential material, which is masked before\nthe event leaves the process. Live-only, like the other events whose\nabsence keeps the persisted stream readable by older builds.", "required": [ "message", "type" ], "properties": { "message": { "type": "string" }, "thread_name": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "model_error" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "thread_name": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "run_finished" ] } } } ] }, "ApiErrorBody": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "AssignSessionRequest": { "type": "object", "required": [ "session_id" ], "properties": { "session_id": { "type": "string" } } }, "AssistantStreamDelta": { "type": "object", "description": "A slice of model output as it is being produced. Rides its own channel\nrather than [`SessionEvent`]: deltas arrive an order of magnitude more\noften than session events, they are worthless the moment the assistant\nmessage lands, and pushing them through the sequenced bus would evict the\nreplay ring a reconnecting client depends on. So no sequence id, no replay,\nno persistence — a subscriber that falls behind just misses text it is about\nto receive in full anyway.", "properties": { "reasoning": { "type": [ "string", "null" ] }, "reset": { "type": "boolean", "description": "Clear abandoned live output before displaying a replacement attempt." }, "retry_attempt": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "text": { "type": [ "string", "null" ] }, "thread_name": { "type": [ "string", "null" ] } } }, "AttachUserTerminalRequest": { "type": "object", "required": [ "protocol_version", "page_limit" ], "properties": { "page_limit": { "type": "integer", "format": "int32", "maximum": 65536, "minimum": 1 }, "protocol_version": { "type": "integer", "format": "int32", "minimum": 0 } }, "additionalProperties": false }, "AttentionAvailabilityDto": { "type": "object", "required": [ "work", "questions", "permissions", "reviews", "topology" ], "properties": { "permissions": { "$ref": "#/components/schemas/AttentionFacetDto" }, "questions": { "$ref": "#/components/schemas/AttentionFacetDto" }, "reviews": { "$ref": "#/components/schemas/AttentionFacetDto" }, "topology": { "$ref": "#/components/schemas/AttentionFacetDto" }, "work": { "$ref": "#/components/schemas/AttentionFacetDto" } } }, "AttentionChangeDto": { "oneOf": [ { "type": "object", "required": [ "snapshot", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "source_replaced" ] }, "snapshot": { "$ref": "#/components/schemas/AttentionSnapshotDto" } } }, { "type": "object", "required": [ "work", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "work_settled" ] }, "work": { "$ref": "#/components/schemas/AttentionWorkDto" } } }, { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "work_cleared" ] } } }, { "type": "object", "required": [ "decision", "kind" ], "properties": { "decision": { "$ref": "#/components/schemas/AttentionDecisionDto" }, "kind": { "type": "string", "enum": [ "decision_pending" ] } } }, { "type": "object", "required": [ "decision", "kind" ], "properties": { "decision": { "$ref": "#/components/schemas/AttentionDecisionDto" }, "kind": { "type": "string", "enum": [ "decision_resolved" ] } } }, { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "session_deleted" ] } } }, { "type": "object", "required": [ "availability", "kind" ], "properties": { "availability": { "$ref": "#/components/schemas/AttentionAvailabilityDto" }, "kind": { "type": "string", "enum": [ "availability" ] } } }, { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "checkpoint" ] } } } ] }, "AttentionCursor": { "type": "object", "required": [ "engine", "epoch", "sequence" ], "properties": { "engine": { "type": "string" }, "epoch": { "type": "string" }, "sequence": { "type": "integer", "format": "int64", "minimum": 0 } } }, "AttentionDecisionDto": { "oneOf": [ { "type": "object", "required": [ "request_id", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "permission" ] }, "request_id": { "type": "string" } } }, { "type": "object", "required": [ "review_id", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "review" ] }, "review_id": { "type": "string" } } }, { "type": "object", "required": [ "request_id", "run_id", "generation", "revision", "kind" ], "properties": { "generation": { "type": "string" }, "kind": { "type": "string", "enum": [ "question" ] }, "request_id": { "type": "string" }, "revision": { "type": "integer", "format": "int64", "minimum": 0 }, "run_id": { "type": "string" } } } ] }, "AttentionDispositionDto": { "type": "string", "enum": [ "completed", "continuing", "waiting_for_decision" ] }, "AttentionFacetDto": { "type": "string", "enum": [ "available", "unknown", "unsupported" ] }, "AttentionFrame": { "oneOf": [ { "type": "object", "required": [ "page", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "completions" ] }, "page": { "$ref": "#/components/schemas/CompletionPageDto" } } }, { "type": "object", "required": [ "boundary", "sources", "reset", "kind" ], "properties": { "boundary": { "$ref": "#/components/schemas/AttentionCursor" }, "kind": { "type": "string", "enum": [ "baseline" ] }, "reset": { "oneOf": [ { "$ref": "#/components/schemas/AttentionResetDto" }, { "type": "null" } ] }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/AttentionSnapshotDto" } } } }, { "type": "object", "required": [ "boundary", "source", "source_revision", "change", "new_attention", "kind" ], "properties": { "boundary": { "$ref": "#/components/schemas/AttentionCursor" }, "change": { "$ref": "#/components/schemas/AttentionChangeDto" }, "kind": { "type": "string", "enum": [ "record" ] }, "new_attention": { "type": "boolean" }, "source": { "$ref": "#/components/schemas/AttentionSourceDto" }, "source_revision": { "type": "integer", "format": "int64", "minimum": 0 } } }, { "type": "object", "required": [ "reason", "kind" ], "properties": { "kind": { "type": "string", "enum": [ "reset" ] }, "reason": { "$ref": "#/components/schemas/AttentionResetDto" } } } ], "description": "Current-state baselines are silent. Historical completion pages use their\nown stable store frontier and never infer that a whole session is idle." }, "AttentionGoalDto": { "type": "object", "required": [ "id", "version" ], "properties": { "id": { "type": "string" }, "version": { "type": "integer", "format": "int64", "minimum": 0 } } }, "AttentionResetDto": { "type": "string", "enum": [ "incarnation", "replay_gap", "invalid_cursor" ] }, "AttentionSnapshotDto": { "type": "object", "required": [ "source", "revision", "work", "pending", "availability" ], "properties": { "availability": { "$ref": "#/components/schemas/AttentionAvailabilityDto" }, "pending": { "type": "array", "items": { "$ref": "#/components/schemas/AttentionDecisionDto" } }, "revision": { "type": "integer", "format": "int64", "minimum": 0 }, "source": { "$ref": "#/components/schemas/AttentionSourceDto" }, "work": { "oneOf": [ { "$ref": "#/components/schemas/AttentionWorkDto" }, { "type": "null" } ] } } }, "AttentionSourceDto": { "type": "object", "required": [ "session_id", "epoch" ], "properties": { "epoch": { "type": "string" }, "session_id": { "type": "string" } } }, "AttentionWorkDto": { "type": "object", "required": [ "run_id", "goal", "disposition" ], "properties": { "disposition": { "$ref": "#/components/schemas/AttentionDispositionDto" }, "goal": { "oneOf": [ { "$ref": "#/components/schemas/AttentionGoalDto" }, { "type": "null" } ] }, "run_id": { "type": "string" } } }, "AuthStatus": { "type": "string", "description": "Whether a provider has a usable credential right now, as served by\n`GET /models`. A picker HINT only — it never changes how auth works:\nAPI-key providers still read only the exact `api_key_env` selector and\nmanaged providers still read only their stored credential file.", "enum": [ "ready", "no_credential" ] }, "AuthenticateMcpOAuthRequest": { "type": "object", "properties": { "additional_scopes": { "type": "array", "items": { "type": "string" } } } }, "AuthenticateMcpOAuthResponse": { "type": "object", "required": [ "status", "authorization_url" ], "properties": { "authorization_url": { "type": "string" }, "status": { "$ref": "#/components/schemas/McpOAuthPublicStatus" } } }, "BackendKind": { "type": "string", "enum": [ "deepseek-chat", "fireworks-chat", "together-chat", "openai-responses", "openai-chat-completions", "chatgpt-codex-responses", "anthropic-messages", "arcee-auth", "arcee-api" ] }, "Branch": { "type": "object", "required": [ "name", "is_current" ], "properties": { "is_current": { "type": "boolean" }, "name": { "type": "string" } } }, "BranchList": { "type": "object", "required": [ "branches", "dirty" ], "properties": { "branches": { "type": "array", "items": { "$ref": "#/components/schemas/Branch" } }, "current": { "type": [ "string", "null" ], "description": "None on a detached HEAD or in a repository without commits." }, "dirty": { "type": "boolean", "description": "Tracked files differ from HEAD, which makes switching unsafe." } } }, "BrowseEntry": { "type": "object", "required": [ "name", "path", "is_directory" ], "properties": { "is_directory": { "type": "boolean" }, "name": { "type": "string" }, "path": { "type": "string" } } }, "BrowseKind": { "type": "string", "enum": [ "directory", "toml", "file" ] }, "BrowseListing": { "type": "object", "required": [ "path", "entries", "truncated" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/BrowseEntry" } }, "home": { "type": [ "string", "null" ] }, "parent": { "type": [ "string", "null" ], "description": "`None` at a filesystem root, which is where upward navigation stops." }, "path": { "type": "string", "description": "Canonical path of the listed directory." }, "truncated": { "type": "boolean" } } }, "CancelInboxItemRequest": { "type": "object", "required": [ "expected_version" ], "properties": { "expected_version": { "type": "integer", "format": "int64" } } }, "CancelQuestionRequest": { "type": "object", "required": [ "expected_revision" ], "properties": { "expected_revision": { "type": "integer", "format": "int64" } }, "additionalProperties": false }, "ChangedFileStat": { "type": "object", "required": [ "status", "path" ], "properties": { "additions": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "deletions": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "path": { "type": "string" }, "status": { "type": "string" } } }, "ClearGoalRequest": { "type": "object", "required": [ "expected_version" ], "properties": { "expected_version": { "type": "integer", "format": "int64" } } }, "CommandStatus": { "type": "string", "enum": [ "completed", "timed_out", "cancelled", "spawn_error" ] }, "CommitOutcome": { "type": "object", "required": [ "sha", "files_changed", "additions", "deletions" ], "properties": { "additions": { "type": "integer", "format": "int64", "minimum": 0 }, "branch": { "type": [ "string", "null" ], "description": "None on a detached HEAD." }, "deletions": { "type": "integer", "format": "int64", "minimum": 0 }, "files_changed": { "type": "integer", "minimum": 0 }, "sha": { "type": "string" } } }, "CommitWorkspaceRequest": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "CompactSessionResponse": { "oneOf": [ { "type": "object", "required": [ "compaction_id", "status" ], "properties": { "compaction_id": { "type": "string" }, "status": { "type": "string", "enum": [ "compacted" ] } } }, { "type": "object", "required": [ "compaction_id", "reason", "status" ], "properties": { "compaction_id": { "type": "string" }, "reason": { "$ref": "#/components/schemas/CompactionSkipReason" }, "status": { "type": "string", "enum": [ "unchanged" ] } } } ] }, "CompactionFailure": { "type": "string", "enum": [ "summary_request_failed", "summary_rejected", "checkpoint_persistence_failed", "cancelled" ] }, "CompactionReason": { "type": "string", "enum": [ "auto", "manual" ] }, "CompactionSkipReason": { "type": "string", "enum": [ "no_eligible_boundary", "already_compacted" ] }, "CompletionKindDto": { "type": "string", "enum": [ "request", "goal" ] }, "CompletionOccurrenceDto": { "type": "object", "required": [ "sequence", "session_id", "run_id", "behavior", "kind", "goal_id", "mark_version" ], "properties": { "behavior": { "type": "string" }, "goal_id": { "type": [ "string", "null" ] }, "kind": { "$ref": "#/components/schemas/CompletionKindDto" }, "mark_version": { "type": [ "integer", "null" ], "format": "int64" }, "run_id": { "type": "string" }, "sequence": { "type": "integer", "format": "int64" }, "session_id": { "type": "string" } } }, "CompletionPageDto": { "type": "object", "required": [ "store_id", "cursor", "high_water", "baseline", "more", "items" ], "properties": { "baseline": { "type": "boolean" }, "cursor": { "type": "integer", "format": "int64" }, "high_water": { "type": "integer", "format": "int64" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CompletionOccurrenceDto" } }, "more": { "type": "boolean" }, "store_id": { "type": "string" } } }, "ConfigureMcpOAuthRequest": { "type": "object", "properties": { "authorization_metadata": { "oneOf": [ { "$ref": "#/components/schemas/McpOAuthAuthorizationMetadataRequest" }, { "type": "null" } ] }, "client_id_credential": { "type": [ "string", "null" ], "deprecated": true, "writeOnly": true }, "client_secret_credential": { "type": [ "string", "null" ], "deprecated": true, "writeOnly": true }, "registration": { "oneOf": [ { "$ref": "#/components/schemas/McpOAuthRegistrationRequest" }, { "type": "null" } ] }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "ControlledTerminalInputRequest": { "type": "object", "required": [ "protocol_version", "expected_revision", "bytes" ], "properties": { "bytes": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } }, "expected_revision": { "type": "string" }, "protocol_version": { "type": "integer", "format": "int32", "minimum": 0 } }, "additionalProperties": false }, "CostTier": { "type": "object", "description": "One context-priced rate step (models.dev `cost.tiers[]` with\n`tier.type == \"context\"`): applies when the response's prompt tokens\n(input + cache read + cache write) exceed `input_tokens_above`. Rates\nare complete — mappers fill buckets a tier omits from the base rates, so\nselection is a wholesale swap.", "required": [ "input_tokens_above", "input", "output", "cache_read", "cache_write" ], "properties": { "cache_read": { "type": "number", "format": "double" }, "cache_write": { "type": "number", "format": "double" }, "input": { "type": "number", "format": "double" }, "input_tokens_above": { "type": "integer", "format": "int64", "minimum": 0 }, "output": { "type": "number", "format": "double" } } }, "CreateGoalRequest": { "type": "object", "required": [ "objective" ], "properties": { "objective": { "type": "string" }, "token_budget": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } }, "CreateInboxItemRequest": { "type": "object", "required": [ "delivery", "prompt" ], "properties": { "delivery": { "$ref": "#/components/schemas/InboxDelivery" }, "prompt": { "type": "string" } } }, "CreateMcpServerRequest": { "type": "object", "required": [ "name", "transport" ], "properties": { "allowed_tools": { "type": [ "array", "null" ], "items": { "type": "string" } }, "approval": { "$ref": "#/components/schemas/McpToolApproval" }, "args": { "type": "array", "items": { "type": "string" } }, "bearer_token_env_var": { "type": [ "string", "null" ] }, "catalog_timeout_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "command": { "type": [ "string", "null" ] }, "cwd": { "type": [ "string", "null" ] }, "denied_tools": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "env": { "type": "object", "additionalProperties": { "type": "string", "writeOnly": true }, "propertyNames": { "type": "string", "writeOnly": true }, "example": { "TOKEN": "fake-token" } }, "env_headers": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "env_vars": { "type": "array", "items": { "type": "string" } }, "execution_timeout_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "header_helper": { "oneOf": [ { "$ref": "#/components/schemas/McpHeaderHelperConfig" }, { "type": "null" } ] }, "headers": { "type": "object", "additionalProperties": { "type": "string", "writeOnly": true }, "propertyNames": { "type": "string", "writeOnly": true }, "example": { "Authorization": "Bearer fake-token" } }, "library_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "protocol": { "$ref": "#/components/schemas/McpProtocolSelection" }, "required": { "type": "boolean" }, "startup_timeout_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "tool_approvals": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/McpToolApproval" }, "propertyNames": { "type": "string" } }, "transport": { "$ref": "#/components/schemas/McpTransportSchema" }, "url": { "type": [ "string", "null" ] } } }, "CreateModelConfigurationRequest": { "type": "object", "required": [ "name", "backend", "model" ], "properties": { "allow_insecure_http": { "type": "boolean", "description": "Explicitly permit sending credentials and model traffic over public plaintext HTTP.", "default": false }, "api_key": { "type": [ "string", "null" ], "example": "fake-api-key", "writeOnly": true }, "backend": { "$ref": "#/components/schemas/BackendKind" }, "base_url": { "type": [ "string", "null" ], "description": "Defaults to the provider's canonical URL." }, "extra_headers": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "initial_prompt": { "type": [ "string", "null" ] }, "light_model": { "oneOf": [ { "$ref": "#/components/schemas/LightModelSettings" }, { "type": "null" } ] }, "model": { "type": "string" }, "name": { "type": "string" }, "orchestrator_compaction_threshold": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "reasoning_effort": { "oneOf": [ { "$ref": "#/components/schemas/ReasoningEffort" }, { "type": "null" } ] } } }, "CreateProjectRequest": { "type": "object", "required": [ "cwd" ], "properties": { "cwd": { "type": "string" }, "default_model_config_id": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "ssh_host": { "type": [ "string", "null" ] }, "ssh_identity_file": { "type": [ "string", "null" ] }, "ssh_port": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } }, "CreateSessionRequest": { "type": "object", "properties": { "allow_insecure_http": { "$ref": "#/components/schemas/RequestField_bool_bool", "description": "Explicitly permit public plaintext HTTP for this session's primary and light endpoints." }, "api_key_env": { "$ref": "#/components/schemas/RequestField_String_String" }, "backend": { "$ref": "#/components/schemas/RequestField_String_String" }, "base_url": { "$ref": "#/components/schemas/RequestField_String_String" }, "behavior": { "$ref": "#/components/schemas/SessionBehavior", "description": "Immutable execution behavior. Omission preserves the established\norchestrator default." }, "cwd": { "type": [ "string", "null" ] }, "extra_headers": { "$ref": "#/components/schemas/RequestField_HeadersRequest_HeadersRequest", "description": "Prefer a JSON object. A JSON-encoded object string remains accepted for compatibility." }, "first_chat": { "type": "boolean", "description": "Marks the required first chat for an empty project. The server\nserializes this admission and returns the already-created primary chat\nto concurrent callers instead of creating a duplicate. Ordinary New\nChat requests leave this false." }, "first_chat_same_behavior": { "type": "boolean", "description": "Opt-in first-chat admission restricted to the requested immutable behavior.\nOmission preserves newest-primary admission across all behaviors." }, "light_model": { "$ref": "#/components/schemas/RequestField_LightModelSettings_LightModelSettings", "description": "Optional light model. Omitted inherits project/session defaults, null\nexplicitly selects single-model operation, and a value replaces the\ninherited selection." }, "model": { "$ref": "#/components/schemas/RequestField_String_String" }, "orchestrator_compaction_threshold": { "$ref": "#/components/schemas/RequestField_u64_u64", "description": "Omitted defaults to 70% of the model's context window; null or zero disables." }, "project_id": { "type": [ "string", "null" ], "description": "Explicit project selection. Projects are never inferred from `cwd`." }, "reasoning_effort": { "$ref": "#/components/schemas/RequestField_String_String" }, "sandbox": { "$ref": "#/components/schemas/SandboxRequest" }, "ssh_host": { "type": [ "string", "null" ], "description": "OpenSSH target for remote sessions; `cwd` is remote and defaults to `~`." }, "ssh_identity_file": { "type": [ "string", "null" ] }, "ssh_port": { "type": [ "integer", "null" ], "format": "int32", "description": "Port and private key for the ssh target. Both are optional: omitted\nleaves the choice to ssh, which is what a host configured in\n`~/.ssh/config` wants. Supplying them is what lets a session reach a box\nnac has no config for at all.", "minimum": 0 } } }, "CreateSshConfigurationRequest": { "type": "object", "required": [ "name", "ssh_host" ], "properties": { "name": { "type": "string" }, "ssh_host": { "type": "string" }, "ssh_identity_file": { "type": [ "string", "null" ] }, "ssh_port": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } }, "DefaultLimits": { "type": "object", "description": "A provider `_default` entry's limits and effort support, as served by\n`GET /models`: powers the frontend's unrecognized-model badge, estimated\ncontext gauge and custom-model effort list without a second resolve call.", "required": [ "context_window", "max_tokens", "supported_efforts" ], "properties": { "context_window": { "type": "integer", "format": "int64", "minimum": 0 }, "max_tokens": { "type": "integer", "format": "int64", "minimum": 0 }, "supported_efforts": { "type": "array", "items": { "$ref": "#/components/schemas/ReasoningEffort" } } } }, "DeleteProjectResponse": { "type": "object", "required": [ "released_session_ids", "deleted_session_ids" ], "properties": { "deleted_session_ids": { "type": "array", "items": { "type": "string" }, "description": "Sessions deleted along with the project." }, "released_session_ids": { "type": "array", "items": { "type": "string" }, "description": "Sessions that stayed behind and are now unassigned." } } }, "DeleteProjectSessions": { "type": "string", "description": "What a project delete does with the chats inside it.", "enum": [ "keep", "delete" ] }, "DeviceLoginStartedResponse": { "type": "object", "required": [ "login_id", "provider", "verification_uri", "user_code", "expires_in_secs" ], "properties": { "expires_in_secs": { "type": "integer", "format": "int64", "minimum": 0 }, "login_id": { "type": "string", "description": "Handle for polling this login; it names nothing on disk." }, "provider": { "$ref": "#/components/schemas/ManagedAuthProvider" }, "user_code": { "type": [ "string", "null" ], "description": "Present only when the flow leaves something to read out: Codex's device\nflow expects it typed, Arcee's asks for it to be checked against the\npage, and the redirect flow has nothing to show at all." }, "verification_uri": { "type": "string", "description": "The page to open." } } }, "DeviceLoginStateResponse": { "oneOf": [ { "type": "object", "description": "The provider has not seen the user approve it yet.", "required": [ "state" ], "properties": { "state": { "type": "string", "enum": [ "pending" ] } } }, { "type": "object", "required": [ "auth", "state" ], "properties": { "auth": { "$ref": "#/components/schemas/ManagedAuthStatusResponse" }, "state": { "type": "string", "enum": [ "complete" ] } } }, { "type": "object", "required": [ "error", "state" ], "properties": { "error": { "type": "string" }, "state": { "type": "string", "enum": [ "failed" ] } } } ] }, "EpisodeSnapshot": { "type": "object", "required": [ "id", "thread_name", "session_id", "action", "content", "status", "created_at" ], "properties": { "action": { "type": "string" }, "content": { "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "integer", "format": "int64" }, "session_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/EpisodeStatus", "description": "`ok` for a retained handoff, otherwise how the dispatch died. Snapshots\nwritten before dispatch outcomes were recorded only held handoffs." }, "thread_name": { "type": "string" } } }, "EpisodeStatus": { "type": "string", "description": "How a dispatch ended.\n\nOnly [`EpisodeStatus::Ok`] episodes are retained context: they are the ones\na later dispatch reads back and the ones `thread_read` renders. The failure\nkinds exist so the panel can still show what a thread was asked to do and\nhow it died, which is otherwise lost the moment the worker is killed.", "enum": [ "ok", "error", "timed_out", "cancelled" ] }, "ExecutionFrameResponse": { "type": "object", "required": [ "protocol_version", "observer_id", "terminal", "execution", "bytes", "offset", "next_offset", "retained_start", "retained_end", "gap", "caught_up", "requires_ack", "segments" ], "properties": { "bytes": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } }, "caught_up": { "type": "boolean" }, "execution": { "$ref": "#/components/schemas/ExecutionStatus" }, "gap": { "type": "boolean" }, "next_offset": { "type": "string" }, "observer_id": { "type": "string" }, "offset": { "type": "string" }, "protocol_version": { "type": "integer", "format": "int32", "minimum": 0 }, "requires_ack": { "type": "boolean" }, "retained_end": { "type": "string" }, "retained_start": { "type": "string" }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/ExecutionOutputSegment" } }, "terminal": { "$ref": "#/components/schemas/UserTerminalResponse" } } }, "ExecutionHistory": { "type": "object", "required": [ "entries", "limit", "older_entries_omitted" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ExecutionHistoryEntry" } }, "limit": { "type": "integer", "minimum": 0 }, "older_entries_omitted": { "type": "boolean" } } }, "ExecutionHistoryEntry": { "type": "object", "required": [ "id", "output", "started_at_epoch_ms" ], "properties": { "command": { "oneOf": [ { "$ref": "#/components/schemas/ShellCommandSnapshot", "description": "Canonical durable result/preview; private output artifact ids are omitted." }, { "type": "null" } ] }, "execution": { "oneOf": [ { "$ref": "#/components/schemas/ExecutionStatus" }, { "type": "null" } ] }, "id": { "type": "string", "description": "Canonical session-scoped human command request identity, or the existing local\nexecution identity. This is a view key, never an execution capability." }, "outcome": { "oneOf": [ { "$ref": "#/components/schemas/CommandStatus", "description": "Pipe process result, independent of collector completion/error. PTY\nexit codes remain in the existing execution status; absent is unknown." }, { "type": "null" } ] }, "output": { "$ref": "#/components/schemas/ExecutionHistoryOutput" }, "started_at_epoch_ms": { "type": "string" } } }, "ExecutionHistoryOutput": { "type": "object", "required": [ "availability" ], "properties": { "availability": { "$ref": "#/components/schemas/ExecutionOutputAvailability" }, "retained_end": { "type": [ "string", "null" ] }, "retained_start": { "type": [ "string", "null" ], "description": "Decimal byte cursors have the same exact wire contract as observation." } } }, "ExecutionHistoryResponse": { "type": "object", "required": [ "protocol_version", "history" ], "properties": { "history": { "$ref": "#/components/schemas/ExecutionHistory" }, "protocol_version": { "type": "integer", "format": "int32", "minimum": 0 } } }, "ExecutionListResponse": { "type": "object", "required": [ "protocol_version", "executions" ], "properties": { "executions": { "type": "array", "items": { "$ref": "#/components/schemas/ExecutionStatus" } }, "protocol_version": { "type": "integer", "format": "int32", "minimum": 0 } } }, "ExecutionOrigin": { "type": "string", "enum": [ "human", "agent", "human_command" ] }, "ExecutionOutputAvailability": { "type": "string", "enum": [ "retained", "tail_gap", "expired", "process_local_unavailable", "not_recorded" ] }, "ExecutionOutputSegment": { "type": "object", "required": [ "stream", "sequence", "combined_start", "combined_end", "stream_start", "stream_end" ], "properties": { "combined_end": { "type": "string" }, "combined_start": { "type": "string" }, "sequence": { "type": "string" }, "stream": { "type": "string" }, "stream_end": { "type": "string" }, "stream_start": { "type": "string" } } }, "ExecutionProcessState": { "type": "string", "enum": [ "running", "cleanup_pending", "settled" ] }, "ExecutionRepresentation": { "type": "string", "enum": [ "pty", "log" ] }, "ExecutionStatus": { "type": "object", "description": "Process settlement and collector completion are independent facts. IDs bind\nthis manager instance; artifact IDs are private implementation details.", "required": [ "id", "origin", "representation", "cwd", "backend", "alive", "process_state", "output_complete", "input", "resize", "stop", "retained", "cols", "rows" ], "properties": { "alive": { "type": "boolean" }, "backend": { "type": "string" }, "cols": { "type": "integer", "format": "int32", "minimum": 0 }, "cwd": { "type": "string" }, "exit_code": { "type": [ "integer", "null" ], "format": "int32" }, "id": { "type": "string" }, "input": { "type": "boolean" }, "origin": { "$ref": "#/components/schemas/ExecutionOrigin" }, "output_complete": { "type": "boolean" }, "output_error": { "type": [ "string", "null" ] }, "process_state": { "$ref": "#/components/schemas/ExecutionProcessState" }, "representation": { "$ref": "#/components/schemas/ExecutionRepresentation" }, "request_id": { "type": [ "string", "null" ] }, "resize": { "type": "boolean" }, "retained": { "type": "boolean" }, "rows": { "type": "integer", "format": "int32", "minimum": 0 }, "stop": { "type": "boolean" } } }, "ForkSessionRequest": { "type": "object", "required": [ "message_idx" ], "properties": { "message_idx": { "type": "integer", "description": "Transcript index of the assistant message to fork from. Trailing tool\nresults that belong to that turn are copied with it.", "minimum": 0 } } }, "ForkSessionResponse": { "type": "object", "required": [ "session_id" ], "properties": { "session_id": { "type": "string" } } }, "FreshTaskDestination": { "type": "object", "description": "Explicit choices are retained; absent model/reasoning choices inherit the\ndestination's defaults when a new occurrence is prepared.", "required": [ "project_id", "retained_limit" ], "properties": { "default_ref": { "type": [ "string", "null" ], "description": "Used only to establish an unbound project's saved default branch.\nAn existing binding cannot be silently replaced by this value." }, "model": { "type": [ "string", "null" ] }, "pinned_commit": { "type": [ "string", "null" ] }, "project_id": { "type": "string" }, "reasoning_effort": { "type": [ "string", "null" ] }, "retained_limit": { "type": "integer", "format": "int64" } }, "additionalProperties": false }, "FreshTaskLaunchReceipt": { "type": "object", "description": "Durable reservation data. The host allowance counts this row before any\nmaterialization and keeps it after occurrence-history or task deletion.", "required": [ "occurrence_id", "schedule_id", "request", "destination", "binding", "session_id", "stop_requested", "created_at_ms" ], "properties": { "binding": { "$ref": "#/components/schemas/HeartbeatBinding" }, "created_at_ms": { "type": "integer", "format": "int64" }, "destination": { "$ref": "#/components/schemas/FreshTaskDestination" }, "first_input_id": { "type": [ "integer", "null" ], "format": "int64" }, "initial_outcome": { "oneOf": [ { "$ref": "#/components/schemas/HeartbeatOccurrence" }, { "type": "null" } ] }, "initial_run_id": { "type": [ "string", "null" ] }, "occurrence_id": { "type": "string" }, "request": { "$ref": "#/components/schemas/TaskLaunchRequest" }, "schedule_id": { "type": "string" }, "session_id": { "type": "string" }, "shared_directory": { "type": [ "boolean", "null" ] }, "stop_requested": { "type": "boolean" } } }, "FreshTaskRetainedAllowance": { "type": "object", "required": [ "revision", "retained_limit", "retained_count" ], "properties": { "retained_count": { "type": "integer", "format": "int64", "description": "Includes partial preparations and deleted tasks, across all projects." }, "retained_limit": { "type": "integer", "format": "int64" }, "revision": { "type": "integer", "format": "int64" } } }, "FreshTaskRetainedAllowanceChange": { "type": "object", "required": [ "request_id", "expected_revision", "retained_limit" ], "properties": { "expected_revision": { "type": "integer", "format": "int64" }, "request_id": { "type": "string" }, "retained_limit": { "type": "integer", "format": "int64" } }, "additionalProperties": false }, "FreshTaskRetainedAllowanceReceipt": { "type": "object", "required": [ "request_id", "allowance" ], "properties": { "allowance": { "$ref": "#/components/schemas/FreshTaskRetainedAllowance" }, "request_id": { "type": "string" } } }, "FreshTaskScheduleControlRequest": { "type": "object", "required": [ "request_id", "operation" ], "properties": { "creator_session_id": { "type": [ "string", "null" ] }, "destination": { "oneOf": [ { "$ref": "#/components/schemas/FreshTaskDestination" }, { "type": "null" } ] }, "operation": { "$ref": "#/components/schemas/HeartbeatAction" }, "request_id": { "type": "string" } }, "additionalProperties": false }, "FreshTaskScheduleInspection": { "type": "object", "required": [ "heartbeat", "inventory", "host_retained_limit", "host_allowance", "launches" ], "properties": { "heartbeat": { "$ref": "#/components/schemas/HeartbeatInspection" }, "host_allowance": { "$ref": "#/components/schemas/FreshTaskRetainedAllowance" }, "host_retained_limit": { "type": "integer", "format": "int64" }, "inventory": { "type": "array", "items": { "$ref": "#/components/schemas/FreshTaskLaunchReceipt" } }, "launches": { "type": "array", "items": { "$ref": "#/components/schemas/TaskLaunchRecord" } } } }, "FunctionCall": { "type": "object", "required": [ "name", "arguments" ], "properties": { "arguments": { "type": "string" }, "name": { "type": "string" } } }, "GeneratedCredential": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "GitHubBranchListResponse": { "type": "object", "required": [ "branches" ], "properties": { "branches": { "type": "array", "items": { "type": "string" } } } }, "GitHubLoginStartedResponse": { "type": "object", "required": [ "login_id", "verification_uri", "user_code", "expires_in_secs" ], "properties": { "expires_in_secs": { "type": "integer", "format": "int64", "minimum": 0 }, "login_id": { "type": "string" }, "user_code": { "type": "string" }, "verification_uri": { "type": "string" } } }, "GitHubLoginStateResponse": { "oneOf": [ { "type": "object", "required": [ "state" ], "properties": { "state": { "type": "string", "enum": [ "pending" ] } } }, { "type": "object", "required": [ "auth", "state" ], "properties": { "auth": { "$ref": "#/components/schemas/GitHubStatusResponse" }, "state": { "type": "string", "enum": [ "complete" ] } } }, { "type": "object", "required": [ "error", "state" ], "properties": { "error": { "type": "string" }, "state": { "type": "string", "enum": [ "failed" ] } } } ] }, "GitHubRepositoryListResponse": { "type": "object", "required": [ "repositories" ], "properties": { "repositories": { "type": "array", "items": { "$ref": "#/components/schemas/GitHubRepositoryResponse" } } } }, "GitHubRepositoryResponse": { "type": "object", "required": [ "id", "name", "full_name", "private", "can_read", "can_write", "default_branch", "clone_url", "html_url" ], "properties": { "can_read": { "type": "boolean" }, "can_write": { "type": "boolean" }, "clone_url": { "type": "string" }, "default_branch": { "type": "string" }, "full_name": { "type": "string" }, "html_url": { "type": "string" }, "id": { "type": "integer", "format": "int64", "minimum": 0 }, "name": { "type": "string" }, "private": { "type": "boolean" } } }, "GitHubStatusResponse": { "type": "object", "required": [ "configured", "connected", "git_configured" ], "properties": { "avatar_url": { "type": [ "string", "null" ] }, "configured": { "type": "boolean" }, "connected": { "type": "boolean" }, "expires_at_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "git_configured": { "type": "boolean" }, "git_email": { "type": [ "string", "null" ] }, "git_name": { "type": [ "string", "null" ] }, "login": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "organization": { "type": [ "string", "null" ] } } }, "GitIdentityResponse": { "type": "object", "required": [ "name", "email" ], "properties": { "email": { "type": "string" }, "name": { "type": "string" } } }, "GoalStatus": { "type": "string", "enum": [ "active", "paused", "blocked", "usage_limited", "budget_limited", "complete" ] }, "HealthResponse": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string" } } }, "HeartbeatAction": { "oneOf": [ { "type": "object", "required": [ "spec", "action" ], "properties": { "action": { "type": "string", "enum": [ "create" ] }, "spec": { "$ref": "#/components/schemas/HeartbeatSpec" } } }, { "type": "object", "required": [ "schedule_id", "expected_version", "spec", "action" ], "properties": { "action": { "type": "string", "enum": [ "edit" ] }, "expected_version": { "type": "integer", "format": "int64" }, "schedule_id": { "type": "string" }, "spec": { "$ref": "#/components/schemas/HeartbeatSpec" } } }, { "type": "object", "required": [ "schedule_id", "expected_version", "action" ], "properties": { "action": { "type": "string", "enum": [ "pause" ] }, "expected_version": { "type": "integer", "format": "int64" }, "schedule_id": { "type": "string" } } }, { "type": "object", "required": [ "schedule_id", "expected_version", "action" ], "properties": { "action": { "type": "string", "enum": [ "resume" ] }, "expected_version": { "type": "integer", "format": "int64" }, "schedule_id": { "type": "string" } } }, { "type": "object", "required": [ "schedule_id", "expected_version", "action" ], "properties": { "action": { "type": "string", "enum": [ "stop" ] }, "expected_version": { "type": "integer", "format": "int64" }, "schedule_id": { "type": "string" } } }, { "type": "object", "required": [ "schedule_id", "expected_version", "action" ], "properties": { "action": { "type": "string", "enum": [ "delete" ] }, "expected_version": { "type": "integer", "format": "int64" }, "schedule_id": { "type": "string" } } }, { "type": "object", "required": [ "schedule_id", "expected_version", "action" ], "properties": { "action": { "type": "string", "enum": [ "run_now" ] }, "expected_version": { "type": "integer", "format": "int64" }, "schedule_id": { "type": "string" } } } ] }, "HeartbeatAttentionAcknowledgement": { "type": "object", "required": [ "through_sequence" ], "properties": { "through_sequence": { "type": "integer", "format": "int64" } }, "additionalProperties": false }, "HeartbeatAttentionResult": { "type": "object", "required": [ "occurrence_id", "schedule_id", "outcome", "sequence", "seen" ], "properties": { "occurrence_id": { "type": "string" }, "outcome": { "$ref": "#/components/schemas/HeartbeatOutcome" }, "run_id": { "type": [ "string", "null" ] }, "schedule_id": { "type": "string" }, "seen": { "type": "boolean" }, "sequence": { "type": "integer", "format": "int64" } } }, "HeartbeatBinding": { "type": "object", "description": "An authenticated Local store is one owning user's host boundary. The exact\npersisted session/configuration is pinned; a later change requires review.", "required": [ "config_version", "cwd", "backend" ], "properties": { "backend": { "type": "string" }, "config_version": { "type": "integer", "format": "int64" }, "creator_session_id": { "type": [ "string", "null" ] }, "cwd": { "type": "string" }, "execution_cwd": { "type": [ "string", "null" ], "description": "Construction-time canonical Local workspace, checked again after\nrestore. Persisted display/relative paths alone are not an identity." }, "fresh_task": { "oneOf": [ { "$ref": "#/components/schemas/FreshTaskDestination" }, { "type": "null" } ] }, "model_configuration_id": { "type": [ "string", "null" ] }, "project_id": { "type": [ "string", "null" ] }, "scheduling_request": { "type": [ "string", "null" ], "description": "Actual person input or service-issued human configuration intent. It\ngrants only this saved scheduling purpose, never human tool authority." }, "seen_through_sequence": { "type": "integer", "format": "int64", "description": "Human attention metadata only; excluded from canonical target binding." } } }, "HeartbeatCalendarDays": { "oneOf": [ { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "daily" ] } } }, { "type": "object", "required": [ "days", "kind" ], "properties": { "days": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } }, "kind": { "type": "string", "enum": [ "weekdays" ] } } }, { "type": "object", "required": [ "day", "kind" ], "properties": { "day": { "type": "integer", "format": "int32", "minimum": 0 }, "kind": { "type": "string", "enum": [ "weekly" ] } } } ], "description": "Selected weekdays use Monday=1 through Sunday=7. Encoding order is canonical\n(ascending); duplicate and unsupported days are rejected rather than lost." }, "HeartbeatCalendarDraft": { "type": "object", "description": "Only an unsaved preview may select the currently supported data version.\nCreation saves its resolved rule; durable rules never default the version.", "required": [ "zone", "hour", "minute", "days" ], "properties": { "data_version": { "type": [ "string", "null" ] }, "days": { "$ref": "#/components/schemas/HeartbeatCalendarDays" }, "hour": { "type": "integer", "format": "int32", "minimum": 0 }, "minute": { "type": "integer", "format": "int32", "minimum": 0 }, "zone": { "type": "string" } }, "additionalProperties": false }, "HeartbeatCalendarPreview": { "type": "object", "description": "A passive projection from the pinned data, separate from retained control\nresponses. The owning rule always travels with its UTC/local instants.", "required": [ "calendar", "occurrences" ], "properties": { "calendar": { "$ref": "#/components/schemas/HeartbeatCalendarRule" }, "next_due": { "oneOf": [ { "$ref": "#/components/schemas/HeartbeatCalendarPreviewPoint" }, { "type": "null" } ] }, "occurrences": { "type": "array", "items": { "$ref": "#/components/schemas/HeartbeatCalendarPreviewPoint" } } } }, "HeartbeatCalendarPreviewPoint": { "type": "object", "required": [ "due_ms", "utc", "local" ], "properties": { "due_ms": { "type": "integer", "format": "int64" }, "local": { "type": "string" }, "utc": { "type": "string" } } }, "HeartbeatCalendarRule": { "type": "object", "required": [ "zone", "data_version", "hour", "minute", "days" ], "properties": { "data_version": { "type": "string" }, "days": { "$ref": "#/components/schemas/HeartbeatCalendarDays" }, "hour": { "type": "integer", "format": "int32", "minimum": 0 }, "minute": { "type": "integer", "format": "int32", "minimum": 0 }, "zone": { "type": "string" } }, "additionalProperties": false }, "HeartbeatControlRequest": { "type": "object", "required": [ "request_id", "operation" ], "properties": { "operation": { "$ref": "#/components/schemas/HeartbeatAction" }, "request_id": { "type": "string" } }, "additionalProperties": false }, "HeartbeatInspection": { "type": "object", "required": [ "schedule", "history" ], "properties": { "calendar_preview": { "oneOf": [ { "$ref": "#/components/schemas/HeartbeatCalendarPreview" }, { "type": "null" } ] }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/HeartbeatOccurrence" } }, "schedule": { "$ref": "#/components/schemas/HeartbeatSchedule" } } }, "HeartbeatOccurrence": { "type": "object", "required": [ "occurrence_id", "schedule_id", "schedule_version", "due_first_ms", "due_last_ms", "coalesced_count", "run_now", "state", "spec", "receipt_id", "revision", "attempt_count" ], "properties": { "attempt_count": { "type": "integer", "format": "int64" }, "coalesced_count": { "type": "integer", "format": "int64" }, "due_first_ms": { "type": "integer", "format": "int64" }, "due_last_ms": { "type": "integer", "format": "int64" }, "evidence": { "type": [ "string", "null" ] }, "generation": { "type": [ "string", "null" ] }, "inbox_item_id": { "type": [ "integer", "null" ], "format": "int64" }, "occurrence_id": { "type": "string" }, "outcome": { "oneOf": [ { "$ref": "#/components/schemas/HeartbeatOutcome" }, { "type": "null" } ] }, "provisional_outcome": { "oneOf": [ { "$ref": "#/components/schemas/HeartbeatOutcome" }, { "type": "null" } ] }, "receipt_id": { "type": "string" }, "revision": { "type": "integer", "format": "int64" }, "run_id": { "type": [ "string", "null" ] }, "run_now": { "type": "boolean" }, "schedule_id": { "type": "string" }, "schedule_version": { "type": "integer", "format": "int64" }, "session_id": { "type": [ "string", "null" ], "description": "A fresh occurrence acquires its exact execution session at publication." }, "settled_at_ms": { "type": [ "integer", "null" ], "format": "int64" }, "settlement_sequence": { "type": [ "integer", "null" ], "format": "int64" }, "spec": { "$ref": "#/components/schemas/HeartbeatSpec" }, "started_at_ms": { "type": [ "integer", "null" ], "format": "int64" }, "state": { "$ref": "#/components/schemas/HeartbeatOccurrenceState" }, "tokens_used": { "type": [ "integer", "null" ], "format": "int64" } } }, "HeartbeatOccurrenceState": { "type": "string", "enum": [ "pending", "admitted", "settled", "withdrawn" ] }, "HeartbeatOutcome": { "type": "string", "enum": [ "unchanged", "meaningful", "finished", "needs_human_action", "failed", "interrupted", "unknown" ] }, "HeartbeatPreviewRequest": { "type": "object", "required": [ "calendar" ], "properties": { "calendar": { "$ref": "#/components/schemas/HeartbeatCalendarDraft" }, "count": { "type": [ "integer", "null" ], "maximum": 16, "minimum": 1 } }, "additionalProperties": false }, "HeartbeatReceipt": { "type": "object", "required": [ "request_id", "schedule" ], "properties": { "active_occurrence": { "oneOf": [ { "$ref": "#/components/schemas/HeartbeatOccurrence", "description": "Exact already-admitted work. Delete alone never claims cancellation." }, { "type": "null" } ] }, "occurrence": { "oneOf": [ { "$ref": "#/components/schemas/HeartbeatOccurrence" }, { "type": "null" } ] }, "request_id": { "type": "string" }, "schedule": { "$ref": "#/components/schemas/HeartbeatSchedule" } } }, "HeartbeatSchedule": { "type": "object", "required": [ "schedule_id", "version", "state", "binding", "spec", "anchor_ms", "next_due_ms", "starts", "tokens_used", "time_used_ms", "usage_unknown", "created_at_ms", "updated_at_ms" ], "properties": { "anchor_ms": { "type": "integer", "format": "int64" }, "binding": { "$ref": "#/components/schemas/HeartbeatBinding" }, "created_at_ms": { "type": "integer", "format": "int64" }, "next_due_ms": { "type": "integer", "format": "int64" }, "reason": { "type": [ "string", "null" ] }, "schedule_id": { "type": "string" }, "session_id": { "type": [ "string", "null" ], "description": "Existing-chat schedules bind a session. Standalone project schedules\nhave no owning execution session; the creator is separate provenance." }, "spec": { "$ref": "#/components/schemas/HeartbeatSpec" }, "starts": { "type": "integer", "format": "int64" }, "state": { "$ref": "#/components/schemas/HeartbeatState" }, "time_used_ms": { "type": "integer", "format": "int64" }, "tokens_used": { "type": "integer", "format": "int64" }, "updated_at_ms": { "type": "integer", "format": "int64" }, "usage_unknown": { "type": "boolean" }, "version": { "type": "integer", "format": "int64" } } }, "HeartbeatSpec": { "allOf": [ { "type": "object", "required": [ "name", "instructions", "end_condition" ], "properties": { "calendar": { "oneOf": [ { "$ref": "#/components/schemas/HeartbeatCalendarRule" }, { "type": "null" } ] }, "end_condition": { "type": "string" }, "execution_timeout_ms": { "type": "integer", "format": "int64" }, "goal_id": { "type": [ "string", "null" ] }, "instructions": { "type": "string" }, "interval_ms": { "type": [ "integer", "null" ], "format": "int64" }, "max_occurrences": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "skills": { "type": "array", "items": { "type": "string" } }, "token_allowance": { "type": [ "integer", "null" ], "format": "int64" } }, "additionalProperties": false }, { "oneOf": [ { "type": "object", "required": [ "interval_ms" ], "properties": { "calendar": { "type": "null" }, "interval_ms": { "type": "integer" } } }, { "type": "object", "required": [ "calendar" ], "properties": { "calendar": { "$ref": "#/components/schemas/HeartbeatCalendarRule" }, "interval_ms": { "type": "null" } } } ] } ] }, "HeartbeatState": { "type": "string", "enum": [ "active", "paused", "suspended", "stopped", "finished", "deleted" ] }, "InboxDelivery": { "type": "string", "enum": [ "steer", "queue" ] }, "InboxItemResponse": { "type": "object", "required": [ "id", "session_id", "delivery", "status", "prompt", "created_at", "updated_at", "version" ], "properties": { "cancelled_at": { "type": [ "string", "null" ] }, "client_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "delivered_at": { "type": [ "string", "null" ] }, "delivered_run_id": { "type": [ "string", "null" ] }, "delivery": { "$ref": "#/components/schemas/InboxDelivery" }, "id": { "type": "integer", "format": "int64" }, "prompt": { "type": "string" }, "session_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/InboxStatus" }, "target_run_id": { "type": [ "string", "null" ] }, "terminal_selection": { "oneOf": [ { "$ref": "#/components/schemas/TerminalSelectionEvidence" }, { "type": "null" } ] }, "updated_at": { "type": "string" }, "version": { "type": "integer", "format": "int64" } } }, "InboxStatus": { "type": "string", "enum": [ "pending", "delivered", "cancelled" ] }, "InputControlStatus": { "type": "object", "required": [ "controller", "revision", "in_flight", "frozen" ], "properties": { "controller": { "$ref": "#/components/schemas/InputController" }, "frozen": { "type": "boolean" }, "in_flight": { "type": "boolean" }, "revision": { "type": "string", "description": "Decimal on the wire, without JavaScript integer rounding." } } }, "InputController": { "type": "string", "enum": [ "human", "agent" ] }, "InputDeliveryOutcome": { "type": "string", "enum": [ "written", "rejected", "unconfirmed" ] }, "InputDeliveryReceipt": { "type": "object", "required": [ "outcome" ], "properties": { "error": { "type": [ "string", "null" ] }, "outcome": { "$ref": "#/components/schemas/InputDeliveryOutcome" } } }, "LaggedEvent": { "type": "object", "required": [ "missed" ], "properties": { "missed": { "type": "integer", "format": "int64", "minimum": 0 } } }, "LaunchModelDefaults": { "type": "object", "properties": { "configured_model": { "type": [ "string", "null" ], "description": "Configured model id; lets the launch dialog render the inherited\n\"from config\" selection resolved against the model catalog (the\nfrontend resolves the provider from the model id, exactly like\nsession creation does)." }, "configured_reasoning_effort": { "oneOf": [ { "$ref": "#/components/schemas/ReasoningEffort", "description": "Configured reasoning effort, if any." }, { "type": "null" } ] } } }, "LaunchModelDefaultsRequest": { "type": "object", "properties": { "cwd": { "type": [ "string", "null" ] }, "ssh_host": { "type": [ "string", "null" ], "description": "OpenSSH target for remote sessions; remote paths never select local config." }, "ssh_identity_file": { "type": [ "string", "null" ] }, "ssh_port": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } }, "LightModelSettings": { "type": "object", "description": "The optional light model selection stored with a session. Orchestrator\nruntimes use it for weight-classified dispatch, and direct-with-orchestrator\nsessions pass it to the orchestrators they launch. Plain direct sessions\nretain it without a runtime consumer pending ALL-36. The model remains a\ncatalog id; backend and reasoning effort are typed before entering the\ndomain model, and the credential is always a selector name, never a key\nvalue.", "required": [ "model" ], "properties": { "api_key_env": { "type": [ "string", "null" ] }, "backend": { "oneOf": [ { "$ref": "#/components/schemas/BackendKind" }, { "type": "null" } ] }, "base_url": { "type": [ "string", "null" ] }, "model": { "type": "string" }, "reasoning_effort": { "oneOf": [ { "$ref": "#/components/schemas/ReasoningEffort" }, { "type": "null" } ] } } }, "ManagedAcceptedIdentity": { "type": "object", "required": [ "managed_host_id", "host_incarnation_id", "operation_id", "target" ], "properties": { "host_incarnation_id": { "type": "string" }, "managed_host_id": { "type": "string" }, "operation_id": { "type": "string" }, "target": { "$ref": "#/components/schemas/ManagedUpgradeTarget" } } }, "ManagedAuthListResponse": { "type": "object", "required": [ "providers" ], "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedAuthStatusResponse" } } } }, "ManagedAuthProvider": { "type": "string", "description": "A provider that authenticates from a browser login rather than an API key.", "enum": [ "arcee", "codex" ] }, "ManagedAuthStatusResponse": { "type": "object", "required": [ "provider", "backend", "signed_in", "account", "organization", "base_url", "expires_at_ms", "path" ], "properties": { "account": { "type": [ "string", "null" ] }, "backend": { "$ref": "#/components/schemas/BackendKind", "description": "The backend a session selects to use this login." }, "base_url": { "type": [ "string", "null" ] }, "expires_at_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "organization": { "type": [ "string", "null" ] }, "path": { "type": "string" }, "provider": { "$ref": "#/components/schemas/ManagedAuthProvider" }, "signed_in": { "type": "boolean" } } }, "ManagedBlockerKind": { "type": "string", "enum": [ "active_run", "compaction", "traditional_child", "managed_orchestrator", "terminal_process", "clone_operation", "workspace_mutation", "operation_lease", "resource_lease", "maintenance_operation" ] }, "ManagedCloneOperation": { "type": "object", "required": [ "version", "operation_id", "status", "repository_id", "repository", "source_identity", "branch", "destination", "project_id", "project_name", "progress", "reused_existing_checkout", "created_at_unix_ms", "updated_at_unix_ms" ], "properties": { "branch": { "type": "string" }, "created_at_unix_ms": { "type": "integer", "format": "int64", "minimum": 0 }, "destination": { "type": "string" }, "error": { "type": [ "string", "null" ] }, "operation_id": { "type": "string" }, "progress": { "type": "string" }, "project": { "oneOf": [ { "$ref": "#/components/schemas/ProjectRecord" }, { "type": "null" } ] }, "project_id": { "type": "string" }, "project_name": { "type": "string" }, "repository": { "type": "string" }, "repository_id": { "type": "integer", "format": "int64", "minimum": 0 }, "reused_existing_checkout": { "type": "boolean" }, "source_identity": { "type": "string" }, "status": { "$ref": "#/components/schemas/ManagedCloneStatus" }, "updated_at_unix_ms": { "type": "integer", "format": "int64", "minimum": 0 }, "version": { "type": "integer", "format": "int32", "minimum": 0 } } }, "ManagedCloneStatus": { "type": "string", "enum": [ "running", "completed", "failed", "cancelled", "interrupted" ] }, "ManagedHostStatusResponse": { "type": "object", "required": [ "managed", "ready", "version", "schema_version", "product_version", "build_id", "build_track", "source_revision", "supported_schema_version", "minimum_migratable_schema_version", "migration_state", "maintenance_state", "logical_host_id", "public_hostname", "repository_root", "model_ready", "model", "github_status", "secret_count", "project_count", "session_count", "checks" ], "properties": { "build_id": { "type": "string" }, "build_track": { "type": "string" }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/ReadinessCheck" } }, "github_status": { "type": "string" }, "logical_host_id": { "type": "string" }, "maintenance": { "oneOf": [ { "$ref": "#/components/schemas/ManagedMaintenanceSnapshot" }, { "type": "null" } ] }, "maintenance_state": { "type": "string" }, "managed": { "type": "boolean" }, "migration_failure": { "type": [ "string", "null" ] }, "migration_state": { "type": "string" }, "minimum_migratable_schema_version": { "type": "integer", "format": "int64" }, "model": { "$ref": "#/components/schemas/ManagedModelStatus" }, "model_ready": { "type": "boolean" }, "opened_schema_version": { "type": [ "integer", "null" ], "format": "int64" }, "owner": { "type": [ "string", "null" ] }, "product_version": { "type": "string" }, "project_count": { "type": "integer", "minimum": 0 }, "public_hostname": { "type": "string" }, "ready": { "type": "boolean" }, "repository_root": { "type": "string" }, "schema_version": { "type": "integer", "format": "int64" }, "secret_count": { "type": "integer", "minimum": 0 }, "session_count": { "type": "integer", "minimum": 0 }, "source_revision": { "type": "string" }, "supported_schema_version": { "type": "integer", "format": "int64" }, "version": { "type": "string" } } }, "ManagedMaintenanceSnapshot": { "type": "object", "required": [ "state", "version", "blockers" ], "properties": { "accepted_identity": { "oneOf": [ { "$ref": "#/components/schemas/ManagedAcceptedIdentity" }, { "type": "null" } ] }, "blockers": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedUpgradeBlocker" } }, "operation_id": { "type": [ "string", "null" ] }, "prepared_at": { "type": [ "string", "null" ] }, "state": { "$ref": "#/components/schemas/ManagedMaintenanceState" }, "target": { "oneOf": [ { "$ref": "#/components/schemas/ManagedUpgradeTarget" }, { "type": "null" } ] }, "version": { "type": "integer", "format": "int64", "minimum": 0 } } }, "ManagedMaintenanceState": { "type": "string", "enum": [ "serving", "maintenance" ] }, "ManagedModelStatus": { "type": "object", "required": [ "backend", "id", "endpoint", "display_name" ], "properties": { "backend": { "$ref": "#/components/schemas/BackendKind" }, "display_name": { "type": "string" }, "endpoint": { "type": "string" }, "id": { "type": "string" } } }, "ManagedOrchestratorRecord": { "type": "object", "required": [ "orchestrator_session_id", "parent_session_id", "root_session_id", "description", "status", "generation", "created_at", "updated_at", "version" ], "properties": { "completion_inbox_id": { "type": [ "integer", "null" ], "format": "int64" }, "created_at": { "type": "string" }, "description": { "type": "string" }, "execution_mode": { "oneOf": [ { "$ref": "#/components/schemas/TraditionalChildExecutionMode" }, { "type": "null" } ] }, "failure": { "type": [ "string", "null" ] }, "generation": { "type": "integer", "format": "int64", "minimum": 0 }, "orchestrator_session_id": { "type": "string" }, "parent_session_id": { "type": "string" }, "report": { "type": [ "string", "null" ] }, "root_session_id": { "type": "string" }, "run_id": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/TraditionalChildStatus" }, "updated_at": { "type": "string" }, "version": { "type": "integer", "format": "int64" } } }, "ManagedSecretList": { "type": "object", "required": [ "secrets", "healthy" ], "properties": { "healthy": { "type": "boolean" }, "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/ManagedSecretSummary" } } } }, "ManagedSecretSummary": { "type": "object", "required": [ "name", "updated_at_unix_ms" ], "properties": { "name": { "type": "string" }, "updated_at_unix_ms": { "type": "integer", "format": "int64", "minimum": 0 } } }, "ManagedSessionSummary": { "type": "object", "required": [ "summary", "active" ], "properties": { "active": { "type": "boolean" }, "active_run": { "oneOf": [ { "$ref": "#/components/schemas/ActiveRunSnapshot" }, { "type": "null" } ] }, "attention_revision": { "type": "integer", "format": "int64" }, "attention_updated_at": { "type": [ "string", "null" ] }, "heartbeat_results": { "type": "array", "items": { "$ref": "#/components/schemas/HeartbeatAttentionResult" } }, "lineage": { "oneOf": [ { "$ref": "#/components/schemas/SessionLineageSnapshot", "description": "Delegated sessions remain addressable by id, but clients use lineage\nto keep them out of primary chat navigation and enforce ownership UI." }, { "type": "null" } ] }, "summary": { "$ref": "#/components/schemas/SessionSummarySnapshot" }, "workspace_diff": { "oneOf": [ { "$ref": "#/components/schemas/WorkspaceDiffTotals" }, { "type": "null" } ] } } }, "ManagedUpgradeBlocker": { "type": "object", "required": [ "kind", "id", "detail" ], "properties": { "detail": { "type": "string" }, "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/ManagedBlockerKind" }, "session_id": { "type": [ "string", "null" ] } } }, "ManagedUpgradeTarget": { "type": "object", "required": [ "release_id", "source_sha", "product_version", "schema_version", "minimum_schema_version" ], "properties": { "minimum_schema_version": { "type": "integer", "format": "int64" }, "product_version": { "type": "string" }, "release_id": { "type": "string" }, "schema_version": { "type": "integer", "format": "int64" }, "source_sha": { "type": "string" } } }, "McpHeaderHelperConfig": { "type": "object", "required": [ "command" ], "properties": { "args": { "type": "array", "items": { "type": "string" } }, "command": { "type": "string" }, "cwd": { "type": [ "string", "null" ] }, "env": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "env_vars": { "type": "array", "items": { "type": "string" } }, "timeout_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } }, "McpLibraryAuth": { "type": "string", "description": "What a library server needs before it can connect.", "enum": [ "none", "optional_header", "required_header" ] }, "McpLibraryEntry": { "type": "object", "description": "One catalog entry. Every field feeds the add-server form: the entry is a\npre-fill, never a hidden configuration — what is saved is exactly what the\nform shows.", "required": [ "id", "name", "description", "transport", "url", "auth", "docs_url", "category", "tags" ], "properties": { "auth": { "$ref": "#/components/schemas/McpLibraryAuth" }, "auth_header": { "type": [ "string", "null" ], "description": "Header the form should prompt for, when auth wants one." }, "auth_hint": { "type": [ "string", "null" ], "description": "Hint shown next to the header input, e.g. the expected value shape." }, "category": { "type": "string", "description": "Section the picker groups the entry under before a search." }, "description": { "type": "string" }, "docs_url": { "type": "string" }, "icon_url": { "type": [ "string", "null" ], "description": "Thumbnail shown next to the entry in the picker." }, "id": { "type": "string", "description": "Stable identifier, recorded on servers created from the entry." }, "name": { "type": "string", "description": "Display name; also the default server name." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Search fallback terms: consulted when a query matches neither name\nnor description." }, "transport": { "type": "string", "description": "All current entries are `streamable_http`; stdio ones may appear\nlater." }, "url": { "type": "string" } } }, "McpLibraryResponse": { "type": "object", "required": [ "entries" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/McpLibraryEntry" } } } }, "McpNotificationKind": { "type": "string", "enum": [ "catalog_refreshed", "catalog_refresh_failed", "resource_updated", "log", "progress", "subscription_ended" ] }, "McpOAuthAuthorizationMetadataRequest": { "type": "object", "required": [ "authorization_endpoint", "token_endpoint" ], "properties": { "authorization_endpoint": { "type": "string" }, "code_challenge_methods_supported": { "type": [ "array", "null" ], "items": { "type": "string" } }, "issuer": { "type": [ "string", "null" ] }, "jwks_uri": { "type": [ "string", "null" ] }, "registration_endpoint": { "type": [ "string", "null" ] }, "response_types_supported": { "type": [ "array", "null" ], "items": { "type": "string" } }, "scopes_supported": { "type": [ "array", "null" ], "items": { "type": "string" } }, "token_endpoint": { "type": "string" } }, "additionalProperties": {} }, "McpOAuthPublicStatus": { "type": "string", "enum": [ "needs_configuration", "needs_authorization", "connecting", "connected", "failed" ] }, "McpOAuthRegistrationRequest": { "oneOf": [ { "type": "object", "required": [ "client_id_credential", "type" ], "properties": { "client_id_credential": { "type": "string", "writeOnly": true }, "client_secret_credential": { "type": [ "string", "null" ], "writeOnly": true }, "type": { "type": "string", "enum": [ "pre_registered" ] } } }, { "type": "object", "required": [ "url", "type" ], "properties": { "type": { "type": "string", "enum": [ "client_metadata" ] }, "url": { "type": "string" } } }, { "type": "object", "required": [ "type" ], "properties": { "client_name": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "dynamic" ] } } } ] }, "McpOAuthStatusResponse": { "type": "object", "required": [ "status" ], "properties": { "authorization_url": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/McpOAuthPublicStatus" } } }, "McpProbeResult": { "type": "object", "required": [ "protocol_version", "capabilities", "tools", "prompt_count", "resource_count", "resource_template_count", "catalog_warnings" ], "properties": { "capabilities": { "type": "array", "items": { "type": "string" } }, "catalog_warnings": { "type": "array", "items": { "type": "string" }, "description": "Best-effort catalog sections that could not be listed after the\nrequired tool catalog had already succeeded." }, "instructions": { "type": [ "string", "null" ] }, "prompt_count": { "type": "integer", "minimum": 0 }, "protocol_version": { "type": "string" }, "resource_count": { "type": "integer", "minimum": 0 }, "resource_template_count": { "type": "integer", "minimum": 0 }, "server_name": { "type": [ "string", "null" ] }, "server_version": { "type": [ "string", "null" ] }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/McpProbedTool" } } } }, "McpProbedTool": { "type": "object", "description": "A tool a probe discovered on a server, before anything is saved.", "required": [ "name" ], "properties": { "_meta": {}, "annotations": {}, "description": { "type": [ "string", "null" ] }, "icons": {}, "name": { "type": "string" }, "output_schema": {}, "title": { "type": [ "string", "null" ] } } }, "McpPromptArgument": { "type": "object", "required": [ "name", "required" ], "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "required": { "type": "boolean" } } }, "McpProtocolSelection": { "type": "string", "description": "Selects the MCP lifecycle independently for each configured server.", "enum": [ "legacy", "auto", "current" ] }, "McpRuntimeState": { "type": "string", "enum": [ "disabled", "disconnected", "connecting", "connected", "failed" ] }, "McpRuntimeStatus": { "type": "object", "required": [ "name", "state", "required", "auth_required", "tool_count", "sessions_blocked" ], "properties": { "auth_required": { "type": "boolean" }, "error": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "protocol_version": { "type": [ "string", "null" ] }, "required": { "type": "boolean" }, "server_name": { "type": [ "string", "null" ] }, "server_version": { "type": [ "string", "null" ] }, "sessions_blocked": { "type": "boolean", "description": "The user disconnected this server; sessions refuse to use it until it is connected." }, "state": { "$ref": "#/components/schemas/McpRuntimeState" }, "tool_count": { "type": "integer", "minimum": 0 } } }, "McpRuntimeStatusList": { "type": "object", "required": [ "servers" ], "properties": { "servers": { "type": "array", "items": { "$ref": "#/components/schemas/McpRuntimeStatus" } } } }, "McpServerList": { "type": "object", "required": [ "servers" ], "properties": { "servers": { "type": "array", "items": { "$ref": "#/components/schemas/McpServerView" } } } }, "McpServerView": { "type": "object", "description": "A saved server as the dashboard sees it: env and header values are\nredacted, everything else round-trips.", "required": [ "name", "enabled", "required", "protocol", "transport", "args", "env", "env_vars", "headers", "env_headers", "denied_tools", "approval", "tool_approvals" ], "properties": { "allowed_tools": { "type": [ "array", "null" ], "items": { "type": "string" } }, "approval": { "$ref": "#/components/schemas/McpToolApproval" }, "args": { "type": "array", "items": { "type": "string" } }, "bearer_token_env_var": { "type": [ "string", "null" ] }, "catalog_timeout_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "command": { "type": [ "string", "null" ] }, "cwd": { "type": [ "string", "null" ] }, "denied_tools": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "env": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "env_headers": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "env_vars": { "type": "array", "items": { "type": "string" } }, "execution_timeout_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "header_helper": { "oneOf": [ { "$ref": "#/components/schemas/McpHeaderHelperConfig" }, { "type": "null" } ] }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "library_id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "protocol": { "$ref": "#/components/schemas/McpProtocolSelection" }, "required": { "type": "boolean" }, "startup_timeout_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "tool_approvals": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/McpToolApproval" }, "propertyNames": { "type": "string" } }, "transport": { "$ref": "#/components/schemas/McpTransportSchema" }, "url": { "type": [ "string", "null" ] } } }, "McpToolApproval": { "type": "string", "enum": [ "allow", "ask" ] }, "McpTransportSchema": { "type": "string", "enum": [ "stdio", "streamable_http" ] }, "Message": { "oneOf": [ { "type": "object", "required": [ "content", "role" ], "properties": { "content": { "type": "string" }, "role": { "type": "string", "enum": [ "system" ] } } }, { "type": "object", "required": [ "content", "role" ], "properties": { "content": { "type": "string" }, "role": { "type": "string", "enum": [ "user" ] } } }, { "type": "object", "required": [ "content", "role" ], "properties": { "content": { "type": [ "string", "null" ] }, "duration_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "Wall-clock time the model call behind this message took. Only ever\nread by the UI: every provider mapper drops it, so it never travels\nback out on the wire.", "minimum": 0 }, "model_origin": { "oneOf": [ { "$ref": "#/components/schemas/ModelOrigin", "description": "The model that produced this message (S5). Stamped at the\ntranscript push site; `None` on pre-S5 (legacy) messages, which\nthe wire normalization treats as same-model. Drives the\nsame-model reasoning-replay gate in `model::normalize_history`." }, { "type": "null" } ] }, "reasoning_details": {}, "reasoning_field": { "type": [ "string", "null" ], "description": "The wire field that carried `reasoning_text` on completions\nendpoints (\"reasoning_content\" vs \"reasoning\"); replayed under\nthe same name. `None` for details-based reasoning (Anthropic,\nOpenAI Responses) and legacy messages." }, "reasoning_text": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "assistant" ] }, "tool_calls": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ToolCall" } } } }, { "type": "object", "required": [ "tool_call_id", "content", "role" ], "properties": { "content": { "$ref": "#/components/schemas/ToolContentSchema" }, "role": { "type": "string", "enum": [ "tool" ] }, "tool_call_id": { "type": "string" } } } ] }, "MessageCycleMetadata": { "type": "object", "required": [ "marker", "thread_names" ], "properties": { "marker": { "type": "string" }, "thread_names": { "type": "array", "items": { "type": "string" } } } }, "MessagePageMetadata": { "type": "object", "required": [ "start", "end", "total", "has_older" ], "properties": { "end": { "type": "integer", "minimum": 0 }, "has_older": { "type": "boolean" }, "start": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } } }, "MessagesPageResponse": { "type": "object", "required": [ "messages", "created_at", "page" ], "properties": { "created_at": { "type": "array", "items": { "type": [ "string", "null" ] } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "page": { "$ref": "#/components/schemas/MessagePageMetadata" }, "terminal_selection_attributions": { "type": "array", "items": { "$ref": "#/components/schemas/TerminalSelectionMessageReference" } } } }, "ModelConfigFromFileRequest": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" } } }, "ModelConfigurationList": { "type": "object", "required": [ "configurations" ], "properties": { "configurations": { "type": "array", "items": { "$ref": "#/components/schemas/ModelConfigurationRecord" } } } }, "ModelConfigurationRecord": { "type": "object", "description": "A named, reusable model setup offered by the launch modal.\n\n`api_key_env` names the credential rather than holding it: the value lives\nin the credential store (or the environment), exactly as it does for a\nconfiguration written by hand in `config.toml`.", "required": [ "config_id", "name", "backend", "model", "base_url", "allow_insecure_http", "extra_headers", "created_at", "updated_at" ], "properties": { "allow_insecure_http": { "type": "boolean" }, "api_key_env": { "type": [ "string", "null" ] }, "backend": { "type": "string" }, "base_url": { "type": "string" }, "config_id": { "type": "string" }, "created_at": { "type": "string" }, "extra_headers": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "initial_prompt": { "type": [ "string", "null" ], "description": "Message the launch modal pre-fills when this setup is chosen." }, "light_model": { "oneOf": [ { "$ref": "#/components/schemas/LightModelSettings", "description": "Light worker model; `None` keeps single-model behavior." }, { "type": "null" } ] }, "model": { "type": "string" }, "name": { "type": "string" }, "orchestrator_compaction_threshold": { "type": [ "integer", "null" ], "format": "int64", "description": "Compaction budget a session started from this setup inherits; `None`\nfalls back to `[compaction].threshold_tokens`.", "minimum": 0 }, "reasoning_effort": { "type": [ "string", "null" ] }, "updated_at": { "type": "string" } } }, "ModelCostRates": { "type": "object", "description": "Cost rates in USD per 1M tokens. All-zero = unknown (pi's zero-cost\nfallback); `calculate_cost` bills unknown pricing as zero. Missing fields\ndeserialize as zero so partial catalog records stay loadable.\n\n`tiers` carries context-dependent pricing (models.dev `cost.tiers`,\npi's `model.cost.tiers`): when a response's prompt size exceeds a tier's\n`input_tokens_above`, that tier's rates replace the base rates for the\nresponse. `None` and `Some([])` both mean flat pricing; the Option keeps\nuser overrides three-state (absent = keep existing tiers, `[]` = clear).", "required": [ "input", "output", "cache_read", "cache_write" ], "properties": { "cache_read": { "type": "number", "format": "double" }, "cache_write": { "type": "number", "format": "double" }, "input": { "type": "number", "format": "double" }, "output": { "type": "number", "format": "double" }, "tiers": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CostTier" } } } }, "ModelEntry": { "type": "object", "description": "One real catalog entry as served by `GET /models` (never a\nProviderDefault/Fallback synthesis product).", "required": [ "id", "display_name", "context_window", "max_tokens", "cost", "reasoning", "supported_efforts", "source" ], "properties": { "context_window": { "type": "integer", "format": "int64", "minimum": 0 }, "cost": { "$ref": "#/components/schemas/ModelCostRates" }, "display_name": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "max_tokens": { "type": "integer", "format": "int64", "minimum": 0 }, "reasoning": { "type": "boolean" }, "source": { "$ref": "#/components/schemas/ModelSource" }, "supported_efforts": { "type": "array", "items": { "$ref": "#/components/schemas/ReasoningEffort" } } } }, "ModelListing": { "type": "object", "description": "The full catalog listing served by `GET /models`.", "required": [ "catalog_version", "providers" ], "properties": { "catalog_version": { "type": "integer", "format": "int64", "description": "Monotonic version of the process-global catalog, bumped on every\nreload (the initial load is version 1). Debugging/future-staleness\nsurface only; v1 attaches no cache semantics.", "minimum": 0 }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderListing" } } } }, "ModelOrigin": { "type": "object", "description": "Identifies the model that produced an assistant message (S5 reasoning\ndiscipline). Reasoning signatures (Anthropic thinking blocks, OpenAI\nreasoning items, completions reasoning text) are only replayed to the\nsame origin; a different origin makes the wire normalization strip them.", "required": [ "backend", "model" ], "properties": { "backend": { "$ref": "#/components/schemas/BackendKind" }, "model": { "type": "string" } } }, "ModelSource": { "type": "string", "description": "Where the metadata for a resolved model came from. Served by the\n`/models` listing (snake_case wire names) — the frontend badges\nuser-overridden and unrecognized (provider-default) models from it.", "enum": [ "baseline", "overlay", "user_override", "provider_default", "fallback" ] }, "OpenLocalPathResult": { "type": "object", "required": [ "opened", "fell_back_to_parent" ], "properties": { "fell_back_to_parent": { "type": "boolean", "description": "True when the requested file was missing and its parent was opened." }, "opened": { "type": "string", "description": "Absolute path handed to the OS opener." } } }, "OpenUserTerminalRequest": { "type": "object", "required": [ "protocol_version", "launch_id", "cols", "rows" ], "properties": { "cols": { "type": "integer", "format": "int32", "maximum": 500, "minimum": 2 }, "launch_id": { "type": "string" }, "protocol_version": { "type": "integer", "format": "int32", "maximum": 1, "minimum": 1 }, "rows": { "type": "integer", "format": "int32", "maximum": 300, "minimum": 1 } }, "additionalProperties": false }, "OpenWorkspacePathRequest": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" } } }, "OrchestratorSteeringRequest": { "type": "object", "required": [ "instruction" ], "properties": { "instruction": { "type": "string" } } }, "OrchestratorSteeringResponse": { "type": "object", "required": [ "steering_id", "status", "instruction_preview" ], "properties": { "instruction_preview": { "type": "string" }, "status": { "type": "string" }, "steering_id": { "type": "integer", "format": "int64" } } }, "PartialModelOutput": { "type": "object", "properties": { "reasoning": { "type": "boolean" }, "text": { "type": "boolean" }, "tool_call": { "type": "boolean" } } }, "PermissionApprovalMode": { "type": "string", "description": "User-selected approval behavior for one durable direct ownership tree.\n\nThis is deliberately an answer policy at the broker boundary, not an\nexecution backend or a reusable resource grant.", "enum": [ "manual", "auto_approve", "review" ] }, "PermissionGrantRecord": { "type": "object", "required": [ "id", "session_id", "action", "resource", "backend", "session_config_version", "created_at" ], "properties": { "action": { "type": "string" }, "backend": { "type": "string" }, "created_at": { "type": "string" }, "id": { "type": "string" }, "resource": { "type": "string" }, "session_config_version": { "type": "integer", "format": "int64" }, "session_id": { "type": "string" } } }, "PermissionReply": { "type": "string", "enum": [ "once", "always", "reject" ] }, "PermissionRequest": { "type": "object", "required": [ "id", "session_id", "tool", "resources", "created_at_epoch_ms" ], "properties": { "call_id": { "type": [ "string", "null" ] }, "created_at_epoch_ms": { "type": "integer", "format": "int64", "minimum": 0 }, "id": { "type": "string" }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionRequestResource" } }, "session_id": { "type": "string" }, "tool": { "type": "string" } } }, "PermissionRequestResource": { "type": "object", "required": [ "action", "resource", "display" ], "properties": { "action": { "type": "string" }, "display": { "type": "string" }, "resource": { "type": "string" }, "save_resource": { "type": [ "string", "null" ] } } }, "PermissionReview": { "type": "object", "description": "Redacted record of one automatic review, emitted to clients. It carries\nno arguments beyond the redacted display already shown to the reviewer.", "required": [ "id", "session_id", "tool", "backend", "resources", "user_authorized_retry", "reviewer", "created_at_epoch_ms" ], "properties": { "backend": { "type": "string" }, "call_id": { "type": [ "string", "null" ] }, "category": { "oneOf": [ { "$ref": "#/components/schemas/ReviewCategory" }, { "type": "null" } ] }, "code": { "oneOf": [ { "$ref": "#/components/schemas/PermissionReviewCode" }, { "type": "null" } ] }, "created_at_epoch_ms": { "type": "integer", "format": "int64", "minimum": 0 }, "duration_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "failure_reason": { "oneOf": [ { "$ref": "#/components/schemas/PermissionReviewFailureReason", "description": "A fixed, safe explanation for an unavailable review. No provider text." }, { "type": "null" } ] }, "id": { "type": "string" }, "outcome": { "oneOf": [ { "$ref": "#/components/schemas/PermissionReviewOutcome" }, { "type": "null" } ] }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewResource" } }, "reviewer": { "type": "string" }, "session_id": { "type": "string" }, "tool": { "type": "string" }, "user_authorized_retry": { "type": "boolean" } } }, "PermissionReviewCode": { "type": "string", "description": "Stable machine-readable codes returned to the model with an unexecuted\noperation.", "enum": [ "review_rejected", "review_uncertain", "review_unavailable", "review_stopped" ] }, "PermissionReviewFailureReason": { "type": "string", "description": "Safe failure categories that clients can explain without provider details.", "enum": [ "authentication", "access_denied", "model_unavailable", "insufficient_credits", "rate_limited", "timeout", "invalid_response", "service_unavailable", "cancelled" ] }, "PermissionReviewOutcome": { "type": "string", "description": "The outcome reported to clients and recorded for audit.", "enum": [ "approved", "rejected", "uncertain", "unavailable" ] }, "PermissionStateResponse": { "type": "object", "required": [ "approval_mode", "requests", "grants" ], "properties": { "approval_mode": { "$ref": "#/components/schemas/PermissionApprovalMode", "description": "Effective for this session's durable traditional-child ownership tree.\n`manual` is the compatibility default." }, "authorizable_review_ids": { "type": "array", "items": { "type": "string" }, "description": "Blocked reviews the user may still authorize for one retry." }, "grants": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionGrantRecord" } }, "requests": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionRequest" } }, "reviews": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionReview" }, "description": "Recent automatic reviews in every state, newest first: in progress\n(no outcome), approved, blocked or unavailable. Empty outside Approve\nfor me." } } }, "ProductAvailability": { "type": "string", "enum": [ "available", "disabled", "unavailable", "unknown" ] }, "ProductBuild": { "type": "object", "required": [ "product_version", "build_id", "track", "source_revision" ], "properties": { "build_id": { "type": "string" }, "product_version": { "type": "string" }, "source_revision": { "type": "string" }, "track": { "type": "string" } } }, "ProductCapability": { "type": "object", "required": [ "availability", "count" ], "properties": { "availability": { "$ref": "#/components/schemas/ProductAvailability" }, "count": { "type": [ "integer", "null" ], "description": "A count is present only when observed in this bound runtime.", "minimum": 0 } } }, "ProductContext": { "type": "object", "required": [ "schema_version", "build", "source", "managed", "features", "session", "mcp", "destinations" ], "properties": { "build": { "$ref": "#/components/schemas/ProductBuild" }, "destinations": { "type": "array", "items": { "$ref": "#/components/schemas/ProductDestinationInfo" } }, "features": { "type": "array", "items": { "$ref": "#/components/schemas/ProductFeature" } }, "managed": { "type": "boolean" }, "mcp": { "$ref": "#/components/schemas/ProductCapability", "description": "Host dashboard readiness, not session tool authorization or connectivity." }, "schema_version": { "type": "integer", "format": "int32", "minimum": 0 }, "session": { "oneOf": [ { "$ref": "#/components/schemas/ProductSessionContext" }, { "type": "null" } ] }, "source": { "type": "string", "description": "Source identity for facts, distinct from a future Guide document reference." } } }, "ProductDestination": { "type": "string", "enum": [ "projects", "mcp-settings", "configurations", "model-authentication", "ssh-configurations", "session-subagents", "session-files", "session-terminal", "session-history" ] }, "ProductDestinationInfo": { "type": "object", "required": [ "destination", "label", "availability", "steps" ], "properties": { "availability": { "$ref": "#/components/schemas/ProductAvailability" }, "destination": { "$ref": "#/components/schemas/ProductDestination" }, "label": { "type": "string" }, "steps": { "type": "string" } } }, "ProductExecutionBackend": { "type": "string", "enum": [ "local", "ssh", "podman" ] }, "ProductFeature": { "type": "object", "required": [ "feature", "label", "availability" ], "properties": { "availability": { "$ref": "#/components/schemas/ProductAvailability" }, "feature": { "$ref": "#/components/schemas/ProductFeatureKind" }, "label": { "type": "string" } } }, "ProductFeatureKind": { "type": "string", "enum": [ "traditional_subagents", "managed_orchestrators", "managed_host", "product_navigation" ] }, "ProductNavigationRequest": { "type": "object", "required": [ "destination", "expected_build_id" ], "properties": { "destination": { "$ref": "#/components/schemas/ProductDestination" }, "expected_build_id": { "type": "string" }, "session_id": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "ProductNavigationResolution": { "type": "object", "required": [ "build", "session_id", "target", "opened" ], "properties": { "build": { "$ref": "#/components/schemas/ProductBuild" }, "opened": { "type": "boolean", "description": "Resolution never claims that a browser opened anything." }, "session_id": { "type": [ "string", "null" ] }, "target": { "$ref": "#/components/schemas/ProductDestinationInfo" } } }, "ProductSessionContext": { "type": "object", "required": [ "session_id", "behavior", "execution_backend", "skills", "tools" ], "properties": { "behavior": { "$ref": "#/components/schemas/SessionBehavior" }, "execution_backend": { "$ref": "#/components/schemas/ProductExecutionBackend", "description": "Construction-time execution backend, never the model provider." }, "session_id": { "type": "string" }, "skills": { "$ref": "#/components/schemas/ProductCapability" }, "tools": { "$ref": "#/components/schemas/ProductCapability" } } }, "ProjectList": { "type": "object", "required": [ "projects" ], "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectRecord" } } } }, "ProjectRecord": { "type": "object", "description": "Stable project projection shared by persistence, managed workflows, and\ndelivery without exposing a SQLite implementation.", "required": [ "project_id", "name", "cwd", "created_at", "updated_at", "pinned", "sort_order", "presentation_version" ], "properties": { "created_at": { "type": "string" }, "cwd": { "type": "string" }, "default_model_config_id": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "pinned": { "type": "boolean" }, "presentation_version": { "type": "integer", "format": "int64" }, "project_id": { "type": "string" }, "sort_order": { "type": "integer", "format": "int64" }, "ssh_host": { "type": [ "string", "null" ] }, "ssh_identity_file": { "type": [ "string", "null" ] }, "ssh_port": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "updated_at": { "type": "string" } } }, "ProviderAuth": { "type": "string", "description": "How a provider authenticates, as served by `GET /models`: auth\n*requirements* (drives picker field visibility and hints), not status.", "enum": [ "api_key_env", "managed_arcee", "codex_oauth" ] }, "ProviderConnection": { "type": "object", "description": "The server-owned account a unified picker can use for this provider.\n`api_key_env` is a selector only; the credential value never leaves the\nserver. Managed logins therefore carry no selector.", "required": [ "base_url", "api_key_env" ], "properties": { "api_key_env": { "type": [ "string", "null" ] }, "base_url": { "type": "string" } } }, "ProviderListing": { "type": "object", "description": "One provider group in the `GET /models` listing.", "required": [ "id", "auth", "auth_status", "auth_hint", "connection", "managed_base_url", "default_base_url", "default_limits", "models" ], "properties": { "auth": { "$ref": "#/components/schemas/ProviderAuth" }, "auth_hint": { "type": [ "string", "null" ], "description": "The conventional credential env var name (API-key providers) or the\nlogin command (managed providers) when `auth_status` is\n`no_credential`; `None` when ready or when no conventional name is\nknown." }, "auth_status": { "$ref": "#/components/schemas/AuthStatus", "description": "Computed per request from the process environment and the managed\ncredential files — never baked into the catalog." }, "connection": { "oneOf": [ { "$ref": "#/components/schemas/ProviderConnection", "description": "The currently selected server-owned account route, if usable. This is\nthe sole routing source for unified selectors; it contains no secret." }, { "type": "null" } ] }, "default_base_url": { "type": [ "string", "null" ], "description": "The provider's catalog endpoint default (models.dev `api` or the\ncurated SDK-default URL; hand-seeded for arcee-api); `None` for the\nmanaged providers. An absent request `base_url` materializes to it\nat settings resolution." }, "default_limits": { "$ref": "#/components/schemas/DefaultLimits" }, "id": { "$ref": "#/components/schemas/BackendKind" }, "managed_base_url": { "type": [ "string", "null" ] }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/ModelEntry" } } } }, "ProviderModel": { "type": "object", "required": [ "id", "display_name" ], "properties": { "display_name": { "type": [ "string", "null" ] }, "id": { "type": "string" } } }, "ProviderModelList": { "type": "object", "required": [ "base_url", "models" ], "properties": { "base_url": { "type": "string", "description": "The URL the models were actually read from, so the caller can persist\nthe same destination it validated against." }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderModel" } } } }, "ProviderModelsRequest": { "type": "object", "required": [ "backend" ], "properties": { "allow_insecure_http": { "type": "boolean", "description": "Explicitly permit public plaintext HTTP during provider discovery.", "default": false }, "api_key": { "type": [ "string", "null" ], "example": "fake-provider-key", "writeOnly": true }, "api_key_env": { "type": [ "string", "null" ], "description": "Names a key already held in the environment or in NAC home, for a caller\nthat has one on file and no copy of the secret to send." }, "backend": { "$ref": "#/components/schemas/BackendKind" }, "base_url": { "type": [ "string", "null" ], "description": "Overrides the provider's canonical URL, for a proxy or a custom gateway." } } }, "PullUserTerminalRequest": { "type": "object", "required": [ "protocol_version", "acknowledge_reset", "wait_ms" ], "properties": { "acknowledge_offset": { "type": [ "string", "null" ], "description": "Exact decimal byte cursor of the frame the renderer finished processing." }, "acknowledge_reset": { "type": "boolean", "description": "A replay gap must be acknowledged only after resetting the renderer." }, "protocol_version": { "type": "integer", "format": "int32", "minimum": 0 }, "wait_ms": { "type": "integer", "format": "int32", "maximum": 1000, "minimum": 0 } }, "additionalProperties": false }, "PutManagedSecretRequest": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string", "example": "fake-managed-secret-value", "writeOnly": true } } }, "QuestionAnswer": { "type": "object", "required": [ "request_id", "run_id", "generation", "expected_revision", "answer" ], "properties": { "answer": { "type": "string" }, "expected_revision": { "type": "integer", "format": "int64" }, "generation": { "type": "string" }, "request_id": { "type": "string" }, "run_id": { "type": "string" } }, "additionalProperties": false }, "QuestionAnswerReceipt": { "type": "object", "required": [ "session_id", "request_id", "run_id", "generation", "revision", "answer", "continuation_run_id", "inbox_item_id" ], "properties": { "answer": { "type": "string" }, "continuation_run_id": { "type": "string" }, "generation": { "type": "string" }, "inbox_item_id": { "type": "integer", "format": "int64" }, "request_id": { "type": "string" }, "revision": { "type": "integer", "format": "int64" }, "run_id": { "type": "string" }, "session_id": { "type": "string" } } }, "QuestionRecord": { "type": "object", "required": [ "request", "revision", "status", "goal_id", "answer", "continuation_state", "created_at" ], "properties": { "answer": { "oneOf": [ { "$ref": "#/components/schemas/QuestionAnswerReceipt" }, { "type": "null" } ] }, "continuation_state": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "goal_id": { "type": [ "string", "null" ] }, "request": { "$ref": "#/components/schemas/QuestionRequest" }, "revision": { "type": "integer", "format": "int64" }, "status": { "type": "string" } } }, "QuestionRequest": { "type": "object", "required": [ "session_id", "request_id", "run_id", "generation", "text", "choices", "responder_class" ], "properties": { "choices": { "type": "array", "items": { "type": "string" } }, "generation": { "type": "string" }, "request_id": { "type": "string" }, "responder_class": { "$ref": "#/components/schemas/QuestionResponder" }, "run_id": { "type": "string" }, "session_id": { "type": "string" }, "text": { "type": "string" } }, "additionalProperties": false }, "QuestionResponder": { "type": "string", "enum": [ "information", "human_decision" ] }, "RawSessionConfig": { "type": "object", "required": [ "session_id", "model", "base_url", "allow_insecure_http", "backend", "reasoning_effort", "api_key_env", "extra_headers_json", "orchestrator_compaction_threshold", "config_version" ], "properties": { "allow_insecure_http": { "type": "boolean" }, "api_key_env": { "type": [ "string", "null" ] }, "backend": { "type": [ "string", "null" ] }, "base_url": { "type": "string" }, "config_version": { "type": "integer", "format": "int64" }, "diagnostics": { "type": "array", "items": { "type": "string" }, "description": "Structural parse failures in the persisted values. These are diagnostics,\nnot migrations: callers must explicitly PATCH every invalid value." }, "extra_headers_json": { "type": [ "string", "null" ] }, "light_model": { "oneOf": [ { "$ref": "#/components/schemas/LightModelSettings", "description": "Light worker model; `None` keeps single-model dispatch." }, { "type": "null" } ] }, "model": { "type": "string" }, "orchestrator_compaction_threshold": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "reasoning_effort": { "type": [ "string", "null" ] }, "session_id": { "type": "string" } } }, "ReadinessCheck": { "type": "object", "required": [ "name", "ready", "detail" ], "properties": { "detail": { "type": "string" }, "name": { "type": "string" }, "ready": { "type": "boolean" } } }, "ReadinessResponse": { "type": "object", "required": [ "status", "managed", "version", "schema_version", "product_version", "build_id", "build_track", "source_revision", "supported_schema_version", "minimum_migratable_schema_version", "migration_state", "maintenance_state", "checks" ], "properties": { "build_id": { "type": "string" }, "build_track": { "type": "string" }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/ReadinessCheck" } }, "maintenance_state": { "type": "string" }, "managed": { "type": "boolean" }, "migration_failure": { "type": [ "string", "null" ] }, "migration_state": { "type": "string" }, "minimum_migratable_schema_version": { "type": "integer", "format": "int64" }, "opened_schema_version": { "type": [ "integer", "null" ], "format": "int64" }, "product_version": { "type": "string" }, "schema_version": { "type": "integer", "format": "int64" }, "source_revision": { "type": "string" }, "status": { "type": "string" }, "supported_schema_version": { "type": "integer", "format": "int64" }, "version": { "type": "string" } } }, "ReasoningEffort": { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] }, "RecentEventsResponse": { "type": "object", "required": [ "boundary", "events" ], "properties": { "boundary": { "$ref": "#/components/schemas/SessionEventBoundary" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/SessionEventEnvelope" } } } }, "RecoveryAction": { "type": "string", "enum": [ "automatic_retry", "resume_goal", "regenerate_with_rewind", "settings", "none" ] }, "RefreshSessionIntegrationsRequest": { "type": "object", "required": [ "expected_revision" ], "properties": { "expected_revision": { "type": "integer", "format": "int64" } }, "additionalProperties": false }, "RegenerateSessionRequest": { "type": "object", "required": [ "message_idx" ], "properties": { "message_idx": { "type": "integer", "description": "Transcript index of the user message to answer again. It and everything\nafter it are dropped before the same prompt is submitted afresh.", "minimum": 0 } } }, "ReorderProjectsRequest": { "type": "object", "required": [ "pinned", "project_ids", "expected_versions" ], "properties": { "expected_versions": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "propertyNames": { "type": "string" } }, "pinned": { "type": "boolean" }, "project_ids": { "type": "array", "items": { "type": "string" } } } }, "ReorderProjectsResponse": { "type": "object", "required": [ "pinned", "projects" ], "properties": { "pinned": { "type": "boolean" }, "projects": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectRecord" } } } }, "ReorderSessionsRequest": { "type": "object", "required": [ "pinned", "session_ids", "expected_versions" ], "properties": { "expected_versions": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "propertyNames": { "type": "string" } }, "pinned": { "type": "boolean" }, "session_ids": { "type": "array", "items": { "type": "string" } } } }, "ReorderSessionsResponse": { "type": "object", "required": [ "pinned", "sessions" ], "properties": { "pinned": { "type": "boolean" }, "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/SessionSummarySnapshot" } } } }, "ReplayBoundaryEvent": { "type": "object", "required": [ "epoch_id", "replay_boundary_sequence_id" ], "properties": { "epoch_id": { "type": "string" }, "replay_boundary_sequence_id": { "type": "integer", "format": "int64", "minimum": 0 } } }, "ReplayGapEvent": { "type": "object", "required": [ "replay_gap" ], "properties": { "replay_gap": { "$ref": "#/components/schemas/SessionReplayGap" } } }, "ReplyPermissionRequest": { "type": "object", "required": [ "reply" ], "properties": { "reply": { "$ref": "#/components/schemas/PermissionReply" } } }, "RequestField_BTreeMap_BTreeMap_String_McpToolApproval": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": { "type": "string", "enum": [ "allow", "ask" ] }, "propertyNames": { "type": "string" } } ] }, "RequestField_BTreeMap_BTreeMap_String_Option_String": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "propertyNames": { "type": "string" } } ] }, "RequestField_BTreeMap_BTreeMap_String_String": { "oneOf": [ { "type": "null" }, { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } } ] }, "RequestField_BackendKind_BackendKind": { "oneOf": [ { "type": "null" }, { "type": "string", "enum": [ "deepseek-chat", "fireworks-chat", "together-chat", "openai-responses", "openai-chat-completions", "chatgpt-codex-responses", "anthropic-messages", "arcee-auth", "arcee-api" ] } ] }, "RequestField_HeadersRequest_HeadersRequest": { "oneOf": [ { "type": "null" }, { "oneOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "string", "description": "Compatibility form: a nonblank string containing a JSON object with string values.", "pattern": ".*\\S.*" } ], "description": "Prefer an object of header names to values. The JSON-encoded string form is accepted for compatibility." } ] }, "RequestField_LightModelSettings_LightModelSettings": { "oneOf": [ { "type": "null" }, { "type": "object", "description": "The optional light model selection stored with a session. Orchestrator\nruntimes use it for weight-classified dispatch, and direct-with-orchestrator\nsessions pass it to the orchestrators they launch. Plain direct sessions\nretain it without a runtime consumer pending ALL-36. The model remains a\ncatalog id; backend and reasoning effort are typed before entering the\ndomain model, and the credential is always a selector name, never a key\nvalue.", "required": [ "model" ], "properties": { "api_key_env": { "type": [ "string", "null" ] }, "backend": { "oneOf": [ { "$ref": "#/components/schemas/BackendKind" }, { "type": "null" } ] }, "base_url": { "type": [ "string", "null" ] }, "model": { "type": "string" }, "reasoning_effort": { "oneOf": [ { "$ref": "#/components/schemas/ReasoningEffort" }, { "type": "null" } ] } } } ] }, "RequestField_McpProtocolSelection_McpProtocolSelection": { "oneOf": [ { "type": "null" }, { "type": "string", "description": "Selects the MCP lifecycle independently for each configured server.", "enum": [ "legacy", "auto", "current" ] } ] }, "RequestField_McpToolApproval_McpToolApproval": { "oneOf": [ { "type": "null" }, { "type": "string", "enum": [ "allow", "ask" ] } ] }, "RequestField_ReasoningEffort_ReasoningEffort": { "oneOf": [ { "type": "null" }, { "type": "string", "enum": [ "none", "minimal", "low", "medium", "high", "xhigh", "max" ] } ] }, "RequestField_String_String": { "oneOf": [ { "type": "null" }, { "type": "string" } ] }, "RequestField_UpdateMcpHeaderHelperRequest_UpdateMcpHeaderHelperRequest": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "command" ], "properties": { "args": { "type": "array", "items": { "type": "string" } }, "command": { "type": "string" }, "cwd": { "type": [ "string", "null" ] }, "env": { "type": "object", "additionalProperties": { "type": [ "string", "null" ], "writeOnly": true }, "propertyNames": { "type": "string", "writeOnly": true } }, "env_vars": { "type": "array", "items": { "type": "string" } }, "timeout_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } } ] }, "RequestField_Vec_Vec_String": { "oneOf": [ { "type": "null" }, { "type": "array", "items": { "type": "string" } } ] }, "RequestField_bool_bool": { "oneOf": [ { "type": "null" }, { "type": "boolean" } ] }, "RequestField_u16_u16": { "oneOf": [ { "type": "null" }, { "type": "integer", "format": "int32", "minimum": 0 } ] }, "RequestField_u64_u64": { "oneOf": [ { "type": "null" }, { "type": "integer", "format": "int64", "minimum": 0 } ] }, "ResizeUserTerminalRequest": { "type": "object", "required": [ "protocol_version", "cols", "rows" ], "properties": { "cols": { "type": "integer", "format": "int32", "minimum": 0 }, "protocol_version": { "type": "integer", "format": "int32", "minimum": 0 }, "rows": { "type": "integer", "format": "int32", "minimum": 0 } }, "additionalProperties": false }, "ResolvedModelConfiguration": { "type": "object", "required": [ "backend", "model", "base_url", "allow_insecure_http", "api_key_env", "reasoning_effort", "models", "models_error" ], "properties": { "allow_insecure_http": { "type": "boolean" }, "api_key_env": { "type": [ "string", "null" ] }, "backend": { "$ref": "#/components/schemas/BackendKind" }, "base_url": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderModel" } }, "models_error": { "type": [ "string", "null" ] }, "reasoning_effort": { "oneOf": [ { "$ref": "#/components/schemas/ReasoningEffort" }, { "type": "null" } ] } } }, "ResponseTimingSnapshot": { "type": "object", "properties": { "cumulative_token_usage": { "oneOf": [ { "$ref": "#/components/schemas/TokenUsage" }, { "type": "null" } ] }, "last_response_duration_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "last_token_usage": { "oneOf": [ { "$ref": "#/components/schemas/TokenUsage" }, { "type": "null" } ] }, "previous_response_duration_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "response_durations_ms": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } }, "token_usages": { "type": [ "array", "null" ], "items": { "oneOf": [ { "$ref": "#/components/schemas/TokenUsage" }, { "type": "null" } ] } }, "unattributed_token_usage": { "oneOf": [ { "$ref": "#/components/schemas/TokenUsage", "description": "Cumulative usage from runs that produced no visible response." }, { "type": "null" } ] } } }, "RevealWorkspacePathRequest": { "type": "object", "required": [ "path", "expected_workspace_root", "expected_path_root" ], "properties": { "expected_path_root": { "type": "string", "description": "Coordinate root of the originating Files listing. Ordinary directory\ncallers explicitly use their selected workspace root. Never an OS target." }, "expected_workspace_root": { "type": "string", "description": "Root observed in the initiating session snapshot; never a target override." }, "path": { "type": "string", "description": "Existing path, relative to the explicitly observed expected_path_root." } }, "additionalProperties": false }, "RevertSessionRequest": { "type": "object", "required": [ "message_idx" ], "properties": { "message_idx": { "type": "integer", "description": "Transcript index of the user message to go back to. That message and\neverything after it are dropped.", "minimum": 0 } } }, "RevertSessionResponse": { "type": "object", "required": [ "transcript_len", "messages_removed", "workspace_restored", "revisions_removed", "threads_removed" ], "properties": { "messages_removed": { "type": "integer", "minimum": 0 }, "revisions_removed": { "type": "integer", "minimum": 0 }, "threads_removed": { "type": "integer", "minimum": 0 }, "transcript_len": { "type": "integer", "minimum": 0 }, "workspace_restored": { "type": "boolean" } } }, "ReviewCategory": { "type": "string", "description": "Risk category reported by a reviewer.", "enum": [ "routine", "destructive", "exfiltration", "credential", "out_of_scope", "unclear" ] }, "ReviewResource": { "type": "object", "description": "One resource as the reviewer sees it.", "required": [ "action", "resource", "display" ], "properties": { "action": { "type": "string" }, "display": { "type": "string" }, "resource": { "type": "string" } } }, "RunFailure": { "type": "object", "description": "Credential-redacted failure metadata suitable for persistence and API use.", "required": [ "kind", "phase", "transient", "attempt_count", "summary", "diagnostic", "recovery_action" ], "properties": { "attempt_count": { "type": "integer", "format": "int32", "minimum": 0 }, "diagnostic": { "type": "string" }, "http_status": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "kind": { "$ref": "#/components/schemas/RunFailureKind" }, "partial_output": { "$ref": "#/components/schemas/PartialModelOutput" }, "phase": { "$ref": "#/components/schemas/RunFailurePhase" }, "recovery_action": { "$ref": "#/components/schemas/RecoveryAction" }, "retry_after_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "summary": { "type": "string" }, "transient": { "type": "boolean" } } }, "RunFailureKind": { "type": "string", "description": "Stable failure categories carried from execution into durable presentation.\nProvider-specific wire codes are deliberately collapsed at the adapter edge.", "enum": [ "transport", "capacity", "authentication", "validation", "configuration", "protocol", "interrupted", "unknown" ] }, "RunFailurePhase": { "type": "string", "enum": [ "request", "response", "stream", "decode", "agent" ] }, "SandboxActivity": { "type": "object", "description": "What sandbox setup is currently doing for one launching session, for UIs\nwaiting on a launch. Sandbox creation can take minutes (a first image\npull), and without this the only signal is a hung request.", "required": [ "phase", "since_epoch_ms" ], "properties": { "phase": { "type": "string" }, "since_epoch_ms": { "type": "integer", "format": "int64", "minimum": 0 } } }, "SandboxAvailability": { "type": "object", "description": "The result of probing the sandbox runtime, with the steps that would make\nit usable. Surfaced by the API so launch UIs can warn before a session\nfails, and embedded in session-creation errors for agents driving the MCP.", "required": [ "status" ], "properties": { "detail": { "type": [ "string", "null" ], "description": "Why the runtime is unusable, when it is." }, "guidance": { "type": [ "string", "null" ], "description": "Platform-specific commands that would make it usable." }, "status": { "$ref": "#/components/schemas/SandboxAvailabilityStatus" } } }, "SandboxAvailabilityStatus": { "type": "string", "description": "Whether the sandbox runtime (podman) can be used on this host right now.", "enum": [ "ready", "missing", "unavailable" ] }, "SandboxRequest": { "type": "object", "properties": { "activity_key": { "type": [ "string", "null" ], "description": "Client-generated launch id used to key sandbox setup activity, so the\nlaunching UI polls its own launch's progress. Deliberately not part of\n`sandbox_requested`: it correlates progress reporting, nothing else." }, "backend": { "type": [ "string", "null" ] }, "cpus": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "enabled": { "type": "boolean" }, "gpus": { "type": "array", "items": { "type": "string" } }, "image": { "type": [ "string", "null" ] }, "memory_mib": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "mounts": { "type": "array", "items": { "type": "string" } }, "mounts_ro": { "type": "array", "items": { "type": "string" } }, "no_mount_cwd": { "type": "boolean" }, "session_key": { "type": [ "string", "null" ] }, "shm_size": { "type": [ "string", "null" ] }, "workdir": { "type": [ "string", "null" ] } } }, "SessionBehavior": { "type": "string", "description": "Immutable execution behavior selected when a top-level session is created.\nStored as text so future behaviors can fail closed instead of being\nmisinterpreted as the orchestrator.", "enum": [ "orchestrator", "direct", "direct-with-orchestrator" ] }, "SessionClientId": { "type": "string" }, "SessionEvent": { "oneOf": [ { "type": "object", "description": "Agent/model progress. The canonical top-level session busy lifecycle is\nrepresented by RunStarted/RunCompleted/RunFailed/RunCancelled. AgentEvent\nRunStarted/RunFinished remain low-level progress markers.", "required": [ "event", "type" ], "properties": { "event": { "$ref": "#/components/schemas/AgentEvent" }, "type": { "type": "string", "enum": [ "agent" ] } } }, { "type": "object", "required": [ "prompt_preview", "started_at_epoch_ms", "type" ], "properties": { "prompt_preview": { "type": "string" }, "started_at_epoch_ms": { "type": "integer", "format": "int64", "minimum": 0 }, "submitted_user_message": { "oneOf": [ { "$ref": "#/components/schemas/SubmittedUserMessageSnapshot" }, { "type": "null" } ] }, "type": { "type": "string", "enum": [ "run_started" ] } } }, { "type": "object", "required": [ "response", "type" ], "properties": { "duration_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "response": { "type": "string" }, "type": { "type": "string", "enum": [ "run_completed" ] } } }, { "type": "object", "required": [ "message", "type" ], "properties": { "failure": { "oneOf": [ { "$ref": "#/components/schemas/RunFailure" }, { "type": "null" } ] }, "message": { "type": "string" }, "type": { "type": "string", "enum": [ "run_failed" ] } } }, { "type": "object", "description": "The run ended because the user asked it to, which is an outcome rather\nthan a fault. Carries no message: the user already knows what happened,\nand the reason is a constant with nothing to report.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "run_cancelled" ] } } }, { "type": "object", "description": "Live approval request for a prepared direct-session tool invocation.\nThe broker owns the pending state; this event lets web clients render\nit without polling.", "required": [ "request", "type" ], "properties": { "request": { "$ref": "#/components/schemas/PermissionRequest" }, "type": { "type": "string", "enum": [ "permission_asked" ] } } }, { "type": "object", "required": [ "request_id", "reply", "type" ], "properties": { "reply": { "$ref": "#/components/schemas/PermissionReply" }, "request_id": { "type": "string" }, "type": { "type": "string", "enum": [ "permission_replied" ] } } }, { "type": "object", "description": "The waiting call ended without a user reply (for example cancellation\nor timeout), so clients must remove the no-longer-actionable prompt.", "required": [ "request_id", "reason", "type" ], "properties": { "reason": { "type": "string" }, "request_id": { "type": "string" }, "type": { "type": "string", "enum": [ "permission_dismissed" ] } } }, { "type": "object", "description": "The durable answer policy for this direct session changed. No request\nresources or credential-bearing payloads are included.", "required": [ "mode", "type" ], "properties": { "mode": { "$ref": "#/components/schemas/PermissionApprovalMode" }, "type": { "type": "string", "enum": [ "permission_approval_mode_changed" ] } } }, { "type": "object", "description": "An eligible Ask request was sent to the automatic reviewer. Carries\nonly the redacted projection the reviewer sees.", "required": [ "review", "type" ], "properties": { "review": { "$ref": "#/components/schemas/PermissionReview" }, "type": { "type": "string", "enum": [ "permission_review_started" ] } } }, { "type": "object", "description": "The automatic reviewer finished. Rejected and uncertain reviews are\nreturned to the model unexecuted; the user may authorize one retry.", "required": [ "review", "type" ], "properties": { "review": { "$ref": "#/components/schemas/PermissionReview" }, "type": { "type": "string", "enum": [ "permission_reviewed" ] } } }, { "type": "object", "required": [ "session_id", "type" ], "properties": { "session_id": { "type": "string" }, "type": { "type": "string", "enum": [ "snapshot_saved" ] } } }, { "type": "object", "description": "Live-only signal that the orchestrator transcript log gained rows\n(DB-direct transcript workset, step 3). `transcript_len` is the raw\nmerged transcript length after the append. Emitted at each transcript\ncommit point so subscribers refetch the store-backed transcript\nmid-run. Never persisted: the bus persists only Agent events.", "required": [ "transcript_len", "type" ], "properties": { "transcript_len": { "type": "integer", "format": "int64", "minimum": 0 }, "type": { "type": "string", "enum": [ "transcript_appended" ] } } }, { "type": "object", "description": "Live-only signal that a revert cut the transcript back to\n`transcript_len` messages. Subscribers must refetch rather than apply a\ndelta: unlike an append, everything they hold past this point is gone.", "required": [ "transcript_len", "type" ], "properties": { "transcript_len": { "type": "integer", "format": "int64", "minimum": 0 }, "type": { "type": "string", "enum": [ "transcript_reverted" ] } } } ] }, "SessionEventBoundary": { "type": "object", "required": [ "epoch_id", "sequence_id" ], "properties": { "epoch_id": { "type": "string" }, "sequence_id": { "type": "integer", "format": "int64", "minimum": 0 } } }, "SessionEventEnvelope": { "type": "object", "required": [ "epoch_id", "sequence_id", "event" ], "properties": { "client_id": { "oneOf": [ { "$ref": "#/components/schemas/SessionClientId" }, { "type": "null" } ] }, "epoch_id": { "type": "string" }, "event": { "$ref": "#/components/schemas/SessionEvent" }, "run_id": { "oneOf": [ { "$ref": "#/components/schemas/SessionRunId" }, { "type": "null" } ] }, "sequence_id": { "type": "integer", "format": "int64", "minimum": 0 }, "session_id": { "type": [ "string", "null" ] } } }, "SessionForkLink": { "type": "object", "required": [ "session_id", "source_message_idx", "deleted" ], "properties": { "deleted": { "type": "boolean", "description": "True when the forked session row is gone. The original chat still\nshows the marker as a deleted item until the user dismisses it." }, "session_id": { "type": "string" }, "source_message_idx": { "type": "integer", "minimum": 0 }, "title": { "type": [ "string", "null" ], "description": "Live fork presentation title. Absent on a deleted fork." } } }, "SessionForkOrigin": { "type": "object", "description": "The chat this session was forked from, for tab and list-row marks.", "required": [ "session_id", "title" ], "properties": { "deleted": { "type": "boolean", "description": "True when the original chat row is gone. The stored title still names it." }, "session_id": { "type": "string" }, "title": { "type": "string" } } }, "SessionFrontendSnapshot": { "type": "object", "required": [ "metadata", "messages", "response_timing", "sessions", "threads", "thread_episodes", "thread_event_boundary", "worksets", "workspace" ], "properties": { "active_compaction": { "oneOf": [ { "$ref": "#/components/schemas/ActiveCompactionSnapshot" }, { "type": "null" } ] }, "active_run": { "oneOf": [ { "$ref": "#/components/schemas/ActiveRunSnapshot" }, { "type": "null" } ] }, "active_threads": { "type": "array", "items": { "type": "string" } }, "covered_orchestrator_steering_ids": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "Delivered orchestrator steering records whose verbatim user message is\nalready present in the transcript source backing this snapshot. The\nfrontend hides those records so guidance renders exactly once — as the\ncanonical user message." }, "forks": { "type": "array", "items": { "$ref": "#/components/schemas/SessionForkLink" }, "description": "Conversation forks created from a model turn in this session." }, "message_created_at": { "type": "array", "items": { "type": [ "string", "null" ] }, "description": "When each message was written to the transcript log, aligned with\n`messages`. `None` for messages carried by the snapshot blob, which\npredates the log and stores no per-message time." }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "metadata": { "$ref": "#/components/schemas/SessionMetadata" }, "primary_tool_events": { "type": "array", "items": { "$ref": "#/components/schemas/AgentEvent" }, "description": "Sanitized, bounded lifecycle events for top-level direct tool calls.\nKept separate from worker logs so primary calls cannot become a fake\ndelegated topology and the web never needs raw transcript payloads." }, "response_timing": { "$ref": "#/components/schemas/ResponseTimingSnapshot" }, "run_failure": { "oneOf": [ { "$ref": "#/components/schemas/RunFailure" }, { "type": "null" } ] }, "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/SessionSummarySnapshot" } }, "shell_commands": { "type": "array", "items": { "$ref": "#/components/schemas/ShellCommandSnapshot" } }, "thread_episodes": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/EpisodeSnapshot" } }, "propertyNames": { "type": "string" } }, "thread_event_boundary": { "$ref": "#/components/schemas/SessionEventBoundary" }, "thread_event_diagnostics": { "type": "array", "items": { "$ref": "#/components/schemas/ThreadEventDecodeDiagnostic" } }, "thread_events": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/AgentEvent" } }, "propertyNames": { "type": "string" } }, "thread_steering": { "type": "array", "items": { "$ref": "#/components/schemas/ThreadSteeringRecord" } }, "threads": { "type": "array", "items": { "$ref": "#/components/schemas/ThreadSnapshot" } }, "transcript_recovery_warning": { "type": [ "string", "null" ] }, "worksets": { "$ref": "#/components/schemas/WorksetsSnapshot" }, "workspace": { "$ref": "#/components/schemas/WorkspaceSnapshot" } } }, "SessionGoalRecord": { "type": "object", "required": [ "session_id", "goal_id", "objective", "status", "token_budget", "tokens_used", "time_used_ms", "accounting_run_id", "accounting_token_baseline", "accounting_started_at_epoch_ms", "continuation_run_id", "consecutive_transient_failures", "next_attempt_at_epoch_ms", "last_failure", "created_at", "updated_at", "version" ], "properties": { "accounting_run_id": { "type": [ "string", "null" ] }, "accounting_started_at_epoch_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "accounting_token_baseline": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "consecutive_transient_failures": { "type": "integer", "format": "int32", "minimum": 0 }, "continuation_run_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "goal_id": { "type": "string" }, "last_failure": { "oneOf": [ { "$ref": "#/components/schemas/RunFailure" }, { "type": "null" } ] }, "next_attempt_at_epoch_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "objective": { "type": "string" }, "session_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/GoalStatus" }, "time_used_ms": { "type": "integer", "format": "int64", "minimum": 0 }, "token_budget": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "tokens_used": { "type": "integer", "format": "int64", "minimum": 0 }, "updated_at": { "type": "string" }, "version": { "type": "integer", "format": "int64" } } }, "SessionLineageKind": { "type": "string", "enum": [ "traditional-child", "managed-orchestrator" ] }, "SessionLineageSnapshot": { "type": "object", "required": [ "kind", "parent_session_id", "root_session_id", "description" ], "properties": { "description": { "type": "string" }, "kind": { "$ref": "#/components/schemas/SessionLineageKind" }, "parent_session_id": { "type": "string" }, "root_session_id": { "type": "string" } } }, "SessionMcpRefreshState": { "type": "string", "enum": [ "not_requested", "current", "pending", "degraded", "failed", "scheduled_for_workers" ] }, "SessionMcpRefreshStatus": { "type": "object", "required": [ "revision", "requested_at", "applied_revision", "incarnation_id", "state", "message" ], "properties": { "applied_revision": { "type": [ "integer", "null" ], "format": "int64", "description": "Process-local acknowledgement for this direct agent incarnation. An\norchestrator has independent workers and does not claim an aggregate acknowledgement." }, "incarnation_id": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "requested_at": { "type": [ "string", "null" ] }, "revision": { "type": "integer", "format": "int64" }, "state": { "$ref": "#/components/schemas/SessionMcpRefreshState" } } }, "SessionMetadata": { "type": "object", "required": [ "cwd", "store_path", "model", "backend", "sandbox_status", "agents_md_status" ], "properties": { "agents_md_status": { "type": "string" }, "api_key_env": { "type": [ "string", "null" ] }, "backend": { "type": "string" }, "base_url": { "type": "string" }, "behavior": { "$ref": "#/components/schemas/SessionBehavior" }, "cwd": { "type": "string" }, "extra_headers": { "type": "object", "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "model": { "type": "string" }, "project_id": { "type": [ "string", "null" ] }, "reasoning_effort": { "type": [ "string", "null" ] }, "sandbox_status": { "type": "string" }, "session_id": { "type": [ "string", "null" ] }, "store_path": { "type": "string" }, "workspace_host_path": { "type": [ "string", "null" ] } } }, "SessionReplayGap": { "type": "object", "required": [ "missing_from_sequence_id", "missing_to_sequence_id" ], "properties": { "missing_from_sequence_id": { "type": "integer", "format": "int64", "minimum": 0 }, "missing_to_sequence_id": { "type": "integer", "format": "int64", "minimum": 0 } } }, "SessionRunId": { "type": "string" }, "SessionSnapshotResponse": { "allOf": [ { "$ref": "#/components/schemas/SessionFrontendSnapshot" }, { "type": "object", "properties": { "lineage": { "oneOf": [ { "$ref": "#/components/schemas/SessionLineageSnapshot" }, { "type": "null" } ] }, "message_cycle": { "oneOf": [ { "$ref": "#/components/schemas/MessageCycleMetadata" }, { "type": "null" } ] }, "message_page": { "oneOf": [ { "$ref": "#/components/schemas/MessagePageMetadata" }, { "type": "null" } ] }, "terminal_selection_attributions": { "type": "array", "items": { "$ref": "#/components/schemas/TerminalSelectionMessageReference" } } } } ] }, "SessionSummarySnapshot": { "type": "object", "required": [ "session_id", "cwd", "model", "backend", "visible_message_count", "last_user_prompt", "sandboxed", "ssh_host", "title", "created_at", "updated_at" ], "properties": { "backend": { "type": "string" }, "behavior": { "$ref": "#/components/schemas/SessionBehavior" }, "created_at": { "type": "string" }, "cwd": { "type": "string" }, "forked_from": { "oneOf": [ { "$ref": "#/components/schemas/SessionForkOrigin", "description": "Present when this chat was forked from another session." }, { "type": "null" } ] }, "last_user_prompt": { "type": [ "string", "null" ] }, "model": { "type": "string" }, "model_config_error": { "type": [ "string", "null" ] }, "pinned": { "type": "boolean" }, "presentation_version": { "type": "integer", "format": "int64" }, "project_id": { "type": [ "string", "null" ] }, "run_count": { "type": "integer", "format": "int64", "description": "Runs ever started in this session. Older stored snapshots default to 0.", "minimum": 0 }, "sandboxed": { "type": "boolean" }, "session_id": { "type": "string" }, "sort_order": { "type": "integer", "format": "int64" }, "ssh_host": { "type": [ "string", "null" ], "description": "OpenSSH/freeform target the session runs on; `None` = local session." }, "ssh_identity_file": { "type": [ "string", "null" ] }, "ssh_port": { "type": [ "integer", "null" ], "format": "int32", "description": "Port and key the session was created with, so anything rebuilding the\nconnection reaches the same machine the same way. Omitted when the\nsession leaves them to ssh, which is what older snapshots always did.", "minimum": 0 }, "title": { "type": [ "string", "null" ] }, "total_cost_micros": { "type": [ "integer", "null" ], "format": "int64", "description": "Micro-USD spend for the session. Omitted when no usage was recorded;\nzero means the catalog had no rates for the model.", "minimum": 0 }, "total_tokens": { "type": [ "integer", "null" ], "format": "int64", "description": "Billable tokens accumulated over the session. Omitted when unknown, so\nolder stored snapshots keep deserializing.", "minimum": 0 }, "updated_at": { "type": "string" }, "visible_message_count": { "type": "integer", "minimum": 0 } } }, "ShellCommandRequest": { "type": "object", "required": [ "request_id", "command" ], "properties": { "command": { "type": "string" }, "request_id": { "type": "string" }, "timeout_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } }, "ShellCommandSnapshot": { "type": "object", "required": [ "request_id", "operation_id", "command", "timeout_ms", "state", "accepted_at_epoch_ms", "stdout", "stderr" ], "properties": { "accepted_at_epoch_ms": { "type": "integer", "format": "int64", "minimum": 0 }, "command": { "type": "string", "description": "Credential literals are masked before this projection is persisted." }, "diagnostic": { "type": [ "string", "null" ] }, "exit_code": { "type": [ "integer", "null" ], "format": "int32" }, "finished_at_epoch_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "operation_id": { "type": "string" }, "output_id": { "type": [ "string", "null" ] }, "request_id": { "type": "string" }, "state": { "$ref": "#/components/schemas/ShellCommandState" }, "stderr": { "type": "string" }, "stdout": { "type": "string" }, "timeout_ms": { "type": "integer", "format": "int64", "minimum": 0 }, "transcript_index": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } }, "ShellCommandState": { "type": "string", "enum": [ "accepted", "started", "completed", "timed_out", "cancelled", "rejected", "spawn_failed", "interrupted", "outcome_unknown" ] }, "ShellOutputPage": { "type": "object", "required": [ "content", "offset", "next_offset", "eof", "overflowed" ], "properties": { "content": { "type": "string" }, "eof": { "type": "boolean" }, "next_offset": { "type": "integer", "format": "int64", "minimum": 0 }, "offset": { "type": "integer", "format": "int64", "minimum": 0 }, "overflowed": { "type": "boolean" } } }, "SkillCatalogEntry": { "type": "object", "required": [ "name", "description" ], "properties": { "compatibility": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "name": { "type": "string" } } }, "SlashCommand": { "type": "string", "description": "Slash commands understood by NAC.", "enum": [ "compact", "goal", "mcp_prompt" ] }, "SlashCommandDefinition": { "type": "object", "description": "User-facing metadata shared by command parsing and frontend discovery.", "required": [ "command", "name", "description", "accepts_arguments" ], "properties": { "accepts_arguments": { "type": "boolean" }, "arguments": { "type": "array", "items": { "$ref": "#/components/schemas/McpPromptArgument" } }, "command": { "$ref": "#/components/schemas/SlashCommand" }, "description": { "type": "string" }, "name": { "type": "string" } } }, "SshBrowseRequest": { "type": "object", "description": "Where to look on an SSH host, for the remote half of the path picker.\n\nThe connection is described in the request rather than taken from a session,\nbecause this is what the launch form asks *before* there is a session.", "properties": { "hidden": { "type": "boolean", "description": "Dot-prefixed names are hidden unless explicitly requested, as locally." }, "path": { "type": [ "string", "null" ], "description": "Absent or empty opens on the login home, which is where a fresh remote\nsession would start anyway." }, "ssh_host": { "type": [ "string", "null" ] }, "ssh_identity_file": { "type": [ "string", "null" ] }, "ssh_port": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } }, "SshConfigurationList": { "type": "object", "required": [ "configurations" ], "properties": { "configurations": { "type": "array", "items": { "$ref": "#/components/schemas/SshConfigurationRecord" } } } }, "SshConfigurationRecord": { "type": "object", "description": "A named, reusable SSH connection offered by the launch modal.", "required": [ "config_id", "name", "ssh_host", "created_at", "updated_at" ], "properties": { "config_id": { "type": "string" }, "created_at": { "type": "string" }, "name": { "type": "string" }, "ssh_host": { "type": "string" }, "ssh_identity_file": { "type": [ "string", "null" ] }, "ssh_port": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "updated_at": { "type": "string" } } }, "StartManagedCloneRequest": { "type": "object", "required": [ "repository_id", "repository", "branch", "destination", "project_name" ], "properties": { "branch": { "type": "string" }, "destination": { "type": "string" }, "project_description": { "type": [ "string", "null" ] }, "project_name": { "type": "string" }, "repository": { "type": "string" }, "repository_id": { "type": "integer", "format": "int64", "minimum": 0 } } }, "StartManagedOrchestratorRequest": { "type": "object", "required": [ "description", "prompt" ], "properties": { "background": { "type": "boolean" }, "description": { "type": "string" }, "orchestrator_session_id": { "type": [ "string", "null" ] }, "prompt": { "type": "string" } } }, "StartTraditionalChildRequest": { "type": "object", "required": [ "profile", "description", "prompt" ], "properties": { "background": { "type": "boolean" }, "child_session_id": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "profile": { "type": "string" }, "prompt": { "type": "string" } } }, "StoreCredentialRequest": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string", "example": "fake-credential-value", "writeOnly": true } } }, "StoreInfo": { "type": "object", "required": [ "root_cwd", "store_path", "worker_executable" ], "properties": { "root_cwd": { "type": "string" }, "store_path": { "type": "string" }, "worker_executable": { "type": "string" } } }, "StoredCredentialList": { "type": "object", "required": [ "credentials" ], "properties": { "credentials": { "type": "array", "items": { "$ref": "#/components/schemas/StoredCredentialSummary" } } } }, "StoredCredentialSummary": { "type": "object", "required": [ "name", "last_four" ], "properties": { "last_four": { "type": "string", "description": "Empty when the secret is too short for a suffix to be safe to show." }, "name": { "type": "string" } } }, "SubmitPromptRequest": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string" } } }, "SubmitPromptResponse": { "type": "object", "required": [ "run_id", "display_prompt" ], "properties": { "client_id": { "type": [ "string", "null" ] }, "display_prompt": { "type": "string" }, "run_id": { "type": "string" } } }, "SubmittedUserMessageSnapshot": { "type": "object", "required": [ "run_id", "content", "submitted_at_epoch_ms" ], "properties": { "client_id": { "oneOf": [ { "$ref": "#/components/schemas/SessionClientId" }, { "type": "null" } ] }, "content": { "type": "string" }, "run_id": { "$ref": "#/components/schemas/SessionRunId" }, "submitted_at_epoch_ms": { "type": "integer", "format": "int64", "minimum": 0 }, "terminal_selection": { "oneOf": [ { "$ref": "#/components/schemas/TerminalSelectionEvidence", "description": "Read-only projection carried by the identified inbox admission, before\ncanonical transcript hydration catches up. Legacy/ordinary input omits it." }, { "type": "null" } ] } } }, "SwitchBranchRequest": { "type": "object", "required": [ "name" ], "properties": { "create": { "type": "boolean", "description": "Make the branch first, off the current HEAD." }, "name": { "type": "string" } } }, "TaskFollowupAction": { "type": "string", "enum": [ "queue", "steer", "auto" ] }, "TaskFollowupDelegation": { "type": "object", "required": [ "id", "caller_session_id", "human_request_id", "target_session_id", "action", "issued_config_version", "origin", "created_at" ], "properties": { "action": { "$ref": "#/components/schemas/TaskFollowupAction" }, "caller_session_id": { "type": "string" }, "created_at": { "type": "string" }, "human_request_id": { "type": "string" }, "id": { "type": "string" }, "issued_config_version": { "type": "integer", "format": "int64" }, "origin": { "type": "string" }, "revoked_at": { "type": [ "string", "null" ] }, "target_session_id": { "type": "string" } } }, "TaskFollowupDelegationRequest": { "type": "object", "required": [ "request_id", "target_session_id", "action" ], "properties": { "action": { "$ref": "#/components/schemas/TaskFollowupAction" }, "project_id": { "type": [ "string", "null" ] }, "request_id": { "type": "string" }, "target_session_id": { "type": "string" } }, "additionalProperties": false }, "TaskLaunchPhase": { "type": "string", "enum": [ "pinned", "preparing_workspace", "preparing_runtime", "ready", "failed", "cancelled" ] }, "TaskLaunchRecord": { "type": "object", "required": [ "request", "source", "session_id", "workspace_path", "phase", "session_present", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string" }, "error": { "type": [ "string", "null" ] }, "first_input_id": { "type": [ "integer", "null" ], "format": "int64" }, "phase": { "$ref": "#/components/schemas/TaskLaunchPhase" }, "request": { "$ref": "#/components/schemas/TaskLaunchRequest" }, "session_id": { "type": "string" }, "session_present": { "type": "boolean", "description": "Passive projection; inventory survives deletion of its published session." }, "source": { "$ref": "#/components/schemas/TaskLaunchSource" }, "updated_at": { "type": "string" }, "workspace_path": { "type": "string" } } }, "TaskLaunchRequest": { "type": "object", "required": [ "request_id", "project_id", "title", "prompt" ], "properties": { "default_ref": { "type": [ "string", "null" ], "description": "Required when initially binding a project without an invoking task.\nThe binding persists independently of the ref selected for this launch." }, "git_ref": { "type": [ "string", "null" ] }, "invoking_session_id": { "type": [ "string", "null" ] }, "project_id": { "type": "string" }, "prompt": { "type": "string" }, "request_id": { "type": "string" }, "title": { "type": "string" } }, "additionalProperties": false }, "TaskLaunchSource": { "type": "object", "required": [ "project_cwd", "source_cwd", "repo_root", "common_git_dir", "repository_identity", "subdirectory", "default_ref", "selected_ref", "commit", "excluded_source_edits" ], "properties": { "commit": { "type": "string" }, "common_git_dir": { "type": "string" }, "default_ref": { "type": "string" }, "excluded_source_edits": { "type": "boolean", "description": "Source-selection policy, not the result of scanning dirty contents." }, "project_cwd": { "type": "string" }, "repo_root": { "type": "string" }, "repository_identity": { "type": "string" }, "selected_ref": { "type": "string" }, "source_cwd": { "type": "string" }, "subdirectory": { "type": "string" } } }, "TaskLaunchSourceInfo": { "type": "object", "required": [ "eligible" ], "properties": { "default_ref": { "type": [ "string", "null" ] }, "eligible": { "type": "boolean" } } }, "TerminalSelectionAttribution": { "type": "object", "required": [ "protocol_version", "intent_sha256", "source_kind", "admission_id", "capture_id", "source_session_id", "terminal_id", "owner_instance_id" ], "properties": { "admission_id": { "type": "string" }, "capture_id": { "type": "string" }, "client_capture_time_ms": { "type": [ "string", "null" ] }, "intent_sha256": { "type": "string" }, "owner_instance_id": { "type": "string" }, "protocol_version": { "type": "integer", "format": "int32", "minimum": 0 }, "source_kind": { "$ref": "#/components/schemas/TerminalSelectionSourceKind" }, "source_session_id": { "type": "string" }, "terminal_id": { "type": "string" } }, "additionalProperties": false }, "TerminalSelectionDelivery": { "type": "string", "enum": [ "send", "queue", "steer" ] }, "TerminalSelectionEvidence": { "type": "object", "description": "Read-only projection of reviewed canonical evidence; no live capability.", "required": [ "attribution", "text" ], "properties": { "attribution": { "$ref": "#/components/schemas/TerminalSelectionAttribution" }, "text": { "type": "string" }, "user_text": { "type": [ "string", "null" ] } } }, "TerminalSelectionIntent": { "type": "object", "required": [ "protocol_version", "source_kind", "admission_id", "capture_id", "source_session_id", "terminal_id", "owner_instance_id", "text", "initial_delivery" ], "properties": { "admission_id": { "type": "string" }, "capture_id": { "type": "string" }, "client_capture_time_ms": { "type": [ "string", "null" ] }, "initial_delivery": { "$ref": "#/components/schemas/TerminalSelectionDelivery" }, "initial_expected_run_id": { "type": [ "string", "null" ] }, "owner_instance_id": { "type": "string" }, "protocol_version": { "type": "integer", "format": "int32", "minimum": 0 }, "source_kind": { "$ref": "#/components/schemas/TerminalSelectionSourceKind" }, "source_session_id": { "type": "string" }, "terminal_id": { "type": "string" }, "text": { "type": "string" }, "user_text": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "TerminalSelectionMessageReference": { "type": "object", "description": "Presentation projection alongside the unchanged canonical attribution.", "required": [ "message_index", "attribution" ], "properties": { "attribution": { "$ref": "#/components/schemas/TerminalSelectionAttribution" }, "evidence": { "oneOf": [ { "$ref": "#/components/schemas/TerminalSelectionEvidence" }, { "type": "null" } ] }, "message_index": { "type": "integer", "format": "int64", "minimum": 0 } } }, "TerminalSelectionPreviewRequest": { "type": "object", "required": [ "protocol_version", "capture_id", "selected_text" ], "properties": { "capture_id": { "type": "string", "description": "Client-assigned hyphenated UUID for one frozen selection, not execution authority." }, "client_capture_time_ms": { "type": [ "string", "null" ], "description": "Untrusted optional capture-time claim in exact decimal milliseconds." }, "protocol_version": { "type": "integer", "format": "int32", "maximum": 1, "minimum": 1 }, "selected_text": { "type": "string", "maxLength": 8192 }, "user_text": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "TerminalSelectionPreviewResponse": { "type": "object", "required": [ "protocol_version", "capture_id", "source_kind", "source_session_id", "terminal_id", "owner_instance_id", "previewed_at_ms", "text", "input_utf8_bytes", "input_scalars", "text_utf8_bytes", "text_scalars", "controls_removed", "line_endings_normalized", "max_utf8_bytes", "max_scalars", "truncated" ], "properties": { "capture_id": { "type": "string" }, "client_capture_time_ms": { "type": [ "string", "null" ], "description": "The client claim is retained as a claim, never an authoritative capture time." }, "controls_removed": { "type": "integer", "format": "int32", "minimum": 0 }, "input_scalars": { "type": "integer", "format": "int32", "minimum": 0 }, "input_utf8_bytes": { "type": "integer", "format": "int32", "minimum": 0 }, "line_endings_normalized": { "type": "integer", "format": "int32", "minimum": 0 }, "max_scalars": { "type": "integer", "format": "int32", "minimum": 0 }, "max_utf8_bytes": { "type": "integer", "format": "int32", "minimum": 0 }, "owner_instance_id": { "type": "string" }, "previewed_at_ms": { "type": "string" }, "protocol_version": { "type": "integer", "format": "int32", "minimum": 0 }, "source_kind": { "$ref": "#/components/schemas/TerminalSelectionSourceKind" }, "source_session_id": { "type": "string" }, "terminal_id": { "type": "string" }, "text": { "type": "string" }, "text_scalars": { "type": "integer", "format": "int32", "minimum": 0 }, "text_utf8_bytes": { "type": "integer", "format": "int32", "minimum": 0 }, "truncated": { "type": "boolean", "description": "This endpoint rejects over-limit text; it never silently truncates." }, "user_text": { "type": [ "string", "null" ] } } }, "TerminalSelectionSourceKind": { "type": "string", "enum": [ "user_supplied_rendered_selection" ] }, "TerminalSelectionSubmissionRequest": { "type": "object", "required": [ "protocol_version", "admission_id", "capture_id", "expected_owner_instance_id", "original_selected_text", "expected_selection_text", "delivery" ], "properties": { "admission_id": { "type": "string" }, "capture_id": { "type": "string" }, "client_capture_time_ms": { "type": [ "string", "null" ] }, "delivery": { "$ref": "#/components/schemas/TerminalSelectionDelivery" }, "expected_owner_instance_id": { "type": "string" }, "expected_run_id": { "type": [ "string", "null" ] }, "expected_selection_text": { "type": "string" }, "expected_user_text": { "type": [ "string", "null" ] }, "original_selected_text": { "type": "string" }, "original_user_text": { "type": [ "string", "null" ] }, "protocol_version": { "type": "integer", "format": "int32", "minimum": 0 } }, "additionalProperties": false }, "TerminalSelectionSubmissionResponse": { "type": "object", "required": [ "protocol_version", "admission_id", "replayed", "inbox_id", "status", "version", "current_delivery", "accepted_intent" ], "properties": { "accepted_intent": { "$ref": "#/components/schemas/TerminalSelectionIntent" }, "admission_id": { "type": "string" }, "current_delivery": { "$ref": "#/components/schemas/InboxDelivery" }, "current_target_run_id": { "type": [ "string", "null" ] }, "delivered_run_id": { "type": [ "string", "null" ] }, "inbox_id": { "type": "string" }, "protocol_version": { "type": "integer", "format": "int32", "minimum": 0 }, "replayed": { "type": "boolean" }, "status": { "$ref": "#/components/schemas/InboxStatus", "description": "Current mutable inbox state, separate from immutable accepted intent." }, "version": { "type": "integer", "format": "int64" } } }, "TestMcpServerRequest": { "type": "object", "description": "Probes a server before anything is saved. Either names a saved server or\ncarries the draft inline; inline map values may be null to borrow the\nstored value when `stored_name` is also given.", "properties": { "args": { "type": [ "array", "null" ], "items": { "type": "string" } }, "bearer_token_env_var": { "type": [ "string", "null" ] }, "catalog_timeout_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "command": { "type": [ "string", "null" ] }, "cwd": { "type": [ "string", "null" ] }, "env": { "type": [ "object", "null" ], "additionalProperties": { "type": [ "string", "null" ], "writeOnly": true }, "propertyNames": { "type": "string", "writeOnly": true }, "example": { "TOKEN": "fake-probe-token" } }, "env_headers": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "env_vars": { "type": [ "array", "null" ], "items": { "type": "string" } }, "execution_timeout_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "header_helper": { "oneOf": [ { "$ref": "#/components/schemas/UpdateMcpHeaderHelperRequest" }, { "type": "null" } ] }, "headers": { "type": [ "object", "null" ], "additionalProperties": { "type": [ "string", "null" ], "writeOnly": true }, "propertyNames": { "type": "string", "writeOnly": true }, "example": { "Authorization": "Bearer fake-probe-token" } }, "name": { "type": [ "string", "null" ] }, "protocol": { "oneOf": [ { "$ref": "#/components/schemas/McpProtocolSelection" }, { "type": "null" } ] }, "startup_timeout_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "stored_name": { "type": [ "string", "null" ] }, "transport": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } }, "TestMcpServerResponse": { "type": "object", "required": [ "connected", "auth_required", "tools" ], "properties": { "auth_required": { "type": "boolean" }, "connected": { "type": "boolean" }, "error": { "type": [ "string", "null" ] }, "probe": { "oneOf": [ { "$ref": "#/components/schemas/McpProbeResult" }, { "type": "null" } ] }, "tools": { "type": "array", "items": { "$ref": "#/components/schemas/McpProbedTool" } } } }, "ThreadEventDecodeDiagnostic": { "type": "object", "required": [ "id", "thread_name", "created_at", "error" ], "properties": { "created_at": { "type": "string" }, "error": { "type": "string" }, "id": { "type": "integer", "format": "int64" }, "thread_name": { "type": "string" } } }, "ThreadEventPage": { "type": "object", "required": [ "events", "has_older" ], "properties": { "diagnostics": { "type": "array", "items": { "$ref": "#/components/schemas/ThreadEventDecodeDiagnostic" } }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/ThreadEventPageItem" } }, "has_older": { "type": "boolean" }, "next_before_id": { "type": [ "integer", "null" ], "format": "int64" }, "thread_event_boundary": { "oneOf": [ { "$ref": "#/components/schemas/SessionEventBoundary" }, { "type": "null" } ] } } }, "ThreadEventPageItem": { "type": "object", "required": [ "id", "created_at", "event" ], "properties": { "created_at": { "type": "string" }, "event": { "$ref": "#/components/schemas/AgentEvent" }, "id": { "type": "integer", "format": "int64" } } }, "ThreadSnapshot": { "type": "object", "required": [ "name", "session_id", "created_at", "updated_at", "episode_count", "latest_action" ], "properties": { "created_at": { "type": "string" }, "episode_count": { "type": "integer", "format": "int64" }, "latest_action": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "session_id": { "type": "string" }, "updated_at": { "type": "string" } } }, "ThreadSteeringRecord": { "type": "object", "required": [ "id", "session_id", "thread_name", "dispatch_id", "instruction", "status", "created_at" ], "properties": { "claimed_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "delivered_at": { "type": [ "string", "null" ] }, "dispatch_id": { "type": "string" }, "expired_at": { "type": [ "string", "null" ] }, "id": { "type": "integer", "format": "int64" }, "instruction": { "type": "string" }, "session_id": { "type": "string" }, "status": { "type": "string" }, "thread_name": { "type": "string" } } }, "ThreadSteeringRequest": { "type": "object", "required": [ "instruction" ], "properties": { "instruction": { "type": "string" } } }, "ThreadSteeringResponse": { "type": "object", "required": [ "steering_id", "thread_name", "status", "instruction_preview" ], "properties": { "instruction_preview": { "type": "string" }, "status": { "type": "string" }, "steering_id": { "type": "integer", "format": "int64" }, "thread_name": { "type": "string" } } }, "TokenCostMicros": { "type": "object", "description": "Per-response cost in micro-USD (1e-6 USD), stored as u64 so `TokenUsage`\nstays `Eq`. All-zero = unknown pricing (pi's zero-cost fallback). `total`\nis the saturating sum of the four buckets, stored so consumers read it\ndirectly. Missing fields deserialize as zero so partial records stay\nloadable.", "properties": { "cache_read": { "type": "integer", "format": "int64", "minimum": 0 }, "cache_write": { "type": "integer", "format": "int64", "minimum": 0 }, "input": { "type": "integer", "format": "int64", "minimum": 0 }, "output": { "type": "integer", "format": "int64", "minimum": 0 }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "TokenUsage": { "type": "object", "required": [ "input_tokens", "output_tokens", "cache_read_tokens", "cache_write_tokens", "total_tokens" ], "properties": { "cache_read_tokens": { "type": "integer", "format": "int64", "minimum": 0 }, "cache_write_tokens": { "type": "integer", "format": "int64", "minimum": 0 }, "cost": { "$ref": "#/components/schemas/TokenCostMicros", "description": "Per-response cost computed from catalog rates when the response was\nparsed; zero when pricing is unknown. Serde-additive: rows persisted\nbefore S3 deserialize with zero cost." }, "input_tokens": { "type": "integer", "format": "int64", "minimum": 0 }, "output_tokens": { "type": "integer", "format": "int64", "description": "Inclusive of `reasoning_tokens` — parsers normalize to the OpenAI\nconvention, and cost billing relies on it (reasoning bills at the\noutput rate via `max(output_tokens, reasoning_tokens)`).", "minimum": 0 }, "reasoning_tokens": { "type": "integer", "format": "int64", "minimum": 0 }, "total_tokens": { "type": "integer", "format": "int64", "description": "Current context window size from the last ordinary orchestrator call.", "minimum": 0 } } }, "ToolCall": { "type": "object", "required": [ "id", "type", "function" ], "properties": { "function": { "$ref": "#/components/schemas/FunctionCall" }, "id": { "type": "string" }, "type": { "type": "string" } } }, "ToolCallContentResponse": { "type": "object", "description": "Full content of one main-session tool call. Each field is redacted before\nit is bounded; a `*_truncated` flag marks a field that was cut.", "required": [ "call_id", "arguments", "arguments_truncated", "output", "output_truncated" ], "properties": { "arguments": { "type": "string" }, "arguments_truncated": { "type": "boolean" }, "call_id": { "type": "string" }, "output": { "type": [ "string", "null" ], "description": "Null while the call has no recorded result." }, "output_truncated": { "type": "boolean" } } }, "ToolCompletionStatus": { "type": "string", "enum": [ "success", "error", "timed_out", "cancelled" ] }, "ToolContentPartSchema": { "oneOf": [ { "type": "object", "required": [ "text", "type" ], "properties": { "text": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] } } }, { "type": "object", "required": [ "image", "type" ], "properties": { "image": { "$ref": "#/components/schemas/ToolImageSchema" }, "type": { "type": "string", "enum": [ "image" ] } } } ] }, "ToolContentSchema": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "$ref": "#/components/schemas/ToolContentPartSchema" } } ] }, "ToolImageSchema": { "type": "object", "required": [ "mime_type", "data" ], "properties": { "data": { "type": "string" }, "mime_type": { "type": "string" } } }, "TraditionalChildExecutionMode": { "type": "string", "enum": [ "foreground", "background" ] }, "TraditionalChildRecord": { "type": "object", "required": [ "child_session_id", "parent_session_id", "root_session_id", "profile", "description", "nesting_depth", "status", "generation", "run_id", "execution_mode", "report", "failure", "change_summary", "verification_summary", "completion_inbox_id", "created_at", "updated_at", "version" ], "properties": { "change_summary": { "type": [ "string", "null" ] }, "child_session_id": { "type": "string" }, "completion_inbox_id": { "type": [ "integer", "null" ], "format": "int64" }, "created_at": { "type": "string" }, "description": { "type": "string" }, "execution_mode": { "oneOf": [ { "$ref": "#/components/schemas/TraditionalChildExecutionMode" }, { "type": "null" } ] }, "failure": { "type": [ "string", "null" ] }, "generation": { "type": "integer", "format": "int64", "minimum": 0 }, "nesting_depth": { "type": "integer", "format": "int64", "minimum": 0 }, "parent_session_id": { "type": "string" }, "profile": { "type": "string" }, "report": { "type": [ "string", "null" ] }, "root_session_id": { "type": "string" }, "run_id": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/TraditionalChildStatus" }, "updated_at": { "type": "string" }, "verification_summary": { "type": [ "string", "null" ] }, "version": { "type": "integer", "format": "int64" } } }, "TraditionalChildStatus": { "type": "string", "enum": [ "idle", "running", "completed", "failed", "cancelled", "interrupted" ] }, "TransferTerminalControlRequest": { "type": "object", "required": [ "protocol_version", "expected_revision", "controller", "acknowledge_uncertainty" ], "properties": { "acknowledge_uncertainty": { "type": "boolean" }, "controller": { "$ref": "#/components/schemas/InputController" }, "expected_revision": { "type": "string" }, "protocol_version": { "type": "integer", "format": "int32", "minimum": 0 } }, "additionalProperties": false }, "UiConfiguration": { "type": "object", "required": [ "orchestration_enabled" ], "properties": { "diagnostic": { "type": [ "string", "null" ] }, "orchestration_enabled": { "type": "boolean" } } }, "UpdateConfigRequest": { "type": "object", "properties": { "allow_insecure_http": { "$ref": "#/components/schemas/RequestField_bool_bool", "description": "Omitted preserves the session value; null disables the opt-in." }, "api_key_env": { "$ref": "#/components/schemas/RequestField_String_String" }, "backend": { "$ref": "#/components/schemas/RequestField_String_String" }, "base_url": { "$ref": "#/components/schemas/RequestField_String_String" }, "extra_headers": { "$ref": "#/components/schemas/RequestField_HeadersRequest_HeadersRequest", "description": "Prefer a JSON object. Null or an empty object clears the persisted map." }, "light_model": { "$ref": "#/components/schemas/RequestField_LightModelSettings_LightModelSettings", "description": "Omitted preserves; null returns the session to single-model mode." }, "model": { "$ref": "#/components/schemas/RequestField_String_String" }, "orchestrator_compaction_threshold": { "$ref": "#/components/schemas/RequestField_u64_u64", "description": "Omitted preserves; null or zero disables." }, "reasoning_effort": { "$ref": "#/components/schemas/RequestField_String_String" } } }, "UpdateGitIdentityRequest": { "type": "object", "required": [ "name", "email" ], "properties": { "email": { "type": "string" }, "name": { "type": "string" } } }, "UpdateGoalRequest": { "type": "object", "required": [ "expected_version" ], "properties": { "expected_version": { "type": "integer", "format": "int64" }, "objective": { "type": [ "string", "null" ] }, "status": { "oneOf": [ { "$ref": "#/components/schemas/GoalStatus" }, { "type": "null" } ] }, "token_budget": { "$ref": "#/components/schemas/RequestField_u64_u64" } } }, "UpdateInboxItemRequest": { "type": "object", "required": [ "expected_version", "delivery" ], "properties": { "delivery": { "$ref": "#/components/schemas/InboxDelivery" }, "expected_version": { "type": "integer", "format": "int64" } } }, "UpdateMcpHeaderHelperRequest": { "type": "object", "required": [ "command" ], "properties": { "args": { "type": "array", "items": { "type": "string" } }, "command": { "type": "string" }, "cwd": { "type": [ "string", "null" ] }, "env": { "type": "object", "additionalProperties": { "type": [ "string", "null" ], "writeOnly": true }, "propertyNames": { "type": "string", "writeOnly": true } }, "env_vars": { "type": "array", "items": { "type": "string" } }, "timeout_ms": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } }, "UpdateMcpServerRequest": { "type": "object", "description": "Edits a stored server in place. Every field is tri-state: omit it to keep\nwhat is stored, send null to clear it, send a value to replace it.\n\n`env` and `headers` replace the whole map when sent, except that a null\nvalue under a key keeps the stored value for that key — the stored value\nis never echoed back, so this is how an untouched secret survives an edit.", "properties": { "allowed_tools": { "$ref": "#/components/schemas/RequestField_Vec_Vec_String" }, "approval": { "$ref": "#/components/schemas/RequestField_McpToolApproval_McpToolApproval" }, "args": { "$ref": "#/components/schemas/RequestField_Vec_Vec_String" }, "bearer_token_env_var": { "$ref": "#/components/schemas/RequestField_String_String" }, "catalog_timeout_ms": { "$ref": "#/components/schemas/RequestField_u64_u64" }, "command": { "$ref": "#/components/schemas/RequestField_String_String" }, "cwd": { "$ref": "#/components/schemas/RequestField_String_String" }, "denied_tools": { "$ref": "#/components/schemas/RequestField_Vec_Vec_String" }, "enabled": { "$ref": "#/components/schemas/RequestField_bool_bool" }, "env": { "$ref": "#/components/schemas/RequestField_BTreeMap_BTreeMap_String_Option_String", "writeOnly": true }, "env_headers": { "$ref": "#/components/schemas/RequestField_BTreeMap_BTreeMap_String_String" }, "env_vars": { "$ref": "#/components/schemas/RequestField_Vec_Vec_String" }, "execution_timeout_ms": { "$ref": "#/components/schemas/RequestField_u64_u64" }, "header_helper": { "$ref": "#/components/schemas/RequestField_UpdateMcpHeaderHelperRequest_UpdateMcpHeaderHelperRequest" }, "headers": { "$ref": "#/components/schemas/RequestField_BTreeMap_BTreeMap_String_Option_String", "writeOnly": true }, "library_id": { "$ref": "#/components/schemas/RequestField_String_String" }, "name": { "$ref": "#/components/schemas/RequestField_String_String" }, "protocol": { "$ref": "#/components/schemas/RequestField_McpProtocolSelection_McpProtocolSelection" }, "required": { "$ref": "#/components/schemas/RequestField_bool_bool" }, "startup_timeout_ms": { "$ref": "#/components/schemas/RequestField_u64_u64" }, "tool_approvals": { "$ref": "#/components/schemas/RequestField_BTreeMap_BTreeMap_String_McpToolApproval" }, "transport": { "$ref": "#/components/schemas/RequestField_String_String" }, "url": { "$ref": "#/components/schemas/RequestField_String_String" } } }, "UpdateModelConfigurationRequest": { "type": "object", "properties": { "allow_insecure_http": { "$ref": "#/components/schemas/RequestField_bool_bool" }, "api_key": { "$ref": "#/components/schemas/RequestField_String_String", "writeOnly": true }, "backend": { "$ref": "#/components/schemas/RequestField_BackendKind_BackendKind" }, "base_url": { "$ref": "#/components/schemas/RequestField_String_String" }, "extra_headers": { "$ref": "#/components/schemas/RequestField_BTreeMap_BTreeMap_String_String" }, "initial_prompt": { "$ref": "#/components/schemas/RequestField_String_String" }, "light_model": { "$ref": "#/components/schemas/RequestField_LightModelSettings_LightModelSettings" }, "model": { "$ref": "#/components/schemas/RequestField_String_String" }, "name": { "$ref": "#/components/schemas/RequestField_String_String" }, "orchestrator_compaction_threshold": { "$ref": "#/components/schemas/RequestField_u64_u64" }, "reasoning_effort": { "$ref": "#/components/schemas/RequestField_ReasoningEffort_ReasoningEffort" } } }, "UpdatePermissionApprovalModeRequest": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "$ref": "#/components/schemas/PermissionApprovalMode" } } }, "UpdateProjectRequest": { "type": "object", "properties": { "default_model_config_id": { "$ref": "#/components/schemas/RequestField_String_String" }, "description": { "$ref": "#/components/schemas/RequestField_String_String" }, "name": { "$ref": "#/components/schemas/RequestField_String_String" }, "pinned": { "$ref": "#/components/schemas/RequestField_bool_bool", "description": "Toggling this moves the project to the end of the target pin group and\nbumps `presentation_version`." } } }, "UpdateSessionPresentationRequest": { "type": "object", "required": [ "title", "pinned", "expected_version" ], "properties": { "expected_version": { "type": "integer", "format": "int64" }, "pinned": { "type": "boolean" }, "title": { "type": "string" } } }, "UpdateSshConfigurationRequest": { "type": "object", "description": "Edits a saved SSH setup in place. Every field is tri-state: omit it to keep\nwhat is stored, send null to clear it, send a value to replace it.", "properties": { "name": { "$ref": "#/components/schemas/RequestField_String_String" }, "ssh_host": { "$ref": "#/components/schemas/RequestField_String_String" }, "ssh_identity_file": { "$ref": "#/components/schemas/RequestField_String_String" }, "ssh_port": { "$ref": "#/components/schemas/RequestField_u16_u16" } } }, "UserTerminalFrameResponse": { "type": "object", "required": [ "protocol_version", "observer_id", "terminal", "bytes", "offset", "next_offset", "retained_start", "retained_end", "gap", "caught_up", "requires_ack" ], "properties": { "bytes": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "Sanitized bytes, with no UTF-8 or key-name conversion at delivery." }, "caught_up": { "type": "boolean" }, "gap": { "type": "boolean" }, "next_offset": { "type": "string" }, "observer_id": { "type": "string" }, "offset": { "type": "string", "description": "Decimal strings preserve exact u64 cursors in JavaScript consumers." }, "protocol_version": { "type": "integer", "format": "int32", "minimum": 0 }, "requires_ack": { "type": "boolean" }, "retained_end": { "type": "string" }, "retained_start": { "type": "string" }, "terminal": { "$ref": "#/components/schemas/UserTerminalResponse" } } }, "UserTerminalInputRequest": { "type": "object", "required": [ "protocol_version", "bytes" ], "properties": { "bytes": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } }, "protocol_version": { "type": "integer", "format": "int32", "minimum": 0 } }, "additionalProperties": false }, "UserTerminalListResponse": { "type": "object", "required": [ "protocol_version", "terminals" ], "properties": { "protocol_version": { "type": "integer", "format": "int32", "minimum": 0 }, "terminals": { "type": "array", "items": { "$ref": "#/components/schemas/UserTerminalResponse" } } } }, "UserTerminalObserverResponse": { "type": "object", "required": [ "protocol_version", "observer_id", "idle_expiry_ms", "terminal" ], "properties": { "idle_expiry_ms": { "type": "integer", "format": "int32", "minimum": 0 }, "observer_id": { "type": "string" }, "protocol_version": { "type": "integer", "format": "int32", "minimum": 0 }, "terminal": { "$ref": "#/components/schemas/UserTerminalResponse" } } }, "UserTerminalResponse": { "type": "object", "required": [ "protocol_version", "terminal_id", "cols", "rows", "alive", "output_complete" ], "properties": { "alive": { "type": "boolean" }, "cols": { "type": "integer", "format": "int32", "minimum": 0 }, "exit_code": { "type": [ "integer", "null" ], "format": "int32" }, "output_complete": { "type": "boolean" }, "output_error": { "type": [ "string", "null" ] }, "protocol_version": { "type": "integer", "format": "int32", "minimum": 0 }, "rows": { "type": "integer", "format": "int32", "minimum": 0 }, "terminal_id": { "type": "string" } } }, "WorksetItemSnapshot": { "type": "object", "required": [ "position", "title", "scope", "description", "role", "depends_on", "acceptance", "updated_at" ], "properties": { "acceptance": { "type": "string" }, "depends_on": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "position": { "type": "integer", "format": "int64" }, "role": { "type": "string" }, "scope": { "type": "string" }, "title": { "type": "string" }, "updated_at": { "type": "string" } } }, "WorksetSnapshot": { "type": "object", "required": [ "id", "session_id", "goal", "status", "summary", "created_at", "updated_at", "items" ], "properties": { "created_at": { "type": "string" }, "goal": { "type": "string" }, "id": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/WorksetItemSnapshot" } }, "session_id": { "type": "string" }, "status": { "type": "string" }, "summary": { "type": "string" }, "updated_at": { "type": "string" }, "verification_recipe": { "type": [ "string", "null" ] } } }, "WorksetsSnapshot": { "type": "object", "required": [ "items" ], "properties": { "error": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/WorksetSnapshot" } } } }, "WorkspaceDiffHunk": { "type": "object", "required": [ "old_start", "old_lines", "new_start", "new_lines", "function_context", "lines" ], "properties": { "function_context": { "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceDiffLine" } }, "new_lines": { "type": "integer", "minimum": 0 }, "new_start": { "type": "integer", "minimum": 0 }, "old_lines": { "type": "integer", "minimum": 0 }, "old_start": { "type": "integer", "minimum": 0 } } }, "WorkspaceDiffLine": { "type": "object", "required": [ "kind", "old_lineno", "new_lineno", "content", "has_trailing_newline" ], "properties": { "content": { "type": "string" }, "has_trailing_newline": { "type": "boolean" }, "kind": { "type": "string" }, "new_lineno": { "type": [ "integer", "null" ], "minimum": 0 }, "old_lineno": { "type": [ "integer", "null" ], "minimum": 0 } } }, "WorkspaceDiffSection": { "type": "object", "required": [ "stage", "status", "binary", "too_large", "truncated", "additions", "deletions", "hunks", "error" ], "properties": { "additions": { "type": "integer", "format": "int64", "minimum": 0 }, "binary": { "type": "boolean" }, "deletions": { "type": "integer", "format": "int64", "minimum": 0 }, "error": { "type": [ "string", "null" ] }, "hunks": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceDiffHunk" } }, "stage": { "type": "string" }, "status": { "type": "string" }, "too_large": { "type": "boolean" }, "truncated": { "type": "boolean" } } }, "WorkspaceDiffTotals": { "type": "object", "required": [ "total_additions", "total_deletions" ], "properties": { "error": { "type": [ "string", "null" ] }, "total_additions": { "type": "integer", "format": "int64", "minimum": 0 }, "total_deletions": { "type": "integer", "format": "int64", "minimum": 0 } } }, "WorkspaceFileContent": { "type": "object", "required": [ "path", "size", "binary", "too_large" ], "properties": { "binary": { "type": "boolean" }, "content": { "type": [ "string", "null" ], "description": "None whenever the file cannot be shown as text." }, "path": { "type": "string" }, "size": { "type": "integer", "format": "int64", "minimum": 0 }, "too_large": { "type": "boolean" } } }, "WorkspaceFileDiff": { "type": "object", "required": [ "path", "old_path", "sections", "error" ], "properties": { "error": { "type": [ "string", "null" ] }, "old_path": { "type": [ "string", "null" ] }, "path": { "type": "string" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceDiffSection" } } } }, "WorkspaceFileList": { "type": "object", "required": [ "files", "truncated" ], "properties": { "files": { "type": "array", "items": { "type": "string" } }, "path_root": { "type": [ "string", "null" ], "description": "Origin of these repository-relative identities, when locally available.\nA missing legacy/remote/revision context cannot authorize Finder reveal." }, "truncated": { "type": "boolean", "description": "The repository has more files than were returned." } } }, "WorkspaceRevisionChanges": { "type": "object", "required": [ "changed_files", "total_additions", "total_deletions" ], "properties": { "changed_files": { "type": "array", "items": { "$ref": "#/components/schemas/ChangedFileStat" } }, "error": { "type": [ "string", "null" ] }, "total_additions": { "type": "integer", "format": "int64", "minimum": 0 }, "total_deletions": { "type": "integer", "format": "int64", "minimum": 0 } } }, "WorkspaceRevisionRecord": { "type": "object", "description": "One captured state of a session's checkout.\n\nThe heavy part of a revision — the files — lives in the repository as a git\ncommit; this row is only the bookkeeping that tells us which commit belongs\nto which run, and what it should be compared against.", "required": [ "id", "session_id", "run_id", "commit_sha", "base_sha", "branch", "label", "additions", "deletions", "changed_files", "created_at", "transcript_len" ], "properties": { "additions": { "type": "integer", "format": "int64", "minimum": 0 }, "base_sha": { "type": [ "string", "null" ], "description": "The commit this revision is shown as a change against." }, "branch": { "type": [ "string", "null" ] }, "changed_files": { "type": "integer", "format": "int64", "minimum": 0 }, "commit_sha": { "type": "string" }, "created_at": { "type": "string" }, "deletions": { "type": "integer", "format": "int64", "minimum": 0 }, "id": { "type": "integer", "format": "int64" }, "label": { "type": "string", "description": "Prompt that started the run, for telling revisions apart in a list." }, "run_id": { "type": "string" }, "session_id": { "type": "string" }, "transcript_len": { "type": [ "integer", "null" ], "format": "int64", "description": "How many transcript messages the session had when this revision was\ntaken — the link that lets a revert ask \"what did the checkout look\nlike at this point in the conversation\". `None` on rows written before\nthe column existed.", "minimum": 0 } } }, "WorkspaceSnapshot": { "type": "object", "required": [ "workspace_display", "changed_files", "total_additions", "total_deletions" ], "properties": { "branch": { "type": [ "string", "null" ] }, "changed_files": { "type": "array", "items": { "$ref": "#/components/schemas/ChangedFileStat" } }, "error": { "type": [ "string", "null" ] }, "file_path_prefix": { "type": [ "string", "null" ], "description": "Session-directory prefix for repository-relative Files paths. Empty at\nthe repository root; unavailable when the Git location is unknown." }, "host_root": { "type": [ "string", "null" ] }, "repo_label": { "type": [ "string", "null" ] }, "total_additions": { "type": "integer", "format": "int64", "minimum": 0 }, "total_deletions": { "type": "integer", "format": "int64", "minimum": 0 }, "workspace_display": { "type": "string" } } } } } }