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.

6.3 KB
Raw Blame
/**
 * A Codex conversation moved between a grid and the own login, forked while no client holds it.
 *
 * A fork keeps the instructions saved in the conversation (`core/src/session/mod.rs`: config, then history, then the
 * model's own). An OpenAI model's say "call functions.exec"; a grid model has no such tool, so it calls it, Codex answers
 * `unsupported call: exec`, and the turn never ends. So the fork starts with the instructions Codex gives the
 * destination model in a new conversation. They stay in the new thread's metadata, so the pane's plain `codex resume`
 * needs no extra flags. The history and the source conversation are not touched.
 */
import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
import { createInterface } from 'node:readline'
import gridInstructions from './gridInstructions.json' with { type: 'json' }

const REQUEST_MS = 30_000

/**
 * Codex 0.166 advertises `exec` in the conversation it resumes but does not declare it as a tool on a
 * grid. A model following that habit calls it, Codex answers `unsupported call: exec`, and the turn
 * never ends. A person's request is one turn and the history still shows the old tool, so the only
 * place a grid move can say otherwise is the instructions the fork starts with.
 */
export const GRID_SHELL_INSTRUCTION =
  '\n\nThe shell tool on this provider is `exec_command`. Do not call `exec`: it does not exist here, and a call to it fails the turn. Run shell commands with `exec_command` directly.'

export interface CodexMove {
  sessionId: string
  toGrid: boolean
  /** The launch's own arguments: its `-c` pairs select the provider, its `-m` the model. */
  args: readonly string[]
  /** The full argv for these Codex arguments: on Windows an npm shim's batch file cannot be spawned (lib/windows/launch.ts). */
  argv: (args: readonly string[]) => string[]
  env: NodeJS.ProcessEnv
  cwd?: string
}

/** `-c` pairs and the model from a pane's argv. `codex app-server` takes `-c` but refuses `-m`. */
export function appServerArgs(args: readonly string[]): { config: string[]; model: string | null } {
  const config: string[] = []
  let model: string | null = null
  for (let i = 0; i < args.length; i++) {
    if (args[i] === '-c' && args[i + 1] !== undefined) config.push('-c', args[++i])
    else if (args[i] === '-m' && args[i + 1] !== undefined) model = args[++i]
  }
  return { config, model }
}

/** The instructions Codex's catalog gives a model. Null for a model it does not list, or a Codex with no such command. */
async function catalogInstructions(move: CodexMove, slug: string): Promise<string | null> {
  const output = await new Promise<string>((resolve) => {
    const [command, ...args] = move.argv(['debug', 'models', ...appServerArgs(move.args).config])
    const child = spawn(command!, args, { env: move.env, stdio: ['ignore', 'pipe', 'ignore'] })
    let text = ''
    child.stdout.on('data', (chunk) => { text += chunk })
    const timer = setTimeout(() => child.kill(), REQUEST_MS)
    child.on('error', () => { clearTimeout(timer); resolve('') })
    child.on('close', () => { clearTimeout(timer); resolve(text) })
  })
  try {
    const card = JSON.parse(output).models?.find((entry: { slug?: string }) => entry.slug === slug)
    return typeof card?.base_instructions === 'string' ? card.base_instructions : null
  } catch { return null }
}

function appServer(move: CodexMove) {
  const [command, ...args] = move.argv(['app-server', ...appServerArgs(move.args).config])
  const child: ChildProcessWithoutNullStreams = spawn(command!, args, { env: move.env, stdio: ['pipe', 'pipe', 'pipe'] })
  let next = 1
  const waiting = new Map<number, { resolve(result: any): void; reject(error: Error): void }>()
  const fail = (error: Error) => { for (const entry of waiting.values()) entry.reject(error); waiting.clear() }
  child.on('error', fail)
  child.on('exit', () => fail(new Error('Codex exited during the move')))
  child.stderr.resume()
  createInterface({ input: child.stdout }).on('line', (line) => {
    let message: any
    try { message = JSON.parse(line) } catch { return }
    const entry = typeof message.id === 'number' ? waiting.get(message.id) : undefined
    if (!entry) return
    waiting.delete(message.id)
    if (message.error) entry.reject(new Error(String(message.error.message ?? 'Codex refused the request')))
    else entry.resolve(message.result)
  })
  const request = (method: string, params: Record<string, unknown>) => new Promise<any>((resolve, reject) => {
    const id = next++
    const timer = setTimeout(() => { waiting.delete(id); reject(new Error(`Codex did not answer ${method}`)) }, REQUEST_MS)
    waiting.set(id, {
      resolve: (result) => { clearTimeout(timer); resolve(result) },
      reject: (error) => { clearTimeout(timer); reject(error) },
    })
    child.stdin.write(`${JSON.stringify({ id, method, params })}\n`)
  })
  return { child, request, notify: (method: string) => child.stdin.write(`${JSON.stringify({ method })}\n`) }
}

/** Returns the new conversation's id, ready for `codex resume`. Throws, having left the source as it was. */
export async function moveCodexConversation(move: CodexMove): Promise<string> {
  const server = appServer(move)
  try {
    await server.request('initialize', { clientInfo: { name: 'harness', version: '1' } })
    server.notify('initialized')
    const { model } = appServerArgs(move.args)
    // The launch's model, or the fork asks the new provider for the one the conversation was on.
    const params: Record<string, unknown> = { threadId: move.sessionId, ...(model ? { model } : {}), ...(move.cwd ? { cwd: move.cwd } : {}) }
    if (move.toGrid) {
      params.baseInstructions = gridInstructions.instructions + GRID_SHELL_INSTRUCTION
    } else {
      const listed = await server.request('model/list', { includeHidden: true })
      const slug = model ?? listed?.data?.find((entry: { isDefault?: boolean }) => entry.isDefault)?.model
      const instructions = typeof slug === 'string' ? await catalogInstructions(move, slug) : null
      if (instructions) params.baseInstructions = instructions
    }
    const forked = await server.request('thread/fork', params)
    const threadId: unknown = forked?.thread?.id
    if (typeof threadId !== 'string') throw new Error('Codex returned no conversation id for the fork')
    return threadId
  } finally { server.child.kill() }
}