@xingular/harness 0.0.0-stage → 0.1.0

package/src/server/server.test.ts

@@ -0,0 +1,174 @@
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { memorySecretStore } from '../accounts/secrets'
+import { createHarness, type Harness } from '../harness'
+import type { PiSessionLike } from '../sessions/runner'
+import { rootWithProject, writeFile } from '../../tests/helpers'
+import { remoteDirectory, remotePolicy, remoteSecrets, remoteTools } from './remote'
+import { RpcPeer, type Transport } from './rpc'
+import { attach, serve } from './serve'
+
+const open: Harness[] = []
+afterEach(async () => {
+  for (const harness of open.splice(0)) await harness.close()
+})
+
+/** A host on the other end of the protocol: sends requests, answers the harness's calls. */
+function host(hostCalls: Record<string, (params: any) => unknown> = {}) {
+  let toHarness: (line: string) => void = () => undefined
+  const events: any[] = []
+  const notices: any[] = []
+  const waiting = new Map<string, { resolve: (value: any) => void; reject: (error: any) => void }>()
+  let next = 0
+  const transport: Transport = {
+    onLine: (listener) => void (toHarness = listener),
+    write: (line) => {
+      const message = JSON.parse(line)
+      if (message.event) events.push(message.event)
+      else if (message.notice) notices.push(message.notice)
+      else if (message.call) {
+        queueMicrotask(async () => {
+          try {
+            const handler = hostCalls[message.call]
+            if (!handler) throw new Error(`host has no ${message.call}`)
+            toHarness(JSON.stringify({ v: 1, id: message.id, result: (await handler(message.params)) ?? null }))
+          } catch (error) {
+            toHarness(JSON.stringify({ v: 1, id: message.id, error: { code: 'host_error', message: error instanceof Error ? error.message : String(error) } }))
+          }
+        })
+      } else {
+        const pending = waiting.get(message.id)
+        waiting.delete(message.id)
+        if (message.error) pending?.reject(message.error)
+        else pending?.resolve(message.result)
+      }
+    }
+  }
+  const request = <T = any>(method: string, params: unknown = {}): Promise<T> =>
+    new Promise<T>((resolve, reject) => {
+      const id = `h${++next}`
+      waiting.set(id, { resolve, reject })
+      toHarness(JSON.stringify({ v: 1, id, method, params }))
+    })
+  return { transport, request, events, notices }
+}
+
+const idle = (): PiSessionLike => ({ sessionId: 'native-1', subscribe: () => () => undefined, prompt: async () => undefined, sendCustomMessage: async () => undefined, abort: async () => undefined, dispose: () => undefined })
+
+describe('the harness served to a host', () => {
+  it('answers by method name, reports failures with their code, and forwards events and notices', async () => {
+    const { transport, request, events, notices } = host()
+    const harness = createHarness({ dataRoot: rootWithProject(), stateDir: mkdtempSync(join(tmpdir(), 'hs-')), secrets: memorySecretStore(), sessionFactory: async () => idle() })
+    open.push(harness)
+    serve(harness, transport)
+
+    const status = await request('harness.status')
+    expect(status).toMatchObject({ dataRoot: harness.env.root, productName: 'Xingular Harness', activeRuns: [] })
+    expect(await request<string[]>('harness.methods')).toEqual(expect.arrayContaining(['accounts.list', 'sessions.run', 'wiki.pages', 'terminal.prepare', 'skills.list', 'skills.import', 'connections.list', 'harness.shutdown']))
+
+    const overview = await request('accounts.create', { label: 'Main', authKind: 'apiKey' })
+    expect(overview.accounts).toHaveLength(1)
+    expect(notices).toContainEqual(expect.objectContaining({ type: 'accounts.changed' }))
+    await expect(request('accounts.rename', { accountId: 'nope', label: 'x' })).rejects.toMatchObject({ code: 'not_found' })
+    await expect(request('accounts.rename', {})).rejects.toMatchObject({ code: 'invalid_request', message: 'accountId is required.' })
+    await expect(request('nope.nothing')).rejects.toMatchObject({ code: 'unknown_method' })
+
+    expect((await request<any[]>('wiki.namespaces')).map((entry) => entry.namespace)).toEqual(expect.arrayContaining(['/projects/app']))
+    const blocks = await request<any[]>('blocks.list', { agentIds: ['a1'] })
+    expect(blocks.map((block) => block.label)).toEqual(expect.arrayContaining(['user', 'persona', 'notes']))
+    expect(await request('memory.call', { context: { agentId: 'a1', agentName: 'Helper', actor: 'Chat' }, call: 'memory.append', params: { block: 'notes', text: 'Ship on Fridays.' } })).toContain('notes')
+    expect(notices).toContainEqual({ type: 'wiki.changed' })
+    const compiled = await request('context.compile', { context: { agentId: 'a1', agentName: 'Helper', actor: 'Chat' }, render: true })
+    expect(compiled.text).toContain('Ship on Fridays.')
+    expect(await request('context.profiles')).toEqual({ profiles: {}, stats: [] })
+
+    const started = await request('sessions.run', { run: { id: 'r1', sessionId: 'a1' }, cwd: harness.env.root, sessionDir: join(harness.env.root, 'sessions', 'a1'), text: 'hello', caller: { agentId: 'a1', agentName: 'Helper', actor: 'Chat' }, tools: { allow: ['read'] } })
+    expect(started).toEqual({ runId: 'r1', nativeSessionId: 'native-1' })
+    await new Promise((resolve) => setTimeout(resolve, 30))
+    expect(events.map((event) => event.type)).toEqual(['started', 'status.changed', 'context.snapshot', 'completed'])
+    expect((await request('runs.load', { runId: 'r1' })).run).toMatchObject({ id: 'r1', status: 'completed' })
+    expect((await request<any[]>('runs.list', { filter: { sessionId: 'a1' } })).map((run) => run.id)).toEqual(['r1'])
+    expect((await request('context.profiles')).stats).toMatchObject([{ subject: 'a1', mode: 'chat', contextProfile: 'full', runs: 1, completed: 1, runIds: ['r1'] }])
+  })
+
+  it('lets a host that is not a Node program supply secrets, policy, names, and tools over the protocol', async () => {
+    const secrets = new Map<string, string>()
+    const called: any[] = []
+    const { transport, request } = host({
+      'secrets.get': ({ key }) => secrets.get(key) ?? null,
+      'secrets.set': ({ key, value }) => void secrets.set(key, value),
+      'secrets.delete': ({ key }) => void secrets.delete(key),
+      'policy.scope': ({ tool }) => ({ allowed: tool !== 'bash', reason: 'No shell here.' }),
+      'policy.authorize': () => null,
+      'tools.call': (params) => {
+        called.push(params)
+        return { ok: true, echoed: params.input }
+      }
+    })
+    const peer = new RpcPeer(transport)
+    let gate: { check: (name: string, input: unknown) => Promise<string | null> } | null = null
+    let offered: { name: string; execute: (input: Record<string, unknown>) => Promise<unknown> }[] = []
+    const harness = createHarness({
+      dataRoot: rootWithProject(),
+      stateDir: mkdtempSync(join(tmpdir(), 'hs-')),
+      secrets: remoteSecrets(peer),
+      policy: remotePolicy(peer),
+      directory: remoteDirectory(peer),
+      sessionFactory: async (input) => {
+        gate = input.gate
+        offered = input.tools.filter((tool) => input.allow.includes(tool.name))
+        return idle()
+      }
+    })
+    open.push(harness)
+    harness.sessions.provide(remoteTools(peer))
+    attach(harness, peer)
+
+    const { accounts } = await request('accounts.create', { label: 'Main', authKind: 'apiKey' })
+    await request('accounts.setApiKey', { accountId: accounts[0].id, key: 'sk-test-0000000000000000', provider: 'anthropic' })
+    expect([...secrets.keys()]).toEqual([`${accounts[0].id}/pi-auth/anthropic`])
+
+    await request('directory.set', { agents: { a1: 'Scout' } })
+    expect(harness.env.directory.agentName('a1')).toBe('Scout')
+
+    expect(await request('tools.register', { tools: [{ name: 'lookup', description: 'Look something up', parameters: { type: 'object', properties: { q: { type: 'string' } } } }] })).toEqual({ registered: ['lookup'] })
+    await request('sessions.run', { run: { id: 'r1', sessionId: 'a1' }, cwd: harness.env.root, sessionDir: join(harness.env.root, 'sessions', 'a1'), text: 'hello', caller: { agentId: 'a1', actor: 'Chat' }, tools: { allow: ['lookup', 'bash'] } })
+    expect(offered.map((tool) => tool.name)).toContain('lookup')
+    expect(await offered.find((tool) => tool.name === 'lookup')!.execute({ q: 'x' })).toBe('{"ok":true,"echoed":{"q":"x"}}')
+    expect(called[0]).toMatchObject({ name: 'lookup', runId: 'r1', sessionId: 'a1', caller: { agentId: 'a1' } })
+    expect(await gate!.check('bash', {})).toBe('No shell here.')
+    expect(await gate!.check('lookup', {})).toBeNull()
+  })
+})
+
+describe('built-in skills', () => {
+  it('are on everywhere until switched off, and a person\'s own item of the same name replaces one', async () => {
+    const builtins = mkdtempSync(join(tmpdir(), 'builtin-'))
+    writeFile(join(builtins, 'skills', 'review', 'SKILL.md'), '---\nname: review\ndescription: Review a change before it ships\n---\nRead the diff first.\n')
+    writeFile(join(builtins, 'rules', 'plain.md'), '---\nname: Plain words\ndescription: Write plainly\n---\nUse plain words.\n')
+    const { transport, request } = host()
+    const harness = createHarness({ dataRoot: rootWithProject(), stateDir: mkdtempSync(join(tmpdir(), 'hs-')), secrets: memorySecretStore(), builtins: [builtins] })
+    open.push(harness)
+    serve(harness, transport)
+
+    const state = await request('skills.list')
+    expect(state.items).toMatchObject([{ id: 'rules/plain', builtin: true }, { id: 'skills/review', builtin: true }])
+    expect(state.enabled.global).toEqual(['rules/plain', 'skills/review'])
+    expect((await request<any[]>('skills.enabledFor', { projectId: 'p1' })).map((item) => item.id)).toEqual(['rules/plain', 'skills/review'])
+    expect((await request('context.compile', { context: { projectId: 'p1', actor: 'Code' }, render: true })).text).toContain('Use plain words.')
+
+    const off = await request('skills.setEnabled', { projectId: null, ids: ['skills/review'] })
+    expect(off.enabled).toMatchObject({ global: ['skills/review'], builtinOff: ['rules/plain'] })
+    expect((await request<any[]>('skills.enabledFor', {})).map((item) => item.id)).toEqual(['skills/review'])
+
+    writeFile(join(harness.env.root, 'registry', 'skills', 'review', 'SKILL.md'), '---\nname: review\ndescription: My own review steps\n---\nMine.\n')
+    const mine = (await request('skills.list')).items.find((item: any) => item.id === 'skills/review')
+    expect(mine).toMatchObject({ description: 'My own review steps' })
+    expect(mine.builtin).toBeUndefined()
+    // A person's own item is enabled the usual way, not by default.
+    expect((await request<any[]>('skills.enabledFor', {})).map((item) => item.id)).toEqual([])
+  })
+})

package/src/sessions/approvals.ts

@@ -0,0 +1,118 @@
+// What the user has chosen to stop being asked about: an "always approve" switch per kind of
+// session and, per session, the tools they answered "Always allow" for.
+import { chmodSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { Bus } from '../core/bus'
+import { invalid } from '../core/errors'
+import { readJson, writeJson } from '../core/fs'
+import type { RunRecord } from './contracts'
+
+/** Kinds of session with a switch: an agent's own conversations, and sessions in a project. */
+export const APPROVAL_KEYS = ['chat', 'pi'] as const
+
+export interface ApprovalPolicy {
+  /** Switch key → every approval is granted without asking. */
+  auto: Record<string, boolean>
+  /** Session id → approval targets always allowed there. */
+  remembered: Record<string, string[]>
+}
+
+/** Why a request is granted without asking. */
+export type AutomaticReason = 'always' | 'remembered' | 'scope'
+
+/** What only the embedding application knows about a pending approval. */
+export interface ApprovalFacts {
+  /** Unattended work keeps to its saved scope whatever the switches say. */
+  unattended?: boolean
+  /** The session may not change anything; the switch must not approve its way out of that. */
+  readOnly?: boolean
+  /** The application's own scope already covers this exact operation. */
+  inScope?: boolean
+}
+
+/** Why the standing choices grant this request, if they do. */
+export function decide(policy: ApprovalPolicy, key: string, sessionId: string, target: string): AutomaticReason | null {
+  if (policy.auto[key]) return 'always'
+  return policy.remembered[sessionId]?.includes(target) ? 'remembered' : null
+}
+
+export function grant(policy: ApprovalPolicy, key: string, sessionId: string, target: string, facts: ApprovalFacts = {}): AutomaticReason | null {
+  if (facts.unattended) return null
+  // "Always approve" must not let a read-only session approve its way out of read-only mode.
+  return decide(facts.readOnly ? { auto: {}, remembered: policy.remembered } : policy, key, sessionId, target)
+}
+
+/** A conversation's runs share one switch whatever model they use; other runs follow their own. */
+export const approvalKey = (run: Pick<RunRecord, 'mode' | 'harness'>): string => (run.mode === 'chat' ? 'chat' : run.harness)
+
+export class Approvals {
+  private readonly path: string
+
+  constructor(stateDir: string, private readonly bus: Bus) {
+    this.path = join(stateDir, 'approvals.json')
+  }
+
+  read(): ApprovalPolicy {
+    const stored = readJson<Partial<ApprovalPolicy>>(this.path) ?? {}
+    return { auto: stored.auto ?? {}, remembered: stored.remembered ?? {} }
+  }
+
+  private change(update: (policy: ApprovalPolicy) => void): ApprovalPolicy {
+    const policy = this.read()
+    update(policy)
+    writeJson(this.path, policy)
+    try {
+      chmodSync(this.path, 0o600)
+    } catch {
+      // The file was written; a mode that cannot be set is not worth failing the change.
+    }
+    this.bus.emit({ type: 'approvals.changed' })
+    return policy
+  }
+
+  isAuto(key: string): boolean {
+    try {
+      return Boolean(this.read().auto[key])
+    } catch {
+      return false
+    }
+  }
+
+  /** Why this run's approval for `target` can be granted without asking, if it can. */
+  automatic(run: RunRecord, target: string, facts: ApprovalFacts = {}): AutomaticReason | null {
+    // What the application's own scope already covers needs neither the switch nor the user.
+    return grant(this.read(), approvalKey(run), run.sessionId, target, facts) ?? (!facts.unattended && facts.inScope ? 'scope' : null)
+  }
+
+  setAuto(key: string, on: boolean): ApprovalPolicy {
+    if (!(APPROVAL_KEYS as readonly string[]).includes(key)) throw invalid('Unknown harness.')
+    return this.change((policy) => void (policy.auto[key] = on))
+  }
+
+  /** Always allow `target` in this session. */
+  remember(sessionId: string, target: string): ApprovalPolicy {
+    if (!target.trim()) throw invalid('A tool is required.')
+    return this.change((policy) => {
+      const targets = (policy.remembered[sessionId] ??= [])
+      if (!targets.includes(target)) targets.push(target)
+    })
+  }
+
+  forget(sessionId: string, target: string): ApprovalPolicy {
+    return this.change((policy) => {
+      const targets = policy.remembered[sessionId]?.filter((item) => item !== target) ?? []
+      if (targets.length) policy.remembered[sessionId] = targets
+      else delete policy.remembered[sessionId]
+    })
+  }
+
+  /** Forgets what was remembered for a session that no longer exists. */
+  forgetSession(sessionId: string): void {
+    try {
+      if (sessionId in this.read().remembered) this.change((policy) => void delete policy.remembered[sessionId])
+    } catch {
+      // Nothing recorded.
+    }
+  }
+}

package/src/sessions/contracts.ts

@@ -0,0 +1,299 @@
+// Run records and the run-event stream: the one contract every session shares. Every event is
+// validated against these schemas before it is persisted or handed to a listener.
+import { z } from 'zod'
+
+export const runStatusSchema = z.enum(['queued', 'running', 'waiting_for_approval', 'waiting_for_input', 'interrupted', 'completed', 'failed'])
+export type RunStatus = z.infer<typeof runStatusSchema>
+
+export const runEventTypeSchema = z.enum([
+  'started',
+  'context.snapshot',
+  'message.delta',
+  'message.completed',
+  'tool.started',
+  'tool.completed',
+  'retry.started',
+  'retry.ended',
+  'compaction.started',
+  'compaction.ended',
+  'approval.requested',
+  'approval.resolved',
+  'question.requested',
+  'question.answered',
+  'extension.notice',
+  'reaction.added',
+  'agent.message',
+  'artifact.added',
+  'file.changed',
+  'usage.updated',
+  'account.status',
+  'status.changed',
+  'failed',
+  'completed'
+])
+export type RunEventType = z.infer<typeof runEventTypeSchema>
+
+const messageDeltaPayload = z.object({ messageId: z.string(), text: z.string() })
+const messageCompletedPayload = z.object({ messageId: z.string(), role: z.enum(['user', 'assistant']), text: z.string() })
+const contextSnapshotPayload = z.object({
+  systemPrompt: z.string().max(100_000),
+  contextUpdate: z.string().max(100_000).optional(),
+  tools: z.array(z.object({ name: z.string(), description: z.string().max(2_000), parameters: z.unknown() })).max(120),
+  systemPromptTruncated: z.boolean().optional(),
+  contextUpdateTruncated: z.boolean().optional(),
+  toolsTruncated: z.boolean().optional()
+})
+const toolPayload = z.object({
+  toolCallId: z.string(),
+  name: z.string(),
+  summary: z.string().max(200).optional(),
+  input: z.string().max(24_000).optional(),
+  inputTruncated: z.boolean().optional(),
+  output: z.string().max(24_000).optional(),
+  outputTruncated: z.boolean().optional(),
+  ok: z.boolean().optional(),
+  /** On `tool.completed`: how long the call ran, and the size of what it returned to the model. */
+  durationMs: z.number().optional(),
+  resultChars: z.number().optional()
+})
+const retryStartedPayload = z.object({ attempt: z.number(), maxAttempts: z.number(), delayMs: z.number(), error: z.string().max(1_000).optional() })
+const retryEndedPayload = z.object({ attempt: z.number(), success: z.boolean(), error: z.string().max(1_000).optional() })
+const compactionStartedPayload = z.object({ reason: z.string() })
+const compactionEndedPayload = z.object({
+  reason: z.string(),
+  aborted: z.boolean(),
+  willRetry: z.boolean().optional(),
+  error: z.string().max(1_000).optional(),
+  tokensBefore: z.number().optional(),
+  tokensAfter: z.number().optional(),
+  summary: z.string().max(24_000).optional(),
+  summaryTruncated: z.boolean().optional()
+})
+/** Granted without asking: the standing switch, a remembered tool, or the embedding application's own scope. */
+const approvalAutomaticSchema = z.enum(['always', 'remembered', 'scope'])
+const approvalRequestedPayload = z.object({
+  approvalId: z.string(),
+  target: z.string(),
+  action: z.string(),
+  screenshotRef: z.string().optional(),
+  operation: z.object({ tool: z.string(), args: z.unknown() }).optional(),
+  /** A tool the user may choose to always allow for this session. */
+  rememberable: z.boolean().optional(),
+  /** Set when the request was granted as it was made, so nobody is waiting on it. */
+  automatic: approvalAutomaticSchema.optional()
+})
+const approvalResolvedPayload = z.object({ approvalId: z.string(), decision: z.enum(['approved', 'denied', 'native']), automatic: approvalAutomaticSchema.optional() })
+export const questionOptionSchema = z.object({ label: z.string().min(1), description: z.string().optional() })
+export type QuestionOption = z.infer<typeof questionOptionSchema>
+const questionRequestedPayload = z.object({
+  questionId: z.string(),
+  question: z.string().min(1),
+  options: z.array(questionOptionSchema),
+  multiSelect: z.boolean(),
+  allowText: z.boolean(),
+  userOnly: z.boolean().optional()
+})
+const questionAnsweredPayload = z.object({ questionId: z.string(), selected: z.array(z.string()), text: z.string().optional() })
+/** A short emoji sequence, never words or numbers. */
+const reactionAddedPayload = z.object({ emoji: z.string().min(1).refine((text) => Buffer.byteLength(text) <= 16 && !/[A-Za-z0-9\s]/.test(text)) })
+/** A message this run's agent sent to (`to`) or received back from (`from`) another agent. */
+const agentMessagePayload = z.object({ direction: z.enum(['to', 'from']), agentId: z.string(), agentName: z.string(), text: z.string() })
+/** A status line, a notification or an error from a Pi extension loaded in the session. */
+const extensionNoticePayload = z.object({
+  kind: z.enum(['notify', 'status', 'widget', 'title', 'error']),
+  level: z.enum(['info', 'warning', 'error']).optional(),
+  key: z.string().optional(),
+  text: z.string(),
+  extension: z.string().optional()
+})
+const artifactPayload = z.object({ artifactId: z.string(), name: z.string(), file: z.unknown().optional() })
+const fileChangedPayload = z.object({ path: z.string(), change: z.enum(['added', 'modified', 'deleted']) })
+/** Where a cost figure comes from: Pi reported it, or the tokens were priced at list rates. */
+export const costSourceSchema = z.enum(['harness', 'estimate', 'mixed'])
+export type CostSource = z.infer<typeof costSourceSchema>
+/** What one model request used. Token fields mean the same as on the run's totals. */
+export const usageRequestSchema = z.object({
+  /** Position in the run, from 1. */
+  index: z.number(),
+  responseId: z.string().optional(),
+  model: z.string().optional(),
+  provider: z.string().optional(),
+  inputTokens: z.number().optional(),
+  cacheReadTokens: z.number().optional(),
+  cacheWriteTokens: z.number().optional(),
+  outputTokens: z.number().optional(),
+  reasoningTokens: z.number().optional(),
+  costUsd: z.number().optional(),
+  costSource: z.enum(['harness', 'estimate']).optional(),
+  /** Separate provider-supplied summary; never generic private thinking content. */
+  reasoningSummary: z.string().max(4_000).optional(),
+  /** From sending the request to the end of the response, and to its first output. */
+  durationMs: z.number().optional(),
+  ttftMs: z.number().optional(),
+  stopReason: z.string().optional()
+})
+export type UsageRequest = z.infer<typeof usageRequestSchema>
+/** Token totals so far in this run (cumulative for the run, not the native session). */
+export const usagePayloadSchema = z.object({
+  /** Input tokens that were not read from the provider's cache. */
+  inputTokens: z.number().optional(),
+  /** Includes reasoning tokens. */
+  outputTokens: z.number().optional(),
+  cacheReadTokens: z.number().optional(),
+  cacheWriteTokens: z.number().optional(),
+  reasoningTokens: z.number().optional(),
+  costUsd: z.number().optional(),
+  costSource: costSourceSchema.optional(),
+  /** Model requests made so far. */
+  requests: z.number().optional(),
+  /** Size of the latest request (not cumulative), and the model's limit. */
+  contextTokens: z.number().optional(),
+  contextWindow: z.number().optional(),
+  model: z.string().optional(),
+  provider: z.string().optional(),
+  /** The request this update reports. */
+  request: usageRequestSchema.optional()
+})
+export type UsagePayload = z.infer<typeof usagePayloadSchema>
+export const accountIssueCategorySchema = z.enum(['auth_expired', 'rate_limited', 'quota', 'network', 'unknown'])
+export type AccountIssueCategory = z.infer<typeof accountIssueCategorySchema>
+export const accountLimitSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  usedPercent: z.number().nullable().optional(),
+  resetsAt: z.string().nullable().optional(),
+  windowMinutes: z.number().nullable().optional(),
+  status: z.string().nullable().optional()
+})
+export type AccountLimit = z.infer<typeof accountLimitSchema>
+/** Limit snapshots, plan changes, and classified account failures. */
+const accountStatusPayload = z.object({
+  accountId: z.string(),
+  category: accountIssueCategorySchema.optional(),
+  message: z.string().optional(),
+  resetsAt: z.string().optional(),
+  plan: z.string().optional(),
+  limits: z.array(accountLimitSchema).optional()
+})
+const statusPayload = z.object({ status: runStatusSchema, reason: z.string().optional() })
+const failedPayload = z.object({ code: z.string(), message: z.string() })
+const emptyPayload = z.object({}).passthrough()
+
+/** Payload schema per discriminant. */
+export const runEventPayloadSchemas = {
+  started: emptyPayload,
+  'context.snapshot': contextSnapshotPayload,
+  'message.delta': messageDeltaPayload,
+  'message.completed': messageCompletedPayload,
+  'tool.started': toolPayload,
+  'tool.completed': toolPayload,
+  'retry.started': retryStartedPayload,
+  'retry.ended': retryEndedPayload,
+  'compaction.started': compactionStartedPayload,
+  'compaction.ended': compactionEndedPayload,
+  'approval.requested': approvalRequestedPayload,
+  'approval.resolved': approvalResolvedPayload,
+  'question.requested': questionRequestedPayload,
+  'question.answered': questionAnsweredPayload,
+  'extension.notice': extensionNoticePayload,
+  'reaction.added': reactionAddedPayload,
+  'agent.message': agentMessagePayload,
+  'artifact.added': artifactPayload,
+  'file.changed': fileChangedPayload,
+  'usage.updated': usagePayloadSchema,
+  'account.status': accountStatusPayload,
+  'status.changed': statusPayload,
+  failed: failedPayload,
+  completed: emptyPayload
+} satisfies Record<RunEventType, z.ZodType>
+
+export const runEventSchema = z
+  .object({
+    id: z.string(),
+    runId: z.string(),
+    sessionId: z.string(),
+    sequence: z.number().int().nonnegative(),
+    timestamp: z.string(),
+    type: runEventTypeSchema,
+    payload: z.unknown(),
+    /** The native event this one was derived from, kept as evidence. */
+    native: z.unknown().optional(),
+    /** Set when consecutive text deltas were merged for relay; covers sequences coalescedFrom..sequence. */
+    coalescedFrom: z.number().int().nonnegative().optional()
+  })
+  .superRefine((event, context) => {
+    if (!runEventPayloadSchemas[event.type].safeParse(event.payload).success) {
+      context.addIssue({ code: 'custom', path: ['payload'], message: `Invalid payload for ${event.type}` })
+    }
+  })
+export type RunEvent = z.infer<typeof runEventSchema>
+
+/**
+ * One tracked execution interval of a session. `mode`, `harness`, `sessionType`, `worktreeId`,
+ * `attachmentCount`, `exitCode`, `handoffId` and `trigger` belong to the embedding application:
+ * the harness stores and returns them, and reads only `mode` (`chat` is an agent's own
+ * conversation, `code` is a session in a project).
+ */
+export interface RunRecord {
+  resumedFromRunId: string | null
+  /** Opaque run lineage supplied by the embedding application. */
+  parentRunId: string | null
+  relation: string | null
+  terminalReason: string | null
+  id: string
+  projectId: string | null
+  mode: string
+  harness: string
+  sessionType: string
+  sessionId: string
+  nativeSessionId: string | null
+  workingDirectory: string | null
+  worktreeId: string | null
+  goal: string | null
+  attachmentCount: number
+  startedAt: string
+  endedAt: string | null
+  status: string
+  exitCode: number | null
+  handoffId: string | null
+  /** The account the run used. */
+  accountId: string | null
+  /** The agent that replied. */
+  agentId: string | null
+  /** What started the run. */
+  trigger: string | null
+}
+
+const text = z.string().nullish().transform((value) => value ?? null)
+
+export const runRecordSchema = z.object({
+  resumedFromRunId: text,
+  parentRunId: text,
+  relation: text,
+  terminalReason: text,
+  id: z.string(),
+  projectId: text,
+  mode: z.string(),
+  harness: z.string(),
+  sessionType: z.string(),
+  sessionId: z.string(),
+  nativeSessionId: text,
+  workingDirectory: text,
+  worktreeId: text,
+  goal: text,
+  attachmentCount: z.number().int().nonnegative().default(0),
+  startedAt: z.string(),
+  endedAt: text,
+  status: z.string(),
+  exitCode: z.number().int().nullish().transform((value) => value ?? null),
+  handoffId: text,
+  accountId: text,
+  agentId: text,
+  trigger: text
+}) satisfies z.ZodType<RunRecord, unknown>
+
+export const ACTIVE_STATUSES: readonly string[] = ['queued', 'running', 'waiting_for_approval', 'waiting_for_input']
+
+export function isActiveStatus(status: string): boolean {
+  return ACTIVE_STATUSES.includes(status)
+}