@xingular/harness 0.0.0-stage → 0.1.0

package/src/memory/api.test.ts

@@ -0,0 +1,82 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { afterEach, expect, test } from 'vitest'
+
+import { dataRoot, writeFile } from '../../tests/helpers'
+import { createEnv, type HarnessEnv } from '../core/env'
+import { writeJson } from '../core/fs'
+import { closeIndex } from '../core/index'
+import { launchText } from '../prompt/compile'
+import { list, memories, memoryEdit, propose, read, search, skill } from './api'
+import * as blocks from './blocks'
+import type { CallerContext } from './caller'
+import { findMemory } from './facts'
+import { readRunContext } from './runContext'
+import { ensureProjectNamespace, wikiDir } from './store'
+import { reindexWiki } from './wikiIndex'
+
+const roots: string[] = []
+afterEach(() => roots.splice(0).forEach(closeIndex))
+
+function setup(): HarnessEnv {
+  const root = dataRoot()
+  roots.push(root)
+  writeJson(join(root, 'projects.json'), [
+    { id: 'p1', name: 'Xingular Agent', rootPath: '/src/xingular-agent', autoMaintenance: true, createdAt: 't', slug: 'xingular-agent' },
+    { id: 'p2', name: 'Site', rootPath: '/src/site', autoMaintenance: true, createdAt: 't', slug: 'site' }
+  ])
+  ensureProjectNamespace(root, 'xingular-agent', 'Xingular Agent')
+  ensureProjectNamespace(root, 'site', 'Site')
+  const wiki = wikiDir(root)
+  writeFileSync(join(wiki, 'projects/site/deploy.md'), '---\nid: deploy\ntitle: Deploying the site\ntype: decision\nsourceIds: [run:r0]\n---\n\nThe site deploys with wrangler.\n')
+  writeFileSync(join(wiki, 'facts/pnpm.md'), '---\nid: pnpm\ntitle: Use pnpm\nkind: preference\nnamespace: /\nconfidence: high\n---\n\nUse pnpm, not npm.\n')
+  writeFileSync(join(wiki, 'facts/site-only.md'), '---\nid: site-only\ntitle: Site uses Astro\nkind: fact\nnamespace: /projects/site\n---\n\nAstro.\n')
+  writeFile(join(root, 'registry/rules/tests.md'), '---\nname: Run tests\n---\n\nAlways run the tests.\n')
+  writeFile(join(root, 'registry/skills/review/SKILL.md'), '---\nname: review\ndescription: Review a change\n---\n\nRead the diff first.\n')
+  writeJson(join(root, 'config/registry-enabled.json'), { global: ['rules/tests'], p1: ['skills/review'] })
+  mkdirSync(join(root, 'runs/run-1'), { recursive: true })
+  writeJson(join(root, 'runs/run-1/run.json'), { id: 'run-1', projectId: 'p1', mode: 'code', harness: 'pi', sessionType: 'structured', sessionId: 's1', nativeSessionId: null, workingDirectory: null, worktreeId: null, goal: 'Please keep commits small from now on.', startedAt: 't', endedAt: null, status: 'running' })
+  reindexWiki(root)
+  return createEnv(root)
+}
+
+const context = (project: string): CallerContext => ({ runId: 'run-1', projectId: project, actor: 'Code' })
+
+test('sessions edit their project brief through memory calls', () => {
+  const env = setup()
+  expect(memoryEdit(env, context('p1'), 'memory.append', { block: 'project', text: 'Tauri 2 desktop app.' })).toContain('project/xingular-agent')
+  expect(launchText(env, context('p1'))).toContain('Tauri 2 desktop app.')
+  expect(() => memoryEdit(env, context('p1'), 'memory.append', { block: 'user', text: 'x' })).toThrow()
+  // A session reads its project's brief by id, but never an agent's blocks.
+  expect(read(env, context('p1'), { id: 'blocks/projects/xingular-agent/brief' })).toContain('Tauri 2 desktop app.')
+  blocks.ensureAgent(wikiDir(env.root), 'a1')
+  expect(() => read(env, context('p1'), { id: 'blocks/agents/a1/persona' })).toThrow()
+  expect(() => memoryEdit(env, { actor: 'Chat' }, 'memory.append', { block: 'user', text: 'x' })).toThrow()
+  expect(readRunContext(env.root, 'run-1').some((entry) => entry.id === 'blocks/projects/xingular-agent/brief' && entry.via === 'edit')).toBe(true)
+})
+
+test('agents read across project namespaces', () => {
+  const env = setup()
+  const hits = search(env, context('p1'), { query: 'wrangler' })
+  expect(hits).toContain('Deploying the site')
+  expect(hits).toContain('/projects/site/deploy')
+  const page = read(env, context('p1'), { id: '/projects/site/deploy' })
+  expect(page).toContain('The site deploys with wrangler.')
+  expect(page).toContain('Sources: run:r0')
+  expect(skill(env, context('p2'), { name: 'review' })).toContain('Read the diff first.')
+  expect(memories(env, context('p1'), { namespace: '/projects/site' })).toContain('Astro')
+  expect(list(env, {})).toContain('/projects/site')
+  expect(readRunContext(env.root, 'run-1').some((entry) => entry.id === 'deploy' && entry.via === 'read')).toBe(true)
+})
+
+test('proposals apply in the project namespace or wait in the inbox', () => {
+  const env = setup()
+  const applied = propose(env, context('p1'), { kind: 'memory', title: 'Small commits', type: 'preference', body: 'Keep commits small.', confidence: 'high', sourceRefs: [{ kind: 'run', ref: 'current', excerpt: 'please keep commits small' }] })
+  expect(applied).toContain('saved')
+  expect(findMemory(wikiDir(env.root), 'small-commits').front.namespace).toBe('/projects/xingular-agent')
+  expect(propose(env, context('p1'), { kind: 'page', title: 'Rumor', body: 'Maybe.' })).toContain('Inbox')
+  // The caller's own run without a quote from it is not evidence.
+  expect(propose(env, context('p1'), { kind: 'memory', title: 'Bare', body: 'Unquoted.', confidence: 'high', sourceRefs: [{ kind: 'run', ref: 'current' }] })).toContain('Inbox')
+  expect(propose(env, context('p1'), { kind: 'skill', title: 'Deploy', body: 'Steps.' })).toContain('waiting in the Wiki Inbox')
+  expect(existsSync(join(env.root, 'registry/skills/deploy'))).toBe(false)
+})

package/src/memory/api.ts

@@ -0,0 +1,287 @@
+// The Wiki as a model sees it: search, read, list, skills, facts, proposals, and memory-block
+// edits. Results are plain text with `[id@revision]` citations, and every entry a run reads is
+// recorded in `runs/<id>/wiki-context.json`.
+import { dirname } from 'node:path'
+
+import type { HarnessEnv } from '../core/env'
+import { HarnessError, invalid, notFound } from '../core/errors'
+import { charCount } from '../core/text'
+import { applicableMemories, clip } from '../prompt/compile'
+import { findRun, readEvents } from '../sessions/runStore'
+import type { RunEvent } from '../sessions/contracts'
+import { takeChars } from '../core/text'
+import * as registry from '../skills/registry'
+import * as blocks from './blocks'
+import { actorOf, blockCaller, projectOf, type CallerContext } from './caller'
+import * as facts from './facts'
+import { apply, captureHashes, parkRegistryProposal, parseProposalSet, type Trigger } from './proposals'
+import * as references from './references'
+import { cite, record, recordSources } from './runContext'
+import * as store from './store'
+import { backlinks, entryId, namespaces, registryEntryKind, resolveEntry, searchEntries } from './wiki'
+
+const READ_LIMIT = 20_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() : ''
+}
+
+const rawParam = (params: Params, key: string): string => (typeof params?.[key] === 'string' ? (params[key] as string) : '')
+const countParam = (params: Params, key: string): number | null => {
+  const value = params?.[key]
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0 ? value : null
+}
+
+// ---- Run evidence -------------------------------------------------------------------------------
+
+function transcriptText(goal: string, events: readonly RunEvent[]): string {
+  let text = `User: ${goal}\n`
+  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') text += `Assistant: ${typeof payload.text === 'string' ? payload.text : ''}\n`
+    else if (event.type === 'tool.started') text += `Tool ${typeof payload.name === 'string' ? payload.name : 'tool'}: ${typeof payload.summary === 'string' ? payload.summary : ''}\n`
+  }
+  return text
+}
+
+/** What a consolidation job reads of a run, capped. */
+export function transcript(goal: string, events: readonly RunEvent[]): string {
+  return takeChars(transcriptText(goal, events), 24_000)
+}
+
+/** Everything recorded of a run, uncapped: what an excerpt is checked against. */
+export function evidenceText(root: string, runId: string): string {
+  let events: RunEvent[] = []
+  try {
+    events = readEvents(root, runId)
+  } catch {
+    events = []
+  }
+  return transcriptText(findRun(root, runId)?.goal ?? '', events)
+}
+
+// ---- Memory blocks -----------------------------------------------------------------------
+
+/** `memory.append`, `memory.replace`, and `memory.rethink`. */
+export function memoryEdit(env: HarnessEnv, context: CallerContext, call: string, params: Params): string {
+  const caller = blockCaller(env, context)
+  const label = textParam(params, 'block')
+  if (!label) throw invalid('Name the block to edit, such as user, persona, or notes.')
+  let edit: blocks.Edit
+  if (call === 'memory.append') edit = { kind: 'append', text: rawParam(params, 'text') }
+  else if (call === 'memory.replace') edit = { kind: 'replace', old: rawParam(params, 'old'), new: rawParam(params, 'new') }
+  else if (call === 'memory.rethink') edit = { kind: 'rethink', text: rawParam(params, 'body') }
+  else throw new HarnessError('unknown_method', `Unknown memory call ${call}.`)
+  const block = blocks.edit(env.root, caller, label, edit)
+  record(env.root, context, 'edit', [[block.id, 'block']])
+  return `Updated the ${block.front.label} block (${charCount(block.body)} of ${block.front.limit} characters). It is in your context from the next turn.`
+}
+
+// ---- Retrieval ------------------------------------------------------------------------------
+
+function ownBlocksPrefix(env: HarnessEnv, context: CallerContext): string | null {
+  try {
+    const caller = blockCaller(env, context)
+    return caller.kind === 'agent' ? `blocks/agents/${caller.id}/` : null
+  } catch {
+    return null
+  }
+}
+
+/** A fact is stored and indexed under the kind `memory`. A model says `fact`; `memory` is still understood. */
+const storedKind = (kind: string): string => (kind === 'fact' ? 'memory' : kind)
+const shownKind = (kind: string): string => (kind === 'memory' ? 'fact' : kind)
+
+export function search(env: HarnessEnv, context: CallerContext, params: Params): string {
+  const { root } = env
+  const query = textParam(params, 'query')
+  if (!query) return 'Give a query.'
+  const kinds = (Array.isArray(params?.kinds) ? params.kinds.filter((kind): kind is string => typeof kind === 'string') : []).map(storedKind)
+  const limit = countParam(params, 'limit') ?? 8
+  // Another agent's blocks never appear; a block of the caller's own does.
+  const own = ownBlocksPrefix(env, context)
+  const hits = searchEntries(root, query, { kinds, namespace: textParam(params, 'namespace') || null, projectId: context.projectId, limit: limit + 6 })
+    .filter((hit) => !(hit.kind === 'block' && hit.type === 'agent') || (own !== null && hit.id.startsWith(own)))
+    .slice(0, limit)
+  if (!hits.length) return 'No matching Wiki entries.'
+  const wiki = store.wikiDir(root)
+  record(root, context, 'search', hits.map((hit) => [hit.id, hit.kind]))
+  return `${hits.map((hit, index) => `${index + 1}. [${shownKind(hit.kind)}] ${hit.title} — ${hit.path} ${cite(wiki, hit.id)}\n   ${hit.snippet}`).join('\n')}\n\nRead an entry with wiki_read and its id or path.`
+}
+
+export function read(env: HarnessEnv, context: CallerContext, params: Params): string {
+  const { root } = env
+  const key = textParam(params, 'id') || textParam(params, 'path') || textParam(params, 'idOrPath')
+  if (!key) throw invalid('Give an id or Wiki path.')
+  if (typeof params?.revision === 'string') {
+    const text = references.readPinned(root, context.runId, key, params.revision, countParam(params, 'offset') ?? 0)
+    recordSources(root, context, 'read', [{ id: key, kind: key.startsWith('skills/') ? 'skill' : 'page', revision: params.revision }])
+    return text
+  }
+  const wiki = store.wikiDir(root)
+  const entry = resolveEntry(root, key)
+  // An agent's own blocks are not readable by other agents or by sessions.
+  if (entry.kind === 'block' && entry.block.scope === 'agent') {
+    const own = ownBlocksPrefix(env, context)
+    if (own === null || `blocks/agents/${entry.block.owner}/` !== own) throw notFound('Wiki entry')
+  }
+  const linking = backlinks(root, entryId(entry))
+  const linked = linking.length ? linking.map((link) => `${link.fromId} (${link.type})`).join(', ') : 'none'
+  let kind: string
+  let text: string
+  if (entry.kind === 'page') {
+    const { frontmatter: front, location, body } = entry.page
+    kind = 'page'
+    text = `# ${front.title} ${cite(wiki, front.id)}\nPath: ${location.path} · namespace ${location.namespace} · type ${front.type} · updated ${front.updatedAt}\nSources: ${front.sourceIds.length ? front.sourceIds.join(', ') : 'none (unresolved)'}\nLinks: ${front.links.length ? front.links.map((link) => `${link.type} ${link.toId}`).join(', ') : 'none'}\nBacklinks: ${linked}\n\n${clip(body, READ_LIMIT)}`
+  } else if (entry.kind === 'memory') {
+    const { front, body } = entry.memory
+    kind = 'memory'
+    text = `# ${front.title} ${cite(wiki, front.id)}\nFact · ${front.kind} · namespace ${front.namespace} · ${front.confidence} confidence · ${front.status}${front.supersedes ? ` · supersedes ${front.supersedes}` : ''}\nSources: ${front.sourceIds.length ? front.sourceIds.join(', ') : 'none'}\nBacklinks: ${linked}\n\n${body}`
+  } else if (entry.kind === 'block') {
+    const { block } = entry
+    kind = 'block'
+    text = `# ${block.front.label} ${cite(wiki, block.id)}\nMemory block · ${block.scope} · ${charCount(block.body)} of ${block.front.limit} characters\n${block.front.description}\n\n${block.body}`
+  } else {
+    const { item } = entry
+    kind = registryEntryKind(item.kind) ?? 'skill'
+    text = `# ${item.name} ${cite(wiki, item.id)}\nRegistry ${item.id} · file ${item.path}\nBacklinks: ${linked}\n\n${clip(registry.itemBody(item), READ_LIMIT)}`
+  }
+  record(root, context, 'read', [[entryId(entry), kind]])
+  return text
+}
+
+export function list(env: HarnessEnv, params: Params): string {
+  const { root } = env
+  const namespace = textParam(params, 'namespace')
+  const kind = storedKind(textParam(params, 'kind'))
+  const wiki = store.wikiDir(root)
+  if (kind === 'memory') {
+    const memories = facts.loadMemories(wiki)
+    if (!memories.length) return 'No facts yet.'
+    return memories
+      .filter((memory) => !namespace || memory.front.namespace === namespace)
+      .map((memory) => `- ${memory.front.title} (${memory.front.id}) [${memory.front.kind}] ${memory.front.namespace} · ${memory.front.status}`)
+      .join('\n')
+  }
+  if (kind === 'skill' || kind === 'rule' || kind === 'prompt') {
+    const plural = `${kind}s`
+    const items = registry.list(root).filter((item) => item.kind === plural).map((item) => `- ${item.name} (${item.id}) — ${item.description}`)
+    return items.length ? items.join('\n') : `No ${plural} yet.`
+  }
+  let text = ''
+  if (!namespace) text += `Namespaces: / (Home), /library${namespaces(root).map((entry) => `, ${entry.namespace}`).join('')}\n\n`
+  const prefix = `${namespace.replace(/\/+$/, '')}/`
+  const pages = store
+    .loadPages(wiki)
+    .filter((page) => !namespace || page.location.namespace === namespace || page.location.path.startsWith(prefix))
+    .slice(0, 200)
+    .map((page) => `- ${page.location.path} — ${page.frontmatter.title} (${page.frontmatter.type}) [${page.frontmatter.id}]`)
+  return text + (pages.length ? pages.join('\n') : 'No pages here.')
+}
+
+/** One skill's instructions by name or id, or the skills index when no name is given. */
+export function skill(env: HarnessEnv, context: CallerContext, params: Params): string {
+  const { root } = env
+  const name = textParam(params, 'name').toLowerCase()
+  const items = registry.list(root).filter((item) => item.kind === 'skills')
+  if (!name) {
+    if (!items.length) return 'No skills yet.'
+    const active = registry.enabledFor(root, context.projectId ?? null, context.agentId ?? null).map((item) => item.id)
+    return items.map((item) => `- ${item.name} (${item.id})${active.includes(item.id) ? ' · active' : ''} — ${item.description}`).join('\n')
+  }
+  const found = items.find((item) => item.id.toLowerCase() === name || item.id.replace(/^skills\//, '').toLowerCase() === name || item.name.toLowerCase() === name)
+  if (!found) return `There is no skill called "${name}". Call skill_load without a name to list them.`
+  record(root, context, 'skill', [[found.id, 'skill']])
+  const folder = found.path.endsWith('SKILL.md') ? `\nSupporting files are in ${dirname(found.path)}.` : ''
+  return `# ${found.name} ${cite(store.wikiDir(root), found.id)}\n${found.description}${folder}\n\n${clip(registry.itemBody(found), READ_LIMIT)}`
+}
+
+/** ", volatile, observed 12 days ago" for a fact that describes current state. */
+export function volatileNote(front: facts.MemoryFront): string {
+  if (!front.volatile) return ''
+  const days = facts.ageDays(front)
+  return days === null ? ', volatile' : `, volatile, observed ${days} day${days === 1 ? '' : 's'} ago`
+}
+
+export function memories(env: HarnessEnv, context: CallerContext, params: Params): string {
+  const { root } = env
+  const wiki = store.wikiDir(root)
+  const query = textParam(params, 'query')
+  const namespace = textParam(params, 'namespace')
+  let selected: facts.ParsedMemory[]
+  if (!query) {
+    selected = applicableMemories(wiki, namespace || (projectOf(root, context)?.wikiNamespace ?? null))
+  } else {
+    selected = searchEntries(root, query, { kinds: ['memory'], namespace: namespace || null, projectId: context.projectId, limit: 20 }).flatMap((hit) => {
+      try {
+        return [facts.findMemory(wiki, hit.id)]
+      } catch {
+        return []
+      }
+    })
+  }
+  if (!selected.length) return 'No facts match.'
+  const shown = selected.slice(0, 30)
+  record(root, context, 'memory', shown.map((memory) => [memory.front.id, 'memory']))
+  return shown
+    .map((memory) => `- [${memory.front.kind}] ${memory.front.title} ${cite(wiki, memory.front.id)} (${memory.front.namespace}, ${memory.front.confidence} confidence${memory.front.status === 'active' ? '' : `, ${memory.front.status}`}${volatileNote(memory.front)})\n  ${memory.body.trim().replaceAll('\n', '\n  ')}`)
+    .join('\n')
+}
+
+// ---- Proposals -------------------------------------------------------------------------------
+
+function sourceRefs(params: Params, context: CallerContext): { kind: string; ref: string; excerpt?: string }[] {
+  if (!Array.isArray(params?.sourceRefs)) return []
+  return params.sourceRefs.flatMap((reference: { kind?: unknown; ref?: unknown; excerpt?: unknown } | null) => {
+    if (!reference || typeof reference.kind !== 'string') return []
+    const given = typeof reference.ref === 'string' ? reference.ref : ''
+    // "current" (or nothing) names the caller's own run.
+    const own = reference.kind === 'run' && (!given || given === 'current')
+    if (own && !context.runId) return []
+    return [{ kind: reference.kind, ref: own ? context.runId! : given, ...(typeof reference.excerpt === 'string' ? { excerpt: reference.excerpt } : {}) }]
+  })
+}
+
+/** A `links` argument: usable only when every entry names a target and a type. */
+function links(params: Params): { toId: string; type: string }[] {
+  const given = params?.links
+  if (!Array.isArray(given) || !given.every((link) => link && typeof link.toId === 'string' && typeof link.type === 'string')) return []
+  return given.map((link: { toId: string; type: string }) => ({ toId: link.toId, type: link.type }))
+}
+
+const optional = (params: Params, key: string): string | null => textParam(params, key) || null
+
+/** Validates and applies (or parks) one proposal. */
+export function propose(env: HarnessEnv, context: CallerContext, params: Params): string {
+  const { root } = env
+  const wiki = store.wikiDir(root)
+  const kind = storedKind(textParam(params, 'kind'))
+  const trigger: Trigger = { kind: 'agent', runId: context.runId ?? null, actor: actorOf(context) }
+  const defaultNamespace = projectOf(root, context)?.wikiNamespace ?? store.LIBRARY_NAMESPACE
+  const title = textParam(params, 'title')
+  const body = rawParam(params, 'body')
+  let proposals: unknown
+  if (kind === 'page') {
+    proposals = { pages: [{ id: optional(params, 'id'), title, type: optional(params, 'type') ?? 'concept', body, namespace: optional(params, 'namespace'), confidence: optional(params, 'confidence'), sourceRefs: sourceRefs(params, context), links: links(params) }] }
+  } else if (kind === 'memory') {
+    proposals = {
+      memories: [{ id: optional(params, 'id'), title, kind: optional(params, 'type') ?? 'fact', body, namespace: optional(params, 'namespace'), confidence: optional(params, 'confidence'), supersedes: optional(params, 'supersedes'), volatile: typeof params?.volatile === 'boolean' ? params.volatile : null, sourceRefs: sourceRefs(params, context), links: links(params) }]
+    }
+  } else if (kind === 'skill' || kind === 'rule' || kind === 'prompt') {
+    const id = parkRegistryProposal(wiki, trigger, { kind, name: optional(params, 'id') ?? title, description: textParam(params, 'description'), body, reason: textParam(params, 'reason') })
+    return `The ${kind} change (${id}) is waiting in the Wiki Inbox. Skills, prompts, and rules change only after the user accepts them.`
+  } else {
+    throw invalid('kind must be page, fact, skill, rule, or prompt.')
+  }
+  // The caller's own run is evidence only for what it can quote from it.
+  const outcome = apply(wiki, defaultNamespace, trigger, parseProposalSet(proposals), captureHashes(wiki), { runText: context.runId ? evidenceText(root, context.runId) : null })
+  let text = outcome.notes.join('\n')
+  if (outcome.operation) {
+    text += `\nApplied as operation ${outcome.operation.id.slice(0, 8)}; the user can undo it from the Wiki Inbox.`
+    record(root, context, 'edit', outcome.operation.pages.map((page) => [page.pageId, kind]))
+  }
+  return text
+}

package/src/memory/blocks.test.ts

@@ -0,0 +1,78 @@
+import { expect, test } from 'vitest'
+
+import { rootWithProject } from '../../tests/helpers'
+import { applyEdit, attached, DEFAULT_LIMIT, edit, PROJECT_LIMIT, render, saveAsUser, undoLast, type BlockInput, type Caller } from './blocks'
+import { readManifest, wikiDir } from './store'
+
+const agent = (id: string): Caller => ({ kind: 'agent', id, name: 'Nora' })
+const append = (text: string) => ({ kind: 'append' as const, text })
+
+test('edits apply with limits and exact replacement', () => {
+  expect(applyEdit('', append('Likes pnpm.'))).toBe('Likes pnpm.')
+  expect(applyEdit('A', append(' B '))).toBe('A\nB')
+  expect(applyEdit('Use npm.', { kind: 'replace', old: 'npm', new: 'pnpm' })).toBe('Use pnpm.')
+  expect(() => applyEdit('a a', { kind: 'replace', old: 'a', new: 'b' })).toThrow('2 times')
+  expect(() => applyEdit('a', { kind: 'replace', old: 'z', new: 'b' })).toThrow()
+  expect(() => applyEdit('a', append('  '))).toThrow()
+  expect(applyEdit('old', { kind: 'rethink', text: ' new ' })).toBe('new')
+})
+
+test('an agent gets its blocks, the user block and work project briefs', () => {
+  const root = rootWithProject()
+  const blocks = attached(root, agent('a1'), ['app', 'missing'])
+  expect(blocks.map((block) => block.front.label)).toEqual(['persona', 'notes', 'user', 'project/app'])
+  expect(blocks[0].id).toBe('blocks/agents/a1/persona')
+  expect(blocks[3].front.limit).toBe(PROJECT_LIMIT)
+  expect(attached(root, { kind: 'session', projectSlug: 'app' }, []).map((block) => block.front.label)).toEqual(['user', 'project/app'])
+})
+
+test('edits are revisioned, limited and undoable', () => {
+  const root = rootWithProject()
+  const wiki = wikiDir(root)
+  const nora = agent('a1')
+  expect(edit(root, nora, 'user', append('Prefers short answers.')).body).toBe('Prefers short answers.')
+  const revisions = readManifest(wiki, 'blocks/shared/user')
+  expect(revisions).toHaveLength(2)
+  expect(revisions[1].actor).toBe('Nora')
+  edit(root, nora, 'user', append('Works in Bangkok time.'))
+  expect(readManifest(wiki, 'blocks/shared/user')).toHaveLength(3)
+  expect(undoLast(wiki, 'blocks/shared/user').body).toBe('Prefers short answers.')
+  expect(undoLast(wiki, 'blocks/shared/user').body).toBe('')
+  expect(() => undoLast(wiki, 'blocks/shared/user')).toThrow()
+
+  expect(() => edit(root, nora, 'notes', { kind: 'rethink', text: 'x'.repeat(DEFAULT_LIMIT + 1) })).toThrow('memory_rethink')
+  expect(() => edit(root, nora, 'notes', append('key sk-ant-abc'))).toThrow('credential')
+  expect(() => edit(root, nora, 'nope', append('x'))).toThrow()
+})
+
+test('sessions edit only their project brief', () => {
+  const root = rootWithProject()
+  const session: Caller = { kind: 'session', projectSlug: 'app' }
+  expect(edit(root, session, 'project', append('Tauri 2 app.')).id).toBe('blocks/projects/app/brief')
+  expect(() => edit(root, session, 'user', append('x'))).toThrow('cannot edit')
+  expect(() => edit(root, session, 'persona', append('x'))).toThrow()
+  attached(root, agent('a1'), [])
+  expect(() => edit(root, session, 'blocks/agents/a1/persona', append('x'))).toThrow()
+  expect(() => edit(root, { kind: 'session', projectSlug: null }, 'project/app', append('x'))).toThrow()
+  // An agent may edit any project's brief, and its own blocks, but not another agent's.
+  expect(edit(root, agent('a1'), 'project/app', append('Uses pnpm.')).body).toContain('Uses pnpm.')
+  expect(() => edit(root, agent('a2'), 'blocks/agents/a1/persona', append('x'))).toThrow()
+})
+
+test('the user creates and restricts shared blocks', () => {
+  const root = rootWithProject()
+  const wiki = wikiDir(root)
+  const input = (id: string | null, label: string | null, agents: string[], readOnly: boolean): BlockInput => ({ id, label, body: 'We ship on Fridays.', description: 'Team habits.', limit: 500, readOnly, agents })
+  const created = saveAsUser(wiki, input(null, 'Team habits', ['a1'], false))
+  expect(created.id).toBe('blocks/shared/team-habits')
+  expect(() => saveAsUser(wiki, input(null, 'Team habits', [], false))).toThrow()
+  expect(() => saveAsUser(wiki, input(null, 'user', [], false))).toThrow()
+  expect(attached(root, agent('a1'), []).some((block) => block.id === created.id)).toBe(true)
+  expect(attached(root, agent('a2'), []).some((block) => block.id === created.id)).toBe(false)
+  expect(() => edit(root, agent('a2'), 'team-habits', append('x'))).toThrow()
+  saveAsUser(wiki, input(created.id, null, [], true))
+  expect(() => edit(root, agent('a1'), 'team-habits', append('x'))).toThrow('read-only')
+  const rendered = render(attached(root, agent('a1'), []), agent('a1'), false)
+  expect(rendered).toContain('<block label="team-habits" chars="19/500" read-only="true">')
+  expect(rendered).toContain('<block label="persona" chars="0/2000">')
+})