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 {
hasUnsafeProviderSessionIdChars,
isResumableTuiAgent,
type AgentProviderSessionMetadata,
type ResumableTuiAgent
} from './agent-session-resume'
import type { RuntimeTerminalCreate, RuntimeTerminalPresentation } from './runtime-types'
import { isTerminalLeafId } from './stable-pane-id'
import { isValidTerminalTabId } from './terminal-tab-id'
import type { TuiAgent } from './tui-agent'
import type { SpawnIntent } from './host-spawn-admission'
export { AGENT_SESSION_HOST_AUTHORITY_RUNTIME_CAPABILITY as AGENT_SESSION_HOST_AUTHORITY_CAPABILITY } from './protocol-version'
export const AGENT_SESSION_RPC_ERROR_CODES = [
'agent_session_identity_required',
'agent_session_conflict',
'agent_session_resume_not_authorized',
'agent_session_exited_during_start',
'agent_session_claim_unavailable',
'agent_session_ownership_unknown',
'agent_session_checkpoint_stale',
'agent_session_operation_invalid',
'agent_session_operation_conflict',
'agent_session_operation_expired',
'agent_session_operation_capacity',
'agent_session_operation_unknown',
'agent_session_legacy_required',
'execution_owner_reconciling',
'execution_owner_unavailable'
] as const
export const AGENT_SESSION_CLAIM_DIGEST_VERSION = 1 as const
export const AGENT_SESSION_OPERATION_FUTURE_SKEW_MS = 5 * 60 * 1000
export const AGENT_SESSION_MAX_NEW_OPERATION_AGE_MS = 24 * 60 * 60 * 1000
/** Oldest an operation can be when admitted, plus the host tombstone lifetime after admission. */
export const AGENT_SESSION_MAX_OPERATION_REPLAY_AGE_MS =
AGENT_SESSION_MAX_NEW_OPERATION_AGE_MS * 2 + AGENT_SESSION_OPERATION_FUTURE_SKEW_MS
const AGENT_SESSION_OPERATION_ID_PATTERN = /^(\d{13})-[0-9a-f]{32}$/
export function parseAgentSessionOperationTimestamp(operationId: string): number | null {
const match = AGENT_SESSION_OPERATION_ID_PATTERN.exec(operationId)
if (!match) {
return null
}
const timestamp = Number(match[1])
return Number.isSafeInteger(timestamp) ? timestamp : null
}
const BASE64URL_RE = /^[A-Za-z0-9_-]+$/
const SHA256_BASE64URL_LENGTH = 43
function isBoundedWireString(value: unknown, maxLength: number): value is string {
return (
typeof value === 'string' &&
value.length > 0 &&
value.length <= maxLength &&
!hasUnsafeProviderSessionIdChars(value)
)
}
export type AgentSessionSurfaceBinding = {
worktreeId: string
tabId: string
leafId: string
terminalHandle: string
}
export type AgentSessionExecutionClaim = {
digestVersion: typeof AGENT_SESSION_CLAIM_DIGEST_VERSION
keyId: string
identityDigest: string
worktreeScopeDigest: string
agent: ResumableTuiAgent
}
export type AgentSessionOwnerBinding = {
claim: AgentSessionExecutionClaim
generation: string
phase: 'reserved' | 'live'
ptyId: string
surface: AgentSessionSurfaceBinding
}
export type AgentSessionClaimedSpawnResult = {
disposition: 'created' | 'adopted'
owner: AgentSessionOwnerBinding
}
export type AgentLaunchPreferences = {
model?: string
effort?: string
mode?: string
}
export type AgentPromptDelivery = 'auto-submit' | 'draft'
export type RuntimeEnsureAgentSessionRequest =
| {
kind: 'automatic'
sleepingCheckpointId: string
presentation?: RuntimeTerminalPresentation
}
| {
kind: 'explicit'
resumeOrigin?: 'saved'
worktree: string
agent: ResumableTuiAgent
providerSession: AgentProviderSessionMetadata
ompResumeFilePath?: string
terminalKittyKeyboardProtocol?: boolean
/** Explicit client override. Omission keeps launch defaults host-owned. */
agentArgs?: string | null
launchPreferences?: AgentLaunchPreferences
presentation?: RuntimeTerminalPresentation
placement?: { tabId?: string; leafId?: string }
spawnIntent?: SpawnIntent
/** Account routing env a desktop prepared for a host with no account services (WSL orcad). */
accountEnv?: Record<string, string>
}
export type RuntimeEnsureAgentSessionResult = {
terminal: RuntimeTerminalCreate
disposition: 'created' | 'adopted'
}
export type RuntimeCreateAgentSessionRequest = {
clientOperationId: string
terminalKittyKeyboardProtocol?: boolean
worktree: string
agent: TuiAgent
prompt?: string
promptDelivery?: AgentPromptDelivery
/** Explicit client override. Omission keeps launch defaults host-owned. */
agentArgs?: string | null
launchPreferences?: AgentLaunchPreferences
startupCwd?: string
presentation?: RuntimeTerminalPresentation
placement?: { tabId?: string; leafId?: string }
viewMode?: 'terminal' | 'chat'
/** Account routing env a desktop prepared for a host with no account services (WSL orcad). */
accountEnv?: Record<string, string>
}
export type RuntimeCreateAgentSessionResult = {
terminal: RuntimeTerminalCreate
disposition: 'created' | 'replayed'
}
export type RuntimeAgentSessionRpcCaller = {
terminalImageViewerSupported?: boolean
clientId?: string
clientKind?: 'mobile' | 'runtime'
signal?: AbortSignal
}
export function isAgentSessionExecutionClaim(value: unknown): value is AgentSessionExecutionClaim {
if (typeof value !== 'object' || value === null) {
return false
}
const claim = value as Partial<AgentSessionExecutionClaim>
return (
claim.digestVersion === AGENT_SESSION_CLAIM_DIGEST_VERSION &&
isBoundedWireString(claim.keyId, 128) &&
BASE64URL_RE.test(claim.keyId) &&
typeof claim.identityDigest === 'string' &&
claim.identityDigest.length === SHA256_BASE64URL_LENGTH &&
BASE64URL_RE.test(claim.identityDigest) &&
typeof claim.worktreeScopeDigest === 'string' &&
claim.worktreeScopeDigest.length === SHA256_BASE64URL_LENGTH &&
BASE64URL_RE.test(claim.worktreeScopeDigest) &&
isResumableTuiAgent(claim.agent)
)
}
export function isAgentSessionSurfaceBinding(value: unknown): value is AgentSessionSurfaceBinding {
if (typeof value !== 'object' || value === null) {
return false
}
const surface = value as Partial<AgentSessionSurfaceBinding>
return (
isBoundedWireString(surface.worktreeId, 4096) &&
isBoundedWireString(surface.tabId, 512) &&
isValidTerminalTabId(surface.tabId) &&
typeof surface.leafId === 'string' &&
isTerminalLeafId(surface.leafId) &&
isBoundedWireString(surface.terminalHandle, 128) &&
surface.terminalHandle.startsWith('term_') &&
BASE64URL_RE.test(surface.terminalHandle)
)
}
export function isAgentSessionOwnerBinding(value: unknown): value is AgentSessionOwnerBinding {
if (typeof value !== 'object' || value === null) {
return false
}
const owner = value as Partial<AgentSessionOwnerBinding>
return (
isAgentSessionExecutionClaim(owner.claim) &&
isBoundedWireString(owner.generation, 128) &&
(owner.phase === 'reserved' || owner.phase === 'live') &&
isBoundedWireString(owner.ptyId, 4096) &&
isAgentSessionSurfaceBinding(owner.surface)
)
}
export function isAgentSessionClaimedSpawnResult(
value: unknown
): value is AgentSessionClaimedSpawnResult {
if (typeof value !== 'object' || value === null) {
return false
}
const result = value as Partial<AgentSessionClaimedSpawnResult>
return (
(result.disposition === 'created' || result.disposition === 'adopted') &&
isAgentSessionOwnerBinding(result.owner) &&
result.owner.phase === 'live'
)
}