openapi: 3.1.0
info:
  title: DevFlow Agent Protocol
  version: 1.0.0
  description: |
    Framework-agnostic protocol for runtime app inspection, interaction, and debugging. Supports any UI framework (MAUI, React Native, Flutter, native Android/iOS, etc.).
  license:
    name: Ailoha Binary Distribution License
    url: https://ailoha.dev/license.html
servers:
  - url: http://localhost:{port}
    description: Agent HTTP server running inside the target application
    variables:
      port:
        default: '9233'
        description: Port the agent is listening on
tags:
  - name: agent
    description: Agent discovery and status
  - name: ui
    description: UI tree inspection, element queries, screenshots
  - name: ui-actions
    description: UI interaction (tap, fill, scroll, gestures, etc.)
  - name: webview
    description: WebView inspection and interaction
  - name: profiler
    description: Performance profiling
  - name: network
    description: Network request monitoring
  - name: logs
    description: Application logs
  - name: device
    description: Device info, sensors, BLE, jobs, permissions, geolocation
  - name: storage
    description: Preferences, secure storage, and sandboxed app files
  - name: extensions
    description: Third-party extension routes
paths:
  /api/v1/agent/status:
    get:
      operationId: getAgentStatus
      tags:
        - agent
      summary: Get agent status
      description: |
        Returns the agent's identity, platform, version, and running state.
      responses:
        '200':
          description: Agent status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/agent-status'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/agent/capabilities:
    get:
      operationId: getAgentCapabilities
      tags:
        - agent
      summary: Get agent capabilities
      description: |
        Returns the capabilities and extensions supported by this agent.
      responses:
        '200':
          description: Agent capabilities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/agent-capabilities'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/ui/tree:
    get:
      operationId: getUiTree
      tags:
        - ui
      summary: Get visual tree
      description: |
        Returns the full visual tree of the application. Windows are root nodes. Use query parameters to limit depth, select a tree layer, or scope to a subtree.
      parameters:
        - name: depth
          in: query
          description: Maximum depth of the tree to return. Unlimited if omitted.
          schema:
            type: integer
            minimum: 0
        - name: layer
          in: query
          description: Which tree layer to return.
          schema:
            type: string
            enum:
              - framework
              - native
              - render
            default: framework
        - name: rootId
          in: query
          description: Element ID to scope the tree to a subtree.
          schema:
            type: string
        - name: include
          in: query
          description: Additional data to include with each element.
          schema:
            type: array
            items:
              type: string
              enum:
                - properties
          style: form
          explode: false
      responses:
        '200':
          description: Array of root elements (windows) with their children.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/element-info'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/ui/elements/{id}:
    get:
      operationId: getElement
      tags:
        - ui
      summary: Get element by ID
      description: |
        Returns a single element by its globally unique identifier.
      parameters:
        - $ref: '#/components/parameters/ElementIdPath'
      responses:
        '200':
          description: The requested element.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/element-info'
        '404':
          $ref: '#/components/responses/ElementNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/ui/elements:
    get:
      operationId: queryElements
      tags:
        - ui
      summary: Query elements with locator strategies
      description: |
        Searches the visual tree for elements matching the given locator strategy and value.
      parameters:
        - name: strategy
          in: query
          required: true
          description: Locator strategy to use.
          schema:
            $ref: '#/components/schemas/LocatorStrategy'
        - name: value
          in: query
          required: true
          description: Locator value.
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of results.
          schema:
            type: integer
            minimum: 1
            default: 10
        - name: include
          in: query
          description: Additional data to include with each element.
          schema:
            type: array
            items:
              type: string
              enum:
                - properties
                - bounds
          style: form
          explode: false
      responses:
        '200':
          description: Matching elements.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/element-info'
        '400':
          $ref: '#/components/responses/InvalidSelector'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/ui/hit-test:
    get:
      operationId: hitTest
      tags:
        - ui
      summary: Find element at coordinates
      description: |
        Returns the elements at the given screen coordinates, ordered deepest first (innermost element first).
      parameters:
        - name: x
          in: query
          required: true
          description: X coordinate.
          schema:
            type: number
        - name: 'y'
          in: query
          required: true
          description: Y coordinate.
          schema:
            type: number
      responses:
        '200':
          description: Elements at the given coordinates (deepest first).
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/element-info'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/ui/screenshot:
    get:
      operationId: captureScreenshot
      tags:
        - ui
      summary: Capture screenshot
      description: |
        Captures a screenshot of the entire screen or a specific element.
      parameters:
        - name: elementId
          in: query
          description: Element to screenshot. If omitted, captures the full screen.
          schema:
            type: string
        - name: maxWidth
          in: query
          description: Maximum width in pixels. The image is scaled down if wider.
          schema:
            type: integer
            minimum: 1
        - name: scale
          in: query
          description: |
            Scale mode. `native` returns at device pixel density; `auto` returns a reasonable size for agent consumption.
          schema:
            type: string
            enum:
              - native
              - auto
            default: auto
        - name: format
          in: query
          description: Image format.
          schema:
            type: string
            enum:
              - png
              - jpeg
            default: png
      responses:
        '200':
          description: Screenshot image.
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/ElementNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/ui/actions/tap:
    post:
      operationId: tapElement
      tags:
        - ui-actions
      summary: Tap element or coordinates
      description: |
        Taps on an element (by ID) or at absolute coordinates.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TapRequest'
      responses:
        '200':
          $ref: '#/components/responses/ActionSuccess'
        '400':
          $ref: '#/components/responses/ElementNotInteractable'
        '404':
          $ref: '#/components/responses/ElementNotFound'
        '408':
          $ref: '#/components/responses/Timeout'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/ui/actions/fill:
    post:
      operationId: fillElement
      tags:
        - ui-actions
      summary: Fill text into element
      description: |
        Clears any existing text and fills the element with the given text.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FillRequest'
      responses:
        '200':
          $ref: '#/components/responses/ActionSuccess'
        '400':
          $ref: '#/components/responses/ElementNotInteractable'
        '404':
          $ref: '#/components/responses/ElementNotFound'
        '408':
          $ref: '#/components/responses/Timeout'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/ui/actions/clear:
    post:
      operationId: clearElement
      tags:
        - ui-actions
      summary: Clear text from element
      description: |
        Clears any text content from the specified element.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClearRequest'
      responses:
        '200':
          $ref: '#/components/responses/ActionSuccess'
        '400':
          $ref: '#/components/responses/ElementNotInteractable'
        '404':
          $ref: '#/components/responses/ElementNotFound'
        '408':
          $ref: '#/components/responses/Timeout'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/ui/actions/focus:
    post:
      operationId: focusElement
      tags:
        - ui-actions
      summary: Focus element
      description: |
        Gives keyboard focus to the specified element.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FocusRequest'
      responses:
        '200':
          $ref: '#/components/responses/ActionSuccess'
        '400':
          $ref: '#/components/responses/ElementNotInteractable'
        '404':
          $ref: '#/components/responses/ElementNotFound'
        '408':
          $ref: '#/components/responses/Timeout'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/ui/actions/scroll:
    post:
      operationId: scrollElement
      tags:
        - ui-actions
      summary: Scroll element
      description: |
        Scrolls an element by delta, to an item index, or to a named position.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScrollRequest'
      responses:
        '200':
          $ref: '#/components/responses/ActionSuccess'
        '400':
          $ref: '#/components/responses/ElementNotInteractable'
        '404':
          $ref: '#/components/responses/ElementNotFound'
        '408':
          $ref: '#/components/responses/Timeout'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/ui/actions/navigate:
    post:
      operationId: navigateRoute
      tags:
        - ui-actions
      summary: Navigate to route
      description: |
        Navigates the application to the specified route or page.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NavigateRequest'
      responses:
        '200':
          $ref: '#/components/responses/ActionSuccess'
        '408':
          $ref: '#/components/responses/Timeout'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/ui/actions/resize:
    post:
      operationId: resizeWindow
      tags:
        - ui-actions
      summary: Resize window
      description: |
        Resizes a window or element to the given dimensions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResizeRequest'
      responses:
        '200':
          $ref: '#/components/responses/ActionSuccess'
        '404':
          $ref: '#/components/responses/ElementNotFound'
        '408':
          $ref: '#/components/responses/Timeout'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/ui/actions/back:
    post:
      operationId: goBack
      tags:
        - ui-actions
      summary: Go back
      description: |
        Performs a back navigation gesture in the application.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BackRequest'
      responses:
        '200':
          $ref: '#/components/responses/ActionSuccess'
        '408':
          $ref: '#/components/responses/Timeout'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/ui/actions/key:
    post:
      operationId: pressKey
      tags:
        - ui-actions
      summary: Press key
      description: |
        Sends a key press event to the focused element or the application.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeyRequest'
      responses:
        '200':
          $ref: '#/components/responses/ActionSuccess'
        '408':
          $ref: '#/components/responses/Timeout'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/ui/actions/gesture:
    post:
      operationId: performGesture
      tags:
        - ui-actions
      summary: Perform complex gesture
      description: |
        Executes a sequence of pointer actions (move, down, up, pause) to perform complex gestures like swipe, pinch, or drag.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GestureRequest'
      responses:
        '200':
          $ref: '#/components/responses/ActionSuccess'
        '408':
          $ref: '#/components/responses/Timeout'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/ui/actions/batch:
    post:
      operationId: batchActions
      tags:
        - ui-actions
      summary: Execute batch actions
      description: |
        Executes multiple actions in sequence. Optionally continues on error.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          $ref: '#/components/responses/ActionSuccess'
        '408':
          $ref: '#/components/responses/Timeout'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/ui/elements/{id}/properties/{name}:
    get:
      operationId: getElementProperty
      tags:
        - ui
      summary: Get element property value
      description: |
        Returns the current value of a named property on an element.
      parameters:
        - $ref: '#/components/parameters/ElementIdPath'
        - name: name
          in: path
          required: true
          description: Property name.
          schema:
            type: string
      responses:
        '200':
          description: Property value.
          content:
            application/json:
              schema:
                type: object
                required:
                  - value
                properties:
                  value: {}
        '404':
          $ref: '#/components/responses/ElementNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: setElementProperty
      tags:
        - ui
      summary: Set element property value
      description: |
        Sets the value of a named property on an element and returns the new value.
      parameters:
        - $ref: '#/components/parameters/ElementIdPath'
        - name: name
          in: path
          required: true
          description: Property name.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - value
              properties:
                value:
                  description: The value to set.
      responses:
        '200':
          description: The new property value after setting.
          content:
            application/json:
              schema:
                type: object
                required:
                  - value
                properties:
                  value: {}
        '404':
          $ref: '#/components/responses/ElementNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/webview/contexts:
    get:
      operationId: getWebViewContexts
      tags:
        - webview
      summary: List WebView instances
      description: |
        Returns all active WebView contexts in the application.
      responses:
        '200':
          description: Array of WebView contexts.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WebViewContext'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/webview/evaluate:
    post:
      operationId: evaluateJavaScript
      tags:
        - webview
      summary: Execute JavaScript in WebView
      description: |
        Evaluates a JavaScript expression inside a WebView context and returns the result.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvaluateRequest'
      responses:
        '200':
          description: Evaluation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluateResponse'
        '404':
          $ref: '#/components/responses/ElementNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/webview/dom:
    get:
      operationId: getWebViewDom
      tags:
        - webview
      summary: Get DOM snapshot
      description: |
        Returns a simplified snapshot of the DOM tree in the WebView.
      parameters:
        - name: contextId
          in: query
          description: WebView context ID. Uses the default context if omitted.
          schema:
            type: string
      responses:
        '200':
          description: Simplified DOM tree.
          content:
            application/json:
              schema:
                type: object
                description: Simplified DOM tree representation.
        '404':
          $ref: '#/components/responses/ElementNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/webview/dom/query:
    post:
      operationId: queryWebViewDom
      tags:
        - webview
      summary: CSS query in DOM
      description: |
        Executes a CSS selector query against the WebView DOM and returns matching nodes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomQueryRequest'
      responses:
        '200':
          description: Matching DOM nodes.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: Simplified DOM node.
        '400':
          $ref: '#/components/responses/InvalidSelector'
        '404':
          $ref: '#/components/responses/ElementNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/webview/source:
    get:
      operationId: getWebViewSource
      tags:
        - webview
      summary: Get page source
      description: |
        Returns the HTML source of the WebView page.
      parameters:
        - name: contextId
          in: query
          description: WebView context ID. Uses the default context if omitted.
          schema:
            type: string
      responses:
        '200':
          description: Page HTML source.
          content:
            text/html:
              schema:
                type: string
        '404':
          $ref: '#/components/responses/ElementNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/webview/navigate:
    post:
      operationId: navigateWebView
      tags:
        - webview
      summary: Navigate WebView
      description: |
        Navigates the WebView to the specified URL.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebViewNavigateRequest'
      responses:
        '200':
          description: Navigation initiated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '404':
          $ref: '#/components/responses/ElementNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/webview/input/click:
    post:
      operationId: clickInWebView
      tags:
        - webview
      summary: Click element in WebView
      description: |
        Clicks a DOM element matching the given CSS selector inside the WebView.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebViewInputClickRequest'
      responses:
        '200':
          description: Click performed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '400':
          $ref: '#/components/responses/InvalidSelector'
        '404':
          $ref: '#/components/responses/ElementNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/webview/input/fill:
    post:
      operationId: fillInWebView
      tags:
        - webview
      summary: Fill field in WebView
      description: |
        Clears and fills a DOM input element matching the given CSS selector.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebViewInputFillRequest'
      responses:
        '200':
          description: Fill performed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '400':
          $ref: '#/components/responses/InvalidSelector'
        '404':
          $ref: '#/components/responses/ElementNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/webview/input/text:
    post:
      operationId: insertTextInWebView
      tags:
        - webview
      summary: Insert text in WebView
      description: |
        Inserts text into the currently focused element in the WebView without clearing existing content.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebViewInputTextRequest'
      responses:
        '200':
          description: Text inserted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '404':
          $ref: '#/components/responses/ElementNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/webview/screenshot:
    get:
      operationId: captureWebViewScreenshot
      tags:
        - webview
      summary: Capture WebView screenshot
      description: |
        Captures a screenshot of the WebView content.
      parameters:
        - name: contextId
          in: query
          description: WebView context ID. Uses the default context if omitted.
          schema:
            type: string
      responses:
        '200':
          description: Screenshot image.
          content:
            image/png:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/ElementNotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/profiler/capabilities:
    get:
      operationId: getProfilerCapabilities
      tags:
        - profiler
      summary: Get profiling capabilities
      description: |
        Returns which profiling features are supported on the current platform.
      responses:
        '200':
          description: Profiler capabilities.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfilerCapabilities'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/profiler/sessions:
    post:
      operationId: startProfilerSession
      tags:
        - profiler
      summary: Start profiler session
      description: |
        Starts a new profiling session with the given sample interval.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sampleIntervalMs:
                  type: integer
                  minimum: 1
                  description: Sampling interval in milliseconds.
      responses:
        '200':
          description: Session started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfilerSessionInfo'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/profiler/sessions/{id}:
    delete:
      operationId: stopProfilerSession
      tags:
        - profiler
      summary: Stop profiler session
      description: |
        Stops an active profiling session.
      parameters:
        - name: id
          in: path
          required: true
          description: Profiler session ID.
          schema:
            type: string
      responses:
        '200':
          description: Session stopped.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfilerSessionInfo'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/profiler/sessions/{id}/samples:
    get:
      operationId: getProfilerSamples
      tags:
        - profiler
      summary: Get profiler samples
      description: |
        Returns profiling samples, markers, and spans collected since the given cursors. Use cursor values from the previous response to poll for new data.
      parameters:
        - name: id
          in: path
          required: true
          description: Profiler session ID.
          schema:
            type: string
        - name: sampleCursor
          in: query
          description: Cursor for samples. Start at 0.
          schema:
            type: integer
            minimum: 0
        - name: markerCursor
          in: query
          description: Cursor for markers. Start at 0.
          schema:
            type: integer
            minimum: 0
        - name: spanCursor
          in: query
          description: Cursor for spans. Start at 0.
          schema:
            type: integer
            minimum: 0
        - name: limit
          in: query
          description: Maximum number of items to return per category.
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: Profiler batch of samples, markers, and spans.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfilerBatch'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/profiler/markers:
    post:
      operationId: publishProfilerMarker
      tags:
        - profiler
      summary: Publish profiler marker
      description: |
        Publishes a timestamped marker event into the active profiling session.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfilerMarker'
      responses:
        '200':
          description: Marker published.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/profiler/spans:
    post:
      operationId: publishProfilerSpan
      tags:
        - profiler
      summary: Publish profiler span
      description: |
        Publishes a completed span into the active profiling session.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProfilerSpan'
      responses:
        '200':
          description: Span published.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/profiler/hotspots:
    get:
      operationId: getProfilerHotspots
      tags:
        - profiler
      summary: Get performance hotspots
      description: |
        Returns aggregated performance hotspots from the profiling session.
      parameters:
        - name: limit
          in: query
          description: Maximum number of hotspots to return.
          schema:
            type: integer
            minimum: 1
        - name: minDurationMs
          in: query
          description: Minimum average duration in milliseconds.
          schema:
            type: number
            minimum: 0
        - name: kind
          in: query
          description: Filter by hotspot kind.
          schema:
            type: string
      responses:
        '200':
          description: Array of hotspots.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProfilerHotspot'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/network/requests:
    get:
      operationId: getNetworkRequests
      tags:
        - network
      summary: List captured network requests
      description: |
        Returns captured HTTP requests, optionally filtered by host, method, or status code.
      parameters:
        - name: limit
          in: query
          description: Maximum number of requests to return.
          schema:
            type: integer
            minimum: 1
        - name: host
          in: query
          description: Filter by host name.
          schema:
            type: string
        - name: method
          in: query
          description: Filter by HTTP method.
          schema:
            type: string
        - name: statusCode
          in: query
          description: Filter by status code.
          schema:
            type: integer
            minimum: 100
            maximum: 599
      responses:
        '200':
          description: Array of network request summaries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NetworkRequestSummary'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: clearNetworkRequests
      tags:
        - network
      summary: Clear captured requests
      description: |
        Clears all captured network requests from the buffer.
      responses:
        '204':
          description: Requests cleared.
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/network/requests/{id}:
    get:
      operationId: getNetworkRequestDetail
      tags:
        - network
      summary: Get network request detail
      description: |
        Returns full details for a captured network request, including headers and body content.
      parameters:
        - name: id
          in: path
          required: true
          description: Network request ID.
          schema:
            type: string
      responses:
        '200':
          description: Full network request detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworkRequestDetail'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/logs:
    get:
      operationId: getLogs
      tags:
        - logs
      summary: Query application logs
      description: |
        Returns application log entries, optionally filtered by source and level.
      parameters:
        - name: limit
          in: query
          description: Maximum number of log entries.
          schema:
            type: integer
            minimum: 1
        - name: skip
          in: query
          description: Number of entries to skip (for pagination).
          schema:
            type: integer
            minimum: 0
        - name: source
          in: query
          description: Filter by log source.
          schema:
            type: string
            enum:
              - native
              - webview
              - framework
        - name: level
          in: query
          description: Minimum log level.
          schema:
            type: string
            enum:
              - trace
              - debug
              - info
              - warning
              - error
              - critical
      responses:
        '200':
          description: Array of log entries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LogEntry'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/device/info:
    get:
      operationId: getDeviceInfo
      tags:
        - device
      summary: Get device info
      description: |
        Returns hardware and OS information about the device.
      responses:
        '200':
          description: Device information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceInfo'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/device/display:
    get:
      operationId: getDisplayInfo
      tags:
        - device
      summary: Get display info
      description: |
        Returns display dimensions, density, and orientation.
      responses:
        '200':
          description: Display information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisplayInfo'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/device/battery:
    get:
      operationId: getBatteryInfo
      tags:
        - device
      summary: Get battery info
      description: |
        Returns battery level, state, and power source.
      responses:
        '200':
          description: Battery information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatteryInfo'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/device/connectivity:
    get:
      operationId: getConnectivityInfo
      tags:
        - device
      summary: Get connectivity info
      description: |
        Returns network connectivity status and connection profiles.
      responses:
        '200':
          description: Connectivity information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectivityInfo'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/device/app:
    get:
      operationId: getAppInfo
      tags:
        - device
      summary: Get app info
      description: |
        Returns application name, version, build number, and package ID.
      responses:
        '200':
          description: Application information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppInfo'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/device/sensors:
    get:
      operationId: listSensors
      tags:
        - device
      summary: List available sensors
      description: |
        Returns the list of sensors and their availability/active status.
      responses:
        '200':
          description: Array of sensor info.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SensorInfo'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/device/sensors/{name}/start:
    post:
      operationId: startSensor
      tags:
        - device
      summary: Start sensor
      description: |
        Starts collecting data from the named sensor. Readings are delivered via the WebSocket sensor channel.
      parameters:
        - name: name
          in: path
          required: true
          description: Sensor name (e.g. accelerometer, gyroscope, compass).
          schema:
            type: string
        - name: speed
          in: query
          description: |
            Sensor update speed. Framework-dependent (e.g. "fastest", "game", "ui", "default").
          schema:
            type: string
      responses:
        '200':
          description: Sensor started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SensorInfo'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '501':
          $ref: '#/components/responses/UnsupportedCapability'
  /api/v1/device/sensors/{name}/stop:
    post:
      operationId: stopSensor
      tags:
        - device
      summary: Stop sensor
      description: |
        Stops collecting data from the named sensor.
      parameters:
        - name: name
          in: path
          required: true
          description: Sensor name.
          schema:
            type: string
      responses:
        '200':
          description: Sensor stopped.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SensorInfo'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/device/permissions:
    get:
      operationId: listPermissions
      tags:
        - device
      summary: List permissions
      description: |
        Returns the status of all known permissions.
      responses:
        '200':
          description: Array of permission info.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PermissionInfo'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/device/permissions/{name}:
    get:
      operationId: checkPermission
      tags:
        - device
      summary: Check permission status
      description: |
        Returns the current status of a specific permission.
      parameters:
        - name: name
          in: path
          required: true
          description: Permission name (e.g. camera, location, microphone).
          schema:
            type: string
      responses:
        '200':
          description: Permission status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionInfo'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/device/geolocation:
    get:
      operationId: getGeolocation
      tags:
        - device
      summary: Get current location
      description: |
        Returns the device's current geographic location.
      parameters:
        - name: accuracy
          in: query
          description: Desired accuracy level.
          schema:
            type: string
        - name: timeout
          in: query
          description: Timeout in milliseconds for the location request.
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: Current location.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeolocationResult'
        '408':
          $ref: '#/components/responses/Timeout'
        '500':
          $ref: '#/components/responses/InternalError'
        '501':
          $ref: '#/components/responses/UnsupportedCapability'
  /api/v1/device/jobs:
    get:
      operationId: listDeviceJobs
      tags:
        - device
      summary: List platform background jobs
      description: |
        Returns platform background jobs known to the agent. Android reports WorkManager identifiers, tags, states, and run attempts. iOS and Mac Catalyst report pending BGTaskScheduler requests.
      responses:
        '200':
          description: Platform job list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobListResponse'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/device/jobs/{identifier}/run:
    post:
      operationId: runDeviceJob
      tags:
        - device
      summary: Trigger a platform background job
      description: |
        Attempts to trigger the named platform background job. iOS and Mac Catalyst submit a BGTaskRequest for the identifier; pass `type` when the task is known to be an app refresh task. Android may report `success=false` when worker types and request inputs cannot be reconstructed safely from the listed identifier or tags.
      parameters:
        - name: identifier
          in: path
          required: true
          description: Platform job identifier returned by the list endpoint.
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobRunRequest'
      responses:
        '200':
          description: Job trigger result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobRunResponse'
        '500':
          $ref: '#/components/responses/InternalError'
        '501':
          $ref: '#/components/responses/UnsupportedCapability'
  /api/v1/device/ble:
    get:
      operationId: getBleStatus
      tags:
        - device
      summary: Get BLE monitor status
      description: |
        Returns Bluetooth Low Energy monitor status, including whether scanning is active, the number of buffered events, active stream subscribers, and whether native scanning is supported.
      responses:
        '200':
          description: BLE monitor status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BleStatus'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/device/ble/events:
    get:
      operationId: getBleEvents
      tags:
        - device
      summary: List BLE events
      description: |
        Returns recent BLE events recorded by the agent, optionally filtered by event type.
      parameters:
        - name: limit
          in: query
          description: Maximum number of events to return.
          schema:
            type: integer
            minimum: 0
            default: 100
        - name: type
          in: query
          description: Optional BLE event type filter.
          schema:
            type: string
      responses:
        '200':
          description: Buffered BLE events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BleEventsResponse'
        '400':
          description: Invalid BLE event query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: clearBleEvents
      tags:
        - device
      summary: Clear BLE events
      description: Clears all buffered BLE events.
      responses:
        '200':
          description: BLE events cleared.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResponse'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/device/ble/scan/start:
    post:
      operationId: startBleScan
      tags:
        - device
      summary: Start BLE scan
      description: |
        Starts native BLE scanning when supported by the current platform. Discovered advertisements are buffered as BLE events and streamed to BLE WebSocket subscribers.
      responses:
        '200':
          description: BLE scan started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResponse'
        '500':
          $ref: '#/components/responses/InternalError'
        '501':
          $ref: '#/components/responses/UnsupportedCapability'
  /api/v1/device/ble/scan/stop:
    post:
      operationId: stopBleScan
      tags:
        - device
      summary: Stop BLE scan
      description: Stops an active BLE scan.
      responses:
        '200':
          description: BLE scan stopped.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionResponse'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/storage/roots:
    get:
      operationId: listStorageRoots
      tags:
        - storage
      summary: List file storage roots
      description: |
        Lists logical file storage roots advertised by the agent. Absolute on-device paths are not returned. The shared implementation advertises `appData` when an app data directory is available.
      responses:
        '200':
          description: Storage roots.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageRootsResponse'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/storage/files:
    get:
      operationId: listFiles
      tags:
        - storage
      summary: List storage files
      description: |
        Lists files and directories under an advertised storage root. The optional path is always relative to the selected root; rooted paths, `..` traversal segments, and symlink/reparse-point traversal are rejected. Absolute on-device paths are not returned. Omit `root` to use the default `appData` root.
      parameters:
        - name: root
          in: query
          description: Storage root id. Defaults to `appData`. Use `/api/v1/storage/roots` to discover supported roots.
          schema:
            type: string
            default: appData
        - name: path
          in: query
          description: Relative subdirectory path. Omit or pass an empty string for the selected root.
          schema:
            type: string
      responses:
        '200':
          description: Directory listing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileListResponse'
        '400':
          $ref: '#/components/responses/InvalidPath'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/storage/files/{path}:
    get:
      operationId: downloadFile
      tags:
        - storage
      summary: Download a storage file
      description: |
        Downloads a file under an advertised storage root and returns base64-encoded content. The path parameter is a single URI-encoded relative path; path separators inside it must be percent-encoded. Omit `root` to use the default `appData` root.
      parameters:
        - name: path
          in: path
          required: true
          description: URI-encoded relative file path under the selected storage root.
          schema:
            type: string
        - name: root
          in: query
          description: Storage root id. Defaults to `appData`. Use `/api/v1/storage/roots` to discover supported roots.
          schema:
            type: string
            default: appData
      responses:
        '200':
          description: File content and metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileDownloadResponse'
        '400':
          $ref: '#/components/responses/InvalidPath'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: uploadFile
      tags:
        - storage
      summary: Upload a storage file
      description: |
        Creates or overwrites a file under an advertised storage root. Parent directories are created automatically after path sandbox validation. Omit `root` to use the default `appData` root.
      parameters:
        - name: path
          in: path
          required: true
          description: URI-encoded relative file path under the selected storage root.
          schema:
            type: string
        - name: root
          in: query
          description: Storage root id. Defaults to `appData`. Use `/api/v1/storage/roots` to discover supported roots.
          schema:
            type: string
            default: appData
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileUploadRequest'
      responses:
        '200':
          description: Uploaded file metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileUploadResponse'
        '400':
          $ref: '#/components/responses/InvalidPath'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteFile
      tags:
        - storage
      summary: Delete a storage file
      description: Deletes a file under an advertised storage root. Omit `root` to use the default `appData` root.
      parameters:
        - name: path
          in: path
          required: true
          description: URI-encoded relative file path under the selected storage root.
          schema:
            type: string
        - name: root
          in: query
          description: Storage root id. Defaults to `appData`. Use `/api/v1/storage/roots` to discover supported roots.
          schema:
            type: string
            default: appData
      responses:
        '200':
          description: Deleted file metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileDeleteResponse'
        '400':
          $ref: '#/components/responses/InvalidPath'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/storage/preferences:
    get:
      operationId: listPreferences
      tags:
        - storage
      summary: List preferences
      description: |
        Returns all preference entries, optionally scoped to a shared container.
      parameters:
        - name: sharedName
          in: query
          description: Shared preference container name.
          schema:
            type: string
      responses:
        '200':
          description: Array of preference entries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PreferenceEntry'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: clearPreferences
      tags:
        - storage
      summary: Clear all preferences
      description: |
        Deletes all preferences, optionally scoped to a shared container.
      parameters:
        - name: sharedName
          in: query
          description: Shared preference container name.
          schema:
            type: string
      responses:
        '204':
          description: Preferences cleared.
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/storage/preferences/{key}:
    get:
      operationId: getPreference
      tags:
        - storage
      summary: Get preference value
      description: |
        Returns the value of a specific preference key.
      parameters:
        - name: key
          in: path
          required: true
          description: Preference key.
          schema:
            type: string
        - name: type
          in: query
          description: Expected value type for deserialization.
          schema:
            $ref: '#/components/schemas/PreferenceValueType'
        - name: sharedName
          in: query
          description: Shared preference container name.
          schema:
            type: string
      responses:
        '200':
          description: Preference entry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreferenceEntry'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: setPreference
      tags:
        - storage
      summary: Set preference value
      description: |
        Creates or updates a preference entry.
      parameters:
        - name: key
          in: path
          required: true
          description: Preference key.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreferenceSetRequest'
      responses:
        '200':
          description: Preference set.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreferenceEntry'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deletePreference
      tags:
        - storage
      summary: Delete preference
      description: |
        Deletes a specific preference by key.
      parameters:
        - name: key
          in: path
          required: true
          description: Preference key.
          schema:
            type: string
        - name: sharedName
          in: query
          description: Shared preference container name.
          schema:
            type: string
      responses:
        '204':
          description: Preference deleted.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/storage/secure:
    delete:
      operationId: clearSecureStorage
      tags:
        - storage
      summary: Clear all secure storage
      description: |
        Deletes all values from secure storage.
      responses:
        '204':
          description: Secure storage cleared.
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/storage/secure/{key}:
    get:
      operationId: getSecureValue
      tags:
        - storage
      summary: Get secure storage value
      description: |
        Returns the value stored under the given key in secure storage.
      parameters:
        - name: key
          in: path
          required: true
          description: Secure storage key.
          schema:
            type: string
      responses:
        '200':
          description: Secure value.
          content:
            application/json:
              schema:
                type: object
                required:
                  - value
                properties:
                  value:
                    type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: setSecureValue
      tags:
        - storage
      summary: Set secure storage value
      description: |
        Stores a value in secure storage under the given key.
      parameters:
        - name: key
          in: path
          required: true
          description: Secure storage key.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecureStorageSetRequest'
      responses:
        '200':
          description: Value stored.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: deleteSecureValue
      tags:
        - storage
      summary: Delete secure storage value
      description: |
        Deletes a specific value from secure storage.
      parameters:
        - name: key
          in: path
          required: true
          description: Secure storage key.
          schema:
            type: string
      responses:
        '204':
          description: Value deleted.
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/ext/{namespace}/{path}:
    get:
      operationId: callExtensionGet
      tags:
        - extensions
      summary: Call extension endpoint (GET)
      description: |
        Proxy route for third-party extension GET endpoints. The namespace uses reverse-domain notation (e.g. `com.example.analytics`). Available extensions and their self-describing tools are discoverable via `GET /api/v1/agent/capabilities`. The `path` segment represents the extension-defined relative path; agents may accept nested sub-paths.
      parameters:
        - name: namespace
          in: path
          required: true
          description: Extension namespace in reverse-domain notation.
          schema:
            type: string
            pattern: ^[a-z][a-z0-9]*\.[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)*$
        - name: path
          in: path
          required: true
          description: Extension-defined sub-path.
          schema:
            type: string
      responses:
        '200':
          description: Extension-defined response.
          content:
            application/json:
              schema: {}
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      operationId: callExtensionPost
      tags:
        - extensions
      summary: Call extension endpoint (POST)
      description: |
        Proxy route for third-party extension POST endpoints. Request and response schemas are extension-defined and advertised by the tool descriptor in the capabilities response.
      parameters:
        - name: namespace
          in: path
          required: true
          description: Extension namespace in reverse-domain notation.
          schema:
            type: string
            pattern: ^[a-z][a-z0-9]*\.[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)*$
        - name: path
          in: path
          required: true
          description: Extension-defined sub-path.
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema: {}
      responses:
        '200':
          description: Extension-defined response.
          content:
            application/json:
              schema: {}
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      operationId: callExtensionPut
      tags:
        - extensions
      summary: Call extension endpoint (PUT)
      description: |
        Proxy route for third-party extension PUT endpoints. Request and response schemas are extension-defined and advertised by the tool descriptor in the capabilities response.
      parameters:
        - name: namespace
          in: path
          required: true
          description: Extension namespace in reverse-domain notation.
          schema:
            type: string
            pattern: ^[a-z][a-z0-9]*\.[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)*$
        - name: path
          in: path
          required: true
          description: Extension-defined sub-path.
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema: {}
      responses:
        '200':
          description: Extension-defined response.
          content:
            application/json:
              schema: {}
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
    delete:
      operationId: callExtensionDelete
      tags:
        - extensions
      summary: Call extension endpoint (DELETE)
      description: |
        Proxy route for third-party extension DELETE endpoints. Available extension tools and behavior annotations are discoverable from `GET /api/v1/agent/capabilities`.
      parameters:
        - name: namespace
          in: path
          required: true
          description: Extension namespace in reverse-domain notation.
          schema:
            type: string
            pattern: ^[a-z][a-z0-9]*\.[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)*$
        - name: path
          in: path
          required: true
          description: Extension-defined sub-path.
          schema:
            type: string
      responses:
        '200':
          description: Extension-defined response.
          content:
            application/json:
              schema: {}
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    ElementIdPath:
      name: id
      in: path
      required: true
      description: Globally unique element identifier.
      schema:
        $ref: '#/components/schemas/ElementId'
  responses:
    ActionSuccess:
      description: Action completed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ActionResponse'
    ElementNotFound:
      description: Element not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: urn:devflow:error:element-not-found
            title: Element not found
            status: 404
            errorCode: element-not-found
    ElementNotInteractable:
      description: Element is not interactable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: urn:devflow:error:element-not-interactable
            title: Element not interactable
            status: 400
            errorCode: element-not-interactable
    InvalidSelector:
      description: Invalid selector or locator.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: urn:devflow:error:invalid-selector
            title: Invalid selector
            status: 400
            errorCode: invalid-selector
    Timeout:
      description: Operation timed out.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: urn:devflow:error:timeout
            title: Timeout
            status: 408
            errorCode: timeout
    UnsupportedCapability:
      description: Capability not supported on this platform.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: urn:devflow:error:unsupported-capability
            title: Unsupported capability
            status: 501
            errorCode: unsupported-capability
    InvalidPath:
      description: Invalid or unsafe storage path or unavailable storage root.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: urn:devflow:error:invalid-path
            title: Invalid storage path
            status: 400
            errorCode: invalid-path
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: urn:devflow:error:element-not-found
            title: Not found
            status: 404
    InternalError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: urn:devflow:error:internal-error
            title: Internal error
            status: 500
            errorCode: internal-error
  schemas:
    agent-status:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: agent-status.json
      title: AgentStatus
      description: Agent status response providing runtime information about the agent, device, and application.
      type: object
      required:
        - agent
        - platform
        - device
        - app
        - running
        - uptime
      properties:
        agent:
          type: object
          description: Information about the DevFlow agent itself.
          required:
            - name
            - version
            - framework
            - frameworkVersion
          properties:
            name:
              type: string
              description: Name of the DevFlow agent implementation.
            version:
              type: string
              description: Semantic version of the agent.
            sessionId:
              type: string
              description: Optional metadata-only identifier for the build/session that produced this agent. It is used to distinguish agents from different worktrees or environments without changing the application package or bundle identity.
            framework:
              type: string
              description: The UI framework the agent is instrumented for (e.g. 'maui', 'react-native').
            frameworkVersion:
              type: string
              description: Version of the UI framework.
        platform:
          type: string
          enum:
            - ios
            - android
            - maccatalyst
            - windows
            - linux
            - macos
          description: The target platform the agent is running on.
        device:
          type: object
          description: Information about the device or emulator/simulator.
          required:
            - model
            - manufacturer
            - osVersion
            - idiom
          properties:
            model:
              type: string
              description: Device model name (e.g. 'iPhone 15 Pro', 'Pixel 8').
            manufacturer:
              type: string
              description: Device manufacturer (e.g. 'Apple', 'Google').
            osVersion:
              type: string
              description: Operating system version string.
            idiom:
              type: string
              enum:
                - phone
                - tablet
                - desktop
                - tv
                - watch
              description: Device form factor idiom.
        app:
          type: object
          description: Information about the instrumented application.
          required:
            - name
            - version
            - packageId
          properties:
            name:
              type: string
              description: Display name of the application.
            version:
              type: string
              description: Application version string.
            packageId:
              type: string
              description: Application package identifier (e.g. 'com.example.myapp').
        running:
          type: boolean
          description: Whether the application is currently running and responsive.
        capabilities:
          type: object
          description: Boolean status summary for agent capabilities.
          properties:
            ui:
              type: boolean
            screenshots:
              type: boolean
            webview:
              type: boolean
            network:
              type: boolean
            logs:
              type: boolean
            sensors:
              type: boolean
            storage:
              type: boolean
            profiler:
              type: boolean
            jobs:
              type: boolean
              description: Whether platform background jobs are supported by this agent.
            ble:
              type: boolean
              description: Whether Bluetooth Low Energy monitoring is supported by this agent.
          additionalProperties: true
        uptime:
          type: string
          description: Agent uptime as an ISO 8601 duration (e.g. 'PT1H30M15S').
          pattern: ^P
        extensions:
          type: object
          description: Lightweight marker indicating registered extensions. Allows clients to skip the heavier capabilities fetch when no extensions are present or when cached extension descriptors are still current.
          properties:
            count:
              type: integer
              description: Number of registered extensions. When 0, clients can skip the capabilities call for extension discovery.
              minimum: 0
            hash:
              type: string
              description: SHA-256 hash of the serialized extensions map from the capabilities response. Clients cache extension metadata keyed by this hash and only re-fetch capabilities when it changes.
              pattern: ^[a-f0-9]{64}$
          required:
            - count
            - hash
    ProblemDetails:
      type: object
      description: RFC 7807 Problem Details error response.
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          format: uri
          description: A URI reference that identifies the problem type.
        title:
          type: string
          description: A short, human-readable summary of the problem type.
        status:
          type: integer
          description: The HTTP status code for this occurrence of the problem.
          minimum: 100
          maximum: 599
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          format: uri
          description: A URI reference that identifies the specific occurrence of the problem.
        errorCode:
          type: string
          enum:
            - element-not-found
            - stale-element-reference
            - element-not-interactable
            - invalid-selector
            - timeout
            - unknown-command
            - unsupported-capability
            - invalid-path
            - internal-error
          description: Machine-readable error code identifying the category of failure.
    ExtensionToolAnnotations:
      type: object
      description: Hints about the tool's behavior, modeled after MCP tool annotations.
      properties:
        readOnly:
          type: boolean
          description: True if the tool only reads data and has no side effects.
          default: false
        idempotent:
          type: boolean
          description: True if calling the tool multiple times with the same input has the same effect as calling it once.
          default: false
        destructive:
          type: boolean
          description: True if the tool may delete data or cause irreversible changes.
          default: false
        category:
          type: string
          description: Optional grouping category (e.g. 'diagnostics', 'analytics', 'testing').
    ExtensionTool:
      type: object
      required:
        - name
        - description
        - method
        - path
      properties:
        name:
          type: string
          description: Machine-readable tool name, unique within the extension (e.g. 'list_errors', 'capture_message').
          pattern: ^[a-z][a-z0-9_]*$
        description:
          type: string
          description: Human-readable description of what this tool does. Used by CLI help text and MCP tool metadata.
        method:
          type: string
          enum:
            - GET
            - POST
            - PUT
            - DELETE
          description: HTTP method for this tool's endpoint.
        path:
          type: string
          description: Full URL path for this tool (e.g. '/api/v1/ext/com.example.analytics/events').
        parameters:
          type: object
          description: JSON Schema describing the tool's input parameters. For GET requests, parameters are query strings. For POST and PUT, parameters are the JSON request body.
          additionalProperties: true
        returns:
          type: object
          description: JSON Schema describing the tool's response body.
          additionalProperties: true
        annotations:
          $ref: '#/components/schemas/ExtensionToolAnnotations'
    ExtensionDescriptor:
      type: object
      required:
        - version
        - description
        - tools
      properties:
        version:
          type: string
          description: Semantic version of this extension. Changes to this value signal clients to refresh cached tool definitions.
          pattern: ^\d+\.\d+\.\d+
        description:
          type: string
          description: Human-readable description of what this extension provides.
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ExtensionTool'
          description: Self-describing tools exposed by this extension. Each tool maps to an HTTP endpoint under /api/v1/ext/{namespace}/.
      description: Extension descriptor with version, description, and self-describing tools.
    agent-capabilities:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: agent-capabilities.json
      title: AgentCapabilities
      description: Capability discovery response describing what the agent supports.
      type: object
      required:
        - agent
        - capabilities
      properties:
        agent:
          type: object
          description: Information about the DevFlow agent itself.
          required:
            - name
            - version
            - framework
            - frameworkVersion
          properties:
            name:
              type: string
              description: Name of the DevFlow agent implementation.
            version:
              type: string
              description: Semantic version of the agent.
            framework:
              type: string
              description: The UI framework the agent is instrumented for.
            frameworkVersion:
              type: string
              description: Version of the UI framework.
        capabilities:
          type: object
          description: Map of capability namespaces to their details. Keys are dot-separated namespaces.
          additionalProperties:
            type: object
            required:
              - version
              - features
            properties:
              version:
                type: integer
                description: Capability version number.
                minimum: 1
              features:
                type: array
                items:
                  type: string
                description: List of supported features within this capability namespace.
            additionalProperties: true
            description: Capability details including version, features, and optional extra fields.
          examples:
            - ui.tree:
                version: 1
                features:
                  - find
                  - query
                  - snapshot
              ui.actions:
                version: 1
                features:
                  - tap
                  - fill
                  - scroll
                  - gesture
              ui.screenshot:
                version: 1
                features:
                  - fullPage
                  - element
              webview:
                version: 1
                features:
                  - evaluate
                  - dom
                  - navigate
              profiler:
                version: 1
                features:
                  - samples
                  - spans
                  - markers
              network:
                version: 1
                features:
                  - capture
                  - detail
              logs:
                version: 1
                features:
                  - stream
                  - query
              device.info:
                version: 1
                features:
                  - display
                  - battery
                  - connectivity
              device.sensors:
                version: 1
                features:
                  - accelerometer
                  - gyroscope
                  - compass
              device.jobs:
                version: 1
                features:
                  - list
                  - run
                supported: true
              device.ble:
                version: 1
                features:
                  - status
                  - events
                  - scan
                  - websocket
                supported: true
              storage.preferences:
                version: 1
                features:
                  - get
                  - set
                  - delete
              storage.files:
                version: 1
                features:
                  - roots
                  - list
                  - download
                  - upload
                  - delete
              storage.secure:
                version: 1
                features:
                  - get
                  - set
                  - delete
        extensions:
          type: object
          description: Map of extension namespaces (reverse-domain notation) to their self-describing tool registrations. Each extension is discoverable and invocable by CLI and MCP clients without hardcoded extension-specific code.
          additionalProperties:
            $ref: '#/components/schemas/ExtensionDescriptor'
      $defs:
        ExtensionDescriptor:
          type: object
          required:
            - version
            - description
            - tools
          properties:
            version:
              type: string
              description: Semantic version of this extension. Changes to this value signal clients to refresh cached tool definitions.
              pattern: ^\d+\.\d+\.\d+
            description:
              type: string
              description: Human-readable description of what this extension provides.
            tools:
              type: array
              items:
                $ref: '#/components/schemas/ExtensionTool'
              description: Self-describing tools exposed by this extension. Each tool maps to an HTTP endpoint under /api/v1/ext/{namespace}/.
          description: Extension descriptor with version, description, and self-describing tools.
        ExtensionTool:
          type: object
          required:
            - name
            - description
            - method
            - path
          properties:
            name:
              type: string
              description: Machine-readable tool name, unique within the extension (e.g. 'list_errors', 'capture_message').
              pattern: ^[a-z][a-z0-9_]*$
            description:
              type: string
              description: Human-readable description of what this tool does. Used by CLI help text and MCP tool metadata.
            method:
              type: string
              enum:
                - GET
                - POST
                - PUT
                - DELETE
              description: HTTP method for this tool's endpoint.
            path:
              type: string
              description: Full URL path for this tool (e.g. '/api/v1/ext/com.example.analytics/events').
            parameters:
              type: object
              description: JSON Schema describing the tool's input parameters. For GET requests, parameters are query strings. For POST and PUT, parameters are the JSON request body.
              additionalProperties: true
            returns:
              type: object
              description: JSON Schema describing the tool's response body.
              additionalProperties: true
            annotations:
              $ref: '#/components/schemas/ExtensionToolAnnotations'
        ExtensionToolAnnotations:
          type: object
          description: Hints about the tool's behavior, modeled after MCP tool annotations.
          properties:
            readOnly:
              type: boolean
              description: True if the tool only reads data and has no side effects.
              default: false
            idempotent:
              type: boolean
              description: True if calling the tool multiple times with the same input has the same effect as calling it once.
              default: false
            destructive:
              type: boolean
              description: True if the tool may delete data or cause irreversible changes.
              default: false
            category:
              type: string
              description: Optional grouping category (e.g. 'diagnostics', 'analytics', 'testing').
    ElementId:
      type: string
      description: Globally unique element identifier within the visual tree.
    CoordinateSystem:
      type: string
      enum:
        - window
        - screen
      description: Coordinate system for bounding rectangles and points.
    bounds-info:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: bounds-info.json
      title: BoundsInfo
      description: Bounding rectangle for a visual element.
      type: object
      required:
        - x
        - 'y'
        - width
        - height
      properties:
        x:
          type: number
          description: The x-coordinate of the top-left corner.
        'y':
          type: number
          description: The y-coordinate of the top-left corner.
        width:
          type: number
          description: The width of the bounding rectangle.
          minimum: 0
        height:
          type: number
          description: The height of the bounding rectangle.
          minimum: 0
        coordinate:
          $ref: '#/components/schemas/CoordinateSystem'
          description: The coordinate system for this bounding rectangle.
          default: window
    element-info:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: element-info.json
      title: ElementInfo
      description: Core visual tree element model representing a single node in the UI hierarchy.
      type: object
      required:
        - id
        - type
        - fullType
        - framework
        - state
        - bounds
      properties:
        id:
          $ref: '#/components/schemas/ElementId'
          description: Globally unique identifier for this element.
        parentId:
          oneOf:
            - $ref: '#/components/schemas/ElementId'
            - type: 'null'
          description: Identifier of the parent element, or null for root elements.
        type:
          type: string
          description: Short type name of the element (e.g. 'Button').
        fullType:
          type: string
          description: Fully qualified type name (e.g. 'Microsoft.Maui.Controls.Button').
        framework:
          type: string
          description: The UI framework that owns this element.
          examples:
            - maui
            - react-native
            - flutter
            - android
            - ios
        automationId:
          type:
            - string
            - 'null'
          description: Automation identifier set by the developer for testing purposes.
        text:
          type:
            - string
            - 'null'
          description: Visible text content of the element.
        value:
          type:
            - string
            - 'null'
          description: Current value for input elements (e.g. text field content, slider value).
        role:
          type: string
          description: Semantic role of the element for accessibility and interaction purposes.
          examples:
            - button
            - textbox
            - checkbox
            - image
            - list
            - listitem
            - link
            - heading
            - window
        traits:
          type: array
          items:
            type: string
          description: Semantic traits describing the element's capabilities and behavior.
          examples:
            - - interactive
              - focusable
              - scrollable
              - adjustable
              - header
              - summary
        state:
          type: object
          description: Current interactive and visual state of the element.
          required:
            - displayed
            - enabled
            - selected
            - focused
            - opacity
          properties:
            displayed:
              type: boolean
              description: Whether the element is currently visible on screen.
            enabled:
              type: boolean
              description: Whether the element is enabled for user interaction.
            selected:
              type: boolean
              description: Whether the element is currently selected.
            focused:
              type: boolean
              description: Whether the element currently has input focus.
            opacity:
              type: number
              description: Opacity of the element from fully transparent (0) to fully opaque (1).
              minimum: 0
              maximum: 1
        bounds:
          $ref: '#/components/schemas/bounds-info'
          description: Bounding rectangle of the element.
        gestures:
          type: array
          items:
            type: string
          description: Gesture types recognized by this element.
          examples:
            - - tap
              - doubleTap
              - longPress
              - swipe
              - pinch
        style:
          type: object
          description: Style information for the element.
          properties:
            classes:
              type: array
              items:
                type: string
              description: CSS or style classes applied to this element.
        nativeView:
          type:
            - object
            - 'null'
          description: Information about the underlying native platform view.
          properties:
            type:
              type:
                - string
                - 'null'
              description: Native platform type name (e.g. 'UIButton', 'android.widget.Button').
            properties:
              type:
                - object
                - 'null'
              additionalProperties: true
              description: Key-value pairs of native view properties.
        frameworkProperties:
          type:
            - object
            - 'null'
          additionalProperties: true
          description: Framework-specific key-value pairs not captured by standard fields.
        children:
          type: array
          items:
            $ref: '#/components/schemas/element-info'
            description: Child element in the visual tree.
          description: Child elements forming the subtree under this element.
    LocatorStrategy:
      type: string
      enum:
        - accessibility-id
        - css-selector
        - type
        - text
        - xpath
      description: Strategy used to locate an element in the visual tree.
    IncludeOption:
      type: array
      items:
        type: string
        enum:
          - screenshot
          - tree
      description: Optional data to include in the action response.
    TapRequest:
      type: object
      description: Request to perform a tap/click action on an element or at coordinates.
      properties:
        elementId:
          type:
            - string
            - 'null'
          description: Target element identifier. Either elementId or coordinates must be provided.
        x:
          type:
            - number
            - 'null'
          description: X coordinate for the tap. Used when tapping by position rather than element.
        'y':
          type:
            - number
            - 'null'
          description: Y coordinate for the tap. Used when tapping by position rather than element.
        include:
          $ref: '#/components/schemas/IncludeOption'
          description: Optional data to include in the response.
    ActionResponse:
      type: object
      description: Response returned after executing an action, optionally including a screenshot and/or visual tree.
      required:
        - success
      properties:
        success:
          type: boolean
          description: Whether the action completed successfully.
        error:
          oneOf:
            - $ref: '#/components/schemas/ProblemDetails'
            - type: 'null'
          description: Error details if the action failed.
        screenshot:
          type:
            - string
            - 'null'
          contentEncoding: base64
          description: Base64-encoded screenshot taken after the action, if requested via include.
        tree:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/element-info'
          description: Visual tree snapshot taken after the action, if requested via include.
    FillRequest:
      type: object
      description: Request to fill text into an input element.
      required:
        - elementId
        - text
      properties:
        elementId:
          type: string
          description: Target input element identifier.
        text:
          type: string
          description: Text content to fill into the element.
        include:
          $ref: '#/components/schemas/IncludeOption'
          description: Optional data to include in the response.
    ClearRequest:
      type: object
      description: Request to clear the content of an input element.
      required:
        - elementId
      properties:
        elementId:
          type: string
          description: Target input element identifier.
        include:
          $ref: '#/components/schemas/IncludeOption'
          description: Optional data to include in the response.
    FocusRequest:
      type: object
      description: Request to move input focus to an element.
      required:
        - elementId
      properties:
        elementId:
          type: string
          description: Target element identifier to receive focus.
        include:
          $ref: '#/components/schemas/IncludeOption'
          description: Optional data to include in the response.
    ScrollRequest:
      type: object
      description: Request to perform a scroll action on a scrollable element.
      properties:
        elementId:
          type:
            - string
            - 'null'
          description: Target scrollable element identifier. If null, scrolls the primary scrollable view.
        deltaX:
          type: number
          description: Horizontal scroll delta in device-independent pixels.
        deltaY:
          type: number
          description: Vertical scroll delta in device-independent pixels.
        animated:
          type: boolean
          description: Whether the scroll should be animated.
          default: true
        itemIndex:
          type:
            - integer
            - 'null'
          description: Index of the item to scroll to in a list or collection view.
          minimum: 0
        groupIndex:
          type:
            - integer
            - 'null'
          description: Index of the group containing the target item.
          minimum: 0
        scrollToPosition:
          type:
            - string
            - 'null'
          enum:
            - makeVisible
            - start
            - center
            - end
            - null
          description: Alignment of the target item within the viewport after scrolling.
        include:
          $ref: '#/components/schemas/IncludeOption'
          description: Optional data to include in the response.
    NavigateRequest:
      type: object
      description: Request to navigate to a named route or URI within the application.
      required:
        - route
      properties:
        route:
          type: string
          description: Route or URI to navigate to.
        include:
          $ref: '#/components/schemas/IncludeOption'
          description: Optional data to include in the response.
    ResizeRequest:
      type: object
      description: Request to resize a window or element.
      required:
        - width
        - height
      properties:
        elementId:
          type:
            - string
            - 'null'
          description: Target window element identifier. If null, resizes the main application window.
        width:
          type: integer
          description: Target width in device-independent pixels.
          minimum: 1
        height:
          type: integer
          description: Target height in device-independent pixels.
          minimum: 1
        include:
          $ref: '#/components/schemas/IncludeOption'
          description: Optional data to include in the response.
    BackRequest:
      type: object
      description: Request to perform a back navigation action.
      properties:
        include:
          $ref: '#/components/schemas/IncludeOption'
          description: Optional data to include in the response.
    KeyRequest:
      type: object
      description: Request to send a key press event.
      required:
        - key
      properties:
        key:
          type: string
          description: Key identifier to press (e.g. 'Enter', 'Escape', 'Tab', 'a', 'F1').
        include:
          $ref: '#/components/schemas/IncludeOption'
          description: Optional data to include in the response.
    GestureAction:
      type: object
      description: A single action within a gesture sequence.
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - pointerMove
            - pointerDown
            - pointerUp
            - pause
          description: The type of gesture action to perform.
        x:
          type:
            - number
            - 'null'
          description: X coordinate for the action.
        'y':
          type:
            - number
            - 'null'
          description: Y coordinate for the action.
        duration:
          type:
            - integer
            - 'null'
          description: Duration of this action in milliseconds.
          minimum: 0
        button:
          type:
            - integer
            - 'null'
          description: Pointer button index (0 = primary, 1 = middle, 2 = secondary).
          default: 0
          minimum: 0
    GestureRequest:
      type: object
      description: Request to perform a complex gesture as a sequence of pointer actions.
      required:
        - actions
      properties:
        actions:
          type: array
          items:
            $ref: '#/components/schemas/GestureAction'
          description: Ordered sequence of gesture actions to perform.
        include:
          $ref: '#/components/schemas/IncludeOption'
          description: Optional data to include in the response.
    BatchAction:
      type: object
      description: A single action within a batch, combining the action type with its parameters.
      required:
        - action
      properties:
        action:
          type: string
          enum:
            - tap
            - fill
            - clear
            - focus
            - scroll
            - navigate
            - resize
            - back
            - key
            - gesture
          description: The type of action to perform.
        elementId:
          type:
            - string
            - 'null'
          description: Target element identifier.
        x:
          type:
            - number
            - 'null'
          description: X coordinate (for tap and gesture actions).
        'y':
          type:
            - number
            - 'null'
          description: Y coordinate (for tap and gesture actions).
        text:
          type:
            - string
            - 'null'
          description: Text content (for fill action).
        deltaX:
          type:
            - number
            - 'null'
          description: Horizontal scroll delta (for scroll action).
        deltaY:
          type:
            - number
            - 'null'
          description: Vertical scroll delta (for scroll action).
        animated:
          type:
            - boolean
            - 'null'
          description: Whether scroll should be animated (for scroll action).
        itemIndex:
          type:
            - integer
            - 'null'
          description: Item index to scroll to (for scroll action).
          minimum: 0
        groupIndex:
          type:
            - integer
            - 'null'
          description: Group index for scroll target (for scroll action).
          minimum: 0
        scrollToPosition:
          type:
            - string
            - 'null'
          enum:
            - makeVisible
            - start
            - center
            - end
            - null
          description: Scroll alignment (for scroll action).
        route:
          type:
            - string
            - 'null'
          description: Route to navigate to (for navigate action).
        width:
          type:
            - integer
            - 'null'
          description: Target width (for resize action).
          minimum: 1
        height:
          type:
            - integer
            - 'null'
          description: Target height (for resize action).
          minimum: 1
        key:
          type:
            - string
            - 'null'
          description: Key to press (for key action).
        actions:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/GestureAction'
          description: Gesture action sequence (for gesture action).
    BatchRequest:
      type: object
      description: Request to perform multiple actions in sequence as a single batch operation.
      required:
        - actions
      properties:
        actions:
          type: array
          items:
            $ref: '#/components/schemas/BatchAction'
          description: Ordered list of actions to perform.
        include:
          $ref: '#/components/schemas/IncludeOption'
          description: Optional data to include in the response.
        continueOnError:
          type: boolean
          description: Whether to continue executing remaining actions if one fails.
          default: false
    WebViewContext:
      type: object
      description: Represents a discovered WebView context within the application.
      required:
        - id
        - url
        - ready
      properties:
        id:
          type: string
          description: Unique identifier for this WebView context.
        elementId:
          type:
            - string
            - 'null'
          description: Identifier linking this WebView to its corresponding element in the native UI tree.
        url:
          type: string
          description: Current URL loaded in the WebView.
        title:
          type:
            - string
            - 'null'
          description: Page title of the WebView content.
        ready:
          type: boolean
          description: Whether the WebView is ready for interaction (page loaded and DOM available).
    EvaluateRequest:
      type: object
      description: Request to evaluate a JavaScript expression in a WebView context.
      required:
        - expression
      properties:
        expression:
          type: string
          description: JavaScript expression to evaluate.
        contextId:
          type:
            - string
            - 'null'
          description: Target WebView context identifier. If null, uses the default or only available context.
        returnByValue:
          type: boolean
          description: Whether to return the result by value (serialized) rather than by reference.
          default: true
    EvaluateResponse:
      type: object
      description: Response from evaluating a JavaScript expression.
      properties:
        result:
          description: The result of the JavaScript evaluation as a JSON value.
        exceptionDetails:
          type:
            - object
            - 'null'
          description: Exception details if the evaluation threw an error.
          properties:
            text:
              type: string
              description: Exception message text.
            lineNumber:
              type:
                - integer
                - 'null'
              description: Line number where the exception occurred.
              minimum: 0
            columnNumber:
              type:
                - integer
                - 'null'
              description: Column number where the exception occurred.
              minimum: 0
    DomQueryRequest:
      type: object
      description: Request to query the DOM using a CSS selector.
      required:
        - selector
      properties:
        selector:
          type: string
          description: CSS selector to query the DOM.
        contextId:
          type:
            - string
            - 'null'
          description: Target WebView context identifier.
    WebViewNavigateRequest:
      type: object
      description: Request to navigate a WebView to a URL.
      required:
        - url
      properties:
        url:
          type: string
          description: URL to navigate the WebView to.
        contextId:
          type:
            - string
            - 'null'
          description: Target WebView context identifier.
    WebViewInputClickRequest:
      type: object
      description: Request to click an element within a WebView using a CSS selector.
      required:
        - selector
      properties:
        selector:
          type: string
          description: CSS selector of the element to click.
        contextId:
          type:
            - string
            - 'null'
          description: Target WebView context identifier.
    WebViewInputFillRequest:
      type: object
      description: Request to fill text into a WebView input element identified by a CSS selector.
      required:
        - selector
        - text
      properties:
        selector:
          type: string
          description: CSS selector of the input element to fill.
        text:
          type: string
          description: Text content to fill into the input element.
        contextId:
          type:
            - string
            - 'null'
          description: Target WebView context identifier.
    WebViewInputTextRequest:
      type: object
      description: Request to type text into the currently focused element within a WebView.
      required:
        - text
      properties:
        text:
          type: string
          description: Text to type into the focused element.
        contextId:
          type:
            - string
            - 'null'
          description: Target WebView context identifier.
    ProfilerCapabilities:
      type: object
      description: Describes the profiler capabilities available on the current platform and agent.
      required:
        - platform
        - managedMemorySupported
        - nativeMemorySupported
        - gcSupported
        - cpuPercentSupported
        - fpsSupported
        - frameTimingsEstimated
        - nativeFrameTimingsSupported
        - jankEventsSupported
        - uiThreadStallSupported
        - threadCountSupported
      properties:
        platform:
          type: string
          description: Platform identifier (e.g. 'ios', 'android', 'maccatalyst').
        managedMemorySupported:
          type: boolean
          description: Whether managed heap memory measurement is supported.
        nativeMemorySupported:
          type: boolean
          description: Whether native memory measurement is supported.
        gcSupported:
          type: boolean
          description: Whether garbage collection counter reporting is supported.
        cpuPercentSupported:
          type: boolean
          description: Whether CPU percentage measurement is supported.
        fpsSupported:
          type: boolean
          description: Whether frames-per-second measurement is supported.
        frameTimingsEstimated:
          type: boolean
          description: Whether frame timings are estimated rather than measured directly.
        nativeFrameTimingsSupported:
          type: boolean
          description: Whether native frame timing measurement is supported.
        jankEventsSupported:
          type: boolean
          description: Whether jank frame detection events are supported.
        uiThreadStallSupported:
          type: boolean
          description: Whether UI thread stall detection is supported.
        threadCountSupported:
          type: boolean
          description: Whether thread count reporting is supported.
    Timestamp:
      type: string
      format: date-time
      description: ISO 8601 date-time timestamp.
    ProfilerSessionInfo:
      type: object
      description: Information about an active or completed profiler session.
      required:
        - sessionId
        - startedAtUtc
        - sampleIntervalMs
        - isActive
      properties:
        sessionId:
          type: string
          description: Unique identifier for this profiler session.
        startedAtUtc:
          $ref: '#/components/schemas/Timestamp'
          description: UTC timestamp when the profiler session started.
        sampleIntervalMs:
          type: integer
          description: Interval between profiler samples in milliseconds.
          minimum: 1
        isActive:
          type: boolean
          description: Whether the profiler session is currently active.
    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.
    ProfilerHotspot:
      type: object
      description: A profiler hotspot identifying a frequently occurring or slow operation.
      required:
        - kind
        - name
        - count
        - avgDurationMs
      properties:
        kind:
          type: string
          description: Kind of hotspot (e.g. 'layout', 'render', 'navigation', 'network').
        name:
          type: string
          description: Name of the operation that is a hotspot.
        screen:
          type:
            - string
            - 'null'
          description: Screen or page where this hotspot occurs.
        count:
          type: integer
          description: Number of times this operation was observed.
          minimum: 0
        errorCount:
          type:
            - integer
            - 'null'
          description: Number of times this operation resulted in an error.
          minimum: 0
        avgDurationMs:
          type: number
          description: Average duration of this operation in milliseconds.
          minimum: 0
        p95DurationMs:
          type:
            - number
            - 'null'
          description: 95th percentile duration in milliseconds.
          minimum: 0
        maxDurationMs:
          type:
            - number
            - 'null'
          description: Maximum observed duration in milliseconds.
          minimum: 0
    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.
    DeviceInfo:
      type: object
      description: Hardware and platform information about the device.
      required:
        - model
        - manufacturer
        - osVersion
        - platform
        - idiom
        - architecture
      properties:
        model:
          type: string
          description: Device model name (e.g. 'iPhone 15 Pro', 'Pixel 8').
        manufacturer:
          type: string
          description: Device manufacturer (e.g. 'Apple', 'Google', 'Samsung').
        osVersion:
          type: string
          description: Operating system version string.
        platform:
          type: string
          description: Platform identifier (e.g. 'ios', 'android', 'maccatalyst', 'windows').
        idiom:
          type: string
          description: Device form factor (e.g. 'phone', 'tablet', 'desktop', 'tv', 'watch').
        architecture:
          type: string
          description: CPU architecture (e.g. 'arm64', 'x64', 'x86').
    DisplayInfo:
      type: object
      description: Display characteristics of the device screen.
      required:
        - width
        - height
        - density
        - orientation
      properties:
        width:
          type: number
          description: Display width in device-independent pixels.
          minimum: 0
        height:
          type: number
          description: Display height in device-independent pixels.
          minimum: 0
        density:
          type: number
          description: Display pixel density (ratio of physical to logical pixels).
          exclusiveMinimum: 0
        orientation:
          type: string
          enum:
            - portrait
            - landscape
          description: Current display orientation.
        refreshRate:
          type:
            - number
            - 'null'
          description: Display refresh rate in Hz, or null if unavailable.
          exclusiveMinimum: 0
    BatteryInfo:
      type: object
      description: Battery status information.
      required:
        - level
        - state
        - powerSource
      properties:
        level:
          type: number
          description: Battery charge level from empty (0) to full (1).
          minimum: 0
          maximum: 1
        state:
          type: string
          enum:
            - unknown
            - charging
            - discharging
            - full
            - notCharging
          description: Current battery charging state.
        powerSource:
          type: string
          enum:
            - unknown
            - battery
            - ac
            - usb
            - wireless
          description: Current power source.
    ConnectivityInfo:
      type: object
      description: Network connectivity status.
      required:
        - networkAccess
        - connectionProfiles
      properties:
        networkAccess:
          type: string
          enum:
            - none
            - local
            - internet
            - constrainedInternet
          description: Level of network access available.
        connectionProfiles:
          type: array
          items:
            type: string
          description: Active connection profiles (e.g. 'wifi', 'cellular', 'ethernet', 'bluetooth').
    AppInfo:
      type: object
      description: Application metadata.
      required:
        - name
        - version
        - buildNumber
        - packageId
      properties:
        name:
          type: string
          description: Display name of the application.
        version:
          type: string
          description: Application version string.
        buildNumber:
          type: string
          description: Application build number.
        packageId:
          type: string
          description: Application package identifier (e.g. 'com.example.myapp').
        theme:
          type:
            - string
            - 'null'
          description: Current application theme (e.g. 'light', 'dark', 'system').
    SensorInfo:
      type: object
      description: Information about a device sensor.
      required:
        - name
        - available
        - active
      properties:
        name:
          type: string
          description: Name of the sensor (e.g. 'accelerometer', 'gyroscope', 'magnetometer', 'barometer', 'compass').
        available:
          type: boolean
          description: Whether this sensor is available on the device.
        active:
          type: boolean
          description: Whether this sensor is currently active and streaming data.
    PermissionInfo:
      type: object
      description: Status of a device permission.
      required:
        - name
        - status
      properties:
        name:
          type: string
          description: Name of the permission (e.g. 'camera', 'location', 'microphone', 'photos', 'contacts').
        status:
          type: string
          enum:
            - unknown
            - denied
            - granted
            - restricted
            - limited
          description: Current status of this permission.
    GeolocationResult:
      type: object
      description: A geolocation reading.
      required:
        - latitude
        - longitude
        - accuracy
        - timestamp
      properties:
        latitude:
          type: number
          description: Latitude in decimal degrees.
          minimum: -90
          maximum: 90
        longitude:
          type: number
          description: Longitude in decimal degrees.
          minimum: -180
          maximum: 180
        altitude:
          type:
            - number
            - 'null'
          description: Altitude in meters above sea level, or null if unavailable.
        accuracy:
          type: number
          description: Horizontal accuracy in meters.
          minimum: 0
        timestamp:
          $ref: '#/components/schemas/Timestamp'
          description: UTC timestamp when the location was determined.
    PlatformJob:
      type: object
      description: A platform background job. Android jobs expose WorkManager fields; iOS and Mac Catalyst jobs expose BGTaskScheduler fields.
      required:
        - identifier
      properties:
        identifier:
          type: string
          description: Platform job identifier. Android maps this to the WorkManager UUID; iOS and Mac Catalyst map this to the BGTask identifier.
        tags:
          type: array
          items:
            type: string
          description: Android WorkManager tags associated with the work.
        state:
          type: string
          description: Android WorkManager state, such as ENQUEUED, RUNNING, SUCCEEDED, FAILED, BLOCKED, or CANCELLED.
        runAttemptCount:
          type: integer
          minimum: 0
          description: Android WorkManager run attempt count.
        type:
          type: string
          enum:
            - processing
            - refresh
          description: iOS or Mac Catalyst BGTask request type.
        earliestBeginDate:
          type: string
          description: Earliest begin date reported by BGTaskScheduler, if present.
      additionalProperties: true
    JobListResponse:
      type: object
      description: Response returned when listing platform background jobs.
      required:
        - platform
        - supported
        - jobs
      properties:
        platform:
          type: string
          description: Platform name reported by the agent.
        type:
          type: string
          description: Platform scheduler implementation, such as WorkManager or BGTaskScheduler.
        supported:
          type: boolean
          description: Whether the current platform supports listing jobs.
        runSupported:
          type: boolean
          description: Whether listed jobs can be triggered by this agent.
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/PlatformJob'
          description: Background jobs reported by the platform.
        error:
          type: string
          description: Platform-specific error message if listing failed.
      additionalProperties: true
    JobRunRequest:
      type: object
      description: Optional request body used when triggering a platform background job.
      properties:
        type:
          type: string
          enum:
            - processing
            - refresh
          description: iOS or Mac Catalyst BGTask request type. If omitted, the agent resolves it from pending requests when possible and otherwise defaults to processing.
      additionalProperties: false
    JobRunResponse:
      type: object
      description: Response returned after attempting to trigger a platform background job.
      required:
        - success
      properties:
        success:
          type: boolean
          description: Whether the job trigger request was submitted successfully.
        supported:
          type: boolean
          description: Whether triggering this job is supported on the current platform.
        identifier:
          type: string
          description: Requested platform job identifier.
        type:
          type: string
          enum:
            - processing
            - refresh
          description: BGTask request type used on iOS or Mac Catalyst.
        message:
          type: string
          description: Human-readable success message.
        error:
          type: string
          description: Human-readable error message.
      additionalProperties: true
    BleStatus:
      type: object
      description: Bluetooth Low Energy monitor status.
      required:
        - isScanning
        - eventCount
        - subscriberCount
        - scanSupported
      properties:
        isScanning:
          type: boolean
          description: Whether a native BLE scan is currently active.
        eventCount:
          type: integer
          minimum: 0
          description: Number of BLE events currently buffered.
        subscriberCount:
          type: integer
          minimum: 0
          description: Number of active BLE event stream subscribers.
        scanSupported:
          type: boolean
          description: Whether this agent implementation supports native BLE scanning.
        error:
          type: string
          description: Last platform-specific BLE error, if any.
      additionalProperties: true
    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
    BleEventsResponse:
      type: object
      description: Response returned when listing buffered BLE events.
      required:
        - events
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/BleEvent'
          description: Buffered BLE events.
    StorageRoot:
      type: object
      description: A logical app storage root advertised by the agent. Absolute device paths are intentionally not exposed.
      required:
        - id
        - displayName
        - kind
        - isWritable
        - isReadOnly
        - isPersistent
        - isBackedUp
        - mayBeClearedBySystem
        - isUserVisible
        - supportedOperations
      properties:
        id:
          type: string
          description: Stable root id to pass as the root query parameter.
        displayName:
          type: string
          description: Human-readable root name.
        kind:
          type: string
          description: Portable root kind, such as appData.
        isWritable:
          type: boolean
          description: Whether files can be uploaded or deleted in this root.
        isReadOnly:
          type: boolean
          description: Whether this root is read-only.
        isPersistent:
          type: boolean
          description: Whether data is expected to persist across app restarts.
        isBackedUp:
          type: boolean
          description: Whether the platform typically backs up this root.
        mayBeClearedBySystem:
          type: boolean
          description: Whether the operating system may purge files in this root.
        isUserVisible:
          type: boolean
          description: Whether the root is normally visible to users outside the app.
        supportedOperations:
          type: array
          items:
            type: string
            enum:
              - list
              - download
              - upload
              - delete
          description: File operations supported by this root.
    StorageRootsResponse:
      type: object
      description: Logical file storage roots advertised by the agent.
      required:
        - roots
      properties:
        roots:
          type: array
          items:
            $ref: '#/components/schemas/StorageRoot'
    FileEntry:
      type: object
      description: A file or directory under a storage root.
      required:
        - name
        - type
        - lastModified
      properties:
        name:
          type: string
          description: Entry name, not including parent directories.
        type:
          type: string
          enum:
            - file
            - directory
          description: Entry kind.
        size:
          type: integer
          minimum: 0
          description: File size in bytes. Present only for file entries.
        lastModified:
          type: string
          format: date-time
          description: UTC timestamp when the entry was last modified.
    FileListResponse:
      type: object
      description: Directory listing under a logical storage root. Absolute device paths are never returned.
      required:
        - root
        - path
        - entries
      properties:
        root:
          type: string
          description: Logical storage root id used for the listing.
        path:
          type: string
          description: Normalized relative directory path. Empty string represents the selected storage root.
        entries:
          type: array
          items:
            $ref: '#/components/schemas/FileEntry'
    FileDownloadResponse:
      type: object
      description: Downloaded file content and metadata.
      required:
        - root
        - path
        - size
        - lastModified
        - contentBase64
      properties:
        root:
          type: string
          description: Logical storage root id used for the download.
        path:
          type: string
          description: Normalized relative file path.
        size:
          type: integer
          minimum: 0
          description: File size in bytes.
        lastModified:
          type: string
          format: date-time
          description: UTC timestamp when the file was last modified.
        contentBase64:
          type: string
          contentEncoding: base64
          description: File content encoded as base64.
    FileUploadRequest:
      type: object
      description: Request to upload file content under a storage root.
      required:
        - contentBase64
      properties:
        contentBase64:
          type: string
          contentEncoding: base64
          description: File content encoded as base64.
    FileUploadResponse:
      type: object
      description: Uploaded file metadata.
      required:
        - success
        - root
        - path
        - size
        - lastModified
      properties:
        success:
          type: boolean
        root:
          type: string
          description: Logical storage root id used for the upload.
        path:
          type: string
          description: Normalized relative file path.
        size:
          type: integer
          minimum: 0
          description: File size in bytes.
        lastModified:
          type: string
          format: date-time
          description: UTC timestamp when the file was last modified.
    FileDeleteResponse:
      type: object
      description: Deleted file metadata.
      required:
        - success
        - root
        - path
      properties:
        success:
          type: boolean
        root:
          type: string
          description: Logical storage root id used for the delete.
        path:
          type: string
          description: Normalized relative file path.
        message:
          type: string
          description: Human-readable delete confirmation.
    PreferenceValueType:
      type: string
      enum:
        - string
        - int
        - bool
        - double
        - float
        - long
        - datetime
      description: Data type of a preference value.
    PreferenceEntry:
      type: object
      description: A single preference key-value entry.
      required:
        - key
        - value
        - type
      properties:
        key:
          type: string
          description: Preference key name.
        value:
          description: Preference value. The actual JSON type depends on the type field.
        type:
          $ref: '#/components/schemas/PreferenceValueType'
          description: Data type of the preference value.
    PreferenceSetRequest:
      type: object
      description: Request to set a preference value.
      required:
        - value
      properties:
        value:
          description: The value to set for the preference.
        type:
          oneOf:
            - $ref: '#/components/schemas/PreferenceValueType'
            - type: 'null'
          description: Data type of the value. If null, the type is auto-detected from the JSON value.
        sharedName:
          type:
            - string
            - 'null'
          description: Shared preference container name. If null, uses the default container.
    SecureStorageSetRequest:
      type: object
      description: Request to set a value in secure (encrypted) storage.
      required:
        - value
      properties:
        value:
          type: string
          description: The string value to store securely.