@xingular/harness 2.0.0 → 2.0.1-unstable

package/src/plugins/builtin.ts

@@ -1,84 +0,0 @@
-// The harness's own parts, described as plugins. Each is a description of code that already
-// exists; none of it is loaded through Pi's extension system.
-import { CONNECTION_TOOLS, NATIVE_GROUP } from '../prompt/compile'
-import { ASK_USER } from '../tools/askUser'
-import { SPAWN_SUBAGENT, WAIT_SUBAGENTS } from '../sessions/subagents'
-import { PLUGIN_PROPOSE } from '../tools/pluginPropose'
-import { MEMORY_TOOLS, RECALL_TOOLS, TRAJECTORY_TOOLS, WIKI_TOOLS, type WikiToolDefinition } from '../tools/definitions'
-import { FIRST_PARTY_PLUGINS } from './firstParty'
-import type { PluginDescriptor } from './types'
-
-const tools = (definitions: readonly WikiToolDefinition[]): PluginDescriptor['tools'] => definitions.map((tool) => ({ name: tool.name, description: tool.label }))
-
-/** Pi itself. Its command's built-in extensions are added to it as they are found. */
-export const PI_PLUGIN: PluginDescriptor = {
-  id: 'pi',
-  title: 'Pi',
-  description: 'The engine every session runs on: its base prompt, its file and shell tools, and the extensions built into its command.',
-  required: 'Pi runs every session.',
-  tools: NATIVE_GROUP.map((name) => ({ name })),
-  toolGroups: ['Native']
-}
-
-/** A person's own registry. It owns the rules and skills sections even while it is empty. */
-export const YOURS_PLUGIN: PluginDescriptor = {
-  id: 'yours',
-  title: 'Yours',
-  description: 'Rules, skills and prompts you wrote, kept as files in the registry folder.',
-  manage: 'registry',
-  sections: [
-    { id: 'rules', name: 'Rules', description: 'The full text of every rule that is on.' },
-    { id: 'skills', name: 'Skills list', description: 'One line for each skill that is on.' }
-  ],
-  tools: WIKI_TOOLS.filter((tool) => tool.name === 'skill_load').map((tool) => ({ name: tool.name, description: tool.label }))
-}
-
-export const INCLUDED_PLUGIN: PluginDescriptor = { id: 'included', title: 'Included', description: 'Rules, skills and prompts that ship with the app.', manage: 'registry' }
-
-export const HARNESS_PLUGINS: readonly PluginDescriptor[] = [
-  PI_PLUGIN,
-  { id: 'subagents', title: 'Subagents', description: 'Isolated child runs of the same caller, bounded by parent capabilities and nesting depth.', required: 'Availability is selected by the session host; child runs retain the parent permission boundary.', tools: [{ name: SPAWN_SUBAGENT, description: 'Start a subagent' }, { name: WAIT_SUBAGENTS, description: 'Wait for subagents' }] },
-  {
-    id: 'memory',
-    title: 'Memory',
-    description: 'Blocks of text that are always in context and that the agent edits as it works.',
-    required: 'Every agent keeps its own memory, and the background upkeep depends on it.',
-    // Facts are memory too: what the agent wrote down, recalled on request.
-    tools: tools([...MEMORY_TOOLS, ...WIKI_TOOLS.filter((tool) => tool.name === 'memory_facts')]),
-    sections: [{ id: 'blocks', name: 'Memory blocks', description: 'Every block attached to the caller, in full.' }],
-    toolGroups: ['Memory']
-  },
-  {
-    id: 'wiki',
-    title: 'Wiki',
-    description: 'Pages and facts the agent searches, reads, and proposes changes to.',
-    required: 'What was learned is recorded and checked here.',
-    // `WIKI_TOOLS` is every memory tool; the Wiki's own are the ones that are not Memory's or History's.
-    tools: tools(WIKI_TOOLS.filter((tool) => tool.name.startsWith('wiki_'))),
-    sections: [
-      { id: 'knowledge', name: 'Knowledge map', description: 'Project pages, the Library count, and facts that match the request.' },
-      { id: 'references', name: 'Selected references', description: 'Pages and skills pinned to one request.' }
-    ],
-    toolGroups: ['Knowledge']
-  },
-  { id: 'history', title: 'History', description: 'Search earlier conversations and inspect recorded run trajectories.', required: 'Earlier runs are how an agent picks up where work stopped.', tools: tools([...RECALL_TOOLS, ...TRAJECTORY_TOOLS]) },
-  {
-    id: 'plugin-proposals',
-    title: 'Plugin proposals',
-    description: 'Lets an agent propose a plugin. You accept it in the Inbox, switch it on, and trust its code; an agent can do none of those.',
-    required: 'It only proposes. Nothing is saved or run until you decide.',
-    tools: [{ name: PLUGIN_PROPOSE, description: 'Propose a plugin' }]
-  },
-  { id: 'ask-user', title: 'Ask the user', description: 'Lets the agent stop and ask a question with choices.', required: 'An agent must be able to stop and ask you.', tools: [{ name: ASK_USER }] },
-  {
-    id: 'connected-apps',
-    title: 'Connected apps',
-    description: 'Outside services reached over MCP, behind two tools that list and call what is connected.',
-    required: 'Connected apps are reached only through it. Each app is switched on its own.',
-    manage: 'connections',
-    tools: CONNECTION_TOOLS.map((name) => ({ name })),
-    toolGroups: ['Connections']
-  },
-  YOURS_PLUGIN,
-  ...FIRST_PARTY_PLUGINS
-]

package/src/plugins/catalogue.test.ts

@@ -1,254 +0,0 @@
-import { mkdtempSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { afterEach, describe, expect, it } from 'vitest'
-
-import { memorySecretStore } from '../accounts/secrets'
-import { createHarness, type Harness } from '../harness'
-import { methods } from '../server/methods'
-import { WIKI_TOOLS } from '../tools/definitions'
-import { WEB_PLUGIN } from '../web/tools'
-import { rootWithProject, writeFile } from '../../tests/helpers'
-import { HARNESS_PLUGINS } from './builtin'
-import type { Found } from './discover'
-import type { Inventory, Plugin, PluginDescriptor } from './types'
-
-const open: Harness[] = []
-afterEach(async () => {
-  for (const harness of open.splice(0)) await harness.close()
-})
-
-const APP_PLUGINS: PluginDescriptor[] = [
-  WEB_PLUGIN,
-  { id: 'app-identity', title: 'Identity and roles', description: 'Who the agent is.', required: 'It names the agent.', sections: [{ id: 'identity', name: 'Identity line' }] },
-  { id: 'app-tasks', title: 'Tasks', description: 'Hands work to other sessions.', tools: [{ name: 'start_task', description: 'Start a task' }], toolGroups: ['Tasks'] }
-]
-
-function setup() {
-  const root = rootWithProject()
-  writeFile(join(root, 'registry/rules/tests.md'), '---\nname: Run tests\ndescription: Always test.\n---\nAlways run the test suite before finishing.\n')
-  writeFile(join(root, 'registry/skills/release/SKILL.md'), '---\nname: Release notes\ndescription: Write release notes from commits.\n---\nSteps.\n')
-  writeFile(join(root, 'registry/prompts/review.md'), 'Review this change.\n')
-  writeFile(join(root, 'registry/skills/unused.md'), '# Unused\n')
-  writeFile(join(root, 'config/registry-enabled.json'), JSON.stringify({ global: ['rules/tests'], p1: ['skills/release', 'prompts/review'] }))
-  const base = mkdtempSync(join(tmpdir(), 'catalogue-'))
-  const cwd = join(base, 'project')
-  writeFile(join(cwd, '.pi/extensions/local.ts'), 'export default function () {}\n')
-  writeFile(join(cwd, 'AGENTS.md'), 'Use tabs.\n')
-  writeFile(join(base, 'package/package.json'), JSON.stringify({ name: 'review-kit', description: 'Review helpers.', version: '1.2.0' }))
-  writeFile(join(base, 'package/extensions/guard.ts'), 'export default function () {}\n')
-  writeFile(join(base, 'package/skills/audit/SKILL.md'), '---\nname: audit\ndescription: Audit a change.\n---\nSteps.\n')
-  writeFile(join(base, 'home/.agents/skills/deploy/SKILL.md'), '---\nname: deploy\ndescription: Deploy a site.\n---\nSteps.\n')
-  const item = (kind: Found['kind'], path: string, origin: Found['origin'], rest: Partial<Found> = {}): Found => ({ kind, path, origin, project: origin === 'project', packageRoot: null, source: null, enabled: true, ...rest })
-  const found: Found[] = [
-    item('extension', join(cwd, '.pi/extensions/local.ts'), 'project'),
-    item('context', join(cwd, 'AGENTS.md'), 'project'),
-    item('extension', join(base, 'package/extensions/guard.ts'), 'package', { packageRoot: join(base, 'package'), source: 'npm:review-kit' }),
-    item('skill', join(base, 'package/skills/audit/SKILL.md'), 'package', { packageRoot: join(base, 'package'), source: 'npm:review-kit' }),
-    item('skill', join(base, 'home/.agents/skills/deploy/SKILL.md'), 'home'),
-    item('extension', 'builtin:mcp', 'builtin'),
-    item('extension', 'builtin:llama.cpp', 'builtin', { enabled: false })
-  ]
-  const harness = createHarness({ dataRoot: root, stateDir: mkdtempSync(join(tmpdir(), 'hs-')), secrets: memorySecretStore(), plugins: APP_PLUGINS, resolver: async () => found })
-  open.push(harness)
-  harness.accounts.create('Main', 'apiKey')
-  const call = methods(harness)
-  return { harness, root, cwd, base, call: <T>(method: string, params: Record<string, unknown> = {}) => call[method](params) as Promise<T> }
-}
-
-const summary = (plugins: Plugin[]) => plugins.map((plugin) => [plugin.id, plugin.source, plugin.contributions.map((entry) => `${entry.kind}:${entry.name}:${entry.state}`)])
-
-describe('the plugin list', () => {
-  it('has every source as bundles, with what each contributes and who it is on for', async () => {
-    const { call, cwd, base, harness } = setup()
-    const loading = await harness.plugins.loading({ cwd, agentDir: harness.accounts.context(harness.accounts.resolve(null, null)).configDir })
-    harness.plugins.loaded([{ path: join(base, 'package/extensions/guard.ts'), hash: loading.packageCode[join(base, 'package')].hash, hooks: ['tool_call'], tools: [], commands: ['guard'], flags: [], shortcuts: [] }])
-    const plugins = await call<Plugin[]>('plugins.list', { cwd })
-    expect(summary(plugins.filter((plugin) => !['builtin', 'pi'].includes(plugin.source)))).toEqual([
-      ['project', 'project', ['code:local.ts:untrusted', 'instruction:AGENTS.md:on']],
-      ['package:review-kit', 'package', ['code:guard.ts:on', 'command:guard:on', 'skill:audit:on']],
-      ['home', 'home', ['skill:deploy:on']],
-      ['yours', 'yours', ['instruction:Rules:on', 'instruction:Skills list:on', 'tool:skill_load:on', 'command:review:on', 'instruction:Run tests:on', 'skill:Release notes:on', 'skill:unused:off']],
-      ['app-identity', 'application', ['instruction:Identity line:on']],
-      ['app-tasks', 'application', ['tool:start_task:on']],
-      ['web', 'application', ['tool:web_search:on', 'tool:web_fetch:on']]
-    ])
-    expect(plugins.filter((plugin) => plugin.source === 'builtin').map((plugin) => plugin.id)).toEqual(['ask-user', 'budget-guard', 'connected-apps', 'history', 'memory', 'output-trim', 'plugin-proposals', 'subagents', 'wiki'])
-
-    const kit = plugins.find((plugin) => plugin.id === 'package:review-kit')!
-    // It was there when trust was first asked per package, so it was taken over as trusted.
-    expect(kit).toMatchObject({ title: 'review-kit', description: 'Review helpers.', version: '1.2.0', runsCode: true, trust: 'trusted', code: { files: ['extensions/guard.ts', 'package.json', 'skills/audit/SKILL.md'] }, path: join(base, 'package') })
-    expect(kit.contributions[0].description).toBe('Adds commands /guard; hooks tool_call.')
-    const project = plugins.find((plugin) => plugin.id === 'project')!
-    expect(project).toMatchObject({ runsCode: true, trust: 'untrusted', code: { files: ['.pi/extensions/local.ts'] } })
-    const yours = plugins.find((plugin) => plugin.id === 'yours')!
-    expect(yours.contributions.map((entry) => entry.scope)).toEqual([null, null, null, 'App', 'Everywhere', 'App', null])
-    const pi = plugins.find((plugin) => plugin.id === 'pi')!
-    expect(pi.required).toBe('Pi runs every session.')
-    expect(pi.contributions.filter((entry) => entry.kind === 'code').map((entry) => [entry.name, entry.state])).toEqual([['mcp', 'on'], ['llama.cpp', 'off']])
-  })
-
-  it('gives every tool, prompt section and tool group of the harness to one plugin', () => {
-    for (const pick of [(plugin: PluginDescriptor) => (plugin.tools ?? []).map((tool) => tool.name), (plugin: PluginDescriptor) => (plugin.sections ?? []).map((section) => section.id), (plugin: PluginDescriptor) => plugin.toolGroups ?? []]) {
-      const names = HARNESS_PLUGINS.flatMap(pick)
-      expect(names.filter((name, index) => names.indexOf(name) !== index)).toEqual([])
-    }
-    const declared = HARNESS_PLUGINS.flatMap((plugin) => (plugin.tools ?? []).map((tool) => tool.name))
-    expect(WIKI_TOOLS.map((tool) => tool.name).filter((name) => !declared.includes(name))).toEqual([])
-  })
-
-  it('lists nothing a folder brings when no folder is named, and what every account shares even before the first account exists', async () => {
-    const { call } = setup()
-    expect((await call<Plugin[]>('plugins.list')).map((plugin) => plugin.id)).not.toContain('project')
-    const fresh = createHarness({ dataRoot: rootWithProject(), stateDir: mkdtempSync(join(tmpdir(), 'hs-')), secrets: memorySecretStore(), resolver: async () => [{ kind: 'skill', path: '/shared/skills/a/SKILL.md', origin: 'shared', project: false, packageRoot: null, source: null, enabled: true }] })
-    open.push(fresh)
-    // The shared folder is the same for every account, so it stands in until there is one.
-    expect(((await methods(fresh)['plugins.list']({})) as Plugin[]).map((plugin) => plugin.source)).toContain('shared')
-    // An account that was named and does not exist is not replaced by anything.
-    expect(((await methods(fresh)['plugins.list']({ accountId: 'missing' })) as Plugin[]).map((plugin) => plugin.source)).not.toContain('shared')
-  })
-
-  it("trusts a folder's code only while it is the code that was shown", async () => {
-    const { call, cwd } = setup()
-    const before = (await call<Plugin[]>('plugins.list', { cwd })).find((plugin) => plugin.id === 'project')!
-    await expect(call('plugins.trust', { cwd, hash: 'stale' })).rejects.toMatchObject({ message: expect.stringContaining('changed since it was shown') })
-    const trusted = (await call<Plugin[]>('plugins.trust', { cwd, hash: before.code!.hash })).find((plugin) => plugin.id === 'project')!
-    expect(trusted.trust).toBe('trusted')
-    expect(trusted.contributions[0].state).toBe('on')
-
-    writeFileSync(join(cwd, '.pi/extensions/local.ts'), 'export default function () { /* changed */ }\n')
-    expect((await call<Plugin | null>('plugins.get', { cwd, pluginId: 'project' }))?.trust).toBe('untrusted')
-    const again = (await call<Plugin | null>('plugins.get', { cwd, pluginId: 'project' }))!
-    await call('plugins.trust', { cwd, hash: again.code!.hash })
-    expect((await call<Plugin[]>('plugins.untrust', { cwd, hash: again.code!.hash })).find((plugin) => plugin.id === 'project')?.trust).toBe('untrusted')
-  })
-})
-
-describe('what reaches one caller', () => {
-  const launch = {
-    tools: ['read', 'bash', 'start_task', 'web_search'],
-    connections: 'Use mcp_list_tools.',
-    sections: [{ id: 'identity', title: 'Identity', body: 'You are Ada.', budget: 500, order: 10 }],
-    toolGroups: [{ group: 'Tasks', tools: ['start_task'], guidance: 'Tasks: start_task hands work to another session.', order: 40 }]
-  }
-
-  it('attributes every prompt section, tool group and tool to a plugin', async () => {
-    const { call, cwd } = setup()
-    const result = await call<Inventory>('plugins.inventory', { cwd, context: { agentId: 'a1', projectId: 'p1' }, launch, tools: ['read', 'bash', 'start_task', 'web_search'] })
-    expect(result.unattributed).toEqual([])
-    const of = (plugin: string) => result.items.filter((item) => item.pluginId === plugin).map((item) => `${item.kind}:${item.name}:${item.delivery}`)
-    expect(of('app-identity')).toEqual(['instruction:Identity line:system'])
-    expect(of('app-tasks')).toEqual(['instruction:Tool guidance: Tasks:system', 'tool:start_task:tool'])
-    expect(of('yours')).toEqual(['instruction:Run tests:system', 'instruction:Skills list:system', 'command:review:on-demand', 'skill:Release notes:on-demand', 'tool:skill_load:tool'])
-    // Facts are memory: recalling them is a memory tool, though it is defined beside the Wiki's.
-    expect(of('memory')).toEqual(['instruction:Memory blocks:context', 'instruction:Tool guidance: Memory:system', 'tool:memory_append:tool', 'tool:memory_replace:tool', 'tool:memory_rethink:tool', 'tool:memory_facts:tool'])
-    expect(of('pi')).toEqual(['instruction:Tool guidance: Native:system', 'tool:read:tool', 'tool:bash:tool', 'instruction:Base prompt:system'])
-    // The working folder's code is not trusted, so only its instruction file reaches the caller.
-    expect(of('project')).toEqual(['instruction:AGENTS.md:system'])
-    expect(of('package:review-kit')).toEqual(['code:guard.ts:code', 'skill:audit:on-demand'])
-    expect(result.items.find((item) => item.name === 'Run tests')).toMatchObject({ contributionId: 'yours/rules/tests', cut: false })
-    expect(result.items.find((item) => item.name === 'AGENTS.md')?.chars).toBe(10)
-    expect(result.systemChars).toBeGreaterThan(0)
-    expect(result.contextChars).toBeGreaterThan(0)
-    expect(result.plugins.map((plugin) => plugin.id)).not.toContain('home-not-there')
-    expect(result.plugins.every((plugin) => result.items.some((item) => item.pluginId === plugin.id))).toBe(true)
-  })
-
-  it('reports what no plugin accounts for', async () => {
-    const { call } = setup()
-    const result = await call<Inventory>('plugins.inventory', {
-      context: { agentId: 'a1' },
-      launch: { ...launch, sections: [...launch.sections, { id: 'mystery', title: 'Mystery', body: 'Unlisted text.', budget: 500, order: 20 }], toolGroups: [...launch.toolGroups, { group: 'Secret', tools: ['hidden_tool'], guidance: 'Secret: hidden_tool.', order: 50 }], tools: [...launch.tools, 'hidden_tool'] },
-      tools: [...launch.tools, 'hidden_tool']
-    })
-    expect(result.unattributed).toEqual([
-      { kind: 'section', id: 'mystery' },
-      { kind: 'toolGroup', id: 'Secret' },
-      { kind: 'tool', id: 'hidden_tool' }
-    ])
-  })
-
-  it("lists the pi command's own extensions only for a terminal session", async () => {
-    const { call } = setup()
-    const names = async (context: Record<string, unknown>) => (await call<Inventory>('plugins.inventory', { context, launch })).items.filter((item) => item.kind === 'code' && item.pluginId === 'pi').map((item) => item.name)
-    expect(await names({ agentId: 'a1' })).toEqual([])
-    expect(await names({ sessionId: 's1', actor: 'Code', surface: 'cli' })).toEqual(['mcp'])
-  })
-})
-
-describe('switching a plugin on and off', () => {
-  const state = (plugins: Plugin[], id: string) => plugins.flatMap((plugin) => plugin.contributions).find((entry) => entry.id === id)?.state
-
-  it('switches a registry item for one agent, and the agent then gets it in its prompt', async () => {
-    const { call } = setup()
-    const compiled = async (agentId: string) => (await call<{ text: string }>('context.compile', { context: { agentId, actor: 'Chat' }, render: true })).text
-    expect(await compiled('a1')).not.toContain('Release notes')
-    const after = await call<Plugin[]>('plugins.attach', { id: 'yours/skills/release', scope: { agentId: 'a1' } })
-    const release = after.flatMap((plugin) => plugin.contributions).find((entry) => entry.id === 'yours/skills/release')!
-    expect(release.attachment).toEqual({ global: false, on: { agentIds: ['a1'], projectIds: ['p1'] }, off: { agentIds: [], projectIds: [] } })
-    expect(release.scope).toBe('App, 1 agent')
-    expect(await compiled('a1')).toContain('Release notes')
-    expect(await compiled('a2')).not.toContain('Release notes')
-    // The earlier calls read the same choices.
-    expect((await call<any>('skills.list')).enabled).toEqual({ global: ['rules/tests'], p1: ['skills/release', 'prompts/review'] })
-
-    // A rule that is on everywhere is switched off for one agent only.
-    await call('plugins.detach', { id: 'yours/rules/tests', scope: { agentId: 'a1' } })
-    expect(await compiled('a1')).not.toContain('Always run the test suite')
-    expect(await compiled('a2')).toContain('Always run the test suite')
-    expect(state(await call<Plugin[]>('plugins.list', { agentId: 'a1' }), 'yours/rules/tests')).toBe('off')
-    expect(state(await call<Plugin[]>('plugins.list', { agentId: 'a2' }), 'yours/rules/tests')).toBe('on')
-
-    await call('plugins.forgetAgent', { agentId: 'a1' })
-    expect(await compiled('a1')).toContain('Always run the test suite')
-  })
-
-  it('stops a found plugin, or one item of it, from loading for the caller it was switched off for', async () => {
-    const { call, harness, cwd, base } = setup()
-    const agentDir = harness.accounts.context(harness.accounts.resolve(null, null)).configDir
-    const guard = join(base, 'package/extensions/guard.ts')
-    const audit = join(base, 'package/skills/audit/SKILL.md')
-    const loaded = async (caller: { agentId?: string; projectId?: string }) => {
-      const loading = await harness.plugins.loading({ cwd, agentDir, caller })
-      return { guard: loading.extensionPaths.includes(guard), audit: loading.skillPaths.includes(audit) }
-    }
-    expect(await loaded({})).toEqual({ guard: true, audit: true })
-
-    const off = await call<Plugin[]>('plugins.detach', { cwd, id: 'package:review-kit', scope: { projectId: 'p1' } })
-    expect(off.find((plugin) => plugin.id === 'package:review-kit')!.attachment).toEqual({ global: true, on: { agentIds: [], projectIds: [] }, off: { agentIds: [], projectIds: ['p1'] } })
-    expect(await loaded({ projectId: 'p1' })).toEqual({ guard: false, audit: false })
-    expect(await loaded({})).toEqual({ guard: true, audit: true })
-    // One item back on, inside a plugin that is off.
-    await call('plugins.attach', { cwd, id: 'package:review-kit/skill/audit', scope: { projectId: 'p1' } })
-    expect(await loaded({ projectId: 'p1' })).toEqual({ guard: false, audit: true })
-    expect(summary(await call<Plugin[]>('plugins.list', { cwd, projectId: 'p1' })).find(([id]) => id === 'package:review-kit')![2]).toEqual(['code:guard.ts:off', 'skill:audit:on'])
-
-    // What is switched off does not reach the caller's inventory either.
-    const inventory = await call<Inventory>('plugins.inventory', { cwd, context: { projectId: 'p1', actor: 'Code' } })
-    expect(inventory.items.filter((item) => item.pluginId === 'package:review-kit').map((item) => item.name)).toEqual(['audit'])
-  })
-
-  it('refuses a required part, an application part, and a file Pi reads itself, and says why', async () => {
-    const { call, cwd } = setup()
-    await expect(call('plugins.detach', { id: 'memory' })).rejects.toThrow('Memory cannot be switched off. Every agent keeps its own memory')
-    await expect(call('plugins.detach', { id: 'memory/tool/memory_append' })).rejects.toThrow('cannot be switched off')
-    await expect(call('plugins.detach', { id: 'app-tasks' })).rejects.toThrow('switched by the application')
-    await expect(call('plugins.detach', { id: 'yours' })).rejects.toThrow('one item at a time')
-    await expect(call('plugins.detach', { cwd, id: 'project/instruction/AGENTS.md' })).rejects.toThrow('cannot be switched on its own')
-    await expect(call('plugins.detach', { id: 'no-such-plugin' })).rejects.toThrow()
-    await expect(call('plugins.attach', { id: 'yours/skills/release', scope: { projectId: 'nope' } })).rejects.toThrow()
-  })
-
-  it('switches a connected app for one agent through its own scope', async () => {
-    const { call, harness } = setup()
-    await harness.apps.save({ id: 'c1', name: 'Docs', kind: 'local', command: 'docs-server', enabled: true, global: true })
-    const id = 'connected-apps/connection/c1'
-    const off = await call<Plugin[]>('plugins.detach', { id, scope: { agentId: 'a1' } })
-    expect(off.flatMap((plugin) => plugin.contributions).find((entry) => entry.id === id)).toMatchObject({ state: 'on', scope: 'Everywhere', attachment: { global: true, off: { agentIds: ['a1'], projectIds: [] } } })
-    expect(harness.apps.connections.forScope({ agentId: 'a1' })).toEqual([])
-    expect(harness.apps.connections.forScope({ agentId: 'a2' }).map((connection) => connection.id)).toEqual(['c1'])
-    await call('plugins.attach', { id, scope: { agentId: 'a1' } })
-    expect(harness.apps.connections.forScope({ agentId: 'a1' }).map((connection) => connection.id)).toEqual(['c1'])
-  })
-})
-

package/src/plugins/catalogue.ts

@@ -1,251 +0,0 @@
-// Every plugin there is, from every source, as one list. Building it reads files and settings;
-// it runs no plugin's code and changes nothing.
-import { basename, dirname, join } from 'node:path'
-
-import { projectsOrNone } from '../core/projects'
-import { compareText } from '../core/text'
-import type { Connection } from '../mcp/types'
-import * as registry from '../skills/registry'
-import { attached, describe, type Attachment, type Attachments, type AttachScope } from './attachments'
-import { INCLUDED_PLUGIN, YOURS_PLUGIN } from './builtin'
-import { settingValue } from './firstParty'
-import { BUILTIN_PREFIX, type Found } from './discover'
-import { registrationHash } from './runtime'
-import { contributionId, describeFound, FOUND_KINDS, packageManifest, pluginIdOf } from './identity'
-import type { HookStatus } from './hooks'
-import { loads, switchable, trustedBy, type Loading, type Registered, type Trusted } from './plugins'
-import type { Contribution, ContributionKind, Plugin, PluginDescriptor, PluginSource } from './types'
-
-export interface CatalogueInput {
-  root: string
-  /** The harness's own parts, then the application's. */
-  descriptors: readonly PluginDescriptor[]
-  /** Ids of the descriptors the application supplied. */
-  application: ReadonlySet<string>
-  connections: readonly Connection[]
-  /** What was found for one account and working folder, or `null` when there is no account yet. */
-  loading: Loading | null
-  /** The working folder the list is for. Without one, nothing a folder brings is listed. */
-  cwd: string | null
-  /** The folder every account shares. */
-  sharedDir: string
-  /** The folder of packages kept with a person's data. */
-  packagesDir: string
-  /** What each hooks file listens for and how its last run went, by its path. */
-  hooks: Record<string, HookStatus>
-  registered: Record<string, Registered>
-  /** The choices a person made about what is switched on. */
-  attachments: Attachments
-  /** Whose list this is. With an agent or a project, each state is what that caller gets. */
-  caller: AttachScope
-}
-
-const REGISTRY_KINDS: Record<string, ContributionKind> = { rules: 'instruction', skills: 'skill', prompts: 'command' }
-
-const contribution = (plugin: string, kind: ContributionKind, name: string, rest: Partial<Contribution> = {}): Contribution => ({
-  id: contributionId(plugin, kind, name),
-  kind,
-  name,
-  description: '',
-  path: null,
-  state: 'on',
-  scope: null,
-  attachment: null,
-  registered: null,
-  problem: null,
-  background: false,
-  ...rest
-})
-
-function fromDescriptor(descriptor: PluginDescriptor, source: PluginSource, attachments: Attachments | null = null, caller: AttachScope = {}): Plugin {
-  const switchable = descriptor.switchable && attachments ? descriptor.switchable : null
-  const on = switchable ? attached(attachments!, [descriptor.id], caller, switchable.on) : true
-  return {
-    id: descriptor.id,
-    title: descriptor.title,
-    description: descriptor.description,
-    version: null,
-    source,
-    path: null,
-    runsCode: !!descriptor.code?.length,
-    trust: 'none',
-    code: null,
-    install: null,
-    extends: [],
-    required: descriptor.required ?? null,
-    manage: descriptor.manage ?? (descriptor.tools?.length ? 'tools' : null),
-    settings: (descriptor.settings ?? []).map((setting) => ({ ...setting, value: settingValue(setting, attachments?.settings[descriptor.id]) })),
-    connectorTemplates: descriptor.connectorTemplates ?? [],
-    attachment: switchable ? describe(attachments!, descriptor.id, switchable.on) : null,
-    contributions: [
-      ...(descriptor.code ?? []).map((code) => contribution(descriptor.id, 'code', code.name, { description: code.description, state: on ? 'on' : 'off' })),
-      ...(descriptor.sections ?? []).map((section) => contribution(descriptor.id, 'instruction', section.name, { description: section.description ?? '' })),
-      ...(descriptor.tools ?? []).map((tool) => contribution(descriptor.id, 'tool', tool.name, { description: tool.description ?? '' }))
-    ]
-  }
-}
-
-const named = (ids: readonly string[], names: Map<string, string>): string[] => ids.flatMap((id) => (names.has(id) ? [names.get(id)!] : []))
-const counted = (count: number, word: string): string => (count ? `${count} ${word}${count === 1 ? '' : 's'}` : '')
-
-/** Who something is switched on for, in words; `null` when it is on for nobody. */
-function scopeWords(attachment: Attachment, projects: Map<string, string>): string | null {
-  if (attachment.global) {
-    const except = [counted(attachment.off.agentIds.length, 'agent'), ...named(attachment.off.projectIds, projects)].filter(Boolean)
-    return except.length ? `Everywhere except ${except.join(', ')}` : 'Everywhere'
-  }
-  const parts = [...named(attachment.on.projectIds, projects), counted(attachment.on.agentIds.length, 'agent')].filter(Boolean)
-  return parts.length ? parts.join(', ') : null
-}
-
-/** A person's registry items, and the built-in ones, as contributions with who each is on for. */
-function registryContributions(input: CatalogueInput, projects: Map<string, string>): { yours: Contribution[]; included: Contribution[] } {
-  const yours: Contribution[] = []
-  const included: Contribution[] = []
-  const scoped = !!(input.caller.agentId || input.caller.projectId)
-  for (const item of registry.list(input.root)) {
-    const kind = REGISTRY_KINDS[item.kind]
-    if (!kind) continue
-    // A registry item's choices are stored under its own id, whichever plugin lists it.
-    const attachment = describe(input.attachments, item.id, !!item.builtin)
-    const scope = scopeWords(attachment, projects)
-    const on = scoped ? attached(input.attachments, [item.id], input.caller, !!item.builtin) : scope !== null
-    const plugin = item.builtin ? INCLUDED_PLUGIN.id : YOURS_PLUGIN.id
-    ;(item.builtin ? included : yours).push({ ...contribution(plugin, kind, item.name, { description: item.description, path: item.path, state: on ? 'on' : 'off', scope, attachment }), id: `${plugin}/${item.id}` })
-  }
-  return { yours, included }
-}
-
-/** A connection keeps its own scope; this is the same shape for a screen. */
-function connectionAttachment(connection: Connection): Attachment | null {
-  if (!connection.enabled) return null
-  return { global: connection.global, on: { agentIds: connection.agentIds, projectIds: connection.projectIds }, off: { agentIds: connection.excludedAgentIds, projectIds: connection.excludedProjectIds } }
-}
-
-function connectionScope(connection: Connection): string | null {
-  if (!connection.enabled) return null
-  if (connection.global) return 'Everywhere'
-  const parts = [counted(connection.agentIds.length, 'agent'), counted(connection.projectIds.length, 'project')].filter(Boolean)
-  return parts.length ? parts.join(', ') : null
-}
-
-const CONTEXT_NOTES: Record<string, string> = {
-  'SYSTEM.md': "Replaces Pi's base prompt.",
-  'APPEND_SYSTEM.md': "Added to the end of Pi's base prompt."
-}
-
-/** What an extension added, in a line; or that no session has loaded it yet. */
-function registeredLine(entry: Registered | undefined): string {
-  if (!entry) return 'Not loaded in a session yet, so what it adds is not known.'
-  const parts = [
-    entry.commands.length ? `commands ${entry.commands.map((name) => `/${name}`).join(', ')}` : '',
-    entry.tools.length ? `tools ${entry.tools.join(', ')}` : '',
-    entry.hooks.length ? `hooks ${entry.hooks.join(', ')}` : '',
-    entry.flags.length ? `flags ${entry.flags.map((name) => `--${name}`).join(', ')}` : '',
-    entry.shortcuts.length ? `shortcuts ${entry.shortcuts.join(', ')}` : ''
-  ].filter(Boolean)
-  return parts.length ? `Adds ${parts.join('; ')}.` : 'Registers nothing a session can see.'
-}
-
-function foundContribution(plugin: string, item: Found, trusted: Trusted, input: CatalogueInput, projects: Map<string, string>): Contribution {
-  const kind = FOUND_KINDS[item.kind]
-  const { name, description } = describeFound(item)
-  const id = contributionId(plugin, kind, name)
-  // A hook runs for everyone or not at all: it follows its plugin's switch for everyone and has none of its own.
-  const attachment = switchable(item) && item.kind !== 'hook' ? describe(input.attachments, id, attached(input.attachments, [plugin], {}, true)) : null
-  const on = item.kind === 'hook' ? attached(input.attachments, [plugin], {}, true) : !attachment || attached(input.attachments, [id, plugin], input.caller, true)
-  const state = !item.enabled || !on ? 'off' : loads(item, trusted) ? 'on' : 'untrusted'
-  const rest = { state, attachment, scope: attachment ? scopeWords(attachment, projects) : null } as const
-  if (item.path.startsWith(BUILTIN_PREFIX)) return contribution(plugin, kind, name, { ...rest, description: 'Built into the pi command. A terminal session loads it; other sessions do not have it.' })
-  if (item.kind === 'extension') {
-    const observed = input.registered[item.path]
-    const hash = input.loading ? registrationHash(input.loading, item.path) : null
-    const current = observed && hash !== null && observed.hash === hash ? observed : undefined
-    return contribution(plugin, kind, name, { ...rest, description: registeredLine(current), path: item.path, registered: current ?? null })
-  }
-  if (item.kind === 'hook') {
-    const status = input.hooks[item.path]
-    const events = status?.events ?? []
-    const described = events.length ? `Runs in the background after: ${events.join(', ')}.` : state === 'on' ? 'Runs in the background. It has not said what it listens for yet.' : 'Runs in the background once it is switched on for everyone and trusted.'
-    return contribution(plugin, kind, name, { ...rest, description: described, path: item.path, problem: status?.lastError ?? null, background: true })
-  }
-  if (item.kind === 'context') return contribution(plugin, kind, name, { ...rest, description: CONTEXT_NOTES[basename(item.path)] ?? 'Read by Pi at the start of every session in this folder.', path: item.path })
-  return contribution(plugin, kind, name, { ...rest, description: description ?? '', path: item.path })
-}
-
-const empty = (id: string, title: string, description: string, source: PluginSource, path: string | null): Plugin => ({ id, title, description, version: null, source, path, runsCode: false, trust: 'none', code: null, install: null, extends: [], required: null, manage: 'files', settings: [], connectorTemplates: [], attachment: null, contributions: [] })
-
-export function catalogue(input: CatalogueInput): Plugin[] {
-  const plugins = new Map<string, Plugin>()
-  for (const descriptor of input.descriptors) plugins.set(descriptor.id, fromDescriptor(descriptor, descriptor.id === 'pi' ? 'pi' : descriptor.id === YOURS_PLUGIN.id ? 'yours' : input.application.has(descriptor.id) ? 'application' : 'builtin', input.attachments, input.caller))
-
-  const projects = new Map(projectsOrNone(input.root).map((project) => [project.id, project.name]))
-  const items = registryContributions(input, projects)
-  const yours = plugins.get(YOURS_PLUGIN.id)
-  if (yours) {
-    yours.path = join(input.root, 'registry')
-    yours.contributions.push(...items.yours)
-  }
-  if (items.included.length) plugins.set(INCLUDED_PLUGIN.id, { ...fromDescriptor(INCLUDED_PLUGIN, 'builtin'), contributions: items.included })
-
-  const apps = plugins.get('connected-apps')
-  if (apps) {
-    for (const connection of input.connections) {
-      const scope = connectionScope(connection)
-      apps.contributions.push({ ...contribution(apps.id, 'connection', connection.name || connection.id, { description: connection.serverName ?? connection.url ?? connection.command, state: scope ? 'on' : 'off', scope, attachment: connectionAttachment(connection) }), id: `${apps.id}/connection/${connection.id}` })
-    }
-  }
-
-  const loading = input.loading
-  const trusted = trustedBy(loading)
-  for (const item of loading?.found ?? []) {
-    if (item.project && !input.cwd) continue
-    const id = pluginIdOf(item)
-    let plugin = plugins.get(id)
-    if (!plugin) {
-      if (item.origin === 'builtin') continue
-      if (item.packageRoot) {
-        const manifest = packageManifest(item.packageRoot)
-        // A package a working folder's settings name is that folder's to remove, not a person's install.
-        const install = item.project ? null : item.packageRoot.startsWith(`${input.packagesDir}/`) ? ({ kind: 'folder', source: item.packageRoot } as const) : item.source ? ({ kind: 'settings', source: item.source } as const) : null
-        // Only parts that exist can be extended; a made-up name is dropped.
-        const extended = manifest.extends.filter((part) => input.descriptors.some((descriptor) => descriptor.id === part))
-        plugin = { ...empty(id, manifest.name, manifest.description, item.project ? 'project' : 'package', item.packageRoot), version: manifest.version, install, extends: extended, connectorTemplates: manifest.connectorTemplates }
-      } else if (item.origin === 'home') plugin = empty(id, 'Home folder skills', 'Skills in the .agents folder of your home folder. Pi reads them for every account.', 'home', dirname(dirname(item.path)))
-      else if (item.origin === 'project') plugin = empty(id, 'Project folder', 'Found in the working folder: its .pi and .agents folders, and the instruction files Pi reads on the way up from it.', 'project', input.cwd)
-      else plugin = empty(id, 'Shared Pi folder', 'Extensions, skills, prompts and instruction files in the folder every account shares.', 'shared', input.sharedDir)
-      plugin.attachment = describe(input.attachments, id, true)
-      plugins.set(id, plugin)
-    }
-    const added = foundContribution(plugin.id, item, trusted, input, projects)
-    if (plugin.contributions.some((existing) => existing.id === added.id)) continue
-    plugin.contributions.push(added)
-    if (item.kind === 'extension' && added.registered) {
-      const registered = added.registered
-      const append = (kind: ContributionKind, name: string, rest: Partial<Contribution> = {}) => {
-        const id = contributionId(plugin!.id, kind, name)
-        if (!plugin!.contributions.some((existing) => existing.id === id)) plugin!.contributions.push(contribution(plugin!.id, kind, name, { state: added.state, description: `Registered by ${added.name}. Observed ${registered.seenAt ?? 'in a session'}.`, ...rest }))
-      }
-      for (const name of registered.tools) append('tool', name)
-      for (const name of registered.commands) append('command', name)
-      for (const resource of registered.resources ?? []) {
-        const id = contributionId(plugin.id, resource.kind, resource.name)
-        const on = attached(input.attachments, [id, plugin.id], input.caller, true)
-        append(resource.kind, resource.name, { path: resource.path, state: on ? added.state : 'off', attachment: describe(input.attachments, id, attached(input.attachments, [plugin.id], {}, true)) })
-      }
-    }
-    if (added.kind === 'code' && item.origin !== 'builtin') {
-      plugin.runsCode = true
-      // A working folder's code and an installed package's wait for trust; a loose file in the
-      // shared folder was placed by the person.
-      const code = item.project ? loading?.projectCode : item.packageRoot ? loading?.packageCode[item.packageRoot] : null
-      if (code) {
-        plugin.trust = code.trusted ? 'trusted' : 'untrusted'
-        plugin.code = { hash: code.hash, files: code.files }
-      }
-    }
-  }
-
-  const order: PluginSource[] = ['project', 'package', 'shared', 'home', 'yours', 'application', 'builtin', 'pi']
-  return [...plugins.values()].sort((left, right) => order.indexOf(left.source) - order.indexOf(right.source) || compareText(left.title, right.title))
-}