@xingular/harness 0.1.7 → 1.1.1

package/dist/sdk/doctor/types.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+export const findingSchema = z.object({
+    id: z.string(), category: z.string(), title: z.string(),
+    status: z.enum(['pass', 'warning', 'fail', 'disabled', 'blocked', 'unverified']),
+    verification: z.enum(['local', 'live']), evidence: z.string(), remedy: z.string().optional(),
+    checkedAt: z.string()
+});
+export const doctorInputSchema = z.object({
+    context: z.object({
+        caller: z.record(z.string(), z.unknown()).default({}), cwd: z.string().min(1),
+        accountId: z.string().nullable(), model: z.string().nullable(), tools: z.array(z.string()),
+        variant: z.union([
+            z.object({ scope: z.string(), version: z.string().nullable().optional() }),
+            z.object({ dir: z.string(), scope: z.string().nullable().optional() })
+        ]).nullable().optional(),
+        capabilities: z.object({ version: z.literal(1), tools: z.array(z.string()), connectors: z.array(z.string()), contributions: z.array(z.string()) }).optional()
+    }),
+    mode: z.enum(['local', 'live']).default('local'),
+    checks: z.array(z.string()).default([]),
+    /** A trusted host attests that the person approved these exact checks. */
+    confirmed: z.boolean().default(false)
+});
+export const doctorReportSchema = z.object({
+    id: z.string(), state: z.enum(['running', 'completed', 'cancelled']),
+    startedAt: z.string(), endedAt: z.string().nullable(), mode: z.enum(['local', 'live']),
+    context: z.object({ accountId: z.string().nullable(), model: z.string().nullable() }),
+    completed: z.number(), total: z.number(), findings: z.array(findingSchema),
+    liveChecks: z.array(z.object({ id: z.string(), title: z.string(), notice: z.string() }))
+});

package/dist/sdk/harness.d.ts

@@ -0,0 +1,148 @@
+import { Subagents } from "./sessions/subagentService.js";
+import { Accounts } from "./accounts/accounts.js";
+import { Hub, type HubOptions } from "./hub/hub.js";
+import { type SecretStore } from "./accounts/secrets.js";
+import { Bus } from "./core/bus.js";
+import { type Directory, type HarnessEnv } from "./core/env.js";
+import { ConnectedApps } from "./mcp/service.js";
+import type { AppOAuthClients } from "./mcp/types.js";
+import { Lessons } from "./history/lessons.js";
+import type { RefineHost } from "./refine/host.js";
+import { Refinements } from "./refine/service.js";
+import { VariantTrust } from "./variant/trust.js";
+import { World } from "./world/world.js";
+import { Doctor } from "./doctor/service.js";
+import type { Resolver } from "./plugins/discover.js";
+import { Hooks } from "./plugins/hooks.js";
+import { Plugins } from "./plugins/plugins.js";
+import type { PluginDescriptor } from "./plugins/types.js";
+import { Approvals } from "./sessions/approvals.js";
+import type { ToolPolicy } from "./sessions/policy.js";
+import { RunRegistry } from "./sessions/registry.js";
+import type { SessionFactory } from "./sessions/runner.js";
+import { Sessions } from "./sessions/sessions.js";
+import { SideQuestions } from "./sessions/sideQuestions.js";
+import { Terminals, type TerminalAssets } from "./terminal/terminals.js";
+import { Worktrees } from "./worktrees/service.js";
+import { AnnotationCapture } from "./annotations/capture.js";
+import { NoteDeliveries } from "./annotations/delivery.js";
+import type { WorktreesOptions } from "./worktrees/types.js";
+export interface HarnessOptions {
+    /** Disable the generic backend when a host supplies its own browser tools. */
+    browser?: boolean;
+    hub?: HubOptions;
+    /** Where knowledge and history live. May be set later with `open`. */
+    dataRoot?: string | null;
+    /** Device-local state that never belongs in the data root: accounts, approvals, connections, sockets. */
+    stateDir: string;
+    /** Where credentials are kept. Defaults to an owner-only file in the state directory. */
+    secrets?: SecretStore;
+    /** How the harness names itself to a model. */
+    productName?: string;
+    directory?: Directory;
+    policy?: ToolPolicy;
+    /** Replaces Pi, for tests. */
+    sessionFactory?: SessionFactory;
+    /** Where refinement executions work and with what; without it, a temporary copy of the task's source and Pi's own tools. */
+    refineHost?: RefineHost;
+    /** Where the built commands a terminal session runs are, when they are not beside this package. */
+    assets?: TerminalAssets;
+    /** @deprecated Ignored. The Harness-owned OpenTUI frontend is the only terminal. */
+    piProgram?: () => string | null;
+    /** Folders of built-in skills, prompts, and rules for the component library, each laid out like `registry/`. */
+    builtins?: string[];
+    /**
+     * The application's own parts, described as plugins: which tools, prompt sections and tool
+     * groups each one provides. Data only; it changes what is listed, never what runs.
+     */
+    plugins?: PluginDescriptor[];
+    /** Replaces Pi's own search for extensions, skills, prompts and themes, for tests. */
+    resolver?: Resolver;
+    /**
+     * The application's own registered OAuth clients, so a connector it publishes needs no client
+     * from the person. Only a catalog entry listed in `ids` can use one, and nothing is stored.
+     */
+    oauthClients?: AppOAuthClients;
+    /** Replaces how a plugin's hooks file is read as a module, for tests. */
+    hookImporter?: (address: string) => Promise<unknown>;
+    /** Where managed worktrees are made, the prefix of branches they get, and how many `prune` keeps. */
+    worktrees?: WorktreesOptions;
+}
+/** What starting on a data root found and repaired. */
+export interface Recovery {
+    interruptedRuns: number;
+    /** The runs marked interrupted, which the application may continue with `continueFrom`. */
+    interruptedRunIds: string[];
+    /** Notes in the Wiki. */
+    reindexedPages: number;
+    /** Where an earlier Wiki's memory, facts and revisions were moved, when they were. */
+    legacyWiki?: string | null;
+    /** Set when the storage migration failed; the old data is left as it was. */
+    migrationError: string | null;
+}
+declare class Env implements HarnessEnv {
+    readonly directory: Directory;
+    readonly productName: string;
+    dataRoot: string | null;
+    readonly bus: Bus;
+    constructor(dataRoot: string | null, directory: Directory, productName: string, bus: Bus);
+    get root(): string;
+}
+export declare class Harness {
+    private readonly browserEnabled;
+    readonly hub: Hub;
+    readonly bus: Bus;
+    readonly env: Env;
+    readonly stateDir: string;
+    readonly policy: ToolPolicy;
+    readonly accounts: Accounts;
+    readonly approvals: Approvals;
+    readonly runs: RunRegistry;
+    readonly apps: ConnectedApps;
+    readonly plugins: Plugins;
+    /** Code plugins gave the harness to run after memory, the Wiki or history changed. */
+    readonly hooks: Hooks;
+    /** Every part described as a plugin: the harness's own, then the application's. */
+    descriptors: readonly PluginDescriptor[];
+    applicationPlugins: ReadonlySet<string>;
+    readonly subagents: Subagents;
+    readonly sessions: Sessions;
+    /** Tool-free, run-backed questions over a redacted projection of the main conversation. */
+    readonly sideQuestions: SideQuestions;
+    /** Web, browser and computer tools (page 13). */
+    readonly world: World;
+    /** Which plugin code in variants a person trusted. */
+    readonly trust: VariantTrust;
+    /** Refinement: improving a variant from evidence of how it ran. */
+    readonly refine: Refinements;
+    /** Reflection on finished runs, when the `lessons` plugin is on (page 08). */
+    readonly lessons: Lessons;
+    refineHost: RefineHost | null;
+    readonly terminals: Terminals;
+    readonly doctor: Doctor;
+    /** Managed git worktrees sessions can work in (PROP-0016). */
+    readonly worktrees: Worktrees;
+    /** The terminal's visible browser for capturing page notes (PROP-0017). */
+    readonly noteCapture: AnnotationCapture;
+    /** Page notes on their way to a session (PROP-0018). */
+    readonly pageNotes: NoteDeliveries;
+    /** Resolves when what was loaded in the background at construction is in place. */
+    readonly ready: Promise<void>;
+    recovery: Recovery;
+    constructor(options: HarnessOptions);
+    get dataRoot(): string | null;
+    /** Sets the application's own parts, described as plugins. One with a harness plugin's id is ignored. */
+    describe(plugins: readonly PluginDescriptor[]): void;
+    /**
+     * Opens a data root: moves an earlier Wiki's memory and facts aside (once), lays out the Wiki,
+     * settles runs that never ended, and refreshes the history index. `agentIds` is accepted for
+     * hosts written against earlier versions and is not used.
+     */
+    open(dataRoot: string, _agentIds?: readonly string[]): Recovery;
+    /** Rebuilds the history index from the run records. Returns the notes in the Wiki. */
+    rebuildIndex(): number;
+    /** Stops live runs and refinements and releases the index. */
+    close(): Promise<void>;
+}
+export declare function createHarness(options: HarnessOptions): Harness;
+export {};

package/dist/sdk/harness.js

@@ -0,0 +1,338 @@
+// The harness, assembled: Pi sessions on isolated accounts, versioned variants that shape
+// them, refinement that improves those variants from evidence, a compiled prompt, project notes,
+// tools, and connected apps. An application embeds one of these and adds its own prompt
+// sections, tools, and policy; nothing here knows what that application is.
+import { Subagents } from "./sessions/subagentService.js";
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { Accounts } from "./accounts/accounts.js";
+import { Hub } from "./hub/hub.js";
+import * as capabilities from "./capabilities/api.js";
+import { ensureSharedDir, isolateProcess } from "./accounts/env.js";
+import { fileSecretStore } from "./accounts/secrets.js";
+import { Bus, log } from "./core/bus.js";
+import { DEFAULT_PRODUCT_NAME, EMPTY_DIRECTORY } from "./core/env.js";
+import { HarnessError } from "./core/errors.js";
+import { readJsonOr } from "./core/fs.js";
+import { closeIndex } from "./core/index.js";
+import { ConnectedApps } from "./mcp/service.js";
+import { migrateConnectionScopes } from "./mcp/scopeMigration.js";
+import { Lessons } from "./history/lessons.js";
+import * as recall from "./history/recall.js";
+import { Refinements } from "./refine/service.js";
+import { configureBuiltins } from "./variant/components.js";
+import { migrateVariantLayout } from "./variant/migrate.js";
+import { VariantTrust } from "./variant/trust.js";
+import * as notes from "./wiki/notes.js";
+import * as pluginApi from "./plugins/api.js";
+import * as pluginInstall from "./plugins/install.js";
+import * as attachments from "./plugins/attachments.js";
+import { HARNESS_PLUGINS } from "./plugins/builtin.js";
+import { World } from "./world/world.js";
+import { Doctor } from "./doctor/service.js";
+import { builtinChecks } from "./doctor/checks.js";
+import { diagnosticProbe } from "./doctor/probe.js";
+import { Hooks } from "./plugins/hooks.js";
+import { packageFolders, Plugins } from "./plugins/plugins.js";
+import { approvalKey, Approvals } from "./sessions/approvals.js";
+import { RunRegistry } from "./sessions/registry.js";
+import { loadRun, markInterruptedRuns } from "./sessions/runStore.js";
+import { Sessions } from "./sessions/sessions.js";
+import { SideQuestions } from "./sessions/sideQuestions.js";
+import { Terminals } from "./terminal/terminals.js";
+import { Worktrees } from "./worktrees/service.js";
+import { AnnotationCapture } from "./annotations/capture.js";
+import { NoteDeliveries } from "./annotations/delivery.js";
+class Env {
+    directory;
+    productName;
+    dataRoot;
+    bus;
+    constructor(dataRoot, directory, productName, bus) {
+        this.directory = directory;
+        this.productName = productName;
+        this.dataRoot = dataRoot;
+        this.bus = bus;
+    }
+    get root() {
+        if (!this.dataRoot)
+            throw new HarnessError('data_root_missing', 'Choose a data location first.', 'Open Settings → Projects and Storage.');
+        return this.dataRoot;
+    }
+}
+export class Harness {
+    browserEnabled;
+    hub;
+    bus = new Bus();
+    env;
+    stateDir;
+    policy;
+    accounts;
+    approvals;
+    runs;
+    apps;
+    plugins;
+    /** Code plugins gave the harness to run after memory, the Wiki or history changed. */
+    hooks;
+    /** Every part described as a plugin: the harness's own, then the application's. */
+    descriptors = HARNESS_PLUGINS;
+    applicationPlugins = new Set();
+    subagents;
+    sessions;
+    /** Tool-free, run-backed questions over a redacted projection of the main conversation. */
+    sideQuestions;
+    /** Web, browser and computer tools (page 13). */
+    world;
+    /** Which plugin code in variants a person trusted. */
+    trust;
+    /** Refinement: improving a variant from evidence of how it ran. */
+    refine;
+    /** Reflection on finished runs, when the `lessons` plugin is on (page 08). */
+    lessons;
+    refineHost;
+    terminals;
+    doctor;
+    /** Managed git worktrees sessions can work in (PROP-0016). */
+    worktrees;
+    /** The terminal's visible browser for capturing page notes (PROP-0017). */
+    noteCapture;
+    /** Page notes on their way to a session (PROP-0018). */
+    pageNotes;
+    /** Resolves when what was loaded in the background at construction is in place. */
+    ready;
+    recovery = { interruptedRuns: 0, interruptedRunIds: [], reindexedPages: 0, migrationError: null };
+    constructor(options) {
+        this.browserEnabled = options.browser !== false;
+        this.stateDir = options.stateDir;
+        mkdirSync(this.stateDir, { recursive: true });
+        // Before anything can start a session: no inherited credential, no `~/.pi`.
+        isolateProcess(join(this.stateDir, 'accounts'));
+        this.env = new Env(options.dataRoot || null, options.directory ?? EMPTY_DIRECTORY, options.productName ?? DEFAULT_PRODUCT_NAME, this.bus);
+        this.hub = new Hub(this, options.hub);
+        this.policy = options.policy ?? {};
+        configureBuiltins(options.builtins ?? []);
+        this.trust = new VariantTrust(this.stateDir);
+        this.refineHost = options.refineHost ?? null;
+        const secrets = options.secrets ?? fileSecretStore(join(this.stateDir, 'secrets.json'));
+        this.accounts = new Accounts({ dir: join(this.stateDir, 'accounts'), secrets, bus: this.bus });
+        this.approvals = new Approvals(this.stateDir, this.bus);
+        this.runs = new RunRegistry({
+            root: () => this.env.root,
+            automatic: async (run, target, operation, standing) => {
+                if (standing === 'switch')
+                    return this.approvals.isAuto(approvalKey(run)) ? 'always' : null;
+                return this.approvals.automatic(run, target, (await this.policy.approval?.({ run, target, operation })) ?? {});
+            },
+            redact: (event) => this.apps.connections.redactEvent(event),
+            ended: (runId, sessionId) => this.apps.revokeRun(runId, sessionId)
+        });
+        this.apps = new ConnectedApps({ env: this.env, stateDir: this.stateDir, secrets, bus: this.bus, runs: this.runs, policy: this.policy, oauthClients: options.oauthClients });
+        this.plugins = new Plugins({ stateDir: this.stateDir, bus: this.bus, resolver: options.resolver, attachments: () => (this.env.dataRoot ? attachments.load(this.env.dataRoot) : null), packagesDir: () => (this.env.dataRoot ? join(this.env.dataRoot, 'plugins') : null) });
+        this.hooks = new Hooks({
+            stateDir: this.stateDir,
+            bus: this.bus,
+            // A hook runs for everyone or not at all, so only what is on everywhere and trusted counts.
+            // The shared folder stands in for an account: packages are the same for all of them.
+            wanted: async () => {
+                if (!this.env.dataRoot)
+                    return [];
+                const shared = ensureSharedDir(join(this.stateDir, 'accounts'));
+                // A hook comes only with a package: one kept beside the data, or one the shared settings
+                // name. With neither there is nothing to look for, and Pi is not loaded to find that out.
+                const named = readJsonOr(join(shared, 'settings.json'), {}).packages;
+                if (!packageFolders(join(this.env.dataRoot, 'plugins')).length && !(Array.isArray(named) && named.length))
+                    return [];
+                return (await this.plugins.loading({ cwd: this.stateDir, agentDir: shared, caller: {} })).hooks;
+            },
+            call: (connection, tool, args) => this.apps.callUnattended(connection, tool, args ?? {}),
+            importFile: options.hookImporter
+        });
+        let reloadTimer = null;
+        this.bus.on((notice) => {
+            if (notice.type !== 'plugins.changed' || reloadTimer)
+                return;
+            // Several changes arrive together when a plugin is installed or switched; one reload covers them.
+            reloadTimer = setTimeout(() => {
+                reloadTimer = null;
+                void this.hooks.reload();
+            }, 50);
+            reloadTimer.unref?.();
+        });
+        this.describe(options.plugins ?? []);
+        this.worktrees = new Worktrees(this.stateDir, options.worktrees);
+        this.noteCapture = new AnnotationCapture({ stateDir: this.stateDir });
+        this.subagents = new Subagents(this.env, this.runs, (input) => this.sessions.run(input), { descriptors: () => HARNESS_PLUGINS });
+        this.sessions = new Sessions({
+            subagents: this.subagents,
+            env: this.env,
+            accounts: this.accounts,
+            runs: this.runs,
+            policy: this.policy,
+            broker: this.apps,
+            plugins: this.plugins,
+            resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, tools }),
+            factory: options.sessionFactory,
+            trust: this.trust,
+            worktrees: this.worktrees
+        });
+        this.sideQuestions = new SideQuestions({ env: this.env, sessions: this.sessions, runs: this.runs });
+        this.world = new World({ root: () => this.env.root, stateDir: this.stateDir, secrets, browser: this.browserEnabled ? undefined : false, notesChanged: (sessionId, ids) => this.bus.emit({ type: 'annotations.changed', sessionId, ids }) });
+        // The harness's own world tools come first; a tool an application provides under the same name is not added again.
+        this.sessions.provide(this.world.provider());
+        this.doctor = new Doctor({
+            checks: context => builtinChecks(this, context, secrets, options.assets),
+            probe: (context, signal, action) => diagnosticProbe(this, context, signal, action)
+        });
+        const refineRuntime = { root: () => this.env.root, runs: this.runs, run: (input) => this.sessions.run(input) };
+        this.refine = new Refinements({ root: () => this.env.root, bus: this.bus, trust: this.trust, host: () => this.refineHost, runtime: refineRuntime });
+        this.lessons = new Lessons({ root: () => this.env.root, runtime: refineRuntime });
+        this.pageNotes = new NoteDeliveries({ root: () => this.env.root, bus: this.bus, terminals: () => this.terminals ?? null });
+        this.terminals = new Terminals({ trust: this.trust, subagents: this.subagents, sideQuestions: this.sideQuestions, resolveCapabilities: (caller, tools, cwd) => capabilities.resolve(this, { agentId: caller.agentId ?? null, projectId: caller.projectId ?? null, cwd, tools }), env: this.env, stateDir: this.stateDir, accounts: this.accounts, runs: this.runs, approvals: this.approvals, apps: this.apps, policy: this.policy, bus: this.bus, plugins: this.plugins, pluginControl: { list: (scope) => pluginApi.list(this, scope), attach: (params, on) => pluginApi.attach(this, params, on), trust: (scope) => pluginApi.trust(this, scope), untrust: (scope) => pluginApi.untrust(this, scope), configure: (params) => pluginApi.configure(this, params), install: params => pluginInstall.install(this, params), remove: params => pluginInstall.remove(this, params) }, assets: options.assets, hub: this.hub, world: this.world, doctor: this.doctor, worktrees: this.worktrees, noteCapture: this.noteCapture, pageNotes: this.pageNotes });
+        this.ready = this.apps.start().catch((error) => log('connected apps', error instanceof Error ? error.message : String(error)));
+        this.runs.listen((event, run) => {
+            this.accounts.onRunEvent(event, run);
+            // Each run is indexed when it ends, so the next turn can already recall it.
+            if (event.type === 'completed' || event.type === 'failed')
+                recall.indexRun(this.env.root, event.runId);
+            if (run?.trigger === 'doctor')
+                return;
+            const runEnded = event.type === 'completed' || event.type === 'failed' || (event.type === 'status.changed' && event.payload.status === 'interrupted');
+            if (runEnded && run?.sessionId) {
+                // Notes sent with "Proceed now" while this session was working go out now; the terminal
+                // needs a moment to see its run as ended.
+                setTimeout(() => void this.pageNotes.runEnded(run.sessionId).catch((error) => log('page notes', error instanceof Error ? error.message : String(error))), 250).unref?.();
+            }
+            if ((event.type === 'completed' || event.type === 'failed') && run) {
+                if (event.type === 'completed')
+                    this.lessons.consider(run);
+                this.hooks.emit({ type: 'history.run.ended', runId: run.id, sessionId: run.sessionId, status: run.status, goal: run.goal ?? null, agentId: run.agentId ?? null, projectId: run.projectId ?? null, startedAt: run.startedAt, endedAt: run.endedAt ?? null, at: event.timestamp });
+            }
+        });
+    }
+    get dataRoot() {
+        return this.env.dataRoot;
+    }
+    /** Sets the application's own parts, described as plugins. One with a harness plugin's id is ignored. */
+    describe(plugins) {
+        const foundation = HARNESS_PLUGINS.filter(plugin => this.browserEnabled || plugin.id !== 'browser');
+        const own = new Set(foundation.map((plugin) => plugin.id));
+        const supplied = plugins.filter((plugin) => plugin && typeof plugin.id === 'string' && !own.has(plugin.id));
+        this.descriptors = [...foundation, ...supplied];
+        this.applicationPlugins = new Set(supplied.map((plugin) => plugin.id));
+    }
+    /**
+     * Opens a data root: moves an earlier Wiki's memory and facts aside (once), lays out the Wiki,
+     * settles runs that never ended, and refreshes the history index. `agentIds` is accepted for
+     * hosts written against earlier versions and is not used.
+     */
+    open(dataRoot, _agentIds = []) {
+        if (this.hub.busy && this.env.dataRoot !== dataRoot)
+            throw new HarnessError('hub_busy', 'Wait for the hub installation before changing the data location.');
+        if (this.env.dataRoot && this.env.dataRoot !== dataRoot)
+            closeIndex(this.env.dataRoot);
+        this.env.dataRoot = dataRoot;
+        this.hub.watch(dataRoot);
+        const root = dataRoot;
+        this.hooks.watch(notes.wikiDir(root));
+        void this.hooks.reload();
+        for (const folder of ['registry/skills', 'registry/prompts', 'registry/rules', 'config', 'runs'])
+            mkdirSync(join(root, folder), { recursive: true });
+        let migrationError = null;
+        try {
+            const moved = migrateVariantLayout(root);
+            if (moved.length)
+                log(`renamed ${moved.length} earlier harness folders to variants`);
+        }
+        catch (error) {
+            migrationError = error instanceof Error ? error.message : String(error);
+            log('variant layout', migrationError);
+        }
+        mkdirSync(join(root, 'variants'), { recursive: true });
+        let legacyWiki = null;
+        try {
+            legacyWiki = notes.moveLegacy(root);
+            if (legacyWiki)
+                log(`moved the earlier Wiki's memory, facts and revisions to ${legacyWiki}`);
+            notes.ensureLayout(root, this.env.productName);
+        }
+        catch (error) {
+            migrationError = error instanceof Error ? error.message : String(error);
+            log('Wiki layout', migrationError);
+        }
+        try {
+            migrateConnectionScopes(root, this.stateDir);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            migrationError = migrationError ? `${migrationError}; connector scope migration: ${detail}` : detail;
+            log('connector scope migration failed', detail);
+        }
+        let interruptedRunIds = [];
+        try {
+            interruptedRunIds = markInterruptedRuns(root, `${this.env.productName} stopped before the run settled.`);
+            const recoveredSessions = new Set();
+            for (const runId of interruptedRunIds) {
+                try {
+                    const sessionId = loadRun(root, runId).sessionId;
+                    if (!sessionId || recoveredSessions.has(sessionId))
+                        continue;
+                    recoveredSessions.add(sessionId);
+                    setTimeout(() => void this.pageNotes.runEnded(sessionId).catch((error) => log('page notes', error instanceof Error ? error.message : String(error))), 250).unref?.();
+                }
+                catch {
+                    // A malformed run record does not prevent the rest of recovery.
+                }
+            }
+        }
+        catch (error) {
+            log('run recovery', error instanceof Error ? error.message : String(error));
+        }
+        try {
+            // Runs recorded while nothing was running become searchable.
+            recall.sync(root);
+        }
+        catch (error) {
+            log('recall', error instanceof Error ? error.message : String(error));
+        }
+        this.recovery = { interruptedRuns: interruptedRunIds.length, interruptedRunIds, reindexedPages: safeCount(root), migrationError, legacyWiki };
+        return this.recovery;
+    }
+    /** Rebuilds the history index from the run records. Returns the notes in the Wiki. */
+    rebuildIndex() {
+        recall.sync(this.env.root);
+        const count = safeCount(this.env.root);
+        this.recovery = { ...this.recovery, reindexedPages: count };
+        return count;
+    }
+    /** Stops live runs and refinements and releases the index. */
+    async close() {
+        await this.doctor.close();
+        this.hub.close();
+        await this.refine.close();
+        await this.lessons.close();
+        await this.terminals.close();
+        await this.noteCapture.close();
+        await this.sideQuestions.close();
+        await this.runs.interruptAll();
+        await this.world.close();
+        await this.hooks.settled().catch(() => undefined);
+        this.hooks.close();
+        await this.apps.close();
+        if (this.env.dataRoot)
+            closeIndex(this.env.dataRoot);
+    }
+}
+function safeCount(root) {
+    try {
+        return notes.paths(root).length;
+    }
+    catch {
+        return 0;
+    }
+}
+export function createHarness(options) {
+    const harness = new Harness(options);
+    if (options.dataRoot)
+        harness.open(options.dataRoot);
+    return harness;
+}

package/dist/sdk/history/lessonPrompt.d.ts

@@ -0,0 +1,2 @@
+export declare const REFLECTION_IDENTITY = "You read the record of one finished agent run and decide whether it teaches a lesson worth keeping for later runs. Work only inside the current folder: the evidence is under `context/`. Do not change any file. Follow the mission in the user message exactly.";
+export declare function lessonMission(): string;

package/dist/sdk/history/lessonPrompt.js

@@ -0,0 +1,15 @@
+// The mission of a reflection run: read how one finished run went and write at most one lesson
+// for the Wiki. The lesson shape (a cue, a checkable lesson, the evidence, or NO_ENTRY) is the
+// one the refinement library uses (`refine/prompts.ts::experience`), from harness².
+import { ANSWER_FREE, EVIDENCE_BOUNDARY } from "../refine/prompts.js";
+export const REFLECTION_IDENTITY = 'You read the record of one finished agent run and decide whether it teaches a lesson worth keeping for later runs. Work only inside the current folder: the evidence is under `context/`. Do not change any file. Follow the mission in the user message exactly.';
+export function lessonMission() {
+    return [
+        'Read `context/run.md`: the complete record of one finished run of an agent, in the order it happened -- the request, what the agent said, every tool call and what came back. `context/lessons.md` lists the lessons already kept, one per line, as `path -- cue`.',
+        '# WHAT A LESSON IS\n\nA lesson is something a later run, on a different request, would do differently because it read it. It comes from a contrast the record shows: an approach that failed and one that then worked, a tool call that was wasted, a check that caught a mistake, a step that had to be redone.\n\nThe `cue` describes the SHAPE OF SITUATION the lesson applies to, so it can fire on a different matter. Not this run\'s facts -- the pattern. The `lesson` is the operation to perform, stated so it can be applied and checked.\n\nToo generic is useless (\'be thorough\', \'read the code first\'); too specific never fires again (\'the config file is at src/app.json\'). Aim between: \'when a build tool reports a missing module after a dependency upgrade, check the lockfile was regenerated before editing imports\'.\n\nNever put into a lesson a fact about this run\'s subject: names of files, people, projects, values, or anything the user said about their own work. Those are wrong anchors for any other run, and they may be private.',
+        '# WHEN TO WRITE NOTHING\n\nMost runs teach nothing new. If the record shows no concrete contrast -- the work simply went as planned, or the only lesson would be generic advice -- reply with the single line NO_ENTRY. That is the expected answer for most runs.\n\nIf one of the lessons in `context/lessons.md` already says the same thing, reply with the single line `SAME <path>` naming it, instead of a new entry.',
+        ANSWER_FREE,
+        EVIDENCE_BOUNDARY,
+        '# OUTPUT FORMAT\n\nExactly one of:\n\nNO_ENTRY\n\nSAME <path from context/lessons.md>\n\n<experience>\ncue: <the shape of situation this applies to, one line>\nlesson: <the operation to perform, one line>\nevidence: <the contrast in the record this rests on, one line, without the subject\'s facts>\nconfidence: <high|medium|low, and why>\n</experience>'
+    ].join('\n\n') + '\n';
+}

package/dist/sdk/history/lessons.d.ts

@@ -0,0 +1,52 @@
+import { type RefineRuntime } from "../refine/pi.js";
+import type { Improver } from "../refine/types.js";
+import type { RunRecord } from "../sessions/contracts.js";
+export declare const REFLECTION_TRIGGER = "reflection";
+export declare const LESSONS_FOLDER = "library/lessons";
+export type LessonOutcome = {
+    kind: 'written';
+    path: string;
+} | {
+    kind: 'same';
+    path: string;
+} | {
+    kind: 'no_entry';
+} | {
+    kind: 'skipped';
+    reason: string;
+};
+export interface LessonsOptions {
+    root: () => string;
+    runtime: RefineRuntime;
+    /** Builds the reflection session for one run. Tests pass a fake; by default it is a `PiImprover`. */
+    reflector?: (run: RunRecord, model: string | null, signal: AbortSignal) => Improver;
+}
+interface KeptLesson {
+    path: string;
+    cue: string;
+    sources: string[];
+    front: Record<string, unknown>;
+    body: string;
+}
+/** The lessons the Wiki keeps now. */
+export declare function keptLessons(root: string): KeptLesson[];
+export declare class Lessons {
+    private readonly options;
+    private readonly queue;
+    private readonly abort;
+    private draining;
+    private closed;
+    constructor(options: LessonsOptions);
+    /** Called when a run completes. Cheap: the work happens later, one run at a time. */
+    consider(run: RunRecord | null): void;
+    /** Resolves when everything queued so far was reflected on. */
+    idle(): Promise<void>;
+    close(): Promise<void>;
+    private drain;
+    /** The plugin's settings for this run's caller, or null when it is off for them. */
+    private limits;
+    /** Reflects on one finished run. Exposed for tests and for a host that wants to ask directly. */
+    reflect(runId: string): Promise<LessonOutcome>;
+    private keep;
+}
+export {};