@bluewombat/implementer 0.1.0

package/dist/child/run-child.js

@@ -0,0 +1,141 @@
+import { spawn } from "node:child_process";
+// Two bounds, for two different things.
+//
+// The first protects this process: a child that writes without end is not one
+// whose answer can be read, so past this much it is killed and reported as
+// broken. No sane child comes near it, and nothing a child says is cut by it.
+const OUTPUT_LIMIT_CHARS = 8 * 1024 * 1024;
+// The second protects the ledger: when a child left no contract line, its
+// stdout and stderr become the report, and only their end — where a crash says
+// why — is kept. Same size as the tracker keeps of a report.
+const REPORT_KEEP_CHARS = 8_192;
+function keepEnd(text) {
+    if (text.length <= REPORT_KEEP_CHARS) {
+        return text;
+    }
+    return `[…${text.length - REPORT_KEEP_CHARS} characters cut]${text.slice(-REPORT_KEEP_CHARS)}`;
+}
+function killProcessTree(child) {
+    try {
+        child.kill("SIGKILL");
+    }
+    catch {
+        // already gone
+    }
+}
+/**
+ * Run one child with a wall-clock timeout. Does not inherit Implementer stdin.
+ */
+export function runChild(request) {
+    return new Promise((resolve) => {
+        const [file, ...args] = request.argv;
+        if (file === undefined) {
+            resolve({ kind: "spawn_error", detail: "Empty command." });
+            return;
+        }
+        let settled = false;
+        let timedOut = false;
+        let interrupted = false;
+        let stdout = "";
+        let stderr = "";
+        let timer;
+        let interruptPoll;
+        const finish = (outcome) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+            if (interruptPoll !== undefined) {
+                clearInterval(interruptPoll);
+            }
+            resolve(outcome);
+        };
+        let child;
+        try {
+            child = spawn(file, args, {
+                cwd: request.cwd,
+                env: request.env,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            finish({ kind: "spawn_error", detail });
+            return;
+        }
+        if (!child.stdout || !child.stderr) {
+            finish({ kind: "spawn_error", detail: "Child stdout/stderr pipes unavailable." });
+            return;
+        }
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        let overflowed = false;
+        const take = (chunk) => {
+            if (overflowed) {
+                return false;
+            }
+            if (stdout.length + stderr.length + chunk.length > OUTPUT_LIMIT_CHARS) {
+                overflowed = true;
+                killProcessTree(child);
+                return false;
+            }
+            return true;
+        };
+        child.stdout.on("data", (chunk) => {
+            if (take(chunk)) {
+                stdout += chunk;
+            }
+        });
+        child.stderr.on("data", (chunk) => {
+            if (take(chunk)) {
+                stderr += chunk;
+            }
+        });
+        child.on("error", (error) => {
+            finish({ kind: "spawn_error", detail: error.message });
+        });
+        timer = setTimeout(() => {
+            timedOut = true;
+            killProcessTree(child);
+        }, Math.max(1, request.timeoutMs));
+        interruptPoll = setInterval(() => {
+            if (request.shouldInterrupt()) {
+                interrupted = true;
+                killProcessTree(child);
+            }
+        }, 20);
+        if (request.shouldInterrupt()) {
+            interrupted = true;
+            killProcessTree(child);
+        }
+        child.on("close", (exitCode, signal) => {
+            const out = stdout;
+            const err = stderr;
+            if (overflowed) {
+                finish({
+                    kind: "spawn_error",
+                    detail: `Child wrote more than ${OUTPUT_LIMIT_CHARS} characters; its answer cannot be read.`,
+                });
+                return;
+            }
+            if (interrupted || request.shouldInterrupt()) {
+                finish({ kind: "interrupted", stdout: out, stderr: err });
+                return;
+            }
+            if (timedOut) {
+                finish({ kind: "timed_out", stdout: out, stderr: err });
+                return;
+            }
+            finish({ kind: "exited", exitCode, signal, stdout: out, stderr: err });
+        });
+    });
+}
+/** The fallback report of a child that left no contract line: its last words. */
+export function combinedOutput(stdout, stderr) {
+    const parts = [stdout, stderr].filter((p) => p.length > 0);
+    return keepEnd(parts.join("\n"));
+}
+//# sourceMappingURL=run-child.js.map

package/dist/child/run-child.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-child.js","sourceRoot":"","sources":["../../src/child/run-child.ts"],"names":[],"mappings":"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"}

package/dist/child/run-gate.d.ts

@@ -0,0 +1,14 @@
+import type { GateSpec, GateTraceEntry, Invocation } from "../types.js";
+export type GateRunResult = {
+    entry: GateTraceEntry;
+    /** When not pass, the Attempt ends with this (or interrupted). */
+    stop?: "fail-retryable" | "fail-blocking" | "interrupted";
+};
+export declare function runGate(input: {
+    invocation: Invocation;
+    attempt: number;
+    gate: GateSpec;
+    timeoutMs: number;
+    shouldInterrupt: () => boolean;
+}): Promise<GateRunResult>;
+//# sourceMappingURL=run-gate.d.ts.map

package/dist/child/run-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-gate.d.ts","sourceRoot":"","sources":["../../src/child/run-gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIxE,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,cAAc,CAAC;IACtB,kEAAkE;IAClE,IAAI,CAAC,EAAE,gBAAgB,GAAG,eAAe,GAAG,aAAa,CAAC;CAC3D,CAAC;AAEF,wBAAsB,OAAO,CAAC,KAAK,EAAE;IACnC,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,OAAO,CAAC;CAChC,GAAG,OAAO,CAAC,aAAa,CAAC,CA2BzB"}

package/dist/child/run-gate.js

@@ -0,0 +1,72 @@
+import { parseGateVerdictJson } from "./parse-child-output.js";
+import { runChild } from "./run-child.js";
+export async function runGate(input) {
+    const { invocation, attempt, gate, timeoutMs, shouldInterrupt } = input;
+    const argv = [
+        ...gate.argv,
+        "--id",
+        invocation.id,
+        "--attempt",
+        String(attempt),
+        "--gate-id",
+        gate.id,
+        "--intention",
+        invocation.intention,
+        "--definition-of-done",
+        invocation.definitionOfDone,
+        "--stage",
+        invocation.stage ?? "unit",
+    ];
+    const outcome = await runChild({
+        argv,
+        cwd: invocation.workspace,
+        timeoutMs,
+        shouldInterrupt,
+    });
+    return interpretGateOutcome(gate.id, outcome, timeoutMs);
+}
+function interpretGateOutcome(gateId, outcome, timeoutMs) {
+    if (outcome.kind === "spawn_error") {
+        return {
+            entry: { id: gateId, verdict: "fail-blocking", report: outcome.detail },
+            stop: "fail-blocking",
+        };
+    }
+    if (outcome.kind === "interrupted") {
+        return {
+            entry: { id: gateId, verdict: "fail-blocking", report: "stop signal" },
+            stop: "interrupted",
+        };
+    }
+    if (outcome.kind === "timed_out") {
+        const report = `killed after ${timeoutMs}ms, its own ceiling`;
+        return {
+            entry: { id: gateId, verdict: "fail-retryable", report },
+            stop: "fail-retryable",
+        };
+    }
+    const parsed = parseGateVerdictJson(outcome.stdout);
+    if (!parsed) {
+        return {
+            entry: {
+                id: gateId,
+                verdict: "fail-blocking",
+                report: "Gate stdout is not a JSON object with a known verdict.",
+            },
+            stop: "fail-blocking",
+        };
+    }
+    const entry = {
+        id: gateId,
+        verdict: parsed.verdict,
+        report: parsed.report,
+    };
+    if (parsed.verdict === "pass") {
+        return { entry };
+    }
+    return {
+        entry,
+        stop: parsed.verdict,
+    };
+}
+//# sourceMappingURL=run-gate.js.map

package/dist/child/run-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-gate.js","sourceRoot":"","sources":["../../src/child/run-gate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAqB,MAAM,gBAAgB,CAAC;AAQ7D,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,KAM7B;IACC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,eAAe,EAAE,GAAG,KAAK,CAAC;IAExE,MAAM,IAAI,GAAG;QACX,GAAG,IAAI,CAAC,IAAI;QACZ,MAAM;QACN,UAAU,CAAC,EAAE;QACb,WAAW;QACX,MAAM,CAAC,OAAO,CAAC;QACf,WAAW;QACX,IAAI,CAAC,EAAE;QACP,aAAa;QACb,UAAU,CAAC,SAAS;QACpB,sBAAsB;QACtB,UAAU,CAAC,gBAAgB;QAC3B,SAAS;QACT,UAAU,CAAC,KAAK,IAAI,MAAM;KAC3B,CAAC;IAEF,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC;QAC7B,IAAI;QACJ,GAAG,EAAE,UAAU,CAAC,SAAS;QACzB,SAAS;QACT,eAAe;KAChB,CAAC,CAAC;IAEH,OAAO,oBAAoB,CAAC,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;AAC3D,CAAC;AAED,SAAS,oBAAoB,CAC3B,MAAc,EACd,OAAqB,EACrB,SAAiB;IAEjB,IAAI,OAAO,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;QACnC,OAAO;YACL,KAAK,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;YACvE,IAAI,EAAE,eAAe;SACtB,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;QACnC,OAAO;YACL,KAAK,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,aAAa,EAAE;YACtE,IAAI,EAAE,aAAa;SACpB,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,gBAAgB,SAAS,qBAAqB,CAAC;QAC9D,OAAO;YACL,KAAK,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE;YACxD,IAAI,EAAE,gBAAgB;SACvB,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACpD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO;YACL,KAAK,EAAE;gBACL,EAAE,EAAE,MAAM;gBACV,OAAO,EAAE,eAAe;gBACxB,MAAM,EAAE,wDAAwD;aACjE;YACD,IAAI,EAAE,eAAe;SACtB,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAmB;QAC5B,EAAE,EAAE,MAAM;QACV,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;KACtB,CAAC;IAEF,IAAI,MAAM,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;QAC9B,OAAO,EAAE,KAAK,EAAE,CAAC;IACnB,CAAC;IAED,OAAO;QACL,KAAK;QACL,IAAI,EAAE,MAAM,CAAC,OAAO;KACrB,CAAC;AACJ,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { parseArgs } from "./args/parse-args.js";
+import { createStdoutProgressWriter } from "./progress/emit.js";
+import { invalidInvocationResult, runImplementer } from "./run/run-implementer.js";
+/**
+ * Process signals belong to the binary, not to the Transformer: a Transformer imported into
+ * a host must not hijack the host's SIGINT. The CLI owns the flag it passes in.
+ */
+function installSignalHandlers(state) {
+    const onSignal = () => {
+        state.interrupted = true;
+    };
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+    return () => {
+        process.off("SIGINT", onSignal);
+        process.off("SIGTERM", onSignal);
+    };
+}
+async function main(argv) {
+    const write = createStdoutProgressWriter();
+    const parsed = parseArgs(argv);
+    if (!parsed.ok) {
+        const result = invalidInvocationResult(undefined, write, parsed.reason);
+        return result.exitCode;
+    }
+    const interruptFlag = { interrupted: false };
+    const detachSignals = installSignalHandlers(interruptFlag);
+    try {
+        const result = await runImplementer({
+            invocation: parsed.invocation,
+            write,
+            interruptFlag,
+            cwd: process.cwd(),
+        });
+        return result.exitCode;
+    }
+    finally {
+        detachSignals();
+    }
+}
+const exitCode = await main(process.argv.slice(2));
+process.exitCode = exitCode;
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAEnF;;;GAGG;AACH,SAAS,qBAAqB,CAAC,KAA+B;IAC5D,MAAM,QAAQ,GAAG,GAAS,EAAE;QAC1B,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC;IAC3B,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAChC,OAAO,GAAG,EAAE;QACV,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAChC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IACnC,CAAC,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,IAAI,CAAC,IAAc;IAChC,MAAM,KAAK,GAAG,0BAA0B,EAAE,CAAC;IAC3C,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,uBAAuB,CAAC,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACxE,OAAO,MAAM,CAAC,QAAQ,CAAC;IACzB,CAAC;IAED,MAAM,aAAa,GAAG,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;IAC7C,MAAM,aAAa,GAAG,qBAAqB,CAAC,aAAa,CAAC,CAAC;IAC3D,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC;YAClC,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,KAAK;YACL,aAAa;YACb,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;SACnB,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,QAAQ,CAAC;IACzB,CAAC;YAAS,CAAC;QACT,aAAa,EAAE,CAAC;IAClB,CAAC;AACH,CAAC;AAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACnD,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Import entry point for this Transformer.
+ *
+ * The Transformer is a function. `cli.ts` is a thin adapter over this surface: it
+ * reads argv and stdin, calls runImplementer, and maps the outcome to an exit code.
+ * Everything a caller needs in process is reachable from here.
+ */
+export type { ProgressWriter } from "./progress/emit.js";
+export type { RunOptions, RunResult } from "./run/run-implementer.js";
+export { runImplementer } from "./run/run-implementer.js";
+export type * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,mBAAmB,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * Import entry point for this Transformer.
+ *
+ * The Transformer is a function. `cli.ts` is a thin adapter over this surface: it
+ * reads argv and stdin, calls runImplementer, and maps the outcome to an exit code.
+ * Everything a caller needs in process is reachable from here.
+ */
+export { runImplementer } from "./run/run-implementer.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/loop/decide-after-attempt.d.ts

@@ -0,0 +1,23 @@
+import type { AttemptEnded, RunOutcome } from "../types.js";
+export type LoopInput = {
+    ended: AttemptEnded;
+    /** Attempts started so far, including the one that just ended. */
+    attemptsStarted: number;
+    maxAttempts: number;
+};
+export type LoopDecision = {
+    action: "finish";
+    outcome: Exclude<RunOutcome, "invalid-invocation">;
+} | {
+    action: "retry";
+};
+/**
+ * Pure loop rule: next action from the Attempt verdict and the count.
+ *
+ * No clock enters here any more. Every child of an Attempt carries its own
+ * ceiling, so a slow one ends its Attempt as any other failure does, and the
+ * budget of a whole Task is what the Project wrote: `maxAttempts` times the
+ * producer and its Gates.
+ */
+export declare function decideAfterAttempt(input: LoopInput): LoopDecision;
+//# sourceMappingURL=decide-after-attempt.d.ts.map

package/dist/loop/decide-after-attempt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decide-after-attempt.d.ts","sourceRoot":"","sources":["../../src/loop/decide-after-attempt.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE5D,MAAM,MAAM,SAAS,GAAG;IACtB,KAAK,EAAE,YAAY,CAAC;IACpB,kEAAkE;IAClE,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,YAAY,GACpB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC,UAAU,EAAE,oBAAoB,CAAC,CAAA;CAAE,GACxE;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC;AAExB;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG,YAAY,CAkBjE"}

package/dist/loop/decide-after-attempt.js

@@ -0,0 +1,26 @@
+/**
+ * Pure loop rule: next action from the Attempt verdict and the count.
+ *
+ * No clock enters here any more. Every child of an Attempt carries its own
+ * ceiling, so a slow one ends its Attempt as any other failure does, and the
+ * budget of a whole Task is what the Project wrote: `maxAttempts` times the
+ * producer and its Gates.
+ */
+export function decideAfterAttempt(input) {
+    const { ended, attemptsStarted, maxAttempts } = input;
+    if (ended === "validated") {
+        return { action: "finish", outcome: "validated" };
+    }
+    if (ended === "fail-blocking") {
+        return { action: "finish", outcome: "escalated" };
+    }
+    if (ended === "interrupted") {
+        return { action: "finish", outcome: "interrupted" };
+    }
+    // fail-retryable
+    if (attemptsStarted >= maxAttempts) {
+        return { action: "finish", outcome: "escalated" };
+    }
+    return { action: "retry" };
+}
+//# sourceMappingURL=decide-after-attempt.js.map

package/dist/loop/decide-after-attempt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decide-after-attempt.js","sourceRoot":"","sources":["../../src/loop/decide-after-attempt.ts"],"names":[],"mappings":"AAaA;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAgB;IACjD,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,GAAG,KAAK,CAAC;IAEtD,IAAI,KAAK,KAAK,WAAW,EAAE,CAAC;QAC1B,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;IACpD,CAAC;IACD,IAAI,KAAK,KAAK,eAAe,EAAE,CAAC;QAC9B,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;IACpD,CAAC;IACD,IAAI,KAAK,KAAK,aAAa,EAAE,CAAC;QAC5B,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC;IACtD,CAAC;IAED,iBAAiB;IACjB,IAAI,eAAe,IAAI,WAAW,EAAE,CAAC;QACnC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;IACpD,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAC7B,CAAC"}

package/dist/progress/emit.d.ts

@@ -0,0 +1,5 @@
+import type { Status } from "../types.js";
+export type ProgressWriter = (line: Record<string, unknown>) => void;
+export declare function createStdoutProgressWriter(): ProgressWriter;
+export declare function emitStatusEvent(write: ProgressWriter, taskId: string, status: Status): void;
+//# sourceMappingURL=emit.d.ts.map

package/dist/progress/emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/progress/emit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;AAErE,wBAAgB,0BAA0B,IAAI,cAAc,CAI3D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAiB3F"}

package/dist/progress/emit.js

@@ -0,0 +1,24 @@
+export function createStdoutProgressWriter() {
+    return (line) => {
+        process.stdout.write(`${JSON.stringify(line)}\n`);
+    };
+}
+export function emitStatusEvent(write, taskId, status) {
+    const line = {
+        event: "status",
+        task_id: taskId,
+        phase: status.phase,
+        label: status.label,
+    };
+    if (status.attempt !== undefined) {
+        line.attempt = status.attempt;
+    }
+    if (status.max_attempts !== undefined) {
+        line.max_attempts = status.max_attempts;
+    }
+    if (status.gate_id !== undefined) {
+        line.gate_id = status.gate_id;
+    }
+    write(line);
+}
+//# sourceMappingURL=emit.js.map

package/dist/progress/emit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.js","sourceRoot":"","sources":["../../src/progress/emit.ts"],"names":[],"mappings":"AAIA,MAAM,UAAU,0BAA0B;IACxC,OAAO,CAAC,IAAI,EAAE,EAAE;QACd,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpD,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAqB,EAAE,MAAc,EAAE,MAAc;IACnF,MAAM,IAAI,GAA4B;QACpC,KAAK,EAAE,QAAQ;QACf,OAAO,EAAE,MAAM;QACf,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,KAAK,EAAE,MAAM,CAAC,KAAK;KACpB,CAAC;IACF,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAChC,CAAC;IACD,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACtC,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;IAC1C,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAChC,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,CAAC;AACd,CAAC"}

package/dist/run/run-implementer.d.ts

@@ -0,0 +1,23 @@
+import type { ProgressWriter } from "../progress/emit.js";
+import type { Invocation, RunOutcome, Trace } from "../types.js";
+export type RunResult = {
+    outcome: RunOutcome;
+    traces: Trace[];
+    exitCode: number;
+};
+export type RunOptions = {
+    invocation: Invocation;
+    write?: ProgressWriter;
+    /** When set, polled for interrupt; otherwise process signals are used. */
+    interruptFlag?: {
+        interrupted: boolean;
+    };
+    /** Working directory for spawned children. Undefined lets them inherit. */
+    cwd?: string;
+};
+/**
+ * Run one Implementer invocation to a run outcome.
+ */
+export declare function runImplementer(options: RunOptions): Promise<RunResult>;
+export declare function invalidInvocationResult(invocationId: string | undefined, write: ProgressWriter, reason: string): RunResult;
+//# sourceMappingURL=run-implementer.d.ts.map

package/dist/run/run-implementer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-implementer.d.ts","sourceRoot":"","sources":["../../src/run/run-implementer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAG1D,OAAO,KAAK,EAA8B,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAE7F,MAAM,MAAM,SAAS,GAAG;IACtB,OAAO,EAAE,UAAU,CAAC;IACpB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,UAAU,EAAE,UAAU,CAAC;IACvB,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,0EAA0E;IAC1E,aAAa,CAAC,EAAE;QAAE,WAAW,EAAE,OAAO,CAAA;KAAE,CAAC;IACzC,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAuCF;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAQ5E;AAuPD,wBAAgB,uBAAuB,CACrC,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,MAAM,GACb,SAAS,CAqBX"}