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.
TypeScript adeagent-ideai-agentsautomationbotclaude-codecodexghosttygrok-bothermes-agentmobile-appmuseopenclawopencodeorchestrationpiruntimeterminalworktreesyc-backed
import { describe, expect, it } from 'vitest'
import { ID, harness } from './bridge-host-test-harness'
import { clientFrame, createFakeRpcClient, flushBridge } from './bridge-host-test-fakes'
import {
BRIDGE_EXTERNAL_LINK_GRANT,
BRIDGE_FAULT_GRANT,
BRIDGE_NAVIGATE_BACK_NOTIFY
} from './bridge/bridge-envelope'
import { BRIDGE_PAGE_PAINTED } from './bridge/bridge-page-painted'
import { BRIDGE_ROUTE_PARAM_CLEAR } from './bridge/bridge-route-update'
import { BRIDGE_HAPTICS_GRANT, BRIDGE_HAPTICS_NOTIFY } from './bridge/bridge-haptics-notify'
import { BRIDGE_LIVENESS_PROBE_NOTIFY } from './bridge/bridge-liveness-probe-notify'
import { MOBILE_WEB_SHELL_GRANTS } from './page-route-policy'
describe('notifications, refusals and the fence', () => {
it('forwards foreground with the arity the page used, and the viewport whole', () => {
const bridge = harness({ routeGrants: [] })
bridge.host.receive(clientFrame({ type: 'ready' }))
bridge.host.receive(clientFrame({ type: 'notify', name: 'foreground' }))
bridge.host.receive(clientFrame({ type: 'notify', name: 'foreground', reason: 'app-resume' }))
bridge.host.receive(
clientFrame({ type: 'notify', name: 'terminalViewport', terminal: 't1', cols: 80, rows: 24 })
)
expect(bridge.client.foregroundCalls).toEqual([[], ['app-resume']])
expect(bridge.client.viewports).toEqual([{ terminal: 't1', cols: 80, rows: 24 }])
})
it('hands a page fault to the session and asks the client for nothing', () => {
const bridge = harness()
bridge.host.receive(clientFrame({ type: 'ready' }))
bridge.host.receive(
clientFrame({
type: 'notify',
name: BRIDGE_FAULT_GRANT,
error: { category: 'Error', message: 'route threw', isRpcDeliveryUnknown: false }
})
)
expect(bridge.frames()[0]).toMatchObject({
type: 'init',
grants: { native: expect.arrayContaining(['fault']) }
})
expect(bridge.pageFaults).toEqual([
{ category: 'Error', message: 'route threw', isRpcDeliveryUnknown: false }
])
expect(bridge.client.requests).toHaveLength(0)
expect(bridge.client.foregroundCalls).toEqual([])
expect(bridge.diagnostics).toEqual([])
})
it('refuses a notify from a page it has told nothing, grant or no grant', () => {
const bridge = harness()
bridge.host.receive(
clientFrame({
type: 'notify',
name: BRIDGE_FAULT_GRANT,
error: { category: 'Error', message: 'route threw', isRpcDeliveryUnknown: false }
})
)
bridge.host.receive(clientFrame({ type: 'notify', name: 'foreground' }))
bridge.host.receive(
clientFrame({ type: 'notify', name: 'terminalViewport', terminal: 't1', cols: 80, rows: 24 })
)
expect(bridge.client.viewports).toEqual([])
expect(bridge.pageFaults).toEqual([])
expect(bridge.client.foregroundCalls).toEqual([])
expect(bridge.diagnostics).toEqual([
{ kind: 'notify-refused', name: BRIDGE_FAULT_GRANT, why: 'before-ready' },
{ kind: 'notify-refused', name: 'foreground', why: 'before-ready' },
{ kind: 'notify-refused', name: 'terminalViewport', why: 'before-ready' }
])
})
it('drops a page fault that arrives after the document said goodbye', () => {
const bridge = harness()
bridge.host.receive(clientFrame({ type: 'close' }))
bridge.host.receive(
clientFrame({
type: 'notify',
name: BRIDGE_FAULT_GRANT,
error: { category: 'Error', message: 'late', isRpcDeliveryUnknown: false }
})
)
expect(bridge.pageFaults).toEqual([])
expect(bridge.diagnostics).toEqual([{ kind: 'frame-after-close' }])
})
it('reports a listener that throws on a page fault once, and keeps reading', () => {
const failure = new Error('the session is gone')
const bridge = harness({
onPageFault: () => {
throw failure
}
})
const fault = clientFrame({
type: 'notify',
name: BRIDGE_FAULT_GRANT,
error: { category: 'Error', message: 'route threw', isRpcDeliveryUnknown: false }
})
bridge.host.receive(clientFrame({ type: 'ready' }))
// Never let a throw escape the native event handler delivering this frame.
bridge.host.receive(fault)
bridge.host.receive(fault)
expect(bridge.diagnostics).toEqual([{ kind: 'notify-failed', error: failure }])
bridge.host.receive(clientFrame({ type: 'ready' }))
expect(bridge.last().type).toBe('init')
})
it('reports a refused frame and forwards nothing from it', () => {
const bridge = harness()
bridge.host.receive('{"v":1,"type":')
bridge.host.receive(clientFrame({ type: 'request', id: 'short', method: 'x' }))
expect(bridge.diagnostics).toEqual([
{ kind: 'refused', refusal: 'malformed-json' },
{ kind: 'refused', refusal: 'unrecognised-message' }
])
expect(bridge.client.requests).toHaveLength(0)
})
it('reports a client that throws on a notify once per session, and keeps reading', () => {
const client = createFakeRpcClient()
const failure = new Error('no client')
const bridge = harness({
client: {
...client,
notifyForeground: () => {
throw failure
},
updateTerminalSubscriptionViewport: () => {
throw failure
}
}
})
bridge.host.receive(clientFrame({ type: 'ready' }))
// Never let a throw escape the native event handler delivering this frame.
bridge.host.receive(clientFrame({ type: 'notify', name: 'foreground' }))
bridge.host.receive(
clientFrame({ type: 'notify', name: 'terminalViewport', terminal: 't1', cols: 80, rows: 24 })
)
expect(bridge.diagnostics).toEqual([{ kind: 'notify-failed', error: failure }])
bridge.host.receive(clientFrame({ type: 'ready' }))
expect(bridge.last().type).toBe('init')
})
it('reports a post that throws instead of rejecting, and does not take the sender down', () => {
const failure = new Error('the bridge module is gone')
const client = createFakeRpcClient()
const bridge = harness({
client,
post: () => {
throw failure
}
})
// State frames run inside client fan-out; a thrown post must not take down sibling listeners.
expect(() => client.pushState('reconnecting')).not.toThrow()
expect(bridge.diagnostics).toEqual([{ kind: 'post-failed', error: failure }])
})
it('reports a failing post once per session', async () => {
const failure = new Error('nowhere to post')
const bridge = harness({ post: () => Promise.reject(failure) })
bridge.host.receive(clientFrame({ type: 'ready' }))
bridge.host.receive(clientFrame({ type: 'ready' }))
await flushBridge()
expect(bridge.diagnostics).toEqual([{ kind: 'post-failed', error: failure }])
expect(bridge.posted).toHaveLength(2)
})
it('forwards to the client it was built with, whatever the frame names', () => {
const mine = createFakeRpcClient()
const theirs = createFakeRpcClient()
const bridge = harness({ ready: true, client: mine })
harness({ client: theirs })
bridge.host.receive(
clientFrame({ type: 'request', id: ID, method: 'status.get', hostId: 'other-host' })
)
expect(mine.requests.map((request) => request.method)).toEqual(['status.get'])
expect(theirs.requests).toHaveLength(0)
})
it('carries no host name into the client message it parsed', () => {
const bridge = harness({ ready: true })
bridge.host.receive(
clientFrame({ type: 'request', id: ID, method: 'status.get', hostId: 'other-host' })
)
expect(bridge.client.requests[0]?.args).toEqual(['status.get'])
})
})
// Back notify has no reply; diagnostics alone distinguish a successful pop from an empty native stack.
describe('navigate-back', () => {
const back = clientFrame({ type: 'notify', name: BRIDGE_NAVIGATE_BACK_NOTIFY })
it('pops the shell stack and asks the client for nothing', () => {
const bridge = harness({ routeGrants: ['navigate'] })
bridge.host.receive(clientFrame({ type: 'ready' }))
expect(bridge.last()).toMatchObject({
type: 'init',
grants: { native: ['fault', 'rpcEnvelope', 'navigate'] }
})
bridge.host.receive(back)
expect(bridge.backPops).toEqual(['popped'])
expect(bridge.navigations).toEqual([])
expect(bridge.client.requests).toHaveLength(0)
expect(bridge.diagnostics).toEqual([])
})
it('reports the pop that found nothing, because the page hears nothing either way', () => {
const bridge = harness({ onNavigateBack: () => 'nothing-to-pop' })
bridge.host.receive(clientFrame({ type: 'ready' }))
bridge.host.receive(back)
expect(bridge.backPops).toEqual(['nothing-to-pop'])
expect(bridge.diagnostics).toEqual([{ kind: 'navigate-back-refused', why: 'nothing-to-pop' }])
})
it('names a pop refused for a pop already pending, which is a different bug', () => {
const bridge = harness({ onNavigateBack: () => 'pop-pending' })
bridge.host.receive(clientFrame({ type: 'ready' }))
bridge.host.receive(back)
expect(bridge.diagnostics).toEqual([{ kind: 'navigate-back-refused', why: 'pop-pending' }])
})
it('refuses it from a page that has not asked for a session', () => {
const bridge = harness()
bridge.host.receive(back)
expect(bridge.backPops).toEqual([])
expect(bridge.diagnostics).toEqual([
{ kind: 'notify-refused', name: BRIDGE_NAVIGATE_BACK_NOTIFY, why: 'before-ready' }
])
})
it('reports a screen that threw on the pop once, and keeps reading', () => {
const failure = new Error('the stack is gone')
const bridge = harness({
onNavigateBack: () => {
throw failure
}
})
bridge.host.receive(clientFrame({ type: 'ready' }))
// Never let a throw escape the native event handler delivering this frame.
bridge.host.receive(back)
bridge.host.receive(back)
expect(bridge.diagnostics).toEqual([{ kind: 'notify-failed', error: failure }])
bridge.host.receive(clientFrame({ type: 'ready' }))
expect(bridge.last().type).toBe('init')
})
})
// Validate external-link schemes at the envelope too; a page bypassing its own guard must not reach the device handler with arbitrary URLs.
describe('externalLink', () => {
const open = (url: string) =>
clientFrame({ type: 'notify', name: BRIDGE_EXTERNAL_LINK_GRANT, url })
it('hands an allowed URL to the caller and asks the client for nothing', () => {
const bridge = harness()
bridge.host.receive(clientFrame({ type: 'ready' }))
expect(bridge.last()).toMatchObject({
type: 'init',
grants: { native: expect.arrayContaining(['externalLink']) }
})
bridge.host.receive(open('https://github.com/stablyai/orca/pull/1'))
bridge.host.receive(open('mailto:[email protected]'))
expect(bridge.externalLinks).toEqual([
'https://github.com/stablyai/orca/pull/1',
'mailto:[email protected]'
])
expect(bridge.client.requests).toHaveLength(0)
expect(bridge.navigations).toEqual([])
expect(bridge.diagnostics).toEqual([])
})
it('hands over the URL the parser read, not the string the page sent', () => {
const bridge = harness()
bridge.host.receive(clientFrame({ type: 'ready' }))
// The WHATWG parser strips tab/LF/CR and trims leading C0/space; these raw spellings pass a naive scheme check.
bridge.host.receive(open('ht\ntps://example.com'))
bridge.host.receive(open('https://example.com/a\r\n'))
bridge.host.receive(open(' https://example.com/a '))
bridge.host.receive(open('https:example.com'))
expect(bridge.externalLinks).toEqual([
'https://example.com/',
'https://example.com/a',
'https://example.com/a',
'https://example.com/'
])
})
it('refuses a scheme the grant does not cover, as a frame the reader never accepts', () => {
const bridge = harness()
bridge.host.receive(clientFrame({ type: 'ready' }))
for (const url of ['javascript:alert(1)', 'file:///etc/passwd', 'orca-mobile-web://s/x']) {
bridge.host.receive(open(url))
}
expect(bridge.externalLinks).toEqual([])
// Envelope refusal must precede grants/device dispatch; the reporter, not this host harness, deduplicates repeated diagnostics.
expect(bridge.diagnostics).toEqual(
Array.from({ length: 3 }, () => ({ kind: 'refused', refusal: 'unrecognised-message' }))
)
})
it('refuses it from a page that has not asked for a session', () => {
const bridge = harness()
bridge.host.receive(open('https://example.com'))
expect(bridge.externalLinks).toEqual([])
expect(bridge.diagnostics).toEqual([
{ kind: 'notify-refused', name: BRIDGE_EXTERNAL_LINK_GRANT, why: 'before-ready' }
])
})
})
// Haptics use notify so row taps do not consume the 64-slot request window; observe device calls and refusal diagnostics.
describe('haptics', () => {
const play = (kind: string) => clientFrame({ type: 'notify', name: BRIDGE_HAPTICS_NOTIFY, kind })
it('plays each kind on the device and asks the client for nothing', () => {
const bridge = harness()
bridge.host.receive(clientFrame({ type: 'ready' }))
const init = bridge.last()
expect(init.type === 'init' && init.grants.native).toContain('haptics')
expect(init.type === 'init' && init.grants.native).not.toContain('native.haptics.trigger')
for (const kind of ['mediumImpact', 'selection', 'success', 'error', 'edgeBump']) {
bridge.host.receive(play(kind))
}
expect(bridge.haptics).toEqual(['mediumImpact', 'selection', 'success', 'error', 'edgeBump'])
expect(bridge.client.requests).toHaveLength(0)
expect(bridge.client.foregroundCalls).toEqual([])
expect(bridge.diagnostics).toEqual([])
})
it('plays one per frame, so a twelve-row scroll is twelve taps and not one', () => {
const bridge = harness()
bridge.host.receive(clientFrame({ type: 'ready' }))
for (let row = 0; row < 12; row += 1) {
bridge.host.receive(play('selection'))
}
expect(bridge.haptics).toHaveLength(12)
})
it('plays nothing for a route that was granted no haptics', () => {
const bridge = harness({
routeGrants: MOBILE_WEB_SHELL_GRANTS.filter((grant) => grant !== BRIDGE_HAPTICS_GRANT)
})
bridge.host.receive(clientFrame({ type: 'ready' }))
bridge.host.receive(play('selection'))
expect(bridge.haptics).toEqual([])
expect(bridge.diagnostics).toEqual([
{ kind: 'notify-refused', name: BRIDGE_HAPTICS_NOTIFY, why: 'ungranted' }
])
})
it('plays nothing for a page that has not asked for a session', () => {
const bridge = harness()
bridge.host.receive(play('selection'))
expect(bridge.haptics).toEqual([])
expect(bridge.diagnostics).toEqual([
{ kind: 'notify-refused', name: BRIDGE_HAPTICS_NOTIFY, why: 'before-ready' }
])
})
it('plays nothing for a kind this app has no function for', () => {
const bridge = harness()
bridge.host.receive(clientFrame({ type: 'ready' }))
bridge.host.receive(play('heavyImpact'))
expect(bridge.haptics).toEqual([])
// Unknown haptic kinds fail envelope parsing; older shells must not substitute a different effect.
expect(bridge.diagnostics).toEqual([{ kind: 'refused', refusal: 'unrecognised-message' }])
})
})
// A page that stops hearing back cannot probe the socket itself; native owns the connection it rides.
describe('liveness probe', () => {
const probe = clientFrame({ type: 'notify', name: BRIDGE_LIVENESS_PROBE_NOTIFY })
it('asks the native client for a decisive probe', () => {
const bridge = harness()
let probes = 0
bridge.client.probeLivenessNow = () => {
probes += 1
}
bridge.host.receive(clientFrame({ type: 'ready' }))
bridge.host.receive(probe)
expect(probes).toBe(1)
expect(bridge.diagnostics).toEqual([])
})
})
describe('the page erasing a one-shot route param', () => {
// Forward both one-shot key and value to the native route holder; only it can compare before clearing (ruling 34).
it('carries a page clear up with the param and the value it named', () => {
const bridge = harness({ route: { pathname: '/h/host-a/session/wt-1' } })
bridge.host.receive(clientFrame({ type: 'ready' }))
bridge.host.receive(
clientFrame({
type: 'notify',
name: BRIDGE_ROUTE_PARAM_CLEAR,
param: 'paneKey',
value: 'p-1'
})
)
expect(bridge.routeParamClears()).toEqual([{ param: 'paneKey', value: 'p-1' }])
})
it('carries no clear up from a page that has not asked for a session', () => {
const bridge = harness({ route: { pathname: '/h/host-a/session/wt-1' } })
bridge.host.receive(
clientFrame({
type: 'notify',
name: BRIDGE_ROUTE_PARAM_CLEAR,
param: 'paneKey',
value: 'p-1'
})
)
expect(bridge.routeParamClears()).toEqual([])
expect(bridge.diagnostics).toEqual([
{ kind: 'notify-refused', name: BRIDGE_ROUTE_PARAM_CLEAR, why: 'before-ready' }
])
})
it('refuses a clear for a param the page may not erase', () => {
const bridge = harness({ route: { pathname: '/h/host-a/session/wt-1' } })
bridge.host.receive(clientFrame({ type: 'ready' }))
bridge.host.receive(
clientFrame({ type: 'notify', name: BRIDGE_ROUTE_PARAM_CLEAR, param: 'name', value: 'x' })
)
expect(bridge.routeParamClears()).toEqual([])
expect(bridge.diagnostics).toEqual([{ kind: 'refused', refusal: 'unrecognised-message' }])
})
})
// Only first-frame proves a rendered tree; WebView commit and pre-render ready cannot justify uncovering the page.
describe('the page reporting its first frame', () => {
it('hands the report to the session and asks the client for nothing', () => {
const bridge = harness()
bridge.host.receive(clientFrame({ type: 'ready' }))
bridge.host.receive(clientFrame({ type: 'notify', name: BRIDGE_PAGE_PAINTED }))
expect(bridge.pagePaintCount()).toBe(1)
expect(bridge.client.requests).toHaveLength(0)
expect(bridge.client.foregroundCalls).toHaveLength(0)
})
it('refuses a report from a document nothing has answered', () => {
const bridge = harness()
bridge.host.receive(clientFrame({ type: 'notify', name: BRIDGE_PAGE_PAINTED }))
expect(bridge.pagePaintCount()).toBe(0)
expect(bridge.diagnostics).toContainEqual({
kind: 'notify-refused',
name: BRIDGE_PAGE_PAINTED,
why: 'before-ready'
})
})
})