@xingular/harness 0.1.6 → 1.0.0

package/dist/sdk/refine/recursion.js

@@ -0,0 +1,258 @@
+// Task-level recursion, parallel and sequential. Each mode schedules 4k rollouts and 3k
+// improvement stages, including the shared base executions. An invalid proposal gets one retry
+// with the validator's message, then inherits the current harness.
+//
+// Ported from Harness² (Apache-2.0, Google LLC; `harness2/core/recursion.py`).
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { PI_SURFACE } from "../variant/surface.js";
+import { autotrigger, diversity, isUnchanged, readVariant, VariantError, validate, writeVariant } from "../variant/variant.js";
+import * as evidence from "./evidence.js";
+import { Ledger } from "./ledger.js";
+import * as P from "./prompts.js";
+import { ImproverError } from "./types.js";
+export const STAGE_ATTEMPTS = 2;
+export function modeRecord(result) {
+    return {
+        mode: result.mode,
+        taskId: result.taskId,
+        k: result.k,
+        finals: result.finals,
+        ok: result.finals.length > 0 && result.errors.length === 0,
+        fellBack: result.stages.filter((stage) => stage.fellBack).map((stage) => stage.label),
+        keptBase: result.stages.filter((stage) => stage.keptBase).map((stage) => stage.label),
+        stages: result.stages.map(({ variant: _tree, ...rest }) => ({ ...rest, error: rest.error.slice(0, 400) })),
+        similarity: result.similarity,
+        ledger: result.ledger.toRecord(),
+        errors: result.errors
+    };
+}
+/** Runs `fn` over `items` with at most `width` at a time, keeping input order in the result. */
+export async function mapLimit(items, width, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.max(1, Math.min(width, items.length)) }, async () => {
+        while (next < items.length) {
+            const i = next++;
+            out[i] = await fn(items[i]);
+        }
+    });
+    await Promise.all(workers);
+    return out;
+}
+function checkAborted(signal) {
+    if (signal?.aborted)
+        throw new Error('Refinement was cancelled.');
+}
+/** Repairs, then validates, a proposed variant. Returns whether it equals the fallback and any error. */
+export function acceptVariant(task, executor, next, fallback) {
+    autotrigger(PI_SURFACE, next);
+    const keptBase = isUnchanged(PI_SURFACE, fallback, next);
+    try {
+        validate(PI_SURFACE, next, { allowSubagents: task.allowSubagents !== false });
+        executor.validateVariant?.(task, next);
+        evidence.assertVariantHasNoGraderVerdicts(next);
+    }
+    catch (error) {
+        return { keptBase, error: error instanceof VariantError ? error.problems.join(' | ') : error instanceof Error ? error.message : String(error) };
+    }
+    return { keptBase, error: '' };
+}
+/** Builds evidence, asks for an edit, and retries an invalid one once. Never throws. */
+export async function runStage(ctx, input) {
+    const { label, dim, fallback } = input;
+    ctx.onEvent?.({ type: 'stage.started', label, dim });
+    const finish = (stage) => {
+        ctx.onEvent?.({ type: 'stage.finished', label, dim, fellBack: stage.fellBack, keptBase: stage.keptBase, error: stage.error });
+        return stage;
+    };
+    let folder;
+    let mission;
+    try {
+        folder = evidence.build(join(ctx.workDir, 'context', label), {
+            task: ctx.task,
+            executor: ctx.executor,
+            rollouts: input.rollouts,
+            variantDir: input.variantDir,
+            libraryDir: ctx.libraryDir,
+            pool: input.pool,
+            decisions: input.decisions
+        });
+        mission = evidence.mission(folder, input.job);
+    }
+    catch (error) {
+        return finish({ label, dim, variant: { ...fallback }, keptBase: false, fellBack: true, error: `could not build evidence: ${error instanceof Error ? error.message : String(error)}`.slice(0, 400), usd: 0, attempts: 0, cached: false, notes: '' });
+    }
+    let err = '';
+    let usd = 0;
+    let attempts = 0;
+    let allCached = true;
+    for (let attempt = 1; attempt <= STAGE_ATTEMPTS; attempt++) {
+        if (ctx.signal?.aborted) {
+            err = 'cancelled';
+            break;
+        }
+        let reply;
+        try {
+            reply = await ctx.improver.call({
+                mission: mission + (err ? `\n\n# YOUR PREVIOUS ATTEMPT WAS REJECTED\n\n${err}\n\nFix it in \`context/harness/\` and reply again.` : ''),
+                contextDir: folder.root,
+                label: `${label}.a${attempt}`,
+                harvest: 'context/harness',
+                signal: ctx.signal
+            });
+        }
+        catch (error) {
+            err = error instanceof Error ? error.message : String(error);
+            attempts += error instanceof ImproverError ? error.attempts || 1 : 1;
+            usd += error instanceof ImproverError ? error.costUsd : 0;
+            allCached = false;
+            break;
+        }
+        usd += reply.costUsd;
+        attempts += reply.cached ? 0 : Math.max(1, reply.attempts);
+        allCached = allCached && reply.cached;
+        if (!reply.workspace || !existsSync(reply.workspace)) {
+            err = 'the harness directory did not come back from the session; edit the files in `context/harness/` in place';
+            continue;
+        }
+        const rejected = [];
+        const next = readVariant(PI_SURFACE, reply.workspace, rejected);
+        if (!Object.keys(next).length) {
+            err = '`context/harness/` came back empty -- edit the files, do not delete them all';
+            continue;
+        }
+        if (rejected.length) {
+            err = `these files are off the editable surface and were not applied: ${rejected.sort().slice(0, 6).join(', ')}. Component names must be lowercase letters, digits, \`_\` or \`-\` (e.g. \`skills/doc_review/SKILL.md\`, \`scripts/check_totals.py\`).`;
+            continue;
+        }
+        const accepted = acceptVariant(ctx.task, ctx.executor, next, fallback);
+        if (accepted.error) {
+            err = accepted.error;
+            // The next attempt edits what came back, so it fixes rather than restarts.
+            writeVariant(PI_SURFACE, next, join(folder.root, 'harness'));
+            continue;
+        }
+        const notes = /<notes>([\s\S]*?)<\/notes>/.exec(reply.text)?.[1]?.trim() ?? reply.text.trim();
+        return finish({ label, dim, variant: next, keptBase: accepted.keptBase, fellBack: false, error: '', usd, attempts, cached: allCached, notes });
+    }
+    return finish({ label, dim, variant: { ...fallback }, keptBase: false, fellBack: true, error: err.slice(0, 400), usd, attempts, cached: allCached, notes: '' });
+}
+function recordSessions(ledger, stages) {
+    for (const stage of stages)
+        ledger.session(stage.label, stage.usd, { cached: stage.cached, attempts: stage.attempts });
+}
+/** Writes a harness and rolls it once. A dead rollout is recorded, never thrown. */
+async function roll(ctx, label, variant) {
+    const variantDir = writeVariant(PI_SURFACE, variant, join(ctx.workDir, 'variants', label));
+    const runId = ctx.runIdOf(label);
+    ctx.onEvent?.({ type: 'rollout.started', label });
+    let rollout;
+    try {
+        checkAborted(ctx.signal);
+        rollout = await ctx.executor.execute(ctx.task, variantDir, label, runId);
+    }
+    catch (error) {
+        rollout = { label, runId, dir: join(ctx.workDir, 'missing', label), ok: false, delivered: false, costUsd: 0, wallMs: 0, error: error instanceof Error ? error.message : String(error) };
+    }
+    ctx.onEvent?.({ type: 'rollout.finished', label, ok: rollout.ok, delivered: rollout.delivered, error: rollout.error });
+    return rollout;
+}
+/** Rolls independent harnesses concurrently, then records them in the caller's order. */
+async function rollMany(ctx, ledger, items) {
+    const got = await mapLimit(items, ctx.rolloutWidth ?? 4, ([label, variant]) => roll(ctx, label, variant));
+    const out = {};
+    items.forEach(([label], i) => {
+        ledger.rollout(label, got[i].costUsd);
+        out[label] = got[i];
+    });
+    return out;
+}
+function newResult(mode, ctx, k, base) {
+    const ledger = new Ledger(mode, ctx.task.id, k);
+    for (const rollout of base)
+        ledger.rollout(rollout.label, rollout.costUsd);
+    return { mode, taskId: ctx.task.id, k, stages: [], variants: {}, rollouts: Object.fromEntries(base.map((rollout) => [rollout.label, rollout])), finals: [], ledger, similarity: null, errors: [] };
+}
+const variantPath = (ctx, label) => join(ctx.workDir, 'variants', label);
+/** WIDTH: 2k independent candidates from shared evidence, then k independent compositions. */
+export async function runParallel(ctx, k, base) {
+    const result = newResult('agg', ctx, k, base);
+    const prompts = ctx.task.prompts ?? defaultPrompts();
+    const baseDir = writeVariant(PI_SURFACE, ctx.baseVariant, variantPath(ctx, 'base'));
+    const specs = [];
+    for (let i = 1; i <= k; i++)
+        for (const dim of ['INV', 'DOM'])
+            specs.push([`${dim.toLowerCase()}${i}`, dim, i]);
+    const stages = await mapLimit(specs, ctx.proposeWidth ?? 4, ([label, dim, index]) => runStage(ctx, { label, dim, job: P.propose(prompts, dim, { k, index }), fallback: ctx.baseVariant, rollouts: base, variantDir: baseDir }));
+    recordSessions(result.ledger, stages);
+    for (const stage of stages) {
+        result.stages.push(stage);
+        result.variants[stage.label] = stage.variant;
+    }
+    Object.assign(result.rollouts, await rollMany(ctx, result.ledger, stages.map((stage) => [stage.label, stage.variant])));
+    const pool = stages.map((stage) => ({ label: stage.label, variantDir: variantPath(ctx, stage.label), rollout: result.rollouts[stage.label] ?? null }));
+    const decisions = Object.fromEntries(stages.map((stage) => [stage.label, stage.notes || stage.error]));
+    const aggs = await mapLimit(Array.from({ length: k }, (_, i) => i + 1), ctx.proposeWidth ?? 4, (index) => runStage(ctx, { label: `agg${index}`, dim: 'AGG', job: P.aggregate(prompts, { k, index }), fallback: ctx.baseVariant, rollouts: base, variantDir: baseDir, pool, decisions }));
+    recordSessions(result.ledger, aggs);
+    for (const stage of aggs) {
+        result.stages.push(stage);
+        result.variants[stage.label] = stage.variant;
+        result.finals.push(stage.label);
+    }
+    Object.assign(result.rollouts, await rollMany(ctx, result.ledger, aggs.map((stage) => [stage.label, stage.variant])));
+    result.similarity = diversity(Object.fromEntries(aggs.map((stage) => [stage.label, stage.variant])));
+    result.ledger.assertIdentity();
+    return result;
+}
+/** DEPTH: k nested passes over the same shared base evidence. */
+export async function runSequential(ctx, k, base) {
+    const result = newResult('seq', ctx, k, base);
+    const prompts = ctx.task.prompts ?? defaultPrompts();
+    let current = { ...ctx.baseVariant };
+    let history = [];
+    for (let t = 1; t <= k; t++) {
+        checkAborted(ctx.signal);
+        const currentLabel = t > 1 ? `c${t - 1}` : 'base';
+        const currentDir = writeVariant(PI_SURFACE, current, variantPath(ctx, currentLabel));
+        const decisions = () => Object.fromEntries(result.stages.map((stage) => [stage.label, stage.notes || stage.error]));
+        const specs = [[`inv${t}`, 'INV'], [`dom${t}`, 'DOM']];
+        const before = decisions();
+        const fallback = current;
+        const stages = await mapLimit(specs, Math.min(2, ctx.proposeWidth ?? 2), ([label, dim]) => runStage(ctx, { label, dim, job: P.propose(prompts, dim, { k, index: t, roundT: k > 1 ? t : null }), fallback, rollouts: base, variantDir: currentDir, pool: [...history], decisions: before }));
+        recordSessions(result.ledger, stages);
+        for (const stage of stages) {
+            result.stages.push(stage);
+            result.variants[stage.label] = stage.variant;
+        }
+        Object.assign(result.rollouts, await rollMany(ctx, result.ledger, stages.map((stage) => [stage.label, stage.variant])));
+        const roundPool = [...history, ...stages.map((stage) => ({ label: stage.label, variantDir: variantPath(ctx, stage.label), rollout: result.rollouts[stage.label] ?? null }))];
+        const ck = `c${t}`;
+        const job = k === 1 ? P.aggregate(prompts, { k: 1, index: 1 }) : P.composeRound(prompts, { t, k });
+        const comp = await runStage(ctx, { label: ck, dim: 'COMPOSE', job, fallback: current, rollouts: base, variantDir: currentDir, pool: roundPool, decisions: decisions() });
+        recordSessions(result.ledger, [comp]);
+        result.stages.push(comp);
+        result.variants[ck] = comp.variant;
+        const rolled = await roll(ctx, ck, comp.variant);
+        result.ledger.rollout(ck, rolled.costUsd);
+        result.rollouts[ck] = rolled;
+        history = [...roundPool, { label: ck, variantDir: variantPath(ctx, ck), rollout: rolled }];
+        current = comp.variant;
+    }
+    result.finals = Array.from({ length: k }, (_, i) => `c${i + 1}`);
+    result.ledger.assertIdentity();
+    return result;
+}
+export function defaultPrompts() {
+    return {
+        work: 'The work is the request in `context/task.md`, done for the person who asked for it, with the tools this agent has.',
+        domainWord: 'area'
+    };
+}
+export function runMode(mode, ctx, k, base) {
+    return mode === 'parallel' ? runParallel(ctx, k, base) : runSequential(ctx, k, base);
+}
+/** Reads a harness a stage wrote, for callers that hold only labels. */
+export function stageVariant(workDir, label) {
+    return readVariant(PI_SURFACE, variantPath({ workDir }, label));
+}

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

@@ -0,0 +1,81 @@
+import { type Variant } from "../variant/surface.js";
+import { type Experience } from "./library.js";
+import type { LedgerRecord } from "./ledger.js";
+import { type ModeRecord, type RecursionEvent } from "./recursion.js";
+import { type Selection } from "./selection.js";
+import type { Executor, Improver, RecursionMode, RefineTask } from "./types.js";
+export type RefineStatus = 'running' | 'ok' | 'partial' | 'failed' | 'cancelled';
+export interface RefineSummary {
+    id: string;
+    taskId: string;
+    scope: string;
+    area: string;
+    k: number;
+    mode: RecursionMode;
+    status: RefineStatus;
+    startedAt: string;
+    endedAt: string | null;
+    /** The head the refinement started from. */
+    baseFingerprint: string;
+    base: {
+        label: string;
+        runId: string;
+        ok: boolean;
+        delivered: boolean;
+        error: string;
+    }[];
+    recursion: ModeRecord | null;
+    selection: Selection | null;
+    /** The chosen harness, saved as a version of the scope without moving its head; null when it is the base. */
+    chosenFingerprint: string | null;
+    chosenIsBase: boolean;
+    libraryEntry: string | null;
+    experience: Partial<Experience> | null;
+    usd: number;
+    errors: string[];
+    /** The executor and improver settings the refinement was started with (PROP-0003). Run records hold what each run resolved. */
+    settings?: {
+        executor: RefineSettings | null;
+        improver: RefineSettings | null;
+    };
+}
+export interface RefineSettings {
+    model?: string | null;
+    effort?: string | null;
+    accountId?: string | null;
+    poolId?: string | null;
+}
+export type RefineEvent = RecursionEvent | {
+    type: 'phase';
+    phase: 'base' | 'recursion' | 'selection' | 'reflection' | 'done';
+} | {
+    type: 'summary';
+    summary: RefineSummary;
+};
+export interface RefineRunInput {
+    root: string;
+    id: string;
+    task: RefineTask;
+    k: number;
+    mode: RecursionMode;
+    executor: Executor;
+    improver: Improver;
+    /** The selector; defaults to the improver. */
+    selector?: Improver;
+    /** The harness to start from. Defaults to the scope's head. */
+    baseVariant?: Variant;
+    proposeWidth?: number;
+    rolloutWidth?: number;
+    /** Recorded on the summary only; the executor and improver already carry them. */
+    settings?: {
+        executor: RefineSettings | null;
+        improver: RefineSettings | null;
+    };
+    onEvent?: (event: RefineEvent) => void;
+    signal?: AbortSignal;
+}
+export declare function refineDir(root: string, id: string): string;
+export declare function readSummary(root: string, id: string): RefineSummary | null;
+/** Runs one refinement to the end. Failures are recorded on the summary; only bad input throws. */
+export declare function runRefinement(input: RefineRunInput): Promise<RefineSummary>;
+export type { LedgerRecord };

package/dist/sdk/refine/runner.js

@@ -0,0 +1,150 @@
+// One refinement: k shared base executions on the current harness, one recursion mode, blind
+// selection of a final, reflection, and a library entry. Everything is written under
+// `<data>/refine/<id>/` as it happens; `summary.json` is the record a person or an application
+// reads.
+//
+// Shaped after Harness² (Apache-2.0, Google LLC; `harness2/core/schedule.py::run_task`).
+import { join } from 'node:path';
+import { now, readJson, safeId, writeJson } from "../core/fs.js";
+import * as store from "../variant/store.js";
+import { PI_SURFACE } from "../variant/surface.js";
+import { isUnchanged, writeVariant } from "../variant/variant.js";
+import { Library, hasExperience } from "./library.js";
+import { mapLimit, modeRecord, runMode } from "./recursion.js";
+import { reflectAdoption, runSelection, selectionPool, trivialSelection } from "./selection.js";
+export function refineDir(root, id) {
+    return join(root, 'refine', safeId(id));
+}
+export function readSummary(root, id) {
+    return readJson(join(refineDir(root, id), 'summary.json'));
+}
+const modeToken = (mode) => (mode === 'parallel' ? 'agg' : 'seq');
+/** Runs one refinement to the end. Failures are recorded on the summary; only bad input throws. */
+export async function runRefinement(input) {
+    const { root, id, task, k, mode, executor, improver } = input;
+    if (!Number.isInteger(k) || k < 1 || k > 8)
+        throw new Error('k must be a whole number from 1 to 8.');
+    safeId(task.scope);
+    const workDir = refineDir(root, id);
+    const area = task.domain ?? task.scope;
+    const baseVariant = input.baseVariant ?? store.headVariant(root, task.scope)?.variant;
+    if (!baseVariant)
+        throw new Error(`The harness '${task.scope}' has no version to start from.`);
+    const baseFingerprint = store.fingerprint(baseVariant);
+    const library = new Library(root, task.scope, area);
+    const runIdOf = (label) => `${id}-${label}`;
+    const emit = (event) => input.onEvent?.(event);
+    const summary = {
+        id,
+        taskId: task.id,
+        scope: task.scope,
+        area,
+        k,
+        mode,
+        status: 'running',
+        startedAt: now(),
+        endedAt: null,
+        baseFingerprint,
+        base: [],
+        recursion: null,
+        selection: null,
+        chosenFingerprint: null,
+        chosenIsBase: false,
+        libraryEntry: null,
+        experience: null,
+        usd: 0,
+        errors: [],
+        ...(input.settings ? { settings: input.settings } : {})
+    };
+    const save = () => {
+        writeJson(join(workDir, 'summary.json'), summary);
+        emit({ type: 'summary', summary: structuredClone(summary) });
+    };
+    const finish = (status) => {
+        summary.status = input.signal?.aborted ? 'cancelled' : status;
+        summary.endedAt = now();
+        save();
+        emit({ type: 'phase', phase: 'done' });
+        return summary;
+    };
+    writeJson(join(workDir, 'task.json'), { task, k, mode });
+    save();
+    // The library a refinement reads is the one before it, so the record of what it read is stable.
+    const libraryDir = library.contextDir();
+    emit({ type: 'phase', phase: 'base' });
+    const baseDir = writeVariant(PI_SURFACE, baseVariant, join(workDir, 'variants', 'base'));
+    const labels = Array.from({ length: k }, (_, i) => `base${i + 1}`);
+    const base = await mapLimit(labels, input.rolloutWidth ?? 4, async (label) => {
+        emit({ type: 'rollout.started', label });
+        let rollout;
+        try {
+            if (input.signal?.aborted)
+                throw new Error('Refinement was cancelled.');
+            rollout = await executor.execute(task, baseDir, label, runIdOf(label));
+        }
+        catch (error) {
+            rollout = { label, runId: runIdOf(label), dir: join(workDir, 'missing', label), ok: false, delivered: false, costUsd: 0, wallMs: 0, error: error instanceof Error ? error.message : String(error) };
+        }
+        emit({ type: 'rollout.finished', label, ok: rollout.ok, delivered: rollout.delivered, error: rollout.error });
+        return rollout;
+    });
+    summary.base = base.map((r) => ({ label: r.label, runId: r.runId, ok: r.ok, delivered: r.delivered, error: r.error }));
+    if (!base.some((rollout) => rollout.ok)) {
+        summary.errors.push('no base rollout produced anything');
+        summary.usd = base.reduce((sum, r) => sum + r.costUsd, 0);
+        return finish('failed');
+    }
+    save();
+    emit({ type: 'phase', phase: 'recursion' });
+    let result;
+    try {
+        result = await runMode(mode, { task, executor, improver, workDir, runIdOf, baseVariant, libraryDir, proposeWidth: input.proposeWidth, rolloutWidth: input.rolloutWidth, onEvent: emit, signal: input.signal }, k, base);
+    }
+    catch (error) {
+        summary.errors.push(`${mode}: ${error instanceof Error ? error.message : String(error)}`);
+        return finish(input.signal?.aborted ? 'cancelled' : 'failed');
+    }
+    summary.recursion = modeRecord(result);
+    summary.usd = result.ledger.usd();
+    save();
+    emit({ type: 'phase', phase: 'selection' });
+    const token = modeToken(mode);
+    const candidates = selectionPool(token, k, result.rollouts);
+    const sel = k === 1
+        ? trivialSelection({ task, k, mode: token, candidates, executor, workDir })
+        : await runSelection({ task, k, mode: token, candidates, executor, improver: input.selector ?? improver, workDir, signal: input.signal });
+    summary.selection = sel;
+    if (!sel.ok)
+        summary.errors.push(`${mode}: selection failed: ${sel.error}`);
+    const chosen = candidates[sel.chosenLabel];
+    if (chosen && !chosen.delivered)
+        summary.errors.push(`${mode}: selected run ${chosen.runId} produced no deliverable`);
+    const chosenVariant = result.variants[sel.chosenLabel] ?? baseVariant;
+    summary.chosenIsBase = isUnchanged(PI_SURFACE, baseVariant, chosenVariant);
+    if (sel.chosenLabel && !summary.chosenIsBase) {
+        try {
+            summary.chosenFingerprint = store.commit(root, task.scope, chosenVariant, { kind: 'refinement', refineId: id, label: sel.chosenLabel, note: sel.why.slice(0, 500) }, { moveHead: false }).fingerprint;
+        }
+        catch (error) {
+            summary.errors.push(`could not save the chosen harness: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    save();
+    if (sel.ok) {
+        emit({ type: 'phase', phase: 'reflection' });
+        const decisions = Object.fromEntries(result.stages.map((stage) => [stage.label, stage.notes || stage.error]));
+        const experience = await reflectAdoption({ task, selection: sel, rollouts: result.rollouts, executor, improver: input.selector ?? improver, workDir, baseVariant, decisions, signal: input.signal });
+        summary.experience = Object.keys(experience).length ? experience : null;
+        if (hasExperience(experience)) {
+            try {
+                summary.libraryEntry = library.add(task.id, chosenVariant, { why: sel.why, label: sel.chosenLabel, runId: sel.chosenRunId, experience });
+            }
+            catch (error) {
+                summary.errors.push(`could not add to the library: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    summary.usd = Math.round((result.ledger.usd() + sel.usd) * 1e6) / 1e6;
+    const ok = summary.recursion.ok && sel.ok && Boolean(sel.chosenLabel) && !summary.errors.length;
+    return finish(ok ? 'ok' : sel.chosenLabel ? 'partial' : 'failed');
+}

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

@@ -0,0 +1,57 @@
+import { type Variant } from "../variant/surface.js";
+import type { Experience } from "./library.js";
+import { type Executor, type Improver, type RefineTask, type Rollout } from "./types.js";
+export interface Selection {
+    taskId: string;
+    mode: 'agg' | 'seq';
+    k: number;
+    chosenId: string;
+    chosenLabel: string;
+    chosenRunId: string;
+    chosenDir: string;
+    why: string;
+    idMap: Record<string, string>;
+    dropped: string[];
+    candidates: number;
+    ok: boolean;
+    fallback: boolean;
+    trivial: boolean;
+    error: string;
+    usd: number;
+    experience: Partial<Experience>;
+}
+/** A..Z, AA..AZ, BA...: always accepted by the choice parser. */
+export declare function anonId(index: number): string;
+/** anon id → label, by canonical sort then a seeded shuffle. */
+export declare function assignIds(labels: readonly string[], taskId: string, k: number, mode: string): Record<string, string>;
+/** Exactly the k finals of a mode: agg1..aggk or c1..ck. The base executions are never in it. */
+export declare function selectionPool(mode: 'agg' | 'seq', k: number, rollouts: Record<string, Rollout>): Record<string, Rollout>;
+export interface SelectInput {
+    task: RefineTask;
+    k: number;
+    mode: 'agg' | 'seq';
+    candidates: Record<string, Rollout>;
+    executor: Executor;
+    improver: Improver;
+    workDir: string;
+    signal?: AbortSignal;
+}
+/** Picks one output. A selector failure falls back to the first final and never throws. */
+export declare function runSelection(input: SelectInput): Promise<Selection>;
+/** Delivers the single k=1 final without a selector session. */
+export declare function trivialSelection(input: Omit<SelectInput, 'improver' | 'signal'>): Selection;
+export interface ReflectInput {
+    task: RefineTask;
+    selection: Selection;
+    rollouts: Record<string, Rollout>;
+    executor: Executor;
+    improver: Improver;
+    workDir: string;
+    baseVariant: Variant;
+    decisions?: Record<string, string>;
+    signal?: AbortSignal;
+}
+/** Learns from the edits, decisions, trajectories and outputs after adoption. Never throws. */
+export declare function reflectAdoption(input: ReflectInput): Promise<Partial<Experience>>;
+/** Reads `<edits>` and `<experience>` blocks. A reply without a supported lesson gives only the edits. */
+export declare function parseExperience(text: string): Partial<Experience>;