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.

16.4 KB
Raw Blame
import type { SshPendingPtyKill } from './ssh-pending-pty-kill'
import type { OrcadSshProvisioningIntent } from './orcad-ssh-provisioning'
import type { NodeDistMirrorAttempt } from './node-dist-mirror'

export const MIN_SSH_RELAY_GRACE_PERIOD_SECONDS = 60
export const MAX_SSH_RELAY_GRACE_PERIOD_SECONDS = 7 * 24 * 60 * 60
export const LEGACY_DEFAULT_SSH_RELAY_GRACE_PERIOD_SECONDS = 3 * 60 * 60

/** pinned-node uses uploaded Node/prebuilt addons (D6 ladder/D5 design); opt-in legacy uses host Node/npm native deps. */
export const SSH_REMOTE_RUNTIMES = ['legacy', 'pinned-node'] as const
export type SshRemoteRuntime = (typeof SSH_REMOTE_RUNTIMES)[number]

/** Where the design D6 fallback ladder landed; `legacy` is the opt-in host-npm path outside it. */
export const SSH_REMOTE_RUNTIME_RUNGS = ['A', 'B', 'C', 'D', 'legacy'] as const
export type SshRemoteRuntimeRung = (typeof SSH_REMOTE_RUNTIME_RUNGS)[number]

/** Main-owned ladder cache; changes to glibc, pinned-runtime hash or Orca major invalidate it. */
export type SshRemoteRuntimeResolution = {
  rung: SshRemoteRuntimeRung
  /** The classified refusal that stepped off Orca's pinned Node, when one did. */
  pinnedRefusal?: string
  /** Epoch ms the refusal was proved; a refusal the host can lose expires from it. */
  refusedAt?: number
  glibc: string | null
  runtimeSha256: string
  orcaMajor: number
}

/** Who created a hidden target as an implementation detail, and so owns its lifecycle. */
export type SshTargetOwner = { type: 'on-demand-runtime'; runtimeId: string }

export type SshTarget = {
  id: string
  label: string
  /** Internal targets are hidden from normal host management. */
  owner?: SshTargetOwner
  /** Host alias to resolve through OpenSSH config (ssh -G). */
  configHost?: string
  host: string
  port: number
  username: string
  /** Path to private key file, if using key-based auth. */
  identityFile?: string
  /** SSH agent socket path from IdentityAgent, if configured. */
  identityAgent?: string
  /** Whether OpenSSH IdentitiesOnly should limit public-key auth attempts. */
  identitiesOnly?: boolean
  /** ssh2 lacks gssapi-with-mic; configured Kerberos targets try system OpenSSH first. */
  gssapiAuthentication?: boolean
  /** ProxyCommand from SSH config, if any. */
  proxyCommand?: string
  /** Jump host (ProxyJump), if any. */
  jumpHost?: string
  /** ssh-config refreshes config-derived fields on import; manual is never overwritten.
   * Legacy absent source is adopted only when the old import shape matches (ssh-target-source.ts). */
  source?: 'ssh-config' | 'manual'
  /** Grace period in seconds before relay shuts down after disconnect.
   *  0 disables expiry. Default: 0 (until reset). Max: 604800 (7 days). */
  relayGracePeriodSeconds?: number
  /** Allow this host’s CLI to drive desktop browser tabs in its workspaces and relay-era terminal orchestration.
   * Enabled unless false; use isRemoteCliControlAllowed. */
  allowRemoteCliControl?: boolean
  /** Retired: written by earlier builds and ignored now. Kept so a downgrade still finds its stamp. */
  allowRemoteCliControlConsent?: 'desktop-browser-bridge'
  /** Undefined means on; false leaves this host disconnected at launch until the user connects it. */
  reconnectOnLaunch?: boolean
  /** Persist prompted-auth history so startup defers credential-requiring hosts without attempting a connection. */
  lastRequiredPassphrase?: boolean
  portForwards?: SavedPortForward[]
  /** Reuse a system OpenSSH connection across setup commands. Undefined means
   *  enabled; false is an explicit per-target compatibility opt-out. */
  systemSshConnectionReuse?: boolean
  /** Windows only: hold one loopback tunnel through a ProxyCommand/ProxyJump and run later
   *  commands over it. Opt-in; undefined means off. */
  systemSshProxyConnectionReuse?: boolean
  /** Relay runtime for this host; undefined means pinned-node. */
  remoteRuntime?: SshRemoteRuntime
  /** Main-owned ladder cache; renderer updates never set it. */
  remoteRuntimeResolution?: SshRemoteRuntimeResolution
  /** Main-owned registration incarnation fences automation reuse after create/re-create/re-adopt; connect state never advances it. */
  generation?: number
  /** Main-owned provisioning intent; never fall back to a relay while it exists. */
  orcadProvisioning?: OrcadSshProvisioningIntent
  /** Main-owned: managed orcad can't run on this host; retried once this app version changes. */
  managedServerUnavailable?: { reason: string; appVersion: string }
  /** Retired with the move offer (hosts convert on connect); kept so a downgraded build doesn't re-offer. */
  managedServerMoveOffered?: { appVersion: string }
  /** Confirmed “Move anyway” leaves uncarried state in the desktop profile; clear after the move. */
  managedServerLeaveBehind?: { confirmedAt: string }
  /** Main-owned: updating the managed server to this app version failed; retried once it changes. */
  managedServerUpdateFailure?: { reason: string; appVersion: string }
  /** Main-owned: the user stopped and removed this host's server; only an explicit Connect deploys again. */
  managedServerRemoved?: { removedAt: string }
  orcadFence?: {
    environmentId: string
    /** The retained source holds projects no move took: the host is unserved until moved again. */
    sourceChangedAt?: string
  }
}

/** Renderer-authored target fields; registration generations are allocated and owned by main. */
export type SshTargetCreateInput = Omit<
  SshTarget,
  | 'id'
  | 'generation'
  | 'orcadProvisioning'
  | 'orcadFence'
  | 'managedServerUnavailable'
  | 'managedServerMoveOffered'
  | 'managedServerLeaveBehind'
  | 'managedServerUpdateFailure'
  | 'managedServerRemoved'
>
export type SshTargetUpdateInput = Partial<SshTargetCreateInput>

/** Public target identity and observed host metadata safe to mirror to a paired client. */
export type SshTargetSummary = Pick<SshTarget, 'id' | 'label' | 'generation'> & {
  /** The SSH host's OS, when it has connected and the relay has detected it. */
  remotePlatform?: SshRemotePlatform
  /** Whether the target currently has a host-owned connected SSH lifecycle. */
  connected?: boolean
  /** Current SSH lifecycle state, when the desktop has one for this target. */
  connectionStatus?: SshConnectionStatus
}

/** Re-adopt orphaned repos/worktrees onto a replacement target ID; those records retain only the deleted target ID. */
export type RemovedSshTargetTombstone = {
  oldTargetId: string
  /** ssh-config alias, if any — the most stable re-adoption key. */
  configHost?: string
  host: string
  port: number
  username: string
  label: string
  /** ms epoch when the target was removed, for pruning old tombstones. */
  removedAt: number
}

/** Exact repo ownership changes made while re-adopting a removed SSH host. */
export type SshRepoReadoption = {
  oldTargetId: string
  newTargetId: string
  repoIds: string[]
}

export type SshTargetAddResult = {
  target: SshTarget
  repoReadoptions: SshRepoReadoption[]
}

export type SshConfigImportResult = {
  targets: SshTarget[]
  repoReadoptions: SshRepoReadoption[]
}

/** Concrete Host entry from ~/.ssh/config, for pickers that prefill the add-host form. */
export type SshConfigHostSummary = {
  alias: string
  hostname: string
  port: number
  username: string
  identityFile?: string
  proxyCommand?: string
  jumpHost?: string
  /** True when an Orca SSH target already uses this config alias. */
  alreadyInOrca: boolean
  /** Deleted alias remains explicitly selectable; passive/Add all import excludes it until re-adoption or save. */
  previouslyRemoved?: boolean
}

export const SSH_CONFIG_HOST_RESULT_LIMIT = 100

export type SshConfigHostListResult = {
  hosts: SshConfigHostSummary[]
  totalHostCount: number
  newHostCount: number
  matchCount: number
  hasMore: boolean
}

/** `refresh` re-reads ~/.ssh/config; filter keystrokes reuse the cached parse. */
export type SshConfigHostListArgs = { query?: string; refresh?: boolean }

/** Effective OpenSSH values used to prefill one manually managed target. */
export type SshConfigHostResolution = {
  alias: string
  hostname: string
  port: number
  username: string
  identityFiles: string[]
  identityAgent?: string
  identitiesOnly: boolean
  forwardAgent: boolean
  gssapiAuthentication?: boolean
  proxyCommand?: string
  proxyUseFdpass: boolean
  jumpHost?: string
}

export type SavedPortForward = {
  localPort: number
  remoteHost: string
  remotePort: number
  label?: string
}

/** A saved forward that isn't open on this connection; `error` is why its last start failed. */
export type UnrestoredPortForward = SavedPortForward & {
  error?: string
  /** It ran, then its process died, rather than never starting. */
  stopped?: true
}

export type SshConnectionStatus =
  | 'disconnected'
  | 'connecting'
  | 'auth-failed'
  | 'deploying-relay'
  | 'connected'
  | 'reconnecting'
  | 'reconnection-failed'
  | 'error'

export type SshRemotePlatform = 'linux' | 'darwin' | 'win32'

export type SshProviderEpoch = string & { readonly __sshProviderEpoch: unique symbol }

export type DirectSshAuthority = {
  targetId: string
  providerEpoch: SshProviderEpoch
  connectionGeneration: number
}

export type SshConnectionState = {
  targetId: string
  status: SshConnectionStatus
  error: string | null
  /** Number of reconnection attempts since last disconnect. */
  reconnectAttempt: number
  /** Opaque provider-incarnation token issued by main. */
  providerEpoch?: SshProviderEpoch | null
  /** Non-secret owner token used to reject mutations captured for an obsolete SSH session. */
  connectionGeneration?: number
  /** Folder downloads require ssh2 SFTP and are unavailable on system SSH. */
  supportsFolderDownload?: boolean
  /** Remote OS detected by the SSH relay once available. */
  remotePlatform?: SshRemotePlatform
  /** Set while connected without the Orca remote server (runtime ladder rung D). */
  plainSsh?: SshPlainSshMode
  /** Set while the relay runs on the opt-in host-Node runtime, an unsupported configuration. */
  hostNodeRuntime?: boolean
  /** Which server this host runs; optional so older clients simply ignore it. */
  managedServer?: SshManagedServerStatus
}

export const SSH_MANAGED_SERVER_PHASES = [
  'deploying',
  'converting',
  'connecting',
  'updating',
  'starting'
] as const

// Every state but host-newer means the server may be behind this app. Readers drop unknown states.
export const SSH_MANAGED_SERVER_UPDATE_STATES = [
  'host-newer',
  'deferred',
  'failed',
  'rolled-back',
  'no-template',
  'migrating',
  'check-failed'
] as const

/** Why a managed server kept its version on this connect; absent when it is current or updated. */
export type SshManagedServerUpdateNote = {
  state: (typeof SSH_MANAGED_SERVER_UPDATE_STATES)[number]
  detail?: string
}

/** A project the server already held at the same host path: this desktop uses the server's now. */
export type SshManagedServerLinkedProject = {
  path: string
  /** This desktop's automations on it, which stay behind with its tabs. */
  automations: number
}

/** A managed server that did not answer and was not proven serving, with why (and orcad.log's tail). */
export type SshManagedServerServingNote = { state: 'unverifiable'; detail: string }

export const SSH_MANAGED_SERVER_RELAY_REASONS = [
  'orcad_unavailable',
  'relay_terminals_live',
  'relay_terminals_unverifiable',
  'source_changed',
  'deferred',
  'refused',
  'failed'
] as const

export type SshManagedServerRelayReason = (typeof SSH_MANAGED_SERVER_RELAY_REASONS)[number]

export type SshManagedServerStatus =
  | {
      kind: 'managed'
      environmentId: string
      update?: SshManagedServerUpdateNote
      /** Set when the server did not answer and no start brought it up; never a terminal verdict. */
      serving?: SshManagedServerServingNote
      /** Set on the connect that moved this host's projects, when some were linked instead. */
      linked?: SshManagedServerLinkedProject[]
      /** Set on the connect that moved this host's automations, when its server kept some off. */
      automationsLeftDisabled?: number
      /**
       * macOS 15+: the SSH session that started this server proved exited, so its terminals may
       * have lost Local Network access (#25934). Absent when unknown, e.g. an older launch.
       */
      launchSessionEnded?: true
    }
  | { kind: 'setting-up'; phase: (typeof SSH_MANAGED_SERVER_PHASES)[number] }
  /** `detail` names the blocker for a refusal, or why orcad can't run on the host. */
  | {
      kind: 'relay'
      reason: SshManagedServerRelayReason
      detail?: string
      /** Relay terminals still running, when that is what keeps the host on the relay. */
      terminals?: number
      /** Those terminals belong to another Orca desktop or session, so this one offers no move. */
      terminalsElsewhere?: boolean
      /** The refusal is only saved state the user may leave on this desktop ("Move anyway"). */
      canLeaveBehind?: true
      /** A move to the managed server stopped short and keeps the host locked until it resumes. */
      held?: true
      /** Setup lost contact with the host, so nothing proves it failed there. */
      contactLost?: true
      /** Neither this computer nor the host could download the pinned Node runtime. */
      nodeDownloadBlocked?: SshManagedServerNodeDownloadBlocked
      /** COMPAT(legacy-relay-bridge): the connect stayed up so the bridge serves those terminals. */
      bridged?: true
    }

/** `mirror`: whether that download went through a mirror; admission drops an unknown value. */
export type SshManagedServerNodeDownloadBlocked = { mirror: NodeDistMirrorAttempt }

/** Plain SSH terminals and SFTP browsing only; `reason` is the ladder's classified cause. */
export type SshPlainSshMode = {
  reason: string
  message: string
}

/** Non-secret mutation provenance. Both fields are required when an SSH provider is selected. */
export type SshMutationExpectation = {
  expectedExecutionHostId?: 'local' | `ssh:${string}`
  expectedSshTargetId?: string
  expectedSshConnectionGeneration?: number
}

export type SshRemotePtyLeaseState = 'attached' | 'detached' | 'terminated' | 'expired'

export type SshRemotePtyLease = {
  targetId: string
  ptyId: string
  worktreeId?: string
  tabId?: string
  leafId?: string
  state: SshRemotePtyLeaseState
  createdAt: number
  updatedAt: number
  lastAttachedAt?: number
  lastDetachedAt?: number
  /** Client-local unconfirmed stop for replay to the same target; see ssh-pending-pty-kill.ts. Never sent on the wire. */
  pendingKill?: SshPendingPtyKill
  /** Stored-form winning lease ID, written by supersession; live upserts clear it so recycled IDs cannot inherit the mark. */
  supersededBy?: string
  /** Pending-stop replay proved a different incarnation owns this ID (relay-id-recycled); never reattach this lease. */
  relayIdRecycled?: true
}

/** Attached/detached still claim a running terminal; expired lost its route, while only terminated proves exit. */
export function isLiveSshPtyLease(lease: Pick<SshRemotePtyLease, 'state'>): boolean {
  return lease.state === 'attached' || lease.state === 'detached'
}

/** Expired means lost client route, never proven remote exit (ssh-execution-boundary.md).
 * Superseded/recycled marks prove this route unusable; unmarked orphans may reattach to discover whether the shell survived. */
export function sshRemotePtyLeaseAllowsReattach(
  lease: Pick<SshRemotePtyLease, 'state' | 'supersededBy' | 'relayIdRecycled'>
): boolean {
  if (lease.state === 'terminated') {
    return false
  }
  return (
    lease.state !== 'expired' ||
    (lease.supersededBy === undefined && lease.relayIdRecycled !== true)
  )
}

/** Main-owned relay lease needed to reclaim PTY delivery after a desktop restart. */
export type SshPtyConsumerRecovery = {
  targetId: string
  clientInstanceId: string
  serverBuildId: string
  clientGeneration: number
  ownerGeneration: number
  ownerLease: string
  outputFlowControl?: {
    version: 1
    windowSu: number
  }
}

export type PortForwardEntry = {
  id: string
  connectionId: string
  localPort: number
  remoteHost: string
  remotePort: number
  label?: string
  /** Remote terminal-advertised origin; renderer rewrites the forwarded port and relies on the user’s custom-host DNS. */
  advertisedUrl?: string
  /** Use advertised HTTPS even when its hostname cannot be reused locally. */
  advertisedProtocol?: 'http' | 'https'
}

export type DetectedPort = {
  port: number
  host: string
  pid?: number
  processName?: string
}

/** Main maps terminal-advertised URLs onto relay scan rows for IPC/UI. */
export type EnrichedDetectedPort = DetectedPort & {
  advertisedUrl?: string
  advertisedProtocol?: 'http' | 'https'
}