@xingular/harness 0.1.7 → 2.0.0

package/src/memory/maintenance.ts

@@ -5,6 +5,7 @@
 // their limit are condensed.
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { createHash } from 'node:crypto'
 
 import type { Accounts } from '../accounts/accounts'
 import { log, type Bus } from '../core/bus'
@@ -20,7 +21,7 @@ import { callerBlocks, type CallerContext } from './caller'
 import * as facts from './facts'
 import { piMaintainerFactory, runMaintenance, type ExistingBlock, type ExistingMemory, type ExistingPage, type MaintainerFactory, type MaintenanceRequest } from './maintainer'
 import { inbox, undo } from './operations'
-import { accept, apply, captureHashes, describeTrigger, parseProposalSet, writeIndex, type Evidence, type Trigger } from './proposals'
+import { accept, apply, captureHashes, describeTrigger, parseProposalSet, writeIndex, type Evidence, type ProposalSet, type SourceRef, type Trigger } from './proposals'
 import { looksSecret } from './secrets'
 import { enqueueCuration, listCuration, curationJob, saveCuration, requireCurator, type CurationJob } from './curation'
 import * as registry from '../skills/registry'
@@ -46,27 +47,30 @@ export function chatUpdatesPaused(settings: unknown): boolean {
   return (settings as { autoMaintenanceChat?: unknown } | null)?.autoMaintenanceChat === false
 }
 
+/** A run that automatic maintenance leaves alone for a settled reason: a setting, a pause, or no project. Not an error. */
+class NotEligible extends Error {}
+
 /** Where a settled run's knowledge is filed and what the job reads of it; throws the reason it is not eligible. */
 function runEvidence(root: string, runId: string): { namespace: string; transcript: string } {
   const run = findRun(root, runId)
   if (!run) throw new Error('Run was not found.')
   const settings = readJsonOr<{ excludedSourceIds?: unknown } | null>(join(root, 'config/settings.json'), null)
-  if (Array.isArray(settings?.excludedSourceIds) && settings.excludedSourceIds.includes(runId)) throw new Error('run excluded in settings')
+  if (Array.isArray(settings?.excludedSourceIds) && settings.excludedSourceIds.includes(runId)) throw new NotEligible('run excluded in settings')
   const projectId = run.mode === 'chat' || run.mode === 'code' ? run.projectId : null
   let namespace: string
   if (projectId) {
     const project = findProject(root, projectId)
-    if (!project.autoMaintenance) throw new Error('automatic updates are paused for this project')
+    if (!project.autoMaintenance) throw new NotEligible('automatic updates are paused for this project')
     namespace = project.wikiNamespace
   } else if (run.mode === 'chat') {
-    if (chatUpdatesPaused(settings)) throw new Error('automatic updates are paused for Chat')
+    if (chatUpdatesPaused(settings)) throw new NotEligible('automatic updates are paused for Chat')
     namespace = store.LIBRARY_NAMESPACE
   } else {
-    throw new Error('run has no project')
+    throw new NotEligible('run has no project')
   }
   const text = transcript(run.goal ?? '', readEvents(root, runId))
-  if (!text.includes('Assistant:')) throw new Error('no recorded assistant output to use as evidence')
-  if (looksSecret(text)) throw new Error('the run contains text that looks like a credential')
+  if (!text.includes('Assistant:')) throw new NotEligible('no recorded assistant output to use as evidence')
+  if (looksSecret(text)) throw new NotEligible('the run contains text that looks like a credential')
   return { namespace, transcript: text }
 }
 
@@ -144,6 +148,12 @@ export function fullBlocks(wiki: string, tried: Set<string>): string[] {
 
 const blockValues = (found: readonly blocks.Block[]): ExistingBlock[] => found.map((block) => ({ id: block.id, label: block.front.label, description: block.front.description, limit: block.front.limit, body: block.body }))
 
+export interface MaintenanceBatchDecision {
+  id: string
+  decision: 'apply' | 'reject' | 'needs_user'
+  reason: string
+}
+
 export interface MaintenanceOptions {
   env: HarnessEnv
   bus: Bus
@@ -208,7 +218,12 @@ export class Maintenance {
     if (this.idle) clearTimeout(this.idle)
     if (this.options.external) {
       if (job.kind === 'run') {
-        try { runEvidence(this.options.env.root, job.runId) } catch (error) { log('maintenance source skipped', error instanceof Error ? error.message : String(error)); return }
+        try {
+          runEvidence(this.options.env.root, job.runId)
+        } catch (error) {
+          if (!(error instanceof NotEligible)) log('maintenance source skipped', error instanceof Error ? error.message : String(error))
+          return
+        }
         const run = findRun(this.options.env.root, job.runId)
         const namespace = run?.projectId ? findProject(this.options.env.root, run.projectId).wikiNamespace : store.LIBRARY_NAMESPACE
         enqueueCuration(this.options.env.root, { ...job, namespace })
@@ -233,6 +248,150 @@ export class Maintenance {
 
   jobs(): CurationJob[] { return listCuration(this.options.env.root) }
 
+  /** Reads every request frozen into the current host-assigned review batch. */
+  readBatch(context: CallerContext): { jobs: unknown[] } {
+    requireCurator(context)
+    const ids = context.maintenanceJobIds ?? (context.maintenanceJobId ? [context.maintenanceJobId] : [])
+    return {
+      jobs: ids.map((id) => {
+        try {
+          return this.readJob(context, id)
+        } catch (error) {
+          return { id, status: 'failed', error: error instanceof Error ? error.message : String(error) }
+        }
+      })
+    }
+  }
+
+  /** Applies one evidence-checked Wiki change set for all accepted Wiki requests in a batch. */
+  applyBatch(context: CallerContext, decisions: readonly MaintenanceBatchDecision[], replacement: unknown): { operationId: string | null; jobs: CurationJob[] } {
+    requireCurator(context)
+    if (!decisions.length) throw invalid('Decide every assigned request in the batch.')
+    const ids = decisions.map((decision) => decision.id)
+    if (new Set(ids).size !== ids.length) throw invalid('Each request can appear only once in a batch decision.')
+    const assigned = context.maintenanceJobIds ?? (context.maintenanceJobId ? [context.maintenanceJobId] : [])
+    const pending = assigned.map((id) => curationJob(this.options.env.root, id)).filter((job) => !['completed', 'rejected', 'needs_user'].includes(job.status))
+    if (pending.some((job) => !ids.includes(job.id))) throw invalid('Decide every assigned request in one batch.')
+
+    const entries = decisions.map((decision) => {
+      if (!decision.reason.trim()) throw invalid('Explain every batch decision.')
+      if (!['apply', 'reject', 'needs_user'].includes(decision.decision)) throw invalid('Choose apply, reject, or needs_user for every request.')
+      const job = curationJob(this.options.env.root, decision.id)
+      if (context.maintenanceJobIds !== undefined && !context.maintenanceJobIds.includes(decision.id) && !('caller' in job.input && job.input.caller.runId === context.runId)) throw invalid('This request is not assigned to this run.')
+      if (job.runId && job.runId !== context.runId && job.status === 'running') throw invalid('Another run owns this request.')
+      return { decision, job }
+    })
+    const wikiEntries = entries.filter(({ decision, job }) => decision.decision === 'apply' && !['registry', 'plugin'].includes(job.input.kind) && !['completed', 'rejected', 'needs_user'].includes(job.status))
+    if (wikiEntries.length && replacement === undefined) throw invalid('Provide one combined, evidence-backed Wiki change set for the approved requests.')
+    const proposals: ProposalSet | null = wikiEntries.length ? parseProposalSet(replacement) : null
+    const operationId = wikiEntries.length ? `batch-${createHash('sha256').update(wikiEntries.map(({ job }) => job.id).sort().join('\0')).digest('hex').slice(0, 32)}` : null
+    const results = new Map<string, CurationJob>()
+
+    if (wikiEntries.length) {
+      const prepared = wikiEntries.map(({ job }) => this.claim(context, job.id))
+      const root = this.options.env.root
+      const wiki = store.wikiDir(root)
+      const evidence: Evidence = { runs: {}, sources: {}, blocks: [] }
+      const blocksSeen = new Set<string>()
+      const captured = new Map<string, string>()
+      const conflicts = new Set<string>()
+      for (const job of prepared) {
+        const input = job.input
+        for (const id of job.prepared?.evidence.blocks ?? (input.kind === 'proposal' ? input.proposals.blocks.map((proposal) => proposal.block) : [])) blocksSeen.add(id)
+        for (const [id, hash] of job.hashes) {
+          const previous = captured.get(id)
+          if (previous !== undefined && previous !== hash) conflicts.add(id)
+          else captured.set(id, hash)
+        }
+      }
+      for (const id of conflicts) captured.set(id, `conflicting-batch-snapshot:${id}`)
+      evidence.blocks = [...blocksSeen]
+
+      const refs: SourceRef[] = [...proposals!.pages, ...proposals!.memories, ...proposals!.blocks].flatMap((proposal) => proposal.sourceRefs)
+      const excluded = readJsonOr<{ excludedSourceIds?: unknown } | null>(join(root, 'config/settings.json'), null)?.excludedSourceIds
+      const excludedIds = Array.isArray(excluded) ? excluded.filter((id): id is string => typeof id === 'string') : []
+      for (const ref of refs) {
+        if (ref.kind === 'run' && findRun(root, ref.ref)) {
+          const caller = readJsonOr<CallerContext | null>(join(root, 'runs', ref.ref, 'caller.json'), null)
+          if (!excludedIds.includes(ref.ref) && caller?.vaultAccess !== 'curator') {
+            const text = evidenceText(root, ref.ref)
+            if (!looksSecret(text)) evidence.runs![ref.ref] = takeChars(text, 60_000)
+          }
+        }
+        if (ref.kind === 'source') {
+          const source = store.listSources(wiki).find((item) => item.id === ref.ref)
+          if (source) {
+            try {
+              const text = readFileSync(join(wiki, 'raw', source.id, source.name), 'utf8')
+              if (!looksSecret(text)) evidence.sources![ref.ref] = takeChars(text, 60_000)
+            } catch {
+              // Missing or unreadable evidence is rejected by the proposal validator.
+            }
+          }
+        }
+      }
+
+      const namespaceFor = (sourceRefs: readonly SourceRef[]): string => {
+        for (const ref of sourceRefs) {
+          const sourceJob = prepared.find((job) => {
+            if (job.input.kind === 'proposal') return job.input.caller.runId === ref.ref
+            if (job.input.kind === 'run') return job.input.runId === ref.ref
+            if (job.input.kind === 'ingest') return job.input.sourceId === ref.ref
+            return false
+          })
+          const namespace = sourceJob?.prepared?.namespace ?? (sourceJob?.input.kind === 'proposal' ? sourceJob.input.namespace : undefined)
+          if (namespace) return namespace
+        }
+        return prepared[0]?.prepared?.namespace ?? (prepared[0]?.input.kind === 'proposal' ? prepared[0].input.namespace : undefined) ?? store.LIBRARY_NAMESPACE
+      }
+      const batchProposals: ProposalSet = {
+        ...proposals!,
+        pages: proposals!.pages.map((proposal) => ({ ...proposal, namespace: proposal.namespace ?? namespaceFor(proposal.sourceRefs) })),
+        memories: proposals!.memories.map((proposal) => ({ ...proposal, namespace: proposal.namespace ?? namespaceFor(proposal.sourceRefs) }))
+      }
+      const trigger: Trigger = prepared.some((job) => job.input.kind === 'consolidate')
+        ? { kind: 'consolidate' }
+        : prepared.some((job) => job.input.kind === 'run')
+          ? { kind: 'run', runId: (prepared.find((job) => job.input.kind === 'run')!.input as Extract<Job, { kind: 'run' }>).runId }
+          : prepared.some((job) => job.input.kind === 'ingest')
+            ? (prepared.find((job) => job.input.kind === 'ingest')!.prepared?.trigger ?? { kind: 'agent', runId: context.runId ?? null, actor: context.agentName ?? 'Curator' })
+            : { kind: 'agent', runId: context.runId ?? null, actor: context.agentName ?? 'Curator' }
+      const outcome = apply(wiki, namespaceFor(refs), trigger, batchProposals, captured, evidence, operationId!, context.agentName ?? 'Curator')
+      if (outcome.operation) writeJson(join(wiki, 'operations', `${outcome.operation.id}.json`), { ...outcome.operation, protected: true })
+      reindexQuietly(root)
+      this.options.bus.emit({ type: 'wiki.changed' })
+      let operationAssigned = false
+      for (const { decision, job: original } of wikiEntries) {
+        const job = curationJob(root, original.id)
+        const jobReason = decision.reason.trim()
+        job.status = outcome.parked ? 'needs_user' : 'completed'
+        job.reason = jobReason
+        job.receipt = {
+          operationId: outcome.operation && !operationAssigned ? outcome.operation.id : null,
+          notes: [...outcome.notes, ...(outcome.operation ? [`Combined batch operation ${outcome.operation.id}.`] : ['The combined review produced no Wiki changes.'])],
+          parked: outcome.parked,
+          flagged: outcome.flagged
+        }
+        if (outcome.operation && !operationAssigned) operationAssigned = true
+        results.set(job.id, saveCuration(root, job))
+      }
+    }
+
+    for (const { decision, job } of entries) {
+      if (results.has(job.id) || ['completed', 'rejected', 'needs_user'].includes(job.status)) {
+        results.set(job.id, curationJob(this.options.env.root, job.id))
+        continue
+      }
+      if (decision.decision === 'apply') {
+        results.set(job.id, this.applyJob(context, job.id, undefined, decision.reason))
+      } else {
+        results.set(job.id, this.decide(context, job.id, decision.decision, decision.reason))
+      }
+    }
+    const receiptOperationId = [...results.values()].find((job) => job.receipt?.operationId)?.receipt?.operationId ?? null
+    return { operationId: receiptOperationId, jobs: decisions.map(({ id }) => results.get(id) ?? curationJob(this.options.env.root, id)) }
+  }
+
   claim(context: CallerContext, id: string, prepare = true): CurationJob {
     requireCurator(context)
     const root = this.options.env.root
@@ -448,6 +607,8 @@ export class Maintenance {
     const wiki = store.wikiDir(root)
     let prepared: ReturnType<Maintenance['prepare']>
     try { prepared = this.prepare(job) } catch (error) {
+      // A run that is not eligible is an expected outcome, not a problem to report.
+      if (error instanceof NotEligible) return
       const message = error instanceof Error ? error.message : String(error)
       if (job.kind === 'run') log(`maintenance skipped run ${job.runId}: ${message}`)
       else if (job.kind === 'ingest') { inbox(wiki, 'unresolved', 'Source was imported but not summarized', message, []); bus.emit({ type: 'wiki.changed' }) }

package/src/memory/recall.ts

@@ -3,6 +3,7 @@
 // and events stay canonical; the recall index is rebuilt from `runs/`.
 import type { DatabaseSync } from 'node:sqlite'
 
+import { logLine } from '../core/bus'
 import type { HarnessEnv } from '../core/env'
 import { invalid, notFound } from '../core/errors'
 import { all, run as execute, transaction, withIndex } from '../core/index'
@@ -67,7 +68,7 @@ export function indexRun(root: string, runId: string): void {
   try {
     withIndex(root, (database) => writeRun(database, run, found))
   } catch (error) {
-    process.stderr.write(`[recall] run ${runId} was not indexed: ${error instanceof Error ? error.message : String(error)}\n`)
+    logLine(`[recall] run ${runId} was not indexed: ${error instanceof Error ? error.message : String(error)}`)
   }
 }
 

package/src/memory/trajectory.test.ts

@@ -0,0 +1,178 @@
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, expect, test } from 'vitest'
+
+import { createEnv } from '../core/env'
+import { closeIndex } from '../core/index'
+import { writeJson } from '../core/fs'
+import { runRecordSchema, type RunEvent, type RunRecord } from '../sessions/contracts'
+import { appendEvent, saveRun } from '../sessions/runStore'
+import { WIKI_AGENT_TOOLS } from '../tools/definitions'
+import type { CallerContext } from './caller'
+import { dispatch } from './dispatch'
+import { readTool, searchTool } from './trajectory'
+
+const roots: string[] = []
+afterEach(() => roots.splice(0).forEach(closeIndex))
+
+function setup() {
+  const root = mkdtempSync(join(tmpdir(), 'harness-trajectory-'))
+  roots.push(root)
+  writeJson(join(root, 'projects.json'), [
+    { id: 'p1', name: 'App', slug: 'app', rootPath: '/tmp/app', autoMaintenance: true, createdAt: 't' },
+    { id: 'p2', name: 'Site', slug: 'site', rootPath: '/tmp/site', autoMaintenance: true, createdAt: 't' }
+  ])
+  const env = createEnv(root, {
+    directory: {
+      agentName: (id) => ({ 'agent-a': 'Nora', 'agent-b': 'Kai', 'agent-hidden': 'Hidden' })[id] ?? null,
+      sessionAgent: (id) => id === 'hidden-session' ? 'agent-hidden' : null
+    }
+  })
+  return { root, env }
+}
+
+function run(id: string, overrides: Partial<RunRecord> = {}): RunRecord {
+  return runRecordSchema.parse({
+    id,
+    projectId: null,
+    mode: 'chat',
+    harness: 'pi',
+    sessionType: 'structured',
+    sessionId: `session-${id}`,
+    goal: `Goal for ${id}`,
+    startedAt: '2026-10-18T10:00:00.000Z',
+    endedAt: null,
+    status: 'running',
+    agentId: 'agent-a',
+    ...overrides
+  })
+}
+
+function event(runId: string, sequence: number, type: RunEvent['type'], payload: unknown, native?: unknown): RunEvent {
+  return {
+    id: `${runId}-event-${sequence}`,
+    runId,
+    sessionId: `session-${runId}`,
+    sequence,
+    timestamp: `2026-10-18T10:00:${String(sequence).padStart(2, '0')}.000Z`,
+    type,
+    payload,
+    ...(native === undefined ? {} : { native })
+  } as RunEvent
+}
+
+function save(root: string, record: RunRecord, events: RunEvent[] = []): void {
+  saveRun(root, record)
+  for (const entry of events) appendEvent(root, entry)
+}
+
+const agent: CallerContext = { agentId: 'agent-a', actor: 'Chat' }
+
+test('trajectory search filters runs and paginates deterministically, including active runs', () => {
+  const { root, env } = setup()
+  save(root, run('z-run', { projectId: 'p2', agentId: 'agent-b' }))
+  save(root, run('b-run', { projectId: 'p2', agentId: 'agent-b' }))
+  save(root, run('a-run', { projectId: 'p1', agentId: 'agent-a', startedAt: '2026-10-17T10:00:00.000Z', status: 'completed', endedAt: '2026-10-17T10:01:00.000Z' }))
+
+  const first = JSON.parse(searchTool(env, agent, { project: 'site', agent: 'Kai', limit: 1 }))
+  expect(first.runs.map((item: { id: string }) => item.id)).toEqual(['z-run'])
+  expect(first.runs[0]).toMatchObject({ agentId: 'agent-b', agentName: 'Kai', project: { id: 'p2', name: 'Site', slug: 'site' }, status: 'running' })
+  expect(first.hasMore).toBe(true)
+
+  const second = JSON.parse(searchTool(env, agent, { project: 'p2', agent: 'agent-b', limit: 1, cursor: first.nextCursor }))
+  expect(second.runs.map((item: { id: string }) => item.id)).toEqual(['b-run'])
+  expect(second.hasMore).toBe(false)
+
+  const bounded = JSON.parse(searchTool(env, agent, { since: '2026-10-18', until: '2026-10-18', status: 'running' }))
+  expect(bounded.runs.map((item: { id: string }) => item.id)).toEqual(['z-run', 'b-run'])
+})
+
+test('trajectory search and read keep host-excluded agents hidden', () => {
+  const { root, env } = setup()
+  save(root, run('hidden-agent-run', { agentId: 'agent-hidden' }))
+  save(root, run('hidden-session-run', { agentId: null, sessionId: 'hidden-session' }))
+  save(root, run('visible-run'))
+  const caller = { ...agent, recallExcludeAgents: ['agent-hidden'] }
+
+  const results = JSON.parse(searchTool(env, caller, {}))
+  expect(results.runs.map((item: { id: string }) => item.id)).toEqual(['visible-run'])
+  expect(() => readTool(env, caller, { run: 'hidden-agent-run' })).toThrow()
+  expect(() => readTool(env, caller, { run: 'hidden-session-run' })).toThrow()
+})
+
+test('trajectory_read resolves current and returns bounded event pages without native data', () => {
+  const { root, env } = setup()
+  const longInput = 'x'.repeat(20_000)
+  save(root, run('active-run'), [
+    event('active-run', 0, 'context.snapshot', { systemPrompt: 'Be useful', tools: [] }, { privateNative: true }),
+    event('active-run', 1, 'tool.started', { toolCallId: 't1', name: 'read', input: longInput }),
+    event('active-run', 2, 'tool.completed', { toolCallId: 't1', name: 'read', output: 'file contents' })
+  ])
+  const caller = { ...agent, runId: 'active-run' }
+
+  const initial = JSON.parse(readTool(env, caller, { run: 'current', limit: 1 }))
+  expect(initial.events[0]).toMatchObject({ sequence: 0, type: 'context.snapshot', payload: { systemPrompt: 'Be useful', tools: [] } })
+  expect(JSON.stringify(initial)).not.toContain('privateNative')
+
+  const first = JSON.parse(readTool(env, caller, { run: 'current', afterSequence: 0, limit: 1 }))
+  expect(first).toMatchObject({ active: true, run: { id: 'active-run', status: 'running' }, hasMore: true, nextAfterSequence: 1 })
+  expect(first.events[0]).toMatchObject({ sequence: 1, type: 'tool.started', truncatedFields: ['payload.input'] })
+  expect(JSON.stringify(first)).not.toContain('privateNative')
+  expect(first.events[0].payload.input.length).toBeLessThan(longInput.length)
+
+  const second = JSON.parse(readTool(env, caller, { run: 'active-run', afterSequence: first.nextAfterSequence, limit: 1 }))
+  expect(second.events[0]).toMatchObject({ sequence: 2, type: 'tool.completed', payload: { output: 'file contents' } })
+  expect(second.hasMore).toBe(false)
+})
+
+test('trajectory_read follows execution events through the first outcome only', () => {
+  const { root, env } = setup()
+  save(root, run('settled-run', { status: 'completed', endedAt: '2026-10-18T10:01:00.000Z' }), [
+    event('settled-run', 0, 'started', {}),
+    event('settled-run', 1, 'completed', {}),
+    event('settled-run', 2, 'tool.started', { toolCallId: 'late', name: 'ignored' }, { hostIgnored: 'run_already_ended' })
+  ])
+
+  const result = JSON.parse(readTool(env, agent, { run: 'settled-run' }))
+  expect(result.active).toBe(false)
+  expect(result.events.map((item: { sequence: number }) => item.sequence)).toEqual([0, 1])
+  expect(JSON.stringify(result)).not.toContain('ignored')
+})
+
+test('trajectory_read keeps account identifiers and credential fields out of event payloads', () => {
+  const { root, env } = setup()
+  save(root, run('safe-run'), [
+    event('safe-run', 0, 'account.status', { accountId: 'private-account-id', category: 'quota', message: 'Limit reached for sk-abcdefghijklmnopqrstuvwxyz012345' }),
+    event('safe-run', 1, 'tool.started', { toolCallId: 't1', name: 'login', input: '{"username":"ada","password":"private-password"}' }),
+    event('safe-run', 2, 'usage.updated', { inputTokens: 10, request: { index: 1, reasoningSummary: 'private reasoning summary' } })
+  ])
+
+  const result = JSON.parse(readTool(env, agent, { run: 'safe-run' }))
+  expect(result.events[0].omittedFields).toContain('payload.accountId')
+  expect(JSON.stringify(result)).not.toContain('private-account-id')
+  expect(JSON.stringify(result)).not.toContain('sk-abcdefghijklmnopqrstuvwxyz012345')
+  expect(JSON.stringify(result)).not.toContain('private-password')
+  expect(result.events[1].payload.input).not.toContain('password')
+  expect(result.events[2].omittedFields).toContain('payload.request.reasoningSummary')
+  expect(JSON.stringify(result)).not.toContain('private reasoning summary')
+})
+
+test('trajectory calls reject malformed filters and missing current runs', () => {
+  const { env } = setup()
+  expect(() => searchTool(env, agent, { status: 'unknown' })).toThrow()
+  expect(() => searchTool(env, agent, { since: 'not-a-date' })).toThrow()
+  expect(() => searchTool(env, agent, { cursor: 'not-a-cursor' })).toThrow()
+  expect(() => readTool(env, agent, { run: 'current' })).toThrow()
+  expect(() => readTool(env, agent, { run: 'missing' })).toThrow()
+})
+
+test('the model tool registry exposes both trajectory calls through Wiki dispatch', () => {
+  const { root, env } = setup()
+  save(root, run('registered-run'))
+  const calls = WIKI_AGENT_TOOLS.map((tool) => tool.call)
+  expect(calls).toContain('trajectory.search')
+  expect(calls).toContain('trajectory.read')
+  expect(JSON.parse(dispatch(env, agent, 'trajectory.search', {})).runs[0].id).toBe('registered-run')
+  expect(JSON.parse(dispatch(env, agent, 'trajectory.read', { run: 'registered-run' })).run.id).toBe('registered-run')
+})

package/src/memory/trajectory.ts

@@ -0,0 +1,220 @@
+// Read-only views over the canonical run records and validated event logs.
+import type { HarnessEnv } from '../core/env'
+import { invalid, notFound } from '../core/errors'
+import { listProjects } from '../core/projects'
+import { compareText } from '../core/text'
+import { scrub } from '../accounts/store'
+import { scrubSensitive } from '../mcp/connections'
+import { isActiveStatus, runStatusSchema, type RunEvent, type RunRecord } from '../sessions/contracts'
+import { readAllRuns } from '../sessions/runIndex'
+import { findRun, snapshot } from '../sessions/runStore'
+import type { CallerContext } from './caller'
+
+const SEARCH_DEFAULT = 10
+const SEARCH_MAX = 30
+const READ_DEFAULT = 8
+const READ_MAX = 10
+const EVENT_MAX_CHARS = 18_000
+const PAGE_MAX_CHARS = 48_000
+
+export type Params = Record<string, unknown> | null | undefined
+
+function textParam(params: Params, key: string): string {
+  const value = params?.[key]
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+function boundedInteger(params: Params, key: string, fallback: number, minimum: number, maximum: number): number {
+  const value = params?.[key]
+  if (value === undefined) return fallback
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < minimum || value > maximum) {
+    throw invalid(`${key} must be an integer from ${minimum} to ${maximum}.`)
+  }
+  return value
+}
+
+function dateValue(params: Params, key: string): { text: string; timestamp: number } | null {
+  const value = textParam(params, key)
+  if (!value) return null
+  if (!/^\d{4}-\d{2}-\d{2}(?:T.*)?$/.test(value)) throw invalid(`${key} must be a YYYY-MM-DD date or ISO timestamp.`)
+  const timestamp = Date.parse(/^\d{4}-\d{2}-\d{2}$/.test(value) ? `${value}${key === 'until' ? 'T23:59:59.999Z' : 'T00:00:00.000Z'}` : value)
+  if (!Number.isFinite(timestamp)) throw invalid(`${key} must be a valid date or ISO timestamp.`)
+  return { text: value, timestamp }
+}
+
+interface Cursor {
+  startedAt: string
+  id: string
+}
+
+function decodeCursor(value: string): Cursor | null {
+  if (!value) return null
+  try {
+    const parsed = JSON.parse(Buffer.from(value, 'base64url').toString('utf8')) as Partial<Cursor>
+    if (typeof parsed.startedAt !== 'string' || !parsed.startedAt || typeof parsed.id !== 'string' || !parsed.id) throw new Error('invalid cursor')
+    return { startedAt: parsed.startedAt, id: parsed.id }
+  } catch {
+    throw invalid('The trajectory cursor is invalid. Start a new search without it.')
+  }
+}
+
+function encodeCursor(run: RunRecord): string {
+  return Buffer.from(JSON.stringify({ startedAt: run.startedAt, id: run.id })).toString('base64url')
+}
+
+function hidden(env: HarnessEnv, context: CallerContext, run: RunRecord): boolean {
+  const excluded = context.recallExcludeAgents ?? []
+  if (!excluded.length) return false
+  return excluded.includes(run.agentId ?? '') || excluded.includes(run.sessionId) || excluded.includes(env.directory.sessionAgent(run.sessionId) ?? '')
+}
+
+function afterCursor(run: RunRecord, cursor: Cursor): boolean {
+  return run.startedAt < cursor.startedAt || (run.startedAt === cursor.startedAt && run.id < cursor.id)
+}
+
+function summary(env: HarnessEnv, run: RunRecord, projects: ReturnType<typeof listProjects>) {
+  const project = projects.find((entry) => entry.id === run.projectId)
+  const goal = run.goal?.trim() ?? ''
+  return {
+    id: run.id,
+    agentId: run.agentId,
+    agentName: run.agentId ? env.directory.agentName(run.agentId) : null,
+    project: project ? { id: project.id, name: project.name, slug: project.slug } : null,
+    mode: run.mode,
+    status: run.status,
+    goal: goal.length > 500 ? `${goal.slice(0, 497)}…` : goal || null,
+    startedAt: run.startedAt,
+    endedAt: run.endedAt,
+    parentRunId: run.parentRunId,
+    relation: run.relation
+  }
+}
+
+/** `trajectory.search`: structured list/search over the current Harness data root. */
+export function searchTool(env: HarnessEnv, context: CallerContext, params: Params): string {
+  const agent = textParam(params, 'agent')
+  const projectKey = textParam(params, 'project')
+  const mode = textParam(params, 'mode')
+  const status = textParam(params, 'status')
+  const since = dateValue(params, 'since')
+  const until = dateValue(params, 'until')
+  const limit = boundedInteger(params, 'limit', SEARCH_DEFAULT, 1, SEARCH_MAX)
+  const cursor = decodeCursor(textParam(params, 'cursor'))
+
+  if (status && !runStatusSchema.safeParse(status).success) throw invalid(`Unknown run status ${status}.`)
+  const projects = listProjects(env.root)
+  const project = projectKey ? projects.find((entry) => entry.id === projectKey || entry.slug === projectKey || entry.name.toLowerCase() === projectKey.toLowerCase()) : null
+  if (projectKey && !project) throw invalid(`There is no project called ${projectKey}.`)
+
+  const matching = readAllRuns(env.root)
+    .filter((run) => !hidden(env, context, run))
+    .filter((run) => !agent || run.agentId === agent || (run.agentId !== null && env.directory.agentName(run.agentId)?.toLowerCase() === agent.toLowerCase()))
+    .filter((run) => !projectKey || run.projectId === project?.id)
+    .filter((run) => !mode || run.mode === mode)
+    .filter((run) => !status || run.status === status)
+    .filter((run) => !since || Date.parse(run.startedAt) >= since.timestamp)
+    .filter((run) => !until || Date.parse(run.startedAt) <= until.timestamp)
+    .filter((run) => !cursor || afterCursor(run, cursor))
+    .sort((left, right) => compareText(right.startedAt, left.startedAt) || compareText(right.id, left.id))
+
+  const page = matching.slice(0, limit)
+  const hasMore = matching.length > page.length
+  return JSON.stringify({
+    runs: page.map((run) => summary(env, run, projects)),
+    hasMore,
+    nextCursor: hasMore && page.length ? encodeCursor(page[page.length - 1]) : null
+  })
+}
+
+function boundedValue(value: unknown, path: string, truncated: string[], stringLimit: number, arrayLimit: number, depth = 0): unknown {
+  if (typeof value === 'string') {
+    const fieldLimit = path.endsWith('.systemPrompt') || path.endsWith('.contextUpdate') ? Math.min(12_000, stringLimit) :
+      path.endsWith('.input') || path.endsWith('.output') || path.endsWith('.summary') ? Math.min(10_000, stringLimit) : stringLimit
+    if (value.length <= fieldLimit) return value
+    truncated.push(path)
+    return `${value.slice(0, Math.max(0, fieldLimit - 16))}… [truncated]`
+  }
+  if (Array.isArray(value)) {
+    const kept = value.slice(0, arrayLimit).map((item, index) => boundedValue(item, `${path}[${index}]`, truncated, stringLimit, arrayLimit, depth + 1))
+    if (value.length > arrayLimit) truncated.push(path)
+    return kept
+  }
+  if (!value || typeof value !== 'object' || depth >= 8) return value
+  const entries = Object.entries(value as Record<string, unknown>)
+  const kept = entries.slice(0, 40).map(([key, item]) => [key, boundedValue(item, `${path}.${key}`, truncated, stringLimit, arrayLimit, depth + 1)])
+  if (entries.length > 40) truncated.push(path)
+  return Object.fromEntries(kept)
+}
+
+function publicEvent(event: RunEvent): Record<string, unknown> {
+  let stringLimit = 12_000
+  let arrayLimit = 20
+  while (true) {
+    const truncated: string[] = []
+    const omitted: string[] = []
+    let payload = scrubSensitive(event.payload)
+    if (event.type === 'account.status' && payload && typeof payload === 'object' && !Array.isArray(payload)) {
+      const account = payload as Record<string, unknown>
+      if (Object.hasOwn(account, 'accountId')) {
+        delete account.accountId
+        omitted.push('payload.accountId')
+      }
+      if (typeof account.message === 'string') account.message = scrub(account.message)
+    }
+    if (event.type === 'usage.updated' && payload && typeof payload === 'object' && !Array.isArray(payload)) {
+      const request = (payload as Record<string, unknown>).request
+      if (request && typeof request === 'object' && !Array.isArray(request) && Object.hasOwn(request, 'reasoningSummary')) {
+        delete (request as Record<string, unknown>).reasoningSummary
+        omitted.push('payload.request.reasoningSummary')
+      }
+    }
+    const value: Record<string, unknown> = {
+      id: event.id,
+      sequence: event.sequence,
+      timestamp: event.timestamp,
+      type: event.type,
+      payload: boundedValue(payload, 'payload', truncated, stringLimit, arrayLimit)
+    }
+    if (event.coalescedFrom !== undefined) value.coalescedFrom = event.coalescedFrom
+    if (truncated.length) value.truncatedFields = truncated.slice(0, 40)
+    if (omitted.length) value.omittedFields = omitted
+    if (JSON.stringify(value).length <= EVENT_MAX_CHARS || (stringLimit <= 500 && arrayLimit <= 1)) return value
+    stringLimit = Math.max(500, Math.floor(stringLimit / 2))
+    arrayLimit = Math.max(1, Math.floor(arrayLimit / 2))
+  }
+}
+
+/** `trajectory.read`: a bounded page of the events that affected a run. */
+export function readTool(env: HarnessEnv, context: CallerContext, params: Params): string {
+  const requested = textParam(params, 'run')
+  if (!requested) throw invalid('Give a run id or "current".')
+  const runId = requested === 'current' ? context.runId ?? '' : requested
+  if (!runId) throw invalid('This caller has no current run.')
+  const run = findRun(env.root, runId)
+  if (!run || hidden(env, context, run)) throw notFound('Run')
+
+  const afterSequence = boundedInteger(params, 'afterSequence', -1, -1, Number.MAX_SAFE_INTEGER)
+  const limit = boundedInteger(params, 'limit', READ_DEFAULT, 1, READ_MAX)
+  const captured = snapshot(env.root, run.id)
+  const candidates = captured.events.filter((event) => event.sequence > afterSequence)
+  const events: Record<string, unknown>[] = []
+  let eventChars = 0
+  for (const event of candidates.slice(0, limit)) {
+    const bounded = publicEvent(event)
+    const size = JSON.stringify(bounded).length
+    if (events.length && eventChars + size > PAGE_MAX_CHARS) break
+    events.push(bounded)
+    eventChars += size
+  }
+  const lastSequence = events.length ? Number(events[events.length - 1].sequence) : afterSequence
+  const hasMore = candidates.some((event) => event.sequence > lastSequence)
+  const projects = listProjects(env.root)
+  const result = {
+    run: summary(env, captured.run, projects),
+    active: isActiveStatus(captured.run.status),
+    events,
+    hasMore,
+    nextAfterSequence: lastSequence
+  }
+  return JSON.stringify(result)
+}