@netnodeag/kraftwerk 0.2.0

package/dist/config.js

@@ -0,0 +1,97 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { parse } from "yaml";
+/**
+ * Project resolution + optional project config.
+ *
+ * `kraftwerk.yml` at the project root is both the config file and the
+ * root marker, so every CLI command works from any subdirectory. Without
+ * it, the walk-up falls back to the first ancestor containing a workflows
+ * root (src/workflows/ or workflows/), then to the first .git directory,
+ * then to the starting cwd.
+ *
+ * All fields are optional — a valid kraftwerk.yml may be empty:
+ *
+ *   workflows: src/workflows   # workflows root, relative to the file
+ *   output: output             # run-artifact directory, relative to the file
+ */
+/** Stable, versionless URL of the workflow JSON schema (editor validation). */
+export const SCHEMA_URL = "https://raw.githubusercontent.com/NETNODEAG/kraftwerk/main/kraftwerk/schema/workflow.schema.json";
+export const CONFIG_FILENAMES = ["kraftwerk.yml", "kraftwerk.yaml"];
+const WORKFLOW_ROOT_CANDIDATES = ["src/workflows", "workflows"];
+const exists = async (p) => !!(await stat(p).catch(() => null));
+const isDir = async (p) => (await stat(p).catch(() => null))?.isDirectory() ?? false;
+async function findConfigFile(dir) {
+    for (const name of CONFIG_FILENAMES) {
+        const candidate = path.join(dir, name);
+        if (await exists(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+async function findWorkflowsDir(dir, configured) {
+    const candidates = configured ? [configured] : WORKFLOW_ROOT_CANDIDATES;
+    for (const candidate of candidates) {
+        const abs = path.resolve(dir, candidate);
+        if (await isDir(abs))
+            return abs;
+    }
+    return undefined;
+}
+/**
+ * Resolve the project for a cwd: walk up until a kraftwerk.yml or a
+ * workflows root appears; a .git directory is the fallback root, the cwd
+ * itself the last resort.
+ */
+export async function resolveProject(cwd) {
+    const start = path.resolve(cwd);
+    let gitFallback;
+    for (let dir = start;; dir = path.dirname(dir)) {
+        const configPath = await findConfigFile(dir);
+        if (configPath) {
+            const config = await loadConfig(configPath);
+            return {
+                root: dir,
+                config,
+                configPath,
+                workflowsRoot: await findWorkflowsDir(dir, config.workflows),
+                outputDir: path.resolve(dir, config.output ?? "output"),
+            };
+        }
+        const workflowsRoot = await findWorkflowsDir(dir);
+        if (workflowsRoot) {
+            return { root: dir, config: {}, workflowsRoot, outputDir: path.join(dir, "output") };
+        }
+        if (!gitFallback && (await exists(path.join(dir, ".git"))))
+            gitFallback = dir;
+        if (dir === path.dirname(dir))
+            break;
+    }
+    const root = gitFallback ?? start;
+    return { root, config: {}, outputDir: path.join(root, "output") };
+}
+async function loadConfig(configPath) {
+    let raw;
+    try {
+        raw = parse(await readFile(configPath, "utf8"));
+    }
+    catch (err) {
+        throw new Error(`${path.basename(configPath)}: unreadable YAML: ${err.message}`);
+    }
+    if (raw === null || raw === undefined)
+        return {};
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`${path.basename(configPath)}: expected a mapping (workflows, output)`);
+    }
+    const config = raw;
+    const known = ["workflows", "output"];
+    for (const key of Object.keys(config)) {
+        if (!known.includes(key)) {
+            throw new Error(`${path.basename(configPath)}: unknown key "${key}" (allowed: ${known.join(", ")})`);
+        }
+        if (typeof config[key] !== "string") {
+            throw new Error(`${path.basename(configPath)}: ${key} must be a string`);
+        }
+    }
+    return config;
+}

package/dist/discover.d.ts

@@ -0,0 +1,21 @@
+import { type LoadedWorkflow } from "./yaml.js";
+/**
+ * Workflow auto-discovery for the kraftwerk CLI: a consumer needs no entry
+ * file at all — every workflow folder (containing workflow.yml) and every
+ * top-level .yml file under the workflows root is picked up automatically.
+ *
+ * The project root is resolved by walking up from cwd (kraftwerk.yml or a
+ * workflows root marks it — see config.ts), so discovery works from any
+ * subdirectory. Roots tried in order: src/workflows/, workflows/ (first
+ * existing wins), overridable via `workflows:` in kraftwerk.yml.
+ * Load failures are carried per entry instead of thrown, so `list` can show
+ * broken workflows alongside valid ones.
+ */
+export interface DiscoveredWorkflow {
+    path: string;
+    workflow?: LoadedWorkflow;
+    error?: string;
+}
+/** Workflows root for a cwd (walk-up + kraftwerk.yml aware). */
+export declare function findWorkflowsRoot(cwd: string): Promise<string | undefined>;
+export declare function discoverWorkflows(cwd: string): Promise<DiscoveredWorkflow[]>;

package/dist/discover.js

@@ -0,0 +1,38 @@
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { resolveProject } from "./config.js";
+import { loadWorkflow } from "./yaml.js";
+/** Workflows root for a cwd (walk-up + kraftwerk.yml aware). */
+export async function findWorkflowsRoot(cwd) {
+    return (await resolveProject(cwd)).workflowsRoot;
+}
+export async function discoverWorkflows(cwd) {
+    const root = await findWorkflowsRoot(cwd);
+    if (!root)
+        return [];
+    const found = [];
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+        const entryPath = path.join(root, entry.name);
+        let candidate;
+        if (entry.isDirectory()) {
+            for (const f of ["workflow.yml", "workflow.yaml"]) {
+                if (await stat(path.join(entryPath, f)).catch(() => null)) {
+                    candidate = entryPath;
+                    break;
+                }
+            }
+        }
+        else if (/\.ya?ml$/.test(entry.name)) {
+            candidate = entryPath;
+        }
+        if (!candidate)
+            continue;
+        try {
+            found.push({ path: candidate, workflow: await loadWorkflow(candidate) });
+        }
+        catch (err) {
+            found.push({ path: candidate, error: err.message });
+        }
+    }
+    return found.sort((a, b) => a.path.localeCompare(b.path));
+}

package/dist/envelope.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Typed JSON envelope: every agent phase must end its final message with one
+ * fenced ```json block reporting what it did. The orchestrator parses and
+ * validates it — the agent's prose is ignored, only the envelope (plus the
+ * file gates) decides whether the phase passed.
+ */
+export interface Envelope {
+    phase: string;
+    status: "ok" | "blocked";
+    artifacts: string[];
+    summary?: string;
+    reason?: string;
+}
+export declare function parseEnvelope(text: string, expectedPhase: string): Envelope;
+/**
+ * The output contract appended to every agent phase prompt. Owned by the
+ * framework because `parseEnvelope` is what enforces it.
+ */
+export declare const envelopeContract: (phase: string) => string;
+/** Gate failed: correct in the SAME session instead of a cold restart. */
+export declare const correctionPrompt: (phase: string, failures: string[]) => string;

package/dist/envelope.js

@@ -0,0 +1,61 @@
+/**
+ * Typed JSON envelope: every agent phase must end its final message with one
+ * fenced ```json block reporting what it did. The orchestrator parses and
+ * validates it — the agent's prose is ignored, only the envelope (plus the
+ * file gates) decides whether the phase passed.
+ */
+export function parseEnvelope(text, expectedPhase) {
+    const fences = [...text.matchAll(/```json\s*([\s\S]*?)```/g)];
+    if (fences.length === 0) {
+        throw new Error("Envelope missing: no ```json code block in the final answer");
+    }
+    let raw;
+    try {
+        raw = JSON.parse(fences[fences.length - 1][1]);
+    }
+    catch (err) {
+        throw new Error(`Envelope is not valid JSON: ${err.message}`);
+    }
+    if (raw.phase !== expectedPhase) {
+        throw new Error(`Envelope reports phase "${raw.phase}", expected "${expectedPhase}"`);
+    }
+    if (raw.status !== "ok" && raw.status !== "blocked") {
+        throw new Error(`Envelope has invalid status "${raw.status}" (allowed: ok | blocked)`);
+    }
+    if (!Array.isArray(raw.artifacts) ||
+        raw.artifacts.some((a) => typeof a !== "string")) {
+        throw new Error('Envelope field "artifacts" must be an array of strings');
+    }
+    return {
+        phase: raw.phase,
+        status: raw.status,
+        artifacts: raw.artifacts,
+        summary: typeof raw.summary === "string" ? raw.summary : undefined,
+        reason: typeof raw.reason === "string" ? raw.reason : undefined,
+    };
+}
+/**
+ * The output contract appended to every agent phase prompt. Owned by the
+ * framework because `parseEnvelope` is what enforces it.
+ */
+export const envelopeContract = (phase) => `
+End your final answer with EXACTLY ONE json code block (the envelope):
+
+\`\`\`json
+{"phase": "${phase}", "status": "ok", "artifacts": ["<files written>"], "summary": "<one sentence>"}
+\`\`\`
+
+If you cannot complete the task, set "status": "blocked" and add a
+"reason" field. At most one sentence of text before the code block.
+`.trim();
+/** Gate failed: correct in the SAME session instead of a cold restart. */
+export const correctionPrompt = (phase, failures) => `
+The orchestrator checked your phase "${phase}". The following checks
+failed:
+
+${failures.map((f) => `- ${f}`).join("\n")}
+
+Fix exactly these points (edit the files directly).
+
+${envelopeContract(phase)}
+`.trim();

package/dist/gates.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Gates verify post-execution claims, never predictions: they run AFTER the
+ * agent finishes and look only at the files it left behind. A gate returns
+ * null (passed) or a human-readable failure that goes verbatim into the
+ * correction prompt.
+ *
+ * Only workflow-agnostic gates live here; workflow-specific ones (schema
+ * checks etc.) live next to their workflow and implement the same interface.
+ */
+export interface Gate {
+    name: string;
+    check(runDir: string): Promise<string | null>;
+}
+export declare const fileNonEmpty: (file: string) => Gate;
+/** No {{...}} template slots may survive a fill step. */
+export declare const slotsFilled: (file: string) => Gate;
+/** Fixed template parts chosen by code must survive byte-identically. */
+export declare const containsText: (file: string, needle: string, label: string) => Gate;

package/dist/gates.js

@@ -0,0 +1,34 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+export const fileNonEmpty = (file) => ({
+    name: `file_non_empty(${file})`,
+    async check(runDir) {
+        try {
+            const stats = await stat(path.join(runDir, file));
+            return stats.size > 0 ? null : `${file} exists but is empty`;
+        }
+        catch {
+            return `${file} was not written`;
+        }
+    },
+});
+/** No {{...}} template slots may survive a fill step. */
+export const slotsFilled = (file) => ({
+    name: `slots_filled(${file})`,
+    async check(runDir) {
+        const content = await readFile(path.join(runDir, file), "utf8").catch(() => "");
+        return content.includes("{{")
+            ? `${file} still contains unfilled {{...}} slots`
+            : null;
+    },
+});
+/** Fixed template parts chosen by code must survive byte-identically. */
+export const containsText = (file, needle, label) => ({
+    name: `contains(${file}, ${label})`,
+    async check(runDir) {
+        const content = await readFile(path.join(runDir, file), "utf8").catch(() => "");
+        return content.includes(needle)
+            ? null
+            : `${file} no longer contains "${needle}" — the fixed template part was changed`;
+    },
+});

package/dist/harness.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The harness port: WHICH runtime executes an agent phase.
+ *
+ * A harness is a complete headless agent runtime (claude -p, codex exec,
+ * pi). All of them share the same contract — spawn one short-lived process,
+ * stream JSONL events, resume a session by id — so the framework talks to
+ * a single interface and one adapter per CLI normalizes the flags and the
+ * event schema (see harnesses/).
+ *
+ * Sessions are per harness: two phases on the same harness share context
+ * via resume; across harnesses, context travels through the files in the
+ * run directory (the workspace-context contract).
+ */
+export type HarnessId = "claude" | "codex" | "pi";
+/**
+ * One MCP server an agent may use: either a local stdio server (spawned by
+ * the harness, e.g. `node multiply-server.ts`) or a remote streamable-HTTP
+ * server (`url`). Names must be [A-Za-z0-9_-]. Supported by the claude and
+ * codex harnesses; pi has no MCP support and rejects the invocation.
+ */
+export type McpServerConfig = {
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+} | {
+    url: string;
+};
+export interface AgentInvocation {
+    prompt: string;
+    systemPrompt: string;
+    cwd: string;
+    model: string;
+    effort?: string;
+    tools: string[];
+    /**
+     * CLI command prefixes granted for this phase (e.g. "git", "npm run").
+     * claude: each becomes a scoped `Bash(<name>:*)` allowlist entry.
+     * codex: the sandbox runs commands anyway — nothing to do.
+     * pi: no per-command scoping — enables the plain bash tool.
+     */
+    clis?: string[];
+    /** MCP servers available in this phase, keyed by server name. */
+    mcpServers?: Record<string, McpServerConfig>;
+    resume?: string;
+    onToolUse?: (tool: string, target: string) => void;
+    onText?: (text: string) => void;
+}
+export interface TokenUsage {
+    /** Fresh (uncached) input tokens. */
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+}
+export interface AgentResult {
+    sessionId: string;
+    text: string;
+    numTurns?: number;
+    durationMs?: number;
+    costUsd?: number;
+    usage?: TokenUsage;
+}
+export interface Harness {
+    id: HarnessId;
+    invoke(inv: AgentInvocation): Promise<AgentResult>;
+}

package/dist/harness.js

@@ -0,0 +1,14 @@
+/**
+ * The harness port: WHICH runtime executes an agent phase.
+ *
+ * A harness is a complete headless agent runtime (claude -p, codex exec,
+ * pi). All of them share the same contract — spawn one short-lived process,
+ * stream JSONL events, resume a session by id — so the framework talks to
+ * a single interface and one adapter per CLI normalizes the flags and the
+ * event schema (see harnesses/).
+ *
+ * Sessions are per harness: two phases on the same harness share context
+ * via resume; across harnesses, context travels through the files in the
+ * run directory (the workspace-context contract).
+ */
+export {};

package/dist/harnesses/claude.d.ts

@@ -0,0 +1,2 @@
+import type { Harness } from "../harness.js";
+export declare const claudeHarness: Harness;

package/dist/harnesses/claude.js

@@ -0,0 +1,117 @@
+import { spawn } from "node:child_process";
+function invokeClaude(inv) {
+    const mcpNames = Object.keys(inv.mcpServers ?? {});
+    const allowedTools = [
+        ...inv.tools,
+        ...(inv.clis ?? []).map((name) => `Bash(${name}:*)`),
+        ...mcpNames.map((name) => `mcp__${name}`),
+    ];
+    const args = [
+        "-p",
+        "--chrome",
+        "--output-format", "stream-json",
+        "--verbose",
+        "--model", inv.model,
+        "--system-prompt", inv.systemPrompt,
+        "--allowed-tools", allowedTools.join(","),
+        "--permission-mode", "acceptEdits",
+        // Keep the run hermetic: no user/project settings, hooks, or CLAUDE.md.
+        "--setting-sources", "",
+    ];
+    if (mcpNames.length > 0) {
+        const mcpServers = Object.fromEntries(Object.entries(inv.mcpServers).map(([name, cfg]) => [
+            name,
+            "url" in cfg ? { type: "http", url: cfg.url } : cfg,
+        ]));
+        args.push("--mcp-config", JSON.stringify({ mcpServers }), "--strict-mcp-config");
+    }
+    if (inv.effort)
+        args.push("--effort", inv.effort);
+    if (inv.resume)
+        args.push("--resume", inv.resume);
+    return new Promise((resolve, reject) => {
+        const child = spawn("claude", args, {
+            cwd: inv.cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        child.stdin.write(inv.prompt);
+        child.stdin.end();
+        let sessionId;
+        let final;
+        let stderr = "";
+        let buffer = "";
+        const handleLine = (line) => {
+            if (!line.trim())
+                return;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                return; // non-JSON noise on stdout
+            }
+            if (msg.type === "system" && msg.subtype === "init" && msg.session_id) {
+                sessionId = msg.session_id;
+            }
+            if (msg.type === "assistant" && Array.isArray(msg.message?.content)) {
+                for (const block of msg.message.content) {
+                    if (block?.type === "tool_use") {
+                        const input = block.input ?? {};
+                        // Bash: show the actual command (single line, clipped).
+                        const raw = input.file_path ?? input.url ?? input.path ?? input.command ?? "";
+                        const target = String(raw).replace(/\s+/g, " ").trim();
+                        inv.onToolUse?.(block.name, target.length > 160 ? `${target.slice(0, 160)}…` : target);
+                    }
+                    if (block?.type === "text" && block.text?.trim()) {
+                        inv.onText?.(block.text.trim());
+                    }
+                }
+            }
+            if (msg.type === "result") {
+                if (msg.is_error || msg.subtype !== "success") {
+                    reject(new Error(`claude -p failed: ${msg.subtype} ${msg.result ?? ""}`));
+                    return;
+                }
+                final = {
+                    sessionId: msg.session_id ?? sessionId ?? "",
+                    text: msg.result ?? "",
+                    numTurns: msg.num_turns,
+                    durationMs: msg.duration_ms,
+                    costUsd: msg.total_cost_usd,
+                    usage: msg.usage
+                        ? {
+                            inputTokens: msg.usage.input_tokens ?? 0,
+                            outputTokens: msg.usage.output_tokens ?? 0,
+                            cacheReadTokens: msg.usage.cache_read_input_tokens ?? 0,
+                            cacheCreationTokens: msg.usage.cache_creation_input_tokens ?? 0,
+                        }
+                        : undefined,
+                };
+            }
+        };
+        child.stdout.on("data", (chunk) => {
+            buffer += chunk.toString("utf8");
+            const lines = buffer.split("\n");
+            buffer = lines.pop() ?? "";
+            lines.forEach(handleLine);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.on("error", (err) => reject(new Error(`could not spawn claude: ${err.message}`)));
+        child.on("close", (code) => {
+            handleLine(buffer);
+            if (final?.sessionId) {
+                resolve(final);
+            }
+            else {
+                reject(new Error(`claude -p exited with code ${code} without a result message` +
+                    (stderr.trim() ? `\nstderr: ${stderr.trim().slice(-2000)}` : "")));
+            }
+        });
+    });
+}
+export const claudeHarness = {
+    id: "claude",
+    invoke: invokeClaude,
+};

package/dist/harnesses/codex.d.ts

@@ -0,0 +1,2 @@
+import type { Harness } from "../harness.js";
+export declare const codexHarness: Harness;

package/dist/harnesses/codex.js

@@ -0,0 +1,158 @@
+import { spawn } from "node:child_process";
+const clip = (raw) => {
+    const oneLine = raw.replace(/\s+/g, " ").trim();
+    return oneLine.length > 160 ? `${oneLine.slice(0, 160)}…` : oneLine;
+};
+/** JSON string escaping is valid TOML basic-string escaping. */
+const toml = (value) => JSON.stringify(value);
+function mcpOverrides(servers) {
+    const args = [];
+    for (const [name, cfg] of Object.entries(servers)) {
+        if (!/^[A-Za-z0-9_-]+$/.test(name)) {
+            throw new Error(`codex: MCP server name "${name}" must match [A-Za-z0-9_-]+`);
+        }
+        const key = `mcp_servers.${name}`;
+        if ("url" in cfg) {
+            args.push("-c", `${key}.url=${toml(cfg.url)}`);
+            continue;
+        }
+        args.push("-c", `${key}.command=${toml(cfg.command)}`);
+        if (cfg.args?.length) {
+            args.push("-c", `${key}.args=[${cfg.args.map(toml).join(",")}]`);
+        }
+        if (cfg.env && Object.keys(cfg.env).length > 0) {
+            const table = Object.entries(cfg.env)
+                .map(([k, v]) => `${k}=${toml(v)}`)
+                .join(",");
+            args.push("-c", `${key}.env={${table}}`);
+        }
+    }
+    return args;
+}
+function invokeCodex(inv) {
+    const hasMcp = Object.keys(inv.mcpServers ?? {}).length > 0;
+    const args = [
+        "exec",
+        "--json",
+        "-m", inv.model,
+        // --approve-for-me implies the workspace-write sandbox and lets codex's
+        // automatic reviewer answer MCP tool approvals (headless exec would
+        // otherwise auto-cancel them).
+        ...(hasMcp ? ["--approve-for-me"] : ["--sandbox", "workspace-write"]),
+        "-C", inv.cwd,
+        "--skip-git-repo-check",
+        "--ignore-user-config",
+    ];
+    if (hasMcp)
+        args.push(...mcpOverrides(inv.mcpServers));
+    if (inv.effort)
+        args.push("-c", `model_reasoning_effort=${inv.effort}`);
+    // Governance mapping: a web-tool grant means the sandbox may reach the network.
+    if (inv.tools.some((t) => t === "WebFetch" || t === "WebSearch")) {
+        args.push("-c", "sandbox_workspace_write.network_access=true");
+    }
+    if (inv.resume)
+        args.push("resume", inv.resume);
+    args.push("-"); // read the prompt from stdin
+    // No system-prompt flag on codex: carry persona + context in the prompt.
+    const prompt = `# Role and workspace context for this phase\n\n${inv.systemPrompt}\n\n` +
+        `# Task\n\n${inv.prompt}`;
+    const started = Date.now();
+    return new Promise((resolve, reject) => {
+        const child = spawn("codex", args, {
+            cwd: inv.cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        child.stdin.write(prompt);
+        child.stdin.end();
+        let sessionId;
+        let usage;
+        const texts = [];
+        let failure;
+        let stderr = "";
+        let buffer = "";
+        const handleLine = (line) => {
+            if (!line.trim())
+                return;
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                return; // non-JSON noise on stdout
+            }
+            if (event.type === "thread.started" && event.thread_id) {
+                sessionId = event.thread_id;
+            }
+            if (event.type === "item.started" && event.item) {
+                const item = event.item;
+                if (item.type === "command_execution" && item.command) {
+                    inv.onToolUse?.("Bash", clip(item.command));
+                }
+                if (item.type === "file_change") {
+                    for (const change of item.changes ?? []) {
+                        const tool = change.kind === "add" ? "Write" : "Edit";
+                        inv.onToolUse?.(tool, clip(change.path ?? ""));
+                    }
+                }
+                if (item.type === "mcp_tool_call" && item.server && item.tool) {
+                    inv.onToolUse?.(`mcp__${item.server}__${item.tool}`, clip(item.arguments !== undefined ? JSON.stringify(item.arguments) : ""));
+                }
+            }
+            if (event.type === "item.completed" && event.item?.type === "agent_message") {
+                const text = event.item.text?.trim();
+                if (text) {
+                    texts.push(text);
+                    inv.onText?.(text);
+                }
+            }
+            if (event.type === "turn.completed" && event.usage) {
+                const u = event.usage;
+                const total = u.input_tokens ?? 0;
+                const cached = u.cached_input_tokens ?? 0;
+                usage = {
+                    // codex reports input_tokens as the total including cache reads.
+                    inputTokens: Math.max(0, total - cached),
+                    outputTokens: u.output_tokens ?? 0,
+                    cacheReadTokens: cached,
+                    cacheCreationTokens: u.cache_write_input_tokens ?? 0,
+                };
+            }
+            if (event.type === "turn.failed" || event.type === "error") {
+                failure = event.message ?? line;
+            }
+        };
+        child.stdout.on("data", (chunk) => {
+            buffer += chunk.toString("utf8");
+            const lines = buffer.split("\n");
+            buffer = lines.pop() ?? "";
+            lines.forEach(handleLine);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+        });
+        child.on("error", (err) => reject(new Error(`could not spawn codex: ${err.message}`)));
+        child.on("close", (code) => {
+            handleLine(buffer);
+            if (failure || code !== 0 || !sessionId) {
+                reject(new Error(`codex exec failed (exit ${code})` +
+                    (failure ? `: ${failure}` : "") +
+                    (stderr.trim() ? `\nstderr: ${stderr.trim().slice(-2000)}` : "")));
+                return;
+            }
+            resolve({
+                sessionId,
+                // The envelope sits in the last message; parseEnvelope takes the
+                // last fenced block, so joining all messages is safe.
+                text: texts.join("\n\n"),
+                durationMs: Date.now() - started,
+                usage,
+                // No cost in codex events (subscription auth) — left undefined.
+            });
+        });
+    });
+}
+export const codexHarness = {
+    id: "codex",
+    invoke: invokeCodex,
+};

package/dist/harnesses/pi.d.ts

@@ -0,0 +1,2 @@
+import type { Harness } from "../harness.js";
+export declare const piHarness: Harness;