@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/refine/service.js

@@ -0,0 +1,280 @@
+// Refinements as the harness offers them: start one in the background, follow it, stop it, read
+// what it produced, and adopt its chosen harness. The method itself is in `runner.ts`.
+import { randomUUID } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { HarnessError, invalid, notFound } from "../core/errors.js";
+import { readJsonOr, safeId } from "../core/fs.js";
+import { findRun, listRuns, readEvents } from "../sessions/runStore.js";
+import * as store from "../variant/store.js";
+import { PI_SURFACE } from "../variant/surface.js";
+import { diffSummary, readVariant } from "../variant/variant.js";
+import { DEFAULT_REFINE_HOST } from "./host.js";
+import { Library, libraryAreas, libraryScopes } from "./library.js";
+import { PiExecutor, PiImprover, RETAINED_WORKSPACE } from "./pi.js";
+import { checkGuidance, checkWorkPrompts } from "./prompts.js";
+import { readSummary, refineDir, runRefinement } from "./runner.js";
+/** The text the person typed for a turn: its first user message, else its recorded goal. */
+function requestOf(root, record) {
+    try {
+        for (const event of readEvents(root, record.id)) {
+            const payload = event.payload;
+            if (event.type === 'message.completed' && payload?.role === 'user' && typeof payload.text === 'string' && payload.text.trim())
+                return payload.text;
+        }
+    }
+    catch {
+        // Fall back to the goal.
+    }
+    return record.goal ?? '';
+}
+/** A run a person typed, at the top of its session: what `/refine` may replay. */
+function replayable(record) {
+    return (record.trigger == null || record.trigger === 'user') && !record.relation && !record.parentRunId;
+}
+function checkGuidanceOrInvalid(guidance) {
+    try {
+        return checkGuidance(guidance);
+    }
+    catch (error) {
+        throw invalid(error instanceof Error ? error.message : String(error));
+    }
+}
+/** A refinement's variants folder; records made before PROP-0009 call it `harnesses`. */
+const variantsFolder = (dir) => (existsSync(join(dir, 'variants')) || !existsSync(join(dir, 'harnesses')) ? join(dir, 'variants') : join(dir, 'harnesses'));
+export class Refinements {
+    options;
+    active = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    /** Starts a refinement and returns at once; progress arrives as `refine.changed` and `refine.event` notices. */
+    start(input) {
+        const root = this.options.root();
+        const task = input.task;
+        if (!task || typeof task.id !== 'string' || !task.id.trim() || typeof task.prompt !== 'string' || !task.prompt.trim())
+            throw invalid('A refinement needs a task with an id and a request.');
+        safeId(task.scope);
+        if (task.prompts)
+            checkWorkPrompts(task.prompts);
+        if (task.guidance != null) {
+            if (typeof task.guidance !== 'string')
+                throw invalid('guidance is text.');
+            task.guidance = checkGuidanceOrInvalid(task.guidance) || null;
+        }
+        if (task.workspace != null && (task.workspace.kind !== 'git-snapshot' || typeof task.workspace.repo !== 'string' || !/^[0-9a-f]{40,64}$/.test(String(task.workspace.commit))))
+            throw invalid('workspace is a git snapshot: { kind: "git-snapshot", repo, commit }.');
+        const k = input.k ?? 1;
+        const mode = input.mode ?? 'parallel';
+        if (mode !== 'parallel' && mode !== 'sequential')
+            throw invalid('mode is parallel or sequential.');
+        const base = input.baseVersion ? { variant: store.readVersion(root, task.scope, input.baseVersion) } : store.headVariant(root, task.scope);
+        if (!base)
+            throw new HarnessError('harness_missing', `The harness '${task.scope}' has no version yet.`, 'Create or seed it first.');
+        const id = input.id ? safeId(input.id) : `${new Date().toISOString().slice(0, 10)}-${randomUUID().slice(0, 8)}`;
+        if (this.active.has(id))
+            throw invalid('That refinement is already running.');
+        const dir = refineDir(root, id);
+        const controller = new AbortController();
+        const host = this.options.host() ?? DEFAULT_REFINE_HOST;
+        const executor = this.options.executor?.(id, dir, controller.signal) ?? new PiExecutor(this.options.runtime, host, id, dir, controller.signal, { retainWorkspaces: input.retainWorkspaces === true, settings: input.executor });
+        const improver = this.options.improver?.(id, dir, input.improver ?? {}, controller.signal) ?? new PiImprover(this.options.runtime, dir, input.improver ?? {}, controller.signal);
+        const emit = (event) => {
+            if (event.type === 'summary')
+                this.options.bus.emit({ type: 'refine.changed', id, scope: task.scope, status: event.summary.status });
+            else
+                this.options.bus.emit({ type: 'refine.event', id, scope: task.scope, event });
+        };
+        const done = runRefinement({ root, id, task, k, mode, executor, improver, baseVariant: base.variant, settings: { executor: input.executor ?? null, improver: input.improver ?? null }, onEvent: emit, signal: controller.signal })
+            .catch((error) => {
+            this.options.bus.emit({ type: 'refine.changed', id, scope: task.scope, status: 'failed', error: error instanceof Error ? error.message : String(error) });
+            return null;
+        })
+            .finally(() => this.active.delete(id));
+        this.active.set(id, { controller, done });
+        return { id };
+    }
+    /**
+     * A task that replays one recorded turn (`runId`) or the latest turn a person typed in a session
+     * (`sessionId`), from the working tree as that turn found it. Refuses a turn with no snapshot.
+     */
+    taskFromRun(input) {
+        const root = this.options.root();
+        let record = null;
+        const latest = (records) => records.find((entry) => replayable(entry) && requestOf(root, entry).trim()) ?? null;
+        if (input.runId)
+            record = findRun(root, safeId(input.runId));
+        else if (input.sessionId || input.nativeSessionId) {
+            if (input.sessionId)
+                record = latest(listRuns(root, { sessionId: input.sessionId }));
+            // A terminal that restarted on another version keeps its conversation under a new session id.
+            if (!record && input.nativeSessionId)
+                record = latest(listRuns(root, {}).filter((entry) => entry.nativeSessionId === input.nativeSessionId));
+        }
+        else
+            throw invalid('Name a run or a session to refine from.');
+        if (!record)
+            throw notFound(input.runId ? 'That run' : 'A request in this session');
+        if (!replayable(record))
+            throw invalid('Only a request a person typed can be replayed; this run was started by something else.');
+        const prompt = requestOf(root, record).trim();
+        if (!prompt)
+            throw invalid('That run has no request text to replay.');
+        if (!record.variantScope)
+            throw invalid('That run used no variant, so there is nothing to refine.');
+        const snapshot = record.workspaceSnapshot;
+        if (!snapshot)
+            throw new HarnessError('replay_unavailable', 'That request has no snapshot of the folder it started in, so it cannot be replayed safely.', 'Refinement replays requests made in a git repository; the snapshot is skipped outside git or when it takes over two seconds.');
+        const notes = [];
+        if (snapshot.omitted)
+            notes.push(`${snapshot.omitted} untracked file${snapshot.omitted === 1 ? ' was' : 's were'} too large or too many to snapshot and will be missing from the replay.`);
+        if (record.attachmentCount > 0)
+            notes.push(`${record.attachmentCount} attachment${record.attachmentCount === 1 ? '' : 's'} on that request are not replayed; only its text is.`);
+        const guidance = input.guidance?.trim() ? checkGuidanceOrInvalid(input.guidance) : null;
+        return {
+            task: { id: `turn-${record.id.replace(/[^A-Za-z0-9_-]/g, '').slice(0, 12)}`, scope: record.variantScope, prompt, workspace: snapshot, ...(guidance ? { guidance } : {}) },
+            run: { id: record.id, sessionId: record.sessionId, startedAt: record.startedAt, model: record.model ?? null },
+            notes
+        };
+    }
+    /** Waits for a running refinement; resolves at once for one that is not running. */
+    async wait(id) {
+        return (await this.active.get(id)?.done) ?? readSummary(this.options.root(), id);
+    }
+    get(id) {
+        const summary = readSummary(this.options.root(), safeId(id));
+        if (!summary)
+            throw notFound('That refinement');
+        return summary;
+    }
+    running() {
+        return [...this.active.keys()];
+    }
+    /** Every recorded refinement, newest first, optionally for one scope. */
+    list(options = {}) {
+        const dir = join(this.options.root(), 'refine');
+        if (!existsSync(dir))
+            return [];
+        const out = [];
+        for (const name of readdirSync(dir).sort().reverse()) {
+            if (name === 'library')
+                continue;
+            const summary = readSummary(this.options.root(), name);
+            if (summary && (!options.scope || summary.scope === options.scope))
+                out.push(summary);
+        }
+        return out.sort((a, b) => b.startedAt.localeCompare(a.startedAt)).slice(0, options.limit ?? 100);
+    }
+    async cancel(id) {
+        const running = this.active.get(id);
+        if (!running)
+            return;
+        running.controller.abort();
+        await running.done;
+    }
+    /** Every execution of a refinement: what variant it ran, how it differs from the base, what it produced. */
+    candidates(id) {
+        const root = this.options.root();
+        const summary = this.get(id);
+        const dir = refineDir(root, id);
+        const baseVariant = readVariant(PI_SURFACE, join(variantsFolder(dir), 'base'));
+        const finals = new Set(summary.recursion?.finals ?? []);
+        const labels = existsSync(join(dir, 'rollouts')) ? readdirSync(join(dir, 'rollouts')).sort() : [];
+        return labels.map((label) => {
+            const record = readJsonOr(join(dir, 'rollouts', label, 'rollout.json'), {});
+            const base = summary.base.find((entry) => entry.label === label);
+            const variantDir = join(variantsFolder(dir), label);
+            const variant = existsSync(variantDir) ? readVariant(PI_SURFACE, variantDir) : null;
+            const files = record.files ?? [];
+            const workspace = join(dir, 'rollouts', label, RETAINED_WORKSPACE);
+            return {
+                label,
+                kind: label.startsWith('base') ? 'base' : finals.has(label) ? 'final' : 'candidate',
+                ok: base ? base.ok : record.status ? record.status === 'completed' : true,
+                delivered: base ? base.delivered : files.length > 0,
+                runId: `${id}-${label}`,
+                fingerprint: variant ? store.fingerprint(variant) : null,
+                diff: variant && !label.startsWith('base') ? diffSummary(PI_SURFACE, baseVariant, variant) : null,
+                files,
+                workspace: existsSync(workspace) ? workspace : null
+            };
+        });
+    }
+    /** File by file, how one candidate's variant differs from the refinement's base. */
+    candidateDiff(id, label) {
+        this.get(id);
+        const dir = variantsFolder(refineDir(this.options.root(), id));
+        const base = readVariant(PI_SURFACE, join(dir, 'base'));
+        const candidateDir = join(dir, safeId(label));
+        if (!existsSync(candidateDir))
+            throw notFound('That candidate variant');
+        const after = readVariant(PI_SURFACE, candidateDir);
+        const summary = diffSummary(PI_SURFACE, base, after);
+        const files = [...summary.added, ...summary.removed, ...summary.modified].sort().map((path) => ({ path, before: base[path] ?? null, after: after[path] ?? null }));
+        return { label, files };
+    }
+    /** What one execution produced, filename → text. */
+    candidateOutput(id, label) {
+        this.get(id);
+        const dir = join(refineDir(this.options.root(), id), 'rollouts', safeId(label));
+        if (!existsSync(dir))
+            throw notFound('That execution');
+        const record = readJsonOr(join(dir, 'rollout.json'), {});
+        const out = {};
+        for (const name of record.files ?? []) {
+            try {
+                out[name] = readFileSync(join(dir, 'deliverables', name), 'utf8');
+            }
+            catch {
+                // A file that went missing is not shown.
+            }
+        }
+        return out;
+    }
+    /**
+     * Makes a refinement's chosen harness (or one of its candidates, by label) the scope's head.
+     * Plugin code in it must already be trusted.
+     */
+    adopt(id, options = {}) {
+        const root = this.options.root();
+        const summary = this.get(id);
+        const label = options.label ?? summary.selection?.chosenLabel;
+        if (!label)
+            throw invalid('This refinement has nothing to adopt.');
+        const variant = readVariant(PI_SURFACE, join(variantsFolder(refineDir(root, id)), safeId(label)));
+        if (!Object.keys(variant).length)
+            throw notFound('That candidate variant');
+        if (options.tag)
+            store.checkTagName(options.tag);
+        const untrusted = this.options.trust.review(variant).filter((plugin) => !plugin.trusted);
+        if (untrusted.length)
+            throw new HarnessError('plugin_untrusted', `Trust the plugin code first: ${untrusted.map((plugin) => plugin.path).join(', ')}.`, 'Review the plugin files on the Harness page, trust them, then adopt.');
+        // The model the adopted variant was tuned on: what its own execution resolved, else what the refinement asked for.
+        const model = findRun(root, `${id}-${label}`)?.model ?? summary.settings?.executor?.model ?? null;
+        store.commit(root, summary.scope, variant, { kind: 'refinement', refineId: id, label, note: summary.selection?.why?.slice(0, 500) }, { tunedFor: model ? { model } : null });
+        const adopted = store.head(root, summary.scope);
+        if (options.tag)
+            store.tag(root, summary.scope, options.tag, adopted.fingerprint);
+        this.options.bus.emit({ type: 'variants.changed', scope: summary.scope });
+        return adopted;
+    }
+    library(scope) {
+        const root = this.options.root();
+        return libraryAreas(root, scope).map((area) => ({ area, entries: new Library(root, scope, area).list() }));
+    }
+    libraryEntry(scope, area, task) {
+        const library = new Library(this.options.root(), scope, area);
+        return { experience: library.experienceText(task), variant: library.variantOf(task) };
+    }
+    forget(scope, area, tasks) {
+        new Library(this.options.root(), scope, area).forget(tasks);
+        this.options.bus.emit({ type: 'library.changed', scope });
+    }
+    scopes() {
+        return libraryScopes(this.options.root());
+    }
+    async close() {
+        for (const id of this.running())
+            await this.cancel(id);
+    }
+}

package/dist/sdk/refine/suite.d.ts

@@ -0,0 +1,67 @@
+import { type Variant } from "../variant/surface.js";
+import type { Executor, RefineTask } from "./types.js";
+export type MatrixStatus = 'running' | 'ok' | 'partial' | 'failed' | 'cancelled';
+export interface MatrixVersion {
+    /** Record label; also names the variant copy under the record's variants/ folder. */
+    label: string;
+    variant: Variant;
+}
+export interface MatrixRow {
+    version: string;
+    fingerprint: string;
+    task: string;
+    runId: string;
+    dir: string;
+    ok: boolean;
+    delivered: boolean;
+    costUsd: number;
+    wallMs: number;
+    error: string;
+    /** Comparability keys: one task text, one executor, one package release. */
+    taskHash: string;
+    executor: string;
+    packageVersion: string;
+}
+export interface MatrixSummary {
+    id: string;
+    status: MatrixStatus;
+    startedAt: string;
+    endedAt: string | null;
+    versions: string[];
+    tasks: string[];
+    rows: MatrixRow[];
+    usd: number;
+    errors: string[];
+}
+export type MatrixEvent = {
+    type: 'execution.started';
+    version: string;
+    task: string;
+    label: string;
+} | {
+    type: 'execution.finished';
+    version: string;
+    task: string;
+    ok: boolean;
+    delivered: boolean;
+    error: string;
+} | {
+    type: 'summary';
+    summary: MatrixSummary;
+};
+export interface MatrixInput {
+    root: string;
+    id: string;
+    versions: MatrixVersion[];
+    tasks: RefineTask[];
+    executor: Executor;
+    /** The executor's name for the records; defaults to its constructor's name. */
+    executorName?: string;
+    rolloutWidth?: number;
+    onEvent?: (event: MatrixEvent) => void;
+    signal?: AbortSignal;
+}
+export declare function matrixDir(root: string, id: string): string;
+export declare function readMatrix(root: string, id: string): MatrixSummary | null;
+/** Runs the full version × task matrix. Bad input throws; execution failures become rows. */
+export declare function runMatrix(input: MatrixInput): Promise<MatrixSummary>;

package/dist/sdk/refine/suite.js

@@ -0,0 +1,174 @@
+// Evaluating variants on a task set: one execution per version × task, recorded as an
+// answer-free matrix of what each variant delivered. No improver, no selection, no adoption —
+// the only executions here are the given Executor's probe runs. Records live beside a
+// refinement's, under `<data root>/refine/<id>/`, so a sweep over variant versions or package
+// commits reads the same record family (`refine/<id>/matrix.json`).
+//
+// Every row carries its comparability keys (task-prompt hash, executor name, package
+// version, variant fingerprint), so two matrices — taken at different commits or versions —
+// are diffable without re-reading the runs that produced them.
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { now, readJson, safeId, writeJson } from "../core/fs.js";
+import * as store from "../variant/store.js";
+import { PI_SURFACE } from "../variant/surface.js";
+import { writeVariant } from "../variant/variant.js";
+import { assertVariantHasNoGraderVerdicts } from "./evidence.js";
+import { mapLimit } from "./recursion.js";
+export function matrixDir(root, id) {
+    return join(root, 'refine', safeId(id));
+}
+export function readMatrix(root, id) {
+    return readJson(join(matrixDir(root, id), 'matrix.json'));
+}
+let packageVersionMemo = null;
+/** This package's release, whatever shape the module took: source, esbuild bundle, or an
+ * installed copy. Walks up from the module's own URL to the nearest package.json. */
+function packageVersion() {
+    if (packageVersionMemo === null) {
+        packageVersionMemo = 'unknown';
+        try {
+            let dir = fileURLToPath(import.meta.url);
+            for (let up = 0; up < 6; up++) {
+                dir = dirname(dir);
+                const manifest = join(dir, 'package.json');
+                if (existsSync(manifest)) {
+                    const json = JSON.parse(readFileSync(manifest, 'utf8'));
+                    if (json.version)
+                        packageVersionMemo = json.version;
+                    break;
+                }
+            }
+        }
+        catch {
+            // A record without a version is still a record.
+        }
+    }
+    return packageVersionMemo;
+}
+function taskHash(task) {
+    return createHash('sha256').update(task.prompt).digest('hex').slice(0, 16);
+}
+const SEGMENT = /^[A-Za-z0-9_-]{1,128}$/;
+function stage(input) {
+    const labels = [];
+    for (const entry of input.versions) {
+        if (!SEGMENT.test(entry.label))
+            throw new Error(`Version label '${entry.label}' must be a usable record name (A-Z a-z 0-9 _ -).`);
+        labels.push(entry.label);
+    }
+    if (new Set(labels).size !== labels.length)
+        throw new Error('Version labels must be unique.');
+    if (input.tasks.some((task) => !SEGMENT.test(task.id)))
+        throw new Error('Task ids must be usable record names (A-Z a-z 0-9 _ -).');
+    if (new Set(input.tasks.map((task) => task.id)).size !== input.tasks.length)
+        throw new Error('Task ids must be unique.');
+    // Staging and the tripwire happen before any execution: a variant carrying grader output
+    // never reaches an execution, the same guard the refinement's evidence folder applies
+    // (INV-REF-1). A variant that cannot be written becomes an error row, never an abort.
+    return input.versions.map((entry) => {
+        try {
+            assertVariantHasNoGraderVerdicts(entry.variant);
+            return { label: entry.label, variant: entry.variant, fingerprint: store.fingerprint(entry.variant), dir: writeVariant(PI_SURFACE, entry.variant, join(matrixDir(input.root, input.id), 'variants', entry.label)), error: '' };
+        }
+        catch (error) {
+            return { label: entry.label, variant: entry.variant, fingerprint: store.fingerprint(entry.variant), dir: '', error: error instanceof Error ? error.message : String(error) };
+        }
+    });
+}
+/** Runs the full version × task matrix. Bad input throws; execution failures become rows. */
+export async function runMatrix(input) {
+    if (!input.versions.length)
+        throw new Error('A matrix needs at least one harness version.');
+    if (!input.tasks.length)
+        throw new Error('A matrix needs at least one task.');
+    if (input.tasks.some((task) => !task.prompt.trim()))
+        throw new Error('Every task needs a non-empty prompt.');
+    const { root, id, tasks, executor } = input;
+    const executorName = input.executorName ?? executor.constructor?.name ?? 'executor';
+    const emit = (event) => input.onEvent?.(event);
+    const staged = stage(input);
+    const summary = {
+        id,
+        status: 'running',
+        startedAt: now(),
+        endedAt: null,
+        versions: staged.map((entry) => entry.label),
+        tasks: tasks.map((task) => task.id),
+        rows: [],
+        usd: 0,
+        errors: []
+    };
+    const save = () => {
+        summary.usd = Math.round(summary.rows.reduce((sum, row) => sum + row.costUsd, 0) * 1e6) / 1e6;
+        writeJson(join(matrixDir(root, id), 'matrix.json'), summary);
+        emit({ type: 'summary', summary: structuredClone(summary) });
+    };
+    writeJson(join(matrixDir(root, id), 'suite.json'), { id, versions: staged.map(({ label, fingerprint }) => ({ label, fingerprint })), tasks });
+    save();
+    const pairs = staged.flatMap((version) => tasks.map((task) => ({ version, task })));
+    await mapLimit(pairs, input.rolloutWidth ?? 4, async ({ version, task }) => {
+        const runId = `${id}-${version.label}-${task.id}`;
+        let row;
+        if (input.signal?.aborted)
+            row = failedRow(version, task, runId, executorName, 'The matrix was cancelled.');
+        else if (version.error)
+            row = failedRow(version, task, runId, executorName, `the variant could not be staged: ${version.error}`);
+        else {
+            let validation = null;
+            if (executor.validateVariant) {
+                try {
+                    executor.validateVariant(task, version.variant);
+                }
+                catch (error) {
+                    validation = `invalid variant for this task: ${error instanceof Error ? error.message : String(error)}`;
+                }
+            }
+            if (validation)
+                row = failedRow(version, task, runId, executorName, validation);
+            else {
+                emit({ type: 'execution.started', version: version.label, task: task.id, label: runId });
+                let rollout;
+                try {
+                    rollout = await executor.execute(task, version.dir, runId, runId);
+                }
+                catch (error) {
+                    // The Executor contract says execute never throws; this keeps the record honest if one does.
+                    rollout = { label: runId, runId, dir: join(matrixDir(root, id), 'missing', version.label, task.id), ok: false, delivered: false, costUsd: 0, wallMs: 0, error: error instanceof Error ? error.message : String(error) };
+                }
+                emit({ type: 'execution.finished', version: version.label, task: task.id, ok: rollout.ok, delivered: rollout.delivered, error: rollout.error });
+                row = rowOf(version, task, runId, executorName, rollout);
+            }
+        }
+        summary.rows.push(row);
+        save();
+    });
+    for (const error of staged.filter((entry) => entry.error).map((entry) => `${entry.label}: ${entry.error}`))
+        summary.errors.push(error);
+    summary.status = input.signal?.aborted ? 'cancelled' : summary.rows.some((row) => row.ok) ? 'ok' : summary.rows.length ? 'partial' : 'failed';
+    summary.endedAt = now();
+    save();
+    return summary;
+}
+function rowOf(version, task, runId, executorName, rollout) {
+    return {
+        version: version.label,
+        fingerprint: version.fingerprint,
+        task: task.id,
+        runId,
+        dir: rollout.dir,
+        ok: rollout.ok,
+        delivered: rollout.delivered,
+        costUsd: rollout.costUsd,
+        wallMs: rollout.wallMs,
+        error: rollout.error,
+        taskHash: taskHash(task),
+        executor: executorName,
+        packageVersion: packageVersion()
+    };
+}
+function failedRow(version, task, runId, executorName, error) {
+    return rowOf(version, task, runId, executorName, { label: runId, runId, dir: '', ok: false, delivered: false, costUsd: 0, wallMs: 0, error });
+}

package/dist/sdk/refine/trajectory.d.ts

@@ -0,0 +1,9 @@
+import type { RunEvent } from "../sessions/contracts.js";
+export declare function renderEvents(events: readonly RunEvent[], options: {
+    obsTrunc: number;
+    argsTrunc?: number;
+}): string;
+/** The last assistant message of a run. */
+export declare function finalText(events: readonly RunEvent[]): string;
+/** The run's cost so far, from its last usage report. */
+export declare function costOf(events: readonly RunEvent[]): number;

package/dist/sdk/refine/trajectory.js

@@ -0,0 +1,73 @@
+const TRUNC = (n) => `…(+${n} chars — render truncation)`;
+function clip(text, limit) {
+    const clean = text.replace(/\0/g, '');
+    return limit > 0 && clean.length > limit ? `${clean.slice(0, limit)}${TRUNC(clean.length - limit)}` : clean;
+}
+export function renderEvents(events, options) {
+    const out = [];
+    const argsTrunc = options.argsTrunc ?? 2000;
+    for (const event of events) {
+        const payload = (event.payload ?? {});
+        switch (event.type) {
+            case 'message.completed':
+                if (typeof payload.text === 'string' && payload.text.trim())
+                    out.push(`[${payload.role === 'user' ? 'USER' : 'ASSISTANT'}]\n${clip(payload.text, options.obsTrunc)}`);
+                break;
+            case 'tool.started':
+                out.push(`[ACTION] ${String(payload.name ?? 'tool')}${typeof payload.input === 'string' && payload.input ? ` ${clip(payload.input, argsTrunc)}` : ''}`);
+                break;
+            case 'tool.completed': {
+                const text = typeof payload.output === 'string' ? payload.output : '';
+                out.push(`${payload.ok === false ? '[ERROR]' : '[OBSERVATION]'} ${String(payload.name ?? 'tool')}${typeof payload.durationMs === 'number' ? ` (${Math.round(payload.durationMs)} ms)` : ''}\n${clip(text, options.obsTrunc)}${payload.outputTruncated ? '\n(the tool output was already bounded when it was recorded)' : ''}`);
+                break;
+            }
+            case 'tool.refused':
+                out.push(`[ERROR] ${String(payload.name ?? 'tool')} refused${typeof payload.code === 'string' ? ` (${payload.code})` : ''}${typeof payload.reason === 'string' && payload.reason ? `: ${clip(payload.reason, options.obsTrunc)}` : ''}`);
+                break;
+            case 'retry.started':
+                out.push(`[ERROR] model request failed, retrying (${String(payload.attempt)}/${String(payload.maxAttempts)}): ${String(payload.error ?? '')}`);
+                break;
+            case 'compaction.ended':
+                out.push(`[ACTION] context compacted (${String(payload.reason ?? '')})${typeof payload.tokensBefore === 'number' ? `: ${payload.tokensBefore} → ${String(payload.tokensAfter ?? '?')} tokens` : ''}`);
+                break;
+            case 'approval.resolved':
+                if (payload.decision === 'denied')
+                    out.push('[ERROR] a tool call was refused');
+                break;
+            case 'extension.notice':
+                if (typeof payload.text === 'string')
+                    out.push(`[OBSERVATION] notice: ${clip(payload.text, 2000)}`);
+                break;
+            case 'failed':
+                out.push(`[ERROR] run failed: ${String(payload.message ?? payload.code ?? '')}`);
+                break;
+            case 'status.changed':
+                if (payload.status === 'interrupted') {
+                    const reason = typeof payload.reason === 'string' && payload.reason ? payload.reason : typeof payload.code === 'string' ? payload.code : '';
+                    out.push(`[ERROR] run interrupted${reason ? `: ${clip(reason, options.obsTrunc)}` : ''}`);
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    return out.length ? out.join('\n\n') : '(no trajectory: the run recorded no messages or tool use)';
+}
+/** The last assistant message of a run. */
+export function finalText(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const payload = events[i].payload;
+        if (events[i].type === 'message.completed' && payload?.role === 'assistant' && typeof payload.text === 'string' && payload.text.trim())
+            return payload.text;
+    }
+    return '';
+}
+/** The run's cost so far, from its last usage report. */
+export function costOf(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const payload = events[i].payload;
+        if (events[i].type === 'usage.updated' && typeof payload?.costUsd === 'number')
+            return payload.costUsd;
+    }
+    return 0;
+}