@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/plugins/builtin.js

@@ -0,0 +1,182 @@
+// Built-in feature modules register their contributions here; this registry never loads Pi code.
+import { CONNECTION_TOOLS, NATIVE_GROUP } from "../prompt/compile.js";
+import { ASK_USER, askUserTool } from "../tools/askUser.js";
+import { TODO_WRITE, todoTool } from "../tools/todo.js";
+import { SPAWN_SUBAGENT, WAIT_SUBAGENTS } from "../sessions/subagents.js";
+import { subagentTools } from "../tools/spawnSubagent.js";
+import { SESSION_NAME } from "../tools/sessionName.js";
+import { PLUGIN_PROPOSAL_TOOLS, 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 { KEYLESS_SEARCH, webPart } from "../web/part.js";
+import { BROWSER_PLUGIN, browserPluginPart } from "../browser/index.js";
+import { ANNOTATIONS_PLUGIN } from "../annotations/part.js";
+import { annotationsPart } from "../annotations/part.js";
+import { webServerMethods } from "../web/serverMethods.js";
+import { browserServerMethods } from "../browser/serverMethods.js";
+import { annotationServerMethods } from "../annotations/serverMethods.js";
+import { doctorServerMethods } from "../doctor/serverMethods.js";
+import { worktreeServerMethods } from "../worktrees/serverMethods.js";
+import { hubServerMethods } from "../hub/serverMethods.js";
+import { refinementServerMethods } from "../refine/serverMethods.js";
+import { wikiServerMethods } from "../wiki/serverMethods.js";
+import { historyServerMethods } from "../history/serverMethods.js";
+import { subagentServerMethods } from "../sessions/subagentServerMethods.js";
+import { sideQuestionServerMethods } from "../sessions/sideQuestionServerMethods.js";
+import { connectedAppServerMethods } from "../mcp/serverMethods.js";
+import { harnessTools } from "../tools/harnessTools.js";
+import { GET_CAPABILITIES } from "../tools/getCapabilities.js";
+import { USAGE_SETTINGS } from "../usage/settings.js";
+import { usageServerMethods } from "../usage/serverMethods.js";
+import { createBuiltinPluginRegistry } from "./builtinRegistry.js";
+const tools = (definitions) => definitions.map((tool) => ({ name: tool.name, description: tool.label }));
+const toolContribution = (definitions, toolOrder) => ({
+    toolOrder,
+    tools: (context) => context.harnessTools
+        ? harnessTools(context.env, context.caller, { variantDir: context.variantDir, definitions })
+        : []
+});
+/** 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 })), { name: SESSION_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: 'harness-identity', name: 'Harness identity', description: 'Fixed foundation identity; not part of the variant.' },
+        { 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: 'required-skills', name: 'Required skills', description: 'Skills the person named as required for one request.' },
+        { id: 'reporting', name: 'Reporting', description: 'Fixed foundation text, not part of the variant: how the final reply is shaped.' }
+    ],
+    tools: tools(SKILL_TOOLS)
+};
+const SUBAGENTS_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' }] };
+const WIKI_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']
+};
+const HISTORY_PLUGIN = { 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'] };
+const ASK_USER_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 }] };
+const TODO_PLUGIN = { id: 'todo', title: 'Todo', description: 'Lets the agent keep a todo list 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: TODO_WRITE, description: 'Write the todo list' }] };
+const CONNECTED_APPS_PLUGIN = {
+    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']
+};
+const DOCTOR_PLUGIN = { id: 'doctor', title: 'Doctor', description: 'Local readiness checks and explicitly confirmed live probes for accounts, models and tools.', required: 'Every local terminal has readiness diagnostics.' };
+const WORKTREES_PLUGIN = { id: 'worktrees', title: 'Worktrees', description: 'Create and manage isolated git worktrees, move changes between them, and restore removed worktrees.', required: 'Managed worktrees are available to every local terminal.' };
+const HUB_PLUGIN = { id: 'hub', title: 'Hub', description: 'Browse and install reviewed skills, plugins and documents from configured registries.', required: 'Reviewed Harness resources are available to every host.' };
+const PLUGIN_AUTHORING = { id: 'plugin-authoring', title: 'Plugin authoring', description: 'Propose plugins for a person to review.', required: 'Plugin proposals are reviewed before installation.', tools: tools(PLUGIN_PROPOSAL_TOOLS) };
+const REFINEMENT_PLUGIN = { id: 'refinement', title: 'Refinement', description: 'Improve variants from recorded evidence through isolated refinement runs and reviewed candidates.', required: 'Variant refinement is available to every host.' };
+const CAPABILITIES_PLUGIN = { id: 'capabilities', title: 'Capability discovery', description: 'Inspect the callable tools of the current run, including their input schemas. Discovery never grants access.', required: 'Every interactive session can inspect its own registered capabilities.', tools: [{ name: GET_CAPABILITIES, description: 'Inspect current capabilities' }] };
+const USAGE_PLUGIN = {
+    id: 'usage',
+    title: 'Usage',
+    description: 'Token, cost and latency totals from recorded runs, and the plan windows, balances or rate limits each provider reports.',
+    settings: [...USAGE_SETTINGS]
+};
+const SIDE_QUESTIONS_PLUGIN = {
+    id: 'side-questions',
+    title: 'Side questions',
+    description: 'Separate, tool-free answers that use a redacted projection of the main conversation.',
+    required: 'Every host can ask a side question without steering its main run.',
+    sections: [{ id: 'side-question', name: 'Side-question role', description: 'Fixed instructions for an independent, tool-free side run.' }]
+};
+export const BUILTIN_PLUGIN_REGISTRY = createBuiltinPluginRegistry([
+    {
+        descriptor: PI_PLUGIN,
+        toolOrder: 60,
+        tools: context => context.harnessTools ? [context.sessionName] : []
+    },
+    {
+        descriptor: SUBAGENTS_PLUGIN,
+        toolOrder: 70,
+        tools: context => context.allowedTools.includes(SPAWN_SUBAGENT)
+            ? subagentTools(context.subagents, context.runId).filter(tool => context.allowedTools.includes(tool.name))
+            : [],
+        serverMethods: subagentServerMethods
+    },
+    { descriptor: VARIANT_PLUGIN, ...toolContribution(SKILL_TOOLS, 30) },
+    { descriptor: WIKI_PLUGIN, ...toolContribution([...WIKI_READ_TOOLS, ...WIKI_WRITE_TOOLS], 20), serverMethods: wikiServerMethods },
+    {
+        descriptor: HISTORY_PLUGIN,
+        ...toolContribution([...RECALL_TOOLS, ...TRAJECTORY_TOOLS], 10),
+        serverMethods: historyServerMethods
+    },
+    { descriptor: ASK_USER_PLUGIN, toolOrder: 40, tools: context => context.harnessTools && context.allowedTools.includes(ASK_USER) ? [askUserTool(context.run)] : [] },
+    { descriptor: TODO_PLUGIN, toolOrder: 50, tools: context => context.harnessTools ? [todoTool(context.run)] : [] },
+    {
+        descriptor: CONNECTED_APPS_PLUGIN,
+        toolOrder: 0,
+        tools: context => context.connectionTools?.() ?? [],
+        serverMethods: connectedAppServerMethods
+    },
+    { descriptor: HUB_PLUGIN, serverMethods: hubServerMethods },
+    { descriptor: PLUGIN_AUTHORING, ...toolContribution(PLUGIN_PROPOSAL_TOOLS, 31) },
+    { descriptor: REFINEMENT_PLUGIN, serverMethods: refinementServerMethods },
+    { descriptor: SIDE_QUESTIONS_PLUGIN, serverMethods: sideQuestionServerMethods },
+    {
+        descriptor: WEB_PLUGIN,
+        createWorldPart: ({ options, setting }) => webPart({ secrets: options.secrets, request: options.request, keyless: () => setting(WEB_PLUGIN.id, KEYLESS_SEARCH) === 1 }),
+        serverMethods: webServerMethods
+    },
+    {
+        descriptor: BROWSER_PLUGIN,
+        createWorldPart: ({ browserEngine }) => browserEngine ? browserPluginPart(browserEngine) : null,
+        serverMethods: browserServerMethods
+    },
+    {
+        descriptor: ANNOTATIONS_PLUGIN,
+        commandPrefix: 'annotate',
+        defaultCommand: 'open',
+        commands: [
+            { name: 'open', rootOnly: true, description: 'Annotate a page or app and send it to the agent: /annotate: [url | --app <port> | --bridge]' },
+            { name: 'notes', description: 'Every saved web annotation, searchable' },
+            { name: 'submit', description: 'Send this session\'s unsent annotations with your request: /annotate:submit <request>' },
+            { name: 'clear', description: 'Resolve this session\'s unsent annotations and stop sharing them' }
+        ],
+        createWorldPart: ({ options }) => annotationsPart({ root: options.root }),
+        serverMethods: annotationServerMethods
+    },
+    { descriptor: CAPABILITIES_PLUGIN },
+    {
+        descriptor: USAGE_PLUGIN,
+        commandPrefix: 'usage',
+        defaultCommand: 'analysis',
+        commands: [
+            { name: 'analysis', description: 'Token, cost and latency totals: /usage:analysis [today | 7d | 30d | all]' },
+            { name: 'limit', description: 'Provider plan windows, balances and rate limits: /usage:limit' },
+            { name: 'accounts', description: 'Provider limits across all accounts: /usage:accounts' }
+        ],
+        serverMethods: usageServerMethods
+    },
+    { descriptor: DOCTOR_PLUGIN, serverMethods: doctorServerMethods },
+    { descriptor: WORKTREES_PLUGIN, serverMethods: worktreeServerMethods },
+    ...FIRST_PARTY_PLUGINS.map(descriptor => ({ descriptor }))
+]);
+export const HARNESS_PLUGINS = BUILTIN_PLUGIN_REGISTRY.descriptors();

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

@@ -0,0 +1,62 @@
+import type { Harness } from "../harness.js";
+import type { Handler } from "../server/rpc.js";
+import type { WorldOptions, WorldPart } from "../world/world.js";
+import type { BrowserEngine } from "../browser/index.js";
+import type { CallerContext } from "../core/caller.js";
+import type { DispatchEnv } from "../tools/dispatch.js";
+import type { ToolSpec } from "../tools/types.js";
+import type { Subagents } from "../sessions/subagentService.js";
+import type { ActiveRun } from "../sessions/registry.js";
+import type { PluginDescriptor } from "./types.js";
+export interface BuiltinPluginCommand {
+    pluginId: string;
+    prefix: string;
+    name: string;
+    description: string;
+    legacyBare: boolean;
+    /** Reached only as the namespace root (`/annotate:`); it has no `/<prefix>:<name>` route and is not listed by name. */
+    rootOnly?: boolean;
+}
+export interface BuiltinWorldContext {
+    options: WorldOptions;
+    setting(pluginId: string, key: string): number;
+    browserEngine: BrowserEngine | null;
+}
+export interface BuiltinToolContext {
+    env: DispatchEnv;
+    caller: CallerContext;
+    variantDir: string | null;
+    run: ActiveRun;
+    runId: string;
+    allowedTools: readonly string[];
+    harnessTools: boolean;
+    subagents: Subagents;
+    sessionName: ToolSpec;
+    connectionTools?: () => ToolSpec[];
+}
+export interface BuiltinPluginModule {
+    descriptor: PluginDescriptor;
+    /** Stable terminal command namespace; defaults to the plugin id. */
+    commandPrefix?: string;
+    /** Command invoked by the namespace root, such as `/annotate:`. Mark it `rootOnly` to give it no named route. */
+    defaultCommand?: string;
+    /** Stable order for model tools, independent of descriptor display order. */
+    toolOrder?: number;
+    tools?: (context: BuiltinToolContext) => ToolSpec[];
+    commands?: readonly Omit<BuiltinPluginCommand, 'pluginId' | 'prefix' | 'legacyBare'>[];
+    createWorldPart?: (context: BuiltinWorldContext) => WorldPart | null;
+    serverMethods?: (harness: Harness) => Record<string, Handler>;
+}
+export interface BuiltinPluginRegistry {
+    readonly modules: readonly BuiltinPluginModule[];
+    descriptors(): PluginDescriptor[];
+    commands(): BuiltinPluginCommand[];
+    command(prefix: string, name: string): BuiltinPluginCommand | undefined;
+    commandsNamed(name: string): BuiltinPluginCommand[];
+    defaultCommand(prefix: string): BuiltinPluginCommand | undefined;
+    tools(context: BuiltinToolContext): ToolSpec[];
+    worldParts(context: BuiltinWorldContext): WorldPart[];
+    serverMethods(harness: Harness): Record<string, Handler>;
+}
+/** One checked registry for the Harness-owned plugin modules and their surface contributions. */
+export declare function createBuiltinPluginRegistry(modules: readonly BuiltinPluginModule[]): BuiltinPluginRegistry;

package/dist/sdk/plugins/builtinRegistry.js

@@ -0,0 +1,77 @@
+/** One checked registry for the Harness-owned plugin modules and their surface contributions. */
+export function createBuiltinPluginRegistry(modules) {
+    const pluginIds = new Set();
+    const prefixOwners = new Map();
+    const routeKeys = new Set();
+    for (const module of modules) {
+        const id = module.descriptor.id;
+        if (pluginIds.has(id))
+            throw new Error(`Duplicate built-in plugin id: ${id}`);
+        pluginIds.add(id);
+        const prefix = module.commandPrefix ?? id;
+        if (!/^[a-z][a-z0-9-]*$/.test(prefix) || prefix === 'plugin' || prefix === 'skill')
+            throw new Error(`Invalid built-in plugin command prefix: ${prefix}`);
+        if ((module.commands?.length || module.defaultCommand) && prefixOwners.has(prefix)) {
+            throw new Error(`Duplicate built-in plugin command prefix: ${prefix}`);
+        }
+        if (module.commands?.length || module.defaultCommand)
+            prefixOwners.set(prefix, id);
+        for (const command of module.commands ?? []) {
+            if (!/^[a-z][a-z0-9-]*$/.test(command.name))
+                throw new Error(`Invalid built-in plugin command: ${command.name}`);
+            const key = `${prefix}:${command.name}`;
+            if (routeKeys.has(key))
+                throw new Error(`Duplicate built-in plugin command: ${key}`);
+            routeKeys.add(key);
+        }
+        if (module.defaultCommand && !module.commands?.some(command => command.name === module.defaultCommand)) {
+            throw new Error(`Unknown default command for built-in plugin ${id}: ${module.defaultCommand}`);
+        }
+        for (const command of module.commands ?? []) {
+            if (command.rootOnly && command.name !== module.defaultCommand)
+                throw new Error(`Root-only command ${prefix}:${command.name} must be the default command of built-in plugin ${id}.`);
+        }
+    }
+    const commands = modules.flatMap(module => (module.commands ?? []).map(command => ({
+        pluginId: module.descriptor.id,
+        prefix: module.commandPrefix ?? module.descriptor.id,
+        ...command,
+        legacyBare: !!module.descriptor.required
+    })));
+    const allRoutes = new Map(commands.map(command => [`${command.prefix}:${command.name}`, command]));
+    const routed = commands.filter(command => !command.rootOnly);
+    const byRoute = new Map(routed.map(command => [`${command.prefix}:${command.name}`, command]));
+    const byName = new Map();
+    for (const command of routed)
+        byName.set(command.name, [...(byName.get(command.name) ?? []), command]);
+    const defaults = new Map(modules.flatMap(module => module.defaultCommand
+        ? [[module.commandPrefix ?? module.descriptor.id, allRoutes.get(`${module.commandPrefix ?? module.descriptor.id}:${module.defaultCommand}`)]]
+        : []));
+    const toolModules = modules.map((module, index) => ({ module, index })).filter(({ module }) => module.tools)
+        .sort((left, right) => (left.module.toolOrder ?? left.index) - (right.module.toolOrder ?? right.index));
+    return {
+        modules,
+        descriptors: () => modules.map(module => module.descriptor),
+        commands: () => [...commands],
+        command: (prefix, name) => byRoute.get(`${prefix}:${name}`),
+        commandsNamed: name => [...(byName.get(name) ?? [])],
+        defaultCommand: prefix => defaults.get(prefix),
+        tools: context => toolModules.flatMap(({ module }) => module.tools(context)),
+        worldParts: context => modules.flatMap(module => {
+            const part = module.createWorldPart?.(context);
+            return part ? [part] : [];
+        }),
+        serverMethods: harness => {
+            const methods = {};
+            for (const module of modules) {
+                const contributed = module.serverMethods?.(harness) ?? {};
+                for (const [name, handler] of Object.entries(contributed)) {
+                    if (name in methods)
+                        throw new Error(`Duplicate built-in server method: ${name}`);
+                    methods[name] = handler;
+                }
+            }
+            return methods;
+        }
+    };
+}

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,197 @@
+// 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,
+        surfaces: descriptor.surfaces ?? 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. Xingular sessions do not load it, in the terminal or in a host, so both offer the same tools.' });
+    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: xagent 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;