@xingular/harness 0.0.0-stage → 0.1.0

package/src/plugins/plugins.ts

@@ -0,0 +1,184 @@
+// The harness decides what a Pi session loads. Pi's own discovery is switched off for sessions
+// and terminals; they receive the paths chosen here, so nothing reaches a model unlisted.
+import { chmodSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { Bus } from '../core/bus'
+import { now, readJsonOr, writeJson } from '../core/fs'
+import { removeLinkedSkills } from '../skills/registry'
+import { attached, type Attachments, type AttachScope } from './attachments'
+import { piResolver, type Found, type ResolveInput, type Resolver } from './discover'
+import { foundIds, pluginIdOf } from './identity'
+import { packageCode, projectCode, Trust, type ProjectCode } from './trust'
+
+/** What one session or terminal loads besides the registry's own items. */
+export interface Loading {
+  /** Extension files and folders, in the order Pi would have loaded them. */
+  extensionPaths: string[]
+  skillPaths: string[]
+  promptPaths: string[]
+  themePaths: string[]
+  /** The `pi` command's own extensions left on, as `builtin:<name>`. Only a terminal has them. */
+  builtins: string[]
+  /** Hooks files the harness runs itself. Pi is never given them. */
+  hooks: { path: string; packageRoot: string; hash: string }[]
+  /** Everything found, loaded or not. */
+  found: Found[]
+  /** Paths of found items a person switched off for this caller. */
+  detached: string[]
+  /** Applies the same attachment policy to resources supplied by a trusted extension. */
+  resourceAllowed?: (item: Found) => boolean
+  /** Code the working folder brings, and whether a person trusted it. */
+  projectCode: (ProjectCode & { trusted: boolean }) | null
+  /** Each installed package that brings code, by its folder, and whether a person trusted it. */
+  packageCode: Record<string, ProjectCode & { trusted: boolean }>
+}
+
+/** What one loaded extension added to a session. */
+export interface Registered {
+  path: string
+  hooks: string[]
+  tools: string[]
+  commands: string[]
+  flags: string[]
+  shortcuts: string[]
+  /** Fingerprint at observation time; stale registrations are not presented as current. */
+  hash?: string | null
+  seenAt?: string
+  resources?: RuntimeResource[]
+}
+
+export interface RuntimeResource {
+  kind: 'skill' | 'command' | 'theme'
+  name: string
+  path: string
+  chars: number | null
+}
+
+export interface PluginsOptions {
+  stateDir: string
+  bus: Bus
+  resolver?: Resolver
+  /** The choices a person made about what is switched on, or `null` while there is no data root. */
+  attachments?: () => Attachments | null
+  /** The folder of packages kept with a person's data, or `null` while there is no data root. */
+  packagesDir?: () => string | null
+}
+
+/** The package folders inside a folder: each direct child that is a folder and not hidden. */
+export function packageFolders(directory: string | null): string[] {
+  if (!directory) return []
+  try {
+    return readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith('.')).map((entry) => join(directory, entry.name)).sort()
+  } catch {
+    return []
+  }
+}
+
+export interface LoadingInput extends ResolveInput {
+  /** Who the session is for. Something switched off for this agent or project does not load. */
+  caller?: AttachScope
+}
+
+/** Which code a person trusted: the working folder's as a whole, and each installed package's. */
+export interface Trusted {
+  project: boolean
+  /** Folders of installed packages whose code is not trusted. */
+  untrustedPackages: ReadonlySet<string>
+}
+
+export const trustedBy = (loading: Pick<Loading, 'projectCode' | 'packageCode'> | null): Trusted => ({
+  project: !!loading?.projectCode?.trusted,
+  untrustedPackages: new Set(Object.entries(loading?.packageCode ?? {}).filter(([, code]) => !code.trusted).map(([root]) => root))
+})
+
+/**
+ * Whether a found item loads: it is on in Pi's settings, and if it is code, a person trusted it.
+ * A loose file in the shared folder was put there by hand and needs no trust. Text always loads.
+ */
+export function loads(item: Found, trusted: Trusted): boolean {
+  if (!item.enabled) return false
+  if (item.kind !== 'extension' && item.kind !== 'hook') return true
+  if (item.project) return trusted.project
+  return !(item.packageRoot && trusted.untrustedPackages.has(item.packageRoot))
+}
+
+/**
+ * Whether a person left a found item switched on for a caller. Pi reads its instruction files
+ * itself and its command owns its built-in extensions, so neither can be switched off here.
+ */
+export function switchable(item: Found): boolean {
+  return item.kind !== 'context' && item.origin !== 'builtin'
+}
+
+export class Plugins {
+  readonly trust: Trust
+  private readonly resolver: Resolver
+  private readonly registeredPath: string
+
+  constructor(private readonly options: PluginsOptions) {
+    this.trust = new Trust(options.stateDir, options.bus)
+    this.resolver = options.resolver ?? piResolver
+    this.registeredPath = join(options.stateDir, 'plugin-registered.json')
+  }
+
+  /** Finds what Pi would load in this folder, and chooses what does. */
+  async loading(input: LoadingInput): Promise<Loading> {
+    // Links an earlier version put in the shared skills folder would be found as skills again.
+    removeLinkedSkills(join(input.agentDir, 'skills'))
+    const found = await this.resolver({ ...input, packages: packageFolders(this.options.packagesDir?.() ?? null) })
+    const code = projectCode(found, input.cwd)
+    const packages = packageCode(found)
+    // Packages that loaded before trust was asked per package keep loading: they are taken over once.
+    if (!this.trust.adopted) this.trust.adopt([...packages].map(([folder, packaged]) => ({ code: packaged, folder })))
+    const trustedHashes = new Set(this.trust.list().map((record) => record.hash))
+    const projectCodeState = code ? { ...code, trusted: trustedHashes.has(code.hash) } : null
+    const packageCodeState = Object.fromEntries([...packages].map(([folder, packaged]) => [folder, { ...packaged, trusted: trustedHashes.has(packaged.hash) }]))
+    const trusted = trustedBy({ projectCode: projectCodeState, packageCode: packageCodeState })
+    const choices = this.options.attachments?.() ?? null
+    const off = (item: Found): boolean => {
+      if (!choices || !switchable(item)) return false
+      // A hook runs for everyone or not at all, so only its plugin's switch for everyone counts.
+      if (item.kind === 'hook') return !attached(choices, [pluginIdOf(item)], {}, true)
+      return !attached(choices, foundIds(item), input.caller ?? {}, true)
+    }
+    const detached = found.filter(off).map((item) => item.path)
+    const chosen = found.filter((item) => loads(item, trusted) && !detached.includes(item.path))
+    const paths = (kind: Found['kind'], builtin: boolean): string[] => chosen.filter((item) => item.kind === kind && (item.origin === 'builtin') === builtin).map((item) => item.path)
+    return {
+      extensionPaths: paths('extension', false),
+      skillPaths: paths('skill', false),
+      promptPaths: paths('prompt', false),
+      themePaths: paths('theme', false),
+      builtins: paths('extension', true),
+      hooks: chosen.filter((item) => item.kind === 'hook' && item.packageRoot).map((item) => ({ path: item.path, packageRoot: item.packageRoot!, hash: packageCodeState[item.packageRoot!]?.hash ?? '' })),
+      found,
+      detached,
+      resourceAllowed: (item) => !off(item),
+      projectCode: projectCodeState,
+      packageCode: packageCodeState
+    }
+  }
+
+  /** What each extension registered the last time a session loaded it. */
+  registered(): Record<string, Registered & { seenAt: string }> {
+    return readJsonOr<Record<string, Registered & { seenAt: string }>>(this.registeredPath, {})
+  }
+
+  /** Records what a session's extensions registered, so the list can show it without loading code. */
+  loaded(extensions: readonly Registered[]): void {
+    if (!extensions.length) return
+    const stored = this.registered()
+    let changed = false
+    for (const extension of extensions) {
+      const { seenAt: _seenAt, ...before } = stored[extension.path] ?? ({} as Registered & { seenAt: string })
+      if (JSON.stringify(before) === JSON.stringify(extension)) continue
+      stored[extension.path] = { ...extension, seenAt: now() }
+      changed = true
+    }
+    if (!changed) return
+    writeJson(this.registeredPath, stored)
+    chmodSync(this.registeredPath, 0o600)
+    this.options.bus.emit({ type: 'plugins.changed' })
+  }
+}

package/src/plugins/proposal.ts

@@ -0,0 +1,121 @@
+// A plugin an agent wrote for a person to consider. Nothing here installs anything on its own:
+// the proposal waits in the Inbox; accepting it writes a package beside the person's data,
+// switched off and (when it brings code) untrusted. The person then reads it, switches it on,
+// and trusts it. No agent has a tool for either of those.
+import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { z } from 'zod'
+
+import { invalid } from '../core/errors'
+import { now, safeRelative, writeJson } from '../core/fs'
+import { slugify } from '../core/projects'
+import { inbox } from '../memory/operations'
+import { looksSecret } from '../memory/secrets'
+import * as store from '../memory/store'
+import * as attachments from './attachments'
+
+/** The parts a plugin can say it extends. */
+export const EXTENDABLE = ['memory', 'wiki', 'history'] as const
+
+const MAX_FILES = 40
+const MAX_BYTES = 256 * 1024
+const HOOKS_FILES = ['hooks.mjs', 'hooks.js']
+
+export const pluginProposalSchema = z.object({
+  name: z.string(),
+  description: z.string().default(''),
+  extends: z.array(z.string()).default([]),
+  reason: z.string().default(''),
+  files: z.array(z.object({ path: z.string(), content: z.string() }))
+})
+export type PluginProposal = z.infer<typeof pluginProposalSchema>
+
+interface Checked {
+  slug: string
+  extends: string[]
+  hooks: string | null
+  runsCode: boolean
+  files: { path: string; content: string }[]
+}
+
+/** The proposal with its paths made safe, or the reason it cannot be a plugin. */
+export function checkPluginProposal(proposal: PluginProposal): Checked {
+  const name = proposal.name.trim()
+  const slug = slugify(name)
+  if (!name || slug.startsWith('page-') || name.length > 64) throw invalid('Give the plugin a short name of letters and numbers.')
+  if (!proposal.description.trim()) throw invalid('Say in one line what the plugin does; that line is what the user sees first.')
+  const unknown = proposal.extends.find((part) => !(EXTENDABLE as readonly string[]).includes(part))
+  if (unknown !== undefined) throw invalid(`A plugin can extend ${EXTENDABLE.join(', ')}; "${unknown}" is none of them.`)
+  if (!proposal.files.length || proposal.files.length > MAX_FILES) throw invalid(`A plugin needs between 1 and ${MAX_FILES} files.`)
+  const files: Checked['files'] = []
+  let bytes = 0
+  for (const file of proposal.files) {
+    let path: string
+    try {
+      path = safeRelative(file.path.replace(/^\.\//, ''))
+    } catch {
+      throw invalid(`"${file.path}" is not a path inside the plugin.`)
+    }
+    const parts = path.split('/')
+    if (parts.some((part) => part.startsWith('.') || part.includes(':') || part === 'node_modules')) throw invalid(`"${file.path}" cannot be part of a plugin.`)
+    if (path === 'package.json') throw invalid('Leave package.json out; it is written from the name and description you gave.')
+    if (files.some((existing) => existing.path.toLowerCase() === path.toLowerCase())) throw invalid(`"${file.path}" is listed twice.`)
+    bytes += Buffer.byteLength(file.content, 'utf8')
+    if (bytes > MAX_BYTES) throw invalid('The plugin is larger than 256 KiB.')
+    if (looksSecret(file.content)) throw invalid(`"${file.path}" contains text that looks like a credential. A plugin reaches outside through a connected app, never with a key of its own.`)
+    files.push({ path, content: file.content })
+  }
+  const hooks = files.find((file) => HOOKS_FILES.includes(file.path))?.path ?? null
+  return { slug, extends: [...new Set(proposal.extends)], hooks, runsCode: hooks !== null || files.some((file) => file.path.startsWith('extensions/')), files }
+}
+
+/** Puts a proposed plugin in the Inbox, for a person to read before anything is written. */
+export function parkPluginProposal(wiki: string, from: string, proposal: PluginProposal): string {
+  const checked = checkPluginProposal(proposal)
+  const listed = checked.files.map((file) => `- ${file.path} (${file.content.length} characters)`).join('\n')
+  const code = checked.runsCode ? '\n\nIt brings code. Accepting only saves the files: the code runs after you also switch the plugin on and trust it.' : ''
+  inbox(
+    wiki,
+    'proposed',
+    `Proposed plugin "${proposal.name.trim()}"`,
+    `${proposal.description.trim()}\n\n${proposal.reason.trim() || 'Review it before it is saved.'}${checked.extends.length ? `\n\nExtends: ${checked.extends.join(', ')}.` : ''}\n\nFiles:\n${listed}${code}\n\nFrom ${from}.`,
+    [],
+    null,
+    { kind: 'plugin', proposal: { ...proposal, files: checked.files }, trigger: from }
+  )
+  store.log(wiki, `- ${now()} · ${from} · proposed plugin \`${checked.slug}\` · waiting in Inbox`)
+  return checked.slug
+}
+
+/** Writes an accepted proposal as a package beside the person's data, switched off everywhere. */
+export function acceptPluginProposal(root: string, proposal: PluginProposal): string {
+  const checked = checkPluginProposal(proposal)
+  const directory = join(root, 'plugins')
+  const target = join(directory, checked.slug)
+  if (existsSync(target)) throw invalid(`There is already a plugin folder called "${checked.slug}". Remove it or rename the proposal.`)
+  mkdirSync(directory, { recursive: true })
+  // Written beside its place and moved in whole, so a half-written plugin is never found.
+  const staging = mkdtempSync(join(directory, '.accepting-'))
+  try {
+    writeJson(join(staging, 'package.json'), {
+      name: checked.slug,
+      version: '0.1.0',
+      description: proposal.description.trim(),
+      keywords: ['pi-package'],
+      ...(checked.extends.length || checked.hooks ? { harness: { ...(checked.extends.length ? { extends: checked.extends } : {}), ...(checked.hooks ? { hooks: `./${checked.hooks}` } : {}) } } : {})
+    })
+    for (const file of checked.files) {
+      const path = join(staging, ...file.path.split('/'))
+      mkdirSync(dirname(path), { recursive: true })
+      writeFileSync(path, file.content, { flag: 'wx' })
+    }
+    renameSync(staging, target)
+  } catch (error) {
+    rmSync(staging, { recursive: true, force: true })
+    throw error
+  }
+  const choices = attachments.load(root)
+  attachments.set(choices, [`package:${checked.slug}`], {}, false, true)
+  attachments.save(root, choices)
+  return `Saved the plugin "${checked.slug}", switched off.${checked.runsCode ? ' Its code does not run until you switch it on and trust it.' : ' Switch it on to use it.'}`
+}

package/src/plugins/runtime.test.ts

@@ -0,0 +1,40 @@
+import { mkdtempSync, symlinkSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { expect, it } from 'vitest'
+import type * as Pi from '@earendil-works/pi-coding-agent'
+
+import { writeFile } from '../../tests/helpers'
+import type { Found } from './discover'
+import type { Loading, Registered } from './plugins'
+import { observeResources } from './runtime'
+
+it('expands theme directories, filters individual files and replaces each handler observation', async () => {
+  const pi = await import('@earendil-works/pi-coding-agent')
+  const base = mkdtempSync(join(tmpdir(), 'resource-observation-'))
+  const path = join(base, 'extension.ts')
+  writeFile(path, 'export default function() {}')
+  const first = join(base, 'themes/first.json')
+  const second = join(base, 'themes/second.json')
+  writeFile(first, '{}')
+  writeFile(second, '{}')
+  symlinkSync(join(base, 'absent.json'), join(base, 'themes/broken.json'))
+  writeFile(join(base, 'review.md'), '---\nname: runtime-review\ndescription: Review.\n---\nReview text.')
+  let active = true
+  const handlers = new Map([['resources_discover', [async () => active ? { themePaths: ['./themes'] } : undefined, async () => ({ promptPaths: ['./review.md'] })]]])
+  const extension = { path, resolvedPath: path, handlers }
+  const loader = { getExtensions: () => ({ extensions: [extension] }) } as unknown as Pi.DefaultResourceLoader
+  const owner: Found = { kind: 'extension', path, origin: 'shared', project: false, packageRoot: null, source: null, enabled: true }
+  const loading: Loading = { extensionPaths: [path], skillPaths: [], promptPaths: [], themePaths: [], builtins: [], hooks: [], found: [owner], detached: [], projectCode: null, packageCode: {}, resourceAllowed: (item) => item.path !== first }
+  const records: Registered[] = [{ path, tools: [], commands: [], hooks: ['resources_discover'], flags: [], shortcuts: [] }]
+  let published = 0
+  observeResources(pi, loader, loading, records, () => { published++ })
+  const wrapped = extension.handlers.get('resources_discover')! as unknown as Array<(event: unknown, context: unknown) => Promise<Pi.ResourcesDiscoverResult | undefined>>
+  expect(await wrapped[0]({}, {})).toMatchObject({ themePaths: [second] })
+  await wrapped[1]({}, {})
+  expect(records[0].resources?.map((resource) => resource.name)).toEqual(['first.json', 'second.json', 'runtime-review'])
+  active = false
+  await wrapped[0]({}, {})
+  expect(records[0].resources?.map((resource) => resource.name)).toEqual(['runtime-review'])
+  expect(published).toBe(3)
+})

package/src/plugins/runtime.ts

@@ -0,0 +1,82 @@
+// Observe Pi's structured resource discovery without running code while the catalogue is read.
+import { createHash } from 'node:crypto'
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import type * as Pi from '@earendil-works/pi-coding-agent'
+
+import { charCount } from '../core/text'
+import { FOUND_KINDS, describeFound } from './identity'
+import type { Found } from './discover'
+import type { Loading, Registered, RuntimeResource } from './plugins'
+
+export function runtimeOwner(loading: Loading, path: string): Found | undefined {
+  return loading.found.find((item) => item.kind === 'extension' && (item.path === path || path.startsWith(`${item.path}/`)))
+}
+
+export function registrationHash(loading: Loading, path: string): string | null {
+  const owner = runtimeOwner(loading, path)
+  if (owner?.project) return loading.projectCode?.hash ?? null
+  if (owner?.packageRoot) return loading.packageCode[owner.packageRoot]?.hash ?? null
+  try { return createHash('sha256').update(readFileSync(path)).digest('hex') } catch { return null }
+}
+
+/** A discovered resource has the same identity for its switch, catalogue and load decision. */
+export function resourceOf(owner: Found, kind: 'skill' | 'prompt' | 'theme', path: string): RuntimeResource {
+  const found = { ...owner, kind, path }
+  const described = describeFound(found)
+  let chars: number | null = null
+  try { chars = charCount(readFileSync(path, 'utf8')) } catch { /* Missing files remain observable. */ }
+  return { kind: FOUND_KINDS[kind] as RuntimeResource['kind'], name: described.name, path, chars }
+}
+
+/** Wrap each handler separately so identical extension basenames never lose their owner. */
+export function observeResources(pi: typeof Pi, loader: Pi.DefaultResourceLoader, loading: Loading, records: Registered[], publish: () => void): void {
+  for (const extension of loader.getExtensions().extensions) {
+    if (extension.hidden) continue
+    const path = extension.resolvedPath || extension.path
+    const owner = runtimeOwner(loading, path)
+    const record = records.find((entry) => entry.path === path)
+    if (!owner || !record) continue
+    const handlers = extension.handlers.get('resources_discover')
+    if (!handlers) continue
+    const observations = new Map<number, RuntimeResource[]>()
+    extension.handlers.set('resources_discover', handlers.map((handler, index) => async (event, context) => {
+      const result = await handler(event, context) as Pi.ResourcesDiscoverResult | undefined
+      if (!result) {
+        observations.delete(index)
+        record.resources = [...observations.values()].flat()
+        publish()
+        return result
+      }
+      const collected: RuntimeResource[] = []
+      const allowed = (kind: 'skill' | 'prompt' | 'theme', resourcePath: string): boolean => {
+        const resource = resourceOf(owner, kind, resourcePath)
+        collected.push(resource)
+        return loading.resourceAllowed?.({ ...owner, kind, path: resourcePath }) !== false
+      }
+      const absolute = (entry: string): string => resolve(dirname(path), entry)
+      const skills = pi.loadSkills({ cwd: dirname(path), agentDir: dirname(path), includeDefaults: false, skillPaths: (result.skillPaths ?? []).map(absolute) }).skills
+      const scanner = new pi.DefaultResourceLoader({ cwd: dirname(path), agentDir: dirname(path), settingsManager: pi.SettingsManager.inMemory({}), noExtensions: true, noSkills: true, noThemes: true, noContextFiles: true, noPromptTemplates: true, additionalPromptTemplatePaths: (result.promptPaths ?? []).map(absolute) })
+      await scanner.reload()
+      const prompts = scanner.getPrompts().prompts
+      const themes = (result.themePaths ?? []).map(absolute).flatMap((theme) => {
+        try {
+          if (statSync(theme).isDirectory()) return readdirSync(theme).filter((name) => {
+            if (!name.endsWith('.json')) return false
+            try { return statSync(resolve(theme, name)).isFile() } catch { return false }
+          }).map((name) => resolve(theme, name))
+        } catch { /* Preserve missing paths for Pi's diagnostics. */ }
+        return [theme]
+      })
+      const filtered = {
+        skillPaths: skills.filter((skill) => allowed('skill', skill.filePath)).map((skill) => skill.filePath),
+        promptPaths: prompts.filter((prompt) => allowed('prompt', prompt.filePath)).map((prompt) => prompt.filePath),
+        themePaths: themes.filter((theme) => allowed('theme', theme))
+      }
+      observations.set(index, collected)
+      record.resources = [...new Map([...observations.values()].flat().map((entry) => [`${entry.kind}:${entry.path}`, entry])).values()]
+      publish()
+      return filtered
+    }))
+  }
+}

package/src/plugins/trust.ts

@@ -0,0 +1,142 @@
+// Code a person did not write into the shared folder by hand loads only after they trusted it:
+// a working folder's own (its `.pi/extensions`, or a package its settings name), and every
+// installed package. Trust belongs to the code, not the folder: it is a hash of the files, so a
+// copy of the same code elsewhere is trusted too and a changed file asks again.
+import { createHash } from 'node:crypto'
+import { chmodSync, lstatSync, readdirSync, readFileSync } from 'node:fs'
+import { basename, dirname, join, relative, sep } from 'node:path'
+
+import type { Bus } from '../core/bus'
+import { now, readJsonOr, writeJson } from '../core/fs'
+import { compareText } from '../core/text'
+import type { Found } from './discover'
+
+export interface ProjectCode {
+  /** SHA-256 over every file's name and contents. */
+  hash: string
+  /** The files, named from the working folder where they are inside it. */
+  files: string[]
+}
+
+// Dependencies and version control are left out: the hash says whether the code a person
+// read has changed, and is not a seal on everything that code can import.
+const SKIPPED = new Set(['node_modules', '.git'])
+const MAX_FILES = 5000
+
+function walk(path: string, into: string[]): void {
+  if (into.length >= MAX_FILES) return
+  let meta
+  try {
+    meta = lstatSync(path)
+  } catch {
+    return
+  }
+  if (meta.isSymbolicLink()) return
+  if (meta.isFile()) {
+    into.push(path)
+    return
+  }
+  if (!meta.isDirectory()) return
+  for (const name of readdirSync(path).sort(compareText)) if (!SKIPPED.has(name)) walk(join(path, name), into)
+}
+
+/** The folder or file that holds one extension: its package, its own folder, or the file. */
+const unit = (item: Found): string => item.packageRoot ?? (basename(item.path).startsWith('index.') ? dirname(item.path) : item.path)
+
+/** A hash over the files of some folders and files, each named from `base` where it is inside it. */
+function hashOf(units: readonly string[], base: string): ProjectCode {
+  const paths: string[] = []
+  for (const path of [...units].sort(compareText)) walk(path, paths)
+  const name = (path: string): string => {
+    const within = relative(base, path)
+    return within && !within.startsWith('..') ? within.split(sep).join('/') : path
+  }
+  const hash = createHash('sha256')
+  const files: string[] = []
+  for (const path of [...new Set(paths)].sort(compareText)) {
+    let contents: Buffer
+    try {
+      contents = readFileSync(path)
+    } catch {
+      continue
+    }
+    files.push(name(path))
+    hash.update(`${name(path)}\0${contents.length}\0`).update(contents)
+  }
+  return { hash: hash.digest('hex'), files }
+}
+
+/** The code the working folder brings, or `null` when it brings none. */
+export function projectCode(found: readonly Found[], cwd: string): ProjectCode | null {
+  const units = [...new Set(found.filter((item) => item.project && item.kind === 'extension' && item.enabled).map(unit))]
+  return units.length ? hashOf(units, cwd) : null
+}
+
+/**
+ * Each package a person installed that brings code, by its folder: the whole package is hashed,
+ * so a changed skill or manifest asks again as well. A working folder's packages are part of
+ * `projectCode`.
+ */
+export function packageCode(found: readonly Found[]): Map<string, ProjectCode> {
+  const roots = [...new Set(found.filter((item) => !item.project && (item.kind === 'extension' || item.kind === 'hook') && item.packageRoot).map((item) => item.packageRoot!))]
+  return new Map(roots.map((root) => [root, hashOf([root], root)]))
+}
+
+export interface TrustRecord {
+  hash: string
+  /** The working folder it was trusted in. */
+  folder: string
+  files: string[]
+  trustedAt: string
+}
+
+export class Trust {
+  private readonly path: string
+
+  constructor(stateDir: string, private readonly bus: Bus) {
+    this.path = join(stateDir, 'plugin-trust.json')
+  }
+
+  private read(): { trusted?: unknown; adopted?: unknown } {
+    return readJsonOr<{ trusted?: unknown; adopted?: unknown }>(this.path, {})
+  }
+
+  list(): TrustRecord[] {
+    const stored = this.read()
+    return Array.isArray(stored.trusted) ? (stored.trusted as TrustRecord[]).filter((record) => typeof record?.hash === 'string') : []
+  }
+
+  /** Whether the packages that loaded before trust was asked per package were taken over as trusted. */
+  get adopted(): boolean {
+    return this.read().adopted === true
+  }
+
+  /**
+   * Trusts the packages present the first time this runs, so nothing that loaded before stops.
+   * It happens once; a package installed later, or one of these after a change, waits for a person.
+   */
+  adopt(codes: readonly { code: ProjectCode; folder: string }[]): void {
+    const records = this.list()
+    for (const { code, folder } of codes) if (!records.some((record) => record.hash === code.hash)) records.push({ hash: code.hash, folder, files: code.files, trustedAt: now() })
+    writeJson(this.path, { trusted: records, adopted: true })
+    chmodSync(this.path, 0o600)
+  }
+
+  has(hash: string): boolean {
+    return this.list().some((record) => record.hash === hash)
+  }
+
+  private save(records: TrustRecord[]): void {
+    writeJson(this.path, { trusted: records, ...(this.adopted ? { adopted: true } : {}) })
+    chmodSync(this.path, 0o600)
+    this.bus.emit({ type: 'plugins.changed' })
+  }
+
+  grant(code: ProjectCode, folder: string): void {
+    this.save([...this.list().filter((record) => record.hash !== code.hash), { hash: code.hash, folder, files: code.files, trustedAt: now() }])
+  }
+
+  revoke(hash: string): void {
+    this.save(this.list().filter((record) => record.hash !== hash))
+  }
+}