@xingular/harness 0.1.7 → 1.0.0

package/src/server/server.test.ts

@@ -1,174 +0,0 @@
-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

@@ -1,118 +0,0 @@
-// 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

@@ -1,336 +0,0 @@
-// 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',
-  'message.steered',
-  '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() })
-/** A message the person sent into the run while it was going; the model reads it from its next request on. */
-const messageSteeredPayload = z.object({ 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()
-})
-/** Generic reference to content a provider stores outside the run-event stream. */
-export const toolAttachmentRefSchema = z.object({
-  id: z.string().min(1).max(300),
-  name: z.string().min(1).max(500),
-  mimeType: z.string().min(1).max(100)
-}).strict()
-export const toolAttachmentRefsSchema = z.array(toolAttachmentRefSchema).max(16)
-export type ToolAttachmentRef = z.infer<typeof toolAttachmentRefSchema>
-
-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(),
-  /** Opaque attachment references. Content stays outside the run event stream. */
-  attachments: toolAttachmentRefsSchema.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 questionBatchFields = {
-  batchId: z.string().min(1).optional(),
-  batchIndex: z.number().int().min(1).max(5).optional(),
-  batchCount: z.number().int().min(1).max(5).optional()
-}
-const questionBatchRefinement = <T extends { batchId?: string; batchIndex?: number; batchCount?: number }>(value: T, context: z.RefinementCtx): void => {
-  const fields = [value.batchId, value.batchIndex, value.batchCount]
-  if (fields.some((field) => field !== undefined) && fields.some((field) => field === undefined)) {
-    context.addIssue({ code: z.ZodIssueCode.custom, message: 'Question batch fields must be supplied together.' })
-  }
-  if (value.batchIndex !== undefined && value.batchCount !== undefined && value.batchIndex > value.batchCount) {
-    context.addIssue({ code: z.ZodIssueCode.custom, message: 'Question batch index cannot exceed its count.' })
-  }
-}
-const questionRequestedPayload = z.object({
-  questionId: z.string(),
-  question: z.string().min(1),
-  summary: z.string().min(1).max(100).optional(),
-  options: z.array(questionOptionSchema),
-  multiSelect: z.boolean(),
-  allowText: z.boolean(),
-  userOnly: z.boolean().optional(),
-  ...questionBatchFields
-}).superRefine(questionBatchRefinement)
-const questionAnsweredPayload = z.object({
-  questionId: z.string(),
-  selected: z.array(z.string()),
-  text: z.string().optional(),
-  notes: z.record(z.string(), z.string().max(10_000)).optional(),
-  ...questionBatchFields
-}).superRefine(questionBatchRefinement)
-/** 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,
-  'message.steered': messageSteeredPayload,
-  '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)
-}