@parall/codex-agent 1.18.0

package/src/event-mapping.ts

@@ -0,0 +1,258 @@
+import type { RuntimeEvent } from "@parall/agent-core";
+
+/**
+ * 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 {
+  private readonly toolCallStart = new Map<string, number>();
+
+  /**
+   * Map a single server notification to zero or more RuntimeEvents.
+   * Return `null` for notifications that have no chat surface.
+   */
+  map(method: string, params: unknown): RuntimeEvent[] {
+    const events: RuntimeEvent[] = [];
+    const p = (params ?? {}) as Record<string, unknown>;
+
+    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 as Record<string, unknown> | undefined;
+        if (!item || typeof item.type !== "string") break;
+        events.push(...this.mapItem(item, "started"));
+        break;
+      }
+
+      case "item/completed": {
+        const item = p.item as Record<string, unknown> | undefined;
+        if (!item || typeof item.type !== "string") break;
+        events.push(...this.mapItem(item, "completed"));
+        break;
+      }
+
+      case "turn/completed": {
+        const turn = p.turn as Record<string, unknown> | undefined;
+        const status = turn ? asString(turn.status) : undefined;
+        const error = turn?.error as Record<string, unknown> | undefined;
+        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;
+  }
+
+  private mapItem(item: Record<string, unknown>, phase: "started" | "completed"): RuntimeEvent[] {
+    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.
+   */
+  private resolveDuration(callId: string, now: number, serverDurationMs: unknown): number | undefined {
+    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: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function joinReasoningText(item: Record<string, unknown>): string {
+  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) as string[];
+  return parts.join("\n").trim();
+}
+
+function joinStreams(stdout: unknown, stderr: unknown): string {
+  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: unknown): string {
+  if (typeof command === "string") return command;
+  if (Array.isArray(command)) {
+    return command.map((part) => (typeof part === "string" ? part : JSON.stringify(part))).join(" ");
+  }
+  return "";
+}

package/src/index.ts

@@ -0,0 +1,107 @@
+#!/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: string) {
+  return {
+    info: (msg: string) => console.log(`[${prefix}] ${msg}`),
+    warn: (msg: string) => console.warn(`[${prefix}] ${msg}`),
+    error: (msg: string) => 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/src/jsonrpc-client.ts

@@ -0,0 +1,148 @@
+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;
+
+type Pending = {
+  resolve: (result: unknown) => void;
+  reject: (err: Error) => void;
+  timer: NodeJS.Timeout;
+};
+
+/** 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 {
+  private nextId = 1;
+  private readonly pending = new Map<JsonRpcId, Pending>();
+  private buffer = "";
+  private onNotification: NotificationHandler | null = null;
+  private disposed = false;
+
+  constructor(
+    private readonly proc: ChildProcessWithoutNullStreams,
+    private readonly requestTimeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS,
+  ) {
+    proc.stdout.setEncoding("utf8");
+    proc.stdout.on("data", (chunk: string) => this.ingest(chunk));
+    proc.once("close", () => this.dispose(new Error("app-server subprocess closed")));
+    proc.once("error", (err) => this.dispose(err));
+  }
+
+  setNotificationHandler(handler: NotificationHandler) {
+    this.onNotification = handler;
+  }
+
+  sendRequest(method: string, params?: unknown): Promise<unknown> {
+    if (this.disposed) {
+      return Promise.reject(new Error("JSON-RPC client disposed"));
+    }
+    const id = this.nextId++;
+    const request: JsonRpcRequest = { jsonrpc: "2.0", id, method, params };
+    const promise = new Promise<unknown>((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: string, params?: unknown) {
+    if (this.disposed) return;
+    const notification: JsonRpcNotification = { jsonrpc: "2.0", method, params };
+    this.writeFrame(notification);
+  }
+
+  dispose(err: Error) {
+    if (this.disposed) return;
+    this.disposed = true;
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(err);
+    }
+    this.pending.clear();
+  }
+
+  private writeFrame(message: object) {
+    this.proc.stdin.write(`${JSON.stringify(message)}\n`);
+  }
+
+  private ingest(chunk: string) {
+    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");
+    }
+  }
+
+  private handleLine(line: string) {
+    let message: JsonRpcRequest | JsonRpcResponse | JsonRpcNotification;
+    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: unknown): m is JsonRpcResponse {
+  return !!m && typeof m === "object" && "id" in m && ("result" in m || "error" in m);
+}
+
+function isNotification(m: unknown): m is JsonRpcNotification {
+  return !!m && typeof m === "object" && "method" in m && !("id" in m);
+}

package/src/session-manager.ts

@@ -0,0 +1,104 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ForkSessionHandle } from "@parall/agent-core";
+
+type PersistedThread = {
+  runtimeKey: string;
+  threadId: string;
+};
+
+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 class CodexSessionManager {
+  private readonly threadIds = new Map<string, string>();
+
+  constructor(
+    readonly mainSessionKey: string,
+    private readonly stateFilePath: string,
+    private readonly logger?: Logger,
+  ) {
+    this.restore();
+  }
+
+  isMain(sessionKey: string): boolean {
+    return sessionKey === this.mainSessionKey;
+  }
+
+  getThreadId(sessionKey: string): string | undefined {
+    return this.threadIds.get(sessionKey);
+  }
+
+  recordThreadId(sessionKey: string, threadId: string) {
+    this.threadIds.set(sessionKey, threadId);
+    if (sessionKey === this.mainSessionKey) {
+      this.persist(threadId);
+    }
+  }
+
+  createForkSessionKey(): ForkSessionHandle {
+    const suffix = Math.random().toString(36).slice(2, 10);
+    return {
+      sessionKey: `codex-fork:${Date.now().toString(36)}-${suffix}`,
+    };
+  }
+
+  cleanupFork(sessionKey: string) {
+    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)}`,
+      );
+    }
+  }
+
+  private restore() {
+    try {
+      const raw = fs.readFileSync(this.stateFilePath, "utf8");
+      const parsed = JSON.parse(raw) as Partial<PersistedThread>;
+      if (parsed.runtimeKey === this.mainSessionKey && typeof parsed.threadId === "string" && parsed.threadId.trim()) {
+        this.threadIds.set(this.mainSessionKey, parsed.threadId.trim());
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") {
+        this.logger?.warn(
+          `codex-agent: could not restore main thread state from ${this.stateFilePath}: ${String(error)}`,
+        );
+      }
+    }
+  }
+
+  private persist(threadId: string) {
+    // 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/src/workspace.ts

@@ -0,0 +1,32 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { BRIDGE_WORKSPACE_INSTRUCTIONS } from "@parall/agent-core";
+
+export function ensureCodexWorkspace(
+  workspaceDir: string,
+  log?: { warn: (msg: string) => void },
+) {
+  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");
+}