@parall/codex-agent 1.18.0

package/dist/event-mapping.js

@@ -0,0 +1,246 @@
+/**
+ * Translation layer between `codex app-server` JSON-RPC notifications and
+ * `@parall/agent-core` RuntimeEvents. The adapter owns one of these per
+ * in-flight turn.
+ *
+ * Delta policy: Codex emits streaming `item/*\/delta` chunks plus a final
+ * `item/completed` with the aggregated text. We drop all `*_delta`
+ * notifications entirely and only emit the aggregated `item/completed`
+ * text — symmetric with the Claude bridge, which similarly projects the
+ * assistant's final message as one event.
+ *
+ * Output contract: every `text` event is emitted with `project: false`.
+ * Under the symmetric Layer 0 contract (see
+ * `docs/engineering-design/agent-dm-loop-prevention.md`), plain text is
+ * recorded as a suppressed session step for audit but never surfaces as a
+ * chat message. Outbound messages happen exclusively via the agent
+ * explicitly invoking `@parall/cli messages send` / `dm`.
+ */
+export class EventMapper {
+    toolCallStart = new Map();
+    /**
+     * Map a single server notification to zero or more RuntimeEvents.
+     * Return `null` for notifications that have no chat surface.
+     */
+    map(method, params) {
+        const events = [];
+        const p = (params ?? {});
+        switch (method) {
+            // Streaming deltas are intentionally dropped — see the class comment.
+            case "item/agentMessage/delta":
+            case "item/reasoning/textDelta":
+            case "item/reasoning/summaryTextDelta":
+                break;
+            case "item/started": {
+                const item = p.item;
+                if (!item || typeof item.type !== "string")
+                    break;
+                events.push(...this.mapItem(item, "started"));
+                break;
+            }
+            case "item/completed": {
+                const item = p.item;
+                if (!item || typeof item.type !== "string")
+                    break;
+                events.push(...this.mapItem(item, "completed"));
+                break;
+            }
+            case "turn/completed": {
+                const turn = p.turn;
+                const status = turn ? asString(turn.status) : undefined;
+                const error = turn?.error;
+                if (status === "failed") {
+                    const message = asString(error?.message) ?? "Codex turn failed";
+                    events.push({ type: "error", message });
+                }
+                break;
+            }
+            case "error": {
+                const message = asString(p.message) ?? "Codex error";
+                events.push({ type: "error", message });
+                break;
+            }
+        }
+        return events;
+    }
+    mapItem(item, phase) {
+        const type = asString(item.type);
+        const id = asString(item.id);
+        const now = Date.now();
+        if (type === "agentMessage") {
+            if (phase !== "completed")
+                return [];
+            const text = asString(item.text);
+            if (!text)
+                return [];
+            // Layer 0 symmetric output contract: plain text is never auto-projected;
+            // agents must explicitly call `@parall/cli messages send` / `dm` to reach
+            // the chat. The text is still recorded as a session step for audit.
+            return [{ type: "text", text, project: false }];
+        }
+        if (type === "reasoning") {
+            if (phase !== "completed")
+                return [];
+            const text = joinReasoningText(item);
+            if (!text)
+                return [];
+            return [{ type: "thinking", text }];
+        }
+        if (type === "commandExecution") {
+            const command = formatCommand(item.command);
+            const callId = id ?? `shell-${now}`;
+            if (phase === "started") {
+                this.toolCallStart.set(callId, now);
+                return [{
+                        type: "tool_call",
+                        callId,
+                        toolName: "shell",
+                        input: { command, cwd: asString(item.cwd) },
+                        startedAt: new Date(now).toISOString(),
+                    }];
+            }
+            // Codex app-server uses camelCase: aggregatedOutput / exitCode / durationMs
+            // (see openai/codex codex-rs/app-server-protocol). Earlier snake_case
+            // probing dropped exit codes and split outputs that arrive as one string.
+            const durationMs = this.resolveDuration(callId, now, item.durationMs);
+            const output = asString(item.aggregatedOutput) ?? joinStreams(item.stdout, item.stderr);
+            const exitCode = typeof item.exitCode === "number" ? item.exitCode : undefined;
+            const status = asString(item.status);
+            const failed = (exitCode !== undefined && exitCode !== 0)
+                || status === "failed"
+                || status === "declined";
+            return [{
+                    type: "tool_result",
+                    callId,
+                    toolName: "shell",
+                    output,
+                    ...(failed ? { error: output || `shell ${status ?? "exited"} (code=${exitCode ?? "?"})` } : {}),
+                    ...(durationMs !== undefined ? { durationMs } : {}),
+                }];
+        }
+        if (type === "mcpToolCall") {
+            const server = asString(item.server);
+            const tool = asString(item.tool);
+            const toolName = server && tool ? `${server}:${tool}` : tool ?? server ?? "mcp";
+            const callId = id ?? `mcp-${now}`;
+            if (phase === "started") {
+                this.toolCallStart.set(callId, now);
+                return [{
+                        type: "tool_call",
+                        callId,
+                        toolName,
+                        input: item.arguments ?? {},
+                        startedAt: new Date(now).toISOString(),
+                    }];
+            }
+            const durationMs = this.resolveDuration(callId, now, item.durationMs);
+            const result = item.result;
+            // result === null/undefined must collapse to an empty string, not the
+            // literal `'""'` that JSON.stringify("") would produce — otherwise the
+            // success path renders an empty-quoted output and the failure path's
+            // `output || "MCP tool call failed"` fallback gets eaten because the
+            // literal `'""'` is truthy.
+            const output = result == null
+                ? ""
+                : typeof result === "string" ? result : JSON.stringify(result);
+            const success = item.isSuccess !== false;
+            return [{
+                    type: "tool_result",
+                    callId,
+                    toolName,
+                    output,
+                    ...(success ? {} : { error: output || "MCP tool call failed" }),
+                    ...(durationMs !== undefined ? { durationMs } : {}),
+                }];
+        }
+        if (type === "fileChange") {
+            const callId = id ?? `patch-${now}`;
+            if (phase === "started") {
+                this.toolCallStart.set(callId, now);
+                return [{
+                        type: "tool_call",
+                        callId,
+                        toolName: "patch",
+                        input: { changes: item.changes ?? [] },
+                        startedAt: new Date(now).toISOString(),
+                    }];
+            }
+            const durationMs = this.resolveDuration(callId, now, undefined);
+            return [{
+                    type: "tool_result",
+                    callId,
+                    toolName: "patch",
+                    output: "",
+                    ...(durationMs !== undefined ? { durationMs } : {}),
+                }];
+        }
+        if (type === "webSearch") {
+            const callId = id ?? `search-${now}`;
+            if (phase === "started") {
+                this.toolCallStart.set(callId, now);
+                return [{
+                        type: "tool_call",
+                        callId,
+                        toolName: "web_search",
+                        input: { query: asString(item.query) ?? "" },
+                        startedAt: new Date(now).toISOString(),
+                    }];
+            }
+            const durationMs = this.resolveDuration(callId, now, item.durationMs);
+            const results = Array.isArray(item.results) ? item.results : [];
+            const output = results.length > 0 ? JSON.stringify(results) : "";
+            return [{
+                    type: "tool_result",
+                    callId,
+                    toolName: "web_search",
+                    output,
+                    ...(durationMs !== undefined ? { durationMs } : {}),
+                }];
+        }
+        return [];
+    }
+    /**
+     * Compute the durationMs for a tool call completion, preferring the server's
+     * value and falling back to the locally measured interval. Always clears the
+     * tracked start timestamp so long-lived bridges don't accumulate stale
+     * entries when the server routinely supplies durationMs.
+     */
+    resolveDuration(callId, now, serverDurationMs) {
+        const start = this.toolCallStart.get(callId);
+        this.toolCallStart.delete(callId);
+        if (typeof serverDurationMs === "number" && Number.isFinite(serverDurationMs)) {
+            return Math.max(0, serverDurationMs);
+        }
+        if (start === undefined)
+            return undefined;
+        return Math.max(0, now - start);
+    }
+}
+function asString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function joinReasoningText(item) {
+    const summary = Array.isArray(item.summary) ? item.summary.filter((x) => typeof x === "string") : [];
+    const content = Array.isArray(item.content) ? item.content.filter((x) => typeof x === "string") : [];
+    const parts = [...summary, ...content, asString(item.text)].filter(Boolean);
+    return parts.join("\n").trim();
+}
+function joinStreams(stdout, stderr) {
+    const out = asString(stdout);
+    const err = asString(stderr);
+    if (out && err)
+        return `${out}\n${err}`;
+    return out ?? err ?? "";
+}
+/** Codex sends `command` either as a plain string or as an argv array (e.g. ["sh", "-c", "ls"]). */
+function formatCommand(command) {
+    if (typeof command === "string")
+        return command;
+    if (Array.isArray(command)) {
+        return command.map((part) => (typeof part === "string" ? part : JSON.stringify(part))).join(" ");
+    }
+    return "";
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# 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":""}

package/dist/index.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import * as os from "node:os";
+import { ParallAgentGateway } from "@parall/agent-core";
+import { ParallClient, ParallWs } from "@parall/sdk";
+import { buildCodexRuntimeKey, resolveCodexAgentConfig, resolveWsUrl, sessionStateFilePathForRuntime, stepIdFilePathForSession, } from "./config.js";
+import { CodexAppServerAdapter } from "./dispatch.js";
+import { CodexSessionManager } from "./session-manager.js";
+import { ensureCodexWorkspace } from "./workspace.js";
+function createLogger(prefix) {
+    return {
+        info: (msg) => console.log(`[${prefix}] ${msg}`),
+        warn: (msg) => console.warn(`[${prefix}] ${msg}`),
+        error: (msg) => console.error(`[${prefix}] ${msg}`),
+    };
+}
+async function main() {
+    const config = resolveCodexAgentConfig(process.env);
+    const log = createLogger("codex-agent");
+    ensureCodexWorkspace(config.workspaceDir, log);
+    const client = new ParallClient({
+        baseUrl: config.apiUrl,
+        token: config.apiKey,
+        swimlaneName: config.swimlaneName,
+    });
+    const me = await client.getMe();
+    const agentUserId = me.id;
+    const runtimeKey = config.runtimeKey || buildCodexRuntimeKey(agentUserId);
+    const sessionStateFilePath = sessionStateFilePathForRuntime(config.stateDir, runtimeKey);
+    const sessionManager = new CodexSessionManager(runtimeKey, sessionStateFilePath, log);
+    const resolvedWsUrl = resolveWsUrl(config.apiUrl, config.wsUrl, config.swimlaneName);
+    const ws = new ParallWs({
+        getTicket: () => client.getWsTicket(),
+        wsUrl: resolvedWsUrl,
+    });
+    const adapter = new CodexAppServerAdapter({
+        codexBin: config.codexBin,
+        codexHome: config.codexHome,
+        workspaceDir: config.workspaceDir,
+        model: config.model,
+        reasoningEffort: config.reasoningEffort,
+        sandbox: config.sandbox,
+        approvalPolicy: config.approvalPolicy,
+        sessionManager,
+        log,
+    });
+    const gateway = new ParallAgentGateway({
+        accountId: agentUserId,
+        client,
+        ws,
+        connectionLabel: resolvedWsUrl,
+        config: {
+            parall_url: config.apiUrl,
+            api_key: config.apiKey,
+            org_id: config.orgId,
+        },
+        agentUserId,
+        runtimeType: "codex",
+        runtimeKey,
+        runtimeRef: {
+            hostname: os.hostname(),
+            pid: process.pid,
+            workspace_dir: config.workspaceDir,
+            codex_home: config.codexHome,
+            driver: "app-server",
+        },
+        dispatchAdapter: adapter,
+        log,
+        stepIdFilePathForSession: (sessionKey) => stepIdFilePathForSession(config.stateDir, sessionKey),
+    });
+    const abortController = new AbortController();
+    const abort = () => abortController.abort();
+    process.on("SIGINT", abort);
+    process.on("SIGTERM", abort);
+    try {
+        log.info(`starting self-hosted Codex runtime (app-server driver) for ${me.display_name} (${agentUserId})`);
+        await gateway.run(abortController.signal);
+    }
+    finally {
+        await adapter.stop();
+        process.off("SIGINT", abort);
+        process.off("SIGTERM", abort);
+    }
+}
+main().catch((err) => {
+    console.error(`[codex-agent] fatal: ${String(err)}`);
+    process.exitCode = 1;
+});

package/dist/jsonrpc-client.d.ts

@@ -0,0 +1,51 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+type JsonRpcId = number | string;
+export type JsonRpcRequest = {
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+    method: string;
+    params?: unknown;
+};
+export type JsonRpcNotification = {
+    jsonrpc: "2.0";
+    method: string;
+    params?: unknown;
+};
+export type JsonRpcResponse = {
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+};
+export type NotificationHandler = (method: string, params: unknown) => void;
+/**
+ * Minimal JSON-RPC 2.0 stdio client used to drive a long-running
+ * `codex app-server --listen stdio://` subprocess. Frames are newline
+ * delimited JSON — one message per line. The client dispatches server
+ * responses to the originating request promise and forwards every
+ * notification to a single handler; dispatch-side routing (per thread,
+ * per turn) lives in the adapter, not here.
+ */
+export declare class JsonRpcStdioClient {
+    private readonly proc;
+    private readonly requestTimeoutMs;
+    private nextId;
+    private readonly pending;
+    private buffer;
+    private onNotification;
+    private disposed;
+    constructor(proc: ChildProcessWithoutNullStreams, requestTimeoutMs?: number);
+    setNotificationHandler(handler: NotificationHandler): void;
+    sendRequest(method: string, params?: unknown): Promise<unknown>;
+    sendNotification(method: string, params?: unknown): void;
+    dispose(err: Error): void;
+    private writeFrame;
+    private ingest;
+    private handleLine;
+}
+export {};
+//# sourceMappingURL=jsonrpc-client.d.ts.map

package/dist/jsonrpc-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonrpc-client.d.ts","sourceRoot":"","sources":["../src/jsonrpc-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,oBAAoB,CAAC;AAEzE,KAAK,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAEjC,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,SAAS,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,SAAS,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC3D,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;AAW5E;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAQ3B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IARnC,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,MAAM,CAAM;IACpB,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,QAAQ,CAAS;gBAGN,IAAI,EAAE,8BAA8B,EACpC,gBAAgB,GAAE,MAAmC;IAQxE,sBAAsB,CAAC,OAAO,EAAE,mBAAmB;IAInD,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAmB/D,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO;IAMjD,OAAO,CAAC,GAAG,EAAE,KAAK;IAUlB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,MAAM;IAWd,OAAO,CAAC,UAAU;CAyBnB"}

package/dist/jsonrpc-client.js

@@ -0,0 +1,111 @@
+/** Maximum time to wait for a JSON-RPC response before rejecting. */
+const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
+/**
+ * Minimal JSON-RPC 2.0 stdio client used to drive a long-running
+ * `codex app-server --listen stdio://` subprocess. Frames are newline
+ * delimited JSON — one message per line. The client dispatches server
+ * responses to the originating request promise and forwards every
+ * notification to a single handler; dispatch-side routing (per thread,
+ * per turn) lives in the adapter, not here.
+ */
+export class JsonRpcStdioClient {
+    proc;
+    requestTimeoutMs;
+    nextId = 1;
+    pending = new Map();
+    buffer = "";
+    onNotification = null;
+    disposed = false;
+    constructor(proc, requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+        this.proc = proc;
+        this.requestTimeoutMs = requestTimeoutMs;
+        proc.stdout.setEncoding("utf8");
+        proc.stdout.on("data", (chunk) => this.ingest(chunk));
+        proc.once("close", () => this.dispose(new Error("app-server subprocess closed")));
+        proc.once("error", (err) => this.dispose(err));
+    }
+    setNotificationHandler(handler) {
+        this.onNotification = handler;
+    }
+    sendRequest(method, params) {
+        if (this.disposed) {
+            return Promise.reject(new Error("JSON-RPC client disposed"));
+        }
+        const id = this.nextId++;
+        const request = { jsonrpc: "2.0", id, method, params };
+        const promise = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                const pending = this.pending.get(id);
+                if (!pending)
+                    return;
+                this.pending.delete(id);
+                reject(new Error(`JSON-RPC request "${method}" timed out after ${this.requestTimeoutMs}ms`));
+            }, this.requestTimeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+        });
+        this.writeFrame(request);
+        return promise;
+    }
+    sendNotification(method, params) {
+        if (this.disposed)
+            return;
+        const notification = { jsonrpc: "2.0", method, params };
+        this.writeFrame(notification);
+    }
+    dispose(err) {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(err);
+        }
+        this.pending.clear();
+    }
+    writeFrame(message) {
+        this.proc.stdin.write(`${JSON.stringify(message)}\n`);
+    }
+    ingest(chunk) {
+        this.buffer += chunk;
+        let newlineIndex = this.buffer.indexOf("\n");
+        while (newlineIndex >= 0) {
+            const line = this.buffer.slice(0, newlineIndex).trim();
+            this.buffer = this.buffer.slice(newlineIndex + 1);
+            if (line)
+                this.handleLine(line);
+            newlineIndex = this.buffer.indexOf("\n");
+        }
+    }
+    handleLine(line) {
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (isResponse(message)) {
+            const pending = this.pending.get(message.id);
+            if (!pending)
+                return;
+            this.pending.delete(message.id);
+            clearTimeout(pending.timer);
+            if (message.error) {
+                pending.reject(new Error(message.error.message || "JSON-RPC error"));
+            }
+            else {
+                pending.resolve(message.result);
+            }
+            return;
+        }
+        if (isNotification(message)) {
+            this.onNotification?.(message.method, message.params);
+        }
+    }
+}
+function isResponse(m) {
+    return !!m && typeof m === "object" && "id" in m && ("result" in m || "error" in m);
+}
+function isNotification(m) {
+    return !!m && typeof m === "object" && "method" in m && !("id" in m);
+}

package/dist/session-manager.d.ts

@@ -0,0 +1,28 @@
+import type { ForkSessionHandle } from "@parall/agent-core";
+type Logger = {
+    warn(message: string): void;
+};
+/**
+ * Persists the app-server `threadId` for the main Parall session so the
+ * bridge can resume across restarts via `thread/resume`. Fork sessions
+ * get an ephemeral threadId created via `thread/fork`; they are not
+ * persisted because agent-core's routing treats each fork as disposable.
+ */
+export declare class CodexSessionManager {
+    readonly mainSessionKey: string;
+    private readonly stateFilePath;
+    private readonly logger?;
+    private readonly threadIds;
+    constructor(mainSessionKey: string, stateFilePath: string, logger?: Logger | undefined);
+    isMain(sessionKey: string): boolean;
+    getThreadId(sessionKey: string): string | undefined;
+    recordThreadId(sessionKey: string, threadId: string): void;
+    createForkSessionKey(): ForkSessionHandle;
+    cleanupFork(sessionKey: string): void;
+    /** Clear the main thread id when app-server rejects it (stale / deleted). */
+    clearMainThread(): void;
+    private restore;
+    private persist;
+}
+export {};
+//# sourceMappingURL=session-manager.d.ts.map

package/dist/session-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAO5D,KAAK,MAAM,GAAG;IAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAE9C;;;;;GAKG;AACH,qBAAa,mBAAmB;IAI5B,QAAQ,CAAC,cAAc,EAAE,MAAM;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAL1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;gBAG5C,cAAc,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,YAAA;IAKlC,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAInC,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAInD,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAOnD,oBAAoB,IAAI,iBAAiB;IAOzC,WAAW,CAAC,UAAU,EAAE,MAAM;IAI9B,6EAA6E;IAC7E,eAAe;IAWf,OAAO,CAAC,OAAO;IAgBf,OAAO,CAAC,OAAO;CAqBhB"}

package/dist/session-manager.js

@@ -0,0 +1,82 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+/**
+ * Persists the app-server `threadId` for the main Parall session so the
+ * bridge can resume across restarts via `thread/resume`. Fork sessions
+ * get an ephemeral threadId created via `thread/fork`; they are not
+ * persisted because agent-core's routing treats each fork as disposable.
+ */
+export class CodexSessionManager {
+    mainSessionKey;
+    stateFilePath;
+    logger;
+    threadIds = new Map();
+    constructor(mainSessionKey, stateFilePath, logger) {
+        this.mainSessionKey = mainSessionKey;
+        this.stateFilePath = stateFilePath;
+        this.logger = logger;
+        this.restore();
+    }
+    isMain(sessionKey) {
+        return sessionKey === this.mainSessionKey;
+    }
+    getThreadId(sessionKey) {
+        return this.threadIds.get(sessionKey);
+    }
+    recordThreadId(sessionKey, threadId) {
+        this.threadIds.set(sessionKey, threadId);
+        if (sessionKey === this.mainSessionKey) {
+            this.persist(threadId);
+        }
+    }
+    createForkSessionKey() {
+        const suffix = Math.random().toString(36).slice(2, 10);
+        return {
+            sessionKey: `codex-fork:${Date.now().toString(36)}-${suffix}`,
+        };
+    }
+    cleanupFork(sessionKey) {
+        this.threadIds.delete(sessionKey);
+    }
+    /** Clear the main thread id when app-server rejects it (stale / deleted). */
+    clearMainThread() {
+        this.threadIds.delete(this.mainSessionKey);
+        try {
+            fs.rmSync(this.stateFilePath, { force: true });
+        }
+        catch (error) {
+            this.logger?.warn(`codex-agent: failed to clear main thread state at ${this.stateFilePath}: ${String(error)}`);
+        }
+    }
+    restore() {
+        try {
+            const raw = fs.readFileSync(this.stateFilePath, "utf8");
+            const parsed = JSON.parse(raw);
+            if (parsed.runtimeKey === this.mainSessionKey && typeof parsed.threadId === "string" && parsed.threadId.trim()) {
+                this.threadIds.set(this.mainSessionKey, parsed.threadId.trim());
+            }
+        }
+        catch (error) {
+            if (error?.code !== "ENOENT") {
+                this.logger?.warn(`codex-agent: could not restore main thread state from ${this.stateFilePath}: ${String(error)}`);
+            }
+        }
+    }
+    persist(threadId) {
+        // Atomic write: truncate-in-place risks leaving a half-written / zero-byte
+        // state file if the process dies between `open(O_TRUNC)` and the final
+        // fsync. Since this file is the sole source of cross-restart `resume`
+        // context for the main session, losing it would silently drop
+        // conversation history. Write to a sibling temp file first, then rename —
+        // POSIX rename is atomic within the same directory.
+        try {
+            fs.mkdirSync(path.dirname(this.stateFilePath), { recursive: true });
+            const tmpPath = `${this.stateFilePath}.tmp`;
+            fs.writeFileSync(tmpPath, JSON.stringify({ runtimeKey: this.mainSessionKey, threadId }, null, 2));
+            fs.renameSync(tmpPath, this.stateFilePath);
+        }
+        catch (error) {
+            this.logger?.warn(`codex-agent: failed to persist thread state at ${this.stateFilePath}: ${String(error)}`);
+        }
+    }
+}

package/dist/workspace.d.ts

@@ -0,0 +1,4 @@
+export declare function ensureCodexWorkspace(workspaceDir: string, log?: {
+    warn: (msg: string) => void;
+}): void;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"AAIA,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,MAAM,EACpB,GAAG,CAAC,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,QAyBtC"}

package/dist/workspace.js

@@ -0,0 +1,26 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { BRIDGE_WORKSPACE_INSTRUCTIONS } from "@parall/agent-core";
+export function ensureCodexWorkspace(workspaceDir, log) {
+    fs.mkdirSync(workspaceDir, { recursive: true });
+    // AGENTS.md is bridge-managed: always overwrite so the workspace picks up
+    // updated guardrails / command templates on upgrade. Operators must not
+    // hand-edit this file — workspace customisations should go elsewhere in
+    // the Codex home dir. Surface a warning when we replace divergent content
+    // so an operator who did edit it locally sees a signal instead of silently
+    // losing changes. Mirrors the Claude bridge behaviour.
+    const agentsMdPath = path.join(workspaceDir, "AGENTS.md");
+    if (log) {
+        try {
+            const existing = fs.readFileSync(agentsMdPath, "utf8");
+            if (existing !== BRIDGE_WORKSPACE_INSTRUCTIONS) {
+                log.warn(`codex-agent: overwriting divergent ${agentsMdPath} with bridge-managed template ` +
+                    `(local edits to AGENTS.md are not preserved — customize other files in the workspace instead)`);
+            }
+        }
+        catch {
+            // file missing or unreadable — first-boot case, no warning needed
+        }
+    }
+    fs.writeFileSync(agentsMdPath, BRIDGE_WORKSPACE_INSTRUCTIONS, "utf8");
+}