@xingular/harness 2.0.0 → 2.0.1-unstable

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

@@ -0,0 +1,21 @@
+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[];
+    /** Stable terminal command namespace, or `null` to use the normalized package name. */
+    commandPrefix: string | null;
+    /** A prompt template name exposed only at the package namespace root. */
+    defaultPrompt: string | null;
+    /** The hooks file, inside the package, or `null` when it has none. */
+    hooks: string | null;
+    /** The folder of subagent profiles, inside the package. `agents` unless the manifest names another. */
+    agents: string;
+    /** Skill folders a foreign manifest declares, relative to the package root. */
+    skills: string[];
+    /** 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,94 @@
+// What a package says about itself in its `package.json`: Pi's own fields, and under `harness`
+// which part of the harness it extends, its command namespace, the file of hooks it runs and the
+// folder of subagent profiles it brings. A package written for other agent harnesses may have no
+// `package.json`; its `plugin.json` then names and describes 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(/^\.\//, '').replace(/\/+$/, ''));
+    }
+    catch {
+        return null;
+    }
+}
+/** The plugin manifests other agent harnesses read, in the order they are tried. */
+const PLUGIN_MANIFESTS = ['plugin.json', '.claude-plugin/plugin.json', '.codex-plugin/plugin.json'];
+const text = (value) => (typeof value === 'string' && value.trim() ? value.trim() : null);
+function pluginJson(packageRoot) {
+    for (const file of PLUGIN_MANIFESTS) {
+        const found = readJsonOr(join(packageRoot, file), null);
+        if (found && typeof found === 'object' && !Array.isArray(found))
+            return found;
+    }
+    return {};
+}
+/**
+ * The skill folders a foreign plugin manifest declares. Pi reads only a package's own `skills`
+ * folder and its `package.json` manifest, so a Claude- or Codex-layout package otherwise installs
+ * and contributes nothing.
+ */
+function declaredSkills(packageRoot) {
+    for (const file of PLUGIN_MANIFESTS) {
+        const found = readJsonOr(join(packageRoot, file), {});
+        const listed = typeof found.skills === 'string' ? [found.skills] : Array.isArray(found.skills) ? found.skills : [];
+        const skills = listed.flatMap((entry) => {
+            const path = inside(entry);
+            return path ? [path] : [];
+        });
+        if (skills.length)
+            return skills;
+    }
+    return [];
+}
+export function packageManifest(packageRoot) {
+    const manifest = readJsonOr(join(packageRoot, 'package.json'), {});
+    // Only a package without a name of its own is described by its plugin.json.
+    const plugin = text(manifest.name) ? {} : pluginJson(packageRoot);
+    const own = (manifest.harness && typeof manifest.harness === 'object' && !Array.isArray(manifest.harness) ? manifest.harness : {});
+    const pluginName = text(plugin.name);
+    return {
+        name: text(manifest.name) ?? (pluginName && /^[a-z0-9][a-z0-9._-]*$/i.test(pluginName) ? pluginName : basename(packageRoot)),
+        description: text(manifest.description) ?? text(plugin.description) ?? '',
+        version: text(manifest.version) ?? text(plugin.version),
+        extends: (Array.isArray(own.extends) ? own.extends : typeof own.extends === 'string' ? [own.extends] : []).filter((id) => typeof id === 'string' && !!id),
+        commandPrefix: typeof own.commandPrefix === 'string' && /^[a-z][a-z0-9-]*$/i.test(own.commandPrefix) && !['plugin', 'skill'].includes(own.commandPrefix.toLowerCase()) ? own.commandPrefix.toLowerCase() : null,
+        defaultPrompt: typeof own.defaultPrompt === 'string' && /^[a-z][a-z0-9-]*$/.test(own.defaultPrompt) ? own.defaultPrompt : null,
+        hooks: inside(own.hooks),
+        agents: inside(own.agents) ?? 'agents',
+        skills: declaredSkills(packageRoot),
+        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,106 @@
+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[];
+    /** Subagent profile files packages bring. The harness reads them; Pi is never given them. */
+    profilePaths: 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,165 @@
+// 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),
+            profilePaths: paths('agent', 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/proposals.d.ts

@@ -0,0 +1,17 @@
+import type { Harness } from "../harness.js";
+export interface Proposal {
+    id: string;
+    name: string;
+    description: string;
+    files: Record<string, string>;
+    manifest: string;
+    hash: string;
+    createdAt: string;
+    status: 'pending' | 'accepted' | 'rejected';
+    decidedAt?: string;
+}
+export declare function create(root: string, name: unknown, description: unknown, files: unknown): Proposal;
+export declare function preview(root: string, id: string): Proposal;
+export declare function list(root: string): Proposal[];
+export declare function reject(root: string, id: string, hash: string): Proposal;
+export declare function accept(harness: Harness, id: string, hash: string): Promise<Proposal>;

package/dist/sdk/plugins/proposals.js

@@ -0,0 +1,147 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdirSync, readdirSync, renameSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { invalid, notFound } from "../core/errors.js";
+import * as frontmatter from "../core/frontmatter.js";
+import { now, readJson, safeId, safeRelative, writeJson } from "../core/fs.js";
+import { ensureAdopted, list as listPlugins } from "./api.js";
+import * as attachments from "./attachments.js";
+import { packageCode } from "./trust.js";
+const MAX_FILES = 100;
+const MAX_FILE_BYTES = 256 * 1024;
+const MAX_TOTAL_BYTES = 1024 * 1024;
+const dir = (root) => join(root, 'plugin-proposals');
+const pathOf = (root, id) => join(dir(root), `${safeId(id)}.json`);
+function validate(name, description, input) {
+    if (typeof name !== 'string' || !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(name))
+        throw invalid('Plugin name must be lowercase letters, digits, underscores or hyphens.');
+    if (typeof description !== 'string' || !description.trim() || Buffer.byteLength(description, 'utf8') > 4096 || /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(description))
+        throw invalid('Description must be non-empty valid text of at most 4096 bytes.');
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw invalid('Files must be a path to text object.');
+    const entries = Object.entries(input);
+    if (!entries.length || entries.length > MAX_FILES)
+        throw invalid('A proposal must contain between 1 and 100 files.');
+    const files = Object.create(null);
+    let total = 0;
+    for (const [path, content] of entries) {
+        if (typeof content !== 'string' || /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(content))
+            throw invalid('Each file must be valid UTF-8 text.');
+        if (path.includes('\\') || path.length > 240 || /[\x00-\x1f\x7f]/.test(path) || safeRelative(path) !== path || path.split('/').some((part) => part === 'node_modules' || part === '.git'))
+            throw invalid('Invalid proposal file path.');
+        if (!/^(?:README\.md|extensions\/[A-Za-z0-9_./-]+\.(?:ts|js|mjs)|skills\/[A-Za-z0-9_./-]+\.md|prompts\/[A-Za-z0-9_./-]+\.md|agents\/[A-Za-z0-9_./-]+\.md|themes\/[A-Za-z0-9_./-]+\.json)$/.test(path))
+            throw invalid('Unsupported proposal file type or location.');
+        if (path.startsWith('skills/') && path.endsWith('/SKILL.md')) {
+            if (!/^skills\/[A-Za-z0-9_-]+\/SKILL\.md$/.test(path))
+                throw invalid('Skill files must be in skills/<name>/SKILL.md.');
+            const front = frontmatter.parse(content)?.front;
+            if (front?.name !== path.split('/')[1] || typeof front.description !== 'string' || !front.description.trim())
+                throw invalid('Skill frontmatter needs a matching name and a non-empty description.');
+        }
+        const bytes = Buffer.byteLength(content, 'utf8');
+        if (bytes > MAX_FILE_BYTES || (total += bytes) > MAX_TOTAL_BYTES)
+            throw invalid('Proposal files exceed the size limit.');
+        files[path] = content;
+    }
+    for (const path of Object.keys(files))
+        if (Object.keys(files).some((other) => other.startsWith(`${path}/`)))
+            throw invalid('A file cannot also be a directory.');
+    const manifest = `${JSON.stringify({ name, version: '1.0.0', description }, null, 2)}\n`;
+    const hash = createHash('sha256').update(JSON.stringify([name, description, manifest, Object.entries(files).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)])).digest('hex');
+    return { name, description, files, manifest, hash };
+}
+export function create(root, name, description, files) {
+    const valid = validate(name, description, files);
+    const proposal = { id: randomUUID(), ...valid, createdAt: now(), status: 'pending' };
+    writeJson(pathOf(root, proposal.id), proposal);
+    return proposal;
+}
+export function preview(root, id) {
+    const proposal = readJson(pathOf(root, id));
+    if (!proposal)
+        throw notFound('Proposal');
+    const valid = validate(proposal.name, proposal.description, proposal.files);
+    if (proposal.id !== id || !['pending', 'accepted', 'rejected'].includes(proposal.status))
+        throw invalid('Invalid stored proposal.');
+    return { ...proposal, ...valid };
+}
+export function list(root) {
+    let names;
+    try {
+        names = readdirSync(dir(root));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    return names.filter((name) => /^[a-f0-9-]+\.json$/.test(name)).sort().map((name) => preview(root, name.slice(0, -5)));
+}
+function reviewed(proposal, hash) {
+    if (proposal.status !== 'pending')
+        throw invalid('Proposal is no longer pending.');
+    if (!/^[a-f0-9]{64}$/.test(hash) || proposal.hash !== hash)
+        throw invalid('Stale proposal review; preview it again.');
+}
+export function reject(root, id, hash) {
+    const proposal = preview(root, id);
+    reviewed(proposal, hash);
+    const rejected = { ...proposal, status: 'rejected', decidedAt: now() };
+    writeJson(pathOf(root, id), rejected);
+    return rejected;
+}
+export async function accept(harness, id, hash) {
+    const root = harness.env.root;
+    const initial = preview(root, id);
+    reviewed(initial, hash);
+    await ensureAdopted(harness);
+    const existing = await listPlugins(harness, {});
+    const proposal = preview(root, id);
+    reviewed(proposal, hash);
+    const pluginId = `package:${proposal.name}`;
+    if (existing.some((plugin) => plugin.id === pluginId))
+        throw invalid('A plugin with this name already exists.');
+    const parent = join(root, 'plugins');
+    const destination = join(parent, proposal.name);
+    mkdirSync(parent, { recursive: true });
+    const stage = join(parent, `.proposal-${randomUUID()}`);
+    mkdirSync(stage);
+    let reserved = false;
+    try {
+        for (const [path, content] of Object.entries(proposal.files)) {
+            const target = join(stage, path);
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, content, { flag: 'wx' });
+        }
+        writeFileSync(join(stage, 'package.json'), proposal.manifest, { flag: 'wx' });
+        const found = { kind: 'extension', path: stage, origin: 'package', project: false, packageRoot: stage, source: stage, enabled: true };
+        const code = packageCode([found]).get(stage);
+        if (harness.plugins.trust.has(code.hash))
+            throw invalid('Identical package code is already trusted; change it before accepting.');
+        // Reserve the destination exclusively. Renaming over our empty directory publishes the whole package.
+        mkdirSync(destination);
+        reserved = true;
+        const choices = attachments.load(root);
+        for (const scope of [choices.global, ...Object.values(choices.agents), ...Object.values(choices.projects)]) {
+            scope.on = scope.on.filter((entry) => entry !== pluginId && !entry.startsWith(`${pluginId}/`));
+            scope.off = scope.off.filter((entry) => entry !== pluginId && !entry.startsWith(`${pluginId}/`));
+        }
+        attachments.set(choices, [pluginId], {}, false, true);
+        attachments.save(root, choices);
+        renameSync(stage, destination);
+        reserved = false;
+        const accepted = { ...proposal, status: 'accepted', decidedAt: now() };
+        writeJson(pathOf(root, id), accepted);
+        harness.bus.emit({ type: 'plugins.changed' });
+        return accepted;
+    }
+    finally {
+        rmSync(stage, { recursive: true, force: true });
+        if (reserved) {
+            try {
+                rmdirSync(destination);
+            }
+            catch { /* Do not remove another writer's files. */ }
+        }
+    }
+}

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;

package/dist/sdk/plugins/runtime.js

@@ -0,0 +1,95 @@
+// Observe Pi's structured resource discovery without running code while the catalogue is read.
+import { createHash } from 'node:crypto';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { charCount } from "../core/text.js";
+import { FOUND_KINDS, describeFound } from "./identity.js";
+export function runtimeOwner(loading, path) {
+    return loading.found.find((item) => item.kind === 'extension' && (item.path === path || path.startsWith(`${item.path}/`)));
+}
+export function registrationHash(loading, path) {
+    const owner = runtimeOwner(loading, path);
+    if (owner?.project)
+        return loading.projectCode?.hash ?? null;
+    if (owner?.packageRoot)
+        return loading.packageCode[owner.packageRoot]?.hash ?? null;
+    try {
+        return createHash('sha256').update(readFileSync(path)).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+/** A discovered resource has the same identity for its switch, catalogue and load decision. */
+export function resourceOf(owner, kind, path) {
+    const found = { ...owner, kind, path };
+    const described = describeFound(found);
+    let chars = null;
+    try {
+        chars = charCount(readFileSync(path, 'utf8'));
+    }
+    catch { /* Missing files remain observable. */ }
+    return { kind: FOUND_KINDS[kind], name: described.name, path, chars };
+}
+/** Wrap each handler separately so identical extension basenames never lose their owner. */
+export function observeResources(pi, loader, loading, records, publish) {
+    for (const extension of loader.getExtensions().extensions) {
+        if (extension.hidden)
+            continue;
+        const path = extension.resolvedPath || extension.path;
+        const owner = runtimeOwner(loading, path);
+        const record = records.find((entry) => entry.path === path);
+        if (!owner || !record)
+            continue;
+        const handlers = extension.handlers.get('resources_discover');
+        if (!handlers)
+            continue;
+        const observations = new Map();
+        extension.handlers.set('resources_discover', handlers.map((handler, index) => async (event, context) => {
+            const result = await handler(event, context);
+            if (!result) {
+                observations.delete(index);
+                record.resources = [...observations.values()].flat();
+                publish();
+                return result;
+            }
+            const collected = [];
+            const allowed = (kind, resourcePath) => {
+                const resource = resourceOf(owner, kind, resourcePath);
+                collected.push(resource);
+                return loading.resourceAllowed?.({ ...owner, kind, path: resourcePath }) !== false;
+            };
+            const absolute = (entry) => resolve(dirname(path), entry);
+            const skills = pi.loadSkills({ cwd: dirname(path), agentDir: dirname(path), includeDefaults: false, skillPaths: (result.skillPaths ?? []).map(absolute) }).skills;
+            const scanner = new pi.DefaultResourceLoader({ cwd: dirname(path), agentDir: dirname(path), settingsManager: pi.SettingsManager.inMemory({}), noExtensions: true, noSkills: true, noThemes: true, noContextFiles: true, noPromptTemplates: true, additionalPromptTemplatePaths: (result.promptPaths ?? []).map(absolute) });
+            await scanner.reload();
+            const prompts = scanner.getPrompts().prompts;
+            const themes = (result.themePaths ?? []).map(absolute).flatMap((theme) => {
+                try {
+                    if (statSync(theme).isDirectory())
+                        return readdirSync(theme).filter((name) => {
+                            if (!name.endsWith('.json'))
+                                return false;
+                            try {
+                                return statSync(resolve(theme, name)).isFile();
+                            }
+                            catch {
+                                return false;
+                            }
+                        }).map((name) => resolve(theme, name));
+                }
+                catch { /* Preserve missing paths for Pi's diagnostics. */ }
+                return [theme];
+            });
+            const filtered = {
+                skillPaths: skills.filter((skill) => allowed('skill', skill.filePath)).map((skill) => skill.filePath),
+                promptPaths: prompts.filter((prompt) => allowed('prompt', prompt.filePath)).map((prompt) => prompt.filePath),
+                themePaths: themes.filter((theme) => allowed('theme', theme))
+            };
+            observations.set(index, collected);
+            record.resources = [...new Map([...observations.values()].flat().map((entry) => [`${entry.kind}:${entry.path}`, entry])).values()];
+            publish();
+            return filtered;
+        }));
+    }
+}

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

@@ -0,0 +1,5 @@
+import type { Plugin, PluginSurfaces } from "./types.js";
+/** A short badge for a list row: `better in the app`, or nothing. */
+export declare function surfaceBadge(surfaces: PluginSurfaces | null | undefined): string;
+/** The plugin's description, followed by what the host adds and what the terminal does instead. */
+export declare function describePlugin(plugin: Pick<Plugin, 'description' | 'surfaces'>): string;