@xingular/harness 0.0.0-stage → 0.1.0

package/src/plugins/install.ts

@@ -0,0 +1,106 @@
+// Installing, updating and removing a package. Pi's own package manager does the work, against
+// the settings every account shares, so the `pi` command and the harness agree on what is
+// installed. Fetching runs none of a package's code, and what was installed is switched off and
+// untrusted until a person has looked at it.
+import { existsSync, mkdirSync, renameSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { basename, isAbsolute, join, resolve } from 'node:path'
+
+import { ensureSharedDir } from '../accounts/env'
+import { invalid, notFound } from '../core/errors'
+import { now } from '../core/fs'
+import type { Harness } from '../harness'
+import { ensureAdopted, list, type PluginScope } from './api'
+import * as attachments from './attachments'
+import { withoutInstallScripts } from './discover'
+import type { Plugin } from './types'
+
+/** A folder on this machine, or a package as Pi's settings name it. A bare name is an npm package. */
+export function normalizeSource(input: string): string {
+  const source = input.trim()
+  if (!source) throw invalid('Name a package: a folder, an npm name, or a git address.')
+  if (source.startsWith('~/')) return join(process.env.HOME || homedir(), source.slice(2))
+  if (isAbsolute(source)) return resolve(source)
+  if (source.startsWith('./') || source.startsWith('../')) throw invalid('Give the whole path of the folder.')
+  return /^(npm:|git:|https?:\/\/|ssh:\/\/|git@)/.test(source) ? source : `npm:${source}`
+}
+
+async function manager(harness: Harness) {
+  const pi = await import('@earendil-works/pi-coding-agent')
+  // The shared folder is where `settings.json` really is; an account's own is a link to it.
+  const agentDir = ensureSharedDir(harness.accounts.dir)
+  const settings = pi.SettingsManager.create(harness.stateDir, agentDir)
+  return { settings, packages: new pi.DefaultPackageManager({ cwd: harness.stateDir, agentDir, settingsManager: settings }) }
+}
+
+const changed = (harness: Harness): void => harness.bus.emit({ type: 'plugins.changed' })
+
+/**
+ * Installs a package for every account. It arrives switched off, and if it brings code, not
+ * trusted: nothing of it reaches a session until a person switches it on and trusts it.
+ */
+export async function install(harness: Harness, params: PluginScope & { source: string }): Promise<Plugin[]> {
+  const source = normalizeSource(params.source)
+  if (isAbsolute(source) && !(existsSync(source) && statSync(source).isDirectory())) throw invalid('That folder does not exist.')
+  // What was already there is taken over as trusted before anything new arrives, never after.
+  await ensureAdopted(harness)
+  const before = new Set((await list(harness, params)).map((plugin) => plugin.id))
+  const { settings, packages } = await manager(harness)
+  if (isAbsolute(source)) {
+    // Pi would save a folder as a path relative to the settings file, and each account reads
+    // that file through a link in its own folder, where a relative path points somewhere else.
+    const named = settings.getGlobalSettings().packages ?? []
+    if (!named.some((entry) => (typeof entry === 'string' ? entry : entry.source) === source)) settings.setPackages([...named, source])
+    await settings.flush()
+  } else {
+    await withoutInstallScripts(() => packages.installAndPersist(source))
+  }
+  const after = await list(harness, params)
+  const added = after.filter((plugin) => plugin.install && !before.has(plugin.id))
+  if (added.length) {
+    const choices = attachments.load(harness.env.root)
+    for (const plugin of added) attachments.set(choices, [plugin.id], {}, false, true)
+    attachments.save(harness.env.root, choices)
+  }
+  changed(harness)
+  return added.length ? list(harness, params) : after
+}
+
+function installed(plugins: readonly Plugin[], pluginId: string): Plugin & { install: NonNullable<Plugin['install']> } {
+  const plugin = plugins.find((candidate) => candidate.id === pluginId)
+  if (!plugin) throw notFound('Plugin')
+  if (!plugin.install) throw invalid(`${plugin.title} was not installed as a package, so it cannot be removed or updated here.`)
+  return plugin as Plugin & { install: NonNullable<Plugin['install']> }
+}
+
+/** Removes an installed package. One kept as a folder beside a person's data is moved to the trash there. */
+export async function remove(harness: Harness, params: PluginScope & { pluginId: string }): Promise<Plugin[]> {
+  const plugin = installed(await list(harness, params), params.pluginId)
+  if (plugin.install.kind === 'folder') {
+    const trash = join(harness.env.root, 'trash', 'plugins')
+    mkdirSync(trash, { recursive: true })
+    renameSync(plugin.install.source, join(trash, `${basename(plugin.install.source)}-${now().replace(/[:.]/g, '-')}`))
+  } else {
+    await (await manager(harness)).packages.removeAndPersist(plugin.install.source)
+  }
+  const choices = attachments.load(harness.env.root)
+  for (const scope of [choices.global, ...Object.values(choices.agents), ...Object.values(choices.projects)]) {
+    scope.on = scope.on.filter((id) => id !== plugin.id && !id.startsWith(`${plugin.id}/`))
+    scope.off = scope.off.filter((id) => id !== plugin.id && !id.startsWith(`${plugin.id}/`))
+  }
+  delete choices.settings[plugin.id]
+  attachments.save(harness.env.root, choices)
+  if (plugin.code) harness.plugins.trust.revoke(plugin.code.hash)
+  changed(harness)
+  return list(harness, params)
+}
+
+/** Fetches a newer version of one installed package, or of all of them. Changed code waits for trust again. */
+export async function update(harness: Harness, params: PluginScope & { pluginId?: string | null }): Promise<Plugin[]> {
+  const plugin = params.pluginId ? installed(await list(harness, params), params.pluginId) : null
+  if (plugin?.install.kind === 'folder') throw invalid(`${plugin.title} is a folder on this machine. Change its files to update it.`)
+  const { packages } = await manager(harness)
+  await withoutInstallScripts(() => packages.update(plugin?.install.source))
+  changed(harness)
+  return list(harness, params)
+}

package/src/plugins/inventory.ts

@@ -0,0 +1,123 @@
+// What reaches one caller: every prompt section, tool, skill, connection and extension, each
+// attributed to the plugin it comes from. Anything no plugin accounts for is reported, so a new
+// source of model-visible text cannot appear without showing up here.
+import { readFileSync } from 'node:fs'
+
+import type { HarnessEnv } from '../core/env'
+import { charCount } from '../core/text'
+import { allowed } from '../mcp/connections'
+import type { Connection } from '../mcp/types'
+import type { CallerContext } from '../memory/caller'
+import { BUILT_IN_DYNAMIC, compile, toolGroups, type Launch } from '../prompt/compile'
+import * as registry from '../skills/registry'
+import { ASK_USER } from '../tools/askUser'
+import { PLUGIN_PROPOSE } from '../tools/pluginPropose'
+import { WIKI_TOOL_NAMES } from '../tools/definitions'
+import { INCLUDED_PLUGIN, YOURS_PLUGIN } from './builtin'
+import type { Contribution, Inventory, InventoryItem, Plugin, PluginDescriptor } from './types'
+
+export interface InventoryInput {
+  env: HarnessEnv
+  context: CallerContext
+  /** What the application adds to the prompt for this caller, as it would for a session. */
+  launch: Launch
+  /** The tools the caller has switched on, as a session's `allow` list. */
+  tools: readonly string[]
+  /** Whether the caller gets the connected-apps tools. */
+  connections: boolean
+  plugins: readonly Plugin[]
+  descriptors: readonly PluginDescriptor[]
+  saved: readonly Connection[]
+}
+
+const size = (path: string | null): number | null => {
+  if (!path) return null
+  try {
+    return charCount(readFileSync(path, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+export function inventory(input: InventoryInput): Inventory {
+  const { env, context, launch, descriptors } = input
+  const items: InventoryItem[] = []
+  const unattributed: Inventory['unattributed'] = []
+  const item = (pluginId: string, kind: InventoryItem['kind'], name: string, delivery: InventoryItem['delivery'], chars: number | null, rest: Partial<InventoryItem> = {}): void => {
+    items.push({ pluginId, contributionId: null, kind, name, delivery, chars, cut: false, ...rest })
+  }
+
+  const pack = compile(env, context, launch)
+  const dynamic = new Set([...BUILT_IN_DYNAMIC.map((entry) => entry.id), ...(launch.sections ?? []).filter((section) => section.dynamic).map((section) => section.id)])
+  const active = registry.enabledFor(env.root, context.projectId ?? null, context.agentId ?? null)
+  const owner = (entry: registry.RegistryItem): string => (entry.builtin ? INCLUDED_PLUGIN.id : YOURS_PLUGIN.id)
+  let systemChars = 0
+  let contextChars = 0
+
+  for (const section of pack.sections) {
+    const delivery = dynamic.has(section.id) ? 'context' : 'system'
+    if (delivery === 'context') contextChars += section.size
+    else systemChars += section.size
+    if (section.id === 'tools') {
+      // One paragraph per tool group; each belongs to the plugin that provides the group.
+      for (const group of toolGroups(context, launch)) {
+        if (!group.guidance) continue
+        const plugin = descriptors.find((descriptor) => descriptor.toolGroups?.includes(group.group))
+        if (!plugin) unattributed.push({ kind: 'toolGroup', id: group.group })
+        item(plugin?.id ?? '', 'instruction', `Tool guidance: ${group.group}`, delivery, charCount(group.guidance), { cut: section.cut })
+      }
+      continue
+    }
+    if (section.id === 'rules') {
+      for (const rule of active.filter((entry) => entry.kind === 'rules')) {
+        item(owner(rule), 'instruction', rule.name, delivery, charCount(`### ${rule.name} (${rule.id})\n\n${registry.itemBody(rule).trim()}`), { contributionId: `${owner(rule)}/${rule.id}`, cut: section.cut })
+      }
+      continue
+    }
+    const plugin = descriptors.find((descriptor) => descriptor.sections?.some((declared) => declared.id === section.id))
+    if (!plugin) unattributed.push({ kind: 'section', id: section.id })
+    const name = plugin?.sections?.find((declared) => declared.id === section.id)?.name ?? section.title
+    item(plugin?.id ?? '', 'instruction', name, delivery, section.size, { contributionId: plugin ? `${plugin.id}/instruction/${name}` : null, cut: section.cut })
+  }
+
+  // A skill's or a prompt's own text is loaded only when it is used.
+  for (const entry of active.filter((candidate) => candidate.kind === 'skills' || candidate.kind === 'prompts')) {
+    item(owner(entry), entry.kind === 'skills' ? 'skill' : 'command', entry.name, 'on-demand', size(entry.path), { contributionId: `${owner(entry)}/${entry.id}` })
+  }
+
+  const names = [...input.tools]
+  const extensionToolNames = new Set(input.plugins.filter((plugin) => ['project', 'package', 'shared', 'home'].includes(plugin.source)).flatMap((plugin) => plugin.contributions.filter((entry) => entry.kind === 'tool' && entry.state === 'on').map((entry) => entry.name)))
+  for (const name of [ASK_USER, PLUGIN_PROPOSE, ...WIKI_TOOL_NAMES, ...(input.connections ? ['mcp_list_tools', 'mcp_call_tool'] : [])]) if (!names.includes(name)) names.push(name)
+  for (const name of names) {
+    if (extensionToolNames.has(name)) continue
+    const plugin = descriptors.find((descriptor) => descriptor.tools?.some((tool) => tool.name === name))
+    if (!plugin) unattributed.push({ kind: 'tool', id: name })
+    item(plugin?.id ?? '', 'tool', name, 'tool', null, { contributionId: plugin ? `${plugin.id}/tool/${name}` : null })
+  }
+
+  if (input.connections) {
+    for (const connection of input.saved.filter((candidate) => allowed(candidate, { agentId: context.agentId ?? null, projectId: context.projectId ?? null }))) {
+      item('connected-apps', 'connection', connection.name || connection.id, 'tool', null, { contributionId: `connected-apps/connection/${connection.id}` })
+    }
+  }
+
+  // What the harness found on disk and lets load. Pi's command's own extensions exist only in a terminal.
+  const delivered: Record<Contribution['kind'], InventoryItem['delivery']> = { code: 'code', skill: 'on-demand', command: 'on-demand', instruction: 'system', theme: 'code', tool: 'tool', connection: 'tool' }
+  const terminal = context.surface === 'cli'
+  for (const plugin of input.plugins) {
+    if (!['project', 'package', 'shared', 'home', 'pi'].includes(plugin.source)) continue
+    for (const found of plugin.contributions) {
+      if (found.state !== 'on' || (plugin.source === 'pi' && (found.kind !== 'code' || !terminal)) || (found.kind === 'theme' && !terminal)) continue
+      item(plugin.id, found.kind, found.name, found.background ? 'background' : delivered[found.kind], ['instruction', 'skill', 'command'].includes(found.kind) ? size(found.path) : null, { contributionId: found.id })
+    }
+  }
+  // The harness's own switched-on extensions.
+  for (const plugin of input.plugins) {
+    if (plugin.source !== 'builtin') continue
+    for (const own of plugin.contributions) if (own.kind === 'code' && own.state === 'on') item(plugin.id, 'code', own.name, 'code', null, { contributionId: own.id })
+  }
+  item('pi', 'instruction', 'Base prompt', 'system', null)
+
+  const used = new Set(items.map((entry) => entry.pluginId))
+  return { plugins: input.plugins.filter((plugin) => used.has(plugin.id)), others: input.plugins.filter((plugin) => !used.has(plugin.id)), items, unattributed, systemChars, contextChars }
+}

package/src/plugins/manifest.ts

@@ -0,0 +1,44 @@
+// What a package says about itself in its `package.json`: Pi's own fields, and under `harness`
+// which part of the harness it extends and the file of hooks the harness runs for it.
+import { basename, join } from 'node:path'
+
+import { readJsonOr, safeRelative } from '../core/fs'
+
+export interface PackageManifest {
+  name: string
+  description: string
+  version: string | null
+  /** The parts it adds to, by id: `memory`, `wiki`, `history`. */
+  extends: string[]
+  /** The hooks file, inside the package, or `null` when it has none. */
+  hooks: string | null
+}
+
+interface Raw {
+  name?: unknown
+  description?: unknown
+  version?: unknown
+  harness?: unknown
+}
+
+/** A path inside the package, or `null` for one that is missing, absolute, or climbs out of it. */
+function inside(path: unknown): string | null {
+  if (typeof path !== 'string' || !path.trim()) return null
+  try {
+    return safeRelative(path.replace(/^\.\//, ''))
+  } catch {
+    return null
+  }
+}
+
+export function packageManifest(packageRoot: string): PackageManifest {
+  const manifest = readJsonOr<Raw>(join(packageRoot, 'package.json'), {})
+  const own = (manifest.harness && typeof manifest.harness === 'object' && !Array.isArray(manifest.harness) ? manifest.harness : {}) as { extends?: unknown; hooks?: unknown }
+  return {
+    name: typeof manifest.name === 'string' && manifest.name ? manifest.name : basename(packageRoot),
+    description: typeof manifest.description === 'string' ? manifest.description : '',
+    version: typeof manifest.version === 'string' ? manifest.version : null,
+    extends: (Array.isArray(own.extends) ? own.extends : typeof own.extends === 'string' ? [own.extends] : []).filter((id): id is string => typeof id === 'string' && !!id),
+    hooks: inside(own.hooks)
+  }
+}

package/src/plugins/plugins.test.ts

@@ -0,0 +1,205 @@
+import { existsSync, mkdirSync, mkdtempSync, symlinkSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+import { Bus } from '../core/bus'
+import type { Attachments } from './attachments'
+import { loadResources, type TurnParams } from '../sessions/runner'
+import { piResolver, type Found } from './discover'
+import { Plugins } from './plugins'
+import { projectCode } from './trust'
+
+const temp = (prefix: string): string => mkdtempSync(join(tmpdir(), prefix))
+
+function write(path: string, text: string): void {
+  mkdirSync(join(path, '..'), { recursive: true })
+  writeFileSync(path, text)
+}
+
+/** An extension that leaves a file behind when Pi loads it, and registers a command and a hook. */
+const extension = (marker: string, command: string): string =>
+  `import { writeFileSync } from 'node:fs'\nwriteFileSync(${JSON.stringify(marker)}, 'ran')\nexport default function (pi) {\n  pi.registerCommand('${command}', { description: 'A test command', handler: async () => {} })\n  pi.on('tool_call', async () => undefined)\n}\n`
+
+function workspace() {
+  const base = temp('harness-plugins-')
+  const agentDir = join(base, 'agent')
+  const cwd = join(base, 'project')
+  const markers = { shared: join(base, 'ran-shared'), project: join(base, 'ran-project'), packaged: join(base, 'ran-packaged') }
+  write(join(agentDir, 'extensions/shared.ts'), extension(markers.shared, 'shared'))
+  write(join(agentDir, 'skills/alpha/SKILL.md'), '---\nname: alpha\ndescription: Alpha skill\n---\nAlpha.\n')
+  write(join(agentDir, 'prompts/review.md'), 'Review this.\n')
+  write(join(cwd, '.pi/extensions/project.ts'), extension(markers.project, 'project'))
+  write(join(cwd, '.pi/skills/beta/SKILL.md'), '---\nname: beta\ndescription: Beta skill\n---\nBeta.\n')
+  write(join(base, 'package/package.json'), JSON.stringify({ name: 'local-package', description: 'A local package', version: '0.1.0', keywords: ['pi-package'] }))
+  write(join(base, 'package/extensions/packaged.ts'), extension(markers.packaged, 'packaged'))
+  write(join(base, 'package/skills/gamma/SKILL.md'), '---\nname: gamma\ndescription: Gamma skill\n---\nGamma.\n')
+  write(join(agentDir, 'settings.json'), JSON.stringify({ packages: [join(base, 'package')], extensions: ['-builtin:llama.cpp'] }))
+  const stateDir = join(base, 'state')
+  mkdirSync(stateDir)
+  const notices: string[] = []
+  const bus = new Bus()
+  bus.on((notice) => void notices.push(notice.type))
+  return { base, agentDir, cwd, markers, notices, plugins: new Plugins({ stateDir, bus }) }
+}
+
+const ran = (markers: Record<string, string>): Record<string, boolean> => Object.fromEntries(Object.entries(markers).map(([name, path]) => [name, existsSync(path)]))
+
+describe('what Pi would load', () => {
+  it('is found without running any of it, with where each item comes from', async () => {
+    const { agentDir, cwd, markers, base } = workspace()
+    const found = await piResolver({ cwd, agentDir })
+    const of = (kind: Found['kind']) => found.filter((item) => item.kind === kind).map((item) => [item.origin, item.path.replace(`${base}/`, ''), item.enabled])
+    expect(of('extension')).toEqual([
+      ['project', 'project/.pi/extensions/project.ts', true],
+      ['shared', 'agent/extensions/shared.ts', true],
+      ['package', 'package/extensions/packaged.ts', true],
+      ['builtin', 'builtin:llama.cpp', false],
+      ['builtin', 'builtin:codemode', true],
+      ['builtin', 'builtin:tool-search', true],
+      ['builtin', 'builtin:mcp', true]
+    ])
+    expect(of('skill')).toEqual([
+      ['project', 'project/.pi/skills/beta/SKILL.md', true],
+      ['shared', 'agent/skills/alpha/SKILL.md', true],
+      ['package', 'package/skills/gamma/SKILL.md', true]
+    ])
+    expect(found.find((item) => item.origin === 'package')).toMatchObject({ packageRoot: join(base, 'package'), source: join(base, 'package'), project: false })
+    expect(ran(markers)).toEqual({ shared: false, project: false, packaged: false })
+  })
+
+  it('names a package nobody installed, and installs nothing when only listing', async () => {
+    const { agentDir, cwd } = workspace()
+    writeFileSync(join(agentDir, 'settings.json'), JSON.stringify({ packages: ['npm:@no-such-scope/never-installed'] }))
+    const found = await piResolver({ cwd, agentDir })
+    expect(found.some((item) => item.origin === 'package')).toBe(false)
+    expect(existsSync(join(agentDir, 'npm'))).toBe(false)
+  })
+})
+
+describe('what a session loads', () => {
+  it("leaves a working folder's code out until a person trusts it", async () => {
+    const { agentDir, cwd, plugins, base, notices } = workspace()
+    const before = await plugins.loading({ cwd, agentDir })
+    const short = (paths: string[]) => paths.map((path) => path.replace(`${base}/`, ''))
+    expect(short(before.extensionPaths)).toEqual(['agent/extensions/shared.ts', 'package/extensions/packaged.ts'])
+    expect(short(before.skillPaths)).toEqual(['project/.pi/skills/beta/SKILL.md', 'agent/skills/alpha/SKILL.md', 'package/skills/gamma/SKILL.md'])
+    expect(before.builtins).toEqual(['builtin:codemode', 'builtin:tool-search', 'builtin:mcp'])
+    expect(before.projectCode).toMatchObject({ trusted: false, files: ['.pi/extensions/project.ts'] })
+
+    plugins.trust.grant(before.projectCode!, cwd)
+    expect(notices).toContain('plugins.changed')
+    const trusted = await plugins.loading({ cwd, agentDir })
+    expect(short(trusted.extensionPaths)).toEqual(['project/.pi/extensions/project.ts', 'agent/extensions/shared.ts', 'package/extensions/packaged.ts'])
+
+    // A changed file is different code: it asks again.
+    writeFileSync(join(cwd, '.pi/extensions/project.ts'), 'export default function () {}\n')
+    const changed = await plugins.loading({ cwd, agentDir })
+    expect(changed.projectCode?.trusted).toBe(false)
+    expect(changed.projectCode?.hash).not.toBe(before.projectCode?.hash)
+    expect(short(changed.extensionPaths)).toEqual(['agent/extensions/shared.ts', 'package/extensions/packaged.ts'])
+
+    plugins.trust.revoke(before.projectCode!.hash)
+    // What is left is the package that was there when trust was first asked per package.
+    expect(plugins.trust.list().map((record) => record.folder)).toEqual([join(base, 'package')])
+  })
+
+  it('takes over the packages present once, then makes a new or changed package wait', async () => {
+    const { agentDir, cwd, plugins, base } = workspace()
+    const packaged = join(base, 'package/extensions/packaged.ts')
+    const first = await plugins.loading({ cwd, agentDir })
+    expect(first.packageCode[join(base, 'package')]).toMatchObject({ trusted: true, files: ['extensions/packaged.ts', 'package.json', 'skills/gamma/SKILL.md'] })
+    expect(first.extensionPaths).toContain(packaged)
+
+    // An update changes the code: it does not load until a person trusts it again.
+    writeFileSync(packaged, 'export default function () {}\n')
+    const changed = await plugins.loading({ cwd, agentDir })
+    expect(changed.packageCode[join(base, 'package')].trusted).toBe(false)
+    expect(changed.extensionPaths).not.toContain(packaged)
+    // Its text still loads: a skill runs nothing by itself.
+    expect(changed.skillPaths).toContain(join(base, 'package/skills/gamma/SKILL.md'))
+    plugins.trust.grant(changed.packageCode[join(base, 'package')], join(base, 'package'))
+    expect((await plugins.loading({ cwd, agentDir })).extensionPaths).toContain(packaged)
+
+    // A package added after the first start was never taken over.
+    write(join(base, 'second/package.json'), JSON.stringify({ name: 'second', version: '1.0.0' }))
+    write(join(base, 'second/extensions/later.ts'), 'export default function () {}\n')
+    write(join(agentDir, 'settings.json'), JSON.stringify({ packages: [join(base, 'package'), join(base, 'second')] }))
+    const later = await plugins.loading({ cwd, agentDir })
+    expect(later.packageCode[join(base, 'second')].trusted).toBe(false)
+    expect(later.extensionPaths).not.toContain(join(base, 'second/extensions/later.ts'))
+  })
+
+  it('trusts the same code in another folder, and names files from the folder they are in', () => {
+    const one = temp('harness-code-')
+    const two = temp('harness-code-')
+    for (const cwd of [one, two]) write(join(cwd, '.pi/extensions/tool/index.ts'), 'export default function () {}\n')
+    const item = (cwd: string): Found => ({ kind: 'extension', path: join(cwd, '.pi/extensions/tool/index.ts'), origin: 'project', project: true, packageRoot: null, source: null, enabled: true })
+    write(join(one, '.pi/extensions/tool/node_modules/dep/index.js'), 'ignored')
+    expect(projectCode([item(one)], one)).toEqual(projectCode([item(two)], two))
+    expect(projectCode([item(one)], one)?.files).toEqual(['.pi/extensions/tool/index.ts'])
+    // A helper beside `index.ts` is part of the same extension.
+    write(join(two, '.pi/extensions/tool/helper.ts'), 'export const x = 1\n')
+    expect(projectCode([item(two)], two)?.hash).not.toBe(projectCode([item(one)], one)?.hash)
+    expect(projectCode([{ ...item(one), project: false }], one)).toBeNull()
+  })
+
+  it('removes the skill links an earlier version kept in the shared folder', async () => {
+    const { agentDir, cwd, plugins, base } = workspace()
+    symlinkSync(join(agentDir, 'skills/alpha'), join(agentDir, 'skills/agentx-old'))
+    const loading = await plugins.loading({ cwd, agentDir })
+    expect(existsSync(join(agentDir, 'skills/agentx-old'))).toBe(false)
+    expect(loading.skillPaths.filter((path) => path.startsWith(join(base, 'agent')))).toEqual([join(agentDir, 'skills/alpha/SKILL.md')])
+  })
+})
+
+describe('a Pi session loader', () => {
+  const params = (cwd: string, agentDir: string, plugins: Plugins, extra: Partial<TurnParams> = {}) =>
+    ({
+      cwd,
+      account: { configDir: agentDir } as TurnParams['account'],
+      system: '',
+      plugins: { loading: () => plugins.loading({ cwd, agentDir }), loaded: (extensions) => plugins.loaded(extensions) },
+      ...extra
+    }) satisfies Parameters<typeof loadResources>[1]
+
+  it('runs only what the harness chose, and records what each extension registered', async () => {
+    const { agentDir, cwd, plugins, markers } = workspace()
+    const pi = await import('@earendil-works/pi-coding-agent')
+    const loader = await loadResources(pi, params(cwd, agentDir, plugins), () => undefined)
+    expect(ran(markers)).toEqual({ shared: true, project: false, packaged: true })
+    expect(loader.getSkills().skills.map((skill) => skill.name).sort()).toEqual(['alpha', 'beta', 'gamma'])
+    expect(loader.getPrompts().prompts.map((prompt) => prompt.name)).toEqual(['review'])
+    expect(Object.values(plugins.registered()).map((entry) => [entry.commands, entry.hooks])).toEqual([
+      [['shared'], ['tool_call']],
+      [['packaged'], ['tool_call']]
+    ])
+
+    const code = (await plugins.loading({ cwd, agentDir })).projectCode!
+    plugins.trust.grant(code, cwd)
+    await loadResources(pi, params(cwd, agentDir, plugins), () => undefined)
+    expect(ran(markers).project).toBe(true)
+  })
+
+  it('does not run an extension a person switched off for the caller', async () => {
+    const { agentDir, cwd, markers, base } = workspace()
+    const choices: Attachments = { version: 1, global: { on: [], off: [] }, agents: { a1: { on: [], off: ['shared/code/shared.ts'] } }, projects: {}, settings: {} }
+    const plugins = new Plugins({ stateDir: join(base, 'state'), bus: new Bus(), attachments: () => choices })
+    const pi = await import('@earendil-works/pi-coding-agent')
+    const forAgent = (agentId: string) => ({ ...params(cwd, agentDir, plugins), plugins: { loading: () => plugins.loading({ cwd, agentDir, caller: { agentId } }), loaded: () => undefined } })
+    const loader = await loadResources(pi, forAgent('a1'), () => undefined)
+    expect(ran(markers)).toEqual({ shared: false, project: false, packaged: true })
+    // Its skills are a different contribution and still load.
+    expect(loader.getSkills().skills.map((skill) => skill.name).sort()).toEqual(['alpha', 'beta', 'gamma'])
+    await loadResources(pi, forAgent('a2'), () => undefined)
+    expect(ran(markers).shared).toBe(true)
+  })
+
+  it('loads no extension at all for an unattended run', async () => {
+    const { agentDir, cwd, plugins, markers } = workspace()
+    const pi = await import('@earendil-works/pi-coding-agent')
+    const settings = pi.SettingsManager.inMemory({})
+    await loadResources(pi, params(cwd, agentDir, plugins, { automatic: true }), () => undefined, settings)
+    expect(ran(markers)).toEqual({ shared: false, project: false, packaged: false })
+  })
+})