@xingular/harness 2.1.2 → 3.0.0

package/src/memory/migrate.ts

@@ -1,79 +0,0 @@
-// Storage migration to version 3: memory blocks, facts, and the Library.
-//
-// Version 3 starts from an empty Wiki. Whatever came before is kept whole as a backup and is
-// not carried over: a version 2 `wiki/` becomes `wiki.pre-v3/`, and a version 1 `knowledge/`
-// becomes `knowledge.pre-v2/`. The new tree is staged in `wiki.migrating/` before anything is
-// renamed; on failure the staged tree is removed and the earlier Wiki is left in place.
-import { existsSync, renameSync, rmSync } from 'node:fs'
-import { join } from 'node:path'
-
-import type { HarnessEnv } from '../core/env'
-import { HarnessError } from '../core/errors'
-import { now, readJsonOr, writeJson } from '../core/fs'
-import { listProjects } from '../core/projects'
-import * as registry from '../skills/registry'
-import * as blocks from './blocks'
-import { writeIndex } from './proposals'
-import * as store from './store'
-
-export const WIKI_VERSION = 3
-
-const storagePath = (root: string): string => join(root, 'config/storage.json')
-
-export function version(root: string): number {
-  const stored = readJsonOr<{ wikiVersion?: unknown } | null>(storagePath(root), null)?.wikiVersion
-  if (typeof stored === 'number' && Number.isInteger(stored) && stored >= 0) return stored
-  const wiki = store.wikiDir(root)
-  if (store.isDir(join(root, 'knowledge'))) return 1
-  // A version 2 Wiki whose marker is missing still has its old folders and no blocks.
-  if (!existsSync(join(wiki, 'blocks')) && (store.isDir(join(wiki, 'docs')) || store.isDir(join(wiki, 'memory')))) return 2
-  return WIKI_VERSION
-}
-
-const stamp = (): string => now().replace(/[:.]/g, '-')
-
-/** Moves `from` to `<name>` beside it, or `<name>-<time>` when that backup already exists. */
-function backUp(root: string, from: string, name: string): void {
-  if (!existsSync(from)) return
-  renameSync(from, existsSync(join(root, name)) ? join(root, `${name}-${stamp()}`) : join(root, name))
-}
-
-/**
- * Brings a data root to the current Wiki layout. Safe to call on every start. `agentIds` are
- * the agents that get their own blocks. Returns whether a migration happened.
- */
-export function run(env: HarnessEnv, agentIds: readonly string[] = []): boolean {
-  const { root } = env
-  if (version(root) >= WIKI_VERSION) return false
-  const failed = (detail: string): HarnessError => new HarnessError('migration_failed', `The Wiki was not migrated to version 3; your Wiki is unchanged. ${detail}`)
-  const staging = join(root, 'wiki.migrating')
-  rmSync(staging, { recursive: true, force: true })
-  try {
-    store.ensureLayoutAt(staging, env.productName)
-    blocks.ensureUser(staging)
-    for (const agentId of agentIds) blocks.ensureAgent(staging, agentId)
-    for (const project of listProjects(root)) blocks.ensureProject(staging, project.slug, project.name)
-    store.log(staging, `- ${now()} · ${env.productName} · started storage version 3; the earlier Wiki is kept as a backup beside it`)
-    backUp(root, store.wikiDir(root), 'wiki.pre-v3')
-  } catch (error) {
-    rmSync(staging, { recursive: true, force: true })
-    throw failed(error instanceof Error ? error.message : String(error))
-  }
-  renameSync(staging, store.wikiDir(root))
-  backUp(root, join(root, 'knowledge'), 'knowledge.pre-v2')
-
-  store.ensureLayout(root, env.productName)
-  for (const project of listProjects(root)) store.ensureProjectNamespace(root, project.slug, project.name)
-  // Registry items that version 1 enabled for personal agents are enabled for everyone.
-  const enablement = registry.enablement(root)
-  if ('personal' in enablement) {
-    const ids = registry.enablementIds(enablement, registry.GLOBAL_KEY)
-    for (const id of registry.enablementIds(enablement, 'personal')) if (!ids.includes(id)) ids.push(id)
-    delete enablement.personal
-    enablement[registry.GLOBAL_KEY] = ids
-    writeJson(join(root, 'config/registry-enabled.json'), enablement)
-  }
-  writeIndex(store.wikiDir(root))
-  writeJson(storagePath(root), { wikiVersion: WIKI_VERSION, migratedAt: now() })
-  return true
-}

package/src/memory/operations.ts

@@ -1,150 +0,0 @@
-// Operations: one applied change to the Wiki, recorded so it can be undone. Undo writes new
-// revisions and never erases history. The Inbox holds what was applied, parked, or flagged.
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync } from 'node:fs'
-import { join } from 'node:path'
-
-import { noteChange } from '../core/changes'
-import { invalid, notFound } from '../core/errors'
-import { atomicWrite, newId, now, readJson, safeId, writeJson } from '../core/fs'
-import { compareText } from '../core/text'
-import * as store from './store'
-import * as attachments from '../plugins/attachments'
-import { dirname } from 'node:path'
-
-export interface OperationPage {
-  pageId: string
-  path: string
-  /** Revision holding the content before this operation; `null` when the entry was created. */
-  beforeRevisionId: string | null
-  afterRevisionId: string
-}
-
-export interface Operation {
-  id: string
-  createdAt: string
-  trigger: string
-  pages: OperationPage[]
-  undone: boolean
-  protected?: boolean
-  attachmentsBefore?: attachments.Attachments
-  attachmentsAfter?: attachments.Attachments
-}
-
-export function operationsDir(wiki: string): string {
-  return join(wiki, 'operations')
-}
-
-export function listOperations(wiki: string): Operation[] {
-  let names: string[]
-  try {
-    names = readdirSync(operationsDir(wiki))
-  } catch {
-    return []
-  }
-  const operations: Operation[] = []
-  for (const name of names) {
-    try {
-      const operation = readJson<Operation>(join(operationsDir(wiki), name))
-      if (operation && typeof operation.id === 'string' && Array.isArray(operation.pages)) operations.push({ ...operation, undone: operation.undone ?? false })
-    } catch {
-      // Not an operation record.
-    }
-  }
-  return operations
-}
-
-export function lastOperationAt(wiki: string): string | null {
-  return listOperations(wiki).map((operation) => operation.createdAt).sort(compareText).at(-1) ?? null
-}
-
-export interface InboxItem {
-  id: string
-  kind: string
-  title: string
-  detail: string
-  pageIds: string[]
-  createdAt: string
-  /** Operation this item reports, so it can be undone from the Inbox. */
-  operationId: string | null
-  /** A parked proposal the user can accept (`kind`, `proposal`, `namespace`). */
-  payload?: unknown
-}
-
-export function inbox(wiki: string, kind: string, title: string, detail: string, pageIds: string[], operationId: string | null = null, payload?: unknown): void {
-  const item: InboxItem = { id: newId(), kind, title, detail, pageIds, createdAt: now(), operationId, ...(payload === undefined || payload === null ? {} : { payload }) }
-  writeJson(join(wiki, 'inbox', `${item.id}.json`), item)
-}
-
-/** Inbox items, newest first. */
-export function listInbox(wiki: string): InboxItem[] {
-  let names: string[]
-  try {
-    names = readdirSync(join(wiki, 'inbox'))
-  } catch {
-    return []
-  }
-  const items: InboxItem[] = []
-  for (const name of names) {
-    try {
-      const item = readJson<InboxItem>(join(wiki, 'inbox', name))
-      if (item && typeof item.id === 'string' && typeof item.kind === 'string') items.push({ ...item, operationId: item.operationId ?? null })
-    } catch {
-      // Folders (`dismissed/`) and unreadable files are not items.
-    }
-  }
-  return items.sort((left, right) => compareText(right.createdAt, left.createdAt))
-}
-
-export function dismissInboxItem(wiki: string, itemId: string): void {
-  const source = join(wiki, 'inbox', `${safeId(itemId)}.json`)
-  const target = join(wiki, 'inbox', 'dismissed')
-  mkdirSync(target, { recursive: true })
-  try {
-    renameSync(source, join(target, `${itemId}.json`))
-  } catch {
-    throw notFound('Inbox item')
-  }
-}
-
-/** Reverts an operation through new revisions. Entries it created move to `trash/`. */
-export function undo(wiki: string, operationId: string): Operation {
-  const path = join(operationsDir(wiki), `${safeId(operationId)}.json`)
-  const operation = readJson<Operation>(path)
-  if (!operation) throw notFound('Maintenance operation')
-  if (operation.undone) throw invalid('This operation was already undone.')
-  if (operation.protected) {
-    for (const page of operation.pages) {
-      if (!existsSync(page.path) || readFileSync(page.path, 'utf8') !== store.revisionText(wiki, page.pageId, page.afterRevisionId)) throw invalid('An entry changed after this operation; review it before undoing.')
-    }
-    if (operation.attachmentsAfter && JSON.stringify(attachments.load(dirname(wiki))) !== JSON.stringify(operation.attachmentsAfter)) throw invalid('Attachment settings changed after this operation; review them before undoing.')
-  }
-  const short = operation.id.slice(0, 8)
-  if (operation.attachmentsBefore) attachments.save(dirname(wiki), operation.attachmentsBefore)
-  for (const page of operation.pages) {
-    let current = ''
-    try {
-      current = readFileSync(page.path, 'utf8')
-    } catch {
-      current = ''
-    }
-    if (page.beforeRevisionId) {
-      const previous = store.revisionText(wiki, page.pageId, page.beforeRevisionId)
-      store.snapshot(wiki, page.pageId, current, 'user', `Before undo of ${short}`)
-      atomicWrite(page.path, previous)
-      store.snapshot(wiki, page.pageId, previous, 'user', `Undo of update ${short}`)
-      noteChange({ wiki, id: page.pageId, path: page.path, text: previous, actor: 'user', reason: 'Undid an update' })
-    } else {
-      const trash = join(wiki, 'trash')
-      mkdirSync(trash, { recursive: true })
-      if (existsSync(page.path)) {
-        const target = join(trash, `${page.pageId}-${now().replace(/[:.]/g, '-')}.md`)
-        mkdirSync(join(target, '..'), { recursive: true })
-        renameSync(page.path, target)
-      }
-    }
-  }
-  operation.undone = true
-  writeJson(path, operation)
-  store.log(wiki, `- ${now()} · user · undo · op \`${operation.id}\``)
-  return operation
-}

package/src/memory/proposals.test.ts

@@ -1,168 +0,0 @@
-import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { expect, test } from 'vitest'
-
-import { dataRoot } from '../../tests/helpers'
-import * as blocks from './blocks'
-import { findMemory } from './facts'
-import { listInbox, undo } from './operations'
-import { accept, apply, captureHashes, parkRegistryProposal, parseProposalSet, quotedIn, type Evidence, type Trigger } from './proposals'
-import { readManifest, wikiDir } from './store'
-
-function setup(): { root: string; wiki: string } {
-  const root = dataRoot()
-  return { root, wiki: wikiDir(root) }
-}
-
-const proposal = (id: string, refs: [string, string][]) => ({
-  id,
-  title: `Title ${id}`,
-  type: 'decision',
-  body: `Body of ${id}.`,
-  sourceRefs: refs.map(([kind, ref]) => ({ kind, ref, excerpt: 'we decided to use Tauri' }))
-})
-
-const memoryProposal = (id: string, confidence: string) => ({
-  id,
-  title: `Memory ${id}`,
-  kind: 'preference',
-  body: 'Prefer small commits.',
-  confidence,
-  sourceRefs: [{ kind: 'run', ref: 'run-1', excerpt: 'prefer small commits' as string | undefined }]
-})
-
-/** What run-1 recorded: the text excerpts are checked against. */
-const ev = (): Evidence => ({ runText: 'User: which shell?\nAssistant: We decided to use   Tauri. I prefer small commits.\n' })
-const agent = (): Trigger => ({ kind: 'agent', runId: 'run-1', actor: 'Chat' })
-const set = (value: unknown) => parseProposalSet(value)
-const inboxItems = (wiki: string) => listInbox(wiki).sort((left, right) => (left.kind < right.kind ? -1 : left.kind > right.kind ? 1 : 0))
-
-test('applies cited pages into the namespace and parks uncited ones', () => {
-  const { wiki } = setup()
-  const withKey = { ...proposal('with-key', [['run', 'run-1']]), body: 'token sk-ant-abc123' }
-  const proposals = set({ pages: [proposal('use-tauri', [['run', 'run-1']]), proposal('rumor', [['run', 'other-run']]), withKey], flags: [{ claim: 'x', kind: 'uncited', reason: 'none' }] })
-  const outcome = apply(wiki, '/projects/app', agent(), proposals, new Map(), ev())
-  const operation = outcome.operation!
-  expect(operation.pages).toHaveLength(1)
-  expect(outcome.parked).toBe(2)
-  expect(readFileSync(join(wiki, 'projects/app/use-tauri.md'), 'utf8')).toContain('run:run-1')
-  expect(readFileSync(join(wiki, 'index.md'), 'utf8')).toContain('[/projects/app](projects/app/index.md) — 1 page')
-  expect(readFileSync(join(wiki, 'projects/app/index.md'), 'utf8')).toContain('- [Title use-tauri](use-tauri.md) (decision, `use-tauri`)')
-  expect(readFileSync(join(wiki, 'log.md'), 'utf8')).toContain(operation.id)
-  const items = inboxItems(wiki)
-  expect(items.map((item) => item.kind)).toEqual(['applied', 'blocked', 'unresolved', 'unresolved'])
-  // The parked uncited page can be accepted; the credential one carries no payload.
-  expect(items.some((item) => item.kind === 'unresolved' && item.payload !== undefined)).toBe(true)
-  expect(items.every((item) => item.kind !== 'blocked' || item.payload === undefined)).toBe(true)
-})
-
-test('memories apply with evidence and low confidence waits for acceptance', () => {
-  const { root, wiki } = setup()
-  const outcome = apply(wiki, '/projects/app', { kind: 'agent', runId: 'run-1', actor: 'Code' }, set({ memories: [memoryProposal('small-commits', 'high'), memoryProposal('maybe', 'low')] }), new Map(), ev())
-  expect(outcome.operation!.pages).toHaveLength(1)
-  const saved = findMemory(wiki, 'small-commits')
-  expect(saved.front.namespace).toBe('/projects/app')
-  expect(saved.front.sourceIds).toEqual(['run:run-1'])
-  expect(readManifest(wiki, 'small-commits')[0].actor).toBe('Code')
-  const parked = listInbox(wiki).find((item) => item.payload !== undefined)!
-  accept(root, parked.id)
-  expect(findMemory(wiki, 'maybe').front.sourceIds).toContain('user:accepted')
-  expect(() => accept(root, parked.id)).toThrow()
-})
-
-test('superseding memory retires the old one', () => {
-  const { wiki } = setup()
-  const trigger: Trigger = { kind: 'run', runId: 'run-1' }
-  apply(wiki, '/library', trigger, set({ memories: [memoryProposal('old', 'high')] }), new Map(), ev())
-  apply(wiki, '/library', trigger, set({ memories: [{ ...memoryProposal('new', 'high'), supersedes: 'old' }] }), captureHashes(wiki), ev())
-  expect(findMemory(wiki, 'old').front.status).toBe('superseded')
-  expect(findMemory(wiki, 'new').front.supersedes).toBe('old')
-})
-
-test('registry proposals always wait and accept writes a revision', () => {
-  const { root, wiki } = setup()
-  const id = parkRegistryProposal(wiki, { kind: 'agent', runId: null, actor: 'Chat' }, { kind: 'skill', name: 'Release notes', description: 'Write release notes', body: 'Steps.', reason: '' })
-  expect(id).toBe('skills/release-notes')
-  expect(existsSync(join(root, 'registry/skills/release-notes'))).toBe(false)
-  accept(root, listInbox(wiki).find((item) => item.kind === 'proposed')!.id)
-  const text = readFileSync(join(root, 'registry/skills/release-notes/SKILL.md'), 'utf8')
-  expect(text).toContain('Write release notes')
-  expect(text).toContain('Steps.')
-  expect(readManifest(wiki, 'skills/release-notes')).toHaveLength(1)
-})
-
-test('never overwrites a page edited during the job', () => {
-  const { wiki } = setup()
-  apply(wiki, '/library', agent(), set({ pages: [proposal('p', [['run', 'run-1']])] }), new Map(), ev())
-  const captured = captureHashes(wiki)
-  const path = join(wiki, 'library/p.md')
-  appendFileSync(path, '\nUser edit.\n')
-  const outcome = apply(wiki, '/library', agent(), set({ pages: [proposal('p', [['run', 'run-1']])] }), captured, ev())
-  expect(outcome.operation).toBeNull()
-  expect(readFileSync(path, 'utf8')).toContain('User edit.')
-})
-
-test('undo restores through new revisions', () => {
-  const { wiki } = setup()
-  apply(wiki, '/library', agent(), set({ pages: [proposal('p', [['run', 'run-1']])] }), new Map(), ev())
-  const path = join(wiki, 'library/p.md')
-  const original = readFileSync(path, 'utf8')
-  const second = apply(wiki, '/library', agent(), set({ pages: [{ ...proposal('p', [['run', 'run-1']]), body: 'Changed body.' }] }), captureHashes(wiki), ev()).operation!
-  const revisionsBefore = readManifest(wiki, 'p').length
-  undo(wiki, second.id)
-  expect(readFileSync(path, 'utf8')).toBe(original)
-  expect(readManifest(wiki, 'p').length).toBeGreaterThan(revisionsBefore)
-  expect(() => undo(wiki, second.id)).toThrow()
-})
-
-test('a run reference counts only with an excerpt found in the run', () => {
-  expect(quotedIn('We decided to use\n  Tauri.', 'decided to use tauri')).toBe(true)
-  expect(quotedIn('We decided to use Tauri.', 'Tauri')).toBe(false)
-  expect(quotedIn('We decided to use Tauri.', 'decided to use Electron')).toBe(false)
-  expect(quotedIn(null, 'decided to use tauri')).toBe(false)
-  const { wiki } = setup()
-  const bare = { ...memoryProposal('bare', 'high'), sourceRefs: [{ kind: 'run', ref: 'run-1' }] }
-  const invented = { ...memoryProposal('invented', 'high'), sourceRefs: [{ kind: 'run', ref: 'run-1', excerpt: 'the user loves large commits' }] }
-  const outcome = apply(wiki, '/library', agent(), set({ memories: [bare, invented, memoryProposal('quoted', 'high')] }), new Map(), ev())
-  expect(outcome.parked).toBe(2)
-  expect(findMemory(wiki, 'quoted').front.id).toBe('quoted')
-  expect(() => findMemory(wiki, 'bare')).toThrow()
-  expect(() => findMemory(wiki, 'invented')).toThrow()
-})
-
-test('consolidating a run updates pages and blocks but creates no page', () => {
-  const { wiki } = setup()
-  apply(wiki, '/library', agent(), set({ pages: [proposal('shell', [['run', 'run-1']])] }), new Map(), ev())
-  const user = blocks.ensureUser(wiki)
-  const notes = blocks.ensureAgent(wiki, 'a1')[1]
-  const quoted = (block: string, body: string, excerpt: string) => ({ block, body, sourceRefs: [{ kind: 'run', ref: 'run-1', excerpt }] })
-  const proposals = set({
-    pages: [{ ...proposal('shell', [['run', 'run-1']]), body: 'We use Tauri.' }, proposal('observed-in-run', [['run', 'run-1']])],
-    blocks: [quoted(user.id, 'Prefers small commits.', 'I prefer small commits'), quoted(user.id, 'Made up.', 'something never said at all'), quoted(notes.id, 'Not attached.', 'I prefer small commits')]
-  })
-  const outcome = apply(wiki, '/library', { kind: 'run', runId: 'run-1' }, proposals, captureHashes(wiki), { ...ev(), blocks: [user.id] })
-  const operation = outcome.operation!
-  expect(operation.pages.map((page) => page.pageId)).toEqual(['shell', 'blocks/shared/user'])
-  expect(outcome.parked).toBe(3)
-  expect(existsSync(join(wiki, 'library/observed-in-run.md'))).toBe(false)
-  expect(blocks.find(wiki, user.id).body).toBe('Prefers small commits.')
-  expect(readManifest(wiki, user.id).at(-1)!.actor).toBe('Sleep-time')
-  expect(blocks.find(wiki, notes.id).body).toBe('')
-  // The whole consolidation undoes as one operation.
-  undo(wiki, operation.id)
-  expect(blocks.find(wiki, user.id).body).toBe('')
-})
-
-test('idle consolidation only shortens a block', () => {
-  const { wiki } = setup()
-  const user = blocks.ensureUser(wiki)
-  writeFileSync(user.path, `${readFileSync(user.path, 'utf8')}Likes pnpm. Likes pnpm a lot. Uses pnpm everywhere.\n`)
-  const evidence: Evidence = { blocks: [user.id] }
-  const rewrite = (body: string) => set({ blocks: [{ block: user.id, body }] })
-  const longer = apply(wiki, '/library', { kind: 'consolidate' }, rewrite('Likes pnpm. Likes pnpm a lot. Uses pnpm everywhere. Also loves yarn and npm.'), new Map(), evidence)
-  expect(longer.operation).toBeNull()
-  expect(longer.parked).toBe(1)
-  const shorter = apply(wiki, '/library', { kind: 'consolidate' }, rewrite('Uses pnpm everywhere.'), new Map(), evidence)
-  expect(shorter.operation).not.toBeNull()
-  expect(blocks.find(wiki, user.id).body).toBe('Uses pnpm everywhere.')
-})