amness 0.0.0-stage → 0.1.2

package/dist/src/ratelimit.d.ts

@@ -0,0 +1,34 @@
+import type { Model } from "./harness.ts";
+/** "1s", "6m0s", "20ms", "1.5s" -> milliseconds (the format of x-ratelimit-reset-* headers). */
+export declare function parseDuration(s: string): number | undefined;
+/** How long the server asked us to wait (Retry-After seconds or date, retry-after-ms, or "try again in 1.2s" in the message), if it said. */
+export declare function retryAfterMs(e: any): number | undefined;
+/** A 429 that waiting can fix. Quota, billing and spend-cap errors also arrive as 429 but never recover by retrying. */
+export declare function isRateLimit(e: any): boolean;
+export declare class Gate {
+    max: number;
+    readonly ceiling: number;
+    active: number;
+    pausedUntil: number;
+    private successes;
+    private waiters;
+    limited: number;
+    constructor(o?: {
+        ceiling?: number;
+        start?: number;
+    });
+    private wake;
+    acquire(signal?: AbortSignal): Promise<() => void>;
+    success(): void;
+    /** A 429 happened: pause everyone, halve the concurrency, and say how long. */
+    penalize(retryAfter: number | undefined, attempt: number): number;
+}
+/** The gate for one API endpoint and key: every model built for it shares it. */
+export declare function gateFor(key: string, ceiling?: number): Gate;
+export type RateLimitOptions = {
+    gate?: Gate; /** attempts after the first (default 6) */
+    retries?: number; /** give up when asked to wait longer than this (default 2 minutes) */
+    maxWaitMs?: number;
+    onWait?: (ms: number, attempt: number, gate: Gate) => void;
+};
+export declare function rateLimited(model: Model, o?: RateLimitOptions): Model;

package/dist/src/ratelimit.js

@@ -0,0 +1,116 @@
+const sleep = (ms, signal) => new Promise((res, rej) => {
+    if (signal?.aborted)
+        return rej(new DOMException("aborted", "AbortError"));
+    const t = setTimeout(() => { signal?.removeEventListener("abort", onAbort); res(); }, ms), onAbort = () => { clearTimeout(t); rej(new DOMException("aborted", "AbortError")); };
+    signal?.addEventListener("abort", onAbort, { once: true });
+});
+/** "1s", "6m0s", "20ms", "1.5s" -> milliseconds (the format of x-ratelimit-reset-* headers). */
+export function parseDuration(s) {
+    const re = /(\d+(?:\.\d+)?)(ms|s|m|h)/g;
+    let total = 0, any = false, m;
+    while ((m = re.exec(s))) {
+        any = true;
+        total += Number(m[1]) * { ms: 1, s: 1000, m: 60_000, h: 3_600_000 }[m[2]];
+    }
+    return any ? total : undefined;
+}
+const header = (e, name) => { const h = e?.headers; const v = typeof h?.get === "function" ? h.get(name) : h?.[name]; return v == null ? undefined : String(v); };
+/** How long the server asked us to wait (Retry-After seconds or date, retry-after-ms, or "try again in 1.2s" in the message), if it said. */
+export function retryAfterMs(e) {
+    if (typeof e?.retryAfterMs === "number")
+        return e.retryAfterMs;
+    const ms = header(e, "retry-after-ms");
+    if (ms && Number.isFinite(Number(ms)))
+        return Number(ms);
+    const ra = header(e, "retry-after");
+    if (ra) {
+        if (Number.isFinite(Number(ra)))
+            return Number(ra) * 1000;
+        const d = Date.parse(ra);
+        if (Number.isFinite(d))
+            return Math.max(0, d - Date.now());
+    }
+    const m = /try again in ([\d.]+\s*(?:ms|s|m))/i.exec(String(e?.message ?? ""));
+    return m ? parseDuration(m[1].replace(/\s+/g, "")) : undefined;
+}
+/** A 429 that waiting can fix. Quota, billing and spend-cap errors also arrive as 429 but never recover by retrying. */
+export function isRateLimit(e) {
+    const msg = String(e?.message ?? "");
+    if (/insufficient_quota|exceeded your current quota|billing|spend limit|usage limits|enforced_spend_limit/i.test(msg))
+        return false;
+    return e?.status === 429 || /\bHTTP 429\b|rate.?limit/i.test(msg);
+}
+export class Gate {
+    max;
+    ceiling;
+    active = 0;
+    pausedUntil = 0;
+    successes = 0;
+    waiters = [];
+    limited = 0;
+    constructor(o = {}) { this.ceiling = Math.max(1, o.ceiling ?? 4); this.max = Math.min(this.ceiling, Math.max(1, o.start ?? 2)); }
+    wake() { const w = this.waiters.shift(); if (w)
+        w(); }
+    async acquire(signal) {
+        for (;;) {
+            if (signal?.aborted)
+                throw new DOMException("aborted", "AbortError");
+            const wait = this.pausedUntil - Date.now();
+            if (wait > 0) {
+                await sleep(wait, signal);
+                continue;
+            }
+            if (this.active < this.max) {
+                this.active++;
+                let done = false;
+                return () => { if (done)
+                    return; done = true; this.active--; this.wake(); };
+            }
+            await new Promise((res, rej) => { const w = () => { signal?.removeEventListener("abort", ab); res(); }, ab = () => { this.waiters = this.waiters.filter((x) => x !== w); rej(new DOMException("aborted", "AbortError")); }; this.waiters.push(w); signal?.addEventListener("abort", ab, { once: true }); });
+        }
+    }
+    success() { this.successes++; if (this.successes >= 3 && this.max < this.ceiling) {
+        this.max++;
+        this.successes = 0;
+        this.wake();
+    } }
+    /** A 429 happened: pause everyone, halve the concurrency, and say how long. */
+    penalize(retryAfter, attempt) {
+        const backoff = Math.min(60_000, 1000 * 2 ** attempt), wait = Math.round((retryAfter ?? backoff) + Math.random() * Math.min(750, 100 + 0.25 * (retryAfter ?? backoff)));
+        this.pausedUntil = Math.max(this.pausedUntil, Date.now() + wait);
+        this.max = Math.max(1, Math.floor(this.max / 2));
+        this.successes = 0;
+        this.limited++;
+        return wait;
+    }
+}
+const gates = new Map();
+/** The gate for one API endpoint and key: every model built for it shares it. */
+export function gateFor(key, ceiling = 4) { let g = gates.get(key); if (!g)
+    gates.set(key, (g = new Gate({ ceiling }))); return g; }
+export function rateLimited(model, o = {}) {
+    const gate = o.gate ?? new Gate(), retries = o.retries ?? 6, maxWait = o.maxWaitMs ?? 120_000;
+    const call = (async (messages, tools, opts) => {
+        for (let attempt = 0;; attempt++) {
+            const release = await gate.acquire(opts?.signal);
+            try {
+                const m = await model(messages, tools, opts);
+                gate.success();
+                return m;
+            }
+            catch (e) {
+                if (opts?.signal?.aborted || !isRateLimit(e) || attempt >= retries)
+                    throw e;
+                const ra = retryAfterMs(e);
+                if (ra !== undefined && ra > maxWait)
+                    throw e;
+                const wait = gate.penalize(ra, attempt);
+                o.onWait?.(wait, attempt + 1, gate);
+            }
+            finally {
+                release();
+            }
+        }
+    });
+    return Object.assign(call, model);
+}

package/dist/src/replay.d.ts

@@ -0,0 +1,25 @@
+import { type Message, type Options, type RunResult } from "./harness.ts";
+import { type TraceLine } from "./trace.ts";
+export type TraceRun = {
+    messages: Message[];
+    models: Message[];
+    results: Map<string, string[]>;
+    tools: string[];
+    lines: TraceLine[];
+};
+/** Split a JSONL trace into runs (one per `run` event). Events of subagents are ignored: they are not regenerated. */
+export declare function readTrace(file: string): TraceRun[];
+export type ReplayReport = {
+    run: number;
+    turns: number;
+    recorded: string[];
+    replayed: string[];
+    onlyRecorded: string[];
+    onlyReplayed: string[];
+    same: boolean;
+    result: RunResult;
+};
+/** Feed one recorded run back through the harness with `o` as its options (the thing you changed). */
+export declare function replayRun(run: TraceRun, o?: Partial<Options>): Promise<ReplayReport>;
+export declare function replayFile(file: string, o?: Partial<Options>): Promise<ReplayReport[]>;
+export declare function formatReplay(reports: ReplayReport[]): string;

package/dist/src/replay.js

@@ -0,0 +1,99 @@
+// Replay a recorded trace through the CURRENT harness without calling any model or running any tool: the model's recorded messages and the tools' recorded results are fed back,
+// so only the harness logic (guards, permissions, compaction, cache behaviour, hooks...) can differ. That makes harness changes testable offline, for free, on real sessions.
+import { readFileSync } from "node:fs";
+import { canonicalCall, createHarness, defineTool } from "./harness.js";
+import { Tracer } from "./trace.js";
+const SIGNIFICANT = new Set(["nudge", "loop", "repair", "rejected", "denied", "hook", "trim", "cachebreak", "review", "audit", "finish", "aborted", "budget", "rollover", "tools", "steer"]);
+/** Split a JSONL trace into runs (one per `run` event). Events of subagents are ignored: they are not regenerated. */
+export function readTrace(file) {
+    const runs = [];
+    let cur;
+    const pending = new Map();
+    for (const l of readFileSync(file, "utf8").split("\n")) {
+        if (!l.trim())
+            continue;
+        let e;
+        try {
+            e = JSON.parse(l);
+        }
+        catch {
+            continue;
+        }
+        if (e.agent)
+            continue;
+        if (e.kind === "run") {
+            cur = { messages: e.messages, models: [], results: new Map(), tools: [], lines: [] };
+            runs.push(cur);
+            pending.clear();
+            continue;
+        }
+        if (!cur)
+            continue;
+        if (e.kind === "model") {
+            cur.models.push(e.message);
+            continue;
+        }
+        if (e.kind === "toolstart") {
+            pending.set(String(e.id), { name: String(e.name), args: String(e.args) });
+            continue;
+        }
+        if (e.kind === "tool") {
+            const p = pending.get(String(e.id));
+            if (!p)
+                continue;
+            pending.delete(String(e.id));
+            if (!cur.tools.includes(p.name))
+                cur.tools.push(p.name);
+            let args = {};
+            try {
+                args = JSON.parse(p.args || "{}");
+            }
+            catch { /* keep {} */ }
+            const key = canonicalCall(p.name, args), list = cur.results.get(key) ?? [];
+            list.push(String(e.result));
+            cur.results.set(key, list);
+            continue;
+        }
+        if (SIGNIFICANT.has(e.kind))
+            cur.lines.push(e);
+    }
+    return runs;
+}
+const sig = (l) => { const d = String(l.detail ?? l.summary ?? l.reason ?? "").replace(/\s+/g, " ").slice(0, 80); return `${l.kind}${d ? " · " + d : ""}`; };
+/** Feed one recorded run back through the harness with `o` as its options (the thing you changed). */
+export async function replayRun(run, o = {}) {
+    const models = [...run.models], results = new Map([...run.results].map(([k, v]) => [k, [...v]]));
+    const model = async () => models.shift() ?? { role: "assistant", content: "(replay: the recorded trace ends here)" };
+    const tools = run.tools.map((name) => defineTool({ name, description: "", schema: { type: "object" }, readOnly: true, run: (args) => results.get(canonicalCall(name, args))?.shift() ?? "ERROR: (replay) no recorded result for this call: the harness diverged from the recording here" }));
+    const replayed = [], tracer = new Tracer({ sessionId: "replay", sink: (l) => replayed.push(l) });
+    const result = await createHarness({ maxSteps: 60, approve: () => true, ...o, model, tools, onEvent: (e) => tracer.event(e) }).run("", { resume: run.messages });
+    const A = run.lines.map(sig), B = replayed.filter((l) => SIGNIFICANT.has(l.kind)).map(sig);
+    const left = (xs, ys) => { const c = new Map(); for (const y of ys)
+        c.set(y, (c.get(y) ?? 0) + 1); return xs.filter((x) => { const n = c.get(x) ?? 0; if (n > 0) {
+        c.set(x, n - 1);
+        return false;
+    } return true; }); };
+    const onlyRecorded = left(A, B), onlyReplayed = left(B, A);
+    return { run: 0, turns: run.models.length, recorded: A, replayed: B, onlyRecorded, onlyReplayed, same: !onlyRecorded.length && !onlyReplayed.length, result };
+}
+export async function replayFile(file, o = {}) {
+    const runs = readTrace(file), out = [];
+    for (const [i, r] of runs.entries())
+        out.push({ ...(await replayRun(r, o)), run: i + 1 });
+    return out;
+}
+export function formatReplay(reports) {
+    if (!reports.length)
+        return "no recorded runs in this trace (traces written before replay support, or with recording off, have no model messages)";
+    const out = [];
+    for (const r of reports) {
+        out.push(`run ${r.run}: ${r.turns} model turn(s), ${r.same ? "identical harness behaviour" : `${r.onlyRecorded.length + r.onlyReplayed.length} difference(s)`}`);
+        for (const s of r.onlyRecorded)
+            out.push(`  - recorded only: ${s}`);
+        for (const s of r.onlyReplayed)
+            out.push(`  + replay only:   ${s}`);
+        if (!r.same)
+            out.push("  (after the first difference the recording no longer matches what the model would have said, so later lines are indicative)");
+    }
+    return out.join("\n");
+}

package/dist/src/review.d.ts

@@ -0,0 +1,20 @@
+import { Budget, type Model } from "./harness.ts";
+export type ReviewResult = {
+    pass: boolean;
+    findings: string[];
+    inconclusive?: boolean;
+};
+/** Testable acceptance criteria for `task`. Returns [] when the model's reply cannot be used (the work simply proceeds without a contract). */
+export declare function proposeContract(model: Model, task: string, budget?: Budget): Promise<string[]>;
+export declare function reviewWork(o: {
+    model: Model;
+    cwd: string;
+    task: string;
+    contract: string[];
+    summary: string;
+    diffs: string;
+    commands: string;
+    verify?: string;
+    budget?: Budget;
+    signal?: AbortSignal;
+}): Promise<ReviewResult>;

package/dist/src/review.js

@@ -0,0 +1,49 @@
+// An independent, skeptical reviewer. Builders overpraise their own work, and a separate judge is easier to tune towards scepticism than a builder is to make self-critical.
+// Two parts: a CONTRACT of testable acceptance criteria agreed before the work starts, and a REVIEW of the finished work against it, in a fresh context that cannot edit anything.
+import { codeTools, runShell } from "./code.js";
+import { clip, createHarness, defineTool } from "./harness.js";
+import { BUILD_CMD, TEST_CMD } from "./ledger.js";
+import { parseLooseJson } from "./schema.js";
+const CONTRACT_SYSTEM = "You write acceptance criteria for a coding task before anyone starts it. Be concrete and checkable: each criterion must be verifiable by reading the diff or running a command. Do not describe how to implement. 3 to 7 criteria, each one sentence. Reply with ONLY a JSON array of strings.";
+/** Testable acceptance criteria for `task`. Returns [] when the model's reply cannot be used (the work simply proceeds without a contract). */
+export async function proposeContract(model, task, budget) {
+    try {
+        const m = await model([{ role: "system", content: CONTRACT_SYSTEM }, { role: "user", content: `Task:\n${clip(task, 6000)}` }], []);
+        budget?.add(m);
+        const j = parseLooseJson(m.content ?? "");
+        return Array.isArray(j) ? j.filter((x) => typeof x === "string" && x.trim().length > 3).map((x) => x.trim().slice(0, 300)).slice(0, 7) : [];
+    }
+    catch {
+        return [];
+    }
+}
+const REVIEW_SYSTEM = `You are a skeptical code reviewer. Someone else did this work; assume it is wrong until the evidence shows otherwise.
+- Do NOT trust their summary. Judge from the diff, the files, and commands you run yourself.
+- Check every acceptance criterion. For each one decide: met (with the evidence you saw) or not met (say exactly what is wrong or missing).
+- Look for what they did not do: untouched call sites, missing edge cases, weakened tests, unrelated changes.
+- You can read files and run checks with the tools; you cannot change anything.
+- When done, call finish with a summary that is ONLY this JSON: {"pass": boolean, "findings": ["one specific problem per entry, empty if none"]}.
+Pass only if every criterion is met and you found no real problem. Style opinions are not findings.`;
+/** Read-only tools plus a runner for the project's own checks (tests, build, lint); nothing else can execute. */
+function reviewerTools(cwd, allow) {
+    const read = codeTools(cwd, { mode: () => "plan" }).filter((t) => ["list_files", "read_file", "grep"].includes(t.name));
+    const run = defineTool({ name: "run_check", description: "Run one of the project's own checks (tests, build, typecheck, lint) and see the result. Other commands are refused.", readOnly: true,
+        schema: { type: "object", required: ["cmd"], properties: { cmd: { type: "string" } } },
+        run: async ({ cmd }) => (!/[;&|<>`$()]/.test(cmd) && allow.some((re) => re.test(cmd)) ? clip(await runShell(cmd, cwd, 180_000), 4000) : "ERROR: only the project's test, build, typecheck and lint commands may be run here (one command, no chaining)") });
+    return [...read, run];
+}
+export async function reviewWork(o) {
+    const allow = [TEST_CMD, BUILD_CMD, ...(o.verify ? [new RegExp("^\\s*" + o.verify.trim().split(/\s+/).map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("\\s+"))] : [])];
+    const prompt = `## Task\n${clip(o.task, 4000)}\n\n## Acceptance criteria\n${o.contract.length ? o.contract.map((c, i) => `${i + 1}. ${c}`).join("\n") : "(none were written; judge against the task itself)"}\n\n## What the author says they did\n${clip(o.summary, 2000)}\n\n## Changes (diffs)\n${o.diffs || "(no file was edited)"}\n\n## Commands the author ran\n${o.commands || "(none)"}`;
+    try {
+        const r = await createHarness({ model: o.model, system: REVIEW_SYSTEM, tools: reviewerTools(o.cwd, allow), maxSteps: 14, budget: o.budget, signal: o.signal }).run(prompt);
+        const j = r.finished ? parseLooseJson(r.text) : null;
+        if (!j || typeof j !== "object" || typeof j.pass !== "boolean")
+            return { pass: true, findings: [], inconclusive: true }; // an unusable verdict must not block the work
+        const findings = Array.isArray(j.findings) ? j.findings.filter((x) => typeof x === "string" && !!x.trim()).map((x) => x.slice(0, 500)).slice(0, 8) : [];
+        return { pass: j.pass && findings.length === 0, findings: j.pass ? findings : findings.length ? findings : ["the reviewer rejected the work without saying why"] };
+    }
+    catch {
+        return { pass: true, findings: [], inconclusive: true };
+    }
+}

package/dist/src/route.d.ts

@@ -0,0 +1,9 @@
+import type { Model } from "./harness.ts";
+export type Roles = Partial<Record<"explore" | "compact" | "review" | "cheap", Model>>;
+/** Errors worth trying another model for: rate limits, overload, server errors, timeouts, and network failures (the adapters already retried the same model). */
+export declare function isRetryable(e: unknown): boolean;
+/**
+ * Try `primary`; if it fails with a retryable error, answer from `fallback` instead (and say so through `onFallback`).
+ * The fallback model sees the same messages; adapters ignore reasoning blobs that belong to another provider.
+ */
+export declare function withFallback(primary: Model, fallback: Model, onFallback?: (e: unknown) => void): Model;

package/dist/src/route.js

@@ -0,0 +1,30 @@
+/** Errors worth trying another model for: rate limits, overload, server errors, timeouts, and network failures (the adapters already retried the same model). */
+export function isRetryable(e) {
+    const err = e;
+    if (err?.name === "AbortError")
+        return false;
+    if (typeof err?.status === "number")
+        return err.status === 408 || err.status === 429 || err.status >= 500;
+    return /\b(ECONNRESET|ECONNREFUSED|ETIMEDOUT|ENOTFOUND|EAI_AGAIN|fetch failed|socket hang up|overloaded|HTTP (408|429|5\d\d))\b/i.test(`${err?.code ?? ""} ${err?.message ?? ""}`);
+}
+/**
+ * Try `primary`; if it fails with a retryable error, answer from `fallback` instead (and say so through `onFallback`).
+ * The fallback model sees the same messages; adapters ignore reasoning blobs that belong to another provider.
+ */
+export function withFallback(primary, fallback, onFallback) {
+    const m = async (messages, tools, opts) => {
+        try {
+            return await primary(messages, tools, opts);
+        }
+        catch (e) {
+            if (!isRetryable(e) || opts?.signal?.aborted)
+                throw e;
+            onFallback?.(e);
+            return fallback(messages, tools, opts);
+        }
+    };
+    m.appendOnly = primary.appendOnly || fallback.appendOnly; // if either may be Claude, history must not be rewritten
+    if (primary.api)
+        m.api = primary.api;
+    return m;
+}

package/dist/src/router.d.ts

@@ -0,0 +1,61 @@
+import type { Message, Model } from "./harness.ts";
+export type Tier = "strong" | "cheap";
+export type Prices = {
+    input: number;
+    output: number; /** fraction of the input price charged for cached input (default 0.1) */
+    cachedRate?: number;
+};
+export type Decision = {
+    tier: Tier;
+    reason: string;
+};
+export type RouterOptions = {
+    strong: Model;
+    cheap: Model;
+    prices?: {
+        strong: Prices;
+        cheap: Prices;
+    };
+    /** how long a provider keeps a prompt cache warm (ms); default 5 minutes */ ttlMs?: number;
+    onRoute?: (d: Decision & {
+        switched: boolean;
+        promptTokens: number;
+    }) => void;
+    now?: () => number;
+};
+/** What the end of the conversation looks like: how many exploration-only turns in a row, and whether anything just went wrong or needs judgement. */
+export declare function tailShape(messages: Message[]): {
+    streak: number;
+    trouble: boolean;
+    first: boolean;
+    steering: boolean;
+};
+/** The pure decision, separated so it can be tested and tuned: cheap only when the next step is likely exploration AND switching pays for itself. */
+export declare function decide(o: {
+    tail: ReturnType<typeof tailShape>;
+    promptTokens: number;
+    current: Tier;
+    cheapWarm: boolean;
+    prices: {
+        strong: Prices;
+        cheap: Prices;
+    };
+}): Decision;
+export declare function routedModel(o: RouterOptions): Model;
+/** Route each request to a model chosen by your own function (cost, step kind, failures, budget...). `choose` returns a key of `models`; an unknown key falls back to the first model. */
+export declare function choosingModel(models: Record<string, Model>, choose: (info: {
+    messages: Message[];
+    promptTokens: number;
+    tail: ReturnType<typeof tailShape>;
+}) => string, o?: {
+    onChoose?: (key: string) => void;
+}): Model;
+export type RouteInfo = {
+    messages: Message[];
+    promptTokens: number;
+    tail: ReturnType<typeof tailShape>;
+};
+/** Send each request to the model id your function returns (or the base model when it returns nothing). Models are created once per id, on first use. */
+export declare function routedByFunction(base: Model, modelById: (id: string) => Model, route: (info: RouteInfo) => string | undefined | void, o?: {
+    onRoute?: (id: string | undefined) => void;
+}): Model;

package/dist/src/router.js

@@ -0,0 +1,126 @@
+const READ_ONLY = new Set(["read_file", "list_files", "grep", "repo_map", "find_refs", "impact", "skill", "sh_read", "sh_list", "memory_search", "web_search", "fetch_url", "task", "todo_write"]);
+const failed = (s) => /^(ERROR|DENIED|REJECTED|BLOCKED)/.test(s) || /^exit=(?!0\b)/.test(s);
+const tokensOf = (ms) => Math.ceil(ms.reduce((n, m) => n + (m.content?.length ?? 0) + (m.tool_calls ? JSON.stringify(m.tool_calls).length : 0), 0) / 4);
+/** What the end of the conversation looks like: how many exploration-only turns in a row, and whether anything just went wrong or needs judgement. */
+export function tailShape(messages) {
+    const last = messages.at(-1), assistants = messages.filter((m) => m.role === "assistant");
+    const steering = last?.role === "user" && assistants.length > 0;
+    let streak = 0, trouble = false;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m.role !== "assistant")
+            continue;
+        if (!m.tool_calls?.length)
+            break;
+        const names = m.tool_calls.map((c) => c.function.name);
+        if (!names.every((n) => READ_ONLY.has(n)))
+            break;
+        streak++;
+    }
+    // results after the last assistant message
+    const lastA = messages.map((m) => m.role).lastIndexOf("assistant");
+    for (const m of messages.slice(lastA + 1))
+        if (m.role === "tool" && failed(m.content ?? ""))
+            trouble = true;
+    if (last?.role === "user" && /\b(REJECTED|nothing measurable has improved|going in circles|reflect)\b/i.test(last.content ?? ""))
+        trouble = true;
+    return { streak, trouble, first: assistants.length === 0, steering };
+}
+/** The pure decision, separated so it can be tested and tuned: cheap only when the next step is likely exploration AND switching pays for itself. */
+export function decide(o) {
+    const { tail: t, current } = o;
+    if (t.first)
+        return { tier: "strong", reason: "first step: plan with the strong model" };
+    if (t.trouble)
+        return { tier: "strong", reason: "something just failed: escalate" };
+    if (t.steering)
+        return { tier: "strong", reason: "new instruction from the user" };
+    if (t.streak === 0)
+        return { tier: "strong", reason: "last step changed something or answered: judgement needed" };
+    if (current === "cheap")
+        return { tier: "cheap", reason: `exploration continues (streak ${t.streak}), staying on the cheap model` };
+    // currently strong, tempted to go cheap: price the cold read on the cheap model against the per-step saving
+    const cr = (p) => p.cachedRate ?? 0.1, N = o.promptTokens;
+    const coldRead = o.cheapWarm ? 0 : N * o.prices.cheap.input * (1 - cr(o.prices.cheap)); // extra cost of the first call (uncached input)
+    const savingPerStep = N * (o.prices.strong.input * cr(o.prices.strong) - o.prices.cheap.input * cr(o.prices.cheap)); // cached-read price difference on every cheap step
+    if (savingPerStep <= 0)
+        return { tier: "strong", reason: "the cheap model is not cheaper per cached read" };
+    const needed = coldRead / savingPerStep;
+    return t.streak + 1 >= needed ? { tier: "cheap", reason: `exploration streak ${t.streak}: the cold read (${Math.round(coldRead)} units) is repaid in ~${needed.toFixed(1)} steps` } : { tier: "strong", reason: `streak ${t.streak} is too short to repay a cold read on the cheap model (needs ~${needed.toFixed(1)} steps)` };
+}
+export function routedModel(o) {
+    const prices = o.prices ?? { strong: { input: 5, output: 25 }, cheap: { input: 1, output: 5 } }, now = o.now ?? Date.now, ttl = o.ttlMs ?? 300_000;
+    let current = "strong";
+    let cheapWarmUntil = 0;
+    const owner = new WeakMap();
+    const m = async (messages, tools, opts) => {
+        const tail = tailShape(messages), promptTokens = tokensOf(messages);
+        const d = decide({ tail, promptTokens, current, cheapWarm: now() < cheapWarmUntil, prices });
+        // reasoning blobs only make sense to the model that produced them: drop the other tier's
+        const clean = messages.map((x) => (x.role === "assistant" && x.raw !== undefined && owner.get(x.raw) !== d.tier ? { ...x, raw: undefined } : x));
+        const switched = d.tier !== current;
+        current = d.tier;
+        o.onRoute?.({ ...d, switched, promptTokens });
+        let r;
+        if (d.tier === "cheap") {
+            r = await o.cheap(clean, tools, opts ? { signal: opts.signal } : undefined); // not streamed: if the answer has to be redone, nothing half-shown must be left behind
+            cheapWarmUntil = now() + ttl;
+            const needsJudgement = !r.tool_calls?.length || r.tool_calls.some((c) => !READ_ONLY.has(c.function.name));
+            if (needsJudgement) { // the cheap model reached for an edit, a command, or the final answer: that is the strong model's job
+                o.onRoute?.({ tier: "strong", reason: "the cheap model proposed a change or an answer: redone by the strong model", switched: true, promptTokens });
+                current = "strong";
+                r = await o.strong(messages.map((x) => (x.role === "assistant" && x.raw !== undefined && owner.get(x.raw) === "cheap" ? { ...x, raw: undefined } : x)), tools, opts);
+                if (r.raw !== undefined && typeof r.raw === "object" && r.raw)
+                    owner.set(r.raw, "strong");
+                return r;
+            }
+        }
+        else
+            r = await o.strong(clean, tools, opts);
+        if (r.raw !== undefined && typeof r.raw === "object" && r.raw)
+            owner.set(r.raw, d.tier);
+        return r;
+    };
+    m.appendOnly = o.strong.appendOnly || o.cheap.appendOnly;
+    if (o.strong.api)
+        m.api = o.strong.api;
+    return m;
+}
+/** Route each request to a model chosen by your own function (cost, step kind, failures, budget...). `choose` returns a key of `models`; an unknown key falls back to the first model. */
+export function choosingModel(models, choose, o = {}) {
+    const keys = Object.keys(models), call = (async (messages, tools, opts) => {
+        const k = (() => { try {
+            const x = choose({ messages, promptTokens: tokensOf(messages), tail: tailShape(messages) });
+            return x in models ? x : keys[0];
+        }
+        catch {
+            return keys[0];
+        } })();
+        o.onChoose?.(k);
+        return models[k](messages, tools, opts);
+    });
+    return Object.assign(call, models[keys[0]]);
+}
+/** Send each request to the model id your function returns (or the base model when it returns nothing). Models are created once per id, on first use. */
+export function routedByFunction(base, modelById, route, o = {}) {
+    const cache = new Map();
+    const call = (async (messages, tools, opts) => {
+        let id;
+        try {
+            id = route({ messages, promptTokens: tokensOf(messages), tail: tailShape(messages) }) || undefined;
+        }
+        catch {
+            id = undefined;
+        }
+        o.onRoute?.(id);
+        if (!id)
+            return base(messages, tools, opts);
+        let m = cache.get(id);
+        if (!m) {
+            m = modelById(id);
+            cache.set(id, m);
+        }
+        return m(messages, tools, opts);
+    });
+    return Object.assign(call, base);
+}

package/dist/src/sandbox.d.ts

@@ -0,0 +1,13 @@
+export type SandboxMode = "off" | "workspace" | "strict";
+export type SandboxKind = "seatbelt" | "bwrap";
+export declare const SANDBOX_MODES: SandboxMode[];
+/** Which sandbox this machine can provide. */
+export declare function sandboxKind(): SandboxKind | undefined;
+export declare const sandboxHelp: () => "install bubblewrap (apt install bubblewrap); if it is installed, this kernel or container does not allow it to create namespaces" | "sandbox-exec was not found" | "OS sandboxing is only available on macOS and Linux";
+/** The Seatbelt profile: everything allowed except writing outside the allowed folders (and inside .git), and, in strict mode, the network. */
+export declare function seatbeltProfile(workspace: string, mode: SandboxMode): string;
+/** `file` and `args` that run `cmd` under the sandbox, or undefined when mode is off. Throws when a sandbox was asked for and cannot be provided. */
+export declare function wrapCommand(cmd: string, workspace: string, mode: SandboxMode): {
+    file: string;
+    args: string[];
+} | undefined;