Skip to content

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

20.4 KB
Raw Blame
/** Minimal, replayable work-location evidence. No Git, I/O, shell execution or raw output storage. */
import { createHash } from 'node:crypto'
import { dirname, isAbsolute, resolve } from 'node:path'
import { literalToolCall, literalToolCalls, type ToolOutputSlot } from './literalToolCall.js'

export type WorkLocation = { cwd: string; at: string }
export type WorkPullRequest = { url: string; cwd: string | null; at: string }
type Operation = { paths: string[]; at: string; order: number; createsPr: boolean;
  children?: Array<{ operation: Operation; output?: ToolOutputSlot }> }
export type SessionWorkLedger = {
  context: string | null; sequence: number; latest: number; currentOrder: number; failedOrder: number;
  current: WorkLocation[]; locations: WorkLocation[]; pullRequests: WorkPullRequest[];
  pending: Record<string, Operation>; running: Record<string, Operation>; completed: string[];
  uncertain: boolean; truncated: boolean;
}
export type SessionWork = Pick<SessionWorkLedger, 'current' | 'locations' | 'pullRequests' | 'uncertain' | 'truncated'>
const LIMIT = 128
const RECEIPTS = 2048
const object = (v: unknown): Record<string, unknown> | null =>
  v !== null && typeof v === 'object' && !Array.isArray(v) ? v as Record<string, unknown> : null
const hash = (s: string) => createHash('sha256').update(s).digest('hex')
const stamp = (v: unknown): v is string => typeof v === 'string' && Number.isFinite(Date.parse(v))
export { validWorkPath, validPullRequestUrl } from './sessionWorkWire.js'
import { validWorkPath, validPullRequestUrl } from './sessionWorkWire.js'
export const emptySessionWork = (): SessionWorkLedger => ({ context: null, sequence: 0, latest: 0, currentOrder: 0, failedOrder: 0,
  current: [], locations: [], pullRequests: [], pending: {}, running: {}, completed: [], uncertain: false, truncated: false })

export function validSessionWork(value: unknown): value is SessionWorkLedger {
  const r = object(value)
  const locations = (v: unknown) => Array.isArray(v) && v.length <= LIMIT
    && v.every(x => validWorkPath(x?.cwd) && stamp(x?.at))
  const integer = (v: unknown) => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0
  const operation = (op: Operation, depth = 0): boolean => depth <= 4
    && Array.isArray(op?.paths) && op.paths.length <= LIMIT && op.paths.every(validWorkPath)
    && integer(op.order) && op.order <= Number(r?.sequence) && stamp(op.at) && typeof op.createsPr === 'boolean'
    && (op.children === undefined || Array.isArray(op.children) && op.children.length <= 32
      && op.children.every(child => operation(child?.operation, depth + 1) && (child.output === undefined
        || integer(child.output.block) && child.output.block < 32
        && (child.output.index === undefined || integer(child.output.index) && child.output.index < 32)
        && (child.output.settled === undefined || typeof child.output.settled === 'boolean'))))
  return !!r && (r.context === null || validWorkPath(r.context)) && integer(r.sequence) && integer(r.latest)
    && Number(r.latest) <= Number(r.sequence) && integer(r.currentOrder) && Number(r.currentOrder) <= Number(r.sequence)
    && integer(r.failedOrder) && Number(r.failedOrder) <= Number(r.sequence) && locations(r.current) && locations(r.locations)
    && Array.isArray(r.pullRequests) && r.pullRequests.length <= LIMIT && r.pullRequests.every(p =>
      validPullRequestUrl(p?.url) && (p.cwd === null || validWorkPath(p.cwd)) && stamp(p?.at))
    && [r.pending, r.running].every(operations => !!object(operations) && Object.keys(operations as object).length <= LIMIT
    && Object.entries(operations as Record<string, Operation>).every(([id, op]) => /^[a-f0-9]{64}$/.test(id) && operation(op)))
    && Array.isArray(r.completed) && r.completed.length <= RECEIPTS && r.completed.every(id => /^[a-f0-9]{64}$/.test(id))
    && typeof r.uncertain === 'boolean' && typeof r.truncated === 'boolean'
}

export function sessionWorkSnapshot(state: SessionWorkLedger): SessionWork | null {
  if (!state.sequence && !state.pullRequests.length && !state.locations.length) return null
  // Pending calls are intent, not successful work. Multiple simultaneous calls prevent a claim
  // that the last completed checkout is the unique place the agent is working now.
  const pending = [...Object.values(state.pending), ...Object.values(state.running)]
  return { current: state.current.map(v => ({ ...v })), locations: state.locations.map(v => ({ ...v })),
    pullRequests: state.pullRequests.map(v => ({ ...v })),
    uncertain: state.uncertain || pending.length > 0, truncated: state.truncated }
}

type Word = { text: string; literal: boolean }
type Command = { words: Word[]; after: string }
/** Tokenize only straight-line shell syntax. Quoted words stay words; never evaluate expansion. */
function commands(source: string): Command[] | null {
  if (source.length > 128 * 1024) return null
  const result: Command[] = []
  let words: Word[] = [], text = '', literal = true, quote = '', started = false
  const word = () => { if (started) words.push({ text, literal }); text = ''; literal = true; started = false }
  const command = (after: string) => { word(); if (words.length) result.push({ words, after }); words = [] }
  for (let i = 0; i < source.length; i++) {
    const ch = source[i]
    if (ch === '\\' && quote !== "'") {
      const next = source[++i]
      if (next === undefined) return null
      if (quote === '"' && !['$', '`', '"', '\\', '\n'].includes(next)) text += '\\'
      if (next !== '\n') { text += next; started = true }
      continue
    }
    if (quote) {
      if (ch === quote) quote = ''
      else { text += ch; if (quote !== "'" && (ch === '$' || ch === '`')) literal = false }
      continue
    }
    if (ch === "'" || ch === '"') { quote = ch; started = true; continue }
    if (ch === '#' && !started) { while (i < source.length && source[i] !== '\n') i++; command(';'); continue }
    if (ch === '>' && source[i + 1] === '&' || ch === '&' && source[i + 1] === '>') {
      text += source.slice(i, i + 2); i++; started = true; continue
    }
    // Subshells, substitutions, background work and alternatives need a real execution receipt.
    if ('()`{}'.includes(ch) || ch === '<') return null
    if (ch === '$' || ch === '~' && !started || ch === '*' || ch === '?') literal = false
    if (ch === '&' || ch === '|') {
      const doubled = source[i + 1] === ch
      if (doubled) i++
      if (ch === '&' && !doubled || ch === '|' && doubled) return null
      command(doubled ? '&&' : '|'); continue
    }
    if (ch === ';' || ch === '\n') { command(';'); continue }
    if (/\s/.test(ch)) { word(); continue }
    text += ch; started = true
  }
  if (quote) return null
  command('')
  return result
}

function pathFrom(word: Word | undefined, cwd: string | null): string | null {
  if (!word?.literal || !word.text || word.text.startsWith('-') || /[\x00-\x1f\x7f]/.test(word.text)) return null
  const path = isAbsolute(word.text) ? resolve(word.text) : cwd ? resolve(cwd, word.text) : null
  return validWorkPath(path) ? path : null
}

export function shellWorkLocations(source: string, initial: string | null): { paths: string[]; createsPr: boolean } | null {
  const parsed = commands(source)
  if (!parsed?.length) return null
  let cwd = initial
  const paths = new Set<string>()
  let createsPr = false
  for (const [index, command] of parsed.entries()) {
    const { words, after } = command
    const name = words[0]?.text
    if (!words[0]?.literal || /^(?:if|then|else|fi|for|while|until|case|function|eval|source|exec|command|builtin|pushd|popd|time|!|\.)$/.test(name)) return null
    if (['sh', 'bash', 'zsh', 'fish', 'env', 'sudo'].includes(name) || name.includes('=')) return null
    if (words.some(w => /^(?:GIT_DIR|GIT_WORK_TREE|GIT_COMMON_DIR)=|^--(?:git-dir|work-tree)(?:=|$)/.test(w.text))) return null
    if (name === 'cd') {
      const operand = words[1]?.text === '--' ? words[2] : words[1]
      if (words.length !== (words[1]?.text === '--' ? 3 : 2) || index < parsed.length - 1 && after !== '&&') return null
      cwd = pathFrom(operand, cwd)
      if (!cwd) return null
      if (index === parsed.length - 1) paths.add(cwd)
      continue
    }
    // Environment setup does not establish a separate work location.
    if (['export', 'unset', 'set'].includes(name)) continue
    let location = cwd
    if (name === 'git' && words[1]?.text === '-C') {
      location = pathFrom(words[2], cwd)
      if (!location || words.slice(3).some(w => w.text === '-C' || w.text === '--git-dir' || w.text === '--work-tree')) return null
    }
    // A pipeline's consumers inherit the shell cwd but usually only read stdin. Keep its source.
    if (location && (index === 0 || parsed[index - 1].after !== '|')) paths.add(location)
    if (name === 'gh' && words[1]?.text === 'pr' && words[2]?.text === 'create'
      && index === parsed.length - 1 && words.slice(3).every(w => w.literal)) createsPr = true
  }
  return { paths: [...paths].slice(0, LIMIT), createsPr }
}

function parse(value: unknown): unknown {
  if (typeof value !== 'string') return value
  try { return JSON.parse(value) } catch { return value }
}

/** A single unconditional literal code-mode call. Anything else stays unknown, never evaluated. */
function unwrap(name: string, input: unknown): [string, unknown] {
  if (name !== 'exec' || typeof input !== 'string') return [name, parse(input)]
  const call = literalToolCall(input)
  return call ? [call.name, call.input] : [name, input]
}

function operation(name: string, raw: unknown, cwd: string | null): { paths: string[]; createsPr: boolean } | null | undefined {
  const [tool, input] = unwrap(name.replace(/^functions\./, ''), parse(raw))
  const args = object(input)
  if (['Bash', 'exec_command', 'shell', 'local_shell', 'unified_exec'].includes(tool)) {
    const explicit = args?.workdir ?? args?.cwd
    if (explicit !== undefined && !validWorkPath(explicit)) return null
    const base = validWorkPath(explicit) ? explicit : cwd
    const rawCommand = args?.cmd ?? args?.command
    const source = Array.isArray(rawCommand) && rawCommand.length === 3 && ['-c', '-lc'].includes(rawCommand[1])
      ? rawCommand[2] : rawCommand
    return typeof source === 'string' ? shellWorkLocations(source, base) : null
  }
  if (['Read', 'Edit', 'Write', 'MultiEdit'].includes(tool)) {
    const path = pathFrom({ text: typeof args?.file_path === 'string' ? args.file_path : '', literal: true }, cwd)
    return path ? { paths: [dirname(path)], createsPr: false } : null
  }
  if (tool === 'apply_patch') {
    const patch = typeof input === 'string' ? input : args?.patch ?? args?.input
    if (typeof patch !== 'string' || !patch.startsWith('*** Begin Patch\n') || !patch.trimEnd().endsWith('*** End Patch')) return null
    const files = [...patch.matchAll(/^\*\*\* (?:Add File|Update File|Delete File|Move to): (.+)$/gm)]
    const paths = files.map(match => pathFrom({ text: match[1], literal: true }, cwd)).map(path => path && dirname(path))
    return paths.length && paths.every((p): p is string => !!p)
      ? { paths: [...new Set(paths)].slice(0, LIMIT), createsPr: false } : null
  }
  // Code mode may execute anything; it invalidates confidence when unsupported. Unrelated tools
  // such as web search and user questions do not change where a session last worked.
  return ['exec', 'apply_patch'].includes(tool) ? null : undefined
}

function prepare(state: SessionWorkLedger, name: string, input: unknown, cwd: string | null, at: string,
  order?: number): Operation | null {
  const [tool, raw] = unwrap(name.replace(/^functions\./, ''), parse(input))
  const args = object(raw)
  const continuation = tool === 'write_stdin' && (typeof args?.session_id === 'number' || typeof args?.session_id === 'string')
    ? hash(`process:${args.session_id}`) : tool === 'wait' && typeof args?.cell_id === 'string' ? hash(`cell:${args.cell_id}`) : null
  if (continuation && state.running[continuation]) {
    const running = state.running[continuation]
    delete state.running[continuation]
    // Input could change an interactive shell's directory. Only passive waits confirm an operation.
    return args?.terminate === true || typeof args?.chars === 'string' && args.chars.length > 0
      ? { at: running.at, order: running.order, paths: [], createsPr: false } : running
  }
  const found = continuation ? null : operation(name, input, cwd)
  if (found === undefined) return null
  return { paths: found?.paths ?? [], createsPr: found?.createsPr ?? false, order: order ?? ++state.sequence, at }
}

function begin(state: SessionWorkLedger, id: unknown, name: unknown, input: unknown, cwd: string | null, at: string): void {
  if (typeof id !== 'string' || typeof name !== 'string') return
  const key = hash(id)
  if (state.pending[key] || state.completed.includes(key)) return
  if (Object.keys(state.pending).length >= LIMIT) { state.uncertain = true; state.truncated = true; return }
  const raw = parse(input)
  const calls = name.replace(/^functions\./, '') === 'exec' && typeof raw === 'string' ? literalToolCalls(raw) : null
  if (calls) {
    const orders = new Map<number, number>()
    const children: NonNullable<Operation['children']> = []
    for (const call of calls) {
      const order = orders.get(call.group) ?? state.sequence + 1
      const op = prepare(state, call.name, call.input, cwd, at, order)
      if (op) {
        state.sequence = Math.max(state.sequence, order)
        orders.set(call.group, order)
        children.push({ operation: op, ...(call.output ? { output: call.output } : {}) })
      }
    }
    if (children.length) state.pending[key] = { paths: [], at, order: state.sequence, createsPr: false, children }
  } else {
    const op = prepare(state, name, input, cwd, at)
    if (op) state.pending[key] = op
  }
}

function outputText(raw: unknown): string {
  if (typeof raw === 'string') return raw
  if (Array.isArray(raw)) return raw.map(v => outputText(object(v)?.text)).join('\n')
  const obj = object(raw)
  return typeof obj?.output === 'string' ? obj.output : ''
}

function finish(state: SessionWorkLedger, id: unknown, raw: unknown, failed: boolean, receipt?: unknown): void {
  if (typeof id !== 'string') return
  const key = hash(id), op = state.pending[key]
  if (!op) return
  delete state.pending[key]
  state.completed.push(key)
  if (state.completed.length > RECEIPTS) { state.completed.shift(); state.truncated = true }
  finishOperation(state, op, raw, failed, receipt)
}

/** Codex stores each text(...) output as a separate input_text block. Joining those JSON objects
 * destroys their boundaries and loses yielded process ids, exit codes and PR creation receipts. */
function outputBlocks(raw: unknown): unknown[] {
  const blocks = Array.isArray(raw) ? raw.map(row => object(row)?.text).filter((row): row is string => typeof row === 'string')
    : [typeof raw === 'string' ? raw : JSON.stringify(raw) ?? '']
  return blocks.map(text => text.replace(/^Script completed[\s\S]*?\nOutput:\n/, '').trim())
    .filter(text => text && !/^Script running with cell ID/.test(text)).map(parse)
}

function finishOperation(state: SessionWorkLedger, op: Operation, raw: unknown, failed: boolean, receipt?: unknown): void {
  let text = outputText(raw)
  if (op.children) {
    const blocks = outputBlocks(raw)
    const cell = /Script running with cell ID ([\w-]+)/.exec(text)?.[1]
    const remaining: NonNullable<Operation['children']> = []
    for (const child of op.children) {
      const slot = child.output
      if (cell && slot && slot.block >= blocks.length) {
        remaining.push({ ...child, output: { ...slot, block: slot.block - blocks.length } }); continue
      }
      let value = slot ? blocks[slot.block] : undefined
      const row = object(value)
      const invalid = !slot || value === undefined || slot.index !== undefined && row?.i !== slot.index
        || slot.settled && row?.status !== 'fulfilled'
      if (slot?.settled) value = row?.value
      finishOperation(state, child.operation, value, failed || !!invalid)
    }
    if (cell && remaining.length) {
      if (Object.keys(state.running).length < LIMIT) state.running[hash(`cell:${cell}`)] = { ...op, children: remaining }
      else { state.uncertain = true; state.truncated = true }
    }
    return
  }
  const wrapper = /^Script completed[\s\S]*?\nOutput:\n([\s\S]*)$/.exec(text)
  if (wrapper) text = wrapper[1]
  const result = object(parse(text)) ?? object(raw)
  const native = object(receipt)
  const running = result?.session_id != null && result.exit_code == null
    ? hash(`process:${result.session_id}`)
    : /Process running with session ID ([\w-]+)/.test(text)
      ? hash(`process:${/Process running with session ID ([\w-]+)/.exec(text)![1]}`)
      : /Script running with cell ID ([\w-]+)/.test(text)
        ? hash(`cell:${/Script running with cell ID ([\w-]+)/.exec(text)![1]}`) : null
  const unsuccessful = failed || result?.isError === true || native?.interrupted === true
    || native?.backgroundTaskId != null || running != null
    || typeof result?.exit_code === 'number' && result.exit_code !== 0
    || /(?:Process exited with code|"exit_code"\s*:)\s*[1-9]\d*/.test(text)
    || /Script running with cell ID|Process running with session ID|Script terminated/.test(text)
  if (running && !failed && result?.isError !== true) {
    if (Object.keys(state.running).length < LIMIT) state.running[running] = op
    else state.truncated = true
  }
  state.latest = Math.max(state.latest, op.order)
  if ((!running && unsuccessful) || !op.paths.length) state.failedOrder = Math.max(state.failedOrder, op.order)
  if (!unsuccessful && op.paths.length && op.order >= state.currentOrder) {
    // Keep the last successful location through failures, pending work and unsupported scripts.
    // Calls in one parallel group share an order, so several worktrees stay explicitly multiple.
    const previous = op.order === state.currentOrder ? state.current : []
    state.currentOrder = op.order
    state.current = [...previous, ...op.paths.filter(cwd => !previous.some(row => row.cwd === cwd)).map(cwd => ({ cwd, at: op.at }))].slice(0, LIMIT)
  }
  state.uncertain = state.currentOrder < state.latest || state.failedOrder === state.latest
  if (unsuccessful) return
  for (const cwd of op.paths) {
    const old = state.locations.find(p => p.cwd === cwd)
    if (!old || old.at < op.at) {
      state.locations = [{ cwd, at: op.at }, ...state.locations.filter(p => p.cwd !== cwd)]
        .sort((a, b) => b.at.localeCompare(a.at))
    }
  }
  if (state.locations.length > LIMIT) { state.locations.length = LIMIT; state.truncated = true }
  if (op.createsPr) {
    if (typeof result?.output === 'string') text = result.output
    const urls = [...new Set(text.split('\n').map(s => s.trim()).filter(validPullRequestUrl))]
    if (urls.length === 1 && !state.pullRequests.some(p => p.url === urls[0])) {
      state.pullRequests.unshift({ url: urls[0], cwd: op.paths.length === 1 ? op.paths[0] : null, at: op.at })
      if (state.pullRequests.length > LIMIT) { state.pullRequests.length = LIMIT; state.truncated = true }
    }
  }
}

/** Caller enforces session/fork identity before ingestion. Timestamps are transcript evidence. */
export function ingestSessionWork(state: SessionWorkLedger, row: Record<string, unknown>, engine: string, launchCwd?: string | null): void {
  if (!stamp(row.timestamp)) return
  const at = new Date(row.timestamp).toISOString()
  if (engine === 'codex' && ['session_meta', 'turn_context'].includes(String(row.type))) {
    const cwd = object(row.payload)?.cwd
    if (validWorkPath(cwd)) state.context = cwd
    return
  }
  const cwd = validWorkPath(row.cwd) ? row.cwd : state.context ?? (validWorkPath(launchCwd) ? launchCwd : null)
  if (engine === 'claude') {
    const content = object(row.message)?.content
    if (!Array.isArray(content)) return
    for (const v of content) {
      const item = object(v)
      if (!item) continue
      if (row.type === 'assistant' && item.type === 'tool_use') begin(state, item.id, item.name, item.input, cwd, at)
      if (row.type === 'user' && item.type === 'tool_result') finish(state, item.tool_use_id, item.content, item.is_error === true,
        content.filter(v => object(v)?.type === 'tool_result').length === 1 ? row.toolUseResult : undefined)
    }
  } else if (engine === 'codex' && row.type === 'response_item') {
    const item = object(row.payload)
    if (!item) return
    if (item.type === 'function_call' || item.type === 'custom_tool_call')
      begin(state, item.call_id ?? item.id, item.name, item.arguments ?? item.input, cwd, at)
    if (item.type === 'function_call_output' || item.type === 'custom_tool_call_output')
      finish(state, item.call_id ?? item.id, item.output, item.is_error === true || item.status === 'failed')
  }
}