@xingular/harness 2.0.0 → 2.0.1-unstable

package/src/plugins/hooks.test.ts

@@ -1,250 +0,0 @@
-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

@@ -1,239 +0,0 @@
-// 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

@@ -1,37 +0,0 @@
-// 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

@@ -1,107 +0,0 @@
-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)
-  })
-})