{ "$schema": "http://json-schema.org/draft-07/schema#", "definitions": { "ByteRange": { "properties": { "end": { "format": "uint", "minimum": 0.0, "type": "integer" }, "start": { "format": "uint", "minimum": 0.0, "type": "integer" } }, "required": [ "end", "start" ], "type": "object" }, "CodexErrorInfo": { "description": "This translation layer make sure that we expose codex error code in camel case.\n\nWhen an upstream HTTP status is available (for example, from the Responses API or a provider), it is forwarded in `httpStatusCode` on the relevant `codexErrorInfo` variant.", "oneOf": [ { "enum": [ "contextWindowExceeded", "usageLimitExceeded", "internalServerError", "unauthorized", "badRequest", "threadRollbackFailed", "sandboxError", "other" ], "type": "string" }, { "additionalProperties": false, "properties": { "modelCap": { "properties": { "model": { "type": "string" }, "reset_after_seconds": { "format": "uint64", "minimum": 0.0, "type": [ "integer", "null" ] } }, "required": [ "model" ], "type": "object" } }, "required": [ "modelCap" ], "title": "ModelCapCodexErrorInfo", "type": "object" }, { "additionalProperties": false, "properties": { "httpConnectionFailed": { "properties": { "httpStatusCode": { "format": "uint16", "minimum": 0.0, "type": [ "integer", "null" ] } }, "type": "object" } }, "required": [ "httpConnectionFailed" ], "title": "HttpConnectionFailedCodexErrorInfo", "type": "object" }, { "additionalProperties": false, "description": "Failed to connect to the response SSE stream.", "properties": { "responseStreamConnectionFailed": { "properties": { "httpStatusCode": { "format": "uint16", "minimum": 0.0, "type": [ "integer", "null" ] } }, "type": "object" } }, "required": [ "responseStreamConnectionFailed" ], "title": "ResponseStreamConnectionFailedCodexErrorInfo", "type": "object" }, { "additionalProperties": false, "description": "The response SSE stream disconnected in the middle of a turn before completion.", "properties": { "responseStreamDisconnected": { "properties": { "httpStatusCode": { "format": "uint16", "minimum": 0.0, "type": [ "integer", "null" ] } }, "type": "object" } }, "required": [ "responseStreamDisconnected" ], "title": "ResponseStreamDisconnectedCodexErrorInfo", "type": "object" }, { "additionalProperties": false, "description": "Reached the retry limit for responses.", "properties": { "responseTooManyFailedAttempts": { "properties": { "httpStatusCode": { "format": "uint16", "minimum": 0.0, "type": [ "integer", "null" ] } }, "type": "object" } }, "required": [ "responseTooManyFailedAttempts" ], "title": "ResponseTooManyFailedAttemptsCodexErrorInfo", "type": "object" } ] }, "CollabAgentState": { "properties": { "message": { "type": [ "string", "null" ] }, "status": { "$ref": "#/definitions/CollabAgentStatus" } }, "required": [ "status" ], "type": "object" }, "CollabAgentStatus": { "enum": [ "pendingInit", "running", "completed", "errored", "shutdown", "notFound" ], "type": "string" }, "CollabAgentTool": { "enum": [ "spawnAgent", "sendInput", "wait", "closeAgent" ], "type": "string" }, "CollabAgentToolCallStatus": { "enum": [ "inProgress", "completed", "failed" ], "type": "string" }, "CommandAction": { "oneOf": [ { "properties": { "command": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string" }, "type": { "enum": [ "read" ], "title": "ReadCommandActionType", "type": "string" } }, "required": [ "command", "name", "path", "type" ], "title": "ReadCommandAction", "type": "object" }, { "properties": { "command": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "type": { "enum": [ "listFiles" ], "title": "ListFilesCommandActionType", "type": "string" } }, "required": [ "command", "type" ], "title": "ListFilesCommandAction", "type": "object" }, { "properties": { "command": { "type": "string" }, "path": { "type": [ "string", "null" ] }, "query": { "type": [ "string", "null" ] }, "type": { "enum": [ "search" ], "title": "SearchCommandActionType", "type": "string" } }, "required": [ "command", "type" ], "title": "SearchCommandAction", "type": "object" }, { "properties": { "command": { "type": "string" }, "type": { "enum": [ "unknown" ], "title": "UnknownCommandActionType", "type": "string" } }, "required": [ "command", "type" ], "title": "UnknownCommandAction", "type": "object" } ] }, "CommandExecutionStatus": { "enum": [ "inProgress", "completed", "failed", "declined" ], "type": "string" }, "FileUpdateChange": { "properties": { "diff": { "type": "string" }, "kind": { "$ref": "#/definitions/PatchChangeKind" }, "path": { "type": "string" } }, "required": [ "diff", "kind", "path" ], "type": "object" }, "GitInfo": { "properties": { "branch": { "type": [ "string", "null" ] }, "originUrl": { "type": [ "string", "null" ] }, "sha": { "type": [ "string", "null" ] } }, "type": "object" }, "McpToolCallError": { "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" }, "McpToolCallResult": { "properties": { "content": { "items": true, "type": "array" }, "structuredContent": true }, "required": [ "content" ], "type": "object" }, "McpToolCallStatus": { "enum": [ "inProgress", "completed", "failed" ], "type": "string" }, "PatchApplyStatus": { "enum": [ "inProgress", "completed", "failed", "declined" ], "type": "string" }, "PatchChangeKind": { "oneOf": [ { "properties": { "type": { "enum": [ "add" ], "title": "AddPatchChangeKindType", "type": "string" } }, "required": [ "type" ], "title": "AddPatchChangeKind", "type": "object" }, { "properties": { "type": { "enum": [ "delete" ], "title": "DeletePatchChangeKindType", "type": "string" } }, "required": [ "type" ], "title": "DeletePatchChangeKind", "type": "object" }, { "properties": { "move_path": { "type": [ "string", "null" ] }, "type": { "enum": [ "update" ], "title": "UpdatePatchChangeKindType", "type": "string" } }, "required": [ "type" ], "title": "UpdatePatchChangeKind", "type": "object" } ] }, "SessionSource": { "oneOf": [ { "enum": [ "cli", "vscode", "exec", "appServer", "unknown" ], "type": "string" }, { "additionalProperties": false, "properties": { "subAgent": { "$ref": "#/definitions/SubAgentSource" } }, "required": [ "subAgent" ], "title": "SubAgentSessionSource", "type": "object" } ] }, "SubAgentSource": { "oneOf": [ { "enum": [ "review", "compact" ], "type": "string" }, { "additionalProperties": false, "properties": { "thread_spawn": { "properties": { "depth": { "format": "int32", "type": "integer" }, "parent_thread_id": { "$ref": "#/definitions/ThreadId" } }, "required": [ "depth", "parent_thread_id" ], "type": "object" } }, "required": [ "thread_spawn" ], "title": "ThreadSpawnSubAgentSource", "type": "object" }, { "additionalProperties": false, "properties": { "other": { "type": "string" } }, "required": [ "other" ], "title": "OtherSubAgentSource", "type": "object" } ] }, "TextElement": { "properties": { "byteRange": { "allOf": [ { "$ref": "#/definitions/ByteRange" } ], "description": "Byte range in the parent `text` buffer that this element occupies." }, "placeholder": { "description": "Optional human-readable placeholder for the element, displayed in the UI.", "type": [ "string", "null" ] } }, "required": [ "byteRange" ], "type": "object" }, "Thread": { "properties": { "cliVersion": { "description": "Version of the CLI that created the thread.", "type": "string" }, "createdAt": { "description": "Unix timestamp (in seconds) when the thread was created.", "format": "int64", "type": "integer" }, "cwd": { "description": "Working directory captured for the thread.", "type": "string" }, "gitInfo": { "anyOf": [ { "$ref": "#/definitions/GitInfo" }, { "type": "null" } ], "description": "Optional Git metadata captured when the thread was created." }, "id": { "type": "string" }, "modelProvider": { "description": "Model provider used for this thread (for example, 'openai').", "type": "string" }, "path": { "description": "[UNSTABLE] Path to the thread on disk.", "type": [ "string", "null" ] }, "preview": { "description": "Usually the first user message in the thread, if available.", "type": "string" }, "source": { "allOf": [ { "$ref": "#/definitions/SessionSource" } ], "description": "Origin of the thread (CLI, VSCode, codex exec, codex app-server, etc.)." }, "turns": { "description": "Only populated on `thread/resume`, `thread/rollback`, `thread/fork`, and `thread/read` (when `includeTurns` is true) responses. For all other responses and notifications returning a Thread, the turns field will be an empty list.", "items": { "$ref": "#/definitions/Turn" }, "type": "array" }, "updatedAt": { "description": "Unix timestamp (in seconds) when the thread was last updated.", "format": "int64", "type": "integer" } }, "required": [ "cliVersion", "createdAt", "cwd", "id", "modelProvider", "preview", "source", "turns", "updatedAt" ], "type": "object" }, "ThreadId": { "type": "string" }, "ThreadItem": { "oneOf": [ { "properties": { "content": { "items": { "$ref": "#/definitions/UserInput" }, "type": "array" }, "id": { "type": "string" }, "type": { "enum": [ "userMessage" ], "title": "UserMessageThreadItemType", "type": "string" } }, "required": [ "content", "id", "type" ], "title": "UserMessageThreadItem", "type": "object" }, { "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "type": { "enum": [ "agentMessage" ], "title": "AgentMessageThreadItemType", "type": "string" } }, "required": [ "id", "text", "type" ], "title": "AgentMessageThreadItem", "type": "object" }, { "description": "EXPERIMENTAL - proposed plan item content. The completed plan item is authoritative and may not match the concatenation of `PlanDelta` text.", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "type": { "enum": [ "plan" ], "title": "PlanThreadItemType", "type": "string" } }, "required": [ "id", "text", "type" ], "title": "PlanThreadItem", "type": "object" }, { "properties": { "content": { "default": [], "items": { "type": "string" }, "type": "array" }, "id": { "type": "string" }, "summary": { "default": [], "items": { "type": "string" }, "type": "array" }, "type": { "enum": [ "reasoning" ], "title": "ReasoningThreadItemType", "type": "string" } }, "required": [ "id", "type" ], "title": "ReasoningThreadItem", "type": "object" }, { "properties": { "aggregatedOutput": { "description": "The command's output, aggregated from stdout and stderr.", "type": [ "string", "null" ] }, "command": { "description": "The command to be executed.", "type": "string" }, "commandActions": { "description": "A best-effort parsing of the command to understand the action(s) it will perform. This returns a list of CommandAction objects because a single shell command may be composed of many commands piped together.", "items": { "$ref": "#/definitions/CommandAction" }, "type": "array" }, "cwd": { "description": "The command's working directory.", "type": "string" }, "durationMs": { "description": "The duration of the command execution in milliseconds.", "format": "int64", "type": [ "integer", "null" ] }, "exitCode": { "description": "The command's exit code.", "format": "int32", "type": [ "integer", "null" ] }, "id": { "type": "string" }, "processId": { "description": "Identifier for the underlying PTY process (when available).", "type": [ "string", "null" ] }, "status": { "$ref": "#/definitions/CommandExecutionStatus" }, "type": { "enum": [ "commandExecution" ], "title": "CommandExecutionThreadItemType", "type": "string" } }, "required": [ "command", "commandActions", "cwd", "id", "status", "type" ], "title": "CommandExecutionThreadItem", "type": "object" }, { "properties": { "changes": { "items": { "$ref": "#/definitions/FileUpdateChange" }, "type": "array" }, "id": { "type": "string" }, "status": { "$ref": "#/definitions/PatchApplyStatus" }, "type": { "enum": [ "fileChange" ], "title": "FileChangeThreadItemType", "type": "string" } }, "required": [ "changes", "id", "status", "type" ], "title": "FileChangeThreadItem", "type": "object" }, { "properties": { "arguments": true, "durationMs": { "description": "The duration of the MCP tool call in milliseconds.", "format": "int64", "type": [ "integer", "null" ] }, "error": { "anyOf": [ { "$ref": "#/definitions/McpToolCallError" }, { "type": "null" } ] }, "id": { "type": "string" }, "result": { "anyOf": [ { "$ref": "#/definitions/McpToolCallResult" }, { "type": "null" } ] }, "server": { "type": "string" }, "status": { "$ref": "#/definitions/McpToolCallStatus" }, "tool": { "type": "string" }, "type": { "enum": [ "mcpToolCall" ], "title": "McpToolCallThreadItemType", "type": "string" } }, "required": [ "arguments", "id", "server", "status", "tool", "type" ], "title": "McpToolCallThreadItem", "type": "object" }, { "properties": { "agentsStates": { "additionalProperties": { "$ref": "#/definitions/CollabAgentState" }, "description": "Last known status of the target agents, when available.", "type": "object" }, "id": { "description": "Unique identifier for this collab tool call.", "type": "string" }, "prompt": { "description": "Prompt text sent as part of the collab tool call, when available.", "type": [ "string", "null" ] }, "receiverThreadIds": { "description": "Thread ID of the receiving agent, when applicable. In case of spawn operation, this corresponds to the newly spawned agent.", "items": { "type": "string" }, "type": "array" }, "senderThreadId": { "description": "Thread ID of the agent issuing the collab request.", "type": "string" }, "status": { "allOf": [ { "$ref": "#/definitions/CollabAgentToolCallStatus" } ], "description": "Current status of the collab tool call." }, "tool": { "allOf": [ { "$ref": "#/definitions/CollabAgentTool" } ], "description": "Name of the collab tool that was invoked." }, "type": { "enum": [ "collabAgentToolCall" ], "title": "CollabAgentToolCallThreadItemType", "type": "string" } }, "required": [ "agentsStates", "id", "receiverThreadIds", "senderThreadId", "status", "tool", "type" ], "title": "CollabAgentToolCallThreadItem", "type": "object" }, { "properties": { "action": { "anyOf": [ { "$ref": "#/definitions/WebSearchAction" }, { "type": "null" } ] }, "id": { "type": "string" }, "query": { "type": "string" }, "type": { "enum": [ "webSearch" ], "title": "WebSearchThreadItemType", "type": "string" } }, "required": [ "id", "query", "type" ], "title": "WebSearchThreadItem", "type": "object" }, { "properties": { "id": { "type": "string" }, "path": { "type": "string" }, "type": { "enum": [ "imageView" ], "title": "ImageViewThreadItemType", "type": "string" } }, "required": [ "id", "path", "type" ], "title": "ImageViewThreadItem", "type": "object" }, { "properties": { "id": { "type": "string" }, "review": { "type": "string" }, "type": { "enum": [ "enteredReviewMode" ], "title": "EnteredReviewModeThreadItemType", "type": "string" } }, "required": [ "id", "review", "type" ], "title": "EnteredReviewModeThreadItem", "type": "object" }, { "properties": { "id": { "type": "string" }, "review": { "type": "string" }, "type": { "enum": [ "exitedReviewMode" ], "title": "ExitedReviewModeThreadItemType", "type": "string" } }, "required": [ "id", "review", "type" ], "title": "ExitedReviewModeThreadItem", "type": "object" }, { "properties": { "id": { "type": "string" }, "type": { "enum": [ "contextCompaction" ], "title": "ContextCompactionThreadItemType", "type": "string" } }, "required": [ "id", "type" ], "title": "ContextCompactionThreadItem", "type": "object" } ] }, "Turn": { "properties": { "error": { "anyOf": [ { "$ref": "#/definitions/TurnError" }, { "type": "null" } ], "description": "Only populated when the Turn's status is failed." }, "id": { "type": "string" }, "items": { "description": "Only populated on a `thread/resume` or `thread/fork` response. For all other responses and notifications returning a Turn, the items field will be an empty list.", "items": { "$ref": "#/definitions/ThreadItem" }, "type": "array" }, "status": { "$ref": "#/definitions/TurnStatus" } }, "required": [ "id", "items", "status" ], "type": "object" }, "TurnError": { "properties": { "additionalDetails": { "default": null, "type": [ "string", "null" ] }, "codexErrorInfo": { "anyOf": [ { "$ref": "#/definitions/CodexErrorInfo" }, { "type": "null" } ] }, "message": { "type": "string" } }, "required": [ "message" ], "type": "object" }, "TurnStatus": { "enum": [ "completed", "interrupted", "failed", "inProgress" ], "type": "string" }, "UserInput": { "oneOf": [ { "properties": { "text": { "type": "string" }, "text_elements": { "default": [], "description": "UI-defined spans within `text` used to render or persist special elements.", "items": { "$ref": "#/definitions/TextElement" }, "type": "array" }, "type": { "enum": [ "text" ], "title": "TextUserInputType", "type": "string" } }, "required": [ "text", "type" ], "title": "TextUserInput", "type": "object" }, { "properties": { "type": { "enum": [ "image" ], "title": "ImageUserInputType", "type": "string" }, "url": { "type": "string" } }, "required": [ "type", "url" ], "title": "ImageUserInput", "type": "object" }, { "properties": { "path": { "type": "string" }, "type": { "enum": [ "localImage" ], "title": "LocalImageUserInputType", "type": "string" } }, "required": [ "path", "type" ], "title": "LocalImageUserInput", "type": "object" }, { "properties": { "name": { "type": "string" }, "path": { "type": "string" }, "type": { "enum": [ "skill" ], "title": "SkillUserInputType", "type": "string" } }, "required": [ "name", "path", "type" ], "title": "SkillUserInput", "type": "object" }, { "properties": { "name": { "type": "string" }, "path": { "type": "string" }, "type": { "enum": [ "mention" ], "title": "MentionUserInputType", "type": "string" } }, "required": [ "name", "path", "type" ], "title": "MentionUserInput", "type": "object" } ] }, "WebSearchAction": { "oneOf": [ { "properties": { "queries": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "query": { "type": [ "string", "null" ] }, "type": { "enum": [ "search" ], "title": "SearchWebSearchActionType", "type": "string" } }, "required": [ "type" ], "title": "SearchWebSearchAction", "type": "object" }, { "properties": { "type": { "enum": [ "openPage" ], "title": "OpenPageWebSearchActionType", "type": "string" }, "url": { "type": [ "string", "null" ] } }, "required": [ "type" ], "title": "OpenPageWebSearchAction", "type": "object" }, { "properties": { "pattern": { "type": [ "string", "null" ] }, "type": { "enum": [ "findInPage" ], "title": "FindInPageWebSearchActionType", "type": "string" }, "url": { "type": [ "string", "null" ] } }, "required": [ "type" ], "title": "FindInPageWebSearchAction", "type": "object" }, { "properties": { "type": { "enum": [ "other" ], "title": "OtherWebSearchActionType", "type": "string" } }, "required": [ "type" ], "title": "OtherWebSearchAction", "type": "object" } ] } }, "properties": { "thread": { "$ref": "#/definitions/Thread" } }, "required": [ "thread" ], "title": "ThreadStartedNotification", "type": "object" }