@xingular/harness 0.1.6 → 2.0.0

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)}`)
   }
 }
 
@@ -221,6 +222,13 @@ export function sourceLabel(env: HarnessEnv, mode: string, sessionId: string, pr
   }
 }
 
+/** Whether a conversation belongs to an agent the caller may not recall. */
+function excluded(env: HarnessEnv, context: CallerContext, sessionId: string): boolean {
+  const hidden = context.recallExcludeAgents ?? []
+  if (!hidden.length) return false
+  return hidden.includes(sessionId) || hidden.includes(env.directory.sessionAgent(sessionId) ?? '')
+}
+
 /** `recall.search` as text for a model. */
 export function searchTool(env: HarnessEnv, context: CallerContext, params: Params): string {
   const query = textParam(params, 'query')
@@ -229,7 +237,7 @@ export function searchTool(env: HarnessEnv, context: CallerContext, params: Para
   const requested = params?.limit
   const limit = typeof requested === 'number' && Number.isInteger(requested) && requested >= 0 ? requested : SEARCH_DEFAULT
   // The caller's current run is what it is in the middle of, not something to recall.
-  const hits = search(env.root, query, scope, limit + 4).filter((hit) => hit.runId !== context.runId).slice(0, Math.min(Math.max(limit, 1), SEARCH_MAX))
+  const hits = search(env.root, query, scope, limit + 4 + (context.recallExcludeAgents?.length ? SEARCH_MAX : 0)).filter((hit) => hit.runId !== context.runId && !excluded(env, context, hit.sessionId)).slice(0, Math.min(Math.max(limit, 1), SEARCH_MAX))
   if (!hits.length) {
     return scope.sessionId && !isSession(context) ? 'Nothing in your own conversations matches. Pass scope "all" to search every conversation and Harness run.' : 'Nothing in the recorded history matches.'
   }
@@ -242,7 +250,7 @@ export function readTool(env: HarnessEnv, context: CallerContext, params: Params
   const run = findRun(env.root, runId)
   if (!run) throw notFound('Run')
   // Reading is as wide as an "all" search for an agent, and as narrow as a search for a session.
-  if (!mayRead(callerScope(env.root, context, { scope: 'all' }), run)) throw notFound('Run')
+  if (!mayRead(callerScope(env.root, context, { scope: 'all' }), run) || excluded(env, context, run.sessionId)) throw notFound('Run')
   const messages = read(env.root, run.id)
   if (!messages.length) return 'That run has no recorded messages.'
   let text = `Run ${run.id} · ${run.startedAt.slice(0, 16)} · ${sourceLabel(env, run.mode, run.sessionId, run.projectId)} · ${run.status}\n`

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)
+}

package/src/memory/wiki.ts

@@ -6,6 +6,7 @@ import { readdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { noteChange } from '../core/changes'
+import { logLine } from '../core/bus'
 import { HarnessError, notFound } from '../core/errors'
 import * as frontmatter from '../core/frontmatter'
 import { atomicWrite, now } from '../core/fs'
@@ -216,7 +217,7 @@ export function searchEntries(root: string, query: string, options: SearchOption
   try {
     ranked = wikiIndex.search(root, query, limit * 4, boost)
   } catch (error) {
-    process.stderr.write(`[index] search fell back to files: ${error instanceof Error ? error.message : String(error)}\n`)
+    logLine(`[index] search fell back to files: ${error instanceof Error ? error.message : String(error)}`)
     const needle = query.trim().toLowerCase()
     if (!needle) return []
     const rank = (entry: IndexedEntry): number => (entry.namespace === boost ? 0 : 2) + (entry.title.toLowerCase().includes(needle) ? 0 : 1)

package/src/memory/wikiIndex.ts

@@ -3,6 +3,7 @@
 import { existsSync } from 'node:fs'
 import type { DatabaseSync } from 'node:sqlite'
 
+import { logLine } from '../core/bus'
 import { all, dbPath, deleteIndex, ftsQuery, run, transaction, withIndex } from '../core/index'
 import { readAllRuns, syncRuns, upsertRun } from '../sessions/runIndex'
 import { scan } from './wiki'
@@ -55,7 +56,7 @@ export function reindexQuietly(root: string): void {
   try {
     reindexWiki(root)
   } catch (error) {
-    process.stderr.write(`[index] reindex failed: ${error instanceof Error ? error.message : String(error)}\n`)
+    logLine(`[index] reindex failed: ${error instanceof Error ? error.message : String(error)}`)
   }
 }
 
@@ -81,7 +82,7 @@ export function ensure(root: string, after?: () => void): number {
     try {
       syncRuns(root)
     } catch (error) {
-      process.stderr.write(`[index] ${error instanceof Error ? error.message : String(error)}\n`)
+      logLine(`[index] ${error instanceof Error ? error.message : String(error)}`)
     }
   } else {
     pages = rebuild(root)

package/src/plugins/builtin.ts

@@ -2,8 +2,9 @@
 // exists; none of it is loaded through Pi's extension system.
 import { CONNECTION_TOOLS, NATIVE_GROUP } from '../prompt/compile'
 import { ASK_USER } from '../tools/askUser'
+import { SPAWN_SUBAGENT, WAIT_SUBAGENTS } from '../sessions/subagents'
 import { PLUGIN_PROPOSE } from '../tools/pluginPropose'
-import { MEMORY_TOOLS, RECALL_TOOLS, WIKI_TOOLS, type WikiToolDefinition } from '../tools/definitions'
+import { MEMORY_TOOLS, RECALL_TOOLS, TRAJECTORY_TOOLS, WIKI_TOOLS, type WikiToolDefinition } from '../tools/definitions'
 import { FIRST_PARTY_PLUGINS } from './firstParty'
 import type { PluginDescriptor } from './types'
 
@@ -36,6 +37,7 @@ export const INCLUDED_PLUGIN: PluginDescriptor = { id: 'included', title: 'Inclu
 
 export const HARNESS_PLUGINS: readonly PluginDescriptor[] = [
   PI_PLUGIN,
+  { id: 'subagents', title: 'Subagents', description: 'Isolated child runs of the same caller, bounded by parent capabilities and nesting depth.', required: 'Availability is selected by the session host; child runs retain the parent permission boundary.', tools: [{ name: SPAWN_SUBAGENT, description: 'Start a subagent' }, { name: WAIT_SUBAGENTS, description: 'Wait for subagents' }] },
   {
     id: 'memory',
     title: 'Memory',
@@ -59,7 +61,7 @@ export const HARNESS_PLUGINS: readonly PluginDescriptor[] = [
     ],
     toolGroups: ['Knowledge']
   },
-  { id: 'history', title: 'History', description: 'Search over earlier conversations and runs.', required: 'Earlier runs are how an agent picks up where work stopped.', tools: tools(RECALL_TOOLS) },
+  { id: 'history', title: 'History', description: 'Search earlier conversations and inspect recorded run trajectories.', required: 'Earlier runs are how an agent picks up where work stopped.', tools: tools([...RECALL_TOOLS, ...TRAJECTORY_TOOLS]) },
   {
     id: 'plugin-proposals',
     title: 'Plugin proposals',

package/src/plugins/catalogue.test.ts

@@ -73,7 +73,7 @@ describe('the plugin list', () => {
       ['app-tasks', 'application', ['tool:start_task:on']],
       ['web', 'application', ['tool:web_search:on', 'tool:web_fetch:on']]
     ])
-    expect(plugins.filter((plugin) => plugin.source === 'builtin').map((plugin) => plugin.id)).toEqual(['ask-user', 'budget-guard', 'connected-apps', 'history', 'memory', 'output-trim', 'plugin-proposals', 'wiki'])
+    expect(plugins.filter((plugin) => plugin.source === 'builtin').map((plugin) => plugin.id)).toEqual(['ask-user', 'budget-guard', 'connected-apps', 'history', 'memory', 'output-trim', 'plugin-proposals', 'subagents', 'wiki'])
 
     const kit = plugins.find((plugin) => plugin.id === 'package:review-kit')!
     // It was there when trust was first asked per package, so it was taken over as trusted.

package/src/server/methods.ts

@@ -14,7 +14,7 @@ import { capabilitySet } from '../capabilities/runSnapshot'
 import type { Harness } from '../harness'
 import * as blocks from '../memory/blocks'
 import { validateScopeIds } from '../mcp/connections'
-import type { CallerContext } from '../memory/caller'
+import { callerBlocks, type CallerContext } from '../memory/caller'
 import { dispatch } from '../memory/dispatch'
 import * as facts from '../memory/facts'
 import * as graph from '../memory/graph'
@@ -33,6 +33,7 @@ import { comparison, compile, CONTEXT_PROFILES, load, profiles, render, setProfi
 import { selectHistory } from '../sessions/history'
 import { runsSince } from '../sessions/runIndex'
 import { findRun, listRuns, loadRun, pendingDecisions, readEvents, runFamily, snapshot } from '../sessions/runStore'
+import type { SubagentInput, SubagentSelection } from '../sessions/subagents'
 import type { SessionRunInput } from '../sessions/sessions'
 import * as registry from '../skills/registry'
 import type { TerminalPrepareInput } from '../terminal/terminals'
@@ -46,6 +47,16 @@ const text = (params: Params, name: string): string => {
   return value
 }
 const optional = (params: Params, name: string): string | null => (typeof params[name] === 'string' && params[name] ? (params[name] as string) : null)
+const questionAnswer = (value: unknown): { selected: string[]; text?: string; notes?: Record<string, string> } => {
+  const answer = value && typeof value === 'object' && !Array.isArray(value) ? value as Params : {}
+  return {
+    selected: Array.isArray(answer.selected) ? answer.selected.filter((label: unknown): label is string => typeof label === 'string') : [],
+    ...(typeof answer.text === 'string' && answer.text ? { text: answer.text } : {}),
+    ...(answer.notes && typeof answer.notes === 'object' && !Array.isArray(answer.notes)
+      ? { notes: Object.fromEntries(Object.entries(answer.notes).filter((entry): entry is [string, string] => typeof entry[1] === 'string')) }
+      : {})
+  }
+}
 const pluginScope = (params: Params): plugins.PluginScope => ({ cwd: optional(params, 'cwd'), accountId: optional(params, 'accountId'), agentId: optional(params, 'agentId'), projectId: optional(params, 'projectId') })
 
 /** Sources larger than this are not imported. */
@@ -65,6 +76,14 @@ export function methods(harness: Harness): Record<string, Handler> {
     'harness.status': () => ({ dataRoot: harness.dataRoot, productName: env.productName, recovery: harness.recovery, activeRuns: runs.activeRunIds() }),
     'harness.open': (params: Params) => harness.open(text(params, 'dataRoot'), Array.isArray(params.agentIds) ? params.agentIds : []),
     'harness.rebuildIndex': () => harness.rebuildIndex(),
+    'maintenance.list': (params: Params) => maintenance.jobs().filter((job) => params.runId ? job.runId === params.runId || (Array.isArray(params.ids) && params.ids.includes(job.id)) : params.includeCompleted === true || !['completed', 'rejected'].includes(job.status)).map(({ prepared: _prepared, hashes: _hashes, ...job }) => job),
+    'maintenance.review': (params: Params) => { maintenance.enqueue({ kind: 'review', requestId: optional(params, 'requestId') ?? String(Date.now()), manual: params.manual === true }); return { queued: true } },
+    'maintenance.failRun': (params: Params) => { maintenance.finishRun(text(params, 'runId'), true); return null },
+    'maintenance.retry': (params: Params) => maintenance.retry(text(params, 'id')),
+    'hub.list': (params: Params) => harness.hub.list(params.refresh === true),
+    'hub.get': (params: Params) => harness.hub.get(text(params, 'id'), text(params, 'version'), params.preview === true),
+    'hub.install': (params: Params) => harness.hub.install(text(params, 'id'), text(params, 'version')),
+    'hub.readDocument': (params: Params) => harness.hub.readDocument(text(params, 'id'), text(params, 'version')),
 
     // ---- Accounts --------------------------------------------------------------------------------
     'accounts.list': () => accounts.overview(),
@@ -84,6 +103,7 @@ export function methods(harness: Harness): Record<string, Handler> {
     'accounts.sharedDir': () => ensureSharedDir(accounts.dir),
     'accounts.refresh': (params: Params) => accounts.refresh(optional(params, 'accountId')),
     'accounts.loginStart': (params: Params) => accounts.loginStart(text(params, 'accountId'), text(params, 'provider'), optional(params, 'method')),
+    'accounts.loginStatus': (params: Params) => accounts.loginStatus(text(params, 'accountId')),
     'accounts.loginRespond': (params: Params) => accounts.loginRespond(text(params, 'loginId'), text(params, 'promptId'), typeof params.value === 'string' ? params.value : null),
     'accounts.loginCancel': (params: Params) => accounts.loginCancel(text(params, 'accountId'), optional(params, 'loginId')),
     'accounts.setApiKey': (params: Params) => accounts.setApiKey(text(params, 'accountId'), text(params, 'key'), text(params, 'provider')),
@@ -115,6 +135,7 @@ export function methods(harness: Harness): Record<string, Handler> {
     'connections.setAgentScope': (params: Params) => apps.setAgentScope(params.creator ?? {}, text(params, 'agentId'), Array.isArray(params.ids) ? params.ids : []),
     'connections.removeAgentScope': (params: Params) => apps.removeAgentScope(text(params, 'agentId')),
     'connections.revision': () => apps.connections.revision(),
+    'connections.appClients': () => apps.appClients(),
     'connections.validateScope': (params: Params) => validateScopeIds(apps.connections.list(), { agentId: optional(params, 'agentId'), projectId: optional(params, 'projectId') }, Array.isArray(params.ids) ? params.ids : []),
 
     // ---- Wiki: what a person browses and edits ---------------------------------------------------
@@ -196,6 +217,11 @@ export function methods(harness: Harness): Record<string, Handler> {
     },
 
     // ---- What a session calls, on behalf of a caller the host names -------------------------------
+    'memory.permissions': (params: Params) => {
+      const context = (params.context ?? {}) as CallerContext
+      const { caller, attached } = callerBlocks(env, context)
+      return attached.map((block) => ({ id: block.id, writable: blocks.editRefusal(caller, block) === null, reason: blocks.editRefusal(caller, block) }))
+    },
     'memory.call': (params: Params) => dispatch(env, (params.context ?? {}) as CallerContext, text(params, 'call'), params.params ?? {}),
 
     // ---- Recall ------------------------------------------------------------------------------------
@@ -278,6 +304,13 @@ export function methods(harness: Harness): Record<string, Handler> {
       await runs.interrupt(runId)
       return loadRun(root(), runId)
     },
+    // A message the person sends into a live reply. It reaches the model after the current step;
+    // `message.steered` marks the moment, and a message the run never takes is reported by its end.
+    'runs.steer': async (params: Params) => {
+      const runId = text(params, 'runId')
+      await runs.steer(runId, text(params, 'text'))
+      return { runId }
+    },
     // What the application reports into a live run, and an approval it asks a person for.
     'runs.emit': (params: Params) => {
       const run = runs.active(text(params, 'runId'))
@@ -298,9 +331,17 @@ export function methods(harness: Harness): Record<string, Handler> {
       return { decision }
     },
     'runs.resolveApproval': (params: Params) => runs.resolveApproval(text(params, 'runId'), text(params, 'approvalId'), params.decision),
-    'runs.answerQuestion': (params: Params) => runs.answerQuestion(text(params, 'runId'), text(params, 'questionId'), { selected: Array.isArray(params.answer?.selected) ? params.answer.selected : [], ...(typeof params.answer?.text === 'string' && params.answer.text ? { text: params.answer.text } : {}) }),
+    'runs.answerQuestion': (params: Params) => runs.answerQuestion(text(params, 'runId'), text(params, 'questionId'), questionAnswer(params.answer)),
+    'runs.answerQuestions': (params: Params) => {
+      if (!Array.isArray(params.answers)) throw invalid('answers must be an array.')
+      runs.answerQuestions(text(params, 'runId'), text(params, 'batchId'), params.answers.map((item: Params) => ({ questionId: text(item, 'questionId'), answer: questionAnswer(item.answer) })))
+    },
 
     // ---- Sessions ----------------------------------------------------------------------------------
+    'subagents.spawn': (params: Params) => harness.subagents.spawn(params as SubagentInput),
+    'subagents.wait': (params: Params) => harness.subagents.wait(params as SubagentSelection),
+    'subagents.results': (params: Params) => harness.subagents.results(params as SubagentSelection),
+    'sessions.spawnSubagent': (params: Params) => sessions.spawnSubagent(params as SubagentInput),
     'sessions.run': (params: Params) => sessions.run(params as SessionRunInput),
     'sessions.history': (params: Params) => ({ sessionFile: selectHistory({ sessionDir: text(params, 'sessionDir'), resume: params.resume ?? null }) }),