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.

11.7 KB
Raw Blame
import type { EngineLaunch } from '../facets/launch.js'

const permissionModes = {
  auto: ['--approve-for-me'],
  readOnly: ['--sandbox', 'read-only'],
  ask: [],
  full: ['--dangerously-bypass-approvals-and-sandbox'],
  // Code a Harness Team agent wrote (backend superTabs/teamWritten.ts, audit H2). Codex has no flag for it: a worktree takes its
  // main repository's trust, and `-c projects...` does not turn it off (0.165.0, tried). The start gives this mode an engine
  // home of its own, which trusts no project (superTabs/start.ts). Since v3 it runs as the project owner on their own computer,
  // so with Codex's own approvals and sandbox, never bypassed (review of #3485).
  teamWritten: [],
}

/**
 * Codex's launch, declared: data only, which core applies with the kit (engines/launches.ts,
 * engines/launchPrep.ts, lib/engineLaunch.ts). The pane script's startup probe and retry were
 * lib/engineLaunch.ts's and lib/codexStartupRetry.ts's, the own-login provider was
 * engines/codex/ownLoginProvider.ts, the environment flags were `codexEnvArgs` in this file, the folder trust
 * was lib/claudeTrust.ts's and the resume repair was engines/codex/portableHistory.ts
 * (docs/design/2026-10-08-engine-launch.md).
 */
export const launch: EngineLaunch = {
  permissionModes, bypassPermission: permissionModes.auto,
  firstPromptArgs: [], resumeArgs: ['resume'], forkArgs: { lead: ['fork'] },
  instructionFiles: ['AGENTS.override.md', 'AGENTS.md'],
  /**
   * Codex runs a session's commands in a shared app server (`codex app-server --managed-daemon`, codex-cli
   * 0.159.3), not under the process Harness launched, so they never see that process's environment.
   * Measured: HARNESS_CONTEXT_FILE and every manifest variable were unset in the agent's shell, and the
   * Model Manager ran without its instructions. `shell_environment_policy.set` is what Codex itself gives
   * every command, and `-c` carries it to whichever process runs them. The value is a JSON string, which
   * TOML reads as the same string. `-c a.b.NAME=…` splits the key on dots, so a name must be a bare key.
   */
  envArgs: { flag: '-c', setting: 'shell_environment_policy.set.{name}={value}', name: /^[A-Za-z_][A-Za-z0-9_]*$/ },
  // Older Codex shares one app-server per CODEX_HOME, which owns work independently of its terminal client.
  // New Harness launches opt out with --no-daemon (`startup.ownedFlag` below), as the first option.
  sharedServer: {
    ownedFlag: '--no-daemon', remoteFlag: '--remote', scripts: ['codex', 'codex.js'], pidFile: 'app-server-daemon/daemon.pid',
    messages: {
      unverified: 'Could not verify the Codex server before stopping',
      remote: 'Stop this conversation on its remote Codex server before closing its terminal',
      unidentified: 'Could not identify the conversation on the Codex server; the session is still open',
    },
  },
  /**
   * Undoing the provider a grid launch left behind in Codex's own state. From 0.155 Codex records one PER
   * THREAD in `<CODEX_HOME>/state_5.sqlite` (`threads.model_provider`), written at launch from whatever
   * `-c model_provider=` said. The grid contract says `grid` there (lib/gridLaunch.ts) and defines it in the
   * same argv, so the name is persisted while its definition is not: moved back to its own login, `codex
   * resume` failed before the TUI was up ("thread/resume failed: … Model provider grid not found") and the
   * restart gave up on the conversation. Measured against codex-cli 0.155.1, argv outranks the stored row, so
   * naming a provider again repairs a thread already poisoned; no database is read or written.
   *
   * The person's own top-level `model_provider` is their standing choice and is asked first: TOP-LEVEL only,
   * since in TOML every key after a `[header]` is that table's (a `[profiles.work]` provider is the profile's).
   * `openai` is what Codex itself would pick. Claude Code and Hermes read theirs from the environment or argv
   * every launch, and OpenCode's is a file this daemon writes, so only Codex declares this.
   */
  ownProvider: { home: 'CODEX_HOME', file: 'config.toml', key: 'model_provider', fallback: 'openai', args: ['-c', 'model_provider="{value}"'] },
  /**
   * From codex-cli 0.166.0 that argv no longer outranks the stored row: `thread/resume` checks the thread's saved
   * provider against the one it is given and refuses a difference (app-server config_manager.rs `load_for_resume`,
   * ModelProviderMismatch: "This chat uses openai, but your current provider is grid"), and the restart fell back to a
   * new conversation without its history. No app-server method changes a thread's provider (`thread/metadata/update`
   * and `thread/settings/update` carry none); `thread/fork` builds its config as a new thread's, so a move between a
   * grid and the own login continues the conversation in a fork, history included, on every version.
   */
  providerBoundConversations: true,
  /**
   * Codex keeps its folder trust in `<CODEX_HOME>/config.toml` as a `[projects."<path>"]` table with
   * `trust_level = "trusted"`, read from the agent's own profile or a CODEX_HOME the person moved, exact
   * folders only. Copied from the former lib/claudeTrust.ts.
   */
  trust: { home: { setting: 'CODEX_HOME' }, file: 'config.toml', format: 'toml', table: 'projects', key: 'trust_level', value: 'trusted' },
  /**
   * A rollout written on a grid relay keeps reasoning items the relay's portable_reasoning_item contract
   * forbids (a vendor-style id on plaintext reasoning, text in `content`). Back on Codex's own provider,
   * `codex resume` replays them and fails. Retargeting to the native subscription bypasses the grid, so
   * response-side relay cleanup cannot repair items already persisted: they are repaired before the resume.
   * `response_item` records are replayed as they are, and `compacted` ones replay their `replacement_history`.
   * Copied from the former engines/codex/portableHistory.ts and the rollout lookup of engines/codex/rollout.ts.
   */
  resumeRepair: {
    sessions: { home: { setting: 'CODEX_HOME' }, folder: 'sessions', suffix: '.jsonl', id: /^[a-zA-Z0-9-]{8,128}$/, walk: 5_000 },
    first: { type: 'session_meta', id: ['payload', 'id'] },
    items: [{ type: 'response_item', at: ['payload'] }, { type: 'compacted', at: ['payload', 'replacement_history'], list: true }],
    repair: 'portable-reasoning',
    backup: '.reasoning-backup-', temporary: '.reasoning-tmp-',
    names: { file: 'Codex rollout', history: 'Codex history', items: 'Codex reasoning items' },
  },
  startup: {
    /**
     * Codex 0.157+ otherwise puts the writer outside tmux in a shared server. Keep Harness-owned launches
     * process-owned so Close, hook attribution, provider env and RAM accounting describe the same lifetime.
     * Probed after any install, in the exact pane shell; older versions simply omit the flag. The probe is
     * bounded and never changes the person's Codex configuration.
     */
    ownedFlag: { unverified: 'could not verify Codex startup options. Please try opening this session again.' },
    retry: {
      // A successful startup update ends with Codex's explicit restart request (observed in codex-cli 0.160.0).
      // A tagged template, as the probe was: the bundle escapes its emoji in the raw text, where the escape and
      // the character match alike (scripts/lib/asciiOnly.mjs).
      updated: { status: 0, line: String.raw`^(?:🎉\s*)?Update ran successfully! Please restart Codex\.$`, message: 'Codex updated. Continuing startup…' },
      // Codex 0.159.3 exits 1 when account/read's workspace-routing discovery times out, before thread/start or
      // the first prompt. Retrying that exact bootstrap failure is safe; retrying an arbitrary exit could replay
      // work.
      transient: {
        status: 1,
        line: 'Error: account/read failed during TUI bootstrap: account/read failed: workspace routing discovery timed out (code -32603)',
        withinMs: 30_000, attempts: 3, backoffSeconds: 2,
        message: 'Codex account lookup timed out. Retrying startup ({attempt}/{attempts}) in {delay}s; Ctrl-C cancels.',
      },
    },
  },
  /**
   * Codex 0.157 made its full-screen transcript the default (`tui.fullscreen_transcript`, 0.156 added it), which
   * pins the composer to the foot of a phone's pane (facets/launch.ts `ScreenContract`). `-c` outranks the person's
   * config.toml and a profile's: measured against 0.162.1, `=true` there with `=false` here leaves the alternate
   * screen off. 0.155.1 and 0.146.0, which have no such key, start with it as they would without (2026-10-13).
   * `--no-alt-screen` would also do, but it turns every overlay inline too, the transcript pager among them.
   */
  screen: {
    args: ['-c', 'tui.fullscreen_transcript=false'],
    // In its scrollback 0.162.1 answers every resize, a phone's keyboard going up or down among them, by printing
    // its transcript again: `ESC[2J ESC[3J` outside its synchronized update about 80 ms after the resize, then the
    // whole transcript in one synchronized update (`ESC[?2026h` … `ESC[?2026l`), done by 155-186 ms (measured in a
    // 50x40 pane, 2026-10-13). A keyframe taken at 10-40 ms let the phone draw the cleared screen, a flash at every
    // raise and lower of the keyboard. Waiting instead for the output to pause held a phone's typing 1.5 s: Codex at
    // work redraws its `Working (…)` line without one. Read off its end, the wait was 100-112 ms. The clear came at
    // 78-82 ms idle; at work, past 150 ms (the flash came back at that, 2026-10-13), and one later still than this is
    // caught as live output (lib/terminalStreamManager.ts `REPAINT_GUARD_MS`). A Codex with no transcript to print
    // sends none, and costs the whole `withinMs`.
    resizeRepaint: { clears: '\u001b[3J', ends: '\u001b[?2026l', withinMs: 250 },
  },
  /**
   * Codex asks "Update available" on a start with a newer release out, with Update now (`npm install -g`) the highlighted
   * row, and no one is at a Swarm agent's terminal to answer (Studio Codex, 2026-10-29: tasks held behind it). The
   * startup check is `check_for_update_on_startup` in config.toml's top level (0.165.0's ConfigToml), and `-c` outranks
   * the person's file, as `screen.args` does. Only for sessions the Swarm starts: a person's Codex keeps asking, and
   * updating Codex stays their choice. Codex that still shows the prompt is answered with Skip by the host
   * (superTabs/terminal.ts).
   */
  swarmArgs: ['-c', 'check_for_update_on_startup=false'],
  /**
   * Codex 0.162.1 has no setting for its attribution's text: its own line ("Generated with [Codex](…)") is an
   * instruction in its developer message (`<git_attribution>`), on or off by workspace. `developer_instructions` is
   * the config key that adds to that message, so ours is worded as Codex words its own, and stays beside it.
   */
  attribution: {
    kind: 'instruction',
    home: { setting: 'CODEX_HOME' }, file: 'config.toml', folder: '.codex/config.toml', key: 'developer_instructions',
    instruction: 'When you create or update a pull request, its body must include this exact line once, near the end and '
      + 'after any other attribution line: `{line}` It says another agent started this session in Harness. Do not add it '
      + 'to commit messages.',
    args: ['-c', 'developer_instructions={value}'],
  },
  // Beside the attribution's instruction, in the one `developer_instructions` value (facets/launch.ts).
  // Its sandbox keeps a command from Harness's socket and port: told only that Harness was not running, an agent ran
  // `harness start` and asked the person to let it start Harness (a fresh Mac, 2026-10-12; lib/unreachable.ts).
  harnessInstructions: { kind: 'attribution', also: 'Codex\'s sandbox cannot reach Harness: run each harness command outside it, with escalated permissions.' },
}