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 { spawn } from 'node:child_process'
import { randomUUID } from 'node:crypto'
import { statSync } from 'node:fs'
import type { OrcaVmRecipe } from './orca-yaml-hook-types'
import { parseEphemeralVmRecipeResult, type EphemeralVmRecipeResult } from './ephemeral-vm-recipes'
import {
getEphemeralVmRecipeCheckoutModeFailure,
getEphemeralVmRecipeResultSchemaVersion
} from './ephemeral-vm-recipe-checkout-mode'
import { runRecipeCommand } from './ephemeral-vm-recipe-process'
import {
ephemeralVmExitFailure,
pickEphemeralVmFailureCode,
type EphemeralVmFailure
} from './ephemeral-vm-failure-copy'
import { getEphemeralVmRecipeDestroyFailure } from './ephemeral-vm-recipe-destroy-result'
import {
buildEphemeralVmRecipeCleanupPayload,
buildEphemeralVmRecipeLifecyclePayload
} from './ephemeral-vm-recipe-lifecycle-payload'
export {
buildEphemeralVmRecipeCleanupCommand,
buildEphemeralVmRecipeCleanupPayload,
type EphemeralVmRecipeCleanupPayload
} from './ephemeral-vm-recipe-lifecycle-payload'
export type EphemeralVmRecipeContext = {
instanceId?: string
recipeId: string
projectId?: string
workspaceId?: string
workspaceName?: string
repoPath: string
repoUrl?: string
branch?: string
ref?: string
expectedRefHead?: string
orcaVersion?: string
}
export type EphemeralVmRecipeStartArgs = {
recipe: OrcaVmRecipe
repoPath: string
context?: Partial<Omit<EphemeralVmRecipeContext, 'recipeId' | 'repoPath'>>
env?: NodeJS.ProcessEnv
maxCaptureBytes?: number
signal?: AbortSignal
onStdout?: (chunk: string) => void
onStderr?: (chunk: string) => void
spawnCommand?: typeof spawn
}
export type EphemeralVmRecipeStartSuccess = {
ok: true
context: EphemeralVmRecipeContext
result: EphemeralVmRecipeResult
stdout: string
stderr: string
}
export type EphemeralVmRecipeStartFailure = {
ok: false
context: EphemeralVmRecipeContext
stdout: string
stderr: string
exitCode: number | null
signal: NodeJS.Signals | null
recipeResult?: EphemeralVmRecipeResult
} & EphemeralVmFailure
export type EphemeralVmRecipeStartResult =
| EphemeralVmRecipeStartSuccess
| EphemeralVmRecipeStartFailure
export type EphemeralVmRecipeCleanupArgs = {
recipe: OrcaVmRecipe
repoPath: string
context: EphemeralVmRecipeContext
recipeResult: EphemeralVmRecipeResult
env?: NodeJS.ProcessEnv
maxCaptureBytes?: number
signal?: AbortSignal
onStdout?: (chunk: string) => void
onStderr?: (chunk: string) => void
spawnCommand?: typeof spawn
}
export type EphemeralVmRecipeLifecycleArgs = EphemeralVmRecipeCleanupArgs
export type EphemeralVmRecipeCleanupResult = {
ok: boolean
skipped: boolean
stdout: string
stderr: string
exitCode: number | null
signal: NodeJS.Signals | null
} & Partial<EphemeralVmFailure>
export type EphemeralVmRecipeResumeResult =
| (EphemeralVmRecipeStartSuccess & { skipped: false })
| (EphemeralVmRecipeStartFailure & { skipped: false })
| {
ok: true
skipped: true
context: EphemeralVmRecipeContext
stdout: string
stderr: string
}
export async function runEphemeralVmRecipeStart(
args: EphemeralVmRecipeStartArgs
): Promise<EphemeralVmRecipeStartResult> {
validateRepoPath(args.repoPath)
const context = buildRecipeContext(args.recipe, args.repoPath, args.context)
const processResult = await runRecipeCommand({
command: args.recipe.create,
repoPath: args.repoPath,
context,
mode: 'create',
resultSchemaVersion: getEphemeralVmRecipeResultSchemaVersion(args.recipe),
env: args.env,
maxCaptureBytes: args.maxCaptureBytes,
signal: args.signal,
onStdout: args.onStdout,
onStderr: args.onStderr,
spawnCommand: args.spawnCommand
})
if (processResult.exitCode !== 0) {
return {
ok: false,
context,
...ephemeralVmExitFailure('recipe', processResult.exitCode),
...processResult
}
}
const parsed = parseEphemeralVmRecipeResult(processResult.stdout)
if (!parsed.ok) {
return {
ok: false,
context,
error: parsed.error,
...pickEphemeralVmFailureCode(parsed),
...processResult
}
}
const checkoutModeFailure = getEphemeralVmRecipeCheckoutModeFailure(args.recipe, parsed.result)
if (checkoutModeFailure) {
return {
ok: false,
context,
...checkoutModeFailure,
recipeResult: parsed.result,
...processResult
}
}
return {
ok: true,
context,
result: parsed.result,
stdout: processResult.stdout,
stderr: processResult.stderr
}
}
export async function runEphemeralVmRecipeCleanup(
args: EphemeralVmRecipeCleanupArgs
): Promise<EphemeralVmRecipeCleanupResult> {
validateRepoPath(args.repoPath)
if (args.recipe.destroyDisabled || !args.recipe.destroy) {
return { ok: true, skipped: true, stdout: '', stderr: '', exitCode: null, signal: null }
}
const payload = buildEphemeralVmRecipeCleanupPayload(args)
const processResult = await runRecipeCommand({
command: args.recipe.destroy,
repoPath: args.repoPath,
context: args.context,
mode: 'destroy',
resultSchemaVersion: getEphemeralVmRecipeResultSchemaVersion(args.recipe),
stdin: `${JSON.stringify(payload)}\n`,
env: args.env,
maxCaptureBytes: args.maxCaptureBytes,
signal: args.signal,
onStdout: args.onStdout,
onStderr: args.onStderr,
spawnCommand: args.spawnCommand
})
const failure = getEphemeralVmRecipeDestroyFailure(processResult)
if (failure) {
return failure
}
return { ok: true, skipped: false, ...processResult }
}
export async function runEphemeralVmRecipeSuspend(
args: EphemeralVmRecipeLifecycleArgs
): Promise<EphemeralVmRecipeCleanupResult> {
validateRepoPath(args.repoPath)
if (!args.recipe.suspend) {
return { ok: true, skipped: true, stdout: '', stderr: '', exitCode: null, signal: null }
}
const payload = buildEphemeralVmRecipeLifecyclePayload({ ...args, mode: 'suspend' })
const processResult = await runRecipeCommand({
command: args.recipe.suspend,
repoPath: args.repoPath,
context: args.context,
mode: 'suspend',
resultSchemaVersion: getEphemeralVmRecipeResultSchemaVersion(args.recipe),
stdin: `${JSON.stringify(payload)}\n`,
env: args.env,
maxCaptureBytes: args.maxCaptureBytes,
signal: args.signal,
onStdout: args.onStdout,
onStderr: args.onStderr,
spawnCommand: args.spawnCommand
})
if (processResult.exitCode !== 0) {
return {
ok: false,
skipped: false,
error: `Suspend exited with code ${processResult.exitCode ?? 'unknown'}.`,
...processResult
}
}
return { ok: true, skipped: false, ...processResult }
}
export async function runEphemeralVmRecipeResume(
args: EphemeralVmRecipeLifecycleArgs
): Promise<EphemeralVmRecipeResumeResult> {
validateRepoPath(args.repoPath)
if (!args.recipe.resume) {
return {
ok: true,
skipped: true,
context: args.context,
stdout: '',
stderr: ''
}
}
const payload = buildEphemeralVmRecipeLifecyclePayload({ ...args, mode: 'resume' })
const processResult = await runRecipeCommand({
command: args.recipe.resume,
repoPath: args.repoPath,
context: args.context,
mode: 'resume',
resultSchemaVersion: getEphemeralVmRecipeResultSchemaVersion(args.recipe),
stdin: `${JSON.stringify(payload)}\n`,
env: args.env,
maxCaptureBytes: args.maxCaptureBytes,
signal: args.signal,
onStdout: args.onStdout,
onStderr: args.onStderr,
spawnCommand: args.spawnCommand
})
if (processResult.exitCode !== 0) {
return {
ok: false,
skipped: false,
context: args.context,
error: `Resume exited with code ${processResult.exitCode ?? 'unknown'}.`,
...processResult
}
}
const parsed = parseEphemeralVmRecipeResult(processResult.stdout)
if (!parsed.ok) {
return {
ok: false,
skipped: false,
context: args.context,
error: parsed.error,
...pickEphemeralVmFailureCode(parsed),
...processResult
}
}
const checkoutModeFailure = getEphemeralVmRecipeCheckoutModeFailure(args.recipe, parsed.result)
if (checkoutModeFailure) {
return {
ok: false,
skipped: false,
context: args.context,
...checkoutModeFailure,
recipeResult: parsed.result,
...processResult
}
}
return {
ok: true,
skipped: false,
context: args.context,
result: parsed.result,
stdout: processResult.stdout,
stderr: processResult.stderr
}
}
function buildRecipeContext(
recipe: OrcaVmRecipe,
repoPath: string,
context: EphemeralVmRecipeStartArgs['context'] = {}
): EphemeralVmRecipeContext {
return {
...context,
instanceId: context.instanceId ?? `orca-${randomUUID()}`,
recipeId: recipe.id,
repoPath
}
}
function validateRepoPath(repoPath: string): void {
const stat = statSync(repoPath)
if (!stat.isDirectory()) {
throw new Error(`Recipe repo path is not a directory: ${repoPath}`)
}
}