@xingular/harness 0.1.7 → 1.1.1

package/dist/sdk/plugins/cli.js

@@ -0,0 +1,188 @@
+// `xagent plugins …`: plugin control for a person using the harness without an
+// application. It runs outside any session, as the person who typed it, and acts directly.
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { DEFAULT_PRODUCT_NAME } from "../core/env.js";
+import { Harness } from "../harness.js";
+import * as api from "./api.js";
+import * as install from "./install.js";
+export const PLUGINS_USAGE = `Usage: xagent plugins <command> [options]
+
+  list                         Every plugin and whether it is on
+  show <plugin id>             One plugin: what it brings, where it is on, its code
+  install <source>             A folder, an npm name, or a git address. It arrives off and untrusted
+  remove <plugin id>           Remove a plugin you installed
+  update [plugin id]           Fetch a newer version of one installed plugin, or of all
+  attach <id>                  Switch a plugin, or one thing it brings, on
+  detach <id>                  Switch it off
+  trust <plugin id> [--yes]    Show the files of its code, then trust them
+  untrust <plugin id>          Stop trusting its code
+
+Options:
+  --data <dir>       Data directory (default: ~/.xingular-harness/data)
+  --state <dir>      State directory (default: ~/.xingular-harness/state)
+  --cwd <dir>        Also list what this working folder brings
+  --project <id>     attach/detach for one project instead of everywhere
+  --agent <id>       attach/detach for one agent instead of everywhere
+`;
+function parse(argv) {
+    const positional = [];
+    const values = {};
+    const switches = new Set();
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (!arg.startsWith('--'))
+            positional.push(arg);
+        else if (arg === '--yes')
+            switches.add('yes');
+        else if (index + 1 < argv.length) {
+            values[arg.slice(2)] = argv[index + 1];
+            index += 1;
+        }
+        else
+            throw new Error(`${arg} needs a value.`);
+    }
+    return { positional, values, switches };
+}
+const stateOf = (plugin) => {
+    if (plugin.required)
+        return 'required';
+    if (plugin.trust === 'untrusted')
+        return plugin.attachment && !plugin.attachment.global ? 'off, code not trusted' : 'code not trusted';
+    if (plugin.attachment)
+        return plugin.attachment.global ? 'on' : 'off';
+    const on = plugin.contributions.filter((entry) => entry.state === 'on').length;
+    return `${on} of ${plugin.contributions.length} on`;
+};
+function describe(plugin) {
+    const lines = [`${plugin.title} (${plugin.id})`, `  ${plugin.description || 'No description.'}`, `  Source: ${plugin.source}${plugin.version ? ` ${plugin.version}` : ''}${plugin.path ? ` · ${plugin.path}` : ''}`, `  State: ${stateOf(plugin)}`];
+    if (plugin.extends.length)
+        lines.push(`  Extends: ${plugin.extends.join(', ')}`);
+    if (plugin.code)
+        lines.push(`  Code (${plugin.trust}), fingerprint ${plugin.code.hash.slice(0, 12)}:`, ...plugin.code.files.map((file) => `    ${file}`));
+    for (const entry of plugin.contributions)
+        lines.push(`  ${entry.state === 'on' ? '●' : '○'} ${entry.kind} ${entry.name} (${entry.id})${entry.scope ? ` · ${entry.scope}` : ''}${entry.problem ? ` · last run failed: ${entry.problem}` : ''}`);
+    return lines.join('\n');
+}
+export async function runPluginsCli(argv, dependencies = {}) {
+    const write = dependencies.write ?? ((text) => void process.stdout.write(text));
+    let parsed;
+    try {
+        parsed = parse(argv);
+    }
+    catch (error) {
+        write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 2;
+    }
+    const [command, target] = parsed.positional;
+    if (!command || command === 'help') {
+        write(PLUGINS_USAGE);
+        return command ? 0 : 2;
+    }
+    const base = dependencies.cwd ?? process.cwd();
+    const root = join(dependencies.home ?? homedir(), '.xingular-harness');
+    const options = { dataRoot: parsed.values.data ? resolve(base, parsed.values.data) : join(root, 'data'), stateDir: parsed.values.state ? resolve(base, parsed.values.state) : join(root, 'state'), productName: DEFAULT_PRODUCT_NAME };
+    // Built without opening the data root: a plugin command must not settle runs or migrate a Wiki
+    // that another process may be using.
+    const harness = dependencies.createHarness ? dependencies.createHarness(options) : new Harness(options);
+    const scope = { cwd: parsed.values.cwd ? resolve(base, parsed.values.cwd) : null };
+    const need = (what) => {
+        if (!target)
+            throw new Error(`${command} needs ${what}.`);
+        return target;
+    };
+    const find = async (id) => {
+        const plugin = (await api.list(harness, scope)).find((candidate) => candidate.id === id);
+        if (!plugin)
+            throw new Error(`There is no plugin with the id "${id}". Run "plugins list" to see the ids.`);
+        return plugin;
+    };
+    try {
+        switch (command) {
+            case 'list': {
+                const plugins = await api.list(harness, scope);
+                const width = Math.max(...plugins.map((plugin) => plugin.id.length));
+                write(`${plugins.map((plugin) => `${plugin.id.padEnd(width)}  ${stateOf(plugin).padEnd(22)}  ${plugin.title}`).join('\n')}\n`);
+                return 0;
+            }
+            case 'show':
+                write(`${describe(await find(need('a plugin id')))}\n`);
+                return 0;
+            case 'install': {
+                const before = new Set((await api.list(harness, scope)).map((plugin) => plugin.id));
+                const added = (await install.install(harness, { ...scope, source: need('a folder, an npm name, or a git address') })).filter((plugin) => !before.has(plugin.id));
+                write(added.length ? `${added.map(describe).join('\n\n')}\n\nInstalled, switched off. Switch it on with "plugins attach <id>"${added.some((plugin) => plugin.code) ? ' and trust its code with "plugins trust <id>"' : ''}.\n` : 'Nothing new was installed.\n');
+                return 0;
+            }
+            case 'remove':
+                await install.remove(harness, { ...scope, pluginId: need('a plugin id') });
+                write(`Removed ${target}.\n`);
+                return 0;
+            case 'update':
+                await install.update(harness, { ...scope, pluginId: target ?? null });
+                write(target ? `Updated ${target}. If its code changed, trust it again.\n` : 'Updated the installed plugins. Any whose code changed needs trust again.\n');
+                return 0;
+            case 'attach':
+            case 'detach': {
+                const where = parsed.values.agent ? { agentId: parsed.values.agent } : parsed.values.project ? { projectId: parsed.values.project } : {};
+                await api.attach(harness, { ...scope, id: need('a plugin or contribution id'), scope: where }, command === 'attach');
+                write(`${target} is ${command === 'attach' ? 'on' : 'off'} ${parsed.values.agent ? `for agent ${parsed.values.agent}` : parsed.values.project ? `for project ${parsed.values.project}` : 'everywhere'}. It applies from the next session start.\n`);
+                return 0;
+            }
+            case 'trust': {
+                const plugin = await find(need('a plugin id'));
+                if (!plugin.code)
+                    throw new Error(`${plugin.title} has no code that waits for trust.`);
+                if (plugin.trust === 'trusted') {
+                    write(`${plugin.title} is already trusted.\n`);
+                    return 0;
+                }
+                write(`${plugin.title} brings code that runs inside the harness and its sessions. It can do anything you can, including reading your files and credentials.\n\nFiles:\n${plugin.code.files.map((file) => `  ${file}`).join('\n')}\n\nFingerprint ${plugin.code.hash.slice(0, 12)}\n`);
+                if (!parsed.switches.has('yes')) {
+                    if (!dependencies.ask)
+                        throw new Error('Read the files, then run this again with --yes to trust them.');
+                    if ((await dependencies.ask('Trust this code? Type yes: ')).trim().toLowerCase() !== 'yes') {
+                        write('Not trusted.\n');
+                        return 1;
+                    }
+                }
+                await api.trust(harness, { ...scope, hash: plugin.code.hash });
+                write(`Trusted. If any of these files changes, it asks again.\n`);
+                return 0;
+            }
+            case 'untrust': {
+                const plugin = await find(need('a plugin id'));
+                if (!plugin.code)
+                    throw new Error(`${plugin.title} has no code to stop trusting.`);
+                await api.untrust(harness, { ...scope, hash: plugin.code.hash });
+                write(`${plugin.title} is not trusted any more.\n`);
+                return 0;
+            }
+            default:
+                write(PLUGINS_USAGE);
+                return 2;
+        }
+    }
+    catch (error) {
+        write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    finally {
+        await harness.close();
+    }
+}
+/** Asks on the terminal, when there is one to ask on. */
+export function terminalAsk() {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return undefined;
+    return async (question) => {
+        const reader = createInterface({ input: process.stdin, output: process.stdout });
+        try {
+            return await reader.question(question);
+        }
+        finally {
+            reader.close();
+        }
+    };
+}

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

@@ -0,0 +1,42 @@
+/**
+ * `context` is an instruction file Pi reads on its own: `AGENTS.md`, `SYSTEM.md` and their kin.
+ * `hook` is a package's hooks file, which the harness runs itself; Pi never loads it.
+ */
+export type FoundKind = 'extension' | 'skill' | 'prompt' | 'theme' | 'context' | 'hook';
+/** Where a found item comes from. `builtin` is one of the Pi command's own extensions. */
+export type FoundOrigin = 'shared' | 'package' | 'project' | 'home' | 'builtin';
+export interface Found {
+    kind: FoundKind;
+    /** A file or folder, or `builtin:<name>`. */
+    path: string;
+    origin: FoundOrigin;
+    /** Declared by the working folder: its `.pi` or `.agents` folder, or its settings. */
+    project: boolean;
+    /** The folder of the package this belongs to. */
+    packageRoot: string | null;
+    /** The package as its settings name it (`npm:…`, `git:…`, a folder). */
+    source: string | null;
+    /** Left on in Pi's settings. An item switched off there is found but never loaded. */
+    enabled: boolean;
+}
+export interface ResolveInput {
+    cwd: string;
+    /** The account's Pi agent folder. */
+    agentDir: string;
+    /** Install a package the shared settings name and the account does not have yet. */
+    install?: boolean;
+    /** Folders of packages kept outside Pi's settings: each is found as an installed package. */
+    packages?: readonly string[];
+}
+/** Finds what Pi would load. Replaced in tests. */
+export type Resolver = (input: ResolveInput) => Promise<Found[]>;
+/** The extensions built into the `pi` command. A terminal loads them; an SDK session has none. */
+export declare const PI_BUILTINS: readonly ["llama.cpp", "codemode", "tool-search", "mcp"];
+export declare const BUILTIN_PREFIX = "builtin:";
+/**
+ * Runs an install with the package manager's install scripts switched off, so fetching a
+ * package runs none of its code. A package that builds itself on install then fails to load,
+ * and says so; that is the price of installing being safe to do before trust.
+ */
+export declare function withoutInstallScripts<T>(action: () => Promise<T>): Promise<T>;
+export declare const piResolver: Resolver;

package/dist/sdk/plugins/discover.js

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

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

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

package/dist/sdk/plugins/firstParty.js

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

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

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