@xingular/harness 0.1.7 → 1.1.1

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[]>;

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] : [];
+        })
+    };
+}