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 { z } from 'zod'
import { salvagedOptional } from '../../../../src/shared/zod-salvage'
import { SUPPORTED_UI_LOCALES } from '../../../../src/shared/ui-locale'
import { NODE_PLATFORM_NAMES } from '../../transport/mobile-runtime-host-platform'
import { RpcEnvelopeFieldsSchema } from '../../transport/rpc-envelope-fields'
import { isRpcResponse } from '../../transport/rpc-response-shape'
import type { RpcResponse } from '../../transport/types'
import { BridgeErrorCaptureSchema } from './bridge-error-capture'
import { BridgeInitRouteSchema, type BridgeInitRoute } from './bridge-init-route'
import { BridgePageRouteGrantsSchema } from './bridge-page-route-grants'
import { BridgeSafeAreaInsetsSchema } from './bridge-safe-area-insets'
import { BridgeKeyboardInsetSchema } from './bridge-keyboard-inset'
import { BridgeNotifySchema } from './bridge-notify-envelope'
import { BRIDGE_BACK_FRAME } from './bridge-page-back'
import { BRIDGE_ID_PATTERN, idSchema, methodSchema, versionSchema } from './bridge-frame-fields'
export {
BRIDGE_EXTERNAL_LINK_GRANT,
BRIDGE_FAULT_GRANT,
BRIDGE_FOREGROUND_NUDGE_REASONS,
BRIDGE_ID_PATTERN,
BRIDGE_NAVIGATE_BACK_NOTIFY,
BRIDGE_PROTOCOL_VERSION,
BRIDGE_RPC_ENVELOPE_GRANT
} from './bridge-frame-fields'
import {
isPageStorageKey,
PAGE_STORAGE_MAX_ENTRIES,
PAGE_STORAGE_MAX_KEY_CHARS,
PAGE_STORAGE_MAX_VALUE_CHARS
} from '../page-storage-keys'
import {
BRIDGE_MAX_PAGE_ROUTES,
BRIDGE_MAX_REPLY_PARTS,
BRIDGE_MAX_ROUTE_PATHNAME_CHARS,
BRIDGE_MAX_HOST_FIELD_CHARS,
parseBridgeMessage,
type BridgeDirection,
type BridgeRead
} from './bridge-caps'
export const BRIDGE_CONNECTION_STATES = [
'connecting',
'handshaking',
'connected',
'disconnected',
'reconnecting',
'auth-failed'
] as const
export const BRIDGE_BINARY_FORMATS = ['jpeg', 'png'] as const
// Send whole connection snapshots so lost frames cannot leave partial state; generation detects snapshots that need repair.
export const BridgeConnectionSnapshotSchema = z.object({
state: z.enum(BRIDGE_CONNECTION_STATES),
reconnectAttempt: z.number().int().nonnegative(),
lastConnectedAt: z.number().nullable(),
lastInboundAt: z.number().nullable(),
generation: z.number().int().nonnegative().nullable()
})
export type BridgeConnectionSnapshot = z.infer<typeof BridgeConnectionSnapshotSchema>
export const BridgeGrantsSchema = z.object({
rpc: z.object({
maxPendingRequests: z.number().int().positive(),
maxSubscriptions: z.number().int().positive()
}),
native: z.array(z.string().min(1).max(64))
})
export type BridgeGrants = z.infer<typeof BridgeGrantsSchema>
export { BridgeInitRouteSchema, type BridgeInitRoute }
// Forward only nonsecret host profile fields: web SecureStore is empty, but the bridge already owns credentials/RPC and the page needs host labels to render.
export const BridgeInitHostSchema = z.object({
id: z.string().min(1).max(BRIDGE_MAX_HOST_FIELD_CHARS),
name: z.string().min(1).max(BRIDGE_MAX_HOST_FIELD_CHARS),
// Optional name metadata distinguishes phone overrides from desktop names; salvage unknown platform values so newer shells cannot invalidate the whole init.
// The outer optional keeps the key optional, rather than requiring a T|undefined property.
personalName: salvagedOptional(
'personalName',
z.string().min(1).max(BRIDGE_MAX_HOST_FIELD_CHARS)
).optional(),
lastKnownMachineName: salvagedOptional(
'lastKnownMachineName',
z.string().min(1).max(BRIDGE_MAX_HOST_FIELD_CHARS)
).optional(),
lastKnownHostPlatform: salvagedOptional(
'lastKnownHostPlatform',
z.enum(NODE_PLATFORM_NAMES)
).optional(),
endpoint: z.string().min(1).max(BRIDGE_MAX_HOST_FIELD_CHARS),
lastConnected: z.number().finite()
})
export type BridgeInitHost = z.infer<typeof BridgeInitHostSchema>
// The app's resolved light/dark scheme, so the page paints the same palette as the native chrome around it.
export const BridgeColorSchemeSchema = z.enum(['light', 'dark'])
export type BridgeColorScheme = z.infer<typeof BridgeColorSchemeSchema>
// The app's resolved UI language, so page chrome matches the native chrome and the in-app override.
export const BridgeUiLocaleSchema = z.enum(SUPPORTED_UI_LOCALES)
export type BridgeUiLocale = z.infer<typeof BridgeUiLocaleSchema>
export const BridgeInitStorageSchema = z
.record(
z.string().min(1).max(PAGE_STORAGE_MAX_KEY_CHARS).refine(isPageStorageKey),
z.string().max(PAGE_STORAGE_MAX_VALUE_CHARS)
)
.refine((entries) => Object.keys(entries).length <= PAGE_STORAGE_MAX_ENTRIES)
export const BridgeSendRequestOptionsSchema = z.object({
timeoutMs: z.number().int().positive().optional(),
budgetSpansConnect: z.boolean().optional(),
failWhenDisconnected: z.boolean().optional()
})
// Reuse native isRpcResponse and preserve failures as data, including _meta/error.data and new fields; a narrower bridge reader would reject replies native clients and golden recorders accept.
export const BridgeReplyPayloadSchema = z.custom<RpcResponse>(isRpcResponse)
// Keep screencast metadata loose for newer host fields; z.number accepts the same finite-number values as the host type.
const screencastMetadataSchema = z.looseObject({
offsetTop: z.number().optional(),
pageScaleFactor: z.number().optional(),
deviceWidth: z.number().optional(),
deviceHeight: z.number().optional(),
imageWidth: z.number().optional(),
imageHeight: z.number().optional(),
scrollOffsetX: z.number().optional(),
scrollOffsetY: z.number().optional(),
timestamp: z.number().optional()
})
const replyPartSchema = z.object({
i: z
.number()
.int()
.nonnegative()
.max(BRIDGE_MAX_REPLY_PARTS - 1),
of: z.number().int().positive().max(BRIDGE_MAX_REPLY_PARTS)
})
const BridgeClientMessageSchema = z.discriminatedUnion('type', [
z.object({
v: versionSchema,
type: z.literal('ready')
}),
z.object({
v: versionSchema,
type: z.literal('request'),
id: idSchema,
method: methodSchema,
params: z.unknown().optional(),
options: BridgeSendRequestOptionsSchema.optional(),
envelope: RpcEnvelopeFieldsSchema.optional()
}),
z.object({
v: versionSchema,
type: z.literal('subscribe'),
id: idSchema,
method: methodSchema,
params: z.unknown(),
wantsBinary: z.boolean().optional(),
envelope: RpcEnvelopeFieldsSchema.optional()
}),
z.object({
v: versionSchema,
type: z.literal('cancel'),
id: idSchema,
target: z.enum(['request', 'subscription'])
}),
z.object({
v: versionSchema,
type: z.literal('ack'),
id: idSchema,
seq: z.number().int().nonnegative()
}),
BridgeNotifySchema,
z.object({ v: versionSchema, type: z.literal('close') })
])
export type BridgeClientMessage = z.infer<typeof BridgeClientMessageSchema>
// reply/event each have multiple shapes under type, so use a union rather than a discriminator; try hot frames first.
const BridgeHostMessageSchema = z.union([
z.object({
v: versionSchema,
type: z.literal('event'),
id: idSchema,
seq: z.number().int().nonnegative(),
payload: z.unknown()
}),
z.object({
v: versionSchema,
type: z.literal('event'),
id: idSchema,
seq: z.number().int().nonnegative(),
// Carry decoded-frame metadata alongside base64. Keep bridge seq separate from screencast frameSeq: only the former drives backpressure.
binary: z.object({
b64: z.string(),
format: z.enum(BRIDGE_BINARY_FORMATS),
frameSeq: z.number().int().nonnegative(),
metadata: screencastMetadataSchema
})
}),
z.object({
v: versionSchema,
type: z.literal('reply'),
id: idSchema,
payload: BridgeReplyPayloadSchema
}),
z.object({
v: versionSchema,
type: z.literal('reply'),
id: idSchema,
part: replyPartSchema,
chunk: z.string()
}),
z.object({
v: versionSchema,
type: z.literal('state'),
connection: BridgeConnectionSnapshotSchema
}),
// Back names no destination; only the native stack knows what screen lies beneath.
z.object({ v: versionSchema, type: z.literal(BRIDGE_BACK_FRAME) }),
z.object({
v: versionSchema,
type: z.literal('end'),
id: idSchema,
reason: z.enum(['unsubscribed', 'closed', 'overflow'])
}),
z.object({
v: versionSchema,
type: z.literal('error'),
id: idSchema,
error: BridgeErrorCaptureSchema
}),
z.object({
v: versionSchema,
type: z.literal('init'),
sessionId: z.string().min(1),
buildId: z.string().min(1),
connection: BridgeConnectionSnapshotSchema,
grants: BridgeGrantsSchema,
route: BridgeInitRouteSchema.optional(),
safeAreaInsets: BridgeSafeAreaInsetsSchema.optional(),
keyboardInset: BridgeKeyboardInsetSchema.optional(),
// Older pages strip this key; salvage an unknown future scheme so it cannot invalidate the whole init.
colorScheme: salvagedOptional('colorScheme', BridgeColorSchemeSchema).optional(),
// Older pages strip this key; a locale this page does not ship is salvaged rather than refusing init.
uiLocale: salvagedOptional('uiLocale', BridgeUiLocaleSchema).optional(),
host: BridgeInitHostSchema.optional(),
storage: BridgeInitStorageSchema.optional(),
// Advisory page fast path for oversized keys; the shell independently refuses writes because older pages ignore this additive field (ruling 33.6).
storageOversize: z
.array(z.string().min(1).max(PAGE_STORAGE_MAX_KEY_CHARS).refine(isPageStorageKey))
.max(PAGE_STORAGE_MAX_ENTRIES)
.optional(),
pageRoutes: z
.array(z.string().min(1).max(BRIDGE_MAX_ROUTE_PATHNAME_CHARS))
.max(BRIDGE_MAX_PAGE_ROUTES)
.optional(),
// Send manifest grant pairs so local hops cannot run targets under insufficient opener grants. Older shells omit/older pages ignore this field; absent pairs retain the older handoff rule.
pageRouteGrants: BridgePageRouteGrantsSchema.optional(),
ownsHostArea: salvagedOptional('ownsHostArea', z.boolean()).optional()
})
])
export type BridgeHostMessage = z.infer<typeof BridgeHostMessageSchema>
export type BridgeReplyMessage = Extract<BridgeHostMessage, { type: 'reply' }>
export type BridgeReplyPayload = z.infer<typeof BridgeReplyPayloadSchema>
// Salvage a refused frame’s id through the same caps to settle only an existing exchange; silently dropping replies would strand requests.
// Raw oversize and malformed JSON yield no id, so only close/replacement settles their exchanges; conforming hosts instead chunk or send bounded errors.
export function readRefusedBridgeFrameId(raw: string): string | null {
const framed = parseBridgeMessage(raw, 'shell-to-page')
if (!framed.ok) {
return null
}
const frame = framed.message
if (typeof frame !== 'object' || frame === null || !('id' in frame)) {
return null
}
const { id } = frame
return typeof id === 'string' && BRIDGE_ID_PATTERN.test(id) ? id : null
}
export function readBridgeClientMessage(raw: string): BridgeRead<BridgeClientMessage> {
return readMessage(raw, BridgeClientMessageSchema, 'page-to-shell')
}
export function readBridgeHostMessage(raw: string): BridgeRead<BridgeHostMessage> {
return readMessage(raw, BridgeHostMessageSchema, 'shell-to-page')
}
function readMessage<TMessage>(
raw: string,
schema: z.ZodType<TMessage>,
direction: BridgeDirection
): BridgeRead<TMessage> {
const framed = parseBridgeMessage(raw, direction)
if (!framed.ok) {
return framed
}
const parsed = schema.safeParse(framed.message)
return parsed.success
? { ok: true, message: parsed.data }
: { ok: false, refusal: 'unrecognised-message' }
}