@xingular/harness 0.1.7 → 1.1.1

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;

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/trust.d.ts

@@ -0,0 +1,44 @@
+import type { Bus } from "../core/bus.js";
+import type { Found } from "./discover.js";
+export interface ProjectCode {
+    /** SHA-256 over every file's name and contents. */
+    hash: string;
+    /** The files, named from the working folder where they are inside it. */
+    files: string[];
+}
+/** The code the working folder brings, or `null` when it brings none. */
+export declare function projectCode(found: readonly Found[], cwd: string): ProjectCode | null;
+/**
+ * Each package a person installed that brings code, by its folder: the whole package is hashed,
+ * so a changed skill or manifest asks again as well. A working folder's packages are part of
+ * `projectCode`.
+ */
+export declare function packageCode(found: readonly Found[]): Map<string, ProjectCode>;
+export interface TrustRecord {
+    hash: string;
+    /** The working folder it was trusted in. */
+    folder: string;
+    files: string[];
+    trustedAt: string;
+}
+export declare class Trust {
+    private readonly bus;
+    private readonly path;
+    constructor(stateDir: string, bus: Bus);
+    private read;
+    list(): TrustRecord[];
+    /** Whether the packages that loaded before trust was asked per package were taken over as trusted. */
+    get adopted(): boolean;
+    /**
+     * Trusts the packages present the first time this runs, so nothing that loaded before stops.
+     * It happens once; a package installed later, or one of these after a change, waits for a person.
+     */
+    adopt(codes: readonly {
+        code: ProjectCode;
+        folder: string;
+    }[]): void;
+    has(hash: string): boolean;
+    private save;
+    grant(code: ProjectCode, folder: string): void;
+    revoke(hash: string): void;
+}

package/dist/sdk/plugins/trust.js

@@ -0,0 +1,120 @@
+// Code a person did not write into the shared folder by hand loads only after they trusted it:
+// a working folder's own (its `.pi/extensions`, or a package its settings name), and every
+// installed package. Trust belongs to the code, not the folder: it is a hash of the files, so a
+// copy of the same code elsewhere is trusted too and a changed file asks again.
+import { createHash } from 'node:crypto';
+import { chmodSync, lstatSync, readdirSync, readFileSync } from 'node:fs';
+import { basename, dirname, join, relative, sep } from 'node:path';
+import { now, readJsonOr, writeJson } from "../core/fs.js";
+import { compareText } from "../core/text.js";
+// Dependencies and version control are left out: the hash says whether the code a person
+// read has changed, and is not a seal on everything that code can import.
+const SKIPPED = new Set(['node_modules', '.git']);
+const MAX_FILES = 5000;
+function walk(path, into) {
+    if (into.length >= MAX_FILES)
+        return;
+    let meta;
+    try {
+        meta = lstatSync(path);
+    }
+    catch {
+        return;
+    }
+    if (meta.isSymbolicLink())
+        return;
+    if (meta.isFile()) {
+        into.push(path);
+        return;
+    }
+    if (!meta.isDirectory())
+        return;
+    for (const name of readdirSync(path).sort(compareText))
+        if (!SKIPPED.has(name))
+            walk(join(path, name), into);
+}
+/** The folder or file that holds one extension: its package, its own folder, or the file. */
+const unit = (item) => item.packageRoot ?? (basename(item.path).startsWith('index.') ? dirname(item.path) : item.path);
+/** A hash over the files of some folders and files, each named from `base` where it is inside it. */
+function hashOf(units, base) {
+    const paths = [];
+    for (const path of [...units].sort(compareText))
+        walk(path, paths);
+    const name = (path) => {
+        const within = relative(base, path);
+        return within && !within.startsWith('..') ? within.split(sep).join('/') : path;
+    };
+    const hash = createHash('sha256');
+    const files = [];
+    for (const path of [...new Set(paths)].sort(compareText)) {
+        let contents;
+        try {
+            contents = readFileSync(path);
+        }
+        catch {
+            continue;
+        }
+        files.push(name(path));
+        hash.update(`${name(path)}\0${contents.length}\0`).update(contents);
+    }
+    return { hash: hash.digest('hex'), files };
+}
+/** The code the working folder brings, or `null` when it brings none. */
+export function projectCode(found, cwd) {
+    const units = [...new Set(found.filter((item) => item.project && item.kind === 'extension' && item.enabled).map(unit))];
+    return units.length ? hashOf(units, cwd) : null;
+}
+/**
+ * Each package a person installed that brings code, by its folder: the whole package is hashed,
+ * so a changed skill or manifest asks again as well. A working folder's packages are part of
+ * `projectCode`.
+ */
+export function packageCode(found) {
+    const roots = [...new Set(found.filter((item) => !item.project && (item.kind === 'extension' || item.kind === 'hook') && item.packageRoot).map((item) => item.packageRoot))];
+    return new Map(roots.map((root) => [root, hashOf([root], root)]));
+}
+export class Trust {
+    bus;
+    path;
+    constructor(stateDir, bus) {
+        this.bus = bus;
+        this.path = join(stateDir, 'plugin-trust.json');
+    }
+    read() {
+        return readJsonOr(this.path, {});
+    }
+    list() {
+        const stored = this.read();
+        return Array.isArray(stored.trusted) ? stored.trusted.filter((record) => typeof record?.hash === 'string') : [];
+    }
+    /** Whether the packages that loaded before trust was asked per package were taken over as trusted. */
+    get adopted() {
+        return this.read().adopted === true;
+    }
+    /**
+     * Trusts the packages present the first time this runs, so nothing that loaded before stops.
+     * It happens once; a package installed later, or one of these after a change, waits for a person.
+     */
+    adopt(codes) {
+        const records = this.list();
+        for (const { code, folder } of codes)
+            if (!records.some((record) => record.hash === code.hash))
+                records.push({ hash: code.hash, folder, files: code.files, trustedAt: now() });
+        writeJson(this.path, { trusted: records, adopted: true });
+        chmodSync(this.path, 0o600);
+    }
+    has(hash) {
+        return this.list().some((record) => record.hash === hash);
+    }
+    save(records) {
+        writeJson(this.path, { trusted: records, ...(this.adopted ? { adopted: true } : {}) });
+        chmodSync(this.path, 0o600);
+        this.bus.emit({ type: 'plugins.changed' });
+    }
+    grant(code, folder) {
+        this.save([...this.list().filter((record) => record.hash !== code.hash), { hash: code.hash, folder, files: code.files, trustedAt: now() }]);
+    }
+    revoke(hash) {
+        this.save(this.list().filter((record) => record.hash !== hash));
+    }
+}