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.

9.5 KB
Raw Blame
/** Escape Win32-OpenSSH’s session job so detached children survive disconnect. libuv does not request breakaway; the staged addon uses CreateProcessW.
 * Legacy relay scripts alone may fall back to WMI, which standard-user network logons deny; orcad has no fallback. */
import { closeSync, openSync, readSync, renameSync, statSync, writeFileSync } from 'node:fs'
import { createRequire } from 'node:module'
import { quoteWindowsArgument } from '@orca/process-host/windows-command-line'
import {
  formatWindowsBreakawayLaunchReport,
  WINDOWS_BREAKAWAY_ENV_FLAG,
  WINDOWS_BREAKAWAY_EXIT_CODES,
  WINDOWS_BREAKAWAY_LAUNCH_FLAG,
  WINDOWS_BREAKAWAY_PROCESS_FILE_FLAG,
  WINDOWS_BREAKAWAY_STDERR_FLAG,
  WINDOWS_BREAKAWAY_STDERR_KEEP_PREVIOUS_FLAG,
  WINDOWS_BREAKAWAY_STDOUT_FLAG,
  type WindowsBreakawayLaunchContract,
  type WindowsBreakawayLaunchReport
} from './windows-breakaway-launch'
import { ORCAD_WINDOWS_PROCESS_TREE_FILENAME } from './orcad-artifacts'

/** Both bundles stage the addon under this name beside their entry script. */
const WINDOWS_PROCESS_TREE_ADDON = `./${ORCAD_WINDOWS_PROCESS_TREE_FILENAME}`
/** The kept previous log is its tail, so a crash loop cannot grow it without bound. */
export const PREVIOUS_STDERR_LOG_MAX_BYTES = 1024 * 1024

type SpawnOutsideJobResult =
  | { ok: true; pid: number; inJob: boolean }
  | { ok: false; reason: string; step: string; code: number }

export type SpawnOutsideJob = (
  application: string,
  commandLine: string,
  cwd: string,
  stdoutPath: string,
  stderrPath: string
) => SpawnOutsideJobResult

export type WindowsBreakawayLauncher = {
  spawnOutsideJob: SpawnOutsideJob
  /** Null when the addon cannot say, which callers must read as "identity unknown". */
  readCreationTimeMs: (pid: number) => number | null
}

export type WindowsBreakawayLaunchRequest = {
  stdoutPath: string
  stderrPath: string
  processFilePath?: string
  keepPreviousStderr?: boolean
  env: Record<string, string>
  programArgs: string[]
}

const ENV_ASSIGNMENT = /^([A-Z_][A-Z0-9_]*)=(.*)$/su
// argv is readable by other users on a shared host; secrets need an owner-only staged file instead.
const SECRET_ENV_NAME = /TOKEN|SECRET|KEY|PASSWORD|CREDENTIAL/u

export function parseWindowsBreakawayLaunchRequest(
  contract: WindowsBreakawayLaunchContract,
  argv: readonly string[]
): WindowsBreakawayLaunchRequest | null {
  const flag = argv.indexOf(WINDOWS_BREAKAWAY_LAUNCH_FLAG)
  if (flag === -1) {
    return null
  }
  const separator = argv.indexOf(contract.argsFlag, flag)
  const own = argv.slice(flag + 1, separator === -1 ? argv.length : separator)
  const valueOf = (name: string): string | undefined => {
    const index = own.indexOf(name)
    return index === -1 ? undefined : own[index + 1]
  }
  const required = (name: string): string => {
    const value = valueOf(name)
    if (!value) {
      throw new Error(`${WINDOWS_BREAKAWAY_LAUNCH_FLAG} needs ${name}`)
    }
    return value
  }
  const processFilePath = valueOf(WINDOWS_BREAKAWAY_PROCESS_FILE_FLAG)
  const env: Record<string, string> = {}
  for (const [index, value] of own.entries()) {
    if (value !== WINDOWS_BREAKAWAY_ENV_FLAG) {
      continue
    }
    const assignment = ENV_ASSIGNMENT.exec(own[index + 1] ?? '')
    if (!assignment?.[1]) {
      throw new Error(`${WINDOWS_BREAKAWAY_ENV_FLAG} needs NAME=VALUE`)
    }
    if (SECRET_ENV_NAME.test(assignment[1])) {
      throw new Error(`${WINDOWS_BREAKAWAY_ENV_FLAG} refuses ${assignment[1]}: argv is not secret`)
    }
    env[assignment[1]] = assignment[2] ?? ''
  }
  return {
    stdoutPath: required(WINDOWS_BREAKAWAY_STDOUT_FLAG),
    stderrPath: required(WINDOWS_BREAKAWAY_STDERR_FLAG),
    ...(processFilePath ? { processFilePath } : {}),
    ...(own.includes(WINDOWS_BREAKAWAY_STDERR_KEEP_PREVIOUS_FLAG)
      ? { keepPreviousStderr: true }
      : {}),
    env,
    programArgs: separator === -1 ? [] : argv.slice(separator + 1)
  }
}

/** The staged addon's launcher, or why there is none. */
export function loadWindowsBreakawayLauncher(
  requireNative: (specifier: string) => unknown = createRequire(__filename),
  platform: NodeJS.Platform = process.platform
): WindowsBreakawayLauncher | string {
  if (platform !== 'win32') {
    return 'not-windows'
  }
  let addon: unknown
  try {
    addon = requireNative(WINDOWS_PROCESS_TREE_ADDON)
  } catch {
    return 'addon-missing'
  }
  const record = addon && typeof addon === 'object' ? addon : {}
  const spawn = 'spawnOutsideJob' in record ? record.spawnOutsideJob : undefined
  if (typeof spawn !== 'function') {
    return 'addon-predates-launcher'
  }
  const creationTime =
    'getProcessCreationTime' in record ? record.getProcessCreationTime : undefined
  return {
    spawnOutsideJob: (...args) => readSpawnOutsideJobResult(spawn(...args)),
    readCreationTimeMs: (pid) => {
      const value: unknown = typeof creationTime === 'function' ? creationTime(pid) : undefined
      return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : null
    }
  }
}

function readSpawnOutsideJobResult(value: unknown): SpawnOutsideJobResult {
  const record = value && typeof value === 'object' ? Object.fromEntries(Object.entries(value)) : {}
  if (record.ok === true && typeof record.pid === 'number') {
    return { ok: true, pid: record.pid, inJob: record.inJob === true }
  }
  return {
    ok: false,
    reason: typeof record.reason === 'string' ? record.reason : 'unrecognized-result',
    step: typeof record.step === 'string' ? record.step : 'create-process',
    code: typeof record.code === 'number' ? record.code : 0
  }
}

export function keepPreviousStderrLog(
  path: string,
  maxBytes: number = PREVIOUS_STDERR_LOG_MAX_BYTES
): void {
  try {
    const { size } = statSync(path)
    if (size <= maxBytes) {
      renameSync(path, `${path}.1`)
      return
    }
    const tail = Buffer.alloc(maxBytes)
    const fd = openSync(path, 'r')
    try {
      readSync(fd, tail, 0, maxBytes, size - maxBytes)
    } finally {
      closeSync(fd)
    }
    writeFileSync(`${path}.1`, tail)
  } catch {
    // No previous log, or one still held open: the launch must not depend on keeping it.
  }
}

function writeProcessFile(path: string, contents: string): void {
  const partial = `${path}.partial-${process.pid}`
  writeFileSync(partial, contents)
  renameSync(partial, path)
}

export function launchOutsideJob(
  request: WindowsBreakawayLaunchRequest,
  launcher: WindowsBreakawayLauncher | string,
  runtime: { execPath: string; script: string; cwd: string },
  writeFile: (path: string, contents: string) => void = writeProcessFile,
  terminate: (pid: number) => void = (pid) => process.kill(pid)
): { report: WindowsBreakawayLaunchReport; exitCode: number } {
  if (typeof launcher === 'string') {
    return {
      report: { method: 'unavailable', reason: launcher },
      exitCode: WINDOWS_BREAKAWAY_EXIT_CODES.unavailable
    }
  }
  const commandLine = [runtime.execPath, runtime.script, ...request.programArgs]
    .map(quoteWindowsArgument)
    .join(' ')
  const result = launcher.spawnOutsideJob(
    runtime.execPath,
    commandLine,
    runtime.cwd,
    request.stdoutPath,
    request.stderrPath
  )
  if (!result.ok) {
    const failure = { reason: result.reason, step: result.step, code: result.code }
    // A job without BREAKAWAY_OK is a host property, not a launch failure.
    return result.reason === 'breakaway-denied'
      ? {
          report: { method: 'unavailable', ...failure },
          exitCode: WINDOWS_BREAKAWAY_EXIT_CODES.unavailable
        }
      : { report: { method: 'failed', ...failure }, exitCode: WINDOWS_BREAKAWAY_EXIT_CODES.failed }
  }
  const creationTimeMs = request.processFilePath ? launcher.readCreationTimeMs(result.pid) : null
  if (request.processFilePath) {
    try {
      writeFile(request.processFilePath, JSON.stringify({ pid: result.pid, creationTimeMs }))
    } catch (error) {
      // Without a process record, later cleanup cannot prove this identity; terminate now rather than orphan it.
      try {
        terminate(result.pid)
      } catch {
        // Already gone; nothing else can reach it.
      }
      const errno =
        error && typeof error === 'object' && 'errno' in error && typeof error.errno === 'number'
          ? error.errno
          : 0
      return {
        report: { method: 'failed', reason: 'process-file', code: errno },
        exitCode: WINDOWS_BREAKAWAY_EXIT_CODES.failed
      }
    }
  }
  return {
    report: {
      method: 'breakaway',
      pid: result.pid,
      inJob: result.inJob,
      ...(creationTimeMs === null ? {} : { creationTimeMs })
    },
    exitCode: WINDOWS_BREAKAWAY_EXIT_CODES.launched
  }
}

/** Runs the launcher mode when argv asks for it; false means run the program normally. */
export function runWindowsBreakawayLaunchIfRequested(
  contract: WindowsBreakawayLaunchContract,
  argv: readonly string[]
): boolean {
  const request = parseWindowsBreakawayLaunchRequest(contract, argv)
  if (!request) {
    return false
  }
  // CreateProcessW gets no environment block, so the child inherits this process's, edits included.
  Object.assign(process.env, request.env)
  if (request.keepPreviousStderr) {
    keepPreviousStderrLog(request.stderrPath)
  }
  const { report, exitCode } = launchOutsideJob(request, loadWindowsBreakawayLauncher(), {
    execPath: process.execPath,
    script: argv[1] ?? '',
    cwd: process.cwd()
  })
  // Why exit: nothing this one-shot mode loaded may keep the launching SSH exec open.
  process.stdout.write(`${formatWindowsBreakawayLaunchReport(contract, report)}\n`, () =>
    process.exit(exitCode)
  )
  return true
}