Where agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.
TypeScript
/**
* EngineAdapter — the pluggable "brain" for a BYOA agent.
*
* A BYOA agent's reasoning loop is delegated to a local CLI engine running
* on the user's machine: Claude Code, Codex, Grok Build, Cursor Agent,
* OpenCode, pi, Gemini CLI, Qwen Code, Antigravity, or ZCode. The daemon (daemon.ts) hands
* each wake to an adapter, which spawns the engine headlessly in the agent's
* dedicated home directory. The engine reads its persona + memory + skills
* from that home natively (CLAUDE.md / AGENTS.md, .claude/skills, …) and acts
* on Cumora through a fixed MCP bridge. The historical PATH shim remains only
* in explicitly unsandboxed compatibility mode.
*
* This module is intentionally standalone — only Node builtins — so the
* daemon can run on a machine with no Cumora DB/Redis access.
*
* NOTE on engine flags: the exact non-interactive / permission flags differ
* across engine versions. Claude and Codex run with fail-closed host boundaries
* by default. Engines without a verified boundary, and opaque argv overrides,
* require the explicit CUMORA_BYOA_ALLOW_UNSANDBOXED=1 compatibility opt-in
* (CUMORA_CLAUDE_ARGS / CUMORA_CODEX_ARGS / CUMORA_GROK_ARGS /
* CUMORA_CURSOR_ARGS / CUMORA_OPENCODE_ARGS / CUMORA_PI_ARGS, space-split). Correctness of the
* loop does not depend on the structured output — the agent acts via the
* `cumora` tool regardless of how we parse stdout.
*/
import { type ChildProcess, execFile, execFileSync, spawn as nodeSpawn, type SpawnOptions } from 'node:child_process'
import { randomUUID } from 'node:crypto'
import { existsSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
import { access, lstat, mkdir, mkdtemp, rename, rm, writeFile } from 'node:fs/promises'
import { homedir, tmpdir } from 'node:os'
import { dirname, isAbsolute, join, relative, sep, delimiter as PATH_DELIMITER } from 'node:path'
import { StringDecoder } from 'node:string_decoder'
import { stripLoneSurrogates } from '../text-safety.js'
import { CLAUDE_CORE_ENV_KEYS, claudeProviderFingerprint, isCustomAnthropicEndpoint, readClaudeUserSettings, withClaudeUserSettingsEnv } from './claude-user-settings.js'
import { isCliVersionAtLeast, probeEngineVersion, probeLocalEngineVersionWithRetry, versionCommandInvocation } from './cli-version.js'
import { discoverEngineModelCatalog, type EngineModelCatalog } from './model-catalog.js'
import { visionCapabilityForModel } from './model-capabilities.js'
import { CODEX_RUNTIME_CONFIG_ARGS, codexAuthFingerprint, codexRuntimeEnv } from './codex-runtime.js'
import { cachedCodexProvider, codexProviderEnv, codexProviderFingerprint, codexProviderRuntime, prepareCodexProvider } from './codex-provider.js'
import { assertCodexProviderTransport, codexCommandInvocation } from './codex-rpc.js'
import { modelIdOrNull } from './model-id.js'
import { supportsNativeFastMode } from '../../../../shared/native-fast-mode.js'
const IS_WIN = process.platform === 'win32'
/** Every engine runs headlessly behind the daemon. On Windows, leaving
* `windowsHide` at Node's default (`false`) lets a console executable (or the
* cmd.exe needed for an npm .cmd shim) create a visible terminal even when the
* PowerShell watchdog itself was launched with `-WindowStyle Hidden`.
*
* Keep this in the module-local spawn wrapper so persistent sessions, one-shot
* turns, doctor probes, and PATH probes cannot drift apart. `windowsHide` is
* ignored on non-Windows platforms. */
export function headlessSpawnOptions(options: SpawnOptions = {}): SpawnOptions {
return { ...options, windowsHide: true }
}
/** What `spawn` will actually execute. On Windows, `shell: true` is rewritten
* to an explicit `cmd.exe /d /s /c` invocation with quoted arguments. Node's
* own `shell: true` does not quote argv, so a model id can break out of the
* command. Exported so the rewrite can be tested off Windows. */
export function shellSafeSpawnPlan(
command: string,
args: string[],
options: SpawnOptions = {},
platform = process.platform,
): { command: string; args: string[]; options: SpawnOptions } {
if (options.shell && platform === 'win32') {
const unquoted = command.length >= 2 && command.startsWith('"') && command.endsWith('"')
? command.slice(1, -1)
: command
const invocation = versionCommandInvocation(unquoted, args, platform, process.env.ComSpec || 'cmd.exe', true)
const { shell: _shell, ...rest } = options
return {
command: invocation.command,
args: invocation.args,
options: headlessSpawnOptions({
...rest,
shell: false,
windowsVerbatimArguments: invocation.windowsVerbatimArguments === true,
}),
}
}
return { command, args, options: headlessSpawnOptions(options) }
}
function spawn(command: string, args: string[], options: SpawnOptions = {}): ChildProcess {
const plan = shellSafeSpawnPlan(command, args, options)
return nodeSpawn(plan.command, plan.args, plan.options)
}
/** Model tools may spawn descendants that outlive the CLI parent. Put every
* engine process in its own POSIX process group, and terminate the complete
* tree on cancellation. Windows has no process-group signal equivalent, so
* taskkill /T supplies the platform's tree semantics. */
function spawnEngineChild(command: string, args: string[], options: SpawnOptions = {}): ChildProcess {
return spawn(command, args, { ...options, detached: !IS_WIN })
}
interface EngineTerminationState {
forceRequested: boolean
promise: Promise<void>
}
const engineTerminations = new WeakMap<ChildProcess, EngineTerminationState>()
function childHasExited(child: ChildProcess): boolean {
return child.exitCode !== null || child.signalCode !== null
}
function waitForChildExit(child: ChildProcess, timeoutMs: number): Promise<boolean> {
if (childHasExited(child)) return Promise.resolve(true)
return new Promise((resolve) => {
let settled = false
const finish = (exited: boolean) => {
if (settled) return
settled = true
clearTimeout(timer)
child.off('close', onClose)
child.off('error', onClose)
resolve(exited)
}
const onClose = () => finish(true)
const timer = setTimeout(() => finish(childHasExited(child)), timeoutMs)
timer.unref?.()
child.once('close', onClose)
child.once('error', onClose)
})
}
function readProcessTable(): Promise<Map<number, number>> {
return new Promise((resolve) => {
execFile('ps', ['-axo', 'pid=,ppid='], { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 }, (err, stdout) => {
const table = new Map<number, number>()
if (!err) {
for (const line of stdout.split('\n')) {
const match = line.trim().match(/^(\d+)\s+(\d+)$/)
if (match) table.set(Number(match[1]), Number(match[2]))
}
}
resolve(table)
})
})
}
function expandDescendants(tracked: Set<number>, table: ReadonlyMap<number, number>): void {
let changed = true
while (changed) {
changed = false
for (const [pid, parent] of table) {
if (!tracked.has(pid) && tracked.has(parent)) {
tracked.add(pid)
changed = true
}
}
}
}
function signalPid(pid: number, signal: NodeJS.Signals): void {
try { process.kill(pid, signal) } catch { /* process already exited */ }
}
function anyPidAlive(pids: ReadonlySet<number>): boolean {
for (const pid of pids) {
try {
process.kill(pid, 0)
return true
} catch { /* process is gone */ }
}
return false
}
function signalProcessGroup(child: ChildProcess, signal: NodeJS.Signals): void {
const pid = child.pid
if (!pid) {
try { child.kill(signal) } catch { /* already gone */ }
return
}
try { process.kill(-pid, signal) }
catch { try { child.kill(signal) } catch { /* already gone */ } }
}
async function terminateWindowsTree(child: ChildProcess): Promise<void> {
const pid = child.pid
if (!pid) return
await new Promise<void>((resolve) => {
execFile(
'taskkill.exe', ['/pid', String(pid), '/t', '/f'],
headlessSpawnOptions({ windowsHide: true }),
(err) => {
if (err && !childHasExited(child)) {
try { child.kill('SIGKILL') } catch { /* already gone */ }
}
resolve()
},
)
})
await waitForChildExit(child, 1_500)
}
async function terminatePosixTree(
child: ChildProcess,
state: EngineTerminationState,
): Promise<void> {
const rootPid = child.pid
if (!rootPid) return
const tracked = new Set<number>([rootPid])
// Snapshot before signalling the group. A child may deliberately call
// setsid()/setpgid() and escape the engine's PGID while retaining the engine
// as its parent; explicit descendant signals cover that case.
expandDescendants(tracked, await readProcessTable())
const initialSignal: NodeJS.Signals = state.forceRequested ? 'SIGKILL' : 'SIGTERM'
for (const pid of [...tracked].reverse()) signalPid(pid, initialSignal)
signalProcessGroup(child, initialSignal)
if (!state.forceRequested) {
await waitForChildExit(child, 1_000)
// The engine parent may exit promptly while a detached descendant ignores
// SIGTERM. Do not mistake the parent's close event for completion of the
// previously discovered tree.
if (!anyPidAlive(tracked)) return
}
// Re-scan before escalating. Descendants recorded in `tracked` stay targets
// even if their parent exits and init adopts them between scans.
expandDescendants(tracked, await readProcessTable())
for (const pid of [...tracked].reverse()) signalPid(pid, 'SIGKILL')
signalProcessGroup(child, 'SIGKILL')
// A terminating process can race one final fork with the first snapshot.
// Bounded rescans catch descendants of every still-known PID without turning
// shutdown into an unbounded wait or signalling unrelated processes later.
for (let attempt = 0; attempt < 4; attempt += 1) {
await new Promise((resolve) => setTimeout(resolve, 25))
expandDescendants(tracked, await readProcessTable())
let survivor = false
for (const pid of tracked) {
try {
process.kill(pid, 0)
survivor = true
signalPid(pid, 'SIGKILL')
} catch { /* process is gone */ }
}
if (!survivor) break
}
// Wait for killed PIDs to disappear from the process table (including a
// briefly reparented zombie). `stop()` must not resolve while a known old
// descendant can still run beside the replacement runner.
for (let attempt = 0; attempt < 40 && anyPidAlive(tracked); attempt += 1) {
for (const pid of tracked) signalPid(pid, 'SIGKILL')
await new Promise((resolve) => setTimeout(resolve, 25))
}
await waitForChildExit(child, 1_500)
}
/** Terminate an engine and wait for the platform's tree operation to finish.
* Calls are idempotent; a later force request escalates an in-progress graceful
* stop. Runner replacement awaits this promise before reseeding model-writable
* state or launching the next engine. */
function terminateEngineTree(child: ChildProcess, force = false): Promise<void> {
const current = engineTerminations.get(child)
if (current) {
if (force) current.forceRequested = true
return current.promise
}
const state: EngineTerminationState = { forceRequested: force, promise: Promise.resolve() }
state.promise = (IS_WIN ? terminateWindowsTree(child) : terminatePosixTree(child, state))
.catch(() => {
try { child.kill('SIGKILL') } catch { /* already gone */ }
})
engineTerminations.set(child, state)
return state.promise
}
/** Bind an AbortSignal to one engine child and retain the exact termination
* promise. One-shot helpers must await `wait()` before resolving an aborted
* operation; otherwise AgentRunner's active-run barrier can finish while the
* platform tree terminator is still working. */
function bindAbortTermination(
child: ChildProcess,
signal: AbortSignal,
): { dispose: () => void; wait: () => Promise<void> } {
let termination: Promise<void> | null = null
const onAbort = (): void => {
if (!termination) termination = terminateEngineTree(child, true)
}
signal.addEventListener('abort', onAbort, { once: true })
if (signal.aborted) onAbort()
return {
dispose: () => signal.removeEventListener('abort', onAbort),
wait: () => termination ?? Promise.resolve(),
}
}
// Optional last-resort cap on a single persistent-engine turn. DEFAULT OFF (0):
// a wall-clock timeout CANNOT tell a genuinely-hung turn from a legitimately
// long-running one (e.g. an agent running a multi-hour Bash command blocks this
// turn with no output the whole time), so a default timeout would KILL real work.
// Responsiveness during a long turn is handled by same-turn STEERING, not by
// killing the turn. Set CUMORA_TURN_TIMEOUT_MS (milliseconds) to opt into a runaway
// backstop; 0/unset = no timeout (long tasks run to completion).
const TURN_TIMEOUT_MS = Number(process.env.CUMORA_TURN_TIMEOUT_MS) || 0
// By default the Codex app-server's raw event stream (text deltas, per-item token
// + rate-limit snapshots, full item JSON) is NOT echoed to the daemon log — it's a
// fire-hose the daemon doesn't need. Set CUMORA_CODEX_VERBOSE=1 to dump it raw.
const CODEX_LOG_RAW = process.env.CUMORA_CODEX_VERBOSE === '1'
function codexLocalImagePaths(home: string, localImages: readonly string[]): string[] {
let realHome: string
try { realHome = realpathSync(home) } catch { return [] }
return [...new Set(localImages.filter((path) => {
if (!path || !isAbsolute(path)) return false
try {
const actual = realpathSync(path)
const fromHome = relative(realHome, actual)
return fromHome !== '' && fromHome !== '..' && !fromHome.startsWith(`..${sep}`) && !isAbsolute(fromHome)
} catch { return false }
}))]
}
function codexTurnInput(prompt: string, localImages: readonly string[], home: string): Array<Record<string, unknown>> {
const images = codexLocalImagePaths(home, localImages)
return [
{ type: 'text', text: stripLoneSurrogates(prompt), text_elements: [] },
...images.map((path) => ({ type: 'localImage', path })),
]
}
/** How to spawn a CLI bin cross-platform.
* - POSIX: spawn the bare bin with shell:false — unchanged, zero-risk.
* - Windows: engine CLIs are usually `.cmd` shims that Node CANNOT run with
* shell:false (CreateProcess can't execute a batch file) → "process exited with
* code 1". Resolve the real file on PATH and run a `.cmd`/`.bat` via
* shell:true. When the shell is needed,
* a big multi-line prompt must travel via STDIN, not argv (the shell can't carry
* it) → `wantsStdinPrompt`.
*
* Windows + nvm-windows gotcha: global npm CLIs are shipped as an extensionless
* POSIX shell-shim (`#!/bin/sh` wrapper) ALONGSIDE the real `.cmd`. The old loop
* iterated `['', ...PATHEXT]`, hit the shim first, classified it as non-batch,
* and returned `shell:false` → every engine turn died with ENOENT.
* Fix: prefer a real `.exe`/`.cmd`/`.bat` hit; only fall back to the shim with
* `shell:true` when nothing else is on PATH. */
// Exported for tests; the nvm-windows extensionless-shim regression (issue #5)
// needs a stable handle to the resolver without going through spawn().
export function resolveSpawn(bin: string, env: NodeJS.ProcessEnv = process.env): { command: string; shell: boolean; wantsStdinPrompt: boolean } {
if (!IS_WIN) return { command: bin, shell: false, wantsStdinPrompt: false }
const pathExt = env.PATHEXT ?? env.PathExt ?? '.COM;.EXE;.BAT;.CMD'
const searchPath = env.PATH ?? env.Path ?? ''
const exts = pathExt.split(';').map((e) => e.trim()).filter(Boolean)
for (const dir of searchPath.split(PATH_DELIMITER)) {
if (!dir) continue
for (const ext of exts) {
const candidate = join(dir, bin + ext)
if (existsSync(candidate)) {
const isBatch = /\.(cmd|bat)$/i.test(candidate)
// When shell:true and the path contains spaces, cmd.exe will split the
// command at the space unless we quote it (e.g. "C:\Program Files\codex").
const command = isBatch && candidate.includes(' ') ? `"${candidate}"` : candidate
return { command, shell: isBatch, wantsStdinPrompt: isBatch }
}
}
}
// Last resort: only an extensionless shim (nvm-windows) is on PATH. The shim
// itself is a `#!/bin/sh` wrapper and cannot be exec'd without a shell → force
// shell:true so Node routes the call through cmd.exe, which can find the
// .cmd via PATHEXT after the shim.
for (const dir of searchPath.split(PATH_DELIMITER)) {
if (!dir) continue
const shim = join(dir, bin)
if (existsSync(shim)) {
const command = shim.includes(' ') ? `"${shim}"` : shim
return { command, shell: true, wantsStdinPrompt: true }
}
}
// Not found on PATH at all — let the shell resolve it, and feed the prompt via stdin.
return { command: bin, shell: true, wantsStdinPrompt: true }
}
type CodexSpawn = ReturnType<typeof resolveSpawn> & { argsPrefix: string[] }
/** npm's Windows `codex.cmd` forwards arguments through `%*`. Running that
* shim with Node's `shell:true` lets cmd.exe consume the double quotes inside
* structured `-c key=<toml>` values. A valid inline TOML table then reaches
* Codex as a plain string and strict config loading fails before the turn can
* start. Bypass cmd.exe by invoking the npm package's JS entry point with the
* same Node installation whenever the standard npm layout is available. */
function resolveCodexSpawn(): CodexSpawn {
const fallback = resolveSpawn('codex')
if (!IS_WIN || !fallback.shell) return { ...fallback, argsPrefix: [] }
const shim = fallback.command.startsWith('"') && fallback.command.endsWith('"')
? fallback.command.slice(1, -1)
: fallback.command
if (!/\.cmd$/i.test(shim)) return { ...fallback, argsPrefix: [] }
const invocation = codexCommandInvocation(shim, [], process.env)
if (invocation.windowsVerbatimArguments) return { ...fallback, argsPrefix: [] }
return { command: invocation.command, argsPrefix: invocation.args, shell: false, wantsStdinPrompt: false }
}
/** Interactive setup uses exactly the same home as every background call. */
export async function loginCodexRuntime(): Promise<void> {
const bin = await resolveBinPath('codex')
if (!bin || !await probeLocalEngineVersionWithRetry('codex', bin)) {
throw new Error(bin
? 'Codex CLI was found on PATH, but its version could not be verified. Check `codex --version`, then rerun `cumora agent computer --codex-login`.'
: 'Codex CLI is unavailable on PATH. Install it with `npm install -g @openai/codex`, then rerun `cumora agent computer --codex-login`.')
}
const { command, shell, argsPrefix } = resolveCodexSpawn()
return new Promise((resolve, reject) => {
const child = spawn(command, [...argsPrefix, 'login'], {
env: codexRuntimeEnv(), stdio: 'inherit', shell,
})
child.once('error', reject)
child.once('close', code => code === 0 ? resolve() : reject(new Error(`Codex login exited with code ${code}`)))
})
}
export type EngineId = 'claude' | 'codex' | 'grok' | 'cursor' | 'opencode' | 'pi' | 'gemini' | 'qwen' | 'antigravity' | 'zcode' | 'maka' | 'omp'
/** The pairable engine ids, in the daemon's default detection order. */
export const ENGINE_IDS: EngineId[] = ['claude', 'codex', 'grok', 'cursor', 'opencode', 'pi', 'gemini', 'qwen', 'antigravity', 'zcode', 'maka', 'omp']
/** Engines for which Cumora can impose a fail-closed filesystem + tool-network
* boundary non-interactively. The remaining adapters still work for operators
* who explicitly accept host-level execution, but are never selected merely
* because their binary happens to be on PATH. */
export const SANDBOXED_ENGINE_IDS: readonly EngineId[] = ['claude', 'codex']
export const ALLOW_UNSANDBOXED_BYOA_ENV = 'CUMORA_BYOA_ALLOW_UNSANDBOXED'
export const SECURE_ENGINE_MIN_VERSIONS: Readonly<Partial<Record<EngineId, string>>> = {
// --restricted first shipped here; it is what ignores user/project settings
// and confines built-in file tools to the Agent working directory.
claude: '2.1.248',
// Permission profiles (default_permissions / permissions.*) are supported
// starting with this Codex release.
codex: '0.138.0',
}
export function allowUnsandboxedByoa(env: NodeJS.ProcessEnv = process.env): boolean {
return env[ALLOW_UNSANDBOXED_BYOA_ENV] === '1'
}
export function runnableEngineIds(
installed: readonly EngineId[],
env: NodeJS.ProcessEnv = process.env,
platform: NodeJS.Platform = process.platform,
): EngineId[] {
if (allowUnsandboxedByoa(env)) return [...installed]
const safe = new Set(SANDBOXED_ENGINE_IDS)
return installed.filter((id) => safe.has(id) && !(platform === 'win32' && id === 'claude'))
}
export interface RunnableEngineEvaluation {
/** Evaluation consumers only inspect this inventory; accepting readonly
* arrays also keeps literal test fixtures and immutable snapshots type-safe. */
runnable: readonly EngineId[]
blocked: Array<{
id: EngineId
reason: string
state?: 'confirmed-incompatible' | 'temporarily-unverifiable'
}>
/** Engines kept runnable from a last-known-good verification while their
* current version command was temporarily inconclusive. */
temporarilyUnverifiable?: EngineId[]
}
interface VerifiedEngineVersion {
fingerprint: string
minimum: string
version: string
}
const verifiedEngineVersions = new Map<EngineId, VerifiedEngineVersion>()
/** Test seam and cache invalidation hook for a changed security policy. */
export function clearVerifiedEngineVersions(): void {
verifiedEngineVersions.clear()
}
function engineBinaryFingerprint(path: string | null): string | null {
if (!path) return null
try {
const real = realpathSync(path)
const info = statSync(real)
return `${real}:${info.dev}:${info.ino}:${info.size}:${info.mtimeMs}`
} catch {
return null
}
}
export function secureEngineCapabilityReason(
id: EngineId,
version: string | null,
platform: NodeJS.Platform,
linuxSandboxDeps: { bwrap: boolean; socat: boolean } = { bwrap: true, socat: true },
): string | null {
const minimum = SECURE_ENGINE_MIN_VERSIONS[id]
if (!minimum || !isCliVersionAtLeast(version, minimum)) {
return version
? `version ${version} is older than the secure minimum ${minimum ?? 'unknown'}`
: `could not verify the installed version (secure minimum ${minimum ?? 'unknown'})`
}
if (id === 'claude' && platform === 'linux' && (!linuxSandboxDeps.bwrap || !linuxSandboxDeps.socat)) {
const missing = [!linuxSandboxDeps.bwrap && 'bubblewrap (bwrap)', !linuxSandboxDeps.socat && 'socat'].filter(Boolean).join(', ')
return `missing sandbox dependency: ${missing}`
}
return null
}
/** Fail-closed capability check layered on top of the static engine allowlist.
* Merely having a binary named `claude` or `codex` is insufficient: older
* releases silently ignore the exact boundary controls Cumora depends on. */
export async function evaluateRunnableEngines(
installed: readonly EngineId[],
env: NodeJS.ProcessEnv = process.env,
platform: NodeJS.Platform = process.platform,
): Promise<RunnableEngineEvaluation> {
const candidates = runnableEngineIds(installed, env, platform)
if (allowUnsandboxedByoa(env)) return { runnable: candidates, blocked: [] }
const snapshot = await snapshotDetectedEngines(candidates)
const probes = new Map(await Promise.all(snapshot.map(async (entry) => {
const minimum = SECURE_ENGINE_MIN_VERSIONS[entry.id] ?? ''
const fingerprint = engineBinaryFingerprint(entry.path)
const probed = await probeLocalEngineVersionWithRetry(entry.id, entry.path)
if (probed && fingerprint && minimum) {
verifiedEngineVersions.set(entry.id, { fingerprint, minimum, version: probed })
}
const cached = verifiedEngineVersions.get(entry.id)
const cachedVersion = !probed && fingerprint && cached?.fingerprint === fingerprint && cached.minimum === minimum
? cached.version
: null
return [entry.id, { version: probed ?? cachedVersion, temporarilyUnverifiable: !probed }] as const
})))
const linuxSandboxDeps = platform === 'linux'
? { bwrap: await binOnPath('bwrap'), socat: await binOnPath('socat') }
: { bwrap: true, socat: true }
const runnable: EngineId[] = []
const blocked: RunnableEngineEvaluation['blocked'] = []
const temporarilyUnverifiable: EngineId[] = []
for (const id of candidates) {
const probe = probes.get(id)
const version = probe?.version ?? null
const reason = secureEngineCapabilityReason(id, version, platform, linuxSandboxDeps)
if (reason) {
blocked.push({
id,
reason,
state: version ? 'confirmed-incompatible' : 'temporarily-unverifiable',
})
continue
}
runnable.push(id)
if (probe?.temporarilyUnverifiable) temporarilyUnverifiable.push(id)
}
return { runnable, blocked, temporarilyUnverifiable }
}
export interface EnginePersona {
id: string
name: string
role: string | null
systemPrompt: string | null
}
export interface EngineRunArgs {
/** Agent's dedicated home dir; becomes the engine's cwd and secure sandbox root. */
home: string
/** The per-wake trigger prompt. */
prompt: string
/** Env for the engine subprocess (includes the `cumora` shim wiring). */
env: NodeJS.ProcessEnv
/** Big-brain (main reasoning) model — passed to the engine as --model. */
model?: string | null
/** Small-brain (cheap auxiliary) model. Claude: ANTHROPIC_SMALL_FAST_MODEL.
* Codex has no general fast-model knob, so it's ignored there for now. */
fastModel?: string | null
nativeFastMode?: boolean
/** Resume a prior engine session so the agent keeps continuous context
* across wakes (Claude: `--resume <id>`). Null/undefined → fresh session.
* This is what lets a BYOA agent remember its place in a running task
* (e.g. a counting relay: it knows it already said "2") instead of
* re-deriving everything from a frozen inbox snapshot each wake. */
resumeSessionId?: string | null
/** Explicitly reported visual capability for the active model. */
vision?: 'supported' | 'unsupported' | 'unknown'
/** Absolute paths to image attachments already materialized in the agent home.
* Only adapters with a verified native image-input protocol consume these;
* other adapters continue to receive the textual attachment path. */
localImages?: readonly string[]
/** Called for each stdout/stderr line — daemon logs / Phase-2 observability. */
onLog: (line: string) => void
/** Optional per-hop trajectory hook — same shape as EngineSessionArgs.onHopUsage.
* When the one-shot path runs the engine via a stream parser (Claude
* stream-json), each assistant message fires this; for engines that don't
* emit per-hop usage (Codex `exec`), the callback fires once at the
* terminating `result` event with the run's full usage. Daemon wires this
* into the same buffered ledger as the persistent-session path. */
onHopUsage?: (report: EngineHopReport) => void
/** Aborts the run (daemon shutdown / future mid-run steering). */
signal: AbortSignal
}
/** Raw token usage as engines report it (Anthropic/Claude Code field names).
* Passed through verbatim — the daemon maps it to the cost ledger — so this
* module stays standalone (no pricing import). Undefined = engine gave none. */
export interface EngineUsage {
input_tokens?: number
output_tokens?: number
cache_read_input_tokens?: number
cache_creation_input_tokens?: number
}
export type EngineFailureKind =
| 'startup'
| 'resume-not-found'
| 'context-overflow'
| 'authentication'
| 'rate-limit'
| 'transport'
| 'unknown'
/** Machine-readable failure alongside the existing operator-facing error.
* `diagnostic` retains the bounded engine output used for classification;
* callers must not display it without the daemon's normal redaction. */
export interface EngineFailure {
kind: EngineFailureKind
message: string
diagnostic: string
}
const RESUME_NOT_FOUND_RE = new RegExp([
String.raw`\bno (?:such )?(?:\w+ )?(?:conversation|session|thread)s?\b`,
String.raw`\b(?:conversation|session|thread)s?(?: id)?\b[^\n]{0,24}?\b(?:not found|no longer exists?|do(?:es)? not exist|doesn't exist|has expired|is expired|is invalid|is unknown)\b`,
String.raw`\b(?:invalid|unknown|expired|stale|malformed) (?:\w+ )?(?:conversation|session|thread)s?\b`,
String.raw`\b(?:could ?n(?:o|')?t|cannot|can't|unable to|failed to)\b[^\n]{0,24}?\bresume\b`,
String.raw`\bthread/resume failed\b`,
].join('|'), 'i')
const ENGINE_CONTEXT_OVERFLOW_RE = /context window|context length|context_length_exceeded|maximum context|reached its context|prompt is too long|input is too long|too many tokens/i
const ENGINE_RATE_LIMIT_RE = /rate.?limit|usage limit|quota|too many requests|overloaded|over capacity|credit balance is too low/i
const ENGINE_AUTH_RE = /not (?:logged in|authenticated|signed in)|(?<![\w./\\-])(?:sign|log)[ -]?in(?![\w/\\-]|\.\w)|\brun \/login(?![\w/\\-]|\.\w)|unauthori[sz]ed|forbidden|invalid (?:api )?key|authentication failed/i
const ENGINE_STARTUP_RE = /\bbwrap:\s*execvp\b|\bspawn(?: [^\n]+)? (?:ENOENT|EACCES)\b/i
const ENGINE_TRANSPORT_RE = /ECONN(?:RESET|REFUSED)|EPIPE|socket hang up|network|connection (?:closed|lost|terminated|timed out)|transport|process (?:exited|terminated)|failed to (?:spawn|write)/i
function startupFailureLine(diagnostic: string): string | undefined {
return diagnostic.split('\n').find((line) => ENGINE_STARTUP_RE.test(line))
}
export function classifyEngineFailure(diagnostic: string, hadResume = false): EngineFailureKind {
// A local executable path can itself contain words such as "quota" or "token".
if (ENGINE_STARTUP_RE.test(diagnostic)) return 'startup'
if (hadResume && RESUME_NOT_FOUND_RE.test(diagnostic)) return 'resume-not-found'
if (ENGINE_CONTEXT_OVERFLOW_RE.test(diagnostic)) return 'context-overflow'
if (ENGINE_RATE_LIMIT_RE.test(diagnostic)) return 'rate-limit'
if (ENGINE_AUTH_RE.test(diagnostic)) return 'authentication'
if (ENGINE_TRANSPORT_RE.test(diagnostic)) return 'transport'
return 'unknown'
}
/** Extract diagnostic prose without mistaking a model-authored stream event for
* an engine error. Failed result/error fields are retained; ordinary JSON event
* structure and successful assistant text are discarded. */
export function engineDiagnosticText(raw: string): string {
const out: string[] = []
for (const line of raw.split('\n')) {
const trimmed = line.trim()
if (!trimmed.startsWith('{')) { out.push(line); continue }
let event: { is_error?: unknown; result?: unknown; error?: unknown }
try { event = JSON.parse(trimmed) } catch { continue }
if (event.is_error === true && typeof event.result === 'string') out.push(event.result)
if (typeof event.error === 'string') out.push(event.error)
else if (event.error && typeof event.error === 'object') {
const message = (event.error as { message?: unknown }).message
if (typeof message === 'string') out.push(message)
}
}
return out.join('\n').trim().slice(0, MAX_FAILURE_CHARS)
}
/** Add a structured classification to adapters that still return the legacy
* string field. Adapter-provided classifications win over the generic fallback. */
export function engineFailureOf(result: EngineRunResult, hadResume = false): EngineFailure | null {
if (result.failure) return result.failure
if (!result.error) return null
return {
kind: classifyEngineFailure(result.error, hadResume),
message: result.error,
diagnostic: result.error,
}
}
/** Normalize a run at the adapter boundary. Keeping this next to the shared
* classifier gives every adapter the same vocabulary while still allowing a
* protocol-aware adapter to provide a more precise failure first. */
function classifyEngineResult(result: EngineRunResult, hadResume = false): EngineRunResult {
const failure = engineFailureOf(result, hadResume)
if (failure && !result.failure) result.failure = failure
return result
}
export interface EngineRunResult {
exitCode: number
/** Concise operator-facing compatibility field. New control flow must use
* `failure.kind`, never parse this presentation string. */
error?: string
failure?: EngineFailure
/** The engine session id parsed from this run's stream-json output, to be
* fed back as `resumeSessionId` on the next wake. Null if the engine emits
* no session id (e.g. Codex, or a non-stream-json flag override). */
sessionId?: string | null
/** Token usage from the turn's `result` event, for cache-aware cost. */
usage?: EngineUsage
/** The actual model id the engine used this turn (parsed from its events), so
* cost is priced on the REAL model rather than a fallback guess. */
model?: string | null
}
/** A LOCAL small-brain (cerebellum) completion: feed a self-contained prompt,
* get raw text back. Used for inbox triage — judgment runs on the operator's
* OWN cheap local model (Claude Haiku), never the cloud, never the big brain. */
export interface EngineClassifyArgs {
/** A NEUTRAL cwd with no persona CLAUDE.md / skills / MCP, so triage is a
* fast, clean, tool-free one-shot. */
cwd: string
/** The full triage prompt (instructions + input). */
prompt: string
env: NodeJS.ProcessEnv
/** Small/fast model to run on (Claude: 'haiku'). */
model?: string | null
onLog?: (line: string) => void
signal: AbortSignal
}
export interface EngineClassifyResult {
text: string
error?: string
/** Token usage for this triage call (Claude json output). Undefined when the
* engine emits none (e.g. codex / text-only output). */
usage?: EngineUsage
/** The model id the engine actually ran, when its output reports one. */
model?: string | null
}
/** A `doctor` liveness probe for ONE brain tier of an engine. Doctor has no
* agent/DB context, so its small tier checks only the computer-level fallback,
* not a member-specific fastModel pin. */
export interface EngineProbeArgs {
/** 'big' → engine default model; 'small' → computer-level cheap/fast
* fallback. Member-specific pins are validated only during real triage. */
tier: 'big' | 'small'
/** Neutral temp cwd (no persona). */
cwd: string
env: NodeJS.ProcessEnv
signal: AbortSignal
}
/** Args to a WAKE-PATH probe: validates the SPECIFIC protocol path the real
* wake would use on this machine (the app-server JSON-RPC handshake for codex,
* the persistent-session flag set for claude) — orthogonal to `probe()`, which
* only covers "binary runs + auth ok" via the one-shot subcommand. Same
* one-shot spawn discipline (neutral cwd, AbortSignal-driven timeout). */
export interface EngineWakeProbeArgs {
/** Neutral temp cwd (no persona). Adapters that need a git repo (codex) may
* initialize one here themselves — the caller is responsible for cleanup. */
cwd: string
env: NodeJS.ProcessEnv
signal: AbortSignal
}
export interface EngineWakeProbeResult {
ok: boolean
/** Concise detail on failure; empty on success. */
detail: string
/** Set when this machine WON'T use the distinct wake path (e.g. a
* custom-args override / opt-out env / Windows for codex) — the wake will
* collapse to the same one-shot path `probe()` already covers, so a wake
* probe would be redundant. Doctor hides the line in that case. */
skipped?: boolean
}
/** One LLM round-trip the engine just made — fired by ClaudeSession /
* CodexSession (and the one-shot adapter.run paths) on every assistant /
* turn-completed event. This is the per-HOP granularity the daemon needs to
* build a trajectory ledger: one row per outbound model call, not just one
* row per turn total.
*
* `usage` is the engine's raw usage shape so this module stays standalone
* (no pricing import); the daemon maps it to the cost ledger. */
export interface EngineHopReport {
/** Model id the engine just hit for this hop (e.g. claude-sonnet-4-6,
* gpt-5.5). The model on this hop's own message — NOT the session default,
* since native auto-compaction etc. can switch models mid-turn. */
model: string
usage?: EngineUsage
/** Wall-clock ms since the engine emitted this hop's first event to the
* emission of its terminating event (so cache warming etc. are visible). */
latencyMs?: number
/** Optional ledger-enrichment hints — fed straight into `llm_calls.extras`
* via the daemon. These are the columns we want for "why was this hop
* expensive" without needing the prompt body. Each is optional because
* Codex's app-server doesn't surface them at this granularity (yet). */
hopIndex?: number // 1-based position within the current turn
toolUses?: number // tool_use entries in the assistant message
textChars?: number // total text length the model returned (chars, not tokens)
}
/** Args to start a PERSISTENT engine session (spawned ONCE per agent). */
export interface EngineSessionArgs {
home: string
env: NodeJS.ProcessEnv
model?: string | null
fastModel?: string | null
nativeFastMode?: boolean
/** Resume a prior session on the FIRST spawn / after a restart (Claude:
* `--resume <id>`). Within a live process the session continues on its own. */
resumeSessionId?: string | null
/** The agent's INVARIANT standing prompt (TEXT). Delivered to the engine ONCE at
* spawn via its native out-of-band channel — Claude: written to a file passed as
* `--append-system-prompt-file`; Codex: the app-server thread's
* `developerInstructions` — instead of being re-sent every turn, so the
* transcript stays small enough for native auto-compaction to keep up. Whether a
* session actually carried it is reported by EngineSession.carriesStandingPrompt. */
standingPrompt?: string | null
vision?: 'supported' | 'unsupported' | 'unknown'
onLog: (line: string) => void
/** Fire-and-forget per-hop trajectory report. Called once per assistant
* message (Claude) / per turn-completed event (Codex) with that hop's own
* model + usage breakdown. The daemon buffers these into batched llm_calls
* inserts upstream so the universal ledger sees BYOA trajectory at the same
* granularity it sees cloud trajectory. Omit to disable. */
onHopUsage?: (report: EngineHopReport) => void
}
/** A long-lived engine process for ONE agent. Spawned once; each wake feeds a
* turn via `send()` (a stream-json user message on stdin) and resolves when the
* engine finishes that turn (its `result` event) — so wakes 2..N skip the cold
* start (process boot + MCP init + CLAUDE.md/skills load) the one-shot `run()`
* pays every time. */
export interface EngineSession {
/** Feed ONE turn; resolves when the engine emits its turn `result`. The daemon
* serializes calls (one turn at a time). */
send(prompt: string, localImages?: readonly string[]): Promise<EngineRunResult>
/** Same-turn steering: inject a message into the RUNNING turn at the next safe
* stream-json boundary so the agent answers a direct ping mid-task, then
* continues. No-op if no turn is in flight. */
steer(text: string): void
/** Process is up and stdin is writable. */
readonly alive: boolean
/** The latest session id seen (to `--resume` if the process must be respawned). */
readonly sessionId: string | null
/** True when this session received the standing prompt out-of-band at spawn
* (Claude system-prompt file / Codex developerInstructions). When true the
* daemon sends ONLY the per-turn delta; when false it inlines the standing
* prompt each turn (a one-shot path, or delivery failed). */
readonly carriesStandingPrompt: boolean
/** Tear the process down (daemon shutdown / unrecoverable error). `force`
* skips any engine-specific graceful-exit delay when this daemon process is
* itself about to exit. */
stop(options?: { force?: boolean }): Promise<void>
}
export interface EngineAdapter {
readonly id: EngineId
/** Binary name probed on PATH (e.g. 'claude'). */
readonly bin: string
/** Lay out the agent's home so the engine reads persona/memory natively.
* Idempotent and non-destructive: never clobbers an existing memory file. */
seedHome(home: string, persona: EnginePersona): Promise<void>
/** Run one headless turn. Resolves with the process exit code. */
run(args: EngineRunArgs): Promise<EngineRunResult>
/** Start a PERSISTENT process. Returns null if this engine has no persistent
* mode here (or a custom-args override) — the daemon then falls back to one-shot
* `run()` per wake. The session reports via carriesStandingPrompt whether the
* standing prompt was delivered out-of-band. */
startSession?(args: EngineSessionArgs): EngineSession | null
/** Run a LOCAL small-brain triage completion, returning raw text. */
classify(args: EngineClassifyArgs): Promise<EngineClassifyResult>
/** `doctor` liveness probe for one brain tier (big/small). Same one-shot spawn
* as classify, with a trivial prompt — used to diagnose whether each brain is
* reachable + authed on this machine. */
probe(args: EngineProbeArgs): Promise<EngineClassifyResult>
/** WAKE-PATH probe: exercises the protocol the REAL wake uses on this machine
* (codex → app-server JSON-RPC; claude → persistent-session flags). Returns
* `{ skipped: true }` when the wake path collapses to `probe()`'s shape on
* this machine (override env, opt-out, Windows for codex), so the doctor can
* hide a redundant line. Never throws. */
probeWake(args: EngineWakeProbeArgs): Promise<EngineWakeProbeResult>
}
/** The trivial prompt a `doctor` probe sends — one token of real work. */
const DOCTOR_PROMPT = 'Connectivity check. Reply with exactly: OK'
type BinPathProbe = 'present' | 'absent' | 'error'
/** Probe a binary without conflating "not installed" with an inability to run
* the platform's PATH resolver at all. The distinction matters to the daemon's
* periodic refresh: a healthy scan that finds nothing should clear a stale
* inventory, while a missing/broken `which` or `where` should retain the last
* known-good result. */
async function probeBinOnPath(bin: string): Promise<BinPathProbe> {
return new Promise((resolve) => {
const probe = spawn(process.platform === 'win32' ? 'where' : 'which', [bin], { stdio: 'ignore' })
probe.on('error', () => resolve('error'))
probe.on('close', (code) => resolve(code === 0 ? 'present' : code === 1 ? 'absent' : 'error'))
})
}
/** True if a binary is resolvable on PATH. */
export async function binOnPath(bin: string): Promise<boolean> {
return (await probeBinOnPath(bin)) === 'present'
}
async function exists(p: string): Promise<boolean> {
try { await access(p); return true } catch { return false }
}
async function ensureAgentDirectory(path: string, recursive = false): Promise<void> {
try {
const info = await lstat(path)
if (!info.isDirectory() || info.isSymbolicLink()) {
throw new Error(`secure BYOA refuses non-directory or linked path: ${path}`)
}
return
} catch (err) {
if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
}
await mkdir(path, { recursive })
const created = await lstat(path)
if (!created.isDirectory() || created.isSymbolicLink()) {
throw new Error(`secure BYOA could not create a trusted directory: ${path}`)
}
}
/** Replace a daemon-owned file without following an attacker-planted final
* symlink. The random staging file and target share a verified parent, so the
* final rename swaps the directory entry itself rather than opening its target. */
async function atomicAgentWrite(path: string, data: string): Promise<void> {
const parent = dirname(path)
const staged = join(parent, `.cumora-${process.pid}-${randomUUID()}.tmp`)
await writeFile(staged, data, { encoding: 'utf8', mode: 0o600, flag: 'wx' })
try {
try { await rename(staged, path) }
catch (err) {
if (!IS_WIN || !['EEXIST', 'EPERM'].includes((err as NodeJS.ErrnoException).code ?? '')) throw err
await rm(path, { force: true })
await rename(staged, path)
}
} finally {
await rm(staged, { force: true }).catch(() => {})
}
}
function atomicAgentWriteSync(path: string, data: string): void {
const parent = dirname(path)
const staged = join(parent, `.cumora-${process.pid}-${randomUUID()}.tmp`)
writeFileSync(staged, data, { encoding: 'utf8', mode: 0o600, flag: 'wx' })
try {
try { renameSync(staged, path) }
catch (err) {
if (!IS_WIN || !['EEXIST', 'EPERM'].includes((err as NodeJS.ErrnoException).code ?? '')) throw err
rmSync(path, { force: true })
renameSync(staged, path)
}
} finally {
rmSync(staged, { force: true })
}
}
async function ensureCommonHome(home: string): Promise<void> {
await ensureAgentDirectory(home, true)
await ensureAgentDirectory(join(home, 'memory'))
await ensureAgentDirectory(join(home, 'notes'))
await ensureAgentDirectory(join(home, 'workspace'))
// Seed a memory index so "read memory/MEMORY.md to recall" always has a
// target, and the agent has a concrete place to append pointers. Only when
// absent — never clobber what the agent has written.
const memoryIndex = join(home, 'memory', 'MEMORY.md')
let seedMemoryIndex = false
try {
const info = await lstat(memoryIndex)
if (!info.isFile() || info.isSymbolicLink()) {
throw new Error(`secure BYOA refuses non-file or linked memory index: ${memoryIndex}`)
}
} catch (err) {
if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err
seedMemoryIndex = true
}
if (seedMemoryIndex) {
await atomicAgentWrite(
memoryIndex,
'# Memory index\n\n' +
'One line per durable fact, pointing at the file that holds it:\n' +
'`- [Title](file.md) — one-line hook`\n\n' +
'Write the fact itself in its own `memory/<topic>.md` file; keep this index short.\n',
)
}
}
/** Shared spawn helper: run `bin args…` in `home`, stream lines to onLog,
* abort on signal, resolve with the exit code. */
const MAX_FAILURE_LINES = 30
const MAX_FAILURE_CHARS = 4000
const ANSI_RE = /\x1B\[[0-?]*[ -/]*[@-~]/g
function cleanLine(line: string): string {
return line.replace(ANSI_RE, '').replace(/\r/g, '').trim()
}
function pushTail(lines: string[], line: string): void {
if (!line) return
lines.push(line)
if (lines.length > MAX_FAILURE_LINES) lines.shift()
}
/** Inspect a Claude assistant message's `content` array to count tool_use
* entries and total text length. Used by the hop ledger so the operator can
* see at a glance whether a hop's spend went into prose or tool routing —
* the two have very different optimization targets. Robust to a malformed
* payload: returns zeros, never throws. */
function countAssistantContent(content: unknown): { toolUses: number; textChars: number } {
if (!Array.isArray(content)) return { toolUses: 0, textChars: 0 }
let toolUses = 0, textChars = 0
for (const item of content) {
if (!item || typeof item !== 'object') continue
const it = item as { type?: unknown; text?: unknown }
if (it.type === 'tool_use') toolUses += 1
else if (it.type === 'text' && typeof it.text === 'string') textChars += it.text.length
}
return { toolUses, textChars }
}
/** Exported for tests: pure, and the only way to pin what an operator actually
* reads after every cap downstream has taken its bite. */
export function failurePreview(args: {
exitCode: number
signalName: NodeJS.Signals | null
stderr: string[]
stdout: string[]
}): string {
const parts: string[] = []
if (args.stderr.length > 0) parts.push(args.stderr.join('\n'))
if (args.stdout.length > 0) parts.push(args.stdout.join('\n'))
const detail = parts.join('\n').trim()
const prefix = args.signalName
? `process terminated by ${args.signalName}`
: `process exited with code ${args.exitCode}`
if (!detail) return prefix
// Everything downstream cuts from the END — this cap, then the daemon's own
// 900-character one — and two of the engines put the reason on the LAST line.
// Measured on the installed binaries, each given one flag it does not know:
// gemini 0.1.15 prints 2,819 characters of help with the cause at offset
// 2,765; qwen 0.0.14, 3,798 with the cause at 3,744. Both dump their entire
// --help to stderr. So the operator's notice was 900 characters of option
// documentation, truncated mid-word, with no reason anywhere in it.
//
// salientError() already leads with this line, for exactly this reason, but
// only the probe and handshake paths go through it — an ordinary turn lands
// here instead. Lead with the cause and keep the full output behind it.
const rejected = startupFailureLine(detail) ?? argvRejection(detail)
const body = rejected ? `${rejected}\n${detail}` : detail
return `${prefix}\n${body}`.slice(0, MAX_FAILURE_CHARS)
}
/** Write to an engine's stdin without letting a dead pipe crash the process.
*
* Every stdin write in this file was wrapped in a try/catch whose comment said
* the child's own error/close path would report the failure. That is not what
* happens. A failed pipe write — EPIPE, when the engine died or was killed
* mid-write — is delivered ASYNCHRONOUSLY as an 'error' event on the stdin
* stream (`afterWriteDispatched`, a tick later), so the try/catch has already
* returned and cannot catch it. With no listener on the stream, Node turns it
* into an uncaught exception. It surfaced as a flaky `write EPIPE` failure in
* PiAdapter.probeWake on CI, but every adapter had the same hole.
*
* A dead engine is ordinary: the operator quit the CLI, a turn was aborted,
* doctor tore its probe down. The child's own 'error'/'close' handlers already
* report it, so the stream error is noise — it just must not be UNHANDLED.
*
* Returns false when the write could not even be attempted, so callers that
* care can bail; the ones that don't already fall through to their close path. */
function writeStdin(child: ChildProcess, text: string, opts: { end?: boolean } = {}): boolean {
const stdin = child.stdin
if (!stdin) return false
// Attach once per stream — repeated writes must not stack listeners.
if (stdin.listenerCount('error') === 0) {
stdin.on('error', () => { /* reported by the child's own close/error path */ })
}
try {
stdin.write(text)
if (opts.end) stdin.end()
return true
} catch {
return false
}
}
function spawnEngine(
bin: string,
args: string[],
{ home, env, onLog, signal, onHopUsage }: EngineRunArgs,
spawnOpts: { shell?: boolean; stdinText?: string; onStdoutLine?: (line: string) => void } = {},
): Promise<EngineRunResult> {
return new Promise((resolve, reject) => {
const child = spawnEngineChild(bin, args, {
cwd: home, env,
stdio: [spawnOpts.stdinText != null ? 'pipe' : 'ignore', 'pipe', 'pipe'],
shell: spawnOpts.shell ?? false,
})
if (spawnOpts.stdinText != null) {
writeStdin(child, spawnOpts.stdinText, { end: true })
}
// Retain the platform tree-termination promise. A listener registered after
// abort would never fire, so bindAbortTermination also closes that race.
const abort = bindAbortTermination(child, signal)
const stderrTail: string[] = []
const stdoutTail: string[] = []
let sessionId: string | null = null
let usage: EngineUsage | undefined
let model: string | null = null
// Per-hop timing for the one-shot path. Mirrors ClaudeSession's
// hopStartedAt — set on the first event of a hop, cleared once we've
// emitted the hop, so latency_ms reflects actual time-on-the-wire.
let hopStartedAt: number | null = null
let hopIndex = 0
// A pipe read chops stdout at an arbitrary byte offset (~8KB on macOS, up to
// 64KB on Linux), so a long stream-json event — a Write/Edit tool_use carrying
// file content, or a big final `result` — arrives split across two 'data'
// events. Splitting each chunk on its own handed JSON.parse two halves, both
// of which throw and are swallowed by the catch below: the hop never reached
// the ledger and the turn's authoritative usage/model/session id were lost,
// silently. Carry the trailing partial line into the next chunk, exactly like
// ClaudeSession.onStdout already does for the persistent path. StringDecoder
// does the same job one level down, holding back a multi-byte character split
// across the boundary instead of emitting U+FFFD into the JSON.
const decoder: Record<'stdout' | 'stderr', StringDecoder> =
{ stdout: new StringDecoder('utf8'), stderr: new StringDecoder('utf8') }
const carry: Record<'stdout' | 'stderr', string> = { stdout: '', stderr: '' }
// `buf === null` means end-of-stream: flush whatever is held back, since the
// engine's last line often has no trailing newline.
const pump = (stream: 'stdout' | 'stderr', buf: Buffer | null): void => {
const text = buf === null ? decoder[stream].end() : decoder[stream].write(buf)
const lines = (carry[stream] + text).split('\n')
carry[stream] = buf === null ? '' : (lines.pop() ?? '')
for (const line of lines) {
const cleaned = cleanLine(line)
if (!cleaned) continue
pushTail(stream === 'stderr' ? stderrTail : stdoutTail, cleaned)
// Sniff the engine's session id (to `--resume` next wake), the final
// `result` event's usage (cache-aware cost), and the actual model id
// (real pricing). Cheap: only parse stdout JSON objects carrying one.
if (stream === 'stdout' && cleaned.startsWith('{') && (cleaned.includes('"session_id"') || cleaned.includes('"sessionID"') || cleaned.includes('"usage"') || cleaned.includes('"model"'))) {
try {
const obj = JSON.parse(cleaned) as { session_id?: unknown; sessionID?: unknown; type?: unknown; usage?: EngineUsage; model?: unknown; message?: { model?: unknown; usage?: EngineUsage; content?: unknown } }
const sniffedSessionId = typeof obj.session_id === 'string' ? obj.session_id : obj.sessionID
if (typeof sniffedSessionId === 'string' && sniffedSessionId) sessionId = sniffedSessionId
// The terminal `result` event carries the authoritative turn total.
if (obj.type === 'result' && obj.usage && typeof obj.usage === 'object') usage = obj.usage
// assistant events carry message.model; some events carry top-level model.
const m = typeof obj.message?.model === 'string' ? obj.message.model : (typeof obj.model === 'string' ? obj.model : null)
if (m) model = m
// Per-hop trajectory mirror of ClaudeSession.onStdout. Same shape,
// same purpose: one row per outbound model call so even the
// one-shot path (no persistent session) lands in the universal
// ledger at the right granularity.
if (obj.type === 'assistant' && obj.message?.usage && m && onHopUsage) {
const startedAt = hopStartedAt
hopStartedAt = null
hopIndex += 1
const { toolUses, textChars } = countAssistantContent(obj.message.content)
try { onHopUsage({ model: m, usage: obj.message.usage, latencyMs: startedAt != null ? Date.now() - startedAt : undefined, hopIndex, toolUses, textChars }) }
catch { /* never break the run on a ledger error */ }
} else if (hopStartedAt == null && (obj.type === 'assistant' || obj.type === 'user' || obj.type === 'system')) {
hopStartedAt = Date.now()
}
if (obj.type === 'result') { hopStartedAt = null; hopIndex = 0 }
} catch { /* partial / non-json line — ignore */ }
}
if (stream === 'stdout') spawnOpts.onStdoutLine?.(cleaned)
onLog(cleaned)
}
}
let settled = false
child.stdout?.on('data', (buf: Buffer) => pump('stdout', buf))
child.stderr?.on('data', (buf: Buffer) => pump('stderr', buf))
child.on('error', (err) => {
if (settled) return
settled = true
abort.dispose()
void abort.wait().then(() => reject(err))
})
const settle = async (code: number | null, signalName: NodeJS.Signals | null): Promise<void> => {
if (settled) return
settled = true
abort.dispose()
await abort.wait()
const exitCode = code ?? (signalName ? 128 : 1)
resolve({
exitCode,
error: exitCode === 0 ? undefined : failurePreview({ exitCode, signalName, stderr: stderrTail, stdout: stdoutTail }),
sessionId,
usage,
model,
})
}
// Normal end: wait for 'close', so the last of stdout is parsed. Flush the
// held-back tail BEFORE resolving: the terminating `result` event is
// usually the last line, and it carries the turn's usage.
child.on('close', (code, signalName) => {
if (!settled) { pump('stdout', null); pump('stderr', null) }
void settle(code, signalName)
})
// Torn-down end: 'close' waits for every inherited stdio pipe to reach EOF,
// and the engine's OWN children (Bash tool commands) hold those pipes — a
// grandchild that outlives the kill keeps them open, so 'close' may never
// fire at all. Once we've aborted, the turn is being discarded and its
// remaining output is moot, so settle on 'exit' instead. Without this the
// daemon's shutdown drain waits forever on a turn it already killed, and
// `busy` plus the big-brain slot are never released.
child.on('exit', (code, signalName) => { if (signal.aborted) void settle(code, signalName) })
})
}
/** Like spawnEngine, but for a one-shot completion: collect ALL stdout (the
* model's text) and resolve with it. No session sniffing, no run wiring. */
function spawnCapture(
bin: string,
args: string[],
{ cwd, env, signal, onLog, shell, stdinText }: { cwd: string; env: NodeJS.ProcessEnv; signal: AbortSignal; onLog?: (line: string) => void; shell?: boolean; stdinText?: string },
): Promise<EngineClassifyResult> {
return new Promise((resolve) => {
const child = spawnEngineChild(bin, args, {
cwd, env,
stdio: [stdinText != null ? 'pipe' : 'ignore', 'pipe', 'pipe'],
shell: shell ?? false,
})
if (stdinText != null) {
writeStdin(child, stdinText, { end: true })
}
const abort = bindAbortTermination(child, signal)
let stdout = ''
const stderrTail: string[] = []
let settled = false
child.stdout?.on('data', (buf: Buffer) => { stdout += buf.toString('utf8'); onLog?.(cleanLine(buf.toString('utf8'))) })
child.stderr?.on('data', (buf: Buffer) => { for (const l of buf.toString('utf8').split('\n')) pushTail(stderrTail, cleanLine(l)) })
child.on('error', (err) => {
if (settled) return
settled = true
abort.dispose()
void abort.wait().then(() => {
resolve({ text: '', error: err instanceof Error ? err.message : String(err) })
})
})
child.on('close', (code, signalName) => {
if (settled) return
settled = true
abort.dispose()
void abort.wait().then(() => {
const exitCode = code ?? (signalName ? 128 : 1)
resolve({
text: stdout.replace(ANSI_RE, '').trim(),
error: exitCode === 0 ? undefined : failurePreview({ exitCode, signalName, stderr: stderrTail, stdout: [] }),
})
})
})
})
}
/** The computer-level small/fast model used by standalone probes. */
function triageModel(fallback: string): string {
return process.env.CUMORA_TRIAGE_MODEL?.trim() || fallback
}
function extraArgs(envVar: string): string[] {
const raw = process.env[envVar]
return raw ? raw.split(/\s+/).filter(Boolean) : []
}
/** Whole-argv overrides are intentionally an unsafe escape hatch: Cumora
* cannot prove that an opaque flag set preserves its sandbox. Ignore them in
* the secure default mode; the daemon logs the opt-in requirement at startup. */
function unsafeEngineArgs(envVar: string): string[] {
return allowUnsandboxedByoa() ? extraArgs(envVar) : []
}
const PERSONA_HEADER = (
p: EnginePersona,
opts: { personaFile?: string; skillsDir?: string } = {},
): string => {
const personaFile = opts.personaFile ?? 'CLAUDE.md'
const skillsDir = opts.skillsDir ?? '.claude/skills/'
return `# ${p.name}${p.role ? ` — ${p.role}` : ''}\n\n` +
`You are **${p.name}**, a member of a team that collaborates in Cumora (a team chat).\n` +
(p.systemPrompt?.trim() ? `\n## Your style\n${p.systemPrompt.trim()}\n\n` : '\n') +
`This directory is your private home and your working directory — it persists\n` +
`across wakes and is yours alone. Its layout:\n` +
`- \`${personaFile}\` (this file) — always loaded each wake; keep it short.\n` +
`- \`memory/\` — your durable memory. There is NO hidden memory store: to remember\n` +
` something across wakes you MUST write it to a file here (e.g. \`memory/<topic>.md\`)\n` +
` and add a one-line pointer in \`memory/MEMORY.md\`. Saying "I'll remember" without\n` +
` writing a file means you will NOT remember. At the start of each wake, read\n` +
` \`memory/MEMORY.md\` (and the files it points to) to recall what you know.\n` +
`- \`notes/\` — scratch notes and drafts.\n` +
`- \`${skillsDir}\` — your skills.\n` +
`- \`workspace/\` — **put all project files and scratch here**: git clones, builds,\n` +
` downloads, temp files. Always \`cd workspace\` (or use \`workspace/…\` paths) for\n` +
` that work — do NOT clutter your home root with project files.\n\n` +
`## Privacy boundary — STRICT\n` +
`You run on a machine that belongs to your operator. Everything OUTSIDE your home\n` +
`directory (other projects, \`~/.ssh\`, credentials, browser data, personal files)\n` +
`is private and not yours to touch.\n` +
`- Stay inside your home directory. Do not read, open, list, or search files\n` +
` outside it unless the operator explicitly asks you to in this Cumora workspace.\n` +
`- NEVER paste, quote, summarize, or send the contents — or even the paths — of\n` +
` any file outside your home into Cumora (replies, DMs, docs, kanban). Other\n` +
` people see what you post there.\n` +
`- If a task seems to need something outside your home, ask in Cumora first;\n` +
` don't go fetch it on your own.\n\n` +
`When you act in Cumora, use the \`cumora\` interface. Secure Claude and Codex\n` +
`expose it as the structured \`mcp__cumora__cli\` tool (pass command words in its\n` +
`\`argv\` array); compatibility engines expose the command-line tool on PATH.\n` +
`Key commands:\n` +
`- \`cumora inbox\` — unread messages across your conversations\n` +
`- \`cumora messages <conversationId> --tail 30\` — read a conversation\n` +
`- \`cumora reply <conversationId> '<text>'\` — post a message (SINGLE quotes;\n` +
` for anything with backticks, code, $, quotes, or newlines, write it to a file\n` +
` and use \`cumora reply <conversationId> --file <path>\` in command-line mode.\n` +
` In the structured MCP tool, put the complete text directly in one argv item;\n` +
` local \`--file\` and \`--stdin\` flags are intentionally unavailable.)\n` +
`- \`cumora contacts [<query>]\` — your teammates + humans, each with their role/function\n` +
` (search by name or role, e.g. \`cumora contacts designer\`). Use it when someone asks\n` +
` about a person or role you don't already know.\n` +
`- \`cumora whoami\` — your identity\n\n` +
`Be a real teammate with your own voice — not a generic assistant.\n`
}
/** A persistent Claude Code process for ONE agent (see EngineSession). Spawned in
* stream-json I/O mode (`-p --input-format stream-json --output-format stream-json`):
* the process stays alive reading newline-delimited user messages from stdin and
* exits only when stdin closes. Each `send()` writes one user message and resolves
* on that turn's `result` event — so wakes 2..N skip the cold start the one-shot
* `run()` pays each time. The daemon calls `send()` serially (one turn at a time). */
class ClaudeSession implements EngineSession {
private readonly child: ChildProcess
private readonly onLog: (line: string) => void
private readonly onHopUsage?: (r: EngineHopReport) => void
/** True only until the first result from a process started with --resume.
* Later turns are ordinary continuation and must not treat session wording in
* model/tool output as a failed resume handshake. */
private resumePending: boolean
private outBuf = ''
private sid: string | null
private curModel: string | null = null
/** Wall-clock when the CURRENT hop started receiving its first event.
* Reset to null after a hop is reported; set the moment the next assistant
* event arrives. The wake's pending Promise drives turn-level latency. */
private hopStartedAt: number | null = null
/** 1-based hop counter for the current turn — incremented each time we emit
* an onHopUsage report, reset to 0 at the `result` event. The ledger uses
* this to answer "of the N hops in turn X, which one burned the tokens?"
* without having to JOIN siblings by created_at. */
private hopIndex = 0
private exited = false
private exitCode = 0
private pending: { resolve: (r: EngineRunResult) => void; stderr: string[]; stdout: string[] } | null = null
private stderrTail: string[] = []
private stdoutTail: string[] = []
private pendingTimer: ReturnType<typeof setTimeout> | null = null
private steerQueue: string[] = []
readonly carriesStandingPrompt: boolean
constructor(bin: string, args: string[], opts: EngineSessionArgs, carriesStandingPrompt: boolean, private readonly providerChanged: () => boolean) {
this.onLog = opts.onLog
this.onHopUsage = opts.onHopUsage
this.resumePending = !!opts.resumeSessionId
this.sid = opts.resumeSessionId ?? null
this.carriesStandingPrompt = carriesStandingPrompt
// Cross-platform spawn: on Windows resolve the real claude(.cmd) + shell so a
// .cmd shim runs (Node can't spawn it with shell:false). The prompt already
// travels via stdin (stream-json), so no arg-quoting concerns here.
const { command, shell } = resolveSpawn(bin)
this.child = spawnEngineChild(command, args, { cwd: opts.home, env: opts.env, stdio: ['pipe', 'pipe', 'pipe'], shell })
this.child.stdout?.on('data', (b: Buffer) => this.onStdout(b))
this.child.stderr?.on('data', (b: Buffer) => this.onStderr(b))
this.child.on('error', (err) => this.die(1, err.message))
this.child.on('close', (code, signalName) =>
this.die(code ?? (signalName ? 128 : 1), signalName ? `terminated by ${signalName}` : `exited with code ${code}`))
}
get alive(): boolean {
if (!this.pending && this.providerChanged()) {
void this.stop({ force: true })
return false
}
return !this.exited && this.child.stdin?.writable === true
}
get sessionId(): string | null { return this.sid }
send(prompt: string): Promise<EngineRunResult> {
if (this.pending) {
return Promise.resolve(classifyEngineResult({ exitCode: 1, error: 'engine session busy — a turn is already in flight', sessionId: this.sid }, this.resumePending))
}
if (!this.alive) {
const exitCode = this.exitCode || 1
const detail = failurePreview({ exitCode, signalName: null, stderr: this.stderrTail, stdout: this.stdoutTail })
return Promise.resolve(classifyEngineResult({ exitCode, error: detail || 'engine session is not alive (process gone)', sessionId: this.sid }, this.resumePending))
}
return new Promise<EngineRunResult>((resolve) => {
this.pending = { resolve, stderr: [], stdout: [] }
// Opt-in runaway backstop only (CUMORA_TURN_TIMEOUT_MS); OFF by default so a
// legit long task (e.g. a multi-hour Bash) is never killed mid-work. When set,
// abort + respawn past the cap.
if (TURN_TIMEOUT_MS > 0) {
this.pendingTimer = setTimeout(() => {
this.settle({ exitCode: 124, error: `engine turn exceeded CUMORA_TURN_TIMEOUT_MS (${Math.round(TURN_TIMEOUT_MS / 1000)}s) — aborted; session will respawn`, sessionId: this.sid })
this.stop() // kill the runaway process; the daemon respawns (--resume) on the next wake
}, TURN_TIMEOUT_MS)
this.pendingTimer.unref?.()
}
const msg = JSON.stringify({ type: 'user', message: { role: 'user', content: [{ type: 'text', text: stripLoneSurrogates(prompt) }] } }) + '\n'
if (!writeStdin(this.child, msg)) {
this.settle({ exitCode: 1, error: 'failed to write turn to engine (stdin closed)', sessionId: this.sid })
}
})
}
stop(options: { force?: boolean } = {}): Promise<void> {
this.exited = true
try { this.child.stdin?.end() } catch { /* ignore */ }
return terminateEngineTree(this.child, options.force)
}
/** Same-turn STEERING: queue a message to inject into the
* RUNNING turn at the next safe stream-json boundary, so the agent can answer a
* direct ping mid-task — in the SAME session (full task context) — then continue.
* No-op when no turn is in flight (the daemon's normal turn handles it instead). */
steer(text: string): void {
if (this.pending && this.alive && text.trim()) this.steerQueue.push(text)
}
private flushSteer(): void {
if (!this.pending || !this.alive) return
while (this.steerQueue.length > 0) {
const text = this.steerQueue.shift()!
if (!writeStdin(this.child, JSON.stringify({ type: 'user', message: { role: 'user', content: [{ type: 'text', text: stripLoneSurrogates(text) }] } }) + '\n')) break
}
}
private onStdout(buf: Buffer): void {
this.outBuf += buf.toString('utf8')
let nl: number
while ((nl = this.outBuf.indexOf('\n')) >= 0) {
const line = cleanLine(this.outBuf.slice(0, nl))
this.outBuf = this.outBuf.slice(nl + 1)
if (!line) continue
pushTail(this.stdoutTail, line)
if (this.pending) pushTail(this.pending.stdout, line)
this.onLog(line)
if (!line.startsWith('{')) continue
let ev: { type?: unknown; session_id?: unknown; is_error?: unknown; subtype?: unknown; status?: unknown; result?: unknown; error?: unknown; usage?: EngineUsage; model?: unknown; message?: { model?: unknown; usage?: EngineUsage; content?: unknown } }
try { ev = JSON.parse(line) } catch { continue }
if (typeof ev.session_id === 'string' && ev.session_id) this.sid = ev.session_id
// Capture the real model id (assistant events carry message.model) for pricing.
const evModel = typeof ev.message?.model === 'string' ? ev.message.model : (typeof ev.model === 'string' ? ev.model : null)
if (evModel) this.curModel = evModel
// Per-hop trajectory: every `{type:'assistant', message:{model, usage}}` is
// ONE outbound model call this turn. Fire onHopUsage so the daemon can
// ledger it (see EngineHopReport). The terminating `type:'result'` event
// carries the SUM across hops (already used for the turn's final cost), so
// we deliberately do NOT also emit it as a hop — that'd double-count.
if (ev.type === 'assistant' && ev.message?.usage && evModel) {
const startedAt = this.hopStartedAt
this.hopStartedAt = null
this.hopIndex += 1
// Inspect the assistant's content array to count tool calls + total
// text length. These two numbers explain a lot of why a hop is
// expensive — a 5000-char prose reply is a different optimization
// target from a single tool_use that triggered 6 follow-up hops.
const { toolUses, textChars } = countAssistantContent(ev.message.content)
try {
this.onHopUsage?.({
model: evModel,
usage: ev.message.usage,
latencyMs: startedAt != null ? Date.now() - startedAt : undefined,
hopIndex: this.hopIndex,
toolUses,
textChars,
})
} catch { /* ledger best-effort, never break the stream */ }
} else if (this.hopStartedAt == null && (ev.type === 'assistant' || ev.type === 'user' || ev.type === 'system')) {
// First event of a new hop (post-`result` or fresh turn). Start the timer.
this.hopStartedAt = Date.now()
}
// Observe Claude's NATIVE auto-compaction (telemetry only) — confirms it
// ran without our intervention; the small per-turn delta keeps it able to.
if (ev.subtype === 'status' && ev.status === 'compacting') this.onLog('[claude] native context compaction started')
else if (ev.subtype === 'compact_boundary') this.onLog('[claude] native context compaction finished')
if (ev.type === 'result') {
this.hopStartedAt = null // turn boundary — drop any half-set hop timer
this.hopIndex = 0 // reset the per-turn hop counter
this.steerQueue = [] // turn ending — any unflushed steer falls to the daemon's coalesced rerun
const isErr = ev.is_error === true
const diagnostic = isErr
? engineDiagnosticText([
...(this.pending?.stderr ?? []),
...(this.pending?.stdout ?? []),
].join('\n'))
: ''
const message = diagnostic || `engine turn error${typeof ev.subtype === 'string' ? ` (${ev.subtype})` : ''}: see log`
const wasResume = this.resumePending
this.resumePending = false
this.settle({
exitCode: isErr ? 1 : 0,
error: isErr ? message : undefined,
failure: isErr ? {
kind: classifyEngineFailure(diagnostic || message, wasResume),
message,
diagnostic: diagnostic || message,
} : undefined,
sessionId: this.sid,
usage: ev.usage && typeof ev.usage === 'object' ? ev.usage : undefined,
model: this.curModel,
})
} else if (ev.type === 'user') {
// A tool_result echo is a SAFE stream-json boundary (not mid signed-thinking
// block) → inject any queued steering into THIS running turn so the agent can
// answer a direct ping mid-task, then continue — same-turn steering
// gated on stream-json boundaries.
this.flushSteer()
}
}
}
private onStderr(buf: Buffer): void {
for (const raw of buf.toString('utf8').split('\n')) {
const line = cleanLine(raw)
if (!line) continue
pushTail(this.stderrTail, line)
if (this.pending) pushTail(this.pending.stderr, line)
this.onLog(line)
}
}
private settle(r: EngineRunResult): void {
if (this.pendingTimer) { clearTimeout(this.pendingTimer); this.pendingTimer = null }
const p = this.pending
this.pending = null
if (p) p.resolve(classifyEngineResult(r, this.resumePending))
}
/** Process died (error/close). Mark dead and fail any in-flight turn. */
private die(code: number, why: string): void {
const alreadyDown = this.exited
this.exited = true
this.exitCode = code
// An IDLE death used to be SILENT: with no pending turn there was nothing to
// settle, so a session could vanish (OOM kill, provider-side hangup, macOS
// app-nap, a stray SIGTERM) and the only trace was a later "respawned" line
// at the NEXT wake — a whole fleet's sessions once disappeared with zero
// evidence of why. Always log the death and its cause; skip when `exited`
// was already set (an intentional stop(), or the error+close double-fire).
if (!alreadyDown) {
this.onLog(`[session] engine process died ${this.pending ? 'MID-TURN' : 'while idle'}: ${why} (exit ${code})`)
}
if (this.pending) {
const detail = failurePreview({ exitCode: code, signalName: null, stderr: this.pending.stderr, stdout: this.pending.stdout })
this.settle({ exitCode: code, error: detail || why, sessionId: this.sid })
}
}
}
const TOOL_ENV_ALLOWLIST = new Set([
'PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'TMPDIR', 'TMP', 'TEMP',
'LANG', 'LANGUAGE', 'TERM', 'COLORTERM', 'NO_COLOR',
'CUMORA_AGENT_IPC_DIR', 'CUMORA_AGENT_ID',
'SYSTEMROOT', 'COMSPEC', 'PATHEXT', 'WINDIR',
])
function claudeSecureSettings(agentHome: string, env: NodeJS.ProcessEnv, nativeFastMode = false) {
const deniedEnv = Object.keys(env)
.filter((name) => !TOOL_ENV_ALLOWLIST.has(name.toUpperCase()) && !name.toUpperCase().startsWith('LC_'))
.sort()
.map((name) => ({ name, mode: 'deny' }))
// Claude's command sandbox is write-restricted but read-permissive by
// default. Deny user/application data roots, then carve back only this
// agent's workspace and executable lookup directories. System runtime paths
// (/bin, /usr, /lib, /System) stay readable so the shim can launch.
const denyRead = process.platform === 'darwin'
? ['~/', '/Users', '/Volumes']
: ['~/', '/home', '/root', '/mnt', '/media', '/run', '/proc', '/sys', '/srv', '/var/lib', '/var/log']
const pathDirs = (env.PATH ?? '')
.split(PATH_DELIMITER)
.filter(Boolean)
pathDirs.push(dirname(process.execPath))
const allowRead = [...new Set([agentHome, ...pathDirs])]
// Claude permission rules use // for absolute paths; / is source-relative.
const fileScope = `/${agentHome.replaceAll('\\', '/').replace(/\/$/, '')}`
return {
...readClaudeUserSettings(env).turnSettings,
fastMode: nativeFastMode,
permissions: {
defaultMode: 'dontAsk',
// Restricted mode confines file tools to the working directory. Keep the
// permission rules scoped too, so this JSON remains fail-closed if a
// future Claude release changes a restricted-mode default.
allow: [`Read(${fileScope}/**)`, `Edit(${fileScope}/**)`, 'Bash', 'mcp__cumora__cli'],
// The MCP bridge runs as a trusted daemon helper outside the command
// sandbox. The model must never rewrite either helper executable.
deny: [`Read(${fileScope}/bin/**)`, `Edit(${fileScope}/bin/**)`, 'PowerShell', 'WebFetch', 'WebSearch'],
},
sandbox: {
enabled: true,
failIfUnavailable: true,
allowUnsandboxedCommands: false,
excludedCommands: [],
autoAllowBashIfSandboxed: true,
filesystem: {
denyRead,
allowRead,
},
network: { allowedDomains: [], strictAllowlist: true },
credentials: { envVars: deniedEnv },
},
}
}
function claudeSecureMcpConfig(env: NodeJS.ProcessEnv): string {
const mcpShim = env.CUMORA_AGENT_MCP_SHIM
if (!mcpShim) throw new Error('secure Cumora MCP bridge is not configured')
return JSON.stringify({
mcpServers: {
cumora: {
command: process.execPath,
args: [mcpShim],
env: {
CUMORA_AGENT_IPC_DIR: env.CUMORA_AGENT_IPC_DIR ?? '',
},
},
},
})
}
export function claudeSecureFlags(agentHome: string, env: NodeJS.ProcessEnv, nativeFastMode = false): string[] {
const settings = claudeSecureSettings(agentHome, env, nativeFastMode)
return [
'--restricted',
'--permission-mode', 'dontAsk',
'--tools', 'Read,Write,Edit,Glob,Grep,Bash,mcp__cumora__cli',
// Subprocess credential scrubbing requires an explicit CLI approval list.
'--allowedTools', ...settings.permissions.allow,
'--disallowedTools', 'PowerShell,WebFetch,WebSearch',
'--settings', JSON.stringify(settings),
'--mcp-config', claudeSecureMcpConfig(env),
'--strict-mcp-config',
]
}
/** Restricted Claude ignores ~/.claude/settings.json wholesale. Recover only
* the provider bootstrap variables its trusted core needs; claudeSecureSettings
* denies those names to every model-spawned subprocess. Compatibility mode
* keeps Claude's native settings loading and its already-explicit host risk. */
function claudeCoreEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
if (allowUnsandboxedByoa(env)) return { ...env }
if (readClaudeUserSettings(env).readFailure && !CLAUDE_CORE_ENV_KEYS.every(key => env[key] !== undefined)) {
throw new Error('Cannot read Claude provider settings; retry after its configuration has finished updating')
}
return withClaudeUserSettingsEnv(env)
}
/** Pick the small brain inside the local provider namespace. An explicit
* per-agent/computer pin wins; next use the provider's configured fast model.
* If a custom endpoint names no fast model, omit --model and let that endpoint
* choose instead of injecting Anthropic's `haiku` alias. Anthropic's OWN base
* URL is not a custom endpoint — Claude Code exports it into every child
* process, so keying on "the variable is set" dropped Haiku for first-party
* accounts. */
function claudeMainModel(env: NodeJS.ProcessEnv, requested?: string | null): string | null {
return modelIdOrNull(requested || env.ANTHROPIC_MODEL || readClaudeUserSettings(env).defaultModel)
}
function claudeFastModelArgs(env: NodeJS.ProcessEnv, requested?: string | null): string[] {
const model = requested?.trim()
|| env.CUMORA_TRIAGE_MODEL?.trim()
|| env.ANTHROPIC_DEFAULT_HAIKU_MODEL?.trim()
|| env.ANTHROPIC_SMALL_FAST_MODEL?.trim()
|| (isCustomAnthropicEndpoint(env.ANTHROPIC_BASE_URL) ? claudeMainModel(env) : null)
if (model) return ['--model', model]
return isCustomAnthropicEndpoint(env.ANTHROPIC_BASE_URL) ? [] : ['--model', 'haiku']
}
function claudeTurnEnv(env: NodeJS.ProcessEnv, fastModel?: string | null): NodeJS.ProcessEnv {
const core = claudeCoreEnv(env)
if (!allowUnsandboxedByoa(core)) {
for (const [key, value] of Object.entries(readClaudeUserSettings(env).turnEnv)) {
if (core[key] === undefined) core[key] = value
}
}
const turnEnv: NodeJS.ProcessEnv = {
...core,
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB: allowUnsandboxedByoa(core)
? core.CLAUDE_CODE_SUBPROCESS_ENV_SCRUB
: '1',
}
if (fastModel) {
turnEnv.ANTHROPIC_DEFAULT_HAIKU_MODEL = fastModel
turnEnv.ANTHROPIC_SMALL_FAST_MODEL = fastModel
}
return turnEnv
}
function claudeFastModeError(model: string | null | undefined, env: NodeJS.ProcessEnv, enabled: boolean): string | null {
if (!enabled) return null
let resolved = claudeMainModel(env, model)
if (/^opus(?:\[1m\])?$/i.test(resolved ?? '')) resolved = env.ANTHROPIC_DEFAULT_OPUS_MODEL || resolved
if (!supportsNativeFastMode('claude', resolved)) {
return 'Fast mode requires a supported Opus model; select one explicitly to avoid changing the selected model.'
}
if (env.CLAUDE_CODE_DISABLE_FAST_MODE === '1') return 'Fast mode is disabled by CLAUDE_CODE_DISABLE_FAST_MODE.'
return null
}
class ClaudeAdapter implements EngineAdapter {
readonly id = 'claude' as const
readonly bin = 'claude'
async classify(args: EngineClassifyArgs): Promise<EngineClassifyResult> {
// Plain headless completion on Claude Code's cheap fast model (Haiku for a
// first-party account, or the custom provider's configured/default model).
// NO tools, NO
// MCP (--strict-mcp-config, no --mcp-config = zero MCP init, the slowest
// part of a cold `claude` spawn), NO session, thinking off, neutral cwd (no
// persona CLAUDE.md). Just text in → JSON out, locally. Never the cloud.
// --output-format json wraps the reply in a result envelope that ALSO carries
// token usage (incl. cache_read/cache_creation) → we unwrap `.result` as the
// text and pass `.usage` up for the triage cost ledger.
const flags = unsafeEngineArgs('CUMORA_TRIAGE_ARGS')
const env = claudeCoreEnv(args.env)
const model = claudeFastModelArgs(env, args.model)
const { command, shell, wantsStdinPrompt } = resolveSpawn(this.bin)
const usingJson = flags.length === 0
// On Windows the .cmd shim runs via the shell, which can't carry the big
// multi-line prompt as an argv element → feed it via stdin (`claude -p` reads
// the prompt from stdin when no prompt arg is given). POSIX: prompt in argv as
// before (unchanged).
const base = flags.length
? [...flags, '-p']
: allowUnsandboxedByoa(env)
? ['-p', ...model, '--output-format', 'json', '--tools', '', '--strict-mcp-config']
: ['-p', ...model, '--output-format', 'json', '--restricted', '--tools', '', '--strict-mcp-config']
const argv = wantsStdinPrompt ? base : (flags.length ? [...base, args.prompt] : ['-p', args.prompt, ...base.slice(1)])
const res = await spawnCapture(command, argv, {
cwd: args.cwd,
env: { ...env, MAX_THINKING_TOKENS: '0', CLAUDE_CODE_DISABLE_FAST_MODE: '1' },
signal: args.signal,
onLog: args.onLog,
shell,
stdinText: wantsStdinPrompt ? args.prompt : undefined,
})
if (res.error || !usingJson) return res // failure, or a user flag override that isn't json
try {
const obj = JSON.parse(res.text) as { result?: unknown; usage?: EngineUsage }
return {
text: typeof obj.result === 'string' ? obj.result : res.text,
usage: obj.usage && typeof obj.usage === 'object' ? obj.usage : undefined,
}
} catch {
return res // not the envelope we expected — hand back raw text
}
}
probe(args: EngineProbeArgs): Promise<EngineClassifyResult> {
// Mirror classify's clean one-shot spawn, but pick the tier's model: 'small'
// → the resolved provider-local cerebellum; 'big' → omit --model so Claude
// uses its default main reasoning brain. One token in, "OK" out — proves the binary runs
// and that tier is authed/has quota, with NO tools/MCP/persona.
const env = claudeCoreEnv(args.env)
const main = claudeMainModel(env)
const model = args.tier === 'small' ? claudeFastModelArgs(env) : main ? ['--model', main] : []
const { command, shell, wantsStdinPrompt } = resolveSpawn(this.bin)
const base = allowUnsandboxedByoa(env)
? ['-p', ...model, '--output-format', 'text', '--tools', '', '--strict-mcp-config']
: ['-p', ...model, '--output-format', 'text', '--restricted', '--tools', '', '--strict-mcp-config']
const argv = wantsStdinPrompt ? base : ['-p', DOCTOR_PROMPT, ...base.slice(1)]
return spawnCapture(command, argv, {
cwd: args.cwd,
env: { ...env, MAX_THINKING_TOKENS: '0', CLAUDE_CODE_DISABLE_FAST_MODE: '1' },
signal: args.signal,
shell,
stdinText: wantsStdinPrompt ? DOCTOR_PROMPT : undefined,
})
}
async probeWake(args: EngineWakeProbeArgs): Promise<EngineWakeProbeResult> {
// Skipped when a CUMORA_CLAUDE_ARGS override is set — startSession() returns
// null then, so the wake collapses to run() / one-shot exec, which probe()
// already covers. The honest signal here is just "redundant".
if (unsafeEngineArgs('CUMORA_CLAUDE_ARGS').length) {
return { ok: true, detail: '', skipped: true }
}
// The realistic break on the persistent-session path is `--append-system-prompt-file`
// changing name/spelling across Claude CLI versions: when it disappears, every
// wake fails before the first token. We don't need to drive a full stream-json
// roundtrip to catch that — running `-p` WITH the flag pointed at an empty file
// and asking for "OK" exercises flag acceptance against the same auth path. If
// the flag is rejected the CLI exits non-zero with a parse error; if it's
// accepted we get the one-token reply.
const promptFile = join(args.cwd, '.cumora-doctor-standing.md')
try { await writeFile(promptFile, '', 'utf8') }
catch (err) { return { ok: false, detail: `could not write standing-prompt probe file: ${err instanceof Error ? err.message : String(err)}` } }
const env = claudeCoreEnv(args.env)
const { command, shell, wantsStdinPrompt } = resolveSpawn(this.bin)
const main = claudeMainModel(env)
const model = main ? ['--model', main] : []
const base = allowUnsandboxedByoa(env)
? ['-p', ...model, '--output-format', 'text', '--append-system-prompt-file', promptFile, '--tools', '', '--strict-mcp-config']
: [
'-p', ...model, '--output-format', 'text', '--append-system-prompt-file', promptFile,
'--restricted', '--tools', '', '--strict-mcp-config',
]
const argv = wantsStdinPrompt ? base : ['-p', DOCTOR_PROMPT, ...base.slice(1)]
const r = await spawnCapture(command, argv, {
cwd: args.cwd,
env: { ...env, MAX_THINKING_TOKENS: '0', CLAUDE_CODE_DISABLE_FAST_MODE: '1' },
signal: args.signal,
shell,
stdinText: wantsStdinPrompt ? DOCTOR_PROMPT : undefined,
})
if (r.error || !r.text.trim()) {
return { ok: false, detail: salientError(`${r.error ?? ''}\n${r.text ?? ''}`) || 'no output' }
}
return { ok: true, detail: '' }
}
async seedHome(home: string, persona: EnginePersona): Promise<void> {
await ensureCommonHome(home)
await ensureAgentDirectory(join(home, '.claude'))
await ensureAgentDirectory(join(home, '.claude', 'skills'))
// Always (re)written from the DB's name/role/systemPrompt — this file is
// system-owned, not agent-editable, so it's safe to overwrite on every
// start()/restart (including the restart configMatches() triggers when
// the operator edits the agent's persona in Cumora).
await atomicAgentWrite(join(home, 'CLAUDE.md'), PERSONA_HEADER(persona))
// Legacy settings for unsandboxed compatibility mode. Restricted mode
// ignores project settings and receives its narrow inline policy instead.
if (allowUnsandboxedByoa()) {
const settings = join(home, '.claude', 'settings.json')
if (!(await exists(settings))) {
await atomicAgentWrite(settings, JSON.stringify({ permissions: { allow: ['Bash'] } }, null, 2))
}
}
}
run(args: EngineRunArgs): Promise<EngineRunResult> {
// -p: headless print mode. stream-json + verbose gives line-delimited
// events the daemon can log. Secure mode injects a fail-closed policy;
// the dangerous bypass remains only for explicit compatibility mode.
// Big-brain model → --model; small-brain → ANTHROPIC_SMALL_FAST_MODEL env.
const flags = unsafeEngineArgs('CUMORA_CLAUDE_ARGS')
const selectedModel = claudeMainModel(args.env, args.model)
const model = selectedModel ? ['--model', selectedModel] : []
const env = claudeTurnEnv(args.env, args.fastModel)
const fastMode = args.nativeFastMode ?? false
if (fastMode && flags.length) return Promise.resolve({ exitCode: 1, error: 'Fast mode requires removing the CUMORA_CLAUDE_ARGS override so Cumora can preserve the selected model and settings.' })
if (!fastMode) env.CLAUDE_CODE_DISABLE_FAST_MODE = '1'
const fastModeError = claudeFastModeError(args.model, env, fastMode)
if (fastModeError) return Promise.resolve({ exitCode: 1, error: fastModeError })
const speed = ['--settings', JSON.stringify({ fastMode })]
// Continuous context across wakes: resume the agent's prior session so it
// remembers the running task (its place in a counting relay, what it already
// said) instead of re-deriving from a frozen inbox snapshot each time.
const resume = args.resumeSessionId ? ['--resume', args.resumeSessionId] : []
const { command, shell, wantsStdinPrompt } = resolveSpawn(this.bin)
// Windows: .cmd shim runs via the shell → prompt via stdin, not argv. POSIX
// unchanged (prompt in argv).
const base = flags.length
? [...flags, ...resume, '-p']
: allowUnsandboxedByoa(env)
? ['-p', ...resume, ...model, ...speed, '--output-format', 'stream-json', '--verbose', '--dangerously-skip-permissions']
: ['-p', ...resume, ...model, '--output-format', 'stream-json', '--verbose', ...claudeSecureFlags(args.home, env, fastMode)]
const argv = wantsStdinPrompt ? base : (flags.length ? [...base, args.prompt] : ['-p', args.prompt, ...base.slice(1)])
// Agent turns can be substantial engineering/design work. Preserve the
// operator's reasoning preferences; only triage/doctor force thinking off.
return spawnEngine(command, argv, { ...args, env }, { shell, stdinText: wantsStdinPrompt ? args.prompt : undefined })
.then((result) => classifyEngineResult(result, !!args.resumeSessionId))
}
startSession(args: EngineSessionArgs): EngineSession | null {
// Respect a user's custom flag override (CUMORA_CLAUDE_ARGS) by NOT using the
// persistent path — those flags are tuned for the one-shot run; fall back to run().
if (unsafeEngineArgs('CUMORA_CLAUDE_ARGS').length) return null
const selectedModel = claudeMainModel(args.env, args.model)
const model = selectedModel ? ['--model', selectedModel] : []
const env = claudeTurnEnv(args.env, args.fastModel)
const fastMode = args.nativeFastMode ?? false
if (claudeFastModeError(args.model, env, fastMode)) return null
// --resume only on the FIRST spawn / after a restart, to continue a prior
// session; inside a live process the session continues on its own.
const resume = args.resumeSessionId ? ['--resume', args.resumeSessionId] : []
// The invariant standing prompt loads ONCE here (not re-sent every turn), so
// the per-turn stdin messages stay small and native auto-compaction keeps up.
// Write it to a file in the agent home and pass --append-system-prompt-file.
let sys: string[] = []
let carriesStanding = false
if (args.standingPrompt) {
const file = join(args.home, '.cumora-standing-prompt.md')
try { atomicAgentWriteSync(file, args.standingPrompt); sys = ['--append-system-prompt-file', file]; carriesStanding = true }
catch { /* couldn't write → leave it; the daemon inlines the standing prompt instead */ }
}
const argv = allowUnsandboxedByoa(env)
? [
'-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose',
...resume, ...sys, ...model, '--settings', JSON.stringify({ fastMode }), '--dangerously-skip-permissions',
]
: [
'-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose',
...resume, ...sys, ...model, ...claudeSecureFlags(args.home, env, fastMode),
]
const fingerprint = claudeProviderFingerprint(args.env)
return new ClaudeSession(this.bin, argv, { ...args, env }, carriesStanding,
() => claudeProviderFingerprint(args.env) !== fingerprint)
}
}
/** Codex requires a git repo in its cwd. The one-shot `exec` path uses
* --skip-git-repo-check, but app-server has no such flag, so we
* make the agent home a throwaway repo. Init + ONE empty commit only — we do
* NOT `git add` anything, so the operator's tokens/files under the home are
* never staged. Best-effort: a failure just means app-server may refuse, and
* startSession falls back to one-shot exec. */
function ensureGitRepoForCodex(home: string): void {
if (existsSync(join(home, '.git'))) return
const g = ['-c', 'user.name=cumora', '-c', 'user.email=cumora@local', '-c', 'commit.gpgsign=false']
execFileSync('git', ['init'], { cwd: home, stdio: 'ignore' })
execFileSync('git', [...g, 'commit', '--allow-empty', '-m', 'cumora init'], { cwd: home, stdio: 'ignore' })
}
type CodexRpcMsg = {
id?: number
method?: string
result?: { thread?: { id?: unknown }; turn?: { id?: unknown }; turnId?: unknown }
error?: { message?: unknown }
params?: Record<string, unknown>
}
const CODEX_SECURE_CONFIG_ARGS = [
'--strict-config',
// The unelevated restricted-token sandbox cannot enforce Cumora's split
// filesystem profile. Native Windows uses Codex's elevated sandbox instead.
...(IS_WIN ? ['-c', 'windows.sandbox="elevated"'] : []),
'-c', 'default_permissions="cumora"',
'-c', 'permissions.cumora.network.enabled=false',
'-c', 'shell_environment_policy.inherit="none"',
'-c', 'shell_environment_policy.ignore_default_excludes=false',
]
function codexServiceTierArgs(enabled: boolean): string[] {
return ['-c', `service_tier="${enabled ? 'fast' : 'default'}"`, ...(enabled ? ['-c', 'features.fast_mode=true'] : [])]
}
function codexThreadSecurityParams(): Record<string, unknown> {
return allowUnsandboxedByoa()
? { approvalPolicy: 'never', sandbox: 'danger-full-access' }
: { approvalPolicy: 'never', sandbox: 'workspace-write' }
}
function tomlString(value: string): string {
return JSON.stringify(value)
}
/** The Codex core keeps its auth environment, while every model-spawned
* command receives only this explicit, non-secret environment. */
function codexToolEnvironmentArgs(args: { home: string; env: NodeJS.ProcessEnv }): string[] {
const entries: string[] = []
const add = (name: string, value: string | undefined) => {
if (value !== undefined) entries.push(`${name}=${tomlString(value)}`)
}
add('PATH', args.env.PATH)
add('HOME', args.home)
add('USER', args.env.USER)
add('LOGNAME', args.env.LOGNAME)
add('SHELL', args.env.SHELL)
add('LANG', args.env.LANG)
add('TERM', args.env.TERM)
add('CUMORA_AGENT_IPC_DIR', args.env.CUMORA_AGENT_IPC_DIR)
add('CUMORA_AGENT_ID', args.env.CUMORA_AGENT_ID)
return ['-c', `shell_environment_policy.set={${entries.join(',')}}`]
}
/** Codex rejects the whole invocation when any `-c` override fails to load, and
* the resulting error names `config.toml` without ever mentioning that Cumora
* authored that config — which is how 103 workspaces spent six hours looking at
* agents that would not answer, with no way to reach the cause.
*
* Say it once per daemon: name Cumora as the author, quote what codex actually
* said so it can be reported upstream, and point at the documented escape
* hatch. Deliberately does NOT downgrade on its own — the only fallback
* available is the historical `--dangerously-bypass-approvals-and-sandbox`, and
* trading the sandbox for availability is a maintainer's decision. */
const CODEX_CONFIG_REJECTED_RE = /Error loading config\.toml|unknown configuration field|expected struct \w+PermissionsToml/i
let codexProfileRejected = false
export function codexProfileIsRejected(): boolean {
return codexProfileRejected
}
/** Test seam. */
export function resetCodexProfileRejection(): void {
codexProfileRejected = false
}
export function noteCodexConfigRejection(err: string | undefined, onLog?: (line: string) => void): boolean {
if (!err || codexProfileRejected || !CODEX_CONFIG_REJECTED_RE.test(err)) return false
codexProfileRejected = true
const hint = `[codex] the installed codex rejected the sandbox profile Cumora passes via -c. Every turn on this machine fails until this is resolved. Set ${ALLOW_UNSANDBOXED_BYOA_ENV}=1 on the daemon to run with the historical unsandboxed flags, or report the codex version. Codex said: ${err.slice(0, 300)}`
onLog?.(hint)
console.warn(hint)
return true
}
/** Shared sandbox profile for exec, persistent sessions and wake probes. */
function codexSecureConfigOverrides(args: { home: string; env: NodeJS.ProcessEnv }, readOnly = false): string[] {
const workspaceAccess = readOnly ? 'read' : 'write'
const filesystemEntries = [
'":minimal"="read"',
`":workspace_roots"={"."="${workspaceAccess}"}`,
]
const filesystem = `permissions.cumora.filesystem={${filesystemEntries.join(',')}}`
const secureArgs = [
...CODEX_SECURE_CONFIG_ARGS,
'-c', filesystem,
'-c', 'web_search="disabled"',
'-c', 'features.hooks=false',
'-c', 'features.apps=false',
'-c', 'features.remote_plugin=false',
'-c', 'features.multi_agent=false',
'-c', 'features.shell_snapshot=false',
// Untrusted projects skip project-local config, hooks, and rules. This is a
// CLI override (highest precedence), so a model cannot plant a more
// privileged .codex layer for the next one-shot wake.
//
// Written as an inline table rather than the dotted `projects."<home>".…`
// form, because Codex 0.150/0.151 rejects a quoted dynamic map key in a
// dotted override under --strict-config and refuses to start at all:
// Error loading config.toml: unknown configuration field
// `projects."<agent-home>"` in -c/--config override
// Every wake then failed before the model ran, and the undelivered message
// stayed durable, so the daemon retried the same failure forever (#144).
//
// The inline form parses on every version anyone has checked — 0.134.0 and
// 0.152.0 here, 0.150.1 and 0.151.0-alpha on the report — whereas the
// dotted form does not, so this is the strictly better-supported spelling
// rather than a trade.
//
// Production since corrected one guess above: the dotted form was NOT fixed
// after 0.151. In 30 hours it was rejected 252,589 times on POSIX across 121
// computers, including 35,721 on 0.151.0 (18 machines) and 13,153 on 0.152.0
// (12 machines). POSIX has no shell in this path and so no quote-stripping,
// which is what rules out the Windows cmd.exe cause and leaves the spelling
// itself. Do not restore the dotted form on the strength of a local check.
'-c', `projects={${tomlString(args.home)}={trust_level="untrusted"}}`,
...codexToolEnvironmentArgs(args),
]
if (!readOnly) {
const mcpShim = args.env.CUMORA_AGENT_MCP_SHIM
const ipcDir = args.env.CUMORA_AGENT_IPC_DIR
if (!mcpShim || !ipcDir) throw new Error('secure Cumora MCP bridge is not configured')
const mcp = `mcp_servers.cumora={command=${tomlString(process.execPath)},args=[${tomlString(mcpShim)}],env={CUMORA_AGENT_IPC_DIR=${tomlString(ipcDir)}},required=true,enabled_tools=["cli"],default_tools_approval_mode="approve"}`
secureArgs.push('-c', mcp)
}
return secureArgs
}
function codexSecureExecArgs(args: { home: string; env: NodeJS.ProcessEnv }, readOnly = false): string[] {
return [...codexSecureConfigOverrides(args, readOnly), '-a', 'never', 'exec', '--ignore-user-config', '--ignore-rules']
}
/** A persistent Codex session over the app-server JSON-RPC protocol
* (`codex app-server --listen stdio://`) — the transport with Codex's NATIVE
* context management + auto-compaction (unlike one-shot
* `codex exec`, which re-pays cold start and keeps no persistent context).
* Handshake: initialize → initialized → thread/start|resume (carrying the standing
* prompt as developerInstructions) → turn/start per wake. The daemon calls send()
* serially; each resolves on that turn's `turn/completed`. */
class CodexSession implements EngineSession {
private readonly child: ChildProcess
private readonly authHome: string
private readonly authFingerprint: string | null | undefined
private readonly providerChanged: () => boolean
private readonly onLog: (line: string) => void
private readonly onHopUsage?: (r: EngineHopReport) => void
/** Wall-clock when the CURRENT turn started (turn/start request sent), used to
* attach latency_ms to the hop report at turn/completed. */
private turnStartedAt: number | null = null
private outBuf = ''
private stderrTail = ''
private hasSent = false
private threadId: string | null
private exited = false
private exitCode = 0
private reqId = 0
private initializeId: number | null = null
private threadReq: { method: string; params: Record<string, unknown> } | null
private threadReqId: number | null = null
private threadWasResume = false
// thread params WITHOUT threadId — reused to start a FRESH thread if a resume fails.
private readonly baseThreadParams: Record<string, unknown>
private ready = false
// Why the session died, when it did — so a send() landing after the teardown
// reports the real cause instead of a generic "process gone".
private sessionError: string | null = null
private pending: { resolve: (r: EngineRunResult) => void } | null = null
private queuedInput: { prompt: string; localImages: readonly string[] } | null = null
private activeTurnId: string | null = null
private steerGate = false
private readonly model: string | null
private readonly vision: EngineSessionArgs['vision']
readonly carriesStandingPrompt: boolean
// Codex reports a RUNNING thread token total; per-turn usage is the delta.
private cum = { input: 0, cached: 0, output: 0 }
private turnStart = { input: 0, cached: 0, output: 0 }
constructor(bin: string, spawnArgs: string[], private readonly home: string, env: NodeJS.ProcessEnv, opts: EngineSessionArgs, providerChanged: () => boolean) {
this.providerChanged = providerChanged
this.authHome = env.CODEX_HOME!
this.authFingerprint = codexAuthFingerprint(this.authHome)
this.onLog = opts.onLog
this.onHopUsage = opts.onHopUsage
this.threadId = opts.resumeSessionId ?? null
this.model = opts.model ?? null
this.vision = opts.vision
this.carriesStandingPrompt = !!opts.standingPrompt
// experimentalRawEvents → Codex emits payload-free `rawResponseItem/*` pings we
// use as a liveness signal; we suppress them from the log below.
const params: Record<string, unknown> = {
cwd: home,
...codexThreadSecurityParams(),
experimentalRawEvents: true,
}
if (opts.standingPrompt) params.developerInstructions = opts.standingPrompt
if (opts.model) params.model = opts.model
params.serviceTier = opts.nativeFastMode ? 'fast' : 'default'
this.baseThreadParams = params
this.threadWasResume = !!opts.resumeSessionId
this.threadReq = opts.resumeSessionId
? { method: 'thread/resume', params: { threadId: opts.resumeSessionId, ...params } }
: { method: 'thread/start', params }
this.child = spawnEngineChild(bin, spawnArgs, { cwd: home, env, stdio: ['pipe', 'pipe', 'pipe'], shell: false })
this.child.stdout?.on('data', (b: Buffer) => this.onStdout(b))
this.child.stderr?.on('data', (b: Buffer) => {
this.stderrTail = (this.stderrTail + b.toString('utf8')).slice(-MAX_FAILURE_CHARS)
for (const raw of b.toString('utf8').split('\n')) { const l = cleanLine(raw); if (l) this.onLog(l) }
})
this.child.on('error', (err) => this.die(1, err.message))
this.child.on('close', (code, sig) => this.die(code ?? (sig ? 128 : 1), sig ? `process terminated by ${sig}` : `process exited with code ${code}`))
// Begin the handshake once handlers are attached.
queueMicrotask(() => { this.initializeId = this.req('initialize', { clientInfo: { name: 'cumora-daemon', version: '1.0.0' }, capabilities: { experimentalApi: true } }) })
}
get alive(): boolean {
if (this.exited || this.child.stdin?.writable !== true) return false
if (!this.pending) {
if (this.providerChanged()) {
this.onLog('[codex] provider configuration changed; restarting the idle session')
void this.stop({ force: true })
return false
}
const auth = codexAuthFingerprint(this.authHome)
if (auth !== undefined && auth !== this.authFingerprint) {
this.onLog('[codex] login changed; restarting the session with its saved thread')
void this.stop({ force: true })
return false
}
}
return true
}
get sessionId(): string | null { return this.threadId }
send(prompt: string, localImages: readonly string[] = []): Promise<EngineRunResult> {
if (this.pending) return Promise.resolve(classifyEngineResult({ exitCode: 1, error: 'engine session busy — a turn is already in flight', sessionId: this.threadId }, this.threadWasResume))
if (!this.alive) return Promise.resolve(classifyEngineResult({ exitCode: this.exitCode || 1, error: this.sessionError ?? 'engine session is not alive (process gone)', sessionId: this.threadId }, this.threadWasResume))
// Only the first turn inherits output from process startup. Later turns
// must not classify an old turn's stderr as their own failure.
if (this.hasSent) this.stderrTail = ''
this.hasSent = true
const input = { prompt, localImages: [...localImages] }
return new Promise<EngineRunResult>((resolve) => {
this.pending = { resolve }
this.turnStart = { ...this.cum }
// Fire now if the thread handshake already completed; else queue until it does.
if (this.ready && this.threadId) this.startTurn(input)
else this.queuedInput = input
})
}
steer(text: string): void {
if (!this.alive || !text.trim() || !this.threadId || !this.activeTurnId || this.steerGate) return
writeStdin(this.child, JSON.stringify({ jsonrpc: '2.0', id: this.nextId(), method: 'turn/steer',
params: { threadId: this.threadId, expectedTurnId: this.activeTurnId, input: [{ type: 'text', text: stripLoneSurrogates(text) }] } }) + '\n')
}
stop(options: { force?: boolean } = {}): Promise<void> {
this.exited = true
try { this.child.stdin?.end() } catch { /* ignore */ }
return terminateEngineTree(this.child, options.force)
}
private nextId(): number { this.reqId += 1; return this.reqId }
private req(method: string, params: Record<string, unknown>): number {
const id = this.nextId()
writeStdin(this.child, JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n')
return id
}
private notify(method: string, params: Record<string, unknown>): void {
writeStdin(this.child, JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n')
}
private startTurn(input: { prompt: string; localImages: readonly string[] }): void {
if (this.threadId) {
this.turnStartedAt = Date.now()
this.req('turn/start', {
threadId: this.threadId,
input: codexTurnInput(input.prompt, this.vision === 'supported' ? input.localImages : [], this.home),
})
}
}
private onStdout(buf: Buffer): void {
this.outBuf += buf.toString('utf8')
let nl: number
while ((nl = this.outBuf.indexOf('\n')) >= 0) {
const line = this.outBuf.slice(0, nl)
this.outBuf = this.outBuf.slice(nl + 1)
const t = line.trim()
if (!t.startsWith('{')) { const c = cleanLine(line); if (c) this.onLog(c); continue }
let msg: CodexRpcMsg | null = null
try { msg = JSON.parse(t) as CodexRpcMsg } catch { msg = null }
if (!msg) { const c = cleanLine(line); if (c) this.onLog(c); continue }
// The app-server fire-hoses raw events (text deltas, per-item token/rate-limit
// snapshots, full item start/complete JSON). The daemon needs none of it — the
// agent acts via the `cumora` shim — so by DEFAULT we don't echo raw events to
// the log; handle() emits concise signal lines instead (commands run, final
// answer, compaction, errors). CUMORA_CODEX_VERBOSE=1 dumps the raw stream.
if (CODEX_LOG_RAW) { const c = cleanLine(line); if (c) this.onLog(c) }
this.handle(msg)
}
}
private handle(msg: CodexRpcMsg): void {
// initialize response → initialized + open the thread (start or resume).
if (msg.id !== undefined && msg.id === this.initializeId) {
this.initializeId = null
if (msg.error) { this.failPending(String(msg.error.message || 'codex initialize failed')); return }
this.notify('initialized', {})
if (this.threadReq) { this.threadReqId = this.req(this.threadReq.method, this.threadReq.params); this.threadReq = null }
return
}
// resume_or_fresh: a failed thread/resume — e.g. a stale id, or
// a session id left over from a DIFFERENT engine after an engine switch — falls
// back to a brand-new thread instead of wedging the agent.
if (msg.error && msg.id !== undefined && msg.id === this.threadReqId) {
if (this.threadWasResume) {
this.onLog(`[codex] thread/resume failed (${String(msg.error.message || '')}) — starting a fresh thread`)
this.threadWasResume = false
this.threadId = null
this.threadReqId = this.req('thread/start', this.baseThreadParams)
return
}
this.failPending(String(msg.error.message || 'codex thread start failed'))
return
}
// thread ready: response to thread/start|resume, OR a thread/started notification.
const threadId = msg.result?.thread?.id ?? (msg.method === 'thread/started' ? (msg.params?.thread as { id?: unknown } | undefined)?.id : undefined)
if (typeof threadId === 'string') { this.onThreadReady(threadId); return }
// turn id (for steering) — from the turn/start response or turn/started notif.
const turnId = msg.result?.turn?.id ?? msg.result?.turnId ?? (msg.method === 'turn/started' ? (msg.params?.turn as { id?: unknown } | undefined)?.id : undefined)
if (typeof turnId === 'string') { this.activeTurnId = turnId; this.steerGate = false }
// running thread token total.
if (msg.method === 'thread/tokenUsage/updated') { this.updateUsage((msg.params?.tokenUsage as { total?: unknown } | undefined)?.total); return }
// surface the account rate limit ONLY when it's getting tight (would have flagged
// a usage-limit before it hit). Quiet otherwise.
if (msg.method === 'account/rateLimits/updated') {
const pct = (msg.params?.rateLimits as { primary?: { usedPercent?: unknown } } | undefined)?.primary?.usedPercent
if (typeof pct === 'number' && pct >= 90) this.onLog(`[codex] ⚠️ account rate limit at ${Math.round(pct)}% — turns will start failing when it reaches 100%`)
return
}
// items: observe native compaction; log the commands the agent runs
// + its final answer (concise signal); a completed item briefly gates steering.
if (msg.method === 'item/started' || msg.method === 'item/completed') {
const item = msg.params?.item as { type?: unknown; command?: unknown; text?: unknown } | undefined
const ty = item?.type
if (ty === 'contextCompaction') this.onLog(`[codex] native context compaction ${msg.method === 'item/started' ? 'started' : 'finished'}`)
else if (ty === 'commandExecution' && msg.method === 'item/started' && typeof item?.command === 'string') this.onLog(`[codex] $ ${item.command.replace(/\s+/g, ' ').slice(0, 200)}`)
else if (ty === 'agentMessage' && msg.method === 'item/completed' && typeof item?.text === 'string' && item.text.trim()) this.onLog(`[codex] » ${item.text.replace(/\s+/g, ' ').slice(0, 200)}`)
if (msg.method === 'item/completed') this.steerGate = true
return
}
if (msg.method === 'item/agentMessage/delta' || msg.method === 'item/reasoning/textDelta' || msg.method === 'item/reasoning/summaryTextDelta') { this.steerGate = false; return }
// request-level error (e.g. thread/start failed) → fail the in-flight turn.
if (msg.error && msg.id !== undefined) { this.failPending(String(msg.error.message || 'codex app-server request failed')); return }
// turn finished → resolve the pending send.
if (msg.method === 'turn/completed') {
const turn = msg.params?.turn as { status?: unknown; error?: { message?: unknown } } | undefined
const failed = turn?.status === 'failed' ? String(turn?.error?.message || 'codex turn failed') : undefined
// Per-hop trajectory for Codex: app-server doesn't expose per-message
// usage (only running thread totals via thread/tokenUsage/updated), so
// the finest granularity we can honestly report is ONE row per turn
// with that turn's delta — same shape as turnUsage(). When future
// app-server versions expose per-item usage we can split this further;
// the ledger schema doesn't change. We deliberately emit BEFORE settle()
// so the daemon's flush window includes this hop's row reliably.
if (!failed && this.onHopUsage && this.model) {
try {
this.onHopUsage({
model: this.model,
usage: this.turnUsage(),
latencyMs: this.turnStartedAt != null ? Date.now() - this.turnStartedAt : undefined,
// Codex only reports turn-level totals today, so every emission is
// the 1st (and only) hop for that turn. When app-server starts
// exposing per-item usage, this becomes a real running counter.
hopIndex: 1,
})
} catch { /* never break the stream */ }
}
this.turnStartedAt = null
this.activeTurnId = null; this.steerGate = false
this.settle(failed)
return
}
if (msg.method === 'error') {
const p = msg.params as { message?: unknown; error?: { message?: unknown } } | undefined
this.failPending(String(p?.message || p?.error?.message || 'codex app-server error'))
}
}
private onThreadReady(threadId: string): void {
this.threadId = threadId
this.threadWasResume = false
this.ready = true
if (this.queuedInput && this.pending) {
const input = this.queuedInput
this.queuedInput = null
this.startTurn(input)
}
}
private updateUsage(total: unknown): void {
if (!total || typeof total !== 'object') return
const t = total as Record<string, unknown>
const num = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) ? v : 0)
const input = num(t.inputTokens), cached = num(t.cachedInputTokens)
const output = num(t.outputTokens) + num(t.reasoningOutputTokens)
// Keep the max so a late/partial update can't regress the running total.
this.cum = { input: Math.max(this.cum.input, input), cached: Math.max(this.cum.cached, cached), output: Math.max(this.cum.output, output) }
}
private turnUsage(): EngineUsage {
const inputTotal = Math.max(0, this.cum.input - this.turnStart.input)
const cached = Math.max(0, this.cum.cached - this.turnStart.cached)
return {
input_tokens: Math.max(0, inputTotal - cached), // non-cached portion (Claude-style fields)
cache_read_input_tokens: cached,
output_tokens: Math.max(0, this.cum.output - this.turnStart.output),
}
}
private settle(error?: string): void {
const p = this.pending
this.pending = null
this.stderrTail = ''
if (p) p.resolve(classifyEngineResult({ exitCode: error ? 1 : 0, error, sessionId: this.threadId, usage: this.turnUsage(), model: this.model }, this.threadWasResume))
}
private failPending(error: string): void {
if (this.pending) this.settle(error)
else this.onLog(`[codex] ${error}`)
// A failure BEFORE the thread ever opened kills the SESSION, not just this
// turn. The handshake is one-shot — threadReq is consumed at the initialize
// ack, and only a failed thread/resume re-issues a thread/start — so `ready`
// can never flip afterwards, and every later send() would park its prompt in
// queuedPrompt with nothing left able to drain it (the daemon awaits that
// promise forever, so the agent goes silently and permanently dead and its
// big-brain slot never comes back). The app-server SURVIVES rejecting the
// handshake (a malformed ~/.codex/config.toml, a model this account can't
// use, protocol drift), so `alive` would keep advertising a usable session
// and the daemon would reuse the zombie on every wake. Tear it down instead:
// a !alive session is dropped and the next wake spawns a clean one.
if (!this.ready) { this.sessionError = error; this.stop() }
}
private die(code: number, why: string): void {
const alreadyDown = this.exited
this.exited = true
// Exiting before turn/completed is a failed turn, even after a clean EOF.
this.exitCode = code || 1
const diagnostic = engineDiagnosticText(cleanLine(this.stderrTail))
// The daemon displays only the first 900 characters. Keep the startup
// cause ahead of noisy stderr so the notice retains both cause and kind.
this.sessionError ??= [startupFailureLine(diagnostic), why, diagnostic]
.filter(Boolean).join('\n').slice(0, MAX_FAILURE_CHARS)
// Same idle-death visibility as ClaudeSession.die: a session dying with no
// turn in flight must leave a trace, not silently vanish until the next wake.
if (!alreadyDown) {
this.onLog(`[session] engine process died ${this.pending ? 'MID-TURN' : 'while idle'}: ${why} (exit ${code})`)
}
const p = this.pending
this.pending = null
if (p) p.resolve(classifyEngineResult({ exitCode: this.exitCode, error: this.sessionError, sessionId: this.threadId }, this.threadWasResume))
}
}
class CodexAdapter implements EngineAdapter {
readonly id = 'codex' as const
readonly bin = 'codex'
async classify(args: EngineClassifyArgs): Promise<EngineClassifyResult> {
// gpt-5.4-mini works with ChatGPT auth; arbitrary small API models do not.
const flags = allowUnsandboxedByoa() ? extraArgs('CUMORA_TRIAGE_ARGS') : []
const provider = await prepareCodexProvider(this.bin, args.env)
const model = args.model || (provider.prefersLocalDefault ? provider.defaultModel : 'gpt-5.4-mini')
return this.capture(args, flags.length ? flags : [...(model ? ['--model', model] : []), '--skip-git-repo-check'])
}
async probe(args: EngineProbeArgs): Promise<EngineClassifyResult> {
// Omit --model for the big tier so Codex uses its configured default.
const provider = await prepareCodexProvider(this.bin, args.env)
const selected = args.tier === 'small' ? triageModel(provider.prefersLocalDefault ? provider.defaultModel ?? '' : 'gpt-5.4-mini') : null
const model = selected ? ['--model', selected] : []
return this.capture({ ...args, prompt: DOCTOR_PROMPT }, [...model, '--skip-git-repo-check'])
}
private async capture(args: EngineClassifyArgs, flags: string[]): Promise<EngineClassifyResult> {
const { env, provider } = await codexProviderRuntime(this.bin, args.env)
const { command, shell, argsPrefix } = resolveCodexSpawn()
assertCodexProviderTransport(provider.args, shell)
const exec = allowUnsandboxedByoa() ? ['exec'] : codexSecureExecArgs({ home: args.cwd, env }, true)
return spawnCapture(command, [...argsPrefix, ...provider.args, ...exec, '--ephemeral', ...flags, ...CODEX_RUNTIME_CONFIG_ARGS, ...codexServiceTierArgs(false), '-'], {
cwd: args.cwd, env, signal: args.signal, onLog: args.onLog, shell, stdinText: args.prompt,
})
}
async probeWake(args: EngineWakeProbeArgs): Promise<EngineWakeProbeResult> {
// Same gates as startSession()'s "fall back to one-shot exec" decision: when
// any of these is true, the wake path collapses to `codex exec ...` which
// probe() already covers — running the JSON-RPC probe would just add a false
// signal. Mark skipped and let doctor hide the line.
if (unsafeEngineArgs('CUMORA_CODEX_ARGS').length
|| process.env.CUMORA_CODEX_NO_APP_SERVER === '1'
|| IS_WIN) {
return Promise.resolve({ ok: true, detail: '', skipped: true })
}
const { env, provider } = await codexProviderRuntime(this.bin, args.env)
args = { ...args, env }
// The real wake spawns `codex app-server --listen stdio://` and drives a
// JSON-RPC handshake (initialize → thread/start). The realistic breaks here
// are: app-server subcommand removed/renamed; protocol field names changed
// (approvalPolicy / sandbox / experimentalRawEvents); or git repo
// bootstrapping failing in the cwd. Drive a minimal handshake against all
// three, then tear the process down.
try { ensureGitRepoForCodex(args.cwd) }
catch (err) {
return Promise.resolve({ ok: false, detail: `git init failed for app-server cwd: ${err instanceof Error ? err.message : String(err)}` })
}
const { command, shell, argsPrefix } = resolveCodexSpawn()
return new Promise<EngineWakeProbeResult>((resolve) => {
let settled = false
const finish = (r: EngineWakeProbeResult) => {
if (settled) return
settled = true
try { child.stdin?.end() } catch { /* ignore */ }
void terminateEngineTree(child).then(() => resolve(r))
}
const secure = allowUnsandboxedByoa() ? [] : codexSecureConfigOverrides({ home: args.cwd, env: args.env }, true)
const appServerArgs = [...argsPrefix, ...provider.args, ...secure, ...CODEX_RUNTIME_CONFIG_ARGS, 'app-server', '--listen', 'stdio://']
const child = spawnEngineChild(command, appServerArgs, {
cwd: args.cwd, env: args.env, stdio: ['pipe', 'pipe', 'pipe'], shell,
})
const onAbort = () => finish({ ok: false, detail: 'aborted (timeout)' })
if (args.signal.aborted) { onAbort(); return }
args.signal.addEventListener('abort', onAbort, { once: true })
let buf = ''
let stderrTail = ''
const initId = 1
const threadId = 2
let initialized = false
let threadAcked = false
const writeRpc = (msg: object) => {
writeStdin(child, JSON.stringify(msg) + '\n')
}
// Kick off the handshake once the process is up. spawn() emits stdout
// 'data' lazily — that's the point at which we know the child is alive
// enough to take input. Send `initialize` and wait for its id back.
writeRpc({ jsonrpc: '2.0', id: initId, method: 'initialize',
params: { clientInfo: { name: 'cumora-doctor', version: '1.0.0' },
capabilities: { experimentalApi: true } } })
child.stdout?.on('data', (b: Buffer) => {
buf += b.toString('utf8')
for (;;) {
const nl = buf.indexOf('\n')
if (nl < 0) break
const line = buf.slice(0, nl).trim()
buf = buf.slice(nl + 1)
if (!line) continue
let msg: CodexRpcMsg
try { msg = JSON.parse(line) as CodexRpcMsg } catch { continue }
if (msg.error?.message) {
finish({ ok: false, detail: `app-server rejected handshake: ${String(msg.error.message).slice(0, 240)}` })
return
}
if (!initialized && msg.id === initId && msg.result) {
initialized = true
// notify `initialized` (no id), then thread/start with the SAME
// params shape CodexSession uses — so a field-name break shows up.
writeRpc({ jsonrpc: '2.0', method: 'initialized', params: {} })
writeRpc({ jsonrpc: '2.0', id: threadId, method: 'thread/start',
params: { cwd: args.cwd, ...codexThreadSecurityParams(), experimentalRawEvents: true, ephemeral: true } })
continue
}
if (initialized && !threadAcked && msg.id === threadId && msg.result) {
threadAcked = true
finish({ ok: true, detail: '' })
return
}
}
})
child.stderr?.on('data', (b: Buffer) => {
const tail = (stderrTail + b.toString('utf8'))
stderrTail = tail.length > 2000 ? tail.slice(-2000) : tail
})
child.on('error', (err) => finish({ ok: false, detail: `spawn error: ${err.message}` }))
child.on('close', (code, sig) => {
if (settled) return
const stage = !initialized ? 'before initialize ack' : !threadAcked ? 'before thread/start ack' : 'after handshake'
const exit = sig ? `terminated by ${sig}` : `exit ${code}`
finish({ ok: false, detail: `app-server died ${stage} (${exit}): ${salientError(stderrTail) || 'no stderr'}` })
})
})
}
async seedHome(home: string, persona: EnginePersona): Promise<void> {
await ensureCommonHome(home)
// See ClaudeAdapter.seedHome: system-owned, safe to overwrite every start.
await atomicAgentWrite(join(home, 'AGENTS.md'), PERSONA_HEADER(persona))
}
async run(args: EngineRunArgs): Promise<EngineRunResult> {
// `codex exec` is the non-interactive mode. Secure mode applies a custom
// filesystem/network/environment profile and reaches Cumora only through
// local IPC. Historical full-access flags and argv overrides remain
// available exclusively behind the explicit compatibility opt-in.
const { env, provider } = await codexProviderRuntime(this.bin, args.env)
args = { ...args, env }
const flags = unsafeEngineArgs('CUMORA_CODEX_ARGS')
const base = flags.length
? ['exec', ...flags]
: allowUnsandboxedByoa()
? ['exec', '--dangerously-bypass-approvals-and-sandbox', '--skip-git-repo-check']
: [...codexSecureExecArgs(args), '--skip-git-repo-check']
if (!base.includes('--json')) base.push('--json')
const model = args.model ? ['--model', args.model] : []
const imageArgs = args.vision === 'supported'
? codexLocalImagePaths(args.home, args.localImages ?? []).flatMap((path) => ['--image', path])
: []
// `resume` owns its own positional session id and --image option. Keep the
// option before the id so clap cannot mistake it for the prompt argument.
const resume = args.resumeSessionId
? ['resume', ...imageArgs, args.resumeSessionId]
: []
const freshImages = args.resumeSessionId ? [] : imageArgs
const { command, shell, argsPrefix } = resolveCodexSpawn()
let sessionId = args.resumeSessionId ?? null
assertCodexProviderTransport(provider.args, shell)
let usage: EngineUsage | undefined
let turnError: string | undefined
const started = Date.now()
return spawnEngine(command, [...argsPrefix, ...provider.args, ...base, ...freshImages, ...model, ...CODEX_RUNTIME_CONFIG_ARGS, ...codexServiceTierArgs(args.nativeFastMode ?? false), ...resume, '-'], args, {
shell, stdinText: args.prompt,
onStdoutLine(line) {
let event
try { event = JSON.parse(line) } catch { return }
if (event?.type === 'thread.started' && typeof event.thread_id === 'string' && event.thread_id) sessionId = event.thread_id
if (event?.type === 'turn.failed') turnError = String(event.error?.message || 'codex turn failed')
if (event?.type !== 'turn.completed' || !event.usage) return
const { input_tokens: input, cached_input_tokens: cached = 0, output_tokens: output } = event.usage
if (![input, cached, output].every(value => typeof value === 'number' && Number.isFinite(value) && value >= 0)) return
usage = { input_tokens: Math.max(0, input - cached), cache_read_input_tokens: cached, output_tokens: output }
},
})
.then((res) => {
// A rejected -c override aborts codex before it reads the prompt, so the
// turn fails with a config error that never mentions Cumora. Say it once.
noteCodexConfigRejection(res.error, args.onLog)
if (usage && args.model && !turnError && res.exitCode === 0) {
try { args.onHopUsage?.({ model: args.model, usage, latencyMs: Date.now() - started, hopIndex: 1 }) }
catch { /* never break the run on a ledger error */ }
}
return classifyEngineResult({
...res, sessionId, usage, model: args.model ?? res.model,
exitCode: turnError && res.exitCode === 0 ? 1 : res.exitCode,
error: res.error ?? turnError,
}, !!args.resumeSessionId)
})
}
startSession(args: EngineSessionArgs): EngineSession | null {
// Windows .cmd transport, custom args and explicit opt-outs use exec resume.
if (unsafeEngineArgs('CUMORA_CODEX_ARGS').length
|| process.env.CUMORA_CODEX_NO_APP_SERVER === '1'
|| IS_WIN) return null
const originalEnv = args.env
const provider = cachedCodexProvider(originalEnv)
// First turn can prepare asynchronously through run(); never start on an
// unprepared connection just because this legacy interface is synchronous.
if (!provider) return null
args = { ...args, env: codexProviderEnv(provider, args.env) }
try { ensureGitRepoForCodex(args.home) }
catch (err) { args.onLog(`[codex] could not init git repo for app-server (${err instanceof Error ? err.message : String(err)}) — falling back to one-shot exec`); return null }
const { command, argsPrefix } = resolveCodexSpawn()
const secure = allowUnsandboxedByoa()
? []
: codexSecureConfigOverrides({ home: args.home, env: args.env })
return new CodexSession(command, [...argsPrefix, ...provider.args, ...secure, ...CODEX_RUNTIME_CONFIG_ARGS, ...codexServiceTierArgs(args.nativeFastMode ?? false), 'app-server', '--listen', 'stdio://'], args.home, args.env, args,
() => {
try { return codexProviderFingerprint(originalEnv) !== provider.fingerprint }
catch { return true }
})
}
}
/** Official Grok Build install lives at ~/.grok/bin even when that dir is
* not on the daemon's PATH (launchd / login-shell mismatch). PATH wins. */
function resolveGrokBin(env: NodeJS.ProcessEnv = process.env): string | null {
const searchPath = env.PATH ?? env.Path ?? ''
for (const dir of searchPath.split(PATH_DELIMITER)) {
if (!dir) continue
const candidate = join(dir, IS_WIN ? 'grok.exe' : 'grok')
if (existsSync(candidate)) return candidate
if (IS_WIN && existsSync(join(dir, 'grok'))) return join(dir, 'grok')
}
const homeBin = join(homedir(), '.grok', 'bin', IS_WIN ? 'grok.exe' : 'grok')
return existsSync(homeBin) ? homeBin : null
}
type AcpMsg = {
jsonrpc?: string
id?: number
method?: string
result?: { sessionId?: unknown }
// omp answers a real cause with a generic `Internal error` and puts the cause
// in `data.details` (e.g. "ACP session not found: <id>").
error?: { message?: unknown; data?: { details?: unknown } }
params?: Record<string, unknown>
}
/** Operator-facing text for a JSON-RPC rejection. `data.details` carries the
* actual cause on agents that answer every failure with a generic message;
* appending it is additive, so adapters keyed on the plain message still match. */
function acpErrorMessage(error: AcpMsg['error'], method: string): string {
const message = typeof error?.message === 'string' && error.message ? error.message : `${method} failed`
const details = error?.data?.details
return typeof details === 'string' && details.trim() ? `${message} — ${details}` : message
}
/** Persistent Grok Build session over ACP stdio (`grok agent --always-approve stdio`).
* Handshake: initialize → session/new|load → session/prompt per wake.
* Mid-turn steer is not in the ACP surface Grok exposes — steer() is a no-op
* and the daemon's next-wake coalescing carries the ping instead. */
class GrokSession implements EngineSession {
private readonly child: ChildProcess
private readonly onLog: (line: string) => void
private readonly onHopUsage?: (r: EngineHopReport) => void
private outBuf = ''
private sid: string | null
private exited = false
private exitCode = 0
private reqId = 0
private initializeId: number | null = null
private sessionReqId: number | null = null
private sessionWasLoad = false
private readonly sessionNewParams: Record<string, unknown>
private ready = false
private pending: { resolve: (r: EngineRunResult) => void; id: number; startedAt: number } | null = null
private queuedPrompt: string | null = null
private steerWarned = false
private readonly model: string | null
/** The model the agent is ACTUALLY running on, as reported by the ACP stream
* (`_x.ai/models/update` → `currentModelId`). `this.model` is only the pin
* Cumora asked for, and is null whenever the operator left the model
* unpinned — which is the default. Mirrors ClaudeSession sniffing
* `message.model` off its own stream. */
private curModel: string | null = null
readonly carriesStandingPrompt: boolean
constructor(bin: string, spawnArgs: string[], home: string, env: NodeJS.ProcessEnv, opts: EngineSessionArgs) {
this.onLog = opts.onLog
this.onHopUsage = opts.onHopUsage
this.sid = opts.resumeSessionId ?? null
this.model = opts.model ?? null
this.carriesStandingPrompt = !!opts.standingPrompt
const meta: Record<string, unknown> = { yoloMode: true }
if (opts.standingPrompt) meta.rules = opts.standingPrompt
this.sessionNewParams = { cwd: home, mcpServers: [], _meta: meta }
this.sessionWasLoad = !!opts.resumeSessionId
const grokEnv: NodeJS.ProcessEnv = { ...env, GROK_DISABLE_AUTOUPDATER: env.GROK_DISABLE_AUTOUPDATER ?? '1' }
this.child = spawnEngineChild(bin, spawnArgs, { cwd: home, env: grokEnv, stdio: ['pipe', 'pipe', 'pipe'], shell: false })
this.child.stdout?.on('data', (b: Buffer) => this.onStdout(b))
this.child.stderr?.on('data', (b: Buffer) => {
for (const raw of b.toString('utf8').split('\n')) {
const l = cleanLine(raw)
if (l) this.onLog(l)
}
})
this.child.on('error', (err) => this.die(1, err.message))
this.child.on('close', (code, sig) => this.die(code ?? (sig ? 128 : 1), sig ? `terminated by ${sig}` : `exited with code ${code}`))
queueMicrotask(() => {
this.initializeId = this.req('initialize', {
protocolVersion: 1,
clientInfo: { name: 'cumora-daemon', version: '1.0.0' },
clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } },
})
})
}
get alive(): boolean { return !this.exited && this.child.stdin?.writable === true }
get sessionId(): string | null { return this.sid }
send(prompt: string): Promise<EngineRunResult> {
if (this.pending) return Promise.resolve({ exitCode: 1, error: 'engine session busy — a turn is already in flight', sessionId: this.sid })
if (!this.alive) return Promise.resolve({ exitCode: this.exitCode || 1, error: 'engine session is not alive (process gone)', sessionId: this.sid })
return new Promise<EngineRunResult>((resolve) => {
this.pending = { resolve, id: 0, startedAt: Date.now() }
if (this.ready && this.sid) this.startPrompt(prompt)
else this.queuedPrompt = prompt
})
}
steer(_text: string): void {
// ACP session/prompt is one-in-flight. A mid-turn inject would cancel the
// running turn. The daemon coalesces the ping onto the next wake instead.
if (!this.steerWarned) {
this.steerWarned = true
this.onLog('[grok] same-turn steer is not supported on ACP stdio — the ping rides the next wake')
}
}
stop(options: { force?: boolean } = {}): Promise<void> {
this.exited = true
try { this.child.stdin?.end() } catch { /* ignore */ }
return terminateEngineTree(this.child, options.force)
}
private nextId(): number { this.reqId += 1; return this.reqId }
private req(method: string, params: Record<string, unknown>): number {
const id = this.nextId()
writeStdin(this.child, JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n')
return id
}
private startPrompt(prompt: string): void {
if (!this.sid || !this.pending) return
const id = this.req('session/prompt', {
sessionId: this.sid,
prompt: [{ type: 'text', text: stripLoneSurrogates(prompt) }],
})
this.pending.id = id
}
private onStdout(buf: Buffer): void {
this.outBuf += buf.toString('utf8')
let nl: number
while ((nl = this.outBuf.indexOf('\n')) >= 0) {
const line = this.outBuf.slice(0, nl)
this.outBuf = this.outBuf.slice(nl + 1)
const t = line.trim()
if (!t.startsWith('{')) { const c = cleanLine(line); if (c) this.onLog(c); continue }
let msg: AcpMsg | null = null
try { msg = JSON.parse(t) as AcpMsg } catch { msg = null }
if (!msg) { const c = cleanLine(line); if (c) this.onLog(c); continue }
this.handle(msg)
}
}
private handle(msg: AcpMsg): void {
if (msg.id !== undefined && msg.id === this.initializeId) {
this.initializeId = null
if (msg.error) { this.failPending(String(msg.error.message || 'grok initialize failed')); return }
if (this.sessionWasLoad && this.sid) {
this.sessionReqId = this.req('session/load', { sessionId: this.sid, ...this.sessionNewParams })
} else {
this.sessionReqId = this.req('session/new', this.sessionNewParams)
}
return
}
if (msg.error && msg.id !== undefined && msg.id === this.sessionReqId) {
if (this.sessionWasLoad) {
this.onLog(`[grok] session/load failed (${String(msg.error.message || '')}) — starting a fresh session`)
this.sessionWasLoad = false
this.sid = null
this.sessionReqId = this.req('session/new', this.sessionNewParams)
return
}
this.failPending(String(msg.error.message || 'grok session start failed'))
return
}
if (msg.id !== undefined && msg.id === this.sessionReqId && msg.result) {
const sid = typeof msg.result.sessionId === 'string' ? msg.result.sessionId : this.sid
this.sessionReqId = null
if (typeof sid === 'string' && sid) this.sid = sid
this.ready = true
if (this.queuedPrompt && this.pending) {
const p = this.queuedPrompt
this.queuedPrompt = null
this.startPrompt(p)
}
return
}
// Grok announces the live model here, and again whenever it changes mid
// session. Without it the ledger prices every ACP turn on a pin that is
// usually absent (see curModel).
if (msg.method === '_x.ai/models/update') {
const id = (msg.params as { currentModelId?: unknown } | undefined)?.currentModelId
if (typeof id === 'string' && id) this.curModel = id
return
}
if (msg.method === 'session/update') {
const update = (msg.params?.update ?? msg.params?.sessionUpdate) as Record<string, unknown> | undefined
const kind = typeof update?.sessionUpdate === 'string' ? update.sessionUpdate
: typeof update?.sessionUpdate === 'undefined' && typeof (msg.params as { sessionUpdate?: unknown } | undefined)?.sessionUpdate === 'string'
? String((msg.params as { sessionUpdate?: unknown }).sessionUpdate)
: null
const u = (update ?? msg.params ?? {}) as Record<string, unknown>
const k = kind ?? (typeof u.sessionUpdate === 'string' ? u.sessionUpdate : null)
if (k === 'tool_call' && typeof u.title === 'string') this.onLog(`[grok] tool ${u.title}`)
else if (k === 'agent_message_chunk') {
const content = u.content as { text?: unknown } | undefined
if (typeof content?.text === 'string' && content.text.trim()) {
this.onLog(`[grok] » ${content.text.replace(/\s+/g, ' ').slice(0, 200)}`)
}
}
return
}
if (this.pending && msg.id !== undefined && msg.id === this.pending.id) {
if (msg.error) { this.failPending(String(msg.error.message || 'grok prompt failed')); return }
const usage = extractAcpUsage(msg.result)
if (this.onHopUsage) {
try {
this.onHopUsage({
model: this.curModel || this.model || 'grok',
usage: usage ?? {},
latencyMs: Date.now() - this.pending.startedAt,
hopIndex: 1,
})
} catch { /* never break the stream */ }
}
const p = this.pending
this.pending = null
p.resolve({ exitCode: 0, sessionId: this.sid, usage, model: this.curModel || this.model })
return
}
if (msg.error && msg.id !== undefined) {
this.failPending(String(msg.error.message || 'grok acp request failed'))
}
}
private failPending(error: string): void {
if (this.pending) {
const p = this.pending
this.pending = null
p.resolve({ exitCode: 1, error, sessionId: this.sid })
} else {
this.onLog(`[grok] ${error}`)
}
}
private die(code: number, why: string): void {
const alreadyDown = this.exited
this.exited = true
this.exitCode = code
if (!alreadyDown) {
this.onLog(`[session] engine process died ${this.pending ? 'MID-TURN' : 'while idle'}: ${why} (exit ${code})`)
}
if (this.pending) {
const p = this.pending
this.pending = null
p.resolve({ exitCode: code, error: why, sessionId: this.sid })
}
}
}
function extractAcpUsage(result: unknown): EngineUsage | undefined {
if (!result || typeof result !== 'object') return undefined
const r = result as Record<string, unknown>
const raw = (r.usage ?? (r._meta as Record<string, unknown> | undefined)?.usage) as Record<string, unknown> | undefined
if (!raw || typeof raw !== 'object') return undefined
const num = (v: unknown): number | undefined => (typeof v === 'number' && Number.isFinite(v) ? v : undefined)
const usage: EngineUsage = {
input_tokens: num(raw.input_tokens) ?? num(raw.inputTokens),
output_tokens: num(raw.output_tokens) ?? num(raw.outputTokens),
cache_read_input_tokens: num(raw.cache_read_input_tokens) ?? num(raw.cachedReadTokens) ?? num(raw.cacheReadInputTokens),
cache_creation_input_tokens: num(raw.cache_creation_input_tokens) ?? num(raw.cachedWriteTokens) ?? num(raw.cacheCreationInputTokens),
}
if (usage.input_tokens == null && usage.output_tokens == null) return undefined
return usage
}
class GrokAdapter implements EngineAdapter {
readonly id = 'grok' as const
readonly bin = 'grok'
private command(env?: NodeJS.ProcessEnv): string {
return resolveGrokBin(env) ?? resolveSpawn(this.bin, env).command
}
async classify(args: EngineClassifyArgs): Promise<EngineClassifyResult> {
const flags = extraArgs('CUMORA_TRIAGE_ARGS')
const model = ['--model', args.model || 'grok-4.5']
const command = this.command(args.env)
const { shell, wantsStdinPrompt } = resolveSpawn(this.bin, args.env)
const usingJson = flags.length === 0
const base = flags.length
? [...flags, '-p']
: ['-p', ...model, '--output-format', 'json', '--always-approve', '--no-auto-update']
const argv = wantsStdinPrompt ? base : (flags.length ? [...base, args.prompt] : ['-p', args.prompt, ...base.slice(1)])
const res = await spawnCapture(command, argv, {
cwd: args.cwd,
env: { ...args.env, GROK_DISABLE_AUTOUPDATER: args.env.GROK_DISABLE_AUTOUPDATER ?? '1' },
signal: args.signal,
onLog: args.onLog,
shell,
stdinText: wantsStdinPrompt ? args.prompt : undefined,
})
if (res.error || !usingJson) return res
try {
const obj = JSON.parse(res.text) as { text?: unknown; usage?: EngineUsage }
return {
text: typeof obj.text === 'string' ? obj.text : res.text,
usage: obj.usage && typeof obj.usage === 'object' ? obj.usage : undefined,
}
} catch {
return res
}
}
probe(args: EngineProbeArgs): Promise<EngineClassifyResult> {
const model = args.tier === 'small' ? ['--model', 'grok-4.5'] : []
const command = this.command(args.env)
const { shell, wantsStdinPrompt } = resolveSpawn(this.bin, args.env)
const base = ['-p', ...model, '--output-format', 'json', '--always-approve', '--no-auto-update']
const argv = wantsStdinPrompt ? base : ['-p', DOCTOR_PROMPT, ...base.slice(1)]
return spawnCapture(command, argv, {
cwd: args.cwd,
env: { ...args.env, GROK_DISABLE_AUTOUPDATER: args.env.GROK_DISABLE_AUTOUPDATER ?? '1' },
signal: args.signal,
shell,
stdinText: wantsStdinPrompt ? DOCTOR_PROMPT : undefined,
})
}
async probeWake(args: EngineWakeProbeArgs): Promise<EngineWakeProbeResult> {
// Same gates as startSession: custom args / opt-out / Windows collapse to
// one-shot `grok -p`, which probe() already covers.
if (extraArgs('CUMORA_GROK_ARGS').length || process.env.CUMORA_GROK_NO_ACP === '1' || IS_WIN) {
return { ok: true, detail: '', skipped: true }
}
const command = this.command(args.env)
return new Promise<EngineWakeProbeResult>((resolve) => {
let settled = false
const finish = (r: EngineWakeProbeResult) => {
if (settled) return
settled = true
try { child.stdin?.end() } catch { /* ignore */ }
void terminateEngineTree(child).then(() => resolve(r))
}
const child = spawnEngineChild(command, ['agent', '--always-approve', '--no-leader', 'stdio'], {
cwd: args.cwd,
env: { ...args.env, GROK_DISABLE_AUTOUPDATER: args.env.GROK_DISABLE_AUTOUPDATER ?? '1' },
stdio: ['pipe', 'pipe', 'pipe'],
shell: false,
})
const onAbort = () => finish({ ok: false, detail: 'aborted (timeout)' })
if (args.signal.aborted) { onAbort(); return }
args.signal.addEventListener('abort', onAbort, { once: true })
let buf = ''
let stderrTail = ''
const initId = 1
const sessionId = 2
let initialized = false
const writeRpc = (msg: object) => {
writeStdin(child, JSON.stringify(msg) + '\n')
}
writeRpc({
jsonrpc: '2.0', id: initId, method: 'initialize',
params: { protocolVersion: 1, clientInfo: { name: 'cumora-doctor', version: '1.0.0' }, clientCapabilities: {} },
})
child.stdout?.on('data', (b: Buffer) => {
buf += b.toString('utf8')
for (;;) {
const nl = buf.indexOf('\n')
if (nl < 0) break
const line = buf.slice(0, nl).trim()
buf = buf.slice(nl + 1)
if (!line.startsWith('{')) continue
let msg: AcpMsg
try { msg = JSON.parse(line) as AcpMsg } catch { continue }
if (msg.error?.message) {
finish({ ok: false, detail: `acp rejected handshake: ${String(msg.error.message).slice(0, 240)}` })
return
}
if (!initialized && msg.id === initId && msg.result) {
initialized = true
writeRpc({
jsonrpc: '2.0', id: sessionId, method: 'session/new',
params: { cwd: args.cwd, mcpServers: [], _meta: { yoloMode: true } },
})
continue
}
if (initialized && msg.id === sessionId && msg.result) {
finish({ ok: true, detail: '' })
return
}
}
})
child.stderr?.on('data', (b: Buffer) => {
const tail = stderrTail + b.toString('utf8')
stderrTail = tail.length > 2000 ? tail.slice(-2000) : tail
})
child.on('error', (err) => finish({ ok: false, detail: `spawn error: ${err.message}` }))
child.on('close', (code, sig) => {
if (settled) return
const stage = !initialized ? 'before initialize ack' : 'before session/new ack'
const exit = sig ? `terminated by ${sig}` : `exit ${code}`
finish({ ok: false, detail: `grok agent stdio died ${stage} (${exit}): ${salientError(stderrTail) || 'no stderr'}` })
})
})
}
async seedHome(home: string, persona: EnginePersona): Promise<void> {
await ensureCommonHome(home)
const agentsMd = join(home, 'AGENTS.md')
if (!(await exists(agentsMd))) await writeFile(agentsMd, PERSONA_HEADER(persona), 'utf8')
}
run(args: EngineRunArgs): Promise<EngineRunResult> {
const flags = extraArgs('CUMORA_GROK_ARGS')
const model = args.model ? ['--model', args.model] : []
const resume = args.resumeSessionId ? ['--resume', args.resumeSessionId] : []
const command = this.command(args.env)
const { shell, wantsStdinPrompt } = resolveSpawn(this.bin, args.env)
const base = flags.length
? [...flags, ...resume, '-p']
: ['-p', ...resume, ...model, '--output-format', 'streaming-messages-json', '--always-approve', '--no-auto-update']
const argv = wantsStdinPrompt ? base : (flags.length ? [...base, args.prompt] : ['-p', args.prompt, ...base.slice(1)])
const env: NodeJS.ProcessEnv = { ...args.env, GROK_DISABLE_AUTOUPDATER: args.env.GROK_DISABLE_AUTOUPDATER ?? '1' }
return spawnEngine(command, argv, { ...args, env }, { shell, stdinText: wantsStdinPrompt ? args.prompt : undefined })
}
startSession(args: EngineSessionArgs): EngineSession | null {
if (extraArgs('CUMORA_GROK_ARGS').length) return null
if (process.env.CUMORA_GROK_NO_ACP === '1') return null
// JSON-RPC over a Windows .cmd shim is the same trap Codex hits — exec
// (`grok -p`) is the safe path there.
if (IS_WIN) return null
const model = args.model ? ['--model', args.model] : []
return new GrokSession(this.command(args.env), ['agent', '--always-approve', '--no-leader', ...model, 'stdio'], args.home, args.env, args)
}
}
// ─── zcode ────────────────────────────────────────────────────────────────
//
// ZCode (the `zcode` CLI) is driven through the `zcode-acp-server` npm
// bridge, which wraps ZCode's headless app-server in the standard ACP agent
// surface (initialize / session/new / session/prompt over stdio) — the same
// wire protocol GrokSession speaks. The adapter therefore spawns
//
// node <zcode-acp-server>/dist/index.js
//
// and the bridge, not Cumora, spawns the actual `zcode` process (its PATH
// lookup, or ZCODE_BIN, decides which CLI runs — Cumora only probes `zcode`
// to decide whether the engine is installed). The bridge is a spawn-type
// dependency: it cannot be esbuild-bundled into the daemon because its whole
// job is to be a separate process tree. The npm-published package IS the
// source of truth: the daemon runs `npx -y zcode-acp-server`, so protocol
// fixes ship to operators without a daemon release, and no local checkout can
// silently shadow the published bridge. CUMORA_ZCODE_ACP_BIN pins an explicit
// entry script (a specific npm version on disk, an offline copy, or a dev
// workspace) ahead of that.
//
// Zcode is a COMPATIBILITY engine: Cumora cannot impose a verified fail-closed
// host boundary on the bridge + app-server pair (the operator's zcode login
// and permission config decide what a turn may touch), so it never auto-runs —
// pairing requires CUMORA_BYOA_ALLOW_UNSANDBOXED=1. Zcode reads its persona
// and skills natively from AGENTS.md and .agents/skills/ in the agent home.
// There is no out-of-band standing-prompt channel in the bridge, so
// carriesStandingPrompt stays false and the daemon inlines the invariant
// scaffold into each turn prompt (the Cursor/OpenCode contract).
/** Locate the zcode-acp-server bridge entry script on this machine. */
function resolveZcodeAcpSpawn(env: NodeJS.ProcessEnv): { command: string; args: string[]; shell: boolean } {
const explicit = env.CUMORA_ZCODE_ACP_BIN?.trim()
if (explicit) return { command: process.execPath, args: [explicit], shell: false }
const npx = resolveSpawn('npx')
return { command: npx.command, args: ['-y', 'zcode-acp-server'], shell: npx.shell }
}
interface ZcodeTurnOptions {
cwd: string
env: NodeJS.ProcessEnv
prompt: string
model?: string | null
signal: AbortSignal
onLog?: (line: string) => void
onHopUsage?: (r: EngineHopReport) => void
}
interface ZcodeSessionOptions extends EngineSessionArgs {
/** Assistant text chunks, streamed out for one-shot callers (classify/
* probe/run read the turn's reply text; persistent wakes only log it). */
onAgentText?: (text: string) => void
/** Aborts the session (one-shot turns only; persistent sessions rely on
* stop()). Wired to the platform tree terminator. */
signal?: AbortSignal
}
/** The bridge's backend rejects an unknown / no-longer-live zcode session with
* this phrasing (its dispatch code documents the literal: "Session is not
* active"). The shared classifier's resume patterns don't match it, so a
* resumed session that dies mid-life maps through this adapter-aware rule to
* the same fresh-retry recovery vocabulary as the other engines. */
const ZCODE_MISSING_SESSION_RE = /session is not active|no such session|unknown session/i
/** Hook surface the connection exposes upward. The connection owns only wire
* state — turn settlement stays with the session above it. */
interface AcpRpcConnectionHooks {
onLog: (line: string) => void
/** Server→client notifications; unrecognized methods are the hook's to ignore. */
onNotification: (msg: AcpMsg) => void
/** Process death, fired exactly once. In-flight rpc() calls have already
* been rejected when it fires. */
onDeath: (exitCode: number, why: string) => void
/** session/load fell back to a fresh session/new. */
onLoadFallback: (why: string) => void
}
/**
* Wire-level ACP stdio connection for one bridge process: spawn, JSON-RPC
* framing, the initialize handshake, session new/load, notification routing,
* and death. Deliberately composition (the codebase shares via helpers, not
* inheritance): turn settlement and resume classification stay with the
* session, which observes death and handshake fallback through the hooks.
*/
class AcpRpcConnection {
private readonly child: ChildProcess
private readonly sessionParams: () => Record<string, unknown>
private readonly hooks: AcpRpcConnectionHooks
private readonly signal?: AbortSignal
/** Current session id — absorbed from session/new|load responses. */
sid: string | null
/** True while the current context came from a session/load. The session
* consumes (and clears) this for the failure classifier's resume kind. */
resumed = false
private dead = false
private stopRequested = false
private exitCode = 0
private reqId = 0
/** In-flight requests awaiting their JSON-RPC response. */
private readonly waiters = new Map<number, (msg: AcpMsg) => void>()
private readonly stdoutDecoder = new StringDecoder('utf8')
private readonly stderrDecoder = new StringDecoder('utf8')
private outBuf = ''
/** Settles when the handshake completes; rejects when the handshake or the
* process itself failed. send() awaits it, and so does probeWake(). */
readonly ready: Promise<void>
constructor(
spawnSpec: { command: string; args: string[]; shell: boolean },
home: string,
env: NodeJS.ProcessEnv,
initialSid: string | null,
sessionParams: () => Record<string, unknown>,
hooks: AcpRpcConnectionHooks,
signal?: AbortSignal,
private readonly attachMethod: 'session/load' | 'session/resume' = 'session/load',
) {
this.child = spawnEngineChild(spawnSpec.command, spawnSpec.args, {
cwd: home, env, stdio: ['pipe', 'pipe', 'pipe'], shell: spawnSpec.shell,
})
this.sid = initialSid
this.sessionParams = sessionParams
this.hooks = hooks
this.signal = signal
this.child.stdout?.on('data', (b: Buffer) => this.onStdout(b))
this.child.stderr?.on('data', (b: Buffer) => {
for (const raw of this.stderrDecoder.write(b).split('\n')) {
const l = cleanLine(raw)
if (l) this.hooks.onLog(l)
}
})
this.child.on('error', (err) => this.die(1, err.message))
this.child.on('close', (code, sig) => this.die(code ?? (sig ? 128 : 1), sig ? `terminated by ${sig}` : `exited with code ${code}`))
if (this.signal) {
const abort = () => { void terminateEngineTree(this.child, true) }
if (this.signal.aborted) abort()
else this.signal.addEventListener('abort', abort, { once: true })
}
this.ready = this.handshake()
// An idle failed handshake (no send()/whenReady() consumer) must not
// become an unhandled rejection — the next send() reports it as dead.
this.ready.catch(() => {})
}
get alive(): boolean { return !this.dead && !this.stopRequested && this.child.stdin?.writable === true }
get exitStatusCode(): number { return this.exitCode }
whenReady(): Promise<void> { return this.ready }
/** One JSON-RPC request → response. Server→client notifications route to
* the onNotification hook; a dead process fails every waiter from die(). */
rpc(method: string, params: Record<string, unknown>): Promise<AcpMsg> {
if (this.dead || this.stopRequested) return Promise.reject(new Error('engine session is not alive (process gone)'))
const id = ++this.reqId
return new Promise<AcpMsg>((resolve, reject) => {
this.waiters.set(id, (msg) => {
if (msg.error) reject(new Error(acpErrorMessage(msg.error, method)))
else resolve(msg)
})
writeStdin(this.child, JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n')
})
}
/** Reply to a server→client JSON-RPC request (e.g. session/request_permission). */
reply(id: number | string, result: unknown): void {
if (this.dead || this.stopRequested) return
writeStdin(this.child, JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n')
}
stop(options: { force?: boolean } = {}): Promise<void> {
this.stopRequested = true
try { this.child.stdin?.end() } catch { /* ignore */ }
return terminateEngineTree(this.child, options.force)
}
/** initialize → session/load|resume|new. A stale resume falls back to a fresh
* session; anything else rejects `ready` and fails the pending turn. */
private async handshake(): Promise<void> {
await this.rpc('initialize', {
protocolVersion: 1,
clientInfo: { name: 'cumora-daemon', version: '1.0.0' },
clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } },
})
if (this.sid) {
try {
this.absorbSessionId(await this.rpc(this.attachMethod, { sessionId: this.sid, ...this.sessionParams() }))
this.resumed = true
return
} catch (err) {
const why = err instanceof Error ? err.message : String(err)
this.resumed = false
this.sid = null
this.hooks.onLoadFallback(why)
}
}
this.absorbSessionId(await this.rpc('session/new', this.sessionParams()))
}
private onStdout(buf: Buffer): void {
this.outBuf += this.stdoutDecoder.write(buf)
let nl: number
while ((nl = this.outBuf.indexOf('\n')) >= 0) {
const line = this.outBuf.slice(0, nl)
this.outBuf = this.outBuf.slice(nl + 1)
const t = line.trim()
if (!t.startsWith('{')) { const c = cleanLine(line); if (c) this.hooks.onLog(c); continue }
let msg: AcpMsg | null = null
try { msg = JSON.parse(t) as AcpMsg } catch { msg = null }
if (!msg) { const c = cleanLine(line); if (c) this.hooks.onLog(c); continue }
if (msg.id !== undefined && !msg.method) {
const waiter = this.waiters.get(msg.id)
if (waiter) { this.waiters.delete(msg.id); waiter(msg); continue }
}
this.hooks.onNotification(msg)
}
}
private absorbSessionId(msg: AcpMsg): void {
const sid = typeof msg.result?.sessionId === 'string' ? msg.result.sessionId : null
if (sid) this.sid = sid
}
private die(code: number, why: string): void {
const firstDeath = !this.dead
this.dead = true
this.exitCode = code
// Fail every in-flight request so rpc() callers don't hang on a dead pipe.
for (const [, waiter] of this.waiters) waiter({ error: { message: why } })
this.waiters.clear()
if (firstDeath) this.hooks.onDeath(code, why)
}
}
/** Persistent ZCode session: turn settlement, the lazy model pin, and the
* bridge's missing-session phrasing on top of a wire-level AcpRpcConnection.
* Mid-turn steer is not in the ACP surface — steer() is a no-op and the
* daemon's next-wake coalescing carries the ping (same contract as
* GrokSession). */
class ZcodeSession implements EngineSession {
readonly carriesStandingPrompt = false
private readonly conn: AcpRpcConnection
private readonly onLog: (line: string) => void
private readonly onHopUsage?: (r: EngineHopReport) => void
private readonly onAgentText?: (text: string) => void
private readonly model: string | null
private modelUnapplied: boolean
private turn: { resolve: (r: EngineRunResult) => void } | null = null
private steerWarned = false
private stopped = false
constructor(home: string, env: NodeJS.ProcessEnv, opts: ZcodeSessionOptions) {
this.onLog = opts.onLog
this.onHopUsage = opts.onHopUsage
this.onAgentText = opts.onAgentText
this.model = opts.model ?? null
this.modelUnapplied = !!opts.model
this.conn = new AcpRpcConnection(
resolveZcodeAcpSpawn(env),
home,
env,
opts.resumeSessionId ?? null,
() => ({ cwd: home, mcpServers: [] }),
{
onLog: (line) => this.onLog(line),
onNotification: (msg) => this.onUpdate(msg),
onDeath: (code, why) => this.onDeath(code, why),
onLoadFallback: (why) => {
this.onLog(`[zcode] session/load failed (${why}) — starting a fresh session`)
},
},
opts.signal,
)
}
get alive(): boolean { return this.conn.alive }
get sessionId(): string | null { return this.conn.sid }
whenReady(): Promise<void> { return this.conn.ready }
async send(prompt: string): Promise<EngineRunResult> {
if (this.turn) return classifyEngineResult({ exitCode: 1, error: 'engine session busy — a turn is already in flight', sessionId: this.conn.sid }, this.conn.resumed)
if (!this.alive) return classifyEngineResult({ exitCode: this.conn.exitStatusCode || 1, error: 'engine session is not alive (process gone)', sessionId: this.conn.sid }, this.conn.resumed)
let resolveTurn!: (r: EngineRunResult) => void
const done = new Promise<EngineRunResult>((resolve) => { resolveTurn = resolve })
// Only the first settler wins: process death (onDeath → this.turn.resolve)
// races the async body below, and whichever lands first closes the turn.
// Held in a local because onDeath() nulls this.turn when it settles first.
let settled = false
const settle = (r: EngineRunResult) => { if (!settled) { settled = true; this.turn = null; resolveTurn(r) } }
this.turn = { resolve: settle }
try {
await this.conn.ready
await this.applyModelPin()
if (!this.alive) throw new Error('engine session is not alive (process gone)')
const wasResume = this.conn.resumed
const startedAt = Date.now()
const resp = await this.conn.rpc('session/prompt', {
sessionId: this.conn.sid,
prompt: [{ type: 'text', text: stripLoneSurrogates(prompt) }],
})
this.conn.resumed = false
const usage = extractAcpUsage(resp.result) ?? undefined
if (this.onHopUsage) {
try {
this.onHopUsage({
model: this.model ?? 'zcode',
usage,
latencyMs: Date.now() - startedAt,
hopIndex: 1,
})
} catch { /* never break the stream */ }
}
settle(classifyEngineResult({ exitCode: 0, sessionId: this.conn.sid, usage, model: this.model }, wasResume))
} catch (err) {
const message = err instanceof Error ? err.message : String(err)
const wasResume = this.conn.resumed
this.conn.resumed = false
settle(this.failureResult(message, wasResume, this.conn.exitStatusCode || 1))
}
return done
}
steer(_text: string): void {
// ACP session/prompt is one-in-flight. A mid-turn inject would cancel the
// running turn. The daemon coalesces the ping onto the next wake instead.
if (!this.steerWarned) {
this.steerWarned = true
this.log('[zcode] same-turn steer is not supported on ACP stdio — the ping rides the next wake')
}
}
async stop(options: { force?: boolean } = {}): Promise<void> {
this.stopped = true
await this.conn.stop(options)
}
/** The bridge's session/new is lazy (the backend session materializes on
* first use), so the pin rides the first prompt boundary. A rejected pin
* is a preference loss, not a turn failure — log it and keep retrying on
* later wakes until the bridge accepts. */
private async applyModelPin(): Promise<void> {
if (!this.modelUnapplied || !this.model || !this.conn.sid) return
try {
await this.conn.rpc('session/set_config_option', { sessionId: this.conn.sid, configId: 'model', value: this.model })
this.modelUnapplied = false
} catch (err) {
const why = err instanceof Error ? err.message : String(err)
this.log(`[zcode] model pin rejected (${why}) — continuing on the engine default`)
}
}
/** A failed turn in the shared vocabulary. A resumed session whose backend
* went missing maps to resume-not-found (the bridge's "Session is not
* active" is not in the generic patterns); the generic classifier covers
* everything else. */
private failureResult(message: string, wasResume: boolean, exitCode = 1): EngineRunResult {
return classifyEngineResult({
exitCode,
error: message,
failure: wasResume && ZCODE_MISSING_SESSION_RE.test(message)
? { kind: 'resume-not-found', message, diagnostic: message }
: undefined,
sessionId: this.conn.sid,
}, wasResume)
}
private onDeath(code: number, why: string): void {
if (!this.stopped) {
this.log(`[session] engine process died ${this.turn ? 'MID-TURN' : 'while idle'}: ${why} (exit ${code})`)
}
const wasResume = this.conn.resumed
this.conn.resumed = false
this.turn?.resolve(this.failureResult(why, wasResume, code))
}
/** Common ACP notification surface; unrecognized update kinds are ignored,
* so a new event type in a future bridge never breaks a turn. */
private onUpdate(msg: AcpMsg): void {
if (msg.method !== 'session/update') return
const u = (msg.params?.update ?? msg.params) as Record<string, unknown> | undefined
const kind = typeof u?.sessionUpdate === 'string' ? u.sessionUpdate : null
if (kind === 'tool_call' && typeof u?.title === 'string') {
this.log(`[zcode] tool ${u.title}`)
} else if (kind === 'agent_message_chunk') {
const content = u?.content as { text?: unknown } | undefined
if (typeof content?.text === 'string' && content.text) {
this.onAgentText?.(content.text)
if (content.text.trim()) this.log(`[zcode] » ${content.text.replace(/\s+/g, ' ').slice(0, 200)}`)
}
}
}
private log(line: string): void { this.onLog(line) }
}
/** One full bridge lifecycle for the stateless paths (run/classify/probe): a
* fresh session, one turn, tear-down. Failures fold into the result — a
* missing bridge or a rejected handshake is a failed turn, not a thrown
* one. One-shot turns never resume, so hadResume stays false and the generic
* classifier still tags auth/rate-limit/overflow/transport kinds. */
async function runZcodeAcpTurn(opts: ZcodeTurnOptions): Promise<EngineRunResult & { text: string }> {
const chunks: string[] = []
const session = new ZcodeSession(opts.cwd, opts.env, {
home: opts.cwd,
env: opts.env,
model: opts.model,
standingPrompt: null,
resumeSessionId: null,
onLog: opts.onLog ?? (() => {}),
onHopUsage: opts.onHopUsage,
onAgentText: (text) => chunks.push(text),
signal: opts.signal,
})
try {
return { ...await session.send(opts.prompt), text: chunks.join('') }
} finally {
await session.stop({ force: true })
}
}
class ZcodeAdapter implements EngineAdapter {
readonly id = 'zcode' as const
readonly bin = 'zcode'
async seedHome(home: string, persona: EnginePersona): Promise<void> {
await ensureCommonHome(home)
// zcode-acp-server's skill discovery scans PROJECT skills from
// .agents/skills/ in the session cwd (the same shared directory
// Antigravity reads) — not a zcode-specific folder.
await mkdir(join(home, '.agents', 'skills'), { recursive: true })
await atomicAgentWrite(
join(home, 'AGENTS.md'),
PERSONA_HEADER(persona, { personaFile: 'AGENTS.md', skillsDir: '.agents/skills/' }),
)
}
run(args: EngineRunArgs): Promise<EngineRunResult> {
return runZcodeAcpTurn({
cwd: args.home,
env: args.env,
prompt: args.prompt,
model: args.model,
signal: args.signal,
onLog: args.onLog,
onHopUsage: args.onHopUsage,
})
}
startSession(args: EngineSessionArgs): EngineSession | null {
return new ZcodeSession(args.home, args.env, args)
}
classify(args: EngineClassifyArgs): Promise<EngineClassifyResult> {
// One fresh bridge process in the neutral triage cwd: slower than Claude's
// restricted one-shot, but the bridge has no cheaper no-tool surface.
return runZcodeAcpTurn({
cwd: args.cwd,
env: args.env,
prompt: args.prompt,
model: args.model,
signal: args.signal,
onLog: args.onLog,
})
}
probe(args: EngineProbeArgs): Promise<EngineClassifyResult> {
// Both tiers run the same bridge probe: the model catalog is the
// operator's zcode config, so there is no first-party cheap alias to pin.
return runZcodeAcpTurn({ cwd: args.cwd, env: args.env, prompt: DOCTOR_PROMPT, signal: args.signal })
}
async probeWake(args: EngineWakeProbeArgs): Promise<EngineWakeProbeResult> {
// The wake path IS the bridge handshake on every platform — never skipped.
// Run a real session against the same spawn the wake uses and wait for the
// handshake to settle, then tear down; the bridge's lazy session/new means
// the probe leaves no backend session behind.
const session = new ZcodeSession(args.cwd, args.env, {
home: args.cwd,
env: args.env,
standingPrompt: null,
resumeSessionId: null,
onLog: () => {},
signal: args.signal,
})
try {
await session.whenReady()
return { ok: true, detail: '' }
} catch (err) {
const why = args.signal.aborted
? 'aborted (timeout)'
: err instanceof Error ? err.message : String(err)
return { ok: false, detail: `zcode bridge handshake failed: ${why}`.slice(0, 240) }
} finally {
await session.stop({ force: true })
}
}
}
// ─── maka ─────────────────────────────────────────────────────────────────
// Apache Maka (`maka --acp`) ACP v1 persistent session: initialize →
// session/resume (fallback session/new) → permission_mode=bypass → session/prompt.
/** Resolve `CUMORA_MAKA_BIN` or `maka` on `env.PATH`. */
export function resolveMakaBin(env: NodeJS.ProcessEnv = process.env): string | null {
const explicit = env.CUMORA_MAKA_BIN?.trim()
if (explicit) return explicit
for (const dir of (env.PATH ?? '').split(PATH_DELIMITER)) {
if (!dir) continue
const candidate = join(dir, IS_WIN ? 'maka.cmd' : 'maka')
if (existsSync(candidate)) return candidate
if (IS_WIN && existsSync(join(dir, 'maka.exe'))) return join(dir, 'maka.exe')
if (IS_WIN && existsSync(join(dir, 'maka'))) return join(dir, 'maka')
}
return null
}
/** Locate the `maka --acp` spawn command on this machine. */
function resolveMakaAcpSpawn(env: NodeJS.ProcessEnv): { command: string; args: string[]; shell: boolean } {
const explicit = env.CUMORA_MAKA_BIN?.trim()
if (explicit) {
if (/\.[cm]?js$/i.test(explicit)) return { command: process.execPath, args: [explicit, '--acp'], shell: false }
const sp = resolveSpawn(explicit, env)
return { command: sp.command, args: ['--acp'], shell: sp.shell }
}
const sp = resolveSpawn(resolveMakaBin(env) ?? 'maka')
return { command: sp.command, args: ['--acp'], shell: sp.shell }
}
interface MakaTurnOptions {
cwd: string
env: NodeJS.ProcessEnv
prompt: string
model?: string | null
resumeSessionId?: string | null
permissionMode?: 'ask' | 'bypass'
signal: AbortSignal
onLog?: (line: string) => void
onHopUsage?: (r: EngineHopReport) => void
}
interface MakaSessionOptions extends EngineSessionArgs {
onAgentText?: (text: string) => void
signal?: AbortSignal
permissionMode?: 'ask' | 'bypass'
}
const MAKA_MISSING_SESSION_RE =
/runtime host session was not found|archived runtime host sessions cannot be loaded|session is not owned by this acp connection|cwd does not match the existing session workspace/i
class MakaSession implements EngineSession {
readonly carriesStandingPrompt = false
private readonly conn: AcpRpcConnection
private readonly onLog: (line: string) => void
private readonly onHopUsage?: (r: EngineHopReport) => void
private readonly onAgentText?: (text: string) => void
private readonly model: string | null
private readonly permissionMode: 'ask' | 'bypass'
private permissionModeUnapplied = true
private modelWarned = false
private turn: { resolve: (r: EngineRunResult) => void } | null = null
private promptInFlight = false
private steerWarned = false
private stopped = false
constructor(home: string, env: NodeJS.ProcessEnv, opts: MakaSessionOptions) {
this.onLog = opts.onLog
this.onHopUsage = opts.onHopUsage
this.onAgentText = opts.onAgentText
this.model = opts.model ?? null
this.permissionMode = opts.permissionMode ?? 'bypass'
this.conn = new AcpRpcConnection(
resolveMakaAcpSpawn(env),
home,
env,
opts.resumeSessionId ?? null,
() => ({ cwd: home, mcpServers: [] }),
{
onLog: (line) => this.onLog(line),
onNotification: (msg) => this.onUpdate(msg),
onDeath: (code, why) => this.onDeath(code, why),
onLoadFallback: (why) => {
this.onLog(`[maka] session/resume failed (${why}) — starting a fresh session`)
},
},
opts.signal,
'session/resume',
)
}
get alive(): boolean { return this.conn.alive }
get sessionId(): string | null { return this.conn.sid }
whenReady(): Promise<void> { return this.conn.ready }
async send(prompt: string): Promise<EngineRunResult> {
if (this.turn) return classifyEngineResult({ exitCode: 1, error: 'engine session busy — a turn is already in flight', sessionId: this.conn.sid }, this.conn.resumed)
if (!this.alive) return classifyEngineResult({ exitCode: this.conn.exitStatusCode || 1, error: 'engine session is not alive (process gone)', sessionId: this.conn.sid }, this.conn.resumed)
let resolveTurn!: (r: EngineRunResult) => void
const done = new Promise<EngineRunResult>((resolve) => { resolveTurn = resolve })
let settled = false
const settle = (r: EngineRunResult) => { if (!settled) { settled = true; this.turn = null; resolveTurn(r) } }
this.turn = { resolve: settle }
try {
await this.conn.ready
await this.applySessionConfig()
if (!this.alive) throw new Error('engine session is not alive (process gone)')
const wasResume = this.conn.resumed
const startedAt = Date.now()
this.promptInFlight = true
const resp = await this.conn.rpc('session/prompt', {
sessionId: this.conn.sid,
prompt: [{ type: 'text', text: stripLoneSurrogates(prompt) }],
})
this.conn.resumed = false
const stopReason = (resp.result as { stopReason?: unknown } | undefined)?.stopReason
if (stopReason === 'cancelled') {
settle(this.failureResult('maka turn was cancelled', wasResume, 1))
return done
}
const usage = extractAcpUsage(resp.result) ?? undefined
if (this.onHopUsage) {
try {
this.onHopUsage({
model: '<maka-default>',
usage,
latencyMs: Date.now() - startedAt,
hopIndex: 1,
})
} catch { /* never break the stream */ }
}
settle(classifyEngineResult({ exitCode: 0, sessionId: this.conn.sid, usage, model: '<maka-default>' }, wasResume))
} catch (err) {
const message = err instanceof Error ? err.message : String(err)
const wasResume = this.conn.resumed
this.conn.resumed = false
settle(this.failureResult(message, wasResume, this.conn.exitStatusCode || 1))
} finally {
this.promptInFlight = false
}
return done
}
steer(_text: string): void {
if (!this.steerWarned) {
this.steerWarned = true
this.log('[maka] same-turn steer is not supported on ACP stdio — the ping rides the next wake')
}
}
async stop(options: { force?: boolean } = {}): Promise<void> {
this.stopped = true
await this.conn.stop(options)
}
private async applySessionConfig(): Promise<void> {
if (!this.conn.sid) return
if (!this.modelWarned && this.model) {
this.modelWarned = true
this.log(`[maka] model pin (${this.model}) is ignored — Maka selects its model in its own settings; ACP does not expose model selection`)
}
if (this.permissionModeUnapplied) {
try {
await this.conn.rpc('session/set_config_option', {
sessionId: this.conn.sid,
configId: 'permission_mode',
value: this.permissionMode,
})
this.permissionModeUnapplied = false
} catch (err) {
const why = err instanceof Error ? err.message : String(err)
if (this.permissionMode === 'ask') {
throw new Error(`maka permission_mode=ask could not be applied: ${why}`)
}
this.log(`[maka] permission_mode pin rejected (${why}) — continuing`)
}
}
}
private failureResult(message: string, wasResume: boolean, exitCode = 1): EngineRunResult {
// The wording is Maka's own and unambiguous, so it classifies whether or not
// this turn began as a resume. Gating it on `resumed` let a session that
// disappeared AFTER a successful turn fall through as an unknown error,
// skipping recovery and leaving the connection on a stale session id.
const missingSession = MAKA_MISSING_SESSION_RE.test(message)
return classifyEngineResult({
exitCode,
error: message,
failure: missingSession
? { kind: 'resume-not-found', message, diagnostic: message }
: undefined,
sessionId: this.conn.sid,
}, wasResume)
}
private onDeath(code: number, why: string): void {
if (!this.stopped) {
this.log(`[session] engine process died ${this.turn ? 'MID-TURN' : 'while idle'}: ${why} (exit ${code})`)
}
const wasResume = this.conn.resumed
this.conn.resumed = false
this.turn?.resolve(this.failureResult(why, wasResume, code))
}
private onUpdate(msg: AcpMsg): void {
if (msg.method === 'session/request_permission' && msg.id !== undefined) {
if (this.permissionMode === 'ask') {
this.conn.reply(msg.id, { outcome: { outcome: 'cancelled' } })
return
}
const options = Array.isArray(msg.params?.options)
? msg.params.options as Array<{ optionId?: unknown; kind?: unknown }>
: []
const preferred = options.find((o) => o?.kind === 'allow_always')
?? options.find((o) => o?.kind === 'allow_once')
if (typeof preferred?.optionId === 'string' && preferred.optionId) {
this.conn.reply(msg.id, { outcome: { outcome: 'selected', optionId: preferred.optionId } })
} else {
this.conn.reply(msg.id, { outcome: { outcome: 'cancelled' } })
}
return
}
if (msg.method !== 'session/update' || !this.promptInFlight) return
const u = (msg.params?.update ?? msg.params) as Record<string, unknown> | undefined
const kind = typeof u?.sessionUpdate === 'string' ? u.sessionUpdate : null
if (kind === 'tool_call' && typeof u?.title === 'string') {
this.log(`[maka] tool ${u.title}`)
} else if (kind === 'agent_message_chunk') {
const content = u?.content as { text?: unknown } | undefined
if (typeof content?.text === 'string' && content.text) {
this.onAgentText?.(content.text)
if (content.text.trim()) this.log(`[maka] » ${content.text.replace(/\s+/g, ' ').slice(0, 200)}`)
}
}
}
private log(line: string): void { this.onLog(line) }
}
async function runMakaAcpTurn(opts: MakaTurnOptions): Promise<EngineRunResult & { text: string }> {
const chunks: string[] = []
const session = new MakaSession(opts.cwd, opts.env, {
home: opts.cwd,
env: opts.env,
model: opts.model,
standingPrompt: null,
resumeSessionId: opts.resumeSessionId ?? null,
onLog: opts.onLog ?? (() => {}),
onHopUsage: opts.onHopUsage,
onAgentText: (text) => chunks.push(text),
signal: opts.signal,
permissionMode: opts.permissionMode,
})
try {
return { ...await session.send(opts.prompt), text: chunks.join('') }
} finally {
await session.stop({ force: true })
}
}
class MakaAdapter implements EngineAdapter {
readonly id = 'maka' as const
readonly bin = 'maka'
async seedHome(home: string, persona: EnginePersona): Promise<void> {
await ensureCommonHome(home)
await mkdir(join(home, '.agents', 'skills'), { recursive: true })
await atomicAgentWrite(
join(home, 'AGENTS.md'),
PERSONA_HEADER(persona, { personaFile: 'AGENTS.md', skillsDir: '.agents/skills/' }),
)
}
run(args: EngineRunArgs): Promise<EngineRunResult> {
return runMakaAcpTurn({
cwd: args.home,
env: args.env,
prompt: args.prompt,
model: args.model,
resumeSessionId: args.resumeSessionId,
signal: args.signal,
onLog: args.onLog,
onHopUsage: args.onHopUsage,
})
}
startSession(args: EngineSessionArgs): EngineSession | null {
return new MakaSession(args.home, args.env, args)
}
classify(args: EngineClassifyArgs): Promise<EngineClassifyResult> {
return runMakaAcpTurn({
cwd: args.cwd,
env: args.env,
prompt: args.prompt,
model: args.model,
signal: args.signal,
onLog: args.onLog,
permissionMode: 'ask',
})
}
probe(args: EngineProbeArgs): Promise<EngineClassifyResult> {
return runMakaAcpTurn({
cwd: args.cwd,
env: args.env,
prompt: DOCTOR_PROMPT,
signal: args.signal,
permissionMode: 'ask',
})
}
async probeWake(args: EngineWakeProbeArgs): Promise<EngineWakeProbeResult> {
const session = new MakaSession(args.cwd, args.env, {
home: args.cwd,
env: args.env,
standingPrompt: null,
resumeSessionId: null,
onLog: () => {},
signal: args.signal,
})
try {
await session.whenReady()
return { ok: true, detail: '' }
} catch (err) {
const why = args.signal.aborted
? 'aborted (timeout)'
: err instanceof Error ? err.message : String(err)
return { ok: false, detail: `maka acp handshake failed: ${why}`.slice(0, 240) }
} finally {
await session.stop({ force: true })
}
}
}
// ─── omp ──────────────────────────────────────────────────────────────────
//
// omp (the `omp` CLI, `omp acp`) is an ACP v1 agent server over stdio:
// initialize → session/load (or session/new) → model pin → session/prompt per
// wake. Triage rides the SAME lifecycle with `--no-tools --no-session`
// appended — measured ~3.3s against `omp -p`'s 12–16s, and tool-free by
// construction, one code path instead of a second parser. `omp acp` reads
// AGENTS.md and .agents/skills from the session cwd natively; its
// `--append-system-prompt` is NOT delivered over ACP, so
// carriesStandingPrompt stays false and the daemon inlines the standing
// prompt per wake (the Cursor/OpenCode contract).
/** Resolve `CUMORA_OMP_BIN` or `omp` on `env.PATH`. */
export function resolveOmpBin(env: NodeJS.ProcessEnv = process.env): string | null {
const explicit = env.CUMORA_OMP_BIN?.trim()
if (explicit) return explicit
for (const dir of (env.PATH ?? '').split(PATH_DELIMITER)) {
if (!dir) continue
const candidate = join(dir, IS_WIN ? 'omp.cmd' : 'omp')
if (existsSync(candidate)) return candidate
if (IS_WIN && existsSync(join(dir, 'omp.exe'))) return join(dir, 'omp.exe')
if (IS_WIN && existsSync(join(dir, 'omp'))) return join(dir, 'omp')
}
return null
}
/** Locate the `omp acp` spawn command. `extraArgs` is what separates a wake
* (full tools) from triage (`--no-tools --no-session`). */
function resolveOmpAcpSpawn(env: NodeJS.ProcessEnv, extraArgs: string[]): { command: string; args: string[]; shell: boolean } {
const explicit = env.CUMORA_OMP_BIN?.trim()
if (explicit) {
if (/\.[cm]?js$/i.test(explicit)) return { command: process.execPath, args: [explicit, 'acp', ...extraArgs], shell: false }
const sp = resolveSpawn(explicit, env)
return { command: sp.command, args: ['acp', ...extraArgs], shell: sp.shell }
}
const sp = resolveSpawn(resolveOmpBin(env) ?? 'omp', env)
return { command: sp.command, args: ['acp', ...extraArgs], shell: sp.shell }
}
interface OmpTurnOptions {
cwd: string
env: NodeJS.ProcessEnv
prompt: string
model?: string | null
resumeSessionId?: string | null
signal: AbortSignal
onLog?: (line: string) => void
onHopUsage?: (r: EngineHopReport) => void
/** Stateless triage surface: `--no-tools --no-session`. */
noTools?: boolean
}
interface OmpSessionOptions extends EngineSessionArgs {
onAgentText?: (text: string) => void
signal?: AbortSignal
extraArgs?: string[]
}
/** omp names one failure two ways: `ACP session not found: <id>` when the
* attach misses, `Unsupported ACP session: <id>` from a live call on an id
* the engine no longer holds. Both ride `error.data.details`, which
* acpErrorMessage() surfaces into the classifier's input. */
const OMP_MISSING_SESSION_RE = /acp session not found|unsupported acp session/i
class OmpSession implements EngineSession {
readonly carriesStandingPrompt = false
private readonly conn: AcpRpcConnection
private readonly onLog: (line: string) => void
private readonly onHopUsage?: (r: EngineHopReport) => void
private readonly onAgentText?: (text: string) => void
private readonly model: string | null
private modelPinTried = false
private modelPinAccepted = false
private turn: { resolve: (r: EngineRunResult) => void } | null = null
private promptInFlight = false
private steerWarned = false
private stopped = false
constructor(home: string, env: NodeJS.ProcessEnv, opts: OmpSessionOptions) {
this.onLog = opts.onLog
this.onHopUsage = opts.onHopUsage
this.onAgentText = opts.onAgentText
this.model = opts.model ?? null
this.conn = new AcpRpcConnection(
resolveOmpAcpSpawn(env, opts.extraArgs ?? []),
home,
env,
opts.resumeSessionId ?? null,
() => ({ cwd: home, mcpServers: [] }),
{
onLog: (line) => this.onLog(line),
onNotification: (msg) => this.onUpdate(msg),
onDeath: (code, why) => this.onDeath(code, why),
onLoadFallback: (why) => {
this.onLog(`[omp] session/load failed (${why}) — starting a fresh session`)
},
},
opts.signal,
'session/load',
)
}
get alive(): boolean { return this.conn.alive }
get sessionId(): string | null { return this.conn.sid }
whenReady(): Promise<void> { return this.conn.ready }
async send(prompt: string): Promise<EngineRunResult> {
if (this.turn) return classifyEngineResult({ exitCode: 1, error: 'engine session busy — a turn is already in flight', sessionId: this.conn.sid }, this.conn.resumed)
if (!this.alive) return classifyEngineResult({ exitCode: this.conn.exitStatusCode || 1, error: 'engine session is not alive (process gone)', sessionId: this.conn.sid }, this.conn.resumed)
let resolveTurn!: (r: EngineRunResult) => void
const done = new Promise<EngineRunResult>((resolve) => { resolveTurn = resolve })
let settled = false
const settle = (r: EngineRunResult) => { if (!settled) { settled = true; this.turn = null; resolveTurn(r) } }
this.turn = { resolve: settle }
try {
await this.conn.ready
await this.applyModelPin()
if (!this.alive) throw new Error('engine session is not alive (process gone)')
const wasResume = this.conn.resumed
const startedAt = Date.now()
this.promptInFlight = true
const resp = await this.conn.rpc('session/prompt', {
sessionId: this.conn.sid,
prompt: [{ type: 'text', text: stripLoneSurrogates(prompt) }],
})
this.conn.resumed = false
const stopReason = (resp.result as { stopReason?: unknown } | undefined)?.stopReason
if (stopReason === 'cancelled') {
settle(this.failureResult('omp turn was cancelled', wasResume, 1))
return done
}
const usage = extractAcpUsage(resp.result) ?? undefined
const model = this.model && this.modelPinAccepted ? this.model : '<omp-default>'
if (this.onHopUsage) {
try {
this.onHopUsage({
model,
usage,
latencyMs: Date.now() - startedAt,
hopIndex: 1,
})
} catch { /* never break the stream */ }
}
settle(classifyEngineResult({ exitCode: 0, sessionId: this.conn.sid, usage, model }, wasResume))
} catch (err) {
const message = err instanceof Error ? err.message : String(err)
const wasResume = this.conn.resumed
this.conn.resumed = false
settle(this.failureResult(message, wasResume, this.conn.exitStatusCode || 1))
} finally {
this.promptInFlight = false
}
return done
}
steer(text: string): void {
// Idle means nothing to inject into: omp answers `{outcome:'promptRequired'}`,
// and the daemon's next wake already carries the ping.
if (!this.promptInFlight || !this.conn.sid) return
void this.conn.rpc('_session/steering', {
sessionId: this.conn.sid,
prompt: [{ type: 'text', text: stripLoneSurrogates(text) }],
_meta: { steering: { queue: 'steering' } },
}).catch((err: unknown) => {
// Steering is an optional extension: an older omp rejects the method, and
// an inject that loses the race to the turn's end changes nothing. Either
// way the coalesced rerun is the backstop, so warn once and stop shouting.
if (this.steerWarned) return
this.steerWarned = true
this.log(`[omp] steer rejected (${err instanceof Error ? err.message : String(err)}) — the ping rides the next wake`)
})
}
async stop(options: { force?: boolean } = {}): Promise<void> {
this.stopped = true
await this.conn.stop(options)
}
/** ONE attempt per session process. A rejection is a preference loss, not a
* turn failure: omp answers an unknown selector with `Unknown ACP model` and
* the following prompt still runs on the engine default. */
private async applyModelPin(): Promise<void> {
if (this.modelPinTried || !this.model || !this.conn.sid) return
this.modelPinTried = true
try {
await this.conn.rpc('session/set_config_option', { sessionId: this.conn.sid, configId: 'model', value: this.model })
this.modelPinAccepted = true
} catch (err) {
const why = err instanceof Error ? err.message : String(err)
this.log(`[omp] model pin (${this.model}) rejected (${why}) — continuing on the engine default`)
}
}
private failureResult(message: string, wasResume: boolean, exitCode = 1): EngineRunResult {
// omp's wording is unambiguous, so it classifies whether or not this turn
// began as a resume: a session can also disappear AFTER a successful turn,
// and gating on `resumed` would leave the connection on a stale id.
const missingSession = OMP_MISSING_SESSION_RE.test(message)
return classifyEngineResult({
exitCode,
error: message,
failure: missingSession
? { kind: 'resume-not-found', message, diagnostic: message }
: undefined,
sessionId: this.conn.sid,
}, wasResume)
}
private onDeath(code: number, why: string): void {
if (!this.stopped) {
this.log(`[session] engine process died ${this.turn ? 'MID-TURN' : 'while idle'}: ${why} (exit ${code})`)
}
const wasResume = this.conn.resumed
this.conn.resumed = false
this.turn?.resolve(this.failureResult(why, wasResume, code))
}
private onUpdate(msg: AcpMsg): void {
if (msg.method === 'session/request_permission' && msg.id !== undefined) {
const options = Array.isArray(msg.params?.options)
? msg.params.options as Array<{ optionId?: unknown; kind?: unknown }>
: []
const preferred = options.find((o) => o?.kind === 'allow_always')
?? options.find((o) => o?.kind === 'allow_once')
if (typeof preferred?.optionId === 'string' && preferred.optionId) {
this.conn.reply(msg.id, { outcome: { outcome: 'selected', optionId: preferred.optionId } })
} else {
this.conn.reply(msg.id, { outcome: { outcome: 'cancelled' } })
}
return
}
// A session/load replays the prior transcript as agent_message_chunk
// notifications; only chunks of the turn we asked for are the turn's text.
if (msg.method !== 'session/update' || !this.promptInFlight) return
const u = (msg.params?.update ?? msg.params) as Record<string, unknown> | undefined
const kind = typeof u?.sessionUpdate === 'string' ? u.sessionUpdate : null
if (kind === 'tool_call' && typeof u?.title === 'string') {
this.log(`[omp] tool ${u.title}`)
} else if (kind === 'agent_message_chunk') {
const content = u?.content as { text?: unknown } | undefined
if (typeof content?.text === 'string' && content.text) {
this.onAgentText?.(content.text)
if (content.text.trim()) this.log(`[omp] » ${content.text.replace(/\s+/g, ' ').slice(0, 200)}`)
}
}
}
private log(line: string): void { this.onLog(line) }
}
/** One full omp lifecycle for the stateless paths (run/classify/probe): a fresh
* `omp acp`, one turn, tear-down. A missing binary or a rejected handshake is a
* failed TURN, not a thrown one, so callers keep their uniform error handling. */
async function runOmpAcpTurn(opts: OmpTurnOptions): Promise<EngineRunResult & { text: string }> {
const chunks: string[] = []
const session = new OmpSession(opts.cwd, opts.env, {
home: opts.cwd,
env: opts.env,
model: opts.model,
standingPrompt: null,
resumeSessionId: opts.resumeSessionId ?? null,
onLog: opts.onLog ?? (() => {}),
onHopUsage: opts.onHopUsage,
onAgentText: (text) => chunks.push(text),
signal: opts.signal,
// `omp acp` persists a transcript even with `--no-session`, so triage leaves
// one behind per call. It stays in omp's own store on purpose: `omp gc`
// prunes that directory (retain-newest-per-cwd), and pointing --session-dir
// at a Cumora path would move the files out of reach of that sweep.
extraArgs: opts.noTools ? ['--no-tools', '--no-session'] : [],
})
try {
return { ...await session.send(opts.prompt), text: chunks.join('') }
} finally {
await session.stop({ force: true })
}
}
class OmpAdapter implements EngineAdapter {
readonly id = 'omp' as const
readonly bin = 'omp'
async seedHome(home: string, persona: EnginePersona): Promise<void> {
await ensureCommonHome(home)
// omp discovers project skills under .agents/skills/ in the session cwd and
// reads AGENTS.md from it — both measured against 18.12.6.
await mkdir(join(home, '.agents', 'skills'), { recursive: true })
await atomicAgentWrite(
join(home, 'AGENTS.md'),
PERSONA_HEADER(persona, { personaFile: 'AGENTS.md', skillsDir: '.agents/skills/' }),
)
}
run(args: EngineRunArgs): Promise<EngineRunResult> {
// Full tools: permissions raised mid-turn are auto-answered by OmpSession.
return runOmpAcpTurn({
cwd: args.home,
env: args.env,
prompt: args.prompt,
model: args.model,
resumeSessionId: args.resumeSessionId,
signal: args.signal,
onLog: args.onLog,
onHopUsage: args.onHopUsage,
})
}
startSession(args: EngineSessionArgs): EngineSession | null {
return new OmpSession(args.home, args.env, args)
}
classify(args: EngineClassifyArgs): Promise<EngineClassifyResult> {
return runOmpAcpTurn({
cwd: args.cwd,
env: args.env,
prompt: args.prompt,
model: args.model,
signal: args.signal,
onLog: args.onLog,
noTools: true,
})
}
probe(args: EngineProbeArgs): Promise<EngineClassifyResult> {
// Both tiers run the engine default: the catalog is the operator's own
// omp provider config, so there is no first-party cheap alias to pin.
return runOmpAcpTurn({
cwd: args.cwd,
env: args.env,
prompt: DOCTOR_PROMPT,
signal: args.signal,
noTools: true,
})
}
async probeWake(args: EngineWakeProbeArgs): Promise<EngineWakeProbeResult> {
// The wake path IS `omp acp` on every platform (JSON-RPC over the Windows
// .cmd shim works), so this probe is never skipped.
const session = new OmpSession(args.cwd, args.env, {
home: args.cwd,
env: args.env,
standingPrompt: null,
resumeSessionId: null,
onLog: () => {},
signal: args.signal,
})
try {
await session.whenReady()
return { ok: true, detail: '' }
} catch (err) {
const why = args.signal.aborted
? 'aborted (timeout)'
: err instanceof Error ? err.message : String(err)
return { ok: false, detail: `omp acp handshake failed: ${why}`.slice(0, 240) }
} finally {
await session.stop({ force: true })
}
}
}
// ─── cursor ───────────────────────────────────────────────────────────────
//
// Cursor Agent (the `cursor-agent` CLI bundled with Cursor, 2026.08.11-e8db854)
// is a ONE-SHOT engine: this version exposes no persistent stdio protocol, so
// there is no startSession — every wake spawns a fresh process and continuity
// comes from `--resume <session_id>`, which re-opens the SAME session id in the
// next one-shot process. The daemon's generic one-shot run() path IS the wake
// path; probeWake() therefore always reports `skipped` (probe() already
// exercises the exact spawn a wake uses).
//
// cursor-agent -p --output-format stream-json --force --trust \
// [--model X] [--resume <id>] <prompt>
//
// The stream: a `system/init` event (session id + model), user/assistant/
// thinking events, and a terminal `result` event carrying the turn's usage.
// Two contract quirks that shape this adapter:
// - A stream may report `is_error:true` with process exit 0 — that is a
// FAILED turn (model unavailable, …), so the stream decides, not the exit
// code, so the stream result is authoritative.
// - usage reports uncached input and cache reads as separate fields, matching
// Cursor's bundled `TokenUsage` schema; map them directly without folding.
// Triage/probe use the READ-ONLY `--mode ask` variant and never `--force`.
/** Cursor's result-event usage (OpenAI-ish camelCase). Its bundled TokenUsage
* schema carries uncached input and cache reads as separate counters. */
interface CursorUsage { inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number }
/** The subset of Cursor's stream-json we act on. Everything else is logged and
* ignored, so a new event type in a future Cursor never breaks a turn. */
interface CursorEvent {
type?: unknown
subtype?: unknown
session_id?: unknown
model?: unknown
is_error?: unknown
result?: unknown
usage?: CursorUsage
message?: { role?: unknown; content?: unknown }
}
/** Normalize Cursor's disjoint usage counters into EngineUsage;
* cacheWrite maps to cache_creation. */
function cursorUsageToEngineUsage(u: CursorUsage | undefined): EngineUsage | undefined {
if (!u || typeof u !== 'object') return undefined
const num = (v: unknown): number => (typeof v === 'number' && Number.isFinite(v) ? v : 0)
return {
input_tokens: num(u.inputTokens),
output_tokens: num(u.outputTokens),
cache_read_input_tokens: num(u.cacheReadTokens),
cache_creation_input_tokens: num(u.cacheWriteTokens),
}
}
/** Concatenate the text items of a Cursor message content array (same
* `{type:'text', text}` item shape Claude uses). */
function cursorTextOf(content: unknown): string {
if (!Array.isArray(content)) return ''
let out = ''
for (const item of content) {
if (!item || typeof item !== 'object') continue
const it = item as { type?: unknown; text?: unknown }
if (it.type === 'text' && typeof it.text === 'string') out += it.text
}
return out
}
/** Folds Cursor's stream-json into what the daemon wants from a turn: the
* session id (every event repeats it — resume keeps continuity across the
* per-wake processes), the model from `system/init` (or the pin when the
* stream never names one), the normalized turn usage, the concatenated
* assistant text (triage reads it), and the result event's error. ONE
* turn-level EngineHopReport fires at the `result` event — Cursor reports
* usage once per turn, so emitting per assistant message would double-count. */
class CursorTurnTracker {
sessionId: string | null = null
model: string | null
usage: EngineUsage | undefined
text = ''
error: string | null = null
sawResult = false
private startedAt: number | null = null
constructor(
pin: string | null,
private readonly onHopUsage?: (r: EngineHopReport) => void,
) {
this.model = pin
}
/** Feed one event. Returns true when the event terminates the turn. */
observe(ev: CursorEvent): boolean {
if (typeof ev.session_id === 'string' && ev.session_id) this.sessionId = ev.session_id
if (ev.type === 'system' && ev.subtype === 'init') {
// init's model is what Cursor actually opened the session on — it wins
// over the pin (which is only what we asked for).
if (typeof ev.model === 'string' && ev.model) this.model = ev.model
if (this.startedAt == null) this.startedAt = Date.now()
return false
}
if (ev.type === 'assistant') {
this.text += cursorTextOf(ev.message?.content)
return false
}
if (ev.type === 'result') {
this.sawResult = true
this.usage = cursorUsageToEngineUsage(ev.usage)
if (ev.is_error === true) {
this.error = typeof ev.result === 'string' && ev.result
? ev.result
: `cursor turn error${typeof ev.subtype === 'string' ? ` (${ev.subtype})` : ''}`
}
// The single turn-level hop — Cursor has no per-message usage, so this
// is the honest granularity (same contract as Codex's turn-completed).
if (ev.is_error !== true && this.usage && this.model && this.onHopUsage) {
const startedAt = this.startedAt
try {
this.onHopUsage({
model: this.model,
usage: this.usage,
latencyMs: startedAt != null ? Date.now() - startedAt : undefined,
hopIndex: 1,
textChars: this.text.length,
})
} catch { /* ledger best-effort — never break the stream */ }
}
return true
}
return false
}
}
/** Parse one stdout line of Cursor's stream-json. Non-JSON lines (banners,
* warnings that land on stdout) come back null and are logged verbatim. */
function parseCursorLine(line: string): CursorEvent | null {
if (!line.startsWith('{')) return null
try { return JSON.parse(line) as CursorEvent } catch { return null }
}
/** One-shot `cursor-agent -p --output-format stream-json …`: spawn, fold the
* stream through a CursorTurnTracker, resolve on exit. The tracker's error is
* folded into the result because a Cursor stream reports failure via
* `is_error:true` regardless of the process exit code. Text is the
* concatenated assistant text — what classify()/probe() want. */
function spawnCursorStream(
command: string,
args: string[],
opts: {
cwd: string
env: NodeJS.ProcessEnv
signal: AbortSignal
onLog?: (line: string) => void
shell: boolean
stdinText?: string
onHopUsage?: (r: EngineHopReport) => void
/** Model pin, used as the tracker's model until system/init names one. */
pin?: string | null
/** Fail a clean-exiting stream that never emitted its terminal `result`
* event (run(): a turn that never finished is not a success). classify()
* and probe() settle for whatever text arrived. */
requireResult?: boolean
},
): Promise<EngineRunResult & { text: string }> {
return new Promise((resolve) => {
const tracker = new CursorTurnTracker(opts.pin ?? null, opts.onHopUsage)
const child = spawnEngineChild(command, args, {
cwd: opts.cwd, env: opts.env,
stdio: [opts.stdinText != null ? 'pipe' : 'ignore', 'pipe', 'pipe'],
shell: opts.shell,
})
if (opts.stdinText != null) {
writeStdin(child, opts.stdinText, { end: true })
}
const abort = bindAbortTermination(child, opts.signal)
const stderrTail: string[] = []
const stdoutTail: string[] = []
const decoder: Record<'stdout' | 'stderr', StringDecoder> = {
stdout: new StringDecoder('utf8'),
stderr: new StringDecoder('utf8'),
}
const carry: Record<'stdout' | 'stderr', string> = { stdout: '', stderr: '' }
const takeLine = (stream: 'stdout' | 'stderr', raw: string): void => {
const line = cleanLine(raw)
if (!line) return
pushTail(stream === 'stderr' ? stderrTail : stdoutTail, line)
opts.onLog?.(line)
if (stream === 'stdout') {
const ev = parseCursorLine(line)
if (ev) tracker.observe(ev)
}
}
const pump = (stream: 'stdout' | 'stderr', buf: Buffer | null): void => {
const text = buf === null ? decoder[stream].end() : decoder[stream].write(buf)
const lines = (carry[stream] + text).split('\n')
carry[stream] = buf === null ? '' : (lines.pop() ?? '')
for (const line of lines) takeLine(stream, line)
}
child.stdout?.on('data', (buf: Buffer) => pump('stdout', buf))
child.stderr?.on('data', (buf: Buffer) => pump('stderr', buf))
let settled = false
child.on('error', (err) => {
if (settled) return
settled = true
abort.dispose()
void abort.wait().then(() => {
resolve({ exitCode: 1, error: err instanceof Error ? err.message : String(err), sessionId: null, text: '' })
})
})
child.on('close', (code, signalName) => {
if (settled) return
settled = true
abort.dispose()
void abort.wait().then(() => {
pump('stdout', null)
pump('stderr', null)
const procExit = code ?? (signalName ? 128 : 1)
// The stream is the truth: is_error:true fails the turn even on exit 0.
const streamError = tracker.error
? `engine turn error: ${tracker.error.slice(0, MAX_FAILURE_CHARS)}`
: (opts.requireResult && !tracker.sawResult
? 'engine stream ended without a result event (cursor-agent exited early)'
: null)
const exitCode = procExit !== 0 ? procExit : (streamError ? 1 : 0)
const error = procExit !== 0
? failurePreview({ exitCode: procExit, signalName, stderr: stderrTail, stdout: stdoutTail })
: streamError ?? undefined
resolve({ exitCode, error, sessionId: tracker.sessionId, usage: tracker.usage, model: tracker.model, text: tracker.text })
})
})
})
}
class CursorAdapter implements EngineAdapter {
readonly id = 'cursor' as const
readonly bin = 'cursor-agent'
/** A turn: full-tools one-shot (`--force` auto-approves the agent's tool use
* inside its dedicated, user-owned home — the Cursor analogue of Claude's
* --dangerously-skip-permissions), `--trust` skips the workspace-trust
* prompt a headless spawn can't answer. The prompt is the LAST argv element
* (Cursor takes it positionally); on Windows it travels via stdin instead. */
private turn(prompt: string, args: {
cwd: string
env: NodeJS.ProcessEnv
signal: AbortSignal
onLog?: (line: string) => void
model?: string | null
resumeSessionId?: string | null
onHopUsage?: (r: EngineHopReport) => void
}): Promise<EngineRunResult & { text: string }> {
const { command, shell, wantsStdinPrompt } = resolveSpawn(this.bin)
const model = args.model ? ['--model', args.model] : []
// Continuous context across wakes: --resume re-opens the prior session in
// this fresh one-shot process (Cursor has no persistent protocol to keep
// warm instead).
const resume = args.resumeSessionId ? ['--resume', args.resumeSessionId] : []
const base = ['-p', ...resume, ...model, '--output-format', 'stream-json', '--force', '--trust']
return spawnCursorStream(command, wantsStdinPrompt ? base : [...base, prompt], {
cwd: args.cwd, env: args.env, signal: args.signal, onLog: args.onLog, shell,
stdinText: wantsStdinPrompt ? prompt : undefined,
onHopUsage: args.onHopUsage,
pin: args.model ?? null,
requireResult: true,
})
}
/** The READ-ONE triage/probe shape: `--mode ask` keeps the agent Q&A-only
* (no edits, no shell), so classification can never mutate anything. Never
* `--force` here. */
private ask(prompt: string, args: {
cwd: string
env: NodeJS.ProcessEnv
signal: AbortSignal
onLog?: (line: string) => void
model?: string | null
}): Promise<EngineRunResult & { text: string }> {
const { command, shell, wantsStdinPrompt } = resolveSpawn(this.bin)
const model = args.model ? ['--model', args.model] : []
const base = ['--mode', 'ask', '-p', '--output-format', 'stream-json', ...model, '--trust']
return spawnCursorStream(command, wantsStdinPrompt ? base : [...base, prompt], {
cwd: args.cwd, env: args.env, signal: args.signal, onLog: args.onLog, shell,
stdinText: wantsStdinPrompt ? prompt : undefined,
pin: args.model ?? null,
})
}
async classify(args: EngineClassifyArgs): Promise<EngineClassifyResult> {
const flags = extraArgs('CUMORA_TRIAGE_ARGS')
if (flags.length) {
// User-owned triage flag set → plain print mode, raw text back (the same
// override discipline the other engines share; no stream to fold).
const { command, shell, wantsStdinPrompt } = resolveSpawn(this.bin)
const base = [...flags, '-p']
return spawnCapture(command, wantsStdinPrompt ? base : [...base, args.prompt], {
cwd: args.cwd, env: args.env, signal: args.signal, onLog: args.onLog, shell,
stdinText: wantsStdinPrompt ? args.prompt : undefined,
})
}
// Cursor has no fixed cheap cerebellum id (its models are account-gated
// aliases); unset CUMORA_TRIAGE_MODEL → Cursor's default ('Auto'), honestly
// reported back by the stream's system/init for the ledger.
const r = await this.ask(args.prompt, { cwd: args.cwd, env: args.env, signal: args.signal, onLog: args.onLog, model: args.model })
return { text: r.text, error: r.error, usage: r.usage, model: r.model }
}
async probe(args: EngineProbeArgs): Promise<EngineClassifyResult> {
// 'small' → whatever triage runs on (CUMORA_TRIAGE_MODEL, else Cursor's
// default — the same model as 'big', honestly reported as such); 'big' →
// Cursor's default. Read-only ask mode either way.
const model = args.tier === 'small' ? (process.env.CUMORA_TRIAGE_MODEL || null) : null
const r = await this.ask(DOCTOR_PROMPT, { cwd: args.cwd, env: args.env, signal: args.signal, model })
return { text: r.text, error: r.error, usage: r.usage, model: r.model }
}
probeWake(_args: EngineWakeProbeArgs): Promise<EngineWakeProbeResult> {
// There is no distinct wake path to probe: no persistent protocol in this
// cursor-agent version, so the wake is the SAME one-shot spawn probe()
// already exercises. Mark skipped so doctor hides the redundant line.
return Promise.resolve({ ok: true, detail: '', skipped: true })
}
async seedHome(home: string, persona: EnginePersona): Promise<void> {
await ensureCommonHome(home)
await mkdir(join(home, '.cursor', 'skills'), { recursive: true })
// Always rewrite AGENTS.md so persona edits land without requiring a fresh
// home (matches Claude and Codex). Cursor discovers AGENTS.md from its cwd.
await writeFile(
join(home, 'AGENTS.md'),
PERSONA_HEADER(persona, { personaFile: 'AGENTS.md', skillsDir: '.cursor/skills/' }),
'utf8',
)
}
async run(args: EngineRunArgs): Promise<EngineRunResult> {
const flags = extraArgs('CUMORA_CURSOR_ARGS')
if (flags.length) {
// Whole user-owned flag override → opaque print mode (same escape hatch
// as CUMORA_CLAUDE_ARGS / CUMORA_CODEX_ARGS / CUMORA_GROK_ARGS): we can't
// assume the stream-json shape, so no usage/hop ledger — but keep
// --resume + -p + prompt so session continuity survives the override.
const resume = args.resumeSessionId ? ['--resume', args.resumeSessionId] : []
const { command, shell, wantsStdinPrompt } = resolveSpawn(this.bin)
const base = [...flags, ...resume, '-p']
return spawnEngine(command, wantsStdinPrompt ? base : [...base, args.prompt], args, { shell, stdinText: wantsStdinPrompt ? args.prompt : undefined })
}
return this.turn(args.prompt, {
cwd: args.home, env: args.env, signal: args.signal, onLog: args.onLog,
model: args.model, resumeSessionId: args.resumeSessionId, onHopUsage: args.onHopUsage,
})
}
// No startSession: Cursor exposes no persistent stdio protocol in this
// version — the daemon runs the one-shot path above per wake and resumes
// the session id it reports (see the section note).
}
// ─── opencode ────────────────────────────────────────────────────────────
//
// OpenCode (the `opencode` CLI, contract verified against v1.18.20) is a
// ONE-SHOT engine in Cumora. `opencode run --format json` starts a process for
// one wake and emits JSONL events; continuity comes from passing the emitted
// `sessionID` back through `--session <id>` on the next wake. OpenCode has an
// ACP server, but that protocol is intended for editor clients and does not buy
// us the daemon's standing-prompt/session semantics, so the supported path is
// the documented `run` interface.
//
// opencode run --format json --auto [--model provider/model]
// [--session <id>] # prompt always travels via stdin
//
// A `step_finish` event is one provider hop. Its token fields are already
// disjoint (uncached input, output, reasoning, cache read/write), so the
// adapter can report honest per-hop ledger rows and sum them for the turn.
// OpenCode's event loop can race the terminal `session.status=idle` event and
// omit the final step_finish even after a successful run, so process exit 0 is
// authoritative; accounting is best-effort rather than a completion gate.
// OpenCode's JSON stream does not currently include the resolved model when no
// pin is supplied; in that case the hop uses the explicit `opencode` fallback
// label rather than inventing a provider/model id.
//
// Full turns use `--auto` because the daemon is headless and the agent's home is
// operator-owned. Triage/doctor deliberately do NOT: they select an injected
// `cumora-triage` agent whose wildcard permission is `deny`, giving the small
// brain a hard, tool-free boundary even if the user's normal OpenCode agent is
// configured to allow shell or edits.
interface OpenCodeTokens {
input?: unknown
output?: unknown
reasoning?: unknown
cache?: { read?: unknown; write?: unknown }
}
interface OpenCodePart {
type?: unknown
text?: unknown
tokens?: OpenCodeTokens
}
interface OpenCodeEvent {
type?: unknown
sessionID?: unknown
part?: OpenCodePart
error?: unknown
}
function openCodeUsage(tokens: OpenCodeTokens | undefined): EngineUsage | undefined {
if (!tokens || typeof tokens !== 'object') return undefined
const num = (value: unknown): number =>
typeof value === 'number' && Number.isFinite(value) ? Math.max(0, value) : 0
return {
input_tokens: num(tokens.input),
// OpenCode keeps reasoning separate from ordinary output; Cumora's common
// usage shape prices both as output tokens, so fold them together here.
output_tokens: num(tokens.output) + num(tokens.reasoning),
cache_read_input_tokens: num(tokens.cache?.read),
cache_creation_input_tokens: num(tokens.cache?.write),
}
}
function addEngineUsage(total: EngineUsage | undefined, next: EngineUsage): EngineUsage {
return {
input_tokens: (total?.input_tokens ?? 0) + (next.input_tokens ?? 0),
output_tokens: (total?.output_tokens ?? 0) + (next.output_tokens ?? 0),
cache_read_input_tokens: (total?.cache_read_input_tokens ?? 0) + (next.cache_read_input_tokens ?? 0),
cache_creation_input_tokens: (total?.cache_creation_input_tokens ?? 0) + (next.cache_creation_input_tokens ?? 0),
}
}
function objectRecord(value: unknown): value is Record<string, unknown> {
return !!value && typeof value === 'object' && !Array.isArray(value)
}
function openCodeErrorText(value: unknown): string {
if (typeof value === 'string') return value
if (!objectRecord(value)) return value == null ? 'unknown OpenCode error' : String(value)
const data = objectRecord(value.data) ? value.data : null
for (const candidate of [data?.message, value.message, value.name]) {
if (typeof candidate === 'string' && candidate.trim()) return candidate.trim()
}
try { return JSON.stringify(value) } catch { return 'unknown OpenCode error' }
}
/** Fold OpenCode's JSONL into the common turn/result shape. */
class OpenCodeTurnTracker {
sessionId: string | null = null
model: string | null
usage: EngineUsage | undefined
text = ''
error: string | null = null
private hopStartedAt: number | null = null
private hopIndex = 0
private hopTextChars = 0
private hopToolUses = 0
constructor(
pin: string | null,
private readonly onHopUsage?: (report: EngineHopReport) => void,
) {
this.model = pin
}
observe(event: OpenCodeEvent): void {
if (typeof event.sessionID === 'string' && event.sessionID) this.sessionId = event.sessionID
if (event.type === 'error') {
this.error = openCodeErrorText(event.error)
return
}
if (event.type === 'step_start') {
this.hopStartedAt = Date.now()
this.hopTextChars = 0
this.hopToolUses = 0
return
}
if (event.type === 'text' && typeof event.part?.text === 'string') {
this.text += event.part.text
this.hopTextChars += event.part.text.length
return
}
if (event.type === 'tool_use') {
this.hopToolUses += 1
return
}
if (event.type !== 'step_finish') return
const hopUsage = openCodeUsage(event.part?.tokens)
if (!hopUsage) return
this.usage = addEngineUsage(this.usage, hopUsage)
this.hopIndex += 1
if (this.onHopUsage) {
try {
this.onHopUsage({
model: this.model ?? 'opencode',
usage: hopUsage,
latencyMs: this.hopStartedAt == null ? undefined : Date.now() - this.hopStartedAt,
hopIndex: this.hopIndex,
toolUses: this.hopToolUses,
textChars: this.hopTextChars,
})
} catch { /* ledger reporting is best-effort */ }
}
this.hopStartedAt = null
this.hopTextChars = 0
this.hopToolUses = 0
}
}
function parseOpenCodeLine(line: string): OpenCodeEvent | null {
if (!line.startsWith('{')) return null
try { return JSON.parse(line) as OpenCodeEvent } catch { return null }
}
/** Reuse the battle-tested one-shot process pump (UTF-8/chunk boundaries,
* abort handling, bounded failure tails) while folding each complete stdout
* line through the OpenCode tracker. */
async function spawnOpenCodeStream(
command: string,
argv: string[],
opts: {
cwd: string
env: NodeJS.ProcessEnv
prompt: string
signal: AbortSignal
onLog?: (line: string) => void
shell: boolean
onHopUsage?: (report: EngineHopReport) => void
pin?: string | null
},
): Promise<EngineRunResult & { text: string }> {
const tracker = new OpenCodeTurnTracker(opts.pin ?? null, opts.onHopUsage)
let processResult: EngineRunResult
try {
processResult = await spawnEngine(
command,
argv,
{
home: opts.cwd,
prompt: opts.prompt,
env: opts.env,
onLog: (line) => {
opts.onLog?.(line)
},
signal: opts.signal,
},
{
shell: opts.shell,
stdinText: opts.prompt,
// OpenCode's JSONL protocol is stdout-only. Stderr remains visible in
// logs and process-failure previews, but must never contribute usage,
// session state, or a stream-level provider error.
onStdoutLine: (line) => {
const event = parseOpenCodeLine(line)
if (event) tracker.observe(event)
},
},
)
} catch (err) {
return {
exitCode: 1,
error: err instanceof Error ? err.message : String(err),
sessionId: tracker.sessionId,
usage: tracker.usage,
model: tracker.model,
text: tracker.text,
}
}
const eventError = tracker.error
? `engine turn error: ${tracker.error.slice(0, MAX_FAILURE_CHARS)}`
: null
const streamError = eventError
const exitCode = processResult.exitCode !== 0 ? processResult.exitCode : (streamError ? 1 : 0)
return {
exitCode,
// A real process failure (auth, quota, bad flag, abort) is more useful than
// the secondary fact that its stream never reached step_finish. Promote a
// stream-only error only when the process itself exited cleanly. If the
// JSON stream also carried a provider error, append its decoded prose so
// stale-session/rate-limit recovery can match it without parsing JSON.
error: processResult.exitCode !== 0
? [processResult.error, eventError].filter(Boolean).join('\n')
: (streamError ?? undefined),
sessionId: tracker.sessionId,
usage: tracker.usage,
model: tracker.model,
text: tracker.text,
}
}
const OPENCODE_TRIAGE_AGENT = 'cumora-triage'
/** Inject a reserved, tool-free agent as the final inline config layer while
* preserving any provider/plugin config the operator already supplied there. */
function openCodeTriageEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
let inline: Record<string, unknown> = {}
const raw = env.OPENCODE_CONFIG_CONTENT?.trim()
if (raw) {
let parsed: unknown
try { parsed = JSON.parse(raw) }
catch (err) {
throw new Error(`OPENCODE_CONFIG_CONTENT is not valid JSON: ${err instanceof Error ? err.message : String(err)}`)
}
if (!objectRecord(parsed)) throw new Error('OPENCODE_CONFIG_CONTENT must be a JSON object')
inline = parsed
}
const agents = objectRecord(inline.agent) ? inline.agent : {}
return {
...env,
OPENCODE_CONFIG_CONTENT: JSON.stringify({
...inline,
agent: {
...agents,
[OPENCODE_TRIAGE_AGENT]: {
description: 'Cumora local small-brain classifier (tool-free)',
mode: 'primary',
prompt: 'Answer the user directly. Do not call tools or modify anything.',
permission: { '*': 'deny' },
},
},
}),
}
}
class OpenCodeAdapter implements EngineAdapter {
readonly id = 'opencode' as const
readonly bin = 'opencode'
private turn(prompt: string, args: {
cwd: string
env: NodeJS.ProcessEnv
signal: AbortSignal
onLog?: (line: string) => void
model?: string | null
resumeSessionId?: string | null
onHopUsage?: (report: EngineHopReport) => void
}): Promise<EngineRunResult & { text: string }> {
const { command, shell } = resolveSpawn(this.bin)
const model = args.model ? ['--model', args.model] : []
const resume = args.resumeSessionId ? ['--session', args.resumeSessionId] : []
return spawnOpenCodeStream(
command,
['run', '--format', 'json', '--auto', ...resume, ...model],
{
cwd: args.cwd,
env: args.env,
prompt,
signal: args.signal,
onLog: args.onLog,
shell,
onHopUsage: args.onHopUsage,
pin: args.model ?? null,
},
)
}
private ask(prompt: string, args: {
cwd: string
env: NodeJS.ProcessEnv
signal: AbortSignal
onLog?: (line: string) => void
model?: string | null
}): Promise<EngineRunResult & { text: string }> {
const { command, shell } = resolveSpawn(this.bin)
const model = args.model ? ['--model', args.model] : []
return spawnOpenCodeStream(
command,
['run', '--format', 'json', '--agent', OPENCODE_TRIAGE_AGENT, ...model],
{
cwd: args.cwd,
env: openCodeTriageEnv(args.env),
prompt,
signal: args.signal,
onLog: args.onLog,
shell,
pin: args.model ?? null,
},
)
}
async classify(args: EngineClassifyArgs): Promise<EngineClassifyResult> {
const flags = extraArgs('CUMORA_TRIAGE_ARGS')
if (flags.length) {
// User-owned output flags remain an escape hatch, but the reserved agent
// is appended last so the triage process stays tool-free.
const { command, shell } = resolveSpawn(this.bin)
return spawnCapture(command, ['run', ...flags, '--agent', OPENCODE_TRIAGE_AGENT], {
cwd: args.cwd,
env: openCodeTriageEnv(args.env),
signal: args.signal,
onLog: args.onLog,
shell,
stdinText: args.prompt,
})
}
const result = await this.ask(args.prompt, {
cwd: args.cwd,
env: args.env,
signal: args.signal,
onLog: args.onLog,
model: args.model,
})
return { text: result.text, error: result.error, usage: result.usage, model: result.model }
}
async probe(args: EngineProbeArgs): Promise<EngineClassifyResult> {
// OpenCode has no universal cheap model alias: provider/model ids are
// operator-specific. The small tier honors CUMORA_TRIAGE_MODEL; otherwise
// both probes use the operator's configured default.
const model = args.tier === 'small' ? (process.env.CUMORA_TRIAGE_MODEL?.trim() || null) : null
const result = await this.ask(DOCTOR_PROMPT, {
cwd: args.cwd,
env: args.env,
signal: args.signal,
model,
})
return { text: result.text, error: result.error, usage: result.usage, model: result.model }
}
probeWake(_args: EngineWakeProbeArgs): Promise<EngineWakeProbeResult> {
// The real wake is the same one-shot `opencode run` shape probe() already
// exercises; --session only adds continuity, not a second protocol.
return Promise.resolve({ ok: true, detail: '', skipped: true })
}
async seedHome(home: string, persona: EnginePersona): Promise<void> {
await ensureCommonHome(home)
await mkdir(join(home, '.opencode', 'skills'), { recursive: true })
await writeFile(
join(home, 'AGENTS.md'),
PERSONA_HEADER(persona, { personaFile: 'AGENTS.md', skillsDir: '.opencode/skills/' }),
'utf8',
)
}
async run(args: EngineRunArgs): Promise<EngineRunResult> {
const flags = extraArgs('CUMORA_OPENCODE_ARGS')
if (flags.length) {
// Whole user-owned run-flag override: output becomes opaque, but preserve
// the session id and stdin prompt so continuity and Windows safety remain.
const resume = args.resumeSessionId ? ['--session', args.resumeSessionId] : []
const { command, shell } = resolveSpawn(this.bin)
return spawnEngine(command, ['run', ...flags, ...resume], args, { shell, stdinText: args.prompt })
}
return this.turn(args.prompt, {
cwd: args.home,
env: args.env,
signal: args.signal,
onLog: args.onLog,
model: args.model,
resumeSessionId: args.resumeSessionId,
onHopUsage: args.onHopUsage,
})
}
// No startSession: the documented headless contract is one `run` process per
// wake; --session re-opens the same conversation in that fresh process.
}
// ─── pi ──────────────────────────────────────────────────────────────────
//
// pi (https://pi.dev, npm `@earendil-works/pi-coding-agent`) is a multi-provider
// terminal coding agent. Two headless modes matter here, and they share ONE
// event stream (pi's AgentSessionEvent JSONL):
// - `pi --mode json …` one-shot: a `session` header line, then events, exit.
// - `pi --mode rpc` persistent: JSON commands on stdin (`prompt`, `steer`,
// `abort`, `get_state`, …), `response` frames + the same
// events on stdout. LF-delimited on both sides.
// A turn is finished at `agent_settled` — NOT `agent_end`, which pi can follow
// with an automatic retry / queued continuation. Model failures do NOT change
// the process exit code in json/rpc mode: they surface as an assistant message
// with `stopReason: "error" | "aborted"` + `errorMessage`, so we read the stream,
// not the exit status. Verified against pi 0.83.0.
const PI_LOG_RAW = process.env.CUMORA_PI_VERBOSE === '1'
/** pi's per-message token usage (`@earendil-works/pi-ai` Usage). `input`
* EXCLUDES the cache-read portion — the same convention as Anthropic's
* input_tokens — so it maps 1:1 onto the Claude-shaped EngineUsage the daemon
* already prices (cacheWrite ↔ cache_creation, cacheRead ↔ cache_read). */
interface PiUsage { input?: number; output?: number; cacheRead?: number; cacheWrite?: number }
interface PiMessage {
role?: unknown
model?: unknown
usage?: PiUsage
stopReason?: unknown
errorMessage?: unknown
content?: unknown
}
/** The subset of pi's stream we act on (json + rpc). Everything else is logged
* and ignored, so a new event type in a future pi never breaks a turn. */
interface PiEvent {
type?: unknown
id?: unknown
command?: unknown
success?: unknown
error?: unknown
message?: PiMessage
data?: { sessionId?: unknown }
willRetry?: unknown
messages?: unknown
}
/** Streaming deltas: one line per token / per tool-output chunk. Never logged or
* kept in the failure tail unless CUMORA_PI_VERBOSE=1 — the same fire-hose gate
* Codex has (CUMORA_CODEX_VERBOSE). */
function isNoisyPiEvent(ev: PiEvent): boolean {
return !PI_LOG_RAW && (ev.type === 'message_update' || ev.type === 'tool_execution_update')
}
/** What to log for one pi event. `turn_end` / `agent_end` embed the full
* message list (the whole transcript slice) — collapse those to a one-liner so a
* long turn doesn't dump kilobytes into the daemon log per hop; every other
* event is logged verbatim (message_end included: that's the useful one). */
function piLogLine(ev: PiEvent, raw: string): string {
if (PI_LOG_RAW) return raw
if (ev.type === 'agent_end') return `[pi] agent_end (${Array.isArray(ev.messages) ? ev.messages.length : '?'} messages, willRetry=${ev.willRetry === true})`
if (ev.type === 'turn_end') return '[pi] turn_end'
return raw
}
function piUsageToEngineUsage(u: PiUsage | undefined): EngineUsage | undefined {
if (!u || typeof u !== 'object') return undefined
return {
input_tokens: Number(u.input ?? 0) || 0,
output_tokens: Number(u.output ?? 0) || 0,
cache_read_input_tokens: Number(u.cacheRead ?? 0) || 0,
cache_creation_input_tokens: Number(u.cacheWrite ?? 0) || 0,
}
}
/** pi content items are `{type:'text'|'thinking'|'toolCall', …}` — the same
* question countAssistantContent answers for Claude (did this hop's spend go
* into tool routing or prose?), with pi's spelling of the tool item. */
function countPiContent(content: unknown): { toolUses: number; textChars: number } {
if (!Array.isArray(content)) return { toolUses: 0, textChars: 0 }
let toolUses = 0, textChars = 0
for (const item of content) {
if (!item || typeof item !== 'object') continue
const it = item as { type?: unknown; text?: unknown }
if (it.type === 'toolCall') toolUses += 1
else if (it.type === 'text' && typeof it.text === 'string') textChars += it.text.length
}
return { toolUses, textChars }
}
function piTextOf(content: unknown): string {
if (!Array.isArray(content)) return ''
let out = ''
for (const item of content) {
if (!item || typeof item !== 'object') continue
const it = item as { type?: unknown; text?: unknown }
if (it.type === 'text' && typeof it.text === 'string') out += it.text
}
return out
}
/** Folds pi's event stream into what the daemon wants from a turn: the real
* session id, ONE EngineHopReport per assistant message, the turn's summed
* usage + last model (for the run row — pi has no Claude-style `result` total),
* the assistant's final text (triage reads it), and the first hard error.
* Shared by the persistent PiSession and the one-shot json spawn so both paths
* ledger identically — the same split CursorTurnTracker serves for Cursor. */
class PiTurnTracker {
sessionId: string | null = null
model: string | null = null
usage: EngineUsage | undefined
text = ''
error: string | null = null
private hopIndex = 0
private hopStartedAt: number | null = null
constructor(private readonly onHopUsage?: (r: EngineHopReport) => void) {}
/** Reset the per-turn accumulators (a persistent session runs many turns). */
beginTurn(): void {
this.usage = undefined
this.text = ''
this.error = null
this.hopIndex = 0
this.hopStartedAt = null
}
/** Feed one event. Returns true when the event terminates the turn. */
observe(ev: PiEvent): boolean {
if (ev.type === 'session') {
if (typeof ev.id === 'string' && ev.id) this.sessionId = ev.id
return false
}
// An assistant message begins streaming = one outbound model call begins.
if (ev.type === 'message_start' && ev.message?.role === 'assistant' && this.hopStartedAt == null) {
this.hopStartedAt = Date.now()
return false
}
if (ev.type === 'message_end' && ev.message?.role === 'assistant') {
const m = ev.message
const model = typeof m.model === 'string' && m.model ? m.model : null
if (model) this.model = model
const usage = piUsageToEngineUsage(m.usage)
if (usage) this.usage = addEngineUsage(this.usage, usage)
const text = piTextOf(m.content)
if (text) this.text = text
if (m.stopReason === 'error' || m.stopReason === 'aborted') {
this.error = typeof m.errorMessage === 'string' && m.errorMessage ? m.errorMessage : `pi turn ${String(m.stopReason)}`
}
// Per-hop trajectory — same contract as ClaudeSession.onStdout: one report
// per model call so the universal ledger sees BYOA hops at the same
// granularity as cloud hops.
if (usage && model && this.onHopUsage) {
const startedAt = this.hopStartedAt
this.hopStartedAt = null
this.hopIndex += 1
const { toolUses, textChars } = countPiContent(m.content)
try {
this.onHopUsage({ model, usage, latencyMs: startedAt != null ? Date.now() - startedAt : undefined, hopIndex: this.hopIndex, toolUses, textChars })
} catch { /* ledger is best-effort — never break the stream */ }
} else {
this.hopStartedAt = null
}
return false
}
return ev.type === 'agent_settled'
}
}
/** Parse one stdout line of pi's stream. Non-JSON lines (banners, warnings that
* land on stdout) come back as null and are logged verbatim by the caller. */
function parsePiLine(line: string): PiEvent | null {
if (!line.startsWith('{')) return null
try { return JSON.parse(line) as PiEvent } catch { return null }
}
/** One-shot `pi --mode json …`: spawn, fold the stream through a
* PiTurnTracker, resolve on exit. The tracker's error is folded into the
* result because pi's exit code says nothing about the model call (see the
* module note above). Text is the last assistant message's text — what
* classify()/probe() want. */
function spawnPiJson(
command: string,
args: string[],
opts: { cwd: string; env: NodeJS.ProcessEnv; signal: AbortSignal; onLog?: (line: string) => void; shell: boolean; stdinText?: string; onHopUsage?: (r: EngineHopReport) => void },
): Promise<EngineRunResult & { text: string }> {
// A queued wake can be cancelled before it reaches the engine gate. Do not
// start a Pi process after its owner has already gone away.
if (opts.signal.aborted) {
return Promise.resolve({ exitCode: 130, error: 'engine turn aborted before start', sessionId: null, text: '' })
}
return new Promise((resolve) => {
const tracker = new PiTurnTracker(opts.onHopUsage)
const child = spawnEngineChild(command, args, {
cwd: opts.cwd, env: opts.env,
stdio: [opts.stdinText != null ? 'pipe' : 'ignore', 'pipe', 'pipe'],
shell: opts.shell,
})
if (opts.stdinText != null) {
writeStdin(child, opts.stdinText, { end: true })
}
const abort = bindAbortTermination(child, opts.signal)
// StringDecoder + carried partial line, for the same reason spawnEngine has
// them: a pipe read chops a long event (a big message_end) at an arbitrary
// byte offset, and a naive per-chunk split would hand JSON.parse two halves.
const decoder = new StringDecoder('utf8')
let carry = ''
let settled = false
const stderrTail: string[] = []
const stdoutTail: string[] = []
const takeLine = (raw: string): void => {
const line = cleanLine(raw)
if (!line) return
const ev = parsePiLine(line)
if (ev && isNoisyPiEvent(ev)) return
const shown = ev ? piLogLine(ev, line) : line
pushTail(stdoutTail, shown)
opts.onLog?.(shown)
if (ev) tracker.observe(ev)
}
const pump = (buf: Buffer | null): void => {
const text = buf === null ? decoder.end() : decoder.write(buf)
const lines = (carry + text).split('\n')
carry = buf === null ? '' : (lines.pop() ?? '')
for (const line of lines) takeLine(line)
if (buf === null && carry === '' && lines.length === 0) return
}
child.stdout?.on('data', (buf: Buffer) => pump(buf))
child.stderr?.on('data', (buf: Buffer) => {
for (const raw of buf.toString('utf8').split('\n')) {
const line = cleanLine(raw)
if (!line) continue
pushTail(stderrTail, line)
opts.onLog?.(line)
}
})
child.on('error', (err) => {
if (settled) return
settled = true
abort.dispose()
void abort.wait().then(() => {
resolve({ exitCode: 1, error: err instanceof Error ? err.message : String(err), sessionId: null, text: '' })
})
})
child.on('close', (code, signalName) => {
if (settled) return
settled = true
abort.dispose()
void abort.wait().then(() => {
pump(null) // flush a final line without a trailing newline
const procExit = code ?? (signalName ? 128 : 1)
const exitCode = procExit !== 0 ? procExit : (tracker.error ? 1 : 0)
const error = procExit !== 0
? failurePreview({ exitCode: procExit, signalName, stderr: stderrTail, stdout: stdoutTail })
: (tracker.error ? `engine turn error: ${tracker.error.slice(0, MAX_FAILURE_CHARS)}` : undefined)
resolve({ exitCode, error, sessionId: tracker.sessionId, usage: tracker.usage, model: tracker.model, text: tracker.text })
})
})
})
}
/** A persistent pi process for ONE agent, driven over `pi --mode rpc` (see the
* module note): each `send()` writes ONE `prompt` command and resolves at that
* turn's `agent_settled`. Steering is native — `steer` is delivered by pi
* itself before the agent's next model call — so there is no stream-boundary
* bookkeeping here. The daemon calls send() serially. */
class PiSession implements EngineSession {
private readonly child: ChildProcess
private readonly onLog: (line: string) => void
private readonly tracker: PiTurnTracker
private readonly decoder = new StringDecoder('utf8')
private outBuf = ''
private exited = false
private exitCode = 0
private reqId = 0
private pending: { id: string; resolve: (r: EngineRunResult) => void; stderr: string[]; stdout: string[] } | null = null
private stderrTail: string[] = []
private stdoutTail: string[] = []
private pendingTimer: ReturnType<typeof setTimeout> | null = null
private stopPromise: Promise<void> | null = null
readonly carriesStandingPrompt: boolean
constructor(bin: string, args: string[], opts: EngineSessionArgs, sessionId: string, carriesStandingPrompt: boolean) {
this.onLog = opts.onLog
this.tracker = new PiTurnTracker(opts.onHopUsage)
this.tracker.sessionId = sessionId
this.carriesStandingPrompt = carriesStandingPrompt
// Cross-platform spawn (Windows: `pi.cmd` via the shell). Everything travels
// over stdin as JSON here, so there are no argv-quoting concerns.
const { command, shell } = resolveSpawn(bin)
this.child = spawnEngineChild(command, args, { cwd: opts.home, env: opts.env, stdio: ['pipe', 'pipe', 'pipe'], shell })
this.child.stdout?.on('data', (b: Buffer) => this.onStdout(b))
this.child.stderr?.on('data', (b: Buffer) => this.onStderr(b))
this.child.on('error', (err) => this.die(1, err.message))
this.child.on('close', (code, signalName) =>
this.die(code ?? (signalName ? 128 : 1), signalName ? `terminated by ${signalName}` : `exited with code ${code}`))
// Ask pi which session it actually opened. It should be the --session-id we
// passed; if a future pi ever rewrites it, we resume the REAL one next time.
this.write({ id: 'state', type: 'get_state' })
}
get alive(): boolean { return !this.exited && this.child.stdin?.writable === true }
get sessionId(): string | null { return this.tracker.sessionId }
send(prompt: string): Promise<EngineRunResult> {
if (this.pending) {
return Promise.resolve({ exitCode: 1, error: 'engine session busy — a turn is already in flight', sessionId: this.sessionId })
}
if (!this.alive) {
const exitCode = this.exitCode || 1
const detail = failurePreview({ exitCode, signalName: null, stderr: this.stderrTail, stdout: this.stdoutTail })
return Promise.resolve({ exitCode, error: detail || 'engine session is not alive (process gone)', sessionId: this.sessionId })
}
return new Promise<EngineRunResult>((resolve) => {
const id = `turn-${++this.reqId}`
this.pending = { id, resolve, stderr: [], stdout: [] }
this.tracker.beginTurn()
// Opt-in runaway backstop only (CUMORA_TURN_TIMEOUT_MS); OFF by default so a
// legit long task is never killed mid-work. When set: abort the run, fail the
// turn, tear the process down — the daemon respawns (--session-id) next wake.
if (TURN_TIMEOUT_MS > 0) {
this.pendingTimer = setTimeout(() => {
this.write({ type: 'abort' })
this.settle({ exitCode: 124, error: `engine turn exceeded CUMORA_TURN_TIMEOUT_MS (${Math.round(TURN_TIMEOUT_MS / 1000)}s) — aborted; session will respawn`, sessionId: this.sessionId })
this.stop()
}, TURN_TIMEOUT_MS)
this.pendingTimer.unref?.()
}
if (!this.write({ id, type: 'prompt', message: stripLoneSurrogates(prompt) })) {
this.settle({ exitCode: 1, error: 'failed to write turn to engine', sessionId: this.sessionId })
}
})
}
/** Same-turn steering: pi queues the message and delivers it after the current
* assistant turn's tool calls, before the next model call — the exact "next
* safe boundary" the Claude path has to compute by hand. No-op when idle (the
* daemon's normal turn handles it then). */
steer(text: string): void {
if (this.pending && this.alive && text.trim()) this.write({ type: 'steer', message: stripLoneSurrogates(text) })
}
stop(options: { force?: boolean } = {}): Promise<void> {
this.exited = true
// pi exits cleanly when stdin closes (it disposes the session and returns 0),
// so close stdin first and only SIGTERM a process that hasn't gone by itself.
try { this.child.stdin?.end() } catch { /* ignore */ }
if (options.force) return terminateEngineTree(this.child, true)
if (!this.stopPromise) {
this.stopPromise = (async () => {
if (await waitForChildExit(this.child, 2_000)) return
await terminateEngineTree(this.child)
})()
}
return this.stopPromise
}
private write(msg: object): boolean {
return writeStdin(this.child, `${JSON.stringify(msg)}\n`)
}
private onStdout(buf: Buffer): void {
// StringDecoder so a multi-byte character split across a pipe chunk never
// becomes U+FFFD inside a JSON line (same fix as the one-shot paths).
this.outBuf += this.decoder.write(buf)
let nl: number
while ((nl = this.outBuf.indexOf('\n')) >= 0) {
const line = cleanLine(this.outBuf.slice(0, nl))
this.outBuf = this.outBuf.slice(nl + 1)
if (!line) continue
const ev = parsePiLine(line)
if (ev && isNoisyPiEvent(ev)) continue
const shown = ev ? piLogLine(ev, line) : line
pushTail(this.stdoutTail, shown)
if (this.pending) pushTail(this.pending.stdout, shown)
this.onLog(shown)
if (!ev) continue
if (ev.type === 'response') { this.onResponse(ev); continue }
// Observe pi's NATIVE auto-compaction (telemetry only), like the Claude path.
if (ev.type === 'compaction_start') this.onLog('[pi] native context compaction started')
else if (ev.type === 'compaction_end') this.onLog('[pi] native context compaction finished')
if (this.tracker.observe(ev) && this.pending) {
this.settle({
exitCode: this.tracker.error ? 1 : 0,
error: this.tracker.error ? `engine turn error: ${this.tracker.error.slice(0, MAX_FAILURE_CHARS)}` : undefined,
sessionId: this.sessionId,
usage: this.tracker.usage,
model: this.tracker.model,
})
}
}
}
private onResponse(ev: PiEvent): void {
if (ev.id === 'state') {
const sid = ev.data?.sessionId
if (typeof sid === 'string' && sid) this.tracker.sessionId = sid
return
}
// A prompt rejected BEFORE acceptance (`success:false`) gets no events at all
// — settle now or the turn would hang until the daemon's timeout.
if (this.pending && ev.id === this.pending.id && ev.command === 'prompt' && ev.success === false) {
this.settle({ exitCode: 1, error: `pi rejected the turn: ${typeof ev.error === 'string' && ev.error ? ev.error : 'unknown error'}`, sessionId: this.sessionId })
}
}
private onStderr(buf: Buffer): void {
for (const raw of buf.toString('utf8').split('\n')) {
const line = cleanLine(raw)
if (!line) continue
pushTail(this.stderrTail, line)
if (this.pending) pushTail(this.pending.stderr, line)
this.onLog(line)
}
}
private settle(r: EngineRunResult): void {
if (this.pendingTimer) { clearTimeout(this.pendingTimer); this.pendingTimer = null }
const p = this.pending
this.pending = null
if (p) p.resolve(r)
}
/** Process died (error/close). Mark dead and fail any in-flight turn — always
* logged, even when idle, for the same reason ClaudeSession does it. */
private die(code: number, why: string): void {
const alreadyDown = this.exited
this.exited = true
this.exitCode = code
if (!alreadyDown) {
this.onLog(`[session] engine process died ${this.pending ? 'MID-TURN' : 'while idle'}: ${why} (exit ${code})`)
}
if (this.pending) {
const detail = failurePreview({ exitCode: code, signalName: null, stderr: this.pending.stderr, stdout: this.pending.stdout })
this.settle({ exitCode: code, error: detail || why, sessionId: this.sessionId })
}
}
}
class PiAdapter implements EngineAdapter {
readonly id = 'pi' as const
readonly bin = 'pi'
/** A clean, tool-free, persona-free one-shot: no session file, no built-in /
* extension tools, no extensions, no skills, no AGENTS.md discovery. The pi
* analogue of Claude's `--strict-mcp-config` triage spawn. */
private static readonly BARE = ['--no-session', '--no-tools', '--no-extensions', '--no-skills', '--no-context-files']
/** BYOA turns are short reactive cycles; extended thinking adds latency and,
* in a group @all, makes the slowest agent bow out on the "don't duplicate"
* rule (same reasoning as Claude's MAX_THINKING_TOKENS=0). pi's per-model
* `provider/id:<level>` suffix is the user's opt-in — when the model carries
* one, don't fight it. */
private static thinking(model: string | null | undefined): string[] {
return model && model.includes(':') ? [] : ['--thinking', 'off']
}
private oneShot(prompt: string, args: { cwd: string; env: NodeJS.ProcessEnv; signal: AbortSignal; onLog?: (line: string) => void; model?: string | null }): Promise<EngineRunResult & { text: string }> {
const { command, shell, wantsStdinPrompt } = resolveSpawn(this.bin)
const model = args.model ? ['--model', args.model] : []
// Windows: the .cmd shim runs via the shell, which can't carry a big
// multi-line prompt as an argv element → stdin (pi reads a piped stdin as the
// message when stdin isn't a TTY). POSIX: prompt in argv.
const base = ['--mode', 'json', ...PiAdapter.BARE, ...PiAdapter.thinking(args.model), ...model]
return spawnPiJson(command, wantsStdinPrompt ? base : [...base, prompt], {
cwd: args.cwd, env: args.env, signal: args.signal, onLog: args.onLog, shell,
stdinText: wantsStdinPrompt ? prompt : undefined,
})
}
async classify(args: EngineClassifyArgs): Promise<EngineClassifyResult> {
// pi is multi-provider, so there is no single cheap "cerebellum" id to hard-
// code (claude→haiku, codex→gpt-5.4-mini). CUMORA_TRIAGE_MODEL picks one
// (`provider/id`); unset → pi's own default model, which keeps triage local
// (never the cloud) at the cost of not being cheaper than the big brain.
// The json stream names the model that actually ran, so the ledger prices
// the real one either way.
const flags = extraArgs('CUMORA_TRIAGE_ARGS')
if (flags.length) {
// User-owned flag set → plain print mode, raw text back (mirrors Claude's
// override path: no envelope to unwrap, no usage).
const { command, shell, wantsStdinPrompt } = resolveSpawn(this.bin)
const base = [...flags, '-p']
return spawnCapture(command, wantsStdinPrompt ? base : [...base, args.prompt], {
cwd: args.cwd, env: args.env, signal: args.signal, onLog: args.onLog, shell,
stdinText: wantsStdinPrompt ? args.prompt : undefined,
})
}
const r = await this.oneShot(args.prompt, { cwd: args.cwd, env: args.env, signal: args.signal, onLog: args.onLog, model: args.model })
return { text: r.text, error: r.error, usage: r.usage, model: r.model }
}
async probe(args: EngineProbeArgs): Promise<EngineClassifyResult> {
// 'small' → whatever triage runs on (CUMORA_TRIAGE_MODEL, else pi's default —
// the same model as 'big', honestly reported as such); 'big' → pi's default.
const model = args.tier === 'small' ? (process.env.CUMORA_TRIAGE_MODEL || null) : null
const r = await this.oneShot(DOCTOR_PROMPT, { cwd: args.cwd, env: args.env, signal: args.signal, model })
return { text: r.text, error: r.error, usage: r.usage, model: r.model }
}
probeWake(args: EngineWakeProbeArgs): Promise<EngineWakeProbeResult> {
// Same gate as startSession(): a CUMORA_PI_ARGS override collapses the wake to
// one-shot print mode, which probe() already covers.
if (extraArgs('CUMORA_PI_ARGS').length) return Promise.resolve({ ok: true, detail: '', skipped: true })
// The real wake speaks the rpc protocol. The realistic breaks are: `--mode rpc`
// renamed/removed, or the command/response framing changed. Drive the cheapest
// round-trip there is — `get_state` needs no model call — and tear down.
const { command, shell } = resolveSpawn(this.bin)
return new Promise<EngineWakeProbeResult>((resolve) => {
let settled = false
const finish = (r: EngineWakeProbeResult): void => {
if (settled) return
settled = true
try { child.stdin?.end() } catch { /* ignore */ }
void terminateEngineTree(child).then(() => resolve(r))
}
const child = spawnEngineChild(command, ['--mode', 'rpc', ...PiAdapter.BARE], {
cwd: args.cwd, env: args.env, stdio: ['pipe', 'pipe', 'pipe'], shell,
})
const onAbort = (): void => finish({ ok: false, detail: 'aborted (timeout)' })
if (args.signal.aborted) { onAbort(); return }
args.signal.addEventListener('abort', onAbort, { once: true })
let buf = ''
let stderrTail = ''
writeStdin(child, `${JSON.stringify({ id: 'doctor', type: 'get_state' })}\n`)
child.stdout?.on('data', (b: Buffer) => {
buf += b.toString('utf8')
for (;;) {
const nl = buf.indexOf('\n')
if (nl < 0) break
const line = buf.slice(0, nl).trim()
buf = buf.slice(nl + 1)
const ev = parsePiLine(line)
if (!ev || ev.type !== 'response' || ev.id !== 'doctor') continue
if (ev.success === true) finish({ ok: true, detail: '' })
else finish({ ok: false, detail: `rpc get_state failed: ${typeof ev.error === 'string' ? ev.error.slice(0, 240) : 'unknown error'}` })
return
}
})
child.stderr?.on('data', (b: Buffer) => {
const tail = stderrTail + b.toString('utf8')
stderrTail = tail.length > 2000 ? tail.slice(-2000) : tail
})
child.on('error', (err) => finish({ ok: false, detail: `spawn error: ${err.message}` }))
child.on('close', (code, sig) => {
if (settled) return
finish({ ok: false, detail: `rpc process died before answering get_state (${sig ? `terminated by ${sig}` : `exit ${code}`}): ${salientError(stderrTail) || 'no stderr'}` })
})
})
}
async seedHome(home: string, persona: EnginePersona): Promise<void> {
await ensureCommonHome(home)
await mkdir(join(home, '.pi', 'skills'), { recursive: true })
// Always rewrite AGENTS.md so persona edits land without requiring a fresh
// home (matches Claude and Codex). pi discovers AGENTS.md from its cwd
// natively; skills are loaded explicitly via --skill (see startSession) since
// pi's non-interactive modes ignore project resources in an untrusted dir.
await writeFile(
join(home, 'AGENTS.md'),
PERSONA_HEADER(persona, { personaFile: 'AGENTS.md', skillsDir: '.pi/skills/' }),
'utf8',
)
}
async run(args: EngineRunArgs): Promise<EngineRunResult> {
// Unlike an abort listener registered below, this catches a turn cancelled
// while it was queued and avoids spawning the persistent RPC process at all.
if (args.signal.aborted) {
return { exitCode: 130, error: 'engine turn aborted before start', sessionId: args.resumeSessionId ?? null }
}
const flags = extraArgs('CUMORA_PI_ARGS')
if (flags.length) {
// User-owned flag set → one-shot print mode with their flags. We still pin
// the session so context carries across wakes; nothing structured comes
// back (no stream to sniff), so report the id we passed.
const sid = args.resumeSessionId ?? randomUUID()
const { command, shell, wantsStdinPrompt } = resolveSpawn(this.bin)
const base = [...flags, '--session-id', sid, '-p']
const r = await spawnEngine(command, wantsStdinPrompt ? base : [...base, args.prompt], args, { shell, stdinText: wantsStdinPrompt ? args.prompt : undefined })
return { ...r, sessionId: r.sessionId ?? sid }
}
// Default: the persistent rpc path is the ONLY protocol we drive, so a one-shot
// is simply a session that lives for one turn. Same parser, same ledger.
const session = this.startSession({
home: args.home, env: args.env, model: args.model, fastModel: args.fastModel,
resumeSessionId: args.resumeSessionId, onLog: args.onLog, onHopUsage: args.onHopUsage,
})
if (!session) return { exitCode: 1, error: 'pi session could not be started', sessionId: args.resumeSessionId ?? null }
const onAbort = (): void => { void session.stop({ force: true }) }
args.signal.addEventListener('abort', onAbort, { once: true })
// The signal may have flipped after the pre-spawn check but before the
// listener above was installed.
if (args.signal.aborted) onAbort()
try {
// onAbort() tears the just-created session down, but send() would then
// report that dead session as a generic engine failure. Keep a cancelled
// turn classified as cancellation and never dispatch its prompt.
if (args.signal.aborted) {
return { exitCode: 130, error: 'engine turn aborted before start', sessionId: args.resumeSessionId ?? null }
}
return await session.send(args.prompt)
} finally {
args.signal.removeEventListener('abort', onAbort)
session.stop()
}
}
startSession(args: EngineSessionArgs): EngineSession | null {
// Respect a user's custom flag override by NOT using the persistent path —
// those flags are tuned for one-shot print mode; fall back to run().
if (extraArgs('CUMORA_PI_ARGS').length) return null
// Continuous context across wakes: pin the session id ourselves (`--session-id`
// creates it when missing, resumes it when present) so a respawn — daemon
// restart, timeout, crash — picks up where the agent left off.
const sid = args.resumeSessionId ?? randomUUID()
const model = args.model ? ['--model', args.model] : []
// The invariant standing prompt loads ONCE here (not re-sent every turn), so
// the per-turn stdin messages stay small and pi's native auto-compaction keeps
// up. `--append-system-prompt` takes a file path.
let sys: string[] = []
let carriesStanding = false
if (args.standingPrompt) {
const file = join(args.home, '.cumora-standing-prompt.md')
try { atomicAgentWriteSync(file, args.standingPrompt); sys = ['--append-system-prompt', file]; carriesStanding = true }
catch { /* couldn't write → leave it; the daemon inlines the standing prompt instead */ }
}
const argv = [
'--mode', 'rpc', '--session-id', sid, ...sys, ...model, ...PiAdapter.thinking(args.model),
// Load the agent's own skills explicitly: pi's non-interactive modes ignore
// project-local resources in an untrusted directory, and trusting the home
// outright (`--approve`) would also enable project settings/extensions.
'--skill', join(args.home, '.pi', 'skills'),
]
return new PiSession(this.bin, argv, args, sid, carriesStanding)
}
}
// ── Gemini CLI ───────────────────────────────────────────────────────────────
//
// `gemini -o stream-json` emits JSONL, but NOT Claude Code's stream-json: the
// envelope below is what its own StreamJsonFormatter writes (verified against
// the shipped 0.57.0 bundle and by running the binary). Sibling forks are not
// safe to assume compatible either — Qwen Code shares Gemini's flags and emits
// Claude's envelope instead.
interface GeminiTokenStats {
/** Gemini's PROMPT total. Cache reads are INCLUDED here — see geminiUsage. */
input_tokens?: number
output_tokens?: number
cached?: number
/** prompt − cached. The fresh input, and the one the ledger wants. */
input?: number
}
interface GeminiStats extends GeminiTokenStats {
total_tokens?: number
duration_ms?: number
tool_calls?: number
/** Per-model breakdown, keyed by the model the CLI RESOLVED (`-m flash` and a
* mid-turn fallback both land here under their real ids). */
models?: Record<string, GeminiTokenStats>
}
interface GeminiEvent {
type?: string
session_id?: string
model?: string
role?: string
content?: unknown
status?: string
severity?: string
message?: string
error?: { type?: string; message?: string }
stats?: GeminiStats
}
/** Map Gemini's token stats onto the common (Anthropic-shaped) usage record.
*
* The field named `input_tokens` is NOT the one to bill. uiTelemetryService
* sets `tokens.prompt` from the API's `input_token_count`, which already
* contains the cached prefix, and then derives `tokens.input = prompt −
* cached`; `convertToStreamStats` publishes the first as `input_tokens` and
* the second as `input`. Billing `input_tokens` while ALSO reporting `cached`
* charges the cached prefix twice — and a BYOA agent re-sends a large stable
* prefix on every wake, so that prefix is most of the prompt. */
function geminiUsage(stats: GeminiStats | undefined): EngineUsage | undefined {
if (!stats || typeof stats !== 'object') return undefined
const num = (value: unknown): number =>
typeof value === 'number' && Number.isFinite(value) ? Math.max(0, value) : 0
const cached = num(stats.cached)
const fresh = stats.input != null ? num(stats.input) : Math.max(0, num(stats.input_tokens) - cached)
const output = num(stats.output_tokens)
// A turn that died before its first API call reports every counter as 0 (the
// auth-failure shape). Reporting that as usage would put a zero-token row in
// the ledger for work that never happened.
if (!fresh && !output && !cached) return undefined
return {
input_tokens: fresh,
output_tokens: output,
cache_read_input_tokens: cached,
// Gemini's implicit caching is not billed as a separate write, and its
// stats carry no creation counter — leave it absent rather than invent 0.
}
}
/** The model a turn actually ran on. `init` reports what was REQUESTED; the
* stats key reports what the CLI resolved (an alias like `flash`, or a
* mid-turn fallback, differ). Prefer the resolved id when it is unambiguous —
* cost is priced on it — and keep the requested one when several models ran. */
function geminiResolvedModel(stats: GeminiStats | undefined, seen: string | null): string | null {
const names = stats?.models ? Object.keys(stats.models) : []
return names.length === 1 ? names[0] : seen
}
class GeminiTurnTracker {
text = ''
sessionId: string | null = null
model: string | null = null
usage: EngineUsage | undefined
error: string | null = null
private startedAt: number | null = null
private toolUses = 0
private textChars = 0
constructor(
pin: string | null,
private readonly onHopUsage?: (report: EngineHopReport) => void,
) {
this.model = pin
}
observe(event: GeminiEvent): void {
if (typeof event.session_id === 'string' && event.session_id) this.sessionId = event.session_id
if (event.type === 'init') {
if (typeof event.model === 'string' && event.model) this.model = event.model
this.startedAt = Date.now()
return
}
if (event.type === 'message') {
// Assistant text arrives as deltas; the user echo of our own prompt must
// never be folded into the reply triage reads.
if (event.role === 'assistant' && typeof event.content === 'string') {
this.text += event.content
this.textChars += event.content.length
}
return
}
if (event.type === 'tool_use') { this.toolUses += 1; return }
if (event.type === 'error') {
// `severity: 'warning'` is a loop-detection / blocked-tool notice the run
// survives. Only an error ends the turn, and the terminating `result`
// event carries the authoritative verdict anyway.
if (event.severity !== 'warning' && typeof event.message === 'string') this.error = event.message
return
}
if (event.type !== 'result') return
if (event.status === 'error') {
const detail = event.error?.message ?? event.message
if (typeof detail === 'string' && detail) this.error = detail
else if (!this.error) this.error = 'gemini reported a failed turn with no detail'
}
this.model = geminiResolvedModel(event.stats, this.model)
const usage = geminiUsage(event.stats)
if (!usage) return
this.usage = usage
if (this.onHopUsage) {
// Gemini publishes token stats only at the end of the turn, so — as with
// codex exec — this is ONE hop carrying the turn's whole usage rather
// than a per-round-trip trajectory. Reporting it is what keeps BYOA
// spend visible in the same ledger as everything else.
try {
this.onHopUsage({
model: this.model ?? 'gemini',
usage,
latencyMs: this.startedAt == null ? undefined : Date.now() - this.startedAt,
hopIndex: 1,
toolUses: this.toolUses,
textChars: this.textChars,
})
} catch { /* ledger reporting is best-effort */ }
}
}
}
function parseGeminiLine(line: string): GeminiEvent | null {
if (!line.startsWith('{')) return null
try { return JSON.parse(line) as GeminiEvent } catch { return null }
}
/** Gemini refuses to act on an untrusted folder, and — worse for an unattended
* daemon — SILENTLY downgrades `--yolo` to interactive approval there
* ("Approval mode overridden to 'default' because the current folder is not
* trusted"), so the turn stalls waiting for a human who is not present.
*
* The env var, not the equivalent `--skip-trust` flag: an unknown env var is
* ignored by older builds, while an unknown flag is a fatal argv error. The
* home really is ours to trust — the daemon created and seeded it. */
function geminiEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
return { ...env, GEMINI_CLI_TRUST_WORKSPACE: 'true' }
}
async function spawnGeminiStream(
command: string,
argv: string[],
opts: {
cwd: string
env: NodeJS.ProcessEnv
prompt: string
signal: AbortSignal
onLog?: (line: string) => void
shell: boolean
onHopUsage?: (report: EngineHopReport) => void
pin?: string | null
},
): Promise<EngineRunResult & { text: string }> {
const tracker = new GeminiTurnTracker(opts.pin ?? null, opts.onHopUsage)
let processResult: EngineRunResult
try {
processResult = await spawnEngine(
command,
argv,
{
home: opts.cwd,
prompt: opts.prompt,
env: opts.env,
onLog: (line) => {
const event = parseGeminiLine(line)
if (event) tracker.observe(event)
opts.onLog?.(line)
},
signal: opts.signal,
},
// The prompt goes on stdin on EVERY platform: `gemini` reads it there
// when no -p is given, which sidesteps both argv length limits and the
// Windows .cmd shim's inability to carry a multi-line argument.
{ shell: opts.shell, stdinText: opts.prompt },
)
} catch (err) {
return {
exitCode: 1,
error: err instanceof Error ? err.message : String(err),
sessionId: tracker.sessionId,
usage: tracker.usage,
model: tracker.model,
text: tracker.text,
}
}
const eventError = tracker.error
? `engine turn error: ${tracker.error.slice(0, MAX_FAILURE_CHARS)}`
: null
const exitCode = processResult.exitCode !== 0 ? processResult.exitCode : (eventError ? 1 : 0)
return {
exitCode,
// Same precedence as the other stream adapters: a real process failure
// (auth, quota, bad flag, abort) explains more than the secondary fact that
// the stream reported a failed turn. Keep the event's prose alongside it so
// stale-session recovery can match on it without parsing JSON.
error: processResult.exitCode !== 0
? [processResult.error, eventError].filter(Boolean).join('\n')
: (eventError ?? undefined),
sessionId: tracker.sessionId,
usage: tracker.usage,
model: tracker.model,
text: tracker.text,
}
}
/** Settings that leave the triage process with NO tools at all.
*
* `tools.core` is an allowlist, and the registry applies it as
* `coreTools.some(...)` per tool — an EMPTY array is truthy, matches nothing,
* and so registers no built-in tools. User settings and installed extensions
* can also contribute MCP servers; the system-scope empty MCP allowlist joins
* every configured allowlist by intersection, so none of those servers can
* register tools either. With no tool to confirm, a headless approval prompt
* (which nothing would answer) cannot arise, and the classifier stays a
* one-shot. */
const GEMINI_TRIAGE_SETTINGS = JSON.stringify({ tools: { core: [] }, mcp: { allowed: [] } })
const GEMINI_TRIAGE_SETTINGS_FILE = '.cumora-gemini-triage.json'
class GeminiAdapter implements EngineAdapter {
readonly id = 'gemini' as const
readonly bin = 'gemini'
/** stream-json on BOTH paths, including triage. `-o json` writes nothing to
* stdout when the turn fails before the model answers (the auth-failure
* case) and reports it only on stderr, while stream-json still emits a
* `result` event carrying the reason. */
private static readonly STREAM = ['--output-format', 'stream-json']
private turn(prompt: string, args: {
cwd: string
env: NodeJS.ProcessEnv
signal: AbortSignal
onLog?: (line: string) => void
model?: string | null
resumeSessionId?: string | null
onHopUsage?: (report: EngineHopReport) => void
}): Promise<EngineRunResult & { text: string }> {
const { command, shell } = resolveSpawn(this.bin)
const model = args.model ? ['--model', args.model] : []
// `--resume` takes "latest", a 1-based index, or a full session UUID —
// findSession() matches the UUID first, which is the only stable handle
// across wakes (an index shifts as sessions accumulate).
const resume = args.resumeSessionId ? ['--resume', args.resumeSessionId] : []
return spawnGeminiStream(
command,
[...GeminiAdapter.STREAM, '--yolo', ...resume, ...model],
{
cwd: args.cwd,
env: geminiEnv(args.env),
prompt,
signal: args.signal,
onLog: args.onLog,
shell,
onHopUsage: args.onHopUsage,
pin: args.model ?? null,
},
)
}
private async ask(prompt: string, args: {
cwd: string
env: NodeJS.ProcessEnv
signal: AbortSignal
onLog?: (line: string) => void
model?: string | null
}): Promise<EngineRunResult & { text: string }> {
const { command, shell } = resolveSpawn(this.bin)
const model = ['--model', args.model || triageModel('gemini-2.5-flash-lite')]
const settings = join(args.cwd, GEMINI_TRIAGE_SETTINGS_FILE)
let env = geminiEnv(args.env)
let staged: string | null = null
try {
// Write-then-rename, not writeFile onto the live path. The triage cwd is
// shared — the doctor hands the SAME dir to every engine's probe, and
// concurrent classifies land there too — and writeFile truncates before
// it writes, so a second caller can be mid-truncate while gemini is
// reading. Identical content does not save us from a zero-length read;
// rename is atomic, so a reader sees one whole file or the other.
staged = `${settings}.${process.pid}.${randomUUID().slice(0, 8)}`
await writeFile(staged, GEMINI_TRIAGE_SETTINGS, 'utf8')
await rename(staged, settings)
// System scope so it wins over any user/workspace settings the operator
// has; it MERGES with them, so their auth config is untouched.
env = { ...env, GEMINI_CLI_SYSTEM_SETTINGS_PATH: settings }
} catch (err) {
if (staged) await rm(staged, { force: true }).catch(() => {})
return {
exitCode: 1,
error: `could not install Gemini triage settings: ${err instanceof Error ? err.message : String(err)}`,
sessionId: null,
text: '',
}
}
return spawnGeminiStream(
command,
[...GeminiAdapter.STREAM, '--yolo', ...model],
{
cwd: args.cwd,
env,
prompt,
signal: args.signal,
onLog: args.onLog,
shell,
pin: model[1],
},
)
}
async classify(args: EngineClassifyArgs): Promise<EngineClassifyResult> {
const flags = extraArgs('CUMORA_TRIAGE_ARGS')
if (flags.length) {
// Whole user-owned override: output becomes opaque, but the prompt still
// travels on stdin so a Windows shim and a long prompt both survive.
const { command, shell } = resolveSpawn(this.bin)
return spawnCapture(command, flags, {
cwd: args.cwd,
env: geminiEnv(args.env),
signal: args.signal,
onLog: args.onLog,
shell,
stdinText: args.prompt,
})
}
const result = await this.ask(args.prompt, {
cwd: args.cwd,
env: args.env,
signal: args.signal,
onLog: args.onLog,
model: args.model,
})
return { text: result.text, error: result.error, usage: result.usage, model: result.model }
}
async probe(args: EngineProbeArgs): Promise<EngineClassifyResult> {
// Concrete ids rather than Gemini's `pro` / `flash-lite` aliases: the
// aliases only exist in recent builds, and an operator running an older
// `gemini` would get a model-not-found from the doctor probe itself — a
// red brain that says nothing about their actual configuration.
const model = args.tier === 'small' ? triageModel('gemini-2.5-flash-lite') : 'gemini-2.5-pro'
const result = await this.ask(DOCTOR_PROMPT, {
cwd: args.cwd,
env: args.env,
signal: args.signal,
model,
})
return { text: result.text, error: result.error, usage: result.usage, model: result.model }
}
probeWake(_args: EngineWakeProbeArgs): Promise<EngineWakeProbeResult> {
// The real wake is the same one-shot process probe() already exercises;
// --resume re-opens a conversation inside it, it is not a second protocol.
return Promise.resolve({ ok: true, detail: '', skipped: true })
}
async seedHome(home: string, persona: EnginePersona): Promise<void> {
await ensureCommonHome(home)
await mkdir(join(home, '.gemini', 'skills'), { recursive: true })
await writeFile(
join(home, 'GEMINI.md'),
PERSONA_HEADER(persona, { personaFile: 'GEMINI.md', skillsDir: '.gemini/skills/' }),
'utf8',
)
}
async run(args: EngineRunArgs): Promise<EngineRunResult> {
const flags = extraArgs('CUMORA_GEMINI_ARGS')
if (flags.length) {
const resume = args.resumeSessionId ? ['--resume', args.resumeSessionId] : []
const { command, shell } = resolveSpawn(this.bin)
return spawnEngine(command, [...flags, ...resume], { ...args, env: geminiEnv(args.env) }, { shell, stdinText: args.prompt })
}
return this.turn(args.prompt, {
cwd: args.home,
env: args.env,
signal: args.signal,
onLog: args.onLog,
model: args.model,
resumeSessionId: args.resumeSessionId,
onHopUsage: args.onHopUsage,
})
}
// No startSession: gemini has no stream-json INPUT mode, so there is no way
// to feed turn N+1 into a live process. --resume re-opens the conversation in
// a fresh one, which is what the one-shot path already does.
}
// ── Qwen Code ────────────────────────────────────────────────────────────────
//
// Qwen Code is a Gemini CLI fork, and shares its flags (`-o stream-json`,
// `-p`, `-r`, `-m`) — but NOT its output. It emits Claude Code's envelope
// instead: `{type:'assistant',session_id,message:{model,content,usage}}` and a
// terminating `{type:'result',subtype,is_error,usage}`. That is the shape
// `spawnEngine` already sniffs, so the wake path needs no parser of its own;
// only triage does, because it needs the reply TEXT back.
//
// The two forks having the same flags and different envelopes is exactly why
// neither adapter is derived from the other.
interface QwenBlock { type?: string; text?: unknown }
interface QwenEvent {
type?: string
session_id?: string
is_error?: boolean
error?: { message?: unknown }
usage?: EngineUsage
message?: { model?: unknown; usage?: EngineUsage; content?: unknown }
}
/** Pull the assistant's reply out of a captured stream-json run.
*
* Exported for tests: it is pure, and it is the only part of this adapter
* that a fake binary cannot exercise through `spawnEngine`.
*
* Both `-o json` and `-o stream-json` are event streams here — `json` is
* simply the same events wrapped in a JSON array, NOT Claude's
* `{result,usage}` object — so there is no envelope to unwrap and the text
* has to be assembled from the assistant messages. */
export function qwenReplyFromStream(stdout: string): {
text: string
usage?: EngineUsage
model?: string | null
error?: string
} {
let text = ''
let usage: EngineUsage | undefined
let model: string | null = null
let error: string | undefined
for (const raw of stdout.split('\n')) {
const line = raw.trim()
if (!line.startsWith('{')) continue
let ev: QwenEvent
try { ev = JSON.parse(line) as QwenEvent } catch { continue }
if (typeof ev.message?.model === 'string' && ev.message.model) model = ev.message.model
if (ev.type === 'assistant' && Array.isArray(ev.message?.content)) {
for (const block of ev.message.content as QwenBlock[]) {
if (block?.type === 'text' && typeof block.text === 'string') text += block.text
}
continue
}
if (ev.type !== 'result') continue
if (ev.usage && typeof ev.usage === 'object') usage = ev.usage
if (ev.is_error) {
const detail = ev.error?.message
error = typeof detail === 'string' && detail ? detail : 'qwen reported a failed turn with no detail'
}
}
return { text: text.trim(), usage, model, error }
}
class QwenAdapter implements EngineAdapter {
readonly id = 'qwen' as const
readonly bin = 'qwen'
/** stream-json on both paths. `-o json` returns the same events as a JSON
* array, so it buys nothing here and only adds a second shape to parse. */
private static readonly STREAM = ['--output-format', 'stream-json']
private async ask(prompt: string, args: {
cwd: string
env: NodeJS.ProcessEnv
signal: AbortSignal
onLog?: (line: string) => void
model?: string | null
}): Promise<EngineClassifyResult> {
const { command, shell } = resolveSpawn(this.bin)
// No --model at all when the caller has none: the big-brain probe must
// exercise whatever the operator made default, and forcing the cheap
// triage id there would report on a model their wakes never use.
const model = args.model ? ['--model', args.model] : []
const res = await spawnCapture(
command,
// `--safe-mode` is qwen's own switch for "ignore every customization":
// context files, hooks, extensions, skills and MCP servers all stay
// unloaded, which keeps a cold triage spawn cheap. Plan mode removes
// automatic approval for tool use without changing authentication.
[...QwenAdapter.STREAM, '--safe-mode', '--approval-mode', 'plan', ...model],
{
cwd: args.cwd,
env: args.env,
signal: args.signal,
onLog: args.onLog,
shell,
stdinText: prompt,
},
)
const parsed = qwenReplyFromStream(res.text)
return {
text: parsed.text,
// A process failure explains more than a stream that merely reported one,
// so keep the same precedence the other stream adapters use.
error: res.error ?? (parsed.error ? `engine turn error: ${parsed.error.slice(0, MAX_FAILURE_CHARS)}` : undefined),
usage: parsed.usage,
model: parsed.model ?? args.model ?? null,
}
}
async classify(args: EngineClassifyArgs): Promise<EngineClassifyResult> {
const flags = extraArgs('CUMORA_TRIAGE_ARGS')
if (flags.length) {
// Whole user-owned override: the output becomes opaque, but the prompt
// still travels on stdin so a long prompt and a Windows shim survive.
const { command, shell } = resolveSpawn(this.bin)
return spawnCapture(command, flags, {
cwd: args.cwd, env: args.env, signal: args.signal, onLog: args.onLog, shell, stdinText: args.prompt,
})
}
return this.ask(args.prompt, {
cwd: args.cwd, env: args.env, signal: args.signal, onLog: args.onLog,
model: args.model || triageModel('qwen3-coder-flash'),
})
}
async probe(args: EngineProbeArgs): Promise<EngineClassifyResult> {
// Qwen Code is multi-provider (its own OAuth, DashScope, or any OpenAI-
// compatible base URL), so there is no cheap model id that is right for
// every operator. The small tier honours CUMORA_TRIAGE_MODEL — the same
// knob triage reads, so doctor cannot report a red small brain for an
// operator whose triage is configured correctly — and the big tier uses
// whatever the operator made default.
const model = args.tier === 'small' ? triageModel('qwen3-coder-flash') : null
return this.ask(DOCTOR_PROMPT, { cwd: args.cwd, env: args.env, signal: args.signal, model })
}
probeWake(_args: EngineWakeProbeArgs): Promise<EngineWakeProbeResult> {
// The wake is the same one-shot process probe() already exercises.
// --resume re-opens a conversation inside it, it is not a second protocol.
return Promise.resolve({ ok: true, detail: '', skipped: true })
}
async seedHome(home: string, persona: EnginePersona): Promise<void> {
await ensureCommonHome(home)
await mkdir(join(home, '.qwen', 'skills'), { recursive: true })
await writeFile(
join(home, 'QWEN.md'),
PERSONA_HEADER(persona, { personaFile: 'QWEN.md', skillsDir: '.qwen/skills/' }),
'utf8',
)
}
async run(args: EngineRunArgs): Promise<EngineRunResult> {
const flags = extraArgs('CUMORA_QWEN_ARGS')
const { command, shell } = resolveSpawn(this.bin)
// `--resume <id>` resumes by session id (`-c` resumes the newest, which is
// wrong here: one machine runs many agents out of many homes).
const resume = args.resumeSessionId ? ['--resume', args.resumeSessionId] : []
if (flags.length) {
return spawnEngine(command, [...flags, ...resume], args, { shell, stdinText: args.prompt })
}
const model = args.model ? ['--model', args.model] : []
// No tracker: the envelope is Claude's, so spawnEngine already lifts the
// session id, the terminating usage, the model, and one hop per assistant
// message into the ledger.
return spawnEngine(
command,
[...QwenAdapter.STREAM, '--yolo', ...resume, ...model],
args,
// Prompt on stdin on every platform: `qwen` reads it there when no -p is
// given, which avoids argv limits and the Windows .cmd shim's inability
// to carry a multi-line argument.
{ shell, stdinText: args.prompt },
)
}
// No startSession: qwen has no stream-json INPUT mode, so there is no way to
// feed turn N+1 into a live process. --resume re-opens the conversation in a
// fresh one, which is what the one-shot path already does.
}
// ─── Antigravity CLI ──────────────────────────────────────────────────────────────────
//
// `agy --input-format stream-json --output-format stream-json` is a real
// long-lived protocol: one NDJSON user event goes in per turn and exactly one
// terminal result event comes back. Result usage is CUMULATIVE for the whole
// process, so the tracker must subtract the previous total before handing a
// turn to Cumora's ledger. Treating the result as per-turn silently bills the
// first turn again on every later wake.
interface AntigravityNativeUsage {
input_tokens?: number
output_tokens?: number
thinking_tokens?: number
cache_read_tokens?: number
total_tokens?: number
}
interface AntigravityEvent {
event?: string
conversation_id?: string
init?: { conversation_id?: string; model?: string }
step_update?: {
conversation_id?: string
step_index?: number
state?: string
step_type?: string
tool_name?: string
text_delta?: string
tool_info?: unknown
usage?: AntigravityNativeUsage
}
result?: {
conversation_id?: string
status?: string
response?: string
error?: string
duration_seconds?: number
num_turns?: number
model?: string
usage?: AntigravityNativeUsage
}
}
function antigravityCounter(value: unknown): number {
return typeof value === 'number' && Number.isFinite(value) ? Math.max(0, value) : 0
}
/** Convert Antigravity's counters without charging cache reads twice.
*
* When `input_tokens` includes `cache_read_tokens` (`input_tokens >= cache_read_tokens`),
* subtract `cache_read_tokens` so fresh input and cache reads stay disjoint. When
* `agy` reports `input_tokens` already net of cache reads (`input_tokens < cache_read_tokens`,
* where `total_tokens = input_tokens + output_tokens`), preserve `input_tokens` as-is. */
function antigravityUsage(raw: AntigravityNativeUsage | undefined): EngineUsage | undefined {
if (!raw) return undefined
const cached = antigravityCounter(raw.cache_read_tokens)
const rawInput = antigravityCounter(raw.input_tokens)
const input = rawInput >= cached ? rawInput - cached : rawInput
const output = antigravityCounter(raw.output_tokens)
if (!input && !output && !cached) return undefined
return {
input_tokens: input,
output_tokens: output,
cache_read_input_tokens: cached,
}
}
function antigravityUsageDelta(
current: AntigravityNativeUsage | undefined,
previous: AntigravityNativeUsage | undefined,
): AntigravityNativeUsage | undefined {
if (!current) return undefined
const delta = (key: keyof AntigravityNativeUsage): number => {
const now = antigravityCounter(current[key])
const before = antigravityCounter(previous?.[key])
// A CLI-side session reset makes the cumulative total smaller. That new
// value is the whole current turn, not a negative delta.
return now >= before ? now - before : now
}
return {
input_tokens: delta('input_tokens'),
output_tokens: delta('output_tokens'),
thinking_tokens: delta('thinking_tokens'),
cache_read_tokens: delta('cache_read_tokens'),
total_tokens: delta('total_tokens'),
}
}
function addAntigravityUsage(
acc: AntigravityNativeUsage | undefined,
step: AntigravityNativeUsage,
): AntigravityNativeUsage {
return {
input_tokens: antigravityCounter(acc?.input_tokens) + antigravityCounter(step.input_tokens),
output_tokens: antigravityCounter(acc?.output_tokens) + antigravityCounter(step.output_tokens),
thinking_tokens: antigravityCounter(acc?.thinking_tokens) + antigravityCounter(step.thinking_tokens),
cache_read_tokens: antigravityCounter(acc?.cache_read_tokens) + antigravityCounter(step.cache_read_tokens),
total_tokens: antigravityCounter(acc?.total_tokens) + antigravityCounter(step.total_tokens),
}
}
function parseAntigravityLine(line: string): AntigravityEvent | null {
if (!line.startsWith('{')) return null
try { return JSON.parse(line) as AntigravityEvent } catch { return null }
}
class AntigravityTurnTracker {
sessionId: string | null = null
model: string | null
text = ''
error: string | null = null
usage: EngineUsage | undefined
private previousUsage: AntigravityNativeUsage | undefined
private turnStepUsage: AntigravityNativeUsage | undefined
private startedAt: number | null = null
private toolUses = 0
private readonly seenToolSteps = new Set<number>()
private readonly seenResponseSteps = new Set<number>()
private hopIndex = 0
private awaitingResumedBaseline: boolean
constructor(
pin: string | null,
private readonly onHopUsage?: (report: EngineHopReport) => void,
resumedFromDisk = false,
) {
this.model = pin
this.awaitingResumedBaseline = resumedFromDisk
}
beginTurn(): void {
this.text = ''
this.error = null
this.usage = undefined
this.turnStepUsage = undefined
this.startedAt = Date.now()
this.toolUses = 0
this.seenToolSteps.clear()
this.seenResponseSteps.clear()
}
/** Feed one event. True means the current turn reached its terminal result. */
observe(event: AntigravityEvent): boolean {
const id = event.conversation_id ?? event.init?.conversation_id ?? event.result?.conversation_id
if (typeof id === 'string' && id) this.sessionId = id
const namedModel = event.init?.model ?? event.result?.model
if (typeof namedModel === 'string' && namedModel) this.model = namedModel
if (event.event === 'step_update') {
const step = event.step_update
if (step?.tool_info != null && step.state === 'DONE' && typeof step.step_index === 'number' && !this.seenToolSteps.has(step.step_index)) {
this.seenToolSteps.add(step.step_index)
this.toolUses += 1
}
if (step?.step_type === 'agent_response' && step.state === 'DONE' && step.usage) {
if (typeof step.step_index !== 'number' || !this.seenResponseSteps.has(step.step_index)) {
if (typeof step.step_index === 'number') this.seenResponseSteps.add(step.step_index)
this.turnStepUsage = addAntigravityUsage(this.turnStepUsage, step.usage)
}
}
return false
}
if (event.event !== 'result' || !event.result) return false
const result = event.result
if (typeof result.response === 'string') this.text = result.response
if (result.status !== 'SUCCESS') {
this.error = typeof result.error === 'string' && result.error
? result.error
: `antigravity turn ended with status ${result.status || 'UNKNOWN'}`
}
// Prefer the sum of per-step `agent_response` usages emitted during this turn:
// when resuming via `--conversation <id>`, `result.usage` includes historical
// turns from prior processes, whereas `turnStepUsage` covers only the current
// turn. Fall back to cumulative `result.usage` delta when no step usage was
// emitted (e.g. synthetic fixtures or pre-step errors on fresh sessions).
const delta = this.turnStepUsage
?? (this.awaitingResumedBaseline ? undefined : antigravityUsageDelta(result.usage, this.previousUsage))
if (result.usage) {
this.previousUsage = result.usage
this.awaitingResumedBaseline = false
}
this.usage = antigravityUsage(delta)
if (this.usage && this.onHopUsage) {
this.hopIndex += 1
try {
this.onHopUsage({
model: this.model ?? 'antigravity',
usage: this.usage,
latencyMs: this.startedAt == null ? undefined : Date.now() - this.startedAt,
hopIndex: this.hopIndex,
toolUses: this.toolUses,
textChars: this.text.length,
})
} catch { /* ledger reporting is best-effort */ }
}
return true
}
}
/** Re-inline the full standing prompt every N turns. `agy` exposes no
* system-prompt file, so turn 1 carries it inline; keeping it out of turns
* 2..N is what stops a persistent transcript from growing by a whole standing
* prompt (~5k tokens) on every wake. The periodic refresh covers the engine's
* native compaction dropping old turns. */
const ANTIGRAVITY_STANDING_REFRESH_TURNS = 8
class AntigravitySession implements EngineSession {
private readonly child: ChildProcess
private readonly tracker: AntigravityTurnTracker
private readonly decoder = new StringDecoder('utf8')
private outBuf = ''
private exited = false
private exitCode = 0
private stderrTail: string[] = []
private stdoutTail: string[] = []
private pending: { resolve: (result: EngineRunResult) => void } | null = null
private stopPromise: Promise<void> | null = null
/** Whether this process's transcript already contains the standing prompt. */
private standingDelivered: boolean
/** Turns completed since the standing prompt was last inlined. */
private standingTurns = 0
constructor(
command: string,
argv: string[],
shell: boolean,
private readonly opts: EngineSessionArgs,
pin: string | null,
) {
this.tracker = new AntigravityTurnTracker(pin, opts.onHopUsage, Boolean(opts.resumeSessionId))
// A resumed conversation already carries the standing prompt from the prior
// process; a fresh one gets it inline on its first turn.
this.standingDelivered = Boolean(opts.resumeSessionId)
this.child = spawnEngineChild(command, argv, {
cwd: opts.home,
env: opts.env,
stdio: ['pipe', 'pipe', 'pipe'],
shell,
})
this.child.stdout?.on('data', (buf: Buffer) => this.onStdout(buf))
this.child.stderr?.on('data', (buf: Buffer) => this.onStderr(buf))
this.child.on('error', (err) => this.die(1, err.message))
this.child.on('close', (code, signalName) => {
this.flushStdout()
this.die(code ?? (signalName ? 128 : 1), signalName ? `terminated by ${signalName}` : `exited with code ${code}`)
})
}
get alive(): boolean { return !this.exited && this.child.stdin?.writable === true }
get sessionId(): string | null { return this.tracker.sessionId }
get text(): string { return this.tracker.text }
/** True once the transcript holds the standing prompt, so the daemon sends
* only the per-turn delta. This is the whole reason a long-lived `agy`
* session does not grow by a full standing prompt on every wake. */
get carriesStandingPrompt(): boolean { return this.standingDelivered }
send(prompt: string): Promise<EngineRunResult> {
if (this.pending) return Promise.resolve({ exitCode: 1, error: 'engine session busy — a turn is already in flight', sessionId: this.sessionId })
if (!this.alive) {
return Promise.resolve({
exitCode: this.exitCode || 1,
error: failurePreview({ exitCode: this.exitCode || 1, signalName: null, stderr: this.stderrTail, stdout: this.stdoutTail }),
sessionId: this.sessionId,
})
}
// The prompt was assembled from carriesStandingPrompt a moment ago (see
// daemon.turnPrompt), so an inlined standing prompt is about to enter the
// transcript. Remember it on a SUCCESSFUL write only.
const inlinedStanding = !this.standingDelivered
this.tracker.beginTurn()
return new Promise((resolve) => {
this.pending = { resolve }
const message = JSON.stringify({ event: 'user', message: { content: stripLoneSurrogates(prompt) } })
if (!writeStdin(this.child, `${message}\n`)) {
this.settle({ exitCode: 1, error: 'failed to write turn to antigravity', sessionId: this.sessionId })
return
}
if (inlinedStanding) {
this.standingDelivered = true
this.standingTurns = 0
}
})
}
steer(_text: string): void {
if (!this.pending) return
// The documented protocol requires waiting for a result before the next
// user event. Queueing mid-turn would be an undocumented race; the daemon's
// normal coalesced wake delivers the ping after this turn instead.
this.opts.onLog('[antigravity] same-turn steer is not supported; the ping rides the next wake')
}
stop(options: { force?: boolean } = {}): Promise<void> {
this.exited = true
try { this.child.stdin?.end() } catch { /* ignore */ }
if (options.force) return terminateEngineTree(this.child, true)
if (!this.stopPromise) {
this.stopPromise = (async () => {
if (await waitForChildExit(this.child, 2_000)) return
await terminateEngineTree(this.child)
})()
}
return this.stopPromise
}
private onStdout(buf: Buffer): void {
this.outBuf += this.decoder.write(buf)
let newline: number
while ((newline = this.outBuf.indexOf('\n')) >= 0) {
const raw = this.outBuf.slice(0, newline)
this.outBuf = this.outBuf.slice(newline + 1)
this.takeLine(raw)
}
}
private flushStdout(): void {
this.outBuf += this.decoder.end()
if (this.outBuf) this.takeLine(this.outBuf)
this.outBuf = ''
}
private takeLine(raw: string): void {
const line = cleanLine(raw)
if (!line) return
pushTail(this.stdoutTail, line)
const event = parseAntigravityLine(line)
if (event?.event === 'step_update' && event.step_update) {
const step = event.step_update
const toolName = step.tool_name ?? (step.tool_info as { name?: string } | undefined)?.name
if (step.step_type === 'tool' && step.state === 'ACTIVE' && typeof toolName === 'string' && toolName) {
this.opts.onLog(`[antigravity] tool ${toolName}`)
} else if (step.step_type === 'agent_response' && step.state === 'DONE' && typeof step.text_delta === 'string' && step.text_delta.trim()) {
this.opts.onLog(`[antigravity] » ${step.text_delta.replace(/\s+/g, ' ').trim().slice(0, 200)}`)
} else {
this.opts.onLog(line)
}
} else {
this.opts.onLog(line)
}
if (event && this.tracker.observe(event)) {
const eventError = this.tracker.error
this.settle({
exitCode: eventError ? 1 : 0,
error: eventError ? `engine turn error: ${eventError.slice(0, MAX_FAILURE_CHARS)}` : undefined,
sessionId: this.tracker.sessionId,
usage: this.tracker.usage,
model: this.tracker.model,
})
}
}
private onStderr(buf: Buffer): void {
for (const raw of buf.toString('utf8').split('\n')) {
const line = cleanLine(raw)
if (!line) continue
pushTail(this.stderrTail, line)
this.opts.onLog(line)
}
}
private settle(result: EngineRunResult): void {
const pending = this.pending
if (!pending) return
this.pending = null
if (this.standingDelivered) {
this.standingTurns += 1
if (this.standingTurns >= ANTIGRAVITY_STANDING_REFRESH_TURNS) {
// Native compaction can drop old turns; re-inline soon so the mechanics
// never silently disappear from a long-lived transcript.
this.standingDelivered = false
this.standingTurns = 0
}
}
pending.resolve(result)
}
private die(code: number, detail: string): void {
if (this.exited && !this.pending) return
this.exited = true
this.exitCode = code
if (this.pending) {
this.settle({
exitCode: code || 1,
error: failurePreview({ exitCode: code || 1, signalName: null, stderr: this.stderrTail, stdout: this.stdoutTail }) || detail,
sessionId: this.sessionId,
usage: this.tracker.usage,
model: this.tracker.model,
})
}
}
}
class AntigravityAdapter implements EngineAdapter {
readonly id = 'antigravity' as const
readonly bin = 'agy'
private sessionArgs(args: EngineSessionArgs, mode: 'auto' | 'plan'): string[] {
const model = args.model ? ['--model', args.model] : []
const resume = mode === 'auto' && args.resumeSessionId
? ['--conversation', args.resumeSessionId]
: []
// Only pass `--sandbox` on the read-only triage/probe ('plan') path.
// Real agent turns ('auto') run inside Cumora's outer BYOA boundary and must
// write IPC requests to CUMORA_AGENT_IPC_DIR (outside <home>) to invoke
// `cumora glance/messages/reply/send` as well as read ~/.gitconfig and
// workspace paths; `--sandbox` on real turns causes every `cumora` CLI call
// to fail with EPERM on first attempt and waste an extra LLM turn retrying.
const sandbox = mode === 'plan' ? ['--sandbox'] : []
return [
'--input-format', 'stream-json',
'--output-format', 'stream-json',
...sandbox,
'--mode', mode,
'--dangerously-skip-permissions',
'--disable-slash-commands',
...resume,
...model,
]
}
private start(args: EngineSessionArgs, mode: 'auto' | 'plan'): AntigravitySession {
const { command, shell } = resolveSpawn(this.bin)
return new AntigravitySession(command, this.sessionArgs(args, mode), shell, args, args.model ?? null)
}
startSession(args: EngineSessionArgs): EngineSession | null {
return this.start(args, 'auto')
}
async run(args: EngineRunArgs): Promise<EngineRunResult> {
if (args.signal.aborted) return { exitCode: 130, error: 'engine turn aborted before start', sessionId: null }
const sessionArgs: EngineSessionArgs = {
home: args.home,
env: args.env,
model: args.model,
fastModel: args.fastModel,
resumeSessionId: args.resumeSessionId,
onLog: args.onLog,
onHopUsage: args.onHopUsage,
}
const session = this.start(sessionArgs, 'auto')
const onAbort = (): void => { void session.stop({ force: true }) }
args.signal.addEventListener('abort', onAbort, { once: true })
if (args.signal.aborted) onAbort()
try {
if (args.signal.aborted) return { exitCode: 130, error: 'engine turn aborted before start', sessionId: null }
return await session.send(args.prompt)
} finally {
args.signal.removeEventListener('abort', onAbort)
await session.stop()
}
}
async classify(args: EngineClassifyArgs): Promise<EngineClassifyResult> {
const session = this.start({
home: args.cwd,
env: args.env,
model: args.model ?? process.env.CUMORA_TRIAGE_MODEL ?? null,
onLog: args.onLog ?? (() => {}),
}, 'plan')
const onAbort = (): void => { void session.stop({ force: true }) }
args.signal.addEventListener('abort', onAbort, { once: true })
if (args.signal.aborted) onAbort()
try {
if (args.signal.aborted) return { text: '', error: 'engine turn aborted before start' }
const result = await session.send(args.prompt)
return { text: session.text, error: result.error, usage: result.usage, model: result.model }
} finally {
args.signal.removeEventListener('abort', onAbort)
await session.stop()
}
}
async probe(args: EngineProbeArgs): Promise<EngineClassifyResult> {
const model = args.tier === 'small' ? (process.env.CUMORA_TRIAGE_MODEL ?? null) : null
return this.classify({ cwd: args.cwd, prompt: DOCTOR_PROMPT, env: args.env, model, signal: args.signal })
}
probeWake(_args: EngineWakeProbeArgs): Promise<EngineWakeProbeResult> {
// classify()/probe() use the same bidirectional stream-json protocol as a
// real wake, only in plan mode, so the brain probes already cover it.
return Promise.resolve({ ok: true, detail: '', skipped: true })
}
async seedHome(home: string, persona: EnginePersona): Promise<void> {
await ensureCommonHome(home)
await mkdir(join(home, '.agents', 'skills'), { recursive: true })
await writeFile(
join(home, 'AGENTS.md'),
PERSONA_HEADER(persona, { personaFile: 'AGENTS.md', skillsDir: '.agents/skills/' }),
'utf8',
)
}
}
const ADAPTERS: Record<EngineId, EngineAdapter> = {
claude: new ClaudeAdapter(),
codex: new CodexAdapter(),
grok: new GrokAdapter(),
cursor: new CursorAdapter(),
opencode: new OpenCodeAdapter(),
pi: new PiAdapter(),
gemini: new GeminiAdapter(),
qwen: new QwenAdapter(),
antigravity: new AntigravityAdapter(),
zcode: new ZcodeAdapter(),
maka: new MakaAdapter(),
omp: new OmpAdapter(),
}
export function getAdapter(id: EngineId): EngineAdapter {
return ADAPTERS[id]
}
export interface EngineDetection {
engines: EngineId[]
/** False when `which` / `where` itself failed, so missing engines cannot be
* distinguished from a broken scan and callers should keep their last good
* inventory. */
reliable: boolean
}
/** Probe which engines are installed and whether absence is trustworthy. */
export async function detectEnginesWithStatus(): Promise<EngineDetection> {
const ids = Object.keys(ADAPTERS) as EngineId[]
const probes = await Promise.all(ids.map(async (id) => {
const status = await probeBinOnPath(ADAPTERS[id].bin)
const installed = status === 'present'
|| (id === 'grok' && resolveGrokBin() != null)
|| (id === 'maka' && resolveMakaBin() != null)
|| (id === 'omp' && resolveOmpBin() != null)
return { id, installed, status }
}))
return {
engines: probes.filter((p) => p.installed).map((p) => p.id),
reliable: probes.every((p) => p.status !== 'error'),
}
}
/** Probe which engines are installed on this machine. */
export async function detectEngines(): Promise<EngineId[]> {
return (await detectEnginesWithStatus()).engines
}
/** One detected engine as stored on the computer row and shown in the app.
* Paths are resolved on the daemon machine (Windows `where` / POSIX `which`);
* the renderer never probes PATH. */
export interface DetectedEngineSnapshot {
id: EngineId
bin: string
path: string | null
/** Version fields are absent from the cheap pairing snapshot and filled in by
* enrichDetectedEngines() on the rescan, which is allowed to spawn CLIs. */
version?: string | null
latest?: string | null
outdated?: boolean
updateCommand?: string | null
/** Why this installed engine will NOT be driven — the reason
* evaluateRunnableEngines() produced. Absent on runnable engines. */
blockedReason?: string
/** Account/config-specific model choices discovered by the daemon that owns
* this CLI login. Absent on the cheap pairing snapshot and older daemons. */
modelCatalog?: EngineModelCatalog
}
/** Snapshot the installed engines, optionally in a caller-supplied order
* (pairing puts the chosen default first). Does not spawn the CLIs. */
export async function snapshotDetectedEngines(ids?: readonly EngineId[]): Promise<DetectedEngineSnapshot[]> {
const present = ids ?? await detectEngines()
return Promise.all(present.map(async (id) => {
const bin = ADAPTERS[id].bin
const path = id === 'grok'
? (resolveGrokBin() ?? await resolveBinPath(bin))
: id === 'maka'
? (resolveMakaBin() ?? await resolveBinPath(bin))
: id === 'omp'
? (resolveOmpBin() ?? await resolveBinPath(bin))
: await resolveBinPath(bin)
return { id, bin, path }
}))
}
/** Add each engine's installed version, the newest one upstream, and how to
* update — measured on *this* machine. Spawns one `--version` per engine, so
* it rides the 5-minute rescan rather than the pairing path, which the user is
* sitting and waiting on. */
export async function enrichDetectedEngines(
snapshot: DetectedEngineSnapshot[],
refreshModelCatalog = false,
): Promise<DetectedEngineSnapshot[]> {
return Promise.all(snapshot.map(async (entry) => {
const [version, modelCatalog] = await Promise.all([
probeEngineVersion(entry.id, entry.path),
discoverEngineModelCatalog(entry.id, entry.path, refreshModelCatalog),
])
return { ...entry, ...version, modelCatalog }
}))
}
/** Resolve the active model's visuals from the account-specific catalog. A
* default model inherits the catalog default; a custom pin is looked up by id. */
export function engineVisionCapability(
catalog: Pick<EngineModelCatalog, 'models' | 'defaultModel'> | null | undefined,
modelId: string | null | undefined,
): 'supported' | 'unsupported' | 'unknown' {
return visionCapabilityForModel(catalog, modelId || catalog?.defaultModel || null)
}
/** Resolve a bin's absolute path on PATH (the first hit), or null if absent. */
export async function resolveBinPath(bin: string): Promise<string | null> {
return new Promise((resolve) => {
const probe = spawn(IS_WIN ? 'where' : 'which', [bin], { stdio: ['ignore', 'pipe', 'ignore'] })
let out = ''
probe.stdout?.on('data', (b: Buffer) => { out += b.toString('utf8') })
probe.on('error', () => resolve(null))
probe.on('close', (code) => resolve(code === 0 ? (out.split(/\r?\n/)[0]?.trim() || null) : null))
})
}
/** Health of one brain tier of one engine, as measured by a `doctor` probe. */
export interface BrainHealth {
ok: boolean
/** Probe wall-clock in ms. */
ms: number
/** On ok: the (truncated) reply. On failure: the concise error/exit detail. */
detail: string
}
/** Wake-path probe result, surfaced alongside the per-tier brains. `null` when
* the engine isn't installed; `skipped:true` when the adapter's wake path
* collapses to one-shot exec on this machine (the brain probes already cover
* that case). */
export interface WakeHealth {
ok: boolean
ms: number
detail: string
skipped?: boolean
}
/** `doctor` result for one engine. `big`/`small`/`wake` are null when not installed. */
export interface EngineHealth {
id: EngineId
installed: boolean
/** Absolute path of the resolved bin, or null if not on PATH. */
path: string | null
big: BrainHealth | null
small: BrainHealth | null
/** Wake-path protocol health (codex app-server JSON-RPC handshake; claude
* persistent-session flag set; grok ACP stdio handshake). Cursor/OpenCode
* skip it because their wake path is the same one-shot call as the brain
* probe. Separate signal from big/small because those failures are
* auth/quota, while this one is protocol/CLI compatibility. */
wake: WakeHealth | null
}
/** How the engines Cumora drives word a rejected flag. Taken from the real
* binaries, because the shapes differ more than they look:
*
* claude / cursor-agent error: unknown option '--x'
* codex error: unexpected argument '--x' found
* gemini 0.1.x Unknown argument: o
*
* Only the first two lead with `error:`, which is what `salientError` keys on.
* Gemini prints its ENTIRE help to stderr and puts the cause on the LAST line,
* so without this pattern the operator's diagnosis is 280 characters of usage
* text with the reason cut off the end. */
const ARGV_REJECTION_RE =
/\b(?:unknown (?:argument|option|flag)s?|unrecogni[sz]ed (?:argument|option)s?|unexpected argument|invalid option)\b[^\n]*/i
/** The engine rejected one of OUR flags, so it failed before doing any work.
*
* Worth separating from every other probe failure because the fix is
* different in kind: not "sign in", not "wait out the rate limit", but "the
* installed CLI is older than the flag set this adapter sends". Returns the
* offending line, or null when the failure was something else. */
export function argvRejection(raw: string): string | null {
const m = raw.replace(ANSI_RE, '').replace(/\r/g, '').match(ARGV_REJECTION_RE)
return m ? m[0].replace(/\s+/g, ' ').trim().slice(0, 120) : null
}
/** Pull the most informative line out of an engine's failure output. Engines bury
* the real cause (usage limit / not signed in / bad model) under a multi-line
* startup banner, often on a different stream — lead with the line that names it. */
function salientError(raw: string): string {
// Ahead of the generic scan: an argv rejection can sit BELOW a whole help
// dump, and the fallback (first 280 chars of everything) would show the
// banner instead of the cause.
const rejected = argvRejection(raw)
if (rejected) return rejected
const clean = raw.replace(ANSI_RE, '').replace(/\r/g, '')
const m = clean.match(
/((?:error|fatal)\b[:\- ].*|you'?ve hit your usage limit.*|usage limit.*|rate.?limit.*|quota.*|over(?:loaded|capacity).*|insufficient (?:credit|quota).*|unauthor\w*.*|forbidden.*|invalid (?:api )?key.*|not (?:logged in|authenticated|signed in).*|(?:please )?(?:sign|log) ?in.*|authentication .*)/i,
)
return (m ? m[0] : clean).replace(/\s+/g, ' ').trim().slice(0, 280)
}
/** Diagnose every engine on this machine: is it installed, and are its big-brain
* and small-brain (cerebellum) tiers reachable + authed? Each tier gets a trivial
* one-shot probe (the same spawn path triage/turns use), so a green result means
* real wakes will work. Engines are probed in parallel; the two tiers of one
* engine run sequentially to avoid self-induced rate limits. Never throws. */
export async function runEngineDoctor(opts?: {
engines?: EngineId[]
env?: NodeJS.ProcessEnv
/** Per-tier timeout. Default 60s — a cold engine + auth handshake can be slow. */
timeoutMs?: number
onLog?: (line: string) => void
}): Promise<EngineHealth[]> {
const env = opts?.env ?? process.env
const timeoutMs = opts?.timeoutMs ?? 60_000
const cwd = await mkdtemp(join(tmpdir(), 'cumora-doctor-'))
const ids = opts?.engines ?? Object.keys(ADAPTERS) as EngineId[]
return Promise.all(ids.map(async (id): Promise<EngineHealth> => {
const adapter = ADAPTERS[id]
const path = (await resolveBinPath(adapter.bin))
?? (id === 'grok' ? resolveGrokBin(env)
: id === 'maka' ? resolveMakaBin(env)
: id === 'omp' ? resolveOmpBin(env)
: null)
if (!path) return { id, installed: false, path: null, big: null, small: null, wake: null }
const probeTier = async (tier: 'big' | 'small'): Promise<BrainHealth> => {
const controller = new AbortController()
const timer = setTimeout(() => controller.abort(), timeoutMs)
const t0 = Date.now()
let r: EngineClassifyResult
try {
opts?.onLog?.(`probing ${id} ${tier}-brain…`)
r = await adapter.probe({ tier, cwd, env, signal: controller.signal })
} catch (err) {
r = { text: '', error: err instanceof Error ? err.message : String(err) }
} finally {
clearTimeout(timer)
}
const ms = Date.now() - t0
if (controller.signal.aborted) {
return { ok: false, ms, detail: `timed out after ${timeoutMs}ms (likely blocked on auth or a throttled provider)` }
}
if (r.error || !r.text.trim()) {
// The real cause is often on STDOUT (e.g. codex prints "ERROR: You've hit
// your usage limit" to stdout while stderr holds only the startup banner),
// so search BOTH streams and surface the salient error line — not the banner.
const both = `${r.error ?? ''}\n${r.text ?? ''}`
const rejected = argvRejection(both)
// Name the fix. A red brain that reads "Unknown argument: o" tells an
// operator nothing; the same line plus the binary it came from says
// which CLI to update, and rules out the auth/quota causes they would
// otherwise go looking for first.
if (rejected) {
return { ok: false, ms, detail: `${rejected} — \`${adapter.bin}\` is older than the flags Cumora sends; update it` }
}
return { ok: false, ms, detail: salientError(both) || 'no output' }
}
return { ok: true, ms, detail: r.text.replace(ANSI_RE, '').trim().slice(0, 80) }
}
const probeWakeOnce = async (): Promise<WakeHealth> => {
const controller = new AbortController()
const timer = setTimeout(() => controller.abort(), timeoutMs)
const t0 = Date.now()
let r: EngineWakeProbeResult
try {
opts?.onLog?.(`probing ${id} wake-path…`)
// Use a FRESH subdir per engine: codex may `git init` here and we don't
// want claude's probe (or a re-run) tripping over a stale .git.
const wakeCwd = await mkdtemp(join(tmpdir(), `cumora-doctor-${id}-wake-`))
r = await adapter.probeWake({ cwd: wakeCwd, env, signal: controller.signal })
} catch (err) {
r = { ok: false, detail: err instanceof Error ? err.message : String(err) }
} finally {
clearTimeout(timer)
}
const ms = Date.now() - t0
if (controller.signal.aborted) {
return { ok: false, ms, detail: `timed out after ${timeoutMs}ms (wake-path handshake)` }
}
return { ok: r.ok, ms, detail: r.detail, skipped: r.skipped }
}
// Sequential within an engine (same provider/account → don't race a rate limit).
const big = await probeTier('big')
const small = await probeTier('small')
const wake = await probeWakeOnce()
return { id, installed: true, path, big, small, wake }
}))
}