Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

4.7 KB
Raw Blame
/**
 * Spawning the `claude` CLI for one turn.
 *
 * The invocation mirrors `apps/agent-node/brain/src/prefrontal/process.ts:444-463` — the flags are
 * infrastructural, and the user's message is passed VERBATIM. No wrapper text, no prepended hints.
 *
 * ⚠ This runs with `--dangerously-skip-permissions`: Claude executes tools without asking. That is a
 * deliberate choice for this example (it matches the product's `auto` autonomy) and it means the
 * agent can modify anything under its `cwd`. Point `agents.json` at a directory you are happy to
 * hand over. See README.md.
 */
import { spawn, type ChildProcess } from 'node:child_process'
import { createInterface } from 'node:readline'
import { anthropicSpawnEnv, type AnthropicEnv } from './config.js'
import type { StreamLine } from './mapper.js'

export interface TurnOptions {
  claudeBin: string
  cwd: string
  /** The user's text, passed through untouched. */
  text: string
  /** Present on every turn after the first in a session. */
  resumeSessionId?: string
  model?: string
  /** The endpoint and credential to run against. Absent ⇒ the CLI uses its own local login. */
  anthropic?: AnthropicEnv
  signal?: AbortSignal
}

export interface TurnHandle {
  /** Resolves on exit. CLI failures arrive through `onLine`; input delivery failures set `inputError`. */
  done: Promise<{ code: number | null; killed: boolean; inputError?: string }>
  kill: () => void
}

/**
 * Start a turn. `onLine` receives each parsed stdout line in order.
 *
 * Unparsable stdout is skipped rather than thrown on: the CLI is free to print things that are not
 * our JSON, and a stray line must not kill a turn.
 */
export function runTurn(opts: TurnOptions, onLine: (line: StreamLine) => void, onStderr?: (chunk: string) => void): TurnHandle {
  const args = [
    ...(opts.model ? ['--model', opts.model] : []),
    '--print',
    '--verbose',
    '--output-format', 'stream-json',
    '--input-format', 'stream-json',
    '--include-partial-messages',
    '--dangerously-skip-permissions',
    ...(opts.resumeSessionId ? ['--resume', opts.resumeSessionId] : []),
  ]

  const child = spawn(opts.claudeBin, args, {
    cwd: opts.cwd,
    // Its own process group, so cancelling kills the tools it started too. A bare child.kill()
    // leaves those orphaned — the same reason brain uses kill(-pid) in oneshot.ts.
    detached: true,
    stdio: ['pipe', 'pipe', 'pipe'],
    // Credentials LAST, so a configured endpoint wins over whatever the parent shell happens to
    // export. Absent, this spreads to nothing and the CLI authenticates exactly as it did before.
    env: { ...process.env, ...anthropicSpawnEnv(opts.anthropic) },
  })

  let killed = false
  let inputError: string | undefined
  const kill = (): void => {
    if (killed || child.exitCode !== null) return
    killed = true
    killGroup(child)
  }
  opts.signal?.addEventListener('abort', kill, { once: true })

  const failInput = (err: Error): void => {
    inputError = `could not write input to claude: ${err.message}`
    // A broken pipe is an execution failure, not a user cancellation.
    killGroup(child)
  }
  child.stdin?.on('error', failInput)

  if (child.stdout) {
    const rl = createInterface({ input: child.stdout, crlfDelay: Infinity })
    rl.on('line', (raw) => {
      const trimmed = raw.trim()
      if (!trimmed) return
      let parsed: StreamLine
      try {
        parsed = JSON.parse(trimmed) as StreamLine
      } catch {
        return // not our JSON — ignore rather than fail the turn
      }
      onLine(parsed)
    })
  }
  if (child.stderr && onStderr) {
    child.stderr.on('data', (chunk: Buffer) => onStderr(chunk.toString()))
  }

  // The user's message, verbatim, in the input-format stream-json envelope (brain: process.ts:809).
  try {
    child.stdin?.write(`${JSON.stringify({ type: 'user', message: { role: 'user', content: [{ type: 'text', text: opts.text }] } })}\n`)
    child.stdin?.end()
  } catch (err) {
    failInput(err instanceof Error ? err : new Error(String(err)))
  }

  const done = new Promise<{ code: number | null; killed: boolean; inputError?: string }>((resolve) => {
    let settled = false
    const finish = (code: number | null): void => {
      if (settled) return
      settled = true
      opts.signal?.removeEventListener('abort', kill)
      resolve({ code, killed, ...(inputError ? { inputError } : {}) })
    }
    child.on('close', finish)
    child.on('error', () => finish(null))
  })

  return { done, kill }
}

function killGroup(child: ChildProcess, signal: NodeJS.Signals = 'SIGKILL'): void {
  if (child.pid == null || child.exitCode !== null) return
  try {
    process.kill(-child.pid, signal) // negative pid = the whole group
  } catch {
    try { child.kill(signal) } catch { /* already gone */ }
  }
}