tutti/services/tuttid/api/openapi/tuttid.v1.yaml

openapi: 3.0.3
info:
  title: tuttid API
  version: 0.1.0
  description: Versioned local daemon API for tutti desktop, CLI, and approved local integrations.
x-tutti-openapi-fragments:
  - packages/workspace/issue-manager/openapi/issue-manager.v1.yaml
  - packages/connector/contracts/openapi/connector-market.v1.yaml
  - services/tuttid/api/openapi/mobile-remote-access.v1.yaml
servers:
  - url: http://127.0.0.1:4545
security:
  - bearerAuth: []
tags:
  - name: workspace-agent
    description: Workspace-scoped selectable Agent directory
  - name: runtime
  - name: account
  - name: user-presence
    description: Process-local room interest and account user presence projection
  - name: analytics
  - name: cli
    description: Public local capability protocol for the bundled CLI and future approved local integrations. Command metadata is machine-readable protocol data; command execution remains authorized by the daemon bearer token and filtered by daemon-owned context.
  - name: preferences
  - name: workspace
  - name: terminal
  - name: agent-session
  - name: agent-target
  - name: workspace-workflow
  - name: agent-context
  - name: app-center
  - name: app-factory
  - name: user-project
  - name: agent-quick-prompt
  - name: global-agent-activity
    description: Authenticated cross-room Agent Activity read model
paths:
  /v1/health:
    get:
      operationId: getHealth
      tags:
        - runtime
      summary: Get daemon health status
      responses:
        "200":
          description: Daemon health status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthStatusResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
  /v1/track:
    post:
      operationId: trackEvents
      tags:
        - analytics
      summary: Accept analytics events from approved local clients
      description: Accepts renderer-originated analytics events. Delivery to the analytics backend is handled asynchronously by tuttid.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TrackEventsRequest"
      responses:
        "202":
          description: Analytics events accepted for asynchronous delivery
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/account/login/start:
    post:
      operationId: startAccountLogin
      tags:
        - account
      summary: Start desktop account login
      responses:
        "200":
          description: Login attempt started
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountLoginStartResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/account/login/status:
    get:
      operationId: getAccountLoginStatus
      tags:
        - account
      summary: Get desktop account login status
      parameters:
        - name: attempt_id
          in: query
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        "200":
          description: Login attempt status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountLoginStatusResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/account/user_info:
    get:
      operationId: getAccountUserInfo
      tags:
        - account
      summary: Get current desktop account user
      responses:
        "200":
          description: Current account user, if signed in
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountUserInfoResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/account/product_summary:
    get:
      operationId: getAccountProductSummary
      tags:
        - account
      summary: Get current account membership and credits summary
      description: Returns desktop-safe account product state. tuttid reads the local account session and calls supported Tutti web APIs with the session cookie; session credentials are never returned to the renderer.
      responses:
        "200":
          description: Current account product summary, if signed in
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountProductSummaryResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/account/registration_credits_reward/dismiss:
    post:
      operationId: dismissAccountRegistrationCreditsReward
      tags:
        - account
      summary: Mark the current registration credits reward toast as shown
      description: Marks a desktop-safe registration credits reward event as shown after the renderer has displayed or dismissed the toast. tuttid keeps session credentials local and never returns them to the renderer.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DismissAccountRegistrationCreditsRewardRequest"
      responses:
        "204":
          description: Registration credits reward marked as shown
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/account/logout:
    post:
      operationId: logoutAccount
      tags:
        - account
      summary: Sign out current desktop account
      responses:
        "204":
          description: Account signed out
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/global-agent-activity/filter-options:
    get:
      operationId: getGlobalAgentActivityFilterOptions
      tags:
        - global-agent-activity
      summary: List global Agent Activity filter options
      description: Returns rooms owned by the signed-in user plus session owner, Agent, and activity-time options. Account credentials remain daemon-owned.
      responses:
        "200":
          description: Global Agent Activity filter options
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GlobalAgentActivityFilterOptionsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/global-agent-activity/sessions:
    get:
      operationId: listGlobalAgentActivitySessions
      tags:
        - global-agent-activity
      summary: List filtered global Agent Activity sessions
      description: At least one room, session owner, Agent, or activity-time filter is required. Results are bounded by the control plane and expose truncation instead of pagination.
      parameters:
        - name: roomIds
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              minLength: 1
          style: form
          explode: true
        - name: sessionOwnerUserIds
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              minLength: 1
          style: form
          explode: true
        - name: agentKeys
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              minLength: 1
          style: form
          explode: true
        - name: activityFromUnixMs
          in: query
          required: false
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: activityToUnixMs
          in: query
          required: false
          schema:
            type: integer
            format: int64
            minimum: 0
      responses:
        "200":
          description: Filtered global Agent Activity sessions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GlobalAgentActivitySessionListResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/account/user-presence/current-room:
    put:
      operationId: putAccountUserPresenceCurrentRoom
      tags:
        - user-presence
      summary: Visit or refresh the currently displayed room presence projection
      description: >-
        Moves the room to the head of the daemon process-local ten-room LRU,
        atomically replaces its eligible member source, waits for the exact
        WebSocket subscription ACK, and then obtains an authoritative presence
        snapshot. The LRU and presence cache are never persisted.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccountUserPresenceCurrentRoomRequest"
      responses:
        "200":
          description: Current room presence projection
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountUserPresenceRoomResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/account/user-presence/rooms/{roomID}:
    get:
      operationId: getAccountUserPresenceRoom
      tags:
        - user-presence
      summary: Read the cached presence projection for one recently visited room
      parameters:
        - name: roomID
          in: path
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        "200":
          description: Cached room presence projection, or an empty projection when the room is not in the LRU
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AccountUserPresenceRoomResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/account/user-presence/foreground:
    put:
      operationId: putAccountUserPresenceForeground
      tags:
        - user-presence
      summary: Update whether foreground snapshot reconciliation is active
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccountUserPresenceForegroundRequest"
      responses:
        "204":
          description: Foreground state accepted
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/cli/capabilities:
    get:
      operationId: listCliCapabilities
      tags:
        - cli
      summary: List CLI capabilities visible in the current context
      description: Returns daemon-owned command metadata that clients can use to route user commands without duplicating business rules or workspace resolution.
      parameters:
        - name: workspaceID
          in: query
          required: false
          schema:
            type: string
          description: Optional workspace context. When omitted, the daemon uses the startup workspace.
        - name: agentSessionID
          in: query
          required: false
          schema:
            type: string
          description: Optional canonical Agent Session identity. When present, discovery is constrained by that Session's persisted command capability projection.
        - name: includeHidden
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Include capabilities hidden from ordinary CLI command discovery by provider availability filters and command visibility. Intended for metadata consumers, not ordinary user command routing.
        - name: includeIntegration
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Include integration-only commands while preserving provider availability filters. Intended for app-runtime integrations.
      responses:
        "200":
          description: Visible CLI capabilities
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CliCapabilitiesResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/cli/commands/{commandID}/invoke:
    post:
      operationId: invokeCliCommand
      tags:
        - cli
      summary: Invoke one registered CLI command
      description: Invokes a daemon-owned capability by stable command id. The daemon validates context, resolves workspace state, applies edition filtering, and returns presentation-neutral command output.
      parameters:
        - $ref: "#/components/parameters/CliCommandID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CliInvokeRequest"
      responses:
        "200":
          description: CLI command result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CliInvokeResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-context/workspace-app-mentions:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listWorkspaceAppMentionCandidates
      tags:
        - agent-context
      summary: List workspace app mention candidates for agent context pickers
      description: >
        Returns daemon-owned application mention candidates for Agent GUI and
        rich-text context pickers. Real workspace apps are filtered by App Center
        installation and enabled state. CLI capabilities only enrich search
        metadata; this endpoint does not run command-routing availability
        filters or agent provider auth checks.
      responses:
        "200":
          description: Workspace app mention candidates
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppMentionCandidatesResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/preferences/desktop:
    get:
      operationId: getDesktopPreferences
      tags:
        - preferences
      summary: Get persisted desktop preferences
      responses:
        "200":
          description: Desktop preferences state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DesktopPreferencesStateResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/PreferencesOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    put:
      operationId: putDesktopPreferences
      tags:
        - preferences
      summary: Persist desktop preferences
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutDesktopPreferencesRequest"
      responses:
        "200":
          description: Desktop preferences persisted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DesktopPreferencesStateResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/PreferencesOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/desktop-update-admission:
    get:
      operationId: getDesktopUpdateAdmissionSnapshot
      tags:
        - desktop-update-admission
      summary: Read the daemon-owned desktop update admission snapshot
      responses:
        "200":
          description: Current desktop update admission snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DesktopUpdateAdmissionSnapshot"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/desktop-update-admission/startup:
    get:
      operationId: getDesktopUpdateAdmissionStartup
      tags:
        - desktop-update-admission
      summary: Wait for the daemon-initiated startup admission check
      responses:
        "200":
          description: Completed startup admission snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DesktopUpdateAdmissionSnapshot"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/desktop-update-admission/refresh:
    post:
      operationId: refreshDesktopUpdateAdmission
      tags:
        - desktop-update-admission
      summary: Ask the daemon to refresh admission for a lifecycle trigger
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DesktopUpdateAdmissionRefreshRequest"
      responses:
        "200":
          description: Desktop update admission refresh result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DesktopUpdateAdmissionRefreshResult"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/agent-maintenance/deleted-conversations/purge:
    post:
      operationId: purgeDeletedAgentConversations
      tags:
        - agent-maintenance
      summary: Permanently purge all soft-deleted Agent conversations
      responses:
        "200":
          description: Purge completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeletedAgentConversationPurgeResult"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/agent-quick-prompts:
    get:
      operationId: listAgentQuickPrompts
      tags:
        - agent-quick-prompt
      summary: List device-local Agent quick prompts
      responses:
        "200":
          description: Agent quick prompt list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentQuickPromptListResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/AgentQuickPromptOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    post:
      operationId: createAgentQuickPrompt
      tags:
        - agent-quick-prompt
      summary: Create a device-local Agent quick prompt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAgentQuickPromptRequest"
      responses:
        "201":
          description: Agent quick prompt created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentQuickPromptResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "409":
          $ref: "#/components/responses/AgentQuickPromptConflictError"
        "502":
          $ref: "#/components/responses/AgentQuickPromptOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/agent-quick-prompts/move:
    post:
      operationId: moveAgentQuickPrompt
      tags:
        - agent-quick-prompt
      summary: Move a device-local Agent quick prompt before an anchor or to the end
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MoveAgentQuickPromptRequest"
      responses:
        "200":
          description: Authoritative Agent quick prompt order
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentQuickPromptListResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/AgentQuickPromptNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "409":
          $ref: "#/components/responses/AgentQuickPromptConflictError"
        "502":
          $ref: "#/components/responses/AgentQuickPromptOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/agent-quick-prompts/{promptId}:
    parameters:
      - name: promptId
        in: path
        required: true
        schema:
          type: string
          minLength: 1
    put:
      operationId: updateAgentQuickPrompt
      tags:
        - agent-quick-prompt
      summary: Update a device-local Agent quick prompt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateAgentQuickPromptRequest"
      responses:
        "200":
          description: Agent quick prompt updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentQuickPromptResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/AgentQuickPromptNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "409":
          $ref: "#/components/responses/AgentQuickPromptConflictError"
        "502":
          $ref: "#/components/responses/AgentQuickPromptOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    delete:
      operationId: deleteAgentQuickPrompt
      tags:
        - agent-quick-prompt
      summary: Delete a device-local Agent quick prompt
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeleteAgentQuickPromptRequest"
      responses:
        "204":
          description: Agent quick prompt deleted
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/AgentQuickPromptNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "409":
          $ref: "#/components/responses/AgentQuickPromptConflictError"
        "502":
          $ref: "#/components/responses/AgentQuickPromptOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/user-projects:
    get:
      operationId: listUserProjects
      tags:
        - user-project
      summary: List user project directories in durable order
      responses:
        "200":
          description: User project list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserProjectListResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/PreferencesOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    post:
      operationId: useUserProject
      tags:
        - user-project
      summary: Record a user project directory usage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UseUserProjectRequest"
      responses:
        "201":
          description: User project usage recorded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserProjectResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/PreferencesOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    delete:
      operationId: deleteUserProject
      tags:
        - user-project
      summary: Remove a user project directory from the ordered project list
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeleteUserProjectRequest"
      responses:
        "204":
          description: User project removed
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/PreferencesOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/user-projects/check:
    post:
      operationId: checkUserProjectPath
      tags:
        - user-project
      summary: Check a user project directory path without recording usage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CheckUserProjectPathRequest"
      responses:
        "200":
          description: User project path status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserProjectPathCheckResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/PreferencesOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/user-projects/move:
    post:
      operationId: moveUserProject
      tags:
        - user-project
      summary: Move a user project within its pinned or unpinned partition
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MoveUserProjectRequest"
      responses:
        "200":
          description: Complete ordered user project list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserProjectListResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/PreferencesOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/user-projects/pin:
    post:
      operationId: pinUserProject
      tags:
        - user-project
      summary: Pin or unpin a user project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PinUserProjectRequest"
      responses:
        "200":
          description: Complete ordered user project list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserProjectListResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/PreferencesOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/events/ws:
    get:
      operationId: attachEventStream
      tags:
        - event-stream
      summary: Attach a WebSocket stream to daemon business events
      responses:
        "200":
          description: Event stream upgrade endpoint
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/agent-targets:
    get:
      operationId: listAgentTargets
      tags:
        - agent-target
      summary: List daemon-owned Agent Targets
      description: Returns durable Agent Target records. The launch ref is a controlled union and not a free-form configuration blob.
      responses:
        "200":
          description: Agent Targets
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListAgentTargetsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/PreferencesOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/agent-targets/{agentTargetID}/enabled:
    patch:
      operationId: setSystemAgentTargetEnabled
      tags:
        - agent-target
      summary: Enable or disable one daemon-owned system Agent Target
      description: Desktop control-plane operation that changes only the enabled field of an existing system Agent Target. It is not exposed as a Workspace App CLI capability.
      parameters:
        - name: agentTargetID
          in: path
          required: true
          schema:
            type: string
            minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetSystemAgentTargetEnabledRequest"
      responses:
        "200":
          description: Updated system Agent Target
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentTarget"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/PreferencesOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/agent-targets/{agentTargetID}/account-usage:
    post:
      operationId: probeAgentTargetAccountUsage
      tags:
        - agent-target
      summary: Probe provider-owned account usage for one Agent Target
      description: >
        Executes only a versioned account-usage capability declared by the
        exact verified Agent Extension installation. The daemon validates the
        companion executable under the Target-scoped managed runtime and
        returns a provider-neutral result containing stable error codes only.
        Account-usage availability never changes Agent runtime readiness.
      parameters:
        - name: agentTargetID
          in: path
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        "200":
          description: Provider-owned account usage result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentTargetAccountUsageProbeResult"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/AgentTargetNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-targets/{agentTargetID}/setup:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - name: agentTargetID
        in: path
        required: true
        schema:
          type: string
          minLength: 1
    get:
      operationId: getAgentTargetSetup
      tags:
        - agent-target
      summary: Resolve Agent Target setup state
      description: >
        Prefers a compatible local runtime. Otherwise returns a daemon-derived
        installation plan and any durable install action for the fixed Target.
        The managed runtime is installed under the user's stable ~/.local data
        root and is reused across workspaces. Clients cannot submit runner args,
        package identity, executable paths, or installation roots.
      responses:
        "200":
          description: Target setup state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentTargetSetupSnapshot"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-targets/{agentTargetID}/setup/install:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - name: agentTargetID
        in: path
        required: true
        schema:
          type: string
          minLength: 1
    post:
      operationId: installAgentTargetRuntime
      tags:
        - agent-target
      summary: Start an Agent Target runtime installation
      description: >
        Recomputes the trusted installation plan, verifies its digest, then
        starts or returns the durable idempotent action identified by
        clientActionId. The daemon owns all executable arguments and paths.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InstallAgentTargetRuntimeRequest"
      responses:
        "200":
          description: Current Target setup state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentTargetSetupSnapshot"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-targets/{agentTargetID}/setup/authenticate:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - name: agentTargetID
        in: path
        required: true
        schema:
          type: string
          minLength: 1
    post:
      operationId: authenticateAgentTargetRuntime
      tags:
        - agent-target
      summary: Authenticate an Agent Target runtime
      description: >
        Validates methodId against auth methods returned by a fresh ACP
        initialize, calls ACP authenticate, then requires session/new to
        succeed before reporting ready. The durable action is idempotent by
        clientActionId and never stores credentials.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AuthenticateAgentTargetRuntimeRequest"
      responses:
        "200":
          description: Current Target setup state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentTargetSetupSnapshot"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces:
    get:
      operationId: listWorkspaces
      tags:
        - workspace
      summary: List registered workspaces
      responses:
        "200":
          description: Workspace catalog
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListWorkspacesResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    post:
      operationId: createWorkspace
      tags:
        - workspace
      summary: Create a workspace record
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWorkspaceRequest"
      responses:
        "201":
          description: Workspace created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/startup:
    get:
      operationId: getStartupWorkspace
      tags:
        - workspace
      summary: Resolve the workspace that should open on startup
      responses:
        "200":
          description: Startup workspace selection
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StartupWorkspaceResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: getWorkspace
      tags:
        - workspace
      summary: Get one workspace by id
      responses:
        "200":
          description: Workspace details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    patch:
      operationId: updateWorkspace
      tags:
        - workspace
      summary: Update one workspace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateWorkspaceRequest"
      responses:
        "200":
          description: Workspace updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    delete:
      operationId: deleteWorkspace
      tags:
        - workspace
      summary: Delete one workspace
      responses:
        "200":
          description: Workspace deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteWorkspaceResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/workbench:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: getWorkspaceWorkbench
      tags:
        - workspace
      summary: Get one workspace workbench snapshot
      responses:
        "200":
          description: Workspace workbench snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceWorkbenchResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    put:
      operationId: putWorkspaceWorkbench
      tags:
        - workspace
      summary: Persist one workspace workbench snapshot
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutWorkspaceWorkbenchRequest"
      responses:
        "200":
          description: Workspace workbench snapshot persisted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceWorkbenchResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/model-plans:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listModelPlans
      tags:
        - model-plan
      summary: List workspace model access plans
      description: Returns every named model access plan for the workspace. Credentials never appear in responses; only hasApiKey is exposed.
      responses:
        "200":
          description: Model access plans
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListModelPlansResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    post:
      operationId: createModelPlan
      tags:
        - model-plan
      summary: Create one named model access plan
      description: Creates a plan for one access scheme (official subscription, coding plan, relay, or custom compatible endpoint). Multiple named plans may share one protocol. New plans start undetected.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutModelPlanRequest"
      responses:
        "200":
          description: Created model access plan
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelPlan"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/model-plans/detect:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    post:
      operationId: detectModelPlan
      tags:
        - model-plan
      summary: Run the staged connection detection for a plan or draft
      description: Runs the network, auth, model discovery, and minimal real inference stages in order and reports one structured result per stage. With planId the outcome persists onto the stored plan; omitted fields fall back to stored values. Without planId the request verifies an unsaved draft.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DetectModelPlanRequest"
      responses:
        "200":
          description: Staged detection outcome
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DetectModelPlanResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/ModelPlanNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/model-plans/{modelPlanID}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/ModelPlanID"
    get:
      operationId: getModelPlan
      tags:
        - model-plan
      summary: Get one model access plan
      responses:
        "200":
          description: Model access plan
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelPlan"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/ModelPlanNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    put:
      operationId: updateModelPlan
      tags:
        - model-plan
      summary: Update one model access plan
      description: Replaces the mutable plan fields. Omitting apiKey keeps the stored credential. Changing the credential, base URL, or protocol resets detection state. Changes affect only calls that have not started yet.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutModelPlanRequest"
      responses:
        "200":
          description: Updated model access plan
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelPlan"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/ModelPlanNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    delete:
      operationId: deleteModelPlan
      tags:
        - model-plan
      summary: Delete one model access plan
      description: Deletion is blocked with a 409 while any agent target still references the plan. Callers rebind or clear those bindings first; the references endpoint lists them.
      responses:
        "200":
          description: Model access plan deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteModelPlanResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/ModelPlanNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "409":
          $ref: "#/components/responses/ModelPlanReferencedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/model-plans/{modelPlanID}/duplicate:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/ModelPlanID"
    post:
      operationId: duplicateModelPlan
      tags:
        - model-plan
      summary: Duplicate one model access plan
      description: Clones the plan, including its credential, into a new disabled plan that must be re-detected before use.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DuplicateModelPlanRequest"
      responses:
        "200":
          description: Duplicated model access plan
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelPlan"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/ModelPlanNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/model-plans/{modelPlanID}/enabled:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/ModelPlanID"
    patch:
      operationId: setModelPlanEnabled
      tags:
        - model-plan
      summary: Enable or disable one model access plan
      description: Disabling a plan blocks new calls through it without deleting the configuration. Running calls are never interrupted.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetModelPlanEnabledRequest"
      responses:
        "200":
          description: Updated model access plan
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelPlan"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/ModelPlanNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/model-plans/{modelPlanID}/references:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/ModelPlanID"
    get:
      operationId: listModelPlanReferences
      tags:
        - model-plan
      summary: List consumers that reference one model access plan
      description: Returns the agent targets that currently reference the plan so change and delete impact can be shown before committing.
      responses:
        "200":
          description: Plan references
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelPlanReferencesResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/ModelPlanNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/collaboration-runs:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listCollaborationRuns
      tags:
        - collaboration-run
      summary: List workspace collaboration runs
      description: Returns collaboration runs (model consults, forks, delegations, handoffs) newest first. Credentials never appear on run records.
      parameters:
        - name: sourceSessionId
          in: query
          required: false
          description: Narrow to runs started from one source agent session.
          schema:
            type: string
            minLength: 1
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
      responses:
        "200":
          description: Collaboration runs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListCollaborationRunsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    post:
      operationId: createCollaborationRun
      tags:
        - collaboration-run
      summary: Start or record one collaboration run
      description: Mode consult executes a daemon-side advisory completion against a workspace model access plan synchronously and returns the completed or failed run; the advisor never executes tools and task ownership never changes. Modes fork, delegate, and handoff record a run for a target session the GUI already created through the session-create path.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateCollaborationRunRequest"
      responses:
        "200":
          description: Collaboration run
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollaborationRun"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/collaboration-runs/{collaborationRunID}/adoption:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/CollaborationRunID"
    post:
      operationId: setCollaborationRunAdoption
      tags:
        - collaboration-run
      summary: Record whether a collaboration run outcome was adopted
      description: Consult and delegate outcomes track adoption (pending, adopted, rejected). Fork and handoff runs are not adoptable.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetCollaborationRunAdoptionRequest"
      responses:
        "200":
          description: Updated collaboration run
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollaborationRun"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/collaboration-runs/{collaborationRunID}/cancel:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/CollaborationRunID"
    post:
      operationId: cancelCollaborationRun
      tags:
        - collaboration-run
      summary: Cancel a running consult
      description: Marks a still-running consult canceled and aborts its in-flight completion call. Settled runs are returned unchanged.
      responses:
        "200":
          description: Collaboration run after the cancel request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollaborationRun"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-model-bindings:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listAgentModelBindings
      tags:
        - model-plan
      summary: List per-workspace agent target model bindings
      description: Returns the default model plan and default model bound to each agent target in the workspace. Targets without a binding keep their provider-native model source.
      responses:
        "200":
          description: Agent model bindings
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListAgentModelBindingsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-model-bindings/{agentTargetID}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - name: agentTargetID
        in: path
        required: true
        schema:
          type: string
          minLength: 1
    put:
      operationId: setAgentModelBinding
      tags:
        - model-plan
      summary: Set or clear one agent target model binding
      description: Binds the agent target to a default model plan and model for the workspace. An all-empty body clears the binding. Changes affect only sessions that have not started; running sessions keep their recorded configuration.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetAgentModelBindingRequest"
      responses:
        "200":
          description: Updated agent model binding
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentModelBinding"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/AgentTargetNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/model-policies:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listModelPolicies
      deprecated: true
      tags:
        - model-plan
      summary: List legacy role-based model policies
      description: Compatibility-only. New workflows use WorkspaceAgent for runtime model configuration and AutomationRule for optional collaboration actions.
      responses:
        "200":
          description: Model usage policies
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListModelPoliciesResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    post:
      operationId: createModelPolicy
      deprecated: true
      tags:
        - model-plan
      summary: Create one legacy role-based model policy
      description: Compatibility-only. The production daemon does not execute this policy's role map or fixed review runner; create a WorkspaceAgent and AutomationRule for new workflows.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutModelPolicyRequest"
      responses:
        "200":
          description: Created model usage policy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelUsagePolicy"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/model-policies/{modelPolicyID}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/ModelPolicyID"
    get:
      operationId: getModelPolicy
      deprecated: true
      tags:
        - model-plan
      summary: Get one legacy role-based model policy
      description: Compatibility-only. The policy is retained for persisted data and acceptance records.
      responses:
        "200":
          description: Model usage policy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelUsagePolicy"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    put:
      operationId: updateModelPolicy
      deprecated: true
      tags:
        - model-plan
      summary: Update one legacy role-based model policy
      description: Compatibility-only. Changes do not drive the production Agent runtime or AutomationRule engine.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutModelPolicyRequest"
      responses:
        "200":
          description: Updated model usage policy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelUsagePolicy"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    delete:
      operationId: deleteModelPolicy
      deprecated: true
      tags:
        - model-plan
      summary: Delete one legacy role-based model policy
      description: Deletion is blocked with a 409 while any agent binding still references the policy. Callers rebind or clear those bindings first.
      responses:
        "200":
          description: Model usage policy deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteModelPolicyResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "409":
          $ref: "#/components/responses/ModelPolicyReferencedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/model-policy-override:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
    get:
      operationId: getAgentSessionModelPolicyOverride
      deprecated: true
      tags:
        - model-plan
      summary: Get the legacy session model-policy override
      description: Compatibility-only. Use the AutomationRule session override for new workflows.
      responses:
        "200":
          description: Session policy override; absent override returns disabled=false with no policy id
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSessionModelPolicyOverride"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    put:
      operationId: setAgentSessionModelPolicyOverride
      deprecated: true
      tags:
        - model-plan
      summary: Set the legacy session model-policy override
      description: Compatibility-only. The legacy review runner is not wired in production; use the AutomationRule session override to select or disable future actions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetAgentSessionModelPolicyOverrideRequest"
      responses:
        "200":
          description: Updated session policy override
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSessionModelPolicyOverride"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/acceptance:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
    get:
      operationId: getAgentSessionAcceptance
      tags:
        - model-plan
      summary: Get the session acceptance ladder state
      description: States distinguish agent_claimed, auto_checked, and user_accepted. Only user_accepted may close work; automated review can reach auto_checked at most.
      responses:
        "200":
          description: Session acceptance state; sessions never claimed complete return no state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSessionAcceptanceResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    post:
      operationId: acceptAgentSessionWork
      tags:
        - model-plan
      summary: Record explicit user acceptance for the session's claimed work
      responses:
        "200":
          description: Acceptance recorded as user_accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSessionAcceptanceResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/workflows:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listWorkspaceWorkflows
      tags:
        - workspace-workflow
      summary: List Tutti-owned workflows for a source Agent session
      parameters:
        - name: sourceSessionId
          in: query
          required: true
          schema:
            type: string
            minLength: 1
        - name: checkpointStatus
          in: query
          required: false
          schema:
            type: string
            enum:
              - pending
            x-enum-varnames:
              - ListWorkspaceWorkflowsParamsCheckpointStatusPending
          description: When omitted, returns every workflow for the source session. Pass pending to return only workflows with a pending checkpoint.
      responses:
        "200":
          description: Matching authoritative workflow snapshots
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceWorkflowListResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/workflows/{workflowID}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - name: workflowID
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: getWorkspaceWorkflow
      tags:
        - workspace-workflow
      summary: Get one authoritative Tutti-owned workflow snapshot
      responses:
        "200":
          description: Authoritative workflow snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceWorkflowSnapshot"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/workflows/{workflowID}/checkpoints/{checkpointID}/decision:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - name: workflowID
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: checkpointID
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      operationId: decideWorkspaceWorkflowCheckpoint
      tags:
        - workspace-workflow
      summary: Decide one Tutti-owned workflow checkpoint
      description: This user-facing API is the only decision boundary; Agent CLI capabilities cannot self-approve a checkpoint.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DecideWorkspaceWorkflowCheckpointRequest"
      responses:
        "200":
          description: Updated authoritative workflow snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceWorkflowSnapshot"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "409":
          description: Checkpoint was already decided differently or is no longer current
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listWorkspaceApps
      tags:
        - app-center
      summary: List app catalog and installation state for one workspace
      responses:
        "200":
          description: Workspace apps
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppListResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/catalog/refresh:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    post:
      operationId: refreshWorkspaceAppCatalog
      tags:
        - app-center
      summary: Refresh the remote app catalog for one workspace
      responses:
        "200":
          description: Workspace apps after the refresh request was accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppListResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/import:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    post:
      operationId: importWorkspaceApp
      tags:
        - app-center
      summary: Import one workspace app package archive
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ImportWorkspaceAppRequest"
      responses:
        "200":
          description: Workspace app package imported
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/load-local:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    post:
      operationId: loadLocalWorkspaceApp
      tags:
        - app-center
      summary: Load one unpacked local workspace app directory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoadLocalWorkspaceAppRequest"
      responses:
        "200":
          description: Local workspace app loaded and installed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/start-enabled:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    post:
      operationId: startEnabledWorkspaceApps
      tags:
        - app-center
      summary: Start enabled installed apps for one workspace
      responses:
        "200":
          description: Enabled workspace apps start attempted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppListResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/stop-all:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    post:
      operationId: stopAllWorkspaceApps
      tags:
        - app-center
      summary: Stop all running apps for one workspace
      responses:
        "200":
          description: Workspace apps stopped
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppListResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/{appID}/install:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppID"
    post:
      operationId: installWorkspaceApp
      tags:
        - app-center
      summary: Install one app in a workspace
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InstallWorkspaceAppRequest"
      responses:
        "200":
          description: Workspace app installed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/{appID}/reload-local:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppID"
    post:
      operationId: reloadLocalWorkspaceApp
      tags:
        - app-center
      summary: Reload one unpacked local workspace app directory
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReloadLocalWorkspaceAppRequest"
      responses:
        "200":
          description: Local workspace app reloaded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/{appID}/preferences/agent:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppID"
    get:
      operationId: getWorkspaceAppAgentPreferences
      deprecated: true
      tags:
        - app-center
      summary: Get workspace-app agent preference projection
      description: >
        Read-only subset of desktop agent preferences for one workspace app
        runtime. Intended for workspace app server tokens; exposes default
        provider selection and developer-gated provider visibility only. Deprecated
        for Agent integrations: use the current agent catalog (`tutti --json agent list`) through
        `@tutti-os/agent-acp-kit/tutti`. Removal is gated by the production-usage
        telemetry and release criteria in
        `docs/conventions/deprecated-workspace-app-agent-apis.md`.
      responses:
        "200":
          description: Workspace app agent preferences
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppAgentPreferencesResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/PreferencesOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/{appID}/agent-providers/status:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppID"
    get:
      operationId: getWorkspaceAppAgentProviderStatuses
      deprecated: true
      tags:
        - app-center
      summary: Get agent provider availability for one workspace app
      description: >
        Workspace-app scoped alias of `GET /v1/agent-providers/status` for app
        server tokens. When `providers` is omitted, returns provider statuses
        for enabled daemon-owned Agent Targets visible to Agent GUI. When
        `providers` is supplied, it narrows that Agent Target set and cannot
        expose providers outside it. Deprecated for Agent integrations: use
        the current agent catalog (`tutti --json agent list`) through
        `@tutti-os/agent-acp-kit/tutti`.
        Removal is gated by the production-usage telemetry and release criteria
        in `docs/conventions/deprecated-workspace-app-agent-apis.md`.
      parameters:
        - name: providers
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              $ref: "#/components/schemas/WorkspaceAgentProvider"
        - name: includeNetwork
          in: query
          required: false
          schema:
            type: boolean
        - name: refresh
          in: query
          required: false
          description: Bypass the daemon provider-readiness cache.
          schema:
            type: boolean
      responses:
        "200":
          description: Agent provider status snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentProviderStatusListResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/{appID}/agent-providers/{provider}/composer-options:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppID"
      - name: provider
        in: path
        required: true
        schema:
          $ref: "#/components/schemas/WorkspaceAgentProvider"
    post:
      operationId: getWorkspaceAppAgentProviderComposerOptions
      deprecated: true
      tags:
        - app-center
      summary: Get agent provider composer options for one workspace app
      description: >
        Workspace-app scoped alias of
        `POST /v1/agent-providers/{provider}/composer-options` for app server
        tokens. Deprecated for Agent integrations: use
        `tutti --json agent composer-options --agent-id <agentId>` through
        `@tutti-os/agent-acp-kit/tutti`. Removal is gated by the production-usage
        telemetry and release criteria in
        `docs/conventions/deprecated-workspace-app-agent-apis.md`.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GetAgentProviderComposerOptionsRequest"
      responses:
        "200":
          description: Agent provider composer options
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentProviderComposerOptionsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/{appID}/references/list:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppID"
    post:
      operationId: listWorkspaceAppReferences
      tags:
        - app-center
      summary: List file references exposed by one running workspace app
      description: >
        Proxies a reference list request to a running workspace app and returns
        daemon-resolved file references. Workspace app runtimes return scoped
        locations to the daemon; this public daemon API returns absolute file
        paths that desktop clients can use as ordinary file links.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AppReferenceListRequest"
      responses:
        "200":
          description: Workspace app reference list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AppReferenceListResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/{appID}/references/search:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppID"
    post:
      operationId: searchWorkspaceAppReferences
      tags:
        - app-center
      summary: Search file references exposed by one running workspace app
      description: >
        Proxies a recursive reference search request to a running workspace app
        and returns daemon-resolved file references ordered by relevance. Unlike
        the list filterText, search spans the whole app reference tree and never
        returns groups. Workspace app runtimes return scoped locations to the
        daemon; this public daemon API returns absolute file paths that desktop
        clients can use as ordinary file links.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AppReferenceSearchRequest"
      responses:
        "200":
          description: Workspace app reference search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AppReferenceSearchResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/{appID}/uploads:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppID"
    post:
      operationId: prepareWorkspaceAppUpload
      tags:
        - app-center
      summary: Prepare one managed file upload for a workspace app
      description: >
        Creates an in-memory upload session scoped to one installed workspace
        app. The response only identifies the daemon upload session; desktop
        hosts construct the direct content upload URL and keep storage-provider
        details out of the app-facing browser bridge.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PrepareWorkspaceAppUploadRequest"
      responses:
        "201":
          description: Workspace app upload session prepared
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PrepareWorkspaceAppUploadResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/{appID}/uploads/{uploadID}/content:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppID"
      - name: uploadID
        in: path
        required: true
        schema:
          type: string
          minLength: 1
    put:
      operationId: putWorkspaceAppUploadContent
      tags:
        - app-center
      summary: Stream upload bytes into one workspace app upload session
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        "204":
          description: Workspace app upload content accepted
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/{appID}/uploads/{uploadID}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppID"
      - name: uploadID
        in: path
        required: true
        schema:
          type: string
          minLength: 1
    delete:
      operationId: cancelWorkspaceAppUpload
      tags:
        - app-center
      summary: Cancel one managed file upload session for a workspace app
      description: >
        Drops the in-memory upload session and removes the temporary upload
        file when the upload has not been completed. Completed durable files are
        not deleted by this operation.
      responses:
        "204":
          description: Workspace app upload session canceled
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/{appID}/uploads/{uploadID}/complete:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppID"
      - name: uploadID
        in: path
        required: true
        schema:
          type: string
          minLength: 1
    post:
      operationId: completeWorkspaceAppUpload
      tags:
        - app-center
      summary: Complete one managed file upload for a workspace app
      responses:
        "200":
          description: Workspace app upload completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CompleteWorkspaceAppUploadResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/{appID}/export:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppID"
    post:
      operationId: exportWorkspaceApp
      tags:
        - app-center
      summary: Export one workspace app package archive
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExportWorkspaceAppRequest"
      responses:
        "200":
          description: Workspace app package exported
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExportWorkspaceAppResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/{appID}/icon:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppID"
    post:
      operationId: replaceWorkspaceAppIcon
      tags:
        - app-center
      summary: Replace the icon for one generated workspace app
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReplaceWorkspaceAppIconRequest"
      responses:
        "200":
          description: Workspace app icon replaced
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/{appID}/uninstall:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppID"
    post:
      operationId: uninstallWorkspaceApp
      tags:
        - app-center
      summary: Uninstall one installed app from a workspace
      responses:
        "200":
          description: Workspace app uninstalled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/{appID}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppID"
    delete:
      operationId: deleteWorkspaceApp
      tags:
        - app-center
      summary: Delete one local workspace app package
      responses:
        "200":
          description: Local workspace app package deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteWorkspaceAppResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/{appID}/launch:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppID"
    post:
      operationId: launchWorkspaceApp
      tags:
        - app-center
      summary: Launch one installed workspace app
      responses:
        "200":
          description: Workspace app launch prepared
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/{appID}/retry:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppID"
    post:
      operationId: retryWorkspaceApp
      tags:
        - app-center
      summary: Retry one failed installed workspace app
      responses:
        "200":
          description: Workspace app failure retried
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/apps/{appID}/rollback:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppID"
    post:
      operationId: rollbackWorkspaceApp
      tags:
        - app-center
      summary: Roll back one workspace app to a previous package version
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RollbackWorkspaceAppRequest"
      responses:
        "200":
          description: Workspace app rolled back
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/app-factory/jobs:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listWorkspaceAppFactoryJobs
      tags:
        - app-factory
      summary: List App Factory jobs for one workspace
      responses:
        "200":
          description: App Factory jobs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppFactoryJobListResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    post:
      operationId: createWorkspaceAppFactoryJob
      tags:
        - app-factory
      summary: Create an App Factory job
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWorkspaceAppFactoryJobRequest"
      responses:
        "201":
          description: App Factory job created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppFactoryJobResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/app-factory/agent-targets/{agentTargetID}/composer-options:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - name: agentTargetID
        in: path
        required: true
        schema:
          type: string
          minLength: 1
    post:
      operationId: getWorkspaceAppFactoryAgentTargetComposerOptions
      tags:
        - app-factory
      summary: Get App Factory agent target composer options
      description: >
        Resolves provider composer options for App Factory using daemon-owned
        workspace and factory draft context. Clients provide workspace and
        agent target selection, while tuttid owns the working directory used
        for provider discovery.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GetWorkspaceAppFactoryAgentTargetComposerOptionsRequest"
      responses:
        "200":
          description: App Factory agent target composer options
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentProviderComposerOptionsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/app-factory/jobs/{jobID}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppFactoryJobID"
    get:
      operationId: getWorkspaceAppFactoryJob
      tags:
        - app-factory
      summary: Get one App Factory job
      responses:
        "200":
          description: App Factory job
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppFactoryJobResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    delete:
      operationId: deleteWorkspaceAppFactoryJob
      tags:
        - app-factory
      summary: Delete one App Factory job
      responses:
        "200":
          description: App Factory job deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppFactoryJobListResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/app-factory/jobs/{jobID}/cancel:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppFactoryJobID"
    post:
      operationId: cancelWorkspaceAppFactoryJob
      tags:
        - app-factory
      summary: Cancel one App Factory job
      responses:
        "200":
          description: App Factory job canceled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppFactoryJobResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/app-factory/jobs/{jobID}/retry-validation:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppFactoryJobID"
    post:
      operationId: retryWorkspaceAppFactoryJobValidation
      tags:
        - app-factory
      summary: Retry validation for one App Factory draft
      responses:
        "200":
          description: App Factory job validation retried
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppFactoryJobResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/app-factory/jobs/{jobID}/fix:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppFactoryJobID"
    post:
      operationId: fixWorkspaceAppFactoryJob
      tags:
        - app-factory
      summary: Ask AI to fix one App Factory draft
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FixWorkspaceAppFactoryJobRequest"
      responses:
        "200":
          description: App Factory job fix requested
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppFactoryJobResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/app-factory/jobs/{jobID}/prepare-modification:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppFactoryJobID"
    post:
      operationId: prepareWorkspaceAppFactoryJobModification
      tags:
        - app-factory
      summary: Prepare one published App Factory job for modification
      responses:
        "200":
          description: App Factory draft prepared for modification
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAppFactoryJobResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/app-factory/jobs/{jobID}/publish:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAppFactoryJobID"
    post:
      operationId: publishWorkspaceAppFactoryJob
      tags:
        - app-factory
      summary: Publish one validated App Factory draft
      responses:
        "200":
          description: App Factory job published
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublishWorkspaceAppFactoryJobResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceAppNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-session-recordings:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listAgentSessionRecordings
      tags:
        - agent-session
      summary: List developer Agent Session recordings for one workspace
      responses:
        "200":
          description: Agent Session recordings ordered by latest update
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSessionRecordingListResponse"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    post:
      operationId: startAgentSessionRecording
      tags:
        - agent-session
      summary: Start one developer Agent Session recording
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StartAgentSessionRecordingRequest"
      responses:
        "201":
          description: Agent Session recording prepared or recording
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSessionRecording"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "409":
          description: Another recording is active
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-session-recordings/{recordingID}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - name: recordingID
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: getAgentSessionRecording
      tags:
        - agent-session
      summary: Get one developer Agent Session recording
      responses:
        "200":
          description: Agent Session recording
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSessionRecording"
        "404":
          description: Recording not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    patch:
      operationId: renameAgentSessionRecording
      tags:
        - agent-session
      summary: Rename one developer Agent Session recording and its Cassette
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RenameAgentSessionRecordingRequest"
      responses:
        "200":
          description: Agent Session recording renamed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSessionRecording"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          description: Recording not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    delete:
      operationId: deleteAgentSessionRecording
      tags:
        - agent-session
      summary: Delete one inactive developer Agent Session recording and its Cassette
      responses:
        "204":
          description: Agent Session recording deleted
        "404":
          description: Recording not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "409":
          description: Active recording cannot be deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-session-recordings/{recordingID}/complete:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - name: recordingID
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      operationId: completeAgentSessionRecording
      tags:
        - agent-session
      summary: Complete one active developer Agent Session recording
      responses:
        "200":
          description: Agent Session recording completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSessionRecording"
        "404":
          description: Recording not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "409":
          description: Recording cannot complete in its current state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-session-recordings/{recordingID}/activity-events:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - name: recordingID
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      operationId: appendAgentSessionRecordingActivityEvents
      tags:
        - agent-session
      summary: Append an ordered batch of renderer Agent Activity events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AppendAgentSessionRecordingActivityEventsRequest"
      responses:
        "200":
          description: Activity events persisted through the returned Cassette sequence
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AppendAgentSessionRecordingActivityEventsResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          description: Recording not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "409":
          description: Recording cannot accept Activity events in its current state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-session-recordings/{recordingID}/cancel:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - name: recordingID
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      operationId: cancelAgentSessionRecording
      tags:
        - agent-session
      summary: Cancel one active developer Agent Session recording
      responses:
        "200":
          description: Agent Session recording canceled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSessionRecording"
        "404":
          description: Recording not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-session-cassettes:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listAgentSessionCassettes
      tags:
        - agent-session
      summary: List immutable Agent Session Cassettes for one workspace
      responses:
        "200":
          description: Cassettes ordered by creation time
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSessionCassetteListResponse"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-session-cassettes/import:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    post:
      operationId: importAgentSessionCassettes
      tags:
        - agent-session
      summary: Import one or more portable Agent Session Cassette directories
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ImportAgentSessionCassettesRequest"
      responses:
        "200":
          description: Per-Cassette import results, including partial success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImportAgentSessionCassettesResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-session-replay-workspaces:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    post:
      operationId: prepareAgentSessionReplayWorkspace
      tags:
        - agent-session
      summary: Validate a fixed batch of distinct replay Cassettes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PrepareAgentSessionReplayWorkspaceRequest"
      responses:
        "201":
          description: Portable Cassette launch handoffs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSessionReplayWorkspaceLaunch"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          description: Cassette not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "409":
          description: Cassette is corrupt or duplicated in this workspace
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/agent-session-replay/cassettes/{cassetteID}/transport/verify:
    parameters:
      - name: cassetteID
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      operationId: verifyAgentSessionReplayTransport
      tags:
        - agent-session
      summary: Verify that the isolated replay transport consumed its complete Cassette
      responses:
        "204":
          description: Replay transport consumed every recorded connection and frame
        "409":
          description: Replay transport mismatch or incomplete consumption
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/agent-session-replay/cassettes/{cassetteID}/transport/playback:
    parameters:
      - name: cassetteID
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: getAgentSessionReplayTransportPlayback
      tags:
        - agent-session
      summary: Read playback timing for the isolated replay transport
      responses:
        "200":
          description: Current replay playback timing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSessionReplayTransportPlayback"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    post:
      operationId: updateAgentSessionReplayTransportPlayback
      tags:
        - agent-session
      summary: Update playback timing for the isolated replay transport
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateAgentSessionReplayTransportPlaybackRequest"
      responses:
        "200":
          description: Updated replay playback timing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSessionReplayTransportPlayback"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/agent-session-replay/cassettes/{cassetteID}/checkpoints/{checkpointIndex}/verify:
    parameters:
      - name: cassetteID
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: checkpointIndex
        in: path
        required: true
        schema:
          type: integer
          minimum: 0
    post:
      operationId: verifyAgentSessionReplayCheckpoint
      tags:
        - agent-session
      summary: Verify one Replay Checkpoint trigger and canonical readiness
      responses:
        "200":
          description: Current semantic checkpoint verification state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSessionReplayCheckpointVerification"
        "409":
          description: Checkpoint identity, trigger, or observation mismatch
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listWorkspaceAgentSessions
      tags:
        - agent-session
      summary: List agent sessions for one workspace
      parameters:
        - name: agentTargetId
          in: query
          required: false
          schema:
            type: string
            minLength: 1
        - name: searchQuery
          in: query
          required: false
          description: Case-insensitive, whitespace-tokenized search over the session title only.
          schema:
            type: string
        - name: cursor
          in: query
          required: false
          schema:
            type: string
            minLength: 1
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        "200":
          description: Workspace agent sessions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionListResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    delete:
      operationId: clearWorkspaceAgentSessions
      tags:
        - agent-session
      summary: Hard-delete all agent sessions for one workspace
      responses:
        "200":
          description: Workspace agent sessions cleared
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClearWorkspaceAgentSessionsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "409":
          $ref: "#/components/responses/TuttiExecutionActiveError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    post:
      operationId: createWorkspaceAgentSession
      tags:
        - agent-session
      summary: Create an agent session for one workspace
      parameters:
        - $ref: "#/components/parameters/AgentCommandOrigin"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWorkspaceAgentSessionRequest"
      responses:
        "201":
          description: Workspace agent session created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/batch:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    delete:
      operationId: deleteWorkspaceAgentSessionsBatch
      tags:
        - agent-session
      summary: Delete an exact snapshot of agent sessions for one workspace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeleteWorkspaceAgentSessionsBatchRequest"
      responses:
        "200":
          description: Workspace agent sessions deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteWorkspaceAgentSessionsBatchResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "409":
          $ref: "#/components/responses/TuttiExecutionActiveError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/deleted-agent-sessions:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listWorkspaceDeletedAgentSessions
      tags:
        - agent-session
      summary: List topmost soft-deleted agent session components for one workspace
      parameters:
        - name: searchQuery
          in: query
          required: false
          description: Case-insensitive search over the original session title only.
          schema:
            type: string
        - name: railSectionKey
          in: query
          required: false
          description: Select sessions by their exact persisted rail section key. Mutually exclusive with the deprecated project filters; omit every section filter to list all locations.
          schema:
            type: string
            minLength: 1
        - name: projectScope
          in: query
          required: false
          deprecated: true
          description: Deprecated explicit conversations-section selector. It is resolved to the fixed conversations rail section key and is mutually exclusive with railSectionKey and projectPath.
          schema:
            type: string
            enum:
              - unscoped
        - name: projectPath
          in: query
          required: false
          deprecated: true
          description: Deprecated explicit project selector. The path is resolved to its canonical rail section key before querying and is mutually exclusive with railSectionKey and projectScope.
          schema:
            type: string
            minLength: 1
        - name: cursor
          in: query
          required: false
          description: Opaque cursor returned by the previous page.
          schema:
            type: string
            minLength: 1
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        "200":
          description: Topmost soft-deleted agent session components in the workspace
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceDeletedAgentSessionListResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    delete:
      operationId: purgeWorkspaceDeletedAgentSessions
      tags:
        - agent-session
      summary: Permanently purge all soft-deleted agent sessions in one workspace
      responses:
        "200":
          description: Workspace soft-deleted agent sessions permanently purged
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeletedAgentConversationPurgeResult"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/deleted-agent-sessions/{agentSessionID}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
    delete:
      operationId: purgeWorkspaceDeletedAgentSession
      tags:
        - agent-session
      summary: Permanently purge one topmost soft-deleted agent session component
      responses:
        "200":
          description: Soft-deleted agent session tree permanently purged
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeletedAgentConversationPurgeResult"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/deleted-agent-sessions/{agentSessionID}/restore:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
    post:
      operationId: restoreWorkspaceDeletedAgentSession
      tags:
        - agent-session
      summary: Restore one topmost soft-deleted agent session component
      responses:
        "200":
          description: Soft-deleted agent session tree restored
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestoreWorkspaceDeletedAgentSessionResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "409":
          description: The deleted session is unavailable for restoration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-session-sections:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listWorkspaceAgentSessionSections
      tags:
        - agent-session
      summary: List agent session rail sections for one workspace
      parameters:
        - name: limitPerSection
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: agentTargetId
          in: query
          required: false
          description: Optional agent target filter applied before section pagination and hasMore calculation.
          schema:
            type: string
            minLength: 1
      responses:
        "200":
          description: Workspace agent session sections
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionSectionsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-session-sections/page:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listWorkspaceAgentSessionSectionPage
      tags:
        - agent-session
      summary: List one agent session rail section page for one workspace
      parameters:
        - name: sectionKey
          in: query
          required: true
          schema:
            type: string
            minLength: 1
        - name: cursor
          in: query
          required: false
          description: Cursor for the next older page, encoded as conversationSortTimeUnixMs|agentSessionId.
          schema:
            type: string
            minLength: 1
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: agentTargetId
          in: query
          required: false
          description: Optional agent target filter applied before section pagination and hasMore calculation.
          schema:
            type: string
            minLength: 1
      responses:
        "200":
          description: Workspace agent session section page
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionSectionPageResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-session-sections/deletion-candidates:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listWorkspaceAgentSessionSectionDeletionCandidates
      tags:
        - agent-session
      summary: List the exact agent session deletion candidates in one rail section
      parameters:
        - name: sectionKey
          in: query
          required: true
          schema:
            type: string
            minLength: 1
        - name: agentTargetId
          in: query
          required: false
          description: Optional agent target filter applied before selecting candidates.
          schema:
            type: string
            minLength: 1
        - name: excludePinned
          in: query
          required: false
          description: Exclude pinned sessions from the deletion candidate snapshot.
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: Workspace agent session section deletion candidates
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionSectionDeletionCandidatesResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/external-imports/scan:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    post:
      operationId: scanWorkspaceExternalAgentSessionImports
      tags:
        - agent-session
      summary: Scan local agent history or a supported provider export that can be imported into one workspace
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExternalAgentImportScanRequest"
      responses:
        "200":
          description: External agent session import scan result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExternalAgentImportScanResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/external-imports/import:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    post:
      operationId: importWorkspaceExternalAgentSessions
      tags:
        - agent-session
      summary: Import selected local agent history or provider-export conversations into one workspace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ImportExternalAgentSessionsRequest"
      responses:
        "200":
          description: External agent session import result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExternalAgentImportResultResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/agent-providers/{provider}/composer-options:
    parameters:
      - name: provider
        in: path
        required: true
        schema:
          $ref: "#/components/schemas/WorkspaceAgentProvider"
    post:
      operationId: getAgentProviderComposerOptions
      tags:
        - agent-session
      summary: Get provider composer options with Claude Code live discovery
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GetAgentProviderComposerOptionsRequest"
      responses:
        "200":
          description: Agent provider composer options with Claude Code live discovery when needed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentProviderComposerOptionsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/agent-providers/{provider}/runtime-candidates:
    parameters:
      - name: provider
        in: path
        required: true
        schema:
          $ref: "#/components/schemas/WorkspaceAgentProvider"
    get:
      operationId: getAgentProviderRuntimeCandidates
      tags:
        - agent-session
      summary: Discover and validate local runtime candidates for an agent provider
      responses:
        "200":
          description: Current runtime candidates and selection policy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentProviderRuntimeCatalogResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/agent-providers/{provider}/runtime-selection:
    parameters:
      - name: provider
        in: path
        required: true
        schema:
          $ref: "#/components/schemas/WorkspaceAgentProvider"
    put:
      operationId: setAgentProviderRuntimeSelection
      tags:
        - agent-session
      summary: Select one currently discovered runtime candidate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetAgentProviderRuntimeSelectionRequest"
      responses:
        "200":
          description: Updated runtime candidate catalog and selection policy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentProviderRuntimeCatalogResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/agent-providers/{provider}/probe:
    parameters:
      - name: provider
        in: path
        required: true
        schema:
          $ref: "#/components/schemas/WorkspaceAgentProvider"
    post:
      operationId: probeAgentProvider
      tags:
        - agent-session
      summary: Probe whether tuttid can start a local agent provider runtime command
      responses:
        "200":
          description: Agent provider runtime command probe result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentProviderProbeResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/agent-providers/{provider}/actions/{actionID}/run:
    parameters:
      - name: provider
        in: path
        required: true
        schema:
          $ref: "#/components/schemas/WorkspaceAgentProvider"
      - name: actionID
        in: path
        required: true
        schema:
          $ref: "#/components/schemas/AgentProviderActionID"
    post:
      operationId: runAgentProviderAction
      tags:
        - agent-session
      summary: Run a local agent provider action owned by tuttid
      responses:
        "200":
          description: Agent provider action run result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentProviderActionRunResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/agent-providers/status:
    get:
      operationId: getAgentProviderStatuses
      tags:
        - agent-session
      summary: Get local agent provider availability and action status
      parameters:
        - name: providers
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              $ref: "#/components/schemas/WorkspaceAgentProvider"
        - name: includeNetwork
          in: query
          required: false
          description: >-
            Opt into the network connectivity probe (registry / provider API /
            proxy reachability). Off by default so the common detection path
            stays local and never blocks on the network; only the agent-env
            wizard's network diagnostic sets this.
          schema:
            type: boolean
        - name: includeUpdates
          in: query
          required: false
          description: >-
            Opt into cached remote update discovery for provider CLIs. Off by
            default so ordinary readiness and status requests stay purely
            local. Discovery failures are reported on each provider's update
            status and do not fail the status request.
          schema:
            type: boolean
        - name: refresh
          in: query
          required: false
          description: >-
            Bypass only the daemon's local provider-readiness cache. This does
            not opt into or refresh remote update discovery.
          schema:
            type: boolean
        - name: refreshUpdates
          in: query
          required: false
          description: >-
            Bypass only the provider update-metadata cache when includeUpdates
            is true. This does not bypass local readiness or network-diagnostic
            caches and does not opt into discovery by itself.
          schema:
            type: boolean
      responses:
        "200":
          description: Agent provider status snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentProviderStatusListResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
    get:
      operationId: getWorkspaceAgentSession
      tags:
        - agent-session
      summary: Get one workspace agent session
      parameters:
        - name: projection
          in: query
          required: false
          description: Selects the detail projection. messageHydration preserves the session hierarchy and message cursors used by reconciliation discovery without resolving provider-backed lifecycle capabilities.
          schema:
            $ref: "#/components/schemas/WorkspaceAgentSessionDetailProjection"
            default: full
      responses:
        "200":
          description: Workspace agent session
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionDetailResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    delete:
      operationId: deleteWorkspaceAgentSession
      tags:
        - agent-session
      summary: Delete one workspace agent session
      responses:
        "200":
          description: Workspace agent session deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteWorkspaceAgentSessionResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "409":
          $ref: "#/components/responses/TuttiExecutionActiveError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/tutti-executions/{issueID}/cancel-execution:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - name: issueID
        in: path
        required: true
        schema:
          type: string
          minLength: 1
    post:
      operationId: cancelTuttiModeExecution
      tags:
        - workspace-workflow
      summary: Stop one active Tutti execution without archiving it
      responses:
        "200":
          description: Tutti execution stopped
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CancelIssueManagerExecutionResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceIssueResourceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/tutti-executions/{issueID}/archive:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - name: issueID
        in: path
        required: true
        schema:
          type: string
          minLength: 1
    post:
      operationId: archiveTuttiModeExecution
      tags:
        - workspace-workflow
      summary: Stop and durably archive one Tutti execution
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ArchiveTuttiModeExecutionRequest"
      responses:
        "200":
          description: Current durable archive operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TuttiModeArchiveOperation"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceIssueResourceNotFoundError"
        "409":
          $ref: "#/components/responses/TuttiModeArchiveConflictError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    get:
      operationId: getTuttiModeArchiveOperation
      tags:
        - workspace-workflow
      summary: Get the current archive operation for one Tutti execution
      parameters:
        - name: operationId
          in: query
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        "200":
          description: Current durable archive operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TuttiModeArchiveOperation"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceIssueResourceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/fork:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
    post:
      operationId: forkWorkspaceAgentSession
      tags:
        - agent-session
      summary: Fork one workspace agent session at an exact canonical boundary
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ForkWorkspaceAgentSessionRequest"
      responses:
        "200":
          description: Terminal workspace agent session fork operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionForkOperationResponse"
        "202":
          description: Accepted workspace agent session fork operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionForkOperationResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "409":
          description: The source session or requested fork boundary is not forkable. Boundary validation failures keep reason `agent_session_fork_conflict` and include the stable rejection code in `error.params.forkBoundaryReason`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-session-fork-operations/{operationID}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/SessionForkOperationID"
    get:
      operationId: getWorkspaceAgentSessionForkOperation
      tags:
        - agent-session
      summary: Get one durable workspace agent session fork operation
      responses:
        "200":
          description: Workspace agent session fork operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionForkOperationResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          description: Agent session fork operation was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-session-fork-operations/{operationID}/acknowledge:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/SessionForkOperationID"
    post:
      operationId: acknowledgeWorkspaceAgentSessionForkOperation
      tags:
        - agent-session
      summary: Acknowledge that a client observed one durable session fork operation
      description: >
        Records an explicit client-observed acknowledgement. Reading the
        operation does not implicitly acknowledge it.
      responses:
        "200":
          description: Acknowledged workspace agent session fork operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionForkOperationResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          description: Agent session fork operation was not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "409":
          description: Agent session fork operation cannot be acknowledged
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/tutti-mode-activation:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
    get:
      operationId: getWorkspaceAgentSessionTuttiModeActivation
      tags:
        - agent-session
      summary: Get the independent Tutti mode activation for one agent session
      responses:
        "200":
          description: Tutti mode activation projection
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TuttiModeActivationResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    put:
      operationId: updateWorkspaceAgentSessionTuttiModeActivation
      tags:
        - agent-session
      summary: Update the independent Tutti mode activation for one agent session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateTuttiModeActivationRequest"
      responses:
        "200":
          description: Updated Tutti mode activation projection
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UpdateTuttiModeActivationResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "409":
          description: Tutti mode activation revision conflict
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-session-sections/pinned-page:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listWorkspaceAgentPinnedSessionPage
      tags:
        - agent-session
      summary: List pinned agent session page for one workspace
      parameters:
        - name: cursor
          in: query
          required: false
          description: Cursor for the next older pinned page, encoded as pinnedAtUnixMs|agentSessionId.
          schema:
            type: string
            minLength: 1
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: agentTargetId
          in: query
          required: false
          description: Optional agent target filter applied before pinned pagination and hasMore calculation.
          schema:
            type: string
            minLength: 1
      responses:
        "200":
          description: Workspace pinned agent session page
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionPageResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-generated-files:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listWorkspaceAgentGeneratedFiles
      tags:
        - agent-session
      summary: List files generated by workspace agent sessions
      parameters:
        - in: query
          name: query
          required: false
          schema:
            type: string
        - in: query
          name: sectionKey
          required: true
          description: Persisted conversation-rail section key used to scope generated files. The pinned aggregate key is not accepted.
          schema:
            type: string
            minLength: 1
        - in: query
          name: agentTargetIds
          required: false
          description: Optional agent target filters applied before generated-file limiting.
          style: form
          explode: true
          schema:
            type: array
            maxItems: 100
            items:
              type: string
              minLength: 1
        - in: query
          name: cursor
          required: false
          description: Opaque cursor for the next page within the bounded recent generated-file result.
          schema:
            type: string
            minLength: 1
            maxLength: 32
        - in: query
          name: limit
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
      responses:
        "200":
          description: Workspace agent generated files
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentGeneratedFileListResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/messages:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
    get:
      operationId: listWorkspaceAgentSessionMessages
      tags:
        - agent-session
      summary: List persisted messages for one workspace agent session
      parameters:
        - in: query
          name: afterVersion
          required: false
          schema:
            $ref: "#/components/schemas/WorkspaceAgentMessageCursor"
        - in: query
          name: beforeVersion
          required: false
          schema:
            $ref: "#/components/schemas/WorkspaceAgentMessageCursor"
        - in: query
          name: order
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: asc
        - in: query
          name: limit
          required: false
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: Workspace agent session messages
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionMessagesResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/attachments/{attachmentID}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
      - $ref: "#/components/parameters/AgentSessionAttachmentID"
    get:
      operationId: readWorkspaceAgentSessionAttachment
      tags:
        - agent-session
      summary: Read one workspace agent session attachment
      responses:
        "200":
          description: Workspace agent session attachment
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionAttachmentResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/git-branches:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listWorkspaceGitBranches
      tags:
        - agent-session
      summary: List git branches for a workspace working directory
      parameters:
        - in: query
          name: workingDirectory
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        "200":
          description: Git branches for the working directory
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionGitBranchesResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/git-patch-support:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: resolveWorkspaceGitPatchSupport
      tags:
        - agent-session
      summary: Resolve whether git patch operations are available for a workspace working directory
      parameters:
        - in: query
          name: cwd
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        "200":
          description: Git patch support status for the working directory
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceGitPatchSupportResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-session-worktree-support:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: resolveWorkspaceAgentSessionWorktreeSupport
      tags:
        - agent-session
      summary: Resolve whether a local Agent Session can launch in an isolated git worktree
      parameters:
        - in: query
          name: agentTargetId
          required: true
          schema:
            type: string
            minLength: 1
        - in: query
          name: cwd
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        "200":
          description: Worktree launch support status for the working directory
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionWorktreeSupportResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/managed-worktrees:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listWorkspaceManagedWorktrees
      tags:
        - workspace
      summary: List explicitly managed Git worktrees for a workspace
      responses:
        "200":
          description: Managed worktrees
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceManagedWorktreeListResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/managed-worktrees/{worktreeID}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - in: path
        name: worktreeID
        required: true
        schema:
          type: string
          minLength: 1
    delete:
      operationId: deleteWorkspaceManagedWorktree
      tags:
        - workspace
      summary: Explicitly delete one clean managed Git worktree
      responses:
        "200":
          description: Managed worktree deletion result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteWorkspaceManagedWorktreeResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          description: Managed worktree was not found in this workspace
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "409":
          description: Managed worktree is dirty, ahead of its base, or changed during deletion
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/git-patch:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    post:
      operationId: applyWorkspaceGitPatch
      tags:
        - agent-session
      summary: Apply or reverse-apply a git patch in a workspace working directory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WorkspaceGitPatchRequest"
      responses:
        "200":
          description: Git patch apply result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceGitPatchResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/git-branches:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
    get:
      operationId: listWorkspaceAgentSessionGitBranches
      tags:
        - agent-session
      summary: List git branches for the agent session working directory
      responses:
        "200":
          description: Git branches for the agent session working directory
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionGitBranchesResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/turns/{turnID}/cancel:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
      - $ref: "#/components/parameters/AgentTurnID"
    post:
      operationId: cancelWorkspaceAgentTurn
      tags:
        - agent-session
      summary: Cancel one workspace agent turn
      parameters:
        - $ref: "#/components/parameters/AgentCommandOrigin"
      description: >-
        Idempotent turn-scoped cancellation (protocol v2). Canceling a turn
        that is already settled or unknown is a no-op success, not an error;
        the race between a user stop request and natural turn settlement is
        harmless at the protocol level.
      responses:
        "200":
          description: Workspace agent turn cancel result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentTurnCancelResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/turns/{turnID}/edit-retry:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
      - $ref: "#/components/parameters/AgentTurnID"
    post:
      operationId: editRetryWorkspaceAgentTurn
      tags:
        - agent-session
      summary: Edit and retry the latest completed user turn
      description: >-
        Starts or resumes one idempotent durable edit-retry operation. The
        operation retracts exactly one latest completed user turn from the
        effective provider history and submits its edited replacement while
        preserving non-text input. A completed operation returns 200; a
        durable operation that still needs confirmation or explicit recovery
        returns 202.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EditRetryWorkspaceAgentTurnRequest"
      responses:
        "200":
          description: Edit-retry operation completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentEditRetryResponse"
        "202":
          description: Edit-retry operation is durably pending confirmation or recovery
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentEditRetryResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "409":
          description: The turn, history revision, or operation identity conflicts with current canonical state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/edit-retry-operations/{operationID}/recover:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
      - name: operationID
        in: path
        required: true
        schema:
          type: string
          minLength: 1
    post:
      operationId: recoverWorkspaceAgentEditRetry
      tags:
        - agent-session
      summary: Reconcile or safely retry one durable edit-retry operation
      description: >-
        Reconcile is provider-read-only. retry_replacement is accepted only
        after Host proves from authoritative provider history that the prior
        replacement was not dispatched.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecoverWorkspaceAgentEditRetryRequest"
      responses:
        "200":
          description: Edit-retry recovery completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentEditRetryResponse"
        "202":
          description: Edit-retry operation remains durably pending confirmation or recovery
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentEditRetryResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "409":
          description: The operation identity or requested recovery action conflicts with current canonical state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/side-capabilities:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
    get:
      operationId: resolveWorkspaceAgentSideCapabilities
      tags:
        - agent-session
      summary: Resolve transient Side support for a live agent session
      responses:
        "200":
          description: Side capabilities for the live source session
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSideCapabilitiesResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "409":
          description: The source session is not eligible for Side
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/side-conversations:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
    post:
      operationId: openWorkspaceAgentSideConversation
      tags:
        - agent-session
      summary: Open one runtime-only Side conversation from a live source session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OpenWorkspaceAgentSideConversationRequest"
      responses:
        "200":
          description: Opened or reconciled transient Side conversation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSideConversationResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "409":
          description: Side identity conflicts, is opening, or the source is ineligible
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-side-conversations/{sideAgentSessionID}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - in: path
        name: sideAgentSessionID
        required: true
        schema:
          type: string
          minLength: 1
    delete:
      operationId: closeWorkspaceAgentSideConversation
      tags:
        - agent-session
      summary: Close and release one runtime-only Side conversation
      responses:
        "204":
          description: Side conversation closed or already absent
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-side-conversations/{sideAgentSessionID}/turns:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - in: path
        name: sideAgentSessionID
        required: true
        schema:
          type: string
          minLength: 1
    post:
      operationId: sendWorkspaceAgentSideConversationInput
      tags:
        - agent-session
      summary: Send one input to a runtime-only Side conversation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SendWorkspaceAgentSideConversationInputRequest"
      responses:
        "200":
          description: Accepted transient Side turn
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSideTurnResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "409":
          description: The Side conversation has expired or cannot accept input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-side-conversations/{sideAgentSessionID}/turns/{turnID}/cancel:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - in: path
        name: sideAgentSessionID
        required: true
        schema:
          type: string
          minLength: 1
      - $ref: "#/components/parameters/AgentTurnID"
    post:
      operationId: cancelWorkspaceAgentSideConversationTurn
      tags:
        - agent-session
      summary: Cancel the exact active turn in a runtime-only Side conversation
      responses:
        "200":
          description: Side turn cancel result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSideTurnCancelResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "409":
          description: The Side conversation has expired
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-side-conversations/{sideAgentSessionID}/turns/{turnID}/interactive/{requestID}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - in: path
        name: sideAgentSessionID
        required: true
        schema:
          type: string
          minLength: 1
      - $ref: "#/components/parameters/AgentTurnID"
      - $ref: "#/components/parameters/AgentPermissionRequestID"
    post:
      operationId: submitWorkspaceAgentSideConversationInteractive
      tags:
        - agent-session
      summary: Respond to one live interactive request in a Side conversation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SubmitWorkspaceAgentSideConversationInteractiveRequest"
      responses:
        "200":
          description: Side interactive response disposition
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSideInteractiveResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "409":
          description: The Side conversation or interaction is no longer live
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/turns/{turnID}/plan-decisions/{requestID}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
      - $ref: "#/components/parameters/AgentTurnID"
      - $ref: "#/components/parameters/AgentPermissionRequestID"
    post:
      operationId: submitWorkspaceAgentPlanDecision
      tags:
        - agent-session
      summary: Submit one durable workspace agent plan decision
      parameters:
        - $ref: "#/components/parameters/AgentCommandOrigin"
      description: >-
        Prepares and advances an idempotent daemon-owned plan decision saga.
        The workspace, session, turn, request, and idempotency key form the
        strict operation scope. A retry with the same identity and payload
        returns the existing operation; a mismatched payload is rejected.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SubmitWorkspaceAgentPlanDecisionRequest"
      responses:
        "200":
          description: Durable plan decision operation state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentPlanDecisionResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "409":
          description: The idempotency identity conflicts or the scoped plan turn is not currently decidable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/goal:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
    get:
      operationId: getWorkspaceAgentSessionGoal
      tags:
        - agent-session
      summary: Get the durable desired and observed goal state
      responses:
        "200":
          description: Workspace agent session goal state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionGoalStateResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    post:
      operationId: goalControlWorkspaceAgentSession
      tags:
        - agent-session
      summary: Perform a goal control action on one workspace agent session
      parameters:
        - $ref: "#/components/parameters/AgentCommandOrigin"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WorkspaceAgentSessionGoalControlRequest"
      responses:
        "200":
          description: Workspace agent session goal updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionGoalControlResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/goal/reconcile:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
    post:
      operationId: reconcileWorkspaceAgentSessionGoal
      tags:
        - agent-session
      summary: Reconcile the durable goal projection with provider evidence
      responses:
        "200":
          description: Reconciled workspace agent session goal state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionGoalStateResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/input:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
    post:
      operationId: sendWorkspaceAgentSessionInput
      tags:
        - agent-session
      summary: Send user input to one workspace agent session
      parameters:
        - $ref: "#/components/parameters/AgentCommandOrigin"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SendWorkspaceAgentSessionInputRequest"
      responses:
        "200":
          description: Workspace agent session input accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SendWorkspaceAgentSessionInputResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/settings:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
    post:
      operationId: updateWorkspaceAgentSessionSettings
      tags:
        - agent-session
      summary: Update one workspace agent session settings
      parameters:
        - $ref: "#/components/parameters/AgentCommandOrigin"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AgentSessionComposerSettings"
      responses:
        "200":
          description: Workspace agent session settings updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/title:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
    post:
      operationId: updateWorkspaceAgentSessionTitle
      tags:
        - agent-session
      summary: Update one workspace agent session title
      description: >-
        Titles longer than 120 Unicode characters return `invalid_request` with
        reason `workspace_agent_session_title_too_long` and
        `params.maxCharacters` set to 120.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateWorkspaceAgentSessionTitleRequest"
      responses:
        "200":
          description: Workspace agent session title updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/visibility:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
    post:
      operationId: updateWorkspaceAgentSessionVisibility
      tags:
        - agent-session
      summary: Update one workspace agent session visibility
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateWorkspaceAgentSessionVisibilityRequest"
      responses:
        "200":
          description: Workspace agent session visibility updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/pin:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
    post:
      operationId: updateWorkspaceAgentSessionPin
      tags:
        - agent-session
      summary: Update one workspace agent session pinned state
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateWorkspaceAgentSessionPinRequest"
      responses:
        "200":
          description: Workspace agent session pinned state updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/interactives/{requestID}/response:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
      - $ref: "#/components/parameters/AgentPermissionRequestID"
    post:
      operationId: submitWorkspaceAgentInteractive
      tags:
        - agent-session
      summary: Submit one workspace agent interactive response
      parameters:
        - $ref: "#/components/parameters/AgentCommandOrigin"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SubmitWorkspaceAgentInteractiveRequest"
      responses:
        "200":
          description: Workspace agent interactive response accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgentSessionResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "409":
          $ref: "#/components/responses/AgentInteractiveConflictError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/terminals:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listWorkspaceTerminals
      tags:
        - terminal
      summary: List live terminal sessions for one workspace
      responses:
        "200":
          description: Workspace terminal sessions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceTerminalListResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    post:
      operationId: createWorkspaceTerminal
      tags:
        - terminal
      summary: Create a local terminal session for one workspace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWorkspaceTerminalRequest"
      responses:
        "201":
          description: Workspace terminal session created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceTerminalResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/terminals/{terminalID}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/TerminalID"
    get:
      operationId: getWorkspaceTerminal
      tags:
        - terminal
      summary: Get one workspace terminal session
      responses:
        "200":
          description: Workspace terminal session
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceTerminalResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceTerminalNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    delete:
      operationId: terminateWorkspaceTerminal
      tags:
        - terminal
      summary: Terminate one workspace terminal session
      responses:
        "200":
          description: Workspace terminal session terminated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceTerminalResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceTerminalNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/terminals/{terminalID}/close-guard:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/TerminalID"
    post:
      operationId: checkWorkspaceTerminalCloseGuard
      tags:
        - terminal
      summary: Check whether terminating a terminal session requires confirmation
      responses:
        "200":
          description: Workspace terminal close guard state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceTerminalCloseGuardResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceTerminalNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/terminals/{terminalID}/resize:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/TerminalID"
    post:
      operationId: resizeWorkspaceTerminal
      tags:
        - terminal
      summary: Resize one workspace terminal session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResizeWorkspaceTerminalRequest"
      responses:
        "200":
          description: Workspace terminal resized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceTerminalResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceTerminalNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/terminals/{terminalID}/snapshot:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/TerminalID"
    get:
      operationId: getWorkspaceTerminalSnapshot
      tags:
        - terminal
      summary: Get replay snapshot for one workspace terminal session
      responses:
        "200":
          description: Workspace terminal snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceTerminalSnapshotResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceTerminalNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/terminals/{terminalID}/ws:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/TerminalID"
      - $ref: "#/components/parameters/TerminalAfterSeq"
    get:
      operationId: attachWorkspaceTerminal
      tags:
        - terminal
      summary: Attach a WebSocket stream to one workspace terminal session
      responses:
        "200":
          description: Terminal stream upgrade endpoint
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceTerminalNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/files/directory:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listWorkspaceFileDirectory
      tags:
        - workspace
      summary: List direct children for one workspace directory
      parameters:
        - $ref: "#/components/parameters/WorkspaceFilePath"
        - $ref: "#/components/parameters/WorkspaceFileIncludeHidden"
      responses:
        "200":
          description: Workspace directory listing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceFileDirectoryResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceFileNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    put:
      operationId: createWorkspaceFileDirectory
      tags:
        - workspace
      summary: Create one workspace directory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWorkspaceFileDirectoryRequest"
      responses:
        "200":
          description: Workspace directory created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceFileEntryResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceFileNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/issues/{issueID}/tutti-mode-review/self:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/IssueID"
    post:
      operationId: switchTuttiModeGoalReviewToSelf
      tags:
        - workspace
      summary: Switch a failed independent Tutti Mode Goal Review to self review
      description: >-
        Performs the explicit audited fallback for one failed independent
        reviewer operation. The authenticated local actor is resolved by the
        daemon and cannot be supplied in the request body.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SwitchTuttiModeGoalReviewToSelfRequest"
      responses:
        "200":
          description: Goal Review switched to self review, or an idempotent replay
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SwitchTuttiModeGoalReviewToSelfResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/TuttiModeGoalReviewNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "409":
          $ref: "#/components/responses/TuttiModeGoalReviewConflictError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/files/recent:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listWorkspaceRecentFiles
      tags:
        - workspace
      summary: List the workspace's recently accessed entries, most-recent first
      parameters:
        - $ref: "#/components/parameters/WorkspaceFileRecentLimit"
      responses:
        "200":
          description: Workspace recent files listing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceFileDirectoryResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceFileNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/files/tree-snapshot:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: getWorkspaceFileTreeSnapshot
      tags:
        - workspace
      summary: Get one workspace directory tree snapshot with budgeted prefetch
      parameters:
        - $ref: "#/components/parameters/WorkspaceFilePath"
        - $ref: "#/components/parameters/WorkspaceFileIncludeHidden"
        - $ref: "#/components/parameters/WorkspaceFilePrefetchDepth"
        - $ref: "#/components/parameters/WorkspaceFilePrefetchBudgetMs"
      responses:
        "200":
          description: Workspace directory tree snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceFileTreeSnapshotResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceFileNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/files/search:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: searchWorkspaceFiles
      tags:
        - workspace
      summary: Search workspace files by logical path
      parameters:
        - $ref: "#/components/parameters/WorkspaceFileSearchQuery"
        - $ref: "#/components/parameters/WorkspaceFileSearchWithin"
        - $ref: "#/components/parameters/WorkspaceFileSearchLimit"
        - $ref: "#/components/parameters/WorkspaceFileSearchKinds"
        - $ref: "#/components/parameters/WorkspaceFileSearchFilters"
        - $ref: "#/components/parameters/WorkspaceFileIncludeHidden"
      responses:
        "200":
          description: Workspace file search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceFileSearchResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/files/file:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    put:
      operationId: createWorkspaceFile
      tags:
        - workspace
      summary: Create one workspace file
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWorkspaceFileRequest"
      responses:
        "200":
          description: Workspace file created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceFileEntryResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceFileNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/files/file/preview:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: readWorkspaceFilePreview
      tags:
        - workspace
      summary: Read bytes for one workspace file preview
      parameters:
        - $ref: "#/components/parameters/WorkspaceFilePath"
      responses:
        "200":
          description: Workspace file preview bytes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceFilePreviewResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceFileNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/files/file/text:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    put:
      operationId: writeWorkspaceFileText
      tags:
        - workspace
      summary: Write UTF-8 text content to one workspace file
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WriteWorkspaceFileTextRequest"
      responses:
        "200":
          description: Workspace file written
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceFileEntryResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceFileNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/files/entry:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    delete:
      operationId: deleteWorkspaceFileEntry
      tags:
        - workspace
      summary: Delete one workspace file entry
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeleteWorkspaceFileEntryRequest"
      responses:
        "200":
          description: Workspace file entry deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteWorkspaceFileEntryResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceFileNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/files/entry/move:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    post:
      operationId: moveWorkspaceFileEntry
      tags:
        - workspace
      summary: Move one workspace file entry into one directory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MoveWorkspaceFileEntryRequest"
      responses:
        "200":
          description: Workspace file entry moved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceFileEntryResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceFileNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/files/entry/rename:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    post:
      operationId: renameWorkspaceFileEntry
      tags:
        - workspace
      summary: Rename one workspace file entry in place
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RenameWorkspaceFileEntryRequest"
      responses:
        "200":
          description: Workspace file entry renamed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceFileEntryResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceFileNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/files/entry/copy:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    post:
      operationId: copyWorkspaceFileEntry
      tags:
        - workspace
      summary: Duplicate one workspace file entry in its parent directory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CopyWorkspaceFileEntryRequest"
      responses:
        "200":
          description: Workspace file entry copied
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceFileEntryResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceFileNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/files/upload:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    post:
      operationId: uploadWorkspaceFiles
      tags:
        - workspace
      summary: Upload local files into one workspace directory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UploadWorkspaceFilesRequest"
      responses:
        "200":
          description: Workspace files uploaded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadWorkspaceFilesResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceFileNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/files/upload/preflight:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    post:
      operationId: preflightUploadWorkspaceFiles
      tags:
        - workspace
      summary: Detect conflicting local file uploads into one workspace directory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PreflightUploadWorkspaceFilesRequest"
      responses:
        "200":
          description: Workspace upload conflicts detected
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PreflightUploadWorkspaceFilesResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceFileNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/open:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    post:
      operationId: openWorkspace
      tags:
        - workspace
      summary: Open one workspace
      responses:
        "200":
          description: Workspace open request accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agents:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listWorkspaceAgents
      tags:
        - workspace-agent
      summary: List the configured Agent options for one workspace
      description: Returns explicit workspace Agent configurations. Each Agent maps one harness target to an optional model access plan and carries its own description, instructions, and call conditions.
      responses:
        "200":
          description: Workspace Agent configurations
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListWorkspaceAgentsResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    post:
      operationId: createWorkspaceAgent
      tags:
        - workspace-agent
      summary: Create one selectable workspace Agent
      description: Creates an explicit Agent option from a harness target plus an optional model access plan. It does not generate a Harness by ModelPlan Cartesian product.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutWorkspaceAgentRequest"
      responses:
        "201":
          description: Created workspace Agent
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgent"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agents/{workspaceAgentID}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/WorkspaceAgentID"
    get:
      operationId: getWorkspaceAgent
      tags:
        - workspace-agent
      summary: Get one workspace Agent configuration
      responses:
        "200":
          description: Workspace Agent configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgent"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    put:
      operationId: updateWorkspaceAgent
      tags:
        - workspace-agent
      summary: Replace one workspace Agent configuration
      description: Replaces mutable fields and increments the Agent revision. Omitted or null modelPlanId/defaultModel clear those fields. Existing sessions continue using their recorded runtime configuration.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutWorkspaceAgentRequest"
      responses:
        "200":
          description: Updated workspace Agent
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceAgent"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    delete:
      operationId: deleteWorkspaceAgent
      tags:
        - workspace-agent
      summary: Delete one workspace Agent configuration
      description: Deletes only the named workspace Agent. Its Harness target and ModelPlan remain unchanged.
      responses:
        "200":
          description: Workspace Agent deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteWorkspaceAgentResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/automation-rules:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
    get:
      operationId: listAutomationRules
      tags:
        - automation-rule
      summary: List workspace automation rules
      description: Returns action-centric rules that react to Agent session lifecycle events. Rules target either a ModelPlan for a tool-free consult or a WorkspaceAgent for fork, delegate, and handoff actions.
      responses:
        "200":
          description: Workspace automation rules
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListAutomationRulesResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    post:
      operationId: createAutomationRule
      tags:
        - automation-rule
      summary: Create a workspace automation rule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutAutomationRuleRequest"
      responses:
        "201":
          description: Created automation rule
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AutomationRule"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/automation-rules/{automationRuleID}:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AutomationRuleID"
    get:
      operationId: getAutomationRule
      tags:
        - automation-rule
      summary: Get a workspace automation rule
      responses:
        "200":
          description: Workspace automation rule
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AutomationRule"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    put:
      operationId: updateAutomationRule
      tags:
        - automation-rule
      summary: Replace a workspace automation rule
      description: Replaces mutable rule fields. Changes apply only to future trigger evaluations; already-started actions keep their recorded configuration.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PutAutomationRuleRequest"
      responses:
        "200":
          description: Updated automation rule
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AutomationRule"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    delete:
      operationId: deleteAutomationRule
      tags:
        - automation-rule
      summary: Delete a workspace automation rule
      responses:
        "200":
          description: Automation rule deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeleteAutomationRuleResponse"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
  /v1/workspaces/{workspaceID}/agent-sessions/{agentSessionID}/automation-rule-override:
    parameters:
      - $ref: "#/components/parameters/WorkspaceID"
      - $ref: "#/components/parameters/AgentSessionID"
    get:
      operationId: getAgentSessionAutomationRuleOverride
      tags:
        - automation-rule
      summary: Get the session-level automation rule override
      description: An absent override returns disabled=false and an empty rule id list.
      responses:
        "200":
          description: Session automation rule override
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSessionAutomationRuleOverride"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    put:
      operationId: setAgentSessionAutomationRuleOverride
      tags:
        - automation-rule
      summary: Disable or select automation rules for one session
      description: Disabled stops every future rule evaluation for this session. A non-empty ruleIds list replaces the workspace rule set for this session; an empty list uses all enabled workspace rules. Already-started actions are unchanged.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetAgentSessionAutomationRuleOverrideRequest"
      responses:
        "200":
          description: Updated session automation rule override
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentSessionAutomationRuleOverride"
        "400":
          $ref: "#/components/responses/InvalidRequestError"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/WorkspaceNotFoundError"
        "405":
          $ref: "#/components/responses/MethodNotAllowedError"
        "502":
          $ref: "#/components/responses/WorkspaceOperationError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  parameters:
    AgentCommandOrigin:
      name: X-Tutti-Agent-Command-Origin
      in: header
      required: false
      description: >-
        Typed caller provenance for Agent command recording. Renderer Engine
        commands use renderer-engine; absent provenance identifies direct API
        and CLI commands.
      schema:
        type: string
        enum:
          - renderer-engine
    CliCommandID:
      name: commandID
      in: path
      required: true
      schema:
        type: string
        minLength: 1
    WorkspaceID:
      name: workspaceID
      in: path
      required: true
      schema:
        type: string
        minLength: 1
    SessionForkOperationID:
      name: operationID
      in: path
      required: true
      schema:
        type: string
        minLength: 1
    IssueID:
      name: issueID
      in: path
      required: true
      schema:
        type: string
        minLength: 1
    WorkspaceAppID:
      name: appID
      in: path
      required: true
      schema:
        type: string
        minLength: 1
    WorkspaceAppFactoryJobID:
      name: jobID
      in: path
      required: true
      schema:
        type: string
        minLength: 1
    ModelPlanID:
      name: modelPlanID
      in: path
      required: true
      schema:
        type: string
        minLength: 1
    WorkspaceAgentID:
      name: workspaceAgentID
      in: path
      required: true
      schema:
        type: string
        minLength: 1
    ModelPolicyID:
      name: modelPolicyID
      in: path
      required: true
      schema:
        type: string
        minLength: 1
    CollaborationRunID:
      name: collaborationRunID
      in: path
      required: true
      schema:
        type: string
        minLength: 1
    WorkspaceFilePath:
      name: path
      in: query
      description: Omit to resolve the current workspace file root.
      required: false
      schema:
        type: string
        minLength: 1
    WorkspaceFileIncludeHidden:
      name: includeHidden
      in: query
      required: false
      schema:
        type: boolean
        default: false
    WorkspaceFilePrefetchDepth:
      name: prefetchDepth
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 8
        default: 4
    WorkspaceFilePrefetchBudgetMs:
      name: prefetchBudgetMs
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 5000
        default: 500
    WorkspaceFileSearchQuery:
      name: query
      in: query
      required: true
      schema:
        type: string
    WorkspaceFileSearchWithin:
      name: within
      in: query
      required: false
      description: >-
        可选:把搜索限定在工作区根下的某子路径(对应左栏选中的「位置」,如
        文稿/下载/桌面)。相对工作区根的逻辑路径;缺省/空 = 跨整根搜索。
      schema:
        type: string
        minLength: 1
    WorkspaceFileSearchLimit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 30
    WorkspaceFileRecentLimit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 30
    WorkspaceFileSearchKinds:
      name: includeKinds
      in: query
      required: false
      style: form
      explode: true
      schema:
        type: array
        items:
          $ref: "#/components/schemas/WorkspaceFileFilterKind"
    WorkspaceFileSearchFilters:
      name: filters
      in: query
      required: false
      style: form
      explode: true
      description: >-
        已选「文件类型筛选分类」id(全局统一口径:image/video/document/
        webpage/other)。筛选与搜索是同一能力:query 可空、filters
        非空时即按类型 list-all。空/缺省 = 不按类型过滤。
      schema:
        type: array
        items:
          type: string
    TerminalID:
      name: terminalID
      in: path
      required: true
      schema:
        type: string
        minLength: 1
    AgentSessionID:
      name: agentSessionID
      in: path
      required: true
      schema:
        type: string
        minLength: 1
    AgentSessionAttachmentID:
      name: attachmentID
      in: path
      required: true
      schema:
        type: string
        minLength: 1
    AgentPermissionRequestID:
      name: requestID
      in: path
      required: true
      schema:
        type: string
        minLength: 1
    AgentTurnID:
      name: turnID
      in: path
      required: true
      schema:
        type: string
        minLength: 1
    TerminalAfterSeq:
      name: afterSeq
      in: query
      required: false
      schema:
        type: integer
        format: int64
        minimum: 0
    AutomationRuleID:
      name: automationRuleID
      in: path
      required: true
      schema:
        type: string
        minLength: 1
  responses:
    UnauthorizedError:
      description: Bearer token is missing or invalid
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            unauthorized:
              value:
                error:
                  code: unauthorized
                  reason: missing_or_invalid_token
                  developerMessage: daemon request is not authorized
    InvalidRequestError:
      description: Request payload or parameters are invalid
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            invalidRequest:
              value:
                error:
                  code: invalid_request
                  reason: missing_workspace_id
                  developerMessage: workspace id is required
    TuttiExecutionActiveError:
      description: One or more source sessions own a nonterminal Tutti execution
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            protectedSource:
              value:
                error:
                  code: tutti_execution_active
                  reason: tutti_execution_active
                  params:
                    workspaceId: workspace-1
                    protectedIssues:
                      - issueId: issue-1
                        executionId: execution-1
                        sourceSessionId: session-1
                        status: running
    MethodNotAllowedError:
      description: HTTP method is not supported on this route
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            methodNotAllowed:
              value:
                error:
                  code: method_not_allowed
                  reason: method_not_allowed
                  developerMessage: method not allowed
    ServiceUnavailableError:
      description: Required daemon service dependency is unavailable
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            serviceUnavailable:
              value:
                error:
                  code: service_unavailable
                  reason: workspace_service_unavailable
                  developerMessage: workspace service is unavailable
    WorkspaceNotFoundError:
      description: Workspace id was not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            workspaceNotFound:
              value:
                error:
                  code: workspace_not_found
                  reason: workspace_not_found
                  developerMessage: workspace not found
    WorkspaceFileNotFoundError:
      description: Workspace file entry was not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            workspaceFileNotFound:
              value:
                error:
                  code: workspace_file_not_found
                  reason: workspace_file_not_found
                  developerMessage: workspace file entry not found
    WorkspaceTerminalNotFoundError:
      description: Workspace terminal session was not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            workspaceTerminalNotFound:
              value:
                error:
                  code: workspace_terminal_not_found
                  reason: workspace_terminal_not_found
                  developerMessage: workspace terminal session not found
    WorkspaceAppNotFoundError:
      description: Workspace app was not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            workspaceAppNotFound:
              value:
                error:
                  code: workspace_app_not_found
                  reason: workspace_app_not_found
                  developerMessage: workspace app not found
    WorkspaceOperationError:
      description: Workspace operation failed in an upstream adapter or command
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            workspaceOperationFailed:
              value:
                error:
                  code: workspace_operation_failed
                  reason: workspace_operation_failed
                  developerMessage: workspace operation failed
            agentConfigDependencyUnavailable:
              value:
                error:
                  code: workspace_operation_failed
                  reason: agent.config_dependency_unavailable
                  params:
                    provider: codex
                    configKey: model_instructions_file
                    dependencyPath: instructions.md
                    failureKind: missing
                  retryable: false
                  developerMessage: codex configuration dependency model_instructions_file is unavailable
    AgentInteractiveConflictError:
      description: Interactive response no longer matches a pending canonical request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            staleInteractiveResponse:
              value:
                error:
                  code: workspace_operation_failed
                  reason: agent_interactive_request_stale
                  developerMessage: interactive request is no longer live
    AgentTargetNotFoundError:
      description: Agent target was not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            agentTargetNotFound:
              value:
                error:
                  code: agent_target_not_found
                  reason: agent_target_not_found
                  developerMessage: agent target not found
    ModelPlanNotFoundError:
      description: Model access plan was not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            modelPlanNotFound:
              value:
                error:
                  code: model_plan_not_found
                  reason: model_plan_not_found
                  developerMessage: model plan not found
    ModelPlanReferencedError:
      description: Model plan is still referenced by agent targets
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            modelPlanReferenced:
              value:
                error:
                  code: model_plan_referenced
                  reason: model_plan_referenced
                  developerMessage: model plan is still referenced; rebind or disable consumers first
    ModelPolicyReferencedError:
      description: Model usage policy is still referenced by agent bindings
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            modelPolicyReferenced:
              value:
                error:
                  code: model_policy_referenced
                  reason: model_policy_referenced
                  developerMessage: model usage policy is still referenced; rebind or clear the referencing bindings first
    PreferencesOperationError:
      description: Desktop preferences operation failed in an upstream adapter or command
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            preferencesOperationFailed:
              value:
                error:
                  code: preferences_operation_failed
                  reason: preferences_operation_failed
                  developerMessage: desktop preferences operation failed
    AgentQuickPromptNotFoundError:
      description: Agent quick prompt was not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
    AgentQuickPromptConflictError:
      description: Agent quick prompt limit, expected version, or ordering anchor conflicts with current state
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
    AgentQuickPromptOperationError:
      description: Agent quick prompt persistence operation failed
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
    TuttiModeGoalReviewNotFoundError:
      description: Tutti Mode execution or Goal Review was not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            goalReviewNotFound:
              value:
                error:
                  code: tutti_mode_goal_review_not_found
                  reason: tutti_goal_review_not_found
    TuttiModeGoalReviewConflictError:
      description: Goal Review fallback conflicts with current durable state or request history
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            goalReviewConflict:
              value:
                error:
                  code: tutti_mode_goal_review_conflict
                  reason: tutti_goal_review_conflict
    TuttiModeArchiveConflictError:
      description: Archive request id conflicts with a different durable archive request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          examples:
            archiveRequestConflict:
              value:
                error:
                  code: tutti_mode_archive_conflict
                  reason: tutti_archive_request_conflict
  schemas:
    AccountUserPresenceCurrentRoomRequest:
      type: object
      required:
        - roomId
        - members
      properties:
        roomId:
          type: string
          minLength: 1
        members:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/AccountUserPresenceRoomMember"
    AccountUserPresenceRoomMember:
      type: object
      required:
        - userId
        - membershipActive
        - accountPresenceCapable
      properties:
        userId:
          type: string
          minLength: 1
          maxLength: 256
        membershipActive:
          type: boolean
          description: True only for a currently joined, non-deleted membership.
        accountPresenceCapable:
          type: boolean
          description: False for system identities without Account Device Presence semantics.
    AccountUserPresenceForegroundRequest:
      type: object
      required:
        - foreground
      properties:
        foreground:
          type: boolean
    AccountUserPresenceRoomResponse:
      type: object
      required:
        - roomId
        - members
      properties:
        roomId:
          type: string
        members:
          type: array
          items:
            $ref: "#/components/schemas/AccountUserPresenceUser"
    AccountUserPresenceUser:
      type: object
      required:
        - userId
        - status
        - availability
        - authoritative
        - authorityGeneration
        - presenceRevision
      properties:
        userId:
          type: string
        status:
          type: string
          enum:
            - ONLINE
            - OFFLINE
        availability:
          type: string
          enum:
            - NOT_WATCHED
            - SUBSCRIBING
            - SYNCING
            - READY
            - STALE
            - UNKNOWN
            - DEGRADED
        authoritative:
          type: boolean
        authorityGeneration:
          type: string
        presenceRevision:
          type: string
          pattern: "^[0-9]*$"
        observedAt:
          type: string
          format: date-time
          nullable: true
    SwitchTuttiModeGoalReviewToSelfRequest:
      type: object
      additionalProperties: false
      required:
        - checkpointId
        - expectedGraphRevision
        - requestId
        - reason
      properties:
        checkpointId:
          type: string
          minLength: 1
        expectedGraphRevision:
          type: integer
          format: int64
          minimum: 1
        requestId:
          type: string
          minLength: 1
        reason:
          type: string
          minLength: 1
    SwitchTuttiModeGoalReviewToSelfResponse:
      type: object
      additionalProperties: false
      required:
        - executionId
        - reviewId
        - reviewMode
        - replayed
      properties:
        executionId:
          type: string
          minLength: 1
        reviewId:
          type: string
          minLength: 1
        reviewMode:
          type: string
          enum:
            - self
        replayed:
          type: boolean
    HealthStatusResponse:
      type: object
      additionalProperties: false
      required:
        - service
        - status
      properties:
        service:
          type: string
        status:
          type: string
          enum:
            - ok
    TrackEventsRequest:
      type: object
      additionalProperties: false
      required:
        - events
      properties:
        events:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: "#/components/schemas/TrackEvent"
    TrackEvent:
      type: object
      additionalProperties: false
      required:
        - name
        - client_ts
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 128
          pattern: "^[a-z][a-z0-9_]*(?:\\.[a-z][a-z0-9_]*)+$"
        client_ts:
          type: integer
          format: int64
          minimum: 1
        params:
          type: object
          additionalProperties: true
    AccountUserInfo:
      type: object
      additionalProperties: false
      required:
        - user_id
      properties:
        user_id:
          type: string
          minLength: 1
        name:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        avatar:
          type: string
          nullable: true
    AccountUserInfoResponse:
      type: object
      additionalProperties: false
      required:
        - user
      properties:
        user:
          allOf:
            - $ref: "#/components/schemas/AccountUserInfo"
          nullable: true
    GlobalAgentActivityRoom:
      type: object
      additionalProperties: false
      required:
        - roomId
        - name
        - avatarUri
      properties:
        roomId:
          type: string
          minLength: 1
        name:
          type: string
        avatarUri:
          type: string
    GlobalAgentActivitySessionOwner:
      type: object
      additionalProperties: false
      required:
        - userId
        - displayName
        - avatarUrl
        - avatarFallbackUrl
        - avatarClientTransform
      properties:
        userId:
          type: string
          minLength: 1
        displayName:
          type: string
        avatarUrl:
          type: string
        avatarFallbackUrl:
          type: string
        avatarClientTransform:
          type: boolean
    GlobalAgentActivityAgent:
      type: object
      additionalProperties: false
      required:
        - agentKey
        - agentTargetId
        - provider
        - name
        - iconKey
      properties:
        agentKey:
          type: string
          minLength: 1
        agentTargetId:
          type: string
        provider:
          type: string
        name:
          type: string
        iconKey:
          type: string
    GlobalAgentActivityTimeBounds:
      type: object
      additionalProperties: false
      required:
        - minActivityAtUnixMs
        - maxActivityAtUnixMs
        - serverNowUnixMs
      properties:
        minActivityAtUnixMs:
          type: integer
          format: int64
        maxActivityAtUnixMs:
          type: integer
          format: int64
        serverNowUnixMs:
          type: integer
          format: int64
    GlobalAgentActivityFilterOptionsResponse:
      type: object
      additionalProperties: false
      required:
        - rooms
        - sessionOwners
        - agents
        - timeBounds
      properties:
        rooms:
          type: array
          items:
            $ref: "#/components/schemas/GlobalAgentActivityRoom"
        sessionOwners:
          type: array
          items:
            $ref: "#/components/schemas/GlobalAgentActivitySessionOwner"
        agents:
          type: array
          items:
            $ref: "#/components/schemas/GlobalAgentActivityAgent"
        timeBounds:
          $ref: "#/components/schemas/GlobalAgentActivityTimeBounds"
    GlobalAgentActivitySession:
      type: object
      additionalProperties: false
      required:
        - room
        - workspaceId
        - agentSessionId
        - sessionOwner
        - agent
        - status
        - title
        - summary
        - latestUserPrompt
        - needsAttention
        - activityAtUnixMs
        - latestMessageAtUnixMs
        - startedAtUnixMs
        - endedAtUnixMs
        - latestTurnId
      properties:
        room:
          $ref: "#/components/schemas/GlobalAgentActivityRoom"
        workspaceId:
          type: string
          minLength: 1
        agentSessionId:
          type: string
          minLength: 1
        sessionOwner:
          $ref: "#/components/schemas/GlobalAgentActivitySessionOwner"
        agent:
          $ref: "#/components/schemas/GlobalAgentActivityAgent"
        status:
          type: string
        title:
          type: string
        summary:
          type: string
        latestUserPrompt:
          type: string
        needsAttention:
          type: boolean
        activityAtUnixMs:
          type: integer
          format: int64
        latestMessageAtUnixMs:
          type: integer
          format: int64
        startedAtUnixMs:
          type: integer
          format: int64
        endedAtUnixMs:
          type: integer
          format: int64
        latestTurnId:
          type: string
    GlobalAgentActivitySessionListResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - truncated
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/GlobalAgentActivitySession"
        truncated:
          type: boolean
    AccountMembershipSummary:
      type: object
      additionalProperties: false
      required:
        - tier_key
        - display_name
      properties:
        tier_key:
          type: string
          minLength: 1
        display_name:
          type: string
          minLength: 1
        billing_period:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
        access_status:
          type: string
          nullable: true
        current_period_end:
          type: string
          nullable: true
        cancel_at_period_end:
          type: boolean
          nullable: true
    AccountMembershipAccessState:
      type: string
      enum:
        - free
        - active
        - inactive
        - unknown
    AccountCreditsSummary:
      type: object
      additionalProperties: false
      required:
        - available_credits
      properties:
        available_credits:
          type: string
          nullable: true
        expiring_credits_within_24h:
          type: string
          nullable: true
        next_expire_at:
          type: string
          nullable: true
        refreshed_at:
          type: string
          nullable: true
    AccountProductSummaryLinks:
      type: object
      additionalProperties: false
      required:
        - plan_url
        - usage_url
        - settings_url
      properties:
        plan_url:
          type: string
          minLength: 1
        usage_url:
          type: string
          minLength: 1
        settings_url:
          type: string
          minLength: 1
    AccountProductSummaryPartialError:
      type: object
      additionalProperties: false
      required:
        - scope
        - code
      properties:
        scope:
          type: string
          enum:
            - membership
            - credits
            - links
            - unknown
        code:
          type: string
        message:
          type: string
          nullable: true
    AccountRegistrationCreditsReward:
      type: object
      additionalProperties: false
      required:
        - id
        - grant_no
        - credits
        - created_at
      properties:
        id:
          type: string
          minLength: 1
        grant_no:
          type: string
          minLength: 1
        credits:
          type: integer
          format: int64
          minimum: 1
        created_at:
          type: string
          minLength: 1
    AccountProductSummaryResponse:
      type: object
      additionalProperties: false
      required:
        - user
        - membership
        - membership_access
        - credits
        - links
      properties:
        user:
          allOf:
            - $ref: "#/components/schemas/AccountUserInfo"
          nullable: true
        membership:
          allOf:
            - $ref: "#/components/schemas/AccountMembershipSummary"
          nullable: true
        membership_access:
          $ref: "#/components/schemas/AccountMembershipAccessState"
        credits:
          allOf:
            - $ref: "#/components/schemas/AccountCreditsSummary"
          nullable: true
        partial_error:
          allOf:
            - $ref: "#/components/schemas/AccountProductSummaryPartialError"
          nullable: true
        registration_credits_reward:
          allOf:
            - $ref: "#/components/schemas/AccountRegistrationCreditsReward"
          nullable: true
        links:
          $ref: "#/components/schemas/AccountProductSummaryLinks"
    DismissAccountRegistrationCreditsRewardRequest:
      type: object
      additionalProperties: false
      required:
        - reward_id
      properties:
        reward_id:
          type: string
          minLength: 1
    AccountLoginStartResponse:
      type: object
      additionalProperties: false
      required:
        - attempt_id
        - login_url
        - expires_at
      properties:
        attempt_id:
          type: string
          minLength: 1
        login_url:
          type: string
          minLength: 1
        expires_at:
          type: integer
          format: int64
    AccountLoginStatusValue:
      type: string
      enum:
        - pending
        - completed
        - failed
        - expired
    AccountLoginStatusResponse:
      type: object
      additionalProperties: false
      required:
        - attempt_id
        - status
        - expires_at
      properties:
        attempt_id:
          type: string
          minLength: 1
        status:
          $ref: "#/components/schemas/AccountLoginStatusValue"
        expires_at:
          type: integer
          format: int64
        error:
          type: string
          nullable: true
        user:
          allOf:
            - $ref: "#/components/schemas/AccountUserInfo"
          nullable: true
    CliOutputMode:
      type: string
      enum:
        - table
        - json
        - plain
        - markdown
    CliTableColumn:
      type: object
      description: Machine-readable table column metadata for clients that render command output.
      additionalProperties: false
      required:
        - key
        - label
      properties:
        key:
          type: string
          minLength: 1
        label:
          type: string
          description: Human-readable fallback label supplied by the protocol for terminal rendering.
          minLength: 1
    CliTableOutput:
      type: object
      additionalProperties: false
      required:
        - columns
      properties:
        columns:
          type: array
          items:
            $ref: "#/components/schemas/CliTableColumn"
    CliCapabilityOutput:
      type: object
      additionalProperties: false
      required:
        - defaultMode
        - json
      properties:
        defaultMode:
          $ref: "#/components/schemas/CliOutputMode"
        json:
          type: boolean
        table:
          allOf:
            - $ref: "#/components/schemas/CliTableOutput"
          nullable: true
    CliCommandExecutionMode:
      type: string
      enum:
        - wait
    CliCommandExecution:
      type: object
      description: Optional client-side execution behavior declared by a command. Wait commands remain active while handlers return a pending continuation.
      additionalProperties: false
      required:
        - mode
      properties:
        mode:
          $ref: "#/components/schemas/CliCommandExecutionMode"
    CliCapabilitySourceKind:
      type: string
      enum:
        - builtin
        - app
    CliCapabilitySource:
      type: object
      additionalProperties: false
      required:
        - kind
      properties:
        kind:
          $ref: "#/components/schemas/CliCapabilitySourceKind"
        appId:
          type: string
          nullable: true
        appName:
          type: string
          nullable: true
        iconUrl:
          type: string
          description: App manifest icon data URL for app-sourced commands.
          nullable: true
        cliDescription:
          type: string
          description: CLI scope description for app-sourced commands.
          nullable: true
        appDescription:
          type: string
          description: App manifest description for app-sourced commands.
          nullable: true
        documentationFile:
          type: string
          description: Package-local command documentation file declared by the app CLI manifest.
          nullable: true
        documentationPath:
          type: string
          description: Absolute command documentation path resolved from the installed app package.
          nullable: true
    CliCapabilityVisibility:
      type: string
      enum:
        - public
        - integration
    CliCapability:
      type: object
      description: Stable command metadata exposed by the local CLI capability protocol.
      additionalProperties: false
      required:
        - id
        - path
        - summary
        - output
        - source
      properties:
        id:
          type: string
          description: Stable command identifier used by invoke routes.
          minLength: 1
        path:
          type: array
          description: Terminal command path segments, excluding the tutti binary name.
          minItems: 1
          items:
            type: string
            minLength: 1
        summary:
          type: string
          description: Short human-readable summary for help surfaces.
          minLength: 1
        description:
          type: string
          description: Optional longer human-readable command description.
          nullable: true
        visibility:
          $ref: "#/components/schemas/CliCapabilityVisibility"
          description: Command discovery visibility. Public commands are user-facing; integration commands are app-runtime plumbing and should not be exposed as ordinary user or Agent actions.
        inputSchema:
          type: object
          description: Optional JSON Schema fragment describing accepted command input.
          additionalProperties: true
          nullable: true
        output:
          $ref: "#/components/schemas/CliCapabilityOutput"
        execution:
          allOf:
            - $ref: "#/components/schemas/CliCommandExecution"
          nullable: true
        handlerTimeoutMs:
          type: integer
          description: Per-invocation App handler timeout used by clients to budget the daemon request.
          minimum: 1000
          maximum: 600000
          nullable: true
        source:
          $ref: "#/components/schemas/CliCapabilitySource"
    CliCapabilitiesResponse:
      type: object
      additionalProperties: false
      required:
        - commands
      properties:
        commands:
          type: array
          items:
            $ref: "#/components/schemas/CliCapability"
    CliInvokeContext:
      type: object
      description: Client-supplied invocation context. These fields are hints for routing and audit only; authorization and workspace validation remain daemon-owned.
      additionalProperties: false
      required:
        - source
      properties:
        source:
          type: string
          description: Client source label such as cli. This is not an authorization boundary.
          minLength: 1
        appId:
          type: string
          description: Calling workspace app id hint. Managed-model commands validate it against their grant binding.
          nullable: true
        workspaceID:
          type: string
          nullable: true
        parentCommandId:
          type: string
          nullable: true
        agentSessionId:
          type: string
          description: Caller agent session id hint. This is not an authorization boundary.
          nullable: true
        agentCwd:
          type: string
          description: Host-injected caller Agent working directory inherited by nested Agent starts that omit an explicit cwd. This is not an authorization boundary.
          nullable: true
        agentRailPlacementJSON:
          type: string
          description: Host-injected versioned RailPlacement JSON inherited together with agentCwd. The Agent command provider validates this value before use.
          nullable: true
    CliInvokeRequest:
      type: object
      additionalProperties: false
      properties:
        input:
          type: object
          additionalProperties: true
          nullable: true
        outputMode:
          allOf:
            - $ref: "#/components/schemas/CliOutputMode"
          nullable: true
        context:
          allOf:
            - $ref: "#/components/schemas/CliInvokeContext"
          nullable: true
    CliCommandOutput:
      type: object
      additionalProperties: false
      required:
        - kind
      properties:
        kind:
          $ref: "#/components/schemas/CliOutputMode"
        columns:
          type: array
          items:
            $ref: "#/components/schemas/CliTableColumn"
        rows:
          type: array
          items:
            type: object
            additionalProperties: true
        value:
          type: object
          additionalProperties: true
          nullable: true
        text:
          type: string
          nullable: true
        warnings:
          type: array
          items:
            $ref: "#/components/schemas/CliCommandWarning"
        continuation:
          allOf:
            - $ref: "#/components/schemas/CliCommandContinuation"
          nullable: true
    CliCommandContinuationState:
      type: string
      enum:
        - pending
    CliCommandContinuation:
      type: object
      description: Internal continuation signal consumed by the CLI for wait commands and not rendered as a terminal result.
      additionalProperties: false
      required:
        - state
        - retryAfterMs
      properties:
        state:
          $ref: "#/components/schemas/CliCommandContinuationState"
        retryAfterMs:
          type: integer
          description: Delay before the CLI invokes the same command again.
          minimum: 250
          maximum: 60000
    CliCommandWarning:
      type: object
      additionalProperties: false
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
    CliInvokeResponse:
      type: object
      additionalProperties: false
      required:
        - ok
      properties:
        ok:
          type: boolean
        output:
          allOf:
            - $ref: "#/components/schemas/CliCommandOutput"
          nullable: true
    WorkspaceAppMentionCandidateSource:
      type: string
      enum:
        - workspace_app
        - cli_app
    WorkspaceAppMentionCliMetadata:
      type: object
      additionalProperties: false
      required:
        - commandCount
        - commandDescriptions
        - commandPaths
        - commandSummaries
        - scopes
      properties:
        commandCount:
          type: integer
          minimum: 0
        commandDescriptions:
          type: array
          items:
            type: string
        commandPaths:
          type: array
          items:
            type: string
        commandSummaries:
          type: array
          items:
            type: string
        scopes:
          type: array
          items:
            type: string
    WorkspaceAppMentionCandidate:
      type: object
      additionalProperties: false
      required:
        - appId
        - displayName
        - description
        - iconUrl
        - availableIconUrl
        - installed
        - enabled
        - source
        - localizations
        - references
        - cli
      properties:
        appId:
          type: string
          minLength: 1
        displayName:
          type: string
          minLength: 1
        description:
          type: string
        iconUrl:
          type: string
          nullable: true
        availableIconUrl:
          type: string
          nullable: true
        installed:
          type: boolean
        enabled:
          type: boolean
        source:
          $ref: "#/components/schemas/WorkspaceAppMentionCandidateSource"
        localizations:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceAppLocalization"
        references:
          $ref: "#/components/schemas/WorkspaceAppReferencesState"
        cli:
          $ref: "#/components/schemas/WorkspaceAppMentionCliMetadata"
    WorkspaceAppMentionCandidatesResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - apps
      properties:
        workspaceId:
          type: string
          minLength: 1
        apps:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceAppMentionCandidate"
    ApiErrorDetails:
      type: object
      additionalProperties: false
      required:
        - code
      properties:
        code:
          type: string
          enum:
            - invalid_request
            - method_not_allowed
            - unauthorized
            - service_unavailable
            - workspace_not_found
            - workspace_file_not_found
            - workspace_issue_resource_exists
            - workspace_terminal_not_found
            - workspace_app_not_found
            - workspace_issue_resource_not_found
            - workspace_operation_failed
            - preferences_operation_failed
            - agent_quick_prompt_not_found
            - agent_quick_prompt_conflict
            - agent_quick_prompt_operation_failed
            - agent_session_cassette_not_found
            - agent_session_replay_workspace_conflict
            - agent_session_fork_operation_not_found
            - agent_target_not_found
            - model_plan_not_found
            - model_plan_referenced
            - model_policy_referenced
            - workspace_agent_not_found
            - collaboration_run_not_found
            - automation_rule_not_found
            - tutti_mode_goal_review_not_found
            - tutti_mode_goal_review_conflict
            - tutti_mode_goal_review_operation_failed
            - tutti_mode_goal_review_service_unavailable
            - tutti_mode_archive_conflict
            - tutti_execution_active
        reason:
          type: string
        params:
          type: object
          additionalProperties: true
        retryable:
          type: boolean
        developerMessage:
          type: string
        correlationId:
          type: string
    ApiErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          $ref: "#/components/schemas/ApiErrorDetails"
    WorkspaceSummary:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - lastOpenedAt
      properties:
        id:
          type: string
        name:
          type: string
        lastOpenedAt:
          type: string
          format: date-time
          nullable: true
    DesktopLocale:
      type: string
      enum:
        - en
        - zh-CN
    DesktopThemeSource:
      type: string
      enum:
        - system
        - dark
        - light
      x-enum-varnames:
        - DesktopThemeSourceSystem
        - DesktopThemeSourceDark
        - DesktopThemeSourceLight
    DesktopSleepPreventionMode:
      type: string
      enum:
        - never
        - whileAgentRunning
        - always
    DesktopUpdatePolicy:
      type: string
      enum:
        - off
        - prompt
        - auto
    DesktopUpdateChannel:
      type: string
      enum:
        - stable
        - rc
    DesktopDockPlacement:
      type: string
      enum:
        - bottom
        - left
    DesktopDockIconStyle:
      type: string
      enum:
        - default
        - flat
    DesktopBrowserUseConnectionMode:
      type: string
      enum:
        - isolated
        - autoConnect
    DesktopAppCatalogChannel:
      type: string
      enum:
        - production
        - staging
    DeletedAgentConversationRetentionDays:
      type: integer
      enum:
        - 15
        - 30
    DeletedAgentConversationPurgeResult:
      type: object
      additionalProperties: false
      required:
        - removedSessions
        - removedMessages
        - payloadBytes
      properties:
        removedSessions:
          type: integer
          minimum: 0
        removedMessages:
          type: integer
          minimum: 0
        payloadBytes:
          type: integer
          format: int64
          minimum: 0
    WorkspaceDeletedAgentSessionUnavailableReason:
      type: string
      enum:
        - legacyDataUnavailable
        - incompleteSessionTree
    WorkspaceDeletedAgentSession:
      type: object
      additionalProperties: false
      required:
        - agentSessionId
        - title
        - railSectionKey
        - projectPath
        - updatedAtUnixMs
        - deletedAtUnixMs
        - restorable
        - unavailableReason
      properties:
        agentSessionId:
          type: string
          minLength: 1
          description: Identity of the topmost Session in this deleted component. It may be a canonical root or a child whose parent is not deleted.
        title:
          type: string
          description: Original canonical title. Empty titles remain empty.
        railSectionKey:
          type: string
          minLength: 1
          description: Immutable persisted rail section identity used for classification.
        projectPath:
          type: string
          nullable: true
          description: Persisted project path retained as presentation metadata. Classification is determined only by railSectionKey.
        updatedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
          description: Last session update before deletion. This value is not the deletion time.
        deletedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
          description: Tombstone time used by the retention policy.
        restorable:
          type: boolean
        unavailableReason:
          allOf:
            - $ref: "#/components/schemas/WorkspaceDeletedAgentSessionUnavailableReason"
          nullable: true
          description: Null when the complete deleted Session component can be restored.
    WorkspaceDeletedAgentSessionProjectOption:
      type: object
      additionalProperties: false
      required:
        - railSectionKey
        - projectPath
        - projectLabel
        - projectAvailable
      properties:
        railSectionKey:
          type: string
          minLength: 1
          description: Exact persisted rail section identity represented by this option.
        projectPath:
          type: string
          nullable: true
          description: Persisted project path retained as presentation metadata; it is not the option identity.
        projectLabel:
          type: string
          minLength: 1
        projectAvailable:
          type: boolean
          description: Whether the original project is still registered in the current project catalog.
    WorkspaceDeletedAgentSessionListResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - sessions
        - projectOptions
        - hasMore
        - totalCount
        - workspaceTotalCount
      properties:
        workspaceId:
          type: string
          minLength: 1
        sessions:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceDeletedAgentSession"
        projectOptions:
          type: array
          description: Distinct original tombstone projects for the workspace, independent of search, project filter, cursor, and limit.
          items:
            $ref: "#/components/schemas/WorkspaceDeletedAgentSessionProjectOption"
        hasMore:
          type: boolean
        nextCursor:
          type: string
          minLength: 1
          description: Opaque cursor for the next older matching page.
        totalCount:
          type: integer
          minimum: 0
          description: Total matching topmost soft-deleted Session components before cursor pagination.
        workspaceTotalCount:
          type: integer
          minimum: 0
          description: Total topmost soft-deleted Session components in this workspace before search, project filtering, and cursor pagination.
    RestoreWorkspaceDeletedAgentSessionResponse:
      type: object
      additionalProperties: false
      required:
        - agentSessionId
        - restored
      properties:
        agentSessionId:
          type: string
          minLength: 1
        restored:
          type: boolean
    DesktopPreferences:
      type: object
      additionalProperties: false
      required:
        - agentCliUpdateCheckEnabled
        - agentComposerDefaultsByProvider
        - agentGuiConversationRailCollapsedByProvider
        - agentConversationDetailMode
        - agentDockLayout
        - appCatalogChannel
        - defaultAgentProvider
        - dockIconStyle
        - dockPlacement
        - deletedAgentConversationRetentionDays
        - fileDefaultOpenersByExtension
        - featureFlags
        - workbenchShortcuts
        - locale
        - minimizeAnimation
        - sleepPreventionMode
        - showAppDeveloperSources
        - themeSource
        - updateChannel
        - updatePolicy
      properties:
        agentCliUpdateCheckEnabled:
          type: boolean
          default: true
          description: Whether tuttid may periodically discover newer managed agent CLI releases on this device. This never authorizes automatic installation.
        agentComposerDefaultsByProvider:
          $ref: "#/components/schemas/DesktopAgentComposerDefaultsByProvider"
        agentComposerDefaultsByAgentTarget:
          $ref: "#/components/schemas/DesktopAgentComposerDefaultsByAgentTarget"
        agentGuiConversationRailCollapsedByProvider:
          $ref: "#/components/schemas/DesktopAgentGuiConversationRailCollapsedByProvider"
        agentSessionLaunchModesByWorkspace:
          $ref: "#/components/schemas/DesktopAgentSessionLaunchModesByWorkspace"
          description: Daemon-owned remembered Agent Session launch modes. Full desktop preference updates preserve this map; mutate one workspace/project entry through the dedicated event-stream patch intent.
        agentConversationDetailMode:
          $ref: "#/components/schemas/DesktopAgentConversationDetailMode"
        agentDockLayout:
          $ref: "#/components/schemas/DesktopAgentDockLayout"
        appCatalogChannel:
          $ref: "#/components/schemas/DesktopAppCatalogChannel"
        browserUseConnectionMode:
          $ref: "#/components/schemas/DesktopBrowserUseConnectionMode"
        defaultAgentProvider:
          $ref: "#/components/schemas/DesktopDefaultAgentProvider"
        dockIconStyle:
          $ref: "#/components/schemas/DesktopDockIconStyle"
        dockPlacement:
          $ref: "#/components/schemas/DesktopDockPlacement"
        deletedAgentConversationRetentionDays:
          $ref: "#/components/schemas/DeletedAgentConversationRetentionDays"
        fileDefaultOpenersByExtension:
          $ref: "#/components/schemas/DesktopFileDefaultOpenersByExtension"
        featureFlags:
          $ref: "#/components/schemas/DesktopFeatureFlags"
        workbenchShortcuts:
          $ref: "#/components/schemas/DesktopWorkbenchShortcuts"
        locale:
          $ref: "#/components/schemas/DesktopLocale"
        minimizeAnimation:
          $ref: "#/components/schemas/DesktopMinimizeAnimation"
        sleepPreventionMode:
          $ref: "#/components/schemas/DesktopSleepPreventionMode"
        showAppDeveloperSources:
          type: boolean
        themeSource:
          $ref: "#/components/schemas/DesktopThemeSource"
        updateChannel:
          $ref: "#/components/schemas/DesktopUpdateChannel"
        updatePolicy:
          $ref: "#/components/schemas/DesktopUpdatePolicy"
        workbenchWindowSnapping:
          $ref: "#/components/schemas/DesktopWorkbenchWindowSnapping"
    DesktopFeatureFlags:
      type: object
      additionalProperties:
        type: boolean
    DesktopWorkbenchShortcuts:
      type: object
      additionalProperties: false
      required:
        - newAgentConversation
        - newSameTypeWindow
      properties:
        newAgentConversation:
          type: string
          nullable: true
          maxLength: 80
          description: Keyboard shortcut binding for opening an AgentGUI new conversation, or null when unbound.
        newSameTypeWindow:
          type: string
          nullable: true
          maxLength: 80
          description: Keyboard shortcut binding for opening a new window of the active workbench node type, or null when unbound.
        captureScreenshot:
          type: string
          nullable: true
          maxLength: 80
          description: Keyboard shortcut binding for the global screenshot capture, or null/absent when the built-in CommandOrControl+Shift+S default applies. Unlike the other bindings, null does not mean unbound.
    DesktopWorkbenchWindowSnapping:
      type: object
      additionalProperties: false
      required:
        - enabled
        - shortcutPreset
      properties:
        enabled:
          type: boolean
        shortcutPreset:
          $ref: "#/components/schemas/DesktopWorkbenchWindowSnappingShortcutPreset"
    DesktopWorkbenchWindowSnappingShortcutPreset:
      type: string
      enum:
        - commandArrows
        - commandShiftArrows
    DesktopAgentComposerDefaults:
      type: object
      additionalProperties: false
      properties:
        codexSaverMode:
          type: boolean
          description: Enables the Codex-specific saver subagent mode
        rtkSaverMode:
          type: boolean
          description: Enables provider-neutral RTK saver mode
        model:
          type: string
        permissionModeId:
          type: string
        reasoningEffort:
          type: string
        speed:
          type: string
    DesktopAgentConversationDetailMode:
      type: string
      enum:
        - coding
        - general
    DesktopDefaultAgentProvider:
      type: string
      enum:
        - tutti-agent
        - claude-code
        - codex
        - cursor
        - opencode
      x-enum-varnames:
        - DesktopDefaultAgentProviderTuttiAgent
        - DesktopDefaultAgentProviderClaudeCode
        - DesktopDefaultAgentProviderCodex
        - DesktopDefaultAgentProviderCursor
        - DesktopDefaultAgentProviderOpencode
    DesktopAgentDockLayout:
      type: string
      enum:
        - legacySplit
        - unified
    DesktopAgentComposerDefaultsByProvider:
      type: object
      additionalProperties: false
      properties:
        claude-code:
          $ref: "#/components/schemas/DesktopAgentComposerDefaults"
        codex:
          $ref: "#/components/schemas/DesktopAgentComposerDefaults"
        tutti-agent:
          $ref: "#/components/schemas/DesktopAgentComposerDefaults"
        cursor:
          $ref: "#/components/schemas/DesktopAgentComposerDefaults"
        nexight:
          $ref: "#/components/schemas/DesktopAgentComposerDefaults"
        openclaw:
          $ref: "#/components/schemas/DesktopAgentComposerDefaults"
        opencode:
          $ref: "#/components/schemas/DesktopAgentComposerDefaults"
    DesktopAgentComposerDefaultsByAgentTarget:
      type: object
      additionalProperties:
        $ref: "#/components/schemas/DesktopAgentComposerDefaults"
    DesktopAgentGuiConversationRailCollapsedByProvider:
      type: object
      additionalProperties: false
      properties:
        claude-code:
          type: boolean
        codex:
          type: boolean
        tutti-agent:
          type: boolean
        cursor:
          type: boolean
        nexight:
          type: boolean
        openclaw:
          type: boolean
        opencode:
          type: boolean
    DesktopAgentSessionLaunchMode:
      type: string
      enum:
        - local
        - worktree
    DesktopAgentSessionLaunchModesByProject:
      type: object
      additionalProperties:
        $ref: "#/components/schemas/DesktopAgentSessionLaunchMode"
    DesktopAgentSessionLaunchModesByWorkspace:
      type: object
      additionalProperties:
        $ref: "#/components/schemas/DesktopAgentSessionLaunchModesByProject"
    DesktopFileDefaultOpener:
      type: string
      enum:
        - appBrowser
        - defaultBrowser
        - fileViewer
        - system
    DesktopFileDefaultOpenersByExtension:
      type: object
      additionalProperties:
        $ref: "#/components/schemas/DesktopFileDefaultOpener"
    DesktopMinimizeAnimation:
      type: string
      enum:
        - scale
        - genie
        - off
    DesktopPreferencesStateResponse:
      type: object
      additionalProperties: false
      required:
        - initialized
        - preferences
      properties:
        initialized:
          type: boolean
        preferences:
          $ref: "#/components/schemas/DesktopPreferences"
    WorkspaceAppAgentPreferencesResponse:
      type: object
      additionalProperties: false
      required:
        - defaultAgentProvider
      properties:
        defaultAgentProvider:
          $ref: "#/components/schemas/DesktopDefaultAgentProvider"
    PutDesktopPreferencesRequest:
      type: object
      additionalProperties: false
      required:
        - preferences
      properties:
        writeMode:
          $ref: "#/components/schemas/DesktopPreferencesWriteMode"
        preferences:
          $ref: "#/components/schemas/DesktopPreferences"
    DesktopPreferencesWriteMode:
      type: string
      description: >-
        replace performs the normal full preference update, and omitting
        writeMode is equivalent to replace. initializeIfAbsent atomically
        creates the preference row only when it does not exist after applying
        the daemon-owned Agent workspace-mode default to the supplied
        preferences. If the row already exists, it returns the authoritative
        stored preferences unchanged.
      default: replace
      enum:
        - replace
        - initializeIfAbsent
      x-enum-varnames:
        - DesktopPreferencesWriteModeReplace
        - DesktopPreferencesWriteModeInitializeIfAbsent
    DesktopUpdateAdmissionProduct:
      type: string
      enum:
        - tsh-desktop
        - tutti-desktop
      x-enum-varnames:
        - DesktopUpdateAdmissionProductTshDesktop
        - DesktopUpdateAdmissionProductTuttiDesktop
    DesktopUpdateAdmissionPlatform:
      type: string
      enum:
        - macos
        - windows
        - linux
      x-enum-varnames:
        - DesktopUpdateAdmissionPlatformMacos
        - DesktopUpdateAdmissionPlatformWindows
        - DesktopUpdateAdmissionPlatformLinux
    DesktopUpdateAdmissionArchitecture:
      type: string
      enum:
        - arm64
        - x64
      x-enum-varnames:
        - DesktopUpdateAdmissionArchitectureArm64
        - DesktopUpdateAdmissionArchitectureX64
    DesktopUpdateAdmissionIdentity:
      type: object
      additionalProperties: false
      required:
        - product
        - platform
        - architecture
        - currentVersion
      properties:
        product:
          $ref: "#/components/schemas/DesktopUpdateAdmissionProduct"
        platform:
          $ref: "#/components/schemas/DesktopUpdateAdmissionPlatform"
        architecture:
          $ref: "#/components/schemas/DesktopUpdateAdmissionArchitecture"
        currentVersion:
          type: string
          minLength: 1
    DesktopUpdateAdmissionPolicyResponse:
      type: object
      additionalProperties: false
      required:
        - channel
        - decision
        - reason
        - policyRevision
      properties:
        channel:
          type: string
          enum:
            - stable
            - rc
            - unmanaged
          x-enum-varnames:
            - DesktopUpdateAdmissionPolicyResponseChannelStable
            - DesktopUpdateAdmissionPolicyResponseChannelRc
            - DesktopUpdateAdmissionPolicyResponseChannelUnmanaged
        minimumVersion:
          type: string
          minLength: 1
        decision:
          type: string
          enum:
            - allowed
            - upgradeRequired
            - notApplicable
          x-enum-varnames:
            - DesktopUpdateAdmissionPolicyResponseDecisionAllowed
            - DesktopUpdateAdmissionPolicyResponseDecisionUpgradeRequired
            - DesktopUpdateAdmissionPolicyResponseDecisionNotApplicable
        reason:
          type: string
          enum:
            - belowMinimum
            - meetsMinimum
            - minimumNotConfigured
            - unmanagedPrerelease
            - unsupportedRelease
          x-enum-varnames:
            - DesktopUpdateAdmissionPolicyResponseReasonBelowMinimum
            - DesktopUpdateAdmissionPolicyResponseReasonMeetsMinimum
            - DesktopUpdateAdmissionPolicyResponseReasonMinimumNotConfigured
            - DesktopUpdateAdmissionPolicyResponseReasonUnmanagedPrerelease
            - DesktopUpdateAdmissionPolicyResponseReasonUnsupportedRelease
        policyRevision:
          type: string
          minLength: 1
    DesktopUpdateAdmissionPolicyFailure:
      type: object
      additionalProperties: false
      required:
        - kind
      properties:
        kind:
          type: string
          enum:
            - timeout
            - transport
            - invalidResponse
          x-enum-varnames:
            - DesktopUpdateAdmissionPolicyFailureKindTimeout
            - DesktopUpdateAdmissionPolicyFailureKindTransport
            - DesktopUpdateAdmissionPolicyFailureKindInvalidResponse
    DesktopUpdateAdmissionPolicySnapshot:
      type: object
      additionalProperties: false
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - checking
            - resolved
            - failedOpen
            - skipped
          x-enum-varnames:
            - DesktopUpdateAdmissionPolicySnapshotStatusChecking
            - DesktopUpdateAdmissionPolicySnapshotStatusResolved
            - DesktopUpdateAdmissionPolicySnapshotStatusFailedOpen
            - DesktopUpdateAdmissionPolicySnapshotStatusSkipped
        response:
          $ref: "#/components/schemas/DesktopUpdateAdmissionPolicyResponse"
        failure:
          $ref: "#/components/schemas/DesktopUpdateAdmissionPolicyFailure"
        reason:
          type: string
          enum:
            - checksDisabled
          x-enum-varnames:
            - DesktopUpdateAdmissionPolicySnapshotReasonChecksDisabled
    DesktopUpdateAdmissionFeatureAvailability:
      type: object
      additionalProperties: false
      required:
        - keys
        - source
        - policyRevision
        - fetchedAt
      properties:
        keys:
          type: array
          maxItems: 256
          items:
            type: string
        source:
          type: string
          enum:
            - remote
            - cache
            - empty
          x-enum-varnames:
            - DesktopUpdateAdmissionFeatureAvailabilitySourceRemote
            - DesktopUpdateAdmissionFeatureAvailabilitySourceCache
            - DesktopUpdateAdmissionFeatureAvailabilitySourceEmpty
        policyRevision:
          type: string
          nullable: true
        fetchedAt:
          type: string
          format: date-time
          nullable: true
    DesktopUpdateAdmissionSnapshot:
      type: object
      additionalProperties: false
      required:
        - identity
        - policy
        - featureAvailability
        - lastAttemptAt
        - nextForegroundCheckAt
      properties:
        identity:
          $ref: "#/components/schemas/DesktopUpdateAdmissionIdentity"
        policy:
          $ref: "#/components/schemas/DesktopUpdateAdmissionPolicySnapshot"
        featureAvailability:
          $ref: "#/components/schemas/DesktopUpdateAdmissionFeatureAvailability"
        lastAttemptAt:
          type: string
          format: date-time
          nullable: true
        nextForegroundCheckAt:
          type: string
          format: date-time
          nullable: true
    DesktopUpdateAdmissionRefreshTrigger:
      type: string
      enum:
        - foreground
        - retry
      x-enum-varnames:
        - DesktopUpdateAdmissionRefreshTriggerForeground
        - DesktopUpdateAdmissionRefreshTriggerRetry
    DesktopUpdateAdmissionRefreshRequest:
      type: object
      additionalProperties: false
      required:
        - trigger
      properties:
        trigger:
          $ref: "#/components/schemas/DesktopUpdateAdmissionRefreshTrigger"
    DesktopUpdateAdmissionRefreshResult:
      type: object
      additionalProperties: false
      required:
        - performed
        - snapshot
      properties:
        performed:
          type: boolean
        skipReason:
          type: string
          enum:
            - checksDisabled
            - throttled
            - requestInFlight
          x-enum-varnames:
            - DesktopUpdateAdmissionRefreshResultSkipReasonChecksDisabled
            - DesktopUpdateAdmissionRefreshResultSkipReasonThrottled
            - DesktopUpdateAdmissionRefreshResultSkipReasonRequestInFlight
        snapshot:
          $ref: "#/components/schemas/DesktopUpdateAdmissionSnapshot"
    AgentTargetProvider:
      type: string
      minLength: 1
      maxLength: 128
      pattern: "^[a-z][a-z0-9._:-]*$"
    AgentTargetSource:
      type: string
      enum:
        - system
        - user
    AgentTargetLaunchRef:
      oneOf:
        - $ref: "#/components/schemas/AgentTargetBuiltinLocalLaunchRef"
        - $ref: "#/components/schemas/AgentTargetExtensionLaunchRef"
      discriminator:
        propertyName: type
        mapping:
          builtin_local: "#/components/schemas/AgentTargetBuiltinLocalLaunchRef"
          agent_extension: "#/components/schemas/AgentTargetExtensionLaunchRef"
    AgentTargetBuiltinLocalLaunchRef:
      type: object
      additionalProperties: false
      required:
        - type
        - provider
      properties:
        type:
          type: string
          enum:
            - builtin_local
          x-enum-varnames:
            - AgentTargetBuiltinLocalLaunchRefTypeBuiltinLocal
        provider:
          $ref: "#/components/schemas/AgentTargetProvider"
    AgentTargetExtensionLaunchRef:
      type: object
      additionalProperties: false
      required:
        - type
        - extensionInstallationId
      properties:
        type:
          type: string
          enum:
            - agent_extension
          x-enum-varnames:
            - AgentTargetExtensionLaunchRefTypeAgentExtension
        extensionInstallationId:
          type: string
          minLength: 1
    AgentTarget:
      type: object
      additionalProperties: false
      required:
        - id
        - provider
        - launchRef
        - name
        - enabled
        - source
        - sortOrder
        - createdAtUnixMs
        - updatedAtUnixMs
      properties:
        id:
          type: string
          maxLength: 128
          pattern: "^[a-z0-9][a-z0-9._:-]{0,127}$"
        provider:
          $ref: "#/components/schemas/AgentTargetProvider"
        launchRef:
          $ref: "#/components/schemas/AgentTargetLaunchRef"
        name:
          type: string
        iconKey:
          type: string
          nullable: true
        iconUrl:
          type: string
          nullable: true
        maskIconUrl:
          type: string
          nullable: true
        heroImageUrl:
          type: string
          nullable: true
        availability:
          allOf:
            - $ref: "#/components/schemas/AgentProviderAvailability"
          nullable: true
        enabled:
          type: boolean
        source:
          $ref: "#/components/schemas/AgentTargetSource"
        sortOrder:
          type: integer
        createdAtUnixMs:
          type: integer
          format: int64
        updatedAtUnixMs:
          type: integer
          format: int64
    ListAgentTargetsResponse:
      type: object
      additionalProperties: false
      required:
        - targets
      properties:
        targets:
          type: array
          items:
            $ref: "#/components/schemas/AgentTarget"
    AgentTargetAccountUsageProbeResult:
      oneOf:
        - $ref: "#/components/schemas/AgentTargetAccountUsageAvailableResult"
        - $ref: "#/components/schemas/AgentTargetAccountUsageUnsupportedResult"
        - $ref: "#/components/schemas/AgentTargetAccountUsageErrorResult"
      discriminator:
        propertyName: outcome
        mapping:
          available: "#/components/schemas/AgentTargetAccountUsageAvailableResult"
          unsupported: "#/components/schemas/AgentTargetAccountUsageUnsupportedResult"
          error: "#/components/schemas/AgentTargetAccountUsageErrorResult"
    AgentTargetAccountUsageAvailableResult:
      type: object
      additionalProperties: false
      required:
        - schemaVersion
        - agentTargetId
        - provider
        - outcome
        - capturedAtUnixMs
        - billingMode
        - quotaState
        - quotas
      properties:
        schemaVersion:
          type: string
          enum:
            - tutti.agent.account-usage.v2
        agentTargetId:
          type: string
          minLength: 1
        provider:
          $ref: "#/components/schemas/AgentTargetProvider"
        outcome:
          type: string
          enum:
            - available
        capturedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        billingMode:
          $ref: "#/components/schemas/AgentTargetAccountUsageBillingMode"
        quotaState:
          $ref: "#/components/schemas/AgentTargetAccountUsageQuotaState"
        quotas:
          type: array
          maxItems: 64
          items:
            $ref: "#/components/schemas/AgentTargetAccountUsageQuota"
    AgentTargetAccountUsageUnsupportedResult:
      type: object
      additionalProperties: false
      required:
        - schemaVersion
        - agentTargetId
        - provider
        - outcome
        - capturedAtUnixMs
      properties:
        schemaVersion:
          type: string
          enum:
            - tutti.agent.account-usage.v2
        agentTargetId:
          type: string
          minLength: 1
        provider:
          $ref: "#/components/schemas/AgentTargetProvider"
        outcome:
          type: string
          enum:
            - unsupported
        capturedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
    AgentTargetAccountUsageErrorResult:
      type: object
      additionalProperties: false
      required:
        - schemaVersion
        - agentTargetId
        - provider
        - outcome
        - capturedAtUnixMs
        - errorCode
      properties:
        schemaVersion:
          type: string
          enum:
            - tutti.agent.account-usage.v2
        agentTargetId:
          type: string
          minLength: 1
        provider:
          $ref: "#/components/schemas/AgentTargetProvider"
        outcome:
          type: string
          enum:
            - error
        capturedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        errorCode:
          $ref: "#/components/schemas/AgentTargetAccountUsageErrorCode"
    AgentTargetAccountUsageBillingMode:
      type: string
      enum:
        - subscription
        - api
        - coding_plan
        - provider_account
    AgentTargetAccountUsageQuotaState:
      type: string
      enum:
        - complete
        - unavailable
        - not_applicable
    AgentTargetAccountUsageErrorCode:
      type: string
      enum:
        - auth_required
        - config_invalid
        - execution_failed
        - no_data
        - parse_failed
        - rate_limited
        - runtime_unavailable
        - session_expired
        - timeout
    AgentTargetAccountUsageQuotaType:
      type: string
      enum:
        - session
        - daily
        - weekly
        - monthly
        - model
        - credits
        - cost
    AgentTargetAccountUsageQuota:
      type: object
      additionalProperties: false
      required:
        - quotaType
        - percentRemaining
      properties:
        quotaType:
          $ref: "#/components/schemas/AgentTargetAccountUsageQuotaType"
        percentRemaining:
          type: number
          minimum: 0
          maximum: 100
        amountRemaining:
          type: number
          format: double
          minimum: 0
        amountLimit:
          type: number
          format: double
          minimum: 0
        amountUnit:
          type: string
          enum:
            - credits
        resetsAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        modelName:
          type: string
          minLength: 1
          maxLength: 128
    SetSystemAgentTargetEnabledRequest:
      type: object
      additionalProperties: false
      required:
        - enabled
      properties:
        enabled:
          type: boolean
          x-go-type: "*bool"
    AgentTargetInstallPlan:
      type: object
      additionalProperties: false
      required:
        - agentTargetId
        - extensionInstallationId
        - agentKey
        - extensionVersion
        - runtimeKind
        - platform
        - runner
        - packageName
        - packageVersion
        - installRoot
        - installCommand
        - executable
        - launchArgs
        - planDigest
      properties:
        agentTargetId:
          type: string
          minLength: 1
        extensionInstallationId:
          type: string
          minLength: 1
        agentKey:
          type: string
          minLength: 1
        extensionVersion:
          type: string
          minLength: 1
        runtimeKind:
          type: string
          minLength: 1
        platform:
          type: string
          minLength: 1
        runner:
          type: string
          enum:
            - npm
            - pnpm
            - uv
            - binary
        packageName:
          type: string
          minLength: 1
        packageVersion:
          type: string
          minLength: 1
        installRoot:
          type: string
          minLength: 1
        installCommand:
          type: array
          minItems: 1
          items:
            type: string
            minLength: 1
        executable:
          type: string
          minLength: 1
        launchArgs:
          type: array
          items:
            type: string
        planDigest:
          type: string
          pattern: "^[a-f0-9]{64}$"
    AgentTargetSetupStatus:
      type: string
      enum:
        - ready
        - auth_required
        - not_installed
        - installing
        - authenticating
        - failed
    AgentTargetRuntimeSource:
      type: string
      enum:
        - local
        - managed
      x-enum-varnames:
        - AgentTargetRuntimeSourceLocal
        - AgentTargetRuntimeSourceManaged
    AgentTargetSetupActionKind:
      type: string
      enum:
        - install
        - authenticate
      x-enum-varnames:
        - AgentTargetSetupActionKindInstall
        - AgentTargetSetupActionKindAuthenticate
    AgentTargetSetupActionStatus:
      type: string
      enum:
        - queued
        - running
        - succeeded
        - failed
        - interrupted
    AgentTargetSetupActionPhase:
      type: string
      enum:
        - preparing
        - installing
        - verifying
        - probing
        - activating
        - authenticating
        - complete
    AgentTargetSetupAction:
      type: object
      additionalProperties: false
      required:
        - actionId
        - clientActionId
        - kind
        - status
        - phase
        - createdAtUnixMs
        - updatedAtUnixMs
      properties:
        actionId:
          type: string
          minLength: 1
        clientActionId:
          type: string
          minLength: 1
        kind:
          $ref: "#/components/schemas/AgentTargetSetupActionKind"
        status:
          $ref: "#/components/schemas/AgentTargetSetupActionStatus"
        phase:
          $ref: "#/components/schemas/AgentTargetSetupActionPhase"
        errorCode:
          type: string
          nullable: true
        errorMessage:
          type: string
          nullable: true
        createdAtUnixMs:
          type: integer
          format: int64
        updatedAtUnixMs:
          type: integer
          format: int64
    AgentTargetAuthenticatedAccount:
      type: object
      additionalProperties: false
      required:
        - id
        - displayName
        - authMethodId
      properties:
        id:
          type: string
          minLength: 1
        displayName:
          type: string
          minLength: 1
        authMethodId:
          type: string
          minLength: 1
        organization:
          type: string
          nullable: true
    AgentTargetSetupSnapshot:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - agentTargetId
        - status
        - runtimeSource
        - runtimeVersion
        - reason
        - authMethods
        - account
        - plan
        - action
      properties:
        workspaceId:
          type: string
          minLength: 1
        agentTargetId:
          type: string
          minLength: 1
        status:
          $ref: "#/components/schemas/AgentTargetSetupStatus"
        runtimeSource:
          allOf:
            - $ref: "#/components/schemas/AgentTargetRuntimeSource"
          nullable: true
        runtimeVersion:
          type: string
          nullable: true
        reason:
          type: string
          nullable: true
        authMethods:
          type: array
          items:
            $ref: "#/components/schemas/AgentTargetAuthMethod"
        account:
          allOf:
            - $ref: "#/components/schemas/AgentTargetAuthenticatedAccount"
          nullable: true
        plan:
          allOf:
            - $ref: "#/components/schemas/AgentTargetInstallPlan"
          nullable: true
        action:
          allOf:
            - $ref: "#/components/schemas/AgentTargetSetupAction"
          nullable: true
    AgentTargetAuthMethod:
      type: object
      additionalProperties: false
      required:
        - id
        - name
      properties:
        id:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
        description:
          type: string
          nullable: true
        type:
          type: string
          nullable: true
          description: Provider-declared method kind (for example "terminal").
        terminalCommand:
          type: string
          nullable: true
          description: Ready-to-run interactive sign-in launch command for terminal-type methods.
        terminalStartupAction:
          allOf:
            - $ref: "#/components/schemas/AgentTargetTerminalStartupAction"
          nullable: true
          description: Optional typed terminal action submitted after the interactive runtime reaches its declared ready marker.
    AgentTargetTerminalStartupAction:
      type: object
      additionalProperties: false
      required:
        - type
        - commandName
        - readyText
      properties:
        type:
          type: string
          enum:
            - slash_command
          x-enum-varnames:
            - AgentTargetTerminalStartupActionTypeSlashCommand
        commandName:
          type: string
          minLength: 1
          maxLength: 64
          pattern: "^[a-z0-9][a-z0-9._:-]{0,63}$"
        readyText:
          type: string
          minLength: 1
          maxLength: 256
    InstallAgentTargetRuntimeRequest:
      type: object
      additionalProperties: false
      required:
        - planDigest
        - clientActionId
      properties:
        planDigest:
          type: string
          pattern: "^[a-f0-9]{64}$"
        clientActionId:
          type: string
          minLength: 1
          maxLength: 128
    AuthenticateAgentTargetRuntimeRequest:
      type: object
      additionalProperties: false
      required:
        - methodId
        - clientActionId
      properties:
        methodId:
          type: string
          minLength: 1
          maxLength: 128
        clientActionId:
          type: string
          minLength: 1
          maxLength: 128
    ListWorkspacesResponse:
      type: object
      additionalProperties: false
      required:
        - workspaces
        - totalCount
      properties:
        workspaces:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceSummary"
        totalCount:
          type: integer
          minimum: 0
    StartupWorkspaceResponse:
      type: object
      additionalProperties: false
      required:
        - workspace
      properties:
        workspace:
          allOf:
            - $ref: "#/components/schemas/WorkspaceSummary"
          nullable: true
    WorkspaceResponse:
      type: object
      additionalProperties: false
      required:
        - workspace
      properties:
        workspace:
          $ref: "#/components/schemas/WorkspaceSummary"
    DeleteWorkspaceResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
      properties:
        workspaceId:
          type: string
    AutomationRuleTargetKind:
      type: string
      description: Every rule targets a launchable Agent. The legacy model kind retired with the consult action and no longer appears.
      enum:
        - agent
    AutomationRuleTarget:
      type: object
      additionalProperties: false
      required:
        - kind
        - requiredCapabilities
      properties:
        kind:
          $ref: "#/components/schemas/AutomationRuleTargetKind"
        workspaceAgentId:
          type: string
          nullable: true
          description: Target Agent that receives the automated follow-up session. Accepts a WorkspaceAgent id or a built-in Harness AgentTarget id; the Agent must be enabled and launchable.
        modelPlanId:
          type: string
          nullable: true
          description: Retired consult-era field; always empty. Launches inherit the target Agent's model configuration.
        model:
          type: string
          nullable: true
          description: Retired consult-era field; always empty.
        requiredCapabilities:
          type: array
          description: Retired consult-era field; always empty.
          items:
            type: string
            minLength: 1
    AutomationRulePermissions:
      type: object
      additionalProperties: false
      required:
        - allowedTools
      description: Authority narrowing applied to the automatically launched target session. The option catalogs follow the selected target Agent's capability directory.
      properties:
        permissionModeId:
          type: string
          nullable: true
        allowedTools:
          type: array
          items:
            type: string
            minLength: 1
    AutomationRuleBudget:
      type: object
      additionalProperties: false
      required:
        - maxRunsPerSession
        - maxTotalTokensPerSession
      description: Independent per-source-session limit. Zero uses the daemon safety default and never means unlimited.
      properties:
        maxRunsPerSession:
          type: integer
          minimum: 0
        maxTotalTokensPerSession:
          type: integer
          format: int64
          minimum: 0
    AutomationRuleTrigger:
      type: string
      description: Lifecycle outcome that evaluates the rule. A failed-turn rule can delegate to a stronger WorkspaceAgent as a bounded escalation attempt; automated outcomes never final-accept the source task.
      enum:
        - on_task_complete
        - on_task_failed
    AutomationRule:
      type: object
      additionalProperties: false
      description: One workspace automation rule. A triggered rule launches a new target-Agent session whose first message carries the rule prompt, a source-session mention, and a short event note.
      required:
        - id
        - workspaceId
        - name
        - enabled
        - trigger
        - target
        - permissions
        - budget
        - prompt
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          minLength: 1
        workspaceId:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
        enabled:
          type: boolean
        trigger:
          $ref: "#/components/schemas/AutomationRuleTrigger"
        sourceWorkspaceAgentId:
          type: string
          nullable: true
          description: Optional source-session Agent filter. Empty means all non-automation-origin sessions.
        target:
          $ref: "#/components/schemas/AutomationRuleTarget"
        permissions:
          $ref: "#/components/schemas/AutomationRulePermissions"
        budget:
          $ref: "#/components/schemas/AutomationRuleBudget"
        prompt:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ListAutomationRulesResponse:
      type: object
      additionalProperties: false
      required:
        - rules
      properties:
        rules:
          type: array
          items:
            $ref: "#/components/schemas/AutomationRule"
    PutAutomationRuleRequest:
      type: object
      additionalProperties: false
      required:
        - name
        - enabled
        - trigger
        - target
        - permissions
        - budget
        - prompt
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
        enabled:
          type: boolean
        trigger:
          $ref: "#/components/schemas/AutomationRuleTrigger"
        sourceWorkspaceAgentId:
          type: string
          nullable: true
        target:
          $ref: "#/components/schemas/AutomationRuleTarget"
        permissions:
          $ref: "#/components/schemas/AutomationRulePermissions"
        budget:
          $ref: "#/components/schemas/AutomationRuleBudget"
        prompt:
          type: string
          maxLength: 100000
    DeleteAutomationRuleResponse:
      type: object
      additionalProperties: false
      required:
        - automationRuleId
      properties:
        automationRuleId:
          type: string
    AgentSessionAutomationRuleOverride:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - agentSessionId
        - disabled
        - ruleIds
      properties:
        workspaceId:
          type: string
          minLength: 1
        agentSessionId:
          type: string
          minLength: 1
        disabled:
          type: boolean
        ruleIds:
          type: array
          items:
            type: string
            minLength: 1
        updatedAt:
          type: string
          format: date-time
          nullable: true
    SetAgentSessionAutomationRuleOverrideRequest:
      type: object
      additionalProperties: false
      required:
        - disabled
        - ruleIds
      properties:
        disabled:
          type: boolean
        ruleIds:
          type: array
          items:
            type: string
            minLength: 1
    ModelPlanProtocol:
      type: string
      description: Wire protocol family used to call the plan's models.
      enum:
        - openai
        - anthropic
    ModelPlanTemplateKind:
      type: string
      description: Access-scheme template the plan was created from. Presentation and guidance hint; runtime behavior derives from protocol.
      enum:
        - official_subscription
        - coding_plan
        - domestic
        - relay
        - custom
    ModelPlanStatus:
      type: string
      description: Derived plan lifecycle status. A plan is ready when its latest connection detection passed.
      enum:
        - disabled
        - undetected
        - detection_failed
        - ready
    ModelPlanDetectionStage:
      type: string
      enum:
        - network
        - auth
        - model_discovery
        - inference
    ModelPlanStageStatus:
      type: string
      enum:
        - passed
        - failed
        - skipped
    ModelPlanStageResult:
      type: object
      additionalProperties: false
      required:
        - stage
        - status
      properties:
        stage:
          $ref: "#/components/schemas/ModelPlanDetectionStage"
        status:
          $ref: "#/components/schemas/ModelPlanStageStatus"
        latencyMs:
          type: integer
          format: int64
          nullable: true
        failureReason:
          type: string
          nullable: true
          description: Machine-readable failure code such as connection_failed, unauthorized, model_catalog_unavailable, model_rejected, inference_failed.
        remedy:
          type: string
          nullable: true
          description: Machine-readable remedy code such as check_network_or_base_url, check_api_key, add_models_manually, check_model_id, select_model. UI layers localize.
        detail:
          type: string
          nullable: true
        checkedAt:
          type: string
          format: date-time
          nullable: true
    ModelPlanDetection:
      type: object
      additionalProperties: false
      required:
        - stages
      properties:
        stages:
          type: array
          items:
            $ref: "#/components/schemas/ModelPlanStageResult"
        checkedAt:
          type: string
          format: date-time
          nullable: true
        model:
          type: string
          nullable: true
          description: Model id exercised by the inference stage.
    ModelPlanModel:
      type: object
      additionalProperties: false
      required:
        - id
        - name
      properties:
        id:
          type: string
        name:
          type: string
        capabilities:
          type: array
          nullable: true
          items:
            type: string
    ModelPlan:
      type: object
      additionalProperties: false
      description: Workspace-level model access plan. Credentials are stored daemon-side only; hasApiKey is the only credential signal in responses.
      required:
        - id
        - workspaceId
        - revision
        - name
        - templateKind
        - protocol
        - hasApiKey
        - models
        - enabled
        - status
        - detection
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
        workspaceId:
          type: string
        revision:
          type: integer
          format: int64
          minimum: 0
        name:
          type: string
        templateKind:
          $ref: "#/components/schemas/ModelPlanTemplateKind"
        protocol:
          $ref: "#/components/schemas/ModelPlanProtocol"
        hasApiKey:
          type: boolean
        baseUrl:
          type: string
          nullable: true
        models:
          type: array
          items:
            $ref: "#/components/schemas/ModelPlanModel"
        defaultModel:
          type: string
          nullable: true
        enabled:
          type: boolean
        status:
          $ref: "#/components/schemas/ModelPlanStatus"
        detection:
          $ref: "#/components/schemas/ModelPlanDetection"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ListModelPlansResponse:
      type: object
      additionalProperties: false
      required:
        - plans
      properties:
        plans:
          type: array
          items:
            $ref: "#/components/schemas/ModelPlan"
    PutModelPlanRequest:
      type: object
      additionalProperties: false
      required:
        - name
        - protocol
      properties:
        name:
          type: string
          minLength: 1
        templateKind:
          allOf:
            - $ref: "#/components/schemas/ModelPlanTemplateKind"
          nullable: true
        protocol:
          $ref: "#/components/schemas/ModelPlanProtocol"
        apiKey:
          type: string
          nullable: true
          description: Omitted or null keeps the stored credential on update; a value replaces it. Never echoed back.
        baseUrl:
          type: string
          nullable: true
        models:
          type: array
          nullable: true
          items:
            $ref: "#/components/schemas/ModelPlanModel"
        defaultModel:
          type: string
          nullable: true
        enabled:
          type: boolean
          nullable: true
    DuplicateModelPlanRequest:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          nullable: true
    SetModelPlanEnabledRequest:
      type: object
      additionalProperties: false
      required:
        - enabled
      properties:
        enabled:
          type: boolean
          x-go-type: "*bool"
    DetectModelPlanRequest:
      type: object
      additionalProperties: false
      properties:
        planId:
          type: string
          nullable: true
          description: When set, omitted fields fall back to the stored plan and the outcome persists onto it.
        templateKind:
          allOf:
            - $ref: "#/components/schemas/ModelPlanTemplateKind"
          nullable: true
          description: Required for unsaved drafts whose detection path depends on the access scheme, such as an official provider subscription.
        protocol:
          allOf:
            - $ref: "#/components/schemas/ModelPlanProtocol"
          nullable: true
        baseUrl:
          type: string
          nullable: true
        apiKey:
          type: string
          nullable: true
        models:
          type: array
          nullable: true
          items:
            $ref: "#/components/schemas/ModelPlanModel"
        model:
          type: string
          nullable: true
          description: Model id for the inference stage; defaults to the plan default model, then the first known model.
    DetectModelPlanResponse:
      type: object
      additionalProperties: false
      required:
        - detection
        - discoveredModels
      properties:
        detection:
          $ref: "#/components/schemas/ModelPlanDetection"
        discoveredModels:
          type: array
          items:
            $ref: "#/components/schemas/ModelPlanModel"
    ModelPlanReference:
      type: object
      additionalProperties: false
      required:
        - kind
        - id
      properties:
        kind:
          type: string
          enum:
            - agent_target
            - model_policy
            - workspace_agent
        id:
          type: string
        name:
          type: string
          nullable: true
        role:
          type: string
          nullable: true
          description: How the consumer uses the plan. Agent target bindings report "default"; model usage policies report the bound role (execution, planning, or review).
    ModelPlanReferencesResponse:
      type: object
      additionalProperties: false
      required:
        - references
      properties:
        references:
          type: array
          items:
            $ref: "#/components/schemas/ModelPlanReference"
    DeleteModelPlanResponse:
      type: object
      additionalProperties: false
      required:
        - modelPlanId
      properties:
        modelPlanId:
          type: string
    PlanModelRef:
      type: object
      additionalProperties: false
      properties:
        modelPlanId:
          type: string
          nullable: true
        model:
          type: string
          nullable: true
    ModelPolicyReviewRule:
      type: object
      additionalProperties: false
      required:
        - enabled
      properties:
        enabled:
          type: boolean
        trigger:
          type: string
          enum:
            - on_task_complete
          nullable: true
        maxRunsPerSession:
          type: integer
          nullable: true
        maxTotalTokensPerSession:
          type: integer
          format: int64
          nullable: true
    ModelUsagePolicy:
      type: object
      additionalProperties: false
      required:
        - id
        - workspaceId
        - name
        - reviewRule
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
        workspaceId:
          type: string
        name:
          type: string
        execution:
          allOf:
            - $ref: "#/components/schemas/PlanModelRef"
          nullable: true
        planning:
          allOf:
            - $ref: "#/components/schemas/PlanModelRef"
          nullable: true
        review:
          allOf:
            - $ref: "#/components/schemas/PlanModelRef"
          nullable: true
        reviewRule:
          $ref: "#/components/schemas/ModelPolicyReviewRule"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ListModelPoliciesResponse:
      type: object
      additionalProperties: false
      required:
        - policies
      properties:
        policies:
          type: array
          items:
            $ref: "#/components/schemas/ModelUsagePolicy"
    PutModelPolicyRequest:
      type: object
      additionalProperties: false
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
        execution:
          allOf:
            - $ref: "#/components/schemas/PlanModelRef"
          nullable: true
        planning:
          allOf:
            - $ref: "#/components/schemas/PlanModelRef"
          nullable: true
        review:
          allOf:
            - $ref: "#/components/schemas/PlanModelRef"
          nullable: true
        reviewRule:
          allOf:
            - $ref: "#/components/schemas/ModelPolicyReviewRule"
          nullable: true
    DeleteModelPolicyResponse:
      type: object
      additionalProperties: false
      required:
        - modelPolicyId
      properties:
        modelPolicyId:
          type: string
    AgentSessionModelPolicyOverride:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - agentSessionId
        - disabled
      properties:
        workspaceId:
          type: string
        agentSessionId:
          type: string
        disabled:
          type: boolean
        modelPolicyId:
          type: string
          nullable: true
        updatedAt:
          type: string
          format: date-time
          nullable: true
    SetAgentSessionModelPolicyOverrideRequest:
      type: object
      additionalProperties: false
      required:
        - disabled
      properties:
        disabled:
          type: boolean
        modelPolicyId:
          type: string
          nullable: true
    AgentSessionAcceptance:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - agentSessionId
        - state
      properties:
        workspaceId:
          type: string
        agentSessionId:
          type: string
        state:
          type: string
          enum:
            - agent_claimed
            - auto_checked
            - user_accepted
        reviewRunId:
          type: string
          nullable: true
        updatedAt:
          type: string
          format: date-time
          nullable: true
    AgentSessionAcceptanceResponse:
      type: object
      additionalProperties: false
      properties:
        acceptance:
          allOf:
            - $ref: "#/components/schemas/AgentSessionAcceptance"
          nullable: true
    CollaborationRunMode:
      type: string
      description: Collaboration kind. consult is a daemon-side advisory completion (advice only, no tools, ownership never changes); fork, delegate, and handoff link to a target session created through the session-create path.
      enum:
        - consult
        - fork
        - delegate
        - handoff
    CollaborationRunTriggerSource:
      type: string
      enum:
        - user
        - agent
        - policy
    CollaborationRunStatus:
      type: string
      enum:
        - running
        - completed
        - failed
        - canceled
    CollaborationRunAdoption:
      type: string
      description: Whether the run outcome was taken up by the source task. Fork and handoff runs report not_applicable.
      enum:
        - pending
        - adopted
        - rejected
        - not_applicable
    CollaborationRunUsage:
      type: object
      additionalProperties: false
      required:
        - inputTokens
        - outputTokens
      properties:
        inputTokens:
          type: integer
          format: int64
        outputTokens:
          type: integer
          format: int64
    CollaborationRun:
      type: object
      additionalProperties: false
      description: One recorded collaboration run with full accounting. Credentials never appear on run records; consults resolve the plan credential at call time only.
      required:
        - id
        - workspaceId
        - mode
        - triggerSource
        - status
        - adoption
        - usage
        - durationMs
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
        workspaceId:
          type: string
        mode:
          $ref: "#/components/schemas/CollaborationRunMode"
        triggerSource:
          $ref: "#/components/schemas/CollaborationRunTriggerSource"
        triggerReason:
          type: string
          nullable: true
        sourceSessionId:
          type: string
          nullable: true
        targetSessionId:
          type: string
          nullable: true
        targetAgentTargetId:
          type: string
          nullable: true
        modelPlanId:
          type: string
          nullable: true
        model:
          type: string
          nullable: true
        contextScope:
          type: string
          nullable: true
          description: How much source context was carried over, for example none, summary, or full.
        prompt:
          type: string
          nullable: true
          description: Stored consult input (context plus question).
        resultText:
          type: string
          nullable: true
          description: Consult output text.
        failureReason:
          type: string
          nullable: true
          description: Machine-readable failure code such as unauthorized, model_rejected, or canceled.
        status:
          $ref: "#/components/schemas/CollaborationRunStatus"
        adoption:
          $ref: "#/components/schemas/CollaborationRunAdoption"
        usage:
          $ref: "#/components/schemas/CollaborationRunUsage"
        startedAt:
          type: string
          format: date-time
          nullable: true
        completedAt:
          type: string
          format: date-time
          nullable: true
        durationMs:
          type: integer
          format: int64
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ListCollaborationRunsResponse:
      type: object
      additionalProperties: false
      required:
        - runs
      properties:
        runs:
          type: array
          items:
            $ref: "#/components/schemas/CollaborationRun"
    CreateCollaborationRunRequest:
      type: object
      additionalProperties: false
      required:
        - mode
        - triggerSource
      properties:
        mode:
          $ref: "#/components/schemas/CollaborationRunMode"
        sourceSessionId:
          type: string
          nullable: true
          description: Required for consult runs; consults are capped per source session.
        targetSessionId:
          type: string
          nullable: true
        targetAgentTargetId:
          type: string
          nullable: true
        modelPlanId:
          type: string
          nullable: true
          description: Required for consult runs; the plan must exist and be enabled.
        model:
          type: string
          nullable: true
          description: Defaults to the plan default model for consult runs.
        question:
          type: string
          nullable: true
          description: Consult question; required for consult runs.
        contextText:
          type: string
          nullable: true
          description: Optional prepared context prepended to the consult question.
        contextScope:
          type: string
          nullable: true
        triggerSource:
          $ref: "#/components/schemas/CollaborationRunTriggerSource"
        triggerReason:
          type: string
          nullable: true
        maxTokens:
          type: integer
          nullable: true
          description: Consult completion output token cap.
    SetCollaborationRunAdoptionRequest:
      type: object
      additionalProperties: false
      required:
        - adoption
      properties:
        adoption:
          $ref: "#/components/schemas/CollaborationRunAdoption"
    AgentModelBinding:
      type: object
      additionalProperties: false
      description: Per-workspace default model configuration for one agent target. Empty modelPlanId means the target keeps its provider-native model source.
      required:
        - workspaceId
        - agentTargetId
      properties:
        workspaceId:
          type: string
        agentTargetId:
          type: string
        modelPlanId:
          type: string
          nullable: true
        defaultModel:
          type: string
          nullable: true
        modelPolicyId:
          type: string
          nullable: true
        updatedAt:
          type: string
          format: date-time
          nullable: true
    ListAgentModelBindingsResponse:
      type: object
      additionalProperties: false
      required:
        - bindings
      properties:
        bindings:
          type: array
          items:
            $ref: "#/components/schemas/AgentModelBinding"
    SetAgentModelBindingRequest:
      type: object
      additionalProperties: false
      properties:
        modelPlanId:
          type: string
          nullable: true
        defaultModel:
          type: string
          nullable: true
          description: Must belong to the referenced plan's model list when a plan is set.
        modelPolicyId:
          type: string
          nullable: true
    WorkspaceAppInstallUserPhase:
      type: string
      enum:
        - downloading
        - installing
        - starting
      x-enum-varnames:
        - WorkspaceAppInstallUserPhaseDownloading
        - WorkspaceAppInstallUserPhaseInstalling
        - WorkspaceAppInstallUserPhaseStarting
    WorkspaceAppInstallProgress:
      type: object
      additionalProperties: false
      required:
        - userPhase
        - overallPercent
        - downloadedBytes
        - totalBytes
        - indeterminate
      properties:
        userPhase:
          $ref: "#/components/schemas/WorkspaceAppInstallUserPhase"
        overallPercent:
          type: number
          minimum: 0
          maximum: 100
        downloadedBytes:
          type: integer
          format: int64
          nullable: true
        totalBytes:
          type: integer
          format: int64
          nullable: true
        indeterminate:
          type: boolean
    WorkspaceAppRuntimeStatus:
      type: string
      enum:
        - idle
        - preparing
        - starting
        - running
        - installed_pending_restart
        - failed
        - stopping
      x-enum-varnames:
        - WorkspaceAppRuntimeStatusIdle
        - WorkspaceAppRuntimeStatusPreparing
        - WorkspaceAppRuntimeStatusStarting
        - WorkspaceAppRuntimeStatusRunning
        - WorkspaceAppRuntimeStatusInstalledPendingRestart
        - WorkspaceAppRuntimeStatusFailed
        - WorkspaceAppRuntimeStatusStopping
    WorkspaceAppSource:
      type: string
      enum:
        - builtin
        - generated
        - imported
        - local-dev
      x-enum-varnames:
        - WorkspaceAppSourceBuiltin
        - WorkspaceAppSourceGenerated
        - WorkspaceAppSourceImported
        - WorkspaceAppSourceLocalDev
    WorkspaceAppCatalogLoadStatus:
      type: string
      enum:
        - disabled
        - loading
        - ready
        - failed
      x-enum-varnames:
        - WorkspaceAppCatalogLoadStatusDisabled
        - WorkspaceAppCatalogLoadStatusLoading
        - WorkspaceAppCatalogLoadStatusReady
        - WorkspaceAppCatalogLoadStatusFailed
    WorkspaceAppCatalogLoadState:
      type: object
      additionalProperties: false
      required:
        - status
        - lastError
        - updatedAtUnixMs
      properties:
        status:
          $ref: "#/components/schemas/WorkspaceAppCatalogLoadStatus"
        lastError:
          type: string
          nullable: true
        updatedAtUnixMs:
          type: integer
          format: int64
          nullable: true
    WorkspaceAppCliStatus:
      type: string
      enum:
        - none
        - pending
        - active
        - warning
        - error
    WorkspaceAppCliIssue:
      type: object
      additionalProperties: false
      required:
        - code
        - message
      properties:
        code:
          type: string
          minLength: 1
        message:
          type: string
          minLength: 1
        path:
          type: string
          nullable: true
    WorkspaceAppCliState:
      type: object
      additionalProperties: false
      required:
        - status
        - active
        - issues
      properties:
        status:
          $ref: "#/components/schemas/WorkspaceAppCliStatus"
        scope:
          type: string
          nullable: true
        active:
          type: boolean
        issues:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceAppCliIssue"
    WorkspaceAppReferencesState:
      type: object
      additionalProperties: false
      required:
        - listSupported
        - searchSupported
      properties:
        listSupported:
          type: boolean
        searchSupported:
          type: boolean
    AppReferenceKind:
      type: string
      enum:
        - file
      x-enum-varnames:
        - AppReferenceKindFile
    AppReferenceListRequest:
      type: object
      additionalProperties: false
      properties:
        parentGroupId:
          type: string
          nullable: true
          maxLength: 2048
        filterText:
          type: string
          nullable: true
          maxLength: 200
        limit:
          type: integer
          minimum: 1
          maximum: 200
        cursor:
          type: string
          nullable: true
          maxLength: 2048
        kinds:
          type: array
          items:
            $ref: "#/components/schemas/AppReferenceKind"
        timeRange:
          $ref: "#/components/schemas/AppReferenceListTimeRange"
    AppReferenceListTimeRange:
      type: object
      additionalProperties: false
      description: >
        Inclusive timestamp range for references. For file references, runtimes
        should filter by the file mtimeMs when available.
      properties:
        fromMs:
          type: integer
          format: int64
          minimum: 0
        toMs:
          type: integer
          format: int64
          minimum: 0
    InstallWorkspaceAppRequest:
      type: object
      additionalProperties: false
      properties:
        restartRunning:
          type: boolean
          description: Restart the app runtime after installing if it is already running.
    AppReferenceListResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - appId
        - items
        - nextCursor
      properties:
        workspaceId:
          type: string
          minLength: 1
        appId:
          type: string
          minLength: 1
        items:
          type: array
          items:
            $ref: "#/components/schemas/AppReferenceListItem"
        nextCursor:
          type: string
          nullable: true
          maxLength: 2048
    AppReferenceSearchRequest:
      type: object
      additionalProperties: false
      required:
        - query
      properties:
        query:
          type: string
          maxLength: 200
        limit:
          type: integer
          minimum: 1
          maximum: 200
        cursor:
          type: string
          nullable: true
          maxLength: 2048
        kinds:
          type: array
          items:
            $ref: "#/components/schemas/AppReferenceKind"
        filters:
          type: array
          description: >-
            已选「文件类型筛选分类」id(全局统一口径)。筛选与搜索是同一能力:query
            可空、filters 非空时即按类型查。空/缺省 = 不按类型过滤。
          items:
            type: string
        timeRange:
          $ref: "#/components/schemas/AppReferenceListTimeRange"
    AppReferenceSearchResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - appId
        - items
        - nextCursor
      properties:
        workspaceId:
          type: string
          minLength: 1
        appId:
          type: string
          minLength: 1
        items:
          type: array
          description: >
            Flat, relevance-ordered list of file references. Search never
            returns group items.
          items:
            $ref: "#/components/schemas/AppReferenceListReferenceItem"
        nextCursor:
          type: string
          nullable: true
          maxLength: 2048
    AppReferenceListItem:
      oneOf:
        - $ref: "#/components/schemas/AppReferenceGroup"
        - $ref: "#/components/schemas/AppReferenceListReferenceItem"
      discriminator:
        propertyName: type
        mapping:
          group: "#/components/schemas/AppReferenceGroup"
          reference: "#/components/schemas/AppReferenceListReferenceItem"
    AppReferenceGroup:
      type: object
      additionalProperties: false
      required:
        - type
        - id
        - displayName
        - referenceCount
      properties:
        type:
          type: string
          enum:
            - group
          x-enum-varnames:
            - AppReferenceGroupTypeGroup
        id:
          type: string
          minLength: 1
          maxLength: 2048
        displayName:
          type: string
          minLength: 1
          maxLength: 160
        description:
          type: string
          nullable: true
          maxLength: 500
        referenceCount:
          type: integer
          minimum: 0
    AppReferenceListReferenceItem:
      type: object
      additionalProperties: false
      required:
        - type
        - reference
      properties:
        type:
          type: string
          enum:
            - reference
          x-enum-varnames:
            - AppReferenceListReferenceItemTypeReference
        reference:
          $ref: "#/components/schemas/AppReference"
    AppReference:
      oneOf:
        - $ref: "#/components/schemas/AppFileReference"
      discriminator:
        propertyName: kind
        mapping:
          file: "#/components/schemas/AppFileReference"
    AppFileReference:
      type: object
      additionalProperties: false
      required:
        - kind
        - displayName
        - description
        - path
        - sizeBytes
        - mtimeMs
        - mimeType
        - score
      properties:
        kind:
          type: string
          enum:
            - file
          x-enum-varnames:
            - AppFileReferenceKindFile
        displayName:
          type: string
          nullable: true
          minLength: 1
          maxLength: 160
        description:
          type: string
          nullable: true
          maxLength: 500
        path:
          type: string
          minLength: 1
          description: >
            Absolute filesystem path resolved by tuttid from the app runtime
            reference location. Workspace app runtimes do not provide this
            public API field directly.
        sizeBytes:
          type: integer
          format: int64
          nullable: true
          minimum: 0
        mtimeMs:
          type: integer
          format: int64
          nullable: true
          minimum: 0
        mimeType:
          type: string
          nullable: true
          maxLength: 128
        score:
          type: number
          nullable: true
          minimum: 0
          maximum: 1
        parentGroupLabel:
          type: string
          nullable: true
          maxLength: 160
          description: >
            Optional label of the group/project this file belongs to, surfaced
            as the result's context subtitle in cross-source search. Apps should
            set it on search results so users can tell which project a file is
            in; when omitted, Tutti falls back to the app display name.
    WorkspaceAppLocalization:
      type: object
      additionalProperties: false
      required:
        - locale
        - displayName
        - description
        - tags
      properties:
        locale:
          type: string
          minLength: 1
        displayName:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        tags:
          type: array
          items:
            type: string
    WorkspaceApp:
      type: object
      additionalProperties: false
      required:
        - appId
        - displayName
        - version
        - description
        - authors
        - createdAtUnixMs
        - iconUrl
        - availableVersion
        - availableIconUrl
        - updateAvailable
        - installed
        - enabled
        - status
        - stateRevision
        - launchUrl
        - port
        - failureReason
        - lastError
        - startedAtUnixMs
        - updatedAtUnixMs
        - source
        - exportable
        - tags
        - localizations
        - minimizeBehavior
        - windowMinWidth
        - windowMinHeight
        - cli
        - references
      properties:
        appId:
          type: string
          minLength: 1
        displayName:
          type: string
          minLength: 1
        version:
          type: string
          minLength: 1
        description:
          type: string
        authors:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceAppAuthor"
        repository:
          $ref: "#/components/schemas/WorkspaceAppRepository"
          nullable: true
        createdAtUnixMs:
          type: integer
          format: int64
          minimum: 1
        installProgress:
          $ref: "#/components/schemas/WorkspaceAppInstallProgress"
          nullable: true
        iconUrl:
          type: string
          nullable: true
        availableVersion:
          type: string
          nullable: true
        availableIconUrl:
          type: string
          nullable: true
        updateAvailable:
          type: boolean
        installed:
          type: boolean
        enabled:
          type: boolean
        status:
          $ref: "#/components/schemas/WorkspaceAppRuntimeStatus"
        stateRevision:
          type: integer
          format: int64
          minimum: 0
        launchUrl:
          type: string
          nullable: true
        port:
          type: integer
          nullable: true
          minimum: 1
          maximum: 65535
        failureReason:
          type: string
          nullable: true
        failurePhase:
          type: string
          nullable: true
          enum:
            - downloading
            - installing
            - starting
            - runtime
        lastError:
          type: string
          nullable: true
        startedAtUnixMs:
          type: integer
          format: int64
          nullable: true
        updatedAtUnixMs:
          type: integer
          format: int64
          nullable: true
        source:
          $ref: "#/components/schemas/WorkspaceAppSource"
        localPackageDir:
          type: string
          nullable: true
          description: Absolute package directory for unpacked local development apps.
        exportable:
          type: boolean
        tags:
          type: array
          items:
            type: string
        localizations:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceAppLocalization"
        minimizeBehavior:
          $ref: "#/components/schemas/WorkspaceAppMinimizeBehavior"
        windowMinWidth:
          type: integer
          nullable: true
          minimum: 280
          maximum: 1600
        windowMinHeight:
          type: integer
          nullable: true
          minimum: 160
          maximum: 1200
        cli:
          $ref: "#/components/schemas/WorkspaceAppCliState"
        references:
          $ref: "#/components/schemas/WorkspaceAppReferencesState"
    WorkspaceAppMinimizeBehavior:
      type: string
      enum:
        - hibernate
        - keep-mounted
    WorkspaceAppAuthor:
      type: object
      additionalProperties: false
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
        url:
          type: string
          nullable: true
        avatarUrl:
          type: string
          nullable: true
    WorkspaceAppRepository:
      type: object
      additionalProperties: false
      required:
        - type
        - url
      properties:
        type:
          type: string
          enum:
            - github
        url:
          type: string
          minLength: 1
    WorkspaceAppUploadPurpose:
      type: string
      enum:
        - app-asset
    PrepareWorkspaceAppUploadRequest:
      type: object
      additionalProperties: false
      required:
        - purpose
        - name
        - mimeType
        - sizeBytes
      properties:
        purpose:
          $ref: "#/components/schemas/WorkspaceAppUploadPurpose"
        name:
          type: string
          minLength: 1
        mimeType:
          type: string
          minLength: 1
        sizeBytes:
          type: integer
          format: int64
          minimum: 0
    PrepareWorkspaceAppUploadResponse:
      type: object
      additionalProperties: false
      required:
        - uploadId
        - expiresAt
      properties:
        uploadId:
          type: string
          minLength: 1
        expiresAt:
          type: string
          format: date-time
    CompleteWorkspaceAppUploadResponse:
      type: object
      additionalProperties: false
      required:
        - file
      properties:
        file:
          $ref: "#/components/schemas/WorkspaceAppUploadedFile"
    WorkspaceAppUploadedFile:
      type: object
      additionalProperties: false
      required:
        - path
        - name
        - mimeType
        - sizeBytes
        - sha256
      properties:
        path:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
        mimeType:
          type: string
          minLength: 1
        sizeBytes:
          type: integer
          format: int64
          minimum: 0
        sha256:
          type: string
          minLength: 64
          maxLength: 64
    RollbackWorkspaceAppRequest:
      type: object
      additionalProperties: false
      required:
        - version
      properties:
        version:
          type: string
          minLength: 1
    ImportWorkspaceAppRequest:
      type: object
      additionalProperties: false
      required:
        - archivePath
      properties:
        archivePath:
          type: string
          minLength: 1
    LoadLocalWorkspaceAppRequest:
      type: object
      additionalProperties: false
      required:
        - sourceDir
      properties:
        sourceDir:
          type: string
          minLength: 1
        restartRunning:
          type: boolean
          description: Restart the app runtime if it is already running.
    ReloadLocalWorkspaceAppRequest:
      type: object
      additionalProperties: false
      properties:
        restartRunning:
          type: boolean
          description: Restart the app runtime if it is already running.
    ExportWorkspaceAppRequest:
      type: object
      additionalProperties: false
      required:
        - destinationPath
      properties:
        destinationPath:
          type: string
          minLength: 1
        version:
          type: string
    ReplaceWorkspaceAppIconRequest:
      type: object
      additionalProperties: false
      required:
        - sourcePath
      properties:
        sourcePath:
          type: string
          minLength: 1
    ExportWorkspaceAppResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - appId
        - version
        - archivePath
        - artifactSha256
        - artifactSizeBytes
      properties:
        workspaceId:
          type: string
          minLength: 1
        appId:
          type: string
          minLength: 1
        version:
          type: string
          minLength: 1
        archivePath:
          type: string
          minLength: 1
        artifactSha256:
          type: string
          minLength: 64
          maxLength: 64
        artifactSizeBytes:
          type: integer
          format: int64
          minimum: 0
    DeleteWorkspaceAppResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - appId
        - deleted
      properties:
        workspaceId:
          type: string
          minLength: 1
        appId:
          type: string
          minLength: 1
        deleted:
          type: boolean
    WorkspaceAppFactoryJobStatus:
      type: string
      enum:
        - queued
        - generating
        - preparing
        - validating
        - ready
        - published
        - failed
        - canceled
      x-enum-varnames:
        - WorkspaceAppFactoryJobStatusQueued
        - WorkspaceAppFactoryJobStatusGenerating
        - WorkspaceAppFactoryJobStatusPreparing
        - WorkspaceAppFactoryJobStatusValidating
        - WorkspaceAppFactoryJobStatusReady
        - WorkspaceAppFactoryJobStatusPublished
        - WorkspaceAppFactoryJobStatusFailed
        - WorkspaceAppFactoryJobStatusCanceled
    WorkspaceAppFactoryJob:
      type: object
      additionalProperties: false
      required:
        - jobId
        - workspaceId
        - status
        - prompt
        - appId
        - displayName
        - description
        - agentTargetId
        - provider
        - model
        - reasoningEffort
        - agentSessionId
        - validationResult
        - failureReason
        - publishedVersion
        - createdAtUnixMs
        - updatedAtUnixMs
      properties:
        jobId:
          type: string
          minLength: 1
        workspaceId:
          type: string
          minLength: 1
        status:
          $ref: "#/components/schemas/WorkspaceAppFactoryJobStatus"
        prompt:
          type: string
        appId:
          type: string
          nullable: true
        displayName:
          type: string
          minLength: 1
        description:
          type: string
          nullable: true
        agentTargetId:
          type: string
          nullable: true
        provider:
          type: string
          nullable: true
        model:
          type: string
          nullable: true
        reasoningEffort:
          type: string
          nullable: true
        agentSessionId:
          type: string
          nullable: true
        validationResult:
          type: object
          nullable: true
          additionalProperties: true
        failureReason:
          type: string
          nullable: true
        publishedVersion:
          type: string
          nullable: true
        createdAtUnixMs:
          type: integer
          format: int64
        updatedAtUnixMs:
          type: integer
          format: int64
    CreateWorkspaceAppFactoryJobRequest:
      type: object
      additionalProperties: false
      required:
        - agentTargetId
        - clientSubmitId
        - displayName
        - prompt
      properties:
        prompt:
          type: string
          minLength: 1
        displayName:
          type: string
          minLength: 1
        description:
          type: string
        agentTargetId:
          type: string
          minLength: 1
        clientSubmitId:
          type: string
          minLength: 1
        provider:
          type: string
          deprecated: true
        model:
          type: string
        permissionModeId:
          type: string
        reasoningEffort:
          type: string
    FixWorkspaceAppFactoryJobRequest:
      type: object
      additionalProperties: false
      required:
        - prompt
      properties:
        prompt:
          type: string
          minLength: 1
    WorkspaceAppFactoryJobListResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - jobs
      properties:
        workspaceId:
          type: string
          minLength: 1
        jobs:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceAppFactoryJob"
    WorkspaceAppFactoryJobResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - job
      properties:
        workspaceId:
          type: string
          minLength: 1
        job:
          $ref: "#/components/schemas/WorkspaceAppFactoryJob"
    PublishWorkspaceAppFactoryJobResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - job
        - app
      properties:
        workspaceId:
          type: string
          minLength: 1
        job:
          $ref: "#/components/schemas/WorkspaceAppFactoryJob"
        app:
          $ref: "#/components/schemas/WorkspaceApp"
    WorkspaceAppListResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - catalogStatus
        - apps
      properties:
        workspaceId:
          type: string
          minLength: 1
        catalogStatus:
          $ref: "#/components/schemas/WorkspaceAppCatalogLoadState"
        apps:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceApp"
    WorkspaceAppResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - app
      properties:
        workspaceId:
          type: string
          minLength: 1
        app:
          $ref: "#/components/schemas/WorkspaceApp"
    WorkspaceTerminalRuntimeKind:
      type: string
      enum:
        - local
        - vm
        - remote
    WorkspaceTerminalStatus:
      type: string
      enum:
        - created
        - starting
        - running
        - detached
        - exited
        - failed
      x-enum-varnames:
        - WorkspaceTerminalStatusCreated
        - WorkspaceTerminalStatusStarting
        - WorkspaceTerminalStatusRunning
        - WorkspaceTerminalStatusDetached
        - WorkspaceTerminalStatusExited
        - WorkspaceTerminalStatusFailed
    WorkspaceTerminalCloseGuardReason:
      type: string
      enum:
        - foreground-process
        - not-running
        - running
        - unknown
    WorkspaceTerminalSession:
      type: object
      additionalProperties: false
      required:
        - id
        - workspaceId
        - title
        - cwd
        - profileId
        - runtimeKind
        - status
        - cols
        - rows
        - createdAt
        - updatedAt
        - endedAt
        - lastError
      properties:
        id:
          type: string
          minLength: 1
        workspaceId:
          type: string
          minLength: 1
        title:
          type: string
        cwd:
          type: string
          nullable: true
        profileId:
          type: string
          nullable: true
        runtimeKind:
          $ref: "#/components/schemas/WorkspaceTerminalRuntimeKind"
        status:
          $ref: "#/components/schemas/WorkspaceTerminalStatus"
        cols:
          type: integer
          minimum: 1
        rows:
          type: integer
          minimum: 1
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
          nullable: true
        endedAt:
          type: string
          format: date-time
          nullable: true
        lastError:
          type: string
          nullable: true
    WorkspaceTerminalResponse:
      type: object
      additionalProperties: false
      required:
        - terminal
      properties:
        terminal:
          $ref: "#/components/schemas/WorkspaceTerminalSession"
    WorkspaceTerminalListResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - terminals
      properties:
        workspaceId:
          type: string
          minLength: 1
        terminals:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceTerminalSession"
    CreateWorkspaceTerminalRequest:
      type: object
      additionalProperties: false
      properties:
        cwd:
          type: string
          nullable: true
        profileId:
          type: string
          nullable: true
        initialInput:
          type: string
          nullable: true
        cols:
          type: integer
          minimum: 1
        rows:
          type: integer
          minimum: 1
    ResizeWorkspaceTerminalRequest:
      type: object
      additionalProperties: false
      required:
        - cols
        - rows
      properties:
        cols:
          type: integer
          minimum: 1
        rows:
          type: integer
          minimum: 1
    WorkspaceTerminalSnapshot:
      type: object
      additionalProperties: false
      required:
        - data
      properties:
        data:
          type: string
        fromSeq:
          type: integer
          format: int64
          minimum: 0
        toSeq:
          type: integer
          format: int64
          minimum: 0
        truncated:
          type: boolean
        updatedAt:
          type: integer
          format: int64
          minimum: 0
    WorkspaceTerminalSnapshotResponse:
      type: object
      additionalProperties: false
      required:
        - snapshot
      properties:
        snapshot:
          $ref: "#/components/schemas/WorkspaceTerminalSnapshot"
    WorkspaceTerminalCloseGuard:
      type: object
      additionalProperties: false
      required:
        - status
        - reason
        - requiresConfirmation
      properties:
        status:
          $ref: "#/components/schemas/WorkspaceTerminalStatus"
        reason:
          $ref: "#/components/schemas/WorkspaceTerminalCloseGuardReason"
        requiresConfirmation:
          type: boolean
        leaderCommand:
          type: string
          nullable: true
    WorkspaceTerminalCloseGuardResponse:
      type: object
      additionalProperties: false
      required:
        - guard
      properties:
        guard:
          $ref: "#/components/schemas/WorkspaceTerminalCloseGuard"
    DeleteWorkspaceAgentResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceAgentId
      properties:
        workspaceAgentId:
          type: string
    ListWorkspaceAgentsResponse:
      type: object
      additionalProperties: false
      required:
        - agents
      properties:
        agents:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceAgent"
    PutWorkspaceAgentRequest:
      type: object
      additionalProperties: false
      required:
        - name
        - description
        - harnessAgentTargetId
        - instructions
        - callConditions
        - skills
        - tools
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
        description:
          description: Short human-readable description shown with the Agent in directories and cards.
          type: string
          maxLength: 1000
        harnessAgentTargetId:
          type: string
          minLength: 1
        modelPlanId:
          type: string
          nullable: true
        defaultModel:
          type: string
          nullable: true
        modelFallbacks:
          type: array
          description: Ordered fallback Plan/model references. Omit or pass an empty array to disable failover.
          items:
            $ref: "#/components/schemas/WorkspaceAgentModelRef"
        instructions:
          type: string
          maxLength: 100000
        callConditions:
          type: array
          items:
            type: string
            minLength: 1
        capabilitiesExplicit:
          type: boolean
          description: >-
            When true, Skills and tools are an explicit allowlist, including
            the ability to select none. Omit on update to preserve the stored
            mode; new Agents default to automatic compatible capabilities.
        skills:
          type: array
          items:
            type: string
            minLength: 1
        tools:
          type: array
          items:
            type: string
            minLength: 1
    WorkspaceAgent:
      type: object
      additionalProperties: false
      description: A selectable, workspace-scoped Agent made from one Harness target plus an optional model access plan and Agent-specific behavior configuration.
      required:
        - id
        - agentTargetId
        - workspaceId
        - name
        - description
        - harness
        - modelFallbacks
        - instructions
        - callConditions
        - capabilitiesExplicit
        - skills
        - tools
        - source
        - revision
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          minLength: 1
          description: Opaque Agent option id. New ids use the workspace-agent prefix and may be passed to workspace Agent session APIs.
        agentTargetId:
          type: string
          minLength: 1
          description: Compatibility alias of id for AgentGUI and session creation surfaces.
        workspaceId:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
        description:
          description: Short human-readable description shown with the Agent in directories and cards.
          type: string
        harness:
          $ref: "#/components/schemas/WorkspaceAgentHarness"
        modelPlanId:
          type: string
          nullable: true
        defaultModel:
          type: string
          nullable: true
        modelFallbacks:
          type: array
          description: Dormant contract field without an editor surface. Ordered, explicit fallback chain used only when starting a new session and the primary Plan/model is not usable. Credentials remain daemon-owned.
          items:
            $ref: "#/components/schemas/WorkspaceAgentModelRef"
        instructions:
          type: string
        callConditions:
          type: array
          description: Explicit, user-editable conditions that explain when another Agent or user should invoke this Agent.
          items:
            type: string
            minLength: 1
        capabilitiesExplicit:
          type: boolean
          description: >-
            Dormant contract field without an editor surface. False keeps
            Skills and tools synchronized with all capabilities compatible
            with the selected Harness. True makes the Skills and tools arrays
            an explicit allowlist; empty arrays then mean none.
        skills:
          type: array
          items:
            type: string
            minLength: 1
        tools:
          type: array
          items:
            type: string
            minLength: 1
        source:
          $ref: "#/components/schemas/WorkspaceAgentSource"
        revision:
          type: integer
          format: int64
          minimum: 1
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    WorkspaceAgentHarness:
      type: object
      additionalProperties: false
      required:
        - agentTargetId
        - available
      properties:
        agentTargetId:
          type: string
          minLength: 1
        available:
          type: boolean
          description: False when the referenced Harness target no longer exists. The Agent remains listable so it can be repaired or deleted.
        provider:
          allOf:
            - $ref: "#/components/schemas/AgentTargetProvider"
          nullable: true
        name:
          type: string
          nullable: true
        iconKey:
          type: string
          nullable: true
        enabled:
          type: boolean
          nullable: true
    WorkspaceAgentModelRef:
      type: object
      additionalProperties: false
      required:
        - modelPlanId
      properties:
        modelPlanId:
          type: string
          minLength: 1
        model:
          type: string
          nullable: true
    WorkspaceAgentSource:
      type: string
      description: Origin of the workspace Agent configuration. legacy_binding rows were migrated from the former fixed-target binding model.
      enum:
        - user
        - legacy_binding
    WorkspaceAgentProvider:
      type: string
      minLength: 1
      maxLength: 128
      pattern: "^[a-z][a-z0-9._:-]*$"
    AgentSessionComposerSettings:
      type: object
      additionalProperties: false
      properties:
        codexSaverMode:
          type: boolean
          nullable: true
          description: Enables the Codex-specific saver subagent mode
        rtkSaverMode:
          type: boolean
          nullable: true
          description: Enables provider-neutral RTK saver mode
        model:
          type: string
          nullable: true
        permissionModeId:
          type: string
          nullable: true
        planMode:
          type: boolean
          nullable: true
        browserUse:
          type: boolean
          nullable: true
        reasoningEffort:
          type: string
          nullable: true
        speed:
          type: string
          nullable: true
    PermissionModeSemantic:
      type: string
      enum:
        - ask-before-write
        - accept-edits
        - locked-down
        - auto
        - full-access
        - unconfigurable
    PermissionModeOption:
      type: object
      additionalProperties: false
      required:
        - id
        - label
        - semantic
      properties:
        id:
          type: string
          minLength: 1
        label:
          type: string
          minLength: 1
        description:
          type: string
        semantic:
          $ref: "#/components/schemas/PermissionModeSemantic"
    PermissionConfig:
      type: object
      additionalProperties: false
      required:
        - configurable
        - modes
      properties:
        configurable:
          type: boolean
        defaultValue:
          type: string
        modes:
          type: array
          items:
            $ref: "#/components/schemas/PermissionModeOption"
    AgentProviderComposerConfigOptionValue:
      type: object
      additionalProperties: false
      required:
        - id
        - label
        - value
      properties:
        id:
          type: string
          minLength: 1
        value:
          type: string
          minLength: 1
        label:
          type: string
          minLength: 1
        description:
          type: string
        consumptionMultiplier:
          type: string
          description: >-
            Provider-reported credit consumption multiplier without the
            display suffix. Runtime adapters normalize provider wire data into
            this typed field; clients must not infer it from description.
        supportsImageInput:
          type: boolean
        requested:
          type: boolean
          description: >-
            True when the entry mirrors the requested/current selection
            instead of the provider catalog (warm-catalog append of the
            requested model, selected-model bootstrap echo). Clients keep
            such entries selectable but must not treat them as proof the
            provider can run the model; create validation runs against the
            raw catalog only.
    AgentProviderComposerConfig:
      type: object
      additionalProperties: false
      required:
        - configurable
        - options
      properties:
        configurable:
          type: boolean
        currentValue:
          type: string
        effectiveValue:
          type: string
          description: >-
            Provider-resolved runtime value. This may differ from currentValue
            when the current selection inherits a provider default.
        defaultValue:
          type: string
        options:
          type: array
          items:
            $ref: "#/components/schemas/AgentProviderComposerConfigOptionValue"
    GetAgentProviderComposerOptionsRequest:
      type: object
      additionalProperties: false
      properties:
        agentSessionId:
          type: string
          description: >-
            Active Agent session whose isolated provider home contributes
            session-created Skills to the composer catalog.
        section:
          type: string
          enum:
            - full
            - core
            - capabilities
            - connectors
          default: full
          description: >-
            Selects the independently loadable composer section. Core contains
            model, reasoning, speed, permission, and runtime settings;
            capabilities contains skills and capability catalog data;
            connectors contains only the local Connector Market projection.
            Full is retained for callers that need the combined legacy response.
        waitForFreshModelCatalog:
          type: boolean
          description: >-
            Waits for an authoritative model catalog when the cached result is
            stale. Use only for an explicit model-picker request; ordinary
            composer loads should render the last successful catalog first.
        agentTargetId:
          type: string
          description:
            Agent target whose provider and runtime context the composer options
            resolve against. Optional; when omitted the provider path parameter
            is used directly.
        cwd:
          type: string
        workspaceId:
          type: string
          description: Workspace used for Claude Code live model discovery.
        locale:
          $ref: "#/components/schemas/DesktopLocale"
        settings:
          $ref: "#/components/schemas/AgentSessionComposerSettings"
    GetWorkspaceAppFactoryAgentTargetComposerOptionsRequest:
      type: object
      additionalProperties: false
      properties:
        section:
          type: string
          enum:
            - full
            - core
            - capabilities
            - connectors
          default: full
          description: Independently loadable composer section.
        locale:
          $ref: "#/components/schemas/DesktopLocale"
        settings:
          $ref: "#/components/schemas/AgentSessionComposerSettings"
    AgentProviderComposerOptionsResponse:
      type: object
      additionalProperties: false
      required:
        - provider
        - modelConfig
        - permissionConfig
        - reasoningConfig
        - reasoningOptionsByModel
        - effectiveSettings
        - runtimeContext
        - commands
        - skills
        - capabilityCatalog
        - behavior
      properties:
        codexSaverModeSupported:
          type: boolean
          description: Whether this resolved provider target supports the Codex-specific saver subagent mode
        rtkSaverModeSupported:
          type: boolean
          description: Whether this resolved provider target supports provider-neutral, session-scoped RTK saver mode
        provider:
          $ref: "#/components/schemas/WorkspaceAgentProvider"
        modelConfig:
          $ref: "#/components/schemas/AgentProviderComposerConfig"
        permissionConfig:
          $ref: "#/components/schemas/PermissionConfig"
        reasoningConfig:
          $ref: "#/components/schemas/AgentProviderComposerConfig"
        reasoningOptionsByModel:
          $ref: "#/components/schemas/AgentProviderComposerReasoningOptionsByModel"
        speedConfig:
          $ref: "#/components/schemas/AgentProviderComposerConfig"
        effectiveSettings:
          $ref: "#/components/schemas/AgentSessionComposerSettings"
        runtimeContext:
          type: object
          additionalProperties: true
          description: >-
            Opaque provider runtime metadata retained for legacy and diagnostic
            consumers. Typed composer fields are authoritative; new composer
            capabilities must not be added to this object.
        commands:
          type: array
          description: Commands advertised by the resolved runtime session.
          items:
            $ref: "#/components/schemas/AgentProviderComposerCommandOption"
        capabilities:
          $ref: "#/components/schemas/WorkspaceAgentCapabilities"
          description: >-
            Typed provider capabilities available before a session exists.
            Once a session is active, WorkspaceAgentSession.capabilities is
            authoritative. Older daemons may omit this field during a rolling
            desktop upgrade.
        skills:
          type: array
          items:
            $ref: "#/components/schemas/AgentProviderSkillOption"
        capabilityCatalog:
          type: array
          items:
            $ref: "#/components/schemas/AgentProviderCapabilityOption"
        behavior:
          $ref: "#/components/schemas/AgentProviderComposerBehavior"
        slashCommandPolicy:
          $ref: "#/components/schemas/AgentSlashCommandPolicy"
    AgentProviderComposerCommandOption:
      type: object
      additionalProperties: false
      required:
        - name
      properties:
        name:
          type: string
        description:
          type: string
        inputHint:
          type: string
    AgentProviderComposerReasoningOptionsByModel:
      type: object
      additionalProperties:
        $ref: "#/components/schemas/AgentProviderComposerReasoningProfile"
    AgentProviderComposerReasoningProfile:
      type: object
      additionalProperties: false
      required:
        - options
      properties:
        defaultValue:
          type: string
          nullable: true
        options:
          type: array
          items:
            $ref: "#/components/schemas/AgentProviderComposerConfigOptionValue"
    AgentProviderComposerBehavior:
      type: object
      additionalProperties: false
      required:
        - collapseModelOptionsToLatest
        - modelOptionsAuthoritative
        - refreshModelOptionsAfterSettings
        - prewarmDraftSession
        - planModeExclusiveWithPermissionMode
      properties:
        collapseModelOptionsToLatest:
          type: boolean
        modelOptionsAuthoritative:
          type: boolean
        refreshModelOptionsAfterSettings:
          type: boolean
        prewarmDraftSession:
          type: boolean
        planModeExclusiveWithPermissionMode:
          type: boolean
    AgentSlashCommandEffect:
      type: string
      enum:
        - submitImmediate
        - showReviewPicker
        - activateGoalMode
        - togglePlanMode
        - showStatus
        - toggleSpeed
    AgentSlashCommandEffectDescriptor:
      type: object
      additionalProperties: false
      required:
        - command
        - effect
      properties:
        command:
          type: string
        effect:
          $ref: "#/components/schemas/AgentSlashCommandEffect"
    AgentSlashCommandPolicy:
      type: object
      additionalProperties: false
      required:
        - fallbackCommands
        - commandEffects
      properties:
        fallbackCommands:
          type: array
          items:
            type: string
        commandEffects:
          type: array
          items:
            $ref: "#/components/schemas/AgentSlashCommandEffectDescriptor"
        commandCatalogAuthoritative:
          type: boolean
    AgentProviderSkillOption:
      type: object
      additionalProperties: false
      required:
        - name
        - trigger
        - sourceKind
      properties:
        name:
          type: string
        trigger:
          type: string
        sourceKind:
          type: string
          enum:
            - project
            - personal
            - bundled
            - plugin
            - system
            - tutti-injected
        description:
          type: string
        pluginName:
          type: string
        path:
          type: string
    AgentProviderCapabilityOption:
      type: object
      additionalProperties: false
      required:
        - id
        - kind
        - name
        - label
        - status
        - invocation
      properties:
        id:
          type: string
          minLength: 1
        kind:
          type: string
          enum:
            - skill
            - plugin
            - connector
            - mcpServer
            - mcpTool
        name:
          type: string
          minLength: 1
        label:
          type: string
          minLength: 1
        description:
          type: string
        iconUrl:
          type: string
        installedAtUnixMs:
          type: integer
          format: int64
          minimum: 1
        status:
          type: string
          enum:
            - available
            - disabled
            - authRequired
            - setupRequired
            - unsupported
        source:
          type: string
        pluginName:
          type: string
        serverName:
          type: string
        toolName:
          type: string
        trigger:
          type: string
        path:
          type: string
        invocation:
          type: string
          enum:
            - promptItem
            - textTrigger
            - none
    AgentProviderAvailabilityStatus:
      type: string
      enum:
        - ready
        - not_installed
        - auth_required
        - unsupported
        - unknown
    AgentProviderAuthStatus:
      type: string
      enum:
        - authenticated
        - configured
        - required
        - unknown
    AgentProviderActionKind:
      type: string
      enum:
        - daemon_action
        - terminal_command
        - refresh
    AgentProviderActionID:
      type: string
      enum:
        - install
        - update
        - login
        - refresh
    AgentProviderUpdateCapability:
      type: string
      enum:
        - supported
        - unsupported
    AgentProviderUpdateSource:
      type: string
      enum:
        - npm
    AgentProviderProbeStatus:
      type: string
      enum:
        - ready
        - failed
        - skipped
    AgentProviderActionRunStatus:
      type: string
      enum:
        - completed
        - failed
    AgentProviderActiveActionPhase:
      type: string
      enum:
        - detect
        - install
        - update
        - repair
        - verify
        - done
        - error
    AgentProviderActiveActionStepStatus:
      type: string
      enum:
        - pending
        - running
        - ok
        - error
        - skipped
    AgentProviderActiveActionStep:
      type: object
      additionalProperties: false
      required:
        - id
        - label
        - status
        - detail
      properties:
        id:
          type: string
        label:
          type: string
          nullable: true
        status:
          $ref: "#/components/schemas/AgentProviderActiveActionStepStatus"
        detail:
          type: string
          nullable: true
    AgentProviderActiveActionError:
      type: object
      additionalProperties: false
      required:
        - code
        - message
      properties:
        code:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
    AgentProviderActiveAction:
      type: object
      additionalProperties: false
      required:
        - phase
        - steps
        - registry
        - log
        - error
      properties:
        phase:
          $ref: "#/components/schemas/AgentProviderActiveActionPhase"
        steps:
          type: array
          items:
            $ref: "#/components/schemas/AgentProviderActiveActionStep"
        registry:
          type: string
          nullable: true
        log:
          type: array
          items:
            type: string
        error:
          allOf:
            - $ref: "#/components/schemas/AgentProviderActiveActionError"
          nullable: true
    AgentProviderProbeResponse:
      type: object
      additionalProperties: false
      required:
        - provider
        - status
        - checkedAt
        - command
      properties:
        provider:
          $ref: "#/components/schemas/WorkspaceAgentProvider"
        status:
          $ref: "#/components/schemas/AgentProviderProbeStatus"
        checkedAt:
          type: string
          format: date-time
        reasonCode:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
        binaryPath:
          type: string
          nullable: true
        command:
          type: array
          items:
            type: string
    AgentProviderActionRunResponse:
      type: object
      additionalProperties: false
      required:
        - provider
        - actionID
        - status
        - completedAt
      properties:
        provider:
          $ref: "#/components/schemas/WorkspaceAgentProvider"
        actionID:
          $ref: "#/components/schemas/AgentProviderActionID"
        status:
          $ref: "#/components/schemas/AgentProviderActionRunStatus"
        completedAt:
          type: string
          format: date-time
        reasonCode:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
        command:
          type: string
          nullable: true
        exitCode:
          type: integer
          nullable: true
        stdout:
          type: string
          nullable: true
        stderr:
          type: string
          nullable: true
        probe:
          allOf:
            - $ref: "#/components/schemas/AgentProviderProbeResponse"
          nullable: true
    AgentProviderTerminalCommand:
      type: object
      additionalProperties: false
      required:
        - input
      properties:
        input:
          type: string
          minLength: 1
        cwd:
          type: string
          nullable: true
    AgentProviderAction:
      type: object
      additionalProperties: false
      required:
        - id
        - kind
      properties:
        id:
          $ref: "#/components/schemas/AgentProviderActionID"
        kind:
          $ref: "#/components/schemas/AgentProviderActionKind"
        command:
          allOf:
            - $ref: "#/components/schemas/AgentProviderTerminalCommand"
          nullable: true
    AgentProviderAvailability:
      type: object
      additionalProperties: false
      required:
        - status
      properties:
        status:
          $ref: "#/components/schemas/AgentProviderAvailabilityStatus"
        reasonCode:
          type: string
          nullable: true
        checkedAt:
          type: string
          format: date-time
          nullable: true
    AgentProviderCliStatus:
      type: object
      additionalProperties: false
      required:
        - installed
      properties:
        installed:
          type: boolean
        binaryPath:
          type: string
          nullable: true
        version:
          type: string
          nullable: true
        minVersion:
          type: string
          nullable: true
          description: >-
            The lowest CLI version this provider supports, when it enforces a
            floor. Lets the UI show "current X, requires >= Y" without
            duplicating the backend's version gate.
    AgentProviderAdapterStatus:
      type: object
      additionalProperties: false
      required:
        - installed
        - command
      properties:
        installed:
          type: boolean
        binaryPath:
          type: string
          nullable: true
        command:
          type: array
          items:
            type: string
        version:
          type: string
          nullable: true
          description: >-
            The installed ACP adapter package version, when resolvable. Lets the
            UI and telemetry show the actual adapter version (not just a path).
        requiredVersion:
          type: string
          nullable: true
          description: >-
            The minimum adapter package version this provider accepts. With
            version, lets the UI show "current X, requires >= Y" for an adapter
            version mismatch and makes the drift visible in telemetry.
    AgentProviderAuthInfo:
      type: object
      additionalProperties: false
      required:
        - status
      properties:
        status:
          $ref: "#/components/schemas/AgentProviderAuthStatus"
        accountLabel:
          type: string
          nullable: true
        authMethod:
          type: string
          nullable: true
          description: The authentication method reported by the provider CLI (e.g. oauth, apiKey).
    AgentProviderUpdateStatus:
      type: object
      additionalProperties: false
      required:
        - capability
        - source
        - currentVersion
        - latestVersion
        - updateAvailable
        - unsupportedReason
        - lastCheckedAt
        - reasonCode
      properties:
        capability:
          $ref: "#/components/schemas/AgentProviderUpdateCapability"
        source:
          allOf:
            - $ref: "#/components/schemas/AgentProviderUpdateSource"
          nullable: true
        currentVersion:
          type: string
          nullable: true
        latestVersion:
          type: string
          nullable: true
        updateAvailable:
          type: boolean
          nullable: true
          description: >-
            Null when discovery has not run, failed, or the current/latest
            versions cannot be compared safely.
        unsupportedReason:
          type: string
          nullable: true
          description: Stable reason why this provider cannot be updated by tuttid.
        lastCheckedAt:
          type: string
          format: date-time
          nullable: true
        reasonCode:
          type: string
          nullable: true
          description: Non-fatal discovery or version-comparison result code.
    AgentProviderStatus:
      type: object
      additionalProperties: false
      required:
        - provider
        - availability
        - cli
        - adapter
        - auth
        - update
        - actions
      properties:
        provider:
          $ref: "#/components/schemas/WorkspaceAgentProvider"
        availability:
          $ref: "#/components/schemas/AgentProviderAvailability"
        cli:
          $ref: "#/components/schemas/AgentProviderCliStatus"
        adapter:
          $ref: "#/components/schemas/AgentProviderAdapterStatus"
        auth:
          $ref: "#/components/schemas/AgentProviderAuthInfo"
        update:
          $ref: "#/components/schemas/AgentProviderUpdateStatus"
        actions:
          type: array
          items:
            $ref: "#/components/schemas/AgentProviderAction"
        network:
          allOf:
            - $ref: "#/components/schemas/AgentProviderNetworkStatus"
          nullable: true
        activeAction:
          allOf:
            - $ref: "#/components/schemas/AgentProviderActiveAction"
          nullable: true
    AgentProviderNetworkStatus:
      type: object
      additionalProperties: false
      required:
        - registry
      properties:
        registry:
          $ref: "#/components/schemas/AgentProviderNetworkEndpoint"
        providerApi:
          allOf:
            - $ref: "#/components/schemas/AgentProviderNetworkEndpoint"
          nullable: true
        proxy:
          allOf:
            - $ref: "#/components/schemas/AgentProviderNetworkProxy"
          nullable: true
    AgentProviderNetworkProxy:
      type: object
      additionalProperties: false
      required:
        - configured
        - reachable
      properties:
        configured:
          type: boolean
        url:
          type: string
          nullable: true
        reachable:
          type: boolean
        reasonCode:
          type: string
          nullable: true
    AgentProviderNetworkEndpoint:
      type: object
      additionalProperties: false
      required:
        - reachable
      properties:
        reachable:
          type: boolean
        endpoint:
          type: string
          nullable: true
        reasonCode:
          type: string
          nullable: true
    AgentProviderStatusListResponse:
      type: object
      additionalProperties: false
      required:
        - capturedAt
        - defaultProvider
        - providers
      properties:
        capturedAt:
          type: string
          format: date-time
        defaultProvider:
          $ref: "#/components/schemas/WorkspaceAgentProvider"
        providers:
          type: array
          items:
            $ref: "#/components/schemas/AgentProviderStatus"
    AgentProviderRuntimeCandidateState:
      type: string
      enum:
        - ready
        - unsupported
        - failed
      x-enum-varnames:
        - AgentProviderRuntimeCandidateStateReady
        - AgentProviderRuntimeCandidateStateUnsupported
        - AgentProviderRuntimeCandidateStateFailed
    AgentProviderRuntimeSelectionState:
      type: string
      enum:
        - unavailable
        - implicit_unique
        - selection_required
        - selected
        - stale
      x-enum-varnames:
        - AgentProviderRuntimeSelectionStateUnavailable
        - AgentProviderRuntimeSelectionStateImplicitUnique
        - AgentProviderRuntimeSelectionStateSelectionRequired
        - AgentProviderRuntimeSelectionStateSelected
        - AgentProviderRuntimeSelectionStateStale
    AgentProviderRuntimeCandidate:
      type: object
      additionalProperties: false
      required:
        - id
        - launcherPath
        - packageRoot
        - sources
        - version
        - state
        - reasonCode
        - appServerReady
        - packageLayoutOk
      properties:
        id:
          type: string
          minLength: 1
          description: Opaque identifier valid only for the enclosing catalog revision
        launcherPath:
          type: string
          minLength: 1
        packageRoot:
          type: string
          nullable: true
        sources:
          type: array
          items:
            type: string
            enum:
              - path
              - bun_global
              - pnpm_global
              - npm_global
              - homebrew
            x-enum-varnames:
              - AgentProviderRuntimeCandidateSourcePath
              - AgentProviderRuntimeCandidateSourceBunGlobal
              - AgentProviderRuntimeCandidateSourcePnpmGlobal
              - AgentProviderRuntimeCandidateSourceNpmGlobal
              - AgentProviderRuntimeCandidateSourceHomebrew
        version:
          type: string
          nullable: true
        state:
          $ref: "#/components/schemas/AgentProviderRuntimeCandidateState"
        reasonCode:
          type: string
          nullable: true
        appServerReady:
          type: boolean
        packageLayoutOk:
          type: boolean
    AgentProviderRuntimeSelection:
      type: object
      additionalProperties: false
      required:
        - state
        - candidateId
        - launcherPath
        - updatedAt
      properties:
        state:
          $ref: "#/components/schemas/AgentProviderRuntimeSelectionState"
        candidateId:
          type: string
          nullable: true
        launcherPath:
          type: string
          nullable: true
        updatedAt:
          type: string
          format: date-time
          nullable: true
    AgentProviderRuntimeCatalogResponse:
      type: object
      additionalProperties: false
      required:
        - capturedAt
        - provider
        - revision
        - selection
        - candidates
      properties:
        capturedAt:
          type: string
          format: date-time
        provider:
          $ref: "#/components/schemas/WorkspaceAgentProvider"
        revision:
          type: string
          minLength: 1
        selection:
          $ref: "#/components/schemas/AgentProviderRuntimeSelection"
        candidates:
          type: array
          items:
            $ref: "#/components/schemas/AgentProviderRuntimeCandidate"
    SetAgentProviderRuntimeSelectionRequest:
      type: object
      additionalProperties: false
      required:
        - candidateId
        - revision
      properties:
        candidateId:
          type: string
          minLength: 1
          description: Opaque identifier from the current runtime candidate catalog
        revision:
          type: string
          minLength: 1
          description: Must match the catalog revision that supplied candidateId
    TuttiModeActivationStatus:
      type: string
      enum:
        - active
        - inactive
    TuttiModeActivationSource:
      type: string
      description: User-visible interaction that created this activation revision.
      enum:
        - slash_command
        - badge_remove
      x-enum-varnames:
        - TuttiModeActivationSourceSlashCommand
        - TuttiModeActivationSourceBadgeRemove
    TuttiModeActivationRevision:
      type: object
      additionalProperties: false
      required:
        - id
        - activationId
        - revision
        - status
        - source
        - orchestrationIntensity
        - createdAtUnixMs
      properties:
        id:
          type: string
          format: uuid
        activationId:
          type: string
          format: uuid
        revision:
          type: integer
          format: int64
          minimum: 1
        status:
          $ref: "#/components/schemas/TuttiModeActivationStatus"
        source:
          $ref: "#/components/schemas/TuttiModeActivationSource"
        effect:
          type: integer
          nullable: true
          minimum: 0
          maximum: 100
          description: >-
            Session-scoped outcome-quality preference captured with this
            activation revision. Higher values favor stronger models and
            stronger task verification.
        speed:
          type: integer
          nullable: true
          minimum: 0
          maximum: 100
          description: >-
            Session-scoped completion-speed preference captured with this
            activation revision. Higher values favor faster suitable models.
        orchestrationIntensity:
          type: integer
          minimum: 0
          maximum: 100
          deprecated: true
          description: Legacy single-axis alias of effect. New clients use effect and speed.
        createdAtUnixMs:
          type: integer
          format: int64
          minimum: 0
    TuttiModeActivation:
      type: object
      additionalProperties: false
      required:
        - id
        - workspaceId
        - agentSessionId
        - status
        - currentRevision
        - createdAtUnixMs
        - updatedAtUnixMs
      properties:
        id:
          type: string
          format: uuid
        workspaceId:
          type: string
          minLength: 1
        agentSessionId:
          type: string
          minLength: 1
        status:
          $ref: "#/components/schemas/TuttiModeActivationStatus"
        currentRevision:
          $ref: "#/components/schemas/TuttiModeActivationRevision"
        createdAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        updatedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
    TuttiModeActivationIntent:
      type: object
      additionalProperties: false
      required:
        - status
        - source
      properties:
        status:
          $ref: "#/components/schemas/TuttiModeActivationStatus"
        source:
          $ref: "#/components/schemas/TuttiModeActivationSource"
        effect:
          type: integer
          nullable: true
          minimum: 0
          maximum: 100
          description: >-
            Optional outcome-quality preference carried with the initial
            activation. Omitted uses the daemon default.
        speed:
          type: integer
          nullable: true
          minimum: 0
          maximum: 100
          description: >-
            Optional completion-speed preference carried with the initial
            activation. Omitted uses the daemon default.
        orchestrationIntensity:
          type: integer
          nullable: true
          minimum: 0
          maximum: 100
          deprecated: true
          description: >-
            Legacy single-axis alias of effect. Ignored when effect is present.
    TuttiModeActivationResponse:
      type: object
      additionalProperties: false
      required:
        - activation
      properties:
        activation:
          allOf:
            - $ref: "#/components/schemas/TuttiModeActivation"
          nullable: true
          description: Null until the session has its first Tutti mode activation revision.
    UpdateTuttiModeActivationRequest:
      type: object
      additionalProperties: false
      required:
        - status
        - source
      properties:
        status:
          $ref: "#/components/schemas/TuttiModeActivationStatus"
        source:
          $ref: "#/components/schemas/TuttiModeActivationSource"
        effect:
          type: integer
          nullable: true
          minimum: 0
          maximum: 100
          description: >-
            Optional outcome-quality preference persisted with the appended
            activation revision. Omitted keeps the current value, or the
            daemon default for the first revision.
        speed:
          type: integer
          nullable: true
          minimum: 0
          maximum: 100
          description: >-
            Optional completion-speed preference persisted with the appended
            activation revision. Omitted keeps the current value, or the
            daemon default for the first revision.
        orchestrationIntensity:
          type: integer
          nullable: true
          minimum: 0
          maximum: 100
          deprecated: true
          description: >-
            Legacy single-axis alias of effect. Ignored when effect is present.
        expectedRevision:
          type: integer
          format: int64
          nullable: true
          minimum: 0
          description: Optional optimistic-concurrency guard. Zero means no activation revision exists yet.
    UpdateTuttiModeActivationResponse:
      type: object
      additionalProperties: false
      required:
        - activation
        - changed
      properties:
        activation:
          allOf:
            - $ref: "#/components/schemas/TuttiModeActivation"
          nullable: true
        changed:
          type: boolean
          description: False for an idempotent update that did not create a new revision.
    WorkspaceAgentSessionKind:
      type: string
      description: >-
        Root sessions are user-visible conversations. Child sessions are
        provider-native agents reached through their immutable parent fields.
      enum:
        - root
        - child
    WorkspaceAgentMessageCursor:
      type: integer
      format: int64
      minimum: 0
      maximum: 9007199254740991
      description: >-
        Per-session durable message change cursor. The upper bound preserves
        exact integer representation in JavaScript clients.
    WorkspaceAgentSessionDetailProjection:
      type: string
      enum:
        - full
        - messageHydration
      description: >-
        Projection applied to a Session detail response. messageHydration
        preserves hierarchy and message cursors but leaves provider-backed
        lifecycle capabilities unresolved.
    WorkspaceAgentSessionLifecycleCapabilities:
      type: object
      additionalProperties: false
      required:
        - fork
        - forkThroughTurn
      properties:
        fork:
          type: boolean
          description: Whether this exact session can fork its latest settled state.
        forkThroughTurn:
          type: boolean
          description: Whether this exact session can fork through a provider-bound canonical Turn.
    WorkspaceAgentSessionForkThroughTurnPoint:
      type: object
      additionalProperties: false
      required:
        - type
        - turnId
      properties:
        type:
          type: string
          enum:
            - throughTurn
        turnId:
          type: string
          minLength: 1
          description: Exact canonical Turn id included as the final Turn in the fork.
    WorkspaceAgentSessionForkPoint:
      oneOf:
        - $ref: "#/components/schemas/WorkspaceAgentSessionForkThroughTurnPoint"
      discriminator:
        propertyName: type
        mapping:
          throughTurn: "#/components/schemas/WorkspaceAgentSessionForkThroughTurnPoint"
    WorkspaceAgentSessionForkLineage:
      type: object
      additionalProperties: false
      required:
        - sourceAgentSessionId
        - sourceTurnId
        - targetTurnId
        - operationId
        - forkedAtUnixMs
      properties:
        sourceAgentSessionId:
          type: string
          minLength: 1
        sourceTurnId:
          type: string
          minLength: 1
          description: Inclusive canonical Turn boundary in the source Session.
        targetTurnId:
          type: string
          minLength: 1
          description: Canonical Turn id of that inclusive boundary in the forked Session.
        operationId:
          type: string
          minLength: 1
        forkedAtUnixMs:
          type: integer
          format: int64
          minimum: 1
    WorkspaceAgentSessionForkOperationStatus:
      type: string
      enum:
        - accepted
        - committed
        - failed
        - unknown
      description: >-
        Public durable operation state. accepted collapses the internal
        prepared, dispatching, and provider-accepted phases.
    WorkspaceAgentSessionForkOperationPhase:
      type: string
      enum:
        - frozen
        - dispatching
        - materializing
        - committed
        - failed
        - deliveryUnknown
      description: Durable execution phase for progress and recovery diagnostics.
    WorkspaceAgentSessionForkOperation:
      type: object
      additionalProperties: false
      required:
        - operationId
        - requestId
        - sourceAgentSessionId
        - targetAgentSessionId
        - point
        - status
        - phase
        - session
        - lineage
        - error
      properties:
        operationId:
          type: string
          minLength: 1
        requestId:
          type: string
          minLength: 1
        sourceAgentSessionId:
          type: string
          minLength: 1
        targetAgentSessionId:
          type: string
          minLength: 1
        point:
          $ref: "#/components/schemas/WorkspaceAgentSessionForkPoint"
        status:
          $ref: "#/components/schemas/WorkspaceAgentSessionForkOperationStatus"
        phase:
          $ref: "#/components/schemas/WorkspaceAgentSessionForkOperationPhase"
        session:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentSession"
          nullable: true
          description: Complete target Session projection when status is committed.
        lineage:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentSessionForkLineage"
          nullable: true
          description: Durable lineage when status is committed.
        error:
          type: string
          nullable: true
          description: Durable failure diagnostic for failed or unknown outcomes.
    WorkspaceAgentSessionForkOperationResponse:
      type: object
      additionalProperties: false
      required:
        - operation
      properties:
        operation:
          $ref: "#/components/schemas/WorkspaceAgentSessionForkOperation"
    ForkWorkspaceAgentSessionRequest:
      type: object
      additionalProperties: false
      required:
        - targetAgentSessionId
        - requestId
        - point
      properties:
        targetAgentSessionId:
          type: string
          format: uuid
          description: Caller-stable identity reserved for the forked canonical session.
        requestId:
          type: string
          minLength: 1
          description: Caller-stable idempotency key for safe retries.
        point:
          $ref: "#/components/schemas/WorkspaceAgentSessionForkPoint"
    WorkspaceAgentSession:
      type: object
      additionalProperties: false
      required:
        - id
        - kind
        - rootAgentSessionId
        - rootTurnId
        - parentAgentSessionId
        - parentTurnId
        - parentToolCallId
        - agentTargetId
        - provider
        - providerSessionId
        - messageVersion
        - cwd
        - railSectionKey
        - visible
        - settings
        - permissionConfig
        - resumable
        - pinnedAtUnixMs
        - title
        - createdAtUnixMs
        - updatedAtUnixMs
        - endedAtUnixMs
        - latestTurnInteractions
        - activeTurnId
        - activeTurn
        - latestTurn
        - pendingInteractions
        - capabilities
        - lifecycleCapabilities
        - forkedFrom
        - usage
        - goal
        - goalSyncState
        - tuttiModeActivation
        - imported
      properties:
        id:
          type: string
          minLength: 1
        kind:
          $ref: "#/components/schemas/WorkspaceAgentSessionKind"
        rootAgentSessionId:
          type: string
          nullable: true
          minLength: 1
          description: >-
            Root session that owns this child session. Null when kind is root.
        rootTurnId:
          type: string
          nullable: true
          minLength: 1
          description: >-
            Root turn under which this child session was created. Null when
            kind is root.
        parentAgentSessionId:
          type: string
          nullable: true
          minLength: 1
          description: >-
            Direct parent session that created this child session. Null when
            kind is root.
        parentTurnId:
          type: string
          nullable: true
          minLength: 1
          description: >-
            Exact turn in the direct parent session that created this child
            session. Null when kind is root.
        parentToolCallId:
          type: string
          nullable: true
          minLength: 1
          description: >-
            Delegation tool call in the parent turn that created this child
            session. Null when kind is root.
        agentTargetId:
          type: string
          nullable: true
          description: Agent target that authorized this session launch. Historical or imported provider-only sessions may omit it.
        provider:
          $ref: "#/components/schemas/WorkspaceAgentProvider"
        providerSessionId:
          type: string
          nullable: true
        messageVersion:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentMessageCursor"
          description: >-
            Latest accepted per-session message change cursor. This is a
            high-water mark, not a count of materialized message rows.
        cwd:
          type: string
          nullable: true
        isolation:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentSessionIsolation"
          nullable: true
          description: Durable launch isolation metadata. Null for sessions launched in the selected checkout.
        railSectionKey:
          type: string
          minLength: 1
          description: >-
            Persisted conversation-rail membership key. Clients must use this
            exact key for section placement and must not infer membership from
            cwd or project paths.
        activeTurnId:
          type: string
          nullable: true
          description: >-
            Protocol v2. The only turn reference kept on the session; null
            when no turn is in flight.
        activeTurn:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentTurn"
          nullable: true
          description: >-
            Protocol v2. Embedded snapshot of the active turn; null when no
            turn is in flight.
        latestTurn:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentTurn"
          nullable: true
          description: >-
            Protocol v2. Read-only embedded projection of the most recently
            updated turn for this session, including settled turns. This is
            an independent turn entity projection and is not session-owned
            persistent state or a session reference.
        latestTurnInteractions:
          type: array
          description: >-
            Protocol v2. Read-only independent Interaction entity projections
            for latestTurn, including pending, answered, and superseded
            terminal states. These entities are not session-owned persistent
            state.
          items:
            $ref: "#/components/schemas/WorkspaceAgentInteraction"
        pendingInteractions:
          type: array
          description: >-
            Protocol v2. Pending interactions (approvals, questions, plan
            confirmations) for the active turn. Pending means present in this
            collection with status pending; there is no tri-state null
            protocol.
          items:
            $ref: "#/components/schemas/WorkspaceAgentInteraction"
        capabilities:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentCapabilities"
          nullable: true
          description: >-
            Protocol v2. Authoritative session capability snapshot. Null means
            no authoritative session snapshot is available, either because the
            runtime has not reported one yet or because legacy persisted data is
            ambiguous. A non-null object is complete, so false means explicitly
            unsupported. Only while this field is null may clients fall back to
            the authoritative provider composer descriptor; they must never
            infer capabilities from provider identity.
        lifecycleCapabilities:
          $ref: "#/components/schemas/WorkspaceAgentSessionLifecycleCapabilities"
          description: >-
            Exact-session lifecycle capabilities. Clients must use these flags
            for Session actions and must not infer support from provider identity.
        forkedFrom:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentSessionForkLineage"
          nullable: true
          description: >-
            Durable provenance for a user-initiated root Session fork. Null for
            ordinary root Sessions and provider-native child Sessions.
        usage:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentUsage"
          nullable: true
          description: >-
            Protocol v2. Typed context-window and quota usage projected from
            provider runtime state.
        goal:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentSessionGoal"
          nullable: true
          description: Protocol v2. Explicit field extracted from runtimeContext.
        goalSyncState:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentSessionGoalSyncState"
          nullable: true
          description: >-
            Narrow Host-owned evidence for the durable Goal operation. Null
            means no Goal state exists for this Session; clients must not infer
            pending execution from the visible Goal alone.
        tuttiModeActivation:
          allOf:
            - $ref: "#/components/schemas/TuttiModeActivation"
          nullable: true
          description: >-
            Independent, session-scoped Tutti mode activation projection. Null
            until the first activation revision exists; capability references
            are audit records and never determine this state.
        imported:
          type: boolean
          description: >-
            Protocol v2. True when the session was imported from external
            provider history. Explicit field extracted from runtimeContext.
        visible:
          type: boolean
        settings:
          $ref: "#/components/schemas/AgentSessionComposerSettings"
        permissionConfig:
          $ref: "#/components/schemas/PermissionConfig"
        resumable:
          type: boolean
        pinnedAtUnixMs:
          type: integer
          format: int64
          nullable: true
          minimum: 0
        title:
          type: string
          nullable: true
        createdAtUnixMs:
          type: integer
          format: int64
          minimum: 0
          description: Protocol v2. Unix milliseconds replacement for createdAt.
        updatedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
          description: Protocol v2. Unix milliseconds replacement for updatedAt.
        endedAtUnixMs:
          type: integer
          format: int64
          nullable: true
          minimum: 0
          description: Protocol v2. Unix milliseconds replacement for endedAt.
    WorkspaceAgentSessionResponse:
      type: object
      additionalProperties: false
      required:
        - session
      properties:
        session:
          $ref: "#/components/schemas/WorkspaceAgentSession"
    WorkspaceAgentSessionDetailResponse:
      type: object
      additionalProperties: false
      required:
        - session
        - childSessions
        - turns
        - projection
        - lifecycleCapabilitiesProjected
        - editRetry
      properties:
        projection:
          $ref: "#/components/schemas/WorkspaceAgentSessionDetailProjection"
        lifecycleCapabilitiesProjected:
          type: boolean
          description: >-
            Whether provider-backed lifecycle capability projection ran for
            session and childSessions. A full projection reports true even
            when a provider probe fails closed, because false then means the
            action is unavailable for this response. When false, projection
            was intentionally skipped and capability values must not be
            applied as authoritative.
        session:
          $ref: "#/components/schemas/WorkspaceAgentSession"
        editRetry:
          $ref: "#/components/schemas/WorkspaceAgentEditRetryAvailability"
        childSessions:
          type: array
          description: >-
            Flat collection of every nested child session below session.
            Clients reconstruct the tree from the immutable parent fields.
          items:
            $ref: "#/components/schemas/WorkspaceAgentSession"
        turns:
          type: array
          description: >-
            Ordered durable turns owned by session. This detail-only collection
            is the canonical source for turn-scoped history such as file changes;
            clients must not reconstruct it from provider tool payloads.
          items:
            $ref: "#/components/schemas/WorkspaceAgentTurn"
    WorkspaceAgentEditRetryAvailability:
      type: object
      additionalProperties: false
      required:
        - supported
        - eligible
        - historyRevision
        - recoveryState
        - availableActions
      properties:
        supported:
          type: boolean
        eligible:
          type: boolean
        turnId:
          type: string
          minLength: 1
        historyRevision:
          type: integer
          format: int64
          minimum: 0
        recoveryState:
          type: string
          enum:
            - prepared
            - rolling_back
            - resend_pending
            - recovery_required
            - completed
        operationId:
          type: string
          minLength: 1
        availableActions:
          type: array
          uniqueItems: true
          items:
            $ref: "#/components/schemas/WorkspaceAgentEditRetryRecoveryAction"
        reasonCode:
          $ref: "#/components/schemas/WorkspaceAgentEditRetryReasonCode"
    WorkspaceAgentEditRetryRecoveryAction:
      type: string
      enum:
        - reconcile
        - retry_replacement
      x-enum-varnames:
        - WorkspaceAgentEditRetryRecoveryActionReconcile
        - WorkspaceAgentEditRetryRecoveryActionRetryReplacement
    WorkspaceAgentEditRetryReasonCode:
      type: string
      enum:
        - provider_unsupported
        - turn_not_found
        - turn_not_latest
        - turn_not_settled
        - history_revision_conflict
        - operation_conflict
        - recovery_required
        - provider_outcome_unknown
        - replacement_not_proven_absent
    EditRetryWorkspaceAgentTurnRequest:
      type: object
      additionalProperties: false
      required:
        - editedText
        - clientOperationId
        - expectedHistoryRevision
      properties:
        editedText:
          type: string
          minLength: 1
        clientOperationId:
          type: string
          minLength: 1
        expectedHistoryRevision:
          type: integer
          format: int64
          minimum: 0
    RecoverWorkspaceAgentEditRetryRequest:
      type: object
      additionalProperties: false
      required:
        - action
      properties:
        action:
          $ref: "#/components/schemas/WorkspaceAgentEditRetryRecoveryAction"
    WorkspaceAgentEditRetryResponse:
      type: object
      additionalProperties: false
      required:
        - operationId
        - state
        - retractedTurnId
        - historyRevision
      properties:
        operationId:
          type: string
          minLength: 1
        state:
          type: string
          enum:
            - prepared
            - rolling_back
            - resend_pending
            - recovery_required
            - completed
        retractedTurnId:
          type: string
          minLength: 1
        replacementTurnId:
          type: string
          minLength: 1
        historyRevision:
          type: integer
          format: int64
          minimum: 0
        reasonCode:
          $ref: "#/components/schemas/WorkspaceAgentEditRetryReasonCode"
    SendWorkspaceAgentSessionInputResponse:
      oneOf:
        - $ref: "#/components/schemas/SendWorkspaceAgentSessionInputTurnResponse"
        - $ref: "#/components/schemas/SendWorkspaceAgentSessionInputGoalControlResponse"
      discriminator:
        propertyName: kind
        mapping:
          turn: "#/components/schemas/SendWorkspaceAgentSessionInputTurnResponse"
          goalControl: "#/components/schemas/SendWorkspaceAgentSessionInputGoalControlResponse"
    SendWorkspaceAgentSessionInputTurnResponse:
      type: object
      additionalProperties: false
      required:
        - session
        - kind
        - turnId
        - turn
      properties:
        session:
          $ref: "#/components/schemas/WorkspaceAgentSession"
        kind:
          type: string
          enum:
            - turn
          x-enum-varnames:
            - SendWorkspaceAgentSessionInputTurnResponseKindTurn
        turnId:
          type: string
          minLength: 1
        turn:
          $ref: "#/components/schemas/WorkspaceAgentTurn"
          description: >-
            Protocol v2. Durable snapshot of the exact turn accepted by this
            submission; optimistic client intents reconcile against its turnId.
    SendWorkspaceAgentSessionInputGoalControlResponse:
      type: object
      additionalProperties: false
      required:
        - session
        - goal
        - kind
      properties:
        session:
          $ref: "#/components/schemas/WorkspaceAgentSession"
        kind:
          type: string
          enum:
            - goalControl
          x-enum-varnames:
            - SendWorkspaceAgentSessionInputGoalControlResponseKindGoalControl
        operationId:
          type: string
          nullable: true
          description: Durable GoalControlOperation identity when kind is goalControl.
        goal:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentSessionGoal"
          nullable: true
        goalState:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentSessionGoalState"
          nullable: true
    WorkspaceAgentTurnPhase:
      type: string
      description: >-
        Protocol v2 closed turn phase vocabulary. submitted -> running ->
        waiting (interactions) -> settling -> settled.
      enum:
        - submitted
        - running
        - waiting
        - settling
        - settled
    WorkspaceAgentTurnOutcome:
      type: string
      description: >-
        Protocol v2 closed turn outcome vocabulary; only present once the
        turn is settled. interrupted marks turns reconciled at daemon
        startup after the provider process disappeared.
      enum:
        - completed
        - failed
        - canceled
        - interrupted
    WorkspaceAgentTurnError:
      type: object
      description: Protocol v2 turn-scoped error; never pollutes session state.
      additionalProperties: false
      required:
        - message
      properties:
        message:
          type: string
          minLength: 1
        code:
          type: string
        detail:
          type: string
          maxLength: 240
    WorkspaceAgentCapabilityReference:
      type: object
      description: >-
        A structured user-submission reference to a daemon-owned capability.
        This is provenance for UI and durable workflow linkage; it is not
        injected into provider prompt text and does not gate CLI availability.
      additionalProperties: false
      required:
        - capability
        - source
      properties:
        capability:
          type: string
          enum:
            - tutti
        source:
          type: string
          enum:
            - slash_command
          x-enum-varnames:
            - WorkspaceAgentCapabilityReferenceSourceSlashCommand
    WorkspaceAgentCompletedCommand:
      type: object
      description: >-
        Protocol v2 closed-enum replacement for AgentActivityCompletedCommand.
      additionalProperties: false
      required:
        - kind
        - status
      properties:
        kind:
          type: string
          enum:
            - compact
            - review
            - undo
            - goal
        status:
          type: string
          enum:
            - completed
            - failed
            - canceled
    WorkspaceAgentTurn:
      type: object
      description: >-
        Protocol v2 turn entity. One user-submission-driven execution:
        submit, run, wait, settle. Owns phase, outcome, error, and file
        changes; the session only keeps an activeTurnId reference.
      additionalProperties: false
      required:
        - turnId
        - agentSessionId
        - providerForkBindingAvailable
        - providerForkBindingState
        - phase
        - origin
        - outcome
        - error
        - fileChanges
        - completedCommand
        - startedAtUnixMs
        - settledAtUnixMs
        - updatedAtUnixMs
      properties:
        turnId:
          type: string
          minLength: 1
        agentSessionId:
          type: string
          minLength: 1
        providerForkBindingAvailable:
          type: boolean
          description: >-
            Whether this canonical Turn currently has a durably persisted
            provider Turn binding. This remains false while a settled
            historical Turn is waiting for an on-demand recovery attempt.
        providerForkBindingState:
          type: string
          description: >-
            Canonical provider binding state for Fork projection. bound means
            the durable provider Turn identity is ready; recovery_required
            means a settled historical Turn must complete the Host's
            fail-closed evidence recovery before Fork can be offered;
            unavailable means the Turn cannot be used as a Fork boundary.
          enum:
            - bound
            - recovery_required
            - unavailable
        phase:
          $ref: "#/components/schemas/WorkspaceAgentTurnPhase"
        origin:
          type: string
          description: Durable business provenance; steer is input on an existing turn and is never an origin.
          enum:
            - user_prompt
            - goal_arm
            - goal_continuation
            - provider_initiated
            - legacy_unknown
        sourceGoalOperationId:
          type: string
          nullable: true
          minLength: 1
        sourceGoalRevision:
          type: integer
          format: int64
          nullable: true
          minimum: 0
        sourceGoalRepairEpoch:
          type: integer
          format: int64
          nullable: true
          minimum: 0
        outcome:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentTurnOutcome"
          nullable: true
        error:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentTurnError"
          nullable: true
        fileChanges:
          type: object
          additionalProperties: true
          nullable: true
        completedCommand:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentCompletedCommand"
          nullable: true
        capabilityRefs:
          type: array
          uniqueItems: true
          items:
            $ref: "#/components/schemas/WorkspaceAgentCapabilityReference"
        startedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        settledAtUnixMs:
          type: integer
          format: int64
          nullable: true
          minimum: 0
        updatedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
    WorkspaceAgentInteractionKind:
      type: string
      enum:
        - approval
        - question
        - plan
    WorkspaceAgentInteractionStatus:
      type: string
      enum:
        - pending
        - answered
        - superseded
    WorkspaceAgentInteraction:
      type: object
      description: >-
        Protocol v2 interaction entity. An agent-initiated approval,
        question, or plan confirmation raised during a turn. Pending means
        present in a collection with status pending; replaces the tri-state
        null pendingInteractive protocol.
      additionalProperties: false
      required:
        - requestId
        - agentSessionId
        - turnId
        - kind
        - status
        - toolName
        - input
        - output
        - metadata
        - createdAtUnixMs
        - updatedAtUnixMs
      properties:
        requestId:
          type: string
          minLength: 1
        agentSessionId:
          type: string
          minLength: 1
        turnId:
          type: string
          minLength: 1
        kind:
          $ref: "#/components/schemas/WorkspaceAgentInteractionKind"
        status:
          $ref: "#/components/schemas/WorkspaceAgentInteractionStatus"
        toolName:
          type: string
          nullable: true
        input:
          type: object
          additionalProperties: true
          nullable: true
        output:
          type: object
          additionalProperties: true
          nullable: true
        metadata:
          type: object
          additionalProperties: true
          nullable: true
        createdAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        updatedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
    WorkspaceAgentCapabilities:
      type: object
      description: >-
        Protocol v2 daemon-issued capability descriptor. Clients branch on
        these booleans instead of provider identity. Field names mirror the
        canonical capability vocabulary owned by
        packages/agent/store-sqlite/canonical/provider.go.
      additionalProperties: false
      required:
        - imageInput
        - modelImageInputRequired
        - modelSwitch
        - modelPlanBinding
        - skills
        - compact
        - tokenUsage
        - rateLimits
        - planMode
        - interrupt
        - activeTurnGuidance
        - browserUse
        - computerUse
        - goalPause
        - planImplementation
        - permissionModeChangeDuringTurn
        - permissionModeChangeDeferred
        - review
        - resumeRunningTurn
      properties:
        imageInput:
          type: boolean
        modelImageInputRequired:
          type: boolean
        modelSwitch:
          type: boolean
          description: >-
            The provider can apply a model change to the next call in the
            current session.
        modelPlanBinding:
          type: boolean
          description: >-
            The provider runtime accepts a session-scoped model access plan
            endpoint and credential.
        skills:
          type: boolean
        compact:
          type: boolean
        tokenUsage:
          type: boolean
        rateLimits:
          type: boolean
        planMode:
          type: boolean
        interrupt:
          type: boolean
        activeTurnGuidance:
          type: boolean
          description: >-
            The provider can accept a user prompt as guidance for the currently
            running turn without canceling it or creating a normal next turn.
        browserUse:
          type: boolean
        computerUse:
          type: boolean
        goalPause:
          type: boolean
        planImplementation:
          type: boolean
        permissionModeChangeDuringTurn:
          type: boolean
        permissionModeChangeDeferred:
          type: boolean
        review:
          type: boolean
        resumeRunningTurn:
          type: boolean
    WorkspaceAgentUsageContextWindow:
      type: object
      additionalProperties: false
      required:
        - usedTokens
        - totalTokens
      properties:
        usedTokens:
          type: integer
          format: int64
          minimum: 0
        totalTokens:
          type: integer
          format: int64
          minimum: 1
    WorkspaceAgentUsageQuota:
      type: object
      additionalProperties: false
      required:
        - quotaType
        - percentRemaining
        - resetsAtUnixMs
      properties:
        quotaType:
          type: string
          minLength: 1
        percentRemaining:
          type: number
          format: double
          minimum: 0
          maximum: 100
        resetsAtUnixMs:
          type: integer
          format: int64
          nullable: true
          minimum: 0
    WorkspaceAgentUsage:
      type: object
      additionalProperties: false
      required:
        - contextWindow
        - quotas
      properties:
        contextWindow:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentUsageContextWindow"
          nullable: true
        quotas:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceAgentUsageQuota"
    WorkspaceAgentSessionGoal:
      type: object
      description: Protocol v2 explicit field extracted from runtimeContext.
      additionalProperties: false
      required:
        - objective
        - status
      properties:
        objective:
          type: string
        status:
          type: string
          enum:
            - active
            - paused
            - blocked
            - usageLimited
            - budgetLimited
            - complete
        reason:
          type: string
        startedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        iterations:
          type: integer
          minimum: 0
        durationMs:
          type: integer
          format: int64
          minimum: 0
        tokens:
          type: integer
          format: int64
          minimum: 0
    WorkspaceAgentTurnCancelResult:
      type: object
      additionalProperties: false
      required:
        - canceled
        - reason
      properties:
        canceled:
          type: boolean
        reason:
          type: string
          description: >-
            turn_canceled reports an active turn was stopped. cancel_requested
            reports accepted cancellation whose exact provider delivery still
            needs canonical reconciliation. already_settled and not_found are
            idempotent no-op successes, not errors.
          enum:
            - turn_canceled
            - cancel_requested
            - already_settled
            - not_found
    WorkspaceAgentTurnCancelResponse:
      type: object
      additionalProperties: false
      required:
        - cancel
      properties:
        cancel:
          $ref: "#/components/schemas/WorkspaceAgentTurnCancelResult"
        turn:
          $ref: "#/components/schemas/WorkspaceAgentTurn"
          nullable: true
    AgentActivityMessageSemantics:
      type: object
      additionalProperties: false
      properties:
        userVisibleAssistantResponse:
          type: boolean
        turnSettling:
          type: boolean
        noticeCommand:
          type: string
        noticeCommandStatus:
          type: string
    WorkspaceAgentSessionMessage:
      type: object
      additionalProperties: false
      required:
        - agentSessionId
        - messageId
        - sequence
        - turnId
        - role
        - kind
        - occurredAtUnixMs
        - version
      properties:
        agentSessionId:
          type: string
          minLength: 1
        messageId:
          type: string
          minLength: 1
        sequence:
          type: integer
          format: int64
          minimum: 1
          maximum: 9007199254740991
          description: >-
            Stable message presentation order assigned when the durable message
            row is first created. Updating the same message does not change this
            value; version remains the mutable snapshot change cursor.
        turnId:
          type: string
          nullable: true
          description: >-
            A non-empty turnId attaches a Turn-scoped message to a real
            persisted Turn. Null is valid only when kind is session_audit;
            empty strings are forbidden. Legacy stored turnless rows are read
            as compatibility data and are never assigned a guessed Turn.
        role:
          type: string
          minLength: 1
        kind:
          type: string
          minLength: 1
          description: >-
            session_audit is the only session-scoped kind; every other kind is
            Turn-scoped and requires a non-null turnId.
        status:
          type: string
        semantics:
          $ref: "#/components/schemas/AgentActivityMessageSemantics"
        payload:
          type: object
          additionalProperties: true
        occurredAtUnixMs:
          type: integer
          format: int64
          minimum: 1
        startedAtUnixMs:
          type: integer
          format: int64
        completedAtUnixMs:
          type: integer
          format: int64
        createdAtUnixMs:
          type: integer
          format: int64
        updatedAtUnixMs:
          type: integer
          format: int64
        version:
          $ref: "#/components/schemas/WorkspaceAgentMessageCursor"
    WorkspaceAgentSessionMessagesResponse:
      type: object
      additionalProperties: false
      required:
        - agentSessionId
        - messages
        - latestVersion
        - hasMore
      properties:
        agentSessionId:
          type: string
          minLength: 1
        messages:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceAgentSessionMessage"
        latestVersion:
          $ref: "#/components/schemas/WorkspaceAgentMessageCursor"
        hasMore:
          type: boolean
    WorkspaceAgentGeneratedFileEntry:
      type: object
      additionalProperties: false
      required:
        - path
        - label
      properties:
        path:
          type: string
          minLength: 1
        label:
          type: string
          minLength: 1
    WorkspaceAgentGeneratedFileListResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - entries
        - hasMore
      properties:
        workspaceId:
          type: string
          minLength: 1
        entries:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceAgentGeneratedFileEntry"
        hasMore:
          type: boolean
        nextCursor:
          type: string
          minLength: 1
    WorkspaceAgentSessionListResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - sessions
        - hasMore
      properties:
        workspaceId:
          type: string
          minLength: 1
        sessions:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceAgentSession"
        hasMore:
          type: boolean
        nextCursor:
          type: string
          minLength: 1
          description: Cursor for the next older matching session page, encoded as conversationSortTimeUnixMs|agentSessionId.
    WorkspaceAgentSessionPage:
      type: object
      additionalProperties: false
      required:
        - sessions
        - hasMore
        - totalCount
      properties:
        sessions:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceAgentSession"
        hasMore:
          type: boolean
        totalCount:
          type: integer
          minimum: 0
          description: Total visible sessions in this page scope before cursor pagination.
        nextCursor:
          type: string
          description: Cursor for the next older page, encoded as pinnedAtUnixMs|agentSessionId for pinned pages.
          minLength: 1
    WorkspaceAgentSessionSectionKind:
      type: string
      enum:
        - conversations
        - project
    WorkspaceAgentSessionSection:
      type: object
      additionalProperties: false
      required:
        - kind
        - sectionKey
        - sessions
        - hasMore
        - totalCount
      properties:
        kind:
          $ref: "#/components/schemas/WorkspaceAgentSessionSectionKind"
        sectionKey:
          type: string
          minLength: 1
        userProject:
          $ref: "#/components/schemas/UserProject"
        sessions:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceAgentSession"
        hasMore:
          type: boolean
        totalCount:
          type: integer
          minimum: 0
          description: Total visible sessions in this section before cursor pagination.
        nextCursor:
          type: string
          description: Cursor for the next older page, encoded as conversationSortTimeUnixMs|agentSessionId.
          minLength: 1
    WorkspaceAgentSessionSectionsResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - pinned
        - sections
      properties:
        workspaceId:
          type: string
          minLength: 1
        pinned:
          $ref: "#/components/schemas/WorkspaceAgentSessionPage"
        sections:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceAgentSessionSection"
    WorkspaceAgentSessionSectionPageResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - section
      properties:
        workspaceId:
          type: string
          minLength: 1
        section:
          $ref: "#/components/schemas/WorkspaceAgentSessionSection"
    WorkspaceAgentSessionPageResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - page
      properties:
        workspaceId:
          type: string
          minLength: 1
        page:
          $ref: "#/components/schemas/WorkspaceAgentSessionPage"
    ExternalAgentImportArchiveKind:
      type: string
      description: >-
        Selects which provider data-export archive format to parse. Omit for
        backward compatibility with clients that only send archivePath; the
        daemon then defaults to the Claude data-export format.
      enum:
        - claude
        - chatgpt
    ExternalAgentImportScanRequest:
      type: object
      additionalProperties: false
      properties:
        archivePath:
          type: string
          minLength: 1
          description: >-
            Absolute path to a supported provider data-export ZIP archive.
            When supplied, scan the archive instead of local CLI history.
        archiveKind:
          $ref: "#/components/schemas/ExternalAgentImportArchiveKind"
        providers:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceAgentProvider"
        days:
          type: integer
          description: >-
            Limit the scan to conversations updated within the last N days.
            Omit or 0 for the default 30-day window; a negative value scans all
            available history.
    ExternalAgentImportProvider:
      type: object
      additionalProperties: false
      required:
        - provider
        - root
        - available
        - sessionCount
        - messageCount
      properties:
        provider:
          $ref: "#/components/schemas/WorkspaceAgentProvider"
        root:
          type: string
        available:
          type: boolean
        sessionCount:
          type: integer
          minimum: 0
        messageCount:
          type: integer
          minimum: 0
        error:
          type: string
          nullable: true
    ExternalAgentImportProject:
      type: object
      additionalProperties: false
      required:
        - path
        - label
        - providers
        - sessionCount
        - messageCount
      properties:
        path:
          type: string
          minLength: 1
        label:
          type: string
          minLength: 1
        providers:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceAgentProvider"
        sessionCount:
          type: integer
          minimum: 0
        messageCount:
          type: integer
          minimum: 0
        lastUpdatedAtUnixMs:
          type: integer
          format: int64
          nullable: true
          minimum: 0
    ExternalAgentImportSession:
      type: object
      additionalProperties: false
      required:
        - id
        - projectPath
        - provider
        - title
        - messageCount
      properties:
        id:
          type: string
          minLength: 1
        projectPath:
          type: string
          minLength: 1
        provider:
          $ref: "#/components/schemas/WorkspaceAgentProvider"
        sourcePath:
          type: string
          minLength: 1
          nullable: true
        title:
          type: string
          minLength: 1
        messageCount:
          type: integer
          minimum: 0
        lastUpdatedAtUnixMs:
          type: integer
          format: int64
          nullable: true
          minimum: 0
    ExternalAgentImportError:
      type: object
      additionalProperties: false
      required:
        - message
      properties:
        provider:
          $ref: "#/components/schemas/WorkspaceAgentProvider"
        sourcePath:
          type: string
          nullable: true
        message:
          type: string
          minLength: 1
    ExternalAgentImportScanResponse:
      type: object
      additionalProperties: false
      required:
        - providers
        - projects
        - sessions
        - scannedSessions
        - scannedMessages
        - skippedSessions
        - errors
      properties:
        providers:
          type: array
          items:
            $ref: "#/components/schemas/ExternalAgentImportProvider"
        projects:
          type: array
          items:
            $ref: "#/components/schemas/ExternalAgentImportProject"
        sessions:
          type: array
          items:
            $ref: "#/components/schemas/ExternalAgentImportSession"
        scannedSessions:
          type: integer
          minimum: 0
        scannedMessages:
          type: integer
          minimum: 0
        skippedSessions:
          type: integer
          minimum: 0
        errors:
          type: array
          items:
            $ref: "#/components/schemas/ExternalAgentImportError"
    ExternalAgentImportProjectSelection:
      type: object
      additionalProperties: false
      required:
        - path
      properties:
        path:
          type: string
          minLength: 1
        providers:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceAgentProvider"
        sessionIds:
          type: array
          items:
            type: string
            minLength: 1
    ImportExternalAgentSessionsRequest:
      type: object
      additionalProperties: false
      required:
        - projects
      properties:
        archivePath:
          type: string
          minLength: 1
          description: >-
            Absolute path to the same provider data-export ZIP archive used
            for the preceding scan. The daemon revalidates and rereads the
            archive before importing the selected conversations.
        archiveKind:
          $ref: "#/components/schemas/ExternalAgentImportArchiveKind"
        projects:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/ExternalAgentImportProjectSelection"
        registerUserProjects:
          type: boolean
          default: true
        importSessions:
          type: boolean
          default: true
    ExternalAgentImportResultResponse:
      type: object
      additionalProperties: false
      required:
        - importedProjects
        - importedSessions
        - importedMessages
        - skippedSessions
        - errors
      properties:
        importedProjects:
          type: integer
          minimum: 0
        importedSessions:
          type: integer
          minimum: 0
        importedMessages:
          type: integer
          minimum: 0
        skippedSessions:
          type: integer
          minimum: 0
        errors:
          type: array
          items:
            $ref: "#/components/schemas/ExternalAgentImportError"
    ArchiveTuttiModeExecutionRequest:
      type: object
      additionalProperties: false
      required:
        - requestId
        - reason
      properties:
        requestId:
          type: string
          minLength: 1
        reason:
          type: string
          minLength: 1
    TuttiModeArchiveOperation:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - executionId
        - issueId
        - operationId
        - requestId
        - status
        - requestedBy
        - reason
        - attemptCount
        - lastError
        - createdAtUnixMs
        - updatedAtUnixMs
        - completedAtUnixMs
      properties:
        workspaceId:
          type: string
          minLength: 1
        executionId:
          type: string
          minLength: 1
        issueId:
          type: string
          minLength: 1
        operationId:
          type: string
          minLength: 1
        requestId:
          type: string
          minLength: 1
        status:
          type: string
          enum:
            - requested
            - canceling_runs
            - archiving
            - completed
            - failed
        requestedBy:
          type: string
          minLength: 1
        reason:
          type: string
          minLength: 1
        attemptCount:
          type: integer
          minimum: 0
        lastError:
          type: string
        createdAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        updatedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        completedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
    DeleteWorkspaceAgentSessionResponse:
      type: object
      additionalProperties: false
      required:
        - removed
        - cleanupFailed
      properties:
        removed:
          type: boolean
        cleanupFailed:
          type: boolean
    WorkspaceAgentSessionSectionDeletionCandidatesResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - sectionKey
        - excludePinned
        - sessionIds
      properties:
        workspaceId:
          type: string
          minLength: 1
        sectionKey:
          type: string
          minLength: 1
        agentTargetId:
          type: string
          minLength: 1
        excludePinned:
          type: boolean
        sessionIds:
          type: array
          uniqueItems: true
          items:
            type: string
            minLength: 1
    DeleteWorkspaceAgentSessionsBatchRequest:
      type: object
      additionalProperties: false
      required:
        - sessionIds
      properties:
        sessionIds:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            minLength: 1
    DeleteWorkspaceAgentSessionsBatchResponse:
      type: object
      additionalProperties: false
      required:
        - removedMessages
        - removedSessions
        - removedSessionIds
        - cleanupFailedSessionIds
      properties:
        removedMessages:
          type: integer
          minimum: 0
        removedSessions:
          type: integer
          minimum: 0
        removedSessionIds:
          type: array
          items:
            type: string
            minLength: 1
        cleanupFailedSessionIds:
          type: array
          items:
            type: string
            minLength: 1
    ClearWorkspaceAgentSessionsResponse:
      type: object
      additionalProperties: false
      required:
        - removedMessages
        - removedSessions
        - cleanupFailedSessionIds
      properties:
        removedMessages:
          type: integer
          minimum: 0
        removedSessions:
          type: integer
          minimum: 0
        cleanupFailedSessionIds:
          type: array
          items:
            type: string
            minLength: 1
    UpdateWorkspaceAgentSessionPinRequest:
      type: object
      additionalProperties: false
      required:
        - pinned
      properties:
        pinned:
          type: boolean
    UpdateWorkspaceAgentSessionTitleRequest:
      type: object
      additionalProperties: false
      required:
        - title
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 120
    UpdateWorkspaceAgentSessionVisibilityRequest:
      type: object
      additionalProperties: false
      required:
        - visible
      properties:
        visible:
          type: boolean
    WorkspaceAgentSessionGoalControlRequest:
      type: object
      additionalProperties: false
      required:
        - action
      properties:
        action:
          type: string
          enum:
            - pause
            - resume
            - clear
            - set
          x-enum-varnames:
            - WorkspaceAgentSessionGoalControlRequestActionPause
            - WorkspaceAgentSessionGoalControlRequestActionResume
            - WorkspaceAgentSessionGoalControlRequestActionClear
            - WorkspaceAgentSessionGoalControlRequestActionSet
        clientSubmitId:
          type: string
          minLength: 1
          description: Caller-stable idempotency identity for this Goal Control mutation.
        objective:
          type: string
    WorkspaceAgentSessionGoalControlResponse:
      type: object
      additionalProperties: false
      required:
        - session
        - goal
      properties:
        session:
          $ref: "#/components/schemas/WorkspaceAgentSession"
        goal:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentSessionGoal"
          nullable: true
        operationId:
          type: string
          nullable: true
          description: Durable GoalControlOperation identity; null only for compatibility runtimes without a goal store.
        state:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentSessionGoalState"
          nullable: true
    WorkspaceAgentSessionGoalSyncState:
      type: object
      additionalProperties: false
      required:
        - revision
        - syncStatus
        - pendingOperationId
        - executionPending
      properties:
        revision:
          type: integer
          format: int64
          minimum: 0
        syncStatus:
          type: string
          enum:
            - pending
            - applying
            - synced
            - diverged
            - unknown
            - failed
        pendingOperationId:
          type: string
          nullable: true
        executionPending:
          type: boolean
          description: >-
            Host-owned proof that an accepted initial Goal is expected to
            begin autonomous execution and has not produced its first exact
            Goal Turn yet.
    WorkspaceAgentSessionGoalState:
      type: object
      additionalProperties: false
      required:
        - revision
        - tombstoned
        - syncStatus
        - lastEvidence
        - updatedAtUnixMs
      properties:
        desired:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentSessionGoal"
          nullable: true
        observed:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentSessionGoal"
          nullable: true
        revision:
          type: integer
          format: int64
          minimum: 0
        tombstoned:
          type: boolean
        syncStatus:
          type: string
          enum:
            - pending
            - applying
            - synced
            - diverged
            - unknown
            - failed
        pendingOperationId:
          type: string
          nullable: true
        lastEvidence:
          type: object
          additionalProperties: true
        lastError:
          type: string
        observedAtUnixMs:
          type: integer
          format: int64
          nullable: true
        updatedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
    WorkspaceAgentSessionGoalStateResponse:
      type: object
      additionalProperties: false
      required:
        - session
        - state
      properties:
        session:
          $ref: "#/components/schemas/WorkspaceAgentSession"
        state:
          $ref: "#/components/schemas/WorkspaceAgentSessionGoalState"
    WorkspaceAgentInitialGoalControl:
      type: object
      additionalProperties: false
      required:
        - action
      properties:
        action:
          type: string
          enum:
            - pause
            - resume
            - clear
            - set
          x-enum-varnames:
            - WorkspaceAgentInitialGoalControlActionPause
            - WorkspaceAgentInitialGoalControlActionResume
            - WorkspaceAgentInitialGoalControlActionClear
            - WorkspaceAgentInitialGoalControlActionSet
        objective:
          type: string
          minLength: 1
    CreateWorkspaceAgentSessionRequest:
      type: object
      additionalProperties: false
      required:
        - agentSessionId
        - agentTargetId
        - initialContent
        - clientSubmitId
      properties:
        codexSaverMode:
          type: boolean
          nullable: true
          description: Enables the Codex-specific saver subagent mode for this Agent Session
        rtkSaverMode:
          type: boolean
          nullable: true
          description: Enables provider-neutral, session-scoped RTK executable and RTK.md injection for this Agent Session without changing the selected model
        agentSessionId:
          type: string
          format: uuid
          minLength: 1
        agentTargetId:
          type: string
          minLength: 1
          description: Required target-first session launch authority. The daemon derives provider and providerTargetRef from the stored agent target launchRef and rejects mismatched provider values.
        clientSubmitId:
          type: string
          minLength: 1
        recordingId:
          type: string
          format: uuid
          nullable: true
          description: Developer create-session scenario waiting for this root Session.
        submitDiagnostics:
          $ref: "#/components/schemas/AgentSubmitDiagnostics"
        initialContent:
          type: array
          items:
            $ref: "#/components/schemas/AgentPromptContentBlock"
        initialGoalControl:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentInitialGoalControl"
          nullable: true
          description: Optional typed Goal Control applied after the Session is created without opening an initial Turn. Must not be combined with non-empty initialContent.
        initialDisplayPrompt:
          type: string
          nullable: true
          description: Optional display-only text for the first turn (e.g. a folder bundle shown as one chip while initialContent carries the expanded files).
        title:
          type: string
          nullable: true
        cwd:
          type: string
          nullable: true
        isolation:
          allOf:
            - $ref: "#/components/schemas/WorkspaceAgentSessionIsolationMode"
          nullable: true
          description: Optional create-only isolation mode. Omit or set null to launch in the selected checkout.
        permissionModeId:
          type: string
          nullable: true
        model:
          type: string
          nullable: true
        modelExplicit:
          type: boolean
          nullable: true
          description: True only when model came from an explicit caller selection; false identifies an inherited or remembered fallback preference.
        reasoningEffort:
          type: string
          nullable: true
        reasoningEffortExplicit:
          type: boolean
          nullable: true
          description: True only when reasoning effort came from an explicit caller selection; false identifies a model-dependent inherited value.
        noProject:
          type: boolean
          nullable: true
          description: Classifies a session that is intentionally not attached to a workspace project.
        railPlacement:
          $ref: "#/components/schemas/WorkspaceAgentRailPlacement"
        speed:
          type: string
          nullable: true
        planMode:
          type: boolean
          nullable: true
        browserUse:
          type: boolean
          nullable: true
        capabilityRefs:
          type: array
          uniqueItems: true
          items:
            $ref: "#/components/schemas/WorkspaceAgentCapabilityReference"
          description: Structured capability references attached to the initial submission. They are persisted on the turn but never converted into provider prompt text.
        initialTuttiModeActivation:
          allOf:
            - $ref: "#/components/schemas/TuttiModeActivationIntent"
          nullable: true
          description: Optional independent Tutti mode activation intent applied before the first turn starts.
        visible:
          type: boolean
          nullable: true
    StartAgentSessionRecordingRequest:
      type: object
      additionalProperties: false
      required:
        - agentTargetId
        - replayPrerequisites
      properties:
        agentTargetId:
          type: string
          minLength: 1
        agentSessionId:
          type: string
          minLength: 1
          nullable: true
          description: Existing Session selecting continue-session mode. Omit for create-session mode.
        replayPrerequisites:
          $ref: "#/components/schemas/AgentSessionReplayPrerequisites"
    AgentSessionReplayComposerDefaults:
      type: object
      additionalProperties: false
      required:
        - model
        - permissionModeId
        - reasoningEffort
        - speed
      properties:
        model:
          type: string
          minLength: 1
        permissionModeId:
          type: string
          minLength: 1
        reasoningEffort:
          type: string
          minLength: 1
        speed:
          type: string
          minLength: 1
    AgentSessionReplayPrerequisites:
      type: object
      additionalProperties: false
      required:
        - composerDefaults
      properties:
        composerDefaults:
          $ref: "#/components/schemas/AgentSessionReplayComposerDefaults"
    RenameAgentSessionRecordingRequest:
      type: object
      additionalProperties: false
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
    AgentSessionRecordingActivityEventInput:
      type: object
      additionalProperties: false
      required:
        - eventId
        - kind
        - type
        - occurredAtUnixMs
      properties:
        eventId:
          type: string
          minLength: 1
        kind:
          type: string
          enum:
            - intent
            - effect
            - direct-stimulus
        type:
          type: string
          minLength: 1
        correlationId:
          type: string
          minLength: 1
          nullable: true
        causedByEventId:
          type: string
          minLength: 1
          nullable: true
        agentSessionId:
          type: string
          minLength: 1
          nullable: true
        payload:
          type: object
          additionalProperties: true
        occurredAtUnixMs:
          type: integer
          format: int64
          minimum: 0
    AppendAgentSessionRecordingActivityEventsRequest:
      type: object
      additionalProperties: false
      required:
        - events
      properties:
        events:
          type: array
          minItems: 1
          maxItems: 256
          items:
            $ref: "#/components/schemas/AgentSessionRecordingActivityEventInput"
    AppendAgentSessionRecordingActivityEventsResponse:
      type: object
      additionalProperties: false
      required:
        - acceptedThroughSequence
      properties:
        acceptedThroughSequence:
          type: integer
          format: int64
          minimum: 0
    AgentSessionRecording:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - workspaceId
        - agentTargetId
        - mode
        - status
        - directory
        - createdAtUnixMs
        - updatedAtUnixMs
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          minLength: 1
          maxLength: 120
          description: Mutable name stored in the portable Cassette manifest after completion.
        cassetteId:
          type: string
          format: uuid
          nullable: true
          description: Immutable Cassette produced by a completed Recording.
        workspaceId:
          type: string
          minLength: 1
        agentTargetId:
          type: string
          minLength: 1
        mode:
          type: string
          enum:
            - create-session
            - continue-session
        rootAgentSessionId:
          type: string
          minLength: 1
          nullable: true
        status:
          type: string
          enum:
            - preparing
            - ready
            - recording
            - finalizing
            - complete
            - failed
            - canceled
            - incomplete
        directory:
          type: string
          minLength: 1
        errorCode:
          type: string
          nullable: true
        errorMessage:
          type: string
          nullable: true
        createdAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        updatedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
    AgentSessionRecordingListResponse:
      type: object
      additionalProperties: false
      required:
        - recordings
      properties:
        recordings:
          type: array
          items:
            $ref: "#/components/schemas/AgentSessionRecording"
    ImportAgentSessionCassettesRequest:
      type: object
      additionalProperties: false
      required:
        - sourceDirectories
      properties:
        sourceDirectories:
          type: array
          minItems: 1
          maxItems: 100
          uniqueItems: true
          items:
            type: string
            minLength: 1
          description: Absolute local directories containing portable cassette.json manifests.
    ImportAgentSessionCassettesResponse:
      type: object
      additionalProperties: false
      required:
        - failures
        - recordings
      properties:
        failures:
          type: array
          items:
            $ref: "#/components/schemas/AgentSessionCassetteImportFailure"
        recordings:
          type: array
          items:
            $ref: "#/components/schemas/AgentSessionRecording"
    AgentSessionCassetteImportFailure:
      type: object
      additionalProperties: false
      required:
        - code
        - sourceDirectory
      properties:
        code:
          type: string
          enum:
            - conflict
            - invalid
            - failed
        sourceDirectory:
          type: string
          minLength: 1
    AgentSessionReplayCassetteLaunch:
      type: object
      additionalProperties: false
      required:
        - cassetteId
        - cassetteDirectory
        - rootAgentSessionId
      properties:
        cassetteId:
          type: string
          format: uuid
        cassetteDirectory:
          type: string
          minLength: 1
        rootAgentSessionId:
          type: string
          minLength: 1
    PrepareAgentSessionReplayWorkspaceRequest:
      type: object
      additionalProperties: false
      required:
        - cassetteIds
      properties:
        cassetteIds:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            format: uuid
    AgentSessionReplayWorkspaceLaunch:
      type: object
      additionalProperties: false
      required:
        - launches
      properties:
        launches:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/AgentSessionReplayCassetteLaunch"
    AgentSessionCassette:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - sourceRecordingId
        - agentTargetId
        - rootAgentSessionId
        - mode
        - totalBytes
        - createdAtUnixMs
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          minLength: 1
          maxLength: 120
        sourceRecordingId:
          type: string
          format: uuid
        agentTargetId:
          type: string
          minLength: 1
        rootAgentSessionId:
          type: string
          minLength: 1
        mode:
          type: string
          enum:
            - create-session
            - continue-session
        totalBytes:
          type: integer
          format: int64
          minimum: 0
        createdAtUnixMs:
          type: integer
          format: int64
          minimum: 0
    AgentSessionCassetteListResponse:
      type: object
      additionalProperties: false
      required:
        - cassettes
      properties:
        cassettes:
          type: array
          items:
            $ref: "#/components/schemas/AgentSessionCassette"
    AgentSessionReplayTransportPlayback:
      type: object
      additionalProperties: false
      required:
        - drained
        - paused
        - playbackElapsedMs
        - speed
        - timingMode
        - providerConnections
      properties:
        drained:
          type: boolean
        paused:
          type: boolean
        playbackElapsedMs:
          type: number
          format: double
          minimum: 0
        speed:
          type: number
          format: double
          enum:
            - 0.25
            - 0.5
            - 1
            - 2
            - 4
        timingMode:
          type: string
          enum:
            - realtime
            - fast-forward
        providerConnections:
          type: array
          items:
            $ref: "#/components/schemas/AgentSessionReplayProviderCursor"
    AgentSessionReplayProviderCursor:
      type: object
      additionalProperties: false
      required:
        - connectionId
        - chunkSeq
        - unitIndex
      properties:
        connectionId:
          type: string
          minLength: 1
        chunkSeq:
          type: integer
          format: int64
          minimum: 0
        unitIndex:
          type: integer
          format: int64
          minimum: 0
    AgentSessionReplayCheckpointVerification:
      type: object
      additionalProperties: false
      required:
        - checkpointIndex
        - triggerMatched
        - readinessSatisfied
        - canonicalSessionUpdatedAtUnixMs
        - canonicalMessageVersion
      properties:
        checkpointIndex:
          type: integer
          minimum: 0
        triggerMatched:
          type: boolean
        readinessSatisfied:
          type: boolean
        canonicalSessionUpdatedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        canonicalMessageVersion:
          type: integer
          format: int64
          minimum: 0
    UpdateAgentSessionReplayTransportPlaybackRequest:
      type: object
      additionalProperties: false
      required:
        - command
      properties:
        command:
          type: string
          enum:
            - set-speed
            - pause
            - resume
            - set-timing-mode
            - set-provider-cursor
            - clear-provider-cursor
          x-enum-varnames:
            - UpdateAgentSessionReplayTransportPlaybackRequestCommandSetSpeed
            - UpdateAgentSessionReplayTransportPlaybackRequestCommandPause
            - UpdateAgentSessionReplayTransportPlaybackRequestCommandResume
            - UpdateAgentSessionReplayTransportPlaybackRequestCommandSetTimingMode
            - UpdateAgentSessionReplayTransportPlaybackRequestCommandSetProviderCursor
            - UpdateAgentSessionReplayTransportPlaybackRequestCommandClearProviderCursor
        speed:
          type: number
          format: double
          enum:
            - 0.25
            - 0.5
            - 1
            - 2
            - 4
        timingMode:
          type: string
          enum:
            - realtime
            - fast-forward
        providerConnections:
          type: array
          items:
            $ref: "#/components/schemas/AgentSessionReplayProviderCursor"
    WorkspaceAgentRailPlacement:
      type: object
      additionalProperties: false
      required:
        - version
        - kind
        - sectionKey
      properties:
        version:
          type: integer
          enum:
            - 1
        kind:
          type: string
          enum:
            - conversations
            - project
        projectPath:
          type: string
          minLength: 1
        sectionKey:
          type: string
          minLength: 1
    WorkspaceAgentSideCapabilities:
      type: object
      additionalProperties: false
      required:
        - supported
        - activeSourceTurn
        - ephemeral
        - hideInheritedTurns
        - modelBoundaryInjected
      properties:
        supported:
          type: boolean
        activeSourceTurn:
          type: boolean
        ephemeral:
          type: boolean
        hideInheritedTurns:
          type: boolean
        modelBoundaryInjected:
          type: boolean
    WorkspaceAgentSideCapabilitiesResponse:
      type: object
      additionalProperties: false
      required:
        - capabilities
      properties:
        capabilities:
          $ref: "#/components/schemas/WorkspaceAgentSideCapabilities"
    OpenWorkspaceAgentSideConversationRequest:
      type: object
      additionalProperties: false
      required:
        - sideAgentSessionId
        - requestId
      properties:
        sideAgentSessionId:
          type: string
          minLength: 1
        requestId:
          type: string
          minLength: 1
    WorkspaceAgentSideConversation:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - sourceAgentSessionId
        - sideAgentSessionId
        - provider
        - status
        - capabilities
      properties:
        workspaceId:
          type: string
          minLength: 1
        sourceAgentSessionId:
          type: string
          minLength: 1
        sideAgentSessionId:
          type: string
          minLength: 1
        provider:
          type: string
          minLength: 1
        status:
          type: string
          minLength: 1
        capabilities:
          $ref: "#/components/schemas/WorkspaceAgentSideCapabilities"
    WorkspaceAgentSideConversationResponse:
      type: object
      additionalProperties: false
      required:
        - side
      properties:
        side:
          $ref: "#/components/schemas/WorkspaceAgentSideConversation"
    SendWorkspaceAgentSideConversationInputRequest:
      type: object
      additionalProperties: false
      required:
        - turnId
        - clientSubmitId
        - content
      properties:
        turnId:
          type: string
          minLength: 1
        clientSubmitId:
          type: string
          minLength: 1
        content:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/AgentPromptContentBlock"
        displayPrompt:
          type: string
          nullable: true
    WorkspaceAgentSideTurnResponse:
      type: object
      additionalProperties: false
      required:
        - sideAgentSessionId
        - turnId
        - accepted
        - status
      properties:
        sideAgentSessionId:
          type: string
          minLength: 1
        turnId:
          type: string
          minLength: 1
        accepted:
          type: boolean
        status:
          type: string
          minLength: 1
    WorkspaceAgentSideTurnCancelResponse:
      type: object
      additionalProperties: false
      required:
        - canceled
        - targetAbsent
      properties:
        canceled:
          type: boolean
        targetAbsent:
          type: boolean
    SubmitWorkspaceAgentSideConversationInteractiveRequest:
      type: object
      additionalProperties: false
      properties:
        action:
          type: string
        optionId:
          type: string
        payload:
          type: object
          additionalProperties: true
    WorkspaceAgentSideInteractiveResponse:
      type: object
      additionalProperties: false
      required:
        - disposition
      properties:
        disposition:
          type: string
          minLength: 1
    SendWorkspaceAgentSessionInputRequest:
      type: object
      additionalProperties: false
      required:
        - content
        - clientSubmitId
      properties:
        content:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/AgentPromptContentBlock"
        clientSubmitId:
          type: string
          minLength: 1
        submitDiagnostics:
          $ref: "#/components/schemas/AgentSubmitDiagnostics"
        displayPrompt:
          type: string
          nullable: true
          description: Optional display-only text shown in the conversation (e.g. a folder bundle rendered as one chip while content carries the expanded files).
        capabilityRefs:
          type: array
          uniqueItems: true
          items:
            $ref: "#/components/schemas/WorkspaceAgentCapabilityReference"
          description: Structured capability references attached to this submission. They are persisted on the turn but never converted into provider prompt text.
        guidance:
          type: boolean
          description: When true, send this input as guidance to the exact active turn identified by turnId instead of starting a new turn.
        turnId:
          type: string
          minLength: 1
          description: Exact canonical active Turn targeted by guidance. Required when guidance is true; ignored for normal new-turn submits.
    AgentSubmitDiagnostics:
      type: object
      additionalProperties: false
      properties:
        submittedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        blockCount:
          type: integer
          minimum: 0
        hasImage:
          type: boolean
        promptLength:
          type: integer
          minimum: 0
        queued:
          type: boolean
        source:
          type: string
        uiMode:
          type: string
          enum:
            - os
            - agent
    AgentPromptContentBlock:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - text
            - image
            - skill
            - mention
            - connector
        text:
          type: string
        mimeType:
          type: string
          enum:
            - image/png
            - image/jpeg
            - image/webp
        data:
          type: string
          description: Base64-encoded image bytes. Mutually exclusive with url.
        url:
          type: string
          format: uri
          pattern: '^https://[^@/?#\s]+([/?#]|$)'
          description: HTTPS image URL fetched directly by a capable provider. Mutually exclusive with data.
        attachmentId:
          type: string
        name:
          type: string
        path:
          type: string
        connectorKey:
          type: string
          minLength: 1
          pattern: "^[a-z][a-z0-9._-]{0,127}$"
          description: Stable key of an installed local connector selected for this prompt.
    WorkspaceAgentSessionAttachmentResponse:
      type: object
      additionalProperties: false
      required:
        - attachmentId
        - mimeType
        - data
      properties:
        attachmentId:
          type: string
          minLength: 1
        mimeType:
          type: string
          enum:
            - image/png
            - image/jpeg
            - image/webp
        name:
          type: string
        data:
          type: string
    WorkspaceAgentSessionGitBranchesResponse:
      type: object
      additionalProperties: false
      required:
        - branches
      properties:
        branches:
          type: array
          items:
            type: string
        currentBranch:
          type: string
    WorkspaceGitPatchTarget:
      type: string
      enum:
        - unstaged
        - staged
        - staged-and-unstaged
    WorkspaceGitPatchRequest:
      type: object
      additionalProperties: false
      required:
        - cwd
        - diff
      properties:
        cwd:
          type: string
          minLength: 1
        diff:
          type: string
          minLength: 1
        revert:
          type: boolean
        atomic:
          type: boolean
        target:
          $ref: "#/components/schemas/WorkspaceGitPatchTarget"
        allowBinary:
          type: boolean
    WorkspaceGitPatchStatus:
      type: string
      enum:
        - success
        - partial-success
        - error
    WorkspaceGitPatchErrorCode:
      type: string
      enum:
        - not-git-repo
        - invalid-patch
        - patch-does-not-apply
    WorkspaceGitPatchSupportResponse:
      type: object
      additionalProperties: false
      required:
        - supported
      properties:
        supported:
          type: boolean
        root:
          type: string
        errorCode:
          $ref: "#/components/schemas/WorkspaceGitPatchErrorCode"
    WorkspaceAgentSessionIsolationMode:
      type: string
      enum:
        - worktree
    WorkspaceAgentSessionIsolation:
      type: object
      additionalProperties: false
      required:
        - mode
        - worktreePath
        - branch
        - baseCommit
      properties:
        worktreeId:
          type: string
          minLength: 1
          description: Independent managed worktree resource identity. Legacy sessions may omit it.
        mode:
          $ref: "#/components/schemas/WorkspaceAgentSessionIsolationMode"
        worktreePath:
          type: string
          minLength: 1
        branch:
          type: string
          minLength: 1
        baseCommit:
          type: string
          minLength: 1
    WorkspaceAgentSessionWorktreeSupportErrorCode:
      type: string
      enum:
        - agent-target-unsupported
        - git-unavailable
        - not-git-repo
        - unsupported-repo-layout
    WorkspaceAgentSessionWorktreeSupportResponse:
      type: object
      additionalProperties: false
      required:
        - supported
      properties:
        supported:
          type: boolean
        root:
          type: string
        errorCode:
          $ref: "#/components/schemas/WorkspaceAgentSessionWorktreeSupportErrorCode"
    WorkspaceManagedWorktree:
      type: object
      additionalProperties: false
      required:
        - worktreeId
        - workspaceId
        - repoRoot
        - worktreePath
        - branch
        - baseCommit
      properties:
        worktreeId:
          type: string
          minLength: 1
        workspaceId:
          type: string
          minLength: 1
        repoRoot:
          type: string
          minLength: 1
        worktreePath:
          type: string
          minLength: 1
        branch:
          type: string
          minLength: 1
        baseCommit:
          type: string
          minLength: 1
        relativeCwd:
          type: string
    WorkspaceManagedWorktreeListResponse:
      type: object
      additionalProperties: false
      required:
        - worktrees
      properties:
        worktrees:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceManagedWorktree"
    DeleteWorkspaceManagedWorktreeResponse:
      type: object
      additionalProperties: false
      required:
        - deleted
      properties:
        deleted:
          type: boolean
    WorkspaceGitPatchExecOutput:
      type: object
      additionalProperties: false
      required:
        - command
        - stdout
        - stderr
      properties:
        command:
          type: string
        stdout:
          type: string
        stderr:
          type: string
    WorkspaceGitPatchResponse:
      type: object
      additionalProperties: false
      required:
        - status
        - appliedPaths
        - skippedPaths
        - conflictedPaths
      properties:
        status:
          $ref: "#/components/schemas/WorkspaceGitPatchStatus"
        appliedPaths:
          type: array
          items:
            type: string
        skippedPaths:
          type: array
          items:
            type: string
        conflictedPaths:
          type: array
          items:
            type: string
        errorCode:
          $ref: "#/components/schemas/WorkspaceGitPatchErrorCode"
        execOutput:
          $ref: "#/components/schemas/WorkspaceGitPatchExecOutput"
    AgentQuickPrompt:
      type: object
      additionalProperties: false
      required:
        - id
        - title
        - content
        - version
        - createdAtUnixMs
        - updatedAtUnixMs
      properties:
        id:
          type: string
          minLength: 1
        title:
          type: string
          minLength: 1
          maxLength: 80
        content:
          type: string
          minLength: 1
        version:
          type: integer
          format: int64
          minimum: 1
        createdAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        updatedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
    AgentQuickPromptListResponse:
      type: object
      additionalProperties: false
      required:
        - prompts
      properties:
        prompts:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/AgentQuickPrompt"
    AgentQuickPromptResponse:
      type: object
      additionalProperties: false
      required:
        - prompt
      properties:
        prompt:
          $ref: "#/components/schemas/AgentQuickPrompt"
    CreateAgentQuickPromptRequest:
      type: object
      additionalProperties: false
      required:
        - title
        - content
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 80
        content:
          type: string
          minLength: 1
    UpdateAgentQuickPromptRequest:
      type: object
      additionalProperties: false
      required:
        - title
        - content
        - expectedVersion
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 80
        content:
          type: string
          minLength: 1
        expectedVersion:
          type: integer
          format: int64
          minimum: 1
    DeleteAgentQuickPromptRequest:
      type: object
      additionalProperties: false
      required:
        - expectedVersion
      properties:
        expectedVersion:
          type: integer
          format: int64
          minimum: 1
    MoveAgentQuickPromptRequest:
      type: object
      additionalProperties: false
      required:
        - promptId
        - beforePromptId
        - expectedVersion
      properties:
        promptId:
          type: string
          minLength: 1
        beforePromptId:
          type: string
          nullable: true
          minLength: 1
        expectedVersion:
          type: integer
          format: int64
          minimum: 1
    UserProject:
      type: object
      additionalProperties: false
      required:
        - id
        - path
        - label
        - sectionKey
        - createdAtUnixMs
        - updatedAtUnixMs
        - lastUsedAtUnixMs
        - pinnedAtUnixMs
      properties:
        id:
          type: string
          minLength: 1
        path:
          type: string
          minLength: 1
        label:
          type: string
          minLength: 1
        sectionKey:
          type: string
          minLength: 1
        createdAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        updatedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        lastUsedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        pinnedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
    UserProjectListResponse:
      type: object
      additionalProperties: false
      required:
        - projects
      properties:
        projects:
          type: array
          items:
            $ref: "#/components/schemas/UserProject"
    UserProjectResponse:
      type: object
      additionalProperties: false
      required:
        - project
      properties:
        project:
          $ref: "#/components/schemas/UserProject"
    UseUserProjectRequest:
      type: object
      additionalProperties: false
      required:
        - path
      properties:
        path:
          type: string
          minLength: 1
    DeleteUserProjectRequest:
      type: object
      additionalProperties: false
      required:
        - path
      properties:
        path:
          type: string
          minLength: 1
    MoveUserProjectRequest:
      type: object
      additionalProperties: false
      required:
        - projectId
        - beforeProjectId
      properties:
        projectId:
          type: string
          minLength: 1
        beforeProjectId:
          type: string
          nullable: true
          minLength: 1
    PinUserProjectRequest:
      type: object
      additionalProperties: false
      required:
        - projectId
        - pinned
      properties:
        projectId:
          type: string
          minLength: 1
        pinned:
          type: boolean
    CheckUserProjectPathRequest:
      type: object
      additionalProperties: false
      required:
        - path
      properties:
        path:
          type: string
          minLength: 1
    UserProjectPathCheckResponse:
      type: object
      additionalProperties: false
      required:
        - exists
        - isDirectory
        - path
      properties:
        exists:
          type: boolean
        isDirectory:
          type: boolean
        path:
          type: string
          minLength: 1
    SubmitWorkspaceAgentInteractiveRequest:
      type: object
      additionalProperties: false
      required:
        - turnId
      properties:
        turnId:
          type: string
          minLength: 1
        action:
          type: string
          nullable: true
        optionId:
          type: string
          nullable: true
        payload:
          type: object
          nullable: true
          additionalProperties: true
    SubmitWorkspaceAgentPlanDecisionRequest:
      type: object
      additionalProperties: false
      required:
        - promptKind
        - action
        - idempotencyKey
      properties:
        promptKind:
          type: string
          enum:
            - plan-implementation
        action:
          type: string
          enum:
            - implement
        idempotencyKey:
          type: string
          minLength: 1
    WorkspaceAgentPlanDecisionOperation:
      type: object
      additionalProperties: false
      required:
        - operationId
        - workspaceId
        - agentSessionId
        - turnId
        - requestId
        - idempotencyKey
        - status
      properties:
        operationId:
          type: string
          minLength: 1
        workspaceId:
          type: string
          minLength: 1
        agentSessionId:
          type: string
          minLength: 1
        turnId:
          type: string
          minLength: 1
        requestId:
          type: string
          minLength: 1
        idempotencyKey:
          type: string
          minLength: 1
        status:
          type: string
          enum:
            - prepared
            - leased
            - completed
            - failed
        result:
          type: string
          nullable: true
        error:
          type: string
          nullable: true
    WorkspaceAgentPlanDecisionResponse:
      type: object
      additionalProperties: false
      required:
        - operation
      properties:
        operation:
          $ref: "#/components/schemas/WorkspaceAgentPlanDecisionOperation"
    WorkspaceAgentSessionEventEnvelope:
      type: object
      additionalProperties: false
      required:
        - seq
        - agentSessionId
        - type
        - occurredAt
        - payload
      properties:
        seq:
          type: integer
          format: int64
          minimum: 0
        agentSessionId:
          type: string
          minLength: 1
        agentTargetId:
          type: string
          nullable: true
        type:
          type: string
          minLength: 1
        occurredAt:
          type: string
          format: date-time
        payload:
          type: object
          additionalProperties: true
    WorkspaceFileEntryKind:
      type: string
      enum:
        - file
        - directory
        - unknown
    WorkspaceFileFilterKind:
      type: string
      enum:
        - file
        - directory
      x-enum-varnames:
        - WorkspaceFileFilterKindFile
        - WorkspaceFileFilterKindDirectory
    WorkspaceFileEntry:
      type: object
      additionalProperties: false
      required:
        - path
        - name
        - kind
        - hasChildren
        - sizeBytes
        - mtimeMs
        - createdTimeMs
        - lastOpenedMs
      properties:
        path:
          type: string
          minLength: 1
        name:
          type: string
        kind:
          $ref: "#/components/schemas/WorkspaceFileEntryKind"
        hasChildren:
          type: boolean
        sizeBytes:
          type: integer
          format: int64
          minimum: 0
          nullable: true
        mtimeMs:
          type: integer
          format: int64
          minimum: 0
          nullable: true
        createdTimeMs:
          type: integer
          format: int64
          minimum: 0
          nullable: true
        lastOpenedMs:
          type: integer
          format: int64
          minimum: 0
          nullable: true
    WorkspaceFileEntryResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - root
        - entry
      properties:
        workspaceId:
          type: string
        root:
          type: string
          minLength: 1
        entry:
          $ref: "#/components/schemas/WorkspaceFileEntry"
    WorkspaceFilePreviewResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - root
        - path
        - name
        - bytesBase64
        - sizeBytes
      properties:
        workspaceId:
          type: string
        root:
          type: string
          minLength: 1
        path:
          type: string
          minLength: 1
        name:
          type: string
        bytesBase64:
          type: string
        sizeBytes:
          type: integer
          format: int64
          minimum: 0
    WorkspaceFileDirectoryResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - root
        - directoryPath
        - entries
      properties:
        workspaceId:
          type: string
        root:
          type: string
          minLength: 1
        directoryPath:
          type: string
          minLength: 1
        entries:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceFileEntry"
    WorkspaceFileTreePrefetchState:
      type: string
      enum:
        - loaded
        - partial
        - not_loaded
        - unavailable
    WorkspaceFileTreePrefetchReason:
      type: string
      enum:
        - budget_exhausted
        - depth_limit_reached
        - unreadable
    WorkspaceFileTreeEntry:
      type: object
      additionalProperties: false
      required:
        - path
        - name
        - kind
        - hasChildren
        - sizeBytes
        - mtimeMs
        - createdTimeMs
        - lastOpenedMs
      properties:
        path:
          type: string
          minLength: 1
        name:
          type: string
        kind:
          $ref: "#/components/schemas/WorkspaceFileEntryKind"
        hasChildren:
          type: boolean
        sizeBytes:
          type: integer
          format: int64
          minimum: 0
          nullable: true
        mtimeMs:
          type: integer
          format: int64
          minimum: 0
          nullable: true
        createdTimeMs:
          type: integer
          format: int64
          minimum: 0
          nullable: true
        lastOpenedMs:
          type: integer
          format: int64
          minimum: 0
          nullable: true
        prefetchState:
          allOf:
            - $ref: "#/components/schemas/WorkspaceFileTreePrefetchState"
          nullable: true
        prefetchReason:
          allOf:
            - $ref: "#/components/schemas/WorkspaceFileTreePrefetchReason"
          nullable: true
        prefetchedDirectory:
          allOf:
            - $ref: "#/components/schemas/WorkspaceFileTreeDirectory"
          nullable: true
    WorkspaceFileTreeDirectory:
      type: object
      additionalProperties: false
      required:
        - directoryPath
        - entries
        - prefetchState
      properties:
        directoryPath:
          type: string
          minLength: 1
        entries:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceFileTreeEntry"
        prefetchState:
          $ref: "#/components/schemas/WorkspaceFileTreePrefetchState"
        prefetchReason:
          allOf:
            - $ref: "#/components/schemas/WorkspaceFileTreePrefetchReason"
          nullable: true
    WorkspaceFileTreeSnapshotResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - root
        - directory
        - prefetchBudgetMs
        - prefetchDepth
        - budgetExceeded
      properties:
        workspaceId:
          type: string
        root:
          type: string
          minLength: 1
        directory:
          $ref: "#/components/schemas/WorkspaceFileTreeDirectory"
        prefetchBudgetMs:
          type: integer
          format: int64
          minimum: 1
        prefetchDepth:
          type: integer
          minimum: 1
        budgetExceeded:
          type: boolean
    WorkspaceFileSearchEntry:
      type: object
      additionalProperties: false
      required:
        - path
        - name
        - kind
        - directoryPath
        - matchTarget
        - matchIndices
        - score
      properties:
        path:
          type: string
          minLength: 1
        name:
          type: string
        kind:
          $ref: "#/components/schemas/WorkspaceFileEntryKind"
        directoryPath:
          type: string
          minLength: 1
        matchTarget:
          $ref: "#/components/schemas/WorkspaceFileSearchMatchTarget"
        matchIndices:
          type: array
          items:
            type: integer
            minimum: 0
        score:
          type: integer
          minimum: 0
    WorkspaceFileSearchMatchTarget:
      type: string
      enum:
        - basename
        - path
      x-enum-varnames:
        - WorkspaceFileSearchMatchTargetBasename
        - WorkspaceFileSearchMatchTargetPath
    WorkspaceFileSearchResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - root
        - entries
      properties:
        workspaceId:
          type: string
        root:
          type: string
          minLength: 1
        entries:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceFileSearchEntry"
    CreateWorkspaceFileRequest:
      type: object
      additionalProperties: false
      required:
        - path
      properties:
        path:
          type: string
          minLength: 1
    WriteWorkspaceFileTextRequest:
      type: object
      additionalProperties: false
      required:
        - path
        - content
      properties:
        path:
          type: string
          minLength: 1
        content:
          type: string
    CreateWorkspaceFileDirectoryRequest:
      type: object
      additionalProperties: false
      required:
        - path
      properties:
        path:
          type: string
          minLength: 1
    DeleteWorkspaceFileEntryRequest:
      type: object
      additionalProperties: false
      required:
        - path
      properties:
        path:
          type: string
          minLength: 1
        kind:
          allOf:
            - $ref: "#/components/schemas/WorkspaceFileFilterKind"
          nullable: true
    DeleteWorkspaceFileEntryResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - path
      properties:
        workspaceId:
          type: string
        path:
          type: string
          minLength: 1
    MoveWorkspaceFileEntryRequest:
      type: object
      additionalProperties: false
      required:
        - path
        - targetDirectoryPath
      properties:
        path:
          type: string
          minLength: 1
        targetDirectoryPath:
          type: string
          minLength: 1
    RenameWorkspaceFileEntryRequest:
      type: object
      additionalProperties: false
      required:
        - path
        - newName
      properties:
        path:
          type: string
          minLength: 1
        newName:
          type: string
          minLength: 1
    CopyWorkspaceFileEntryRequest:
      type: object
      additionalProperties: false
      required:
        - path
      properties:
        path:
          type: string
          minLength: 1
    UploadWorkspaceFilesRequest:
      type: object
      additionalProperties: false
      required:
        - sourcePaths
        - targetDirectoryPath
      properties:
        sourcePaths:
          type: array
          minItems: 1
          items:
            type: string
            minLength: 1
        targetDirectoryPath:
          type: string
          minLength: 1
        overwrite:
          type: boolean
    PreflightUploadWorkspaceFilesRequest:
      type: object
      additionalProperties: false
      required:
        - sourcePaths
        - targetDirectoryPath
      properties:
        sourcePaths:
          type: array
          minItems: 1
          items:
            type: string
            minLength: 1
        targetDirectoryPath:
          type: string
          minLength: 1
    WorkspaceFileUploadConflict:
      type: object
      additionalProperties: false
      required:
        - kind
        - name
        - sourcePath
        - destinationPath
        - destinationKind
      properties:
        kind:
          $ref: "#/components/schemas/WorkspaceFileUploadConflictKind"
        name:
          type: string
          minLength: 1
        sourcePath:
          type: string
          minLength: 1
        destinationPath:
          type: string
          minLength: 1
        destinationKind:
          $ref: "#/components/schemas/WorkspaceFileEntryKind"
    WorkspaceFileUploadConflictKind:
      type: string
      enum:
        - replaceable
        - type_mismatch
    UploadWorkspaceFilesResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - root
        - targetDirectoryPath
        - entries
      properties:
        workspaceId:
          type: string
        root:
          type: string
          minLength: 1
        targetDirectoryPath:
          type: string
          minLength: 1
        entries:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceFileEntry"
    PreflightUploadWorkspaceFilesResponse:
      type: object
      additionalProperties: false
      required:
        - workspaceId
        - root
        - targetDirectoryPath
        - conflicts
      properties:
        workspaceId:
          type: string
        root:
          type: string
          minLength: 1
        targetDirectoryPath:
          type: string
          minLength: 1
        conflicts:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceFileUploadConflict"
    WorkbenchLayoutPreset:
      type: object
      additionalProperties: false
      required:
        - kind
      properties:
        kind:
          enum:
            - balanced
            - row
            - column
          type: string
    WorkbenchNormalizedFrame:
      type: object
      additionalProperties: false
      required:
        - x
        - y
        - width
        - height
      properties:
        x:
          type: number
          minimum: 0
          maximum: 1
        y:
          type: number
          minimum: 0
          maximum: 1
        width:
          type: number
          minimum: 0
          exclusiveMinimum: true
          maximum: 1
        height:
          type: number
          minimum: 0
          exclusiveMinimum: true
          maximum: 1
    WorkbenchLockedLayout:
      type: object
      additionalProperties: false
      required:
        - preset
        - nodeIDs
      properties:
        preset:
          $ref: "#/components/schemas/WorkbenchLayoutPreset"
        nodeIDs:
          type: array
          minItems: 2
          uniqueItems: true
          items:
            type: string
            minLength: 1
            maxLength: 160
        normalizedFrames:
          type: object
          propertyNames:
            type: string
            minLength: 1
            maxLength: 160
          additionalProperties:
            $ref: "#/components/schemas/WorkbenchNormalizedFrame"
    WorkbenchSize:
      type: object
      additionalProperties: false
      required:
        - width
        - height
      properties:
        width:
          type: number
          minimum: 0
          exclusiveMinimum: true
        height:
          type: number
          minimum: 0
          exclusiveMinimum: true
    WorkbenchSafeArea:
      type: object
      additionalProperties: false
      required:
        - top
        - right
        - bottom
        - left
      properties:
        top:
          type: number
          minimum: 0
        right:
          type: number
          minimum: 0
        bottom:
          type: number
          minimum: 0
        left:
          type: number
          minimum: 0
    WorkbenchLayoutConstraints:
      type: object
      additionalProperties: false
      required:
        - minWidth
        - minHeight
        - surfacePadding
        - safeArea
      properties:
        minWidth:
          type: number
          minimum: 0
        minHeight:
          type: number
          minimum: 0
        surfacePadding:
          type: number
          minimum: 0
        safeArea:
          $ref: "#/components/schemas/WorkbenchSafeArea"
    WorkbenchLayoutBasis:
      type: object
      additionalProperties: false
      required:
        - surfaceSize
        - layoutConstraints
      properties:
        surfaceSize:
          $ref: "#/components/schemas/WorkbenchSize"
        layoutConstraints:
          $ref: "#/components/schemas/WorkbenchLayoutConstraints"
    WorkbenchFrame:
      type: object
      additionalProperties: false
      required:
        - x
        - y
        - width
        - height
      properties:
        x:
          type: number
        y:
          type: number
        width:
          type: number
          minimum: 160
        height:
          type: number
          minimum: 120
    WorkbenchSnapshotNode:
      type: object
      additionalProperties: false
      required:
        - id
        - kind
        - title
        - frame
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 160
        kind:
          type: string
          minLength: 1
          maxLength: 120
        title:
          type: string
          maxLength: 240
        frame:
          $ref: "#/components/schemas/WorkbenchFrame"
        displayMode:
          enum:
            - floating
            - fullscreen
          type: string
        restoreFrame:
          allOf:
            - $ref: "#/components/schemas/WorkbenchFrame"
          nullable: true
        isMinimized:
          type: boolean
        minimizedAtUnixMs:
          type: integer
          nullable: true
          minimum: 0
        data:
          nullable: true
        adapterState:
          type: object
          additionalProperties: true
    WorkbenchSnapshotSpace:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - nodeIds
      properties:
        id:
          type: string
          minLength: 1
        name:
          type: string
        nodeIds:
          type: array
          items:
            type: string
            minLength: 1
        frame:
          allOf:
            - $ref: "#/components/schemas/WorkbenchFrame"
          nullable: true
        data:
          nullable: true
    WorkbenchSnapshot:
      type: object
      additionalProperties: false
      required:
        - schemaVersion
        - nodes
      properties:
        schemaVersion:
          type: integer
          enum:
            - 1
        nodes:
          type: array
          maxItems: 128
          items:
            $ref: "#/components/schemas/WorkbenchSnapshotNode"
        nodeStack:
          type: array
          items:
            type: string
            minLength: 1
        activeNodeId:
          type: string
          nullable: true
        spaces:
          type: array
          items:
            $ref: "#/components/schemas/WorkbenchSnapshotSpace"
        activeSpaceId:
          type: string
          nullable: true
        layoutBasis:
          $ref: "#/components/schemas/WorkbenchLayoutBasis"
        lockedLayout:
          $ref: "#/components/schemas/WorkbenchLockedLayout"
        metadata:
          type: object
          additionalProperties: true
    WorkspaceWorkbenchResponse:
      type: object
      additionalProperties: false
      required:
        - snapshot
      properties:
        snapshot:
          $ref: "#/components/schemas/WorkbenchSnapshot"
    PutWorkspaceWorkbenchRequest:
      type: object
      additionalProperties: false
      required:
        - snapshot
      properties:
        snapshot:
          $ref: "#/components/schemas/WorkbenchSnapshot"
    WorkspaceWorkflowStatus:
      type: string
      enum:
        - pending_review
        - in_progress
        - accepted
        - rejected
        - completed
        - failed
        - canceled
      x-enum-varnames:
        - WorkspaceWorkflowStatusPendingReview
        - WorkspaceWorkflowStatusInProgress
        - WorkspaceWorkflowStatusAccepted
        - WorkspaceWorkflowStatusRejected
        - WorkspaceWorkflowStatusCompleted
        - WorkspaceWorkflowStatusFailed
        - WorkspaceWorkflowStatusCanceled
    WorkspaceWorkflow:
      type: object
      additionalProperties: false
      required:
        - id
        - workspaceId
        - type
        - owner
        - triggerKind
        - sourceSessionId
        - sourceTurnId
        - sourceToolCallId
        - status
        - currentRevisionId
        - createdAtUnixMs
        - updatedAtUnixMs
      properties:
        id:
          type: string
          format: uuid
        workspaceId:
          type: string
          minLength: 1
        type:
          type: string
          enum:
            - tutti_mode_plan
        owner:
          type: string
          enum:
            - tutti
        triggerKind:
          type: string
          enum:
            - agent_cli
        sourceSessionId:
          type: string
          minLength: 1
        sourceTurnId:
          type: string
          nullable: true
        sourceToolCallId:
          type: string
          nullable: true
        status:
          $ref: "#/components/schemas/WorkspaceWorkflowStatus"
        currentRevisionId:
          type: string
          format: uuid
        createdAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        updatedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
    TuttiModePlanExecution:
      type: object
      additionalProperties: false
      required:
        - mode
        - reasoningIntensity
        - orchestrationIntensity
      properties:
        mode:
          type: string
          enum:
            - sequential
            - parallel
        reasoningIntensity:
          type: integer
          minimum: 0
          maximum: 100
        orchestrationIntensity:
          type: integer
          minimum: 0
          maximum: 100
          description: >-
            Issue-owned decomposition, dependency, review, and retry strength.
            This legacy v1 field keeps its original meaning and is not the
            Tutti Mode speed preference.
        effect:
          type: integer
          nullable: true
          minimum: 0
          maximum: 100
          description: >-
            Optional Tutti Mode outcome-quality preference snapshot. Omitted
            documents use orchestrationIntensity as the legacy single-axis
            effect and use the balanced default for speed.
        speed:
          type: integer
          nullable: true
          minimum: 0
          maximum: 100
          description: >-
            Optional Tutti Mode completion-speed preference snapshot. Omitted
            documents use the balanced default.
    TuttiModePlanBudget:
      type: object
      additionalProperties: false
      required:
        - mode
        - tokenLimit
        - quotaWaterlinePercent
      properties:
        mode:
          type: string
          enum:
            - auto
            - fixed
        tokenLimit:
          type: integer
          format: int64
          minimum: 0
        quotaWaterlinePercent:
          type: number
          format: double
          minimum: 0
          maximum: 100
    TuttiModePlanTask:
      type: object
      additionalProperties: false
      required:
        - id
        - title
        - content
        - priority
        - agentTargetId
        - modelPlanId
        - model
        - permissionModeId
        - reasoningEffort
        - executionDirectory
        - dependsOn
        - parallelizable
        - autoAccept
      properties:
        id:
          type: string
          minLength: 1
        title:
          type: string
          minLength: 1
        content:
          type: string
        priority:
          type: string
          enum:
            - high
            - medium
            - low
        agentTargetId:
          type: string
          nullable: true
        modelPlanId:
          type: string
          nullable: true
        model:
          type: string
          nullable: true
        permissionModeId:
          type: string
          nullable: true
          description: Task-level permission mode applied when the materialized Issue task launches.
        reasoningEffort:
          type: string
          nullable: true
          description: Task-level reasoning effort applied when the materialized Issue task launches.
        executionDirectory:
          type: string
          nullable: true
        dependsOn:
          type: array
          uniqueItems: true
          items:
            type: string
            minLength: 1
        parallelizable:
          type: boolean
          description: >-
            Opts this task out of the sequential default so it may run
            alongside other ready tasks. Persisted onto the materialized
            Issue task.
        autoAccept:
          type: boolean
          description: >-
            Bypasses the human acceptance gate: a successful completion is
            accepted automatically and dispatch advances. Persisted onto the
            materialized Issue task.
    TuttiModePlanDocument:
      type: object
      additionalProperties: false
      required:
        - schema
        - phase
        - title
        - topicId
        - markdownBody
        - execution
        - budget
        - tasks
      properties:
        schema:
          type: string
          enum:
            - tutti-mode-plan/v1
        phase:
          type: string
          enum:
            - configuration
            - task_graph
        title:
          type: string
          minLength: 1
        topicId:
          type: string
          minLength: 1
        markdownBody:
          type: string
          minLength: 1
        execution:
          $ref: "#/components/schemas/TuttiModePlanExecution"
        budget:
          $ref: "#/components/schemas/TuttiModePlanBudget"
        tasks:
          type: array
          items:
            $ref: "#/components/schemas/TuttiModePlanTask"
    WorkspaceWorkflowPlanRevision:
      type: object
      additionalProperties: false
      required:
        - id
        - workflowId
        - sequence
        - schemaVersion
        - documentPath
        - sha256
        - producedByTurnId
        - createdAtUnixMs
        - document
      properties:
        id:
          type: string
          format: uuid
        workflowId:
          type: string
          format: uuid
        sequence:
          type: integer
          minimum: 1
        schemaVersion:
          type: string
          enum:
            - tutti-mode-plan/v1
        documentPath:
          type: string
          minLength: 1
        sha256:
          type: string
          pattern: "^[0-9a-f]{64}$"
        producedByTurnId:
          type: string
          nullable: true
        createdAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        document:
          $ref: "#/components/schemas/TuttiModePlanDocument"
    WorkspaceWorkflowCheckpoint:
      type: object
      additionalProperties: false
      required:
        - id
        - workflowId
        - kind
        - revisionId
        - status
        - decidedBy
        - decisionReason
        - createdAtUnixMs
        - updatedAtUnixMs
        - decidedAtUnixMs
      properties:
        id:
          type: string
          format: uuid
        workflowId:
          type: string
          format: uuid
        kind:
          type: string
          enum:
            - configuration_review
            - task_review
        revisionId:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - pending
            - accepted
            - rejected
            - superseded
            - canceled
        decidedBy:
          type: string
          nullable: true
        decisionReason:
          type: string
          nullable: true
        createdAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        updatedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        decidedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
          nullable: true
    WorkspaceWorkflowTurnLink:
      type: object
      additionalProperties: false
      required:
        - workflowId
        - turnId
        - relation
        - createdAtUnixMs
      properties:
        workflowId:
          type: string
          format: uuid
        turnId:
          type: string
          minLength: 1
        relation:
          type: string
          enum:
            - source
            - decomposition
            - revision
            - feedback
        createdAtUnixMs:
          type: integer
          format: int64
          minimum: 0
    WorkspaceWorkflowOperation:
      type: object
      additionalProperties: false
      required:
        - id
        - workflowId
        - kind
        - status
        - revisionId
        - issueId
        - errorCode
        - errorMessage
        - createdAtUnixMs
        - updatedAtUnixMs
        - startedAtUnixMs
        - completedAtUnixMs
      properties:
        id:
          type: string
          format: uuid
        workflowId:
          type: string
          format: uuid
        kind:
          type: string
          enum:
            - generate_task_graph
            - create_revision
            - create_issue
            - start_issue
        status:
          type: string
          enum:
            - pending
            - running
            - succeeded
            - failed
            - canceled
        revisionId:
          type: string
          format: uuid
          nullable: true
        issueId:
          type: string
          nullable: true
        errorCode:
          type: string
          nullable: true
        errorMessage:
          type: string
          nullable: true
        createdAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        updatedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
        startedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
          nullable: true
        completedAtUnixMs:
          type: integer
          format: int64
          minimum: 0
          nullable: true
    WorkspaceWorkflowSnapshot:
      type: object
      additionalProperties: false
      required:
        - workflow
        - revisions
        - checkpoints
        - turnLinks
        - operations
        - actionableItems
      properties:
        workflow:
          $ref: "#/components/schemas/WorkspaceWorkflow"
        revisions:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceWorkflowPlanRevision"
        checkpoints:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceWorkflowCheckpoint"
        turnLinks:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceWorkflowTurnLink"
        operations:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceWorkflowOperation"
        actionableItems:
          type: array
          description: Read-only projection of the accepted current task graph; never an independent mutable record.
          items:
            $ref: "#/components/schemas/WorkspaceWorkflowActionableItem"
    WorkspaceWorkflowActionableItem:
      type: object
      additionalProperties: false
      required:
        - id
        - sourceWorkflowId
        - sourceRevisionId
        - ordinal
        - topicId
        - execution
        - budget
        - task
      properties:
        id:
          type: string
          minLength: 1
        sourceWorkflowId:
          type: string
          format: uuid
        sourceRevisionId:
          type: string
          format: uuid
        ordinal:
          type: integer
          minimum: 1
        topicId:
          type: string
          minLength: 1
        execution:
          $ref: "#/components/schemas/TuttiModePlanExecution"
        budget:
          $ref: "#/components/schemas/TuttiModePlanBudget"
        task:
          $ref: "#/components/schemas/TuttiModePlanTask"
    WorkspaceWorkflowListResponse:
      type: object
      additionalProperties: false
      required:
        - workflows
      properties:
        workflows:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceWorkflowSnapshot"
    WorkspaceWorkflowTaskAssignment:
      type: object
      additionalProperties: false
      description: >-
        User-owned per-task assignment override recorded with an accepted task
        review decision. Null fields keep the plan document value; empty
        strings clear it.
      required:
        - taskId
      properties:
        taskId:
          type: string
          minLength: 1
        agentTargetId:
          type: string
          nullable: true
        modelPlanId:
          type: string
          nullable: true
        model:
          type: string
          nullable: true
        permissionModeId:
          type: string
          nullable: true
        reasoningEffort:
          type: string
          nullable: true
        parallelizable:
          type: boolean
          nullable: true
          description: Overrides the plan document's per-task parallel opt-in; null keeps it.
        autoAccept:
          type: boolean
          nullable: true
          description: Overrides the plan document's per-task acceptance bypass; null keeps it.
    DecideWorkspaceWorkflowCheckpointRequest:
      type: object
      additionalProperties: false
      required:
        - decision
        - decidedBy
      properties:
        decision:
          type: string
          enum:
            - accepted
            - rejected
            - canceled
        decidedBy:
          type: string
          minLength: 1
        reason:
          type: string
          nullable: true
        taskAssignments:
          type: array
          nullable: true
          description: >-
            Optional per-task assignment overrides. Only valid when accepting
            a task review checkpoint; recorded durably with the decision and
            merged into the materialized Issue tasks.
          items:
            $ref: "#/components/schemas/WorkspaceWorkflowTaskAssignment"
    CreateWorkspaceRequest:
      type: object
      additionalProperties: false
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
    UpdateWorkspaceRequest:
      type: object
      additionalProperties: false
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1