@xingular/harness 2.1.2 → 3.0.0

package/src/prompt/compile.test.ts

@@ -3,17 +3,16 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, expect, test } from 'vitest'
 
-import { dataRoot, writeFile } from '../../tests/helpers'
+import { dataRoot } from '../../tests/helpers'
+import type { CallerContext } from '../core/caller'
 import { createEnv, type HarnessEnv } from '../core/env'
 import { writeJson } from '../core/fs'
 import { closeIndex } from '../core/index'
-import * as blocks from '../memory/blocks'
-import type { CallerContext } from '../memory/caller'
-import * as references from '../memory/references'
-import { readRunContext } from '../memory/runContext'
-import { ensureProjectNamespace, wikiDir } from '../memory/store'
-import { reindexWiki } from '../memory/wikiIndex'
-import { compile, fit, launchText, load, memoryDelta, profileFor, profiles, record, REFERENCES_BUDGET, render, saveForSession, sessionFile, sessionLaunch, setProfile, type ContextPack, type ContextUpdate, type HostSection, type Launch } from './compile'
+import { materialise } from '../tree/materialise'
+import * as store from '../tree/store'
+import type { Tree } from '../tree/surface'
+import * as notes from '../wiki/notes'
+import { compile, fit, load, render, sessionFile, sessionLaunch, SECTION_ORDER, type ContextUpdate, type HostSection, type Launch } from './compile'
 
 const roots: string[] = []
 afterEach(() => roots.splice(0).forEach(closeIndex))
@@ -21,33 +20,33 @@ 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')
-  const wiki = wikiDir(root)
-  writeFileSync(join(wiki, 'projects/xingular-agent/decisions.md'), '---\nid: decisions\ntitle: Decisions\ntype: decision\n---\n\nTauri 2 for the shell.\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/on-call.md'), '---\nid: on-call\ntitle: On call this week\nkind: fact\nnamespace: /\nconfidence: high\nvolatile: true\n---\n\nAstro team is on call.\n')
-  writeFileSync(join(wiki, 'facts/site-only.md'), '---\nid: site-only\ntitle: Site uses Astro\nkind: fact\nnamespace: /projects/site\n---\n\nAstro renders the site.\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'] })
+  writeJson(join(root, 'projects.json'), [{ id: 'p1', name: 'Xingular Agent', rootPath: '/src/xingular-agent', autoMaintenance: true, createdAt: 't', slug: 'xingular-agent' }])
+  notes.ensureLayout(root, 'Test')
+  notes.write(root, 'projects/xingular-agent/decisions', '---\ntitle: Decisions\n---\n\nTauri 2 for the shell. See [[library/glossary]].\n')
+  notes.write(root, 'library/glossary', '# Glossary\n\nA harness is the system around a model.\n')
   mkdirSync(join(root, 'runs/run-1'), { recursive: true })
-  reindexWiki(root)
   return createEnv(root)
 }
 
-const session = (project: string): CallerContext => ({ runId: 'run-1', sessionId: 's1', projectId: project, actor: 'Code' })
-const agent = (extra: Partial<CallerContext> = {}): CallerContext => ({ agentId: 'nora', agentName: 'Nora', actor: 'Chat', ...extra })
-const ids = (pack: ContextPack): string[] => pack.sections.map((entry) => entry.id)
+const tree: Tree = {
+  'systemprompt.md': 'You draft release notes.\n',
+  'guardrails.md': 'Never publish without a review.\n- When writing a changelog, load the `changelog` skill.\n',
+  'memory.md': 'Releases ship on Tuesdays.\n',
+  'tool_guidance.md': 'Prefer grep over reading whole files.\n',
+  'skills/changelog/SKILL.md': '---\nname: changelog\ndescription: writing a changelog\n---\nGroup by type.\n',
+  'sub_agents/reader/AGENT.md': '---\ndescription: reads long logs and answers briefly\n---\nRead the log and answer in three lines.\n',
+  'scripts/count.py': 'print(1)\n'
+}
+
+const agent = (extra: Partial<CallerContext> = {}): CallerContext => ({ agentId: 'nora', agentName: 'Nora', projectId: 'p1', runId: 'run-1', actor: 'Chat', ...extra })
+const identity: HostSection = { id: 'identity', title: 'Identity', body: 'You are Nora.', budget: 1000, order: 10 }
+const work = (body: string): HostSection => ({ id: 'work', title: 'Active work', body, budget: 1000, order: 70, dynamic: true })
+const hosted = (extra: Partial<Launch> = {}): Launch => ({ sections: [identity, work('You have no unresolved work.')], tools: ['read'], ...extra })
 
-// What an application supplies: who the model is, its role, and what it is working on.
-const identity: HostSection = { id: 'identity', title: 'Identity', body: 'You are "Nora", an Xingular Agent agent.', budget: 6000, order: 10 }
-const role: HostSection = { id: 'role', title: 'Role', body: 'You coordinate.', budget: 1500, order: 20 }
-const work = (body: string | null, pinned?: string): HostSection => ({ id: 'work', title: 'Active work', body, budget: 1500, pointer: '(Call list_work for the full inventory.)', order: 70, dynamic: true, pinned: pinned ? { text: pinned, pointer: '(Call list_work for the full evidence.)' } : null })
-const hosted = (extra: Partial<Launch> = {}): Launch => ({ sections: [identity, role, work('You have no unresolved work.\n')], ...extra })
+function scoped(env: HarnessEnv) {
+  store.seed(env.root, 'nora', tree)
+  return materialise(env.root, { scope: 'nora' }, { subagents: true })
+}
 
 test('cuts at a paragraph and points to the rest', () => {
   expect(fit('short', 100, '(more)')).toEqual({ body: 'short', cut: false })
@@ -56,126 +55,46 @@ test('cuts at a paragraph and points to the rest', () => {
   expect(cut.body).toBe(`${'a'.repeat(40)}\n\n${'b'.repeat(40)}\n\n(more)`)
 })
 
-test('selected content is pinned and retained with automatic context off', () => {
-  const env = setup()
-  setProfile(env.root, 'nora', 'off')
-  const revision = references.pin(env.root, 'skill', 'skills/review')
-  writeFileSync(join(env.root, 'registry/skills/review/SKILL.md'), 'Changed instructions.')
-  const newer = references.pin(env.root, 'skill', 'skills/review')
-  const caller = agent({ runId: 'run-1' })
-  const pack = compile(env, caller, hosted({ references: [{ kind: 'skill', id: 'skills/review', label: 'Review', revision }] }))
-  expect(ids(pack)).toEqual(['identity', 'role', 'references'])
-  const selected = pack.sections.find((entry) => entry.id === 'references')!
-  expect(selected.body).toContain('Read the diff first.')
-  expect(selected.body).not.toContain('Changed instructions.')
-  expect(revision).not.toBe(newer)
-  record(env.root, caller, pack)
-  expect(references.readPinned(env.root, 'run-1', 'skills/review', revision, 0)).toContain('Read the diff first.')
-  expect(() => references.readPinned(env.root, 'run-1', 'skills/review', newer, 0)).toThrow()
-  expect(readRunContext(env.root, 'run-1')[0].revisionId).toBe(revision)
-})
-
-test('application lines sit with the references and large sources keep retrieval pointers', () => {
+test('the harness tree supplies the instructions, guardrails, memory, subagents, scripts and tool guidance, in order', () => {
   const env = setup()
-  writeFileSync(join(env.root, 'registry/skills/review/SKILL.md'), 'Review instructions.\n\n'.repeat(2000))
-  const revision = references.pin(env.root, 'skill', 'skills/review')
-  const pack = compile(env, agent(), { references: [{ kind: 'skill', id: 'skills/review', label: 'Review', revision }, { kind: 'line', id: 'exact-agent-id', label: 'Duplicate name', text: '- Agent "Duplicate name": exact ID "exact-agent-id". Agent messaging is unavailable in this reply.' }] })
-  const selected = pack.sections.find((entry) => entry.id === 'references')!
-  expect(selected.body).toContain('Agent messaging is unavailable')
-  expect(selected.cut).toBe(true)
-  expect(selected.size).toBeLessThanOrEqual(REFERENCES_BUDGET)
-  expect(selected.body).toContain('wiki_read(id="skills/review", revision=')
-  expect(selected.sources[0].revision).toBe(revision)
-})
-
-test('a session gets blocks, rules, skills, knowledge and tools', () => {
-  const env = setup()
-  const pack = compile(env, session('p1'), { connections: 'Use get_capabilities.' })
-  expect(pack.profile).toBe('session')
-  expect(ids(pack)).toEqual(['blocks', 'rules', 'skills', 'knowledge', 'tools'])
+  const pack = compile(env, agent(), hosted(), scoped(env))
+  const ids = pack.sections.map((entry) => entry.id)
+  expect(ids).toEqual(['identity', 'system', 'guardrails', 'memory', 'subagents', 'scripts', 'work', 'wiki', 'tools'])
   const text = render(env, pack)
-  for (const expected of ['<block label="user"', '<block label="project/xingular-agent"', 'Always run the tests.', 'review (skills/review)', '/projects/xingular-agent/decisions — Decisions', 'Use pnpm', 'App tools and connected apps: Use get_capabilities.']) expect(text).toContain(expected)
-  expect(text).not.toContain('Astro')
-  const cli = render(env, compile(env, { ...session('p1'), surface: 'cli' }))
-  expect(cli).toContain('xagent-wiki search')
-  expect(cli).toContain('xagent-wiki block append')
+  expect(text).toContain('You draft release notes.')
+  expect(text).toContain('Never publish without a review.')
+  expect(text).toContain('Releases ship on Tuesdays.')
+  expect(text).toContain('- reader — reads long logs and answers briefly')
+  expect(text).toMatch(/scripts: count\.py/)
+  expect(text).toContain('### How to use your tools\n\nPrefer grep over reading whole files.')
+  expect(pack.harness).toEqual({ scope: 'nora', fingerprint: store.head(env.root, 'nora')!.fingerprint })
+  expect(pack.sections.find((entry) => entry.id === 'system')!.sources).toEqual([{ id: 'nora', kind: 'harness', revision: pack.harness!.fingerprint }])
 })
 
-test('long rules shorten only the rules section', () => {
+test('without a tree, only the application, the Wiki and the tools speak', () => {
   const env = setup()
-  writeFileSync(join(env.root, 'registry/rules/tests.md'), `---\nname: Run tests\n---\n\n${'Always run the tests.\n\n'.repeat(600)}\n`)
-  const pack = compile(env, session('p1'))
-  const rules = pack.sections.find((entry) => entry.id === 'rules')!
-  expect(rules.cut && rules.size <= 3000 && rules.body.endsWith('wiki_list kind rule.)')).toBe(true)
-  expect(ids(pack)).toEqual(['blocks', 'rules', 'skills', 'knowledge', 'tools'])
-  expect(pack.sections.filter((entry) => entry.id !== 'rules').every((entry) => !entry.cut)).toBe(true)
+  const pack = compile(env, agent(), hosted())
+  expect(pack.sections.map((entry) => entry.id)).toEqual(['identity', 'work', 'wiki', 'tools'])
+  expect(pack.harness).toBeNull()
 })
 
-test('an agent gets the application sections, its blocks and the tool groups in order', () => {
+test('the Wiki section lists the current project\'s notes and only describes wiki_write when it is on', () => {
   const env = setup()
-  const pack = compile(env, agent({ runId: 'run-1' }), hosted({
-    input: 'How does Astro render the site?',
-    tools: ['dispatch_work', 'list_agents', 'read'],
-    toolGroups: [
-      { group: 'Work', tools: ['dispatch_work'], guidance: 'Work (dispatch_work): record and dispatch substantial tasks.', order: 30 },
-      { group: 'Agents', tools: ['list_agents', 'get_agent'], guidance: 'Agents (list_agents, get_agent): see and message the other agents.', order: 40 },
-      { group: 'Browser', tools: [], guidance: 'Browser: act in the managed browser.', order: 50 },
-      { group: 'Files', tools: ['files_list', 'files_read'], guidance: 'Saved files (files_list, files_read): read the shared vault.', order: 80 }
-    ]
-  }))
-  expect(pack.toolGroups.map((group) => group.group)).toEqual(['Memory', 'Knowledge', 'Work', 'Agents', 'Native', 'Files'])
-  expect(pack.toolGroups[3].tools).toEqual(['list_agents', 'get_agent'])
-  const tools = pack.sections.at(-1)!.body
-  expect(tools).toContain('Work (dispatch_work)')
-  expect(tools).toContain('Files (read)')
-  expect(tools).not.toContain('Browser')
-  expect(tools).not.toContain('connected apps')
-  expect(pack.profile).toBe('agent')
-  expect(ids(pack)).toEqual(['identity', 'role', 'blocks', 'rules', 'skills', 'work', 'knowledge', 'tools'])
-  const text = render(env, pack)
-  for (const expected of ['# Xingular Harness context\n\nYou are "Nora", an Xingular Agent agent.\n\n## Role', '<block label="persona"', '<block label="notes"', 'You have no unresolved work.', '- /projects/xingular-agent', 'Site uses Astro']) expect(text).toContain(expected)
-  // A volatile fact is never carried, even when it matches.
-  expect(text).not.toContain('On call this week')
-  // A skill enabled for one project is not listed for an agent, only pointed to.
-  expect(text).not.toContain('review (skills/review)')
+  const text = render(env, compile(env, agent(), hosted()))
+  expect(text).toContain('- projects/xingular-agent/decisions — Decisions')
+  expect(text).toContain('wiki_search, wiki_read and wiki_list read project notes.')
+  expect(text).not.toContain('wiki_write')
+  expect(render(env, compile(env, agent(), hosted({ tools: ['read', 'wiki_write'] })))).toContain('wiki_write saves one')
 })
 
-test('a running session is told once when a block changes', () => {
+test('selected notes are references for this request only', () => {
   const env = setup()
-  const directory = mkdtempSync(join(tmpdir(), 'harness-session-'))
-  saveForSession(directory, compile(env, session('p1')))
-  expect(memoryDelta(env, directory, session('p1'))).toBeNull()
-  blocks.edit(env.root, { kind: 'user' }, 'project/xingular-agent', { kind: 'append', text: 'Uses pnpm.' })
-  const note = memoryDelta(env, directory, session('p1'))!
-  expect(note.startsWith('[Memory updated since')).toBe(true)
-  expect(note).toContain('<block label="project/xingular-agent"')
-  expect(note).toContain('Uses pnpm.')
-  expect(note).not.toContain('<block label="user"')
-  expect(memoryDelta(env, directory, session('p1'))).toBeNull()
-})
-
-test('a profile limits the sections and is recorded', () => {
-  const env = setup()
-  expect(profileFor(env.root, session('p1'))).toBe('full')
-  setProfile(env.root, 's1', 'minimal')
-  const pack = compile(env, session('p1'))
-  expect([pack.contextProfile, ids(pack)]).toEqual(['minimal', ['rules', 'tools']])
-  setProfile(env.root, 's1', 'off')
-  const off = compile(env, session('p1'))
-  expect([off.sections, off.toolGroups]).toEqual([[], []])
-  setProfile(env.root, 's1', 'full')
-  expect(profiles(env.root)).toEqual({})
-  expect(() => setProfile(env.root, '../x', 'off')).toThrow()
-})
-
-test('the pack is recorded with the run', () => {
-  const env = setup()
-  const text = launchText(env, session('p1'))
-  const saved = load(env.root, 'run-1')!
-  expect(render(env, saved)).toBe(text)
-  expect(saved.sections.some((entry) => entry.id === 'blocks' && entry.sources.some((source) => source.id === 'blocks/shared/user'))).toBe(true)
-  expect(readRunContext(env.root, 'run-1').some((entry) => entry.id === 'rules/tests' && entry.via === 'entrypoint')).toBe(true)
-  expect(load(env.root, 'missing')).toBeNull()
+  const launch = hosted({ references: [{ kind: 'note', path: 'library/glossary' }, { kind: 'line', id: 'l1', label: 'Line', text: 'The user pinned a screenshot.' }] })
+  const section = compile(env, agent(), launch).sections.find((entry) => entry.id === 'references')!
+  expect(section.body).toContain('The user pinned a screenshot.')
+  expect(section.body).toContain('A harness is the system around a model.')
+  expect(section.sources[0]).toMatchObject({ id: 'library/glossary', kind: 'note' })
+  expect(SECTION_ORDER.references).toBeLessThan(SECTION_ORDER.wiki)
 })
 
 function delivered(path: string, update: ContextUpdate): void {
@@ -184,64 +103,28 @@ function delivered(path: string, update: ContextUpdate): void {
 
 test('state stays out of the system prompt and only delivered changes are resent', () => {
   const env = setup()
-  const caller = agent({ runId: 'run-1' })
-  const first = sessionLaunch(env, caller, hosted(), null)
-  const initial = first.update!
-  expect(first.system).not.toContain('<block')
+  const materialised = scoped(env)
+  const first = sessionLaunch(env, agent(), hosted(), null, materialised)
+  expect(first.system).toContain('You draft release notes.')
   expect(first.system).not.toContain('You have no unresolved work.')
-  expect(first.system.endsWith('through tools when needed.\n')).toBe(true)
-  expect(initial.content).toContain('<block')
-  expect(initial.content).toContain('You have no unresolved work.')
-  // Recording a prepared launch is not evidence that the session received its context.
-  expect(sessionLaunch(env, caller, hosted(), null).update).not.toBeNull()
+  expect(first.update!.content).toContain('You have no unresolved work.')
+  expect(first.update!.content).toContain('## Wiki')
   const history = join(mkdtempSync(join(tmpdir(), 'harness-history-')), 'chat.jsonl')
-  delivered(history, initial)
-  const unchanged = sessionLaunch(env, caller, hosted(), history)
+  delivered(history, first.update!)
+  const unchanged = sessionLaunch(env, agent(), hosted(), history, materialised)
   expect(unchanged.system).toBe(first.system)
   expect(unchanged.update).toBeNull()
-  blocks.edit(env.root, { kind: 'user' }, 'user', { kind: 'append', text: 'New shared preference.' })
-  const changed = sessionLaunch(env, caller, hosted(), history)
+  notes.write(env.root, 'projects/xingular-agent/release', '# Release checklist\n')
+  const changed = sessionLaunch(env, agent(), hosted(), history, materialised)
   expect(changed.system).toBe(first.system)
-  expect(changed.update!.content).toContain('New shared preference.')
+  expect(changed.update!.content).toContain('projects/xingular-agent/release')
   expect(changed.update!.content).not.toContain('## Active work')
-  expect(changed.update!.content).not.toContain('## Knowledge')
-  expect(load(env.root, 'run-1')!.delivery!.updatedSectionIds).toEqual(['blocks'])
-  writeFileSync(join(env.root, 'registry/rules/tests.md'), '---\nname: Run tests\n---\n\nFollow the updated rule.\n')
-  const updated = sessionLaunch(env, caller, hosted(), history).system
-  expect(updated).not.toBe(first.system)
-  expect(updated).toContain('Follow the updated rule.')
-})
-
-test('pinned application text reaches native history with context off without changing the system prefix', () => {
-  const env = setup()
-  setProfile(env.root, 'nora', 'off')
-  const before = sessionLaunch(env, agent(), hosted(), null)
-  const after = sessionLaunch(env, agent(), { sections: [identity, role, work('You have no unresolved work.\n', 'Recent task reports:\n\nTask t1: Reviewed evidence shown to the user\n')] }, null)
-  expect(after.system).toBe(before.system)
-  expect(after.update!.content).toContain('Reviewed evidence shown to the user')
-  expect(after.update!.content).not.toContain('You have no unresolved work.')
-  expect(before.update!.content).not.toContain('Reviewed evidence')
-})
-
-test('references apply to each request and profile changes withdraw old state', () => {
-  const env = setup()
-  const revision = references.pin(env.root, 'skill', 'skills/review')
-  const launch = hosted({ references: [{ kind: 'skill', id: 'skills/review', label: 'Review', revision }] })
-  const first = sessionLaunch(env, agent(), launch, null)
-  expect(first.system).not.toContain('Read the diff first.')
-  const history = join(mkdtempSync(join(tmpdir(), 'harness-history-')), 'chat.jsonl')
-  delivered(history, first.update!)
-  const repeated = sessionLaunch(env, agent(), launch, history).update!
-  expect(repeated.content).toContain('Read the diff first.')
-  expect(repeated.content).not.toContain('## Memory blocks')
-  const removed = sessionLaunch(env, agent(), hosted(), history).update!
-  expect(removed.content).toContain('## references')
-  expect(removed.content).not.toContain('Read the diff first.')
-  setProfile(env.root, 'nora', 'off')
-  const withdrawn = sessionLaunch(env, agent(), hosted(), history).update!
-  expect(withdrawn.snapshot).toEqual([])
-  for (const id of ['blocks', 'references', 'work', 'knowledge']) expect(withdrawn.content).toContain(`## ${id}`)
-  expect(sessionLaunch(env, agent(), launch, history).update!.content).toContain('Read the diff first.')
+  expect(load(env.root, 'run-1')!.delivery!.updatedSectionIds).toEqual(['wiki'])
+  // A new harness version changes the stable prefix, never the delivered state.
+  store.commit(env.root, 'nora', { ...tree, 'memory.md': 'Releases ship on Thursdays.\n' }, { kind: 'edit' })
+  const next = sessionLaunch(env, agent(), hosted(), history, materialise(env.root, { scope: 'nora' }, { subagents: true }))
+  expect(next.system).toContain('Releases ship on Thursdays.')
+  expect(next.system).not.toBe(first.system)
 })
 
 test('the snapshot follows the active branch and refreshes after compaction', () => {
@@ -251,11 +134,17 @@ test('the snapshot follows the active branch and refreshes after compaction', ()
   const history = join(directory, 'chat.jsonl')
   delivered(history, initial)
   const original = readFileSync(history, 'utf8')
-  // An unrelated branch's snapshot must not decide what this branch already received.
   writeFileSync(history, `${original}${JSON.stringify({ type: 'custom_message', id: 'other', parentId: null, customType: 'xingular-context', details: { xingularContext: [] } })}\n${JSON.stringify({ type: 'message', id: 'leaf', parentId: 'context-1' })}\n`)
   expect(sessionLaunch(env, agent(), hosted(), history).update).toBeNull()
   writeFileSync(history, `${original}${JSON.stringify({ type: 'compaction', id: 'summary', parentId: 'context-1' })}\n`)
-  expect(sessionLaunch(env, agent(), hosted(), history).update!.content).toContain('## Memory blocks')
+  expect(sessionLaunch(env, agent(), hosted(), history).update!.content).toContain('## Wiki')
   expect(sessionFile(directory, join(directory, 'older.jsonl'))).toBe(join(directory, 'older.jsonl'))
   expect(sessionFile(directory)).toBe(history)
 })
+
+test('a subagent section is left out when the session cannot start subagents', () => {
+  const env = setup()
+  store.seed(env.root, 'nora', tree)
+  const pack = compile(env, agent(), hosted(), materialise(env.root, { scope: 'nora' }, { subagents: false }))
+  expect(pack.sections.some((entry) => entry.id === 'subagents')).toBe(false)
+})