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 type { RuntimeEnvironmentStatus, RuntimeHostBlockedReason } from './runtime-host-status'
import {
LOCAL_EXECUTION_HOST_ID,
getLocalExecutionHostLabel,
getSettingsFocusedExecutionHostId,
getRepoDialableSshTargetId,
isOwnedSshTargetId,
normalizeHostPart,
parseExecutionHostId,
toRuntimeExecutionHostId,
toSshExecutionHostId,
type ExecutionHostId,
type ExecutionHostKind
} from './execution-host'
import { evaluateRuntimeCompat, type RuntimeCompatVerdict } from './protocol-compat'
import { MIN_COMPATIBLE_RUNTIME_SERVER_VERSION, RUNTIME_PROTOCOL_VERSION } from './protocol-version'
import type { RuntimeStatus } from './runtime-types'
import type { SshConnectionState, SshConnectionStatus } from './ssh-types'
import type { RuntimeEnvironmentSource } from './runtime-environments'
import type { GlobalSettings } from './global-settings-types'
import type { Repo } from './repo-types'
import {
annotateManagedOrcadExecutionHosts,
type ManagedOrcadDeploymentSummary
} from './managed-orcad-execution-host'
import { getSshConnectionHealth, type ExecutionHostHealth } from './execution-host-health'
export type { ExecutionHostHealth } from './execution-host-health'
export type ExecutionHostRegistryEntry = {
id: ExecutionHostId
kind: ExecutionHostKind
label: string
detail: string
health: ExecutionHostHealth
connectionStatus?: SshConnectionStatus
compatibility?: RuntimeCompatVerdict
/** Present only while health is blocked; local evidence, never published to peers. */
blockedReason?: RuntimeHostBlockedReason
capabilities?: readonly string[]
appVersion?: string | null
protocolVersion?: number | null
minCompatibleClientVersion?: number | null
platform?: NodeJS.Platform | null
remoteControlState?: RuntimeStatus['remoteControl']
source?: RuntimeEnvironmentSource
/** See managed-orcad-execution-host: pairs an SSH host with its managed server. */
aliasHostIds?: readonly ExecutionHostId[]
mergedIntoHostId?: ExecutionHostId
}
type RuntimeEnvironmentSummary = {
id: string
name?: string | null
source?: RuntimeEnvironmentSource
orcadDeployment?: ManagedOrcadDeploymentSummary | null
}
type RuntimeStatusByEnvironmentId = ReadonlyMap<string, RuntimeEnvironmentStatus>
export type ExecutionHostSource = 'configured-only' | 'include-references'
function runtimeCompatibility(
status: RuntimeStatus | null | undefined
): RuntimeCompatVerdict | null {
if (!status) {
return null
}
return evaluateRuntimeCompat({
clientProtocolVersion: RUNTIME_PROTOCOL_VERSION,
minCompatibleServerProtocolVersion: MIN_COMPATIBLE_RUNTIME_SERVER_VERSION,
serverProtocolVersion: status.runtimeProtocolVersion ?? status.protocolVersion,
serverMinCompatibleClientProtocolVersion:
status.minCompatibleRuntimeClientVersion ?? status.minCompatibleMobileVersion
})
}
function runtimeHealth(
status: RuntimeStatus | null | undefined,
compatibility: RuntimeCompatVerdict | null,
remoteControl: RuntimeStatus['remoteControl'] | null | undefined
): ExecutionHostHealth {
// Without live status, only ready shared control proves server reachability.
if (!status) {
return remoteControl?.state === 'ready' ? 'available' : 'disconnected'
}
if (!compatibility) {
return 'available'
}
return compatibility.kind === 'blocked' ? 'blocked' : 'available'
}
function runtimeControlHealth(
remoteControl: RuntimeStatus['remoteControl'] | null | undefined
): ExecutionHostHealth | null {
switch (remoteControl?.state) {
case 'awaiting_authenticated':
case 'awaiting_ready':
case 'reconnecting':
return 'connecting'
case 'closed':
return remoteControl.lastError ? 'error' : 'disconnected'
case 'ready':
return null
case undefined:
return null
}
}
function setHost(
hosts: Map<ExecutionHostId, ExecutionHostRegistryEntry>,
entry: ExecutionHostRegistryEntry
): void {
const existing = hosts.get(entry.id)
if (!existing) {
hosts.set(entry.id, entry)
return
}
if (existing.health !== 'disconnected') {
return
}
// Health upgrades must retain the first friendly label/source seeded before id-only fallbacks.
hosts.set(entry.id, { ...entry, label: existing.label, source: existing.source ?? entry.source })
}
function addRuntimeHost(
hosts: Map<ExecutionHostId, ExecutionHostRegistryEntry>,
environmentId: string,
label: string,
source: RuntimeEnvironmentSource | undefined,
statusByEnvironmentId: RuntimeStatusByEnvironmentId | undefined
): void {
const hostId = toRuntimeExecutionHostId(environmentId)
const runtimeStatus = statusByEnvironmentId?.get(environmentId)
const status = runtimeStatus?.status
const snapshot = runtimeStatus?.snapshot
const metadata = status ?? snapshot?.status
const compatibility = runtimeCompatibility(metadata)
const remoteControl = runtimeStatus?.remoteControl ?? status?.remoteControl
// Status owners withdraw verified on socket loss, so it proves reachability while shared control connects (#10704).
const reachable =
snapshot?.transport === 'ready'
? snapshot.verification !== 'checking'
: snapshot?.verification === 'verified' && snapshot.transport !== 'disconnected'
const controlHealth = snapshot?.retired
? 'disconnected'
: snapshot?.verification === 'blocked'
? 'blocked'
: reachable
? compatibility?.kind === 'blocked'
? 'blocked'
: 'available'
: !runtimeStatus ||
snapshot?.verification === 'checking' ||
snapshot?.transport === 'disconnected' ||
snapshot?.transport === 'connecting'
? 'connecting'
: runtimeControlHealth(remoteControl)
const health = controlHealth ?? runtimeHealth(status, compatibility, remoteControl)
const blockedReason =
health === 'blocked'
? (snapshot?.verification === 'blocked' && snapshot.blockedReason) || 'incompatible'
: undefined
setHost(hosts, {
id: hostId,
kind: 'runtime',
label,
detail: 'Orca server',
health,
...(blockedReason ? { blockedReason } : {}),
compatibility: compatibility ?? undefined,
capabilities: metadata?.capabilities,
appVersion: runtimeStatus?.appVersion ?? metadata?.appVersion ?? null,
protocolVersion: metadata?.runtimeProtocolVersion ?? metadata?.protocolVersion ?? null,
minCompatibleClientVersion:
metadata?.minCompatibleRuntimeClientVersion ?? metadata?.minCompatibleMobileVersion ?? null,
platform: metadata?.hostPlatform ?? null,
remoteControlState: remoteControl ?? null,
...(source ? { source } : {})
})
}
export function buildExecutionHostRegistry(args: {
repos: readonly Pick<Repo, 'connectionId' | 'executionHostId'>[]
settings: Pick<GlobalSettings, 'activeRuntimeEnvironmentId'> | null | undefined
hostSource?: ExecutionHostSource
sshTargetLabels?: ReadonlyMap<string, string>
sshConnectionStates?: ReadonlyMap<string, SshConnectionState>
runtimeEnvironments?: readonly RuntimeEnvironmentSummary[]
runtimeStatusByEnvironmentId?: RuntimeStatusByEnvironmentId
// Per-host user labels must appear wherever this registry feeds.
hostLabelOverrides?: ReadonlyMap<ExecutionHostId, string>
/** Defaults to this process's platform, which only the host itself may use. */
localHostLabel?: string
}): ExecutionHostRegistryEntry[] {
const hosts = new Map<ExecutionHostId, ExecutionHostRegistryEntry>()
hosts.set(LOCAL_EXECUTION_HOST_ID, {
id: LOCAL_EXECUTION_HOST_ID,
kind: 'local',
label: args.localHostLabel ?? getLocalExecutionHostLabel(),
detail: 'This computer',
health: 'local'
})
for (const environment of args.runtimeEnvironments ?? []) {
const environmentId = normalizeHostPart(environment.id)
if (!environmentId) {
continue
}
addRuntimeHost(
hosts,
environmentId,
normalizeHostPart(environment.name) ?? environmentId,
environment.source,
args.runtimeStatusByEnvironmentId
)
}
for (const environmentId of args.runtimeStatusByEnvironmentId?.keys() ?? []) {
addRuntimeHost(
hosts,
environmentId,
environmentId,
undefined,
args.runtimeStatusByEnvironmentId
)
}
const focusedHost = getSettingsFocusedExecutionHostId(args.settings)
const parsedFocusedHost = parseExecutionHostId(focusedHost)
if (parsedFocusedHost?.kind === 'runtime' && args.hostSource !== 'configured-only') {
addRuntimeHost(
hosts,
parsedFocusedHost.environmentId,
parsedFocusedHost.environmentId,
undefined,
args.runtimeStatusByEnvironmentId
)
}
const sshTargetIds = new Set<string>()
if (args.hostSource !== 'configured-only') {
for (const repo of args.repos) {
const parsedHost = parseExecutionHostId(repo.executionHostId)
if (parsedHost?.kind === 'runtime') {
addRuntimeHost(
hosts,
parsedHost.environmentId,
parsedHost.environmentId,
undefined,
args.runtimeStatusByEnvironmentId
)
}
// VM-owned SSH targets are plumbing and must stay out of visible run targets.
if (parsedHost?.kind === 'ssh' && !isOwnedSshTargetId(parsedHost.targetId)) {
sshTargetIds.add(parsedHost.targetId)
}
}
}
for (const targetId of args.sshTargetLabels?.keys() ?? []) {
const normalized = normalizeHostPart(targetId)
if (normalized && !isOwnedSshTargetId(normalized)) {
sshTargetIds.add(normalized)
}
}
if (args.hostSource !== 'configured-only') {
for (const repo of args.repos) {
// A paired-server repo’s raw connectionId belongs to that server and is not client-dialable.
const targetId = getRepoDialableSshTargetId(repo)
if (targetId && !isOwnedSshTargetId(targetId)) {
sshTargetIds.add(targetId)
}
}
}
for (const targetId of sshTargetIds) {
const state = args.sshConnectionStates?.get(targetId)
setHost(hosts, {
id: toSshExecutionHostId(targetId),
kind: 'ssh',
label: args.sshTargetLabels?.get(targetId) || targetId,
detail: 'SSH',
health: getSshConnectionHealth(state?.status),
connectionStatus: state?.status
})
}
annotateManagedOrcadExecutionHosts({
hosts,
runtimeEnvironments: args.runtimeEnvironments ?? [],
sshConnectionStates: args.sshConnectionStates
})
const overrides = args.hostLabelOverrides
if (!overrides || overrides.size === 0) {
return [...hosts.values()]
}
return [...hosts.values()].map((host) => {
// A rename on a merged-away alias still names the merged row.
const label =
overrides.get(host.id) ??
host.aliasHostIds?.map((aliasHostId) => overrides.get(aliasHostId)).find(Boolean)
return label ? { ...host, label } : host
})
}