@xingular/harness 0.1.7 → 1.0.0

package/src/plugins/cli.ts

@@ -1,184 +0,0 @@
-// `xingular-harness plugins …`: plugin control for a person using the harness without an
-// application. It runs outside any session, as the person who typed it, and acts directly.
-import { homedir } from 'node:os'
-import { join, resolve } from 'node:path'
-import { createInterface } from 'node:readline/promises'
-
-import { Harness, type HarnessOptions } from '../harness'
-import * as api from './api'
-import * as install from './install'
-import type { Plugin } from './types'
-
-export const PLUGINS_USAGE = `Usage: xingular-harness plugins <command> [options]
-
-  list                         Every plugin and whether it is on
-  show <plugin id>             One plugin: what it brings, where it is on, its code
-  install <source>             A folder, an npm name, or a git address. It arrives off and untrusted
-  remove <plugin id>           Remove a plugin you installed
-  update [plugin id]           Fetch a newer version of one installed plugin, or of all
-  attach <id>                  Switch a plugin, or one thing it brings, on
-  detach <id>                  Switch it off
-  trust <plugin id> [--yes]    Show the files of its code, then trust them
-  untrust <plugin id>          Stop trusting its code
-
-Options:
-  --data <dir>       Data directory (default: ~/.xingular-harness/data)
-  --state <dir>      State directory (default: ~/.xingular-harness/state)
-  --cwd <dir>        Also list what this working folder brings
-  --project <id>     attach/detach for one project instead of everywhere
-  --agent <id>       attach/detach for one agent instead of everywhere
-`
-
-export interface PluginsCliDependencies {
-  home?: string
-  cwd?: string
-  write?: (text: string) => void
-  /** Asks the person a question and returns what they typed. Without it, a trust needs `--yes`. */
-  ask?: (question: string) => Promise<string>
-  createHarness?: (options: HarnessOptions) => Harness
-}
-
-function parse(argv: string[]): { positional: string[]; values: Record<string, string>; switches: Set<string> } {
-  const positional: string[] = []
-  const values: Record<string, string> = {}
-  const switches = new Set<string>()
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index]
-    if (!arg.startsWith('--')) positional.push(arg)
-    else if (arg === '--yes') switches.add('yes')
-    else if (index + 1 < argv.length) {
-      values[arg.slice(2)] = argv[index + 1]
-      index += 1
-    } else throw new Error(`${arg} needs a value.`)
-  }
-  return { positional, values, switches }
-}
-
-const stateOf = (plugin: Plugin): string => {
-  if (plugin.required) return 'required'
-  if (plugin.trust === 'untrusted') return plugin.attachment && !plugin.attachment.global ? 'off, code not trusted' : 'code not trusted'
-  if (plugin.attachment) return plugin.attachment.global ? 'on' : 'off'
-  const on = plugin.contributions.filter((entry) => entry.state === 'on').length
-  return `${on} of ${plugin.contributions.length} on`
-}
-
-function describe(plugin: Plugin): string {
-  const lines = [`${plugin.title} (${plugin.id})`, `  ${plugin.description || 'No description.'}`, `  Source: ${plugin.source}${plugin.version ? ` ${plugin.version}` : ''}${plugin.path ? ` · ${plugin.path}` : ''}`, `  State: ${stateOf(plugin)}`]
-  if (plugin.extends.length) lines.push(`  Extends: ${plugin.extends.join(', ')}`)
-  if (plugin.code) lines.push(`  Code (${plugin.trust}), fingerprint ${plugin.code.hash.slice(0, 12)}:`, ...plugin.code.files.map((file) => `    ${file}`))
-  for (const entry of plugin.contributions) lines.push(`  ${entry.state === 'on' ? '●' : '○'} ${entry.kind} ${entry.name} (${entry.id})${entry.scope ? ` · ${entry.scope}` : ''}${entry.problem ? ` · last run failed: ${entry.problem}` : ''}`)
-  return lines.join('\n')
-}
-
-export async function runPluginsCli(argv: string[], dependencies: PluginsCliDependencies = {}): Promise<number> {
-  const write = dependencies.write ?? ((text: string) => void process.stdout.write(text))
-  let parsed: ReturnType<typeof parse>
-  try {
-    parsed = parse(argv)
-  } catch (error) {
-    write(`${error instanceof Error ? error.message : String(error)}\n`)
-    return 2
-  }
-  const [command, target] = parsed.positional
-  if (!command || command === 'help') {
-    write(PLUGINS_USAGE)
-    return command ? 0 : 2
-  }
-  const base = dependencies.cwd ?? process.cwd()
-  const root = join(dependencies.home ?? homedir(), '.xingular-harness')
-  const options: HarnessOptions = { dataRoot: parsed.values.data ? resolve(base, parsed.values.data) : join(root, 'data'), stateDir: parsed.values.state ? resolve(base, parsed.values.state) : join(root, 'state'), productName: 'Xingular Harness' }
-  // Built without opening the data root: a plugin command must not settle runs or migrate a Wiki
-  // that another process may be using.
-  const harness = dependencies.createHarness ? dependencies.createHarness(options) : new Harness(options)
-  const scope = { cwd: parsed.values.cwd ? resolve(base, parsed.values.cwd) : null }
-  const need = (what: string): string => {
-    if (!target) throw new Error(`${command} needs ${what}.`)
-    return target
-  }
-  const find = async (id: string): Promise<Plugin> => {
-    const plugin = (await api.list(harness, scope)).find((candidate) => candidate.id === id)
-    if (!plugin) throw new Error(`There is no plugin with the id "${id}". Run "plugins list" to see the ids.`)
-    return plugin
-  }
-  try {
-    switch (command) {
-      case 'list': {
-        const plugins = await api.list(harness, scope)
-        const width = Math.max(...plugins.map((plugin) => plugin.id.length))
-        write(`${plugins.map((plugin) => `${plugin.id.padEnd(width)}  ${stateOf(plugin).padEnd(22)}  ${plugin.title}`).join('\n')}\n`)
-        return 0
-      }
-      case 'show':
-        write(`${describe(await find(need('a plugin id')))}\n`)
-        return 0
-      case 'install': {
-        const before = new Set((await api.list(harness, scope)).map((plugin) => plugin.id))
-        const added = (await install.install(harness, { ...scope, source: need('a folder, an npm name, or a git address') })).filter((plugin) => !before.has(plugin.id))
-        write(added.length ? `${added.map(describe).join('\n\n')}\n\nInstalled, switched off. Switch it on with "plugins attach <id>"${added.some((plugin) => plugin.code) ? ' and trust its code with "plugins trust <id>"' : ''}.\n` : 'Nothing new was installed.\n')
-        return 0
-      }
-      case 'remove':
-        await install.remove(harness, { ...scope, pluginId: need('a plugin id') })
-        write(`Removed ${target}.\n`)
-        return 0
-      case 'update':
-        await install.update(harness, { ...scope, pluginId: target ?? null })
-        write(target ? `Updated ${target}. If its code changed, trust it again.\n` : 'Updated the installed plugins. Any whose code changed needs trust again.\n')
-        return 0
-      case 'attach':
-      case 'detach': {
-        const where = parsed.values.agent ? { agentId: parsed.values.agent } : parsed.values.project ? { projectId: parsed.values.project } : {}
-        await api.attach(harness, { ...scope, id: need('a plugin or contribution id'), scope: where }, command === 'attach')
-        write(`${target} is ${command === 'attach' ? 'on' : 'off'} ${parsed.values.agent ? `for agent ${parsed.values.agent}` : parsed.values.project ? `for project ${parsed.values.project}` : 'everywhere'}. It applies from the next session start.\n`)
-        return 0
-      }
-      case 'trust': {
-        const plugin = await find(need('a plugin id'))
-        if (!plugin.code) throw new Error(`${plugin.title} has no code that waits for trust.`)
-        if (plugin.trust === 'trusted') {
-          write(`${plugin.title} is already trusted.\n`)
-          return 0
-        }
-        write(`${plugin.title} brings code that runs inside the harness and its sessions. It can do anything you can, including reading your files and credentials.\n\nFiles:\n${plugin.code.files.map((file) => `  ${file}`).join('\n')}\n\nFingerprint ${plugin.code.hash.slice(0, 12)}\n`)
-        if (!parsed.switches.has('yes')) {
-          if (!dependencies.ask) throw new Error('Read the files, then run this again with --yes to trust them.')
-          if ((await dependencies.ask('Trust this code? Type yes: ')).trim().toLowerCase() !== 'yes') {
-            write('Not trusted.\n')
-            return 1
-          }
-        }
-        await api.trust(harness, { ...scope, hash: plugin.code.hash })
-        write(`Trusted. If any of these files changes, it asks again.\n`)
-        return 0
-      }
-      case 'untrust': {
-        const plugin = await find(need('a plugin id'))
-        if (!plugin.code) throw new Error(`${plugin.title} has no code to stop trusting.`)
-        await api.untrust(harness, { ...scope, hash: plugin.code.hash })
-        write(`${plugin.title} is not trusted any more.\n`)
-        return 0
-      }
-      default:
-        write(PLUGINS_USAGE)
-        return 2
-    }
-  } catch (error) {
-    write(`${error instanceof Error ? error.message : String(error)}\n`)
-    return 1
-  } finally {
-    await harness.close()
-  }
-}
-
-/** Asks on the terminal, when there is one to ask on. */
-export function terminalAsk(): ((question: string) => Promise<string>) | undefined {
-  if (!process.stdin.isTTY || !process.stdout.isTTY) return undefined
-  return async (question) => {
-    const reader = createInterface({ input: process.stdin, output: process.stdout })
-    try {
-      return await reader.question(question)
-    } finally {
-      reader.close()
-    }
-  }
-}

package/src/plugins/discover.ts

@@ -1,151 +0,0 @@
-// What Pi would load for a session, found with Pi's own resolver so the list matches Pi's
-// rules. Resolving reads folders and manifests; it never runs an extension.
-import { existsSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { join, sep } from 'node:path'
-
-import { log } from '../core/bus'
-import { packageManifest } from './manifest'
-
-/**
- * `context` is an instruction file Pi reads on its own: `AGENTS.md`, `SYSTEM.md` and their kin.
- * `hook` is a package's hooks file, which the harness runs itself; Pi never loads it.
- */
-export type FoundKind = 'extension' | 'skill' | 'prompt' | 'theme' | 'context' | 'hook'
-
-/** Where a found item comes from. `builtin` is one of the Pi command's own extensions. */
-export type FoundOrigin = 'shared' | 'package' | 'project' | 'home' | 'builtin'
-
-export interface Found {
-  kind: FoundKind
-  /** A file or folder, or `builtin:<name>`. */
-  path: string
-  origin: FoundOrigin
-  /** Declared by the working folder: its `.pi` or `.agents` folder, or its settings. */
-  project: boolean
-  /** The folder of the package this belongs to. */
-  packageRoot: string | null
-  /** The package as its settings name it (`npm:…`, `git:…`, a folder). */
-  source: string | null
-  /** Left on in Pi's settings. An item switched off there is found but never loaded. */
-  enabled: boolean
-}
-
-export interface ResolveInput {
-  cwd: string
-  /** The account's Pi agent folder. */
-  agentDir: string
-  /** Install a package the shared settings name and the account does not have yet. */
-  install?: boolean
-  /** Folders of packages kept outside Pi's settings: each is found as an installed package. */
-  packages?: readonly string[]
-}
-
-/** Finds what Pi would load. Replaced in tests. */
-export type Resolver = (input: ResolveInput) => Promise<Found[]>
-
-/** The extensions built into the `pi` command. A terminal loads them; an SDK session has none. */
-export const PI_BUILTINS = ['llama.cpp', 'codemode', 'tool-search', 'mcp'] as const
-export const BUILTIN_PREFIX = 'builtin:'
-
-const inside = (path: string, parent: string): boolean => path === parent || path.startsWith(parent.endsWith(sep) ? parent : `${parent}${sep}`)
-
-interface Metadata {
-  source: string
-  scope: string
-  origin: string
-  baseDir?: string
-  packageRoot?: string
-}
-
-function origin(path: string, metadata: Metadata): FoundOrigin {
-  if (path.startsWith(BUILTIN_PREFIX)) return 'builtin'
-  if (metadata.origin === 'package') return 'package'
-  if (metadata.scope === 'project') return 'project'
-  return metadata.baseDir && inside(metadata.baseDir, join(process.env.HOME || homedir(), '.agents')) ? 'home' : 'shared'
-}
-
-/**
- * Runs an install with the package manager's install scripts switched off, so fetching a
- * package runs none of its code. A package that builds itself on install then fails to load,
- * and says so; that is the price of installing being safe to do before trust.
- */
-export async function withoutInstallScripts<T>(action: () => Promise<T>): Promise<T> {
-  const before = process.env.npm_config_ignore_scripts
-  process.env.npm_config_ignore_scripts = 'true'
-  try {
-    return await action()
-  } finally {
-    if (before === undefined) delete process.env.npm_config_ignore_scripts
-    else process.env.npm_config_ignore_scripts = before
-  }
-}
-
-export const piResolver: Resolver = async ({ cwd, agentDir, install, packages }) => {
-  const pi = await import('@earendil-works/pi-coding-agent')
-  const settings = pi.SettingsManager.create(cwd, agentDir)
-  const shared = new Set((settings.getGlobalSettings().packages ?? []).map((entry) => (typeof entry === 'string' ? entry : entry.source)))
-  const manager = (): InstanceType<typeof pi.DefaultPackageManager> => new pi.DefaultPackageManager({ cwd, agentDir, settingsManager: settings, builtinExtensions: [...PI_BUILTINS] })
-  const resolve = (installing: boolean) => manager().resolve(async (source) => (installing && shared.has(source) ? 'install' : 'skip'))
-  let resolved: Awaited<ReturnType<typeof resolve>>
-  try {
-    resolved = install ? await withoutInstallScripts(() => resolve(true)) : await resolve(false)
-  } catch (error) {
-    if (!install) throw error
-    // A package that cannot be installed must not stop the session; it is found again next time.
-    log('a plugin package could not be installed', error instanceof Error ? error.message : String(error))
-    resolved = await resolve(false)
-  }
-  const found: Found[] = []
-  const add = (paths: typeof resolved): void => {
-    const kinds = [['extension', paths.extensions], ['skill', paths.skills], ['prompt', paths.prompts], ['theme', paths.themes]] as const
-    for (const [kind, resources] of kinds) {
-      for (const resource of resources) {
-        const metadata = resource.metadata as Metadata
-        const packaged = metadata.origin === 'package'
-        found.push({
-          kind,
-          path: resource.path,
-          origin: origin(resource.path, metadata),
-          project: metadata.scope === 'project',
-          packageRoot: packaged ? (metadata.packageRoot ?? metadata.baseDir ?? null) : null,
-          source: packaged ? metadata.source : null,
-          enabled: resource.enabled
-        })
-      }
-    }
-  }
-  add(resolved)
-  // Packages a person keeps beside their data are read where they are; nothing is fetched for them.
-  if (packages?.length) {
-    try {
-      add(await manager().resolveExtensionSources([...packages]))
-    } catch (error) {
-      log('a local plugin could not be read', error instanceof Error ? error.message : String(error))
-    }
-  }
-  // A package may name a hooks file for the harness. Only a package a person installed counts:
-  // a working folder's package cannot put code into the harness's own process.
-  const roots = new Map<string, string>()
-  for (const configured of manager().listConfiguredPackages()) if (configured.scope === 'user' && configured.installedPath) roots.set(configured.installedPath, configured.source)
-  for (const folder of packages ?? []) roots.set(folder, folder)
-  for (const [root, source] of roots) {
-    const hooks = packageManifest(root).hooks
-    if (!hooks || !existsSync(join(root, hooks))) continue
-    found.push({ kind: 'hook', path: join(root, hooks), origin: 'package', project: false, packageRoot: root, source, enabled: true })
-    // Pi takes a folder with none of its own resources to be an extension itself. A package that
-    // only brings hooks is not one, and must not be handed to Pi as code to load.
-    const fallback = found.findIndex((item) => item.kind === 'extension' && item.path === root)
-    if (fallback !== -1) found.splice(fallback, 1)
-  }
-  // Pi reads these itself, whatever else is switched off. They are text, so they are only listed.
-  const context = [
-    ...pi.loadProjectContextFiles({ cwd, agentDir }).map((file) => file.path),
-    ...[join(agentDir, 'SYSTEM.md'), join(agentDir, 'APPEND_SYSTEM.md'), join(cwd, '.pi', 'SYSTEM.md'), join(cwd, '.pi', 'APPEND_SYSTEM.md')].filter((path) => existsSync(path))
-  ]
-  for (const path of context) {
-    const shared = inside(path, agentDir)
-    found.push({ kind: 'context', path, origin: shared ? 'shared' : 'project', project: !shared, packageRoot: null, source: null, enabled: true })
-  }
-  return found
-}

package/src/plugins/firstParty.test.ts

@@ -1,143 +0,0 @@
-// The harness's own two plugins, run through a real Pi session with a scripted model: nothing
-// here is faked on Pi's side except what the model says.
-import { mkdtempSync } 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 type { RunEvent } from '../sessions/contracts'
-import { fauxModel } from '../../tests/faux'
-import { rootWithProject, writeFile } from '../../tests/helpers'
-import { settingValue, trimText } from './firstParty'
-import type { Inventory, Plugin } from './types'
-
-const open: Harness[] = []
-afterEach(async () => {
-  for (const harness of open.splice(0)) await harness.close()
-})
-
-async function setup() {
-  const root = rootWithProject()
-  const base = mkdtempSync(join(tmpdir(), 'first-party-'))
-  // The background upkeep would ask the scripted model too; it is not what is tested here.
-  const harness = createHarness({ dataRoot: root, stateDir: join(base, 'state'), secrets: memorySecretStore(), maintainerFactory: async () => ({ prompt: async () => undefined, dispose: () => undefined, error: () => null }) })
-  open.push(harness)
-  harness.accounts.create('Main', 'apiKey')
-  const model = await fauxModel(harness)
-  const events: RunEvent[] = []
-  harness.runs.listen((event) => void events.push(event))
-  const table = methods(harness)
-  const call = <T>(method: string, params: Record<string, unknown> = {}) => table[method](params) as Promise<T>
-  let count = 0
-  /** One reply: a real session, run until it settles. */
-  const reply = async (agentId: string, extra: Record<string, unknown> = {}) => {
-    const id = `run-${(count += 1)}`
-    await harness.sessions.run({ run: { id, sessionId: agentId }, cwd: base, sessionDir: join(root, 'sessions', agentId), text: 'Go.', model: model.model, caller: { agentId, agentName: 'Helper', actor: 'Chat' }, tools: { allow: ['read'] }, ...extra })
-    for (let waited = 0; waited < 200 && !events.some((event) => event.runId === id && (event.type === 'completed' || event.type === 'failed')); waited += 1) await new Promise((resolve) => setTimeout(resolve, 25))
-    return events.filter((event) => event.runId === id)
-  }
-  return { harness, root, base, model, call, reply }
-}
-
-describe('Output trim', () => {
-  it('keeps the beginning and the end of a long text and says what is missing', () => {
-    const text = `${'a'.repeat(700)}${'b'.repeat(4000)}${'c'.repeat(300)}`
-    const trimmed = trimText(text, 1000)
-    expect(trimmed.startsWith('a'.repeat(700))).toBe(true)
-    expect(trimmed.endsWith('c'.repeat(300))).toBe(true)
-    expect(trimmed).toContain('4000 of 5000 characters were cut here by the Output trim plugin')
-    expect(trimText('short', 1000)).toBe('short')
-  })
-
-  it('is off until switched on, then cuts what the model reads, for the agent it is on for', async () => {
-    const { base, model, call, reply } = await setup()
-    writeFile(join(base, 'big.txt'), `${'START '.repeat(10)}${'x'.repeat(30_000)}${' END'.repeat(10)}`)
-    const read = () => model.script([model.calls(['read', { path: join(base, 'big.txt') }]), model.says('Done.')])
-
-    read()
-    await reply('a1')
-    expect(model.lastToolResults()[0].length).toBeGreaterThan(30_000)
-
-    const listed = await call<Plugin[]>('plugins.attach', { id: 'output-trim', scope: { agentId: 'a1' } })
-    expect(listed.find((plugin) => plugin.id === 'output-trim')).toMatchObject({ source: 'builtin', runsCode: true, trust: 'none', required: null, attachment: { global: false, on: { agentIds: ['a1'], projectIds: [] } }, settings: [{ key: 'maxChars', value: 20_000, default: 20_000 }] })
-    await call('plugins.configure', { pluginId: 'output-trim', settings: { maxChars: 3000 } })
-
-    read()
-    await reply('a1')
-    // The conversation continues, so the model is sent the earlier result too; the newest is last.
-    const seen = model.lastToolResults().at(-1)!
-    expect(seen.length).toBeLessThan(3400)
-    expect(seen.startsWith('START START')).toBe(true)
-    expect(seen.endsWith('END END')).toBe(true)
-    expect(seen).toContain('characters were cut here by the Output trim plugin')
-
-    // Another agent still reads the whole result.
-    read()
-    await reply('a2')
-    expect(model.lastToolResults().at(-1)!.length).toBeGreaterThan(30_000)
-
-    // It reaches the agent it is on for, and is listed as that agent's.
-    const inventory = await call<Inventory>('plugins.inventory', { context: { agentId: 'a1' }, tools: ['read'] })
-    expect(inventory.items.filter((item) => item.pluginId === 'output-trim').map((item) => [item.kind, item.delivery])).toEqual([['code', 'code']])
-    expect((await call<Inventory>('plugins.inventory', { context: { agentId: 'a2' }, tools: ['read'] })).items.some((item) => item.pluginId === 'output-trim')).toBe(false)
-  })
-
-  it('also runs in unattended work, where nothing on disk is loaded', async () => {
-    const { base, model, call, reply } = await setup()
-    writeFile(join(base, 'big.txt'), 'y'.repeat(30_000))
-    await call('plugins.attach', { id: 'output-trim' })
-    await call('plugins.configure', { pluginId: 'output-trim', settings: { maxChars: 2000 } })
-    model.script([model.calls(['read', { path: join(base, 'big.txt') }]), model.says('Done.')])
-    await reply('a1', { automatic: true })
-    expect(model.lastToolResults()[0]).toContain('were cut here by the Output trim plugin')
-  })
-})
-
-describe('Budget guard', () => {
-  it('refuses tool calls past the limit, gives the agent one request to wrap up, then ends the reply', async () => {
-    const { base, model, call, reply } = await setup()
-    writeFile(join(base, 'a.txt'), 'A file.')
-    await call('plugins.attach', { id: 'budget-guard' })
-    await call('plugins.configure', { pluginId: 'budget-guard', settings: { maxRequests: 5 } })
-    const again = model.calls(['read', { path: join(base, 'a.txt') }])
-    // A model that never stops by itself: every reply asks for another read.
-    model.script(Array.from({ length: 40 }, () => again))
-    const events = await reply('a1')
-    const tools = events.filter((event) => event.type === 'tool.completed').map((event) => (event.payload as { ok: boolean }).ok)
-    // Four reads run. The fifth request's read is refused and the agent is told to wrap up; it asks
-    // again in the sixth, which is refused too, and that ends the reply.
-    expect(tools).toEqual([true, true, true, true, false, false])
-    expect(model.requests()).toBe(6)
-    expect(model.lastToolResults().at(-1)).toContain('reached its limit of 5 model requests (the Budget guard plugin)')
-    expect(events.at(-1)?.type).toBe('completed')
-  })
-
-  it('lets a reply that wraps up when told finish in its own words', async () => {
-    const { base, model, call, reply } = await setup()
-    writeFile(join(base, 'a.txt'), 'A file.')
-    await call('plugins.attach', { id: 'budget-guard' })
-    await call('plugins.configure', { pluginId: 'budget-guard', settings: { maxRequests: 5 } })
-    const again = model.calls(['read', { path: join(base, 'a.txt') }])
-    model.script([again, again, again, again, again, model.says('I read the file four times; one more read is left.')])
-    const events = await reply('a1')
-    expect(model.requests()).toBe(6)
-    expect(events.filter((event) => event.type === 'message.completed').map((event) => (event.payload as { text: string }).text).at(-1)).toBe('I read the file four times; one more read is left.')
-  })
-
-  it('does nothing while it is switched off, and takes only numbers inside its range', async () => {
-    const { base, model, call, reply } = await setup()
-    writeFile(join(base, 'a.txt'), 'A file.')
-    const again = model.calls(['read', { path: join(base, 'a.txt') }])
-    model.script([...Array.from({ length: 8 }, () => again), model.says('Done.')])
-    const events = await reply('a1')
-    expect(events.filter((event) => event.type === 'tool.completed').every((event) => (event.payload as { ok: boolean }).ok)).toBe(true)
-    await expect(call('plugins.configure', { pluginId: 'budget-guard', settings: { maxRequests: 1 } })).rejects.toThrow('must be a number from 5 to 2000')
-    await expect(call('plugins.configure', { pluginId: 'budget-guard', settings: { speed: 3 } })).rejects.toThrow('has no setting called "speed"')
-    await expect(call('plugins.configure', { pluginId: 'memory', settings: {} })).rejects.toThrow('has no settings')
-    expect(settingValue({ key: 'k', label: '', description: '', default: 60, min: 5, max: 100 }, { k: 1000 })).toBe(60)
-    expect(settingValue({ key: 'k', label: '', description: '', default: 60, min: 5, max: 100 }, { k: 80.9 })).toBe(80)
-  })
-})

package/src/plugins/firstParty.ts

@@ -1,129 +0,0 @@
-// Plugins that ship with the harness and are off until a person switches them on. Each is a Pi
-// extension, written against the same API anyone's plugin uses. They are loaded as inline
-// extensions, so they also run in unattended work, where nothing on disk is loaded, and they
-// need no trust: they are the harness's own code.
-//
-// Both act on one run: a session is opened for each request a person or the application makes,
-// so what they count starts at zero each time.
-import type { PluginDescriptor, PluginSetting } from './types'
-
-/** The part of Pi's extension API these two use. */
-interface Api {
-  on(event: 'tool_result', handler: (event: ToolResult) => unknown): void
-  on(event: 'tool_call', handler: (event: { toolName: string }) => unknown): void
-  on(event: 'turn_start', handler: () => unknown): void
-  on(event: 'message_end', handler: (event: { message: { role: string; usage?: { input?: number; output?: number; cacheRead?: number; cacheWrite?: number } } }) => unknown): void
-}
-
-interface ToolResult {
-  toolName: string
-  content: ({ type: 'text'; text: string } | { type: string; [key: string]: unknown })[]
-}
-
-export const OUTPUT_TRIM = 'output-trim'
-export const BUDGET_GUARD = 'budget-guard'
-
-const OUTPUT_TRIM_SETTINGS: PluginSetting[] = [
-  { key: 'maxChars', label: 'Longest tool result', description: 'A tool result longer than this many characters is cut to its beginning and its end.', default: 20_000, min: 2_000, max: 400_000 }
-]
-
-const BUDGET_GUARD_SETTINGS: PluginSetting[] = [
-  { key: 'maxRequests', label: 'Model requests in one reply', description: 'After this many model requests in one reply or one run of work, tool calls are refused so the agent wraps up.', default: 60, min: 5, max: 2_000 },
-  { key: 'maxTokens', label: 'Tokens in one reply', description: 'The same, counted in tokens of every kind (cached ones included). 0 means no token limit.', default: 0, min: 0, max: 500_000_000 }
-]
-
-export const FIRST_PARTY_PLUGINS: readonly PluginDescriptor[] = [
-  {
-    id: OUTPUT_TRIM,
-    title: 'Output trim',
-    description: 'Cuts a very long tool result to its beginning and its end before the model reads it, and says how much was cut.',
-    switchable: { on: false },
-    settings: OUTPUT_TRIM_SETTINGS,
-    code: [{ name: 'Trim long tool results', description: 'Runs after every tool call, in conversations, task threads and unattended work. Not in terminal sessions yet.' }]
-  },
-  {
-    id: BUDGET_GUARD,
-    title: 'Budget guard',
-    description: 'Stops a reply that keeps going: past a limit of model requests or tokens, further tool calls are refused and the agent is told to wrap up.',
-    switchable: { on: false },
-    settings: BUDGET_GUARD_SETTINGS,
-    code: [{ name: 'Refuse tool calls past the limit', description: 'Counts model requests and tokens in one reply, in conversations, task threads and unattended work. Not in terminal sessions yet.' }]
-  }
-]
-
-/** A setting's value: what a person saved when it is a number inside the setting's range, else its default. */
-export function settingValue(setting: PluginSetting, saved: Record<string, unknown> | undefined): number {
-  const value = saved?.[setting.key]
-  return typeof value === 'number' && Number.isFinite(value) && value >= setting.min && value <= setting.max ? Math.floor(value) : setting.default
-}
-
-const values = (settings: readonly PluginSetting[], saved: Record<string, unknown> | undefined): Record<string, number> => Object.fromEntries(settings.map((setting) => [setting.key, settingValue(setting, saved)]))
-
-/** The text of a long result, cut to its first 70% and its last 30% of `maxChars`, with a line between that says what is missing. */
-export function trimText(text: string, maxChars: number): string {
-  if (text.length <= maxChars) return text
-  const head = Math.floor(maxChars * 0.7)
-  const tail = maxChars - head
-  const cut = text.length - maxChars
-  return `${text.slice(0, head)}\n\n[… ${cut} of ${text.length} characters were cut here by the Output trim plugin. Ask for a narrower result (a line range, a filter, a smaller file) to see them. …]\n\n${text.slice(text.length - tail)}`
-}
-
-export function outputTrim(saved: Record<string, unknown> | undefined): (pi: Api) => void {
-  const { maxChars } = values(OUTPUT_TRIM_SETTINGS, saved)
-  return (pi) => {
-    pi.on('tool_result', (event) => {
-      const texts = event.content.filter((part): part is { type: 'text'; text: string } => part.type === 'text' && typeof (part as { text?: unknown }).text === 'string')
-      const total = texts.reduce((sum, part) => sum + part.text.length, 0)
-      if (total <= maxChars) return undefined
-      // Several text parts are read as one result; pictures and anything else pass through untouched.
-      const trimmed = trimText(texts.map((part) => part.text).join('\n'), maxChars)
-      return { content: [{ type: 'text', text: trimmed }, ...event.content.filter((part) => part.type !== 'text')] }
-    })
-  }
-}
-
-export function budgetGuard(saved: Record<string, unknown> | undefined): (pi: Api) => void {
-  const { maxRequests, maxTokens } = values(BUDGET_GUARD_SETTINGS, saved)
-  return (pi) => {
-    let requests = 0
-    let tokens = 0
-    let refusedInRequest = 0
-    pi.on('turn_start', () => {
-      requests += 1
-    })
-    pi.on('message_end', (event) => {
-      if (event.message.role !== 'assistant' || !event.message.usage) return
-      const usage = event.message.usage
-      tokens += (usage.input ?? 0) + (usage.output ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0)
-    })
-    // Pi's own event before a request can change what is sent and cannot refuse it, so the limit
-    // is held where the loop can be stopped: at the tool calls that keep it going.
-    pi.on('tool_call', () => {
-      const over = requests >= maxRequests ? `${maxRequests} model requests` : maxTokens > 0 && tokens >= maxTokens ? `${maxTokens} tokens` : null
-      if (!over) return undefined
-      // The first refusal leaves the agent one request to say what is done. If it calls tools
-      // again instead, the batch ends the reply.
-      const again = refusedInRequest !== 0 && refusedInRequest !== requests
-      refusedInRequest ||= requests
-      return {
-        block: true,
-        terminate: again,
-        reason: `This reply reached its limit of ${over} (the Budget guard plugin). Call no more tools. Tell the user what is done and what is left; they can raise the limit on the Plugins page.`
-      }
-    })
-  }
-}
-
-export interface InlineExtension {
-  name: string
-  /** A Pi extension factory. Typed loosely so this module needs nothing of Pi's to be loaded. */
-  factory: unknown
-}
-
-/** The first-party extensions switched on for a caller, each with the settings a person saved. */
-export function firstPartyExtensions(on: (pluginId: string) => boolean, settings: Record<string, Record<string, unknown>>): InlineExtension[] {
-  const extensions: InlineExtension[] = []
-  if (on(OUTPUT_TRIM)) extensions.push({ name: OUTPUT_TRIM, factory: outputTrim(settings[OUTPUT_TRIM]) })
-  if (on(BUDGET_GUARD)) extensions.push({ name: BUDGET_GUARD, factory: budgetGuard(settings[BUDGET_GUARD]) })
-  return extensions
-}