core-agent-ide/codex-rs/app-server-protocol/schema/json/ServerRequest.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "ApplyPatchApprovalParams": {
      "properties": {
        "callId": {
          "description": "Use to correlate this with [codex_protocol::protocol::PatchApplyBeginEvent] and [codex_protocol::protocol::PatchApplyEndEvent].",
          "type": "string"
        },
        "conversationId": {
          "$ref": "#/definitions/ThreadId"
        },
        "fileChanges": {
          "additionalProperties": {
            "$ref": "#/definitions/FileChange"
          },
          "type": "object"
        },
        "grantRoot": {
          "description": "When set, the agent is asking the user to allow writes under this root for the remainder of the session (unclear if this is honored today).",
          "type": [
            "string",
            "null"
          ]
        },
        "reason": {
          "description": "Optional explanatory reason (e.g. request for extra write access).",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "callId",
        "conversationId",
        "fileChanges"
      ],
      "type": "object"
    },
    "ChatgptAuthTokensRefreshParams": {
      "properties": {
        "previousAccountId": {
          "description": "Workspace/account identifier that Codex was previously using.\n\nClients that manage multiple accounts/workspaces can use this as a hint to refresh the token for the correct workspace.\n\nThis may be `null` when the prior auth state did not include a workspace identifier (`chatgpt_account_id`).",
          "type": [
            "string",
            "null"
          ]
        },
        "reason": {
          "$ref": "#/definitions/ChatgptAuthTokensRefreshReason"
        }
      },
      "required": [
        "reason"
      ],
      "type": "object"
    },
    "ChatgptAuthTokensRefreshReason": {
      "oneOf": [
        {
          "description": "Codex attempted a backend request and received `401 Unauthorized`.",
          "enum": [
            "unauthorized"
          ],
          "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"
        }
      ]
    },
    "CommandExecutionRequestApprovalParams": {
      "properties": {
        "approvalId": {
          "description": "Unique identifier for this specific approval callback.\n\nFor regular shell/unified_exec approvals, this is null.\n\nFor zsh-exec-bridge subcommand approvals, multiple callbacks can belong to one parent `itemId`, so `approvalId` is a distinct opaque callback id (a UUID) used to disambiguate routing.",
          "type": [
            "string",
            "null"
          ]
        },
        "command": {
          "description": "The command to be executed.",
          "type": [
            "string",
            "null"
          ]
        },
        "commandActions": {
          "description": "Best-effort parsed command actions for friendly display.",
          "items": {
            "$ref": "#/definitions/CommandAction"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "cwd": {
          "description": "The command's working directory.",
          "type": [
            "string",
            "null"
          ]
        },
        "itemId": {
          "type": "string"
        },
        "networkApprovalContext": {
          "anyOf": [
            {
              "$ref": "#/definitions/NetworkApprovalContext"
            },
            {
              "type": "null"
            }
          ],
          "description": "Optional context for managed-network approval prompts."
        },
        "proposedExecpolicyAmendment": {
          "description": "Optional proposed execpolicy amendment to allow similar commands without prompting.",
          "items": {
            "type": "string"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "reason": {
          "description": "Optional explanatory reason (e.g. request for network access).",
          "type": [
            "string",
            "null"
          ]
        },
        "threadId": {
          "type": "string"
        },
        "turnId": {
          "type": "string"
        }
      },
      "required": [
        "itemId",
        "threadId",
        "turnId"
      ],
      "type": "object"
    },
    "DynamicToolCallParams": {
      "properties": {
        "arguments": true,
        "callId": {
          "type": "string"
        },
        "threadId": {
          "type": "string"
        },
        "tool": {
          "type": "string"
        },
        "turnId": {
          "type": "string"
        }
      },
      "required": [
        "arguments",
        "callId",
        "threadId",
        "tool",
        "turnId"
      ],
      "type": "object"
    },
    "ExecCommandApprovalParams": {
      "properties": {
        "approvalId": {
          "description": "Identifier for this specific approval callback.",
          "type": [
            "string",
            "null"
          ]
        },
        "callId": {
          "description": "Use to correlate this with [codex_protocol::protocol::ExecCommandBeginEvent] and [codex_protocol::protocol::ExecCommandEndEvent].",
          "type": "string"
        },
        "command": {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "conversationId": {
          "$ref": "#/definitions/ThreadId"
        },
        "cwd": {
          "type": "string"
        },
        "parsedCmd": {
          "items": {
            "$ref": "#/definitions/ParsedCommand"
          },
          "type": "array"
        },
        "reason": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "callId",
        "command",
        "conversationId",
        "cwd",
        "parsedCmd"
      ],
      "type": "object"
    },
    "FileChange": {
      "oneOf": [
        {
          "properties": {
            "content": {
              "type": "string"
            },
            "type": {
              "enum": [
                "add"
              ],
              "title": "AddFileChangeType",
              "type": "string"
            }
          },
          "required": [
            "content",
            "type"
          ],
          "title": "AddFileChange",
          "type": "object"
        },
        {
          "properties": {
            "content": {
              "type": "string"
            },
            "type": {
              "enum": [
                "delete"
              ],
              "title": "DeleteFileChangeType",
              "type": "string"
            }
          },
          "required": [
            "content",
            "type"
          ],
          "title": "DeleteFileChange",
          "type": "object"
        },
        {
          "properties": {
            "move_path": {
              "type": [
                "string",
                "null"
              ]
            },
            "type": {
              "enum": [
                "update"
              ],
              "title": "UpdateFileChangeType",
              "type": "string"
            },
            "unified_diff": {
              "type": "string"
            }
          },
          "required": [
            "type",
            "unified_diff"
          ],
          "title": "UpdateFileChange",
          "type": "object"
        }
      ]
    },
    "FileChangeRequestApprovalParams": {
      "properties": {
        "grantRoot": {
          "description": "[UNSTABLE] When set, the agent is asking the user to allow writes under this root for the remainder of the session (unclear if this is honored today).",
          "type": [
            "string",
            "null"
          ]
        },
        "itemId": {
          "type": "string"
        },
        "reason": {
          "description": "Optional explanatory reason (e.g. request for extra write access).",
          "type": [
            "string",
            "null"
          ]
        },
        "threadId": {
          "type": "string"
        },
        "turnId": {
          "type": "string"
        }
      },
      "required": [
        "itemId",
        "threadId",
        "turnId"
      ],
      "type": "object"
    },
    "NetworkApprovalContext": {
      "properties": {
        "host": {
          "type": "string"
        },
        "protocol": {
          "$ref": "#/definitions/NetworkApprovalProtocol"
        }
      },
      "required": [
        "host",
        "protocol"
      ],
      "type": "object"
    },
    "NetworkApprovalProtocol": {
      "enum": [
        "http",
        "https",
        "socks5Tcp",
        "socks5Udp"
      ],
      "type": "string"
    },
    "ParsedCommand": {
      "oneOf": [
        {
          "properties": {
            "cmd": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "path": {
              "description": "(Best effort) Path to the file being read by the command. When possible, this is an absolute path, though when relative, it should be resolved against the `cwd`` that will be used to run the command to derive the absolute path.",
              "type": "string"
            },
            "type": {
              "enum": [
                "read"
              ],
              "title": "ReadParsedCommandType",
              "type": "string"
            }
          },
          "required": [
            "cmd",
            "name",
            "path",
            "type"
          ],
          "title": "ReadParsedCommand",
          "type": "object"
        },
        {
          "properties": {
            "cmd": {
              "type": "string"
            },
            "path": {
              "type": [
                "string",
                "null"
              ]
            },
            "type": {
              "enum": [
                "list_files"
              ],
              "title": "ListFilesParsedCommandType",
              "type": "string"
            }
          },
          "required": [
            "cmd",
            "type"
          ],
          "title": "ListFilesParsedCommand",
          "type": "object"
        },
        {
          "properties": {
            "cmd": {
              "type": "string"
            },
            "path": {
              "type": [
                "string",
                "null"
              ]
            },
            "query": {
              "type": [
                "string",
                "null"
              ]
            },
            "type": {
              "enum": [
                "search"
              ],
              "title": "SearchParsedCommandType",
              "type": "string"
            }
          },
          "required": [
            "cmd",
            "type"
          ],
          "title": "SearchParsedCommand",
          "type": "object"
        },
        {
          "properties": {
            "cmd": {
              "type": "string"
            },
            "type": {
              "enum": [
                "unknown"
              ],
              "title": "UnknownParsedCommandType",
              "type": "string"
            }
          },
          "required": [
            "cmd",
            "type"
          ],
          "title": "UnknownParsedCommand",
          "type": "object"
        }
      ]
    },
    "RequestId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "format": "int64",
          "type": "integer"
        }
      ]
    },
    "ThreadId": {
      "type": "string"
    },
    "ToolRequestUserInputOption": {
      "description": "EXPERIMENTAL. Defines a single selectable option for request_user_input.",
      "properties": {
        "description": {
          "type": "string"
        },
        "label": {
          "type": "string"
        }
      },
      "required": [
        "description",
        "label"
      ],
      "type": "object"
    },
    "ToolRequestUserInputParams": {
      "description": "EXPERIMENTAL. Params sent with a request_user_input event.",
      "properties": {
        "itemId": {
          "type": "string"
        },
        "questions": {
          "items": {
            "$ref": "#/definitions/ToolRequestUserInputQuestion"
          },
          "type": "array"
        },
        "threadId": {
          "type": "string"
        },
        "turnId": {
          "type": "string"
        }
      },
      "required": [
        "itemId",
        "questions",
        "threadId",
        "turnId"
      ],
      "type": "object"
    },
    "ToolRequestUserInputQuestion": {
      "description": "EXPERIMENTAL. Represents one request_user_input question and its required options.",
      "properties": {
        "header": {
          "type": "string"
        },
        "id": {
          "type": "string"
        },
        "isOther": {
          "default": false,
          "type": "boolean"
        },
        "isSecret": {
          "default": false,
          "type": "boolean"
        },
        "options": {
          "items": {
            "$ref": "#/definitions/ToolRequestUserInputOption"
          },
          "type": [
            "array",
            "null"
          ]
        },
        "question": {
          "type": "string"
        }
      },
      "required": [
        "header",
        "id",
        "question"
      ],
      "type": "object"
    }
  },
  "description": "Request initiated from the server and sent to the client.",
  "oneOf": [
    {
      "description": "NEW APIs Sent when approval is requested for a specific command execution. This request is used for Turns started via turn/start.",
      "properties": {
        "id": {
          "$ref": "#/definitions/RequestId"
        },
        "method": {
          "enum": [
            "item/commandExecution/requestApproval"
          ],
          "title": "Item/commandExecution/requestApprovalRequestMethod",
          "type": "string"
        },
        "params": {
          "$ref": "#/definitions/CommandExecutionRequestApprovalParams"
        }
      },
      "required": [
        "id",
        "method",
        "params"
      ],
      "title": "Item/commandExecution/requestApprovalRequest",
      "type": "object"
    },
    {
      "description": "Sent when approval is requested for a specific file change. This request is used for Turns started via turn/start.",
      "properties": {
        "id": {
          "$ref": "#/definitions/RequestId"
        },
        "method": {
          "enum": [
            "item/fileChange/requestApproval"
          ],
          "title": "Item/fileChange/requestApprovalRequestMethod",
          "type": "string"
        },
        "params": {
          "$ref": "#/definitions/FileChangeRequestApprovalParams"
        }
      },
      "required": [
        "id",
        "method",
        "params"
      ],
      "title": "Item/fileChange/requestApprovalRequest",
      "type": "object"
    },
    {
      "description": "EXPERIMENTAL - Request input from the user for a tool call.",
      "properties": {
        "id": {
          "$ref": "#/definitions/RequestId"
        },
        "method": {
          "enum": [
            "item/tool/requestUserInput"
          ],
          "title": "Item/tool/requestUserInputRequestMethod",
          "type": "string"
        },
        "params": {
          "$ref": "#/definitions/ToolRequestUserInputParams"
        }
      },
      "required": [
        "id",
        "method",
        "params"
      ],
      "title": "Item/tool/requestUserInputRequest",
      "type": "object"
    },
    {
      "description": "Execute a dynamic tool call on the client.",
      "properties": {
        "id": {
          "$ref": "#/definitions/RequestId"
        },
        "method": {
          "enum": [
            "item/tool/call"
          ],
          "title": "Item/tool/callRequestMethod",
          "type": "string"
        },
        "params": {
          "$ref": "#/definitions/DynamicToolCallParams"
        }
      },
      "required": [
        "id",
        "method",
        "params"
      ],
      "title": "Item/tool/callRequest",
      "type": "object"
    },
    {
      "properties": {
        "id": {
          "$ref": "#/definitions/RequestId"
        },
        "method": {
          "enum": [
            "account/chatgptAuthTokens/refresh"
          ],
          "title": "Account/chatgptAuthTokens/refreshRequestMethod",
          "type": "string"
        },
        "params": {
          "$ref": "#/definitions/ChatgptAuthTokensRefreshParams"
        }
      },
      "required": [
        "id",
        "method",
        "params"
      ],
      "title": "Account/chatgptAuthTokens/refreshRequest",
      "type": "object"
    },
    {
      "description": "DEPRECATED APIs below Request to approve a patch. This request is used for Turns started via the legacy APIs (i.e. SendUserTurn, SendUserMessage).",
      "properties": {
        "id": {
          "$ref": "#/definitions/RequestId"
        },
        "method": {
          "enum": [
            "applyPatchApproval"
          ],
          "title": "ApplyPatchApprovalRequestMethod",
          "type": "string"
        },
        "params": {
          "$ref": "#/definitions/ApplyPatchApprovalParams"
        }
      },
      "required": [
        "id",
        "method",
        "params"
      ],
      "title": "ApplyPatchApprovalRequest",
      "type": "object"
    },
    {
      "description": "Request to exec a command. This request is used for Turns started via the legacy APIs (i.e. SendUserTurn, SendUserMessage).",
      "properties": {
        "id": {
          "$ref": "#/definitions/RequestId"
        },
        "method": {
          "enum": [
            "execCommandApproval"
          ],
          "title": "ExecCommandApprovalRequestMethod",
          "type": "string"
        },
        "params": {
          "$ref": "#/definitions/ExecCommandApprovalParams"
        }
      },
      "required": [
        "id",
        "method",
        "params"
      ],
      "title": "ExecCommandApprovalRequest",
      "type": "object"
    }
  ],
  "title": "ServerRequest"
}