Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

250 KB
Raw Blame
{
  "openapi": "3.1.0",
  "info": {
    "title": "agent_harness_service",
    "description": "",
    "termsOfService": "https://macro.com/terms",
    "license": {
      "name": ""
    },
    "version": "0.1.0"
  },
  "paths": {
    "/agent-auto-archive-preferences": {
      "get": {
        "tags": ["agent-sessions"],
        "summary": "Read which triggers archive the caller's sessions by default.",
        "operationId": "get_agent_auto_archive_preferences",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutoArchivePreferencesBody"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": ["agent-sessions"],
        "summary": "Replace which triggers archive the caller's sessions by default.",
        "operationId": "put_agent_auto_archive_preferences",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AutoArchivePreferencesBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutoArchivePreferencesBody"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-capabilities/discover": {
      "post": {
        "tags": ["agent-capabilities"],
        "summary": "Probe one provider's ACP session configuration without persisting a session.",
        "operationId": "discover_agent_capabilities_handler",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DiscoverAgentCapabilitiesRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Fresh provider session capabilities",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DiscoverAgentCapabilitiesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid target"
          },
          "401": {
            "description": "Unauthenticated"
          },
          "403": {
            "description": "Harness is not visible to caller"
          },
          "409": {
            "description": "Macrod runtime or Cursor account is not connected"
          },
          "502": {
            "description": "Provider probe failed"
          },
          "504": {
            "description": "Macrod probe timed out"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/agent-coding-preferences": {
      "get": {
        "tags": ["agent-sessions"],
        "summary": "Read what the caller's new coding sessions are told to do beyond their assignment.",
        "operationId": "get_agent_coding_preferences",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CodingPreferencesBody"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": ["agent-sessions"],
        "summary": "Replace the caller's coding preferences.",
        "operationId": "put_agent_coding_preferences",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CodingPreferencesBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CodingPreferencesBody"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-conversations/{channel_id}": {
      "get": {
        "tags": ["agent-conversations"],
        "summary": "The agent conversations in a channel the caller may see. Ordinary channels\nand other people's conversations list none.",
        "operationId": "list_agent_conversations",
        "parameters": [
          {
            "name": "channel_id",
            "in": "path",
            "description": "Conversation channel",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The caller's agent conversations in the channel",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentConversationsDto"
                }
              }
            }
          },
          "503": {
            "description": "Conversations temporarily unavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/agent-conversations/{channel_id}/{bot_id}/start-fresh": {
      "post": {
        "tags": ["agent-conversations"],
        "summary": "Start a fresh agent context, retaining the channel transcript.",
        "operationId": "start_fresh_agent_conversation",
        "parameters": [
          {
            "name": "channel_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "bot_id",
            "in": "path",
            "description": "Persona the conversation is with",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StartFreshAgentConversationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "New context reserved"
          },
          "404": {
            "description": "Conversation not found"
          },
          "409": {
            "description": "Context is busy, stale or unavailable"
          },
          "503": {
            "description": "Temporarily unavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/agent-conversations/{channel_id}/{bot_id}/turns/{source}/retry": {
      "post": {
        "tags": ["agent-conversations"],
        "summary": "Explicitly retry a failed message in the conversation's current session.",
        "operationId": "retry_agent_conversation_turn",
        "parameters": [
          {
            "name": "channel_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "bot_id",
            "in": "path",
            "description": "Persona the conversation is with",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "source",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RetryAgentConversationTurnRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Retry queued"
          },
          "404": {
            "description": "Conversation or turn not found"
          },
          "409": {
            "description": "Attempt cannot be retried"
          },
          "503": {
            "description": "Temporarily unavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/agent-mode-choice": {
      "post": {
        "tags": ["agent-mode-choice"],
        "summary": "Choose whether a composer prompt goes to a chat or a coding agent.",
        "operationId": "choose_agent_mode",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentModeChoiceRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "The kind of agent the prompt goes to",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentModeChoiceResponse"
                }
              }
            }
          },
          "400": {
            "description": "The prompt is blank"
          },
          "401": {
            "description": "Unauthenticated"
          },
          "402": {
            "description": "The caller cannot start new AI work"
          },
          "403": {
            "description": "Auto mode is not enabled for the caller"
          },
          "503": {
            "description": "The classifier is unconfigured, failed, or timed out"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/agent-models/load": {
      "post": {
        "tags": ["agent-models"],
        "summary": "Probe one provider's model catalog without creating an agent session.",
        "operationId": "load_agent_models_handler",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoadAgentModelsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Fresh provider model catalog",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LoadAgentModelsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid target"
          },
          "401": {
            "description": "Unauthenticated"
          },
          "403": {
            "description": "Harness is not visible to caller"
          },
          "409": {
            "description": "Macrod runtime or Cursor account is not connected"
          },
          "502": {
            "description": "Provider probe failed"
          },
          "504": {
            "description": "Macrod probe timed out"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/agent-repositories": {
      "get": {
        "tags": ["agent-repositories"],
        "summary": "List the GitHub repositories the caller can select for a coding session.",
        "operationId": "list_agent_repositories",
        "responses": {
          "200": {
            "description": "The caller's reachable repositories",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentRepositoriesResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthenticated"
          },
          "502": {
            "description": "GitHub could not be asked which repositories the caller reaches"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/agent-repositories/branches": {
      "get": {
        "tags": ["agent-repositories"],
        "summary": "List the branches on one repository the caller can start a session from.",
        "operationId": "list_agent_repository_branches",
        "parameters": [
          {
            "name": "repoUrl",
            "in": "query",
            "description": "Canonical https://github.com/owner/name URL",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The repository's branches",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentRepositoryBranchesResponse"
                }
              }
            }
          },
          "400": {
            "description": "The query did not name a GitHub repository"
          },
          "401": {
            "description": "Unauthenticated"
          },
          "403": {
            "description": "The caller cannot reach this repository"
          },
          "502": {
            "description": "GitHub could not be asked which branches the repository has"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/agent-sandbox-size": {
      "get": {
        "tags": ["agent-sessions"],
        "summary": "Read the caller's default sandbox size for new `@coder` sessions.",
        "operationId": "get_agent_sandbox_size",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SandboxSizeBody"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": ["agent-sessions"],
        "summary": "Set the caller's default sandbox size for the next `@coder` mention.",
        "operationId": "put_agent_sandbox_size",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SandboxSizeBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SandboxSizeBody"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions": {
      "post": {
        "tags": ["agent-sessions"],
        "summary": "Open an agent session served by an external runtime.",
        "description": "Nothing here tells the runtime where to dial: one connection per bot\ncarries every session it runs, so a runtime that has already dialed serves\nthis session too, and one that has not dials the gateway its own\nconfiguration names. The triggering mention reaches the session as its\nfirst prompt through the control endpoint.",
        "operationId": "create_agent_session",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAgentSessionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateAgentSessionResponse"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "AI allowance exhausted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AiAdmissionErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "422": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "503": {
            "description": "AI usage validation unavailable; retry later",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AiAdmissionErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/by-pull-request": {
      "post": {
        "tags": ["agent-sessions"],
        "summary": "List the sessions associated with a pull request that the caller can view.",
        "operationId": "agent_sessions_for_pull_request",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PullRequestUrl"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PullRequestSessionsResponse"
                }
              }
            }
          },
          "400": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/by-pull-requests": {
      "post": {
        "tags": ["agent-sessions"],
        "summary": "List the sessions associated with each of up to 100 pull requests that the caller can view,\nwith the thread each session was started from.",
        "operationId": "agent_sessions_for_pull_requests",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PullRequestUrls"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PullRequestsSessionsResponse"
                }
              }
            }
          },
          "400": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/preview": {
      "post": {
        "tags": ["agent-sessions"],
        "summary": "Preview a batch of agent sessions for rendering chips.",
        "description": "No per-id access extractor: a chip has to render for a session the caller\ncannot open, so access is answered per id in the body rather than\nenforced on the request. The caller learns the fields a chip shows for\nsessions they may view, and only existence for the rest.",
        "operationId": "preview_agent_sessions",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PreviewAgentSessionsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PreviewAgentSessionsResponse"
                }
              }
            }
          },
          "400": {
            "description": "more than the maximum number of session ids",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/warm": {
      "post": {
        "tags": ["agent-sessions"],
        "summary": "Prepare MCP connections without sending a prompt or creating a visible list row.",
        "operationId": "warm_agent_session_handler",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WarmAgentSessionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WarmAgentSessionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/{session_id}": {
      "get": {
        "tags": ["agent-sessions"],
        "summary": "Get an agent session by id.",
        "description": "A caller holding no grant is answered 401; an id with no session behind it\nat all is answered 404. They used to be the same answer, which left a\nclient that read a session before its create had landed unable to tell a\nrace it should retry from a refusal it should not.",
        "operationId": "get_agent_session",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentSessionResponse"
                }
              }
            }
          },
          "401": {
            "description": "the session exists but is not this caller's",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "no session with this id: not created yet, or deleted since",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["agent-sessions"],
        "summary": "Delete an agent session and its live resources.",
        "operationId": "delete_agent_session",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": ""
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/{session_id}/activity": {
      "get": {
        "tags": ["agent-sessions"],
        "summary": "Read activity using the same visibility capability as the session transcript.",
        "operationId": "get_agent_session_activity",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "agentCorrelationId",
            "in": "query",
            "description": "Restrict activity to one code-mode invocation within this session.",
            "required": false,
            "schema": {
              "type": ["string", "null"],
              "format": "uuid"
            }
          },
          {
            "name": "beforeAt",
            "in": "query",
            "description": "Cursor timestamp from the previous page.",
            "required": false,
            "schema": {
              "type": ["string", "null"],
              "format": "date-time"
            }
          },
          {
            "name": "beforeId",
            "in": "query",
            "description": "Cursor activity ID from the previous page.",
            "required": false,
            "schema": {
              "type": ["string", "null"],
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size, from 1 to 100; defaults to 50.",
            "required": false,
            "schema": {
              "type": ["integer", "null"],
              "format": "int32",
              "maximum": 100,
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentActivityPage"
                }
              }
            }
          },
          "400": {
            "description": ""
          },
          "401": {
            "description": ""
          },
          "403": {
            "description": ""
          }
        }
      }
    },
    "/agent-sessions/{session_id}/app-connections": {
      "post": {
        "tags": ["agent-sessions"],
        "summary": "Continue the session now that its owner connected an app it asked for.",
        "description": "The harness produces an `app.connected` system event, which the transcript\nshows as no prompt; it starts a turn once the session is idle.",
        "operationId": "report_agent_session_app_connected",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AppConnectedRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "The session continues once it is idle"
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "Not the session's owner, or no edit access",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "409": {
            "description": "The session is archived",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "422": {
            "description": "The owner has not connected that app",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/{session_id}/archived": {
      "put": {
        "tags": ["agent-sessions"],
        "summary": "Archive or unarchive an agent session.",
        "operationId": "set_agent_session_archived",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetAgentSessionArchivedRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": ""
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "409": {
            "description": "The session answers an agent conversation",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/{session_id}/auto-archive": {
      "get": {
        "tags": ["agent-sessions"],
        "summary": "Read a session's auto-archive settings and whether a trigger archived it.",
        "operationId": "get_agent_session_auto_archive",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionAutoArchiveResponse"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": ["agent-sessions"],
        "summary": "Replace a session's own auto-archive choices. Owner only.",
        "operationId": "put_agent_session_auto_archive",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AutoArchiveOverridesBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutoArchiveOverridesBody"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/{session_id}/changes": {
      "get": {
        "tags": ["agent-sessions"],
        "summary": "The latest captured changes of an agent session: the changed files with\nstatuses and line counts, and how the latest capture attempt went.",
        "operationId": "get_agent_session_changes",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentSessionChangesResponse"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/{session_id}/changes/patch": {
      "get": {
        "tags": ["agent-sessions"],
        "summary": "The unified diff behind the session's latest changeset.",
        "operationId": "get_agent_session_changes_patch",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentSessionChangesPatchResponse"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/{session_id}/changes/refresh": {
      "post": {
        "tags": ["agent-sessions"],
        "summary": "Capture the session's changes again now. Answers at once with the state\nas it stands; the capture runs on and viewers are told when it lands.",
        "operationId": "refresh_agent_session_changes",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentSessionChangesResponse"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/{session_id}/code-executions/{execution_id}": {
      "get": {
        "tags": ["agent-sessions"],
        "summary": "Fetch one execution only after the caller has obtained view access to its session.",
        "operationId": "get_code_execution",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "Owning session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "execution_id",
            "in": "path",
            "description": "Execution receipt identity",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExecutionRecord"
                }
              }
            }
          },
          "401": {
            "description": ""
          },
          "403": {
            "description": ""
          },
          "404": {
            "description": ""
          },
          "500": {
            "description": ""
          }
        }
      }
    },
    "/agent-sessions/{session_id}/code-executions/{execution_id}/connected-apps": {
      "get": {
        "tags": ["agent-sessions"],
        "summary": "List the connected apps and custom MCP servers the session's agent may use.",
        "operationId": "list_execution_connected_apps",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "execution_id",
            "in": "path",
            "description": "A running execution of the session's current turn",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ConnectedApp"
                  }
                }
              }
            }
          },
          "403": {
            "description": ""
          },
          "404": {
            "description": ""
          }
        }
      }
    },
    "/agent-sessions/{session_id}/code-executions/{execution_id}/connected-apps/discover": {
      "post": {
        "tags": ["agent-sessions"],
        "summary": "Search the connectable app catalog, or inspect one app's tools and connection status.",
        "operationId": "discover_connected_apps",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "execution_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DiscoveryRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DiscoverConnectorsResponse"
                }
              }
            }
          },
          "400": {
            "description": ""
          },
          "403": {
            "description": ""
          },
          "404": {
            "description": ""
          }
        }
      }
    },
    "/agent-sessions/{session_id}/code-executions/{execution_id}/connected-apps/servers": {
      "post": {
        "tags": ["agent-sessions"],
        "summary": "Add a custom MCP server to the execution account's connections.",
        "operationId": "add_connected_mcp_server",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "execution_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConnectMcpServer"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConnectMcpServerResponse"
                }
              }
            }
          },
          "400": {
            "description": ""
          },
          "403": {
            "description": ""
          },
          "404": {
            "description": ""
          }
        }
      }
    },
    "/agent-sessions/{session_id}/code-executions/{execution_id}/connected-apps/tools": {
      "get": {
        "tags": ["agent-sessions"],
        "summary": "Find tools across the agent's connected apps by keywords.",
        "operationId": "search_connected_app_tools",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "execution_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "query",
            "in": "query",
            "description": "Keywords matched against tool names and descriptions, e.g. `linear issue`.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConnectedToolSearch"
                }
              }
            }
          },
          "403": {
            "description": ""
          },
          "404": {
            "description": ""
          }
        }
      }
    },
    "/agent-sessions/{session_id}/code-executions/{execution_id}/connected-apps/{kind}/{key}/calls": {
      "post": {
        "tags": ["agent-sessions"],
        "summary": "Call one tool of a connected app as the execution's account.",
        "operationId": "call_connected_app_tool",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "execution_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "kind",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/ConnectedAppKind"
            }
          },
          {
            "name": "key",
            "in": "path",
            "description": "The app's slug or custom server key",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CallConnectedTool"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConnectedToolResult"
                }
              }
            }
          },
          "400": {
            "description": ""
          },
          "403": {
            "description": ""
          },
          "404": {
            "description": ""
          }
        }
      }
    },
    "/agent-sessions/{session_id}/code-executions/{execution_id}/connected-apps/{kind}/{key}/tools": {
      "get": {
        "tags": ["agent-sessions"],
        "summary": "List the tools one connected app serves.",
        "operationId": "list_connected_app_tools",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "execution_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "kind",
            "in": "path",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/ConnectedAppKind"
            }
          },
          {
            "name": "key",
            "in": "path",
            "description": "The app's slug or custom server key",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ConnectedTool"
                  }
                }
              }
            }
          },
          "403": {
            "description": ""
          },
          "404": {
            "description": ""
          }
        }
      }
    },
    "/agent-sessions/{session_id}/code-executions/{execution_id}/reviews": {
      "get": {
        "tags": ["agent-sessions"],
        "summary": "List blocks created during an execution, including interrupted executions.",
        "operationId": "list_execution_reviews",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "execution_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ReviewRecord"
                  }
                }
              }
            }
          },
          "403": {
            "description": ""
          }
        }
      }
    },
    "/agent-sessions/{session_id}/control": {
      "post": {
        "tags": ["agent-sessions"],
        "summary": "Perform a control operation on a live agent session.",
        "description": "Edit access suffices: whoever can prompt the bot through its thread can\nprompt it here.\n\nA caller may name the action with `actionId`; the response echoes it.\nRe-posting an id the session still holds queued or in flight reports that\naction's status rather than accepting a duplicate.",
        "operationId": "control_agent_session",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ControlRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Accepted. `sent` reached the runtime; `queued` waits for the running turn to end and can be edited or removed meanwhile.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ControlResponse"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "AI allowance exhausted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AiAdmissionErrorBody"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "422": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "503": {
            "description": "AI usage validation unavailable, or replica draining; retry later",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AiAdmissionErrorBody"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/{session_id}/log": {
      "get": {
        "tags": ["agent-sessions"],
        "summary": "The raw protocol log of one agent session.",
        "description": "Served unfolded from the latest successful load initialization, or the\nbeginning when no load succeeded. Consumers stage load attempts so failed\nor interrupted replay does not become visible conversation content.\n\nAn unknown session is an error: the response has to name the session's\nagent, and a session that never existed has none to name.",
        "operationId": "get_agent_session_log",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentSessionLogResponse"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/{session_id}/log/folded": {
      "get": {
        "tags": ["agent-sessions"],
        "summary": "One agent session's history folded into renderable messages: the same\nfold the web client runs over [`get_agent_session_log_handler`]'s frames.",
        "description": "For readers that do not run the fold themselves, such as SDK programs and\nagents reading another session's history.",
        "operationId": "get_agent_session_folded_log",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentSessionFoldedLogResponse"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/{session_id}/name": {
      "put": {
        "tags": ["agent-sessions"],
        "summary": "Rename an agent session.",
        "operationId": "rename_agent_session",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RenameAgentSessionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": ""
          },
          "400": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "409": {
            "description": "The session is archived",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/{session_id}/permissions": {
      "get": {
        "tags": ["agent-sessions"],
        "summary": "Read sharing settings for a session the caller can view.",
        "operationId": "get_agent_session_permissions",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SharePermissionV2"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": ["agent-sessions"],
        "summary": "Update link, channel, or team sharing after owner authorization.",
        "operationId": "update_agent_session_permissions",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateSharePermissionRequestV2"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SharePermissionV2"
                }
              }
            }
          },
          "400": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "409": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/{session_id}/pull-requests": {
      "get": {
        "tags": ["agent-sessions"],
        "summary": "List the pull requests associated with a session the caller can view.",
        "operationId": "list_agent_session_pull_requests",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionPullRequestsResponse"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "put": {
        "tags": ["agent-sessions"],
        "summary": "Link a pull request to a session the caller can edit.",
        "operationId": "link_agent_session_pull_request",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PullRequestUrl"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": ""
          },
          "400": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["agent-sessions"],
        "summary": "Unlink a pull request a person linked to a session the caller can edit. The pull request\nthe session's agent opened stays linked.",
        "operationId": "unlink_agent_session_pull_request",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "url",
            "in": "query",
            "description": "The pull request's GitHub URL",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": ""
          },
          "400": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/{session_id}/queue": {
      "get": {
        "tags": ["agent-sessions"],
        "summary": "The actions waiting to dispatch in this session, oldest first.",
        "operationId": "get_agent_session_queue",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentSessionQueueResponse"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/{session_id}/queue/{action_id}": {
      "put": {
        "tags": ["agent-sessions"],
        "summary": "Replace a queued prompt's text before it dispatches.",
        "operationId": "edit_queued_action",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "action_id",
            "in": "path",
            "description": "ID the action was accepted under",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EditQueuedActionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": ""
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Already dispatched or never queued",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "422": {
            "description": "The queued action carries no text",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["agent-sessions"],
        "summary": "Remove a queued action before it dispatches. There is no un-sending: an\naction that already went out answers 404.",
        "operationId": "remove_queued_action",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "action_id",
            "in": "path",
            "description": "ID the action was accepted under",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": ""
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Already dispatched or never queued",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/{session_id}/queue/{action_id}/steer": {
      "post": {
        "tags": ["agent-sessions"],
        "summary": "Run a queued action next. Moves it ahead of the rest of the queue and\ncancels the turn in flight, so this entry dispatches when that turn ends.",
        "operationId": "steer_queued_action",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "action_id",
            "in": "path",
            "description": "ID the action was accepted under",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": ""
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "Already dispatched or never queued",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/{session_id}/reviews": {
      "post": {
        "tags": ["agent-sessions"],
        "summary": "Persist a review without keeping the agent turn blocked.",
        "operationId": "create_session_review",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateReview"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReviewRecord"
                }
              }
            }
          },
          "400": {
            "description": ""
          },
          "403": {
            "description": ""
          }
        }
      }
    },
    "/agent-sessions/{session_id}/reviews/{review_id}": {
      "get": {
        "tags": ["agent-sessions"],
        "summary": "Read a persisted interactive block.",
        "operationId": "get_session_review",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "review_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReviewRecord"
                }
              }
            }
          },
          "403": {
            "description": ""
          },
          "404": {
            "description": ""
          }
        }
      },
      "post": {
        "tags": ["agent-sessions"],
        "summary": "Save edits or atomically claim the exact draft revision the user submitted.",
        "operationId": "decide_session_review",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "review_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReviewDecision"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReviewRecord"
                }
              }
            }
          },
          "403": {
            "description": ""
          },
          "409": {
            "description": ""
          }
        }
      }
    },
    "/agent-sessions/{session_id}/sandbox-size": {
      "put": {
        "tags": ["agent-sessions"],
        "summary": "Resize this session's sandbox and remember the size as the owner's default.",
        "operationId": "put_agent_session_sandbox_size",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SandboxSizeBody"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SandboxSizeBody"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/{session_id}/tool-approvals/{approval_id}": {
      "post": {
        "tags": ["agent-sessions"],
        "summary": "Answer a tool call the agent made in a turn somebody other than the\nsession's owner prompted. Approve and deny are the owner's; cancel is\nanyone's with edit access.",
        "operationId": "answer_agent_session_tool_approval",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "approval_id",
            "in": "path",
            "description": "ID of the held tool call",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnswerToolApprovalRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnswerToolApprovalResponse"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "Not the owner, for approve or deny; or no edit access",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "409": {
            "description": "Already resolved",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "422": {
            "description": "Approve for good, for a call no person asked for",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-sessions/{session_id}/views": {
      "post": {
        "tags": ["agent-sessions"],
        "summary": "Present a view in the session: a review with nothing saved.",
        "operationId": "present_session_view",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PresentView"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": ""
          },
          "400": {
            "description": ""
          },
          "403": {
            "description": ""
          }
        }
      }
    },
    "/agent-sessions/{session_id}/work-registration": {
      "put": {
        "tags": ["agent-sessions"],
        "summary": "Register a session as the caller's work. Requires edit access. Repeating returns the active\nregistration. Registering does not share the session: viewers who cannot open it do not see\nit, so share it too.",
        "operationId": "register_agent_session_work",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkRegistrationResponse"
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "403": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "409": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["agent-sessions"],
        "summary": "End the caller's own registration of a session. Repeating does nothing. It touches only the\ncaller's own row, so it needs no access to the session: losing access must not strand it.",
        "operationId": "unregister_agent_session_work",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "description": "ID of the agent session",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "The caller has no active registration of the session"
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agent-work-registrations": {
      "get": {
        "tags": ["agent-sessions"],
        "summary": "List the caller's active registrations of sessions they can still view, newest first.",
        "operationId": "list_agent_work_registrations",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WorkRegistrationResponse"
                  }
                }
              }
            }
          },
          "401": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "description": "",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/universal_input/classify": {
      "post": {
        "tags": ["universal_input::inbound::axum_router"],
        "summary": "Classify a draft for the authenticated user.",
        "operationId": "classify",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ClassifyInputRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClassifyInputResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Unauthenticated"
          },
          "402": {
            "description": "AI allowance exhausted"
          },
          "503": {
            "description": "Detection unavailable"
          }
        }
      }
    },
    "/universal_input/extract": {
      "post": {
        "tags": ["universal_input::inbound::axum_router"],
        "summary": "Extract editable fields for the authenticated user.",
        "operationId": "extract",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExtractInputRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExtractInputResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Unauthenticated"
          },
          "402": {
            "description": "AI allowance exhausted"
          },
          "503": {
            "description": "Extraction unavailable"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AccessLevel": {
        "type": "string",
        "description": "Ordered from least to most access top -> bottom",
        "enum": ["view", "comment", "edit", "owner"]
      },
      "ActivityWireRow": {
        "type": "object",
        "description": "One activity row on the wire — the realtime projection of an inserted\n`activity_events` row.",
        "required": [
          "id",
          "actor_id",
          "subject_id",
          "entity_type",
          "entity_id",
          "action",
          "occurred_at"
        ],
        "properties": {
          "action": {
            "type": "string",
            "description": "The stored action tag."
          },
          "action_payload": {
            "description": "The stored action payload, if any."
          },
          "actor_id": {
            "type": "string",
            "description": "Who mechanically acted, as a principal string (`macro|…` / `bot|…`)."
          },
          "agent_correlation_id": {
            "type": ["string", "null"],
            "format": "uuid",
            "description": "Originating code-mode invocation, absent on older events."
          },
          "entity_id": {
            "type": "string",
            "description": "The entity acted on."
          },
          "entity_type": {
            "$ref": "#/components/schemas/EntityType",
            "description": "The kind of entity acted on."
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The stored activity id."
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time",
            "description": "When it happened."
          },
          "subject_id": {
            "type": "string",
            "description": "Whose activity this is (a principal string)."
          }
        }
      },
      "AgentAction": {
        "oneOf": [
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/AgentPromptAction",
                "description": "Send the agent a prompt."
              },
              {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["prompt"]
                  }
                }
              }
            ],
            "description": "Send the agent a prompt."
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/AgentSetModelAction",
                "description": "Switch the model the agent runs on."
              },
              {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["setModel"]
                  }
                }
              }
            ],
            "description": "Switch the model the agent runs on."
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/AgentSetConfigOptionAction",
                "description": "Change an agent-advertised select-style session setting."
              },
              {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["setConfigOption"]
                  }
                }
              }
            ],
            "description": "Change an agent-advertised select-style session setting."
          },
          {
            "type": "object",
            "description": "Compact the agent's current context.",
            "required": ["type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["compact"]
              }
            }
          },
          {
            "type": "object",
            "description": "Interrupt whatever the agent is doing.",
            "required": ["type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["stop"]
              }
            }
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/AgentRespondElicitationAction",
                "description": "Answer an `elicitation/create` the agent sent.\n\nThe one action whose wire form is a JSON-RPC *response* rather than a\nrequest or notification: the agent asked, we answer on its id. The\nminted [`AgentActionId`] therefore never reaches the wire for this\naction; the fold correlates on the agent's id instead."
              },
              {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["respondElicitation"]
                  }
                }
              }
            ],
            "description": "Answer an `elicitation/create` the agent sent.\n\nThe one action whose wire form is a JSON-RPC *response* rather than a\nrequest or notification: the agent asked, we answer on its id. The\nminted [`AgentActionId`] therefore never reaches the wire for this\naction; the fold correlates on the agent's id instead."
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/AgentPermissionAction",
                "description": "Answer a permission request the agent is waiting on."
              },
              {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["respondToPermission"]
                  }
                }
              }
            ],
            "description": "Answer a permission request the agent is waiting on."
          }
        ],
        "description": "One thing a caller wants an agent to do."
      },
      "AgentActionId": {
        "type": "string",
        "format": "uuid",
        "description": "Identifies one accepted [`AgentAction`] end to end: returned by the\ncontrol endpoint, written as the JSON-RPC request id on the action's wire\nframe, and read back off that frame as `request_id` on the folded message\nit derives.\n\nA v7 uuid, so ids sort by mint time. Minted by the server at accept time,\nor by a client that speculated the action and named it in the control\nrequest - either way the server is the only writer of runtime-bound\nframes, so a uuid-shaped request id remains the whole ownership test. The\nmachine's own handshake request ids (`agent_session:{session}:{n}`) are\nnot uuids and stay `None`."
      },
      "AgentActivityCursor": {
        "type": "object",
        "description": "Stable chronological resume position.",
        "required": ["occurredAt", "id"],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Tie-breaking activity identity."
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "Last stored event time."
          }
        }
      },
      "AgentActivityPage": {
        "type": "object",
        "description": "One page of the activity caused by this session.",
        "required": ["activities"],
        "properties": {
          "activities": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ActivityWireRow"
            },
            "description": "Original activity rows, also retained in the affected entities' histories."
          },
          "nextCursor": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/AgentActivityCursor",
                "description": "Resume position, present when more raw rows remain."
              }
            ]
          }
        }
      },
      "AgentActor": {
        "type": "object",
        "description": "An agent acting for a person.",
        "required": ["bot", "on_behalf_of", "lineage"],
        "properties": {
          "bot": {
            "$ref": "#/components/schemas/BotId",
            "description": "The agent."
          },
          "lineage": {
            "$ref": "#/components/schemas/Lineage",
            "description": "Where the agent's own work came from."
          },
          "on_behalf_of": {
            "$ref": "#/components/schemas/MacroUserIdStr",
            "description": "The person it acts for."
          }
        }
      },
      "AgentConfigKindDto": {
        "oneOf": [
          {
            "type": "object",
            "description": "A single-value selector.",
            "required": ["currentValue", "options", "type"],
            "properties": {
              "currentValue": {
                "type": "string",
                "description": "Current opaque value."
              },
              "options": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AgentConfigSelectOptionDto"
                },
                "description": "Ordered values supplied by the agent."
              },
              "type": {
                "type": "string",
                "enum": ["select"]
              }
            }
          },
          {
            "type": "object",
            "description": "An on/off setting.",
            "required": ["currentValue", "type"],
            "properties": {
              "currentValue": {
                "type": "boolean",
                "description": "Current value."
              },
              "type": {
                "type": "string",
                "enum": ["boolean"]
              }
            }
          }
        ],
        "description": "Type-specific state for one agent session setting."
      },
      "AgentConfigOptionDto": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AgentConfigKindDto",
            "description": "Type-specific current value and choices."
          },
          {
            "type": "object",
            "required": ["id", "name"],
            "properties": {
              "category": {
                "type": ["string", "null"],
                "description": "ACP semantic category, such as `model` or `thought_level`."
              },
              "description": {
                "type": ["string", "null"],
                "description": "Optional explanatory copy."
              },
              "id": {
                "type": "string",
                "description": "Opaque id used to change this setting."
              },
              "name": {
                "type": "string",
                "description": "Display label supplied by the agent."
              }
            }
          }
        ],
        "description": "One agent-advertised ACP session setting."
      },
      "AgentConfigSelectOptionDto": {
        "type": "object",
        "description": "One value in an agent-advertised select.",
        "required": ["value", "name"],
        "properties": {
          "description": {
            "type": ["string", "null"],
            "description": "Optional provider description of this value."
          },
          "group": {
            "type": ["string", "null"],
            "description": "Optional group heading supplied by the provider."
          },
          "name": {
            "type": "string",
            "description": "Display label."
          },
          "value": {
            "type": "string",
            "description": "Opaque value returned to the agent when selected."
          }
        }
      },
      "AgentConversationDto": {
        "type": "object",
        "description": "An agent's conversation in a channel, as the person it is with sees it.",
        "required": [
          "channelId",
          "botId",
          "name",
          "available",
          "settingsChanged",
          "sessions",
          "turns"
        ],
        "properties": {
          "available": {
            "type": "boolean",
            "description": "Whether the caller may currently send a new prompt."
          },
          "avatarUrl": {
            "type": ["string", "null"],
            "description": "Optional persona avatar."
          },
          "botId": {
            "type": "string",
            "format": "uuid",
            "description": "Persona id (without the bot principal prefix)."
          },
          "channelId": {
            "type": "string",
            "format": "uuid",
            "description": "The channel containing the visible transcript."
          },
          "name": {
            "type": "string",
            "description": "Persona's historical display name."
          },
          "sessions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentConversationSessionDto"
            },
            "description": "The sessions the conversation has run on, oldest first."
          },
          "settingsChanged": {
            "type": "boolean",
            "description": "Whether new persona settings are available to adopt explicitly."
          },
          "turns": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentConversationTurnDto"
            },
            "description": "Persistent state of each accepted message and its current attempt."
          }
        }
      },
      "AgentConversationSessionDto": {
        "type": "object",
        "description": "One session a conversation has run on; every channel message stays visible.",
        "required": ["sessionId", "createdAt", "isCurrent"],
        "properties": {
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the session began."
          },
          "isCurrent": {
            "type": "boolean",
            "description": "Whether this is the current agent context."
          },
          "sessionId": {
            "type": "string",
            "format": "uuid",
            "description": "Session whose controls and live events belong to this context."
          }
        }
      },
      "AgentConversationTurnDto": {
        "type": "object",
        "description": "Execution status without exposing the persona prompt or stored credentials.",
        "required": [
          "sourceMessageId",
          "actionId",
          "sessionId",
          "state",
          "retryable",
          "createdAt"
        ],
        "properties": {
          "actionId": {
            "type": "string",
            "format": "uuid",
            "description": "Current runtime attempt identity."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the source message was first accepted."
          },
          "replyMessageId": {
            "type": ["string", "null"],
            "format": "uuid",
            "description": "The associated agent reply, if it has been posted."
          },
          "retryable": {
            "type": "boolean",
            "description": "Whether Retry would be accepted now. A failed attempt is not retryable\nuntil its reply says how it ended."
          },
          "sessionId": {
            "type": "string",
            "format": "uuid",
            "description": "Session carrying this turn."
          },
          "sourceMessageId": {
            "type": "string",
            "format": "uuid",
            "description": "The user's message in the channel timeline."
          },
          "state": {
            "$ref": "#/components/schemas/ConversationTurnState",
            "description": "Durable execution state."
          }
        }
      },
      "AgentConversationsDto": {
        "type": "object",
        "description": "The agent conversations in a channel the caller may see.",
        "required": ["conversations"],
        "properties": {
          "conversations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentConversationDto"
            },
            "description": "Empty for ordinary channels and other people's conversations."
          }
        }
      },
      "AgentMode": {
        "type": "string",
        "description": "Which kind of agent a prompt is sent to.",
        "enum": ["chat", "code"]
      },
      "AgentModeChoiceRequest": {
        "type": "object",
        "description": "Request body for `POST /agent-mode-choice`.",
        "required": ["prompt"],
        "properties": {
          "prompt": {
            "type": "string",
            "description": "The prompt the composer is about to send."
          }
        }
      },
      "AgentModeChoiceResponse": {
        "type": "object",
        "description": "Response body for `POST /agent-mode-choice`.",
        "required": ["mode"],
        "properties": {
          "mode": {
            "$ref": "#/components/schemas/AgentMode",
            "description": "Which kind of agent should receive the prompt."
          }
        }
      },
      "AgentModelDto": {
        "type": "object",
        "description": "One model picker option.",
        "required": ["id", "name"],
        "properties": {
          "description": {
            "type": ["string", "null"],
            "description": "Optional provider description."
          },
          "group": {
            "type": ["string", "null"],
            "description": "Optional group heading supplied by the provider."
          },
          "id": {
            "type": "string",
            "description": "Provider model id."
          },
          "name": {
            "type": "string",
            "description": "Display name."
          },
          "supportsImages": {
            "type": ["boolean", "null"],
            "description": "Image input support, absent when the runtime does not advertise it."
          }
        }
      },
      "AgentModelsStatusDto": {
        "type": "string",
        "description": "Model-selection availability returned over HTTP.",
        "enum": ["available", "unsupported"]
      },
      "AgentPermissionAction": {
        "type": "object",
        "description": "A user's answer to the agent's `session/request_permission`.\n\nUnlike every other action this is not a new request but the reply to one\nthe agent made, so it carries the agent's own request id rather than\nreceiving a server-minted one.",
        "required": ["requestId", "answer"],
        "properties": {
          "answer": {
            "$ref": "#/components/schemas/PermissionAnswer",
            "description": "What the user decided."
          },
          "requestId": {
            "description": "The agent's JSON-RPC request id, echoed verbatim from the folded\npermission part. A string or a number on the wire; agents mint both,\nand `7` does not answer `\"7\"`."
          }
        }
      },
      "AgentPromptAction": {
        "type": "object",
        "description": "Ask the agent to work on something.",
        "required": ["prompt"],
        "properties": {
          "attachments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PromptAttachment"
            },
            "description": "Files the prompt refers to, in the order the user attached them.\nDelivered after the text as one `resource_link` block each."
          },
          "prompt": {
            "type": "string",
            "description": "What to tell the agent."
          }
        }
      },
      "AgentRepositoriesResponse": {
        "type": "object",
        "description": "Response body for `GET /agent-repositories`.",
        "required": ["repositories"],
        "properties": {
          "repositories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentRepositoryDto"
            },
            "description": "Every repository the caller reaches through Macro's GitHub App, sorted\nby `owner/name`. Empty when the App is installed nowhere the caller\nhas a claim to."
          }
        }
      },
      "AgentRepositoryBranchesResponse": {
        "type": "object",
        "description": "Response body for `GET /agent-repositories/branches`.",
        "required": ["branches"],
        "properties": {
          "branches": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Branch names on the repository, in the order GitHub returned them.\nEmpty when the repository has no commits yet."
          }
        }
      },
      "AgentRepositoryDto": {
        "type": "object",
        "description": "One repository the caller can select for a coding session.",
        "required": ["url"],
        "properties": {
          "defaultBranch": {
            "type": ["string", "null"],
            "description": "The branch a clone checks out, and where a session starts when its\nrequest selects this repository without a `repoBranch`. Absent for a\nrepository with no commits."
          },
          "url": {
            "type": "string",
            "description": "The canonical `https://github.com/owner/name` url, in the form\n`POST /agent-sessions` accepts as `repoUrl`."
          }
        }
      },
      "AgentRespondElicitationAction": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ElicitationAnswer",
            "description": "The decision."
          },
          {
            "type": "object",
            "required": ["requestId"],
            "properties": {
              "requestId": {
                "$ref": "#/components/schemas/ElicitationRequestId",
                "description": "The agent's `elicitation/create` request id - not an\n[`AgentActionId`], because the agent minted it."
              }
            }
          }
        ],
        "description": "Answer an elicitation the agent is waiting on."
      },
      "AgentSessionChangesPatchResponse": {
        "type": "object",
        "description": "Response body for `GET /agent-sessions/{session_id}/changes/patch`.\n\nClients deserialize this, so both derives are used.",
        "required": ["patch"],
        "properties": {
          "patch": {
            "type": "string",
            "description": "The git-style unified diff of the current changeset."
          }
        }
      },
      "AgentSessionChangesResponse": {
        "type": "object",
        "description": "Response body for `GET /agent-sessions/{session_id}/changes`.\n\nClients deserialize this, so both derives are used.",
        "required": ["capturing"],
        "properties": {
          "attempt": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/CaptureAttemptDto",
                "description": "The latest attempt, if any was made."
              }
            ]
          },
          "capturing": {
            "type": "boolean",
            "description": "A capture is running right now."
          },
          "changeset": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/ChangesetDto",
                "description": "The latest capture, if any succeeded."
              }
            ]
          }
        }
      },
      "AgentSessionFoldedLogResponse": {
        "type": "object",
        "description": "Response body for one session's folded log.",
        "required": ["bot", "messages"],
        "properties": {
          "bot": {
            "$ref": "#/components/schemas/SessionBot",
            "description": "The agent whose messages these are; it sent every agent message."
          },
          "messages": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "The conversation, oldest first: prompts, replies, tool calls and their\nresults, plans, permission requests and how each turn ended. Each\nelement is a `FoldedMessage` from the fold's TypeScript contract,\nwhich the SDK exports; the schema is opaque here because those types\nare described with specta rather than utoipa."
          }
        }
      },
      "AgentSessionLogEntryDto": {
        "allOf": [
          {
            "$ref": "#/components/schemas/LogFrameDto",
            "description": "The frame: `direction` and the protocol envelope under `content`.\n\nSerialized by [`Message`] itself rather than rebuilt field by field, so\nthe bytes on the wire are exactly what the fold's own log type reads\nback. [`LogFrameDto`] describes the two fields that produces."
          },
          {
            "type": "object",
            "required": ["id", "createdAt"],
            "properties": {
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "description": "When the log recorded the frame.\n\nThe frame itself carries no time, so this comes from the log row. It is\nwhat a reader has to order these against anything else it is showing\nbeside them - the fold derives an order among the messages of one\nsession and nothing more."
              },
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "Durable transport row identity; together with `createdAt`, its order cursor."
              },
              "userId": {
                "type": ["string", "null"],
                "description": "The user whose action produced the frame, absent when no user did.\n\nOnly prompts carry one, and only when the frame was attributed at the\ntime - a replayed or recorded session's are anonymous."
              }
            }
          }
        ],
        "description": "One entry of a session's protocol log.\n\nSerializes as `{\"userId\": ..., \"direction\": ..., \"content\": ...}` - the\nframe's own two fields, flattened in beside the attribution, which is the\nsame shape a recorded session's JSONL carries. A reader can deserialize the\n`direction`/`content` pair straight back into the fold's own log type\nrather than through a transport vocabulary of its own.\n\n`agentSessionId` is not repeated per entry: every entry in a response\nbelongs to the session named once at the top.\n\n`Deserialize` is for the wire-contract tests only - nothing server-side\ndecodes its own response type."
      },
      "AgentSessionLogResponse": {
        "type": "object",
        "description": "Response body for one session's raw protocol log.\n\nA wrapper rather than a bare array so that anything which is about the\nresponse rather than about a frame has somewhere to go later without\nbreaking every client.",
        "required": ["bot", "entries"],
        "properties": {
          "bot": {
            "$ref": "#/components/schemas/SessionBot",
            "description": "The agent whose messages the log derives.\n\nHere because a client renders those messages and cannot otherwise work\nout who sent them: the sender of an agent message is this session's\nbot, and nothing else names it."
          },
          "entries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentSessionLogEntryDto"
            },
            "description": "Effective history in ascending `(createdAt, id)` order.\nThe first row is the inclusive history boundary cursor: buffered rows\nbefore it are obsolete. Reconcile snapshot overlap by row ID, never content.\nAn empty history has no boundary or overlapping rows."
          }
        }
      },
      "AgentSessionPreviewData": {
        "type": "object",
        "description": "The fields a chip renders for a session the caller may view.\n\nClients deserialize this, so both derives are used.",
        "required": [
          "id",
          "name",
          "ownerId",
          "botId",
          "status",
          "createdAt",
          "modifiedAt"
        ],
        "properties": {
          "bot": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/SessionBot",
                "description": "Minimal identity of the session's bot, when available."
              }
            ]
          },
          "botId": {
            "type": "string",
            "format": "uuid",
            "description": "The bot running the agent."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the session was created."
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The session id."
          },
          "modifiedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the session was last modified."
          },
          "name": {
            "type": "string",
            "description": "User-facing session name."
          },
          "ownerId": {
            "type": "string",
            "description": "The user who owns the session."
          },
          "status": {
            "$ref": "#/components/schemas/SessionStatusDto",
            "description": "The session's last known status."
          }
        }
      },
      "AgentSessionPreviewDto": {
        "oneOf": [
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/AgentSessionPreviewData",
                "description": "The caller may view the session."
              },
              {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["access"]
                  }
                }
              }
            ],
            "description": "The caller may view the session."
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/WithAgentSessionId",
                "description": "The session exists but the caller holds no grant on it."
              },
              {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["no_access"]
                  }
                }
              }
            ],
            "description": "The session exists but the caller holds no grant on it."
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/WithAgentSessionId",
                "description": "No session with this id exists."
              },
              {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["does_not_exist"]
                  }
                }
              }
            ],
            "description": "No session with this id exists."
          }
        ],
        "description": "What one requested id resolved to, on the wire.\n\nTagged the same way the chat and document preview endpoints tag theirs\n(`type` in `access` / `no_access` / `does_not_exist`), so a client that\nrenders those chips can render this one with the same branch.\n\nClients deserialize this, so both derives are used."
      },
      "AgentSessionQueueResponse": {
        "type": "object",
        "description": "Response body for a session's queue: everything waiting, oldest first.\n\nA wrapper rather than a bare array so that anything which is about the\nresponse rather than about an entry has somewhere to go later without\nbreaking every client.",
        "required": ["entries"],
        "properties": {
          "entries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/QueuedActionDto"
            },
            "description": "The waiting actions, in dispatch order."
          }
        }
      },
      "AgentSessionResponse": {
        "type": "object",
        "description": "Response body describing an agent session.\n\nClients deserialize this, so both derives are used.",
        "required": [
          "id",
          "name",
          "ownerId",
          "canEdit",
          "botId",
          "model",
          "harness",
          "workspace",
          "sandboxSize",
          "status",
          "createdAt",
          "modifiedAt"
        ],
        "properties": {
          "acpSessionId": {
            "type": ["string", "null"],
            "description": "The ACP session id, if one exists."
          },
          "archivedAt": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "When the session was archived, or `None` while it is active."
          },
          "archivedBy": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/ArchiveCause",
                "description": "Who or what archived the session, or `None` while it is active. An archived session is\nread-only."
              }
            ]
          },
          "botId": {
            "type": "string",
            "format": "uuid",
            "description": "The bot running the agent."
          },
          "canEdit": {
            "type": "boolean",
            "description": "Whether the caller may drive the session - prompt it, answer its\nquestions, stop it - rather than only watch. Edit access; the\ncreator owns the session, so a create response always says so."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the session was created."
          },
          "external": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/ExternalSessionResponse",
                "description": "The external provider serving this session, when one does. Absent for\nsandboxed sessions, so existing payloads are byte-identical."
              }
            ]
          },
          "harness": {
            "type": "string",
            "description": "Harness slug."
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The session id."
          },
          "instructions": {
            "type": ["string", "null"],
            "description": "Instructions the session's runtime works under, when any were stated\nat creation. Absent otherwise, so existing payloads are unchanged."
          },
          "model": {
            "type": "string",
            "description": "Model slug."
          },
          "modifiedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the session was last modified."
          },
          "name": {
            "type": "string",
            "description": "User-facing session name."
          },
          "origin": {
            "$ref": "#/components/schemas/TriggerOrigin",
            "description": "What opened the session: who or what started it, and what it is about.\n`unknown` when nothing recorded it."
          },
          "originatingMessageId": {
            "type": ["string", "null"],
            "format": "uuid",
            "description": "The exact message that invoked the bot, if any."
          },
          "ownerId": {
            "type": "string",
            "description": "The user who created and owns the session."
          },
          "pullRequestUrl": {
            "type": ["string", "null"],
            "description": "The session's linked pull request."
          },
          "repoUrl": {
            "type": ["string", "null"],
            "description": "The repository the session works with, when one was stated."
          },
          "sandboxSize": {
            "$ref": "#/components/schemas/SandboxSize",
            "description": "Compute tier of the managed sandbox."
          },
          "status": {
            "$ref": "#/components/schemas/SessionStatusDto",
            "description": "The session's status."
          },
          "taskId": {
            "type": ["string", "null"],
            "description": "The Macro task the session was linked to."
          },
          "threadChannelId": {
            "type": ["string", "null"],
            "format": "uuid",
            "description": "The channel `thread_id` lives in, when the session was spawned from a\nchannel thread. Derived from `thread_parent`."
          },
          "threadId": {
            "type": ["string", "null"],
            "format": "uuid",
            "description": "The root message of the thread the session was created from, if any."
          },
          "threadParent": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/MessageParent",
                "description": "The channel or document `thread_id` lives in, when the session was\nspawned from a thread."
              }
            ]
          },
          "workspace": {
            "type": "string",
            "description": "The directory the session's harness runs in on its runtime."
          }
        }
      },
      "AgentSetConfigOptionAction": {
        "type": "object",
        "description": "Ask the agent to change one advertised select-style session setting.",
        "required": ["configId", "value"],
        "properties": {
          "configId": {
            "type": "string",
            "description": "Opaque ACP config id advertised by the agent."
          },
          "value": {
            "type": "string",
            "description": "Opaque select value advertised for that config option."
          }
        }
      },
      "AgentSetModelAction": {
        "type": "object",
        "description": "Ask the agent to run on a different model from here on.",
        "required": ["model"],
        "properties": {
          "model": {
            "type": "string",
            "description": "The model slug the agent should switch to."
          }
        }
      },
      "AiAdmissionErrorBody": {
        "type": "object",
        "description": "Public admission error payload. Handlers with additional fields can reuse the\ndomain error's code and message and [`admission_status`].",
        "required": ["error", "code"],
        "properties": {
          "code": {
            "type": "string",
            "description": "Stable denial or unavailability code."
          },
          "error": {
            "type": "string",
            "description": "Human-readable explanation, without internal billing diagnostics."
          }
        }
      },
      "AiSuggestions": {
        "type": "object",
        "description": "Editable fields for ai inference, before submission and identity resolution.",
        "additionalProperties": false
      },
      "AnswerToolApprovalRequest": {
        "type": "object",
        "description": "Request body for answering a held tool call.",
        "required": ["answer"],
        "properties": {
          "answer": {
            "$ref": "#/components/schemas/ToolApprovalAnswerDto",
            "description": "The answer."
          }
        }
      },
      "AnswerToolApprovalResponse": {
        "type": "object",
        "description": "Response body for answering a held tool call.",
        "required": ["status"],
        "properties": {
          "status": {
            "$ref": "#/components/schemas/ToolApprovalStatusDto",
            "description": "Where the call stands now."
          }
        }
      },
      "AppConnectedRequest": {
        "type": "object",
        "description": "Request body for reporting a connected app.",
        "required": ["appSlug"],
        "properties": {
          "actionId": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/AgentActionId",
                "description": "Names the report, so a retried one wakes the session once."
              }
            ]
          },
          "appSlug": {
            "type": "string",
            "description": "The Pipedream app slug the owner connected, e.g. `notion`."
          }
        }
      },
      "ArchiveCause": {
        "type": "string",
        "description": "Who or what archived a session.",
        "enum": ["user", "pull_request_merged", "runtime_closed"]
      },
      "AutoArchiveOverridesBody": {
        "type": "object",
        "description": "One session's choices over its owner's defaults. `null` follows the owner.",
        "properties": {
          "onPullRequestMerged": {
            "type": ["boolean", "null"],
            "description": "Archive once the session's pull requests merge, or `null` to follow the owner."
          },
          "onRuntimeClosed": {
            "type": ["boolean", "null"],
            "description": "Archive once the session's runtime session is deliberately closed, or `null` to follow\nthe owner."
          }
        }
      },
      "AutoArchivePreferencesBody": {
        "type": "object",
        "description": "Which triggers archive the caller's sessions when a session has no choice of its own.",
        "required": ["onPullRequestMerged", "onRuntimeClosed"],
        "properties": {
          "onPullRequestMerged": {
            "type": "boolean",
            "description": "Archive a session once every pull request linked to it is closed and at least one merged."
          },
          "onRuntimeClosed": {
            "type": "boolean",
            "description": "Archive a session once the runtime session backing it is deliberately closed."
          }
        }
      },
      "BotId": {
        "type": "string"
      },
      "CalendarSuggestions": {
        "type": "object",
        "description": "Editable fields for calendar inference, before submission and identity resolution.",
        "properties": {
          "body": {
            "type": ["string", "null"],
            "description": "Suggested Markdown content or outgoing message body."
          },
          "end": {
            "type": ["string", "null"],
            "description": "Event end as a local wall-clock value in the request's timezone."
          },
          "guests": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Only populated when an invitation was explicitly requested."
          },
          "location": {
            "type": ["string", "null"],
            "description": "Human-readable event venue or meeting URL."
          },
          "recurrence": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/RecurrenceSuggestion",
                "description": "Validated repetition values for the shared calendar composer."
              }
            ]
          },
          "start": {
            "type": ["string", "null"],
            "description": "Local wall-clock values, interpreted in the request's IANA timezone."
          },
          "start_assumption": {
            "type": ["string", "null"],
            "description": "Verbatim clock phrase whose missing AM/PM required an editable assumption."
          },
          "title": {
            "type": ["string", "null"],
            "description": "Suggested note, task, or event title."
          }
        },
        "additionalProperties": false
      },
      "CallConnectedTool": {
        "type": "object",
        "description": "Call one tool of a connected app.",
        "required": ["tool"],
        "properties": {
          "arguments": {
            "type": "object",
            "description": "The tool's arguments, matching its input schema."
          },
          "tool": {
            "type": "string",
            "description": "The tool's name on its server."
          }
        },
        "additionalProperties": false
      },
      "CallSearchSuggestions": {
        "type": "object",
        "description": "Call search supports speakers, channels and attendance status.",
        "required": ["from", "in"],
        "properties": {
          "from": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Speaker names or supplied addresses."
          },
          "in": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Channel names."
          },
          "query": {
            "type": ["string", "null"],
            "description": "Remaining keyword phrase."
          },
          "status": {
            "type": ["string", "null"],
            "description": "Attendance display value, resolved against supported options by the client."
          }
        },
        "additionalProperties": false
      },
      "Caller": {
        "oneOf": [
          {
            "type": "object",
            "description": "A person.",
            "required": ["user", "type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["person"]
              },
              "user": {
                "$ref": "#/components/schemas/MacroUserIdStr",
                "description": "Who."
              }
            }
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/AgentActor",
                "description": "An agent, which always acts for a person on a path that opens a session."
              },
              {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["agent"]
                  }
                }
              }
            ],
            "description": "An agent, which always acts for a person on a path that opens a session."
          }
        ],
        "description": "Who did something that opened a session."
      },
      "CapabilityHarnessDto": {
        "type": "string",
        "description": "Harness names accepted by the capability-discovery endpoint.",
        "enum": ["in-memory", "cursor", "macrod"]
      },
      "CaptureAttemptDto": {
        "type": "object",
        "description": "The latest capture attempt.\n\nClients deserialize this, so both derives are used.",
        "required": ["startedAt"],
        "properties": {
          "error": {
            "type": ["string", "null"],
            "description": "Why it did not capture, in a sentence the user can read."
          },
          "finishedAt": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "When it ended; absent while it runs."
          },
          "outcome": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/CaptureOutcomeDto",
                "description": "How it ended; absent while it runs."
              }
            ]
          },
          "startedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When it started."
          }
        }
      },
      "CaptureOutcomeDto": {
        "type": "string",
        "description": "How the latest capture attempt ended, on the wire.",
        "enum": ["captured", "not_ready", "failed"]
      },
      "ChangedFileDto": {
        "type": "object",
        "description": "One changed file.\n\nClients deserialize this, so both derives are used.",
        "required": [
          "path",
          "kind",
          "additions",
          "deletions",
          "binary",
          "patchOmitted"
        ],
        "properties": {
          "additions": {
            "type": "integer",
            "format": "int32",
            "description": "Lines added.",
            "minimum": 0
          },
          "binary": {
            "type": "boolean",
            "description": "The diff carries no text for this file."
          },
          "deletions": {
            "type": "integer",
            "format": "int32",
            "description": "Lines removed.",
            "minimum": 0
          },
          "kind": {
            "$ref": "#/components/schemas/FileChangeKindDto",
            "description": "What happened to the file."
          },
          "patchOmitted": {
            "type": "boolean",
            "description": "The file's hunks were left out of the patch to fit the size budget."
          },
          "path": {
            "type": "string",
            "description": "The file's path after the change, or before it for a deletion."
          },
          "previousPath": {
            "type": ["string", "null"],
            "description": "Where a renamed file came from."
          }
        }
      },
      "ChangesetDto": {
        "type": "object",
        "description": "One changeset: the files a patch touches and what happened to each.\n\nClients deserialize this, so both derives are used.",
        "required": [
          "id",
          "source",
          "base",
          "head",
          "files",
          "additions",
          "deletions",
          "patchBytes",
          "truncated",
          "capturedAt"
        ],
        "properties": {
          "additions": {
            "type": "integer",
            "format": "int32",
            "description": "Lines added across all files.",
            "minimum": 0
          },
          "base": {
            "$ref": "#/components/schemas/GitRefDto",
            "description": "The side the work started from."
          },
          "capturedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the diff was taken."
          },
          "deletions": {
            "type": "integer",
            "format": "int32",
            "description": "Lines removed across all files.",
            "minimum": 0
          },
          "files": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ChangedFileDto"
            },
            "description": "Every changed file, in patch order."
          },
          "head": {
            "$ref": "#/components/schemas/GitRefDto",
            "description": "The side carrying the work."
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The changeset's id; a different id means different changes."
          },
          "patchBytes": {
            "type": "integer",
            "format": "int64",
            "description": "Size of the patch the matching patch route serves; zero when nothing\nchanged.",
            "minimum": 0
          },
          "repository": {
            "type": ["string", "null"],
            "description": "`https://github.com/owner/name`, when known."
          },
          "source": {
            "$ref": "#/components/schemas/ChangesetSourceDto",
            "description": "Where the diff was read from."
          },
          "truncated": {
            "type": "boolean",
            "description": "Some files' hunks were left out of the patch."
          }
        }
      },
      "ChangesetSourceDto": {
        "type": "string",
        "description": "The source of a changeset's diff, on the wire.",
        "enum": ["github_pull_request"]
      },
      "ChannelSearchSuggestions": {
        "type": "object",
        "description": "Message filters remain display names until resolved against the user's directory.",
        "required": ["from", "in"],
        "properties": {
          "from": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Explicit message sender names or addresses."
          },
          "in": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Explicit channel names."
          },
          "query": {
            "type": ["string", "null"],
            "description": "Remaining keyword phrase."
          }
        },
        "additionalProperties": false
      },
      "ChannelSharePermission": {
        "type": "object",
        "description": "The channel share permission",
        "required": ["channel_id", "access_level"],
        "properties": {
          "access_level": {
            "$ref": "#/components/schemas/AccessLevel",
            "description": "The access level for the channel"
          },
          "channel_id": {
            "type": "string",
            "description": "The channel id"
          }
        }
      },
      "ClassifyInputRequest": {
        "type": "object",
        "description": "A draft snapshot. Revisions are opaque to the server and echoed to the client.",
        "required": ["text", "revision"],
        "properties": {
          "revision": {
            "type": "integer",
            "format": "int32",
            "description": "Opaque client revision used to discard stale predictions.",
            "minimum": 0
          },
          "text": {
            "type": "string",
            "description": "Current draft text to classify without executing it."
          }
        }
      },
      "ClassifyInputResponse": {
        "type": "object",
        "description": "Ranked-type evidence for a particular client draft revision.",
        "required": ["revision", "scores"],
        "properties": {
          "revision": {
            "type": "integer",
            "format": "int32",
            "description": "Revision echoed from the classification request.",
            "minimum": 0
          },
          "scores": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/IntentScore"
            },
            "description": "Independent scores in the fixed intent-question order."
          }
        }
      },
      "CodingPreferencesBody": {
        "type": "object",
        "description": "Request or response body for the caller's coding preferences.",
        "required": ["createTasks", "openPullRequests"],
        "properties": {
          "createTasks": {
            "type": "boolean",
            "description": "Whether new coding sessions research prior work and link a Macro task."
          },
          "openPullRequests": {
            "type": "boolean",
            "description": "Whether new coding sessions deliver their work as a pull request."
          }
        }
      },
      "ConnectMcpServer": {
        "type": "object",
        "description": "Add a custom MCP server to the user's connections.",
        "required": ["url", "serverName"],
        "properties": {
          "serverName": {
            "type": "string",
            "description": "Display name for the server."
          },
          "url": {
            "type": "string",
            "description": "The server's URL."
          }
        }
      },
      "ConnectMcpServerResponse": {
        "type": "object",
        "description": "Response from [`ConnectMcpServer`].",
        "required": [
          "url",
          "serverName",
          "alreadyConnected",
          "authenticated",
          "enabled",
          "summary"
        ],
        "properties": {
          "alreadyConnected": {
            "type": "boolean",
            "description": "Whether the user already had this server before the call."
          },
          "authenticated": {
            "type": "boolean",
            "description": "Whether the server holds the user's sign-in."
          },
          "enabled": {
            "type": "boolean",
            "description": "Whether the server's tools are turned on."
          },
          "serverName": {
            "type": "string",
            "description": "The server's display name."
          },
          "summary": {
            "type": "string",
            "description": "What happened and what the user still has to do."
          },
          "url": {
            "type": "string",
            "description": "The server's URL."
          }
        }
      },
      "ConnectedApp": {
        "type": "object",
        "description": "A connected app the session's agent may use.",
        "required": ["kind", "key", "name"],
        "properties": {
          "key": {
            "type": "string",
            "description": "The app's slug, or its custom server key."
          },
          "kind": {
            "$ref": "#/components/schemas/ConnectedAppKind",
            "description": "Which store the app comes from."
          },
          "name": {
            "type": "string",
            "description": "Display name, e.g. `Slack` or the owner's name for a custom server."
          }
        }
      },
      "ConnectedAppKind": {
        "type": "string",
        "description": "Which store a connected app comes from.",
        "enum": ["app", "custom"]
      },
      "ConnectedTool": {
        "type": "object",
        "description": "One tool a connected app serves.",
        "required": ["name", "inputSchema"],
        "properties": {
          "description": {
            "type": ["string", "null"],
            "description": "What the server says the tool does."
          },
          "inputSchema": {
            "type": "object",
            "description": "JSON Schema for the tool's arguments."
          },
          "name": {
            "type": "string",
            "description": "The tool's name on its server."
          }
        }
      },
      "ConnectedToolMatch": {
        "type": "object",
        "description": "One tool found by a search across the agent's connected apps.",
        "required": ["app", "tool"],
        "properties": {
          "app": {
            "$ref": "#/components/schemas/ConnectedApp",
            "description": "The app serving the tool."
          },
          "tool": {
            "$ref": "#/components/schemas/ConnectedTool",
            "description": "The tool."
          }
        }
      },
      "ConnectedToolResult": {
        "type": "object",
        "description": "A connected tool's answer: MCP's `CallToolResult`.",
        "required": ["isError", "content"],
        "properties": {
          "content": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "MCP content blocks, e.g. `{type: \"text\", text}`."
          },
          "isError": {
            "type": "boolean",
            "description": "The tool failed, or could not run; `content` says why."
          },
          "structuredContent": {
            "type": ["object", "null"],
            "description": "Structured output, for tools that declare an output schema."
          }
        }
      },
      "ConnectedToolSearch": {
        "type": "object",
        "description": "The best matches across the agent's connected apps, and the apps whose\ntools could not be listed, which the search did not cover.",
        "required": ["matches", "unsearched"],
        "properties": {
          "matches": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConnectedToolMatch"
            },
            "description": "At most [`MAX_TOOL_MATCHES`] tools, best first."
          },
          "unsearched": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConnectedApp"
            },
            "description": "Apps whose tools could not be listed."
          }
        }
      },
      "ConnectorTool": {
        "type": "object",
        "description": "An advertised action, not a tool loaded into the current turn.",
        "required": ["name", "description"],
        "properties": {
          "description": {
            "type": "string",
            "description": "What the action supports."
          },
          "name": {
            "type": "string",
            "description": "Upstream tool name."
          }
        }
      },
      "ControlRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AgentAction",
            "description": "The operation to perform."
          },
          {
            "type": "object",
            "properties": {
              "actionId": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/AgentActionId",
                    "description": "The id the caller already speculated this action under, when it has\none. Adopted as the accepted id, so a client that renders the action\noptimistically promotes that entry in place instead of retracting it\nand re-speculating under a server id. Re-sending the same id is not a\nsecond action: see [`ControlResponse`].\n\nNamed rather than flattened so it cannot collide with the action's own\nfields, which are tagged under `type`."
                  }
                ]
              },
              "context": {
                "type": ["object", "null"],
                "description": "Why the agent is being asked. Only a runtime forwarding a triggered\nprompt may send it; a user's request carrying it is refused."
              }
            }
          }
        ],
        "description": "Request body for a control operation on a live session.\n\nA wrapper around the operation rather than the bare enum so that fields\nwhich are about the request rather than the operation have somewhere to go.\nThe acting user is deliberately not one of them: it comes from the caller's\ncredentials, so that a caller cannot attribute an operation to someone else.\n\nClients serialize this, so both derives are used."
      },
      "ControlResponse": {
        "type": "object",
        "description": "Response body for a control operation.\n\nClients deserialize this, so both derives are used.",
        "required": ["actionId", "status"],
        "properties": {
          "actionId": {
            "$ref": "#/components/schemas/AgentActionId",
            "description": "Matches `requestId` on the folded message this action derives once it\ndispatches, and names the queue entry until then. The caller's own\n`actionId` when it supplied one; a freshly minted id otherwise."
          },
          "status": {
            "$ref": "#/components/schemas/ControlStatusDto",
            "description": "Whether the action went out or waits in the queue."
          }
        }
      },
      "ControlStatusDto": {
        "type": "string",
        "description": "What accepting a control operation did with it, on the wire.",
        "enum": ["sent", "queued"]
      },
      "ConversationTurnState": {
        "type": "string",
        "description": "The state of one source message, retained after completion for deduplication.",
        "enum": [
          "queued",
          "running",
          "succeeded",
          "failed",
          "stopped",
          "interrupted"
        ]
      },
      "CreateAgentSessionRequest": {
        "type": "object",
        "description": "Request body for `POST /agent-sessions`.\n\nCarries two shapes, told apart by `workspace`. Naming one asks for an\nexternal session: the runtime is the bot operator's, so the caller has to\nsay which bot and which directory, and must own that bot. Omitting it asks\nfor a managed session, whose runtime this deployment provisions. A managed\nrequest may select an authorized persisted persona with `botId`; omitting\nit uses the deployment's default coding persona, or Cursor when `repoUrl`\nis set. Fields describing someone else's runtime must still be omitted\nrather than quietly ignored. Mixing the two shapes is refused rather\nthan guessed at.\n\nClients serialize this, so both derives are used.",
        "properties": {
          "botId": {
            "type": ["string", "null"],
            "format": "uuid",
            "description": "Bot the session runs for. On a managed request this optionally selects\na persisted persona the user owns, may use through team membership, or\ncan `@` mention in a shared channel; omitting it uses the deployment's\ndefault coding persona, or Cursor when `repoUrl` is set. On an\nexternal request, bot callers may omit it (their own identity is used)\nand must not name another bot; user callers must supply a bot they own."
          },
          "id": {
            "type": ["string", "null"],
            "format": "uuid",
            "description": "Id to create the session under, minted by the caller. Lets a surface\nopen on the session's final id - URL, history row, references - the\nmoment the user acts, rather than after this request answers (which\nfor a managed sandbox can take a while). Omitted, the service mints\none. Answers 409 if a session already holds the id. On an external\nrequest it is how a runtime answering a composer request names the\nid it was handed, so the requester waiting on that id finds the session."
          },
          "instructions": {
            "type": ["string", "null"],
            "description": "Instructions the session's runtime works under, for its whole life.\n\nRecorded on the session whichever runtime serves it. Only the\nin-process one acts on them today; `agent_harness`'s `AgentKind`\nrecords what each of the others will need to."
          },
          "model": {
            "type": ["string", "null"],
            "description": "Model the managed session runs on, overriding the persona's. Managed\nsessions only: an external runtime picks its own.\n\nThe session's model from the moment it exists, which is what a caller\nchoosing one before the first prompt means. Selecting a model *during*\na session is a control action instead, and reads as one in its\ntranscript."
          },
          "owner": {
            "type": ["string", "null"],
            "description": "The user who owns the session. Ignored for user callers, who always\nown their own sessions, for harness callers, whose verified acting\nuser owns the session, and for bots that already act for a verified\nuser. A bot without one may name a user here. That claim is trusted\nfor the bot's own sessions. With no claim, a team bot owns the session\nitself only while non-user owners are enabled. Every other bot still\nneeds an owner."
          },
          "prompt": {
            "type": ["string", "null"],
            "description": "First prompt to deliver once the session is running. Managed sessions\nonly - an external runtime sends its own first prompt through the\ncontrol endpoint. Omitted, the session opens idle."
          },
          "promptActionId": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/AgentActionId",
                "description": "Id to deliver `prompt` under, minted by the caller so the prompt it\nalready shows is the row the log confirms. Requires `prompt`; omitted,\nthe service mints one."
              }
            ]
          },
          "promptAttachments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PromptAttachment"
            },
            "description": "Files `prompt` refers to, in the order the user attached them.\nRequires `prompt`."
          },
          "repoBranch": {
            "type": ["string", "null"],
            "description": "Starting branch for a managed coding session's selected repository.\nOmitted, the session starts on the repository's default branch."
          },
          "repoUrl": {
            "type": ["string", "null"],
            "description": "Explicit GitHub repository for a managed Cursor session, as one of the\nurls `GET /agent-repositories` lists for the caller. Access is checked\nfor the session owner. On a managed request that names no `botId`,\nthis starts the session as Cursor — the only managed persona that\nhonors a repository. For external sessions this is informational:\ncloning it is the runtime operator's job."
          },
          "thread": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/CreateSessionThread",
                "description": "The thread whose mention triggered the session, when one did.\nLinkage only - the mention's text is delivered by the runtime as the\nfirst prompt through the control endpoint, never through here."
              }
            ]
          },
          "workspace": {
            "type": ["string", "null"],
            "description": "Absolute directory the bot's harness runs in on its runtime. Present\nfor an external session, absent for a managed one, which runs in the\npath baked into its image."
          }
        }
      },
      "CreateAgentSessionResponse": {
        "type": "object",
        "description": "Response body for `POST /agent-sessions`.\n\nClients deserialize this, so both derives are used.",
        "required": ["session"],
        "properties": {
          "session": {
            "$ref": "#/components/schemas/AgentSessionResponse",
            "description": "The created session."
          }
        }
      },
      "CreateReview": {
        "allOf": [
          {
            "type": "object",
            "description": "The review's kind (email, calendar, import) and its drafts: 1–100\nSendEmail or CreateCalendarEvent arguments, or exactly one import\nplan selection."
          },
          {
            "type": "object",
            "required": ["title"],
            "properties": {
              "executionId": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/ExecutionId",
                    "description": "Optional code execution that prepared these drafts."
                  }
                ]
              },
              "title": {
                "type": "string",
                "description": "Stack label."
              }
            }
          }
        ],
        "description": "Review creation. Decoding it validates every draft; creating a review only\npresents the drafts, and the account holder acts separately."
      },
      "CreateSessionThread": {
        "type": "object",
        "description": "The triggering mention on a create request.\n\nClients serialize this, so both derives are used.",
        "required": ["messageId"],
        "properties": {
          "channelId": {
            "type": ["string", "null"],
            "format": "uuid",
            "description": "Channel the mentioning message was posted in. Runtimes built before\nmessage parents send this instead of `parent`."
          },
          "content": {
            "type": "string",
            "description": "The mention's text, quoted in the session's announcement."
          },
          "messageId": {
            "type": "string",
            "format": "uuid",
            "description": "The mentioning message."
          },
          "parent": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/MessageParent",
                "description": "Entity the mentioning message was posted in."
              }
            ]
          },
          "reuseOriginMessage": {
            "type": "boolean",
            "description": "Update the existing bot response reserved by a task assignment."
          },
          "threadId": {
            "type": ["string", "null"],
            "format": "uuid",
            "description": "Thread the session belongs to; defaults to the message itself, which\nis how a top-level mention roots its own thread."
          }
        }
      },
      "DecisionVia": {
        "type": "string",
        "description": "Surface of a review decision.",
        "enum": ["card", "chat", "inbox"]
      },
      "DiscoverAgentCapabilitiesRequest": {
        "type": "object",
        "description": "HTTP request selecting one provider to probe.",
        "required": ["harness"],
        "properties": {
          "harness": {
            "$ref": "#/components/schemas/CapabilityHarnessDto",
            "description": "Provider to probe."
          },
          "harnessId": {
            "type": ["string", "null"],
            "format": "uuid",
            "description": "Required for macrod and forbidden for other targets."
          },
          "model": {
            "type": ["string", "null"],
            "description": "Model whose session settings should be inspected."
          }
        }
      },
      "DiscoverAgentCapabilitiesResponse": {
        "type": "object",
        "description": "Successful capability-discovery response.",
        "required": ["configOptions"],
        "properties": {
          "configOptions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentConfigOptionDto"
            },
            "description": "Complete ordered ACP session configuration advertised by the agent."
          }
        }
      },
      "DiscoverConnectorsResponse": {
        "type": "object",
        "description": "Discovery metadata and optional markup for a user-controlled auth flow.",
        "required": ["result"],
        "properties": {
          "connect_markup": {
            "type": ["string", "null"],
            "description": "Include verbatim only if an advertised tool supports the requested task."
          },
          "result": {
            "$ref": "#/components/schemas/DiscoveryResult",
            "description": "Catalog or capability results."
          }
        }
      },
      "DiscoveredApp": {
        "type": "object",
        "description": "A verified app identity from the directory.",
        "required": ["app_slug", "name"],
        "properties": {
          "app_slug": {
            "type": "string",
            "description": "Exact identity to inspect or connect."
          },
          "description": {
            "type": ["string", "null"],
            "description": "Directory description; inspect tools to verify specific capabilities."
          },
          "name": {
            "type": "string",
            "description": "Human-readable app name."
          }
        }
      },
      "DiscoveryRequest": {
        "oneOf": [
          {
            "type": "object",
            "description": "Find connectable apps by name.",
            "required": ["query", "operation"],
            "properties": {
              "operation": {
                "type": "string",
                "enum": ["search"]
              },
              "query": {
                "type": "string",
                "description": "App name, e.g. \"Notion\" or \"Linear\", not a task description."
              }
            }
          },
          {
            "type": "object",
            "description": "Verify capabilities and connection status for one catalog app.",
            "required": ["app_slug", "operation"],
            "properties": {
              "app_slug": {
                "type": "string",
                "description": "Exact app slug from search results."
              },
              "operation": {
                "type": "string",
                "enum": ["inspect"]
              }
            }
          }
        ],
        "description": "Search by app name, then inspect a returned slug before recommending auth."
      },
      "DiscoveryResult": {
        "oneOf": [
          {
            "type": "object",
            "description": "Candidate apps; none has had its capabilities verified yet.",
            "required": ["apps", "more_results", "operation"],
            "properties": {
              "apps": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/DiscoveredApp"
                },
                "description": "Matching apps."
              },
              "more_results": {
                "type": "boolean",
                "description": "Narrow the app name if this is true."
              },
              "operation": {
                "type": "string",
                "enum": ["search"]
              }
            }
          },
          {
            "type": "object",
            "description": "Verified identity, capabilities and this caller's connection status.",
            "required": [
              "app",
              "connected",
              "tools",
              "tools_truncated",
              "operation"
            ],
            "properties": {
              "app": {
                "$ref": "#/components/schemas/DiscoveredApp",
                "description": "App from the directory."
              },
              "connected": {
                "type": "boolean",
                "description": "Whether this caller has an enabled connection. For an app that\nconnects through its own MCP server, that connection is checked\nthere, not in Pipedream."
              },
              "operation": {
                "type": "string",
                "enum": ["inspect"]
              },
              "tools": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ConnectorTool"
                },
                "description": "Advertised tools. Use SearchTools after connecting to load them."
              },
              "tools_truncated": {
                "type": "boolean",
                "description": "True when some advertised tools were omitted."
              }
            }
          }
        ],
        "description": "Discovery results never execute tools or change connections."
      },
      "DocumentId": {
        "type": "string",
        "description": "A validated document identifier. Historical document ids need not be UUIDs."
      },
      "EditQueuedActionRequest": {
        "type": "object",
        "description": "Request body for editing a queued prompt.",
        "required": ["prompt"],
        "properties": {
          "prompt": {
            "type": "string",
            "description": "The new raw prompt text, replacing the old wholesale. Never blank: a\nprompt with nothing to say is a removal, and there is an endpoint for\nthat.",
            "minLength": 1
          }
        }
      },
      "ElicitationAnswer": {
        "oneOf": [
          {
            "type": "object",
            "description": "The user submitted the form, or consented to open the URL.",
            "required": ["action"],
            "properties": {
              "action": {
                "type": "string",
                "enum": ["accept"]
              },
              "content": {
                "type": ["object", "null"],
                "description": "Form: the submitted values keyed by property. URL: omitted.",
                "additionalProperties": {
                  "$ref": "#/components/schemas/ElicitationContentValue"
                },
                "propertyNames": {
                  "type": "string"
                }
              }
            }
          },
          {
            "type": "object",
            "description": "The user explicitly said no.",
            "required": ["action"],
            "properties": {
              "action": {
                "type": "string",
                "enum": ["decline"]
              }
            }
          },
          {
            "type": "object",
            "description": "The user dismissed the request without choosing.",
            "required": ["action"],
            "properties": {
              "action": {
                "type": "string",
                "enum": ["cancel"]
              }
            }
          }
        ],
        "description": "What the user decided about an elicitation. Mirrors ACP's three actions;\nthere is no `Other` because we never originate an action we do not know."
      },
      "ElicitationContentValue": {
        "oneOf": [
          {
            "type": "string",
            "description": "A string, and the shape a whole draft rides in as JSON text."
          },
          {
            "type": "boolean",
            "description": "A yes/no."
          },
          {
            "type": "integer",
            "format": "int64",
            "description": "A whole number."
          },
          {
            "type": "number",
            "format": "double",
            "description": "A number that is not whole."
          },
          {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "A multi-select's chosen values."
          }
        ],
        "description": "A value ACP accepts in an elicitation answer.\n\nMirrors ACP's `ElicitationContentValue` so that the contract a caller\nanswers against is the closed union ACP will accept, rather than arbitrary\nJSON narrowed on the way out. An object, a null, or a mixed array is\nrefused when the request is deserialized - where the caller learns of it -\ninstead of at send time, when the elicitation slot has already been\nreleased."
      },
      "ElicitationRequestId": {
        "oneOf": [
          {
            "type": "integer",
            "format": "int64",
            "description": "A numeric JSON-RPC id. Specta refuses `i64` (it does not fit a JS\nnumber); agents count their requests from zero, so `i32` is the\nhonest TypeScript face."
          },
          {
            "type": "string",
            "description": "A string JSON-RPC id."
          }
        ],
        "description": "The JSON-RPC id of an agent's `elicitation/create` request, carried whole\nso the answer echoes exactly what the agent sent.\n\nAgents pick these, not us: Claude Code counts from `0`, others use\nstrings. `null` is not a legal id for a request that expects a response,\nso it is not representable here."
      },
      "EmailSearchSuggestions": {
        "type": "object",
        "description": "Email search exposes importance and connected inbox addresses, not sender filters.",
        "required": ["inboxes"],
        "properties": {
          "importance": {
            "type": ["string", "null"],
            "description": "Explicit importance wording, resolved by the client."
          },
          "inboxes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Explicit connected inbox addresses, resolved by the client."
          },
          "query": {
            "type": ["string", "null"],
            "description": "Remaining keyword phrase."
          }
        },
        "additionalProperties": false
      },
      "EmailSuggestions": {
        "type": "object",
        "description": "Editable fields for email inference, before submission and identity resolution.",
        "properties": {
          "bcc": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Explicit blind-carbon-copy recipient names or supplied email addresses."
          },
          "body": {
            "type": ["string", "null"],
            "description": "Suggested Markdown content or outgoing message body."
          },
          "cc": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Explicit carbon-copy recipient names or supplied email addresses."
          },
          "recipients": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Person or channel names for the client to resolve."
          },
          "subject": {
            "type": ["string", "null"],
            "description": "Suggested outgoing email subject."
          }
        },
        "additionalProperties": false
      },
      "EntityType": {
        "type": "string",
        "description": "The type of an entity in Macro",
        "enum": [
          "user",
          "chat",
          "channel",
          "channel_message",
          "document",
          "project",
          "email_thread",
          "calendar_event",
          "team",
          "call",
          "foreign_entity",
          "static_file",
          "crm_company",
          "crm_contact",
          "crm_pipeline",
          "reminder",
          "skill",
          "agent_session",
          "scheduled_action",
          "initiative",
          "database",
          "database_row",
          "form",
          "external_chat"
        ]
      },
      "ExecutionActivity": {
        "type": "object",
        "description": "A bounded SDK operation observed during execution; not an authorization or write receipt.",
        "required": ["id", "label", "status"],
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Request identity within the execution.",
            "minimum": 0
          },
          "label": {
            "type": "string",
            "description": "Server-selected label from the generated operation catalog."
          },
          "status": {
            "$ref": "#/components/schemas/RecordedCallStatus",
            "description": "Observed request state; unfinished operations have unknown outcomes."
          }
        }
      },
      "ExecutionId": {
        "type": "string",
        "format": "uuid",
        "description": "Caller-selected UUID persisted in tool input before execution begins."
      },
      "ExecutionRecord": {
        "type": "object",
        "description": "Durable source and final outcome, with historical bridge calls when present.\nThe full journal is not included in the model's tool result.",
        "required": ["executionId", "source", "status", "calls"],
        "properties": {
          "actingAs": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/ToolActor",
                "description": "Account choice bound to this saved execution; absent on historical records."
              }
            ]
          },
          "activity": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ExecutionActivity"
            },
            "description": "Advisory SDK operation activity, without arguments or response contents."
          },
          "activityTruncated": {
            "type": "boolean",
            "description": "Additional request activity was omitted at the bounded observation limit."
          },
          "calls": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RecordedToolCall"
            },
            "description": "Historical bridge calls. Direct HTTP executions leave this empty."
          },
          "error": {
            "type": ["string", "null"],
            "description": "Safe execution failure text."
          },
          "executionId": {
            "$ref": "#/components/schemas/ExecutionId",
            "description": "Execution identity."
          },
          "result": {
            "description": "JSON returned by the program, if successful."
          },
          "source": {
            "type": "string",
            "description": "The submitted JavaScript module."
          },
          "status": {
            "$ref": "#/components/schemas/ExecutionStatus",
            "description": "Overall execution state."
          },
          "turnId": {
            "type": ["string", "null"],
            "format": "uuid",
            "description": "Original turn, preventing another requester from replaying a saved result."
          }
        }
      },
      "ExecutionStatus": {
        "type": "string",
        "description": "The recorded outcome of a program.",
        "enum": ["running", "succeeded", "failed", "cancelled", "timed_out"]
      },
      "ExternalSessionResponse": {
        "type": "object",
        "description": "The provider-side identity of an externally-served session.",
        "required": ["provider"],
        "properties": {
          "name": {
            "type": ["string", "null"],
            "description": "The provider's display name for the agent, when it reported one."
          },
          "provider": {
            "type": "string",
            "description": "Which provider serves the session, e.g. `cursor`."
          },
          "url": {
            "type": ["string", "null"],
            "description": "The agent's page on the provider's site, for a client to link out to."
          }
        }
      },
      "ExtractInputRequest": {
        "type": "object",
        "description": "Draft snapshot and local context used to suggest editable destination fields.",
        "required": [
          "text",
          "intent",
          "revision",
          "reference_time",
          "time_zone"
        ],
        "properties": {
          "intent": {
            "$ref": "#/components/schemas/InputIntent",
            "description": "Destination whose fields should be extracted."
          },
          "property_definitions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InputPropertyDefinition"
            },
            "description": "Available task fields and display values, never authorized entity IDs."
          },
          "reference_time": {
            "type": "string",
            "format": "date-time",
            "description": "Reference instant for interpreting relative dates."
          },
          "revision": {
            "type": "integer",
            "format": "int32",
            "description": "Opaque client revision used to discard stale suggestions.",
            "minimum": 0
          },
          "search_type": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/SearchType",
                "description": "Explicitly selected search type; absent means infer it before extracting filters."
              }
            ]
          },
          "text": {
            "type": "string",
            "description": "Original draft text; inference must not execute its instructions."
          },
          "time_zone": {
            "type": "string",
            "description": "IANA timezone for interpreting local dates and clock times."
          }
        }
      },
      "ExtractInputResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/InputSuggestions",
            "description": "Destination and applicable editable fields, encoded together."
          },
          {
            "type": "object",
            "required": ["revision"],
            "properties": {
              "revision": {
                "type": "integer",
                "format": "int32",
                "description": "Revision echoed from the extraction request.",
                "minimum": 0
              }
            }
          }
        ],
        "description": "Validated suggestions for a particular client draft revision."
      },
      "FileChangeKindDto": {
        "type": "string",
        "description": "What happened to a file, on the wire.",
        "enum": ["added", "modified", "deleted", "renamed"]
      },
      "GitRefDto": {
        "type": "object",
        "description": "One end of the compared range.",
        "properties": {
          "name": {
            "type": ["string", "null"],
            "description": "The branch name, when known."
          },
          "sha": {
            "type": ["string", "null"],
            "description": "The commit, when known."
          }
        }
      },
      "InputIntent": {
        "type": "string",
        "description": "A destination the composer can prepare, but never execute through inference.",
        "enum": ["ai", "search", "email", "note", "task", "calendar", "message"]
      },
      "InputPropertyDefinition": {
        "type": "object",
        "description": "A task property and the display values available for extraction.",
        "required": ["name"],
        "properties": {
          "name": {
            "type": "string",
            "description": "Property display name from the client's catalog."
          },
          "options": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Allowed display values; an empty list permits free-text suggestions."
          }
        }
      },
      "InputPropertySuggestion": {
        "type": "object",
        "description": "Suggested display values to resolve against a real task-property catalog.",
        "required": ["name", "values"],
        "properties": {
          "name": {
            "type": "string",
            "description": "Property display name, never an authorized identifier."
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Suggested display values, never authorized entity identifiers."
          }
        },
        "additionalProperties": false
      },
      "InputSuggestions": {
        "oneOf": [
          {
            "type": "object",
            "description": "Editable ai fields.",
            "required": ["suggestions", "intent"],
            "properties": {
              "intent": {
                "type": "string",
                "enum": ["ai"]
              },
              "suggestions": {
                "$ref": "#/components/schemas/AiSuggestions",
                "description": "Editable ai fields."
              }
            }
          },
          {
            "type": "object",
            "description": "Editable search fields.",
            "required": ["suggestions", "intent"],
            "properties": {
              "intent": {
                "type": "string",
                "enum": ["search"]
              },
              "suggestions": {
                "$ref": "#/components/schemas/SearchSuggestions",
                "description": "Editable search fields."
              }
            }
          },
          {
            "type": "object",
            "description": "Editable email fields.",
            "required": ["suggestions", "intent"],
            "properties": {
              "intent": {
                "type": "string",
                "enum": ["email"]
              },
              "suggestions": {
                "$ref": "#/components/schemas/EmailSuggestions",
                "description": "Editable email fields."
              }
            }
          },
          {
            "type": "object",
            "description": "Editable note fields.",
            "required": ["suggestions", "intent"],
            "properties": {
              "intent": {
                "type": "string",
                "enum": ["note"]
              },
              "suggestions": {
                "$ref": "#/components/schemas/NoteSuggestions",
                "description": "Editable note fields."
              }
            }
          },
          {
            "type": "object",
            "description": "Editable task fields.",
            "required": ["suggestions", "intent"],
            "properties": {
              "intent": {
                "type": "string",
                "enum": ["task"]
              },
              "suggestions": {
                "$ref": "#/components/schemas/TaskSuggestions",
                "description": "Editable task fields."
              }
            }
          },
          {
            "type": "object",
            "description": "Editable calendar fields.",
            "required": ["suggestions", "intent"],
            "properties": {
              "intent": {
                "type": "string",
                "enum": ["calendar"]
              },
              "suggestions": {
                "$ref": "#/components/schemas/CalendarSuggestions",
                "description": "Editable calendar fields."
              }
            }
          },
          {
            "type": "object",
            "description": "Editable message fields.",
            "required": ["suggestions", "intent"],
            "properties": {
              "intent": {
                "type": "string",
                "enum": ["message"]
              },
              "suggestions": {
                "$ref": "#/components/schemas/MessageSuggestions",
                "description": "Editable message fields."
              }
            }
          }
        ],
        "description": "A single inferred destination together with only its applicable fields."
      },
      "IntentScore": {
        "type": "object",
        "description": "Independent yes/no probabilities; these do not sum to one.",
        "required": ["intent", "score"],
        "properties": {
          "intent": {
            "$ref": "#/components/schemas/InputIntent",
            "description": "Destination evaluated by the classifier."
          },
          "score": {
            "type": "number",
            "format": "float",
            "description": "Independent probability between zero and one."
          }
        }
      },
      "Lineage": {
        "oneOf": [
          {
            "type": "object",
            "description": "The session the agent acted from, and so where the chain started.",
            "required": ["session", "root", "type"],
            "properties": {
              "root": {
                "$ref": "#/components/schemas/Root",
                "description": "The first non-agent cause of its work."
              },
              "session": {
                "type": "string",
                "format": "uuid",
                "description": "The acting session."
              },
              "type": {
                "type": "string",
                "enum": ["session"]
              }
            }
          },
          {
            "type": "object",
            "description": "An agent acted, but its session was not captured.",
            "required": ["type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["unattributed"]
              }
            }
          }
        ],
        "description": "Where an acting agent's work came from."
      },
      "LinkShare": {
        "type": "string",
        "description": "Defines who can access an item through its share link.",
        "enum": ["PUBLIC", "TEAM"]
      },
      "LoadAgentModelsRequest": {
        "type": "object",
        "description": "HTTP request selecting one provider to probe.",
        "required": ["harness"],
        "properties": {
          "harness": {
            "$ref": "#/components/schemas/ModelHarnessDto",
            "description": "Provider to probe."
          },
          "harnessId": {
            "type": ["string", "null"],
            "format": "uuid",
            "description": "Required for macrod and forbidden for other targets."
          }
        }
      },
      "LoadAgentModelsResponse": {
        "type": "object",
        "description": "Successful model-discovery response.",
        "required": ["status", "models"],
        "properties": {
          "currentModel": {
            "type": ["string", "null"],
            "description": "Current provider model, if model selection is available."
          },
          "models": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentModelDto"
            },
            "description": "Ordered model catalog."
          },
          "status": {
            "$ref": "#/components/schemas/AgentModelsStatusDto",
            "description": "Model-selection availability."
          }
        }
      },
      "LogDirectionDto": {
        "type": "string",
        "description": "Which way a logged frame travelled, mirroring [`Message`]'s discriminant.",
        "enum": ["notification", "to_server", "to_runtime"]
      },
      "LogFrameDto": {
        "type": "object",
        "description": "The two fields [`AgentSessionLogEntryDto`] flattens in.\n\nSchema only. Nothing constructs one: the entry serializes through\n[`Message`], and this exists so the generated clients see `direction` and\n`content` as named fields instead of an open map. A hand-built copy could\ndrift from the fold's wire format, and the point of the endpoint is that it\ncannot - so this describes that format without being able to produce it.",
        "required": ["direction", "content"],
        "properties": {
          "content": {
            "type": "object",
            "description": "The protocol envelope, verbatim. Opaque here: it is Agent Runtime\nProtocol, whose shape belongs to the fold rather than this endpoint."
          },
          "direction": {
            "$ref": "#/components/schemas/LogDirectionDto",
            "description": "Which way the frame travelled."
          }
        }
      },
      "MacroUserIdStr": {
        "type": "string"
      },
      "MessageParent": {
        "oneOf": [
          {
            "type": "object",
            "description": "A channel, including direct messages.",
            "required": ["id", "type"],
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "A channel, including direct messages."
              },
              "type": {
                "type": "string",
                "enum": ["channel"]
              }
            }
          },
          {
            "type": "object",
            "description": "A document, including tasks and PDFs.",
            "required": ["id", "type"],
            "properties": {
              "id": {
                "$ref": "#/components/schemas/DocumentId",
                "description": "A document, including tasks and PDFs."
              },
              "type": {
                "type": "string",
                "enum": ["document"]
              }
            }
          },
          {
            "type": "object",
            "description": "An initiative, presented as a project in the application.",
            "required": ["id", "type"],
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "An initiative, presented as a project in the application."
              },
              "type": {
                "type": "string",
                "enum": ["initiative"]
              }
            }
          },
          {
            "type": "object",
            "description": "A CRM company.",
            "required": ["id", "type"],
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "A CRM company."
              },
              "type": {
                "type": "string",
                "enum": ["crm_company"]
              }
            }
          },
          {
            "type": "object",
            "description": "A CRM contact.",
            "required": ["id", "type"],
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "A CRM contact."
              },
              "type": {
                "type": "string",
                "enum": ["crm_contact"]
              }
            }
          },
          {
            "type": "object",
            "description": "A video call and its persistent chat thread.",
            "required": ["id", "type"],
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "A video call and its persistent chat thread."
              },
              "type": {
                "type": "string",
                "enum": ["call"]
              }
            }
          }
        ],
        "description": "The entity whose permissions and lifecycle govern a message."
      },
      "MessageSuggestions": {
        "type": "object",
        "description": "Editable fields for message inference, before submission and identity resolution.",
        "properties": {
          "body": {
            "type": ["string", "null"],
            "description": "Suggested Markdown content or outgoing message body."
          },
          "recipients": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Person or channel names for the client to resolve."
          }
        },
        "additionalProperties": false
      },
      "ModelHarnessDto": {
        "type": "string",
        "description": "Harness names accepted by the model discovery endpoint.",
        "enum": ["in-memory", "cursor", "macrod"]
      },
      "MonthlyWeekday": {
        "type": "object",
        "description": "Monthly ordinal weekday, such as the first Friday.",
        "required": ["ordinal", "weekday"],
        "properties": {
          "ordinal": {
            "type": "integer",
            "format": "int32",
            "description": "One through five, or minus one for last."
          },
          "weekday": {
            "$ref": "#/components/schemas/WeekdayCode",
            "description": "Weekday selected by the ordinal."
          }
        },
        "additionalProperties": false
      },
      "NoteSuggestions": {
        "type": "object",
        "description": "Editable fields for note inference, before submission and identity resolution.",
        "properties": {
          "body": {
            "type": ["string", "null"],
            "description": "Suggested Markdown content or outgoing message body."
          },
          "title": {
            "type": ["string", "null"],
            "description": "Suggested note, task, or event title."
          }
        },
        "additionalProperties": false
      },
      "PermissionAnswer": {
        "oneOf": [
          {
            "type": "object",
            "description": "One of the options the agent offered was chosen.",
            "required": ["optionId", "kind"],
            "properties": {
              "kind": {
                "type": "string",
                "enum": ["selected"]
              },
              "optionId": {
                "type": "string",
                "description": "The chosen option's id, as the agent listed it."
              }
            }
          },
          {
            "type": "object",
            "description": "The request was dismissed without choosing.",
            "required": ["kind"],
            "properties": {
              "kind": {
                "type": "string",
                "enum": ["cancelled"]
              }
            }
          }
        ],
        "description": "The decision carried by an [`AgentPermissionAction`]."
      },
      "PresentView": {
        "type": "object",
        "description": "A view to present.",
        "required": ["view"],
        "properties": {
          "executionId": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/ExecutionId",
                "description": "The code execution presenting it, when one does."
              }
            ]
          },
          "view": {
            "type": "object",
            "description": "A dynamic-UI view, in the format of the PresentView schema in\nExecuteCode's description."
          }
        },
        "additionalProperties": false
      },
      "PreviewAgentSessionsRequest": {
        "type": "object",
        "description": "Request body for `POST /agent-sessions/preview`.\n\nClients serialize this, so both derives are used.",
        "required": ["sessionIds"],
        "properties": {
          "sessionIds": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The sessions to preview. Duplicates are collapsed server-side; at most\n[`MAX_PREVIEW_SESSION_IDS`](crate::domain::model::MAX_PREVIEW_SESSION_IDS)\ndistinct ids per request."
          }
        }
      },
      "PreviewAgentSessionsResponse": {
        "type": "object",
        "description": "Response body for `POST /agent-sessions/preview`: one entry per distinct\nrequested id, in no particular order.\n\nClients deserialize this, so both derives are used.",
        "required": ["previews"],
        "properties": {
          "previews": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgentSessionPreviewDto"
            },
            "description": "What the caller may see of each requested session."
          }
        }
      },
      "PromptAttachment": {
        "type": "object",
        "description": "A file the prompt refers to, by where the agent can fetch it.\n\nMirrors ACP's `resource_link` content block, which every agent must\naccept: bytes never ride the prompt, only a URI (a static file service URL\nin practice) with enough metadata for a client to render a chip and for\nthe agent to decide whether to fetch it. Keeping the wire shape ACP-native\nmeans the harness translates without resolving anything, and the fold\nreads the same fields back off the logged frame.",
        "required": ["uri", "name"],
        "properties": {
          "mimeType": {
            "type": ["string", "null"],
            "description": "The file's media type, when known."
          },
          "name": {
            "type": "string",
            "description": "Display name, typically the original file name."
          },
          "size": {
            "type": ["integer", "null"],
            "format": "int64",
            "description": "Size in bytes, when known."
          },
          "uri": {
            "type": "string",
            "description": "Where the agent can fetch the file."
          }
        }
      },
      "PullRequestLinkSource": {
        "type": "string",
        "description": "Who associated a pull request with a session.",
        "enum": ["agent", "user"]
      },
      "PullRequestLinkedSession": {
        "type": "object",
        "description": "A session linked to a pull request, as a viewer of that session sees it.",
        "required": ["sessionId", "source"],
        "properties": {
          "originMessageId": {
            "type": ["string", "null"],
            "format": "uuid",
            "description": "The message that started the session, such as an @mention, when it was\nstarted from a thread. A mention inside a thread is that reply, not the root."
          },
          "sessionId": {
            "type": "string",
            "format": "uuid",
            "description": "The session id."
          },
          "source": {
            "$ref": "#/components/schemas/PullRequestLinkSource",
            "description": "Who associated the pull request with the session."
          },
          "threadParent": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/MessageParent",
                "description": "The channel, task, or CRM record whose thread the session was started from, if any."
              }
            ]
          }
        }
      },
      "PullRequestSessions": {
        "type": "object",
        "description": "The sessions linked to one pull request that the caller can view.",
        "required": ["url", "githubKey", "sessions"],
        "properties": {
          "githubKey": {
            "type": "string",
            "description": "The pull request's `owner/repo/pull/number` key."
          },
          "sessions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PullRequestLinkedSession"
            },
            "description": "Linked sessions the caller can view, oldest link first."
          },
          "url": {
            "type": "string",
            "description": "The requested pull request URL, canonicalized."
          }
        }
      },
      "PullRequestSessionsResponse": {
        "type": "object",
        "description": "The sessions associated with a pull request.",
        "required": ["sessionIds"],
        "properties": {
          "sessionIds": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Sessions associated with the pull request that the caller can view."
          }
        }
      },
      "PullRequestUrl": {
        "type": "object",
        "description": "A GitHub pull request, by URL.",
        "required": ["url"],
        "properties": {
          "url": {
            "type": "string",
            "description": "The pull request's GitHub URL, such as `https://github.com/owner/repo/pull/12`."
          }
        }
      },
      "PullRequestUrls": {
        "type": "object",
        "description": "GitHub pull requests, by URL.",
        "required": ["urls"],
        "properties": {
          "urls": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Pull request GitHub URLs, at most 100."
          }
        }
      },
      "PullRequestsSessionsResponse": {
        "type": "object",
        "description": "The sessions associated with each requested pull request.",
        "required": ["pullRequests"],
        "properties": {
          "pullRequests": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PullRequestSessions"
            },
            "description": "One entry per requested pull request, in request order."
          }
        }
      },
      "QuerySearchSuggestions": {
        "type": "object",
        "description": "A topic for search types without additional supported facets.",
        "properties": {
          "query": {
            "type": ["string", "null"],
            "description": "Remaining keyword phrase after supported filters and instructions."
          }
        },
        "additionalProperties": false
      },
      "QueuedActionDto": {
        "type": "object",
        "description": "One action waiting in a session's queue.\n\nClients deserialize this, so both derives are used.",
        "required": ["actionId", "kind", "createdAt"],
        "properties": {
          "actionId": {
            "$ref": "#/components/schemas/AgentActionId",
            "description": "The id the action was accepted under."
          },
          "actorUserId": {
            "type": ["string", "null"],
            "description": "The user who queued it, absent when a bot acted on nobody's behalf."
          },
          "attachments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PromptAttachment"
            },
            "description": "Files the prompt refers to, for prompts only. Kept through an edit,\nwhich replaces the text alone."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When it was accepted."
          },
          "kind": {
            "type": "string",
            "description": "What kind of action waits - `prompt` or `compact`; only\nturn-occupying actions are ever queued."
          },
          "prompt": {
            "type": ["string", "null"],
            "description": "The prompt's raw text, present for prompts only. What an edit\nreplaces."
          }
        }
      },
      "RecordedCallStatus": {
        "type": "string",
        "description": "A dispatch result; unfinished work is never reported as success.",
        "enum": ["running", "completed", "failed", "unknown"]
      },
      "RecordedToolCall": {
        "type": "object",
        "description": "A real inner call, recorded by trusted dispatch for the existing renderers.",
        "required": ["id", "name", "input", "outputOmitted", "status"],
        "properties": {
          "error": {
            "type": ["string", "null"],
            "description": "Safe tool failure, if one was returned."
          },
          "id": {
            "type": "string",
            "description": "Stable, execution-scoped component identity."
          },
          "input": {
            "description": "Arguments passed to the actual tool."
          },
          "name": {
            "type": "string",
            "description": "Canonical Macro tool name from the allowlisted registry."
          },
          "output": {
            "description": "Original tool output, retained independently of the program's return value."
          },
          "outputOmitted": {
            "type": "boolean",
            "description": "Whether the response was omitted to keep the durable journal bounded."
          },
          "status": {
            "$ref": "#/components/schemas/RecordedCallStatus",
            "description": "A started call that never replied has an unknown side-effect outcome."
          }
        }
      },
      "RecurrenceEnd": {
        "oneOf": [
          {
            "type": "object",
            "description": "No ending condition.",
            "required": ["kind"],
            "properties": {
              "kind": {
                "type": "string",
                "enum": ["never"]
              }
            }
          },
          {
            "type": "object",
            "description": "Explicit occurrence limit.",
            "required": ["count", "kind"],
            "properties": {
              "count": {
                "type": "integer",
                "format": "int32",
                "description": "Positive occurrence count.",
                "minimum": 0
              },
              "kind": {
                "type": "string",
                "enum": ["after"]
              }
            }
          },
          {
            "type": "object",
            "description": "Inclusive local ISO date.",
            "required": ["date", "kind"],
            "properties": {
              "date": {
                "type": "string",
                "description": "Date resolved against the request's clock and timezone."
              },
              "kind": {
                "type": "string",
                "enum": ["on"]
              }
            }
          }
        ],
        "description": "Resolved recurrence ending condition accepted by the shared calendar editor."
      },
      "RecurrenceFrequency": {
        "type": "string",
        "description": "Repetition units supported by the shared calendar editor.",
        "enum": ["DAILY", "WEEKLY", "MONTHLY", "YEARLY"]
      },
      "RecurrenceSuggestion": {
        "type": "object",
        "description": "Resolved, editable repetition values; the existing calendar serializer builds RRULEs.",
        "required": ["frequency", "interval", "by_day", "ends"],
        "properties": {
          "by_day": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WeekdayCode"
            },
            "description": "Weekly weekday selectors."
          },
          "ends": {
            "$ref": "#/components/schemas/RecurrenceEnd",
            "description": "Resolved ending condition."
          },
          "frequency": {
            "$ref": "#/components/schemas/RecurrenceFrequency",
            "description": "Repetition unit."
          },
          "interval": {
            "type": "integer",
            "format": "int32",
            "description": "Positive interval.",
            "minimum": 0
          },
          "monthly_by_day": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/MonthlyWeekday",
                "description": "Monthly ordinal weekday, if explicitly supplied."
              }
            ]
          }
        }
      },
      "RenameAgentSessionRequest": {
        "type": "object",
        "description": "Request body for renaming an agent session.",
        "required": ["name"],
        "properties": {
          "name": {
            "type": "string",
            "description": "New user-facing name. Leading and trailing whitespace is discarded."
          }
        }
      },
      "RetryAgentConversationTurnRequest": {
        "type": "object",
        "description": "The attempt the user saw and chose to retry; prevents double-click reruns.",
        "required": ["actionId"],
        "properties": {
          "actionId": {
            "type": "string",
            "format": "uuid",
            "description": "Current failed attempt identity."
          }
        }
      },
      "ReviewDecision": {
        "oneOf": [
          {
            "type": "object",
            "description": "Save one edited draft.",
            "required": ["revision", "item", "draft", "action"],
            "properties": {
              "action": {
                "type": "string",
                "enum": ["edit"]
              },
              "draft": {
                "type": "object",
                "description": "Replacement action arguments, keyed by the review's kind."
              },
              "item": {
                "type": "string",
                "format": "uuid",
                "description": "Pending item to update."
              },
              "revision": {
                "type": "integer",
                "format": "int64",
                "description": "Revision displayed by the caller."
              }
            }
          },
          {
            "type": "object",
            "description": "Send/create selected items, or all pending items when empty.",
            "required": ["revision", "items", "action"],
            "properties": {
              "action": {
                "type": "string",
                "enum": ["submit"]
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "Pending items, or an empty list to select all pending items."
              },
              "revision": {
                "type": "integer",
                "format": "int64",
                "description": "Revision displayed by the caller."
              }
            }
          },
          {
            "type": "object",
            "description": "Dismiss selected pending items, or all pending items when empty.",
            "required": ["revision", "items", "action"],
            "properties": {
              "action": {
                "type": "string",
                "enum": ["dismiss"]
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "uuid"
                },
                "description": "Pending items, or an empty list to select all pending items."
              },
              "revision": {
                "type": "integer",
                "format": "int64",
                "description": "Revision displayed by the caller."
              }
            }
          }
        ],
        "description": "One atomic user decision against the displayed revision."
      },
      "ReviewDecisionContext": {
        "type": "object",
        "description": "Facts about the most recent account-holder decision.",
        "required": ["by", "via", "revision", "items"],
        "properties": {
          "by": {
            "type": "string",
            "description": "Authenticated account holder."
          },
          "items": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Items selected by this decision."
          },
          "revision": {
            "type": "integer",
            "format": "int64",
            "description": "Revision claimed by this batch, used in notification deduplication."
          },
          "via": {
            "$ref": "#/components/schemas/DecisionVia",
            "description": "Entry surface."
          }
        }
      },
      "ReviewId": {
        "type": "string",
        "format": "uuid",
        "description": "Persisted review identity."
      },
      "ReviewRecord": {
        "allOf": [
          {
            "type": "object",
            "description": "Component kind, drafts and per-item outcomes."
          },
          {
            "type": "object",
            "required": [
              "id",
              "sessionId",
              "actingUser",
              "title",
              "revision",
              "updatedAt"
            ],
            "properties": {
              "actingUser": {
                "type": "string",
                "description": "Account whose email/calendar the drafts use."
              },
              "decision": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/ReviewDecisionContext",
                    "description": "Current batch's authenticated decision, preserved for interrupted work."
                  }
                ]
              },
              "executionId": {
                "oneOf": [
                  {
                    "type": "null"
                  },
                  {
                    "$ref": "#/components/schemas/ExecutionId",
                    "description": "Originating code execution, absent for directly presented reviews."
                  }
                ]
              },
              "id": {
                "$ref": "#/components/schemas/ReviewId",
                "description": "Review identity."
              },
              "presentedAt": {
                "type": ["integer", "null"],
                "format": "int64",
                "description": "Durable presentation acknowledgment, separate from user decisions."
              },
              "revision": {
                "type": "integer",
                "format": "int64",
                "description": "Compare-and-swap revision for edits and submissions."
              },
              "sessionId": {
                "type": "string",
                "format": "uuid",
                "description": "Owning session."
              },
              "title": {
                "type": "string",
                "description": "Stack label."
              },
              "updatedAt": {
                "type": "integer",
                "format": "int64",
                "description": "Milliseconds since epoch of the last state change."
              }
            }
          }
        ],
        "description": "Full UI record, fetched outside the model context."
      },
      "Root": {
        "oneOf": [
          {
            "type": "object",
            "description": "A person.",
            "required": ["user", "type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["person"]
              },
              "user": {
                "$ref": "#/components/schemas/MacroUserIdStr",
                "description": "Who."
              }
            }
          },
          {
            "type": "object",
            "description": "A routine.",
            "required": ["routine", "type"],
            "properties": {
              "routine": {
                "type": "string",
                "format": "uuid",
                "description": "The routine."
              },
              "type": {
                "type": "string",
                "enum": ["routine"]
              }
            }
          }
        ],
        "description": "The first non-agent cause. An agent cannot be one, so a chain always ends\nat a person or a routine."
      },
      "RoutineCause": {
        "oneOf": [
          {
            "type": "object",
            "description": "One of its schedules came due.",
            "required": ["type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["scheduled"]
              }
            }
          },
          {
            "type": "object",
            "description": "Its owner started it by hand.",
            "required": ["type"],
            "properties": {
              "type": {
                "type": "string",
                "enum": ["manual"]
              }
            }
          },
          {
            "type": "object",
            "description": "An event it watches happened.",
            "required": ["event_id", "type"],
            "properties": {
              "event_id": {
                "type": "string",
                "format": "uuid",
                "description": "The event."
              },
              "type": {
                "type": "string",
                "enum": ["event"]
              }
            }
          }
        ],
        "description": "What made a routine fire."
      },
      "SandboxSize": {
        "type": "string",
        "description": "Named compute tier for a managed sandbox.\n\nThe API and database store the name. CPU, RAM, and disk live in\n`crates/agent_harness/sandbox_sizes.json`.",
        "enum": ["small", "default", "large"]
      },
      "SandboxSizeBody": {
        "type": "object",
        "description": "Request or response body for a named sandbox size.",
        "required": ["size"],
        "properties": {
          "size": {
            "$ref": "#/components/schemas/SandboxSize",
            "description": "Named compute tier."
          }
        }
      },
      "SearchSuggestions": {
        "oneOf": [
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/QuerySearchSuggestions",
                "description": "Query across content types."
              },
              {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["all"]
                  }
                }
              }
            ],
            "description": "Query across content types."
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/ChannelSearchSuggestions",
                "description": "Message topic, senders and channels."
              },
              {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["channels"]
                  }
                }
              }
            ],
            "description": "Message topic, senders and channels."
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/QuerySearchSuggestions",
                "description": "Document or file topic."
              },
              {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["document-or-file"]
                  }
                }
              }
            ],
            "description": "Document or file topic."
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/TaskSearchSuggestions",
                "description": "Task topic and supported task facets."
              },
              {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["task"]
                  }
                }
              }
            ],
            "description": "Task topic and supported task facets."
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/EmailSearchSuggestions",
                "description": "Email topic, importance and inbox addresses."
              },
              {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["email"]
                  }
                }
              }
            ],
            "description": "Email topic, importance and inbox addresses."
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/CallSearchSuggestions",
                "description": "Call topic, speakers, channels and attendance."
              },
              {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["calls"]
                  }
                }
              }
            ],
            "description": "Call topic, speakers, channels and attendance."
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/QuerySearchSuggestions",
                "description": "Folder topic."
              },
              {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["folders"]
                  }
                }
              }
            ],
            "description": "Folder topic."
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/QuerySearchSuggestions",
                "description": "AI conversation topic."
              },
              {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["agent"]
                  }
                }
              }
            ],
            "description": "AI conversation topic."
          },
          {
            "allOf": [
              {
                "$ref": "#/components/schemas/QuerySearchSuggestions",
                "description": "Calendar event topic."
              },
              {
                "type": "object",
                "required": ["type"],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": ["calendar"]
                  }
                }
              }
            ],
            "description": "Calendar event topic."
          }
        ],
        "description": "Only the selected type's fields can appear in a search suggestion."
      },
      "SearchType": {
        "type": "string",
        "description": "Search indexes supported by the shared search editor.",
        "enum": [
          "all",
          "channels",
          "document-or-file",
          "task",
          "email",
          "calls",
          "folders",
          "agent",
          "calendar"
        ]
      },
      "SessionAutoArchiveResponse": {
        "type": "object",
        "description": "A session's auto-archive settings and history.",
        "required": ["overrides", "defaults"],
        "properties": {
          "autoArchivedAt": {
            "type": ["string", "null"],
            "format": "date-time",
            "description": "When a trigger first archived the session. Kept when a person restores it: a session\narchives itself at most once."
          },
          "defaults": {
            "$ref": "#/components/schemas/AutoArchivePreferencesBody",
            "description": "The owner's defaults, which apply where the session has no choice of its own."
          },
          "overrides": {
            "$ref": "#/components/schemas/AutoArchiveOverridesBody",
            "description": "The session's own choices."
          }
        }
      },
      "SessionBot": {
        "type": "object",
        "description": "The agent behind a session, as much of it as rendering a message needs.",
        "required": ["id", "name", "handle"],
        "properties": {
          "avatarUrl": {
            "type": ["string", "null"],
            "description": "Avatar, when it has one."
          },
          "handle": {
            "type": "string",
            "description": "Stable `@` handle, without a leading `@`."
          },
          "id": {
            "$ref": "#/components/schemas/BotId",
            "description": "The bot's id. A message it sent has `\"bot|{id}\"` as its sender."
          },
          "name": {
            "type": "string",
            "description": "Display name."
          }
        }
      },
      "SessionPullRequestLink": {
        "type": "object",
        "description": "A pull request associated with a session.",
        "required": ["githubKey", "url", "source", "createdAt"],
        "properties": {
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the pull request was associated with the session."
          },
          "githubKey": {
            "type": "string",
            "description": "The pull request's `owner/repo/pull/number` key."
          },
          "linkedBy": {
            "type": ["string", "null"],
            "description": "The Macro user who linked it, for links a person made."
          },
          "source": {
            "$ref": "#/components/schemas/PullRequestLinkSource",
            "description": "Who associated the pull request with the session."
          },
          "url": {
            "type": "string",
            "description": "The pull request's GitHub URL."
          }
        }
      },
      "SessionPullRequestsResponse": {
        "type": "object",
        "description": "The pull requests associated with a session.",
        "required": ["pullRequests"],
        "properties": {
          "pullRequests": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SessionPullRequestLink"
            },
            "description": "Pull requests, oldest link first."
          }
        }
      },
      "SessionStatusDto": {
        "oneOf": [
          {
            "type": "object",
            "description": "No status updates received.",
            "required": ["kind"],
            "properties": {
              "kind": {
                "type": "string",
                "enum": ["no_messages"]
              }
            }
          },
          {
            "type": "object",
            "description": "The last system event received from the runtime.",
            "required": ["event", "kind"],
            "properties": {
              "event": {
                "type": "string",
                "description": "The wire name of the system event, e.g. `acp_ready`."
              },
              "kind": {
                "type": "string",
                "enum": ["event"]
              }
            }
          },
          {
            "type": "object",
            "description": "The session disconnected without sending a closed event.",
            "required": ["kind"],
            "properties": {
              "kind": {
                "type": "string",
                "enum": ["disconnected"]
              }
            }
          }
        ],
        "description": "Transport representation of a session's status, mirroring\n[`SessionStatus`]."
      },
      "SetAgentSessionArchivedRequest": {
        "type": "object",
        "description": "Request body for archiving or unarchiving an agent session.",
        "required": ["archived"],
        "properties": {
          "archived": {
            "type": "boolean",
            "description": "Archive the session, or restore it."
          }
        }
      },
      "SharePermissionV2": {
        "type": "object",
        "required": ["id", "owner"],
        "properties": {
          "channelSharePermissions": {
            "type": ["array", "null"],
            "items": {
              "$ref": "#/components/schemas/ChannelSharePermission"
            },
            "description": "The channel share permissions for the item"
          },
          "id": {
            "type": "string",
            "description": "The share permission id"
          },
          "linkShare": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/LinkShare",
                "description": "Who can access the item through its share link"
              }
            ]
          },
          "linkShareAccessLevel": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/AccessLevel",
                "description": "The level of access granted through the share link"
              }
            ]
          },
          "owner": {
            "type": "string",
            "description": "The owner of the item"
          },
          "teamShareAccessLevel": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/AccessLevel",
                "description": "The explicit access level granted to the owner's team, or `null` when disabled."
              }
            ]
          }
        }
      },
      "StartFreshAgentConversationRequest": {
        "type": "object",
        "description": "The session the user is choosing to leave behind.",
        "required": ["sessionId"],
        "properties": {
          "sessionId": {
            "type": "string",
            "format": "uuid",
            "description": "Current session id shown in the conversation metadata."
          }
        }
      },
      "TaskSearchSuggestions": {
        "type": "object",
        "description": "Task facets match the shared search editor; assignee and creator are distinct.",
        "required": ["status", "priority", "assignees", "created_by"],
        "properties": {
          "assignees": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Assigned people's names or supplied addresses."
          },
          "created_by": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Task creators' names or supplied addresses."
          },
          "priority": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Priority display values for client-side option resolution."
          },
          "query": {
            "type": ["string", "null"],
            "description": "Remaining keyword phrase."
          },
          "status": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Status display values for client-side option resolution."
          }
        },
        "additionalProperties": false
      },
      "TaskSuggestions": {
        "type": "object",
        "description": "Editable fields for task inference, before submission and identity resolution.",
        "properties": {
          "body": {
            "type": ["string", "null"],
            "description": "Suggested Markdown content or outgoing message body."
          },
          "due_date": {
            "type": ["string", "null"],
            "description": "Task deadline as a local ISO date."
          },
          "properties": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InputPropertySuggestion"
            },
            "description": "Display names/values that the client resolves against available task fields."
          },
          "title": {
            "type": ["string", "null"],
            "description": "Suggested note, task, or event title."
          }
        },
        "additionalProperties": false
      },
      "ToolActor": {
        "type": "string",
        "description": "Which authenticated participant's access a tool call requests.",
        "enum": ["requester", "owner"]
      },
      "ToolApprovalAnswerDto": {
        "type": "string",
        "description": "How a person answers a held tool call.",
        "enum": ["approve", "approve_and_remember", "deny", "cancel"]
      },
      "ToolApprovalStatusDto": {
        "type": "string",
        "description": "Where a held tool call stands once answered.",
        "enum": ["pending", "approved", "denied", "cancelled", "expired"]
      },
      "TriggerOrigin": {
        "oneOf": [
          {
            "type": "object",
            "description": "A message mentioned the agent.",
            "required": ["by", "message_id", "origin"],
            "properties": {
              "by": {
                "$ref": "#/components/schemas/Caller",
                "description": "Who posted it."
              },
              "message_id": {
                "type": "string",
                "format": "uuid",
                "description": "The message."
              },
              "origin": {
                "type": "string",
                "enum": ["mentioned"]
              }
            }
          },
          {
            "type": "object",
            "description": "A person wrote in their private conversation with the agent.",
            "required": ["by", "message_id", "origin"],
            "properties": {
              "by": {
                "$ref": "#/components/schemas/MacroUserIdStr",
                "description": "Who wrote."
              },
              "message_id": {
                "type": "string",
                "format": "uuid",
                "description": "The message."
              },
              "origin": {
                "type": "string",
                "enum": ["conversation"]
              }
            }
          },
          {
            "type": "object",
            "description": "The agent was added to a task's assignees.",
            "required": ["by", "task", "origin"],
            "properties": {
              "by": {
                "$ref": "#/components/schemas/Caller",
                "description": "Who assigned it."
              },
              "origin": {
                "type": "string",
                "enum": ["task_assigned"]
              },
              "task": {
                "type": "string",
                "description": "The task."
              }
            }
          },
          {
            "type": "object",
            "description": "The task joined a project, and inherited the project's agents.",
            "required": ["by", "task", "project", "origin"],
            "properties": {
              "by": {
                "$ref": "#/components/schemas/Caller",
                "description": "Who added the task to the project."
              },
              "origin": {
                "type": "string",
                "enum": ["project_inherited"]
              },
              "project": {
                "type": "string",
                "format": "uuid",
                "description": "The project."
              },
              "task": {
                "type": "string",
                "description": "The task."
              }
            }
          },
          {
            "type": "object",
            "description": "A person opened the session directly, from the composer.",
            "required": ["by", "origin"],
            "properties": {
              "by": {
                "$ref": "#/components/schemas/MacroUserIdStr",
                "description": "Who opened it."
              },
              "origin": {
                "type": "string",
                "enum": ["requested"]
              }
            }
          },
          {
            "type": "object",
            "description": "A tool handed the agent work. The tool knows only whose authority it\nruns under, not which agent called it.",
            "required": ["on_behalf_of", "origin"],
            "properties": {
              "on_behalf_of": {
                "$ref": "#/components/schemas/MacroUserIdStr",
                "description": "The user whose authority the work runs under."
              },
              "origin": {
                "type": "string",
                "enum": ["dispatched"]
              }
            }
          },
          {
            "type": "object",
            "description": "A routine fired. Its owner owns the session, so the owner is not repeated.",
            "required": ["routine", "firing", "origin"],
            "properties": {
              "firing": {
                "$ref": "#/components/schemas/RoutineCause",
                "description": "What made it fire."
              },
              "origin": {
                "type": "string",
                "enum": ["routine"]
              },
              "routine": {
                "type": "string",
                "format": "uuid",
                "description": "The routine."
              }
            }
          },
          {
            "type": "object",
            "description": "Not known: an unclaimed warm session, a producer that predates this\nrecord, or a kind this build does not know.",
            "required": ["origin"],
            "properties": {
              "origin": {
                "type": "string",
                "enum": ["unknown"]
              }
            }
          }
        ],
        "description": "What opened a session."
      },
      "UpdateChannelSharePermission": {
        "type": "object",
        "required": ["operation", "channelId"],
        "properties": {
          "accessLevel": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/AccessLevel",
                "description": "The access level for the channel\nThis is required if the operation is add or replace"
              }
            ]
          },
          "channelId": {
            "type": "string",
            "description": "The channel id"
          },
          "operation": {
            "$ref": "#/components/schemas/UpdateOperation",
            "description": "The type of operation to be performed on the chanel share permission\nYou can add, remove or replace and existing permission"
          }
        }
      },
      "UpdateOperation": {
        "type": "string",
        "enum": ["add", "remove", "replace"]
      },
      "UpdateSharePermissionRequestV2": {
        "type": "object",
        "properties": {
          "channelSharePermissions": {
            "type": ["array", "null"],
            "items": {
              "$ref": "#/components/schemas/UpdateChannelSharePermission"
            },
            "description": "Any channel share permissions to be created/updated/removed"
          },
          "linkShare": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/LinkShare",
                "description": "Who can access the item through its share link. Omit to leave unchanged or pass `null` to\ndisable link sharing."
              }
            ]
          },
          "linkShareAccessLevel": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/AccessLevel",
                "description": "The link access level. Omit to leave unchanged or pass `null` to reset it to the default\nlevel when a link share exists."
              }
            ]
          },
          "teamShareAccessLevel": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/AccessLevel",
                "description": "The explicit team access level. Omit to leave unchanged or pass `null` to disable team\nsharing. Only the actual owner may change this setting; `owner` is not an allowed level."
              }
            ]
          }
        }
      },
      "WarmAgentSessionRequest": {
        "type": "object",
        "description": "A client-minted id deduplicates warm calls without creating a conversation.",
        "required": ["id"],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Id reserved by this browser for its next in-memory conversation."
          }
        }
      },
      "WarmAgentSessionResponse": {
        "type": "object",
        "description": "A bounded best-effort warm attempt; absence means normal creation should proceed.",
        "properties": {
          "session": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/AgentSessionResponse",
                "description": "Prepared session, hidden until explicitly claimed through create."
              }
            ]
          }
        }
      },
      "WeekdayCode": {
        "type": "string",
        "description": "RFC weekday values used by the existing recurrence UI.",
        "enum": ["MO", "TU", "WE", "TH", "FR", "SA", "SU"]
      },
      "WithAgentSessionId": {
        "type": "object",
        "description": "Just a session id, for the preview variants that carry nothing else.\n\nClients deserialize this, so both derives are used.",
        "required": ["id"],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The session id."
          }
        }
      },
      "WorkRegistrationResponse": {
        "type": "object",
        "description": "One account's active registration of one session as its work.",
        "required": ["id", "accountId", "agentSessionId", "registeredAt"],
        "properties": {
          "accountId": {
            "type": "string",
            "description": "The account whose work this is."
          },
          "agentSessionId": {
            "type": "string",
            "format": "uuid",
            "description": "The session registered."
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The registration."
          },
          "registeredAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the account registered it."
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "tags": [
    {
      "name": "agent-sessions",
      "description": "Agent sessions"
    },
    {
      "name": "agent-models",
      "description": "Fresh provider model discovery"
    },
    {
      "name": "agent-repositories",
      "description": "Repositories a coding session can work on"
    },
    {
      "name": "agent-mode-choice",
      "description": "Whether a composer prompt goes to a chat or a coding agent"
    }
  ]
}