@xingular/harness 2.0.0 → 2.0.1-unstable

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

@@ -0,0 +1,93 @@
+import type { Variant } from "../variant/surface.js";
+import type { WorkPrompts } from "./prompts.js";
+export type RecursionMode = 'parallel' | 'sequential';
+/** One piece of work to refine on. */
+export interface RefineTask {
+    /** Stable id of the task; names its folder and its library entry. */
+    id: string;
+    /** The request, as the agent received it, with any expected answer stripped. */
+    prompt: string;
+    /** The harness scope: whose variant this is and whose library it reads and grows. */
+    scope: string;
+    /** A grouping inside the scope's library. Defaults to the scope. */
+    domain?: string;
+    /** Material the work was done from, served to improvers and the selector as `source/`. */
+    sourceDir?: string | null;
+    /** Paths that must never reach a model (answer keys and the like), as globs. */
+    leakGlobs?: string[];
+    /** The text about the work the prompts interpolate. */
+    prompts?: WorkPrompts;
+    /** Whether a harness here may carry subagents. Default true. */
+    allowSubagents?: boolean;
+    /**
+     * Where the person asked improvers and composers to look (`/refine <guidance>`). It describes
+     * the work, never its measurement, and never reaches the selector or the reflector.
+     */
+    guidance?: string | null;
+    /** Where an execution starts: a snapshot of a git working tree, replayed in a throwaway worktree. */
+    workspace?: GitSnapshotWorkspace | null;
+}
+/** A commit made from a working tree (tracked edits and untracked files) without touching it. */
+export interface GitSnapshotWorkspace {
+    kind: 'git-snapshot';
+    /** The repository's top-level folder. */
+    repo: string;
+    commit: string;
+    /** Untracked files the snapshot left out because they were too large or too many. */
+    omitted?: number;
+}
+/** What the method knows about one finished execution. Never carries a score. */
+export interface Rollout {
+    label: string;
+    runId: string;
+    /** A folder that holds this execution's evidence. */
+    dir: string;
+    ok: boolean;
+    delivered: boolean;
+    costUsd: number;
+    wallMs: number;
+    error: string;
+}
+export interface Executor {
+    /**
+     * Runs one execution of `task` with the harness in `variantDir` (null: the base harness) and
+     * returns what it produced. A failure is returned as `ok: false`, never thrown.
+     */
+    execute(task: RefineTask, variantDir: string | null, label: string, runId: string): Promise<Rollout>;
+    /** The execution in the shared `[ACTION]/[OBSERVATION]/[ERROR]` grammar. */
+    trajectory(rollout: Rollout, options: {
+        obsTrunc: number;
+    }): string;
+    /** filename → readable text, one entry per artifact produced. */
+    deliverableFiles(rollout: Rollout): Record<string, string>;
+    /** Extra validation of a proposed variant for this task; throw with every problem listed. */
+    validateVariant?(task: RefineTask, variant: Variant): void;
+}
+export interface ImproverReply {
+    label: string;
+    text: string;
+    costUsd: number;
+    attempts: number;
+    cached: boolean;
+    /** The harvested folder, when the call asked for one; null when it did not come back. */
+    workspace: string | null;
+}
+export declare class ImproverError extends Error {
+    readonly attempts: number;
+    readonly costUsd: number;
+    constructor(message: string, attempts?: number, costUsd?: number);
+}
+export interface ImproverCall {
+    /** The instruction; evidence stays on disk under `context/`. */
+    mission: string;
+    /** The folder copied into the session as `context/`. */
+    contextDir: string;
+    /** A unique label for the audit trail and cache. */
+    label: string;
+    /** A path inside the session's folder to copy out before it is removed, e.g. `context/harness`. */
+    harvest?: string;
+    signal?: AbortSignal;
+}
+export interface Improver {
+    call(input: ImproverCall): Promise<ImproverReply>;
+}

package/dist/sdk/refine/types.js

@@ -0,0 +1,10 @@
+export class ImproverError extends Error {
+    attempts;
+    costUsd;
+    constructor(message, attempts = 0, costUsd = 0) {
+        super(message);
+        this.attempts = attempts;
+        this.costUsd = costUsd;
+        this.name = 'ImproverError';
+    }
+}

package/dist/sdk/remote/addresses.d.ts

@@ -0,0 +1,19 @@
+import { type NetworkInterfaceInfo } from 'node:os';
+export type RemoteAddressKind = 'tailscale' | 'lan';
+export type RemoteInterfaceChoice = 'auto' | RemoteAddressKind;
+export interface RemoteAddress {
+    kind: RemoteAddressKind;
+    address: string;
+    family: 'IPv4' | 'IPv6';
+    interface: string;
+}
+/** Tailscale hands out 100.64.0.0/10 and fd7a:115c:a1e0::/48. */
+export declare function isTailscale(address: string): boolean;
+/** RFC 1918 private IPv4 ranges. */
+export declare function isPrivateLan(address: string): boolean;
+/** Every address remote control may bind, Tailscale first. */
+export declare function remoteAddresses(interfaces?: NodeJS.Dict<NetworkInterfaceInfo[]>): RemoteAddress[];
+/** The one address to listen on for a choice, or a clear error when there is none. */
+export declare function pickRemoteAddress(choice: RemoteInterfaceChoice, candidates: readonly RemoteAddress[]): RemoteAddress;
+/** How a URL names the address. */
+export declare function hostPart(address: RemoteAddress): string;

package/dist/sdk/remote/addresses.js

@@ -0,0 +1,52 @@
+// Where remote control may listen: a Tailscale address or a private LAN address, never a public
+// one, never every interface (INV-RC-1).
+import { networkInterfaces } from 'node:os';
+import { HarnessError } from "../core/errors.js";
+const octets = (address) => address.split('.').map(Number);
+/** Tailscale hands out 100.64.0.0/10 and fd7a:115c:a1e0::/48. */
+export function isTailscale(address) {
+    if (address.includes(':'))
+        return address.toLowerCase().startsWith('fd7a:115c:a1e0:');
+    const [a, b] = octets(address);
+    return a === 100 && b >= 64 && b <= 127;
+}
+/** RFC 1918 private IPv4 ranges. */
+export function isPrivateLan(address) {
+    if (address.includes(':'))
+        return false;
+    const [a, b] = octets(address);
+    return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
+}
+/** Every address remote control may bind, Tailscale first. */
+export function remoteAddresses(interfaces = networkInterfaces()) {
+    const found = [];
+    for (const [name, entries] of Object.entries(interfaces)) {
+        for (const entry of entries ?? []) {
+            if (entry.internal)
+                continue;
+            const family = entry.family === 'IPv6' ? 'IPv6' : 'IPv4';
+            if (isTailscale(entry.address))
+                found.push({ kind: 'tailscale', address: entry.address, family, interface: name });
+            else if (isPrivateLan(entry.address))
+                found.push({ kind: 'lan', address: entry.address, family, interface: name });
+        }
+    }
+    // IPv4 first within a kind: it is what a person can type and what every phone resolves.
+    const rank = (address) => (address.kind === 'tailscale' ? 0 : 2) + (address.family === 'IPv4' ? 0 : 1);
+    return found.sort((a, b) => rank(a) - rank(b));
+}
+/** The one address to listen on for a choice, or a clear error when there is none. */
+export function pickRemoteAddress(choice, candidates) {
+    const pick = choice === 'auto' ? candidates[0] : candidates.find((candidate) => candidate.kind === choice);
+    if (pick)
+        return pick;
+    if (choice === 'tailscale')
+        throw new HarnessError('remote_unavailable', 'No Tailscale address found. Start Tailscale on this computer, or use the Wi-Fi address instead.');
+    if (choice === 'lan')
+        throw new HarnessError('remote_unavailable', 'No private Wi-Fi or LAN address found. Join a network, or use Tailscale instead.');
+    throw new HarnessError('remote_unavailable', 'No Tailscale or private network address found. Join a Wi-Fi network or start Tailscale, then try /remote-control again.');
+}
+/** How a URL names the address. */
+export function hostPart(address) {
+    return address.family === 'IPv6' ? `[${address.address}]` : address.address;
+}

package/dist/sdk/remote/pairing.d.ts

@@ -0,0 +1,59 @@
+import { ReplayGuard } from "./seal.js";
+export declare const MAX_DEVICES = 3;
+/** Under a minute: a phone's browser gives up on a request it waits on much longer. */
+export declare const CONFIRM_MS = 50000;
+export interface RemoteDevice {
+    id: string;
+    label: string;
+    key: Uint8Array;
+    pairedAt: number;
+    lastSeen: number;
+    /** The counters this device has sent. */
+    replay: ReplayGuard;
+    /** The counter of the last frame sent to it. */
+    lastOut: number;
+}
+export interface PairRequest {
+    id: string;
+    label: string;
+    at: number;
+}
+/** A short, printable name for a browser from its user agent. Nothing from the phone is trusted. */
+export declare function deviceLabel(userAgent: unknown): string;
+export declare class Pairing {
+    private readonly changed;
+    private readonly clock;
+    private link;
+    private linkReplay;
+    private pending;
+    private readonly devices;
+    private hellos;
+    private failures;
+    private notice;
+    constructor(changed?: () => void, clock?: () => number);
+    private newLink;
+    /** What follows `#` in the pairing URL. */
+    get fragment(): string;
+    get request(): PairRequest | null;
+    /** A warning for the terminal page, such as a link replaced after repeated bad attempts. */
+    get warning(): string | null;
+    list(): RemoteDevice[];
+    device(deviceId: string): RemoteDevice | null;
+    /** A new link; every paired device is dropped and a waiting request denied. */
+    rotate(): void;
+    forget(deviceId: string): void;
+    /** The person at the terminal allowed or refused a waiting request. */
+    confirm(requestId: string, allow: boolean): void;
+    private fail;
+    /**
+     * A phone opened the pairing link. Waits until the person at the terminal decides, then returns
+     * the device's id and key, sealed with the link key.
+     */
+    hello(pairingId: unknown, frame: unknown, confirmMs?: number): Promise<string>;
+    /** Opens a paired device's frame, enforcing its counter. */
+    openFrom<T = unknown>(deviceId: unknown, frame: unknown): {
+        device: RemoteDevice;
+        body: T;
+    };
+    sealFor(device: RemoteDevice, body: unknown): string;
+}

package/dist/sdk/remote/pairing.js

@@ -0,0 +1,160 @@
+// Pairing for remote control. The QR code carries a pairing link: an id and a key, in the URL's
+// fragment. A phone that opens it says hello, sealed with that key; the person at the terminal
+// confirms; the phone receives its own device key. A link pairs one device and is then replaced,
+// so the QR on screen always pairs the next one. Every key lives in memory only (INV-RC-2).
+import { randomBytes } from 'node:crypto';
+import { HarnessError } from "../core/errors.js";
+import { encode, newKey, open, ReplayGuard, sameSecret, seal } from "./seal.js";
+export const MAX_DEVICES = 3;
+const HELLO_WINDOW_MS = 60_000;
+const MAX_HELLOS = 10;
+const MAX_FAILURES = 20;
+/** Under a minute: a phone's browser gives up on a request it waits on much longer. */
+export const CONFIRM_MS = 50_000;
+/** A short, printable name for a browser from its user agent. Nothing from the phone is trusted. */
+export function deviceLabel(userAgent) {
+    const ua = typeof userAgent === 'string' ? userAgent.slice(0, 400) : '';
+    const device = /iPad/.test(ua) ? 'iPad'
+        : /iPhone/.test(ua) ? 'iPhone'
+            : /Android/.test(ua) ? 'Android'
+                : /Macintosh|Mac OS X/.test(ua) ? (/Mobile/.test(ua) ? 'iPad' : 'Mac')
+                    : /Windows/.test(ua) ? 'Windows'
+                        : /Linux/.test(ua) ? 'Linux' : 'Browser';
+    const browser = /EdgiOS|EdgA|Edg\//.test(ua) ? 'Edge'
+        : /CriOS|Chrome\//.test(ua) ? 'Chrome'
+            : /FxiOS|Firefox\//.test(ua) ? 'Firefox'
+                : /Safari\//.test(ua) ? 'Safari' : '';
+    return browser ? `${device} · ${browser}` : device;
+}
+const id = () => randomBytes(12).toString('base64url');
+export class Pairing {
+    changed;
+    clock;
+    link = { id: id(), key: newKey() };
+    linkReplay = new ReplayGuard();
+    pending = null;
+    devices = new Map();
+    hellos = [];
+    failures = 0;
+    notice = null;
+    constructor(changed = () => { }, clock = Date.now) {
+        this.changed = changed;
+        this.clock = clock;
+    }
+    newLink() {
+        this.link = { id: id(), key: newKey() };
+        this.linkReplay = new ReplayGuard();
+    }
+    /** What follows `#` in the pairing URL. */
+    get fragment() {
+        return `${this.link.id}.${encode(this.link.key)}`;
+    }
+    get request() {
+        return this.pending ? { id: this.pending.id, label: this.pending.label, at: this.pending.at } : null;
+    }
+    /** A warning for the terminal page, such as a link replaced after repeated bad attempts. */
+    get warning() {
+        return this.notice;
+    }
+    list() {
+        return [...this.devices.values()];
+    }
+    device(deviceId) {
+        for (const [known, device] of this.devices)
+            if (sameSecret(known, deviceId))
+                return device;
+        return null;
+    }
+    /** A new link; every paired device is dropped and a waiting request denied. */
+    rotate() {
+        this.newLink();
+        this.pending?.decide(false);
+        this.pending = null;
+        this.devices.clear();
+        this.failures = 0;
+        this.notice = null;
+        this.changed();
+    }
+    forget(deviceId) {
+        const device = this.device(deviceId);
+        if (device && this.devices.delete(device.id))
+            this.changed();
+    }
+    /** The person at the terminal allowed or refused a waiting request. */
+    confirm(requestId, allow) {
+        if (!this.pending || this.pending.id !== requestId)
+            throw new HarnessError('invalid_request', 'This pairing request is no longer waiting.');
+        this.pending.decide(allow);
+    }
+    fail() {
+        this.failures += 1;
+        if (this.failures >= MAX_FAILURES) {
+            this.newLink();
+            this.failures = 0;
+            this.notice = 'Too many failed pairing attempts. The link was replaced; scan the new QR code.';
+            this.changed();
+        }
+        return new HarnessError('unauthorized', 'This pairing link is not valid. Scan the QR code in the terminal again.');
+    }
+    /**
+     * A phone opened the pairing link. Waits until the person at the terminal decides, then returns
+     * the device's id and key, sealed with the link key.
+     */
+    async hello(pairingId, frame, confirmMs = CONFIRM_MS) {
+        const at = this.clock();
+        this.hellos = this.hellos.filter((time) => at - time < HELLO_WINDOW_MS);
+        if (this.hellos.length >= MAX_HELLOS)
+            throw new HarnessError('rate_limited', 'Too many pairing attempts. Wait a minute and try again.');
+        this.hellos.push(at);
+        if (typeof pairingId !== 'string' || typeof frame !== 'string' || !sameSecret(pairingId, this.link.id))
+            throw this.fail();
+        const link = this.link;
+        let body;
+        try {
+            body = open(link.key, frame, (n) => this.linkReplay.accept(n)).body ?? {};
+        }
+        catch {
+            throw this.fail();
+        }
+        if (this.pending)
+            throw new HarnessError('remote_busy', 'Another device is waiting for approval in the terminal.');
+        if (this.devices.size >= MAX_DEVICES)
+            throw new HarnessError('remote_full', `At most ${MAX_DEVICES} devices can control a session. Press n in /remote-control to start over.`);
+        const label = deviceLabel(body.userAgent);
+        const allowed = await new Promise((resolve) => {
+            const timer = setTimeout(() => decide(false), confirmMs);
+            timer.unref?.();
+            const decide = (allow) => {
+                clearTimeout(timer);
+                if (this.pending?.decide === decide)
+                    this.pending = null;
+                resolve(allow);
+                this.changed();
+            };
+            this.pending = { id: id(), label, at, decide };
+            this.changed();
+        });
+        // A rotation while the phone waited replaced this link; its request is void.
+        if (!allowed || this.link !== link)
+            throw new HarnessError('remote_denied', 'Pairing was not allowed at the terminal.');
+        const device = { id: id(), label, key: newKey(), pairedAt: this.clock(), lastSeen: this.clock(), replay: new ReplayGuard(), lastOut: 0 };
+        this.devices.set(device.id, device);
+        // The link paired its device; the QR on screen now pairs the next one.
+        this.newLink();
+        this.changed();
+        return seal(link.key, 1, { deviceId: device.id, deviceKey: encode(device.key), label });
+    }
+    /** Opens a paired device's frame, enforcing its counter. */
+    openFrom(deviceId, frame) {
+        const device = typeof deviceId === 'string' ? this.device(deviceId) : null;
+        if (!device || typeof frame !== 'string')
+            throw new HarnessError('unauthorized', 'This device is not paired with the session. Scan the QR code in the terminal again.');
+        const opened = open(device.key, frame, (n) => device.replay.accept(n));
+        device.lastSeen = this.clock();
+        return { device, body: opened.body };
+    }
+    sealFor(device, body) {
+        device.lastOut += 1;
+        return seal(device.key, device.lastOut, body);
+    }
+}

package/dist/sdk/remote/seal.d.ts

@@ -0,0 +1,28 @@
+export declare const KEY_BYTES: number;
+/** How far behind the highest counter a frame may arrive, for requests a phone sent at once. */
+export declare const REPLAY_WINDOW = 256;
+export interface Opened<T> {
+    n: number;
+    body: T;
+}
+export declare function newKey(): Uint8Array;
+/** URL-safe base64 without padding: it travels in fragments, query strings and SSE lines. */
+export declare function encode(bytes: Uint8Array): string;
+export declare function decode(text: string): Uint8Array;
+export declare function seal(key: Uint8Array, n: number, body: unknown): string;
+/**
+ * Opens a frame and asks `fresh` whether its counter is new. A frame that fails here is a wrong
+ * key, a tampered body, or a replay; callers answer all three the same way.
+ */
+export declare function open<T = unknown>(key: Uint8Array, frame: string, fresh: (n: number) => boolean): Opened<T>;
+/**
+ * Remembers the counters a sender used: a counter is fresh when it is above the highest seen, or
+ * within the window below it and not seen before.
+ */
+export declare class ReplayGuard {
+    private highest;
+    private readonly recent;
+    accept(n: number): boolean;
+}
+/** Compares two identifiers without leaking how much of them matched. */
+export declare function sameSecret(a: string, b: string): boolean;

package/dist/sdk/remote/seal.js

@@ -0,0 +1,84 @@
+// Sealed frames for remote control. A LAN page is served over plain HTTP, where the browser has no
+// WebCrypto and anyone on the Wi-Fi can read traffic, so every body is a NaCl secretbox
+// (XSalsa20-Poly1305) under a key the phone got from the QR code's fragment, which a browser never
+// sends. A random 24-byte nonce per frame; the counter inside the frame stops replays.
+import { timingSafeEqual } from 'node:crypto';
+import nacl from 'tweetnacl';
+import { HarnessError } from "../core/errors.js";
+export const KEY_BYTES = nacl.secretbox.keyLength;
+/** How far behind the highest counter a frame may arrive, for requests a phone sent at once. */
+export const REPLAY_WINDOW = 256;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+export function newKey() {
+    return nacl.randomBytes(KEY_BYTES);
+}
+/** URL-safe base64 without padding: it travels in fragments, query strings and SSE lines. */
+export function encode(bytes) {
+    return Buffer.from(bytes).toString('base64url');
+}
+export function decode(text) {
+    return new Uint8Array(Buffer.from(text, 'base64url'));
+}
+export function seal(key, n, body) {
+    const nonce = nacl.randomBytes(nacl.secretbox.nonceLength);
+    const box = nacl.secretbox(encoder.encode(JSON.stringify({ n, body })), nonce, key);
+    const frame = new Uint8Array(nonce.length + box.length);
+    frame.set(nonce);
+    frame.set(box, nonce.length);
+    return encode(frame);
+}
+const rejected = () => new HarnessError('unauthorized', 'This remote-control frame could not be opened.');
+/**
+ * Opens a frame and asks `fresh` whether its counter is new. A frame that fails here is a wrong
+ * key, a tampered body, or a replay; callers answer all three the same way.
+ */
+export function open(key, frame, fresh) {
+    if (typeof frame !== 'string' || frame.length > 1_500_000)
+        throw rejected();
+    const bytes = decode(frame);
+    const nonceLength = nacl.secretbox.nonceLength;
+    if (bytes.length <= nonceLength + nacl.secretbox.overheadLength)
+        throw rejected();
+    const plain = nacl.secretbox.open(bytes.subarray(nonceLength), bytes.subarray(0, nonceLength), key);
+    if (!plain)
+        throw rejected();
+    let value;
+    try {
+        value = JSON.parse(decoder.decode(plain));
+    }
+    catch {
+        throw rejected();
+    }
+    if (typeof value.n !== 'number' || !Number.isSafeInteger(value.n) || value.n < 1 || !fresh(value.n))
+        throw rejected();
+    return { n: value.n, body: value.body };
+}
+/**
+ * Remembers the counters a sender used: a counter is fresh when it is above the highest seen, or
+ * within the window below it and not seen before.
+ */
+export class ReplayGuard {
+    highest = 0;
+    recent = new Set();
+    accept(n) {
+        if (n > this.highest) {
+            this.highest = n;
+            this.recent.add(n);
+            for (const seen of this.recent)
+                if (seen <= n - REPLAY_WINDOW)
+                    this.recent.delete(seen);
+            return true;
+        }
+        if (n <= this.highest - REPLAY_WINDOW || this.recent.has(n))
+            return false;
+        this.recent.add(n);
+        return true;
+    }
+}
+/** Compares two identifiers without leaking how much of them matched. */
+export function sameSecret(a, b) {
+    const left = Buffer.from(a);
+    const right = Buffer.from(b);
+    return left.length === right.length && timingSafeEqual(left, right);
+}

package/dist/sdk/remote/server.d.ts

@@ -0,0 +1,28 @@
+export interface RemoteAsset {
+    type: string;
+    body: string;
+}
+export interface RemoteStream {
+    /** Sends one sealed frame as an SSE message. */
+    send(frame: string): void;
+    end(): void;
+}
+export interface RemoteRoutes {
+    /** The page and its scripts, by path. */
+    asset(path: string): RemoteAsset | null;
+    hello(body: Record<string, unknown>): Promise<{
+        f: string;
+    }>;
+    call(body: Record<string, unknown>): Promise<{
+        f: string;
+    }>;
+    /** Opens a stream for a paired device; returns what to run when the phone hangs up. */
+    stream(deviceId: string, frame: string, stream: RemoteStream): () => void;
+}
+export interface RemoteListening {
+    host: string;
+    port: number;
+    close(): Promise<void>;
+}
+/** Starts the server on one address. `port` 0 picks a free one. */
+export declare function listenRemote(host: string, port: number, routes: RemoteRoutes): Promise<RemoteListening>;