Skip to content

armgit / orca

Public Imported from GitHub
0

Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.

21.6 KB
Raw Blame
import { SKILL_INSTALL_RESULT_V2_CAPABILITY } from '../../shared/skill-install-capability'
import { AGENT_LAUNCH_RUNTIME_CAPABILITY } from '../../shared/agent-launch-runtime-capability'
import { createServer, type Server } from 'node:http'
import { mkdtempSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, describe, expect, it, vi } from 'vitest'
import { WebSocketServer } from 'ws'
import { encodePairingOffer, type PairingOffer } from '../../shared/pairing'
import type { RuntimeStatus } from '../../shared/runtime-types'
import {
  decrypt,
  deriveSharedKey,
  encrypt,
  generateKeyPair,
  publicKeyToBase64
} from '../../shared/e2ee-crypto'
import { sendWebSocketRequestWithStatusPreflight } from './websocket-transport'
import { getRemoteRuntimeRequestAdmissionEvidence } from '../../shared/remote-runtime/requests/remote-runtime-prepared-request-admission'
import { RuntimeClient } from './client'
import { requestWorktreeRemoval } from '../handlers/worktree-removal-request'
import { launchOrcaApp } from './launch'
import { addEnvironmentFromPairingCode } from './environments'
import { RuntimeClientError } from './types'
import {
  AGENT_SESSION_BACKGROUND_TASK_ROW_STOP_CAPABILITY,
  AGENT_SESSION_TURN_ITEM_CAPABILITY,
  AGENT_SESSION_BACKGROUND_TASK_STOP_CAPABILITY,
  AGENT_SESSION_BOUNDARY_RUNTIME_CAPABILITY,
  AUTOMATION_OWNER_FENCING_RUNTIME_CAPABILITY,
  MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION,
  REPO_SEARCH_QUALIFIED_REFS_RUNTIME_CAPABILITY,
  RUNTIME_PROTOCOL_VERSION,
  SESSION_TABS_AUTHORITATIVE_INVENTORY_RUNTIME_CAPABILITY,
  SESSION_TAB_CLOSE_INTENT_RUNTIME_CAPABILITY,
  WORKTREE_GITHUB_PR_SUPPRESSION_RUNTIME_CAPABILITY,
  WORKTREE_VISIBILITY_DEFAULTS_RUNTIME_CAPABILITY,
  WORKTREE_VISIBILITY_SOURCE_DEFAULTS_RUNTIME_CAPABILITY
} from '../../shared/protocol-version'
import {
  TERMINAL_QUICK_COMMAND_LARGE_LISTS_RUNTIME_CAPABILITY,
  TERMINAL_QUICK_COMMAND_LONG_PROMPTS_RUNTIME_CAPABILITY
} from '../../shared/terminal-quick-command-capabilities'
import { AGENT_SESSION_BACKGROUND_TASK_CHILD_VIEWS_CAPABILITY } from '../../shared/agent-session-background-task-child-views-capability'

vi.mock('./launch', () => ({
  launchOrcaApp: vi.fn()
}))

type TestRuntime = {
  endpoint: string
  publicKeyB64: string
  deviceToken: string
  authFrames: Record<string, unknown>[]
  requestMethods: string[]
  requestParams: unknown[]
  connectionCount: () => number
  close: () => Promise<void>
}

describe('CLI remote WebSocket transport', () => {
  const servers: TestRuntime[] = []

  afterEach(async () => {
    vi.mocked(launchOrcaApp).mockClear()
    await Promise.all(servers.splice(0).map((server) => server.close()))
  })

  it('calls a remote runtime through a mobile pairing offer', async () => {
    const runtime = await startTestRuntime('runtime-ws-1')
    servers.push(runtime)

    const pairingUrl = encodePairingOffer({
      v: 2,
      endpoint: runtime.endpoint,
      deviceToken: runtime.deviceToken,
      publicKeyB64: runtime.publicKeyB64
    })
    const client = new RuntimeClient('/tmp/unused', 5_000, pairingUrl)
    const response = await client.call<{ runtimeId: string }>('status.get')
    expect(await client.getOfflineRuntimeAdmission()).toEqual({
      reachable: true,
      legacyPidRunning: false,
      pid: null
    })

    expect(response.ok).toBe(true)
    expect(response.result.runtimeId).toBe('runtime-ws-1')
    expect(runtime.authFrames).toContainEqual(
      expect.objectContaining({
        clientCapabilities: [
          AGENT_SESSION_BACKGROUND_TASK_STOP_CAPABILITY,
          AGENT_SESSION_BACKGROUND_TASK_ROW_STOP_CAPABILITY,
          AGENT_SESSION_BACKGROUND_TASK_CHILD_VIEWS_CAPABILITY,
          AGENT_SESSION_TURN_ITEM_CAPABILITY,
          SESSION_TAB_CLOSE_INTENT_RUNTIME_CAPABILITY,
          SESSION_TABS_AUTHORITATIVE_INVENTORY_RUNTIME_CAPABILITY,
          AGENT_SESSION_BOUNDARY_RUNTIME_CAPABILITY,
          SKILL_INSTALL_RESULT_V2_CAPABILITY,
          WORKTREE_GITHUB_PR_SUPPRESSION_RUNTIME_CAPABILITY,
          WORKTREE_VISIBILITY_DEFAULTS_RUNTIME_CAPABILITY,
          WORKTREE_VISIBILITY_SOURCE_DEFAULTS_RUNTIME_CAPABILITY,
          AUTOMATION_OWNER_FENCING_RUNTIME_CAPABILITY,
          REPO_SEARCH_QUALIFIED_REFS_RUNTIME_CAPABILITY,
          TERMINAL_QUICK_COMMAND_LONG_PROMPTS_RUNTIME_CAPABILITY,
          TERMINAL_QUICK_COMMAND_LARGE_LISTS_RUNTIME_CAPABILITY,
          AGENT_LAUNCH_RUNTIME_CAPABILITY
        ]
      })
    )
  })

  it('rejects malformed remote pairing codes before local runtime lookup', () => {
    expect(() => new RuntimeClient('/tmp/unused', 5_000, 'not-a-pairing-code')).toThrow(
      RuntimeClientError
    )
  })

  it('accepts a bare pairing payload as well as the orca URL wrapper', async () => {
    const runtime = await startTestRuntime('runtime-ws-2', {
      appVersion: '1.5.0',
      remoteUpdateSupport: {
        installMode: 'unsupported-headless-serve',
        automatic: false,
        reason: 'manual-service-update-required'
      },
      capabilities: ['updater.remote-control.v1'],
      degradations: [
        {
          code: 'browser_unavailable',
          capability: 'browser.headless.v1',
          message: 'Browser automation is unavailable.'
        }
      ]
    })
    servers.push(runtime)
    const offer: PairingOffer = {
      v: 2,
      endpoint: runtime.endpoint,
      deviceToken: runtime.deviceToken,
      publicKeyB64: runtime.publicKeyB64
    }
    const pairingUrl = encodePairingOffer(offer)
    const barePayload = new URLSearchParams(pairingUrl.slice(pairingUrl.indexOf('?') + 1)).get(
      'code'
    )!

    const client = new RuntimeClient('/tmp/unused', 5_000, barePayload)
    const status = await client.getCliStatus()

    expect(status.result.app).toEqual({ running: false, pid: null })
    expect(status.result.runtime.reachable).toBe(true)
    expect(status.result.runtime.runtimeId).toBe('runtime-ws-2')
    expect(status.result.runtime).toMatchObject({
      appVersion: '1.5.0',
      remoteUpdateSupport: { automatic: false, reason: 'manual-service-update-required' },
      capabilities: ['updater.remote-control.v1'],
      degradations: [expect.objectContaining({ code: 'browser_unavailable' })]
    })
  })

  it('does not launch a local desktop app for remote-paired open', async () => {
    const runtime = await startTestRuntime('runtime-remote-headless', {
      desktopWindowStatus: 'initializing'
    })
    servers.push(runtime)
    const client = new RuntimeClient(
      '/tmp/unused',
      5_000,
      encodePairingOffer({
        v: 2,
        endpoint: runtime.endpoint,
        deviceToken: runtime.deviceToken,
        publicKeyB64: runtime.publicKeyB64
      })
    )

    const status = await client.openOrca()

    expect(status.result.app.desktopWindowStatus).toBe('initializing')
    expect(launchOrcaApp).not.toHaveBeenCalled()
  })

  it('connects through a saved environment selector', async () => {
    const runtime = await startTestRuntime('runtime-env-1')
    servers.push(runtime)
    const userDataPath = mkdtempSync(join(tmpdir(), 'orca-cli-env-'))
    addEnvironmentFromPairingCode(userDataPath, {
      name: 'remote-dev',
      pairingCode: encodePairingOffer({
        v: 2,
        endpoint: runtime.endpoint,
        deviceToken: runtime.deviceToken,
        publicKeyB64: runtime.publicKeyB64
      })
    })

    const client = new RuntimeClient(userDataPath, 5_000, null, 'remote-dev')
    const status = await client.getCliStatus()

    expect(status.result.app).toEqual({ running: false, pid: null })
    expect(status.result.runtime.reachable).toBe(true)
    expect(status.result.runtime.runtimeId).toBe('runtime-env-1')
  })

  it('blocks remote RPCs when the server protocol is too old', async () => {
    const runtime = await startTestRuntime('runtime-old', { runtimeProtocolVersion: 1 })
    servers.push(runtime)

    const client = new RuntimeClient(
      '/tmp/unused',
      5_000,
      encodePairingOffer({
        v: 2,
        endpoint: runtime.endpoint,
        deviceToken: runtime.deviceToken,
        publicKeyB64: runtime.publicKeyB64
      })
    )

    await expect(client.call('repo.list')).rejects.toMatchObject({
      code: 'incompatible_runtime',
      message: expect.stringContaining('server is too old')
    })
    expect(runtime.connectionCount()).toBe(1)
    expect(runtime.authFrames).toHaveLength(1)
    expect(runtime.requestMethods).toEqual(['status.get'])
  })

  it('preflights and dispatches through one authenticated connection', async () => {
    const runtime = await startTestRuntime('runtime-single-auth')
    servers.push(runtime)
    const client = new RuntimeClient(
      '/tmp/unused',
      5_000,
      encodePairingOffer({
        v: 2,
        endpoint: runtime.endpoint,
        deviceToken: runtime.deviceToken,
        publicKeyB64: runtime.publicKeyB64
      })
    )

    await expect(client.call('repo.list')).rejects.toMatchObject({ code: 'method_not_found' })

    expect(runtime.connectionCount()).toBe(1)
    expect(runtime.authFrames).toHaveLength(1)
    expect(runtime.requestMethods).toEqual(['status.get', 'repo.list'])
  })

  it('blocks orchestration mutations when a remote runtime lacks the contract capability', async () => {
    const runtime = await startTestRuntime('runtime-old-orchestration', { capabilities: [] })
    servers.push(runtime)
    const client = new RuntimeClient(
      '/tmp/unused',
      5_000,
      encodePairingOffer({
        v: 2,
        endpoint: runtime.endpoint,
        deviceToken: runtime.deviceToken,
        publicKeyB64: runtime.publicKeyB64
      })
    )

    await expect(client.call('orchestration.send', { subject: 'hello' })).rejects.toMatchObject({
      code: 'orchestration_migration_required',
      data: {
        reason: 'runtime_capability_missing',
        effectsApplied: false
      }
    })
  })

  it.each(['status', 'capable-mutation', 'legacy-mutation'] as const)(
    'reports paired timeout at %s without replay',
    async (phase) => {
      const received = Promise.withResolvers<void>()
      const status: Parameters<typeof startTestRuntime>[1] = {
        capabilities: ['worktree.remove-branch-policy.v1']
      }
      const runtime = await startTestRuntime('timeout', status)
      servers.push(runtime)
      const client = new RuntimeClient(
        '/tmp/unused',
        5000,
        encodePairingOffer({
          v: 2,
          endpoint: runtime.endpoint,
          deviceToken: runtime.deviceToken,
          publicKeyB64: runtime.publicKeyB64
        })
      )
      await client.getCliStatus()
      status.hold = phase === 'status' ? 'status.get' : 'worktree.rm'
      if (phase === 'legacy-mutation') {
        status.capabilities = undefined
      }
      status.onRequest = (method) => {
        if (method === status.hold) {
          received.resolve()
        }
      }
      const warning = vi.spyOn(console, 'error').mockImplementation(() => {})
      vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] })
      try {
        const response = requestWorktreeRemoval(client, {
          worktree: 'id:task',
          hostId: 'local',
          force: false,
          deleteBranch: false,
          runHooks: false,
          allowFailedArchiveHook: false
        }).catch((error: unknown) => error)
        await received.promise
        await vi.runAllTimersAsync()
        expect(await response).toMatchObject({
          code: phase === 'status' ? 'runtime_timeout' : 'worktree_removal_in_progress'
        })
        expect(runtime.requestMethods).toEqual(
          phase === 'status'
            ? ['status.get', 'status.get']
            : ['status.get', 'status.get', 'worktree.rm']
        )
        expect(warning.mock.calls).toHaveLength(phase === 'legacy-mutation' ? 1 : 0)
        expect(getRemoteRuntimeRequestAdmissionEvidence()).toEqual({
          pendingRequestCount: 0,
          retainedBytes: 0
        })
      } finally {
        vi.useRealTimers()
        warning.mockRestore()
      }
    }
  )

  it('selects paired params before serialization and releases failed preparation without dispatch', async () => {
    const runtime = await startTestRuntime('prepare')
    servers.push(runtime)
    const dispatched = vi.fn()
    await expect(
      sendWebSocketRequestWithStatusPreflight(
        {
          endpoint: runtime.endpoint,
          hostPublicKeyB64: runtime.publicKeyB64,
          credential: { kind: 'token', deviceToken: runtime.deviceToken }
        },
        'worktree.rm',
        {},
        5000,
        () => {},
        undefined,
        { paramsForStatus: () => ({ value: 1n }), onDispatch: dispatched }
      )
    ).rejects.toBeInstanceOf(Error)
    expect(dispatched).not.toHaveBeenCalled()
    expect(runtime.requestMethods).toEqual(['status.get'])
    expect(getRemoteRuntimeRequestAdmissionEvidence()).toEqual({
      pendingRequestCount: 0,
      retainedBytes: 0
    })
  })

  it.each([
    'capable',
    'absent',
    'empty',
    'unrelated',
    'malformed',
    'failed',
    'disconnect',
    'after-send',
    'protocol',
    'auth'
  ] as const)(
    'preflights branch intent on the mutation socket after cached compatibility: %s',
    async (mode) => {
      const status: NonNullable<Parameters<typeof startTestRuntime>[1]> = {
        capabilities: ['worktree.remove-branch-policy.v1'],
        malformed: false,
        failure: false,
        disconnect: false,
        mutationDisconnect: false,
        rejectAuth: false,
        runtimeProtocolVersion: RUNTIME_PROTOCOL_VERSION
      }
      const runtime = await startTestRuntime('removal', status)
      servers.push(runtime)
      const client = new RuntimeClient(
        '/tmp/unused',
        5000,
        encodePairingOffer({
          v: 2,
          endpoint: runtime.endpoint,
          deviceToken: runtime.deviceToken,
          publicKeyB64: runtime.publicKeyB64
        })
      )
      await client.getCliStatus()
      if (mode === 'absent') {
        status.capabilities = undefined
      }
      if (mode === 'empty') {
        status.capabilities = []
      }
      if (mode === 'unrelated') {
        status.capabilities = ['future.capability']
      }
      status.malformed = mode === 'malformed'
      const successful = ['capable', 'absent', 'empty', 'unrelated'].includes(mode)
      const warning = vi.spyOn(console, 'error').mockImplementation(() => {})
      status.failure = mode === 'failed'
      status.disconnect = mode === 'disconnect'
      status.mutationDisconnect = mode === 'after-send'
      status.rejectAuth = mode === 'auth'
      if (mode === 'protocol') {
        status.runtimeProtocolVersion = 0
      }
      const removal = requestWorktreeRemoval(client, {
        worktree: 'id:task',
        hostId: 'local',
        force: false,
        deleteBranch: false,
        runHooks: false,
        allowFailedArchiveHook: false
      })
      await (successful
        ? expect(removal).resolves.toMatchObject({ result: { removed: true } })
        : expect(removal).rejects.toBeInstanceOf(Error))
      expect(
        warning.mock.calls.filter(([message]) => String(message).includes('host is older'))
      ).toHaveLength(successful && mode !== 'capable' ? 1 : 0)
      if (successful) {
        expect(runtime.requestParams.at(-1)).toEqual({
          worktree: 'id:task',
          hostId: 'local',
          force: false,
          runHooks: false,
          allowFailedArchiveHook: false,
          allowUnverifiedPtyStop: false,
          waitForBackgroundRemoval: true,
          ...(mode === 'capable' ? { deleteBranch: false } : {})
        })
      }
      warning.mockRestore()
      expect(runtime.connectionCount()).toBe(2)
      expect(runtime.requestMethods).toEqual(
        successful || mode === 'after-send'
          ? ['status.get', 'status.get', 'worktree.rm']
          : mode === 'auth'
            ? ['status.get']
            : ['status.get', 'status.get']
      )
    }
  )
})

async function startTestRuntime(
  runtimeId: string,
  statusOverrides: {
    runtimeProtocolVersion?: number
    minCompatibleRuntimeClientVersion?: number
    desktopWindowStatus?: 'available' | 'openable' | 'initializing' | 'blocked'
    appVersion?: string
    remoteUpdateSupport?: {
      installMode: 'unsupported-headless-serve'
      automatic: false
      reason: 'manual-service-update-required'
    }
    capabilities?: string[]
    malformed?: boolean
    failure?: boolean
    hold?: string
    onRequest?: (method: string) => void
    disconnect?: boolean
    mutationDisconnect?: boolean
    rejectAuth?: boolean
    degradations?: RuntimeStatus['degradations']
  } = {}
): Promise<TestRuntime> {
  const serverKeyPair = generateKeyPair()
  const deviceToken = `token-${runtimeId}`
  const httpServer = createServer()
  const wss = new WebSocketServer({ server: httpServer })
  const authFrames: Record<string, unknown>[] = []
  const requestMethods: string[] = []
  const requestParams: unknown[] = []
  let connectionCount = 0

  wss.on('connection', (ws) => {
    connectionCount += 1
    let sharedKey: Uint8Array | null = null
    let authenticated = false

    ws.on('message', (data) => {
      const frame = data.toString()
      if (!sharedKey) {
        const hello = JSON.parse(frame) as Record<string, unknown> & {
          type?: string
          publicKeyB64?: string
        }
        const clientPublicKey = Buffer.from(hello.publicKeyB64 ?? '', 'base64')
        sharedKey = deriveSharedKey(serverKeyPair.secretKey, clientPublicKey)
        ws.send(JSON.stringify({ type: 'e2ee_ready' }))
        return
      }

      const plaintext = decrypt(frame, sharedKey)
      if (!plaintext) {
        ws.close(4003, 'decrypt failed')
        return
      }
      if (!authenticated) {
        const auth = JSON.parse(plaintext) as Record<string, unknown> & {
          type?: string
          deviceToken?: string
        }
        authFrames.push(auth)
        if (
          auth.type !== 'e2ee_auth' ||
          auth.deviceToken !== deviceToken ||
          statusOverrides.rejectAuth
        ) {
          ws.send(encrypt(JSON.stringify({ type: 'e2ee_error' }), sharedKey))
          ws.close(4001, 'auth failed')
          return
        }
        authenticated = true
        ws.send(encrypt(JSON.stringify({ type: 'e2ee_authenticated' }), sharedKey))
        return
      }

      const request: { id: string; method: string; params?: unknown } = JSON.parse(plaintext)
      requestMethods.push(request.method)
      requestParams.push(request.params)
      statusOverrides.onRequest?.(request.method)
      if (request.method === statusOverrides.hold) {
        return
      }
      if (request.method === 'status.get' && statusOverrides.disconnect) {
        ws.close()
        return
      }
      if (request.method === 'worktree.rm' && statusOverrides.mutationDisconnect) {
        ws.close()
        return
      }
      const response =
        request.method === 'status.get' && statusOverrides.failure
          ? {
              id: request.id,
              ok: false,
              error: { code: 'runtime_unavailable', message: 'status failed' },
              _meta: { runtimeId }
            }
          : request.method === 'worktree.rm'
            ? { id: request.id, ok: true, result: { removed: true }, _meta: { runtimeId } }
            : request.method === 'status.get'
              ? {
                  id: request.id,
                  ok: true,
                  result: statusOverrides.malformed
                    ? { capabilities: 42 }
                    : {
                        runtimeId,
                        rendererGraphEpoch: 1,
                        graphStatus: 'ready',
                        authoritativeWindowId: null,
                        desktopWindowStatus: statusOverrides.desktopWindowStatus,
                        liveTabCount: 0,
                        liveLeafCount: 0,
                        runtimeProtocolVersion:
                          statusOverrides.runtimeProtocolVersion ?? RUNTIME_PROTOCOL_VERSION,
                        minCompatibleRuntimeClientVersion:
                          statusOverrides.minCompatibleRuntimeClientVersion ??
                          MIN_COMPATIBLE_RUNTIME_CLIENT_VERSION,
                        appVersion: statusOverrides.appVersion,
                        remoteUpdateSupport: statusOverrides.remoteUpdateSupport,
                        capabilities: statusOverrides.capabilities,
                        degradations: statusOverrides.degradations
                      },
                  _meta: { runtimeId }
                }
              : {
                  id: request.id,
                  ok: false,
                  error: { code: 'method_not_found', message: 'Unknown method' },
                  _meta: { runtimeId }
                }
      ws.send(encrypt(JSON.stringify(response), sharedKey))
    })
  })

  await listen(httpServer)
  const address = httpServer.address()
  if (!address || typeof address === 'string') {
    throw new Error('Expected TCP test server')
  }

  return {
    endpoint: `ws://127.0.0.1:${address.port}`,
    publicKeyB64: publicKeyToBase64(serverKeyPair.publicKey),
    deviceToken,
    authFrames,
    requestMethods,
    requestParams,
    connectionCount: () => connectionCount,
    close: async () => {
      await new Promise<void>((resolve) => {
        wss.close(() => resolve())
        for (const client of wss.clients) {
          client.close()
        }
      })
      await closeHttpServer(httpServer)
    }
  }
}

async function listen(server: Server): Promise<void> {
  await new Promise<void>((resolve, reject) => {
    server.once('error', reject)
    server.listen(0, '127.0.0.1', () => {
      server.off('error', reject)
      resolve()
    })
  })
}

async function closeHttpServer(server: Server): Promise<void> {
  await new Promise<void>((resolve, reject) => {
    server.close((error) => {
      if (error) {
        reject(error)
        return
      }
      resolve()
    })
  })
}