@xingular/harness 0.1.7 → 1.0.0

package/src/sessions/runStore.test.ts

@@ -1,152 +0,0 @@
-import { appendFileSync, mkdtempSync, readFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { expect, test } from 'vitest'
-
-import { now } from '../core/fs'
-import { closeIndex } from '../core/index'
-import { isActiveStatus, runEventPayloadSchemas, runRecordSchema, type RunEvent, type RunEventType } from './contracts'
-import { appendEvent, executionEvents, loadRun, markInterruptedRuns, pendingDecisions, persistEvent, readEvents, runDir, saveRun, updateRun } from './runStore'
-
-const temp = () => mkdtempSync(join(tmpdir(), 'harness-runs-'))
-const valid = (type: RunEventType, payload: unknown): boolean => runEventPayloadSchemas[type].safeParse(payload).success
-
-function fixtureRun(root: string, status: string) {
-  const run = runRecordSchema.parse({ id: 'run-1', sessionId: 'agent-1', projectId: null, mode: 'chat', harness: 'pi', sessionType: 'structured', nativeSessionId: null, workingDirectory: null, worktreeId: null, goal: null, status, startedAt: 'start', endedAt: null })
-  saveRun(root, run)
-  return run
-}
-
-const fixtureEvent = (sequence: number, type: string, payload: unknown): RunEvent => ({ id: `e${sequence}`, runId: 'run-1', sessionId: 'agent-1', sequence, timestamp: `time-${sequence}`, type: type as RunEventType, payload })
-
-test('execution prefix includes first terminal and excludes ignored evidence', () => {
-  for (const status of ['completed', 'failed', 'interrupted']) {
-    const ignored = { ...fixtureEvent(1, 'usage.updated', { outputTokens: 99 }), native: { hostIgnored: 'run_already_ended' } }
-    const events = [fixtureEvent(0, 'started', {}), ignored, fixtureEvent(2, 'status.changed', { status }), fixtureEvent(3, 'message.completed', { text: 'late' })]
-    expect(executionEvents(events).map((event) => event.sequence)).toEqual([0, 2])
-  }
-})
-
-test('trajectory evidence event payloads are validated', () => {
-  expect(valid('context.snapshot', { systemPrompt: 'app prompt', contextUpdate: 'changed context', tools: [{ name: 'read', description: 'Read a file', parameters: { type: 'object' } }], contextUpdateTruncated: false })).toBe(true)
-  expect(valid('context.snapshot', { systemPrompt: 'prompt', tools: [{ name: 'read' }] })).toBe(false)
-  expect(valid('tool.started', { toolCallId: 't', name: 'read', input: '{}', inputTruncated: false })).toBe(true)
-  expect(valid('tool.completed', { toolCallId: 't', name: 'read', ok: true, output: 'text', outputTruncated: true })).toBe(true)
-  expect(valid('retry.started', { attempt: 1, maxAttempts: 3, delayMs: 250, error: 'temporary' })).toBe(true)
-  expect(valid('retry.ended', { attempt: 1, success: true })).toBe(true)
-  expect(valid('compaction.started', { reason: 'threshold' })).toBe(true)
-  expect(valid('compaction.ended', { reason: 'threshold', aborted: false, willRetry: true, summary: 'kept recent messages' })).toBe(true)
-  expect(valid('retry.ended', { attempt: 1, success: 'yes' })).toBe(false)
-})
-
-test('pending decisions are the requests nothing answered', () => {
-  const events = [
-    fixtureEvent(0, 'approval.requested', { approvalId: 'a1', target: 'shell', action: 'ls' }),
-    fixtureEvent(1, 'question.requested', { questionId: 'q1', question: 'Which?', options: [], multiSelect: false, allowText: true }),
-    fixtureEvent(2, 'approval.requested', { approvalId: 'a2', target: 'shell', action: 'pwd' }),
-    fixtureEvent(3, 'approval.resolved', { approvalId: 'a1', decision: 'denied' }),
-    // An answer to another kind of request with the same id settles nothing.
-    fixtureEvent(4, 'question.answered', { questionId: 'a2', selected: [] })
-  ]
-  expect(pendingDecisions(events).map((decision) => [decision.kind, decision.id, decision.eventId])).toEqual([['question', 'q1', 'e1'], ['approval', 'a2', 'e2']])
-  expect(valid('approval.requested', { approvalId: 'a3', target: 'shell', action: 'ls', automatic: 'scope' })).toBe(true)
-  expect(valid('approval.resolved', { approvalId: 'a3', decision: 'approved', automatic: 'scope' })).toBe(true)
-  expect(valid('approval.resolved', { approvalId: 'a3', decision: 'approved', automatic: 'whenever' })).toBe(false)
-})
-
-test('interruption is not overwritten by late tools, messages or completion', () => {
-  const root = temp()
-  fixtureRun(root, 'running')
-  expect(persistEvent(root, fixtureEvent(0, 'status.changed', { status: 'interrupted', reason: 'App stopped' }))).toBe(true)
-  const late: [number, string, unknown][] = [
-    [1, 'tool.completed', { toolCallId: 't1', name: 'bash', ok: false }],
-    [2, 'message.completed', { messageId: 'm1', role: 'assistant', text: 'Saved checkpoint' }],
-    [3, 'completed', {}],
-    [4, 'status.changed', { status: 'running' }]
-  ]
-  for (const [index, type, payload] of late) expect(persistEvent(root, fixtureEvent(index, type, payload))).toBe(false)
-  updateRun(root, 'run-1', (run) => {
-    run.status = 'completed'
-    run.nativeSessionId = 'native-1'
-  })
-  const run = loadRun(root, 'run-1')
-  expect([run.status, run.endedAt, run.nativeSessionId, run.terminalReason]).toEqual(['interrupted', 'time-0', 'native-1', 'App stopped'])
-  const events = readEvents(root, 'run-1')
-  expect(events).toHaveLength(5)
-  expect((events[2].payload as { text: string }).text).toBe('Saved checkpoint')
-  expect((events[3].native as { hostIgnored: string }).hostIgnored).toBe('run_already_ended')
-  closeIndex(root)
-})
-
-test('recovery repairs legacy outcomes once without erasing evidence', () => {
-  const root = temp()
-  fixtureRun(root, 'completed')
-  appendEvent(root, fixtureEvent(0, 'status.changed', { status: 'interrupted' }))
-  appendEvent(root, fixtureEvent(1, 'message.completed', { role: 'assistant', messageId: 'm', text: 'Partial answer' }))
-  appendEvent(root, fixtureEvent(2, 'completed', {}))
-  markInterruptedRuns(root)
-  const backup = join(runDir(root, 'run-1'), 'run.json.before-outcome-repair')
-  const original = readFileSync(backup, 'utf8')
-  expect(loadRun(root, 'run-1').status).toBe('interrupted')
-  expect(readEvents(root, 'run-1')).toHaveLength(3)
-  markInterruptedRuns(root)
-  expect(readFileSync(backup, 'utf8')).toBe(original)
-  expect(readEvents(root, 'run-1')).toHaveLength(3)
-  closeIndex(root)
-})
-
-test('a run that never settled is marked interrupted at startup', () => {
-  const root = temp()
-  fixtureRun(root, 'running')
-  appendEvent(root, fixtureEvent(0, 'started', {}))
-  expect(markInterruptedRuns(root)).toBe(1)
-  expect(loadRun(root, 'run-1').status).toBe('interrupted')
-  expect(readEvents(root, 'run-1').at(-1)).toMatchObject({ sequence: 1, type: 'status.changed' })
-  expect(markInterruptedRuns(root)).toBe(0)
-  closeIndex(root)
-})
-
-test('normal completion and failure are terminal too', () => {
-  const cases: [string, string, unknown][] = [['completed', 'completed', {}], ['failed', 'failed', { message: 'No quota', code: 'provider_error' }]]
-  for (const [type, expected, payload] of cases) {
-    const root = temp()
-    fixtureRun(root, 'running')
-    expect(persistEvent(root, fixtureEvent(0, type, payload))).toBe(true)
-    expect(persistEvent(root, fixtureEvent(1, 'status.changed', { status: 'running' }))).toBe(false)
-    expect(loadRun(root, 'run-1').status).toBe(expected)
-    closeIndex(root)
-  }
-})
-
-test('active run filter includes only work in progress', () => {
-  expect(['queued', 'running', 'waiting_for_approval'].every(isActiveStatus)).toBe(true)
-  expect(['completed', 'interrupted', 'failed'].some(isActiveStatus)).toBe(false)
-})
-
-test('validates payloads by type', () => {
-  expect(valid('message.delta', { messageId: 'm', text: 'hi' })).toBe(true)
-  expect(valid('message.delta', { text: 'hi' })).toBe(false)
-  expect(valid('usage.updated', { inputTokens: 3, outputTokens: 1 })).toBe(true)
-  expect(valid('usage.updated', { inputTokens: 3, cacheReadTokens: 9, reasoningTokens: 1, costUsd: 0.02, requests: 2, contextTokens: 12, contextWindow: 1000, model: 'm', provider: 'p' })).toBe(true)
-  expect(valid('usage.updated', { inputTokens: 3, costUsd: '0.02' })).toBe(false)
-  expect(valid('usage.updated', { provider: 4 })).toBe(false)
-  expect(valid('usage.updated', { request: { index: 1, reasoningSummary: 'The provider summary.' } })).toBe(true)
-  expect(valid('usage.updated', { request: { index: 1, reasoningSummary: 'x'.repeat(4_001) } })).toBe(false)
-  expect(valid('approval.resolved', { approvalId: 'a', decision: 'denied' })).toBe(true)
-  expect(valid('approval.resolved', { approvalId: 'a', decision: 'maybe' })).toBe(false)
-  expect(valid('question.requested', { questionId: 'q', question: 'Which?', options: [{ label: 'A' }], multiSelect: false, allowText: true })).toBe(true)
-  expect(valid('question.requested', { questionId: 'q', question: 'Which?', options: [{}], multiSelect: false, allowText: true })).toBe(false)
-  expect(valid('question.answered', { questionId: 'q', selected: ['A'], text: 'also B' })).toBe(true)
-  expect(valid('reaction.added', { emoji: '👍' })).toBe(true)
-  expect(valid('reaction.added', { emoji: 'lol' })).toBe(false)
-  expect(valid('agent.message', { direction: 'to', agentId: 'a', agentName: 'A', text: 'hi' })).toBe(true)
-  expect(valid('status.changed', { status: 'waiting_for_input' })).toBe(true)
-  expect(valid('status.changed', { status: 'done' })).toBe(false)
-})
-
-test('event log skips torn lines', () => {
-  const root = temp()
-  appendEvent(root, { id: 'e', runId: 'run-1', sessionId: 's', sequence: 0, timestamp: now(), type: 'started', payload: {} })
-  appendFileSync(join(runDir(root, 'run-1'), 'events.jsonl'), '{"id":"torn')
-  expect(readEvents(root, 'run-1')).toHaveLength(1)
-})

package/src/sessions/runStore.ts

@@ -1,332 +0,0 @@
-// 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)
-}