amness 0.0.0-stage → 0.1.2

package/dist/src/openai.d.ts

@@ -0,0 +1,50 @@
+import type { Message, Model, ModelOpts } from "./harness.ts";
+/**
+ * Adapter for OpenAI and OpenAI-compatible servers. It speaks two wire APIs:
+ *  - Responses (/v1/responses): what current OpenAI models need. Since GPT-5.4, Chat Completions rejects function tools combined with
+ *    reasoning ("Function tools with reasoning_effort are not supported ... use /v1/responses"), and the GPT-6 family is Responses-first.
+ *  - Chat Completions (/v1/chat/completions): everything else (gpt-4.x, Ollama, vLLM, OpenRouter, most gateways).
+ * `api: "auto"` picks Responses for reasoning models on api.openai.com and Chat elsewhere, and it self-corrects: if a server says to use
+ * /v1/responses it switches, if /v1/responses does not exist it switches back, and if a reasoning option is refused it drops that option.
+ */
+export type Effort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export type OpenAIOptions = {
+    /** Let the caller handle 429 responses (the shared rate limiter does); the adapter still retries timeouts and 5xx. */
+    externalRetry?: boolean;
+    /** Server-side compaction (Responses API): once the prompt passes this many tokens the server compacts the conversation into an opaque item, and we stop re-sending what came before it. Off by default; ignored on servers that do not know the parameter. */
+    compactAt?: number;
+    model?: string;
+    apiKey?: string;
+    baseUrl?: string;
+    retries?: number;
+    /** extra request fields merged into every body */
+    extra?: object;
+    api?: "auto" | "responses" | "chat";
+    /** reasoning effort for reasoning models; omit for the model's default */
+    effort?: Effort;
+    /** ask for reasoning summaries (streamed to `onThinking`). Default on; dropped automatically if the org may not use them. */
+    summary?: boolean;
+    /** let OpenAI keep the response server-side. Default false: stateless, reasoning is replayed by us (encrypted), nothing is retained. */
+    store?: boolean;
+    /** stable key that improves prompt-cache hits across requests (OpenAI only) */
+    promptCacheKey?: string;
+};
+export declare class ApiError extends Error {
+    status: number; /** the server's Retry-After, in milliseconds, when it sent one */
+    retryAfterMs?: number;
+    constructor(status: number, message: string, retryAfterMs?: number);
+}
+export declare const isReasoningModel: (m: string) => boolean;
+export declare const isOpenAIHost: (base: string) => boolean;
+/** Reasoning-effort values a model accepts. Unknown reasoning models get the broad list; the adapter drops a value the server refuses. */
+export declare function effortsFor(model: string): Effort[];
+/** Our transcript -> Responses `instructions` + `input` items. Reasoning/function-call items from the same model are replayed verbatim. */
+export declare function toResponsesInput(msgs: Message[], model: string): {
+    instructions?: string;
+    input: any[];
+};
+/** A finished Responses object -> our Message. `raw` keeps every output item so the next request can replay reasoning. */
+export declare function fromResponse(resp: any, model: string): Message;
+/** Read a streamed Responses call: forward text/reasoning deltas, return the final response object (completed/incomplete). */
+export declare function readResponsesStream(r: Response, h: Pick<ModelOpts, "onText" | "onThinking">): Promise<any>;
+export declare function openai(opts?: OpenAIOptions): Model;

package/dist/src/openai.js

@@ -0,0 +1,307 @@
+export class ApiError extends Error {
+    status; /** the server's Retry-After, in milliseconds, when it sent one */
+    retryAfterMs;
+    constructor(status, message, retryAfterMs) { super(message); this.status = status; this.retryAfterMs = retryAfterMs; }
+}
+export const isReasoningModel = (m) => /^(o\d|gpt-([5-9]|\d{2,}))/i.test(m);
+export const isOpenAIHost = (base) => { try {
+    return new URL(base).hostname === "api.openai.com";
+}
+catch {
+    return false;
+} };
+/** Reasoning-effort values a model accepts. Unknown reasoning models get the broad list; the adapter drops a value the server refuses. */
+export function effortsFor(model) {
+    if (!isReasoningModel(model))
+        return [];
+    if (/gpt-6(\.\d+)?-(astra|sol)/i.test(model))
+        return ["low", "medium", "high", "xhigh", "max"]; // no `none` / `minimal` on the big models
+    return ["none", "low", "medium", "high", "xhigh", "max"];
+}
+// ------------------------------------------------------------------ Responses API: request side
+/** Our transcript -> Responses `instructions` + `input` items. Reasoning/function-call items from the same model are replayed verbatim. */
+export function toResponsesInput(msgs, model) {
+    let instructions;
+    const input = [];
+    for (const m of msgs) {
+        if (m.role === "system")
+            instructions = (instructions ? instructions + "\n\n" : "") + (m.content ?? "");
+        else if (m.role === "user")
+            input.push({ role: "user", content: m.images?.length ? [{ type: "input_text", text: m.content || "(continue)" }, ...m.images.map((i) => ({ type: "input_image", image_url: `data:${i.mime};base64,${i.data}` }))] : m.content || "(continue)" });
+        else if (m.role === "tool")
+            input.push({ type: "function_call_output", call_id: m.tool_call_id, output: m.content ?? "" });
+        else {
+            const raw = m.raw;
+            if (raw?.api === "responses" && raw.model === model && Array.isArray(raw.items)) {
+                input.push(...raw.items);
+                continue;
+            } // keeps encrypted reasoning
+            if (m.content)
+                input.push({ role: "assistant", content: m.content });
+            for (const c of m.tool_calls ?? [])
+                input.push({ type: "function_call", call_id: c.id, name: c.function.name, arguments: c.function.arguments || "{}" });
+        }
+    }
+    // Everything before the newest compaction item is already inside it: sending it again would defeat the point.
+    let cut = -1;
+    input.forEach((it, i) => { if (it?.type === "compaction")
+        cut = i; });
+    return { instructions, input: cut > 0 ? input.slice(cut) : input };
+}
+const toResponsesTool = (t) => ({
+    type: "function", name: t.name, description: t.description || undefined,
+    parameters: t.parameters.type === "object" ? t.parameters : { type: "object", properties: {} },
+    strict: false, // our schemas are not strict-mode shaped; be explicit instead of letting the API guess
+});
+// ------------------------------------------------------------------ Responses API: response side
+/** A finished Responses object -> our Message. `raw` keeps every output item so the next request can replay reasoning. */
+export function fromResponse(resp, model) {
+    const items = resp.output ?? [];
+    let text = "", calls = [], keep = items;
+    for (const it of items) {
+        if (it.type === "message")
+            for (const c of it.content ?? [])
+                text += c.type === "output_text" ? c.text : c.type === "refusal" ? `[declined] ${c.refusal}` : "";
+        else if (it.type === "function_call")
+            calls.push({ id: it.call_id, type: "function", function: { name: it.name, arguments: it.arguments || "{}" } });
+    }
+    if (resp.status === "incomplete" && resp.incomplete_details?.reason === "max_output_tokens" && calls.length) {
+        // a tool call cut off mid-JSON must never run; drop it (and reasoning, which is invalid without its follow-up item) and nudge a smaller step
+        calls = [];
+        keep = items.filter((i) => i.type === "message");
+        text = `${text}\n[output hit the max_output_tokens limit; I'll redo that in smaller steps]`.trim();
+    }
+    const u = resp.usage ?? {};
+    return {
+        role: "assistant", content: text || null, ...(calls.length && { tool_calls: calls }), raw: { api: "responses", model, items: keep },
+        usage: {
+            prompt_tokens: u.input_tokens ?? 0, completion_tokens: u.output_tokens ?? 0, total_tokens: u.total_tokens ?? (u.input_tokens ?? 0) + (u.output_tokens ?? 0),
+            cached_tokens: u.input_tokens_details?.cached_tokens ?? 0, reasoning_tokens: u.output_tokens_details?.reasoning_tokens ?? 0,
+        },
+    };
+}
+/** Read a streamed Responses call: forward text/reasoning deltas, return the final response object (completed/incomplete). */
+export async function readResponsesStream(r, h) {
+    const items = [];
+    let final, buf = "";
+    const dec = new TextDecoder();
+    const handle = (j) => {
+        switch (j.type) {
+            case "response.output_text.delta":
+                if (j.delta)
+                    h.onText?.(j.delta);
+                break;
+            case "response.reasoning_summary_text.delta":
+                if (j.delta)
+                    h.onThinking?.(j.delta);
+                break;
+            case "response.output_item.done":
+                items[j.output_index ?? items.length] = j.item;
+                break;
+            case "response.completed":
+            case "response.incomplete":
+                final = j.response;
+                break;
+            case "response.failed": throw new Error(`response failed: ${j.response?.error?.message ?? "unknown error"}`);
+            case "error": throw new Error(j.message ?? j.error?.message ?? "stream error");
+        }
+    };
+    for await (const chunk of r.body) {
+        buf += dec.decode(chunk, { stream: true });
+        for (let i; (i = buf.indexOf("\n")) >= 0;) {
+            const line = buf.slice(0, i).trim();
+            buf = buf.slice(i + 1);
+            if (!line.startsWith("data:") || line.includes("[DONE]"))
+                continue;
+            let j;
+            try {
+                j = JSON.parse(line.slice(5));
+            }
+            catch {
+                continue;
+            }
+            handle(j);
+        }
+    }
+    if (final) {
+        if (!final.output?.length && items.length)
+            final.output = items.filter(Boolean);
+        return final;
+    }
+    if (items.length)
+        return { output: items.filter(Boolean), status: "incomplete", incomplete_details: { reason: "stream_ended" } };
+    throw new Error("the response stream ended before it completed");
+}
+// ------------------------------------------------------------------ Chat Completions: streaming reader
+async function readChatStream(r, onText) {
+    const calls = [];
+    let content = "", usage, buf = "";
+    const dec = new TextDecoder();
+    for await (const chunk of r.body) {
+        buf += dec.decode(chunk, { stream: true });
+        for (let i; (i = buf.indexOf("\n")) >= 0;) {
+            const line = buf.slice(0, i).trim();
+            buf = buf.slice(i + 1);
+            if (!line.startsWith("data:") || line.includes("[DONE]"))
+                continue;
+            let j;
+            try {
+                j = JSON.parse(line.slice(5));
+            }
+            catch {
+                continue;
+            }
+            if (j.usage)
+                usage = { prompt_tokens: j.usage.prompt_tokens, completion_tokens: j.usage.completion_tokens, total_tokens: j.usage.total_tokens, cached_tokens: j.usage.prompt_tokens_details?.cached_tokens, reasoning_tokens: j.usage.completion_tokens_details?.reasoning_tokens };
+            const d = j.choices?.[0]?.delta;
+            if (!d)
+                continue;
+            if (d.content) {
+                content += d.content;
+                onText(d.content);
+            }
+            for (const tc of d.tool_calls ?? []) {
+                const c = (calls[tc.index ?? 0] ??= { id: "", type: "function", function: { name: "", arguments: "" } });
+                if (tc.id)
+                    c.id = tc.id;
+                if (tc.function?.name)
+                    c.function.name += tc.function.name;
+                if (tc.function?.arguments)
+                    c.function.arguments += tc.function.arguments;
+            }
+        }
+    }
+    const tool_calls = calls.filter(Boolean);
+    return { role: "assistant", content: content || null, ...(tool_calls.length && { tool_calls }), usage };
+}
+// ------------------------------------------------------------------ the adapter
+export function openai(opts = {}) {
+    const base = (opts.baseUrl ?? process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1").replace(/\/$/, "");
+    const key = opts.apiKey ?? process.env.OPENAI_API_KEY ?? "";
+    const model = opts.model ?? process.env.AMNESS_MODEL ?? "gpt-6.1-sol";
+    const retries = opts.retries ?? 4;
+    const official = isOpenAIHost(base);
+    const mode = opts.api ?? "auto";
+    // adapter state that self-corrects at runtime
+    // optional request fields a server may not know; if it says so we stop sending that one field
+    const OPTIONAL = ["prompt_cache_key", "prompt_cache_retention", "include", "stream_options", "parallel_tool_calls", "context_management"], dropped = new Set();
+    let useResponses = mode === "responses" || (mode === "auto" && official && isReasoningModel(model));
+    let sendSummary = opts.summary ?? true, sendEffort = opts.effort !== undefined, chatNoReasoning = false, flips = 0, chatRefused = false;
+    /** POST with retry/backoff on 408/429/5xx and network errors; other 4xx become ApiError immediately. */
+    async function post(path, body, signal) {
+        const payload = JSON.stringify(body);
+        for (let i = 0;; i++) {
+            let err;
+            try {
+                const r = await fetch(base + path, { method: "POST", body: payload, signal, headers: { "content-type": "application/json", authorization: `Bearer ${key}` } });
+                if (r.ok)
+                    return r;
+                const status = r.status, text = await r.text();
+                const ra = r.headers.get("retry-after-ms") ? Number(r.headers.get("retry-after-ms")) : r.headers.get("retry-after") && Number.isFinite(Number(r.headers.get("retry-after"))) ? Number(r.headers.get("retry-after")) * 1000 : undefined;
+                err = new ApiError(status, `HTTP ${status}: ${text}`, ra);
+                if (status !== 408 && status !== 429 && status < 500)
+                    throw err;
+                if (status === 429 && opts.externalRetry)
+                    throw err; // a shared rate limiter owns 429s: retrying here would bypass it
+            }
+            catch (e) {
+                if (e instanceof ApiError && e.status !== 408 && e.status !== 429 && e.status < 500)
+                    throw e;
+                if (signal?.aborted)
+                    throw e;
+                err = e;
+            }
+            if (i >= retries - 1)
+                throw err;
+            await new Promise((res) => setTimeout(res, Math.max(2 ** i * 1000, err.retryAfterMs ?? 0) + Math.random() * 500));
+        }
+    }
+    async function viaResponses(messages, tools, o) {
+        const { instructions, input } = toResponsesInput(messages, model);
+        const reasoning = isReasoningModel(model) ? { ...(sendEffort && opts.effort ? { effort: opts.effort } : {}), ...(sendSummary ? { summary: "auto" } : {}) } : undefined;
+        const store = opts.store ?? false;
+        const body = {
+            model, input, ...(instructions && { instructions }), store, stream: !!o.onText,
+            ...(tools.length && { tools: tools.map(toResponsesTool), tool_choice: "auto" }),
+            ...(reasoning && Object.keys(reasoning).length && { reasoning }),
+            ...(reasoning && !store && { include: ["reasoning.encrypted_content"] }), // older reasoning models only return the replayable blob when asked; newer ones always do
+            ...(opts.promptCacheKey && official && { prompt_cache_key: opts.promptCacheKey, prompt_cache_retention: "24h" }), // keep the cached prefix alive across idle gaps; dropped automatically if a model refuses it
+            ...(opts.compactAt && official && { context_management: [{ type: "compaction", compact_threshold: opts.compactAt }] }),
+            ...opts.extra,
+        };
+        for (const k of dropped)
+            delete body[k];
+        const r = await post("/responses", body, o.signal);
+        const resp = (r.headers.get("content-type") ?? "").includes("text/event-stream") ? await readResponsesStream(r, o) : await r.json();
+        if (resp.error)
+            throw new Error(`response failed: ${resp.error.message ?? JSON.stringify(resp.error)}`);
+        return fromResponse(resp, model);
+    }
+    async function viaChat(messages, tools, o) {
+        const stream = !!o.onText;
+        const body = {
+            model, // only wire fields: `raw` / `usage` belong to other adapters, and replayed tool calls need an explicit type
+            messages: messages.map(({ role, content, tool_calls, tool_call_id, images }) => ({ role, content: images?.length ? [{ type: "text", text: content || "(continue)" }, ...images.map((i) => ({ type: "image_url", image_url: { url: `data:${i.mime};base64,${i.data}` } }))] : content, ...(tool_calls && { tool_calls: tool_calls.map((c) => ({ id: c.id, type: "function", function: c.function })) }), ...(tool_call_id && { tool_call_id }) })),
+            ...(tools.length && { tools: tools.map((t) => ({ type: "function", function: t })) }),
+            ...(stream && { stream: true, stream_options: { include_usage: true } }),
+            ...(chatNoReasoning && isReasoningModel(model) ? { reasoning_effort: "none" } : opts.effort && isReasoningModel(model) && sendEffort ? { reasoning_effort: opts.effort } : {}),
+            ...opts.extra,
+        };
+        for (const k of dropped)
+            delete body[k];
+        const r = await post("/chat/completions", body, o.signal);
+        if ((r.headers.get("content-type") ?? "").includes("text/event-stream"))
+            return readChatStream(r, o.onText ?? (() => { }));
+        const j = await r.json(), m = j.choices[0].message; // server ignored `stream`, or we did not ask
+        if (stream && m.content)
+            o.onText(m.content);
+        const u = j.usage ?? {};
+        return { ...m, usage: { prompt_tokens: u.prompt_tokens, completion_tokens: u.completion_tokens, total_tokens: u.total_tokens, cached_tokens: u.prompt_tokens_details?.cached_tokens, reasoning_tokens: u.completion_tokens_details?.reasoning_tokens } };
+    }
+    const call = async (messages, tools, o2) => {
+        const o = o2 ?? {};
+        for (let step = 0;; step++) {
+            try {
+                return useResponses ? await viaResponses(messages, tools, o) : await viaChat(messages, tools, o);
+            }
+            catch (e) {
+                if (!(e instanceof ApiError) || step >= 6)
+                    throw e;
+                const msg = e.message;
+                const refused = e.status === 400 && /unknown|unsupported|unrecognized|not permitted|invalid/i.test(msg) ? OPTIONAL.find((k) => msg.includes(k) && !dropped.has(k)) : undefined;
+                if (refused) {
+                    dropped.add(refused);
+                    continue;
+                } // e.g. a gateway that has never heard of prompt_cache_key
+                // the server tells us which endpoint to use
+                if (!useResponses && e.status === 400 && /\/v1\/responses|responses api/i.test(msg) && mode !== "chat" && flips++ < 2) {
+                    useResponses = true;
+                    chatRefused = true;
+                    continue;
+                }
+                if (!useResponses && e.status === 400 && /reasoning_effort/i.test(msg) && !chatNoReasoning) {
+                    chatNoReasoning = true;
+                    continue;
+                } // documented workaround: tools + reasoning_effort "none"
+                if (useResponses && (e.status === 404 || e.status === 405) && mode !== "responses" && flips++ < 2) {
+                    useResponses = false;
+                    if (chatRefused)
+                        chatNoReasoning = true;
+                    continue;
+                } // gateway has no /responses: back to chat, already using the workaround
+                // a reasoning option this account/model refuses: drop just that option and carry on
+                if (useResponses && e.status === 400 && sendSummary && /summary|verif/i.test(msg)) {
+                    sendSummary = false;
+                    continue;
+                }
+                if (useResponses && e.status === 400 && sendEffort && /effort|reasoning/i.test(msg)) {
+                    sendEffort = false;
+                    continue;
+                }
+                throw e;
+            }
+        }
+    };
+    call.api = () => (useResponses ? "responses" : "chat");
+    return call;
+}

package/dist/src/parallel.d.ts

@@ -0,0 +1,66 @@
+export type Attempt = {
+    summary?: string;
+    tokens?: number;
+};
+export type Candidate = {
+    index: number;
+    diff: string;
+    tokens: number;
+    summary?: string;
+    passed: boolean;
+    extraPassed: number;
+    verifyOutput: string;
+    error?: string;
+};
+export type BestOfNOptions = {
+    repo: string;
+    n: number;
+    /** Do the work in `dir` (a fresh worktree of HEAD). `index` is 0-based; use it to vary the attempt if you like. */
+    attempt: (dir: string, index: number) => Promise<Attempt>;
+    /** The user's verify command: a candidate that fails it is never chosen. */
+    verify?: string;
+    /** Extra commands (for example generated tests): among passing candidates, the one passing most of these wins. */
+    extraChecks?: string[];
+    /** Optional last-resort judge over the passing candidates that are still tied; returns the index of its pick. */
+    judge?: (c: Candidate[]) => Promise<number>;
+    /** Stop starting attempts after this many tokens in total. */
+    maxTokens?: number;
+    /** Run all n at once instead of one by one until one passes. Costs n attempts every time. */
+    parallel?: boolean;
+    /** Apply the winner's diff to `repo`. */
+    apply?: boolean;
+    onCandidate?: (c: Candidate) => void;
+};
+export type BestOfNResult = {
+    winner?: Candidate;
+    candidates: Candidate[];
+    tokens: number;
+    stoppedForBudget: boolean;
+    applied?: boolean;
+    applyError?: string;
+};
+export declare function bestOfN(o: BestOfNOptions): Promise<BestOfNResult>;
+export type Part = {
+    name: string;
+    task: string;
+};
+export type PartResult = {
+    part: Part;
+    status: "merged" | "failed-verify" | "conflict" | "broke-verify" | "no-change" | "error" | "skipped-budget";
+    tokens: number;
+    summary?: string;
+    detail?: string;
+};
+export type ParallelOptions = {
+    repo: string;
+    parts: Part[];
+    attempt: (part: Part, dir: string) => Promise<Attempt>;
+    verify?: string;
+    maxTokens?: number;
+    concurrency?: number;
+    onPart?: (r: PartResult) => void;
+};
+export declare function parallelParts(o: ParallelOptions): Promise<{
+    results: PartResult[];
+    tokens: number;
+}>;

package/dist/src/parallel.js

@@ -0,0 +1,135 @@
+// Several agents at once, each in its own git worktree so they cannot disturb each other or your working tree. Two uses:
+//   bestOfN       the same task attempted up to n times; a candidate must pass your verify command, then ties are broken by extra checks, an optional judge, and diff size.
+//                 By default attempts run one at a time and stop at the first pass (escalation), so the extra cost is only paid for tasks that need it.
+//   parallelParts independent parts of a task run concurrently; each part must pass verify in its own worktree, and parts are then merged one at a time through verify again.
+//                 A part that conflicts or breaks verify after merging is reverted and reported, never left half-applied.
+// Budgets are explicit: every attempt reports its tokens, and no new attempt starts once the cap is reached.
+import { runShell } from "./code.js";
+import { applyDiff, createWorktree, removeWorktree, revertDiff, worktreeDiff } from "./worktree.js";
+const passes = async (cmd, dir) => { if (!cmd)
+    return { ok: true, out: "" }; const out = await runShell(cmd, dir, 300_000); return { ok: out.startsWith("exit=0"), out }; };
+const lines = (d) => d.split("\n").length;
+export async function bestOfN(o) {
+    const candidates = [];
+    let tokens = 0, stoppedForBudget = false;
+    const one = async (index) => {
+        const w = await createWorktree(o.repo);
+        const c = { index, diff: "", tokens: 0, passed: false, extraPassed: 0, verifyOutput: "" };
+        try {
+            const a = await o.attempt(w.dir, index);
+            c.tokens = a.tokens ?? 0;
+            c.summary = a.summary;
+            c.diff = await worktreeDiff(w);
+            if (c.diff) {
+                const v = await passes(o.verify, w.dir);
+                c.passed = v.ok;
+                c.verifyOutput = v.out.slice(0, 1500);
+                if (c.passed)
+                    for (const x of o.extraChecks ?? [])
+                        if ((await passes(x, w.dir)).ok)
+                            c.extraPassed++;
+            }
+        }
+        catch (e) {
+            c.error = e.message;
+        }
+        finally {
+            await removeWorktree(w);
+        }
+        tokens += c.tokens;
+        candidates.push(c);
+        o.onCandidate?.(c);
+        return c;
+    };
+    if (o.parallel)
+        await Promise.all(Array.from({ length: o.n }, (_, i) => one(i)));
+    else
+        for (let i = 0; i < o.n; i++) {
+            if (o.maxTokens !== undefined && tokens >= o.maxTokens) {
+                stoppedForBudget = true;
+                break;
+            }
+            const c = await one(i);
+            if (c.passed && !(o.extraChecks?.length))
+                break; // with extra checks, a first pass is still compared against later ones only if it missed some
+            if (c.passed && c.extraPassed === (o.extraChecks?.length ?? 0))
+                break;
+        }
+    candidates.sort((a, b) => a.index - b.index);
+    let pool = candidates.filter((c) => c.passed);
+    const best = Math.max(0, ...pool.map((c) => c.extraPassed));
+    pool = pool.filter((c) => c.extraPassed === best);
+    if (pool.length > 1 && o.judge) {
+        const pick = await o.judge(pool).catch(() => -1);
+        const w = pool.find((c) => c.index === pick);
+        if (w)
+            pool = [w];
+    }
+    const winner = pool.sort((a, b) => lines(a.diff) - lines(b.diff) || a.index - b.index)[0];
+    const res = { winner, candidates, tokens, stoppedForBudget };
+    if (o.apply && winner) {
+        const err = await applyDiff(o.repo, winner.diff);
+        res.applied = !err;
+        res.applyError = err;
+    }
+    return res;
+}
+export async function parallelParts(o) {
+    const done = [];
+    let tokens = 0, next = 0;
+    const worker = async () => {
+        while (next < o.parts.length) {
+            const part = o.parts[next++];
+            if (o.maxTokens !== undefined && tokens >= o.maxTokens) {
+                done.push({ part, diff: "", tokens: 0, res: { part, status: "skipped-budget", tokens: 0, detail: "token cap reached before this part started" } });
+                continue;
+            }
+            const w = await createWorktree(o.repo);
+            const d = { part, diff: "", tokens: 0 };
+            try {
+                const a = await o.attempt(part, w.dir);
+                d.tokens = a.tokens ?? 0;
+                d.summary = a.summary;
+                tokens += d.tokens;
+                d.diff = await worktreeDiff(w);
+                if (!d.diff)
+                    d.res = { part, status: "no-change", tokens: d.tokens, summary: a.summary };
+                else {
+                    const v = await passes(o.verify, w.dir);
+                    if (!v.ok)
+                        d.res = { part, status: "failed-verify", tokens: d.tokens, summary: a.summary, detail: v.out.slice(0, 800) };
+                }
+            }
+            catch (e) {
+                d.res = { part, status: "error", tokens: d.tokens, detail: e.message };
+            }
+            finally {
+                await removeWorktree(w);
+            }
+            done.push(d);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(o.concurrency ?? o.parts.length, o.parts.length)) }, worker));
+    done.sort((a, b) => o.parts.indexOf(a.part) - o.parts.indexOf(b.part));
+    const results = [];
+    for (const d of done) { // merge strictly one at a time, in the order given
+        let r = d.res;
+        if (!r) {
+            const err = await applyDiff(o.repo, d.diff);
+            if (err)
+                r = { part: d.part, status: "conflict", tokens: d.tokens, summary: d.summary, detail: err.slice(0, 400) };
+            else {
+                const v = await passes(o.verify, o.repo);
+                if (v.ok)
+                    r = { part: d.part, status: "merged", tokens: d.tokens, summary: d.summary };
+                else {
+                    await revertDiff(o.repo, d.diff);
+                    r = { part: d.part, status: "broke-verify", tokens: d.tokens, summary: d.summary, detail: v.out.slice(0, 800) };
+                }
+            }
+        }
+        results.push(r);
+        o.onPart?.(r);
+    }
+    return { results, tokens };
+}

package/dist/src/patch.d.ts

@@ -0,0 +1,45 @@
+export type Line = {
+    t: " " | "-" | "+";
+    s: string;
+};
+export type Hunk = {
+    anchor?: string;
+    lines: Line[]; /** line number hint from a unified diff (1-based) */
+    hint?: number;
+};
+export type FileOp = {
+    path: string;
+    op: "update" | "add" | "delete";
+    moveTo?: string;
+    hunks: Hunk[];
+};
+export declare function parsePatch(text: string): FileOp[];
+/** Every path a patch touches (for permission checks). */
+export declare function patchPaths(text: string): string[];
+export type Applied = {
+    path: string;
+    before: string | null;
+    after: string | null;
+    fuzzy: number;
+};
+export declare function applyOps(ops: FileOp[], read: (path: string) => string | undefined): {
+    applied: Applied[];
+    errors: string[];
+};
+/** Replace `old` by `nw` in `content`: exactly once. When there is no exact match and `old` spans whole lines, a match that differs only in indentation or trailing space is accepted if it is unique (and reported). */
+export declare function replaceOnce(content: string, old: string, nw: string): {
+    out: string;
+    fuzzy?: boolean;
+} | {
+    error: string;
+};
+/** Apply several edits in order to one file's text; all-or-nothing. */
+export declare function replaceMany(content: string, edits: {
+    old: string;
+    new: string;
+}[]): {
+    out: string;
+    fuzzy: number;
+} | {
+    error: string;
+};