stablyai/orca · error · RuntimeClientError

unsupported_capability

unsupported_capability

Error message

${capabilities.provider} does not support windows.list

What it means

listWindows reads provider capabilities and throws unsupported_capability if supports.windows.list is false. Different desktop providers (macOS native vs script) advertise different capabilities, and not all support window enumeration. The handshake response declares which operations the active provider implements.

Source

Thrown at src/main/computer/desktop-script-provider-client.ts:83

      apps: (response.apps ?? []).map((app) => ({
        name: app.name,
        bundleId: app.bundleId ?? app.bundleIdentifier ?? null,
        pid: app.pid,
        isRunning: true,
        lastUsedAt: null,
        useCount: null
      }))
    }
  }

  async capabilities(): Promise<ComputerProviderCapabilities> {
    return await this.readCapabilities()
  }

  async listWindows(params: Record<string, unknown>): Promise<ComputerListWindowsResult> {
    const capabilities = await this.readCapabilities()
    if (!capabilities.supports.windows.list) {
      throw new RuntimeClientError(
        'unsupported_capability',
        `${capabilities.provider} does not support windows.list`
      )
    }
    const response = await this.callBridge({
      tool: 'list_windows',
      app: stringParam(params, 'app')
    })
    return {
      app: normalizeBridgeApp(response.app),
      windows: (response.windows ?? []).map((window) => ({
        index: window.index,
        app: normalizeBridgeApp(window.app),
        id: window.id ?? null,
        title: window.title,
        x: window.x ?? null,
        y: window.y ?? null,
        width: window.width,

View on GitHub (pinned to 1136503c6a)

Solutions

Check capabilities().supports.windows.list before calling listWindows.
Fall back to snapshot with windowId/windowIndex targeting instead.
Upgrade the desktop provider script to a version that advertises windows.list.

Example fix

// before
const { windows } = await client.listWindows({ app: 'Safari' })
// after
const caps = await client.capabilities()
if (caps.supports.windows.list) {
  const { windows } = await client.listWindows({ app: 'Safari' })
} else {
  const snap = await client.snapshot({ app: 'Safari' })
  // target via snap.windowId / windowIndex
}

Defensive patterns

Strategy: validation

Validate before calling

const caps = await client.capabilities()
if (!caps.supports.windows.list) {
  // fall back to snapshot-based window targeting instead of listWindows
}

Try / catch

try {
  return await client.listWindows(params)
} catch (err) {
  if (err instanceof RuntimeClientError && err.code === 'unsupported_capability') {
    // fall back to snapshot and use windowId/windowIndex
  }
  throw err
}

Prevention

Query capabilities once and cache the result.
Feature-detect before using optional provider operations.

When it happens

Trigger: Calling listWindows on a provider whose handshake capabilities lack windows.list=true; running an older or minimal provider script.

Common situations: Running on a platform or provider without window-list support; mismatched client and provider versions; assuming all providers enumerate windows.

Related errors

AI-assisted analysis of stablyai/orca@1136503c6a (2026-08-12). Data as JSON: /api/errors/04c0ab7937bde403. Report an issue: GitHub.