@xingular/harness 2.1.1 → 3.0.0

package/src/server/methods.ts

@@ -1,42 +1,34 @@
 // Everything a host process can ask of the harness, by name. Each method takes one JSON object
 // and returns JSON; the in-process API these call is the same one a Node application uses
 // directly. Methods are grouped by the part of the harness they belong to.
-import { readFileSync, statSync } from 'node:fs'
-import { basename } from 'node:path'
-
 import { ensureSharedDir, nativeConfig } from '../accounts/env'
 import { audit, readAudit, summaryAuthentication } from '../accounts/store'
 import { HarnessError, invalid } from '../core/errors'
-import { projectsOrNone } from '../core/projects'
 import * as capabilities from '../capabilities/api'
 import { loadRun as loadCapabilitySnapshot } from '../capabilities/runSnapshot'
 import { capabilitySet } from '../capabilities/runSnapshot'
 import type { Harness } from '../harness'
-import * as blocks from '../memory/blocks'
 import { validateScopeIds } from '../mcp/connections'
-import { callerBlocks, type CallerContext } from '../memory/caller'
-import { dispatch } from '../memory/dispatch'
-import * as facts from '../memory/facts'
-import * as graph from '../memory/graph'
-import * as health from '../memory/health'
-import { listInbox, dismissInboxItem } from '../memory/operations'
-import { writeIndex } from '../memory/proposals'
-import * as recall from '../memory/recall'
-import * as references from '../memory/references'
-import { readRunContext } from '../memory/runContext'
-import * as store from '../memory/store'
-import * as wiki from '../memory/wiki'
-import { reindexQuietly, reindexWiki } from '../memory/wikiIndex'
+import type { CallerContext } from '../core/caller'
+import * as recall from '../history/recall'
 import * as plugins from '../plugins/api'
 import * as install from '../plugins/install'
-import { comparison, compile, CONTEXT_PROFILES, load, profiles, render, setProfile, type ContextProfile, type Launch } from '../prompt/compile'
+import { compile, load, render, type Launch } from '../prompt/compile'
+import { readSummary } from '../refine/runner'
 import { selectHistory } from '../sessions/history'
 import { runsSince } from '../sessions/runIndex'
 import { findRun, listRuns, loadRun, pendingDecisions, readEvents, runFamily, snapshot } from '../sessions/runStore'
 import type { SubagentInput, SubagentSelection } from '../sessions/subagents'
 import type { SessionRunInput } from '../sessions/sessions'
-import * as registry from '../skills/registry'
 import type { TerminalPrepareInput } from '../terminal/terminals'
+import { dispatch } from '../tools/dispatch'
+import * as components from '../tree/components'
+import { materialise, type HarnessChoice } from '../tree/materialise'
+import { seedTree } from '../tree/seed'
+import * as trees from '../tree/store'
+import { PI_SURFACE, type Tree } from '../tree/surface'
+import { applyEdit, autotrigger, TreeError, validate } from '../tree/tree'
+import * as notes from '../wiki/notes'
 import type { Handler } from './rpc'
 
 type Params = Record<string, any>
@@ -59,27 +51,35 @@ const questionAnswer = (value: unknown): { selected: string[]; text?: string; no
 }
 const pluginScope = (params: Params): plugins.PluginScope => ({ cwd: optional(params, 'cwd'), accountId: optional(params, 'accountId'), agentId: optional(params, 'agentId'), projectId: optional(params, 'projectId') })
 
-/** Sources larger than this are not imported. */
-const MAX_SOURCE_BYTES = 50 * 1024 * 1024
+const treeOf = (value: unknown): Tree => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw invalid('tree must be an object of path → text.')
+  const out: Tree = {}
+  for (const [path, body] of Object.entries(value as Record<string, unknown>)) {
+    if (typeof body !== 'string') throw invalid(`${path} must be text.`)
+    out[path] = body
+  }
+  return out
+}
+
+/** Validates a tree without throwing: its census, or every problem. */
+function check(tree: Tree): { ok: true; census: ReturnType<typeof validate> } | { ok: false; problems: string[] } {
+  try {
+    return { ok: true, census: validate(PI_SURFACE, tree) }
+  } catch (error) {
+    return { ok: false, problems: error instanceof TreeError ? error.problems : [error instanceof Error ? error.message : String(error)] }
+  }
+}
 
 export function methods(harness: Harness): Record<string, Handler> {
-  const { accounts, approvals, apps, runs, sessions, maintenance, terminals, env } = harness
+  const { accounts, approvals, apps, runs, sessions, terminals, env } = harness
   const root = (): string => env.root
-  const wikiDir = (): string => store.wikiDir(env.root)
-  const changed = (): void => {
-    reindexQuietly(env.root)
-    harness.bus.emit({ type: 'wiki.changed' })
-  }
+  const harnessesChanged = (scope: string): void => harness.bus.emit({ type: 'harnesses.changed', scope })
 
   return {
     // ---- The harness itself --------------------------------------------------------------------
     'harness.status': () => ({ dataRoot: harness.dataRoot, productName: env.productName, recovery: harness.recovery, activeRuns: runs.activeRunIds() }),
     'harness.open': (params: Params) => harness.open(text(params, 'dataRoot'), Array.isArray(params.agentIds) ? params.agentIds : []),
     'harness.rebuildIndex': () => harness.rebuildIndex(),
-    'maintenance.list': (params: Params) => maintenance.jobs().filter((job) => params.runId ? job.runId === params.runId || (Array.isArray(params.ids) && params.ids.includes(job.id)) : params.includeCompleted === true || !['completed', 'rejected'].includes(job.status)).map(({ prepared: _prepared, hashes: _hashes, ...job }) => job),
-    'maintenance.review': (params: Params) => { maintenance.enqueue({ kind: 'review', requestId: optional(params, 'requestId') ?? String(Date.now()), manual: params.manual === true }); return { queued: true } },
-    'maintenance.failRun': (params: Params) => { maintenance.finishRun(text(params, 'runId'), true); return null },
-    'maintenance.retry': (params: Params) => maintenance.retry(text(params, 'id')),
     'hub.list': (params: Params) => harness.hub.list(params.refresh === true),
     'hub.get': (params: Params) => harness.hub.get(text(params, 'id'), text(params, 'version'), params.preview === true),
     'hub.install': (params: Params) => harness.hub.install(text(params, 'id'), text(params, 'version')),
@@ -140,91 +140,124 @@ export function methods(harness: Harness): Record<string, Handler> {
     'connections.appClients': () => apps.appClients(),
     'connections.validateScope': (params: Params) => validateScopeIds(apps.connections.list(), { agentId: optional(params, 'agentId'), projectId: optional(params, 'projectId') }, Array.isArray(params.ids) ? params.ids : []),
 
-    // ---- Wiki: what a person browses and edits ---------------------------------------------------
-    'wiki.pages': (params: Params) => wiki.listPages(root(), optional(params, 'namespace')),
-    'wiki.page': (params: Params) => wiki.loadPage(root(), text(params, 'pageId')),
-    'wiki.find': (params: Params) => wiki.searchEntries(root(), typeof params.query === 'string' ? params.query : '', params.options ?? {}),
-    'wiki.entry': (params: Params) => wiki.loadEntry(root(), text(params, 'entryId')),
-    'wiki.backlinks': (params: Params) => wiki.backlinks(root(), text(params, 'entryId')),
-    'wiki.namespaces': () => wiki.namespaces(root()),
-    'wiki.revisions': (params: Params) => wiki.listRevisions(root(), text(params, 'entryId')),
-    'wiki.revision': (params: Params) => wiki.loadRevision(root(), text(params, 'entryId'), text(params, 'revisionId')),
-    'wiki.restore': (params: Params) => {
-      wiki.restore(root(), text(params, 'entryId'), text(params, 'revisionId'))
-      changed()
+    // ---- Harness trees: the eight components that shape an agent ---------------------------------
+    'harnesses.surface': () => PI_SURFACE,
+    'harnesses.list': () => trees.scopes(root()).map((scope) => {
+      const head = trees.head(root(), scope)
+      return { scope, head, version: head ? trees.versionRecord(root(), scope, head.fingerprint) : null }
+    }),
+    'harnesses.get': (params: Params) => {
+      const scope = text(params, 'scope')
+      const head = trees.head(root(), scope)
+      const fp = optional(params, 'version') ?? head?.fingerprint ?? null
+      if (!fp) return { scope, head: null, version: null, tree: null, plugins: [] }
+      const tree = trees.readVersion(root(), scope, fp)
+      return { scope, head, version: trees.versionRecord(root(), scope, fp), tree, plugins: harness.trust.review(tree), probeCode: harness.trust.probeCode(scope) }
     },
-    // A project was added: it gets its namespace, its fixed pages, and its brief.
-    'wiki.ensureProject': (params: Params) => {
-      store.ensureProjectNamespace(root(), text(params, 'slug'), text(params, 'name'))
-      blocks.ensureProject(wikiDir(), text(params, 'slug'), text(params, 'name'))
-      writeIndex(wikiDir())
-      changed()
+    'harnesses.lineage': (params: Params) => trees.lineage(root(), text(params, 'scope')),
+    'harnesses.compare': (params: Params) => trees.compare(root(), text(params, 'scope'), text(params, 'from'), text(params, 'to')),
+    'harnesses.validate': (params: Params) => {
+      const tree = treeOf(params.tree)
+      const repaired = params.repair === true ? autotrigger(PI_SURFACE, tree) : []
+      return { ...check(tree), repaired, tree }
     },
-    // Files changed outside the harness (an editor, a sync client): bring the index up to date.
-    'wiki.reindex': () => {
-      const pages = reindexWiki(root())
-      harness.bus.emit({ type: 'wiki.changed' })
-      return pages
+    // A whole tree, or an edit of the head that names only the files it changes (null removes one).
+    'harnesses.save': (params: Params) => {
+      const scope = text(params, 'scope')
+      const base = trees.headTree(root(), scope)?.tree ?? {}
+      const tree = params.tree !== undefined ? treeOf(params.tree) : applyEdit(base, (params.edit ?? {}) as Record<string, string | null>)
+      if (params.repair === true) autotrigger(PI_SURFACE, tree)
+      const record = trees.commit(root(), scope, tree, { kind: params.source === 'import' ? 'import' : 'edit', note: optional(params, 'note') ?? undefined, components: Array.isArray(params.components) ? params.components : undefined })
+      harnessesChanged(scope)
+      return record
+    },
+    'harnesses.restore': (params: Params) => {
+      const scope = text(params, 'scope')
+      const head = trees.restore(root(), scope, text(params, 'version'), optional(params, 'note') ?? undefined)
+      harnessesChanged(scope)
+      return head
     },
-    'wiki.sources': () => store.listSources(wikiDir()),
-    'wiki.ingest': (params: Params) => {
+    // A first version: the tree given, or one built from what shaped the caller before harness trees.
+    'harnesses.seed': (params: Params) => {
+      const scope = text(params, 'scope')
+      const tree = params.tree !== undefined ? treeOf(params.tree) : seedTree(root(), { agentId: optional(params, 'agentId') ?? scope, projectId: optional(params, 'projectId'), instructions: typeof params.instructions === 'string' ? params.instructions : '' })
+      const head = trees.seed(root(), scope, tree, optional(params, 'note') ?? undefined)
+      harnessesChanged(scope)
+      return head
+    },
+    'harnesses.legacy': (params: Params) => seedTree(root(), { agentId: optional(params, 'agentId'), projectId: optional(params, 'projectId'), instructions: typeof params.instructions === 'string' ? params.instructions : '' }),
+    'harnesses.trusted': () => harness.trust.list(),
+    'harnesses.trust': (params: Params) => {
+      const scope = text(params, 'scope')
+      const tree = trees.headTree(root(), scope)?.tree ?? {}
       const path = text(params, 'path')
-      if (statSync(path).size > MAX_SOURCE_BYTES) throw invalid('Sources larger than 50 MB are not imported.')
-      const source = maintenance.ingest(optional(params, 'name') ?? basename(path), readFileSync(path), optional(params, 'namespace') ?? store.LIBRARY_NAMESPACE)
-      harness.bus.emit({ type: 'wiki.changed' })
-      return source
+      const body = typeof params.text === 'string' ? params.text : tree[path]
+      if (typeof body !== 'string') throw invalid('That plugin file is not in the harness.')
+      const entry = harness.trust.grant(body, path, scope)
+      harnessesChanged(scope)
+      return entry
     },
-    'wiki.log': () => wiki.recentLog(root()),
-    'wiki.graph': () => graph.build(env),
-    'wiki.health': () => health.check(root()),
-    'wiki.inbox': () => listInbox(wikiDir()),
-    'wiki.inboxDismiss': (params: Params) => {
-      dismissInboxItem(wikiDir(), text(params, 'itemId'))
-      harness.bus.emit({ type: 'wiki.changed' })
+    'harnesses.untrust': (params: Params) => {
+      harness.trust.revoke(text(params, 'hash'))
+      harness.bus.emit({ type: 'harnesses.changed' })
     },
-    'wiki.inboxAccept': async (params: Params) => {
-      // An accepted plugin must arrive untrusted: packages that loaded before are taken over first, never together with it.
-      await plugins.ensureAdopted(harness)
-      const message = maintenance.acceptInboxItem(text(params, 'itemId'))
-      harness.bus.emit({ type: 'plugins.changed' })
-      return message
+    'harnesses.setProbeCode': (params: Params) => {
+      const scope = text(params, 'scope')
+      harness.trust.setProbeCode(scope, params.on === true)
+      harnessesChanged(scope)
+    },
+    // The component library (skills, rules and prompts kept as files), and adding one to a tree.
+    'harnesses.components': () => components.list(root()),
+    'harnesses.importComponents': (params: Params) => components.importItems(root(), (optional(params, 'kind') ?? 'skills') as components.ComponentKind, Array.isArray(params.items) ? params.items : []),
+    'harnesses.addComponent': (params: Params) => {
+      const scope = text(params, 'scope')
+      const base = params.tree !== undefined ? treeOf(params.tree) : trees.headTree(root(), scope)?.tree ?? {}
+      const tree = components.addToTree(root(), base, text(params, 'id'))
+      return { tree, ...check(tree) }
+    },
+    'harnesses.materialise': (params: Params) => {
+      const built = materialise(root(), params.harness as HarnessChoice, { trust: harness.trust })
+      return { ...built, tree: undefined }
     },
-    'wiki.undoOperation': (params: Params) => maintenance.undoOperation(text(params, 'operationId')),
-    'wiki.runContext': (params: Params) => readRunContext(root(), text(params, 'runId')),
 
-    // ---- Facts and memory blocks -----------------------------------------------------------------
-    'facts.list': () => facts.loadMemories(wikiDir()).map((memory) => facts.response(wikiDir(), memory)),
-    'facts.save': (params: Params) => {
-      const saved = facts.saveAsUser(wikiDir(), params.input)
-      changed()
-      return saved
+    // ---- Refinement: improving a harness from evidence -------------------------------------------
+    'refine.start': (params: Params) => harness.refine.start({ task: params.task, k: typeof params.k === 'number' ? params.k : 1, mode: params.mode === 'sequential' ? 'sequential' : 'parallel', improver: params.improver ?? {}, baseVersion: optional(params, 'baseVersion'), id: optional(params, 'id') ?? undefined }),
+    'refine.get': (params: Params) => harness.refine.get(text(params, 'id')),
+    'refine.list': (params: Params) => harness.refine.list({ scope: optional(params, 'scope'), limit: typeof params.limit === 'number' ? params.limit : undefined }),
+    'refine.running': () => harness.refine.running(),
+    'refine.cancel': async (params: Params) => {
+      await harness.refine.cancel(text(params, 'id'))
+      return readSummary(root(), text(params, 'id'))
     },
-    'blocks.list': (params: Params) => {
-      // Defaults exist for the user, each agent the application names, and each project.
-      const directory = wikiDir()
-      blocks.ensureUser(directory)
-      for (const agentId of Array.isArray(params.agentIds) ? params.agentIds : []) blocks.ensureAgent(directory, String(agentId))
-      for (const project of projectsOrNone(root())) blocks.ensureProject(directory, project.slug, project.name)
-      return blocks.loadAll(directory).map((block) => blocks.response(directory, block))
+    'refine.candidates': (params: Params) => harness.refine.candidates(text(params, 'id')),
+    'refine.adopt': (params: Params) => harness.refine.adopt(text(params, 'id'), { label: optional(params, 'label') }),
+    'library.list': (params: Params) => harness.refine.library(text(params, 'scope')),
+    'library.read': (params: Params) => harness.refine.libraryEntry(text(params, 'scope'), text(params, 'area'), text(params, 'task')),
+    'library.forget': (params: Params) => harness.refine.forget(text(params, 'scope'), text(params, 'area'), Array.isArray(params.tasks) ? params.tasks : []),
+
+    // ---- The Wiki: project notes ------------------------------------------------------------------
+    'wiki.list': (params: Params) => notes.list(root(), params.project === undefined ? {} : { project: optional(params, 'project') }),
+    'wiki.read': (params: Params) => notes.read(root(), text(params, 'path')),
+    'wiki.write': (params: Params) => {
+      const note = notes.write(root(), text(params, 'path'), typeof params.text === 'string' ? params.text : '', { expectedUpdatedAt: optional(params, 'expectedUpdatedAt') })
+      harness.bus.emit({ type: 'wiki.changed' })
+      return note
     },
-    'blocks.save': (params: Params) => {
-      const saved = blocks.response(wikiDir(), blocks.saveAsUser(wikiDir(), params.input))
+    'wiki.remove': (params: Params) => {
+      notes.remove(root(), text(params, 'path'))
       harness.bus.emit({ type: 'wiki.changed' })
-      return saved
     },
-    'blocks.undo': (params: Params) => {
-      const block = blocks.response(wikiDir(), blocks.undoLast(wikiDir(), text(params, 'blockId')))
+    'wiki.search': (params: Params) => notes.search(root(), typeof params.query === 'string' ? params.query : '', { project: optional(params, 'project'), limit: typeof params.limit === 'number' ? params.limit : undefined }),
+    'wiki.graph': () => notes.graph(root()),
+    'wiki.versions': (params: Params) => notes.versions(root(), text(params, 'path')),
+    'wiki.version': (params: Params) => notes.version(root(), text(params, 'path'), text(params, 'id')),
+    'wiki.ensureProject': () => {
+      notes.ensureLayout(root(), env.productName)
       harness.bus.emit({ type: 'wiki.changed' })
-      return block
     },
 
     // ---- What a session calls, on behalf of a caller the host names -------------------------------
-    'memory.permissions': (params: Params) => {
-      const context = (params.context ?? {}) as CallerContext
-      const { caller, attached } = callerBlocks(env, context)
-      return attached.map((block) => ({ id: block.id, writable: blocks.editRefusal(caller, block) === null, reason: blocks.editRefusal(caller, block) }))
-    },
-    'memory.call': (params: Params) => dispatch(env, (params.context ?? {}) as CallerContext, text(params, 'call'), params.params ?? {}),
+    'harness.call': (params: Params) => dispatch(env, (params.context ?? {}) as CallerContext, text(params, 'call'), params.params ?? {}, { treeDir: optional(params, 'treeDir') }),
 
     // ---- Recall ------------------------------------------------------------------------------------
     'recall.search': (params: Params) => recall.searchAll(env, typeof params.query === 'string' ? params.query : '', params.filter ?? {}),
@@ -232,30 +265,11 @@ export function methods(harness: Harness): Record<string, Handler> {
 
     // ---- The compiled prompt -----------------------------------------------------------------------
     'context.compile': (params: Params) => {
-      const pack = compile(env, (params.context ?? {}) as CallerContext, (params.launch ?? {}) as Launch)
+      const tree = params.harness ? materialise(root(), params.harness as HarnessChoice, { trust: harness.trust }) : null
+      const pack = compile(env, (params.context ?? {}) as CallerContext, (params.launch ?? {}) as Launch, tree)
       return params.render ? { pack, text: render(env, pack) } : pack
     },
     'context.runPack': (params: Params) => load(root(), text(params, 'runId')),
-    'context.profiles': () => ({ profiles: profiles(root()), stats: comparison(root()) }),
-    'context.setProfile': (params: Params) => {
-      const profile = params.profile as ContextProfile
-      if (!CONTEXT_PROFILES.includes(profile)) throw invalid('Unknown context profile.')
-      setProfile(root(), text(params, 'subject'), profile)
-    },
-    'references.pin': (params: Params) => references.pinAll(root(), (Array.isArray(params.items) ? params.items : []).map((item: Params) => ({ kind: item.kind === 'skill' ? ('skill' as const) : ('page' as const), id: text(item, 'id') }))),
-    'references.body': (params: Params) => references.body(root(), text(params, 'id'), optional(params, 'revision')),
-
-    // ---- Skills, prompts, rules --------------------------------------------------------------------
-    'skills.list': () => registry.state(root()),
-    'skills.setEnabled': (params: Params) => {
-      const state = registry.setEnabled(root(), optional(params, 'projectId'), Array.isArray(params.ids) ? params.ids : [])
-      // The same choices are what the plugin list shows.
-      harness.bus.emit({ type: 'plugins.changed' })
-      return state
-    },
-    'skills.create': (params: Params) => registry.create(root(), text(params, 'kind'), text(params, 'name')),
-    'skills.import': (params: Params) => registry.importSkills(root(), Array.isArray(params.skills) ? params.skills : []),
-    'skills.enabledFor': (params: Params) => registry.enabledFor(root(), optional(params, 'projectId')),
 
     // ---- Plugins: everything that shapes a session, and the trust a working folder's code needs ---
     // A host that is not a Node program describes its own parts here instead of in the options.
@@ -273,7 +287,7 @@ export function methods(harness: Harness): Record<string, Handler> {
     'plugins.update': (params: Params) => install.update(harness, { ...pluginScope(params), pluginId: optional(params, 'pluginId') }),
     'plugins.configure': (params: Params) => plugins.configure(harness, { ...pluginScope(params), pluginId: text(params, 'pluginId'), settings: (params.settings && typeof params.settings === 'object' ? params.settings : {}) as Record<string, unknown> }),
     'plugins.forgetAgent': (params: Params) => plugins.forgetAgent(harness, text(params, 'agentId')),
-    'plugins.inventory': (params: Params) => plugins.inventoryFor(harness, { ...pluginScope(params), context: (params.context ?? {}) as CallerContext, launch: (params.launch ?? {}) as Launch, tools: params.tools, connections: params.connections }),
+    'plugins.inventory': (params: Params) => plugins.inventoryFor(harness, { ...pluginScope(params), context: (params.context ?? {}) as CallerContext, launch: (params.launch ?? {}) as Launch, tools: params.tools, connections: params.connections, harness: (params.harness ?? null) as HarnessChoice | null }),
     'plugins.trust': (params: Params) => plugins.trust(harness, { cwd: optional(params, 'cwd'), accountId: optional(params, 'accountId'), hash: text(params, 'hash') }),
     'plugins.untrust': (params: Params) => plugins.untrust(harness, { cwd: optional(params, 'cwd'), accountId: optional(params, 'accountId'), hash: text(params, 'hash') }),
 

package/src/server/server.test.ts

@@ -84,7 +84,7 @@ describe('the harness served to a host', () => {
 
     const status = await request('harness.status')
     expect(status).toMatchObject({ dataRoot: harness.env.root, productName: 'Xingular Harness', activeRuns: [] })
-    expect(await request<string[]>('harness.methods')).toEqual(expect.arrayContaining(['accounts.list', 'sessions.run', 'sessions.spawnSubagent', 'subagents.spawn', 'subagents.wait', 'subagents.results', 'wiki.pages', 'terminal.prepare', 'skills.list', 'skills.import', 'connections.list', 'harness.shutdown']))
+    expect(await request<string[]>('harness.methods')).toEqual(expect.arrayContaining(['accounts.list', 'sessions.run', 'sessions.spawnSubagent', 'subagents.spawn', 'subagents.wait', 'subagents.results', 'wiki.list', 'wiki.write', 'terminal.prepare', 'harnesses.seed', 'harnesses.save', 'refine.start', 'refine.adopt', 'library.list', 'connections.list', 'harness.shutdown']))
 
     await expect(request('sessions.spawnSubagent', { parentRunId: 'missing', brief: 'Review' })).rejects.toMatchObject({ code: 'run_not_active' })
 
@@ -95,14 +95,11 @@ describe('the harness served to a host', () => {
     await expect(request('accounts.rename', {})).rejects.toMatchObject({ code: 'invalid_request', message: 'accountId is required.' })
     await expect(request('nope.nothing')).rejects.toMatchObject({ code: 'unknown_method' })
 
-    expect((await request<any[]>('wiki.namespaces')).map((entry) => entry.namespace)).toEqual(expect.arrayContaining(['/projects/app']))
-    const blocks = await request<any[]>('blocks.list', { agentIds: ['a1'] })
-    expect(blocks.map((block) => block.label)).toEqual(expect.arrayContaining(['user', 'persona', 'notes']))
-    expect(await request('memory.call', { context: { agentId: 'a1', agentName: 'Helper', actor: 'Chat' }, call: 'memory.append', params: { block: 'notes', text: 'Ship on Fridays.' } })).toContain('notes')
+    await request('wiki.write', { path: 'projects/app/decisions', text: '# Decisions\n\nShip on Fridays.\n' })
     expect(notices).toContainEqual({ type: 'wiki.changed' })
-    const compiled = await request('context.compile', { context: { agentId: 'a1', agentName: 'Helper', actor: 'Chat' }, render: true })
-    expect(compiled.text).toContain('Ship on Fridays.')
-    expect(await request('context.profiles')).toEqual({ profiles: {}, stats: [] })
+    expect(await request('harness.call', { context: { agentId: 'a1', agentName: 'Helper', actor: 'Chat', projectId: 'p1' }, call: 'wiki.search', params: { query: 'Fridays' } })).toContain('projects/app/decisions')
+    const compiled = await request('context.compile', { context: { agentId: 'a1', agentName: 'Helper', actor: 'Chat', projectId: 'p1' }, render: true })
+    expect(compiled.text).toContain('projects/app/decisions — Decisions')
 
     const started = await request('sessions.run', { run: { id: 'r1', sessionId: 'a1' }, cwd: harness.env.root, sessionDir: join(harness.env.root, 'sessions', 'a1'), text: 'hello', caller: { agentId: 'a1', agentName: 'Helper', actor: 'Chat' }, tools: { allow: ['read'] } })
     expect(started).toEqual({ runId: 'r1', nativeSessionId: 'native-1' })
@@ -110,7 +107,7 @@ describe('the harness served to a host', () => {
     expect(events.map((event) => event.type)).toEqual(['started', 'status.changed', 'context.snapshot', 'completed'])
     expect((await request('runs.load', { runId: 'r1' })).run).toMatchObject({ id: 'r1', status: 'completed' })
     expect((await request<any[]>('runs.list', { filter: { sessionId: 'a1' } })).map((run) => run.id)).toEqual(['r1'])
-    expect((await request('context.profiles')).stats).toMatchObject([{ subject: 'a1', mode: 'chat', contextProfile: 'full', runs: 1, completed: 1, runIds: ['r1'] }])
+    expect((await request('context.runPack', { runId: 'r1' })).sections.map((section: { id: string }) => section.id)).toContain('tools')
   })
 
   it('lets a host that is not a Node program supply secrets, policy, names, and tools over the protocol', async () => {
@@ -163,31 +160,41 @@ describe('the harness served to a host', () => {
   })
 })
 
-describe('built-in skills', () => {
-  it('are on everywhere until switched off, and a person\'s own item of the same name replaces one', async () => {
+describe('harness trees over the wire', () => {
+  it('seeds, edits, validates, restores, and adds a built-in component, then compiles the tree', async () => {
     const builtins = mkdtempSync(join(tmpdir(), 'builtin-'))
-    writeFile(join(builtins, 'skills', 'review', 'SKILL.md'), '---\nname: review\ndescription: Review a change before it ships\n---\nRead the diff first.\n')
-    writeFile(join(builtins, 'rules', 'plain.md'), '---\nname: Plain words\ndescription: Write plainly\n---\nUse plain words.\n')
-    const { transport, request } = host()
+    writeFile(join(builtins, 'skills', 'review', 'SKILL.md'), '---\nname: review\ndescription: reviewing a change before it ships\n---\nRead the diff first.\n')
+    writeFile(join(builtins, 'rules', 'plain.md'), '---\nname: Plain words\n---\nUse plain words.\n')
+    const { transport, request, notices } = host()
     const harness = createHarness({ dataRoot: rootWithProject(), stateDir: mkdtempSync(join(tmpdir(), 'hs-')), secrets: memorySecretStore(), builtins: [builtins] })
     open.push(harness)
     serve(harness, transport)
 
-    const state = await request('skills.list')
-    expect(state.items).toMatchObject([{ id: 'rules/plain', builtin: true }, { id: 'skills/review', builtin: true }])
-    expect(state.enabled.global).toEqual(['rules/plain', 'skills/review'])
-    expect((await request<any[]>('skills.enabledFor', { projectId: 'p1' })).map((item) => item.id)).toEqual(['rules/plain', 'skills/review'])
-    expect((await request('context.compile', { context: { projectId: 'p1', actor: 'Code' }, render: true })).text).toContain('Use plain words.')
-
-    const off = await request('skills.setEnabled', { projectId: null, ids: ['skills/review'] })
-    expect(off.enabled).toMatchObject({ global: ['skills/review'], builtinOff: ['rules/plain'] })
-    expect((await request<any[]>('skills.enabledFor', {})).map((item) => item.id)).toEqual(['skills/review'])
-
-    writeFile(join(harness.env.root, 'registry', 'skills', 'review', 'SKILL.md'), '---\nname: review\ndescription: My own review steps\n---\nMine.\n')
-    const mine = (await request('skills.list')).items.find((item: any) => item.id === 'skills/review')
-    expect(mine).toMatchObject({ description: 'My own review steps' })
-    expect(mine.builtin).toBeUndefined()
-    // A person's own item is enabled the usual way, not by default.
-    expect((await request<any[]>('skills.enabledFor', {})).map((item) => item.id)).toEqual([])
+    const seeded = await request('harnesses.seed', { scope: 'a1', instructions: 'You help with releases.' })
+    expect(seeded.fingerprint).toMatch(/^[0-9a-f]{16}$/)
+    expect(notices).toContainEqual({ type: 'harnesses.changed', scope: 'a1' })
+    const first = await request('harnesses.get', { scope: 'a1' })
+    expect(first.tree['systemprompt.md']).toBe('You help with releases.\n')
+
+    const library = await request<any[]>('harnesses.components')
+    expect(library.map((item) => item.id)).toEqual(['rules/plain', 'skills/review'])
+    const added = await request('harnesses.addComponent', { scope: 'a1', id: 'skills/review' })
+    expect(added.ok).toBe(true)
+    expect(added.tree['guardrails.md']).toContain('load the `review` skill')
+    const saved = await request('harnesses.save', { scope: 'a1', tree: added.tree, note: 'Added review' })
+    expect(saved.parent).toBe(seeded.fingerprint)
+
+    const bad = await request('harnesses.validate', { tree: { ...added.tree, 'plugins/x.ts': 'nothing' } })
+    expect(bad).toMatchObject({ ok: false })
+    expect(bad.problems.join(' ')).toContain('default export')
+    await expect(request('harnesses.save', { scope: 'a1', edit: { 'plugins/x.ts': 'nothing' } })).rejects.toMatchObject({ code: 'harness_invalid' })
+
+    const edited = await request('harnesses.save', { scope: 'a1', edit: { 'memory.md': 'Releases ship on Tuesdays.\n' } })
+    expect((await request<any[]>('harnesses.lineage', { scope: 'a1' })).map((version) => version.fingerprint)).toEqual([edited.fingerprint, saved.fingerprint, seeded.fingerprint])
+    const compiled = await request('context.compile', { context: { agentId: 'a1', actor: 'Chat' }, harness: { scope: 'a1' }, render: true })
+    expect(compiled.text).toContain('Releases ship on Tuesdays.')
+    await request('harnesses.restore', { scope: 'a1', version: seeded.fingerprint })
+    expect((await request('harnesses.get', { scope: 'a1' })).head.fingerprint).toBe(seeded.fingerprint)
+    expect(await request('refine.list', { scope: 'a1' })).toEqual([])
   })
 })

package/src/sessions/contracts.ts

@@ -97,7 +97,7 @@ const approvalRequestedPayload = z.object({
   automatic: approvalAutomaticSchema.optional()
 })
 const approvalResolvedPayload = z.object({ approvalId: z.string(), decision: z.enum(['approved', 'denied', 'native']), automatic: approvalAutomaticSchema.optional() })
-export const questionOptionSchema = z.object({ label: z.string().min(1), description: z.string().optional() })
+export const questionOptionSchema = z.object({ label: z.string().min(1), description: z.string().optional(), recommended: z.boolean().optional() })
 export type QuestionOption = z.infer<typeof questionOptionSchema>
 const questionBatchFields = {
   batchId: z.string().min(1).optional(),
@@ -299,6 +299,9 @@ export interface RunRecord {
   agentId: string | null
   /** What started the run. */
   trigger: string | null
+  /** The harness tree the run used: its scope and version fingerprint. */
+  harnessScope?: string | null
+  harnessVersion?: string | null
 }
 
 const text = z.string().nullish().transform((value) => value ?? null)
@@ -326,7 +329,9 @@ export const runRecordSchema = z.object({
   handoffId: text,
   accountId: text,
   agentId: text,
-  trigger: text
+  trigger: text,
+  harnessScope: text.optional(),
+  harnessVersion: text.optional()
 }) satisfies z.ZodType<RunRecord, unknown>
 
 export const ACTIVE_STATUSES: readonly string[] = ['queued', 'running', 'waiting_for_approval', 'waiting_for_input']

package/src/sessions/conversation.test.ts

@@ -1,15 +1,13 @@
 // Whole replies, through everything the harness does for one: the compiled prompt, the plugins
 // it chose to load, the gate, the run's events. Pi is real and so are the extensions; only the
 // model is scripted, so no request leaves the machine.
-import { existsSync, mkdtempSync } from 'node:fs'
+import { mkdtempSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 
 import { memorySecretStore } from '../accounts/secrets'
 import { createHarness, type Harness } from '../harness'
-import { listInbox } from '../memory/operations'
-import { wikiDir } from '../memory/store'
 import type { Plugin } from '../plugins/types'
 import { methods } from '../server/methods'
 import { fauxModel } from '../../tests/faux'
@@ -33,7 +31,7 @@ export default function (pi) {
 async function setup() {
   const root = rootWithProject()
   const base = mkdtempSync(join(tmpdir(), 'conversation-'))
-  const harness = createHarness({ dataRoot: root, stateDir: join(base, 'state'), secrets: memorySecretStore(), maintainerFactory: async () => ({ prompt: async () => undefined, dispose: () => undefined, error: () => null }) })
+  const harness = createHarness({ dataRoot: root, stateDir: join(base, 'state'), secrets: memorySecretStore() })
   open.push(harness)
   harness.accounts.create('Main', 'apiKey')
   const model = await fauxModel(harness)
@@ -181,29 +179,6 @@ describe('a whole reply, with a scripted model', () => {
     expect(model.lastToolResults().at(-1)).toMatch(/denied/)
   })
 
-  it('lets the agent propose a plugin, which reaches the Inbox and nothing else', async () => {
-    const { root, model, start, until, settled, of } = await setup()
-    model.script([
-      model.calls(['plugin_propose', { name: 'Memory to Docs', description: 'Copies each saved memory to the team document.', extends: ['memory'] as never, files: [{ path: 'hooks.mjs', content: "export default function (harness) { harness.on('memory.saved', async () => {}) }\n" }] as never }]),
-      model.says('I proposed it; it is in your Inbox.')
-    ])
-    const id = await start()
-    await until(() => settled(id))
-    expect(model.lastToolResults().at(-1)).toContain('The plugin "memory-to-docs" is waiting in the Inbox')
-    expect(listInbox(wikiDir(root)).map((item) => item.title)).toEqual(['Proposed plugin "Memory to Docs"'])
-    expect(existsSync(join(root, 'plugins'))).toBe(false)
-    // Proposing is not something a person is asked to approve: it changes nothing until they accept.
-    expect(of(id).some((event) => event.type === 'approval.requested')).toBe(false)
-  })
-
-  it('has no plugin proposal tool in unattended work', async () => {
-    const { model, start, until, settled } = await setup()
-    model.script([model.calls(['plugin_propose', { name: 'x', description: 'y', files: [] as never }]), model.says('Done.')])
-    const id = await start({ automatic: true })
-    await until(() => settled(id))
-    expect(model.lastToolResults().at(-1)).not.toContain('waiting in the Inbox')
-  })
-
   it('delivers a message sent during a tool call after that call, before the next request', async () => {
     const { harness, model, call, start, until, settled, of } = await setup()
     model.script([model.calls(['bash', { command: 'ls' }]), model.says('Noted.')])

package/src/sessions/planMode.test.ts

@@ -26,10 +26,17 @@ describe('plan mode', () => {
     const readOnly = new Set(['files_read'])
     for (const tool of ['read', 'grep', 'wiki_read', 'files_read', 'ask_user']) expect(planRefusal(tool, readOnly), tool).toBeNull()
     for (const tool of ['bash', 'write', 'edit', 'memory_append', 'wiki_propose', 'spawn_subagent', 'mcp_call_tool', 'files_write']) {
-      expect(planRefusal(tool, readOnly), tool).toContain('Plan mode is read-only')
+      expect(planRefusal(tool, readOnly), tool).toContain('Plan mode is research-only')
     }
   })
 
+  it('allows only provider calls whose arguments are explicitly classified as research-safe', () => {
+    const safeBrowserCall = (input: Record<string, unknown>) => input.op === 'navigate' || input.op === 'scroll'
+    expect(planRefusal('browser', new Set(), { op: 'navigate' }, safeBrowserCall)).toBeNull()
+    expect(planRefusal('browser', new Set(), { op: 'click' }, safeBrowserCall)).toContain('research-only')
+    expect(planRefusal('browser', new Set(), { op: 'submit' }, safeBrowserCall)).toContain('research-only')
+  })
+
   it('adds its instructions while on, withdraws them once after, and is absent otherwise', () => {
     expect(planSection(true, null)).toMatchObject({ id: PLAN_SECTION_ID, body: PLAN_INSTRUCTIONS, dynamic: true })
     expect(PLAN_INSTRUCTIONS).toContain('<proposed_plan>')