@xingular/harness 0.0.0-stage → 0.1.1

package/src/plugins/hooks.test.ts

@@ -0,0 +1,250 @@
+import { existsSync, mkdtempSync, readFileSync, readdirSync } 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 { Bus } from '../core/bus'
+import { createHarness, type Harness } from '../harness'
+import { listInbox } from '../memory/operations'
+import { wikiDir } from '../memory/store'
+import { methods } from '../server/methods'
+import { pluginProposeTool } from '../tools/pluginPropose'
+import { rootWithProject, writeFile } from '../../tests/helpers'
+import { entryEvent, Hooks, type HookEvent } from './hooks'
+import { checkPluginProposal } from './proposal'
+import type { Plugin } from './types'
+
+const open: Harness[] = []
+afterEach(async () => {
+  for (const harness of open.splice(0)) await harness.close()
+})
+
+const temp = (): string => mkdtempSync(join(tmpdir(), 'hooks-'))
+// The test runner owns `import()` here; in a real process the harness uses Node's own.
+const importFile = (address: string): Promise<unknown> => import(/* @vite-ignore */ address)
+
+/** A hooks file that appends what it was told to a file, so a test can read it back. */
+const recorder = (out: string, events: string[], extra = ''): string =>
+  `import { appendFileSync } from 'node:fs'\nexport default function (harness) {\n${events.map((event) => `  harness.on('${event}', async (event, ctx) => { appendFileSync(${JSON.stringify(out)}, JSON.stringify({ type: event.type, id: event.id ?? event.runId, title: event.title, body: event.body, actor: event.actor }) + '\\n')${extra} })`).join('\n')}\n}\n`
+
+const told = (out: string): Record<string, unknown>[] => (existsSync(out) ? readFileSync(out, 'utf8').trim().split('\n').filter(Boolean).map((line) => JSON.parse(line)) : [])
+
+function kit(folder: string, name: string, hooks: string): void {
+  writeFile(join(folder, 'package.json'), JSON.stringify({ name, version: '1.0.0', description: `${name} mirrors memory.`, harness: { extends: ['memory', 'nonsense'], hooks: './hooks.mjs' } }))
+  writeFile(join(folder, 'hooks.mjs'), hooks)
+}
+
+function setup() {
+  const root = rootWithProject()
+  const base = temp()
+  const harness = createHarness({ dataRoot: root, stateDir: join(base, 'state'), secrets: memorySecretStore(), hookImporter: importFile })
+  open.push(harness)
+  const table = methods(harness)
+  const call = <T>(method: string, params: Record<string, unknown> = {}) => table[method](params) as Promise<T>
+  const saveFact = (title: string, body: string) => call('facts.save', { input: { title, kind: 'fact', body, namespace: '/' } })
+  return { harness, root, base, call, saveFact }
+}
+
+describe('a written file as an event', () => {
+  it('is a fact, a memory block, or a page by where it is in the Wiki', () => {
+    const wiki = '/data/wiki'
+    const change = (path: string, text: string) => entryEvent({ wiki, id: 'x', path: join(wiki, path), text, actor: 'user', reason: 'Edited' })
+    expect(change('facts/pnpm.md', '---\ntitle: Use pnpm\nkind: preference\n---\n\nAlways pnpm.\n')).toMatchObject({ type: 'memory.saved', title: 'Use pnpm', body: 'Always pnpm.', actor: 'user' })
+    expect(change('blocks/agents/a1/notes.md', '---\nlabel: notes\n---\n\nLikes tabs.\n')).toMatchObject({ type: 'memory.block.changed', title: 'notes', body: 'Likes tabs.' })
+    expect(change('library/arch.md', '---\ntitle: Architecture\n---\n\nLayers.\n')).toMatchObject({ type: 'wiki.page.saved', title: 'Architecture' })
+    expect(change('home.md', 'No front matter.')).toMatchObject({ type: 'wiki.page.saved', title: 'x', body: 'No front matter.' })
+  })
+})
+
+describe('hooks a plugin gives the harness', () => {
+  it('mirrors saved facts through a real disposable MCP subprocess and stops on detach, changed code or revoked permission', async () => {
+    const { harness, base, call, saveFact } = setup()
+    const output = join(base, 'mirrored.jsonl')
+    await harness.apps.save({ id: 'mirror', name: 'Disposable mirror', kind: 'local', command: process.execPath, args: [join(process.cwd(), 'tests/mcp-hook-fixture.mjs'), output], enabled: true, global: true, readTools: ['mirror_fact'] })
+    const paths = ['one', 'two'].map((name) => join(base, name))
+    for (const [index, path] of paths.entries()) {
+      const name = ['mirror-one', 'mirror-two'][index]
+      kit(path, name, `export default function(harness) { harness.on('memory.saved', async (event, ctx) => { await ctx.call('Disposable mirror', 'mirror_fact', { plugin: '${name}', id: event.id, title: event.title, body: event.body }) }) }\n`)
+      const plugins = await call<Plugin[]>('plugins.install', { source: path })
+      const plugin = plugins.find((entry) => entry.id === `package:${name}`)!
+      await call('plugins.attach', { id: plugin.id })
+      await call('plugins.trust', { hash: plugin.code!.hash })
+    }
+    await harness.hooks.reload()
+    await saveFact('Synthetic one', 'Generated probe body.')
+    await harness.hooks.settled()
+    expect(told(output).map((row) => row.plugin)).toEqual(['mirror-one', 'mirror-two'])
+    expect(told(output)[0]).toMatchObject({ title: 'Synthetic one', body: 'Generated probe body.' })
+    await call('plugins.detach', { id: 'package:mirror-one' })
+    await saveFact('Synthetic two', 'Second body.')
+    await harness.hooks.settled()
+    expect(told(output).map((row) => row.plugin)).toEqual(['mirror-one', 'mirror-two', 'mirror-two'])
+    writeFile(join(paths[1], 'hooks.mjs'), '// Changed since trust\nexport default function() {}\n')
+    await saveFact('Synthetic three', 'Untrusted code hears nothing.')
+    await harness.hooks.settled()
+    expect(told(output)).toHaveLength(3)
+    await call('plugins.attach', { id: 'package:mirror-one' })
+    await harness.apps.save({ id: 'mirror', name: 'Disposable mirror', kind: 'local', command: process.execPath, args: [join(process.cwd(), 'tests/mcp-hook-fixture.mjs'), output], enabled: true, global: true, readTools: [] })
+    await harness.hooks.reload()
+    await saveFact('Synthetic four', 'Write succeeds with permission revoked.')
+    await harness.hooks.settled()
+    expect(told(output)).toHaveLength(3)
+    expect(harness.hooks.status()[join(paths[0], 'hooks.mjs')].lastError).toContain('asks before running')
+  })
+
+  it('run for every plugin that listens, only once the plugin is switched on for everyone and trusted', async () => {
+    const { harness, base, call, saveFact } = setup()
+    const one = join(base, 'one.log')
+    const two = join(base, 'two.log')
+    kit(join(base, 'docs'), 'memory-to-docs', recorder(one, ['memory.saved']))
+    kit(join(base, 'sheet'), 'memory-to-sheet', recorder(two, ['memory.saved', 'history.run.ended']))
+    await call('plugins.install', { source: join(base, 'docs') })
+    const listed = await call<Plugin[]>('plugins.install', { source: join(base, 'sheet') })
+    const docs = listed.find((plugin) => plugin.id === 'package:memory-to-docs')!
+    const sheet = listed.find((plugin) => plugin.id === 'package:memory-to-sheet')!
+    // What it says it extends is kept only for parts that exist.
+    expect(docs).toMatchObject({ extends: ['memory'], runsCode: true, trust: 'untrusted', attachment: { global: false } })
+    expect(docs.contributions.map((entry) => [entry.kind, entry.name, entry.state])).toEqual([['code', 'hooks.mjs', 'off']])
+
+    // Installed, switched off, untrusted: a saved fact reaches nobody.
+    await saveFact('Use pnpm', 'Always pnpm.')
+    await harness.hooks.settled()
+    expect([told(one), told(two)]).toEqual([[], []])
+
+    // Switched on but not trusted is still nothing.
+    await call('plugins.attach', { id: docs.id })
+    await call('plugins.attach', { id: sheet.id })
+    await harness.hooks.reload()
+    await saveFact('Tabs', 'Use tabs.')
+    await harness.hooks.settled()
+    expect([told(one), told(two)]).toEqual([[], []])
+
+    // Trusted: both hear the next fact, each in its own way.
+    await call('plugins.trust', { hash: docs.code!.hash })
+    const trusted = await call<Plugin[]>('plugins.trust', { hash: sheet.code!.hash })
+    await harness.hooks.reload()
+    await saveFact('Line length', 'Wrap at 100.')
+    await harness.hooks.settled()
+    expect(told(one)).toEqual([{ type: 'memory.saved', id: expect.any(String), title: 'Line length', body: 'Wrap at 100.', actor: 'user' }])
+    expect(told(two)).toEqual(told(one))
+    expect(trusted.find((plugin) => plugin.id === docs.id)!.contributions[0]).toMatchObject({ state: 'on', problem: null })
+    const described = (await call<Plugin[]>('plugins.list')).find((plugin) => plugin.id === sheet.id)!.contributions[0]
+    expect(described.description).toBe('Runs in the background after: memory.saved, history.run.ended.')
+
+    // Switched off for everyone again, it stops hearing; the other keeps going.
+    await call('plugins.detach', { id: docs.id })
+    await harness.hooks.reload()
+    await saveFact('Indent', 'Two spaces.')
+    await harness.hooks.settled()
+    expect([told(one).length, told(two).length]).toEqual([1, 2])
+  })
+
+  it('never lets a hook that throws or hangs touch the write, and shows what went wrong on its plugin', async () => {
+    const bus = new Bus()
+    const base = temp()
+    const out = join(base, 'ok.log')
+    writeFile(join(base, 'bad.mjs'), `export default function (harness) { harness.on('memory.saved', async () => { throw new Error('the document is gone') }) }\n`)
+    writeFile(join(base, 'slow.mjs'), `export default function (harness) { harness.on('memory.saved', () => new Promise(() => {})) }\n`)
+    writeFile(join(base, 'good.mjs'), recorder(out, ['memory.saved']))
+    writeFile(join(base, 'broken.mjs'), `export const nothing = 1\n`)
+    writeFile(join(base, 'unknown.mjs'), `export default function (harness) { harness.on('memory.deleted', () => {}) }\n`)
+    const hooks = new Hooks({ stateDir: base, bus, timeoutMs: 40, importFile, call: async () => undefined, wanted: async () => ['bad', 'slow', 'good', 'broken', 'unknown'].map((name) => ({ path: join(base, `${name}.mjs`), hash: 'h1' })) })
+    await hooks.reload()
+    const event: HookEvent = { type: 'memory.saved', id: 'f1', path: '/w/facts/f1.md', title: 'Fact', body: 'Body', text: 'Body', actor: 'user', reason: 'Created', at: '2026-10-13T00:00:00.000Z' }
+    hooks.emit(event)
+    await hooks.settled()
+    // The good hook ran although two before it failed.
+    expect(told(out)).toHaveLength(1)
+    const status = hooks.status()
+    expect(status[join(base, 'bad.mjs')]).toMatchObject({ events: ['memory.saved'], lastError: 'memory.saved: the document is gone' })
+    expect(status[join(base, 'slow.mjs')].lastError).toMatch(/took longer than/)
+    expect(status[join(base, 'good.mjs')]).toMatchObject({ lastError: null, lastRunAt: expect.any(String) })
+    expect(status[join(base, 'broken.mjs')].lastError).toBe('It could not be loaded: It must export a default function.')
+    expect(status[join(base, 'unknown.mjs')].lastError).toMatch(/There is no event called "memory.deleted"/)
+    hooks.close()
+  })
+
+  it('reads a hooks file again when its code changed, and keeps the one it has when it did not', async () => {
+    const base = temp()
+    const path = join(base, 'hooks.mjs')
+    let hash = 'h1'
+    const read: string[] = []
+    const heard: string[] = []
+    // Stands in for the file on disk: each read gives the code as it is at that moment.
+    const importer = async (address: string) => {
+      read.push(address.slice(address.indexOf('?')))
+      const version = read.length
+      return { default: (harness: { on(event: string, handler: () => void): void }) => harness.on('wiki.page.saved', () => void heard.push(`version ${version}`)) }
+    }
+    const hooks = new Hooks({ stateDir: base, bus: new Bus(), call: async () => undefined, importFile: importer, wanted: async () => [{ path, hash }] })
+    const event: HookEvent = { type: 'wiki.page.saved', id: 'p1', path: '/w/library/p1.md', title: 'Page', body: 'One', text: 'One', actor: 'user', reason: 'Edited', at: '2026-10-13T00:00:00.000Z' }
+    await hooks.reload()
+    await hooks.reload()
+    hooks.emit(event)
+    await hooks.settled()
+    hash = 'h2'
+    await hooks.reload()
+    hooks.emit(event)
+    await hooks.settled()
+    // The fingerprint is part of the address, so Node does not hand back the module it already has.
+    expect(read).toEqual(['?v=h1', '?v=h2'])
+    expect(heard).toEqual(['version 1', 'version 2'])
+    hooks.close()
+  })
+
+  it('lets a hook reach a connected app only through a tool marked to run without asking', async () => {
+    const { harness } = setup()
+    await harness.apps.save({ id: 'docs', name: 'Docs', kind: 'local', command: process.execPath, args: [join(process.cwd(), 'tests/mcp-fixture.mjs')], enabled: true, global: true, readTools: ['read_record'] })
+    await harness.apps.save({ id: 'private', name: 'Private', kind: 'local', command: process.execPath, args: [join(process.cwd(), 'tests/mcp-fixture.mjs')], enabled: true, global: false, agentIds: ['a1'], readTools: ['read_record'] })
+    expect(await harness.apps.callUnattended('Docs', 'read_record', {})).toMatchObject({ content: [{ type: 'text', text: 'fixture' }] })
+    await expect(harness.apps.callUnattended('Docs', 'change_record', {})).rejects.toThrow('asks before running "change_record"')
+    // A hook runs for everyone, so an app that is on for one agent only is out of its reach.
+    await expect(harness.apps.callUnattended('Private', 'read_record', {})).rejects.toThrow('on for everyone')
+    await expect(harness.apps.callUnattended('Nope', 'read_record', {})).rejects.toThrow('no connected app called "Nope"')
+  })
+})
+
+describe('a plugin an agent proposes', () => {
+  const proposal = { name: 'Memory to Docs', description: 'Adds every saved memory to the team document.', extends: ['memory'], reason: 'You asked for a copy in Docs.', files: [{ path: 'hooks.mjs', content: "export default function (harness) { harness.on('memory.saved', async () => {}) }\n" }, { path: 'skills/docs/SKILL.md', content: '---\nname: docs\ndescription: How the copy works.\n---\nSteps.\n' }] }
+
+  it('waits in the Inbox, and is saved switched off and untrusted only when the person accepts it', async () => {
+    const { harness, root, call } = setup()
+    const tool = pluginProposeTool(harness.env, { agentId: 'a1', agentName: 'Helper', actor: 'Chat' })
+    expect(await tool.execute(proposal)).toBe('The plugin "memory-to-docs" is waiting in the Inbox. It is saved only if the user accepts it, and it does nothing until they switch it on and trust its code.')
+    expect(existsSync(join(root, 'plugins'))).toBe(false)
+    const [item] = listInbox(wikiDir(root))
+    expect(item).toMatchObject({ kind: 'proposed', title: 'Proposed plugin "Memory to Docs"' })
+    expect(item.detail).toContain('- hooks.mjs (')
+    expect(item.detail).toContain('It brings code.')
+    expect(item.detail).toContain('From Helper (Chat).')
+
+    expect(await call<string>('wiki.inboxAccept', { itemId: item.id })).toBe('Saved the plugin "memory-to-docs", switched off. Its code does not run until you switch it on and trust it.')
+    expect(readdirSync(join(root, 'plugins'))).toEqual(['memory-to-docs'])
+    expect(JSON.parse(readFileSync(join(root, 'plugins/memory-to-docs/package.json'), 'utf8'))).toMatchObject({ name: 'memory-to-docs', description: proposal.description, harness: { extends: ['memory'], hooks: './hooks.mjs' } })
+    const plugin = (await call<Plugin[]>('plugins.list')).find((candidate) => candidate.id === 'package:memory-to-docs')!
+    expect(plugin).toMatchObject({ extends: ['memory'], trust: 'untrusted', install: { kind: 'folder' }, attachment: { global: false } })
+    expect(plugin.contributions.map((entry) => [entry.kind, entry.name, entry.state])).toEqual([['skill', 'docs', 'off'], ['code', 'hooks.mjs', 'off']])
+    await harness.hooks.reload()
+    expect(Object.keys(harness.hooks.status())).toEqual([])
+    // Accepting the same proposal again would overwrite a folder, so it is refused.
+    await tool.execute(proposal)
+    await expect(call('wiki.inboxAccept', { itemId: listInbox(wikiDir(root))[0].id })).rejects.toThrow('already a plugin folder')
+  })
+
+  it('refuses what could not be a safe plugin, and says why', () => {
+    const bad = (change: Partial<typeof proposal>) => () => checkPluginProposal({ ...proposal, ...change })
+    expect(bad({ name: '  ' })).toThrow('short name')
+    expect(bad({ description: '' })).toThrow('one line')
+    expect(bad({ extends: ['approvals'] })).toThrow('"approvals" is none of them')
+    expect(bad({ files: [] })).toThrow('between 1 and 40 files')
+    expect(bad({ files: [{ path: '../outside.mjs', content: 'x' }] })).toThrow('not a path inside the plugin')
+    expect(bad({ files: [{ path: '/etc/hosts', content: 'x' }] })).toThrow('not a path inside the plugin')
+    expect(bad({ files: [{ path: '.env', content: 'x' }] })).toThrow('cannot be part of a plugin')
+    expect(bad({ files: [{ path: 'node_modules/x/index.js', content: 'x' }] })).toThrow('cannot be part of a plugin')
+    expect(bad({ files: [{ path: 'package.json', content: '{}' }] })).toThrow('Leave package.json out')
+    expect(bad({ files: [{ path: 'a.md', content: 'x' }, { path: 'A.md', content: 'y' }] })).toThrow('listed twice')
+    expect(bad({ files: [{ path: 'big.md', content: 'x'.repeat(300 * 1024) }] })).toThrow('larger than 256 KiB')
+    expect(checkPluginProposal({ ...proposal, files: [{ path: './skills/a/SKILL.md', content: 'x' }] })).toMatchObject({ slug: 'memory-to-docs', hooks: null, runsCode: false })
+  })
+})

package/src/plugins/hooks.ts

@@ -0,0 +1,239 @@
+// Hooks: code a plugin gives the harness to run after something changed. A Pi extension lives
+// only while a session is open, and most memory is written outside one (a person accepts an
+// Inbox item, edits a fact, the background upkeep runs), so these are the harness's own events,
+// delivered in its own process.
+//
+// A hook is told after the fact. It cannot stop or change a write, it runs with a time limit,
+// and what it throws is recorded and shown on its plugin. It reaches outside only through
+// `ctx.call`, which the harness limits to connected-app tools a person marked to run without asking.
+import { chmodSync } from 'node:fs'
+import { join, sep } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import type { Bus } from '../core/bus'
+import { log } from '../core/bus'
+import { onChange, type Change } from '../core/changes'
+import * as frontmatter from '../core/frontmatter'
+import { now, readJsonOr, writeJson } from '../core/fs'
+
+export const HOOK_EVENTS = ['memory.saved', 'memory.block.changed', 'wiki.page.saved', 'history.run.ended'] as const
+export type HookEventType = (typeof HOOK_EVENTS)[number]
+
+/** A fact, a memory block, or a page, as it is after the change. */
+export interface EntryEvent {
+  type: 'memory.saved' | 'memory.block.changed' | 'wiki.page.saved'
+  id: string
+  path: string
+  title: string
+  /** The entry without its front matter. */
+  body: string
+  /** The whole file. */
+  text: string
+  /** Who made the change: `user`, an agent's name, or the background upkeep. */
+  actor: string
+  reason: string
+  at: string
+}
+
+export interface RunEndedEvent {
+  type: 'history.run.ended'
+  runId: string
+  sessionId: string
+  status: string
+  goal: string | null
+  agentId: string | null
+  projectId: string | null
+  startedAt: string
+  endedAt: string | null
+  at: string
+}
+
+export type HookEvent = EntryEvent | RunEndedEvent
+
+export interface HookContext {
+  /** Calls a tool of a connected app that is on for everyone, if a person marked that tool to run without asking. */
+  call(connection: string, tool: string, args?: Record<string, unknown>): Promise<unknown>
+  log(message: string): void
+}
+
+type Handler = (event: HookEvent, context: HookContext) => unknown
+
+/** What a hooks file is given: `export default function (harness) { harness.on('memory.saved', …) }`. */
+export interface HookApi {
+  on(event: HookEventType, handler: Handler): void
+}
+
+export interface HookTarget {
+  /** The hooks file. */
+  path: string
+  /** A hash of the package's code, so a changed file is loaded again. */
+  hash: string
+}
+
+export interface HookStatus {
+  /** The events it listens for. */
+  events: string[]
+  lastRunAt: string | null
+  /** Why it could not be loaded, or what its last failing run threw. */
+  lastError: string | null
+}
+
+export interface HooksOptions {
+  stateDir: string
+  bus: Bus
+  /** The hooks files that should run now: attached for everyone, and trusted. */
+  wanted: () => Promise<HookTarget[]>
+  call: HookContext['call']
+  /** How long one handler may take. */
+  timeoutMs?: number
+  /** Reads a hooks file as a module. Replaced in tests, where the runner owns `import()`. */
+  importFile?: (address: string) => Promise<unknown>
+}
+
+// Node's own `import()`, out of reach of a bundler or a test runner that would rewrite it: a hooks
+// file is a person's file on disk, loaded as it is, and its address must reach Node unchanged.
+const importFile = new Function('address', 'return import(address)') as (address: string) => Promise<unknown>
+
+interface Loaded extends HookTarget {
+  handlers: Map<string, Handler[]>
+}
+
+/** Which event a written file is, from where it is in the Wiki. */
+export function entryEvent(change: Change): EntryEvent {
+  const within = change.path.startsWith(`${change.wiki}${sep}`) ? change.path.slice(change.wiki.length + 1).split(sep) : []
+  const type = within[0] === 'facts' ? 'memory.saved' : within[0] === 'blocks' ? 'memory.block.changed' : 'wiki.page.saved'
+  const parsed = frontmatter.parse(change.text)
+  const front = (parsed?.front ?? {}) as Record<string, unknown>
+  const title = typeof front.title === 'string' ? front.title : typeof front.label === 'string' ? front.label : change.id
+  return { type, id: change.id, path: change.path, title, body: (parsed?.body ?? change.text).trim(), text: change.text, actor: change.actor, reason: change.reason, at: now() }
+}
+
+export class Hooks {
+  private loaded: Loaded[] = []
+  private readonly queue: HookEvent[] = []
+  private working: Promise<void> = Promise.resolve()
+  private reloading: Promise<void> = Promise.resolve()
+  private readonly statusPath: string
+  private wiki: string | null = null
+  private readonly stop: () => void
+
+  constructor(private readonly options: HooksOptions) {
+    this.statusPath = join(options.stateDir, 'plugin-hooks.json')
+    this.stop = onChange((change) => {
+      // Several harnesses can share a process; each hears only about its own Wiki.
+      if (change.wiki === this.wiki) this.emit(entryEvent(change))
+    })
+  }
+
+  /** The Wiki whose changes these hooks hear about. */
+  watch(wiki: string | null): void {
+    this.wiki = wiki
+  }
+
+  /** What each hooks file listens for, and how its last run went. */
+  status(): Record<string, HookStatus> {
+    return readJsonOr<Record<string, HookStatus>>(this.statusPath, {})
+  }
+
+  private record(path: string, change: Partial<HookStatus>): void {
+    const all = this.status()
+    const before = all[path] ?? { events: [], lastRunAt: null, lastError: null }
+    const next = { ...before, ...change }
+    if (JSON.stringify(before) === JSON.stringify(next) && all[path]) return
+    all[path] = next
+    writeJson(this.statusPath, all)
+    chmodSync(this.statusPath, 0o600)
+    // A new failure, or a failure that cleared, is something a person looking at the plugin should see.
+    if (before.lastError !== next.lastError || before.events.join() !== next.events.join()) this.options.bus.emit({ type: 'plugins.changed' })
+  }
+
+  /** Loads the hooks files that should run and drops the ones that should not. Safe to call often. */
+  reload(): Promise<void> {
+    this.reloading = this.reloading.then(async () => {
+      let wanted: HookTarget[]
+      try {
+        wanted = await this.options.wanted()
+      } catch (error) {
+        log('plugin hooks', error instanceof Error ? error.message : String(error))
+        return
+      }
+      const next: Loaded[] = []
+      for (const target of wanted) {
+        const kept = this.loaded.find((hook) => hook.path === target.path && hook.hash === target.hash)
+        if (kept) {
+          next.push(kept)
+          continue
+        }
+        const handlers = new Map<string, Handler[]>()
+        try {
+          // The hash is part of the address, so a changed file is read again and not served from the module cache.
+          const module = (await (this.options.importFile ?? importFile)(`${pathToFileURL(target.path).href}?v=${target.hash}`)) as { default?: unknown }
+          if (typeof module.default !== 'function') throw new Error('It must export a default function.')
+          const api: HookApi = {
+            on: (event, handler) => {
+              if (!(HOOK_EVENTS as readonly string[]).includes(event)) throw new Error(`There is no event called "${String(event)}". The events are ${HOOK_EVENTS.join(', ')}.`)
+              if (typeof handler !== 'function') throw new Error('A handler must be a function.')
+              handlers.set(event, [...(handlers.get(event) ?? []), handler])
+            }
+          }
+          await (module.default as (api: HookApi) => unknown)(api)
+          next.push({ ...target, handlers })
+          this.record(target.path, { events: [...handlers.keys()], lastError: null })
+        } catch (error) {
+          this.record(target.path, { events: [], lastError: `It could not be loaded: ${error instanceof Error ? error.message : String(error)}` })
+        }
+      }
+      this.loaded = next
+    })
+    return this.reloading
+  }
+
+  /** Takes an event down. It is delivered afterwards, in the order events arrived. */
+  emit(event: HookEvent): void {
+    this.queue.push(event)
+    this.working = this.working.then(() => this.drain())
+  }
+
+  private async drain(): Promise<void> {
+    // A file can change on disk without anyone telling the harness. What is loaded is checked
+    // against what should run before it is told anything, so code that changed since it was
+    // trusted stops here. With nothing loaded there is nothing to check: a new hook arrives
+    // with a `plugins.changed` notice.
+    if (this.loaded.length) await this.reload()
+    else await this.reloading
+    for (let event = this.queue.shift(); event; event = this.queue.shift()) {
+      for (const hook of this.loaded) {
+        for (const handler of hook.handlers.get(event.type) ?? []) await this.run(hook, handler, event)
+      }
+    }
+  }
+
+  private async run(hook: Loaded, handler: Handler, event: HookEvent): Promise<void> {
+    const context: HookContext = { call: this.options.call, log: (message) => log(`plugin hook ${hook.path}`, String(message)) }
+    let timer: ReturnType<typeof setTimeout> | undefined
+    try {
+      await Promise.race([
+        Promise.resolve().then(() => handler(event, context)),
+        new Promise((_, reject) => {
+          timer = setTimeout(() => reject(new Error(`It took longer than ${Math.round((this.options.timeoutMs ?? 30_000) / 1000)} seconds and was left behind.`)), this.options.timeoutMs ?? 30_000)
+        })
+      ])
+      this.record(hook.path, { lastRunAt: now(), lastError: null })
+    } catch (error) {
+      this.record(hook.path, { lastRunAt: now(), lastError: `${event.type}: ${error instanceof Error ? error.message : String(error)}`.slice(0, 1000) })
+    } finally {
+      if (timer) clearTimeout(timer)
+    }
+  }
+
+  /** Resolves when every event taken down so far was delivered. */
+  async settled(): Promise<void> {
+    await this.reloading
+    await this.working
+  }
+
+  close(): void {
+    this.stop()
+    this.loaded = []
+  }
+}

package/src/plugins/identity.ts

@@ -0,0 +1,37 @@
+// Which plugin a found file belongs to, and what it is called there. The list a person sees and
+// the choice of what loads both use this, so a switch on the page names exactly what stops loading.
+import { basename, dirname } from 'node:path'
+
+import * as registry from '../skills/registry'
+import { BUILTIN_PREFIX, type Found } from './discover'
+import { packageManifest } from './manifest'
+import type { ContributionKind } from './types'
+
+export { packageManifest } from './manifest'
+
+export const FOUND_KINDS: Record<Found['kind'], ContributionKind> = { extension: 'code', hook: 'code', skill: 'skill', prompt: 'command', theme: 'theme', context: 'instruction' }
+
+/** The id of the plugin a found item is listed under. */
+export function pluginIdOf(item: Found): string {
+  if (item.origin === 'builtin') return 'pi'
+  if (item.packageRoot) return `package:${packageManifest(item.packageRoot).name}`
+  return item.origin === 'home' ? 'home' : item.origin === 'project' ? 'project' : 'shared'
+}
+
+/** A found item's name and description as a person reads them. */
+export function describeFound(item: Found): { name: string; description: string | null } {
+  if (item.path.startsWith(BUILTIN_PREFIX)) return { name: item.path.slice(BUILTIN_PREFIX.length), description: null }
+  const file = basename(item.path)
+  if (item.kind === 'extension') return { name: file.startsWith('index.') ? basename(dirname(item.path)) : file, description: null }
+  if (item.kind === 'context' || item.kind === 'theme' || item.kind === 'hook') return { name: file, description: null }
+  const described = registry.describeFile(item.path)
+  return { name: described?.name ?? file, description: described?.description ?? '' }
+}
+
+export const contributionId = (pluginId: string, kind: ContributionKind, name: string): string => `${pluginId}/${kind}/${name}`
+
+/** The ids a choice about a found item is stored under: the item itself, then its plugin. */
+export function foundIds(item: Found): [string, string] {
+  const pluginId = pluginIdOf(item)
+  return [contributionId(pluginId, FOUND_KINDS[item.kind], describeFound(item).name), pluginId]
+}

package/src/plugins/install.test.ts

@@ -0,0 +1,107 @@
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { sharedDir } from '../accounts/env'
+import { memorySecretStore } from '../accounts/secrets'
+import { createHarness, type Harness } from '../harness'
+import { methods } from '../server/methods'
+import { rootWithProject, writeFile } from '../../tests/helpers'
+import { normalizeSource } from './install'
+import type { Plugin } from './types'
+
+const open: Harness[] = []
+afterEach(async () => {
+  for (const harness of open.splice(0)) await harness.close()
+})
+
+function setup() {
+  const root = rootWithProject()
+  const base = mkdtempSync(join(tmpdir(), 'install-'))
+  const harness = createHarness({ dataRoot: root, stateDir: join(base, 'state'), secrets: memorySecretStore() })
+  open.push(harness)
+  harness.accounts.create('Main', 'apiKey')
+  const agentDir = harness.accounts.context(harness.accounts.resolve(null, null)).configDir
+  const table = methods(harness)
+  const call = <T>(method: string, params: Record<string, unknown> = {}) => table[method](params) as Promise<T>
+  const loaded = async () => {
+    const loading = await harness.plugins.loading({ cwd: base, agentDir, caller: {} })
+    return { extensions: loading.extensionPaths.map((path) => path.replace(`${base}/`, '')), skills: loading.skillPaths.map((path) => path.replace(`${base}/`, '')) }
+  }
+  return { harness, root, base, call, loaded }
+}
+
+function kit(folder: string): void {
+  writeFile(join(folder, 'package.json'), JSON.stringify({ name: 'review-kit', description: 'Review helpers.', version: '1.0.0' }))
+  writeFile(join(folder, 'extensions/guard.ts'), 'export default function () {}\n')
+  writeFile(join(folder, 'skills/audit/SKILL.md'), '---\nname: audit\ndescription: Audit a change.\n---\nSteps.\n')
+}
+
+describe('installing a package', () => {
+  it('reads a name as an npm package, keeps a folder or an address as it is, and refuses a relative path', () => {
+    expect(normalizeSource(' pi-tools ')).toBe('npm:pi-tools')
+    expect(normalizeSource('npm:@scope/pi-tools@1.0.0')).toBe('npm:@scope/pi-tools@1.0.0')
+    expect(normalizeSource('git:github.com/example/pi-tools@v1')).toBe('git:github.com/example/pi-tools@v1')
+    expect(normalizeSource('https://github.com/example/pi-tools')).toBe('https://github.com/example/pi-tools')
+    expect(normalizeSource('/tmp/kit/')).toBe('/tmp/kit')
+    expect(() => normalizeSource('./kit')).toThrow('whole path')
+    expect(() => normalizeSource('  ')).toThrow()
+  })
+
+  it('arrives switched off and untrusted, and loads only once it is both switched on and trusted', async () => {
+    const { harness, base, call, loaded } = setup()
+    kit(join(base, 'kit'))
+    const after = await call<Plugin[]>('plugins.install', { source: join(base, 'kit') })
+    const plugin = after.find((candidate) => candidate.id === 'package:review-kit')!
+    expect(plugin).toMatchObject({ source: 'package', version: '1.0.0', runsCode: true, trust: 'untrusted', install: { kind: 'settings', source: join(base, 'kit') }, attachment: { global: false } })
+    expect(plugin.contributions.map((entry) => `${entry.kind}:${entry.name}:${entry.state}`)).toEqual(['code:guard.ts:off', 'skill:audit:off'])
+    // It is named in the settings every account shares, as `pi install` would have done.
+    expect(JSON.parse(readFileSync(join(sharedDir(harness.accounts.dir), 'settings.json'), 'utf8')).packages).toEqual([join(base, 'kit')])
+    expect(await loaded()).toEqual({ extensions: [], skills: [] })
+
+    // Switched on, its text loads; its code still waits for trust.
+    await call('plugins.attach', { id: plugin.id })
+    expect(await loaded()).toEqual({ extensions: [], skills: ['kit/skills/audit/SKILL.md'] })
+    const trusted = await call<Plugin[]>('plugins.trust', { hash: plugin.code!.hash })
+    expect(trusted.find((candidate) => candidate.id === plugin.id)).toMatchObject({ trust: 'trusted' })
+    expect(await loaded()).toEqual({ extensions: ['kit/extensions/guard.ts'], skills: ['kit/skills/audit/SKILL.md'] })
+
+    // A stale fingerprint is refused, and changed code waits again.
+    writeFileSync(join(base, 'kit/extensions/guard.ts'), 'export default function () { /* changed */ }\n')
+    await expect(call('plugins.trust', { hash: plugin.code!.hash })).rejects.toThrow('changed since it was shown')
+    expect((await loaded()).extensions).toEqual([])
+
+    const removed = await call<Plugin[]>('plugins.remove', { pluginId: plugin.id })
+    expect(removed.some((candidate) => candidate.id === plugin.id)).toBe(false)
+    expect(JSON.parse(readFileSync(join(sharedDir(harness.accounts.dir), 'settings.json'), 'utf8')).packages ?? []).toEqual([])
+    // A folder that was installed in place is not deleted with its entry.
+    expect(existsSync(join(base, 'kit/package.json'))).toBe(true)
+    expect(await loaded()).toEqual({ extensions: [], skills: [] })
+  })
+
+  it('refuses a folder that is not there, and a plugin that was not installed', async () => {
+    const { base, call } = setup()
+    await expect(call('plugins.install', { source: join(base, 'missing') })).rejects.toThrow('does not exist')
+    await expect(call('plugins.remove', { pluginId: 'memory' })).rejects.toThrow('was not installed as a package')
+    await expect(call('plugins.update', { pluginId: 'nope' })).rejects.toThrow()
+  })
+
+  it('finds a package kept as a folder beside the data, and moves it to the trash when removed', async () => {
+    const { root, call, loaded, harness } = setup()
+    // Trust has been asked per package before this folder appears, so its code waits.
+    harness.plugins.trust.adopt([])
+    kit(join(root, 'plugins/review-kit'))
+    mkdirSync(join(root, 'plugins/.hidden'), { recursive: true })
+    const plugins = await call<Plugin[]>('plugins.list')
+    const plugin = plugins.find((candidate) => candidate.id === 'package:review-kit')!
+    expect(plugin).toMatchObject({ trust: 'untrusted', install: { kind: 'folder', source: join(root, 'plugins/review-kit') }, attachment: { global: true } })
+    expect((await loaded()).skills.some((path) => path.endsWith('plugins/review-kit/skills/audit/SKILL.md'))).toBe(true)
+    expect((await loaded()).extensions).toEqual([])
+    await expect(call('plugins.update', { pluginId: plugin.id })).rejects.toThrow('is a folder on this machine')
+
+    await call('plugins.remove', { pluginId: plugin.id })
+    expect(existsSync(join(root, 'plugins/review-kit'))).toBe(false)
+    expect(readdirSync(join(root, 'trash/plugins')).some((name) => name.startsWith('review-kit-'))).toBe(true)
+  })
+})