naftiko: 1.0.0-alpha2
info:
  label: Browserless — Sessions
  description: >-
    Browserless Sessions capability covering session lifecycle (/session,
    /sessions), reconnect URLs, active/kill management, /meta diagnostics,
    and /json/{new,version,protocol} CDP endpoints. Lets agents create,
    reuse, inspect, and tear down long-lived browser sessions.
  tags:
    - Browserless
    - Sessions
    - CDP
    - Lifecycle
  created: '2026-05-25'
  modified: '2026-05-25'
binds:
  - namespace: env
    keys:
      BROWSERLESS_API_TOKEN: BROWSERLESS_API_TOKEN
capability:
  consumes:
    - type: http
      namespace: sessions
      baseUri: https://production-sfo.browserless.io
      description: Browserless session-management consumes block.
      resources:
        - name: session
          path: /session
          operations:
            - name: createSession
              method: POST
              description: Create a long-lived browser session.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
              inputParameters:
                - name: body
                  in: body
                  type: object
                  required: true
                - name: token
                  in: query
                  type: string
                  required: true
        - name: sessions
          path: /sessions
          operations:
            - name: listSessions
              method: GET
              description: List active sessions for the token.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: array
                  value: $.
              inputParameters:
                - name: token
                  in: query
                  type: string
                  required: true
        - name: active
          path: /active
          operations:
            - name: getActive
              method: GET
              description: Return whether at least one session is active.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
              inputParameters:
                - name: token
                  in: query
                  type: string
                  required: true
        - name: kill
          path: /kill/{trackingId}
          operations:
            - name: killSession
              method: GET
              description: Terminate the session matching the supplied trackingId.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
              inputParameters:
                - name: trackingId
                  in: path
                  type: string
                  required: true
                - name: token
                  in: query
                  type: string
                  required: true
        - name: meta
          path: /meta
          operations:
            - name: getMeta
              method: GET
              description: Diagnostic metadata for the running instance.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
              inputParameters:
                - name: token
                  in: query
                  type: string
                  required: true
        - name: json-new
          path: /json/new
          operations:
            - name: newTarget
              method: PUT
              description: Open a new CDP target / tab.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
              inputParameters:
                - name: token
                  in: query
                  type: string
                  required: true
        - name: json-version
          path: /json/version
          operations:
            - name: getVersion
              method: GET
              description: Return CDP version information for the running browser.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
              inputParameters:
                - name: token
                  in: query
                  type: string
                  required: true
        - name: json-protocol
          path: /json/protocol
          operations:
            - name: getProtocol
              method: GET
              description: Return the Chrome DevTools Protocol descriptor.
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: $.
              inputParameters:
                - name: token
                  in: query
                  type: string
                  required: true
      authentication:
        type: apikey
        key: token
        value: '{{env.BROWSERLESS_API_TOKEN}}'
        placement: query
  exposes:
    - type: rest
      namespace: sessions-rest
      port: 8080
      description: REST adapter for sessions.
      resources:
        - path: /session
          name: session
          operations:
            - method: POST
              name: createSession
              call: sessions.createSession
              with: { body: rest.body }
              outputParameters: [{ type: object, mapping: $. }]
        - path: /sessions
          name: sessions
          operations:
            - method: GET
              name: listSessions
              call: sessions.listSessions
              outputParameters: [{ type: array, mapping: $. }]
        - path: /active
          name: active
          operations:
            - method: GET
              name: getActive
              call: sessions.getActive
              outputParameters: [{ type: object, mapping: $. }]
        - path: /kill/{trackingId}
          name: kill
          operations:
            - method: GET
              name: killSession
              call: sessions.killSession
              outputParameters: [{ type: object, mapping: $. }]
        - path: /meta
          name: meta
          operations:
            - method: GET
              name: getMeta
              call: sessions.getMeta
              outputParameters: [{ type: object, mapping: $. }]
    - type: mcp
      namespace: sessions-mcp
      port: 9090
      transport: http
      description: MCP adapter for session management.
      tools:
        - name: browserless-create-session
          description: Create a long-lived browser session.
          hints: { readOnly: false, destructive: false, idempotent: false }
          call: sessions.createSession
          with: { body: tools.body }
          outputParameters: [{ type: object, mapping: $. }]
        - name: browserless-list-sessions
          description: List active sessions for the token.
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: sessions.listSessions
          outputParameters: [{ type: array, mapping: $. }]
        - name: browserless-active
          description: Check whether any sessions are active.
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: sessions.getActive
          outputParameters: [{ type: object, mapping: $. }]
        - name: browserless-kill-session
          description: Terminate the session matching trackingId.
          hints: { readOnly: false, destructive: true, idempotent: true }
          call: sessions.killSession
          outputParameters: [{ type: object, mapping: $. }]
        - name: browserless-meta
          description: Diagnostic metadata.
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: sessions.getMeta
          outputParameters: [{ type: object, mapping: $. }]