openapi: 3.1.0
info:
  title: Kernel Images API
  version: 0.1.0
paths:
  /recording/start:
    post:
      summary: Start a screen recording. Only one recording per ID can be registered at a time.
      operationId: startRecording
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StartRecordingRequest"
      responses:
        "201":
          description: Recording started
        "400":
          $ref: "#/components/responses/BadRequestError"
        "409":
          description: A recording is already in progress
          $ref: "#/components/responses/ConflictError"
        "500":
          $ref: "#/components/responses/InternalError"
  /process/exec:
    post:
      summary: Execute a command synchronously
      operationId: processExec
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProcessExecRequest"
      responses:
        "200":
          description: Execution result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessExecResult"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalError"
  /process/spawn:
    post:
      summary: Execute a command asynchronously
      operationId: processSpawn
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProcessSpawnRequest"
      responses:
        "200":
          description: Spawned
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessSpawnResult"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalError"
  /process/{process_id}/status:
    get:
      summary: Get process status
      operationId: processStatus
      parameters:
        - name: process_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessStatus"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"
  /process/{process_id}/stdout/stream:
    get:
      summary: Stream process stdout over SSE
      operationId: processStdoutStream
      parameters:
        - name: process_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: SSE stream of process output and lifecycle events
          headers:
            X-SSE-Content-Type:
              description: Media type of SSE data events (application/json)
              schema:
                type: string
                const: application/json
          content:
            text/event-stream:
              schema:
                $ref: "#/components/schemas/ProcessStreamEvent"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"
  /process/{process_id}/stdin:
    post:
      summary: Write to process stdin
      operationId: processStdin
      parameters:
        - name: process_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProcessStdinRequest"
      responses:
        "200":
          description: Bytes written
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessStdinResult"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"
  /process/{process_id}/kill:
    post:
      summary: Send signal to process
      operationId: processKill
      parameters:
        - name: process_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProcessKillRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"
  /process/{process_id}/resize:
    post:
      summary: Resize a PTY-backed process
      operationId: processResize
      parameters:
        - name: process_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProcessResizeRequest"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"
  /recording/stop:
    post:
      summary: Stop the recording
      operationId: stopRecording
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StopRecordingRequest"
      responses:
        "200":
          description: Recording stopped
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalError"
  /recording/download:
    get:
      summary: Download the most recently recorded video file
      parameters:
        - name: id
          in: query
          description: Identifier of the recording session to download, as passed to /recording/start. When omitted, the default recording session is downloaded.
          schema:
            type: string
            pattern: "^[a-zA-Z0-9-]+$"
      operationId: downloadRecording
      responses:
        "200":
          description: Recording file
          headers:
            # Note: using a `format: date-time` here doesn't work as intended as the generated code
            # calls a `fmt.Sprint` on the value when setting the header. time.String is a
            # non-standard format that most parses will barf on, making everyone's life harder, so
            # we're skipping the `format` in favor of an explicit description.
            X-Recording-Started-At:
              description: Timestamp of when the recording started. Guaranteed to be RFC3339.
              schema:
                type: string
            X-Recording-Finished-At:
              description: Timestamp of when the recording finished. Guaranteed to be RFC3339.
              schema:
                type: string
          content:
            video/mp4:
              schema:
                type: string
                format: binary
        "202":
          description: Recording is still in progress, please try again later
          headers:
            Retry-After:
              description: Suggested wait time in seconds before retrying
              schema:
                type: integer
                minimum: 1
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"
  /recording/list:
    get:
      summary: List all recorders
      operationId: listRecorders
      responses:
        "200":
          description: List of recorders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/RecorderInfo"
        "500":
          $ref: "#/components/responses/InternalError"
  /recording/delete:
    post:
      summary: Delete a previously recorded video file
      operationId: deleteRecording
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeleteRecordingRequest"
      responses:
        "200":
          description: Recording deleted
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"
        "500":
          $ref: "#/components/responses/InternalError"
  /recording/mark:
    post:
      summary: Add a named marker to an in-progress recording
      description: >-
        Records a named point in time during an active recording. At finalize
        the markers are injected into the output MP4 as chapter markers.
      operationId: markRecording
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MarkRecordingRequest"
      responses:
        "201":
          description: Marker recorded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MarkRecordingResult"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          description: No recording session exists with the given identifier
          $ref: "#/components/responses/NotFoundError"
        "409":
          description: The recording session exists but is not actively recording
          $ref: "#/components/responses/ConflictError"
        "500":
          $ref: "#/components/responses/InternalError"
  /computer/click_mouse:
    post:
      summary: Simulate a mouse click action on the host computer
      operationId: clickMouse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ClickMouseRequest"
      responses:
        "200":
          description: Mouse action performed
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalError"
  /computer/move_mouse:
    post:
      summary: Move the mouse cursor to the specified coordinates on the host computer
      operationId: moveMouse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MoveMouseRequest"
      responses:
        "200":
          description: Mouse cursor moved
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalError"
  /computer/screenshot:
    post:
      summary: Capture a screenshot of the host computer
      operationId: takeScreenshot
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ScreenshotRequest"
      responses:
        "200":
          description: Screenshot image
          content:
            image/png:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalError"
  /computer/cursor:
    post:
      summary: Hide or show the cursor
      operationId: setCursor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetCursorRequest"
      responses:
        "200":
          description: Cursor visibility updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalError"
  /computer/get_mouse_position:
    post:
      summary: Get the current mouse cursor position on the host computer
      operationId: getMousePosition
      responses:
        "200":
          description: Current mouse position
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MousePositionResponse"
        "500":
          $ref: "#/components/responses/InternalError"
  /computer/type:
    post:
      summary: Type text on the host computer
      operationId: typeText
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TypeTextRequest"
      responses:
        "200":
          description: Text typed successfully
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalError"
  /computer/press_key:
    post:
      summary: Press one or more keys on the host computer
      description: |
        Presses the specified keys for an optional duration. Keys should be key symbols
        supported by xdotool. For a comprehensive list of key symbols, see
        the X11 keysym definitions at https://cgit.freedesktop.org/xorg/proto/x11proto/plain/keysymdef.h
        The server honors millisecond-level durations using fractional sleeps under the hood.
      operationId: pressKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PressKeyRequest"
      responses:
        "200":
          description: Keys pressed successfully
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalError"
  /computer/scroll:
    post:
      summary: Scroll the mouse wheel at a position on the host computer
      description: |
        Scroll vertically and/or horizontally at the given coordinates, optionally while holding modifier keys.
        The scroll amounts are in logical ticks (not pixels) and application behavior may vary; tuning may be required.
        When both horizontal and vertical deltas are provided, the server applies them sequentially (vertical then horizontal)
        and batches wheel events using `xdotool click --repeat N --delay 0 <button>`.
      operationId: scroll
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ScrollRequest"
      responses:
        "200":
          description: Scroll performed
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalError"
  /computer/drag_mouse:
    post:
      summary: Drag the mouse along a path
      description: |
        Press and hold a mouse button, optionally wait for a short delay, then move along the given path and release.
        The path is a list of [x, y] coordinate pairs.
      operationId: dragMouse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DragMouseRequest"
      responses:
        "200":
          description: Drag performed
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalError"
  /computer/batch:
    post:
      summary: Execute a batch of computer actions sequentially
      description: |
        Execute an ordered list of computer actions in a single API call. Actions are performed
        sequentially while holding an exclusive lock, so no other input operations can interleave.
        Execution stops on the first error and the response indicates which action failed.
        This is useful for chaining deterministic sequences of mouse and keyboard actions
        without paying network round-trip latency for each individual action.
      operationId: batchComputerAction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BatchComputerActionRequest"
      responses:
        "200":
          description: Batch executed successfully
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalError"
  /computer/clipboard/read:
    post:
      summary: Read text from the system clipboard
      operationId: readClipboard
      responses:
        "200":
          description: Clipboard content read successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClipboardContent"
        "500":
          $ref: "#/components/responses/InternalError"
  /computer/clipboard/write:
    post:
      summary: Write text to the system clipboard
      operationId: writeClipboard
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WriteClipboardRequest"
      responses:
        "200":
          description: Text written to clipboard successfully
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalError"
  /logs/stream:
    get:
      summary: Stream logs over SSE
      operationId: logsStream
      parameters:
        - in: query
          name: source
          required: true
          schema:
            type: string
            enum: [path, supervisor]
        - in: query
          name: follow
          required: false
          schema:
            type: boolean
            default: true
        - in: query
          description: only required if source is path
          name: path
          required: false
          schema:
            type: string
        - in: query
          name: supervisor_process
          description: only required if source is supervisor
          required: false
          schema:
            type: string
      responses:
        "200":
          description: SSE stream of logs
          headers:
            X-SSE-Content-Type:
              description: Media type of SSE data events (application/json)
              schema:
                type: string
                const: application/json
          content:
            text/event-stream:
              schema:
                $ref: "#/components/schemas/LogEvent"
  # File system operations
  /fs/read_file:
    get:
      summary: Read file contents
      operationId: readFile
      parameters:
        - name: path
          in: query
          required: true
          schema:
            type: string
            pattern: "^/.*"
          description: Absolute file path to read.
      responses:
        "200":
          description: File read successfully
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"

  /fs/download_dir_zip:
    get:
      summary: Download a directory as a ZIP archive
      description: Returns a ZIP file containing the contents of the specified directory.
      operationId: downloadDirZip
      parameters:
        - name: path
          in: query
          required: true
          schema:
            type: string
            pattern: "^/.*"
          description: Absolute directory path to archive and download.
      responses:
        "200":
          description: ZIP archive of the requested directory
          content:
            application/zip:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"

  /fs/write_file:
    put:
      summary: Write or create a file
      operationId: writeFile
      parameters:
        - name: path
          in: query
          required: true
          schema:
            type: string
            pattern: "^/.*"
          description: Destination absolute file path.
        - name: mode
          in: query
          required: false
          schema:
            type: string
            pattern: "^[0-7]{3,4}$"
          description: Optional file mode (octal string, e.g. 644). Defaults to 644.
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        "201":
          description: File written successfully
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"

  /fs/upload:
    post:
      summary: Upload one or more files
      description: Allows uploading single or multiple files to the remote filesystem.
      operationId: uploadFiles
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                files:
                  type: array
                  items:
                    type: object
                    properties:
                      file:
                        type: string
                        format: binary
                      dest_path:
                        type: string
                        description: Absolute destination path to write the file.
                        pattern: "^/.*"
                    required: [file, dest_path]
              required: [files]
      responses:
        "201":
          description: Files uploaded successfully
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"

  /fs/upload_zip:
    post:
      summary: Upload a zip archive and extract it
      description: Upload a zip file and extract its contents to the specified destination path.
      operationId: uploadZip
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                zip_file:
                  type: string
                  format: binary
                dest_path:
                  type: string
                  description: Absolute destination directory to extract the archive to.
                  pattern: "^/.*"
              required: [zip_file, dest_path]
      responses:
        "201":
          description: Zip uploaded and extracted successfully
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"

  /fs/download_dir_zstd:
    get:
      summary: Download a directory as a tar.zst archive
      description: |
        Returns a tar.zst (tar archive compressed with zstd) file containing the contents
        of the specified directory. Zstd offers significantly faster compression and
        decompression compared to zip while achieving better compression ratios.
      operationId: downloadDirZstd
      parameters:
        - name: path
          in: query
          required: true
          schema:
            type: string
            pattern: "^/.*"
          description: Absolute directory path to archive and download.
        - name: compression_level
          in: query
          required: false
          schema:
            type: string
            enum: [fastest, default, better, best]
            default: default
          description: |
            Compression level. Higher levels produce smaller archives but take longer.
            - fastest: ~zstd level 1, maximum speed (~300-500 MB/s)
            - default: ~zstd level 3, balanced speed/ratio (~150 MB/s)
            - better: ~zstd level 7, better ratio (~50-80 MB/s)
            - best: ~zstd level 11, best ratio (~20-40 MB/s)
      responses:
        "200":
          description: Tar.zst archive of the requested directory
          content:
            application/zstd:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"

  /fs/upload_zstd:
    post:
      summary: Upload a tar.zst archive and extract it
      description: |
        Upload a tar.zst (tar archive compressed with zstd) file and extract its contents
        to the specified destination path. Zstd offers significantly faster decompression
        compared to zip.
      operationId: uploadZstd
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                archive:
                  type: string
                  format: binary
                  description: The tar.zst archive file.
                dest_path:
                  type: string
                  description: Absolute destination directory to extract the archive to.
                  pattern: "^/.*"
                strip_components:
                  type: integer
                  minimum: 0
                  default: 0
                  description: Number of leading path components to strip during extraction (like tar --strip-components).
              required: [archive, dest_path]
      responses:
        "201":
          description: Archive uploaded and extracted successfully
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"

  /fs/list_files:
    get:
      summary: List files in a directory
      operationId: listFiles
      parameters:
        - name: path
          in: query
          required: true
          schema:
            type: string
            pattern: "^/.*"
          description: Absolute directory path.
      responses:
        "200":
          description: Directory listing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListFiles"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"

  /fs/create_directory:
    put:
      summary: Create a new directory
      operationId: createDirectory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateDirectoryRequest"
      responses:
        "201":
          description: Directory created successfully
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalError"

  /fs/delete_file:
    put:
      summary: Delete a file
      operationId: deleteFile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeletePathRequest"
      responses:
        "200":
          description: File deleted
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"

  /fs/delete_directory:
    put:
      summary: Delete a directory
      operationId: deleteDirectory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeletePathRequest"
      responses:
        "200":
          description: Directory deleted
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"

  /fs/set_file_permissions:
    put:
      summary: Set file or directory permissions/ownership
      operationId: setFilePermissions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetFilePermissionsRequest"
      responses:
        "200":
          description: Permissions updated
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"

  /fs/file_info:
    get:
      summary: Get information about a file or directory
      operationId: fileInfo
      parameters:
        - name: path
          in: query
          required: true
          schema:
            type: string
            pattern: "^/.*"
          description: Absolute path of the file or directory.
      responses:
        "200":
          description: File information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileInfo"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"

  /fs/move:
    put:
      summary: Move or rename a file or directory
      operationId: movePath
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MovePathRequest"
      responses:
        "200":
          description: Move successful
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"

  /fs/watch:
    post:
      summary: Watch a directory for changes
      operationId: startFsWatch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StartFsWatchRequest"
      responses:
        "201":
          description: Watch started successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  watch_id:
                    type: string
                    description: Unique identifier for the directory watch
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"

  /fs/watch/{watch_id}/events:
    get:
      summary: Stream filesystem events for a watch
      operationId: streamFsEvents
      parameters:
        - name: watch_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: SSE stream of filesystem events
          headers:
            X-SSE-Content-Type:
              description: Media type of SSE data events (application/json)
              schema:
                type: string
                const: application/json
          content:
            text/event-stream:
              schema:
                $ref: "#/components/schemas/FileSystemEvent"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"

  /fs/watch/{watch_id}:
    delete:
      summary: Stop watching a directory
      operationId: stopFsWatch
      parameters:
        - name: watch_id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Watch stopped successfully
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"
  /display:
    patch:
      summary: Update display configuration
      operationId: patchDisplay
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchDisplayRequest"
      responses:
        "200":
          description: Updated display configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DisplayConfig"
        "409":
          $ref: "#/components/responses/ConflictError"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalError"

  /chromium/upload-extensions-and-restart:
    post:
      summary: Upload one or more unpacked extensions (as zips) and restart Chromium
      description: |
        Upload one or more extension zip archives, extract them under /home/kernel/extensions/<name>,
        set runtime extension flags in /chromium/flags, restart Chromium via supervisord, and wait
        until the Chromium DevTools "listening" log line is observed before returning success.
      operationId: uploadExtensionsAndRestart
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                extensions:
                  type: array
                  description: List of extensions to upload and activate
                  items:
                    type: object
                    properties:
                      zip_file:
                        type: string
                        format: binary
                        description: Zip archive containing an unpacked Chromium extension (must include manifest.json)
                      name:
                        type: string
                        description: Folder name to place the extension under /home/kernel/extensions/<name>
                        pattern: "^[A-Za-z0-9._-]{1,255}$"
                    required: [zip_file, name]
              required: [extensions]
      responses:
        "201":
          description: Extensions uploaded, Chromium restarted, and DevTools is ready
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalError"

  /chromium/policies:
    patch:
      summary: Update Chromium enterprise policies and restart
      description: |
        Merge user-provided Chromium enterprise policy overrides into the base policy.json,
        restart Chromium via supervisord, and wait until the Chromium DevTools "listening"
        log line is observed before returning success.
        Certain policies managed by kernel infrastructure (e.g. ExtensionSettings,
        proxy-related policies, and policies required for CDP/automation) are blocked
        from override.
      operationId: patchChromiumPolicies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: |
                Chromium enterprise policy overrides. Keys are policy names
                (e.g. "DefaultCookiesSetting") and values are the policy values.
                See https://chromeenterprise.google/policies/ for available policies.
              additionalProperties: true
              example:
                DefaultCookiesSetting: 1
                BasicAuthOverHttpEnabled: true
                HttpsUpgradesEnabled: false
                MaxConnectionsPerProxy: 32
                PopupsAllowedForUrls:
                  - "https://example.com"
      responses:
        "200":
          description: Policies updated and Chromium restarted successfully
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalError"

  /chromium/flags:
    patch:
      summary: Update Chromium launch flags and restart
      description: |
        Merge new flags with existing ones, update /chromium/flags, restart Chromium via supervisord,
        and wait until the Chromium DevTools "listening" log line is observed before returning success.
      operationId: patchChromiumFlags
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                flags:
                  type: array
                  items:
                    type: string
                  description: Chromium flags to merge (e.g., ["--kiosk", "--disable-gpu"])
              required: [flags]
      responses:
        "200":
          description: Flags updated and Chromium restarted successfully
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalError"

  /configure:
    post:
      summary: Apply batched session and browser configuration plus optional navigation
      description: |
        Optional multipart parts apply configuration while Chromium stays stopped once (policy,
        flags, extensions, profile archive, optional display sizing), then Chromium is started exactly
        once and DevTools readiness is awaited. Optional `start_url` dispatches a best-effort
        navigation after readiness without waiting for page load. Bare hosts are normalized to
        `https://`. Omit any part you do not need. At least one actionable part must be present.
        Required configuration steps run in this order: policies, extensions, display, flags,
        then profile archive. Chromium is started only once at the end. The endpoint is not
        transactional: if a later required step fails, earlier successful side effects may remain
        on the instance while the non-2xx error propagates.
        Prefer this over separate `/chromium/*` and `/display` calls when multiple restart-triggering
        steps apply in one session configure.
      operationId: chromiumConfigure
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                display:
                  description: >-
                    UTF-8 JSON object matching `#/components/schemas/PatchDisplayRequest` (width/height/etc.).
                    When combined with restart-triggering fields, the resize is applied while Chromium
                    is stopped and Chromium is started once at the end.
                  type: string
                chromium_flags:
                  description: >-
                    UTF-8 JSON object `{"flags":["--kiosk"]}` — same semantics as PATCH /chromium/flags.
                  type: string
                chrome_policies:
                  description: UTF-8 JSON policy override map — same semantics as PATCH /chromium/policies.
                  type: string
                profile_archive:
                  description: >-
                    tar.zst archive containing the desired `/home/kernel/user-data` profile contents.
                    Prefer archives whose root entries are the profile files/directories themselves
                    (for example `Default/Preferences`). Use `strip_components` only when uploading
                    an archive that includes leading wrapper directories.
                  type: string
                  format: binary
                strip_components:
                  description: Optional number of leading path components to strip from profile_archive entries (non-negative integer as text).
                  type: string
                start_url:
                  description: >-
                    URL text to navigate after configure. Bare hosts are normalized to https://,
                    length is capped at 2048 bytes, and Chrome decides which schemes are navigable.
                  type: string
                extensions:
                  type: array
                  description: Extension zips paired with consecutive extensions.name fields (same as upload-extensions-and-restart).
                  items:
                    type: object
                    properties:
                      zip_file:
                        type: string
                        format: binary
                      name:
                        type: string
                        pattern: "^[A-Za-z0-9._-]{1,255}$"
                    required: [zip_file, name]
      responses:
        "200":
          description: Configuration applied; optional navigate completed successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OkResponse"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "409":
          $ref: "#/components/responses/ConflictError"
        "500":
          description: Configure failure with structured phase
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChromiumConfigureError"

  /playwright/execute:
    post:
      summary: Execute Playwright/TypeScript code against the browser
      description: |
        Execute arbitrary Playwright code in a fresh execution context against the browser running
        on localhost:9222. The code has access to 'page', 'context', and 'browser' variables.
        The result of the code execution is returned in the response.
      operationId: executePlaywrightCode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExecutePlaywrightRequest"
      responses:
        "200":
          description: Code executed successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecutePlaywrightResult"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalError"
  /telemetry:
    get:
      summary: Get telemetry configuration
      description: >
        Returns the current telemetry configuration. Returns 404 if telemetry
        is not configured.
      operationId: getTelemetry
      responses:
        "200":
          description: Telemetry configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TelemetryState"
        "404":
          $ref: "#/components/responses/NotFoundError"
    put:
      summary: Set telemetry configuration
      description: >
        Sets the telemetry configuration. Returns 201 if telemetry was not
        previously configured; returns 200 if it was. Selection is opt-in: a
        request that enables no categories (a browser config with nothing set to
        true, or every category disabled) clears the configuration; this is
        idempotent when telemetry is not configured.
      operationId: putTelemetry
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BrowserTelemetryConfig"
      responses:
        "200":
          description: Telemetry configuration updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TelemetryState"
        "201":
          description: Telemetry configuration set
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TelemetryState"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "500":
          $ref: "#/components/responses/InternalError"
    patch:
      summary: Update telemetry configuration
      description: >
        Partially updates the telemetry configuration. Only categories explicitly
        set in the request body are changed; omitted categories retain their
        current settings. Returns 404 if telemetry is not configured. Setting
        every configurable category to enabled: false clears the configuration.
      operationId: patchTelemetry
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BrowserTelemetryConfig"
      responses:
        "200":
          description: Telemetry configuration updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TelemetryState"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/InternalError"
  /telemetry/events:
    post:
      summary: Publish an event into the telemetry stream
      description: >
        Injects an event into the telemetry stream, gated by the active
        telemetry config. Returns 200 with the assigned envelope when the
        event is admitted, 204 when the event is filtered (no active session
        or the event's category is disabled), or 400 on validation failure.
      operationId: publishTelemetryEvent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PublishEventRequest"
      responses:
        "200":
          description: Event published; envelope carries the assigned sequence.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TelemetryEnvelope"
        "204":
          description: Event accepted but filtered by the active telemetry config; not published.
        "400":
          $ref: "#/components/responses/BadRequestError"
  /telemetry/stream:
    get:
      summary: Stream telemetry events as Server-Sent Events
      description: >
        Opens a live SSE stream of telemetry events.
        Each frame has the form `id: {seq}\ndata: {envelope-json}\n\n`.
        Sequence numbers are process-monotonic and persist across configuration
        changes; a Last-Event-ID from any previous connection is valid for resuming the stream.
        Drops are signaled by gaps in the `id` field: if the received `id` is more
        than 1 ahead of the last-seen `id`, events were evicted from the buffer.
        Clients should track the last-seen `id` to detect gaps.
        Fresh connections with no Last-Event-ID start from the current sequence
        and only see new events; pass `?replay=all` to start from the oldest
        retained event instead.
        The wire shape is the generic `TelemetryEvent`. For browser events
        emitted by the Kernel image (or by callers using a documented `type`),
        the event's `data` conforms to the matching `Browser*EventData`
        schema, selected by `type`.
      operationId: streamTelemetryEvents
      parameters:
        - in: header
          name: Last-Event-ID
          schema:
            type: string
          required: false
          description: >
            Resume after this sequence number. Omit or send 0 to start from
            the current position. Sequence numbers are process-monotonic, so
            any previous value resumes correctly from that point.
            Takes precedence over `replay` when both are present, so SSE
            auto-reconnect resumes cleanly instead of re-replaying history.
        - in: query
          name: replay
          schema:
            type: string
            enum: [all]
          required: false
          description: >
            Pass `all` to start from the oldest retained event. Ring buffer
            caps at 1024; older events are evicted and surface as a first
            `id` greater than 1.
      responses:
        "200":
          description: Live SSE stream of telemetry events.
          headers:
            X-SSE-Content-Type:
              description: Media type of SSE data events (application/json)
              schema:
                type: string
                const: application/json
          content:
            text/event-stream:
              schema:
                $ref: "#/components/schemas/TelemetryEnvelope"
  /scaletozero/disable:
    post:
      summary: Idempotently disable scale to zero on this VM.
      description: >
        Prevents the VM from scaling to zero, regardless of HTTP traffic on it.
        Calling the API on this VM will wake it because Unikraft will automatically wake for any request to the VM.
      operationId: disableScaleToZero
      responses:
        "204":
          description: Scale-to-zero disabled
        "500":
          $ref: "#/components/responses/InternalError"
  /scaletozero/enable:
    post:
      summary: Idempotently enable scale to zero on this VM.
      description: >
        Restores normal scale-to-zero behavior on this VM, allowing it to
        scale to zero again when idle. Call this when the VM no longer needs to be held awake.
      operationId: enableScaleToZero
      responses:
        "204":
          description: Scale-to-zero enabled
        "500":
          $ref: "#/components/responses/InternalError"
components:
  schemas:
    TelemetryEvent:
      type: object
      description: >
        A telemetry event. The wire-level event shape accepted by the publish
        endpoint and emitted on the SSE stream. Arbitrary `type` strings and
        `data` payloads are admitted. For browser events emitted by the Kernel
        image, `data` conforms to the per-type schema documented in the
        `Browser*Event` / `Browser*EventData` definitions, selected by `type`.
      required:
        - type
      properties:
        ts:
          type: integer
          format: int64
          description: Unix timestamp in microseconds. Defaults to the current time when omitted.
        type:
          type: string
          description: Event type identifier.
        category:
          type: string
          description: Event category.
          enum:
            - console
            - network
            - page
            - interaction
            - control
            - connection
            - system
            - screenshot
            - captcha
            - monitor
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          description: >
            Arbitrary JSON payload. For browser events listed in
            `KnownBrowserTelemetryEvent`, the payload conforms to the
            corresponding `Browser*EventData` schema.
        truncated:
          type: boolean
          description: Set by the server when the data field was truncated to fit the size limit.
    BrowserEventSource:
      type: object
      description: Provenance metadata identifying which producer emitted the event.
      required: [kind]
      properties:
        kind:
          type: string
          description: >
            Event producer. `cdp`: Chrome DevTools Protocol events from the
            browser. `kernel_api`: Kernel API server (reserved for
            server-generated events). `extension`: injected Chrome extension.
            `local_process`: system process running alongside the browser.
          enum:
            - cdp
            - kernel_api
            - extension
            - local_process
        event:
          type: string
          description: Producer-specific event name (e.g. `Runtime.consoleAPICalled` for CDP-sourced console events).
        metadata:
          type: object
          description: Producer-specific context (e.g. CDP target/session/frame IDs).
          additionalProperties:
            type: string
      additionalProperties: false
    PublishEventRequest:
      type: object
      description: Request body for publishing an event into the telemetry stream.
      required:
        - type
      properties:
        type:
          type: string
          description: Event type identifier.
        category:
          type: string
          description: >
            Event category. Optional and advisory: for a known event `type` the
            server assigns the category authoritatively and ignores this field.
            It is only used for unknown custom types, where it is required.
          enum:
            - console
            - network
            - page
            - interaction
            - control
            - connection
            - system
            - screenshot
            - captcha
            - monitor
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          description: Telemetry event payload.
      additionalProperties: false
    TelemetryEnvelope:
      type: object
      description: The envelope assigned to a successfully published event.
      required:
        - seq
        - event
      properties:
        seq:
          type: integer
          format: int64
          minimum: 1
          description: >
            Process-monotonic sequence number assigned across the lifetime of
            the server. Use with Last-Event-ID to resume the SSE stream from
            this point.
        event:
          $ref: "#/components/schemas/TelemetryEvent"
      additionalProperties: false
    BrowserTelemetryConfig:
      type: object
      description: >
        Telemetry configuration for a browser. Selection is opt-in. Omit the
        browser key (or send an empty object) to capture the default set:
        lightweight operational signals (control, connection, system, captcha).
        Within `browser`, only the categories you set enabled: true are
        captured; anything omitted is off. The CDP categories (console, network,
        page, interaction) and `screenshot` are off by default and must be
        opted into. A `browser` config with nothing enabled clears the
        telemetry configuration. The `monitor` category (CDP collector health)
        is not configurable here; it flows automatically whenever a CDP category
        is captured.
      properties:
        browser:
          $ref: "#/components/schemas/BrowserTelemetryCategoriesConfig"
        export:
          $ref: "#/components/schemas/BrowserTelemetryExportConfig"
      additionalProperties: false
    BrowserTelemetryExportConfig:
      type: object
      description: >
        Forwarding of captured telemetry to an external destination. Independent
        of what is captured: export is off unless explicitly enabled here, even
        when an export destination is configured. In a PUT (full replace) an
        omitted export block resets export to off, the same as omitted categories
        turn off; in a PATCH an omitted field leaves the current setting unchanged.
      properties:
        otlp:
          $ref: "#/components/schemas/BrowserTelemetryOTLPExportConfig"
      additionalProperties: false
    BrowserTelemetryOTLPExportConfig:
      type: object
      description: OTLP/HTTP export settings.
      properties:
        enabled:
          type: boolean
          description: >
            Whether captured telemetry is forwarded to the configured OTLP
            destination. Off by default. Has no effect (export stays inactive)
            when no export destination is configured.
      additionalProperties: false
    BrowserTelemetryCategoriesConfig:
      type: object
      description: Per-category telemetry capture settings for browser events.
      properties:
        console:
          $ref: "#/components/schemas/BrowserTelemetryCategoryConfig"
          description: Console output (log, warn, error) and uncaught exceptions.
        page:
          $ref: "#/components/schemas/BrowserTelemetryCategoryConfig"
          description: Page lifecycle events (navigation, load, layout shifts, LCP).
        interaction:
          $ref: "#/components/schemas/BrowserTelemetryCategoryConfig"
          description: User interaction events (clicks, keydowns, scroll).
        network:
          $ref: "#/components/schemas/BrowserTelemetryCategoryConfig"
          description: HTTP request/response metadata.
        control:
          $ref: "#/components/schemas/BrowserTelemetryCategoryConfig"
          description: Agent-driven actions against the browser, such as inbound calls to the kernel-images-api server.
        connection:
          $ref: "#/components/schemas/BrowserTelemetryCategoryConfig"
          description: Client attach/detach lifecycle for the CDP proxy and live view.
        system:
          $ref: "#/components/schemas/BrowserTelemetryCategoryConfig"
          description: Browser VM health, such as out-of-memory kills and managed-service crashes.
        screenshot:
          $ref: "#/components/schemas/BrowserTelemetryCategoryConfig"
          description: Periodic base64-encoded viewport screenshots. High volume; off by default and opt-in.
        captcha:
          $ref: "#/components/schemas/BrowserTelemetryCategoryConfig"
          description: Captcha solve attempt outcomes.
      additionalProperties: false
    BrowserTelemetryCategoryConfig:
      type: object
      description: Configuration for a single telemetry category.
      properties:
        enabled:
          type: boolean
          description: >
            Whether this category is captured. In PUT requests selection is opt-in:
            omitting this field (or the whole category) leaves the category off, so
            a PUT captures exactly the categories set to true. In PATCH requests,
            omitting this field (or sending an empty object `{}`) is a no-op; the
            category retains its current state. To enable or disable a category via
            PATCH, you must send an explicit `true` or `false`.
      additionalProperties: false
    BrowserCallStack:
      type: object
      description: >
        CDP Runtime.StackTrace representing the JavaScript call stack at the
        time of an event. Fields use CDP naming conventions rather than
        snake_case to match the Chrome DevTools Protocol wire format.
      required: [callFrames]
      properties:
        description:
          type: string
          description: Optional label for the stack trace (e.g. async cause).
        callFrames:
          type: array
          description: Ordered list of call frames, outermost first.
          items:
            type: object
            required: [functionName, scriptId, url, lineNumber, columnNumber]
            properties:
              functionName:
                type: string
                description: JavaScript function name, or empty string for anonymous functions.
              scriptId:
                type: string
                description: CDP script identifier.
              url:
                type: string
                description: URL or name of the script file.
              lineNumber:
                type: integer
                description: Zero-based line number within the script.
              columnNumber:
                type: integer
                description: Zero-based column number within the line.
        parent:
          $ref: "#/components/schemas/BrowserCallStack"
          description: Parent stack trace for async stacks.
    BrowserHttpHeaders:
      type: object
      description: >
        HTTP headers map forwarded as-is from CDP without normalization.
        Values are typically strings but may be any JSON type.
      additionalProperties: true
    BrowserTargetType:
      type: string
      description: CDP target type of the page that produced the event.
      enum: [page, background_page, service_worker, shared_worker, other]
    BrowserEventContext:
      type: object
      description: >
        Browser event context stamped by the browser monitor onto all
        CDP-sourced events. Identifies the target, frame, and navigation epoch
        in which the event occurred.
      required: [session_id, target_id, target_type, nav_seq]
      properties:
        session_id:
          type: string
          description: CDP session identifier for the target connection.
        target_id:
          type: string
          description: Browser target identifier (stable across navigations within a tab).
        target_type:
          $ref: "#/components/schemas/BrowserTargetType"
        frame_id:
          type: string
          description: CDP frame identifier within the target.
        loader_id:
          type: string
          description: CDP document loader identifier, reset on each navigation.
        url:
          type: string
          description: URL relevant to this event; page URL for navigation and page events, request URL for network events.
        nav_seq:
          type: integer
          format: int64
          description: Monotonically increasing navigation sequence number, incremented on each top-level navigation within the target.
    BrowserConsoleLogEventData:
      allOf:
        - $ref: "#/components/schemas/BrowserEventContext"
        - type: object
          required: [level, text]
          properties:
            level:
              type: string
              description: >
                CDP Runtime.consoleAPICalled type, passed through unfiltered
                from Chrome. `error` is routed to console_error events instead;
                all other CDP console types appear here. See CDP spec for the
                full enum.
            text:
              type: string
              description: First console argument coerced to string.
            args:
              type: array
              description: All console arguments coerced to strings.
              items:
                type: string
            stack_trace:
              $ref: "#/components/schemas/BrowserCallStack"
    BrowserConsoleLogEvent:
      type: object
      description: A browser console log event (console.log, console.info, console.warn, etc.).
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: console_log
        category:
          type: string
          const: console
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserConsoleLogEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserConsoleErrorEventData:
      allOf:
        - $ref: "#/components/schemas/BrowserEventContext"
        - type: object
          required: [text]
          properties:
            text:
              type: string
              description: >
                Human-readable error text, as the browser console would display it.
                For console.error() calls, the first argument coerced to a string.
                For uncaught exceptions, the prefix and error message, e.g.
                "Uncaught Error: boom" or "Uncaught (in promise) TypeError: x is not a function".
            stack_trace:
              $ref: "#/components/schemas/BrowserCallStack"
            level:
              type: string
              description: CDP console type value, always "error". Present only when sourced from Runtime.consoleAPICalled.
            args:
              type: array
              description: All console arguments coerced to strings. Present only when sourced from Runtime.consoleAPICalled.
              items:
                type: string
            line:
              type: integer
              description: Line number in the script where the exception was thrown. Present only when sourced from Runtime.exceptionThrown.
            column:
              type: integer
              description: Column number in the script where the exception was thrown. Present only when sourced from Runtime.exceptionThrown.
            source_url:
              type: string
              description: URL of the script file that threw the exception. Present only when sourced from Runtime.exceptionThrown.
    BrowserConsoleErrorEvent:
      type: object
      description: >
        A browser console error or uncaught JavaScript exception event. Emitted
        from two distinct CDP sources with different data shapes.
        Runtime.consoleAPICalled (console.error calls) produces level, text,
        args, and stack_trace. Runtime.exceptionThrown (uncaught exceptions)
        produces text, line, column, source_url, and stack_trace. Fields not
        applicable to the source are absent.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: console_error
        category:
          type: string
          const: console
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserConsoleErrorEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserNetworkRequestEventData:
      allOf:
        - $ref: "#/components/schemas/BrowserEventContext"
        - type: object
          required: [request_id, method, document_url, headers, initiator_type]
          properties:
            request_id:
              type: string
              description: CDP request identifier, unique within the session.
            method:
              type: string
              description: HTTP method as sent on the wire (e.g. GET, POST).
            document_url:
              type: string
              description: URL of the document that initiated the request.
            headers:
              $ref: "#/components/schemas/BrowserHttpHeaders"
              description: Request headers.
            resource_type:
              type: string
              description: CDP Network.ResourceType for the request, passed through as-is from Chrome. Known values include Document, Fetch, XHR, Script, Stylesheet, Image, Media, Font, TextTrack, EventSource, WebSocket, Manifest, Prefetch, Other, and more.
            initiator_type:
              type: string
              description: CDP Initiator.type indicating what caused the request, passed through as-is from Chrome. Known values include script, parser, preload, and other.
            post_data:
              type: string
              description: Request body for POST/PUT requests, if available.
            is_redirect:
              type: boolean
              description: True if this request is the result of a redirect.
            redirect_url:
              type: string
              description: Original URL before the redirect, present when is_redirect is true.
    BrowserNetworkRequestEvent:
      type: object
      description: A browser network request sent event.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: network_request
        category:
          type: string
          const: network
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserNetworkRequestEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserNetworkResponseEventData:
      allOf:
        - $ref: "#/components/schemas/BrowserEventContext"
        - type: object
          required: [request_id, method, status, headers]
          properties:
            request_id:
              type: string
              description: CDP request identifier matching the originating network_request event.
            method:
              type: string
              description: HTTP method of the original request.
            status:
              type: integer
              description: HTTP response status code.
            status_text:
              type: string
              description: HTTP response status text (e.g. OK, Not Found).
            headers:
              $ref: "#/components/schemas/BrowserHttpHeaders"
              description: Response headers.
            mime_type:
              type: string
              description: MIME type of the response (e.g. text/html, application/json).
            resource_type:
              type: string
              description: CDP Network.ResourceType for the request, passed through as-is from Chrome. Known values include Document, Fetch, XHR, Script, Stylesheet, Image, Media, Font, TextTrack, EventSource, WebSocket, Manifest, Prefetch, Other, and more.
            body:
              type: string
              description: Truncated response body, present only for text MIME types.
    BrowserNetworkResponseEvent:
      type: object
      description: A browser network response received event. Fired after the response body is fully received, not when headers arrive.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: network_response
        category:
          type: string
          const: network
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserNetworkResponseEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserNetworkLoadingFailedEventData:
      allOf:
        - $ref: "#/components/schemas/BrowserEventContext"
        - type: object
          required: [request_id, error_text, canceled]
          properties:
            request_id:
              type: string
              description: CDP request identifier matching the originating network_request event.
            error_text:
              type: string
              description: Network error description (e.g. net::ERR_CONNECTION_REFUSED).
            canceled:
              type: boolean
              description: True if the request was canceled by the browser or page script.
            resource_type:
              type: string
              description: CDP Network.ResourceType for the request, passed through as-is from Chrome. Known values include Document, Fetch, XHR, Script, Stylesheet, Image, Media, Font, TextTrack, EventSource, WebSocket, Manifest, Prefetch, Other, and more.
    BrowserNetworkLoadingFailedEvent:
      type: object
      description: >
        A browser network loading failed event. If the request was already in
        flight when CDP attached (no prior `network_request` was emitted for
        it), `url`, `frame_id`, `loader_id`, and `resource_type` are absent;
        `BrowserEventContext` is partially populated in that case.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: network_loading_failed
        category:
          type: string
          const: network
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserNetworkLoadingFailedEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserNetworkIdleEvent:
      type: object
      description: A browser network idle event emitted after a 500ms quiet period with no in-flight HTTP requests.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: network_idle
        category:
          type: string
          const: network
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserEventContext"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserPageNavigationEventData:
      type: object
      additionalProperties: false
      required: [session_id, target_id, target_type, url, frame_id, loader_id]
      properties:
        url:
          type: string
          description: URL navigated to.
        frame_id:
          type: string
          description: CDP frame identifier of the navigated frame.
        parent_frame_id:
          type: string
          description: Parent frame identifier for subframe navigations; absent for top-level navigations.
        loader_id:
          type: string
          description: New CDP document loader identifier assigned for this navigation.
        session_id:
          type: string
          description: CDP session identifier.
        target_id:
          type: string
          description: Browser target identifier.
        target_type:
          $ref: "#/components/schemas/BrowserTargetType"
    BrowserPageNavigationEvent:
      type: object
      description: A browser page navigation started event (CDP Page.frameNavigated). Carries nav context fields inline but not nav_seq, as this event resets the navigation epoch.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: page_navigation
        category:
          type: string
          const: page
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserPageNavigationEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserPageDomContentLoadedEventData:
      allOf:
        - $ref: "#/components/schemas/BrowserEventContext"
        - type: object
          required: [cdp_timestamp]
          properties:
            cdp_timestamp:
              type: number
              description: Chrome monotonic clock value in seconds at which DOMContentLoaded fired, relative to browser process start (not Unix epoch). Use `ts` for wall-clock time.
    BrowserPageDomContentLoadedEvent:
      type: object
      description: A browser DOMContentLoaded event (CDP Page.domContentEventFired).
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: page_dom_content_loaded
        category:
          type: string
          const: page
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserPageDomContentLoadedEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserPageLoadEventData:
      allOf:
        - $ref: "#/components/schemas/BrowserEventContext"
        - type: object
          required: [cdp_timestamp]
          properties:
            cdp_timestamp:
              type: number
              description: Chrome monotonic clock value in seconds at which the load event fired, relative to browser process start (not Unix epoch). Use `ts` for wall-clock time.
    BrowserPageLoadEvent:
      type: object
      description: A browser page load event (CDP Page.loadEventFired).
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: page_load
        category:
          type: string
          const: page
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserPageLoadEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserPageTabOpenedEventData:
      type: object
      additionalProperties: false
      required: [target_id, target_type, url]
      properties:
        target_id:
          type: string
          description: CDP target identifier for the newly opened tab.
        target_type:
          $ref: "#/components/schemas/BrowserTargetType"
        url:
          type: string
          description: Initial URL of the new tab.
        title:
          type: string
          description: Initial page title of the new tab.
        opener_id:
          type: string
          description: Target identifier of the tab that opened this one, if any.
    BrowserPageTabOpenedEvent:
      type: object
      description: >
        A new browser tab or target was opened (CDP Target.attachedToTarget
        for page targets). Fires before a CDP session is attached to the new
        target, so `session_id`, `frame_id`, `loader_id`, and `nav_seq` are
        absent; this event does not compose `BrowserEventContext`. Consumers
        reading context fields generically should treat it as a special case.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: page_tab_opened
        category:
          type: string
          const: page
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserPageTabOpenedEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserPageCrashedEventData:
      type: object
      additionalProperties: false
      required: [target_id, target_type, url]
      properties:
        target_id:
          type: string
          description: CDP target identifier of the crashed page.
        target_type:
          $ref: "#/components/schemas/BrowserTargetType"
        url:
          type: string
          description: URL the page was on when its renderer process crashed.
    BrowserPageCrashedEvent:
      type: object
      description: >
        A page's renderer process crashed (an "Aw, Snap!" failure) while the
        browser process itself stayed alive. Reported on the crashed page's
        session, with the session and target ids on `source.metadata`. Captured
        only while the `page` category is enabled.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: page_crashed
        category:
          type: string
          const: page
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserPageCrashedEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserPageLayoutShiftEventData:
      allOf:
        - $ref: "#/components/schemas/BrowserEventContext"
        - type: object
          required: [source_frame_id, time, duration]
          properties:
            source_frame_id:
              type: string
              description: CDP frame identifier of the frame where the layout shift occurred.
            time:
              type: number
              description: Performance Timeline timestamp of the layout shift in milliseconds.
            duration:
              type: number
              description: Duration of the layout shift entry in milliseconds (always 0 for layout shifts per spec).
            layout_shift_details:
              type: object
              additionalProperties: false
              description: PerformanceLayoutShift attributes from the Performance Timeline entry.
              properties:
                value:
                  type: number
                  description: Layout shift score for this entry (contribution to CLS).
                had_recent_input:
                  type: boolean
                  description: True if the layout shift was preceded by user input within 500ms, excluding it from CLS.
    BrowserPageLayoutShiftEvent:
      type: object
      description: A browser cumulative layout shift (CLS) event from the Performance Timeline API.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: page_layout_shift
        category:
          type: string
          const: page
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserPageLayoutShiftEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserPageLcpEventData:
      allOf:
        - $ref: "#/components/schemas/BrowserEventContext"
        - type: object
          required: [source_frame_id, time]
          properties:
            source_frame_id:
              type: string
              description: CDP frame identifier of the frame where the LCP element was rendered.
            time:
              type: number
              description: Performance Timeline timestamp of the LCP entry in milliseconds.
            lcp_details:
              type: object
              additionalProperties: false
              description: LargestContentfulPaint attributes from the Performance Timeline entry.
              properties:
                render_time:
                  type: number
                  description: Render time of the LCP element in milliseconds; 0 for cross-origin images without Timing-Allow-Origin.
                load_time:
                  type: number
                  description: Load time of the LCP element in milliseconds.
                size:
                  type: number
                  description: Visible area of the LCP element in pixels squared.
                element_id:
                  type: string
                  description: id attribute of the LCP element, if present.
                url:
                  type: string
                  description: URL of the LCP element for image or video elements.
                node_id:
                  type: integer
                  description: CDP DOM node identifier of the LCP element.
    BrowserPageLcpEvent:
      type: object
      description: A browser Largest Contentful Paint (LCP) event from the Performance Timeline API.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: page_lcp
        category:
          type: string
          const: page
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserPageLcpEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserPageLayoutSettledEvent:
      type: object
      description: A browser layout settled event emitted 1 second after page load with no intervening layout shifts, indicating visual stability. Each layout shift resets the 1-second timer.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: page_layout_settled
        category:
          type: string
          const: page
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserEventContext"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserPageNavigationSettledEvent:
      type: object
      description: >
        Emitted when page_dom_content_loaded and page_layout_settled have both
        fired for the same navigation, indicating the page is loaded and
        visually stable. Independent of network_idle; a single pending request
        does not block it.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: page_navigation_settled
        category:
          type: string
          const: page
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserEventContext"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserInteractionClickEventData:
      allOf:
        - $ref: "#/components/schemas/BrowserEventContext"
        - type: object
          required: [x, y, selector, tag]
          properties:
            x:
              type: integer
              description: Viewport x-coordinate of the click in CSS pixels.
            y:
              type: integer
              description: Viewport y-coordinate of the click in CSS pixels.
            selector:
              type: string
              description: CSS selector path to the clicked element.
            tag:
              type: string
              description: HTML tag name of the clicked element in uppercase (e.g. BUTTON, A, DIV).
            text:
              type: string
              description: Visible text content of the clicked element, trimmed.
    BrowserInteractionClickEvent:
      type: object
      description: A browser user click event captured via injected page script.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: interaction_click
        category:
          type: string
          const: interaction
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserInteractionClickEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserInteractionKeyEventData:
      allOf:
        - $ref: "#/components/schemas/BrowserEventContext"
        - type: object
          required: [key, selector, tag]
          properties:
            key:
              type: string
              description: Key value from the KeyboardEvent (e.g. Enter, Backspace, a).
            selector:
              type: string
              description: CSS selector path to the element that had focus when the key was pressed.
            tag:
              type: string
              description: HTML tag name of the focused element in uppercase (e.g. INPUT, TEXTAREA, DIV).
    BrowserInteractionKeyEvent:
      type: object
      description: A browser keyboard event captured via injected page script.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: interaction_key
        category:
          type: string
          const: interaction
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserInteractionKeyEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserInteractionScrollSettledEventData:
      allOf:
        - $ref: "#/components/schemas/BrowserEventContext"
        - type: object
          required: [from_x, from_y, to_x, to_y, target_selector]
          properties:
            from_x:
              type: integer
              description: Scroll x-position at the start of the scroll gesture in CSS pixels.
            from_y:
              type: integer
              description: Scroll y-position at the start of the scroll gesture in CSS pixels.
            to_x:
              type: integer
              description: Final scroll x-position after the gesture settled in CSS pixels.
            to_y:
              type: integer
              description: Final scroll y-position after the gesture settled in CSS pixels.
            target_selector:
              type: string
              description: CSS selector path to the scrolled element.
    BrowserInteractionScrollSettledEvent:
      type: object
      description: A browser scroll settled event emitted after scroll position stops changing, captured via injected page script.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: interaction_scroll_settled
        category:
          type: string
          const: interaction
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserInteractionScrollSettledEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserMonitorScreenshotEventData:
      type: object
      additionalProperties: false
      required: [png]
      properties:
        png:
          type: string
          contentEncoding: base64
          description: Base64-encoded PNG screenshot of the browser viewport.
    BrowserMonitorScreenshotEvent:
      type: object
      description: A periodic screenshot of the browser viewport.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: monitor_screenshot
        category:
          type: string
          const: screenshot
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserMonitorScreenshotEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserMonitorDisconnectedEventData:
      type: object
      additionalProperties: false
      required: [reason]
      properties:
        reason:
          type: string
          description: 'Reason for the disconnection. chrome_restarted: Chrome process restarted.'
          enum: [chrome_restarted]
    BrowserMonitorDisconnectedEvent:
      type: object
      description: The CDP connection to Chrome was lost. Telemetry events may be dropped until monitor_reconnected arrives. Treat any in-progress computed state (network_idle, page_layout_settled) as unreliable until then.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: monitor_disconnected
        category:
          type: string
          const: monitor
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserMonitorDisconnectedEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserMonitorReconnectedEventData:
      type: object
      additionalProperties: false
      required: [reconnect_duration_ms]
      properties:
        reconnect_duration_ms:
          type: integer
          format: int64
          description: Wall-clock time in milliseconds taken to reconnect after the disconnection.
    BrowserMonitorReconnectedEvent:
      type: object
      description: The CDP connection to Chrome was successfully re-established after a disconnection. Events emitted during the gap are lost. Computed state is reset, so navigation and network tracking restart fresh from this point.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: monitor_reconnected
        category:
          type: string
          const: monitor
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserMonitorReconnectedEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserMonitorReconnectFailedEventData:
      type: object
      additionalProperties: false
      required: [reason]
      properties:
        reason:
          type: string
          description: 'Reason for the reconnection failure. reconnect_exhausted: all retry attempts were used up without successfully restoring the CDP connection.'
          enum: [reconnect_exhausted]
    BrowserMonitorReconnectFailedEvent:
      type: object
      description: The CDP connection to Chrome could not be re-established after exhausting all reconnection attempts. No further telemetry events will arrive on this session.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: monitor_reconnect_failed
        category:
          type: string
          const: monitor
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserMonitorReconnectFailedEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserMonitorInitFailedEventData:
      type: object
      additionalProperties: false
      required: [step]
      properties:
        step:
          type: string
          description: The CDP method or initialization step that failed (e.g. Target.setAutoAttach).
    BrowserMonitorInitFailedEvent:
      type: object
      description: The CDP session could not be initialized.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: monitor_init_failed
        category:
          type: string
          const: monitor
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserMonitorInitFailedEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserApiCallEventData:
      type: object
      description: Per-call payload for `api_call` events.
      additionalProperties: false
      required: [request_id, operation_id, status, duration_ms]
      properties:
        request_id:
          type: string
          description: Per-request identifier from the kernel-images-api request middleware.
        operation_id:
          type: string
          description: OpenAPI operationId of the matched route (e.g. `processExec`, `takeScreenshot`).
        status:
          type: integer
          description: HTTP response status code.
        duration_ms:
          type: number
          description: Wall-clock duration of the handler in milliseconds.
    BrowserApiCallEvent:
      type: object
      description: An HTTP call handled by the kernel-images-api server.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: api_call
        category:
          type: string
          const: control
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserApiCallEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserCdpConnectEvent:
      type: object
      description: An external client (e.g. customer SDK, Playwright, Puppeteer) connected to the CDP WebSocket proxy on this VM.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: cdp_connect
        category:
          type: string
          const: connection
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserCdpDisconnectEventData:
      type: object
      description: Per-disconnect payload for `cdp_disconnect` events.
      additionalProperties: false
      required: [duration_ms, message_count, reason]
      properties:
        duration_ms:
          type: number
          description: Wall-clock duration of the connection in milliseconds.
        message_count:
          type: integer
          description: Number of CDP messages relayed across the connection in either direction.
        reason:
          type: string
          description: >
            Why the connection ended. `client_close`: the client initiated the close.
            `upstream_changed`: Chromium restarted mid-session and the proxy tore down
            so the client could reconnect against the new upstream. `upstream_error`:
            upstream dial or message pump errored. `context_cancelled`: the request
            context was cancelled (typically server shutdown).
          enum:
            - client_close
            - upstream_changed
            - upstream_error
            - context_cancelled
    BrowserCdpDisconnectEvent:
      type: object
      description: An external client disconnected from the CDP WebSocket proxy on this VM. Pair with the immediately preceding `cdp_connect` on the same stream.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: cdp_disconnect
        category:
          type: string
          const: connection
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserCdpDisconnectEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserLiveViewConnectEventData:
      type: object
      description: Per-session payload for `live_view_connect` events.
      additionalProperties: false
      required: [session_id]
      properties:
        session_id:
          type: string
          description: Live view session identifier. Stable across reconnects, so a transient network blip can emit two events with the same `session_id`.
    BrowserLiveViewConnectEvent:
      type: object
      description: A live view client connected to the headful browser's WebRTC server (Neko). Headful only; not emitted for headless images.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: live_view_connect
        category:
          type: string
          const: connection
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserLiveViewConnectEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserLiveViewDisconnectEventData:
      type: object
      description: Per-session payload for `live_view_disconnect` events.
      additionalProperties: false
      required: [session_id, duration_ms]
      properties:
        session_id:
          type: string
          description: Live view session identifier; matches the corresponding `live_view_connect` event.
        duration_ms:
          type: number
          description: Wall-clock duration of the connection in milliseconds.
    BrowserLiveViewDisconnectEvent:
      type: object
      description: A live view client disconnected from the headful browser's WebRTC server (Neko). Pair with `live_view_connect` by `session_id`.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: live_view_disconnect
        category:
          type: string
          const: connection
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserLiveViewDisconnectEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserCaptchaSolveResultEventData:
      type: object
      description: Per-attempt payload for `captcha_solve_result` events.
      additionalProperties: false
      required: [captcha_type, status, duration_ms]
      properties:
        captcha_type:
          type: string
          description: >
            Captcha vendor family. Producers normalize provider-specific task
            names into this set: enterprise variants of recaptcha collapse into
            their version bucket (v2 / v3), and anything not covered (e.g.
            DataDome, MtCaptcha, plain OCR) is reported as `other`.
          enum:
            - hcaptcha
            - recaptcha_v2
            - recaptcha_v3
            - turnstile
            - geetest
            - other
        status:
          type: string
          description: >
            Terminal outcome. `success`: solver returned a usable solution.
            `failure`: solver returned an error (see `error_code`).
            `timeout`: solver did not return within the caller's wait budget.
            `abandoned`: caller cancelled or the page navigated away mid-solve.
          enum:
            - success
            - failure
            - timeout
            - abandoned
        duration_ms:
          type: number
          description: Wall-clock duration from solve start to terminal outcome.
        task_id:
          type: string
          description: Solver-assigned identifier. Opaque, useful for support cross-references.
        website_host:
          type: string
          description: Host of the page where the captcha was solved.
        website_path:
          type: string
          description: Path of the page where the captcha was solved. Query string excluded.
        error_code:
          type: string
          description: Solver-specific error code on failure (e.g. `ERROR_CAPTCHA_UNSOLVABLE`). Absent on success.
    BrowserCaptchaSolveResultEvent:
      type: object
      description: A captcha solve attempt reached a terminal outcome.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: captcha_solve_result
        category:
          type: string
          const: captcha
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserCaptchaSolveResultEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserSystemOomKillEventData:
      type: object
      description: Per-kill payload for `system_oom_kill` events.
      additionalProperties: false
      required: [process_name, pid, rss_kb]
      properties:
        process_name:
          type: string
          description: Comm of the killed process as reported by the kernel (max 15 chars, truncated by the kernel).
        pid:
          type: integer
          description: PID of the killed process.
        rss_kb:
          type: integer
          description: Resident set size of the killed process in KiB (sum of anon-rss, file-rss, and shmem-rss). This is the physical memory the process was using at the time of the kill.
        trigger_process_name:
          type: string
          description: >
            Comm of the process whose allocation request caused the
            kernel to invoke the OOM-killer. Often the same as
            `process_name` (the kernel killed the requester) but can
            differ when the kernel chose a different victim. Max 15
            chars, truncated by the kernel.
        trigger_pid:
          type: integer
          description: >
            PID of the triggering process. Absent if the kernel did
            not emit the standard `CPU: N PID: N Comm:` header line.
        constraint:
          type: string
          description: >
            Why the kernel decided to OOM-kill. `none` means global memory
            exhaustion; `memcg` means a cgroup memory limit was hit;
            `cpuset` / `memory_policy` are NUMA/policy-driven kills.
            Absent on kernels older than 5.0 which did not emit the
            structured `oom-kill:` line.
          enum:
            - none
            - memcg
            - cpuset
            - memory_policy
        mem_total_kb:
          type: integer
          description: >
            Total system memory in KiB at the time of the kill, derived
            from the `N pages RAM` line in the kernel's Mem-Info dump.
            Assumes a 4 KiB page size. Absent if the kernel did not
            emit a parseable Mem-Info section.
        mem_free_kb:
          type: integer
          description: >
            Free system memory in KiB at the time of the kill, derived
            from the `free:N` field in the kernel's Mem-Info dump.
            Assumes a 4 KiB page size. Does not include reclaimable
            caches, so a small value with a large `mem_total_kb` may
            still mean the system was not under hard pressure. Absent
            if the kernel did not emit a parseable Mem-Info section.
        top_tasks:
          type: array
          maxItems: 5
          description: >
            Top processes by resident-set-size at the moment of the
            kill, sorted descending. Sourced from the kernel's
            `Tasks state` table. Empty if the kernel did not emit the
            table. Capped at 5 entries to bound payload size.
          items:
            $ref: "#/components/schemas/BrowserSystemOomKillTask"
    BrowserSystemOomKillTask:
      type: object
      description: A single process entry from the kernel's `Tasks state` dump.
      additionalProperties: false
      required: [pid, name, rss_kb]
      properties:
        pid:
          type: integer
          description: PID of the process.
        name:
          type: string
          description: Comm of the process (max 15 chars, truncated by the kernel).
        rss_kb:
          type: integer
          description: Resident set size in KiB at the moment of the kill.
    BrowserSystemOomKillEvent:
      type: object
      description: >
        The Linux kernel OOM-killer terminated a process inside the VM. Sourced from
        `/dev/kmsg`. Fires for any process killed by the kernel due to memory
        exhaustion, including Chrome renderer subprocesses that are not supervised.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: system_oom_kill
        category:
          type: string
          const: system
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserSystemOomKillEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    BrowserServiceCrashedEventData:
      type: object
      description: >
        Per-crash payload for `service_crashed` events. Exit code and
        signal are not exposed by the underlying process manager on this
        channel, so only the service identity, the lifecycle phase the
        crash occurred in, and (when available) the PID are reported.
      additionalProperties: false
      required: [service_name, phase]
      properties:
        service_name:
          type: string
          description: Program name of the crashed service (e.g. `chromium`, `mutter`, `kernel-images-api`).
        pid:
          type: integer
          description: PID of the crashed process. Absent when the process manager gave up after exhausting restart attempts and is no longer tracking a live PID.
        phase:
          type: string
          description: >
            Lifecycle phase the crash occurred in.
            `startup` means the process died before it ever reached a
            healthy running state. `running` means a previously healthy
            process died unexpectedly. `gave_up` means the process
            manager exhausted its restart attempts and stopped trying;
            no further `service_crashed` events will fire for this
            service until something restarts it.
          enum:
            - startup
            - running
            - gave_up
    BrowserServiceCrashedEvent:
      type: object
      description: >
        A managed service exited unexpectedly. Intentional stops (e.g.
        operator-initiated shutdown) do not produce this event — only
        unexpected exits and terminal restart-give-up transitions do.
      required: [ts, type, category, source]
      properties:
        ts:
          type: integer
          format: int64
          description: Event timestamp in Unix microseconds.
        type:
          type: string
          const: service_crashed
        category:
          type: string
          const: system
        source:
          $ref: "#/components/schemas/BrowserEventSource"
        data:
          $ref: "#/components/schemas/BrowserServiceCrashedEventData"
        truncated:
          type: boolean
          description: True if the data field was truncated due to size limits.
    KnownBrowserTelemetryEvent:
      description: >
        Discriminated union of browser telemetry events emitted by the Kernel
        image. This is a structural taxonomy: any event on the telemetry stream
        whose `data` conforms to one of the variants below (selected by `type`)
        is a `KnownBrowserTelemetryEvent`, regardless of who published it.
        Caller-published events via POST /telemetry/events are not constrained
        to this union; see `TelemetryEvent` for the wire shape. Validation of
        caller payloads against this taxonomy is the consumer's responsibility.
      oneOf:
        - $ref: "#/components/schemas/BrowserConsoleLogEvent"
        - $ref: "#/components/schemas/BrowserConsoleErrorEvent"
        - $ref: "#/components/schemas/BrowserNetworkRequestEvent"
        - $ref: "#/components/schemas/BrowserNetworkResponseEvent"
        - $ref: "#/components/schemas/BrowserNetworkLoadingFailedEvent"
        - $ref: "#/components/schemas/BrowserNetworkIdleEvent"
        - $ref: "#/components/schemas/BrowserPageNavigationEvent"
        - $ref: "#/components/schemas/BrowserPageDomContentLoadedEvent"
        - $ref: "#/components/schemas/BrowserPageLoadEvent"
        - $ref: "#/components/schemas/BrowserPageTabOpenedEvent"
        - $ref: "#/components/schemas/BrowserPageCrashedEvent"
        - $ref: "#/components/schemas/BrowserPageLayoutShiftEvent"
        - $ref: "#/components/schemas/BrowserPageLcpEvent"
        - $ref: "#/components/schemas/BrowserPageLayoutSettledEvent"
        - $ref: "#/components/schemas/BrowserPageNavigationSettledEvent"
        - $ref: "#/components/schemas/BrowserInteractionClickEvent"
        - $ref: "#/components/schemas/BrowserInteractionKeyEvent"
        - $ref: "#/components/schemas/BrowserInteractionScrollSettledEvent"
        - $ref: "#/components/schemas/BrowserMonitorScreenshotEvent"
        - $ref: "#/components/schemas/BrowserMonitorDisconnectedEvent"
        - $ref: "#/components/schemas/BrowserMonitorReconnectedEvent"
        - $ref: "#/components/schemas/BrowserMonitorReconnectFailedEvent"
        - $ref: "#/components/schemas/BrowserMonitorInitFailedEvent"
        - $ref: "#/components/schemas/BrowserApiCallEvent"
        - $ref: "#/components/schemas/BrowserCdpConnectEvent"
        - $ref: "#/components/schemas/BrowserCdpDisconnectEvent"
        - $ref: "#/components/schemas/BrowserLiveViewConnectEvent"
        - $ref: "#/components/schemas/BrowserLiveViewDisconnectEvent"
        - $ref: "#/components/schemas/BrowserCaptchaSolveResultEvent"
        - $ref: "#/components/schemas/BrowserSystemOomKillEvent"
        - $ref: "#/components/schemas/BrowserServiceCrashedEvent"
      discriminator:
        propertyName: type
        mapping:
          console_log: "#/components/schemas/BrowserConsoleLogEvent"
          console_error: "#/components/schemas/BrowserConsoleErrorEvent"
          network_request: "#/components/schemas/BrowserNetworkRequestEvent"
          network_response: "#/components/schemas/BrowserNetworkResponseEvent"
          network_loading_failed: "#/components/schemas/BrowserNetworkLoadingFailedEvent"
          network_idle: "#/components/schemas/BrowserNetworkIdleEvent"
          page_navigation: "#/components/schemas/BrowserPageNavigationEvent"
          page_dom_content_loaded: "#/components/schemas/BrowserPageDomContentLoadedEvent"
          page_load: "#/components/schemas/BrowserPageLoadEvent"
          page_tab_opened: "#/components/schemas/BrowserPageTabOpenedEvent"
          page_crashed: "#/components/schemas/BrowserPageCrashedEvent"
          page_layout_shift: "#/components/schemas/BrowserPageLayoutShiftEvent"
          page_lcp: "#/components/schemas/BrowserPageLcpEvent"
          page_layout_settled: "#/components/schemas/BrowserPageLayoutSettledEvent"
          page_navigation_settled: "#/components/schemas/BrowserPageNavigationSettledEvent"
          interaction_click: "#/components/schemas/BrowserInteractionClickEvent"
          interaction_key: "#/components/schemas/BrowserInteractionKeyEvent"
          interaction_scroll_settled: "#/components/schemas/BrowserInteractionScrollSettledEvent"
          monitor_screenshot: "#/components/schemas/BrowserMonitorScreenshotEvent"
          monitor_disconnected: "#/components/schemas/BrowserMonitorDisconnectedEvent"
          monitor_reconnected: "#/components/schemas/BrowserMonitorReconnectedEvent"
          monitor_reconnect_failed: "#/components/schemas/BrowserMonitorReconnectFailedEvent"
          monitor_init_failed: "#/components/schemas/BrowserMonitorInitFailedEvent"
          api_call: "#/components/schemas/BrowserApiCallEvent"
          cdp_connect: "#/components/schemas/BrowserCdpConnectEvent"
          cdp_disconnect: "#/components/schemas/BrowserCdpDisconnectEvent"
          live_view_connect: "#/components/schemas/BrowserLiveViewConnectEvent"
          live_view_disconnect: "#/components/schemas/BrowserLiveViewDisconnectEvent"
          captcha_solve_result: "#/components/schemas/BrowserCaptchaSolveResultEvent"
          system_oom_kill: "#/components/schemas/BrowserSystemOomKillEvent"
          service_crashed: "#/components/schemas/BrowserServiceCrashedEvent"
    TelemetryState:
      type: object
      description: Current telemetry configuration.
      required:
        - config
        - seq
      properties:
        config:
          $ref: "#/components/schemas/BrowserTelemetryConfig"
        seq:
          type: integer
          format: int64
          description: >-
            Process-monotonic sequence number of the last published event.
            Does not reset across configuration changes.
          minimum: 0
        applied_at:
          type: string
          format: date-time
          description: >-
            Wall-clock time at which the current configuration was applied.
            Omitted when telemetry is not configured.
      additionalProperties: false
    StartRecordingRequest:
      type: object
      properties:
        maxFileSizeInMB:
          type: integer
          description: Maximum file size in MB (overrides server default)
          minimum: 10
          maximum: 10000
        framerate:
          type: integer
          description: Recording framerate in fps (overrides server default)
          minimum: 1
          maximum: 20
        maxDurationInSeconds:
          type: integer
          description: Maximum recording duration in seconds (overrides server default)
          minimum: 1
        recordAudio:
          type: boolean
          description: Capture audio alongside video. Requires the server to have an audio source and PulseAudio socket configured (the image sets both by default). When false the recording is video-only.
          default: false
        id:
          type: string
          description: Optional identifier for this recording session, used to target it from the other /recording endpoints (stop, mark, download, delete) and allowing multiple concurrent recordings. Alphanumeric or hyphen. When omitted, the default recording session is started.
          pattern: "^[a-zA-Z0-9-]+$"
      additionalProperties: false
    StopRecordingRequest:
      type: object
      properties:
        forceStop:
          type: boolean
          description: Immediately stop without graceful shutdown. This may result in a corrupted video file.
          default: false
        id:
          type: string
          description: Identifier of the recording session to stop, as passed to /recording/start. Alphanumeric or hyphen. When omitted, the default recording session is stopped.
          pattern: "^[a-zA-Z0-9-]+$"
      additionalProperties: false
    Error:
      type: object
      required: [message]
      properties:
        message:
          type: string
    ChromiumConfigureError:
      type: object
      description: Failure from batched chromium configure — includes which phase failed.
      required: [phase, message]
      additionalProperties: false
      properties:
        phase:
          type: string
          enum:
            - configure_phase
            - navigate_phase
          description: configure_phase maps to restart/filesystem/policy/extension/profile/display work; navigate_phase is retained for compatibility.
        message:
          type: string
        step:
          type: string
          description: Optional configure step that failed.
          enum:
            - stop_chromium
            - start_chromium
            - chrome_policies
            - extensions
            - display
            - chromium_flags
            - profile
    RecorderInfo:
      type: object
      required: [id, isRecording]
      properties:
        id:
          type: string
        isRecording:
          type: boolean
        started_at:
          type: [string, "null"]
          format: date-time
          description: Timestamp when recording started
        finished_at:
          type: [string, "null"]
          format: date-time
          description: Timestamp when recording finished
    ClickMouseRequest:
      type: object
      required:
        - x
        - y
      properties:
        button:
          type: string
          description: Mouse button to interact with
          enum: [left, right, middle, back, forward]
        click_type:
          type: string
          description: Type of click action
          enum: [down, up, click]
        x:
          type: integer
          description: X coordinate of the click position
        y:
          type: integer
          description: Y coordinate of the click position
        hold_keys:
          type: array
          description: Modifier keys to hold during the click
          items:
            type: string
        num_clicks:
          type: integer
          description: Number of times to repeat the click
          default: 1
      additionalProperties: false
    MoveMouseRequest:
      type: object
      required:
        - x
        - y
      properties:
        x:
          type: integer
          description: X coordinate to move the cursor to
        y:
          type: integer
          description: Y coordinate to move the cursor to
        hold_keys:
          type: array
          description: Modifier keys to hold during the move
          items:
            type: string
        smooth:
          type: boolean
          description: Use human-like Bezier curve path instead of instant mouse movement.
          default: true
        duration_ms:
          type: integer
          description: Target total duration in milliseconds for the mouse movement when smooth=true. Omit for automatic timing based on distance.
          minimum: 50
          maximum: 5000
      additionalProperties: false
    ScreenshotRegion:
      type: object
      required:
        - x
        - y
        - width
        - height
      properties:
        x:
          type: integer
          description: X coordinate of the region's top-left corner
        y:
          type: integer
          description: Y coordinate of the region's top-left corner
        width:
          type: integer
          description: Width of the region in pixels
        height:
          type: integer
          description: Height of the region in pixels
      additionalProperties: false
    ScreenshotRequest:
      type: object
      properties:
        region:
          $ref: "#/components/schemas/ScreenshotRegion"
      additionalProperties: false
    SetCursorRequest:
      type: object
      required:
        - hidden
      properties:
        hidden:
          type: boolean
          description: Whether the cursor should be hidden
      additionalProperties: false
    MousePositionResponse:
      type: object
      required:
        - x
        - y
      properties:
        x:
          type: integer
          description: X coordinate of the cursor
        y:
          type: integer
          description: Y coordinate of the cursor
    TypeTextRequest:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          description: Text to type on the host computer
        delay:
          type: integer
          description: Delay in milliseconds between keystrokes. Ignored when smooth is true.
          minimum: 0
          default: 0
        smooth:
          type: boolean
          description: |
            Use human-like variable keystroke timing instead of a fixed delay.
            Defaults to true (same as moveMouse/dragMouse). Set to false for
            xdotool typing with an optional fixed delay between keys (delay=0 is instant).
            When true, text is typed in word-sized chunks with variable intra-word delays
            and natural inter-word pauses. The delay field is ignored when smooth is true.
          default: true
        typo_chance:
          type: number
          description: |
            Per-character typo injection rate; mistakes are corrected with backspace.
            Default 0. Only applies when smooth is true (silently ignored when
            smooth is false).
          minimum: 0
          maximum: 0.10
          default: 0
      additionalProperties: false
    ClipboardContent:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          description: Current clipboard text content
      additionalProperties: false
    WriteClipboardRequest:
      type: object
      required:
        - text
      properties:
        text:
          type: string
          description: Text to write to the system clipboard
      additionalProperties: false
    PressKeyRequest:
      type: object
      required:
        - keys
      properties:
        keys:
          type: array
          description: |
            List of key symbols to press. Each item should be a key symbol supported by xdotool
            (see X11 keysym definitions). Examples include "Return", "Shift", "Ctrl", "Alt", "F5".
            Items in this list could also be combinations, e.g. "Ctrl+t" or "Ctrl+Shift+Tab".
          items:
            type: string
        duration:
          type: integer
          description: Duration to hold the keys down in milliseconds. If omitted or 0, keys are tapped.
          minimum: 0
          default: 0
        hold_keys:
          type: array
          description: Optional modifier keys to hold during the key press sequence.
          items:
            type: string
      additionalProperties: false
    ScrollRequest:
      type: object
      required:
        - x
        - y
      properties:
        x:
          type: integer
          description: X coordinate at which to perform the scroll
        y:
          type: integer
          description: Y coordinate at which to perform the scroll
        delta_x:
          type: integer
          description: Horizontal scroll amount. Positive scrolls right, negative scrolls left.
          default: 0
        delta_y:
          type: integer
          description: Vertical scroll amount. Positive scrolls down, negative scrolls up.
          default: 0
        hold_keys:
          type: array
          description: Modifier keys to hold during the scroll
          items:
            type: string
      additionalProperties: false
    DragMouseRequest:
      type: object
      required:
        - path
      properties:
        path:
          type: array
          description: Ordered list of [x, y] coordinate pairs to move through while dragging. Must contain at least 2 points.
          minItems: 2
          items:
            type: array
            minItems: 2
            maxItems: 2
            items:
              type: integer
        button:
          type: string
          description: Mouse button to drag with
          enum: [left, middle, right]
        delay:
          type: integer
          description: Delay in milliseconds between button down and starting to move along the path.
          minimum: 0
          default: 0
        steps_per_segment:
          type: integer
          description: Number of relative move steps per segment in the path. Ignored when smooth=true. Minimum 1.
          minimum: 1
          default: 10
        step_delay_ms:
          type: integer
          description: Delay in milliseconds between relative steps while dragging. Ignored when smooth=true.
          minimum: 0
          default: 50
        smooth:
          type: boolean
          description: Use human-like Bezier curves between path waypoints instead of linear interpolation. When true, steps_per_segment and step_delay_ms are ignored.
          default: true
        duration_ms:
          type: integer
          description: Target total duration in milliseconds for the entire drag movement when smooth=true. Omit for automatic timing based on total path length.
          minimum: 50
          maximum: 10000
        hold_keys:
          type: array
          description: Modifier keys to hold during the drag
          items:
            type: string
      additionalProperties: false
    StartFsWatchRequest:
      type: object
      required:
        - path
      properties:
        path:
          type: string
          description: Directory to watch.
        recursive:
          type: boolean
          description: Whether to watch recursively.
          default: false
      additionalProperties: false
    FileSystemEvent:
      type: object
      description: Filesystem change event.
      required: [type, path]
      properties:
        type:
          type: string
          enum: [CREATE, WRITE, DELETE, RENAME]
          description: Event type.
        name:
          type: string
          description: Base name of the file or directory affected.
        path:
          type: string
          description: Absolute path of the file or directory.
        is_dir:
          type: boolean
          description: Whether the affected path is a directory.
    DeleteRecordingRequest:
      type: object
      properties:
        id:
          type: string
          description: Identifier of the recording session to delete, as passed to /recording/start. Alphanumeric or hyphen. When omitted, the default recording session is deleted.
          pattern: "^[a-zA-Z0-9-]+$"
      additionalProperties: false
    MarkRecordingRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: Name of the marker, used as the MP4 chapter title.
          minLength: 1
          maxLength: 200
        id:
          type: string
          description: Identifier of the recording session to mark, as passed to /recording/start. Alphanumeric or hyphen. When omitted, the marker is added to the default recording session.
          pattern: "^[a-zA-Z0-9-]+$"
      additionalProperties: false
    MarkRecordingResult:
      type: object
      required: [name, offset_ms]
      properties:
        name:
          type: string
          description: Name of the recorded marker.
        offset_ms:
          type: integer
          format: int64
          description: >-
            Provisional offset of the marker from the recording start, in
            milliseconds, measured against the start time at mark time. The
            authoritative offset is the chapter start written at finalize.
      additionalProperties: false
    FileInfo:
      type: object
      required: [name, path, size_bytes, is_dir, mod_time, mode]
      properties:
        name:
          type: string
          description: Base name of the file or directory.
        path:
          type: string
          description: Absolute path.
        size_bytes:
          type: integer
          description: Size in bytes. 0 for directories.
        is_dir:
          type: boolean
          description: Whether the path is a directory.
        mod_time:
          type: string
          format: date-time
          description: Last modification time.
        mode:
          type: string
          description: File mode bits (e.g., "drwxr-xr-x" or "-rw-r--r--").

    ListFiles:
      type: array
      description: Array of file or directory information entries.
      items:
        $ref: "#/components/schemas/FileInfo"

    CreateDirectoryRequest:
      type: object
      required: [path]
      properties:
        path:
          type: string
          description: Absolute directory path to create.
          pattern: "^/.*"
        mode:
          type: string
          description: Optional directory mode (octal string, e.g. 755). Defaults to 755.
          pattern: "^[0-7]{3,4}$"
      additionalProperties: false

    DeletePathRequest:
      type: object
      required: [path]
      properties:
        path:
          type: string
          description: Absolute path to delete.
          pattern: "^/.*"
      additionalProperties: false

    SetFilePermissionsRequest:
      type: object
      required: [path, mode]
      properties:
        path:
          type: string
          description: Absolute path whose permissions are to be changed.
          pattern: "^/.*"
        owner:
          type: string
          description: New owner username or UID.
        group:
          type: string
          description: New group name or GID.
        mode:
          type: string
          description: File mode bits (octal string, e.g. 644).
          pattern: "^[0-7]{3,4}$"
      additionalProperties: false

    MovePathRequest:
      type: object
      required: [src_path, dest_path]
      properties:
        src_path:
          type: string
          description: Absolute source path.
          pattern: "^/.*"
        dest_path:
          type: string
          description: Absolute destination path.
          pattern: "^/.*"
      additionalProperties: false
    ProcessExecRequest:
      type: object
      description: Request to execute a command synchronously.
      required: [command]
      properties:
        command:
          type: string
          description: Executable or shell command to run.
        args:
          type: array
          description: Command arguments.
          items:
            type: string
          default: []
        cwd:
          type: [string, "null"]
          description: Working directory (absolute path) to run the command in.
          pattern: "^/.*"
        env:
          type: object
          description: Environment variables to set for the process.
          additionalProperties:
            type: string
          default: {}
        as_user:
          type: [string, "null"]
          description: Run the process as this user.
        as_root:
          type: boolean
          description: Run the process with root privileges.
          default: false
        timeout_sec:
          type: [integer, "null"]
          description: Maximum execution time in seconds.
      additionalProperties: false
    ProcessExecResult:
      type: object
      description: Result of a synchronous command execution.
      properties:
        exit_code:
          type: integer
          description: Process exit code.
        stdout_b64:
          type: string
          description: Base64-encoded stdout buffer.
        stderr_b64:
          type: string
          description: Base64-encoded stderr buffer.
        duration_ms:
          type: integer
          description: Execution duration in milliseconds.
      additionalProperties: false
    ProcessSpawnRequest:
      allOf:
        - $ref: "#/components/schemas/ProcessExecRequest"
        - type: object
          properties:
            allocate_tty:
              type: boolean
              description: Allocate a pseudo-terminal (PTY) for the process to enable interactive shells.
              default: false
            rows:
              type: integer
              description: Initial terminal rows when allocate_tty is true.
              minimum: 1
            cols:
              type: integer
              description: Initial terminal columns when allocate_tty is true.
              minimum: 1
    ProcessSpawnResult:
      type: object
      description: Information about a spawned process.
      properties:
        process_id:
          type: string
          format: uuid
          description: Server-assigned identifier for the process.
        pid:
          type: integer
          description: OS process ID.
        started_at:
          type: string
          format: date-time
          description: Timestamp when the process started.
      additionalProperties: false
    ProcessResizeRequest:
      type: object
      description: Resize a PTY-backed process.
      required: [rows, cols]
      properties:
        rows:
          type: integer
          minimum: 1
          description: New terminal rows.
        cols:
          type: integer
          minimum: 1
          description: New terminal columns.
      additionalProperties: false
    ProcessStatus:
      type: object
      description: Current status of a process.
      properties:
        state:
          type: string
          enum: [running, exited]
          description: Process state.
        exit_code:
          type: [integer, "null"]
          description: Exit code if the process has exited.
        cpu_pct:
          type: number
          description: Estimated CPU usage percentage.
        mem_bytes:
          type: integer
          description: Estimated resident memory usage in bytes.
      additionalProperties: false
    ProcessStdinRequest:
      type: object
      description: Data to write to the process standard input.
      required: [data_b64]
      properties:
        data_b64:
          type: string
          description: Base64-encoded data to write.
      additionalProperties: false
    ProcessStdinResult:
      type: object
      description: Result of writing to stdin.
      properties:
        written_bytes:
          type: integer
          description: Number of bytes written.
      additionalProperties: false
    ProcessKillRequest:
      type: object
      description: Signal to send to the process.
      required: [signal]
      properties:
        signal:
          type: string
          enum: [TERM, KILL, INT, HUP]
          default: TERM
          description: Signal to send.
      additionalProperties: false
    ProcessStreamEvent:
      type: object
      description: SSE payload representing process output or lifecycle events.
      properties:
        stream:
          type: string
          description: Source stream of the data chunk.
          enum: [stdout, stderr]
        data_b64:
          type: string
          description: Base64-encoded data from the process stream.
        event:
          type: string
          description: Lifecycle event type.
          enum: [exit]
        exit_code:
          type: integer
          description: Exit code when the event is "exit".
      additionalProperties: false
    PatchDisplayRequest:
      type: object
      properties:
        width:
          type: integer
          minimum: 320
          description: Display width in pixels
        height:
          type: integer
          minimum: 240
          description: Display height in pixels
        refresh_rate:
          type: integer
          enum: [60, 30, 25, 10]
          description: Display refresh rate in Hz. If omitted, uses the highest available rate for the resolution.
        require_idle:
          type: boolean
          description: If true, refuse to resize when live view or recording/replay is active.
          default: true
        restart_chromium:
          type: boolean
          description: If true, restart Chromium after resolution change to ensure it adapts to new size. Default is false for headful, true for headless.
      additionalProperties: false
    DisplayConfig:
      type: object
      properties:
        width:
          type: integer
          description: Current display width in pixels
        height:
          type: integer
          description: Current display height in pixels
        refresh_rate:
          type: integer
          description: Current display refresh rate in Hz (may be null if not detectable)
      additionalProperties: false
    LogEvent:
      type: object
      description: A log entry from the application.
      required: [message, timestamp]
      properties:
        timestamp:
          type: string
          format: date-time
          description: Time the log entry was produced.
        message:
          type: string
          description: Log message text.
    OkResponse:
      type: object
      description: Generic OK response.
      required: [ok]
      properties:
        ok:
          type: boolean
          description: Indicates success.
          default: true
      additionalProperties: false
    ExecutePlaywrightRequest:
      type: object
      description: Request to execute Playwright code
      required: [code]
      properties:
        code:
          type: string
          description: |
            TypeScript/JavaScript code to execute. The code has access to 'page', 'context', and 'browser' variables.
            Example: "await page.goto('https://example.com'); return await page.title();"
        timeout_sec:
          type: integer
          description: Maximum execution time in seconds. Default is 60.
          default: 60
          minimum: 1
          maximum: 300
      additionalProperties: false
    ExecutePlaywrightResult:
      type: object
      description: Result of Playwright code execution
      required: [success]
      properties:
        success:
          type: boolean
          description: Whether the code executed successfully
        result:
          description: The value returned by the code (if any)
        error:
          type: string
          description: Error message if execution failed
        stdout:
          type: string
          description: Standard output from the execution
        stderr:
          type: string
          description: Standard error from the execution
      additionalProperties: false
    SleepAction:
      type: object
      description: Pause execution for a specified duration.
      required: [duration_ms]
      properties:
        duration_ms:
          type: integer
          description: Duration to sleep in milliseconds.
          minimum: 0
          maximum: 30000
      additionalProperties: false
    ComputerAction:
      type: object
      description: |
        A single computer action to execute as part of a batch. The `type` field selects which
        action to perform, and the corresponding field contains the action parameters.
        Exactly one action field matching the type must be provided.
      required: [type]
      properties:
        type:
          type: string
          description: The type of action to perform.
          enum: [click_mouse, move_mouse, type_text, press_key, scroll, drag_mouse, set_cursor, sleep]
        click_mouse:
          $ref: "#/components/schemas/ClickMouseRequest"
        move_mouse:
          $ref: "#/components/schemas/MoveMouseRequest"
        type_text:
          $ref: "#/components/schemas/TypeTextRequest"
        press_key:
          $ref: "#/components/schemas/PressKeyRequest"
        scroll:
          $ref: "#/components/schemas/ScrollRequest"
        drag_mouse:
          $ref: "#/components/schemas/DragMouseRequest"
        set_cursor:
          $ref: "#/components/schemas/SetCursorRequest"
        sleep:
          $ref: "#/components/schemas/SleepAction"
      additionalProperties: false
    BatchComputerActionRequest:
      type: object
      description: A batch of computer actions to execute sequentially.
      required: [actions]
      properties:
        actions:
          type: array
          description: Ordered list of actions to execute. Execution stops on the first error.
          minItems: 1
          items:
            $ref: "#/components/schemas/ComputerAction"
      additionalProperties: false
  responses:
    BadRequestError:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    ConflictError:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFoundError:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    InternalError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"