asyncapi: 3.0.0
info:
  title: DevFlow Agent Protocol — WebSocket Channels
  version: 1.0.0
  description: |
    Real-time streaming channels for the DevFlow Agent Protocol.
    These complement the HTTP API defined in openapi.yaml.

    All messages (both directions) use a standard envelope:
    ```json
    {
      "type": "string (event/command type)",
      "timestamp": "ISO 8601 datetime",
      "data": { ... }
    }
    ```
defaultContentType: application/json
servers:
  agent:
    host: localhost:{port}
    protocol: ws
    description: Agent WebSocket server
    variables:
      port:
        description: Port number the agent is listening on.
channels:
  network:
    address: /ws/v1/network
    description: |
      Real-time stream of captured HTTP requests. On connect the server replays
      recent requests, then streams new requests as they are captured. Clients
      may request full details for a specific request or clear the buffer.
    servers:
      - $ref: '#/servers/agent'
    messages:
      networkReplay:
        name: networkReplay
        title: Network Replay
        summary: Initial replay of recent requests on connect.
        contentType: application/json
        payload:
          type: object
          description: Replay of recent network request entries.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: replay
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              type: object
              required:
                - entries
              properties:
                entries:
                  type: array
                  items:
                    $ref: '#/components/schemas/NetworkRequestSummary'
                  description: Array of recent network request summaries.
      networkRequest:
        name: networkRequest
        title: Network Request Captured
        summary: New HTTP request captured.
        contentType: application/json
        payload:
          type: object
          description: Live network request event.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: request
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              type: object
              required:
                - entry
              properties:
                entry:
                  $ref: '#/components/schemas/NetworkRequestSummary'
                  description: The captured network request summary.
      networkDetails:
        name: networkDetails
        title: Request Details Response
        summary: Full details for a previously captured network request.
        contentType: application/json
        payload:
          type: object
          description: Response containing full request/response details.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: details
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              type: object
              required:
                - entry
              properties:
                entry:
                  $ref: '#/components/schemas/NetworkRequestDetail'
                  description: Full details of the network request.
      networkCleared:
        name: networkCleared
        title: Buffer Cleared
        summary: Server confirms the request buffer has been cleared.
        contentType: application/json
        payload:
          type: object
          description: Confirmation that the request buffer was cleared.
          required:
            - type
            - timestamp
          properties:
            type:
              type: string
              const: cleared
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
      networkGetDetails:
        name: networkGetDetails
        title: Get Request Details
        summary: Request full details for a specific captured network request.
        contentType: application/json
        payload:
          type: object
          description: Command to retrieve full details for a network request.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: get_details
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              type: object
              required:
                - id
              properties:
                id:
                  type: string
                  description: Unique identifier of the network request to retrieve.
      networkClear:
        name: networkClear
        title: Clear Request Buffer
        summary: Clear the server's captured request buffer.
        contentType: application/json
        payload:
          type: object
          description: Command to clear the request buffer.
          required:
            - type
            - timestamp
          properties:
            type:
              type: string
              const: clear
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
  logs:
    address: /ws/v1/logs
    description: |
      Real-time application log streaming. Supports filtering by source and
      minimum severity level via query-string parameters. Replays recent
      entries on connect.
    servers:
      - $ref: '#/servers/agent'
    bindings:
      ws:
        query:
          type: object
          description: Connection query-string parameters for log filtering.
          properties:
            source:
              type: string
              enum:
                - native
                - webview
                - framework
                - all
              default: all
              description: Filter logs by source.
            level:
              type: string
              enum:
                - trace
                - debug
                - info
                - warning
                - error
                - critical
              default: info
              description: Minimum log severity level to stream.
            replay:
              type: integer
              default: 100
              minimum: 0
              description: Number of recent entries to replay on connect.
    messages:
      logReplay:
        name: logReplay
        title: Log Replay
        summary: Initial replay of recent log entries on connect.
        contentType: application/json
        payload:
          type: object
          description: Replay of recent log entries.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: replay
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              type: object
              required:
                - entries
              properties:
                entries:
                  type: array
                  items:
                    $ref: '#/components/schemas/LogEntry'
                  description: Array of recent log entries.
      logEntry:
        name: logEntry
        title: Log Entry
        summary: New log entry from the application.
        contentType: application/json
        payload:
          type: object
          description: Live log entry event.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: log
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              type: object
              required:
                - entry
              properties:
                entry:
                  $ref: '#/components/schemas/LogEntry'
                  description: The log entry.
  sensors:
    address: /ws/v1/device/sensors
    description: |
      Live sensor data streaming. Connect with query parameters to specify the
      sensor, reading speed, and throttle interval. Supports subscribing to
      different sensors or changing settings over the same connection.
    servers:
      - $ref: '#/servers/agent'
    bindings:
      ws:
        query:
          type: object
          description: Connection query-string parameters.
          required:
            - sensor
          properties:
            sensor:
              type: string
              enum:
                - accelerometer
                - barometer
                - compass
                - gyroscope
                - magnetometer
                - orientation
              description: Sensor to subscribe to (required).
            speed:
              type: string
              enum:
                - UI
                - Game
                - Fastest
                - Default
              default: UI
              description: Reading speed preset.
            throttleMs:
              type: integer
              default: 100
              minimum: 0
              description: Minimum milliseconds between readings.
    messages:
      sensorSubscribed:
        name: sensorSubscribed
        title: Sensor Subscribed
        summary: Confirmation that the sensor subscription is active.
        contentType: application/json
        payload:
          type: object
          description: Sensor subscription confirmation.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: subscribed
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              type: object
              required:
                - sensor
                - speed
                - throttleMs
              properties:
                sensor:
                  type: string
                  description: Name of the subscribed sensor.
                speed:
                  type: string
                  description: Active reading speed.
                throttleMs:
                  type: number
                  description: Active throttle interval in milliseconds.
      sensorReading:
        name: sensorReading
        title: Sensor Reading
        summary: New sensor reading.
        contentType: application/json
        payload:
          type: object
          description: Live sensor reading event.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: reading
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              $ref: '#/components/schemas/SensorReading'
              description: Sensor reading data (shape varies by sensor type).
      sensorError:
        name: sensorError
        title: Sensor Error
        summary: Error occurred while reading sensor data.
        contentType: application/json
        payload:
          type: object
          description: Sensor error notification.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: error
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              type: object
              required:
                - sensor
                - message
              properties:
                sensor:
                  type: string
                  description: Name of the sensor that encountered an error.
                message:
                  type: string
                  description: Human-readable error message.
      sensorStopped:
        name: sensorStopped
        title: Sensor Stopped
        summary: Sensor data streaming has stopped.
        contentType: application/json
        payload:
          type: object
          description: Sensor stopped notification.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: stopped
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              type: object
              required:
                - sensor
              properties:
                sensor:
                  type: string
                  description: Name of the sensor that was stopped.
      sensorSubscribe:
        name: sensorSubscribe
        title: Subscribe to Sensor
        summary: Subscribe to a different sensor or change settings.
        contentType: application/json
        payload:
          type: object
          description: Command to subscribe to a sensor or update settings.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: subscribe
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              type: object
              required:
                - sensor
              properties:
                sensor:
                  type: string
                  description: Name of the sensor to subscribe to.
                speed:
                  type: string
                  enum:
                    - UI
                    - Game
                    - Fastest
                    - Default
                  description: Reading speed preset.
                throttleMs:
                  type: integer
                  minimum: 0
                  description: Minimum milliseconds between readings.
      sensorUnsubscribe:
        name: sensorUnsubscribe
        title: Unsubscribe from Sensor
        summary: Stop receiving readings for a sensor.
        contentType: application/json
        payload:
          type: object
          description: Command to unsubscribe from a sensor.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: unsubscribe
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              type: object
              required:
                - sensor
              properties:
                sensor:
                  type: string
                  description: Name of the sensor to unsubscribe from.
  ble:
    address: /ws/v1/ble
    description: |
      Live Bluetooth Low Energy event stream. Connect with query parameters to
      replay buffered events, filter by event type, and optionally start native
      scanning for the lifetime of the WebSocket connection when supported.
      Streamed events remain in the bounded BLE buffer until evicted by
      retention or cleared via the REST API.
    servers:
      - $ref: '#/servers/agent'
    bindings:
      ws:
        query:
          type: object
          description: Connection query-string parameters.
          properties:
            replay:
              type: integer
              default: 100
              minimum: 0
              description: Number of buffered BLE events to replay after subscription. Use 0 for live-only streaming.
            type:
              type: string
              description: Optional BLE event type filter.
            scan:
              type: boolean
              default: false
              description: Start BLE scanning automatically while this WebSocket connection is active.
    messages:
      bleReplay:
        name: bleReplay
        title: BLE Event Replay
        summary: Initial replay of recent BLE events on connect.
        contentType: application/json
        payload:
          type: object
          description: Replay of recent BLE events.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: replay
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              type: object
              required:
                - events
              properties:
                events:
                  type: array
                  items:
                    $ref: '#/components/schemas/BleEvent'
                  description: Buffered BLE events.
      bleEvent:
        name: bleEvent
        title: BLE Event
        summary: New Bluetooth Low Energy event.
        contentType: application/json
        payload:
          type: object
          description: Live BLE event envelope.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: ble_event
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              $ref: '#/components/schemas/BleEvent'
              description: The recorded BLE event.
      bleError:
        name: bleError
        title: BLE Stream Error
        summary: Error occurred while streaming BLE events.
        contentType: application/json
        payload:
          type: object
          description: BLE stream error notification.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: error
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              type: object
              required:
                - message
              properties:
                message:
                  type: string
                  description: Human-readable error message.
  profiler:
    address: /ws/v1/profiler
    description: |
      Real-time profiler data stream. Streams periodic batches of samples,
      markers, and spans from an active profiling session. Use cursor
      parameters to resume from a specific position.
    servers:
      - $ref: '#/servers/agent'
    bindings:
      ws:
        query:
          type: object
          description: Connection query-string parameters.
          required:
            - sessionId
          properties:
            sessionId:
              type: string
              description: Profiler session ID (required).
            sampleCursor:
              type: integer
              default: 0
              minimum: 0
              description: Starting sample cursor position.
            markerCursor:
              type: integer
              default: 0
              minimum: 0
              description: Starting marker cursor position.
            spanCursor:
              type: integer
              default: 0
              minimum: 0
              description: Starting span cursor position.
    messages:
      profilerBatch:
        name: profilerBatch
        title: Profiler Batch
        summary: Periodic batch of profiler samples, markers, and spans.
        contentType: application/json
        payload:
          type: object
          description: Batch of profiler data with updated cursors.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: batch
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              $ref: '#/components/schemas/ProfilerBatch'
              description: |
                Profiler batch containing samples, markers, spans, and updated cursor positions for pagination.
      profilerStopped:
        name: profilerStopped
        title: Profiler Stopped
        summary: Profiling session has ended.
        contentType: application/json
        payload:
          type: object
          description: Notification that a profiling session ended.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: stopped
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              type: object
              required:
                - sessionId
              properties:
                sessionId:
                  type: string
                  description: Identifier of the stopped profiler session.
  uiEvents:
    address: /ws/v1/ui/events
    description: |
      Real-time UI state change notifications including navigation, lifecycle
      changes, visual tree mutations, system alerts, and unhandled exceptions.
      Clients subscribe to the event types they are interested in.
    servers:
      - $ref: '#/servers/agent'
    messages:
      uiNavigation:
        name: uiNavigation
        title: Navigation Event
        summary: Page or screen navigation occurred.
        contentType: application/json
        payload:
          type: object
          description: Navigation event indicating a page or route change.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: navigation
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              type: object
              required:
                - to
                - timestamp
              properties:
                from:
                  type:
                    - string
                    - 'null'
                  description: Route or page navigated away from.
                to:
                  type: string
                  description: Route or page navigated to.
                route:
                  type:
                    - string
                    - 'null'
                  description: Route pattern, if applicable.
                timestamp:
                  $ref: '#/components/schemas/Timestamp'
                  description: Timestamp when the navigation occurred.
      uiLifecycle:
        name: uiLifecycle
        title: Lifecycle Event
        summary: Application lifecycle state change.
        contentType: application/json
        payload:
          type: object
          description: Application lifecycle event.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: lifecycle
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              type: object
              required:
                - state
                - timestamp
              properties:
                state:
                  type: string
                  enum:
                    - started
                    - resumed
                    - paused
                    - stopped
                    - backgrounded
                    - foregrounded
                  description: New lifecycle state.
                timestamp:
                  $ref: '#/components/schemas/Timestamp'
                  description: Timestamp when the lifecycle change occurred.
      uiTreeChange:
        name: uiTreeChange
        title: Tree Change Event
        summary: Visual tree structure changed (element added, removed, or modified).
        contentType: application/json
        payload:
          type: object
          description: Visual tree mutation event.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: treeChange
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              type: object
              required:
                - changeType
                - elementId
                - elementType
                - timestamp
              properties:
                changeType:
                  type: string
                  enum:
                    - added
                    - removed
                    - modified
                  description: Type of tree change.
                elementId:
                  type: string
                  description: Identifier of the changed element.
                elementType:
                  type: string
                  description: Type name of the changed element.
                parentId:
                  type:
                    - string
                    - 'null'
                  description: Identifier of the parent element, or null for root elements.
                timestamp:
                  $ref: '#/components/schemas/Timestamp'
                  description: Timestamp when the tree change occurred.
      uiAlert:
        name: uiAlert
        title: Alert Event
        summary: System alert or dialog appeared.
        contentType: application/json
        payload:
          type: object
          description: System alert / dialog event.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: alert
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              type: object
              required:
                - buttons
                - timestamp
              properties:
                title:
                  type:
                    - string
                    - 'null'
                  description: Alert title.
                message:
                  type:
                    - string
                    - 'null'
                  description: Alert message body.
                buttons:
                  type: array
                  items:
                    type: string
                  description: Labels of the alert buttons.
                timestamp:
                  $ref: '#/components/schemas/Timestamp'
                  description: Timestamp when the alert appeared.
      uiError:
        name: uiError
        title: Unhandled Error Event
        summary: Unhandled exception occurred in the application.
        contentType: application/json
        payload:
          type: object
          description: Unhandled exception event.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: error
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              type: object
              required:
                - message
                - timestamp
              properties:
                message:
                  type: string
                  description: Error message.
                stackTrace:
                  type:
                    - string
                    - 'null'
                  description: Stack trace, if available.
                timestamp:
                  $ref: '#/components/schemas/Timestamp'
                  description: Timestamp when the error occurred.
      uiSubscribe:
        name: uiSubscribe
        title: Subscribe to Events
        summary: Subscribe to specific UI event types.
        contentType: application/json
        payload:
          type: object
          description: Command to subscribe to UI event types.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: subscribe
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              type: object
              required:
                - events
              properties:
                events:
                  type: array
                  items:
                    type: string
                    enum:
                      - navigation
                      - lifecycle
                      - treeChange
                      - alert
                      - error
                      - all
                  description: |
                    Event types to subscribe to. Use "all" to receive every event type.
      uiUnsubscribe:
        name: uiUnsubscribe
        title: Unsubscribe from Events
        summary: Unsubscribe from specific UI event types.
        contentType: application/json
        payload:
          type: object
          description: Command to unsubscribe from UI event types.
          required:
            - type
            - timestamp
            - data
          properties:
            type:
              type: string
              const: unsubscribe
              description: Message type identifier.
            timestamp:
              $ref: '#/components/schemas/Timestamp'
              description: UTC timestamp when this message was produced.
            data:
              type: object
              required:
                - events
              properties:
                events:
                  type: array
                  items:
                    type: string
                    enum:
                      - navigation
                      - lifecycle
                      - treeChange
                      - alert
                      - error
                      - all
                  description: Event types to unsubscribe from.
operations:
  sendNetworkEvents:
    action: send
    channel:
      $ref: '#/channels/network'
    summary: Server streams network request events to the client.
    description: |
      Sends a replay of recent requests on connect, followed by individual
      request events as new HTTP traffic is captured. Also sends detail
      responses and buffer-cleared confirmations in reply to client commands.
    messages:
      - $ref: '#/channels/network/messages/networkReplay'
      - $ref: '#/channels/network/messages/networkRequest'
      - $ref: '#/channels/network/messages/networkDetails'
      - $ref: '#/channels/network/messages/networkCleared'
  receiveNetworkCommands:
    action: receive
    channel:
      $ref: '#/channels/network'
    summary: Client sends commands to the network channel.
    description: |
      Clients can request full details for a captured request or clear the
      request buffer.
    messages:
      - $ref: '#/channels/network/messages/networkGetDetails'
      - $ref: '#/channels/network/messages/networkClear'
  sendLogEvents:
    action: send
    channel:
      $ref: '#/channels/logs'
    summary: Server streams log entries to the client.
    description: |
      Sends a replay of recent log entries on connect (filtered by query-string
      parameters), then streams new entries in real time.
    messages:
      - $ref: '#/channels/logs/messages/logReplay'
      - $ref: '#/channels/logs/messages/logEntry'
  sendSensorEvents:
    action: send
    channel:
      $ref: '#/channels/sensors'
    summary: Server streams sensor data to the client.
    description: |
      Sends subscription confirmation, live sensor readings, error
      notifications, and stop events for device sensors.
    messages:
      - $ref: '#/channels/sensors/messages/sensorSubscribed'
      - $ref: '#/channels/sensors/messages/sensorReading'
      - $ref: '#/channels/sensors/messages/sensorError'
      - $ref: '#/channels/sensors/messages/sensorStopped'
  receiveSensorCommands:
    action: receive
    channel:
      $ref: '#/channels/sensors'
    summary: Client sends sensor subscription commands.
    description: |
      Clients can subscribe to a different sensor or change settings,
      or unsubscribe to stop receiving readings.
    messages:
      - $ref: '#/channels/sensors/messages/sensorSubscribe'
      - $ref: '#/channels/sensors/messages/sensorUnsubscribe'
  sendProfilerEvents:
    action: send
    channel:
      $ref: '#/channels/profiler'
    summary: Server streams profiler data to the client.
    description: |
      Sends periodic batches of profiler samples, markers, and spans.
      Sends a stopped event when the profiling session ends.
    messages:
      - $ref: '#/channels/profiler/messages/profilerBatch'
      - $ref: '#/channels/profiler/messages/profilerStopped'
  sendUIEvents:
    action: send
    channel:
      $ref: '#/channels/uiEvents'
    summary: Server streams UI lifecycle events to the client.
    description: |
      Sends real-time notifications for navigation, lifecycle changes,
      visual tree mutations, system alerts, and unhandled exceptions.
    messages:
      - $ref: '#/channels/uiEvents/messages/uiNavigation'
      - $ref: '#/channels/uiEvents/messages/uiLifecycle'
      - $ref: '#/channels/uiEvents/messages/uiTreeChange'
      - $ref: '#/channels/uiEvents/messages/uiAlert'
      - $ref: '#/channels/uiEvents/messages/uiError'
  receiveUICommands:
    action: receive
    channel:
      $ref: '#/channels/uiEvents'
    summary: Client sends subscription commands for UI events.
    description: |
      Clients can subscribe or unsubscribe to specific UI event types.
    messages:
      - $ref: '#/channels/uiEvents/messages/uiSubscribe'
      - $ref: '#/channels/uiEvents/messages/uiUnsubscribe'
components:
  schemas:
    Timestamp:
      type: string
      format: date-time
      description: ISO 8601 date-time timestamp.
    NetworkRequestSummary:
      type: object
      description: Summary of a captured network request with key metadata and timing.
      required:
        - id
        - timestamp
        - method
        - url
      properties:
        id:
          type: string
          description: Unique identifier for this network request.
        timestamp:
          $ref: '#/components/schemas/Timestamp'
          description: UTC timestamp when the request was initiated.
        method:
          type: string
          description: HTTP method (e.g. 'GET', 'POST', 'PUT', 'DELETE').
        url:
          type: string
          format: uri
          description: Full URL of the request.
        host:
          type:
            - string
            - 'null'
          description: Hostname portion of the URL.
        path:
          type:
            - string
            - 'null'
          description: Path portion of the URL.
        statusCode:
          type:
            - integer
            - 'null'
          description: HTTP status code of the response, or null if the request has not completed.
          minimum: 100
          maximum: 599
        statusText:
          type:
            - string
            - 'null'
          description: HTTP status text of the response (e.g. 'OK', 'Not Found').
        durationMs:
          type:
            - number
            - 'null'
          description: Total request/response duration in milliseconds.
          minimum: 0
        error:
          type:
            - string
            - 'null'
          description: Error message if the request failed.
        requestContentType:
          type:
            - string
            - 'null'
          description: Content-Type header of the request.
        responseContentType:
          type:
            - string
            - 'null'
          description: Content-Type header of the response.
        requestSize:
          type:
            - integer
            - 'null'
          description: Size of the request body in bytes.
          minimum: 0
        responseSize:
          type:
            - integer
            - 'null'
          description: Size of the response body in bytes.
          minimum: 0
    NetworkRequestDetail:
      description: Detailed view of a captured network request including headers and body content.
      allOf:
        - $ref: '#/components/schemas/NetworkRequestSummary'
        - type: object
          properties:
            requestHeaders:
              type:
                - object
                - 'null'
              additionalProperties:
                type: string
              description: Request headers as key-value pairs. Agents should redact sensitive values such as Authorization, Cookie, Set-Cookie, and Proxy-Authorization by default.
            responseHeaders:
              type:
                - object
                - 'null'
              additionalProperties:
                type: string
              description: Response headers as key-value pairs. Agents should redact sensitive values such as Authorization, Cookie, Set-Cookie, and Proxy-Authorization by default.
            requestBody:
              type:
                - string
                - 'null'
              description: Request body content as a string.
            responseBody:
              type:
                - string
                - 'null'
              description: Response body content as a string.
            requestBodyEncoding:
              type:
                - string
                - 'null'
              description: Encoding of the request body (e.g. 'utf-8', 'base64').
            responseBodyEncoding:
              type:
                - string
                - 'null'
              description: Encoding of the response body (e.g. 'utf-8', 'base64').
            requestBodyTruncated:
              type:
                - boolean
                - 'null'
              description: Whether the request body was truncated due to size limits.
            responseBodyTruncated:
              type:
                - boolean
                - 'null'
              description: Whether the response body was truncated due to size limits.
    LogEntry:
      type: object
      description: A single log entry from the application.
      required:
        - timestamp
        - level
        - category
        - message
        - source
      properties:
        timestamp:
          $ref: '#/components/schemas/Timestamp'
          description: UTC timestamp when the log entry was recorded.
        level:
          type: string
          enum:
            - trace
            - debug
            - info
            - warning
            - error
            - critical
          description: Severity level of the log entry.
        category:
          type: string
          description: Log category or logger name (e.g. 'Microsoft.Maui.Controls', 'HttpClient', 'App').
        message:
          type: string
          description: The log message text.
        exception:
          type:
            - string
            - 'null'
          description: Exception details if the log entry is associated with an error.
        source:
          type: string
          enum:
            - native
            - webview
            - framework
          description: Origin of the log entry.
    SensorReading:
      type: object
      description: A reading from a device sensor. The values object varies by sensor type.
      required:
        - sensor
        - timestamp
        - values
      properties:
        sensor:
          type: string
          description: Name of the sensor that produced this reading.
        timestamp:
          $ref: '#/components/schemas/Timestamp'
          description: UTC timestamp when the reading was taken.
        values:
          type: object
          additionalProperties: true
          description: 'Sensor-specific values. Common shapes: {x, y, z} for accelerometer/gyroscope/magnetometer, {heading, accuracy} for compass, {pressure} for barometer.'
    BleEventType:
      type: string
      description: BLE event type recorded by the monitor. Agents may also record custom app-defined event types.
      examples:
        - scan_result
        - connected
        - disconnected
        - read
        - write
        - notification
        - scan_error
    BleEvent:
      type: object
      description: A Bluetooth Low Energy event recorded by the monitor.
      required:
        - type
        - timestamp
      properties:
        type:
          $ref: '#/components/schemas/BleEventType'
        timestamp:
          $ref: '#/components/schemas/Timestamp'
        deviceId:
          type: string
          description: Platform device identifier, such as a Bluetooth address or UUID.
        deviceName:
          type: string
          description: Device display name, if available.
        rssi:
          type: integer
          description: Received signal strength in dBm, when available.
        serviceUuids:
          type: array
          items:
            type: string
          description: Advertised service UUIDs, when available.
        characteristicUuid:
          type: string
          description: Characteristic UUID for read, write, or notification events.
        valueBase64:
          type: string
          contentEncoding: base64
          description: Characteristic value encoded as base64, when present.
        message:
          type: string
          description: Human-readable event message.
        error:
          type: string
          description: Human-readable error message for error events.
        metadata:
          type: object
          additionalProperties: true
          description: Platform-specific BLE event metadata.
      additionalProperties: true
    ProfilerSample:
      type: object
      description: A single profiler sample capturing a point-in-time snapshot of performance metrics.
      required:
        - tsUtc
      properties:
        tsUtc:
          $ref: '#/components/schemas/Timestamp'
          description: UTC timestamp when this sample was captured.
        fps:
          type:
            - number
            - 'null'
          description: Frames per second at the time of sampling.
          minimum: 0
        frameTimeMsP50:
          type:
            - number
            - 'null'
          description: Median (P50) frame time in milliseconds.
          minimum: 0
        frameTimeMsP95:
          type:
            - number
            - 'null'
          description: 95th percentile (P95) frame time in milliseconds.
          minimum: 0
        worstFrameTimeMs:
          type:
            - number
            - 'null'
          description: Worst (maximum) frame time in milliseconds during the sample interval.
          minimum: 0
        managedBytes:
          type:
            - integer
            - 'null'
          description: Managed heap memory usage in bytes.
          minimum: 0
        gc0:
          type:
            - integer
            - 'null'
          description: Number of generation 0 garbage collections since last sample.
          minimum: 0
        gc1:
          type:
            - integer
            - 'null'
          description: Number of generation 1 garbage collections since last sample.
          minimum: 0
        gc2:
          type:
            - integer
            - 'null'
          description: Number of generation 2 garbage collections since last sample.
          minimum: 0
        nativeMemoryBytes:
          type:
            - integer
            - 'null'
          description: Native (unmanaged) memory usage in bytes.
          minimum: 0
        nativeMemoryKind:
          type:
            - string
            - 'null'
          description: Kind of native memory measurement (e.g. 'resident', 'virtual', 'private').
        cpuPercent:
          type:
            - number
            - 'null'
          description: CPU usage percentage at the time of sampling.
          minimum: 0
          maximum: 100
        threadCount:
          type:
            - integer
            - 'null'
          description: Total number of threads in the process.
          minimum: 0
        jankFrameCount:
          type:
            - integer
            - 'null'
          description: Number of janky (dropped/slow) frames since last sample.
          minimum: 0
        uiThreadStallCount:
          type:
            - integer
            - 'null'
          description: Number of UI thread stalls since last sample.
          minimum: 0
        frameSource:
          type:
            - string
            - 'null'
          description: Source of frame timing data (e.g. 'choreographer', 'displayLink', 'estimated').
        frameQuality:
          type:
            - string
            - 'null'
          description: Qualitative assessment of frame quality (e.g. 'smooth', 'mild-jank', 'severe-jank').
    ProfilerMarker:
      type: object
      description: A discrete profiler marker event representing a notable occurrence.
      required:
        - tsUtc
        - type
        - name
      properties:
        tsUtc:
          $ref: '#/components/schemas/Timestamp'
          description: UTC timestamp when this marker was recorded.
        type:
          type: string
          description: Marker type category (e.g. 'gc', 'layout', 'navigation', 'user').
        name:
          type: string
          description: Human-readable name of the marker event.
        payloadJson:
          type:
            - string
            - 'null'
          description: Optional JSON-encoded payload with additional marker data.
    ProfilerSpan:
      type: object
      description: A profiler span representing a timed operation, compatible with OpenTelemetry span semantics.
      required:
        - spanId
        - startTsUtc
        - durationMs
        - kind
        - name
      properties:
        spanId:
          type: string
          description: Unique identifier for this span.
        parentSpanId:
          type:
            - string
            - 'null'
          description: Identifier of the parent span, or null for root spans.
        traceId:
          type:
            - string
            - 'null'
          description: Trace identifier grouping related spans.
        startTsUtc:
          $ref: '#/components/schemas/Timestamp'
          description: UTC timestamp when this span started.
        endTsUtc:
          oneOf:
            - $ref: '#/components/schemas/Timestamp'
            - type: 'null'
          description: UTC timestamp when this span ended, or null if still in progress.
        durationMs:
          type: number
          description: Duration of the span in milliseconds.
          minimum: 0
        kind:
          type: string
          description: Kind of span (e.g. 'layout', 'render', 'navigation', 'network', 'user').
        name:
          type: string
          description: Human-readable name describing the operation.
        status:
          type:
            - string
            - 'null'
          description: Span status (e.g. 'ok', 'error', 'cancelled').
        threadId:
          type:
            - string
            - 'null'
          description: Identifier of the thread this span executed on.
        screen:
          type:
            - string
            - 'null'
          description: Screen or page name where this span occurred.
        elementPath:
          type:
            - string
            - 'null'
          description: Path to the element in the visual tree associated with this span.
        tagsJson:
          type:
            - string
            - 'null'
          description: Optional JSON-encoded tags with additional span metadata.
        error:
          type:
            - string
            - 'null'
          description: Error message if the span ended with an error.
    ProfilerBatch:
      type: object
      description: A batch of profiler data including samples, markers, and spans with cursor positions for pagination.
      required:
        - sessionId
        - samples
        - markers
        - spans
        - sampleCursor
        - markerCursor
        - spanCursor
        - isActive
      properties:
        sessionId:
          type: string
          description: Identifier of the profiler session this batch belongs to.
        samples:
          type: array
          items:
            $ref: '#/components/schemas/ProfilerSample'
          description: Array of profiler samples in this batch.
        markers:
          type: array
          items:
            $ref: '#/components/schemas/ProfilerMarker'
          description: Array of profiler markers in this batch.
        spans:
          type: array
          items:
            $ref: '#/components/schemas/ProfilerSpan'
          description: Array of profiler spans in this batch.
        sampleCursor:
          type: integer
          description: Cursor position for the next page of samples.
          minimum: 0
        markerCursor:
          type: integer
          description: Cursor position for the next page of markers.
          minimum: 0
        spanCursor:
          type: integer
          description: Cursor position for the next page of spans.
          minimum: 0
        isActive:
          type: boolean
          description: Whether the profiler session is still actively collecting data.