{
  "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.\nThese complement the HTTP API defined in openapi.yaml.\n\nAll messages (both directions) use a standard envelope:\n```json\n{\n  \"type\": \"string (event/command type)\",\n  \"timestamp\": \"ISO 8601 datetime\",\n  \"data\": { ... }\n}\n```\n"
  },
  "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\nrecent requests, then streams new requests as they are captured. Clients\nmay request full details for a specific request or clear the buffer.\n",
      "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\nminimum severity level via query-string parameters. Replays recent\nentries on connect.\n",
      "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\nsensor, reading speed, and throttle interval. Supports subscribing to\ndifferent sensors or changing settings over the same connection.\n",
      "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\nreplay buffered events, filter by event type, and optionally start native\nscanning for the lifetime of the WebSocket connection when supported.\nStreamed events remain in the bounded BLE buffer until evicted by\nretention or cleared via the REST API.\n",
      "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,\nmarkers, and spans from an active profiling session. Use cursor\nparameters to resume from a specific position.\n",
      "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.\n"
              }
            }
          }
        },
        "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\nchanges, visual tree mutations, system alerts, and unhandled exceptions.\nClients subscribe to the event types they are interested in.\n",
      "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.\n"
                  }
                }
              }
            }
          }
        },
        "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\nrequest events as new HTTP traffic is captured. Also sends detail\nresponses and buffer-cleared confirmations in reply to client commands.\n",
      "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\nrequest buffer.\n",
      "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\nparameters), then streams new entries in real time.\n",
      "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\nnotifications, and stop events for device sensors.\n",
      "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,\nor unsubscribe to stop receiving readings.\n",
      "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.\nSends a stopped event when the profiling session ends.\n",
      "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,\nvisual tree mutations, system alerts, and unhandled exceptions.\n",
      "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.\n",
      "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."
          }
        }
      }
    }
  }
}