@xingular/harness 0.0.0-stage → 0.1.0

package/src/sessions/runStore.ts

@@ -0,0 +1,332 @@
+// Canonical run records and their event logs.
+//
+// `<data root>/runs/<run id>/run.json` holds the run's fields; `events.jsonl` is the
+// append-only, validated event log. The harness is the only writer of both.
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { notFound } from '../core/errors'
+import { newId, now, readJson, safeId, writeJson } from '../core/fs'
+import { compareText, lines } from '../core/text'
+import { isActiveStatus, runEventSchema, runRecordSchema, usagePayloadSchema, type RunEvent, type RunRecord, type UsagePayload } from './contracts'
+import { readAllRuns, recordRun, runsForSession } from './runIndex'
+
+export function runDir(root: string, runId: string): string {
+  return join(root, 'runs', safeId(runId))
+}
+
+const recordPath = (root: string, runId: string): string => join(runDir(root, runId), 'run.json')
+
+// Field order of the file, so a record written here reads the same as one written before.
+function ordered(record: RunRecord): RunRecord {
+  return {
+    resumedFromRunId: record.resumedFromRunId,
+    parentRunId: record.parentRunId,
+    relation: record.relation,
+    terminalReason: record.terminalReason,
+    id: record.id,
+    projectId: record.projectId,
+    mode: record.mode,
+    harness: record.harness,
+    sessionType: record.sessionType,
+    sessionId: record.sessionId,
+    nativeSessionId: record.nativeSessionId,
+    workingDirectory: record.workingDirectory,
+    worktreeId: record.worktreeId,
+    goal: record.goal,
+    attachmentCount: record.attachmentCount,
+    startedAt: record.startedAt,
+    endedAt: record.endedAt,
+    status: record.status,
+    exitCode: record.exitCode,
+    handoffId: record.handoffId,
+    accountId: record.accountId,
+    agentId: record.agentId,
+    trigger: record.trigger
+  }
+}
+
+function write(root: string, record: RunRecord): void {
+  writeJson(recordPath(root, record.id), ordered(record))
+  recordRun(root, record)
+}
+
+export function saveRun(root: string, record: RunRecord): void {
+  write(root, record)
+}
+
+function readRecord(path: string): RunRecord | null {
+  const parsed = runRecordSchema.safeParse(readJson(path))
+  return parsed.success ? parsed.data : null
+}
+
+export function loadRun(root: string, runId: string): RunRecord {
+  const record = readRecord(recordPath(root, runId))
+  if (!record) throw notFound('Run')
+  return record
+}
+
+export function findRun(root: string, runId: string): RunRecord | null {
+  try {
+    return loadRun(root, runId)
+  } catch {
+    return null
+  }
+}
+
+/** Changes a run's record. A settled run keeps its outcome whatever the change says. */
+export function updateRun(root: string, runId: string, update: (record: RunRecord) => void): void {
+  const record = readRecord(recordPath(root, runId))
+  if (!record) return
+  const { status, endedAt, terminalReason } = record
+  update(record)
+  if (!isActiveStatus(status)) Object.assign(record, { status, endedAt, terminalReason })
+  write(root, record)
+}
+
+export function terminalStatus(event: Pick<RunEvent, 'type' | 'payload'>): 'completed' | 'failed' | 'interrupted' | null {
+  if (event.type === 'completed') return 'completed'
+  if (event.type === 'failed') return 'failed'
+  if (event.type !== 'status.changed') return null
+  const status = (event.payload as { status?: unknown } | null)?.status
+  return status === 'interrupted' || status === 'failed' || status === 'completed' ? status : null
+}
+
+function reasonOf(event: RunEvent): string | null {
+  const payload = event.payload as { reason?: unknown; message?: unknown } | null
+  const reason = payload?.reason ?? payload?.message
+  return typeof reason === 'string' ? reason : null
+}
+
+export function appendEvent(root: string, event: RunEvent): void {
+  const directory = runDir(root, event.runId)
+  mkdirSync(directory, { recursive: true })
+  // O_APPEND with a single write keeps each line intact.
+  appendFileSync(join(directory, 'events.jsonl'), `${JSON.stringify(event)}\n`)
+}
+
+/** A stored event as it was written: structurally an event, whatever its payload. */
+function storedEvent(line: string): RunEvent | null {
+  try {
+    const value = JSON.parse(line) as RunEvent
+    const valid = value && typeof value.id === 'string' && typeof value.runId === 'string' && typeof value.sessionId === 'string' && Number.isInteger(value.sequence) && value.sequence >= 0 && typeof value.timestamp === 'string' && typeof value.type === 'string' && value.payload !== undefined
+    return valid ? value : null
+  } catch {
+    return null
+  }
+}
+
+/** A torn final line (a crash mid-write) is skipped rather than failing the whole log. */
+export function readEvents(root: string, runId: string): RunEvent[] {
+  let text: string
+  try {
+    text = readFileSync(join(runDir(root, runId), 'events.jsonl'), 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []
+    throw error
+  }
+  return lines(text).flatMap((line) => storedEvent(line) ?? [])
+}
+
+/** An incoming event that passes the contract, or `null`. */
+export function parseEvent(value: unknown): RunEvent | null {
+  const parsed = runEventSchema.safeParse(value)
+  if (!parsed.success) return null
+  try {
+    safeId(parsed.data.runId)
+  } catch {
+    return null
+  }
+  return parsed.data
+}
+
+/** The events that affected execution; what arrived after the outcome stays in the raw log as evidence. */
+export function executionEvents(events: readonly RunEvent[]): RunEvent[] {
+  const end = events.findIndex((event) => terminalStatus(event) !== null)
+  return events.slice(0, end < 0 ? events.length : end + 1).filter((event) => (event.native as { hostIgnored?: unknown } | null | undefined)?.hostIgnored === undefined)
+}
+
+/**
+ * Appends an event and applies it to the run record. An event that arrives after the run
+ * settled is kept as evidence and returns `false`: it is never applied or relayed.
+ */
+export function persistEvent(root: string, event: RunEvent): boolean {
+  const record = loadRun(root, event.runId)
+  if (!isActiveStatus(record.status)) {
+    event.native = { hostIgnored: 'run_already_ended', event: event.native ?? null }
+    appendEvent(root, event)
+    return false
+  }
+  appendEvent(root, event)
+  // Most events (text deltas above all) leave the record as it is; it is rewritten only when it changes.
+  let changed = false
+  const outcome = terminalStatus(event)
+  if (outcome) {
+    record.status = outcome
+    record.endedAt = event.timestamp
+    record.terminalReason = reasonOf(event)
+    changed = true
+  } else if (event.type === 'status.changed') {
+    const status = (event.payload as { status?: unknown }).status
+    if (typeof status === 'string' && status !== record.status) {
+      record.status = status
+      changed = true
+    }
+  }
+  const payload = event.payload as { role?: unknown; text?: unknown }
+  if (event.type === 'message.completed' && payload.role === 'user' && record.mode === 'code' && !record.goal) {
+    record.goal = typeof payload.text === 'string' ? payload.text : null
+    changed = true
+  }
+  if (changed) write(root, record)
+  return true
+}
+
+const STOPPED = 'The harness stopped before the run settled.'
+
+/** Startup reconciliation for every run that did not settle before the process stopped. */
+export function markInterruptedRuns(root: string, reason = STOPPED): number {
+  let count = 0
+  for (const record of readAllRuns(root)) {
+    const path = recordPath(root, record.id)
+    const events = readEvents(root, record.id)
+    const settled = events.find((event) => terminalStatus(event) !== null)
+    if (settled) {
+      const status = terminalStatus(settled)!
+      const settledReason = reasonOf(settled)
+      if (record.status !== status || record.endedAt !== settled.timestamp || record.terminalReason !== settledReason) {
+        const backup = `${path}.before-outcome-repair`
+        if (!existsSync(backup)) copyFileSync(path, backup)
+        Object.assign(record, { status, endedAt: settled.timestamp, terminalReason: settledReason })
+        write(root, record)
+      }
+    }
+    if (!isActiveStatus(record.status)) continue
+    record.status = 'interrupted'
+    record.terminalReason = reason
+    record.endedAt ??= now()
+    const last = events.reduce((highest, event) => Math.max(highest, event.sequence), -1)
+    appendEvent(root, { id: newId(), runId: record.id, sessionId: record.sessionId, sequence: last + 1, timestamp: now(), type: 'status.changed', payload: { status: 'interrupted', reason } })
+    write(root, record)
+    count += 1
+  }
+  return count
+}
+
+/** An approval or question a run asked for that nothing has answered yet. */
+export interface PendingDecision {
+  kind: 'approval' | 'question'
+  id: string
+  eventId: string
+  payload: unknown
+}
+
+/** The run's unanswered approvals and questions, oldest first. */
+export function pendingDecisions(events: readonly RunEvent[]): PendingDecision[] {
+  const pending: PendingDecision[] = []
+  for (const requested of events) {
+    const shape = requested.type === 'approval.requested' ? (['approval', 'approvalId', 'approval.resolved'] as const) : requested.type === 'question.requested' ? (['question', 'questionId', 'question.answered'] as const) : null
+    if (!shape) continue
+    const [kind, key, answered] = shape
+    const id = (requested.payload as Record<string, unknown>)[key]
+    if (typeof id !== 'string') continue
+    if (events.some((entry) => entry.type === answered && (entry.payload as Record<string, unknown>)[key] === id)) continue
+    pending.push({ kind, id, eventId: requested.id, payload: requested.payload })
+  }
+  return pending
+}
+
+export interface RunSnapshot {
+  run: RunRecord
+  events: RunEvent[]
+  lastSequence: number
+}
+
+export interface RunFamilySnapshot {
+  rootRunId: string
+  runs: { run: RunRecord; usage: UsagePayload | null }[]
+  usage: {
+    inputTokens: number | null
+    outputTokens: number | null
+    cacheReadTokens: number | null
+    cacheWriteTokens: number | null
+    reasoningTokens: number | null
+    costUsd: number | null
+    requests: number | null
+  }
+  settled: boolean
+}
+
+function belongsToRoot(record: RunRecord, rootRunId: string, records: Map<string, RunRecord>): boolean {
+  const visited = new Set<string>()
+  let current: RunRecord | undefined = record
+  while (current && !visited.has(current.id)) {
+    if (current.id === rootRunId) return true
+    visited.add(current.id)
+    current = current.parentRunId ? records.get(current.parentRunId) : undefined
+  }
+  return false
+}
+
+/** A root run and all descendants linked through opaque parent-run metadata. */
+export function runFamily(root: string, runId: string): RunFamilySnapshot {
+  const all = readAllRuns(root)
+  const byId = new Map(all.map((record) => [record.id, record]))
+  const target = byId.get(runId)
+  if (!target) throw notFound('Run')
+
+  let familyRoot = target
+  const ancestors = new Set<string>([target.id])
+  while (familyRoot.parentRunId) {
+    const parent = byId.get(familyRoot.parentRunId)
+    if (!parent || ancestors.has(parent.id)) break
+    ancestors.add(parent.id)
+    familyRoot = parent
+  }
+
+  const members = all.filter((record) => belongsToRoot(record, familyRoot.id, byId))
+    .sort((left, right) => compareText(left.startedAt, right.startedAt))
+  const runs = members.map((run) => {
+    const events = executionEvents(readEvents(root, run.id))
+    const lastUsage = events.filter((event) => event.type === 'usage.updated').at(-1)?.payload
+    const parsed = usagePayloadSchema.safeParse(lastUsage)
+    return { run, usage: parsed.success ? parsed.data : null }
+  })
+  const counters = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens', 'costUsd', 'requests'] as const
+  const usage = Object.fromEntries(counters.map((counter) => {
+    const values = runs.map(({ usage: current }) => current?.[counter])
+    return [counter, values.every((value) => typeof value === 'number') ? values.reduce<number>((total, value) => total + (value as number), 0) : null]
+  })) as RunFamilySnapshot['usage']
+
+  return { rootRunId: familyRoot.id, runs, usage, settled: runs.every(({ run }) => !isActiveStatus(run.status)) }
+}
+
+export function snapshot(root: string, runId: string): RunSnapshot {
+  const run = loadRun(root, runId)
+  const events = executionEvents(readEvents(root, runId))
+  return { run, events, lastSequence: events.reduce((highest, event) => Math.max(highest, event.sequence), -1) }
+}
+
+export interface RunListFilter {
+  projectId?: string | null
+  sessionId?: string | null
+  activeOnly?: boolean
+}
+
+/** A session's history comes from the index; other filters scan run records. At most 200, newest first. */
+export function listRuns(root: string, filter: RunListFilter): RunRecord[] {
+  if (filter.sessionId) {
+    try {
+      const records = runsForSession(root, filter.sessionId, 200).flatMap((id) => findRun(root, id) ?? [])
+      return filter.activeOnly ? records.filter((record) => isActiveStatus(record.status)) : records
+    } catch {
+      // Fall through to the files.
+    }
+  }
+  return readAllRuns(root)
+    .filter((record) => !filter.projectId || record.projectId === filter.projectId)
+    .filter((record) => !filter.sessionId || record.sessionId === filter.sessionId)
+    .filter((record) => !filter.activeOnly || isActiveStatus(record.status))
+    .sort((left, right) => compareText(right.startedAt, left.startedAt))
+    .slice(0, 200)
+}