@xingular/harness 0.1.6 → 1.0.0

package/dist/sdk/refine/demo.js

@@ -0,0 +1,114 @@
+// A deterministic local executor and improver that exercise the real refinement workflow with
+// no model and no credentials: the base harness sums only positive ledger amounts, and the
+// scripted improver removes that filter.
+//
+// Ported from Harness² (Apache-2.0, Google LLC; `harness2/demo.py`).
+import { spawnSync } from 'node:child_process';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+export const DEMO_SCRIPT = `import { readFileSync } from 'node:fs'
+
+const rows = readFileSync(process.argv[2], 'utf8').trim().split('\\n').slice(1)
+const cents = rows.map((row) => Math.round(Number(row) * 100))
+const total = cents.filter((amount) => amount > 0).reduce((sum, amount) => sum + amount, 0)
+console.log(\`Total: \${(total / 100).toFixed(2)}\`)
+`;
+export function demoBaseVariant() {
+    return {
+        'systemprompt.md': 'Reconcile the ledger using node scripts/summarize.mjs.\n',
+        'guardrails.md': '',
+        'memory.md': '',
+        'tool_guidance.md': '',
+        'scripts/summarize.mjs': DEMO_SCRIPT
+    };
+}
+export const DEMO_LEDGERS = {
+    'ledger-1': '100.25\n-20.10\n5.00\n',
+    'ledger-2': '35.50\n-10.25\n-5.00\n'
+};
+/** Writes the demo's source ledgers under `root` and returns the tasks. */
+export function demoTasks(root, scope = 'demo') {
+    return Object.entries(DEMO_LEDGERS).map(([id, amounts]) => {
+        const sourceDir = join(root, 'sources', id);
+        mkdirSync(sourceDir, { recursive: true });
+        writeFileSync(join(sourceDir, 'ledger.csv'), `amount\n${amounts}`);
+        writeFileSync(join(sourceDir, 'reference_answer.txt'), 'never shown to a model');
+        return {
+            id,
+            scope,
+            domain: 'accounting',
+            prompt: 'Sum every signed amount in ledger.csv. Return Total: with two decimal places.',
+            sourceDir,
+            leakGlobs: ['reference_answer.txt'],
+            prompts: { work: 'reconcile signed amounts in a transaction ledger' }
+        };
+    });
+}
+export class DemoExecutor {
+    root;
+    executions = 0;
+    constructor(root) {
+        this.root = root;
+    }
+    async execute(task, variantDir, label, runId) {
+        this.executions++;
+        const dir = join(this.root, 'executions', runId);
+        mkdirSync(dir, { recursive: true });
+        const script = join(variantDir ?? '', 'scripts', 'summarize.mjs');
+        const result = spawnSync(process.execPath, [script, join(task.sourceDir ?? '', 'ledger.csv')], { encoding: 'utf8', timeout: 10_000 });
+        if (result.status !== 0) {
+            return { label, runId, dir, ok: false, delivered: false, costUsd: 0, wallMs: 0, error: result.stderr || 'script failed' };
+        }
+        writeFileSync(join(dir, 'answer.txt'), result.stdout);
+        writeFileSync(join(dir, 'trajectory.md'), `[ACTION] Run scripts/summarize.mjs on ledger.csv\n[OBSERVATION]\n${result.stdout}`);
+        return { label, runId, dir, ok: true, delivered: true, costUsd: 0, wallMs: 0, error: '' };
+    }
+    trajectory(rollout) {
+        return readFileSync(join(rollout.dir, 'trajectory.md'), 'utf8');
+    }
+    deliverableFiles(rollout) {
+        const path = join(rollout.dir, 'answer.txt');
+        return existsSync(path) ? { 'answer.txt': readFileSync(path, 'utf8') } : {};
+    }
+    validateVariant(_task, variant) {
+        if (!variant['scripts/summarize.mjs'])
+            throw new Error('The local executor requires scripts/summarize.mjs');
+    }
+}
+function signedTotal(ledger) {
+    const cents = ledger.trim().split('\n').slice(1).map((row) => Math.round(Number(row) * 100));
+    return (cents.reduce((sum, amount) => sum + amount, 0) / 100).toFixed(2);
+}
+/** Scripted edits, selection and reflection. */
+export class DemoImprover {
+    calls = [];
+    async call(input) {
+        this.calls.push(input.label);
+        const context = input.contextDir;
+        let workspace = null;
+        let text;
+        if (input.label.startsWith('select.')) {
+            const expected = `Total: ${signedTotal(readFileSync(join(context, 'source', 'ledger.csv'), 'utf8'))}`;
+            const ids = readdirSync(join(context, 'candidates')).filter((name) => name.endsWith('.md')).sort();
+            const chosen = ids.find((name) => readFileSync(join(context, 'candidates', name), 'utf8').includes(expected))?.replace(/\.md$/, '') ?? ids[0].replace(/\.md$/, '');
+            text = `<why>The signed total matches the source ledger.</why>\n\`\`\`choice\n${chosen}\n\`\`\``;
+        }
+        else if (input.label.startsWith('experience.')) {
+            const changed = readFileSync(join(context, 'harness', 'scripts', 'summarize.mjs'), 'utf8') !== readFileSync(join(context, 'base_harness', 'scripts', 'summarize.mjs'), 'utf8');
+            text =
+                `<edits>\ncomponent: scripts/summarize.mjs\ncandidates: inv1\nchange: dropped the positive-only filter from the amount sum\nobserved: the probe total included the credits the base run omitted\nverdict: ${changed ? 'helped' : 'no observed effect'}\n</edits>\n\n` +
+                    (changed
+                        ? '<experience>\ncue: When a ledger includes credits and debits\nlesson: Include both signs when summing in scripts/summarize.mjs.\nevidence: The scripts/summarize.mjs row -- removing the positive-only filter changed the probe total to include the credits omitted by the base trajectory.\nconfidence: high for this observed arithmetic contrast\n</experience>'
+                        : 'NO_ENTRY');
+        }
+        else {
+            workspace = mkdtempSync(join(tmpdir(), 'harness-demo-'));
+            cpSync(join(context, 'harness'), workspace, { recursive: true });
+            const script = join(workspace, 'scripts', 'summarize.mjs');
+            writeFileSync(script, readFileSync(script, 'utf8').replace('.filter((amount) => amount > 0)', ''));
+            text = '<notes>Keep signed amounts: the base total omitted credits in the source ledger.</notes>';
+        }
+        return { label: input.label, text, costUsd: 0, attempts: 1, cached: false, workspace };
+    }
+}

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

@@ -0,0 +1,55 @@
+import { type Variant } from "../variant/surface.js";
+import type { Executor, RefineTask, Rollout } from "./types.js";
+/** Strings that only a grader's own output contains. A tripwire, not the defence itself. */
+export declare const GRADER_VERDICT_MARKERS: readonly ["deterministic_eval_summary", "deterministic_eval_result", "judge_scope_and_deterministic_status", "Judge findings on the rendered result", "\"passed_count\"", "\"pass_rate\"", "\"test_pass_rate\"", "review_verdict", "\"reviewVerdict\""];
+/** Minimum per-observation truncation; lower values fabricate defects. */
+export declare const MIN_OBS_TRUNC = 10000;
+/** Refuses a folder holding a path the task marks as an answer key. */
+export declare function assertNoLeakPaths(root: string, globs?: readonly string[]): void;
+/** Refuses a folder containing a grader's output, by file name and by content. */
+export declare function assertNoGraderVerdicts(root: string, markers?: readonly string[]): void;
+/** The same tripwire on a variant, before it is rolled or stored. */
+export declare function assertVariantHasNoGraderVerdicts(variant: Record<string, string>, markers?: readonly string[]): void;
+/** Copies the task's source material under `root/source`, minus answer-key paths. */
+export declare function copySource(task: RefineTask, root: string): number;
+/** A line-based unified diff, enough for a reader to see what changed. */
+export declare function unifiedDiff(before: Variant, after: Variant, fromLabel: string, toLabel: string): string;
+export interface PoolEntry {
+    label: string;
+    /** The candidate's harness folder, or null. */
+    variantDir: string | null;
+    rollout: Rollout | null;
+}
+export interface EvidenceFolder {
+    root: string;
+    taskId: string;
+    rollouts: string[];
+    deliverables: string[];
+    harnessFiles: number;
+    library: boolean;
+    pool: string[];
+    failed: string[];
+    sourceFiles: number;
+    decisions: number;
+}
+/** The evidence-layout listing that goes in a mission; it mentions only what exists. */
+export declare function layout(evidence: EvidenceFolder): string;
+export interface BuildInput {
+    task: RefineTask;
+    executor: Executor;
+    rollouts?: readonly Rollout[];
+    variantDir?: string | null;
+    libraryDir?: string | null;
+    pool?: readonly PoolEntry[];
+    decisions?: Record<string, string>;
+    obsTrunc?: number;
+}
+declare function renderDeliverable(executor: Executor, rollout: Rollout): string;
+export { renderDeliverable };
+/**
+ * Writes the evidence folder and returns what landed, so a mission describes only that. A
+ * trajectory is written in full; `obsTrunc` applies per observation.
+ */
+export declare function build(dest: string, input: BuildInput): EvidenceFolder;
+/** The short pointer to the evidence on disk: the job, where the evidence is, and the instruction to open it. */
+export declare function mission(evidence: EvidenceFolder, job: string): string;

package/dist/sdk/refine/evidence.js

@@ -0,0 +1,330 @@
+// The evidence folder an improver reads. Evidence is served as files and the prompt is a short
+// pointer, so nothing is truncated to fit a prompt:
+//
+//   context/task.md                  the task as the agent received it
+//   context/source/                  the material it was done from
+//   context/rollouts/<label>.md      full trajectories
+//   context/deliverables/<label>/    what each rollout produced
+//   context/harness/<rel>            the harness being edited
+//   context/library/INDEX.md         earlier tasks in this area and their full harnesses
+//   context/pool/<label>/            candidate harnesses, their diffs and rollouts
+//   context/decisions/<label>.md     earlier edit and composition notes
+//
+// Ported from Harness² (Apache-2.0, Google LLC; `harness2/core/context.py`).
+import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, relative, sep } from 'node:path';
+import { PI_SURFACE } from "../variant/surface.js";
+import { readVariant } from "../variant/variant.js";
+/** Strings that only a grader's own output contains. A tripwire, not the defence itself. */
+export const GRADER_VERDICT_MARKERS = [
+    'deterministic_eval_summary',
+    'deterministic_eval_result',
+    'judge_scope_and_deterministic_status',
+    'Judge findings on the rendered result',
+    '"passed_count"',
+    '"pass_rate"',
+    '"test_pass_rate"',
+    'review_verdict',
+    '"reviewVerdict"'
+];
+const SCANNED = new Set(['.md', '.txt', '.json', '.csv', '.tsv', '.yaml', '.yml', '.html', '.htm', '.log', '.py', '.js', '.mjs', '.ts', '.sh', '.xml', '.ini', '.toml', '.patch', '.diff', '']);
+/** Minimum per-observation truncation; lower values fabricate defects. */
+export const MIN_OBS_TRUNC = 10_000;
+function files(dir) {
+    const out = [];
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return out;
+    }
+    for (const name of names.sort()) {
+        const path = join(dir, name);
+        let isDir = false;
+        try {
+            isDir = statSync(path).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (isDir)
+            out.push(...files(path));
+        else
+            out.push(path);
+    }
+    return out;
+}
+function rel(root, path) {
+    return relative(root, path).split(sep).join('/');
+}
+function globToRegExp(glob) {
+    const pattern = glob.replace(/\\/g, '/').replace(/^\.\//, '');
+    let out = '';
+    for (const ch of pattern) {
+        if (ch === '*')
+            out += '[^]*';
+        else if (ch === '?')
+            out += '.';
+        else
+            out += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+    return new RegExp(`^(?:[^]*/)?${out}$`);
+}
+/** Refuses a folder holding a path the task marks as an answer key. */
+export function assertNoLeakPaths(root, globs = []) {
+    if (!globs.length || !existsSync(root))
+        return;
+    const rx = globs.map(globToRegExp);
+    const hits = files(root).map((path) => rel(root, path)).filter((path) => rx.some((r) => r.test(path)));
+    if (hits.length)
+        throw new Error(`answer-key path(s) would enter model context: ${hits.sort().slice(0, 8).join(', ')}`);
+}
+/** Refuses a folder containing a grader's output, by file name and by content. */
+export function assertNoGraderVerdicts(root, markers = GRADER_VERDICT_MARKERS) {
+    if (!existsSync(root))
+        return;
+    for (const path of files(root)) {
+        const name = rel(root, path);
+        for (const marker of markers) {
+            if (name.includes(marker))
+                throw new Error(`grader verdict would enter model context: '${name}' matched marker '${marker}' in its NAME. Find the read path that produced it.`);
+        }
+        if (!SCANNED.has(extname(path).toLowerCase()))
+            continue;
+        let body;
+        try {
+            body = readFileSync(path, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const marker of markers) {
+            const at = body.indexOf(marker);
+            if (at >= 0)
+                throw new Error(`grader verdict would enter model context: '${name}' contains marker '${marker}' at offset ${at}. Find the read path that produced it.`);
+        }
+    }
+}
+/** The same tripwire on a variant, before it is rolled or stored. */
+export function assertVariantHasNoGraderVerdicts(variant, markers = GRADER_VERDICT_MARKERS) {
+    for (const [name, body] of Object.entries(variant).sort()) {
+        for (const marker of markers) {
+            if (name.includes(marker))
+                throw new Error(`harness file '${name}' has grader-verdict marker '${marker}' in its NAME; rename it`);
+            if (SCANNED.has(extname(name).toLowerCase()) && body.includes(marker))
+                throw new Error(`harness file '${name}' contains grader-verdict marker '${marker}'; remove that string -- files carrying it cannot be served as evidence to later tasks`);
+        }
+    }
+}
+function copyFolder(src, dst) {
+    let n = 0;
+    for (const path of files(src)) {
+        if (path.includes(`${sep}__pycache__${sep}`) || path.endsWith('.pyc'))
+            continue;
+        const target = join(dst, relative(src, path));
+        mkdirSync(dirname(target), { recursive: true });
+        copyFileSync(path, target);
+        n++;
+    }
+    return n;
+}
+/** Copies the task's source material under `root/source`, minus answer-key paths. */
+export function copySource(task, root) {
+    const src = task.sourceDir;
+    if (!src || !existsSync(src))
+        return 0;
+    const leak = (task.leakGlobs ?? []).map(globToRegExp);
+    let n = 0;
+    for (const path of files(src)) {
+        const name = rel(src, path);
+        if (name.split('/').includes('__pycache__') || leak.some((r) => r.test(name)))
+            continue;
+        const target = join(root, 'source', name);
+        mkdirSync(dirname(target), { recursive: true });
+        copyFileSync(path, target);
+        n++;
+    }
+    if (n)
+        assertNoLeakPaths(join(root, 'source'), task.leakGlobs);
+    return n;
+}
+/** A line-based unified diff, enough for a reader to see what changed. */
+export function unifiedDiff(before, after, fromLabel, toLabel) {
+    const out = [];
+    for (const name of [...new Set([...Object.keys(before), ...Object.keys(after)])].sort()) {
+        const a = before[name] ?? '';
+        const b = after[name] ?? '';
+        if (a === b)
+            continue;
+        out.push(`--- ${fromLabel}/${name}`, `+++ ${toLabel}/${name}`);
+        const x = a ? a.split('\n') : [];
+        const y = b ? b.split('\n') : [];
+        // A longest-common-subsequence walk; variants are small enough for the quadratic table.
+        const dp = Array.from({ length: x.length + 1 }, () => new Array(y.length + 1).fill(0));
+        for (let i = x.length - 1; i >= 0; i--)
+            for (let j = y.length - 1; j >= 0; j--)
+                dp[i][j] = x[i] === y[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+        let i = 0;
+        let j = 0;
+        while (i < x.length || j < y.length) {
+            if (i < x.length && j < y.length && x[i] === y[j]) {
+                out.push(` ${x[i]}`);
+                i++;
+                j++;
+            }
+            else if (j < y.length && (i >= x.length || dp[i][j + 1] >= dp[i + 1][j])) {
+                out.push(`+${y[j]}`);
+                j++;
+            }
+            else {
+                out.push(`-${x[i]}`);
+                i++;
+            }
+        }
+    }
+    return out.length ? `${out.join('\n')}\n` : '';
+}
+/** The evidence-layout listing that goes in a mission; it mentions only what exists. */
+export function layout(evidence) {
+    const lines = ['context/task.md                  the task as the agent received it'];
+    if (evidence.sourceFiles)
+        lines.push('context/source/                 task source materials');
+    if (evidence.decisions)
+        lines.push('context/decisions/              earlier edits and composition decisions');
+    if (evidence.rollouts.length) {
+        const names = evidence.rollouts.slice(0, 6).map((label) => `${label}.md`).join(', ');
+        const more = evidence.rollouts.length > 6 ? ` (+${evidence.rollouts.length - 6} more)` : '';
+        lines.push(`context/rollouts/               FULL trajectories: ${names}${more}`);
+    }
+    if (evidence.deliverables.length)
+        lines.push('context/deliverables/<label>/    the files each rollout produced, one per artifact (browse INDEX.md for the set)');
+    if (evidence.harnessFiles)
+        lines.push(`context/harness/                the harness you are editing (${evidence.harnessFiles} files)`);
+    if (evidence.pool.length)
+        lines.push(`context/pool/                   ${evidence.pool.length} candidates, each with its harness and its rollout`);
+    if (evidence.library)
+        lines.push('context/library/                earlier tasks in this area -- browse INDEX.md first, then open what looks relevant');
+    return lines.join('\n');
+}
+function writeRollout(dest, rollout, executor, obsTrunc) {
+    let failure = '';
+    mkdirSync(join(dest, 'rollouts'), { recursive: true });
+    try {
+        writeFileSync(join(dest, 'rollouts', `${rollout.label}.md`), executor.trajectory(rollout, { obsTrunc }));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        writeFileSync(join(dest, 'rollouts', `${rollout.label}.md`), `(trajectory unavailable: ${message})`);
+        failure = `${rollout.label}: ${message}`;
+    }
+    const dir = join(dest, 'deliverables', rollout.label);
+    mkdirSync(dir, { recursive: true });
+    let produced = {};
+    try {
+        produced = executor.deliverableFiles(rollout);
+    }
+    catch (error) {
+        produced = { 'unavailable.md': `(deliverable unavailable: ${error instanceof Error ? error.message : String(error)})` };
+    }
+    const names = Object.keys(produced).sort();
+    for (const name of names) {
+        const target = join(dir, name);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, produced[name]);
+    }
+    writeFileSync(join(dir, 'INDEX.md'), names.length ? `# ${rollout.label} produced ${names.length} file(s)\n\n${names.map((name) => `- \`${name}\``).join('\n')}\n` : `# ${rollout.label} produced nothing\n`);
+    return failure;
+}
+function renderDeliverable(executor, rollout) {
+    const produced = executor.deliverableFiles(rollout);
+    const names = Object.keys(produced).sort();
+    if (!names.length)
+        return '';
+    if (names.length === 1)
+        return produced[names[0]];
+    return names.map((name) => `## ${name}\n\n${produced[name]}`).join('\n\n');
+}
+export { renderDeliverable };
+/**
+ * Writes the evidence folder and returns what landed, so a mission describes only that. A
+ * trajectory is written in full; `obsTrunc` applies per observation.
+ */
+export function build(dest, input) {
+    const { task, executor } = input;
+    rmSync(dest, { recursive: true, force: true });
+    mkdirSync(dest, { recursive: true });
+    const obsTrunc = Math.max(input.obsTrunc ?? 50_000, MIN_OBS_TRUNC);
+    writeFileSync(join(dest, 'task.md'), task.prompt);
+    const sourceFiles = copySource(task, dest);
+    for (const [label, notes] of Object.entries(input.decisions ?? {})) {
+        mkdirSync(join(dest, 'decisions'), { recursive: true });
+        writeFileSync(join(dest, 'decisions', `${label}.md`), notes || 'No decision notes returned.');
+    }
+    const rollouts = [];
+    const deliverables = [];
+    const failed = [];
+    for (const rollout of input.rollouts ?? []) {
+        const failure = writeRollout(dest, rollout, executor, obsTrunc);
+        if (failure)
+            failed.push(failure);
+        else
+            rollouts.push(rollout.label);
+        deliverables.push(rollout.label);
+    }
+    let harnessFiles = 0;
+    if (input.variantDir && existsSync(input.variantDir)) {
+        assertNoLeakPaths(input.variantDir, task.leakGlobs);
+        harnessFiles = copyFolder(input.variantDir, join(dest, 'harness'));
+    }
+    const pool = [];
+    for (const entry of input.pool ?? []) {
+        const dir = join(dest, 'pool', entry.label);
+        mkdirSync(dir, { recursive: true });
+        if (entry.variantDir && existsSync(entry.variantDir)) {
+            assertNoLeakPaths(entry.variantDir, task.leakGlobs);
+            copyFolder(entry.variantDir, join(dir, 'harness'));
+            const reference = readVariant(PI_SURFACE, join(dest, 'harness'));
+            const candidate = readVariant(PI_SURFACE, entry.variantDir);
+            writeFileSync(join(dir, 'harness.diff'), unifiedDiff(reference, candidate, 'current', entry.label));
+        }
+        if (entry.rollout) {
+            try {
+                writeFileSync(join(dir, 'rollout.md'), executor.trajectory(entry.rollout, { obsTrunc }));
+                writeFileSync(join(dir, 'produced.md'), renderDeliverable(executor, entry.rollout) || '(nothing produced)');
+            }
+            catch (error) {
+                writeFileSync(join(dir, 'rollout.md'), `(unavailable: ${error instanceof Error ? error.message : String(error)})`);
+            }
+        }
+        pool.push(entry.label);
+    }
+    let library = false;
+    if (input.libraryDir && existsSync(input.libraryDir) && readdirSync(input.libraryDir).length) {
+        assertNoLeakPaths(input.libraryDir, task.leakGlobs);
+        cpSync(input.libraryDir, join(dest, 'library'), { recursive: true });
+        library = true;
+    }
+    assertNoLeakPaths(dest, task.leakGlobs);
+    assertNoGraderVerdicts(dest);
+    if ((input.rollouts ?? []).length && !rollouts.length) {
+        throw new Error(`no trajectory could be rendered for ANY rollout -- the improver would be adapting on nothing: ${failed.slice(0, 4).join('; ')}`);
+    }
+    return { root: dest, taskId: task.id, rollouts, deliverables, harnessFiles, library, pool, failed, sourceFiles, decisions: Object.keys(input.decisions ?? {}).length };
+}
+/** The short pointer to the evidence on disk: the job, where the evidence is, and the instruction to open it. */
+export function mission(evidence, job) {
+    return [
+        job.trim(),
+        '',
+        '# YOUR EVIDENCE',
+        '',
+        'It is on disk, in `context/`. Read it -- do not answer from this message alone.',
+        '',
+        layout(evidence),
+        '',
+        'Every trajectory EVENT is present: the trajectory was not clipped to fit this mission. An individual observation may contain an explicit renderer-truncation marker; that marker is ours, not behavior by the solver. Do not diagnose it as a solver failure.',
+        '',
+        'Read `task.md` and the current harness first. Inventory every available rollout or candidate and inspect each at least once before deciding. For a candidate, compare what changed from its editing baseline, what behavior changed in its rollout, what improved, and what regressed or remained unresolved. Then deep-read the evidence relevant to any edit. Cite the specific trajectory moment behind every change; one you cannot trace to a moment is speculation.'
+    ].join('\n');
+}

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

@@ -0,0 +1,51 @@
+import type { CallerContext } from "../core/caller.js";
+import type { Launch } from "../prompt/compile.js";
+import type { Effort } from "../sessions/runner.js";
+import type { RefineTask } from "./types.js";
+/** How one execution of a task runs: who it works as and with what. */
+export interface RolloutSession {
+    caller: CallerContext;
+    tools: {
+        allow: string[];
+        gated?: string[];
+    };
+    launch?: Launch;
+    model?: string | null;
+    effort?: Effort | null;
+    accountId?: string | null;
+    poolId?: string | null;
+    connections?: boolean | {
+        readOnly?: boolean;
+    };
+    providers?: boolean;
+}
+export interface RolloutWorkspace {
+    /** The folder the execution works in. It must not be a folder a person is working in. */
+    cwd: string;
+    /** Called after what the execution produced has been read. */
+    cleanup?: () => Promise<void>;
+}
+export interface RefineHost {
+    /** A fresh, isolated folder for one execution. */
+    prepareWorkspace(input: {
+        refineId: string;
+        label: string;
+        task: RefineTask;
+    }): Promise<RolloutWorkspace>;
+    /** The session settings an execution runs with. */
+    session(input: {
+        refineId: string;
+        label: string;
+        task: RefineTask;
+    }): Promise<RolloutSession>;
+    /** What one execution produced, filename → readable text. Defaults to its reply and the files it changed. */
+    deliverable?(input: {
+        cwd: string;
+        reply: string;
+        task: RefineTask;
+    }): Promise<Record<string, string>>;
+}
+/** The reply, and every text file the execution added or changed relative to the task's source. */
+export declare function defaultDeliverable(cwd: string, reply: string, sourceDir: string | null | undefined): Record<string, string>;
+/** For a host that supplies nothing: a temporary copy of the task's source, the caller as the scope, and Pi's file and shell tools. */
+export declare const DEFAULT_REFINE_HOST: RefineHost;

package/dist/sdk/refine/host.js

@@ -0,0 +1,76 @@
+// The application's part in refinement (the seventh extension point). The harness runs the
+// method; the application says where an execution may work, as whom, with which tools, and what
+// it produced. Nothing here names an application concept.
+import { cpSync, existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, relative, sep } from 'node:path';
+const TEXT_LIMIT = 200_000;
+const FILES_LIMIT = 40;
+function files(dir, into = [], base = dir) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return into;
+    }
+    for (const name of names.sort()) {
+        if (name === '.git' || name === 'node_modules' || name.startsWith('.'))
+            continue;
+        const path = join(dir, name);
+        try {
+            if (statSync(path).isDirectory())
+                files(path, into, base);
+            else
+                into.push(relative(base, path).split(sep).join('/'));
+        }
+        catch {
+            // Skip what cannot be read.
+        }
+        if (into.length > 2_000)
+            break;
+    }
+    return into;
+}
+function readable(path) {
+    try {
+        const buffer = readFileSync(path);
+        if (buffer.length > TEXT_LIMIT || buffer.includes(0))
+            return null;
+        return buffer.toString('utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** The reply, and every text file the execution added or changed relative to the task's source. */
+export function defaultDeliverable(cwd, reply, sourceDir) {
+    const out = {};
+    if (reply.trim())
+        out['reply.md'] = reply;
+    let count = 0;
+    for (const rel of files(cwd)) {
+        const text = readable(join(cwd, rel));
+        if (text === null)
+            continue;
+        const before = sourceDir && existsSync(join(sourceDir, rel)) ? readable(join(sourceDir, rel)) : null;
+        if (before === text)
+            continue;
+        out[`files/${rel}`] = text;
+        if (++count >= FILES_LIMIT)
+            break;
+    }
+    return out;
+}
+/** For a host that supplies nothing: a temporary copy of the task's source, the caller as the scope, and Pi's file and shell tools. */
+export const DEFAULT_REFINE_HOST = {
+    async prepareWorkspace({ task }) {
+        const cwd = mkdtempSync(join(tmpdir(), 'harness-rollout-'));
+        if (task.sourceDir && existsSync(task.sourceDir))
+            cpSync(task.sourceDir, cwd, { recursive: true });
+        return { cwd, cleanup: async () => rmSync(cwd, { recursive: true, force: true }) };
+    },
+    async session({ task }) {
+        return { caller: { agentId: task.scope, actor: 'Code' }, tools: { allow: ['read', 'grep', 'find', 'ls', 'edit', 'write', 'bash'] } };
+    }
+};

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

@@ -0,0 +1,48 @@
+/** R = 4k: k shared base + 2k candidates + k finals. */
+export declare const expectedRollouts: (k: number) => number;
+/** P = 3k: k INV + k DOM + k compositions. */
+export declare const expectedSessions: (k: number) => number;
+export declare class BudgetError extends Error {
+    constructor(message: string);
+}
+export interface LedgerEntry {
+    kind: 'rollout' | 'session';
+    label: string;
+    usd: number;
+    cached: boolean;
+    attempts: number;
+}
+export interface LedgerRecord {
+    mode: string;
+    taskId: string;
+    k: number;
+    R: number;
+    expectedR: number;
+    P: number;
+    expectedP: number;
+    sessionAttempts: number;
+    usd: number;
+    rolloutUsd: number;
+    sessionUsd: number;
+    rollouts: string[];
+    sessions: string[];
+}
+export declare class Ledger {
+    readonly mode: string;
+    readonly taskId: string;
+    readonly k: number;
+    readonly entries: LedgerEntry[];
+    constructor(mode: string, taskId: string, k: number);
+    rollout(label: string, usd?: number, cached?: boolean): void;
+    session(label: string, usd?: number, options?: {
+        cached?: boolean;
+        attempts?: number;
+    }): void;
+    labels(kind: LedgerEntry['kind']): string[];
+    get R(): number;
+    get P(): number;
+    usd(kind?: LedgerEntry['kind']): number;
+    /** Throws unless the entries show exactly R=4k and P=3k with no repeated label. */
+    assertIdentity(): void;
+    toRecord(): LedgerRecord;
+}