@karowanorg/orc-harness-codex 0.1.0

package/LICENSE

@@ -0,0 +1,14 @@
+BSD Zero Clause License (0BSD)
+
+Copyright (c) 2026 Kyle Rowan
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @karowanorg/orc-harness-codex
+
+Codex harness for orc: codex app-server JSON-RPC through the executor.
+
+Part of orc - model-authored promise-native agent programs with deterministic replay, live monitoring, and pluggable harnesses. See the orc repository README for the full picture.

package/dist/harness.d.ts

@@ -0,0 +1,21 @@
+import type { Harness } from "@karowanorg/orc-core";
+import { type ModelRate } from "@karowanorg/orc-core";
+export interface CodexHarnessOptions {
+    /** Command spawned through the executor. Default: ["codex", "app-server"]. */
+    appServerCommand?: string[];
+    /** Wait after turn/interrupt before killing the process. Default 2000ms. */
+    interruptGraceMs?: number;
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
+    /**
+     * Per-model rate table (USD per 1M tokens) for cost ESTIMATION, since codex's
+     * app-server reports tokens but no dollar figure. Defaults to the built-in
+     * DEFAULT_COST_RATES (overridable via ORC_COST_RATES / config costRates).
+     */
+    costRates?: Record<string, ModelRate>;
+}
+export declare function createCodexHarness(options?: CodexHarnessOptions): Harness;
+/** Default codex harness bound to the real `codex app-server` binary. */
+export declare const codexHarness: Harness;

package/dist/harness.js

@@ -0,0 +1,604 @@
+/**
+ * codex harness: drives `codex app-server` (codex-cli 0.144.x) over
+ * newline-delimited JSON-RPC on stdio. The server process is spawned THROUGH
+ * the provided executor, so the same harness works locally and over ssh —
+ * JSON-RPC simply flows through the ssh pipes.
+ *
+ * Wire protocol notes (verified empirically against codex-cli 0.144.5 and its
+ * `codex app-server generate-json-schema` output):
+ *
+ *   client -> server:  initialize, (notify) initialized, thread/start,
+ *                      thread/resume, turn/start, turn/interrupt, model/list
+ *   server -> client notifications: thread/started, turn/started,
+ *                      item/started, item/completed, item/agentMessage/delta,
+ *                      thread/tokenUsage/updated, turn/completed, error
+ *   server -> client requests (approvals), current family:
+ *                      item/commandExecution/requestApproval -> {decision:
+ *                        "accept"|"acceptForSession"|"decline"|"cancel"}
+ *                      item/fileChange/requestApproval        -> same enum
+ *                      legacy family (still in the protocol schema):
+ *                      execCommandApproval / applyPatchApproval -> {decision:
+ *                        "approved"|"approved_for_session"|"denied"|"abort"}
+ *
+ * Approval-mode mapping (design name -> wire name):
+ *   manual       -> approvalPolicy "on-request"; bridge every request
+ *   accept-edits -> approvalPolicy "on-request"; auto-accept fileChange
+ *                   approvals confined to req.cwd, bridge the rest
+ *   auto / bypass -> approvalPolicy "never"
+ * Filesystem policy is orthogonal to approvals (see below): read-only leaf ->
+ * "read-only"; a default write leaf OMITS the sandbox param so codex uses the
+ * user's own ~/.codex config (never more power than the caller); `sandbox` ->
+ * "workspace-write" with cwd + sandboxDirs as runtime workspace roots;
+ * explicit `bypass` -> "danger-full-access".
+ */
+import * as path from "node:path";
+import { estimateCostUsd, loadCostRates } from "@karowanorg/orc-core";
+import { JsonRpcClient } from "./rpc.js";
+import { extractFirstJsonObject, lintStrictOutputSchema, normalizeSchema, restoreOptionalNulls, } from "./schema.js";
+/** Simple push-based async event queue backing the invoke() iterator. */
+class EventQueue {
+    items = [];
+    waiter;
+    done = false;
+    push(ev) {
+        if (this.done)
+            return;
+        this.items.push(ev);
+        this.waiter?.();
+    }
+    end() {
+        this.done = true;
+        this.waiter?.();
+    }
+    async *[Symbol.asyncIterator]() {
+        for (;;) {
+            while (this.items.length > 0)
+                yield this.items.shift();
+            if (this.done)
+                return;
+            await new Promise((resolve) => (this.waiter = resolve));
+            this.waiter = undefined;
+        }
+    }
+}
+function asRecord(v) {
+    return v !== null && typeof v === "object" ? v : {};
+}
+/** Is `candidate` lexically inside (or equal to) directory `root`? */
+function withinDir(candidate, root) {
+    const rel = path.relative(path.resolve(root), path.resolve(root, candidate));
+    return rel === "" || (rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel));
+}
+/** Collect changed file paths from a fileChange item / legacy fileChanges map. */
+function changedPaths(changes) {
+    if (Array.isArray(changes)) {
+        return changes
+            .map((c) => asRecord(c).path)
+            .filter((p) => typeof p === "string");
+    }
+    if (changes !== null && typeof changes === "object")
+        return Object.keys(changes);
+    return [];
+}
+export function createCodexHarness(options = {}) {
+    const appServerCommand = options.appServerCommand ?? ["codex", "app-server"];
+    const interruptGraceMs = options.interruptGraceMs ?? 2000;
+    const clientInfo = options.clientInfo ?? { name: "orc", version: "0.1.0" };
+    const costRates = loadCostRates(options.costRates);
+    async function discover(ctx) {
+        const base = {
+            available: false,
+            models: [],
+            approvalModes: ["manual", "accept-edits", "auto", "bypass"],
+            structuredOutput: true,
+            sessions: true,
+        };
+        const ver = await ctx.executor
+            .run(["codex", "--version"], { timeoutMs: 15_000 })
+            .catch(() => ({ code: -1, stdout: "", stderr: "" }));
+        if (ver.code !== 0)
+            return { ...base, detail: "codex binary not found" };
+        base.available = true;
+        base.version = ver.stdout.trim().replace(/^codex(-cli)?\s+/, "");
+        // Native discovery: model/list on a short-lived app-server session. (The
+        // generate-json-schema output was checked and carries NO model/effort
+        // enums — ReasoningEffort is a free string there — so model/list is the
+        // only native source of truth.)
+        try {
+            const models = await modelList(ctx.executor);
+            if (models.length > 0) {
+                return { ...base, models, detail: "codex app-server model/list" };
+            }
+        }
+        catch {
+            // fall through to config.toml
+        }
+        const fallback = await configTomlModel(ctx.executor);
+        return {
+            ...base,
+            models: fallback
+                ? [
+                    {
+                        id: fallback,
+                        // Documented effort ladder for codex-cli 0.14x, used only when
+                        // the live catalog is unreachable.
+                        reasoningEfforts: ["minimal", "low", "medium", "high", "xhigh"],
+                    },
+                ]
+                : [],
+            detail: fallback
+                ? "fallback: model default from ~/.codex/config.toml (app-server model/list unavailable)"
+                : "fallback: app-server model/list unavailable and no ~/.codex/config.toml model",
+        };
+    }
+    async function modelList(executor) {
+        const proc = executor.spawn(appServerCommand);
+        try {
+            const rpc = new JsonRpcClient(proc);
+            const withTimeout = async (p, ms) => {
+                let timer;
+                try {
+                    return await Promise.race([
+                        p,
+                        new Promise((_, reject) => {
+                            timer = setTimeout(() => reject(new Error("discover timeout")), ms);
+                        }),
+                    ]);
+                }
+                finally {
+                    if (timer)
+                        clearTimeout(timer);
+                }
+            };
+            await withTimeout(rpc.request("initialize", { clientInfo }), 20_000);
+            rpc.notify("initialized", {});
+            const res = await withTimeout(rpc.request("model/list", {}), 20_000);
+            const visible = (res.data ?? []).filter((m) => !m.hidden && typeof m.id === "string");
+            // Default model first.
+            visible.sort((a, b) => Number(b.isDefault ?? false) - Number(a.isDefault ?? false));
+            return visible.map((m) => {
+                const efforts = [];
+                for (const e of m.supportedReasoningEfforts ?? []) {
+                    if (typeof e.reasoningEffort === "string" && !efforts.includes(e.reasoningEffort)) {
+                        efforts.push(e.reasoningEffort);
+                    }
+                }
+                return {
+                    id: m.id,
+                    displayName: m.displayName,
+                    reasoningEfforts: efforts,
+                    default: m.isDefault === true ? true : undefined,
+                };
+            });
+        }
+        finally {
+            proc.kill();
+        }
+    }
+    async function configTomlModel(executor) {
+        try {
+            const home = (await executor.run(["sh", "-c", 'printf %s "$HOME"'])).stdout.trim();
+            if (!home)
+                return undefined;
+            const toml = await executor.readFile(`${home}/.codex/config.toml`);
+            const m = /^\s*model\s*=\s*"([^"]+)"/m.exec(toml);
+            return m?.[1];
+        }
+        catch {
+            return undefined;
+        }
+    }
+    function invoke(req, ctx) {
+        const queue = new EventQueue();
+        void runTurn(req, ctx, queue); // runTurn reports its own errors via the queue
+        return queue;
+    }
+    async function runTurn(req, ctx, queue) {
+        // --- approval-mode mapping (design -> wire) ----------------------------
+        const approvalPolicy = req.approvalMode === "manual" || req.approvalMode === "accept-edits"
+            ? "on-request"
+            : "never";
+        // Filesystem policy — never gives a leaf MORE power than the user's own
+        // codex, orthogonal to the approval policy:
+        // - read-only leaf         -> "read-only"      (orc's readOnly restriction)
+        // - write leaf + sandbox   -> "workspace-write"(explicit confinement, less power)
+        // - write leaf + bypass    -> "danger-full-access" (explicit max, opt-in)
+        // - write leaf (default)   -> OMIT the param → codex uses the user's own
+        //   ~/.codex/config.toml default, so a leaf has exactly the caller's power.
+        const sandbox = req.readOnly
+            ? "read-only"
+            : req.sandbox
+                ? "workspace-write"
+                : req.approvalMode === "bypass"
+                    ? "danger-full-access"
+                    : undefined;
+        const runtimeWorkspaceRoots = req.sandbox && !req.readOnly
+            ? [
+                ...new Set([req.cwd, ...(req.sandboxDirs ?? [])].map((root) => path.normalize(path.isAbsolute(root) ? root : path.resolve(req.cwd, root)))),
+            ]
+            : undefined;
+        // Announce the model/effort actually being requested (codex uses its
+        // configured default when req.model is unset).
+        queue.push({ kind: "model", model: req.model ?? "(codex default)", reasoningEffort: req.reasoningEffort });
+        const proc = ctx.executor.spawn(appServerCommand, { cwd: req.cwd });
+        let turnId;
+        let threadId;
+        let lastErrorMessage;
+        const itemsById = new Map();
+        const messageBuffers = new Map();
+        let finalAnswer;
+        let lastAgentMessage;
+        // Forward server stderr (tracing logs) to the supervisor log.
+        let errBuf = "";
+        proc.stderr.setEncoding("utf8");
+        proc.stderr.on("data", (chunk) => {
+            errBuf += chunk;
+            let idx;
+            while ((idx = errBuf.indexOf("\n")) >= 0) {
+                const line = errBuf.slice(0, idx).trim();
+                errBuf = errBuf.slice(idx + 1);
+                if (line)
+                    ctx.log(line); // hlog is already per-leaf + harness-attributed
+            }
+        });
+        // Output-idle watchdog: any stdout byte resets the timer.
+        let idleTimer;
+        let idleFired = false;
+        const armIdle = () => {
+            if (typeof req.idleTimeoutMs !== "number")
+                return;
+            if (idleTimer)
+                clearTimeout(idleTimer);
+            idleTimer = setTimeout(() => {
+                idleFired = true;
+                queue.push({
+                    kind: "error",
+                    message: `idle timeout: no app-server output for ${req.idleTimeoutMs}ms`,
+                });
+                proc.kill();
+            }, req.idleTimeoutMs);
+            idleTimer.unref?.();
+        };
+        proc.stdout.on("data", armIdle);
+        armIdle();
+        let resolveTurn;
+        const turnDone = new Promise((resolve) => (resolveTurn = resolve));
+        const onNotification = (method, rawParams) => {
+            const params = asRecord(rawParams);
+            if (typeof params.threadId === "string" && threadId && params.threadId !== threadId)
+                return;
+            switch (method) {
+                case "item/started": {
+                    const item = asRecord(params.item);
+                    if (typeof item.id === "string")
+                        itemsById.set(item.id, item);
+                    const atMs = Date.now();
+                    switch (item.type) {
+                        case "commandExecution":
+                            queue.push({
+                                kind: "tool-call-open",
+                                id: item.id ?? "",
+                                name: "command",
+                                input: { command: item.command ?? null, cwd: item.cwd ?? null },
+                                atMs,
+                            });
+                            break;
+                        case "fileChange":
+                            queue.push({
+                                kind: "tool-call-open",
+                                id: item.id ?? "",
+                                name: "edit",
+                                input: { changes: (item.changes ?? null) },
+                                atMs,
+                            });
+                            break;
+                        case "webSearch":
+                            queue.push({
+                                kind: "tool-call-open",
+                                id: item.id ?? "",
+                                name: "webSearch",
+                                input: { query: (item.query ?? null) },
+                                atMs,
+                            });
+                            break;
+                        case "mcpToolCall":
+                            queue.push({
+                                kind: "tool-call-open",
+                                id: item.id ?? "",
+                                name: "mcpToolCall",
+                                input: {
+                                    server: (item.server ?? null),
+                                    tool: (item.tool ?? null),
+                                    arguments: (item.arguments ?? null),
+                                },
+                                atMs,
+                            });
+                            break;
+                        default:
+                            break; // userMessage / reasoning / agentMessage etc: no tool event
+                    }
+                    break;
+                }
+                case "item/completed": {
+                    const item = asRecord(params.item);
+                    if (typeof item.id === "string")
+                        itemsById.set(item.id, item);
+                    const atMs = Date.now();
+                    switch (item.type) {
+                        case "commandExecution":
+                        case "fileChange":
+                        case "webSearch":
+                        case "mcpToolCall": {
+                            const failed = item.status === "failed" || item.status === "declined";
+                            queue.push({
+                                kind: "tool-call-close",
+                                id: item.id ?? "",
+                                status: failed ? "error" : "ok",
+                                atMs,
+                            });
+                            break;
+                        }
+                        case "agentMessage": {
+                            const text = typeof item.text === "string" ? item.text : "";
+                            lastAgentMessage = text;
+                            if (item.phase === "final_answer" || item.phase === undefined)
+                                finalAnswer = text;
+                            break;
+                        }
+                        default:
+                            break;
+                    }
+                    break;
+                }
+                case "item/agentMessage/delta": {
+                    const delta = typeof params.delta === "string" ? params.delta : "";
+                    const itemId = typeof params.itemId === "string" ? params.itemId : "";
+                    messageBuffers.set(itemId, (messageBuffers.get(itemId) ?? "") + delta);
+                    if (delta)
+                        queue.push({ kind: "text", delta, atMs: Date.now() });
+                    break;
+                }
+                case "thread/tokenUsage/updated": {
+                    const usage = asRecord(asRecord(params.tokenUsage).total);
+                    const inputTokens = typeof usage.inputTokens === "number" ? usage.inputTokens : undefined;
+                    const outputTokens = typeof usage.outputTokens === "number" ? usage.outputTokens : undefined;
+                    const cachedInputTokens = typeof usage.cachedInputTokens === "number" ? usage.cachedInputTokens : undefined;
+                    // codex reports tokens but no dollars — estimate from the rate table.
+                    // Fall back to the gpt-5.6 family key when the program didn't pin a model.
+                    const costUsd = estimateCostUsd(costRates, req.model ?? "gpt-5.6", {
+                        inputTokens,
+                        cachedInputTokens,
+                        outputTokens,
+                    });
+                    queue.push({
+                        kind: "usage",
+                        tokensIn: inputTokens,
+                        tokensOut: outputTokens,
+                        ...(costUsd !== undefined ? { costUsd, costEstimated: true } : {}),
+                    });
+                    break;
+                }
+                case "turn/completed": {
+                    resolveTurn(asRecord(params.turn));
+                    break;
+                }
+                case "error": {
+                    const message = asRecord(params.error).message;
+                    if (typeof message === "string")
+                        lastErrorMessage = message;
+                    break;
+                }
+                default:
+                    break;
+            }
+        };
+        const bridgeApproval = async (toolName, input) => {
+            const decision = await ctx.requestApproval({
+                runId: req.runId,
+                seq: req.seq,
+                toolName,
+                input,
+            });
+            if (decision.behavior === "deny") {
+                queue.push({
+                    kind: "denied",
+                    toolName,
+                    reason: decision.message ?? "denied by operator",
+                    atMs: Date.now(),
+                });
+            }
+            return decision;
+        };
+        const denyReadOnly = (toolName) => {
+            queue.push({
+                kind: "denied",
+                toolName,
+                reason: "read-only leaf denied approval",
+                atMs: Date.now(),
+            });
+            return { behavior: "deny" };
+        };
+        const decideFileChange = async (paths, grantRoot, input) => {
+            if (req.readOnly)
+                return denyReadOnly("edit");
+            const confined = paths.length > 0 &&
+                paths.every((p) => withinDir(p, req.cwd)) &&
+                (typeof grantRoot !== "string" || withinDir(grantRoot, req.cwd));
+            if (req.approvalMode === "accept-edits" && confined) {
+                return { behavior: "allow" };
+            }
+            if (req.approvalMode === "auto" || req.approvalMode === "bypass") {
+                // approvalPolicy is "never" for these modes; if the server asks
+                // anyway, honor the mode's intent and allow.
+                return { behavior: "allow" };
+            }
+            return bridgeApproval("edit", input);
+        };
+        const onServerRequest = async (method, rawParams) => {
+            const params = asRecord(rawParams);
+            switch (method) {
+                // --- current (v2) approval family --------------------------------
+                case "item/commandExecution/requestApproval": {
+                    const item = typeof params.itemId === "string" ? itemsById.get(params.itemId) : undefined;
+                    const decision = req.readOnly
+                        ? denyReadOnly("command")
+                        : req.approvalMode === "auto" || req.approvalMode === "bypass"
+                            ? { behavior: "allow" }
+                            : await bridgeApproval("command", {
+                                command: (params.command ?? item?.command ?? null),
+                                cwd: (params.cwd ?? item?.cwd ?? null),
+                                reason: (params.reason ?? null),
+                            });
+                    return { decision: decision.behavior === "allow" ? "accept" : "decline" };
+                }
+                case "item/fileChange/requestApproval": {
+                    const item = typeof params.itemId === "string" ? itemsById.get(params.itemId) : undefined;
+                    const paths = changedPaths(item?.changes);
+                    const decision = await decideFileChange(paths, params.grantRoot, {
+                        changes: (item?.changes ?? null),
+                        paths,
+                        reason: (params.reason ?? null),
+                    });
+                    return { decision: decision.behavior === "allow" ? "accept" : "decline" };
+                }
+                // --- legacy approval family (older servers) ----------------------
+                case "execCommandApproval": {
+                    const decision = req.readOnly
+                        ? denyReadOnly("command")
+                        : req.approvalMode === "auto" || req.approvalMode === "bypass"
+                            ? { behavior: "allow" }
+                            : await bridgeApproval("command", {
+                                command: (params.command ?? null),
+                                cwd: (params.cwd ?? null),
+                                reason: (params.reason ?? null),
+                            });
+                    return { decision: decision.behavior === "allow" ? "approved" : "denied" };
+                }
+                case "applyPatchApproval": {
+                    const paths = changedPaths(params.fileChanges);
+                    const decision = await decideFileChange(paths, params.grantRoot, {
+                        changes: (params.fileChanges ?? null),
+                        paths,
+                        reason: (params.reason ?? null),
+                    });
+                    return { decision: decision.behavior === "allow" ? "approved" : "denied" };
+                }
+                default:
+                    throw new Error(`unsupported server request: ${method}`);
+            }
+        };
+        const rpc = new JsonRpcClient(proc, { onNotification, onServerRequest, log: ctx.log });
+        // Cancellation: best-effort turn/interrupt, then kill.
+        let aborted = false;
+        const onAbort = () => {
+            aborted = true;
+            if (threadId && turnId) {
+                rpc.request("turn/interrupt", { threadId, turnId }).catch(() => undefined);
+            }
+            setTimeout(() => proc.kill(), interruptGraceMs).unref?.();
+        };
+        if (ctx.signal.aborted)
+            onAbort();
+        else
+            ctx.signal.addEventListener("abort", onAbort, { once: true });
+        try {
+            await rpc.request("initialize", { clientInfo });
+            rpc.notify("initialized", {});
+            const developerInstructions = req.system.trim() || undefined;
+            if (req.sessionId) {
+                const resumed = await rpc.request("thread/resume", {
+                    threadId: req.sessionId,
+                    cwd: req.cwd,
+                    ...(runtimeWorkspaceRoots ? { runtimeWorkspaceRoots } : {}),
+                    approvalPolicy,
+                    ...(sandbox !== undefined ? { sandbox } : {}), // omit -> inherit user's config default
+                    ...(developerInstructions ? { developerInstructions } : {}),
+                });
+                threadId = resumed.thread?.id ?? req.sessionId;
+            }
+            else {
+                const started = await rpc.request("thread/start", {
+                    cwd: req.cwd,
+                    ...(runtimeWorkspaceRoots ? { runtimeWorkspaceRoots } : {}),
+                    approvalPolicy,
+                    ...(sandbox !== undefined ? { sandbox } : {}), // omit -> inherit user's config default
+                    ...(developerInstructions ? { developerInstructions } : {}),
+                });
+                threadId = started.thread?.id;
+                if (!threadId)
+                    throw new Error("thread/start returned no thread id");
+            }
+            queue.push({ kind: "session", sessionId: threadId });
+            const turnStarted = await rpc.request("turn/start", {
+                threadId,
+                input: [{ type: "text", text: req.prompt }],
+                ...(req.model ? { model: req.model } : {}),
+                ...(req.reasoningEffort ? { effort: req.reasoningEffort } : {}),
+                ...(req.schema !== undefined ? { outputSchema: normalizeSchema(req.schema) } : {}),
+            });
+            turnId = turnStarted.turn?.id;
+            const outcome = await Promise.race([
+                turnDone.then((turn) => ({ turn })),
+                proc.exited.then((code) => ({ exitCode: code })),
+            ]);
+            if ("exitCode" in outcome) {
+                if (idleFired)
+                    return; // idle watchdog already reported the error
+                queue.push({
+                    kind: "error",
+                    message: aborted
+                        ? "cancelled: turn aborted by supervisor"
+                        : `app-server exited before turn completion (code ${outcome.exitCode})${lastErrorMessage ? `: ${lastErrorMessage}` : ""}`,
+                });
+                return;
+            }
+            const turn = outcome.turn;
+            if (turn.status === "completed") {
+                const message = finalAnswer ?? lastAgentMessage ?? "";
+                if (req.schema !== undefined) {
+                    let output;
+                    try {
+                        output = JSON.parse(message);
+                    }
+                    catch {
+                        output = extractFirstJsonObject(message);
+                    }
+                    if (output === undefined) {
+                        queue.push({
+                            kind: "error",
+                            message: `structured output parse failed: ${message.slice(0, 500)}`,
+                        });
+                        return;
+                    }
+                    queue.push({ kind: "result", output: restoreOptionalNulls(output, req.schema) });
+                }
+                else {
+                    queue.push({ kind: "result", output: { text: message } });
+                }
+            }
+            else if (turn.status === "interrupted") {
+                queue.push({ kind: "error", message: "cancelled: turn interrupted" });
+            }
+            else {
+                queue.push({
+                    kind: "error",
+                    message: `turn failed: ${turn.error?.message ?? lastErrorMessage ?? "unknown error"}`,
+                });
+            }
+        }
+        catch (err) {
+            // Must run before the finally ends the queue, or the event is dropped.
+            queue.push({ kind: "error", message: String(err) });
+        }
+        finally {
+            ctx.signal.removeEventListener("abort", onAbort);
+            if (idleTimer)
+                clearTimeout(idleTimer);
+            proc.kill();
+            queue.end();
+        }
+    }
+    return { name: "codex", discover, invoke, lintOutputSchema: lintStrictOutputSchema };
+}
+/** Default codex harness bound to the real `codex app-server` binary. */
+export const codexHarness = createCodexHarness();

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { codexHarness, createCodexHarness, type CodexHarnessOptions } from "./harness.js";
+export { JsonRpcClient, type JsonRpcClientOptions } from "./rpc.js";
+export { extractFirstJsonObject, lintStrictOutputSchema, normalizeSchema } from "./schema.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { codexHarness, createCodexHarness } from "./harness.js";
+export { JsonRpcClient } from "./rpc.js";
+export { extractFirstJsonObject, lintStrictOutputSchema, normalizeSchema } from "./schema.js";

package/dist/rpc.d.ts

@@ -0,0 +1,34 @@
+import type { Proc } from "@karowanorg/orc-core";
+export type RpcId = number | string;
+export interface JsonRpcClientOptions {
+    /** Server -> client notification (method, params). */
+    onNotification?: (method: string, params: unknown) => void;
+    /**
+     * Server -> client request. The resolved value is sent back as the JSON-RPC
+     * result; a rejection is sent as a JSON-RPC error.
+     */
+    onServerRequest?: (method: string, params: unknown) => Promise<unknown>;
+    log?: (message: string) => void;
+}
+/**
+ * Minimal newline-delimited JSON-RPC 2.0 client over a Proc's stdio.
+ * Hand-rolled on purpose: the same client works locally and across ssh,
+ * because the executor provides the pipes.
+ */
+export declare class JsonRpcClient {
+    private readonly proc;
+    private readonly opts;
+    private nextId;
+    private readonly pending;
+    private buffer;
+    private closed;
+    constructor(proc: Proc, opts?: JsonRpcClientOptions);
+    request<T = unknown>(method: string, params?: unknown): Promise<T>;
+    notify(method: string, params?: unknown): void;
+    respond(id: RpcId, result: unknown): void;
+    respondError(id: RpcId, code: number, message: string): void;
+    private send;
+    private onData;
+    private dispatch;
+    private failAll;
+}

package/dist/rpc.js

@@ -0,0 +1,100 @@
+/**
+ * Minimal newline-delimited JSON-RPC 2.0 client over a Proc's stdio.
+ * Hand-rolled on purpose: the same client works locally and across ssh,
+ * because the executor provides the pipes.
+ */
+export class JsonRpcClient {
+    proc;
+    opts;
+    nextId = 1;
+    pending = new Map();
+    buffer = "";
+    closed = false;
+    constructor(proc, opts = {}) {
+        this.proc = proc;
+        this.opts = opts;
+        proc.stdout.setEncoding("utf8");
+        proc.stdout.on("data", (chunk) => this.onData(chunk));
+        void proc.exited.then((code) => this.failAll(new Error(`app-server exited (code ${code})`)));
+    }
+    request(method, params) {
+        const id = this.nextId++;
+        const promise = new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve: resolve, reject });
+        });
+        this.send({ jsonrpc: "2.0", id, method, params });
+        return promise;
+    }
+    notify(method, params) {
+        this.send({ jsonrpc: "2.0", method, params });
+    }
+    respond(id, result) {
+        this.send({ jsonrpc: "2.0", id, result });
+    }
+    respondError(id, code, message) {
+        this.send({ jsonrpc: "2.0", id, error: { code, message } });
+    }
+    send(msg) {
+        if (this.closed || !this.proc.stdin)
+            return;
+        try {
+            this.proc.stdin.write(JSON.stringify(msg) + "\n");
+        }
+        catch (err) {
+            this.opts.log?.(`rpc write failed: ${String(err)}`);
+        }
+    }
+    onData(chunk) {
+        this.buffer += chunk;
+        let idx;
+        while ((idx = this.buffer.indexOf("\n")) >= 0) {
+            const line = this.buffer.slice(0, idx).trim();
+            this.buffer = this.buffer.slice(idx + 1);
+            if (!line)
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                this.opts.log?.(`rpc: unparseable line: ${line.slice(0, 200)}`);
+                continue;
+            }
+            this.dispatch(msg);
+        }
+    }
+    dispatch(msg) {
+        if (msg.id !== undefined && msg.method === undefined) {
+            // Response to one of our requests.
+            const entry = this.pending.get(msg.id);
+            if (!entry)
+                return;
+            this.pending.delete(msg.id);
+            if (msg.error)
+                entry.reject(new Error(`${msg.error.message} (rpc ${msg.error.code})`));
+            else
+                entry.resolve(msg.result);
+            return;
+        }
+        if (msg.id !== undefined && msg.method !== undefined) {
+            // Server -> client request (approvals etc.).
+            const id = msg.id;
+            const handler = this.opts.onServerRequest;
+            if (!handler) {
+                this.respondError(id, -32601, `no handler for ${msg.method}`);
+                return;
+            }
+            handler(msg.method, msg.params).then((result) => this.respond(id, result), (err) => this.respondError(id, -32603, String(err)));
+            return;
+        }
+        if (msg.method !== undefined) {
+            this.opts.onNotification?.(msg.method, msg.params);
+        }
+    }
+    failAll(err) {
+        this.closed = true;
+        for (const [, entry] of this.pending)
+            entry.reject(err);
+        this.pending.clear();
+    }
+}

package/dist/schema.d.ts

@@ -0,0 +1,37 @@
+import type { Json } from "@karowanorg/orc-core";
+/**
+ * Normalize a JSON Schema for codex `outputSchema`.
+ *
+ * OpenAI structured output (which codex uses) is STRICTER than Claude's:
+ * on every object it requires `additionalProperties: false` AND that `required`
+ * lists every key in `properties`. A merely-optional field ("gap" not in
+ * required) is rejected as `invalid_json_schema`. The documented transform is:
+ * make every property required, and for the ones that were originally optional,
+ * make them NULLABLE so the model can still omit them by returning null. That
+ * preserves the author's intent (optional) while satisfying strict mode.
+ */
+export declare function normalizeSchema(schema: Json): Json;
+/**
+ * Project Codex's strict-schema output back to the caller's schema semantics.
+ * Strict mode represents an omitted optional field as `null`; the original
+ * schema generally expects that key to be absent instead.
+ */
+export declare function restoreOptionalNulls(value: Json, schema: Json): Json;
+/**
+ * Statically flag the parts of a JSON Schema that OpenAI/codex strict output
+ * REJECTS and that `normalizeSchema` cannot auto-fix without changing meaning.
+ *
+ * The one construct that can't be repaired is an open-ended object — a map with
+ * `additionalProperties: true` (or a sub-schema). Strict mode can only describe
+ * a fixed set of keys, so the only faithful fix is the author's: replace the map
+ * with an array of typed records (e.g. `{ name, value }`). `normalizeSchema`
+ * injects `additionalProperties: false` only when the key is ABSENT, so an
+ * explicit open map survives to a runtime `invalid_json_schema` — which this
+ * lint turns into an up-front `orc validate` problem instead.
+ */
+export declare function lintStrictOutputSchema(schema: Json): string[];
+/**
+ * Extract the first balanced top-level JSON object from free text and parse
+ * it. Returns undefined when no parseable object exists.
+ */
+export declare function extractFirstJsonObject(text: string): Json | undefined;

package/dist/schema.js

@@ -0,0 +1,281 @@
+import { validateAgainstSchema } from "@karowanorg/orc-core";
+/**
+ * Normalize a JSON Schema for codex `outputSchema`.
+ *
+ * OpenAI structured output (which codex uses) is STRICTER than Claude's:
+ * on every object it requires `additionalProperties: false` AND that `required`
+ * lists every key in `properties`. A merely-optional field ("gap" not in
+ * required) is rejected as `invalid_json_schema`. The documented transform is:
+ * make every property required, and for the ones that were originally optional,
+ * make them NULLABLE so the model can still omit them by returning null. That
+ * preserves the author's intent (optional) while satisfying strict mode.
+ */
+export function normalizeSchema(schema) {
+    if (Array.isArray(schema))
+        return schema.map(normalizeSchema);
+    if (schema === null || typeof schema !== "object")
+        return schema;
+    const source = { ...schema };
+    const isObjectType = source.type === "object";
+    const hasProps = source.properties !== null && typeof source.properties === "object";
+    let originallyRequired = new Set();
+    if (Array.isArray(source.required)) {
+        originallyRequired = new Set(source.required.filter((k) => typeof k === "string"));
+    }
+    const out = {};
+    const propKeys = [];
+    for (const key of Object.keys(source).sort()) {
+        if (key === "properties" && hasProps) {
+            const props = source[key];
+            const sorted = {};
+            for (const p of Object.keys(props).sort()) {
+                propKeys.push(p);
+                let normalized = normalizeSchema(props[p]);
+                if (!originallyRequired.has(p))
+                    normalized = makeNullable(normalized);
+                sorted[p] = normalized;
+            }
+            out[key] = sorted;
+        }
+        else if (key === "required" && hasProps) {
+            // replaced below with the full key set (strict mode)
+        }
+        else {
+            out[key] = normalizeSchema(source[key]);
+        }
+    }
+    // Every object gets additionalProperties:false (unless explicitly set); an
+    // object WITH properties additionally requires every key (strict mode).
+    if (isObjectType && !("additionalProperties" in source))
+        out.additionalProperties = false;
+    if (hasProps)
+        out.required = [...propKeys].sort();
+    // Stable wire form: sorted top-level keys (incl. the injected ones).
+    const sortedOut = {};
+    for (const k of Object.keys(out).sort())
+        sortedOut[k] = out[k];
+    return sortedOut;
+}
+/**
+ * Project Codex's strict-schema output back to the caller's schema semantics.
+ * Strict mode represents an omitted optional field as `null`; the original
+ * schema generally expects that key to be absent instead.
+ */
+export function restoreOptionalNulls(value, schema) {
+    return restoreNode(value, schema, schema, new Set());
+}
+function restoreNode(value, schema, root, refs) {
+    if (schema === null || typeof schema !== "object" || Array.isArray(schema))
+        return value;
+    const s = schema;
+    if (typeof s.$ref === "string" && !refs.has(s.$ref)) {
+        const target = resolveLocalRef(root, s.$ref);
+        if (target !== undefined) {
+            refs.add(s.$ref);
+            value = restoreNode(value, target, root, refs);
+            refs.delete(s.$ref);
+        }
+    }
+    if (Array.isArray(value)) {
+        if (s.items !== undefined && !Array.isArray(s.items)) {
+            value = value.map((item) => restoreNode(item, s.items, root, refs));
+        }
+    }
+    else if (value !== null && typeof value === "object") {
+        const properties = s.properties !== null && typeof s.properties === "object" && !Array.isArray(s.properties)
+            ? s.properties
+            : undefined;
+        if (properties) {
+            const required = new Set(Array.isArray(s.required)
+                ? s.required.filter((key) => typeof key === "string")
+                : []);
+            const out = { ...value };
+            for (const [key, propertySchema] of Object.entries(properties)) {
+                if (!(key in out))
+                    continue;
+                if (out[key] === null &&
+                    !required.has(key) &&
+                    !acceptsNull(propertySchema, root)) {
+                    delete out[key];
+                }
+                else {
+                    out[key] = restoreNode(out[key], propertySchema, root, refs);
+                }
+            }
+            value = out;
+        }
+    }
+    if (Array.isArray(s.allOf)) {
+        for (const branch of s.allOf)
+            value = restoreNode(value, branch, root, refs);
+    }
+    const union = Array.isArray(s.anyOf)
+        ? s.anyOf
+        : Array.isArray(s.oneOf)
+            ? s.oneOf
+            : undefined;
+    if (union) {
+        const original = union.find((branch) => matchesSchema(value, branch, root));
+        if (original)
+            return restoreNode(value, original, root, refs);
+        for (const branch of union) {
+            const candidate = restoreNode(value, branch, root, refs);
+            if (matchesSchema(candidate, branch, root))
+                return candidate;
+        }
+    }
+    return value;
+}
+function matchesSchema(value, schema, root) {
+    if (schema === null ||
+        typeof schema !== "object" ||
+        Array.isArray(schema) ||
+        root === null ||
+        typeof root !== "object" ||
+        Array.isArray(root)) {
+        return validateAgainstSchema(value, schema) === null;
+    }
+    const rootSchema = root;
+    return (validateAgainstSchema(value, {
+        ...schema,
+        ...("$defs" in rootSchema && !("$defs" in schema) ? { $defs: rootSchema.$defs } : {}),
+        ...("definitions" in rootSchema && !("definitions" in schema)
+            ? { definitions: rootSchema.definitions }
+            : {}),
+    }) === null);
+}
+function resolveLocalRef(root, ref) {
+    if (ref === "#")
+        return root;
+    if (!ref.startsWith("#/"))
+        return undefined;
+    let node = root;
+    for (const raw of ref.slice(2).split("/")) {
+        if (node === null || typeof node !== "object" || Array.isArray(node))
+            return undefined;
+        const key = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+        node = node[key];
+    }
+    return node;
+}
+/**
+ * Statically flag the parts of a JSON Schema that OpenAI/codex strict output
+ * REJECTS and that `normalizeSchema` cannot auto-fix without changing meaning.
+ *
+ * The one construct that can't be repaired is an open-ended object — a map with
+ * `additionalProperties: true` (or a sub-schema). Strict mode can only describe
+ * a fixed set of keys, so the only faithful fix is the author's: replace the map
+ * with an array of typed records (e.g. `{ name, value }`). `normalizeSchema`
+ * injects `additionalProperties: false` only when the key is ABSENT, so an
+ * explicit open map survives to a runtime `invalid_json_schema` — which this
+ * lint turns into an up-front `orc validate` problem instead.
+ */
+export function lintStrictOutputSchema(schema) {
+    const problems = [];
+    walk(schema, "$");
+    return problems;
+    function walk(node, path) {
+        if (Array.isArray(node)) {
+            node.forEach((item, i) => walk(item, `${path}[${i}]`));
+            return;
+        }
+        if (node === null || typeof node !== "object")
+            return;
+        const o = node;
+        const isObject = o.type === "object" || (o.properties != null && typeof o.properties === "object");
+        if (isObject && "additionalProperties" in o && o.additionalProperties !== false) {
+            problems.push(`${path}: open-ended object (additionalProperties is not false) — codex strict structured output can't express arbitrary keys; replace the map with an array of typed records, e.g. [{ name, value }]`);
+        }
+        for (const [k, v] of Object.entries(o))
+            walk(v, path === "$" ? `$.${k}` : `${path}.${k}`);
+    }
+}
+/** Make a property schema accept null (optional-in-strict-mode). */
+function makeNullable(schema) {
+    if (schema === false)
+        return { type: "null" };
+    if (schema === null || typeof schema !== "object" || Array.isArray(schema))
+        return schema;
+    const s = { ...schema };
+    if (acceptsNull(s))
+        return s;
+    return { anyOf: [s, { type: "null" }] };
+}
+function acceptsNull(schema, root = schema, seen = new Set()) {
+    if (typeof schema === "boolean")
+        return schema;
+    if (schema === null || typeof schema !== "object" || Array.isArray(schema))
+        return false;
+    if (seen.has(schema))
+        return true;
+    seen.add(schema);
+    const s = schema;
+    let allowed = true;
+    if (typeof s.type === "string")
+        allowed &&= s.type === "null";
+    else if (Array.isArray(s.type))
+        allowed &&= s.type.includes("null");
+    if (Array.isArray(s.enum))
+        allowed &&= s.enum.includes(null);
+    if ("const" in s)
+        allowed &&= s.const === null;
+    if (typeof s.$ref === "string") {
+        const target = resolveLocalRef(root, s.$ref);
+        allowed &&= target !== undefined && acceptsNull(target, root, seen);
+    }
+    if (Array.isArray(s.allOf)) {
+        allowed &&= s.allOf.every((branch) => acceptsNull(branch, root, seen));
+    }
+    if (Array.isArray(s.anyOf)) {
+        allowed &&= s.anyOf.some((branch) => acceptsNull(branch, root, seen));
+    }
+    if (Array.isArray(s.oneOf)) {
+        allowed &&=
+            s.oneOf.filter((branch) => acceptsNull(branch, root, new Set(seen))).length === 1;
+    }
+    if (s.not !== undefined)
+        allowed &&= !acceptsNull(s.not, root, new Set(seen));
+    seen.delete(schema);
+    return allowed;
+}
+/**
+ * Extract the first balanced top-level JSON object from free text and parse
+ * it. Returns undefined when no parseable object exists.
+ */
+export function extractFirstJsonObject(text) {
+    let start = text.indexOf("{");
+    while (start >= 0) {
+        let depth = 0;
+        let inString = false;
+        let escaped = false;
+        for (let i = start; i < text.length; i++) {
+            const ch = text[i];
+            if (inString) {
+                if (escaped)
+                    escaped = false;
+                else if (ch === "\\")
+                    escaped = true;
+                else if (ch === '"')
+                    inString = false;
+                continue;
+            }
+            if (ch === '"')
+                inString = true;
+            else if (ch === "{")
+                depth++;
+            else if (ch === "}") {
+                depth--;
+                if (depth === 0) {
+                    try {
+                        return JSON.parse(text.slice(start, i + 1));
+                    }
+                    catch {
+                        break; // unbalanced-in-spirit; retry from the next brace
+                    }
+                }
+            }
+        }
+        start = text.indexOf("{", start + 1);
+    }
+    return undefined;
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@karowanorg/orc-harness-codex",
+  "version": "0.1.0",
+  "license": "0BSD",
+  "type": "module",
+  "main": "dist/index.js",
+  "dependencies": {
+    "@karowanorg/orc-core": "^0.1.0",
+    "@karowanorg/orc-executors": "^0.1.0"
+  },
+  "description": "Codex harness for orc: codex app-server JSON-RPC through the executor.",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}