@xingular/harness 2.1.2 → 3.0.0

package/src/memory/proposals.ts

@@ -1,584 +0,0 @@
-// Validated Wiki updates.
-//
-// Agents and the sleep-time maintainer only *propose* pages, facts, and block rewrites. This
-// module validates every proposal (type, links, evidence, confidence, secrets, concurrent
-// edits), applies the valid ones as one atomic operation with revisions, and sends the rest to
-// the Inbox, where the user can accept them. Proposals to change skills, prompts, or rules
-// always wait in the Inbox.
-import { createHash } from 'node:crypto'
-import { mkdirSync, readFileSync, renameSync, rmSync } from 'node:fs'
-import { dirname, join, relative } from 'node:path'
-import { z } from 'zod'
-
-import { noteChange } from '../core/changes'
-import { HarnessError, invalid, notFound } from '../core/errors'
-import { atomicWrite, newId, now, readJson, safeId, writeJson } from '../core/fs'
-import { charCount, compareText, takeChars } from '../core/text'
-import { acceptPluginProposal, pluginProposalSchema } from '../plugins/proposal'
-import * as registry from '../skills/registry'
-import * as blocks from './blocks'
-import * as facts from './facts'
-import { inbox, operationsDir, type InboxItem, type Operation, type OperationPage } from './operations'
-import { looksSecret } from './secrets'
-import * as store from './store'
-import { LINK_TYPES, PAGE_TYPES, type WikiLink } from './store'
-
-// ---- Proposals ------------------------------------------------------------------------------
-
-const optionalText = z.string().nullish().transform((value) => value ?? null)
-
-const sourceRefSchema = z.object({
-  kind: z.string(),
-  ref: z.string(),
-  /** A passage quoted from the evidence. A run or source reference counts only when this passage is found in it. */
-  excerpt: z.string().nullish().transform((value) => value ?? undefined)
-})
-export type SourceRef = z.infer<typeof sourceRefSchema>
-
-const linkProposalSchema = z.object({ toId: z.string(), type: z.string() })
-export type LinkProposal = z.infer<typeof linkProposalSchema>
-
-export const pageProposalSchema = z.object({
-  id: optionalText,
-  title: z.string(),
-  type: z.string(),
-  body: z.string(),
-  /** Where a new page is filed (`/library`, `/projects/<slug>`); the job's namespace by default. */
-  namespace: optionalText,
-  confidence: optionalText,
-  sourceRefs: z.array(sourceRefSchema).default([]),
-  links: z.array(linkProposalSchema).default([])
-})
-export type PageProposal = z.infer<typeof pageProposalSchema>
-
-export const memoryProposalSchema = z.object({
-  id: optionalText,
-  title: z.string(),
-  kind: z.string(),
-  body: z.string(),
-  /** `/` for everything, or a project namespace. The job's project namespace by default. */
-  namespace: optionalText,
-  confidence: optionalText,
-  supersedes: optionalText,
-  volatile: z.boolean().nullish().transform((value) => value ?? null),
-  sourceRefs: z.array(sourceRefSchema).default([]),
-  links: z.array(linkProposalSchema).default([])
-})
-export type MemoryProposal = z.infer<typeof memoryProposalSchema>
-
-/** A rewritten memory block from sleep-time consolidation. */
-const blockProposalSchema = z.object({ block: z.string(), body: z.string(), sourceRefs: z.array(sourceRefSchema).default([]) })
-export type BlockProposal = z.infer<typeof blockProposalSchema>
-
-const claimFlagSchema = z.object({ claim: z.string(), kind: z.string(), reason: z.string() })
-export type ClaimFlag = z.infer<typeof claimFlagSchema>
-
-export const proposalSetSchema = z.object({
-  pages: z.array(pageProposalSchema).default([]),
-  memories: z.array(memoryProposalSchema).default([]),
-  blocks: z.array(blockProposalSchema).default([]),
-  flags: z.array(claimFlagSchema).default([])
-})
-export type ProposalSet = z.infer<typeof proposalSetSchema>
-
-export function parseProposalSet(value: unknown): ProposalSet {
-  const parsed = proposalSetSchema.safeParse(value ?? {})
-  if (!parsed.success) throw new HarnessError('invalid_data', `Stored data could not be read: ${parsed.error.issues[0]?.message ?? 'invalid proposals'}`)
-  return parsed.data
-}
-
-/** The text proposals are checked against, and the blocks a job may rewrite. */
-export interface Evidence {
-  /** The triggering run's request, assistant messages, and tool summaries. */
-  runText?: string | null
-  /** The imported source's text. */
-  sourceText?: string | null
-  /** Ids of the blocks attached to the run. */
-  blocks?: string[]
-  runs?: Record<string, string>
-  sources?: Record<string, string>
-}
-
-const MIN_EXCERPT = 12
-
-function squash(text: string): string {
-  return text.split(/\s+/).filter(Boolean).join(' ').toLowerCase()
-}
-
-/**
- * Whether `excerpt` occurs in `text`, ignoring case and runs of whitespace. Short excerpts
- * prove nothing, so they never count.
- */
-export function quotedIn(text: string | null | undefined, excerpt: string | null | undefined): boolean {
-  if (typeof text !== 'string' || typeof excerpt !== 'string') return false
-  const wanted = squash(excerpt)
-  return charCount(wanted) >= MIN_EXCERPT && squash(text).includes(wanted)
-}
-
-/** What caused the change; decides which evidence references are valid and who the actor is. */
-export type Trigger =
-  | { kind: 'ingest'; sourceId: string; sourceName: string }
-  | { kind: 'run'; runId: string }
-  /** An agent's `wiki_propose` during a run. */
-  | { kind: 'agent'; runId: string | null; actor: string }
-  /** The user accepted an Inbox item. */
-  | { kind: 'user'; itemId: string }
-  /** Idle consolidation of memory blocks that are close to their limit. */
-  | { kind: 'consolidate' }
-
-export function describeTrigger(trigger: Trigger): string {
-  switch (trigger.kind) {
-    case 'ingest':
-      return `ingest of ${trigger.sourceName} (${trigger.sourceId})`
-    case 'run':
-      return `run ${trigger.runId}`
-    case 'agent':
-      return trigger.runId ? `${trigger.actor} agent in run ${trigger.runId}` : `${trigger.actor} agent`
-    case 'user':
-      return `Inbox item ${trigger.itemId.slice(0, 8)}`
-    case 'consolidate':
-      return 'consolidation of full memory blocks'
-  }
-}
-
-function triggerActor(trigger: Trigger): string {
-  return trigger.kind === 'agent' ? trigger.actor : trigger.kind === 'user' ? 'user' : 'Sleep-time'
-}
-
-function triggerRunId(trigger: Trigger): string | null {
-  return trigger.kind === 'run' ? trigger.runId : trigger.kind === 'agent' ? trigger.runId : null
-}
-
-// ---- Applying ---------------------------------------------------------------------------------
-
-function fileHash(path: string): string | null {
-  try {
-    return createHash('sha256').update(readFileSync(path)).digest('hex')
-  } catch {
-    return null
-  }
-}
-
-function readOrNull(path: string): string | null {
-  try {
-    return readFileSync(path, 'utf8')
-  } catch {
-    return null
-  }
-}
-
-/** Captures page, fact, and block file hashes when a job starts, to detect edits made while it ran. */
-export function captureHashes(wiki: string): Map<string, string> {
-  const hashes = new Map<string, string>()
-  const add = (id: string, path: string) => {
-    const hash = fileHash(path)
-    if (hash) hashes.set(id, hash)
-  }
-  for (const page of store.loadPages(wiki)) add(page.frontmatter.id, page.path)
-  for (const memory of facts.loadMemories(wiki)) add(memory.front.id, memory.path)
-  for (const block of blocks.loadAll(wiki)) add(block.id, block.path)
-  for (const item of registry.list(dirname(wiki))) add(item.id, item.path)
-  return hashes
-}
-
-/**
- * Rewrites the generated indexes: the root `index.md` lists the namespaces, and each namespace
- * has its own `index.md` listing its pages with one line each. Any page is two steps away.
- */
-export function writeIndex(wiki: string): void {
-  const pages = store.loadPages(wiki)
-  const memories = facts.loadMemories(wiki)
-  const namespaces = [...new Set(pages.map((page) => page.location.namespace).filter((namespace) => namespace !== store.ROOT_NAMESPACE))].sort(compareText)
-  let root = '# Wiki index\n\nEach namespace has its own index of pages.\n\n'
-  if (!namespaces.length) root += 'No pages yet.\n'
-  for (const namespace of namespaces) {
-    const own = pages.filter((page) => page.location.namespace === namespace).sort((left, right) => compareText(left.location.path, right.location.path))
-    const folder = namespace.replace(/^\/+/, '')
-    root += `- [${namespace}](${folder}/index.md) — ${own.length} page${own.length === 1 ? '' : 's'}\n`
-    let text = `# Index of ${namespace}\n\n`
-    for (const page of own) {
-      const inside = relative(join(wiki, folder), page.path)
-      text += `- [${page.frontmatter.title}](${inside.startsWith('..') ? page.path : inside}) (${page.frontmatter.type}, \`${page.frontmatter.id}\`) — ${store.firstParagraph(page.body)}\n`
-    }
-    atomicWrite(join(wiki, folder, 'index.md'), text)
-  }
-  const active = memories.filter((memory) => memory.front.status === 'active')
-  if (active.length) {
-    root += '\n## Facts\n\n'
-    for (const memory of active) root += `- [${memory.front.title}](facts/${memory.front.id}.md) (${memory.front.kind}, ${memory.front.namespace}${memory.front.volatile ? ', volatile' : ''})\n`
-  }
-  atomicWrite(join(wiki, 'index.md'), root)
-}
-
-export interface ApplyOutcome {
-  operation: Operation | null
-  parked: number
-  flagged: number
-  /** One line per proposal: what happened to it. */
-  notes: string[]
-}
-
-interface Write {
-  entryId: string
-  path: string
-  oldText: string | null
-  newText: string
-}
-
-/** Validates proposals and applies the valid ones as one operation. Pure file logic. */
-export function apply(wiki: string, defaultNamespace: string, trigger: Trigger, proposals: ProposalSet, captured: ReadonlyMap<string, string>, evidence: Evidence, operationKey?: string, appliedBy?: string): ApplyOutcome {
-  if (operationKey) {
-    const committed = readJson<Operation>(join(operationsDir(wiki), `${safeId(operationKey)}.json`))
-    if (committed) return { operation: committed, parked: 0, flagged: 0, notes: ['This request was already applied.'] }
-  }
-  const existing = store.loadPages(wiki)
-  const existingMemories = facts.loadMemories(wiki)
-  const root = dirname(wiki)
-  const sourceIds = new Set(store.listSources(wiki).map((source) => source.id))
-  const knownIds = new Set<string>([
-    ...existing.map((page) => page.frontmatter.id),
-    ...existingMemories.map((memory) => memory.front.id),
-    ...registry.list(root).map((item) => item.id),
-    ...sourceIds
-  ])
-  const proposedIds = new Set<string>([
-    ...proposals.pages.map((page) => store.slug(page.id ?? page.title)),
-    ...proposals.memories.map((memory) => store.slug(memory.id ?? memory.title))
-  ])
-  const outcome: ApplyOutcome = { operation: null, parked: 0, flagged: 0, notes: [] }
-  const writes: Write[] = []
-  const actor = appliedBy ?? triggerActor(trigger)
-  const described = describeTrigger(trigger)
-  const fromUser = trigger.kind === 'user'
-
-  // Sends one proposal to the Inbox with its payload, so the user can accept it later.
-  const park = (kind: string, title: string, label: string, reason: string, body: string, entryId: string, payload: unknown): void => {
-    outcome.parked += 1
-    outcome.notes.push(`${label} went to the Inbox: ${reason}`)
-    inbox(wiki, kind, title, `${reason}\n\n${takeChars(body, 600)}`, [entryId], null, operationKey && payload && typeof payload === 'object' ? { ...payload, curationJobId: operationKey } : payload)
-  }
-
-  // Evidence: a source in the Wiki, the triggering run, a URL, or the user's acceptance. A run
-  // or an imported source counts only with an excerpt found in its text; a bare reference to
-  // the caller's own run proves nothing.
-  const evidenceFor = (refs: readonly SourceRef[]): string[] => {
-    const found: string[] = []
-    for (const reference of refs) {
-      let id: string | null = null
-      if (reference.kind === 'source') {
-        const source = evidence.sources?.[reference.ref] ?? (trigger.kind === 'ingest' && trigger.sourceId === reference.ref ? evidence.sourceText : null)
-        if (sourceIds.has(reference.ref) && (operationKey ? quotedIn(source, reference.excerpt) : (evidence.sourceText == null || quotedIn(evidence.sourceText, reference.excerpt)))) id = reference.ref
-      } else if (reference.kind === 'run') {
-        if (quotedIn(evidence.runs?.[reference.ref] ?? (triggerRunId(trigger) === reference.ref ? evidence.runText : null), reference.excerpt)) id = `run:${reference.ref}`
-      } else if (reference.kind === 'url') {
-        if (!operationKey && (reference.ref.startsWith('https://') || reference.ref.startsWith('http://'))) id = `url:${reference.ref}`
-      } else if (reference.kind === 'user') {
-        if (fromUser) id = 'user:accepted'
-      }
-      if (id && !found.includes(id)) found.push(id)
-    }
-    return found
-  }
-  const filterLinks = (links: readonly LinkProposal[], ownId: string): WikiLink[] =>
-    links
-      .filter((link) => (LINK_TYPES as readonly string[]).includes(link.type))
-      .filter((link) => knownIds.has(link.toId) || proposedIds.has(link.toId))
-      .filter((link) => link.toId !== ownId)
-      .map((link) => ({ fromId: ownId, toId: link.toId, type: link.type }))
-  const changedSince = (id: string, path: string): boolean => (captured.has(id) || Boolean(operationKey)) && captured.get(id) !== fileHash(path)
-
-  for (const proposal of proposals.pages) {
-    const pageId = store.slug(proposal.id ?? proposal.title)
-    const current = existing.find((page) => page.frontmatter.id === pageId)
-    const namespace = current?.location.namespace ?? proposal.namespace ?? defaultNamespace
-    const payload = { kind: 'page', namespace, proposal, trigger: described }
-    const label = `Page "${proposal.title}"`
-    const blocked = `Proposed page "${proposal.title}" was not applied`
-
-    if (!(PAGE_TYPES as readonly string[]).includes(proposal.type) || !proposal.title.trim() || !proposal.body.trim()) {
-      park('blocked', blocked, label, 'The proposal was incomplete (type, title, or body).', proposal.body, pageId, payload)
-      continue
-    }
-    if (looksSecret(proposal.body) || looksSecret(proposal.title)) {
-      // Never stored, not even in the Inbox payload.
-      outcome.parked += 1
-      outcome.notes.push(`Page "${proposal.title}" was rejected: it contains text that looks like a credential.`)
-      inbox(wiki, 'blocked', blocked, 'The proposal contained text that looks like a credential, so it was not written.', [pageId])
-      continue
-    }
-    let targetDir: string | null = null
-    if (!current) {
-      try {
-        targetDir = store.namespaceDir(wiki, namespace)
-      } catch (error) {
-        park('blocked', blocked, label, error instanceof Error ? error.message : String(error), proposal.body, pageId, payload)
-        continue
-      }
-    }
-    // Consolidating a run never creates a page: one run is an episode, not an entity.
-    if (!current && (trigger.kind === 'run' || trigger.kind === 'consolidate')) {
-      park('unresolved', `"${proposal.title}" would be a new page`, label, 'Sleep-time consolidation updates existing pages only. Accept this to create the page.', proposal.body, pageId, payload)
-      continue
-    }
-    const found = evidenceFor(proposal.sourceRefs)
-    if (!found.length) {
-      park('unresolved', `"${proposal.title}" has no verifiable evidence`, label, 'The proposal quotes nothing the host could find in its source or run, so it was not written.', proposal.body, pageId, payload)
-      continue
-    }
-    if (proposal.confidence === 'low' && !fromUser) {
-      park('unresolved', `"${proposal.title}" is low confidence`, label, 'Low-confidence proposals wait for review.', proposal.body, pageId, payload)
-      continue
-    }
-    // An entry edited while the job ran is never overwritten.
-    if (current && changedSince(pageId, current.path)) {
-      park('blocked', blocked, label, 'The page changed while the update was running, so the proposal was parked instead of overwriting the edit.', proposal.body, pageId, payload)
-      continue
-    }
-
-    const links = filterLinks(proposal.links, pageId)
-    const contradicted = links.filter((link) => link.type === 'contradicts')
-    if (contradicted.length) {
-      inbox(wiki, 'unresolved', `"${proposal.title}" contradicts another entry`, 'The page was written with an explicit contradicts link. Review both claims and their sources.', [pageId, ...contradicted.map((link) => link.toId)])
-      outcome.flagged += 1
-    }
-    const sourceList = current ? [...current.frontmatter.sourceIds] : []
-    for (const id of found) if (!sourceList.includes(id)) sourceList.push(id)
-    const front = { id: pageId, title: proposal.title.trim(), type: proposal.type, updatedAt: now(), sourceIds: sourceList, links }
-    const path = current?.path ?? join(targetDir!, `${pageId}.md`)
-    outcome.notes.push(`Page "${proposal.title}" (${pageId}) ${current ? 'updated' : 'created'} in ${namespace}.`)
-    writes.push({ entryId: pageId, oldText: current ? readOrNull(current.path) : null, newText: store.serializePage(front, proposal.body), path })
-  }
-
-  const projectDefault = store.projectNamespaceOf(defaultNamespace) ?? store.ROOT_NAMESPACE
-  for (const proposal of proposals.memories) {
-    const memoryId = store.slug(proposal.id ?? proposal.title)
-    const current = existingMemories.find((memory) => memory.front.id === memoryId)
-    const payload = { kind: 'memory', proposal, trigger: described }
-    const label = `Fact "${proposal.title}"`
-    const title = `Fact "${proposal.title}" needs review`
-    if (looksSecret(proposal.body) || looksSecret(proposal.title)) {
-      outcome.parked += 1
-      outcome.notes.push(`Fact "${proposal.title}" was rejected: it contains text that looks like a credential.`)
-      inbox(wiki, 'blocked', `Fact "${proposal.title}" was not saved`, 'The proposal contained text that looks like a credential, so it was not written.', [])
-      continue
-    }
-    const front: facts.MemoryFront = {
-      id: memoryId,
-      title: proposal.title.trim(),
-      kind: proposal.kind,
-      namespace: current?.front.namespace ?? proposal.namespace ?? projectDefault,
-      sourceIds: current ? [...current.front.sourceIds] : [],
-      confidence: proposal.confidence ?? 'medium',
-      status: 'active',
-      supersedes: proposal.supersedes && existingMemories.some((memory) => memory.front.id === proposal.supersedes) ? proposal.supersedes : null,
-      links: filterLinks(proposal.links, memoryId),
-      createdAt: current?.front.createdAt || now(),
-      updatedAt: now(),
-      observedAt: now(),
-      volatile: proposal.volatile ?? current?.front.volatile ?? false
-    }
-    const problem = facts.validate(front, proposal.body)
-    if (problem) {
-      park('blocked', title, label, problem, proposal.body, memoryId, payload)
-      continue
-    }
-    const found = evidenceFor(proposal.sourceRefs)
-    if (!found.length) {
-      park('unresolved', title, label, 'The fact quotes nothing the host could find in its source or run, so it was not saved.', proposal.body, memoryId, payload)
-      continue
-    }
-    if (front.confidence === 'low' && !fromUser) {
-      park('unresolved', title, label, 'Low-confidence facts wait for review.', proposal.body, memoryId, payload)
-      continue
-    }
-    if (current && changedSince(memoryId, current.path)) {
-      park('blocked', title, label, 'The fact changed while the update was running, so the proposal was parked.', proposal.body, memoryId, payload)
-      continue
-    }
-    for (const id of found) if (!front.sourceIds.includes(id)) front.sourceIds.push(id)
-    // A superseding fact retires the one it replaces in the same operation.
-    const old = front.supersedes ? existingMemories.find((memory) => memory.front.id === front.supersedes) : undefined
-    if (old) {
-      writes.push({ entryId: old.front.id, path: old.path, oldText: readOrNull(old.path), newText: facts.serialize({ ...old.front, status: 'superseded', updatedAt: now() }, old.body) })
-    }
-    const path = current?.path ?? facts.pathFor(wiki, memoryId)
-    outcome.notes.push(`Fact "${proposal.title}" (${memoryId}) ${current ? 'updated' : 'saved'}.`)
-    writes.push({ entryId: memoryId, oldText: current ? readOrNull(current.path) : null, newText: facts.serialize(front, proposal.body), path })
-  }
-
-  const attachedBlocks = evidence.blocks ?? []
-  for (const proposal of proposals.blocks) {
-    const refuse = (reason: string): void => {
-      outcome.parked += 1
-      outcome.notes.push(`Block ${proposal.block} was not rewritten: ${reason}`)
-      inbox(wiki, 'unresolved', `A rewrite of ${proposal.block} was not applied`, `${reason}\n\n${takeChars(proposal.body, 600)}`, [proposal.block])
-    }
-    let block: blocks.Block
-    try {
-      block = blocks.find(wiki, proposal.block)
-    } catch {
-      refuse('there is no such memory block.')
-      continue
-    }
-    const body = proposal.body.trim()
-    if (!attachedBlocks.includes(block.id) || block.front.readOnly) {
-      refuse('the block is not attached to this run, or it is read-only.')
-      continue
-    }
-    const problem = blocks.check(block.front, body)
-    if (problem) {
-      refuse(problem)
-      continue
-    }
-    // A full block is only condensed: the rewrite must be shorter and add no evidence.
-    const grounded = trigger.kind === 'consolidate' ? body !== '' && charCount(body) < charCount(block.body) : evidenceFor(proposal.sourceRefs).length > 0
-    if (!grounded) {
-      refuse(trigger.kind === 'consolidate' ? 'a consolidated block must be shorter than it was.' : 'it quotes nothing the host could find in the run.')
-      continue
-    }
-    if (changedSince(block.id, block.path)) {
-      refuse('the block changed while the update was running.')
-      continue
-    }
-    if (body === block.body.trim()) continue
-    outcome.notes.push(`Block ${block.front.label} rewritten.`)
-    writes.push({ entryId: block.id, oldText: readOrNull(block.path), newText: blocks.serializeBlock({ ...block.front, updatedAt: now() }, body), path: block.path })
-  }
-
-  for (const flag of proposals.flags) {
-    inbox(wiki, flag.kind === 'contradiction' ? 'blocked' : 'unresolved', `Flagged claim: ${takeChars(flag.claim, 120)}`, `${flag.reason} (${flag.kind})`, [])
-    outcome.flagged += 1
-  }
-
-  if (!writes.length) {
-    store.log(wiki, `- ${now()} · ${actor} · ${described} · nothing changed · ${outcome.parked} parked · ${outcome.flagged} flagged`)
-    return outcome
-  }
-
-  // Apply everything or nothing: on any failure, restore what was already written.
-  writes.forEach((write, index) => {
-    try {
-      atomicWrite(write.path, write.newText)
-    } catch (error) {
-      for (const done of writes.slice(0, index)) {
-        try {
-          if (done.oldText === null) rmSync(done.path, { force: true })
-          else atomicWrite(done.path, done.oldText)
-        } catch {
-          // Best effort: the original failure is what the caller needs to see.
-        }
-      }
-      throw error
-    }
-  })
-
-  const operationId = operationKey ?? newId()
-  const short = operationId.slice(0, 8)
-  const pages: OperationPage[] = writes.map((write) => ({
-    pageId: write.entryId,
-    path: write.path,
-    beforeRevisionId: write.oldText === null ? null : store.snapshot(wiki, write.entryId, write.oldText, actor, `Before update ${short}`).id,
-    afterRevisionId: store.snapshot(wiki, write.entryId, write.newText, actor, `Update ${short} (${described})`).id
-  }))
-  const operation: Operation = { id: operationId, createdAt: now(), trigger: described, pages, undone: false }
-  writeJson(join(operationsDir(wiki), `${operationId}.json`), operation)
-  for (const write of writes) noteChange({ wiki, id: write.entryId, path: write.path, text: write.newText, actor, reason: described })
-  writeIndex(wiki)
-  store.log(
-    wiki,
-    `- ${now()} · ${actor} · ${described} · entries ${pages.map((page) => `\`${page.pageId}\``).join(', ')} · revisions ${pages.map((page) => `\`${page.afterRevisionId.slice(0, 8)}\``).join(', ')} · op \`${operationId}\` · ${outcome.parked} parked · ${outcome.flagged} flagged`
-  )
-  inbox(
-    wiki,
-    'applied',
-    `Updated ${pages.length} entr${pages.length === 1 ? 'y' : 'ies'}`,
-    `From ${described}. Undo restores the previous content as new revisions.`,
-    pages.map((page) => page.pageId),
-    operationId
-  )
-  outcome.operation = operation
-  return outcome
-}
-
-// ---- Registry proposals (skills, prompts, rules) -------------------------------------------
-
-export const registryProposalSchema = z.object({
-  /** `skill`, `prompt`, or `rule`. */
-  kind: z.string(),
-  name: z.string(),
-  description: z.string().default(''),
-  body: z.string(),
-  reason: z.string().default('')
-})
-export type RegistryProposal = z.infer<typeof registryProposalSchema>
-
-/**
- * Skills, prompts, and rules change how every agent behaves, so proposals never apply on
- * their own: they wait in the Inbox until the user accepts them.
- */
-export function parkRegistryProposal(wiki: string, trigger: Trigger, proposal: RegistryProposal): string {
-  if (!['skill', 'prompt', 'rule'].includes(proposal.kind) || !proposal.name.trim() || !proposal.body.trim()) {
-    throw invalid('A skill, prompt, or rule proposal needs a kind, name, and body.')
-  }
-  if (looksSecret(proposal.body)) throw invalid('The proposal contains text that looks like a credential.')
-  const id = `${proposal.kind}s/${store.slug(proposal.name)}`
-  inbox(
-    wiki,
-    'proposed',
-    `Proposed ${proposal.kind} "${proposal.name.trim()}"`,
-    `${proposal.reason.trim() || 'Review the change before it applies to every agent.'}\n\nFrom ${describeTrigger(trigger)}.`,
-    [id],
-    null,
-    { kind: proposal.kind, proposal, trigger: describeTrigger(trigger) }
-  )
-  store.log(wiki, `- ${now()} · ${triggerActor(trigger)} · proposed \`${id}\` · waiting in Inbox`)
-  return id
-}
-
-function parsed<T>(schema: z.ZodType<T>, value: unknown): T {
-  const result = schema.safeParse(value)
-  if (!result.success) throw new HarnessError('invalid_data', `Stored data could not be read: ${result.error.issues[0]?.message ?? 'invalid proposal'}`)
-  return result.data
-}
-
-/**
- * Accepts a parked proposal: pages and facts go through `apply` with the user as the
- * authority; registry items are written with a revision before and after.
- */
-export function accept(root: string, itemId: string): string {
-  const wiki = store.wikiDir(root)
-  const path = join(wiki, 'inbox', `${safeId(itemId)}.json`)
-  const item = readJson<InboxItem>(path)
-  if (!item) throw notFound('Inbox item')
-  const payload = item.payload as { kind?: unknown; proposal?: unknown; namespace?: unknown } | undefined | null
-  if (!payload) throw invalid('This Inbox item has nothing to accept.')
-  const kind = typeof payload.kind === 'string' ? payload.kind : ''
-  const trigger: Trigger = { kind: 'user', itemId: item.id }
-  const userRef: SourceRef = { kind: 'user', ref: 'accepted', excerpt: undefined }
-  let message: string
-  if (kind === 'page' || kind === 'memory') {
-    const set: ProposalSet = { pages: [], memories: [], blocks: [], flags: [] }
-    if (kind === 'page') {
-      const proposal = parsed(pageProposalSchema, payload.proposal)
-      set.pages.push({ ...proposal, sourceRefs: [...proposal.sourceRefs, userRef] })
-    } else {
-      const proposal = parsed(memoryProposalSchema, payload.proposal)
-      set.memories.push({ ...proposal, sourceRefs: [...proposal.sourceRefs, userRef] })
-    }
-    const namespace = typeof payload.namespace === 'string' ? payload.namespace : store.LIBRARY_NAMESPACE
-    const outcome = apply(wiki, namespace, trigger, set, new Map(), {})
-    if (!outcome.operation) throw invalid(outcome.notes.join(' '))
-    message = outcome.notes.join(' ')
-  } else if (kind === 'skill' || kind === 'prompt' || kind === 'rule') {
-    const proposal = parsed(registryProposalSchema, payload.proposal)
-    message = `Saved ${registry.writeItem(root, proposal.kind, proposal.name, proposal.description, proposal.body, `Accepted ${describeTrigger(trigger)}`)}.`
-  } else if (kind === 'plugin') {
-    message = acceptPluginProposal(root, parsed(pluginProposalSchema, payload.proposal))
-  } else {
-    throw invalid('Unknown proposal kind.')
-  }
-  const target = join(wiki, 'inbox', 'dismissed')
-  mkdirSync(target, { recursive: true })
-  renameSync(path, join(target, `${item.id}.json`))
-  return message
-}

package/src/memory/references.ts

@@ -1,77 +0,0 @@
-// 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}`
-}