@xingular/harness 0.1.6 → 1.0.0

package/dist/sdk/plugins/builtin.js

@@ -0,0 +1,68 @@
+// 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.js";
+import { ASK_USER } from "../tools/askUser.js";
+import { CHECKLIST_WRITE } from "../tools/checklist.js";
+import { SPAWN_SUBAGENT, WAIT_SUBAGENTS } from "../sessions/subagents.js";
+import { RECALL_TOOLS, SKILL_TOOLS, TRAJECTORY_TOOLS, WIKI_READ_TOOLS, WIKI_WRITE_TOOLS } from "../tools/definitions.js";
+import { FIRST_PARTY_PLUGINS } from "./firstParty.js";
+import { WEB_PLUGIN } from "../web/tools.js";
+import { BROWSER_PLUGIN } from "../browser/index.js";
+const tools = (definitions) => 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 = {
+    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']
+};
+/** The variant: the eight components that shape what an agent is told and can do. */
+export const VARIANT_PLUGIN = {
+    id: 'variant',
+    title: 'Variant',
+    description: 'The agent\'s own variant: system prompt, guardrails, memory and tool guidance in every prompt; skills, scripts and subagents on demand; plugins in the tool loop. Versioned, and refined from evidence.',
+    required: 'Every agent runs on a variant.',
+    sections: [
+        { id: 'system', name: 'System prompt', description: 'c1: role and procedure.' },
+        { id: 'guardrails', name: 'Guardrails', description: 'c2: standing rules.' },
+        { id: 'memory', name: 'Memory', description: 'c3: durable facts about this kind of work.' },
+        { id: 'subagents', name: 'Subagents', description: 'c5: the list of this variant\'s subagents.' },
+        { id: 'scripts', name: 'Scripts', description: 'c7: where this variant\'s scripts are.' },
+        { id: 'reporting', name: 'Reporting', description: 'Fixed foundation text, not part of the variant: how the final reply is shaped.' }
+    ],
+    tools: tools(SKILL_TOOLS)
+};
+export const HARNESS_PLUGINS = [
+    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' }] },
+    VARIANT_PLUGIN,
+    {
+        id: 'wiki',
+        title: 'Wiki',
+        description: 'Notes about projects, linked to each other, that agents search and read.',
+        required: 'Project notes are reached through it.',
+        tools: tools([...WIKI_READ_TOOLS, ...WIKI_WRITE_TOOLS]),
+        sections: [
+            { id: 'wiki', name: 'Wiki', description: 'The current project\'s notes.' },
+            { id: 'references', name: 'Selected references', description: 'Notes pinned to one request.' }
+        ],
+        toolGroups: ['Wiki']
+    },
+    { 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]), toolGroups: ['History'] },
+    { 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: 'checklist', title: 'Checklist', description: 'Lets the agent keep a checklist of the steps of its work, recorded with the run so progress can be shown and picked up again.', required: 'Progress of longer work is kept through it.', tools: [{ name: CHECKLIST_WRITE, description: 'Write the checklist' }] },
+    {
+        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']
+    },
+    WEB_PLUGIN,
+    BROWSER_PLUGIN,
+    ...FIRST_PARTY_PLUGINS
+];

package/dist/sdk/plugins/catalogue.d.ts

@@ -0,0 +1,29 @@
+import type { Connection } from "../mcp/types.js";
+import { type Attachments, type AttachScope } from "./attachments.js";
+import type { HookStatus } from "./hooks.js";
+import { type Loading, type Registered } from "./plugins.js";
+import type { Plugin, PluginDescriptor } from "./types.js";
+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;
+}
+export declare function catalogue(input: CatalogueInput): Plugin[];

package/dist/sdk/plugins/catalogue.js

@@ -0,0 +1,196 @@
+// 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 } from 'node:path';
+import { projectsOrNone } from "../core/projects.js";
+import { compareText } from "../core/text.js";
+import { attached, describe } from "./attachments.js";
+import { settingValue } from "./firstParty.js";
+import { BUILTIN_PREFIX } from "./discover.js";
+import { registrationHash } from "./runtime.js";
+import { contributionId, describeFound, FOUND_KINDS, packageManifest, pluginIdOf } from "./identity.js";
+import { loads, switchable, trustedBy } from "./plugins.js";
+const contribution = (plugin, kind, name, rest = {}) => ({
+    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, source, attachments = null, caller = {}) {
+    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 ?? '', ...(switchable ? { state: on ? 'on' : 'off' } : {}) }))
+        ]
+    };
+}
+const named = (ids, names) => ids.flatMap((id) => (names.has(id) ? [names.get(id)] : []));
+const counted = (count, word) => (count ? `${count} ${word}${count === 1 ? '' : 's'}` : '');
+/** Who something is switched on for, in words; `null` when it is on for nobody. */
+function scopeWords(attachment, projects) {
+    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 connection keeps its own scope; this is the same shape for a screen. */
+function connectionAttachment(connection) {
+    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) {
+    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 = {
+    '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) {
+    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, item, trusted, input, projects) {
+    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 };
+    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, title, description, source, path) => ({ 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) {
+    const plugins = new Map();
+    for (const descriptor of input.descriptors)
+        plugins.set(descriptor.id, fromDescriptor(descriptor, descriptor.id === 'pi' ? 'pi' : input.application.has(descriptor.id) ? 'application' : 'builtin', input.attachments, input.caller));
+    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 projects = new Map(projectsOrNone(input.root).map((project) => [project.id, project.name]));
+    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 } : item.source ? { kind: 'settings', source: item.source } : 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, name, rest = {}) => {
+                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 = ['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));
+}

package/dist/sdk/plugins/cli.d.ts

@@ -0,0 +1,13 @@
+import { Harness, type HarnessOptions } from "../harness.js";
+export declare const PLUGINS_USAGE = "Usage: xharness plugins <command> [options]\n\n  list                         Every plugin and whether it is on\n  show <plugin id>             One plugin: what it brings, where it is on, its code\n  install <source>             A folder, an npm name, or a git address. It arrives off and untrusted\n  remove <plugin id>           Remove a plugin you installed\n  update [plugin id]           Fetch a newer version of one installed plugin, or of all\n  attach <id>                  Switch a plugin, or one thing it brings, on\n  detach <id>                  Switch it off\n  trust <plugin id> [--yes]    Show the files of its code, then trust them\n  untrust <plugin id>          Stop trusting its code\n\nOptions:\n  --data <dir>       Data directory (default: ~/.xingular-harness/data)\n  --state <dir>      State directory (default: ~/.xingular-harness/state)\n  --cwd <dir>        Also list what this working folder brings\n  --project <id>     attach/detach for one project instead of everywhere\n  --agent <id>       attach/detach for one agent instead of everywhere\n";
+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;
+}
+export declare function runPluginsCli(argv: string[], dependencies?: PluginsCliDependencies): Promise<number>;
+/** Asks on the terminal, when there is one to ask on. */
+export declare function terminalAsk(): ((question: string) => Promise<string>) | undefined;

package/dist/sdk/plugins/cli.js

@@ -0,0 +1,187 @@
+// `xharness 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 } from "../harness.js";
+import * as api from "./api.js";
+import * as install from "./install.js";
+export const PLUGINS_USAGE = `Usage: xharness 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
+`;
+function parse(argv) {
+    const positional = [];
+    const values = {};
+    const switches = new Set();
+    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) => {
+    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) {
+    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, dependencies = {}) {
+    const write = dependencies.write ?? ((text) => void process.stdout.write(text));
+    let parsed;
+    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 = { 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) => {
+        if (!target)
+            throw new Error(`${command} needs ${what}.`);
+        return target;
+    };
+    const find = async (id) => {
+        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() {
+    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/dist/sdk/plugins/discover.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `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 declare const PI_BUILTINS: readonly ["llama.cpp", "codemode", "tool-search", "mcp"];
+export declare const BUILTIN_PREFIX = "builtin:";
+/**
+ * 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 declare function withoutInstallScripts<T>(action: () => Promise<T>): Promise<T>;
+export declare const piResolver: Resolver;