@xingular/harness 0.0.0-stage → 0.1.0

package/src/memory/recall.test.ts

@@ -0,0 +1,104 @@
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, expect, test } from 'vitest'
+
+import { writeFile } from '../../tests/helpers'
+import { createEnv, type HarnessEnv } from '../core/env'
+import { newId, writeJson } from '../core/fs'
+import { closeIndex } from '../core/index'
+import { runRecordSchema, type RunRecord } from '../sessions/contracts'
+import { parseEvent } from '../sessions/runStore'
+import type { CallerContext } from './caller'
+import { passages, read, readTool, search, searchTool, sync } from './recall'
+
+const run = (id: string, mode: string, session: string, project: string | null, goal: string): RunRecord =>
+  runRecordSchema.parse({ id, projectId: project, mode, harness: 'pi', sessionType: 'structured', sessionId: session, nativeSessionId: null, workingDirectory: null, worktreeId: null, goal, startedAt: '2026-10-01T10:00:00.000Z', endedAt: '2026-10-01T10:01:00.000Z', status: 'completed' })
+
+const event = (runId: string, type: string, payload: unknown) => ({ id: newId(), runId, sessionId: 's', sequence: 1, timestamp: '2026-10-01T10:00:30.000Z', type, payload })
+
+function save(root: string, record: RunRecord, events: unknown[]): void {
+  writeJson(join(root, 'runs', record.id, 'run.json'), record)
+  writeFile(join(root, 'runs', record.id, 'events.jsonl'), `${events.map((entry) => JSON.stringify(entry)).join('\n')}\n`)
+}
+
+const roots: string[] = []
+afterEach(() => roots.splice(0).forEach(closeIndex))
+
+function setup(): HarnessEnv {
+  const root = mkdtempSync(join(tmpdir(), 'harness-recall-'))
+  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' }
+  ])
+  save(root, run('chat-1', 'chat', 'agent-a', null, 'Which package manager do we use?'), [
+    event('chat-1', 'tool.started', { toolCallId: 't1', name: 'read', summary: 'package.json' }),
+    event('chat-1', 'message.completed', { messageId: 'm1', role: 'assistant', text: 'We use pnpm for every workspace.' })
+  ])
+  save(root, run('chat-2', 'chat', 'agent-b', null, 'Plan the launch'), [event('chat-2', 'message.completed', { messageId: 'm1', role: 'assistant', text: 'The launch is on Friday; pnpm build first.' })])
+  save(root, run('code-1', 'code', 'pane-1', 'p1', 'Fix the pnpm lockfile'), [event('code-1', 'message.completed', { messageId: 'm1', role: 'assistant', text: 'Regenerated the lockfile.' })])
+  save(root, run('code-2', 'code', 'pane-2', 'p2', 'Deploy the site with pnpm'), [])
+  return createEnv(root, { directory: { agentName: (id) => (id === 'agent-a' ? 'Nora' : id === 'agent-b' ? 'Kai' : null), sessionAgent: () => null } })
+}
+
+const agent = (id: string): CallerContext => ({ agentId: id, actor: 'Chat' })
+
+test('a run becomes its request, messages and tool summaries', () => {
+  const record = run('r', 'chat', 'a', null, '[App coordination event e1 / review — not a user message]')
+  const events = [event('r', 'tool.started', { toolCallId: 't1', name: 'grep', summary: 'TODO' }), event('r', 'message.completed', { messageId: 'm1', role: 'assistant', text: ' Done. ' }), event('r', 'message.delta', { messageId: 'm1', text: 'x' })].flatMap((entry) => parseEvent(entry) ?? [])
+  const found = passages(record, events)
+  expect(found.map((passage) => passage.role)).toEqual(['event', 'tool', 'assistant'])
+  expect(found[1].text).toBe('grep: TODO')
+  expect(found[2].text).toBe('Done.')
+})
+
+test('sync indexes missing runs once and reindexes changed ones', () => {
+  const { root } = setup()
+  expect(sync(root)).toBe(4)
+  expect(sync(root)).toBe(0)
+  save(root, { ...run('code-2', 'code', 'pane-2', 'p2', 'Deploy the site with pnpm'), status: 'failed' }, [event('code-2', 'message.completed', { messageId: 'm1', role: 'assistant', text: 'Wrangler failed pnpm.' })])
+  expect(sync(root)).toBe(1)
+  expect(read(root, 'code-2')).toHaveLength(2)
+  expect(search(root, 'pnpm', {}, 30)).toHaveLength(5)
+})
+
+test('an agent recalls its own chats by default and everything on request', () => {
+  const env = setup()
+  sync(env.root)
+  const mine = searchTool(env, agent('agent-a'), { query: 'pnpm package manager' })
+  expect(mine).toContain('run chat-1')
+  expect(mine).toContain('chat with Nora')
+  expect(mine).not.toContain('chat-2')
+  expect(mine).not.toContain('code-1')
+  const all = searchTool(env, agent('agent-a'), { query: 'pnpm', scope: 'all' })
+  expect(all).toContain('chat-2')
+  expect(all).toContain('code-1')
+  expect(all).toContain('Harness session in App')
+  const project = searchTool(env, agent('agent-a'), { query: 'pnpm', project: 'site' })
+  expect(project).toContain('code-2')
+  expect(project).not.toContain('code-1')
+  expect(searchTool(env, agent('agent-a'), { query: 'zebra' })).toContain('scope "all"')
+  expect(searchTool(env, agent('agent-a'), { query: 'pnpm', since: '2027-01-01' })).toContain('Nothing')
+  const transcript = readTool(env, agent('agent-a'), { run: 'chat-2' })
+  expect(transcript).toContain('user: Plan the launch')
+  expect(transcript).toContain('assistant: The launch is on Friday')
+  // The run a caller is in is not offered back to it.
+  expect(searchTool(env, { ...agent('agent-a'), runId: 'chat-1' }, { query: 'pnpm' })).not.toContain('run chat-1')
+})
+
+test('a session recalls only session runs of its project', () => {
+  const env = setup()
+  sync(env.root)
+  const session: CallerContext = { sessionId: 'pane-9', projectId: 'p1', actor: 'Code' }
+  const hits = searchTool(env, session, { query: 'pnpm', scope: 'all' })
+  expect(hits).toContain('code-1')
+  for (const other of ['chat-1', 'chat-2', 'code-2']) expect(hits).not.toContain(other)
+  expect(readTool(env, session, { run: 'code-1' })).toContain('Run code-1')
+  expect(() => readTool(env, session, { run: 'chat-1' })).toThrow()
+  expect(() => readTool(env, session, { run: 'code-2' })).toThrow()
+  // Without a project, a session sees only its own runs.
+  const loose: CallerContext = { sessionId: 'pane-1', actor: 'Code' }
+  expect(searchTool(env, loose, { query: 'pnpm' })).toContain('code-1')
+  expect(() => readTool(env, loose, { run: 'code-2' })).toThrow()
+})

package/src/memory/recall.ts

@@ -0,0 +1,271 @@
+// Recall: the searchable record of what happened in conversations and runs. Each run's request,
+// assistant messages, and tool summaries are indexed as passages in `index.sqlite`. Run records
+// and events stay canonical; the recall index is rebuilt from `runs/`.
+import type { DatabaseSync } from 'node:sqlite'
+
+import type { HarnessEnv } from '../core/env'
+import { invalid, notFound } from '../core/errors'
+import { all, run as execute, transaction, withIndex } from '../core/index'
+import { findProject, listProjects } from '../core/projects'
+import { charCount, takeChars } from '../core/text'
+import type { RunEvent, RunRecord } from '../sessions/contracts'
+import { readAllRuns } from '../sessions/runIndex'
+import { findRun, readEvents } from '../sessions/runStore'
+import { isSession, projectOf, type CallerContext } from './caller'
+
+const PASSAGE_LIMIT = 6000
+const READ_LIMIT = 12_000
+const SEARCH_DEFAULT = 8
+const SEARCH_MAX = 30
+
+export interface Passage {
+  /** `user`, `event` (a turn the application started, not the user), `assistant`, or `tool`. */
+  role: 'user' | 'event' | 'assistant' | 'tool'
+  at: string
+  text: string
+}
+
+/** A run as recall sees it: what was asked, what the assistant said, and which tools it used. */
+export function passages(run: RunRecord, events: readonly RunEvent[]): Passage[] {
+  const found: Passage[] = []
+  const goal = run.goal?.trim()
+  if (goal) found.push({ role: goal.startsWith('[App coordination event') ? 'event' : 'user', at: run.startedAt, text: takeChars(goal, PASSAGE_LIMIT) })
+  for (const event of events) {
+    const payload = event.payload as { role?: unknown; text?: unknown; name?: unknown; summary?: unknown }
+    if (event.type === 'message.completed' && payload.role === 'assistant') {
+      const text = typeof payload.text === 'string' ? payload.text.trim() : ''
+      if (text) found.push({ role: 'assistant', at: event.timestamp, text: takeChars(text, PASSAGE_LIMIT) })
+    } else if (event.type === 'tool.started') {
+      const summary = typeof payload.summary === 'string' ? payload.summary.trim() : ''
+      if (summary) found.push({ role: 'tool', at: event.timestamp, text: takeChars(`${typeof payload.name === 'string' ? payload.name : 'tool'}: ${summary}`, PASSAGE_LIMIT) })
+    }
+  }
+  return found
+}
+
+function writeRun(database: DatabaseSync, run: RunRecord, found: readonly Passage[]): void {
+  execute(database, 'DELETE FROM recall_fts WHERE run_id = ?1', run.id)
+  found.forEach((passage, seq) => {
+    execute(database, 'INSERT INTO recall_fts (run_id, seq, role, at, mode, session_id, project_id, text) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)', run.id, seq, passage.role, passage.at, run.mode, run.sessionId, run.projectId, passage.text)
+  })
+  execute(database, 'INSERT OR REPLACE INTO recall_runs (run_id, passages, status) VALUES (?1, ?2, ?3)', run.id, found.length, run.status)
+}
+
+function eventsOf(root: string, runId: string): RunEvent[] {
+  try {
+    return readEvents(root, runId)
+  } catch {
+    return []
+  }
+}
+
+/** Indexes one run from its record and events. Index failures never block a run. */
+export function indexRun(root: string, runId: string): void {
+  const run = findRun(root, runId)
+  if (!run) return
+  const found = passages(run, eventsOf(root, runId))
+  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`)
+  }
+}
+
+/**
+ * Indexes every run that is missing or whose status changed since it was indexed. Returns how
+ * many were (re)indexed. Called at startup, so earlier conversations are searchable.
+ */
+export function sync(root: string): number {
+  const known = new Map<string, string>()
+  withIndex(root, (database) => {
+    for (const row of all<{ run_id: string; status: string }>(database, 'SELECT run_id, status FROM recall_runs')) known.set(row.run_id, row.status)
+  })
+  const pending = readAllRuns(root)
+    .filter((run) => known.get(run.id) !== run.status)
+    .map((run) => ({ run, found: passages(run, eventsOf(root, run.id)) }))
+  if (pending.length) withIndex(root, (database) => transaction(database, () => pending.forEach(({ run, found }) => writeRun(database, run, found))))
+  return pending.length
+}
+
+// ---- Search ---------------------------------------------------------------------------------
+
+/**
+ * What a caller may recall. An agent searches its own conversations by default and everything
+ * when it asks; a session only sees session runs in its own project (or its own session when
+ * it has none), never an agent's conversation.
+ */
+export interface Scope {
+  /** Only runs of this session. */
+  sessionId?: string | null
+  /** Only runs of this mode (`code` for sessions). */
+  mode?: string | null
+  projectId?: string | null
+  /** ISO date or timestamp; only passages at or after it. */
+  since?: string | null
+}
+
+export interface RecallHit {
+  runId: string
+  seq: number
+  role: string
+  at: string
+  mode: string
+  sessionId: string
+  projectId: string | null
+  snippet: string
+}
+
+/** Any word may match; passages that match more of them, and rarer ones, rank first. */
+function ftsAny(query: string): string | null {
+  const terms: string[] = []
+  for (const word of query.split(/[^\p{Alphabetic}\p{N}]+/u)) {
+    if (charCount(word) <= 1) continue
+    const term = `"${word.toLowerCase()}"*`
+    if (!terms.includes(term) && terms.length < 24) terms.push(term)
+  }
+  return terms.length ? terms.join(' OR ') : null
+}
+
+interface HitRow {
+  run_id: string
+  seq: number | string
+  role: string
+  at: string | null
+  mode: string | null
+  session_id: string | null
+  project_id: string | null
+  snippet: string
+}
+
+export function search(root: string, query: string, scope: Scope, limit: number): RecallHit[] {
+  const fts = ftsAny(query)
+  if (!fts) return []
+  return withIndex(root, (database) =>
+    all<HitRow>(
+      database,
+      `SELECT run_id, seq, role, at, mode, session_id, project_id, snippet(recall_fts, 7, '', '', '…', 40) AS snippet
+       FROM recall_fts WHERE recall_fts MATCH ?1
+         AND (?2 IS NULL OR session_id = ?2) AND (?3 IS NULL OR mode = ?3)
+         AND (?4 IS NULL OR project_id = ?4) AND (?5 IS NULL OR at >= ?5)
+       ORDER BY bm25(recall_fts), at DESC LIMIT ?6`,
+      fts,
+      scope.sessionId ?? null,
+      scope.mode ?? null,
+      scope.projectId ?? null,
+      scope.since ?? null,
+      Math.min(Math.max(limit, 1), SEARCH_MAX)
+    ).map((row) => ({ runId: row.run_id, seq: Number(row.seq), role: row.role, at: row.at ?? '', mode: row.mode ?? '', sessionId: row.session_id ?? '', projectId: row.project_id, snippet: row.snippet }))
+  )
+}
+
+export interface RecallMessage {
+  seq: number
+  role: string
+  at: string
+  text: string
+}
+
+export function read(root: string, runId: string): RecallMessage[] {
+  return withIndex(root, (database) =>
+    all<{ seq: number | string; role: string; at: string | null; text: string }>(database, 'SELECT seq, role, at, text FROM recall_fts WHERE run_id = ?1 ORDER BY CAST(seq AS INTEGER)', runId).map((row) => ({ seq: Number(row.seq), role: row.role, at: row.at ?? '', text: row.text }))
+  )
+}
+
+// ---- Tools ----------------------------------------------------------------------------------
+
+type Params = Record<string, unknown> | null | undefined
+
+function textParam(params: Params, key: string): string {
+  const value = params?.[key]
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+/** The widest scope a caller may use, narrowed by what it asked for. */
+function callerScope(root: string, context: CallerContext, params: Params): Scope {
+  const since = textParam(params, 'since') || null
+  if (isSession(context)) {
+    // A session never reads an agent's conversations: only session runs of its project, or its own.
+    const projectId = projectOf(root, context)?.id ?? null
+    if (!projectId && !context.sessionId) throw invalid('Recall needs a session.')
+    return { sessionId: projectId ? null : context.sessionId, mode: 'code', projectId, since }
+  }
+  if (!context.agentId) throw invalid('Recall needs an agent or a Harness session.')
+  const key = textParam(params, 'project')
+  let projectId: string | null = null
+  if (key) {
+    const project = listProjects(root).find((entry) => entry.id === key || entry.slug === key || entry.name.toLowerCase() === key.toLowerCase())
+    if (!project) throw invalid(`There is no project called ${key}.`)
+    projectId = project.id
+  }
+  const everything = textParam(params, 'scope') === 'all' || projectId !== null
+  return { sessionId: everything ? null : context.agentId, mode: null, projectId, since }
+}
+
+function mayRead(scope: Scope, run: RunRecord): boolean {
+  if (!scope.mode) return true
+  return scope.mode === run.mode && (!scope.projectId || scope.projectId === run.projectId) && (!scope.sessionId || scope.sessionId === run.sessionId)
+}
+
+/** Who a run belonged to, for a person or a model reading a hit. */
+export function sourceLabel(env: HarnessEnv, mode: string, sessionId: string, projectId: string | null): string {
+  if (mode === 'chat') {
+    // One of an agent's extra conversations has its own id.
+    const owner = env.directory.sessionAgent(sessionId)
+    const name = env.directory.agentName(sessionId) ?? (owner ? env.directory.agentName(owner) : null)
+    return name ? `chat with ${name}` : 'group or earlier chat'
+  }
+  try {
+    return projectId ? `Harness session in ${findProject(env.root, projectId).name}` : 'Harness session'
+  } catch {
+    return 'Harness session'
+  }
+}
+
+/** `recall.search` as text for a model. */
+export function searchTool(env: HarnessEnv, context: CallerContext, params: Params): string {
+  const query = textParam(params, 'query')
+  if (!query) throw invalid('Give a query.')
+  const scope = callerScope(env.root, context, params)
+  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))
+  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.'
+  }
+  return `${hits.map((hit) => `- [run ${hit.runId} · ${hit.at.slice(0, 10)} · ${sourceLabel(env, hit.mode, hit.sessionId, hit.projectId)}] ${hit.role}: ${hit.snippet.replaceAll('\n', ' ')}`).join('\n')}\n\nRead a whole run with history_read and its run id.`
+}
+
+/** `recall.read` as text for a model. */
+export function readTool(env: HarnessEnv, context: CallerContext, params: Params): string {
+  const runId = textParam(params, 'run') || textParam(params, 'runId')
+  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')
+  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`
+  for (const message of messages) {
+    const line = `\n${message.role}: ${message.text}\n`
+    if (charCount(text) + charCount(line) > READ_LIMIT) {
+      text += '\n(The rest of the run was left out.)\n'
+      break
+    }
+    text += line
+  }
+  return text
+}
+
+export interface RecallFilter {
+  sessionId?: string | null
+  projectId?: string | null
+  since?: string | null
+}
+
+export type RecallResult = RecallHit & { source: string }
+
+/** A person's search: every conversation and run, narrowed only by the filter. */
+export function searchAll(env: HarnessEnv, query: string, filter: RecallFilter = {}): RecallResult[] {
+  return search(env.root, query, { sessionId: filter.sessionId, mode: null, projectId: filter.projectId, since: filter.since || null }, SEARCH_MAX).map((hit) => ({ ...hit, source: sourceLabel(env, hit.mode, hit.sessionId, hit.projectId) }))
+}

package/src/memory/references.ts

@@ -0,0 +1,77 @@
+// Selected references: Wiki pages and skills a person attached to one request. Each is pinned to
+// a revision when it is selected, so what the model reads cannot change under it, and the rest
+// of a long reference can be retrieved only at that revision.
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { invalid, notFound } from '../core/errors'
+import * as frontmatter from '../core/frontmatter'
+import { readJson, safeId } from '../core/fs'
+import { charCount } from '../core/text'
+import type { Source } from './runContext'
+import * as store from './store'
+import { entryFile, entryId, resolveEntry } from './wiki'
+
+export interface PinnedReference {
+  kind: 'page' | 'skill'
+  id: string
+  label: string
+  revision: string
+}
+
+/**
+ * Pins the entry's current content. The latest revision is reused when it already holds that
+ * content; otherwise a new one is written. The entry must be a page or a saved skill.
+ */
+export function pin(root: string, kind: 'page' | 'skill', id: string): string {
+  return pinAll(root, [{ kind, id }])[0]
+}
+
+/** Pins several entries, resolving every one before any snapshot is written. */
+export function pinAll(root: string, items: readonly { kind: 'page' | 'skill'; id: string }[]): string[] {
+  const wiki = store.wikiDir(root)
+  const contents = items.map(({ kind, id }) => {
+    const entry = resolveEntry(root, id)
+    const valid = kind === 'page' ? entry.kind === 'page' : entry.kind === 'registry' && entry.item.kind === 'skills'
+    if (!valid || entryId(entry) !== id) throw invalid('The selected reference is not a Wiki page or saved skill.')
+    return readFileSync(entryFile(entry), 'utf8')
+  })
+  return items.map(({ id }, index) => {
+    const current = store.currentRevision(wiki, id)
+    if (current) {
+      try {
+        if (store.revisionText(wiki, id, current) === contents[index]) return current
+      } catch {
+        // The manifest names a revision whose text is gone; pin a new one.
+      }
+    }
+    return store.snapshot(wiki, id, contents[index], 'user', 'Pinned chat reference').id
+  })
+}
+
+/** The pinned revision's body without its frontmatter. */
+export function body(root: string, id: string, revision: string | null): string {
+  if (!revision) throw invalid('This reference has no pinned revision.')
+  const text = store.revisionText(store.wikiDir(root), id, revision)
+  return frontmatter.bodyOf(text)
+}
+
+const PAGE_CHARS = 12_000
+
+/** A window of a reference that was selected for the caller's current run. */
+export function readPinned(root: string, runId: string | null | undefined, id: string, revision: string, offset: number): string {
+  if (!runId) throw invalid('Pinned references require a current run.')
+  const pack = readJson<{ sections?: { id: string; sources?: Source[] }[] }>(join(root, 'runs', safeId(runId), 'context.json'))
+  if (!pack) throw notFound('Run context')
+  const selected = (pack.sections ?? [])
+    .filter((section) => section.id === 'references')
+    .flatMap((section) => section.sources ?? [])
+    .find((source) => source.id === id && source.revision === revision && (source.kind === 'page' || source.kind === 'skill'))
+  if (!selected) throw invalid('This revision was not selected for the current reply.')
+  const characters = Array.from(body(root, id, revision))
+  const count = characters.length
+  if (offset > count) throw invalid('The reference offset is past the end.')
+  const excerpt = characters.slice(offset, offset + PAGE_CHARS).join('')
+  const end = offset + charCount(excerpt)
+  return `[${id}@${revision}] · characters ${offset}–${end} of ${count} · nextOffset: ${end < count ? end : 'none'}\n\n${excerpt}`
+}

package/src/memory/runContext.ts

@@ -0,0 +1,93 @@
+// What a run was given and what it read: every Wiki entry a run uses is recorded in
+// `runs/<id>/wiki-context.json`, so a person can see what informed a reply.
+import { join } from 'node:path'
+
+import { now, readJsonOr, safeId, writeJson } from '../core/fs'
+import { runsForSession } from '../sessions/runIndex'
+import type { CallerContext } from './caller'
+import * as store from './store'
+
+/** An entry and the revision that was current when it was used. */
+export interface Source {
+  id: string
+  kind: string
+  revision: string | null
+}
+
+export interface ContextEntry {
+  id: string
+  kind: string
+  revisionId: string | null
+  /** `entrypoint`, `search`, `read`, `skill`, `memory`, or `edit` (an entry the run changed). */
+  via: string
+  at: string
+}
+
+export function contextPath(root: string, runId: string): string {
+  return join(root, 'runs', safeId(runId), 'wiki-context.json')
+}
+
+export function readRunContext(root: string, runId: string): ContextEntry[] {
+  return readJsonOr<ContextEntry[]>(contextPath(root, runId), [])
+}
+
+/** The blocks, facts, and pages these runs changed, without repeats: `[id, kind]`. */
+export function editedBy(root: string, runIds: readonly string[]): [string, string][] {
+  const edited: [string, string][] = []
+  for (const runId of runIds) {
+    let entries: ContextEntry[]
+    try {
+      entries = readRunContext(root, runId)
+    } catch {
+      continue
+    }
+    for (const entry of entries) if (entry.via === 'edit' && !edited.some(([id]) => id === entry.id)) edited.push([entry.id, entry.kind])
+  }
+  return edited
+}
+
+/** The run a call belongs to: the caller's run, else the session's latest run. */
+function runOf(root: string, context: CallerContext): string | null {
+  if (context.runId) return context.runId
+  if (!context.sessionId) return null
+  try {
+    return runsForSession(root, context.sessionId, 1)[0] ?? null
+  } catch {
+    return null
+  }
+}
+
+export function recordSources(root: string, context: CallerContext, via: string, sources: readonly Source[]): void {
+  const runId = runOf(root, context)
+  if (!runId || !sources.length) return
+  let path: string
+  try {
+    path = contextPath(root, runId)
+  } catch {
+    return
+  }
+  if (!store.isDir(join(root, 'runs', runId))) return
+  const recorded = readRunContext(root, runId)
+  for (const source of sources) {
+    if (!recorded.some((entry) => entry.id === source.id && entry.revisionId === source.revision && entry.via === via)) {
+      recorded.push({ id: source.id, kind: source.kind, revisionId: source.revision, via, at: now() })
+    }
+  }
+  try {
+    writeJson(path, recorded)
+  } catch {
+    // A record that cannot be written never fails the call it describes.
+  }
+}
+
+/** `recordSources` for entries at their current revision: `[id, kind]`. */
+export function record(root: string, context: CallerContext, via: string, entries: readonly [string, string][]): void {
+  const wiki = store.wikiDir(root)
+  recordSources(root, context, via, entries.map(([id, kind]) => ({ id, kind, revision: store.currentRevision(wiki, id) })))
+}
+
+/** `[id@revision]`, the citation form every reply uses. */
+export function cite(wiki: string, id: string): string {
+  const revision = store.currentRevision(wiki, id)
+  return revision ? `[${id}@${revision.slice(0, 8)}]` : `[${id}]`
+}

package/src/memory/secrets.ts

@@ -0,0 +1,6 @@
+const SECRET_MARKERS = ['-----BEGIN', 'sk-ant-', 'sk-proj-', 'ghp_', 'github_pat_', 'AKIA', 'xoxb-']
+
+/** Text that carries a credential marker is never written to the Wiki. */
+export function looksSecret(text: string): boolean {
+  return SECRET_MARKERS.some((marker) => text.includes(marker))
+}

package/src/memory/store.test.ts

@@ -0,0 +1,66 @@
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { expect, test } from 'vitest'
+
+import { ensureLayout, ensureProjectNamespace, importSource, isSkeleton, listSources, locate, namespaceDir, parsePage, projectNamespaceOf, revisionsDir, serializePage, wikiDir } from './store'
+
+const temp = () => mkdtempSync(join(tmpdir(), 'harness-store-'))
+
+test('every project has a links page that starts as a map and is never replaced', () => {
+  const root = temp()
+  ensureLayout(root)
+  ensureProjectNamespace(root, 'app', 'App')
+  const links = join(wikiDir(root), 'projects/app/links.md')
+  const text = readFileSync(links, 'utf8')
+  const page = parsePage(text, wikiDir(root), links)!
+  expect([page.frontmatter.id, page.frontmatter.type]).toEqual(['app-links', 'reference'])
+  expect(page.body).toContain('one line each')
+  expect(page.body).toContain('do not copy')
+  expect(isSkeleton(page.location)).toBe(true)
+  // The agent's or user's entries survive the next start, which runs this for every project.
+  writeFileSync(links, text.replace('Nothing recorded yet.', '- docs/specs/product.md: what the app is for'))
+  ensureProjectNamespace(root, 'app', 'App')
+  expect(readFileSync(links, 'utf8')).toContain('docs/specs/product.md')
+})
+
+test('derives paths and namespaces from file locations', () => {
+  const wiki = '/data/wiki'
+  expect(locate(wiki, '/data/wiki/projects/xingular-agent/design/arch.md')).toEqual({ path: '/projects/xingular-agent/design/arch', namespace: '/projects/xingular-agent' })
+  expect(locate(wiki, '/data/wiki/library/tauri.md').namespace).toBe('/library')
+  expect(locate(wiki, '/data/wiki/home.md')).toEqual({ path: '/home', namespace: '/' })
+  expect(namespaceDir(wiki, '/projects/xingular-agent')).toBe('/data/wiki/projects/xingular-agent')
+  expect(namespaceDir(wiki, '/')).toBe('/data/wiki/library')
+  expect(namespaceDir(wiki, '/docs/guides')).toBe('/data/wiki/library/guides')
+  expect(() => namespaceDir(wiki, '/projects/../x')).toThrow()
+  expect(() => namespaceDir(wiki, '/facts')).toThrow()
+  expect(projectNamespaceOf('/projects/a/b')).toBe('/projects/a')
+  expect(projectNamespaceOf('/library')).toBeNull()
+})
+
+test('imports each source once and versions replacements', () => {
+  const root = temp()
+  ensureLayout(root)
+  const wiki = wikiDir(root)
+  const first = importSource(wiki, 'notes.md', Buffer.from('one'))
+  expect(importSource(wiki, 'notes.md', Buffer.from('one')).id).toBe(first.id)
+  const second = importSource(wiki, 'notes.md', Buffer.from('two'))
+  expect(second.version).toBe(2)
+  expect(second.previousId).toBe(first.id)
+  expect(listSources(wiki)).toHaveLength(2)
+})
+
+test('round-trips frontmatter and drops legacy scope', () => {
+  const text = '---\nid: a\ntitle: A\ntype: concept\nscope: personal\nsourceIds:\n- src-1\n---\n\nBody\n'
+  const page = parsePage(text, '/w', '/w/library/a.md')!
+  const serialized = serializePage(page.frontmatter, page.body)
+  expect(serialized).not.toContain('scope')
+  const reparsed = parsePage(serialized, '/w', '/w/library/a.md')!
+  expect(reparsed.frontmatter.sourceIds).toEqual(['src-1'])
+  expect(reparsed.body.trim()).toBe('Body')
+})
+
+test('registry ids get revision folders', () => {
+  expect(revisionsDir('/w', 'skills/review')).toBe('/w/revisions/skills--review')
+  expect(() => revisionsDir('/w', '../x')).toThrow()
+})