@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/mcp/types.d.ts

@@ -0,0 +1,131 @@
+import { z } from 'zod';
+/** Loopback address every OAuth sign-in returns to. Pre-registered clients must list it exactly. */
+export declare const MCP_OAUTH_PORT = 47823;
+export declare const MCP_OAUTH_REDIRECT_URL = "http://127.0.0.1:47823/oauth/callback";
+/**
+ * The application's own registered OAuth clients, by catalog entry. A client supplied here is
+ * used for that sign-in only and is never written to the connection or the secret store.
+ */
+export interface AppOAuthClients {
+    /** The catalog entries this application can sign in for. */
+    ids(): string[];
+    get(catalogId: string): Promise<{
+        clientId: string;
+        clientSecret?: string;
+    } | null>;
+}
+/** Stable attachment key for a connected app's capability switch. */
+export declare const connectionCapabilityId: (id: string) => string;
+export declare const connectionSchema: z.ZodObject<{
+    id: z.ZodDefault<z.ZodString>;
+    name: z.ZodDefault<z.ZodString>;
+    kind: z.ZodDefault<z.ZodString>;
+    command: z.ZodDefault<z.ZodString>;
+    args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    cwd: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    envKeys: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    global: z.ZodDefault<z.ZodBoolean>;
+    agentIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    projectIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    excludedAgentIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    excludedProjectIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    readTools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    expectedVaultId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    checkedAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    serverName: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    tools: z.ZodDefault<z.ZodArray<z.ZodUnknown>>;
+    error: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    auth: z.ZodDefault<z.ZodString>;
+    headerKeys: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    oauthClient: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    oauthScopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    authState: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    catalogId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type Connection = z.infer<typeof connectionSchema>;
+export declare const connectionInputSchema: z.ZodObject<{
+    id: z.ZodDefault<z.ZodString>;
+    name: z.ZodDefault<z.ZodString>;
+    kind: z.ZodDefault<z.ZodString>;
+    command: z.ZodDefault<z.ZodString>;
+    args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    cwd: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    envKeys: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    global: z.ZodDefault<z.ZodBoolean>;
+    agentIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    projectIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    excludedAgentIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    excludedProjectIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    readTools: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    expectedVaultId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    checkedAt: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    serverName: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    tools: z.ZodDefault<z.ZodArray<z.ZodUnknown>>;
+    error: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    url: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    auth: z.ZodDefault<z.ZodString>;
+    headerKeys: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    oauthClient: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    oauthScopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    authState: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    catalogId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    env: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    removeEnv: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    headers: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    removeHeaders: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    oauthCredentials: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        clientId: z.ZodString;
+        clientSecret: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ConnectionInput = z.input<typeof connectionInputSchema>;
+export interface StdioConfig {
+    id: string;
+    name: string;
+    transport: 'stdio';
+    command: string;
+    args: string[];
+    cwd: string | null;
+    env: Record<string, string>;
+}
+export interface HttpConfig {
+    id: string;
+    name: string;
+    transport: 'http';
+    url: string;
+    headers: Record<string, string>;
+    auth: 'none' | 'headers' | 'oauth';
+    scopes: string[];
+}
+/** What it takes to reach a server: a process to start, or an address and its credentials. */
+export type LaunchConfig = StdioConfig | HttpConfig;
+/** Who a session is, for deciding which connections it may reach. */
+export interface Scope {
+    agentId?: string | null;
+    projectId?: string | null;
+}
+export interface McpSource {
+    id: string;
+    title: string;
+    uri: string;
+    path?: string | null;
+    revision?: string;
+    excerpt?: string;
+    projectId?: string;
+}
+/** One connected-app call a run made, kept in `runs/<id>/mcp-context.json`. */
+export interface McpTrace {
+    id: string;
+    connectionId: string;
+    connectionName: string;
+    tool: string;
+    at: string;
+    ok: boolean;
+    summary: string;
+    result: string;
+    sources: McpSource[];
+    truncated: boolean;
+}

package/dist/sdk/mcp/types.js

@@ -0,0 +1,49 @@
+// Connected apps: MCP servers the user added. A connection is device-local; its secrets
+// (environment values, request headers, OAuth tokens and client) are in the secret store,
+// never in `connections.json`.
+import { z } from 'zod';
+/** Loopback address every OAuth sign-in returns to. Pre-registered clients must list it exactly. */
+export const MCP_OAUTH_PORT = 47823;
+export const MCP_OAUTH_REDIRECT_URL = `http://127.0.0.1:${MCP_OAUTH_PORT}/oauth/callback`;
+/** Stable attachment key for a connected app's capability switch. */
+export const connectionCapabilityId = (id) => `connected-apps/connection/${id}`;
+export const connectionSchema = z.object({
+    id: z.string().default(''),
+    name: z.string().default(''),
+    /** `workspace` (the first-party Xingular Workspace server), `local` (a command), or `remote` (Streamable HTTP). */
+    kind: z.string().default(''),
+    command: z.string().default(''),
+    args: z.array(z.string()).default([]),
+    cwd: z.string().nullable().default(null),
+    envKeys: z.array(z.string()).default([]),
+    enabled: z.boolean().default(false),
+    /** Available to every agent and project, except those excluded. */
+    global: z.boolean().default(false),
+    agentIds: z.array(z.string()).default([]),
+    projectIds: z.array(z.string()).default([]),
+    excludedAgentIds: z.array(z.string()).default([]),
+    excludedProjectIds: z.array(z.string()).default([]),
+    /** Tools that run without asking. */
+    readTools: z.array(z.string()).default([]),
+    expectedVaultId: z.string().nullable().default(null),
+    checkedAt: z.string().nullable().default(null),
+    serverName: z.string().nullable().default(null),
+    tools: z.array(z.unknown()).default([]),
+    error: z.string().nullable().default(null),
+    url: z.string().nullable().default(null),
+    /** `none`, `headers`, or `oauth`. */
+    auth: z.string().default(''),
+    headerKeys: z.array(z.string()).default([]),
+    oauthClient: z.string().nullable().default(null),
+    oauthScopes: z.array(z.string()).default([]),
+    authState: z.string().nullable().default(null),
+    catalogId: z.string().nullable().default(null)
+});
+export const connectionInputSchema = connectionSchema.extend({
+    env: z.record(z.string(), z.string()).nullish(),
+    removeEnv: z.array(z.string()).nullish(),
+    headers: z.record(z.string(), z.string()).nullish(),
+    removeHeaders: z.array(z.string()).nullish(),
+    /** A client registered by the user with the provider; replaces any saved sign-in. */
+    oauthCredentials: z.object({ clientId: z.string(), clientSecret: z.string() }).nullish()
+});

package/dist/sdk/pi/retryPolicy.d.ts

@@ -0,0 +1,19 @@
+/** Eight attempts at 2, 4, 8, 16, 32, 60, 60 and 60 seconds: about four minutes in all. */
+export declare const TRANSIENT_RETRY: {
+    readonly enabled: true;
+    readonly maxRetries: 8;
+    readonly baseDelayMs: 2000;
+    readonly maxAgentDelayMs: 60000;
+};
+interface RetrySettings {
+    getGlobalSettings(): {
+        retry?: Record<string, unknown>;
+    };
+    getProjectSettings(): {
+        retry?: Record<string, unknown>;
+    };
+    applyOverrides(overrides: Record<string, unknown>): void;
+}
+/** Raises the retry budget on a settings manager; anything the person set themselves still wins. */
+export declare function withTransientRetry<T extends RetrySettings>(manager: T): T;
+export {};

package/dist/sdk/pi/retryPolicy.js

@@ -0,0 +1,11 @@
+// Pi retries a failed model request three times, 2, 4 and 8 seconds apart: about fourteen seconds
+// of patience, so a half-minute network drop ended the whole reply. A reply that is working should
+// ride out a short outage on its own (the working row shows the countdown), and stop for the person
+// only when the outage outlasts several minutes or the error is not one a retry can fix.
+/** Eight attempts at 2, 4, 8, 16, 32, 60, 60 and 60 seconds: about four minutes in all. */
+export const TRANSIENT_RETRY = { enabled: true, maxRetries: 8, baseDelayMs: 2_000, maxAgentDelayMs: 60_000 };
+/** Raises the retry budget on a settings manager; anything the person set themselves still wins. */
+export function withTransientRetry(manager) {
+    manager.applyOverrides({ retry: { ...TRANSIENT_RETRY, ...manager.getGlobalSettings().retry, ...manager.getProjectSettings().retry } });
+    return manager;
+}

package/dist/sdk/pi/runtime.d.ts

@@ -0,0 +1,14 @@
+export declare const PINNED_PI_VERSION = "1.4.0";
+export declare const HTTP_DISPATCHER_CHUNK = "dist/bundle/chunks/chunk-MM3LKT73.js";
+type PiRuntimeModule = {
+    VERSION: string;
+    getPackageDir(): string;
+};
+type PiDispatcherModule = {
+    configureHttpDispatcher?: unknown;
+};
+export declare function assertPiRuntimeVersion(version: string): void;
+/** Builds a cached Pi loader so initialization order and compatibility behavior can be verified. */
+export declare function createPiLoader<T extends PiRuntimeModule>(importPi: () => Promise<T>, importDispatcher: (packageDir: string) => Promise<PiDispatcherModule>): () => Promise<T>;
+export declare const loadPi: () => Promise<typeof import("@earendil-works/pi-coding-agent")>;
+export {};

package/dist/sdk/pi/runtime.js

@@ -0,0 +1,31 @@
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+export const PINNED_PI_VERSION = '1.4.0';
+export const HTTP_DISPATCHER_CHUNK = 'dist/bundle/chunks/chunk-MM3LKT73.js';
+export function assertPiRuntimeVersion(version) {
+    if (version !== PINNED_PI_VERSION)
+        throw new Error(`The Harness Pi runtime requires Pi ${PINNED_PI_VERSION}; found ${version}. Install the Harness package's pinned dependencies.`);
+}
+/** Builds a cached Pi loader so initialization order and compatibility behavior can be verified. */
+export function createPiLoader(importPi, importDispatcher) {
+    let loading;
+    return () => {
+        if (!loading) {
+            loading = (async () => {
+                const pi = await importPi();
+                assertPiRuntimeVersion(pi.VERSION);
+                const dispatcher = await importDispatcher(pi.getPackageDir());
+                if (typeof dispatcher.configureHttpDispatcher !== 'function') {
+                    throw new Error(`The Harness requires the pinned Pi ${PINNED_PI_VERSION} HTTP dispatcher hook; install the Harness package's pinned dependencies.`);
+                }
+                dispatcher.configureHttpDispatcher();
+                return pi;
+            })().catch((error) => {
+                loading = undefined;
+                throw error;
+            });
+        }
+        return loading;
+    };
+}
+export const loadPi = createPiLoader(() => import('@earendil-works/pi-coding-agent'), async (packageDir) => await import(pathToFileURL(join(packageDir, HTTP_DISPATCHER_CHUNK)).href));

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

@@ -0,0 +1,66 @@
+import type { Harness } from "../harness.js";
+import type { CallerContext } from "../core/caller.js";
+import type { Launch } from "../prompt/compile.js";
+import { type VariantChoice } from "../variant/materialise.js";
+import * as attachments from "./attachments.js";
+import type { Loading } from "./plugins.js";
+import type { Inventory, Plugin } from "./types.js";
+export interface PluginScope {
+    /** The working folder to list for. Without one, nothing a folder brings is listed. */
+    cwd?: string | null;
+    /** The account whose Pi folder is searched. Defaults to the default account. */
+    accountId?: string | null;
+    /** Whose list it is. With either, each state is what that agent or project gets. */
+    agentId?: string | null;
+    projectId?: string | null;
+}
+/**
+ * What Pi would load for this account and folder. Before the first account exists, the folder
+ * every account shares stands in: packages and shared files are the same for all of them.
+ * `null` only when the account that was named cannot be found.
+ */
+export declare function loadingFor(harness: Harness, scope: PluginScope): Promise<Loading | null>;
+export declare function list(harness: Harness, scope?: PluginScope): Promise<Plugin[]>;
+export interface InventoryParams extends PluginScope {
+    context?: CallerContext;
+    launch?: Launch;
+    tools?: string[];
+    connections?: boolean;
+    /** The variant the caller runs, so what it adds is listed too. */
+    variant?: VariantChoice | null;
+}
+export declare function inventoryFor(harness: Harness, params: InventoryParams): Promise<Inventory>;
+/**
+ * Trusts code a person was shown, if it is still that code: a working folder's own, or an
+ * installed package's. The hash names which; a folder is needed only for the working folder's.
+ */
+export declare function trust(harness: Harness, scope: PluginScope & {
+    hash: string;
+}): Promise<Plugin[]>;
+export declare function untrust(harness: Harness, scope: PluginScope & {
+    hash: string;
+}): Promise<Plugin[]>;
+export interface AttachParams extends PluginScope {
+    /** A plugin's id, or one contribution's. */
+    id: string;
+    /** Who the switch is for. Neither id means everywhere. */
+    scope?: attachments.AttachScope | null;
+}
+/**
+ * Switches a plugin, or one thing it brings, on or off: everywhere, for one agent, or for one
+ * project. A required part refuses and says why. Nothing here grants a permission: a tool that
+ * is switched on still passes the gate.
+ */
+export declare function attach(harness: Harness, params: AttachParams, on: boolean): Promise<Plugin[]>;
+/** Saves the numbers a person set on a plugin. Each must be one of the plugin's settings and inside its range. */
+export declare function configure(harness: Harness, params: PluginScope & {
+    pluginId: string;
+    settings: Record<string, unknown>;
+}): Promise<Plugin[]>;
+/**
+ * Makes sure the packages that loaded before trust was asked per package were taken over, before
+ * something new is written that must not be taken over with them.
+ */
+export declare function ensureAdopted(harness: Harness): Promise<void>;
+/** Forgets what was switched for an agent that no longer exists. */
+export declare function forgetAgent(harness: Harness, agentId: string): void;

package/dist/sdk/plugins/api.js

@@ -0,0 +1,155 @@
+// The plugin calls a host makes: the list, what reaches one caller, switching something on or
+// off for a scope, and the trust decision.
+import { join } from 'node:path';
+import { ensureSharedDir, sharedDir } from "../accounts/env.js";
+import { invalid, notFound } from "../core/errors.js";
+import { findProject } from "../core/projects.js";
+import { materialise } from "../variant/materialise.js";
+import * as attachments from "./attachments.js";
+import { catalogue } from "./catalogue.js";
+import { inventory } from "./inventory.js";
+const callerOf = (scope) => ({ agentId: scope.agentId ?? null, projectId: scope.projectId ?? null });
+/**
+ * What Pi would load for this account and folder. Before the first account exists, the folder
+ * every account shares stands in: packages and shared files are the same for all of them.
+ * `null` only when the account that was named cannot be found.
+ */
+export async function loadingFor(harness, scope) {
+    let agentDir;
+    try {
+        agentDir = harness.accounts.context(harness.accounts.resolve(scope.accountId ?? null, null)).configDir;
+    }
+    catch {
+        if (scope.accountId)
+            return null;
+        agentDir = ensureSharedDir(harness.accounts.dir);
+    }
+    // Listing never installs anything. Without a working folder the state folder stands in, and
+    // what it "brings" is dropped by the catalogue.
+    return harness.plugins.loading({ cwd: scope.cwd || harness.stateDir, agentDir, caller: callerOf(scope) });
+}
+export async function list(harness, scope = {}) {
+    return catalogue({
+        root: harness.env.root,
+        descriptors: harness.descriptors,
+        application: harness.applicationPlugins,
+        connections: harness.apps.connections.list(),
+        loading: await loadingFor(harness, scope),
+        cwd: scope.cwd || null,
+        sharedDir: sharedDir(harness.accounts.dir),
+        packagesDir: join(harness.env.root, 'plugins'),
+        registered: harness.plugins.registered(),
+        hooks: harness.hooks.status(),
+        attachments: attachments.load(harness.env.root),
+        caller: callerOf(scope)
+    });
+}
+export async function inventoryFor(harness, params) {
+    return inventory({
+        env: harness.env,
+        context: params.context ?? {},
+        launch: params.launch ?? {},
+        tools: Array.isArray(params.tools) ? params.tools : [],
+        connections: params.connections !== false,
+        // What is switched off for the caller is not in what reaches it.
+        plugins: await list(harness, { ...params, agentId: params.agentId ?? params.context?.agentId ?? null, projectId: params.projectId ?? params.context?.projectId ?? null }),
+        descriptors: harness.descriptors,
+        saved: harness.apps.connections.list(),
+        variant: params.variant ? materialise(harness.env.root, params.variant, { trust: harness.trust }) : null
+    });
+}
+/**
+ * Trusts code a person was shown, if it is still that code: a working folder's own, or an
+ * installed package's. The hash names which; a folder is needed only for the working folder's.
+ */
+export async function trust(harness, scope) {
+    const loading = await loadingFor(harness, scope);
+    const project = scope.cwd && loading?.projectCode?.hash === scope.hash ? { code: loading.projectCode, folder: scope.cwd } : null;
+    const packaged = Object.entries(loading?.packageCode ?? {}).find(([, code]) => code.hash === scope.hash);
+    const match = project ?? (packaged ? { code: packaged[1], folder: packaged[0] } : null);
+    if (!match)
+        throw invalid('This code changed since it was shown. Review it again before trusting it.');
+    harness.plugins.trust.grant({ hash: match.code.hash, files: match.code.files }, match.folder);
+    return list(harness, scope);
+}
+export async function untrust(harness, scope) {
+    harness.plugins.trust.revoke(scope.hash);
+    return list(harness, scope);
+}
+/**
+ * Switches a plugin, or one thing it brings, on or off: everywhere, for one agent, or for one
+ * project. A required part refuses and says why. Nothing here grants a permission: a tool that
+ * is switched on still passes the gate.
+ */
+export async function attach(harness, params, on) {
+    const { root } = harness.env;
+    const scope = { agentId: params.scope?.agentId || null, projectId: params.scope?.projectId || null };
+    if (scope.projectId)
+        findProject(root, scope.projectId);
+    const plugins = await list(harness, params);
+    const plugin = plugins.find((candidate) => candidate.id === params.id || candidate.contributions.some((entry) => entry.id === params.id));
+    if (!plugin)
+        throw notFound('Plugin');
+    const contribution = plugin.id === params.id ? null : plugin.contributions.find((entry) => entry.id === params.id);
+    if (plugin.required && contribution?.kind !== 'connection')
+        throw invalid(`${plugin.title} cannot be switched off. ${plugin.required}`);
+    if (plugin.source === 'application')
+        throw invalid(`${plugin.title} is switched by the application that provides it.`);
+    if (!(contribution ?? plugin).attachment)
+        throw invalid(contribution ? `${contribution.name} cannot be switched on its own.` : `${plugin.title} is switched one item at a time.`);
+    if (contribution?.kind === 'connection') {
+        harness.apps.attach(contribution.id.slice(`${plugin.id}/connection/`.length), scope, on);
+    }
+    else {
+        // A choice is stored under the contribution's id and then its plugin's.
+        const ids = contribution ? [contribution.id, plugin.id] : [plugin.id];
+        // What it is until a person says otherwise: a part that ships switched off is off, and
+        // anything found on disk is on.
+        const shipped = harness.descriptors.find((descriptor) => descriptor.id === plugin.id)?.switchable;
+        const fallback = shipped ? shipped.on : true;
+        const choices = attachments.load(root);
+        attachments.set(choices, ids, scope, on, fallback);
+        attachments.save(root, choices);
+    }
+    harness.bus.emit({ type: 'plugins.changed' });
+    return list(harness, params);
+}
+/** Saves the numbers a person set on a plugin. Each must be one of the plugin's settings and inside its range. */
+export async function configure(harness, params) {
+    const descriptor = harness.descriptors.find((candidate) => candidate.id === params.pluginId);
+    if (!descriptor?.settings?.length)
+        throw invalid('This plugin has no settings.');
+    const choices = attachments.load(harness.env.root);
+    const saved = { ...choices.settings[descriptor.id] };
+    for (const [key, value] of Object.entries(params.settings ?? {})) {
+        const setting = descriptor.settings.find((candidate) => candidate.key === key);
+        if (!setting)
+            throw invalid(`${descriptor.title} has no setting called "${key}".`);
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < setting.min || value > setting.max)
+            throw invalid(`${setting.label} must be a number from ${setting.min} to ${setting.max}.`);
+        saved[key] = Math.floor(value);
+    }
+    choices.settings[descriptor.id] = saved;
+    attachments.save(harness.env.root, choices);
+    harness.bus.emit({ type: 'plugins.changed' });
+    return list(harness, params);
+}
+/**
+ * Makes sure the packages that loaded before trust was asked per package were taken over, before
+ * something new is written that must not be taken over with them.
+ */
+export async function ensureAdopted(harness) {
+    if (harness.plugins.trust.adopted)
+        return;
+    await loadingFor(harness, {});
+    if (!harness.plugins.trust.adopted)
+        harness.plugins.trust.adopt([]);
+}
+/** Forgets what was switched for an agent that no longer exists. */
+export function forgetAgent(harness, agentId) {
+    const choices = attachments.load(harness.env.root);
+    if (!choices.agents[agentId])
+        return;
+    attachments.forget(choices, { agentId });
+    attachments.save(harness.env.root, choices);
+}

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

@@ -0,0 +1,46 @@
+/** Who a choice applies to. Neither id means everywhere. */
+export interface AttachScope {
+    agentId?: string | null;
+    projectId?: string | null;
+}
+interface Entries {
+    on: string[];
+    off: string[];
+}
+export interface Attachments {
+    version: 1;
+    global: Entries;
+    agents: Record<string, Entries>;
+    projects: Record<string, Entries>;
+    /** Values a plugin reads, such as a limit. Keyed by plugin id. */
+    settings: Record<string, Record<string, unknown>>;
+}
+/** Where one id is switched on and off, as data for a screen. */
+export interface Attachment {
+    /** On everywhere, unless a narrower scope says otherwise. */
+    global: boolean;
+    on: {
+        agentIds: string[];
+        projectIds: string[];
+    };
+    off: {
+        agentIds: string[];
+        projectIds: string[];
+    };
+}
+export declare function load(root: string): Attachments;
+export declare function save(root: string, attachments: Attachments): void;
+/** What the stored choices say for a caller, or `null` when none applies. `ids` is the thing, then what it belongs to. */
+export declare function decided(attachments: Attachments, ids: readonly string[], caller?: AttachScope): boolean | null;
+export declare function attached(attachments: Attachments, ids: readonly string[], caller: AttachScope, fallback: boolean): boolean;
+/**
+ * Switches one thing on or off for a scope. A choice that only repeats what the wider scopes
+ * already say is not kept, so the thing follows them again when they change.
+ */
+export declare function set(attachments: Attachments, ids: readonly string[], scope: AttachScope, on: boolean, fallback: boolean): void;
+export declare function describe(attachments: Attachments, id: string, fallback: boolean): Attachment;
+/** Forgets an agent's or a project's own choices, when it is deleted. */
+export declare function forget(attachments: Attachments, scope: AttachScope): void;
+/** Removes one capability's choices without disturbing the other items in each scope. */
+export declare function forgetId(attachments: Attachments, id: string): void;
+export {};

package/dist/sdk/plugins/attachments.js

@@ -0,0 +1,111 @@
+// What is switched on, and for whom. One file in the data root holds every choice a person made
+// about a plugin or one of its contributions; one rule reads it: the narrowest scope that says
+// something wins, an agent before a project before everywhere. With no entry, the thing keeps
+// its own default (what loads today stays on; a person's registry item is off until switched on).
+import { join } from 'node:path';
+import { readJsonOr, writeJson } from "../core/fs.js";
+const path = (root) => join(root, 'config/plugin-attachments.json');
+const legacyPath = (root) => join(root, 'config/registry-enabled.json');
+const strings = (value) => (Array.isArray(value) ? value.filter((id) => typeof id === 'string') : []);
+const entries = (value) => {
+    const record = (value && typeof value === 'object' ? value : {});
+    return { on: strings(record.on), off: strings(record.off) };
+};
+const scoped = (value) => Object.fromEntries(Object.entries((value && typeof value === 'object' && !Array.isArray(value) ? value : {})).map(([id, item]) => [id, entries(item)]));
+/**
+ * The registry's earlier file: enabled ids keyed by project id, `global` (once `personal`) for
+ * everyone, and `builtinOff` for built-in items a person switched off. It is read until the
+ * first change is saved here, and never written again.
+ */
+function fromLegacy(root) {
+    const legacy = readJsonOr(legacyPath(root), {});
+    const map = (legacy && typeof legacy === 'object' && !Array.isArray(legacy) ? legacy : {});
+    const projects = {};
+    for (const [key, ids] of Object.entries(map)) {
+        if (key === 'global' || key === 'personal' || key === 'builtinOff')
+            continue;
+        projects[key] = { on: strings(ids), off: [] };
+    }
+    return { version: 1, global: { on: [...new Set([...strings(map.global), ...strings(map.personal)])], off: strings(map.builtinOff) }, agents: {}, projects, settings: {} };
+}
+export function load(root) {
+    const stored = readJsonOr(path(root), null);
+    if (!stored || typeof stored !== 'object' || stored.version !== 1)
+        return fromLegacy(root);
+    const settings = (stored.settings && typeof stored.settings === 'object' && !Array.isArray(stored.settings) ? stored.settings : {});
+    return { version: 1, global: entries(stored.global), agents: scoped(stored.agents), projects: scoped(stored.projects), settings };
+}
+export function save(root, attachments) {
+    const kept = (map) => Object.fromEntries(Object.entries(map).filter(([, item]) => item.on.length || item.off.length));
+    writeJson(path(root), { ...attachments, agents: kept(attachments.agents), projects: kept(attachments.projects) });
+}
+const said = (item, ids) => {
+    if (!item)
+        return null;
+    // The first id is the thing itself; the rest are what it belongs to.
+    for (const id of ids) {
+        if (item.off.includes(id))
+            return false;
+        if (item.on.includes(id))
+            return true;
+    }
+    return null;
+};
+/** What the stored choices say for a caller, or `null` when none applies. `ids` is the thing, then what it belongs to. */
+export function decided(attachments, ids, caller = {}) {
+    return (caller.agentId ? said(attachments.agents[caller.agentId], ids) : null) ?? (caller.projectId ? said(attachments.projects[caller.projectId], ids) : null) ?? said(attachments.global, ids);
+}
+export function attached(attachments, ids, caller, fallback) {
+    return decided(attachments, ids, caller) ?? fallback;
+}
+function entriesAt(attachments, scope) {
+    if (scope.agentId)
+        return (attachments.agents[scope.agentId] ??= { on: [], off: [] });
+    if (scope.projectId)
+        return (attachments.projects[scope.projectId] ??= { on: [], off: [] });
+    return attachments.global;
+}
+/**
+ * Switches one thing on or off for a scope. A choice that only repeats what the wider scopes
+ * already say is not kept, so the thing follows them again when they change.
+ */
+export function set(attachments, ids, scope, on, fallback) {
+    const [id] = ids;
+    const target = entriesAt(attachments, scope.agentId ? { agentId: scope.agentId } : scope);
+    target.on = target.on.filter((item) => item !== id);
+    target.off = target.off.filter((item) => item !== id);
+    // An agent works in different projects, so a project's choice about this thing cannot stand in for the agent's.
+    const projectSays = !!scope.agentId && Object.values(attachments.projects).some((item) => said(item, ids) !== null);
+    const inherited = decided(attachments, ids, scope.agentId ? { agentId: scope.agentId } : scope) ?? fallback;
+    if (on !== inherited || projectSays)
+        (on ? target.on : target.off).push(id);
+}
+export function describe(attachments, id, fallback) {
+    const where = (map, list) => Object.entries(map).filter(([, item]) => item[list].includes(id)).map(([key]) => key);
+    return {
+        global: said(attachments.global, [id]) ?? fallback,
+        on: { agentIds: where(attachments.agents, 'on'), projectIds: where(attachments.projects, 'on') },
+        off: { agentIds: where(attachments.agents, 'off'), projectIds: where(attachments.projects, 'off') }
+    };
+}
+/** Forgets an agent's or a project's own choices, when it is deleted. */
+export function forget(attachments, scope) {
+    if (scope.agentId)
+        delete attachments.agents[scope.agentId];
+    if (scope.projectId)
+        delete attachments.projects[scope.projectId];
+}
+/** Removes one capability's choices without disturbing the other items in each scope. */
+export function forgetId(attachments, id) {
+    const forgetFrom = (item) => {
+        item.on = item.on.filter((entry) => entry !== id);
+        item.off = item.off.filter((entry) => entry !== id);
+    };
+    forgetFrom(attachments.global);
+    for (const item of Object.values(attachments.agents))
+        forgetFrom(item);
+    for (const item of Object.values(attachments.projects))
+        forgetFrom(item);
+    attachments.agents = Object.fromEntries(Object.entries(attachments.agents).filter(([, item]) => item.on.length || item.off.length));
+    attachments.projects = Object.fromEntries(Object.entries(attachments.projects).filter(([, item]) => item.on.length || item.off.length));
+}

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

@@ -0,0 +1,7 @@
+import type { PluginDescriptor } from "./types.js";
+/** Pi itself. Its command's built-in extensions are added to it as they are found. */
+export declare const PI_PLUGIN: PluginDescriptor;
+/** The variant: the eight components that shape what an agent is told and can do. */
+export declare const VARIANT_PLUGIN: PluginDescriptor;
+export declare const BUILTIN_PLUGIN_REGISTRY: import("./builtinRegistry.js").BuiltinPluginRegistry;
+export declare const HARNESS_PLUGINS: readonly PluginDescriptor[];