@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/harness.js

@@ -0,0 +1,387 @@
+// 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 { openWithSystem } from "./core/links.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 pluginProposals from "./plugins/proposals.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, reconcileStaleRuns } 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 { Usage } from "./usage/service.js";
+import { UsageLimits } from "./usage/limits/service.js";
+import { indexRunUsage, syncUsage } from "./usage/ledger.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 {
+    /** The periodic liveness check, started once with recovery (PROP-0041). */
+    staleRuns;
+    browserEnabled;
+    hub;
+    bus = new Bus();
+    env;
+    stateDir;
+    /** The account registry, account Pi folders and their shared settings; usually `<state dir>/accounts`. */
+    accountsDir;
+    policy;
+    /** How a link a person clicked reaches the operating system (page 10, `links.open`). */
+    linkOpener;
+    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;
+    /** Usage analytics over the derived ledger, and the provider limits last reported. */
+    usage;
+    usageLimits;
+    /** 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;
+        this.accountsDir = options.accountsDir ?? join(this.stateDir, 'accounts');
+        mkdirSync(this.stateDir, { recursive: true });
+        // Before anything can start a session: no inherited credential, no `~/.pi`.
+        isolateProcess(this.accountsDir);
+        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 ?? {};
+        this.linkOpener = options.linkOpener ?? openWithSystem;
+        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: this.accountsDir, secrets, bus: this.bus });
+        this.approvals = new Approvals(this.stateDir, this.bus);
+        this.usageLimits = new UsageLimits({ accounts: this.accounts, root: () => this.env.dataRoot });
+        // Response headers are the free, always-fresh limit signal; the account runtime reports them here.
+        this.accounts.observeModels = (models, accountId) => this.usageLimits.observeModels(models, accountId);
+        this.usage = new Usage({ root: () => this.env.root, accounts: this.accounts });
+        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(this.accountsDir);
+                // 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 }),
+            fullPermission: (run) => this.approvals.isAuto(approvalKey(run)),
+            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, browserExtension: options.browserExtension });
+        // 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, usage: this.usage, usageLimits: this.usageLimits, 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), proposals: { list: () => pluginProposals.list(this.env.root), preview: id => pluginProposals.preview(this.env.root, id), accept: (id, hash) => pluginProposals.accept(this, id, hash), reject: (id, hash) => pluginProposals.reject(this.env.root, id, hash) } }, assets: options.assets, hub: this.hub, world: this.world, doctor: this.doctor, worktrees: this.worktrees, noteCapture: this.noteCapture, pageNotes: this.pageNotes, refine: this.refine, sessionService: this.sessions });
+        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');
+            // The usage ledger is derived from the same recorded events; a failure never blocks the run.
+            // An interrupted run is indexed too, so its spent tokens are not lost until the next start.
+            if (runEnded)
+                indexRunUsage(this.env.root, event.runId);
+            if (runEnded && run?.sessionId) {
+                // Notes sent while this session was working go out now (runEnded waits for the terminal to
+                // see its run as ended, and tries again while it is still busy).
+                void this.pageNotes.runEnded(run.sessionId).catch((error) => log('page notes', error instanceof Error ? error.message : String(error)));
+            }
+            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);
+                    void this.pageNotes.runEnded(sessionId).catch((error) => log('page notes', error instanceof Error ? error.message : String(error)));
+                }
+                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));
+        }
+        try {
+            // Usage rows come from the same run events; the ledger can always be rebuilt from them.
+            syncUsage(root);
+        }
+        catch (error) {
+            log('usage ledger', error instanceof Error ? error.message : String(error));
+        }
+        this.recovery = { interruptedRuns: interruptedRunIds.length, interruptedRunIds, reindexedPages: safeCount(root), migrationError, legacyWiki };
+        if (!this.staleRuns) {
+            // A reply that stops emitting heartbeats while its process lives is settled here, not left
+            // `running` for the next restart (PROP-0041).
+            this.staleRuns = setInterval(() => {
+                try {
+                    reconcileStaleRuns(root);
+                }
+                catch (error) {
+                    log('stale run check', error instanceof Error ? error.message : String(error));
+                }
+            }, 60_000);
+            this.staleRuns.unref?.();
+        }
+        return this.recovery;
+    }
+    /** Rebuilds the history index from the run records. Returns the notes in the Wiki. */
+    rebuildIndex() {
+        recall.sync(this.env.root);
+        syncUsage(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() {
+        if (this.staleRuns)
+            clearInterval(this.staleRuns);
+        await this.doctor.close();
+        this.hub.close();
+        await this.refine.close();
+        await this.lessons.close();
+        await this.terminals.close();
+        this.sessions.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 {};

package/dist/sdk/history/lessons.js

@@ -0,0 +1,173 @@
+// Lessons from finished runs. When the `lessons` plugin is on for a run's caller, a completed
+// top-level run is reflected on in the background: a file-tools-only session reads its record and
+// may keep one general lesson as a Wiki note under `library/lessons/`. The lesson shape and the
+// answer-free guards are refinement's (harness²); the caps follow OMP's memory budget.
+//
+// Lessons are reference notes (INV-MEM-1). They never enter the stable prefix and never change a
+// variant; something that should become an instruction goes through refinement and `adopt`.
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { loadRun as loadCapabilities } from "../capabilities/runSnapshot.js";
+import { log } from "../core/bus.js";
+import * as frontmatter from "../core/frontmatter.js";
+import { looksSecret } from "../core/secrets.js";
+import * as attachments from "../plugins/attachments.js";
+import { LESSONS, LESSONS_CODE, LESSONS_SETTINGS, settingValue } from "../plugins/firstParty.js";
+import { assertNoGraderVerdicts, assertVariantHasNoGraderVerdicts } from "../refine/evidence.js";
+import { hasExperience } from "../refine/library.js";
+import { PiImprover } from "../refine/pi.js";
+import { parseExperience } from "../refine/selection.js";
+import { renderEvents } from "../refine/trajectory.js";
+import { executionEvents, findRun, readEvents } from "../sessions/runStore.js";
+import * as notes from "../wiki/notes.js";
+import { lessonMission, REFLECTION_IDENTITY } from "./lessonPrompt.js";
+export const REFLECTION_TRIGGER = 'reflection';
+export const LESSONS_FOLDER = 'library/lessons';
+/** Runs that are themselves part of improving the harness are never reflected on. */
+const SKIPPED_TRIGGERS = new Set(['probe', 'improver', REFLECTION_TRIGGER]);
+const REFLECTION_TOOLS = ['read', 'grep', 'find', 'ls'];
+/** The same floor refinement keeps for a trajectory (INV-REF-8). */
+const OBS_TRUNC = 10_000;
+const slug = (text) => text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60).replace(/-+$/, '') || 'lesson';
+/** The lessons the Wiki keeps now. */
+export function keptLessons(root) {
+    return notes.paths(root).filter((path) => path.startsWith(`${LESSONS_FOLDER}/`)).flatMap((path) => {
+        try {
+            const text = readFileSync(join(notes.wikiDir(root), `${path}.md`), 'utf8');
+            const parsed = frontmatter.parse(text);
+            const front = parsed?.front ?? {};
+            const sources = Array.isArray(front.sources) ? front.sources.filter((id) => typeof id === 'string') : [];
+            return [{ path, cue: typeof front.cue === 'string' ? front.cue : '', sources, front, body: parsed?.body ?? text }];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+/** The model the run used, as Pi names it, from its last usage report. */
+function modelOf(root, runId) {
+    const usage = readEvents(root, runId).filter((event) => event.type === 'usage.updated').at(-1)?.payload;
+    return typeof usage?.model === 'string' && typeof usage.provider === 'string' ? `${usage.provider}/${usage.model}` : null;
+}
+function lessonNote(experience, sources) {
+    const title = experience.cue.length > 80 ? `${experience.cue.slice(0, 77).trimEnd()}…` : experience.cue;
+    const body = [`# ${title}`, '', `**When:** ${experience.cue}`, '', `**Do:** ${experience.lesson}`, '', `**Evidence:** ${experience.evidence}`].join('\n');
+    return frontmatter.serialize({ title, cue: experience.cue, confidence: experience.confidence ?? null, sources }, body);
+}
+export class Lessons {
+    options;
+    queue = [];
+    abort = new AbortController();
+    draining = null;
+    closed = false;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Called when a run completes. Cheap: the work happens later, one run at a time. */
+    consider(run) {
+        if (this.closed || !run || run.status !== 'completed' || run.parentRunId || run.relation)
+            return;
+        if (run.trigger && SKIPPED_TRIGGERS.has(run.trigger))
+            return;
+        if (this.queue.includes(run.id))
+            return;
+        this.queue.push(run.id);
+        this.draining ??= this.drain().finally(() => {
+            this.draining = null;
+        });
+    }
+    /** Resolves when everything queued so far was reflected on. */
+    async idle() {
+        while (this.draining)
+            await this.draining;
+    }
+    async close() {
+        this.closed = true;
+        this.queue.length = 0;
+        this.abort.abort();
+        await this.draining?.catch(() => undefined);
+    }
+    async drain() {
+        while (this.queue.length && !this.closed) {
+            const runId = this.queue.shift();
+            try {
+                const outcome = await this.reflect(runId);
+                if (outcome.kind !== 'skipped')
+                    log(`lessons: run ${runId}: ${outcome.kind}${'path' in outcome ? ` ${outcome.path}` : ''}`);
+            }
+            catch (error) {
+                log(`lessons: run ${runId} was not reflected on`, error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+    /** The plugin's settings for this run's caller, or null when it is off for them. */
+    limits(root, runId) {
+        const contribution = `${LESSONS}/code/${LESSONS_CODE}`;
+        if (!loadCapabilities(root, runId)?.contributions.includes(contribution))
+            return null;
+        const saved = attachments.load(root).settings[LESSONS];
+        const value = (key) => settingValue(LESSONS_SETTINGS.find((setting) => setting.key === key), saved);
+        return { minToolCalls: value('minToolCalls'), maxLessons: value('maxLessons'), maxChars: value('maxChars') };
+    }
+    /** Reflects on one finished run. Exposed for tests and for a host that wants to ask directly. */
+    async reflect(runId) {
+        const root = this.options.root();
+        const run = findRun(root, runId);
+        if (!run || run.status !== 'completed')
+            return { kind: 'skipped', reason: 'not completed' };
+        const limits = this.limits(root, runId);
+        if (!limits)
+            return { kind: 'skipped', reason: 'plugin off' };
+        const events = executionEvents(readEvents(root, runId));
+        if (events.filter((event) => event.type === 'tool.started').length < limits.minToolCalls)
+            return { kind: 'skipped', reason: 'too few tool calls' };
+        const kept = keptLessons(root);
+        if (kept.some((lesson) => lesson.sources.includes(runId)))
+            return { kind: 'skipped', reason: 'already reflected' };
+        if (kept.length >= limits.maxLessons)
+            return { kind: 'skipped', reason: 'lesson limit reached' };
+        const context = mkdtempSync(join(tmpdir(), 'harness-lesson-'));
+        try {
+            const goal = run.goal ? `# Request\n\n${run.goal}\n\n# Record\n\n` : '# Record\n\n';
+            writeFileSync(join(context, 'run.md'), `${goal}${renderEvents(events, { obsTrunc: OBS_TRUNC })}\n`);
+            writeFileSync(join(context, 'lessons.md'), kept.length ? `${kept.map((lesson) => `${lesson.path} -- ${lesson.cue}`).join('\n')}\n` : '(no lessons kept yet)\n');
+            assertNoGraderVerdicts(context);
+            const reflector = this.options.reflector?.(run, modelOf(root, runId), this.abort.signal)
+                ?? new PiImprover(this.options.runtime, join(root, 'reflection'), { accountId: run.accountId, model: modelOf(root, runId), effort: 'medium' }, this.abort.signal, { trigger: REFLECTION_TRIGGER, identity: REFLECTION_IDENTITY, tools: REFLECTION_TOOLS });
+            const reply = await reflector.call({ mission: lessonMission(), contextDir: context, label: `lesson-${runId}`, signal: this.abort.signal });
+            return this.keep(root, runId, reply.text, kept, limits);
+        }
+        finally {
+            rmSync(context, { recursive: true, force: true });
+        }
+    }
+    keep(root, runId, text, kept, limits) {
+        if (/^\s*NO_ENTRY\s*$/m.test(text) && !text.includes('<experience>'))
+            return { kind: 'no_entry' };
+        const same = /^\s*SAME\s+(\S+)\s*$/m.exec(text)?.[1]?.replace(/\.md$/, '');
+        if (same) {
+            const lesson = kept.find((entry) => entry.path === same);
+            if (!lesson)
+                return { kind: 'skipped', reason: `named an unknown lesson ${same}` };
+            notes.write(root, lesson.path, frontmatter.serialize({ ...lesson.front, sources: [...lesson.sources, runId] }, lesson.body), { actor: REFLECTION_TRIGGER, reason: `Seen again in run ${runId}` });
+            return { kind: 'same', path: lesson.path };
+        }
+        const experience = parseExperience(text);
+        if (!hasExperience(experience))
+            return { kind: 'no_entry' };
+        const body = lessonNote(experience, [runId]);
+        if (`${experience.cue}${experience.lesson}${experience.evidence}`.length > limits.maxChars)
+            return { kind: 'skipped', reason: 'lesson too long' };
+        if (looksSecret(body))
+            return { kind: 'skipped', reason: 'lesson looked like it held a credential' };
+        assertVariantHasNoGraderVerdicts({ 'lesson.md': body });
+        const taken = new Set(notes.paths(root));
+        const base = `${LESSONS_FOLDER}/${slug(experience.cue)}`;
+        let path = base;
+        for (let n = 2; taken.has(path); n++)
+            path = `${base}-${n}`;
+        notes.write(root, path, body, { actor: REFLECTION_TRIGGER, reason: `Lesson from run ${runId}` });
+        return { kind: 'written', path };
+    }
+}