@xingular/harness 0.1.6 → 1.0.0

package/dist/sdk/plugins/discover.js

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

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

@@ -0,0 +1,50 @@
+import type { PluginDescriptor, PluginSetting } from "./types.js";
+/** The part of Pi's extension API these two use. */
+interface Api {
+    on(event: 'tool_result', handler: (event: ToolResult) => unknown): void;
+    on(event: 'tool_call', handler: (event: {
+        toolName: string;
+    }) => unknown): void;
+    on(event: 'turn_start', handler: () => unknown): void;
+    on(event: 'message_end', handler: (event: {
+        message: {
+            role: string;
+            usage?: {
+                input?: number;
+                output?: number;
+                cacheRead?: number;
+                cacheWrite?: number;
+            };
+        };
+    }) => unknown): void;
+}
+interface ToolResult {
+    toolName: string;
+    content: ({
+        type: 'text';
+        text: string;
+    } | {
+        type: string;
+        [key: string]: unknown;
+    })[];
+}
+export declare const OUTPUT_TRIM = "output-trim";
+export declare const BUDGET_GUARD = "budget-guard";
+export declare const LESSONS = "lessons";
+export declare const LESSONS_CODE = "Reflect after a run";
+export declare const LESSONS_SETTINGS: PluginSetting[];
+export declare const FIRST_PARTY_PLUGINS: readonly PluginDescriptor[];
+/** A setting's value: what a person saved when it is a number inside the setting's range, else its default. */
+export declare function settingValue(setting: PluginSetting, saved: Record<string, unknown> | undefined): number;
+/** The text of a long result, cut to its first 70% and its last 30% of `maxChars`, with a line between that says what is missing. */
+export declare function trimText(text: string, maxChars: number): string;
+export declare function outputTrim(saved: Record<string, unknown> | undefined): (pi: Api) => void;
+export declare function budgetGuard(saved: Record<string, unknown> | undefined): (pi: Api) => void;
+export interface InlineExtension {
+    name: string;
+    /** A Pi extension factory. Typed loosely so this module needs nothing of Pi's to be loaded. */
+    factory: unknown;
+}
+/** The first-party extensions switched on for a caller, each with the settings a person saved. */
+export declare function firstPartyExtensions(on: (pluginId: string) => boolean, settings: Record<string, Record<string, unknown>>): InlineExtension[];
+export {};

package/dist/sdk/plugins/firstParty.js

@@ -0,0 +1,113 @@
+export const OUTPUT_TRIM = 'output-trim';
+export const BUDGET_GUARD = 'budget-guard';
+export const LESSONS = 'lessons';
+export const LESSONS_CODE = 'Reflect after a run';
+const OUTPUT_TRIM_SETTINGS = [
+    { key: 'maxChars', label: 'Longest tool result', description: 'A tool result longer than this many characters is cut to its beginning and its end.', default: 20_000, min: 2_000, max: 400_000 }
+];
+const BUDGET_GUARD_SETTINGS = [
+    { key: 'maxRequests', label: 'Model requests in one reply', description: 'After this many model requests in one reply or one run of work, tool calls are refused so the agent wraps up.', default: 60, min: 5, max: 2_000 },
+    { key: 'maxTokens', label: 'Tokens in one reply', description: 'The same, counted in tokens of every kind (cached ones included). 0 means no token limit.', default: 0, min: 0, max: 500_000_000 }
+];
+export const LESSONS_SETTINGS = [
+    { key: 'minToolCalls', label: 'Tool calls before reflecting', description: 'Only a run that made at least this many tool calls is reflected on; shorter runs rarely teach anything.', default: 4, min: 1, max: 1_000 },
+    { key: 'maxLessons', label: 'Most lessons kept', description: 'Once the Wiki holds this many lessons, no new one is written until some are removed.', default: 100, min: 1, max: 1_000 },
+    { key: 'maxChars', label: 'Longest lesson', description: 'A lesson longer than this many characters is not kept.', default: 2_000, min: 200, max: 10_000 }
+];
+export const FIRST_PARTY_PLUGINS = [
+    {
+        id: OUTPUT_TRIM,
+        title: 'Output trim',
+        description: 'Cuts a very long tool result to its beginning and its end before the model reads it, and says how much was cut.',
+        switchable: { on: false },
+        settings: OUTPUT_TRIM_SETTINGS,
+        code: [{ name: 'Trim long tool results', description: 'Runs after every tool call, in conversations, task threads and unattended work. Not in terminal sessions yet.' }]
+    },
+    {
+        id: BUDGET_GUARD,
+        title: 'Budget guard',
+        description: 'Stops a reply that keeps going: past a limit of model requests or tokens, further tool calls are refused and the agent is told to wrap up.',
+        switchable: { on: false },
+        settings: BUDGET_GUARD_SETTINGS,
+        code: [{ name: 'Refuse tool calls past the limit', description: 'Counts model requests and tokens in one reply, in conversations, task threads and unattended work. Not in terminal sessions yet.' }]
+    },
+    {
+        id: LESSONS,
+        title: 'Lessons',
+        description: 'After a finished run, a short reflection reads what happened and may keep one general lesson in the Wiki under library/lessons, for later runs to find. It uses the same account and model as the run, so it costs tokens.',
+        switchable: { on: false },
+        settings: LESSONS_SETTINGS,
+        code: [{ name: LESSONS_CODE, description: 'Runs in the background after a completed top-level run with enough tool calls. It reads only that run\'s record, has no tools that change anything, and writes at most one Wiki note.' }]
+    }
+];
+/** A setting's value: what a person saved when it is a number inside the setting's range, else its default. */
+export function settingValue(setting, saved) {
+    const value = saved?.[setting.key];
+    return typeof value === 'number' && Number.isFinite(value) && value >= setting.min && value <= setting.max ? Math.floor(value) : setting.default;
+}
+const values = (settings, saved) => Object.fromEntries(settings.map((setting) => [setting.key, settingValue(setting, saved)]));
+/** The text of a long result, cut to its first 70% and its last 30% of `maxChars`, with a line between that says what is missing. */
+export function trimText(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    const head = Math.floor(maxChars * 0.7);
+    const tail = maxChars - head;
+    const cut = text.length - maxChars;
+    return `${text.slice(0, head)}\n\n[… ${cut} of ${text.length} characters were cut here by the Output trim plugin. Ask for a narrower result (a line range, a filter, a smaller file) to see them. …]\n\n${text.slice(text.length - tail)}`;
+}
+export function outputTrim(saved) {
+    const { maxChars } = values(OUTPUT_TRIM_SETTINGS, saved);
+    return (pi) => {
+        pi.on('tool_result', (event) => {
+            const texts = event.content.filter((part) => part.type === 'text' && typeof part.text === 'string');
+            const total = texts.reduce((sum, part) => sum + part.text.length, 0);
+            if (total <= maxChars)
+                return undefined;
+            // Several text parts are read as one result; pictures and anything else pass through untouched.
+            const trimmed = trimText(texts.map((part) => part.text).join('\n'), maxChars);
+            return { content: [{ type: 'text', text: trimmed }, ...event.content.filter((part) => part.type !== 'text')] };
+        });
+    };
+}
+export function budgetGuard(saved) {
+    const { maxRequests, maxTokens } = values(BUDGET_GUARD_SETTINGS, saved);
+    return (pi) => {
+        let requests = 0;
+        let tokens = 0;
+        let refusedInRequest = 0;
+        pi.on('turn_start', () => {
+            requests += 1;
+        });
+        pi.on('message_end', (event) => {
+            if (event.message.role !== 'assistant' || !event.message.usage)
+                return;
+            const usage = event.message.usage;
+            tokens += (usage.input ?? 0) + (usage.output ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0);
+        });
+        // Pi's own event before a request can change what is sent and cannot refuse it, so the limit
+        // is held where the loop can be stopped: at the tool calls that keep it going.
+        pi.on('tool_call', () => {
+            const over = requests >= maxRequests ? `${maxRequests} model requests` : maxTokens > 0 && tokens >= maxTokens ? `${maxTokens} tokens` : null;
+            if (!over)
+                return undefined;
+            // The first refusal leaves the agent one request to say what is done. If it calls tools
+            // again instead, the batch ends the reply.
+            const again = refusedInRequest !== 0 && refusedInRequest !== requests;
+            refusedInRequest ||= requests;
+            return {
+                block: true,
+                terminate: again,
+                reason: `This reply reached its limit of ${over} (the Budget guard plugin). Call no more tools. Tell the user what is done and what is left; they can raise the limit on the Plugins page.`
+            };
+        });
+    };
+}
+/** The first-party extensions switched on for a caller, each with the settings a person saved. */
+export function firstPartyExtensions(on, settings) {
+    const extensions = [];
+    if (on(OUTPUT_TRIM))
+        extensions.push({ name: OUTPUT_TRIM, factory: outputTrim(settings[OUTPUT_TRIM]) });
+    if (on(BUDGET_GUARD))
+        extensions.push({ name: BUDGET_GUARD, factory: budgetGuard(settings[BUDGET_GUARD]) });
+    return extensions;
+}

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

@@ -0,0 +1,94 @@
+import type { Bus } from "../core/bus.js";
+import { type Change } from "../core/changes.js";
+export declare const HOOK_EVENTS: readonly ["wiki.page.saved", "history.run.ended"];
+export type HookEventType = (typeof HOOK_EVENTS)[number];
+/** A Wiki note, as it is after the change. */
+export interface EntryEvent {
+    type: 'wiki.page.saved';
+    id: string;
+    path: string;
+    title: string;
+    /** The entry without its front matter. */
+    body: string;
+    /** The whole file. */
+    text: string;
+    /** Who made the change: `user`, an agent's name, or the background upkeep. */
+    actor: string;
+    reason: string;
+    at: string;
+}
+export interface RunEndedEvent {
+    type: 'history.run.ended';
+    runId: string;
+    sessionId: string;
+    status: string;
+    goal: string | null;
+    agentId: string | null;
+    projectId: string | null;
+    startedAt: string;
+    endedAt: string | null;
+    at: string;
+}
+export type HookEvent = EntryEvent | RunEndedEvent;
+export interface HookContext {
+    /** Calls a tool of a connected app that is on for everyone, if a person marked that tool to run without asking. */
+    call(connection: string, tool: string, args?: Record<string, unknown>): Promise<unknown>;
+    log(message: string): void;
+}
+type Handler = (event: HookEvent, context: HookContext) => unknown;
+/** What a hooks file is given: `export default function (harness) { harness.on('wiki.page.saved', …) }`. */
+export interface HookApi {
+    on(event: HookEventType, handler: Handler): void;
+}
+export interface HookTarget {
+    /** The hooks file. */
+    path: string;
+    /** A hash of the package's code, so a changed file is loaded again. */
+    hash: string;
+}
+export interface HookStatus {
+    /** The events it listens for. */
+    events: string[];
+    lastRunAt: string | null;
+    /** Why it could not be loaded, or what its last failing run threw. */
+    lastError: string | null;
+}
+export interface HooksOptions {
+    stateDir: string;
+    bus: Bus;
+    /** The hooks files that should run now: attached for everyone, and trusted. */
+    wanted: () => Promise<HookTarget[]>;
+    call: HookContext['call'];
+    /** How long one handler may take. */
+    timeoutMs?: number;
+    /** Reads a hooks file as a module. Replaced in tests, where the runner owns `import()`. */
+    importFile?: (address: string) => Promise<unknown>;
+}
+/** Which event a written file is, from where it is in the Wiki. */
+export declare function entryEvent(change: Change): EntryEvent;
+export declare class Hooks {
+    private readonly options;
+    private loaded;
+    private readonly queue;
+    private working;
+    private reloading;
+    private readonly statusPath;
+    private wiki;
+    private readonly stop;
+    constructor(options: HooksOptions);
+    /** The Wiki whose changes these hooks hear about. */
+    watch(wiki: string | null): void;
+    /** What each hooks file listens for, and how its last run went. */
+    status(): Record<string, HookStatus>;
+    private record;
+    /** Loads the hooks files that should run and drops the ones that should not. Safe to call often. */
+    reload(): Promise<void>;
+    /** Takes an event down. It is delivered afterwards, in the order events arrived. */
+    emit(event: HookEvent): void;
+    private drain;
+    private run;
+    /** Resolves when every event taken down so far was delivered. */
+    settled(): Promise<void>;
+    close(): void;
+}
+export {};

package/dist/sdk/plugins/hooks.js

@@ -0,0 +1,162 @@
+// Hooks: code a plugin gives the harness to run after something changed. A Pi extension lives
+// only while a session is open, and most memory is written outside one (a person accepts an
+// Inbox item, edits a fact, the background upkeep runs), so these are the harness's own events,
+// delivered in its own process.
+//
+// A hook is told after the fact. It cannot stop or change a write, it runs with a time limit,
+// and what it throws is recorded and shown on its plugin. It reaches outside only through
+// `ctx.call`, which the harness limits to connected-app tools a person marked to run without asking.
+import { chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { log } from "../core/bus.js";
+import { onChange } from "../core/changes.js";
+import * as frontmatter from "../core/frontmatter.js";
+import { now, readJsonOr, writeJson } from "../core/fs.js";
+export const HOOK_EVENTS = ['wiki.page.saved', 'history.run.ended'];
+// Node's own `import()`, out of reach of a bundler or a test runner that would rewrite it: a hooks
+// file is a person's file on disk, loaded as it is, and its address must reach Node unchanged.
+const importFile = new Function('address', 'return import(address)');
+/** Which event a written file is, from where it is in the Wiki. */
+export function entryEvent(change) {
+    const type = 'wiki.page.saved';
+    const parsed = frontmatter.parse(change.text);
+    const front = (parsed?.front ?? {});
+    const title = typeof front.title === 'string' ? front.title : typeof front.label === 'string' ? front.label : change.id;
+    return { type, id: change.id, path: change.path, title, body: (parsed?.body ?? change.text).trim(), text: change.text, actor: change.actor, reason: change.reason, at: now() };
+}
+export class Hooks {
+    options;
+    loaded = [];
+    queue = [];
+    working = Promise.resolve();
+    reloading = Promise.resolve();
+    statusPath;
+    wiki = null;
+    stop;
+    constructor(options) {
+        this.options = options;
+        this.statusPath = join(options.stateDir, 'plugin-hooks.json');
+        this.stop = onChange((change) => {
+            // Several harnesses can share a process; each hears only about its own Wiki.
+            if (change.wiki === this.wiki)
+                this.emit(entryEvent(change));
+        });
+    }
+    /** The Wiki whose changes these hooks hear about. */
+    watch(wiki) {
+        this.wiki = wiki;
+    }
+    /** What each hooks file listens for, and how its last run went. */
+    status() {
+        return readJsonOr(this.statusPath, {});
+    }
+    record(path, change) {
+        const all = this.status();
+        const before = all[path] ?? { events: [], lastRunAt: null, lastError: null };
+        const next = { ...before, ...change };
+        if (JSON.stringify(before) === JSON.stringify(next) && all[path])
+            return;
+        all[path] = next;
+        writeJson(this.statusPath, all);
+        chmodSync(this.statusPath, 0o600);
+        // A new failure, or a failure that cleared, is something a person looking at the plugin should see.
+        if (before.lastError !== next.lastError || before.events.join() !== next.events.join())
+            this.options.bus.emit({ type: 'plugins.changed' });
+    }
+    /** Loads the hooks files that should run and drops the ones that should not. Safe to call often. */
+    reload() {
+        this.reloading = this.reloading.then(async () => {
+            let wanted;
+            try {
+                wanted = await this.options.wanted();
+            }
+            catch (error) {
+                log('plugin hooks', error instanceof Error ? error.message : String(error));
+                return;
+            }
+            const next = [];
+            for (const target of wanted) {
+                const kept = this.loaded.find((hook) => hook.path === target.path && hook.hash === target.hash);
+                if (kept) {
+                    next.push(kept);
+                    continue;
+                }
+                const handlers = new Map();
+                try {
+                    // The hash is part of the address, so a changed file is read again and not served from the module cache.
+                    const module = (await (this.options.importFile ?? importFile)(`${pathToFileURL(target.path).href}?v=${target.hash}`));
+                    if (typeof module.default !== 'function')
+                        throw new Error('It must export a default function.');
+                    const api = {
+                        on: (event, handler) => {
+                            if (!HOOK_EVENTS.includes(event))
+                                throw new Error(`There is no event called "${String(event)}". The events are ${HOOK_EVENTS.join(', ')}.`);
+                            if (typeof handler !== 'function')
+                                throw new Error('A handler must be a function.');
+                            handlers.set(event, [...(handlers.get(event) ?? []), handler]);
+                        }
+                    };
+                    await module.default(api);
+                    next.push({ ...target, handlers });
+                    this.record(target.path, { events: [...handlers.keys()], lastError: null });
+                }
+                catch (error) {
+                    this.record(target.path, { events: [], lastError: `It could not be loaded: ${error instanceof Error ? error.message : String(error)}` });
+                }
+            }
+            this.loaded = next;
+        });
+        return this.reloading;
+    }
+    /** Takes an event down. It is delivered afterwards, in the order events arrived. */
+    emit(event) {
+        this.queue.push(event);
+        this.working = this.working.then(() => this.drain());
+    }
+    async drain() {
+        // A file can change on disk without anyone telling the harness. What is loaded is checked
+        // against what should run before it is told anything, so code that changed since it was
+        // trusted stops here. With nothing loaded there is nothing to check: a new hook arrives
+        // with a `plugins.changed` notice.
+        if (this.loaded.length)
+            await this.reload();
+        else
+            await this.reloading;
+        for (let event = this.queue.shift(); event; event = this.queue.shift()) {
+            for (const hook of this.loaded) {
+                for (const handler of hook.handlers.get(event.type) ?? [])
+                    await this.run(hook, handler, event);
+            }
+        }
+    }
+    async run(hook, handler, event) {
+        const context = { call: this.options.call, log: (message) => log(`plugin hook ${hook.path}`, String(message)) };
+        let timer;
+        try {
+            await Promise.race([
+                Promise.resolve().then(() => handler(event, context)),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error(`It took longer than ${Math.round((this.options.timeoutMs ?? 30_000) / 1000)} seconds and was left behind.`)), this.options.timeoutMs ?? 30_000);
+                })
+            ]);
+            this.record(hook.path, { lastRunAt: now(), lastError: null });
+        }
+        catch (error) {
+            this.record(hook.path, { lastRunAt: now(), lastError: `${event.type}: ${error instanceof Error ? error.message : String(error)}`.slice(0, 1000) });
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    /** Resolves when every event taken down so far was delivered. */
+    async settled() {
+        await this.reloading;
+        await this.working;
+    }
+    close() {
+        this.stop();
+        this.loaded = [];
+    }
+}

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

@@ -0,0 +1,19 @@
+import { type Found } from "./discover.js";
+import type { ContributionKind } from "./types.js";
+export { packageManifest } from "./manifest.js";
+export declare const FOUND_KINDS: Record<Found['kind'], ContributionKind>;
+/** The id of the plugin a found item is listed under. */
+export declare function pluginIdOf(item: Found): string;
+/** A found item's name and description as a person reads them. */
+export declare function describeFound(item: Found): {
+    name: string;
+    description: string | null;
+};
+export declare const contributionId: (pluginId: string, kind: ContributionKind, name: string) => string;
+/** The ids a choice about a found item is stored under: the item itself, then its plugin. */
+export declare function foundIds(item: Found): [string, string];
+/** A Markdown file's `name` and `description` frontmatter; a `SKILL.md` is named after its folder. */
+export declare function describeFile(path: string): {
+    name: string;
+    description: string;
+} | null;

package/dist/sdk/plugins/identity.js

@@ -0,0 +1,48 @@
+// Which plugin a found file belongs to, and what it is called there. The list a person sees and
+// the choice of what loads both use this, so a switch on the page names exactly what stops loading.
+import { readFileSync } from 'node:fs';
+import { basename, dirname } from 'node:path';
+import * as frontmatter from "../core/frontmatter.js";
+import { BUILTIN_PREFIX } from "./discover.js";
+import { packageManifest } from "./manifest.js";
+export { packageManifest } from "./manifest.js";
+export const FOUND_KINDS = { extension: 'code', hook: 'code', skill: 'skill', prompt: 'command', theme: 'theme', context: 'instruction' };
+/** The id of the plugin a found item is listed under. */
+export function pluginIdOf(item) {
+    if (item.origin === 'builtin')
+        return 'pi';
+    if (item.packageRoot)
+        return `package:${packageManifest(item.packageRoot).name}`;
+    return item.origin === 'home' ? 'home' : item.origin === 'project' ? 'project' : 'shared';
+}
+/** A found item's name and description as a person reads them. */
+export function describeFound(item) {
+    if (item.path.startsWith(BUILTIN_PREFIX))
+        return { name: item.path.slice(BUILTIN_PREFIX.length), description: null };
+    const file = basename(item.path);
+    if (item.kind === 'extension')
+        return { name: file.startsWith('index.') ? basename(dirname(item.path)) : file, description: null };
+    if (item.kind === 'context' || item.kind === 'theme' || item.kind === 'hook')
+        return { name: file, description: null };
+    const described = describeFile(item.path);
+    return { name: described?.name ?? file, description: described?.description ?? '' };
+}
+export const contributionId = (pluginId, kind, name) => `${pluginId}/${kind}/${name}`;
+/** The ids a choice about a found item is stored under: the item itself, then its plugin. */
+export function foundIds(item) {
+    const pluginId = pluginIdOf(item);
+    return [contributionId(pluginId, FOUND_KINDS[item.kind], describeFound(item).name), pluginId];
+}
+/** A Markdown file's `name` and `description` frontmatter; a `SKILL.md` is named after its folder. */
+export function describeFile(path) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const front = frontmatter.parse(text)?.front ?? {};
+    const fallback = basename(path) === 'SKILL.md' ? basename(dirname(path)) : basename(path).replace(/\.md$/, '');
+    return { name: typeof front.name === 'string' && front.name.trim() ? front.name.trim() : fallback, description: typeof front.description === 'string' ? front.description.trim() : '' };
+}

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

@@ -0,0 +1,20 @@
+import type { Harness } from "../harness.js";
+import { type PluginScope } from "./api.js";
+import type { Plugin } from "./types.js";
+/** A folder on this machine, or a package as Pi's settings name it. A bare name is an npm package. */
+export declare function normalizeSource(input: string): string;
+/**
+ * Installs a package for every account. It arrives switched off, and if it brings code, not
+ * trusted: nothing of it reaches a session until a person switches it on and trusts it.
+ */
+export declare function install(harness: Harness, params: PluginScope & {
+    source: string;
+}): Promise<Plugin[]>;
+/** Removes an installed package. One kept as a folder beside a person's data is moved to the trash there. */
+export declare function remove(harness: Harness, params: PluginScope & {
+    pluginId: string;
+}): Promise<Plugin[]>;
+/** Fetches a newer version of one installed package, or of all of them. Changed code waits for trust again. */
+export declare function update(harness: Harness, params: PluginScope & {
+    pluginId?: string | null;
+}): Promise<Plugin[]>;