@xingular/harness 0.1.7 → 1.0.0

package/dist/sdk/plugins/install.js

@@ -0,0 +1,110 @@
+// Installing, updating and removing a package. Pi's own package manager does the work, against
+// the settings every account shares, so the `pi` command and the harness agree on what is
+// installed. Fetching runs none of a package's code, and what was installed is switched off and
+// untrusted until a person has looked at it.
+import { existsSync, mkdirSync, renameSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, isAbsolute, join, resolve } from 'node:path';
+import { ensureSharedDir } from "../accounts/env.js";
+import { invalid, notFound } from "../core/errors.js";
+import { now } from "../core/fs.js";
+import { loadPi } from "../pi/runtime.js";
+import { ensureAdopted, list } from "./api.js";
+import * as attachments from "./attachments.js";
+import { withoutInstallScripts } from "./discover.js";
+/** A folder on this machine, or a package as Pi's settings name it. A bare name is an npm package. */
+export function normalizeSource(input) {
+    const source = input.trim();
+    if (!source)
+        throw invalid('Name a package: a folder, an npm name, or a git address.');
+    if (source.startsWith('~/'))
+        return join(process.env.HOME || homedir(), source.slice(2));
+    if (isAbsolute(source))
+        return resolve(source);
+    if (source.startsWith('./') || source.startsWith('../'))
+        throw invalid('Give the whole path of the folder.');
+    return /^(npm:|git:|https?:\/\/|ssh:\/\/|git@)/.test(source) ? source : `npm:${source}`;
+}
+async function manager(harness) {
+    const pi = await loadPi();
+    // The shared folder is where `settings.json` really is; an account's own is a link to it.
+    const agentDir = ensureSharedDir(harness.accounts.dir);
+    const settings = pi.SettingsManager.create(harness.stateDir, agentDir);
+    return { settings, packages: new pi.DefaultPackageManager({ cwd: harness.stateDir, agentDir, settingsManager: settings }) };
+}
+const changed = (harness) => harness.bus.emit({ type: 'plugins.changed' });
+/**
+ * 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 async function install(harness, params) {
+    const source = normalizeSource(params.source);
+    if (isAbsolute(source) && !(existsSync(source) && statSync(source).isDirectory()))
+        throw invalid('That folder does not exist.');
+    // What was already there is taken over as trusted before anything new arrives, never after.
+    await ensureAdopted(harness);
+    const before = new Set((await list(harness, params)).map((plugin) => plugin.id));
+    const { settings, packages } = await manager(harness);
+    if (isAbsolute(source)) {
+        // Pi would save a folder as a path relative to the settings file, and each account reads
+        // that file through a link in its own folder, where a relative path points somewhere else.
+        const named = settings.getGlobalSettings().packages ?? [];
+        if (!named.some((entry) => (typeof entry === 'string' ? entry : entry.source) === source))
+            settings.setPackages([...named, source]);
+        await settings.flush();
+    }
+    else {
+        await withoutInstallScripts(() => packages.installAndPersist(source));
+    }
+    const after = await list(harness, params);
+    const added = after.filter((plugin) => plugin.install && !before.has(plugin.id));
+    if (added.length) {
+        const choices = attachments.load(harness.env.root);
+        for (const plugin of added)
+            attachments.set(choices, [plugin.id], {}, false, true);
+        attachments.save(harness.env.root, choices);
+    }
+    changed(harness);
+    return added.length ? list(harness, params) : after;
+}
+function installed(plugins, pluginId) {
+    const plugin = plugins.find((candidate) => candidate.id === pluginId);
+    if (!plugin)
+        throw notFound('Plugin');
+    if (!plugin.install)
+        throw invalid(`${plugin.title} was not installed as a package, so it cannot be removed or updated here.`);
+    return plugin;
+}
+/** Removes an installed package. One kept as a folder beside a person's data is moved to the trash there. */
+export async function remove(harness, params) {
+    const plugin = installed(await list(harness, params), params.pluginId);
+    if (plugin.install.kind === 'folder') {
+        const trash = join(harness.env.root, 'trash', 'plugins');
+        mkdirSync(trash, { recursive: true });
+        renameSync(plugin.install.source, join(trash, `${basename(plugin.install.source)}-${now().replace(/[:.]/g, '-')}`));
+    }
+    else {
+        await (await manager(harness)).packages.removeAndPersist(plugin.install.source);
+    }
+    const choices = attachments.load(harness.env.root);
+    for (const scope of [choices.global, ...Object.values(choices.agents), ...Object.values(choices.projects)]) {
+        scope.on = scope.on.filter((id) => id !== plugin.id && !id.startsWith(`${plugin.id}/`));
+        scope.off = scope.off.filter((id) => id !== plugin.id && !id.startsWith(`${plugin.id}/`));
+    }
+    delete choices.settings[plugin.id];
+    attachments.save(harness.env.root, choices);
+    if (plugin.code)
+        harness.plugins.trust.revoke(plugin.code.hash);
+    changed(harness);
+    return list(harness, params);
+}
+/** Fetches a newer version of one installed package, or of all of them. Changed code waits for trust again. */
+export async function update(harness, params) {
+    const plugin = params.pluginId ? installed(await list(harness, params), params.pluginId) : null;
+    if (plugin?.install.kind === 'folder')
+        throw invalid(`${plugin.title} is a folder on this machine. Change its files to update it.`);
+    const { packages } = await manager(harness);
+    await withoutInstallScripts(() => packages.update(plugin?.install.source));
+    changed(harness);
+    return list(harness, params);
+}

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

@@ -0,0 +1,22 @@
+import type { HarnessEnv } from "../core/env.js";
+import type { Connection } from "../mcp/types.js";
+import type { CallerContext } from "../core/caller.js";
+import { type Launch } from "../prompt/compile.js";
+import type { Materialised } from "../variant/materialise.js";
+import type { Inventory, Plugin, PluginDescriptor } from "./types.js";
+export interface InventoryInput {
+    env: HarnessEnv;
+    context: CallerContext;
+    /** What the application adds to the prompt for this caller, as it would for a session. */
+    launch: Launch;
+    /** The tools the caller has switched on, as a session's `allow` list. */
+    tools: readonly string[];
+    /** Whether the caller gets the connected-apps tools. */
+    connections: boolean;
+    plugins: readonly Plugin[];
+    descriptors: readonly PluginDescriptor[];
+    saved: readonly Connection[];
+    /** The variant the caller runs, when it has one. */
+    variant?: Materialised | null;
+}
+export declare function inventory(input: InventoryInput): Inventory;

package/dist/sdk/plugins/inventory.js

@@ -0,0 +1,110 @@
+// What reaches one caller: every prompt section, tool, skill, connection and extension, each
+// attributed to the plugin it comes from. Anything no plugin accounts for is reported, so a new
+// source of model-visible text cannot appear without showing up here.
+import { readFileSync } from 'node:fs';
+import { charCount } from "../core/text.js";
+import { allowed } from "../mcp/connections.js";
+import { BUILT_IN_DYNAMIC, compile, toolGroups } from "../prompt/compile.js";
+import { ASK_USER } from "../tools/askUser.js";
+import { CHECKLIST_WRITE } from "../tools/checklist.js";
+import { DEFAULT_TOOL_NAMES } from "../tools/definitions.js";
+import { VARIANT_PLUGIN } from "./builtin.js";
+const size = (path) => {
+    if (!path)
+        return null;
+    try {
+        return charCount(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+};
+export function inventory(input) {
+    const { env, context, launch, descriptors } = input;
+    const items = [];
+    const unattributed = [];
+    const item = (pluginId, kind, name, delivery, chars, rest = {}) => {
+        items.push({ pluginId, contributionId: null, kind, name, delivery, chars, cut: false, ...rest });
+    };
+    const pack = compile(env, context, launch, input.variant ?? null);
+    const dynamic = new Set([...BUILT_IN_DYNAMIC.map((entry) => entry.id), ...(launch.sections ?? []).filter((section) => section.dynamic).map((section) => section.id)]);
+    let systemChars = 0;
+    let contextChars = 0;
+    for (const section of pack.sections) {
+        const delivery = dynamic.has(section.id) ? 'context' : 'system';
+        if (delivery === 'context')
+            contextChars += section.size;
+        else
+            systemChars += section.size;
+        if (section.id === 'tools') {
+            // One paragraph per tool group; each belongs to the plugin that provides the group.
+            for (const group of toolGroups(context, launch)) {
+                if (!group.guidance)
+                    continue;
+                const plugin = descriptors.find((descriptor) => descriptor.toolGroups?.includes(group.group));
+                if (!plugin)
+                    unattributed.push({ kind: 'toolGroup', id: group.group });
+                item(plugin?.id ?? '', 'instruction', `Tool guidance: ${group.group}`, delivery, charCount(group.guidance), { cut: section.cut });
+            }
+            continue;
+        }
+        const plugin = descriptors.find((descriptor) => descriptor.sections?.some((declared) => declared.id === section.id));
+        if (!plugin)
+            unattributed.push({ kind: 'section', id: section.id });
+        const name = plugin?.sections?.find((declared) => declared.id === section.id)?.name ?? section.title;
+        item(plugin?.id ?? '', 'instruction', name, delivery, section.size, { contributionId: plugin ? `${plugin.id}/instruction/${name}` : null, cut: section.cut });
+    }
+    // The variant's skills are loaded only when used; its plugins run in the tool loop.
+    const variant = input.variant ?? null;
+    if (variant) {
+        for (const rel of Object.keys(variant.files).filter((path) => /^skills\/[^/]+\/SKILL\.md$/.test(path)).sort()) {
+            const name = rel.split('/')[1];
+            item(VARIANT_PLUGIN.id, 'skill', name, 'on-demand', charCount(variant.files[rel]), { contributionId: `${VARIANT_PLUGIN.id}/skill/${name}` });
+        }
+        for (const path of variant.extensionPaths) {
+            const name = path.split('/').pop();
+            item(VARIANT_PLUGIN.id, 'code', name, 'code', size(path), { contributionId: `${VARIANT_PLUGIN.id}/code/${name}` });
+        }
+    }
+    const names = [...input.tools];
+    const extensionToolNames = new Set(input.plugins.filter((plugin) => ['project', 'package', 'shared', 'home'].includes(plugin.source)).flatMap((plugin) => plugin.contributions.filter((entry) => entry.kind === 'tool' && entry.state === 'on').map((entry) => entry.name)));
+    for (const name of [ASK_USER, CHECKLIST_WRITE, ...DEFAULT_TOOL_NAMES, ...(input.connections ? ['mcp_list_tools', 'mcp_call_tool'] : [])])
+        if (!names.includes(name))
+            names.push(name);
+    for (const name of names) {
+        if (extensionToolNames.has(name))
+            continue;
+        const plugin = descriptors.find((descriptor) => descriptor.tools?.some((tool) => tool.name === name));
+        if (!plugin)
+            unattributed.push({ kind: 'tool', id: name });
+        item(plugin?.id ?? '', 'tool', name, 'tool', null, { contributionId: plugin ? `${plugin.id}/tool/${name}` : null });
+    }
+    if (input.connections) {
+        for (const connection of input.saved.filter((candidate) => allowed(candidate, { agentId: context.agentId ?? null, projectId: context.projectId ?? null }))) {
+            item('connected-apps', 'connection', connection.name || connection.id, 'tool', null, { contributionId: `connected-apps/connection/${connection.id}` });
+        }
+    }
+    // What the harness found on disk and lets load. Pi's command's own extensions exist only in a terminal.
+    const delivered = { code: 'code', skill: 'on-demand', command: 'on-demand', instruction: 'system', theme: 'code', tool: 'tool', connection: 'tool' };
+    const terminal = context.surface === 'cli';
+    for (const plugin of input.plugins) {
+        if (!['project', 'package', 'shared', 'home', 'pi'].includes(plugin.source))
+            continue;
+        for (const found of plugin.contributions) {
+            if (found.state !== 'on' || (plugin.source === 'pi' && (found.kind !== 'code' || !terminal)) || (found.kind === 'theme' && !terminal))
+                continue;
+            item(plugin.id, found.kind, found.name, found.background ? 'background' : delivered[found.kind], ['instruction', 'skill', 'command'].includes(found.kind) ? size(found.path) : null, { contributionId: found.id });
+        }
+    }
+    // The harness's own switched-on extensions.
+    for (const plugin of input.plugins) {
+        if (plugin.source !== 'builtin')
+            continue;
+        for (const own of plugin.contributions)
+            if (own.kind === 'code' && own.state === 'on')
+                item(plugin.id, 'code', own.name, 'code', null, { contributionId: own.id });
+    }
+    item('pi', 'instruction', 'Base prompt', 'system', null);
+    const used = new Set(items.map((entry) => entry.pluginId));
+    return { plugins: input.plugins.filter((plugin) => used.has(plugin.id)), others: input.plugins.filter((plugin) => !used.has(plugin.id)), items, unattributed, systemChars, contextChars };
+}

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

@@ -0,0 +1,13 @@
+import type { ConnectorTemplate } from "./types.js";
+export interface PackageManifest {
+    name: string;
+    description: string;
+    version: string | null;
+    /** The parts it adds to, by id: `memory`, `wiki`, `history`. */
+    extends: string[];
+    /** The hooks file, inside the package, or `null` when it has none. */
+    hooks: string | null;
+    /** Data-only remote connector forms. Invalid templates are ignored; none can carry credentials. */
+    connectorTemplates: ConnectorTemplate[];
+}
+export declare function packageManifest(packageRoot: string): PackageManifest;

package/dist/sdk/plugins/manifest.js

@@ -0,0 +1,56 @@
+// What a package says about itself in its `package.json`: Pi's own fields, and under `harness`
+// which part of the harness it extends and the file of hooks the harness runs for it.
+import { basename, join } from 'node:path';
+import { z } from 'zod';
+import { readJsonOr, safeRelative } from "../core/fs.js";
+const connectorTemplateSchema = z.object({
+    id: z.string().regex(/^[a-z0-9-]+$/),
+    name: z.string().min(1).max(120),
+    description: z.string().max(500),
+    url: z.string().url().startsWith('https://'),
+    auth: z.enum(['none', 'headers', 'oauth']),
+    oauthClient: z.enum(['dynamic', 'user']).nullable(),
+    oauthScopes: z.array(z.string().max(500)).max(30),
+    docsUrl: z.string().url().startsWith('https://').nullable(),
+    fields: z.array(z.object({
+        header: z.string().regex(/^[A-Za-z0-9_-]+$/),
+        label: z.string().min(1).max(120),
+        prefix: z.string().max(100),
+        help: z.string().max(500)
+    }).strict()).max(12),
+    setup: z.array(z.string().max(1000)).max(20),
+    notice: z.string().max(1000).nullable()
+}).strict().superRefine((template, context) => {
+    const oauth = template.auth === 'oauth';
+    const headers = template.auth === 'headers';
+    if (oauth !== (template.oauthClient !== null))
+        context.addIssue({ code: 'custom', message: 'OAuth templates must state a client type and other templates must not.', path: ['oauthClient'] });
+    if (headers !== (template.fields.length > 0))
+        context.addIssue({ code: 'custom', message: 'Header templates must declare input fields and other templates must not.', path: ['fields'] });
+});
+/** A path inside the package, or `null` for one that is missing, absolute, or climbs out of it. */
+function inside(path) {
+    if (typeof path !== 'string' || !path.trim())
+        return null;
+    try {
+        return safeRelative(path.replace(/^\.\//, ''));
+    }
+    catch {
+        return null;
+    }
+}
+export function packageManifest(packageRoot) {
+    const manifest = readJsonOr(join(packageRoot, 'package.json'), {});
+    const own = (manifest.harness && typeof manifest.harness === 'object' && !Array.isArray(manifest.harness) ? manifest.harness : {});
+    return {
+        name: typeof manifest.name === 'string' && manifest.name ? manifest.name : basename(packageRoot),
+        description: typeof manifest.description === 'string' ? manifest.description : '',
+        version: typeof manifest.version === 'string' ? manifest.version : null,
+        extends: (Array.isArray(own.extends) ? own.extends : typeof own.extends === 'string' ? [own.extends] : []).filter((id) => typeof id === 'string' && !!id),
+        hooks: inside(own.hooks),
+        connectorTemplates: (Array.isArray(own.connectors) ? own.connectors : []).flatMap((value) => {
+            const parsed = connectorTemplateSchema.safeParse(value);
+            return parsed.success ? [parsed.data] : [];
+        })
+    };
+}

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

@@ -0,0 +1,104 @@
+import type { Bus } from "../core/bus.js";
+import { type Attachments, type AttachScope } from "./attachments.js";
+import { type Found, type ResolveInput, type Resolver } from "./discover.js";
+import { Trust, type ProjectCode } from "./trust.js";
+/** What one session or terminal loads besides the registry's own items. */
+export interface Loading {
+    /** Extension files and folders, in the order Pi would have loaded them. */
+    extensionPaths: string[];
+    skillPaths: string[];
+    promptPaths: string[];
+    themePaths: string[];
+    /** The `pi` command's own extensions left on, as `builtin:<name>`. Only a terminal has them. */
+    builtins: string[];
+    /** Hooks files the harness runs itself. Pi is never given them. */
+    hooks: {
+        path: string;
+        packageRoot: string;
+        hash: string;
+    }[];
+    /** Everything found, loaded or not. */
+    found: Found[];
+    /** Paths of found items a person switched off for this caller. */
+    detached: string[];
+    /** Applies the same attachment policy to resources supplied by a trusted extension. */
+    resourceAllowed?: (item: Found) => boolean;
+    /** Code the working folder brings, and whether a person trusted it. */
+    projectCode: (ProjectCode & {
+        trusted: boolean;
+    }) | null;
+    /** Each installed package that brings code, by its folder, and whether a person trusted it. */
+    packageCode: Record<string, ProjectCode & {
+        trusted: boolean;
+    }>;
+}
+/** What one loaded extension added to a session. */
+export interface Registered {
+    path: string;
+    hooks: string[];
+    tools: string[];
+    commands: string[];
+    flags: string[];
+    shortcuts: string[];
+    /** Fingerprint at observation time; stale registrations are not presented as current. */
+    hash?: string | null;
+    seenAt?: string;
+    resources?: RuntimeResource[];
+}
+export interface RuntimeResource {
+    kind: 'skill' | 'command' | 'theme';
+    name: string;
+    path: string;
+    chars: number | null;
+}
+export interface PluginsOptions {
+    stateDir: string;
+    bus: Bus;
+    resolver?: Resolver;
+    /** The choices a person made about what is switched on, or `null` while there is no data root. */
+    attachments?: () => Attachments | null;
+    /** The folder of packages kept with a person's data, or `null` while there is no data root. */
+    packagesDir?: () => string | null;
+}
+/** The package folders inside a folder: each direct child that is a folder and not hidden. */
+export declare function packageFolders(directory: string | null): string[];
+export interface LoadingInput extends ResolveInput {
+    /** Who the session is for. Something switched off for this agent or project does not load. */
+    caller?: AttachScope;
+    /** The contributions frozen for a run. When present, this snapshot governs loading. */
+    contributions?: readonly string[];
+}
+/** Which code a person trusted: the working folder's as a whole, and each installed package's. */
+export interface Trusted {
+    project: boolean;
+    /** Folders of installed packages whose code is not trusted. */
+    untrustedPackages: ReadonlySet<string>;
+}
+export declare const trustedBy: (loading: Pick<Loading, "projectCode" | "packageCode"> | null) => Trusted;
+/**
+ * Whether a found item loads: it is on in Pi's settings, and if it is code, a person trusted it.
+ * A loose file in the shared folder was put there by hand and needs no trust. Text always loads.
+ */
+export declare function loads(item: Found, trusted: Trusted): boolean;
+/**
+ * Whether a person left a found item switched on for a caller. Pi reads its instruction files
+ * itself and its command owns its built-in extensions, so neither can be switched off here.
+ */
+export declare function switchable(item: Found): boolean;
+export declare class Plugins {
+    private readonly options;
+    readonly trust: Trust;
+    private readonly resolver;
+    private readonly registeredPath;
+    constructor(options: PluginsOptions);
+    /** Finds what Pi would load in this folder, and chooses what does. */
+    loading(input: LoadingInput): Promise<Loading>;
+    /** What each extension registered the last time a session loaded it. */
+    registered(): Record<string, Registered & {
+        seenAt: string;
+    }>;
+    /** Records what a session's extensions registered, so the list can show it without loading code. */
+    loaded(extensions: readonly Registered[]): void;
+}
+/** Removes the skill links an earlier version of the harness kept in a Pi agent folder's `skills/`. */
+export declare function removeLinkedSkills(skillsDir: string): void;

package/dist/sdk/plugins/plugins.js

@@ -0,0 +1,164 @@
+// The harness decides what a Pi session loads. Pi's own discovery is switched off for sessions
+// and terminals; they receive the paths chosen here, so nothing reaches a model unlisted.
+import { chmodSync, lstatSync, readdirSync, rmSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { now, readJsonOr, writeJson } from "../core/fs.js";
+import { attached } from "./attachments.js";
+import { piResolver } from "./discover.js";
+import { foundIds, pluginIdOf } from "./identity.js";
+import { packageCode, projectCode, Trust } from "./trust.js";
+/** The package folders inside a folder: each direct child that is a folder and not hidden. */
+export function packageFolders(directory) {
+    if (!directory)
+        return [];
+    try {
+        return readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith('.')).map((entry) => join(directory, entry.name)).sort();
+    }
+    catch {
+        return [];
+    }
+}
+export const trustedBy = (loading) => ({
+    project: !!loading?.projectCode?.trusted,
+    untrustedPackages: new Set(Object.entries(loading?.packageCode ?? {}).filter(([, code]) => !code.trusted).map(([root]) => root))
+});
+/**
+ * Whether a found item loads: it is on in Pi's settings, and if it is code, a person trusted it.
+ * A loose file in the shared folder was put there by hand and needs no trust. Text always loads.
+ */
+export function loads(item, trusted) {
+    if (!item.enabled)
+        return false;
+    if (item.kind !== 'extension' && item.kind !== 'hook')
+        return true;
+    if (item.project)
+        return trusted.project;
+    return !(item.packageRoot && trusted.untrustedPackages.has(item.packageRoot));
+}
+/**
+ * Whether a person left a found item switched on for a caller. Pi reads its instruction files
+ * itself and its command owns its built-in extensions, so neither can be switched off here.
+ */
+export function switchable(item) {
+    return item.kind !== 'context' && item.origin !== 'builtin';
+}
+export class Plugins {
+    options;
+    trust;
+    resolver;
+    registeredPath;
+    constructor(options) {
+        this.options = options;
+        this.trust = new Trust(options.stateDir, options.bus);
+        this.resolver = options.resolver ?? piResolver;
+        this.registeredPath = join(options.stateDir, 'plugin-registered.json');
+    }
+    /** Finds what Pi would load in this folder, and chooses what does. */
+    async loading(input) {
+        // Links an earlier version put in the shared skills folder would be found as skills again.
+        removeLinkedSkills(join(input.agentDir, 'skills'));
+        const found = await this.resolver({ ...input, packages: packageFolders(this.options.packagesDir?.() ?? null) });
+        const code = projectCode(found, input.cwd);
+        const packages = packageCode(found);
+        // Packages that loaded before trust was asked per package keep loading: they are taken over once.
+        if (!this.trust.adopted)
+            this.trust.adopt([...packages].map(([folder, packaged]) => ({ code: packaged, folder })));
+        const trustedHashes = new Set(this.trust.list().map((record) => record.hash));
+        const projectCodeState = code ? { ...code, trusted: trustedHashes.has(code.hash) } : null;
+        const packageCodeState = Object.fromEntries([...packages].map(([folder, packaged]) => [folder, { ...packaged, trusted: trustedHashes.has(packaged.hash) }]));
+        const trusted = trustedBy({ projectCode: projectCodeState, packageCode: packageCodeState });
+        const choices = this.options.attachments?.() ?? null;
+        const off = (item) => {
+            if (!choices || !switchable(item))
+                return false;
+            // A hook runs for everyone or not at all, so only its plugin's switch for everyone counts.
+            if (item.kind === 'hook')
+                return !attached(choices, [pluginIdOf(item)], {}, true);
+            return !attached(choices, foundIds(item), input.caller ?? {}, true);
+        };
+        const allowed = (item) => input.contributions === undefined
+            ? !off(item)
+            : input.contributions.includes(foundIds(item)[0]);
+        const detached = found.filter((item) => !allowed(item)).map((item) => item.path);
+        const chosen = found.filter((item) => loads(item, trusted) && allowed(item));
+        const paths = (kind, builtin) => chosen.filter((item) => item.kind === kind && (item.origin === 'builtin') === builtin).map((item) => item.path);
+        return {
+            extensionPaths: paths('extension', false),
+            skillPaths: paths('skill', false),
+            promptPaths: paths('prompt', false),
+            themePaths: paths('theme', false),
+            builtins: paths('extension', true),
+            hooks: chosen.filter((item) => item.kind === 'hook' && item.packageRoot).map((item) => ({ path: item.path, packageRoot: item.packageRoot, hash: packageCodeState[item.packageRoot]?.hash ?? '' })),
+            found,
+            detached,
+            resourceAllowed: allowed,
+            projectCode: projectCodeState,
+            packageCode: packageCodeState
+        };
+    }
+    /** What each extension registered the last time a session loaded it. */
+    registered() {
+        return readJsonOr(this.registeredPath, {});
+    }
+    /** Records what a session's extensions registered, so the list can show it without loading code. */
+    loaded(extensions) {
+        if (!extensions.length)
+            return;
+        const stored = this.registered();
+        let changed = false;
+        for (const extension of extensions) {
+            const { seenAt: _seenAt, ...before } = stored[extension.path] ?? {};
+            if (JSON.stringify(before) === JSON.stringify(extension))
+                continue;
+            stored[extension.path] = { ...extension, seenAt: now() };
+            changed = true;
+        }
+        if (!changed)
+            return;
+        writeJson(this.registeredPath, stored);
+        chmodSync(this.registeredPath, 0o600);
+        this.options.bus.emit({ type: 'plugins.changed' });
+    }
+}
+// Prefix of the entries an earlier version of the harness linked into a Pi agent folder's `skills/`.
+const LINKED_SKILL_PREFIX = 'agentx-';
+function isLinkedSkill(path) {
+    let meta;
+    try {
+        meta = lstatSync(path);
+    }
+    catch {
+        return false;
+    }
+    if (meta.isSymbolicLink())
+        return true;
+    if (!meta.isDirectory())
+        return false;
+    // A single-file skill was linked as `agentx-<name>/SKILL.md` inside a folder the harness made.
+    try {
+        const entries = readdirSync(path);
+        return entries.length === 1 && entries[0] === 'SKILL.md' && lstatSync(join(path, 'SKILL.md')).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/** Removes the skill links an earlier version of the harness kept in a Pi agent folder's `skills/`. */
+export function removeLinkedSkills(skillsDir) {
+    let names;
+    try {
+        names = readdirSync(skillsDir);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        const path = join(skillsDir, name);
+        if (!name.startsWith(LINKED_SKILL_PREFIX) || !isLinkedSkill(path))
+            continue;
+        if (lstatSync(path).isSymbolicLink())
+            unlinkSync(path);
+        else
+            rmSync(path, { recursive: true, force: true });
+    }
+}

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

@@ -0,0 +1,9 @@
+import type * as Pi from '@earendil-works/pi-coding-agent';
+import type { Found } from "./discover.js";
+import type { Loading, Registered, RuntimeResource } from "./plugins.js";
+export declare function runtimeOwner(loading: Loading, path: string): Found | undefined;
+export declare function registrationHash(loading: Loading, path: string): string | null;
+/** A discovered resource has the same identity for its switch, catalogue and load decision. */
+export declare function resourceOf(owner: Found, kind: 'skill' | 'prompt' | 'theme', path: string): RuntimeResource;
+/** Wrap each handler separately so identical extension basenames never lose their owner. */
+export declare function observeResources(pi: typeof Pi, loader: Pi.DefaultResourceLoader, loading: Loading, records: Registered[], publish: () => void): void;