agent-relay-runner 0.10.19 → 0.10.21

package/src/adapters/codex.ts

@@ -1,17 +1,35 @@
-import { existsSync, readdirSync } from "node:fs";
+import { accessSync, constants, existsSync, readFileSync, realpathSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
-import type { Message } from "agent-relay-sdk";
-import { providerMessageText, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type RunnerSpawnConfig, type SemanticStatus, type SpawnArgs } from "../adapter";
+import type { ContextState, Message } from "agent-relay-sdk";
+import { profileAllowsRelayFeature, providerMessageText, RELAY_CONTEXT, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderPermissionDecisionInput, type ProviderStatusUpdate, type RunnerSpawnConfig, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
+import { prepareCodexProfileHome, profileUsesHostProviderGlobals } from "../profile-home";
 import { CodexAppClient, type ClientEvent } from "./codex-client";
 
+type PendingCodexApproval = {
+  id: string;
+  requestId: string | number;
+  method: string;
+  params: Record<string, unknown>;
+  view: Record<string, unknown>;
+};
+
 export class CodexAdapter implements ProviderAdapter {
   readonly provider = "codex";
-  private statusCb: (status: SemanticStatus) => void = () => {};
+  private statusCb: (status: ProviderStatusUpdate) => void = () => {};
+  private readonly subagentThreads = new Map<string, { label?: string; role?: string; parentId?: string }>();
+  private readonly pendingApprovals = new Map<string, PendingCodexApproval>();
 
-  onStatusChange(cb: (status: SemanticStatus) => void): void {
+  onStatusChange(cb: (status: ProviderStatusUpdate) => void): void {
     this.statusCb = cb;
   }
 
+  // The Codex app-server is headless and has no tmux session, but an unexpected
+  // exit should still be restarted with backoff rather than resolved as a final exit.
+  supportsUnexpectedExitRestart(): boolean {
+    return true;
+  }
+
   async spawn(config: RunnerSpawnConfig): Promise<ManagedProcess> {
     const args = this.buildSpawnArgs(config, config.providerConfig as ProviderConfig);
     const appServer = Bun.spawn([args.command, ...args.args], {
@@ -26,11 +44,12 @@ export class CodexAdapter implements ProviderAdapter {
     if (client) {
       await connectWithRetry(client);
       await client.initialize().catch(() => undefined);
-      client.onEvent((event) => this.handleCodexEvent(event));
     }
 
+    const relaySkillArgs = profileAllowsRelayFeature(config, "skills") ? bundledSkillConfigArgs() : [];
+    const defaultArgs = profileUsesHostProviderGlobals(config) ? config.providerConfig.defaultArgs : [];
     const tui = !config.headless && isCodexCliCommand(config.providerConfig.command)
-      ? Bun.spawn([config.providerConfig.command, "--remote", appServerUrl, ...bundledSkillConfigArgs(), ...config.providerConfig.defaultArgs, ...config.providerArgs], {
+      ? Bun.spawn([config.providerConfig.command, "--remote", appServerUrl, ...relaySkillArgs, ...defaultArgs, ...config.providerArgs, ...codexManagedConfigArgs()], {
         cwd: config.cwd,
         env: args.env,
         stdin: "inherit",
@@ -39,9 +58,32 @@ export class CodexAdapter implements ProviderAdapter {
       })
       : undefined;
 
-    void appServer.exited.then((code) => this.statusCb(code === 0 ? "offline" : "error"));
-    if (tui) void tui.exited.then((code) => this.statusCb(code === 0 ? "idle" : "error"));
-    return { pid: tui?.pid ?? appServer.pid, process: appServer, meta: { client, threadId: config.threadId, cwd: config.cwd, appServer, tui } };
+    // app-server and tui exit independently; the first exit defines the agent's
+    // fate. Latch so a trailing second exit can't fire a duplicate terminal event.
+    let exitReported = false;
+    const reportExit = (status: ProviderStatusUpdate): void => {
+      if (exitReported) return;
+      exitReported = true;
+      this.statusCb(status);
+    };
+    void appServer.exited.then((code) => reportExit(code === 0 ? "offline" : "error"));
+    if (tui) void tui.exited.then((code) => reportExit(code === 0 ? "idle" : "error"));
+    const process: ManagedProcess = {
+      pid: tui?.pid ?? appServer.pid,
+      process: appServer,
+      meta: {
+        client,
+        cwd: config.cwd,
+        appServer,
+        appServerUrl,
+        tui,
+        config,
+        attachCommand: resolveRealCodexCommand(config.providerConfig.command, args.env.PATH),
+      },
+    };
+    process.meta = { ...process.meta, getContext: () => latestCodexContext(process) };
+    if (client) client.onEvent((event) => this.handleCodexEvent(event, process));
+    return process;
   }
 
   async shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<void> {
@@ -50,58 +92,605 @@ export class CodexAdapter implements ProviderAdapter {
     await terminateProcess(process, opts);
   }
 
+  async compact(process: ManagedProcess): Promise<Record<string, unknown>> {
+    const client = process.meta?.client as CodexAppClient | undefined;
+    if (!client) throw new Error("Codex App Server client is unavailable");
+    const threadId = typeof process.meta?.threadId === "string" ? process.meta.threadId : "";
+    if (!threadId) throw new Error("Codex thread is not ready");
+    await client.threadCompactStart(threadId);
+    const currentContext = isContextState(process.meta?.context) ? process.meta.context : undefined;
+    if (currentContext) {
+      process.meta = {
+        ...(process.meta ?? {}),
+        context: { ...currentContext, lifecycleState: "compacting", lastUpdatedAt: Date.now() },
+      };
+    }
+    return { threadId };
+  }
+
+  async clearContext(process: ManagedProcess): Promise<Record<string, unknown>> {
+    const client = process.meta?.client as CodexAppClient | undefined;
+    if (!client) throw new Error("Codex App Server client is unavailable");
+    const previousThreadId = typeof process.meta?.threadId === "string" ? process.meta.threadId : undefined;
+    const started = await client.threadStart({ cwd: typeof process.meta?.cwd === "string" ? process.meta.cwd : globalThis.process.cwd() });
+    process.meta = {
+      ...(process.meta ?? {}),
+      threadId: started.thread.id,
+      relayContextSent: false,
+      context: {
+        utilization: 0,
+        lifecycleState: "fresh",
+        warmTopics: [],
+        activeMemories: [],
+        tasksSinceCompact: 0,
+        lastUpdatedAt: Date.now(),
+        source: "api",
+        confidence: "reported",
+      } satisfies ContextState,
+    };
+    return { previousThreadId, threadId: started.thread.id };
+  }
+
+  async terminalAttachSpec(process: ManagedProcess): Promise<TerminalAttachSpec> {
+    const threadId = typeof process.meta?.threadId === "string" ? process.meta.threadId : "";
+    if (!threadId) throw new Error("Codex thread is not ready");
+    const appServerUrl = typeof process.meta?.appServerUrl === "string" ? process.meta.appServerUrl : "";
+    if (!appServerUrl) throw new Error("Codex app-server URL is unavailable");
+    const command = typeof process.meta?.attachCommand === "string" && process.meta.attachCommand
+      ? process.meta.attachCommand
+      : resolveRealCodexCommand("codex");
+    return {
+      mode: "guest",
+      provider: "codex",
+      cwd: typeof process.meta?.cwd === "string" ? process.meta.cwd : globalThis.process.cwd(),
+      command: [command, ...codexManagedConfigArgs(), "resume", threadId, "--remote", appServerUrl, "--no-alt-screen"],
+      title: `Codex ${threadId.slice(0, 8)}`,
+      ttlMs: 60 * 60 * 1000,
+    };
+  }
+
+  async deliverInitialPrompt(process: ManagedProcess, prompt: string): Promise<void> {
+    const text = prompt.trim();
+    if (!text) return;
+    const threadId = await ensureCodexThread(process);
+    let input = [
+      codexLaunchContext(process),
+      "[agent-relay initial prompt from dashboard]",
+      text,
+    ].filter(Boolean).join("\n\n");
+    if (codexRelayContextEnabled(process) && !process.meta?.relayContextSent) {
+      input = RELAY_CONTEXT + "\n\n" + input;
+      process.meta = { ...(process.meta ?? {}), relayContextSent: true };
+    }
+    console.error(`[agent-relay] starting Codex initial prompt in thread ${threadId}`);
+    const client = process.meta?.client as CodexAppClient;
+    await client.turnStart(threadId, input);
+  }
+
   async deliver(process: ManagedProcess, messages: Message[]): Promise<void> {
+    const threadId = await ensureCodexThread(process);
+    let text = [codexLaunchContext(process), providerMessageText(messages)].filter(Boolean).join("\n\n");
+    if (codexRelayContextEnabled(process) && !process.meta?.relayContextSent) {
+      text = RELAY_CONTEXT + "\n\n" + text;
+      process.meta = { ...(process.meta ?? {}), relayContextSent: true };
+    }
+    console.error(codexDeliveryNotice(messages, threadId));
+    const client = process.meta?.client as CodexAppClient;
+    await client.turnStart(threadId, text);
+  }
+
+  async respondToPermissionDecision(process: ManagedProcess, input: ProviderPermissionDecisionInput): Promise<Record<string, unknown>> {
+    const pending = this.pendingApprovals.get(input.approvalId);
+    if (!pending) throw new Error("approval request not found or already resolved");
     const client = process.meta?.client as CodexAppClient | undefined;
     if (!client) throw new Error("Codex App Server client is unavailable");
-    let threadId = typeof process.meta?.threadId === "string" ? process.meta.threadId : "";
-    if (!threadId) {
-      const started = await client.threadStart({ cwd: typeof process.meta?.cwd === "string" ? process.meta.cwd : globalThis.process.cwd() });
-      threadId = started.thread.id;
-      process.meta = { ...(process.meta ?? {}), threadId };
+    const response = codexApprovalResponse(pending.method, pending.params, input.decision);
+    // Always drop the pending entry: a failed send means the request is dead on
+    // the Codex side too, so a stale entry would only mislead later lookups.
+    try {
+      client.respondToServerRequest(pending.requestId, response);
+    } finally {
+      this.pendingApprovals.delete(input.approvalId);
     }
-    await client.turnStart(threadId, providerMessageText(messages));
+    this.statusCb({
+      status: "busy",
+      reason: "provider-turn",
+      providerState: {
+        state: "active",
+        reason: "permissionResolved",
+        label: "Codex approval resolved",
+        source: "codex",
+        updatedAt: Date.now(),
+      },
+    });
+    return { approvalId: input.approvalId, decision: input.decision, provider: "codex" };
   }
 
   buildSpawnArgs(config: RunnerSpawnConfig, providerConfig: ProviderConfig): SpawnArgs {
     const appServerUrl = String(config.appServerUrl || process.env.CODEX_APP_SERVER_URL || `ws://127.0.0.1:${config.controlPort + 1000}`);
+    const profileHome = prepareCodexProfileHome(config);
+    const defaultArgs = profileUsesHostProviderGlobals(config) ? providerConfig.defaultArgs : [];
     const args = isCodexCliCommand(providerConfig.command)
       ? [
         "app-server",
-        ...codexAppServerConfigArgs(providerConfig.defaultArgs, config.providerArgs),
-        ...bundledSkillConfigArgs(),
+        ...codexAppServerConfigArgs(defaultArgs, config.providerArgs),
+        ...codexModelConfigArgs(config.model, config.effort),
+        ...codexApprovalConfigArgs(config.approvalMode),
+        ...(profileAllowsRelayFeature(config, "skills") ? bundledSkillConfigArgs() : []),
+        ...codexManagedConfigArgs(),
         "--listen",
         appServerUrl,
       ]
-      : [...providerConfig.defaultArgs, ...config.providerArgs];
+      : [...defaultArgs, ...config.providerArgs];
     return {
       command: providerConfig.command,
       args,
       cwd: config.cwd,
       env: {
         ...config.env,
+        ...(profileHome ? { CODEX_HOME: profileHome.path } : {}),
         CODEX_APP_SERVER_URL: appServerUrl,
         AGENT_RELAY_PROVIDER: "codex",
       },
     };
   }
 
-  private handleCodexEvent(event: ClientEvent): void {
+  private handleCodexEvent(event: ClientEvent, process?: ManagedProcess): void {
+    if (event.type === "server-request" && process) {
+      const approval = codexApprovalFromServerRequest(event.message);
+      if (approval) {
+        this.pendingApprovals.set(approval.pending.id, approval.pending);
+        this.statusCb({
+          status: "busy",
+          reason: "provider-turn",
+          providerState: {
+            state: "blocked",
+            reason: "permissionRequest",
+            label: approval.view.title,
+            recommendedAction: "Review the permission request in Agent Relay.",
+            source: "codex",
+            pendingApproval: approval.view,
+            updatedAt: Date.now(),
+          },
+        });
+      }
+      return;
+    }
+
     const method = event.type === "notification" ? event.message.method : "";
-    if (method.includes("turn/started") || method.includes("turn.started")) this.statusCb("busy");
-    if (method.includes("turn/completed") || method.includes("turn.completed")) this.statusCb("idle");
+    const params = event.type === "notification" ? event.message.params : undefined;
+    const thread = isRecord(params?.thread) ? params.thread : undefined;
+    const threadId = stringValue(params?.threadId) ?? stringValue(thread?.id);
+    const isSubagent = Boolean(threadId && this.subagentThreads.has(threadId)) || isSubagentThread(thread, params);
+
+    if (threadId && process && !isSubagent) {
+      const threadPath = stringValue(thread?.path) ?? stringValue(params?.path);
+      process.meta = {
+        ...(process.meta ?? {}),
+        threadId,
+        ...(threadPath ? { threadPath } : {}),
+      };
+    }
+
+    if (method.includes("thread/tokenUsage/updated") || method.includes("thread.tokenUsage.updated") || method.includes("thread/token_usage/updated") || method.includes("thread.token_usage.updated")) {
+      const context = codexTokenUsageContext(params);
+      if (context && process) process.meta = { ...(process.meta ?? {}), context };
+    }
+
+    if ((method.includes("thread/started") || method.includes("thread.started")) && threadId && isSubagent) {
+      const details = subagentThreadDetails(thread, params);
+      this.subagentThreads.set(threadId, details);
+      this.statusCb({ status: "busy", reason: "subagent", id: threadId, ...details });
+      return;
+    }
+
+    if (method.includes("turn/started") || method.includes("turn.started")) {
+      if (threadId && this.subagentThreads.has(threadId)) {
+        this.statusCb({ status: "busy", reason: "subagent", id: threadId, ...this.subagentThreads.get(threadId) });
+      } else {
+        this.statusCb({ status: "busy", reason: "provider-turn" });
+      }
+    }
+    if (method.includes("turn/completed") || method.includes("turn.completed")) {
+      if (threadId && this.subagentThreads.has(threadId)) {
+        this.statusCb({ status: "idle", reason: "subagent", id: threadId, ...this.subagentThreads.get(threadId) });
+      } else {
+        this.statusCb({ status: "idle", reason: "provider-turn" });
+      }
+    }
     if (method.includes("thread/status")) {
-      const params = event.type === "notification" ? event.message.params : undefined;
-      const status = params?.status;
-      if (typeof status === "string" && status.includes("active")) this.statusCb("busy");
-      if (typeof status === "string" && status.includes("idle")) this.statusCb("idle");
+      const status = statusType(params?.status);
+      if (threadId && this.subagentThreads.has(threadId)) {
+        if (status === "active") this.statusCb({ status: "busy", reason: "subagent", id: threadId, ...this.subagentThreads.get(threadId) });
+        if (status === "idle" || status === "notLoaded") this.statusCb({ status: "idle", reason: "subagent", id: threadId, ...this.subagentThreads.get(threadId) });
+      } else {
+        if (status === "active") this.statusCb({ status: "busy", reason: "provider-turn", providerState: this.providerStateFromThreadStatus(params?.status, params) });
+        if (status === "idle") this.statusCb({ status: "idle", reason: "provider-turn" });
+      }
     }
   }
+
+  private providerStateFromThreadStatus(status: unknown, params?: Record<string, unknown>): Record<string, unknown> | undefined {
+    const state = codexProviderStateFromThreadStatus(status, params);
+    if (state?.state !== "blocked" || state.reason !== "waitingOnApproval" || state.pendingApproval) return state;
+    const pending = [...this.pendingApprovals.values()].at(-1);
+    return pending ? { ...state, pendingApproval: pending.view } : state;
+  }
+}
+
+function codexApprovalFromServerRequest(message: { id: string | number; method: string; params?: unknown }): { pending: PendingCodexApproval; view: Record<string, unknown> } | null {
+  if (!isRecord(message.params)) return null;
+  const method = message.method;
+  if (!codexApprovalMethod(method)) return null;
+  const id = `${method}:${String(message.id)}`;
+  const view = codexApprovalView(id, method, message.params);
+  return {
+    pending: { id, requestId: message.id, method, params: message.params, view },
+    view,
+  };
+}
+
+function codexApprovalMethod(method: string): boolean {
+  return method === "execCommandApproval" ||
+    method === "applyPatchApproval" ||
+    method === "item/commandExecution/requestApproval" ||
+    method === "item/fileChange/requestApproval" ||
+    method === "item/permissions/requestApproval";
+}
+
+function codexApprovalView(id: string, method: string, params: Record<string, unknown>): Record<string, unknown> {
+  const command = typeof params.command === "string" ? params.command
+    : Array.isArray(params.command) ? params.command.filter((v): v is string => typeof v === "string").join(" ")
+    : "";
+  const cwd = stringValue(params.cwd) ?? stringValue(params.conversationId) ?? stringValue(params.threadId);
+  const reason = stringValue(params.reason);
+  const grantRoot = stringValue(params.grantRoot);
+  const fileChanges = isRecord(params.fileChanges) ? Object.keys(params.fileChanges) : [];
+  const permissions = isRecord(params.permissions) ? params.permissions : undefined;
+  const body = [
+    command,
+    grantRoot ? `Grant write access: ${grantRoot}` : "",
+    fileChanges.length ? `Files: ${fileChanges.join(", ")}` : "",
+    permissions ? `Permissions: ${JSON.stringify(permissions)}` : "",
+    reason ? `Reason: ${reason}` : "",
+    cwd ? `Context: ${cwd}` : "",
+  ].filter(Boolean).join("\n");
+  const isSessionCapable = method !== "item/permissions/requestApproval";
+  return {
+    id,
+    provider: "codex",
+    kind: method.includes("file") || method === "applyPatchApproval" ? "file-change" : method.includes("permission") ? "permission" : "command",
+    title: method.includes("file") || method === "applyPatchApproval"
+      ? "Approve file changes"
+      : method.includes("permission")
+        ? "Approve extra permissions"
+        : "Approve command",
+    body: body || "Codex is requesting permission.",
+    method,
+    choices: [
+      { id: "approve", label: method.includes("permission") ? "Allow this turn" : "Approve" },
+      ...(isSessionCapable ? [{ id: "approve-session", label: "Approve session" }] : [{ id: "approve-session", label: "Allow session" }]),
+      { id: "deny", label: "Deny" },
+    ],
+  };
+}
+
+function codexApprovalResponse(method: string, params: Record<string, unknown>, decision: ProviderPermissionDecisionInput["decision"]): Record<string, unknown> {
+  if (method === "item/commandExecution/requestApproval") {
+    return { decision: decision === "approve-session" ? "acceptForSession" : decision === "deny" ? "decline" : decision === "abort" ? "cancel" : "accept" };
+  }
+  if (method === "item/fileChange/requestApproval") {
+    return { decision: decision === "approve-session" ? "acceptForSession" : decision === "deny" ? "decline" : decision === "abort" ? "cancel" : "accept" };
+  }
+  if (method === "item/permissions/requestApproval") {
+    const permissions = decision === "deny" || decision === "abort" ? {} : isRecord(params.permissions) ? params.permissions : {};
+    return { permissions, scope: decision === "approve-session" ? "session" : "turn" };
+  }
+  return { decision: decision === "approve-session" ? "approved_for_session" : decision === "deny" ? "denied" : decision === "abort" ? "abort" : "approved" };
+}
+
+async function ensureCodexThread(process: ManagedProcess): Promise<string> {
+  const client = process.meta?.client as CodexAppClient | undefined;
+  if (!client) throw new Error("Codex App Server client is unavailable");
+  const threadId = typeof process.meta?.threadId === "string" ? process.meta.threadId : "";
+  if (threadId) return threadId;
+  // Memoize the in-flight start so concurrent deliveries don't create two threads
+  // and orphan the first turn's context.
+  const pending = process.meta?.threadStartPromise as Promise<string> | undefined;
+  if (pending) return pending;
+  const startPromise = client
+    .threadStart({ cwd: typeof process.meta?.cwd === "string" ? process.meta.cwd : globalThis.process.cwd() })
+    .then((started) => {
+      process.meta = { ...(process.meta ?? {}), threadId: started.thread.id, threadStartPromise: undefined };
+      return started.thread.id;
+    })
+    .catch((error) => {
+      if (process.meta) process.meta.threadStartPromise = undefined;
+      throw error;
+    });
+  process.meta = { ...(process.meta ?? {}), threadStartPromise: startPromise };
+  return startPromise;
+}
+
+export function codexDeliveryNotice(messages: Message[], threadId: string): string {
+  const ids = messages.map((message) => `#${message.id}`).join(", ");
+  const senders = [...new Set(messages.map((message) => message.from))].join(", ");
+  return `[agent-relay] received ${messages.length} relay message${messages.length === 1 ? "" : "s"} ${ids} from ${senders}; injecting into Codex thread ${threadId}`;
+}
+
+export function codexProviderStateFromThreadStatus(status: unknown, params?: Record<string, unknown>, now = Date.now()): Record<string, unknown> | undefined {
+  const type = statusType(status);
+  const flags = activeFlags(status);
+  const threadId = stringValue(params?.threadId) ?? (isRecord(params?.thread) ? stringValue(params.thread.id) : undefined);
+  const raw = { ...(threadId ? { threadId } : {}), status: isRecord(status) ? status : { type } };
+  const reason = flags[0] ?? type;
+
+  if (type === "active" && flags.some((flag) => flag.toLowerCase() === "waitingonapproval")) {
+    return {
+      state: "blocked",
+      reason: "waitingOnApproval",
+      label: "waiting for Codex approval",
+      recommendedAction: "Open the attached TUI to approve, or restart with non-interactive approval.",
+      source: "codex",
+      raw,
+      updatedAt: now,
+    };
+  }
+
+  if (type === "active" && flags.some((flag) => flag.toLowerCase().includes("auth"))) {
+    return {
+      state: "blocked",
+      reason: "authRequired",
+      label: "Codex authentication required",
+      recommendedAction: "Open the provider session and complete authentication, then retry.",
+      source: "codex",
+      raw,
+      updatedAt: now,
+    };
+  }
+
+  if (type === "systemError") {
+    return {
+      state: "blocked",
+      reason: "systemError",
+      label: "Codex system error",
+      recommendedAction: "View provider logs, then restart the provider if the error is not transient.",
+      source: "codex",
+      raw,
+      updatedAt: now,
+    };
+  }
+
+  if (type === "active") {
+    return {
+      state: "active",
+      reason,
+      label: flags.length ? `Codex active: ${flags.join(", ")}` : "Codex turn active",
+      source: "codex",
+      raw,
+      updatedAt: now,
+    };
+  }
+
+  return undefined;
+}
+
+export function codexTokenUsageContext(params: Record<string, unknown> | undefined, now = Date.now()): ContextState | undefined {
+  const usage = isRecord(params?.tokenUsage) ? params.tokenUsage
+    : isRecord(params?.token_usage) ? params.token_usage
+    : isRecord(params?.usage) ? params.usage
+    : isRecord(params?.info) ? params.info
+    : params;
+  if (!usage) return undefined;
+  const total = isRecord(usage.total) ? usage.total
+    : isRecord(usage.totalTokenUsage) ? usage.totalTokenUsage
+    : isRecord(usage.total_token_usage) ? usage.total_token_usage
+    : undefined;
+  const last = isRecord(usage.last) ? usage.last
+    : isRecord(usage.lastTokenUsage) ? usage.lastTokenUsage
+    : isRecord(usage.last_token_usage) ? usage.last_token_usage
+    : undefined;
+  const tokensUsed = numberValue(last?.totalTokens) ?? numberValue(last?.total_tokens) ??
+    numberValue(total?.totalTokens) ?? numberValue(total?.total_tokens) ??
+    numberValue(usage.totalTokens) ?? numberValue(usage.total_tokens);
+  const tokensMax = numberValue(usage.modelContextWindow) ?? numberValue(usage.model_context_window) ??
+    numberValue(params?.modelContextWindow) ?? numberValue(params?.model_context_window);
+  if (tokensUsed === undefined || tokensMax === undefined || tokensMax <= 0) return undefined;
+  return {
+    utilization: Math.max(0, Math.min(1, tokensUsed / tokensMax)),
+    tokensUsed,
+    tokensMax,
+    lifecycleState: "working",
+    warmTopics: [],
+    activeMemories: [],
+    tasksSinceCompact: 0,
+    lastUpdatedAt: now,
+    source: "api",
+    confidence: "reported",
+  };
+}
+
+function latestCodexContext(process: ManagedProcess): ContextState | undefined {
+  const meta = process.meta ?? {};
+  const current = isContextState(meta.context) ? meta.context : undefined;
+  const explicitPath = stringValue(meta.threadPath);
+  const threadId = stringValue(meta.threadId);
+  const rolloutPath = explicitPath ?? (threadId ? findCodexRolloutPath(threadId) : undefined);
+  if (!rolloutPath) return current;
+  const context = readCodexRolloutContext(rolloutPath);
+  if (!context) return current;
+  process.meta = { ...meta, context, threadPath: rolloutPath };
+  return context;
+}
+
+function readCodexRolloutContext(path: string): ContextState | undefined {
+  try {
+    return codexRolloutContextFromText(readFileSync(path, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+export function codexRolloutContextFromText(input: string): ContextState | undefined {
+  const lines = input.split(/\r?\n/);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]?.trim();
+    if (!line) continue;
+    let event: unknown;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!isRecord(event)) continue;
+    const payload = isRecord(event.payload) ? event.payload : undefined;
+    if (payload?.type !== "token_count") continue;
+    const timestamp = typeof event.timestamp === "string" ? Date.parse(event.timestamp) : Date.now();
+    return codexTokenUsageContext(payload, Number.isFinite(timestamp) ? timestamp : Date.now());
+  }
+  return undefined;
+}
+
+function findCodexRolloutPath(threadId: string): string | undefined {
+  const root = join(process.env.CODEX_HOME || join(homedir(), ".codex"), "sessions");
+  return findFileContaining(root, threadId);
+}
+
+function findFileContaining(dir: string, needle: string, depth = 0): string | undefined {
+  if (depth > 8) return undefined;
+  let entries: Array<{ name: string; isFile(): boolean; isDirectory(): boolean }>;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return undefined;
+  }
+  entries.sort((a, b) => b.name.localeCompare(a.name));
+  for (const entry of entries) {
+    const path = join(dir, entry.name);
+    if (entry.isFile() && entry.name.includes(needle) && entry.name.endsWith(".jsonl")) return path;
+    if (entry.isDirectory()) {
+      const found = findFileContaining(path, needle, depth + 1);
+      if (found) return found;
+    }
+  }
+  return undefined;
+}
+
+function isSubagentThread(thread: Record<string, unknown> | undefined, params: Record<string, unknown> | undefined): boolean {
+  if (thread?.threadSource === "subagent" || params?.threadSource === "subagent") return true;
+  const source = isRecord(thread?.sessionSource) ? thread.sessionSource : isRecord(params?.sessionSource) ? params.sessionSource : undefined;
+  return isRecord(source?.subagent);
+}
+
+function subagentThreadDetails(thread: Record<string, unknown> | undefined, params: Record<string, unknown> | undefined): { label?: string; role?: string; parentId?: string } {
+  const source = isRecord(thread?.sessionSource) ? thread.sessionSource : isRecord(params?.sessionSource) ? params.sessionSource : undefined;
+  const subagent = isRecord(source?.subagent) ? source.subagent : undefined;
+  const threadSpawn = isRecord(subagent?.thread_spawn) ? subagent.thread_spawn : undefined;
+  return {
+    label: stringValue(thread?.agentNickname) ?? stringValue(params?.agentNickname) ?? stringValue(threadSpawn?.agent_nickname),
+    role: stringValue(thread?.agentRole) ?? stringValue(params?.agentRole) ?? stringValue(threadSpawn?.agent_role),
+    parentId: stringValue(threadSpawn?.parent_thread_id) ?? stringValue(params?.parentThreadId),
+  };
+}
+
+function statusType(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  return isRecord(value) ? stringValue(value.type) : undefined;
+}
+
+function activeFlags(value: unknown): string[] {
+  if (!isRecord(value) || !Array.isArray(value.activeFlags)) return [];
+  return value.activeFlags.filter((flag): flag is string => typeof flag === "string" && flag.length > 0);
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value ? value : undefined;
+}
+
+function numberValue(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function isContextState(value: unknown): value is ContextState {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const state = value as Record<string, unknown>;
+  return typeof state.utilization === "number" &&
+    typeof state.lifecycleState === "string" &&
+    typeof state.source === "string" &&
+    typeof state.confidence === "string";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function codexModelConfigArgs(model?: string, effort?: string): string[] {
+  const args: string[] = [];
+  if (model) args.push("-c", `model=${tomlString(model)}`);
+  if (effort) args.push("-c", `model_reasoning_effort=${tomlString(effort)}`);
+  return args;
+}
+
+export function codexApprovalConfigArgs(approvalMode?: string): string[] {
+  const sandboxMode = approvalMode === "open"
+    ? "danger-full-access"
+    : approvalMode === "read-only"
+      ? "read-only"
+      : "workspace-write";
+  return [
+    "-c",
+    'approval_policy="never"',
+    "-c",
+    `sandbox_mode=${tomlString(sandboxMode)}`,
+  ];
+}
+
+export function codexManagedConfigArgs(): string[] {
+  return ["-c", "check_for_update_on_startup=false"];
 }
 
 export function isCodexCliCommand(command: string): boolean {
   return basename(command) === "codex";
 }
 
+export function resolveRealCodexCommand(command: string, pathValue = process.env.PATH || ""): string {
+  const candidates: string[] = [];
+  if (command.includes("/")) candidates.push(command);
+  for (const dir of pathValue.split(":").filter(Boolean)) candidates.push(join(dir, "codex"));
+
+  const seen = new Set<string>();
+  for (const candidate of candidates) {
+    if (seen.has(candidate)) continue;
+    seen.add(candidate);
+    if (!isExecutableFile(candidate)) continue;
+    const real = realPath(candidate);
+    if (isAgentRelayCodexShim(candidate) || isAgentRelayCodexShim(real)) continue;
+    return candidate;
+  }
+  return command;
+}
+
+function isExecutableFile(path: string): boolean {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function realPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+function isAgentRelayCodexShim(path: string): boolean {
+  return path.includes("/.agent-relay/codex/bin/codex");
+}
+
 export function bundledCodexSkillDirs(baseDir = resolve(import.meta.dir, "../../plugins/codex/skills")): string[] {
   if (!existsSync(baseDir)) return [];
   return readdirSync(baseDir, { withFileTypes: true })
@@ -142,6 +731,9 @@ function tomlString(value: string): string {
 }
 
 async function connectWithRetry(client: CodexAppClient, attempts = 40): Promise<void> {
+  // Give the freshly-spawned app-server a moment to bind its socket before the
+  // first attempt, so we don't spend the retry budget on guaranteed refusals.
+  await Bun.sleep(150);
   let lastError: unknown;
   for (let i = 0; i < attempts; i++) {
     try {
@@ -221,6 +813,23 @@ function killPid(pid: number, signal: "SIGTERM" | "SIGKILL"): void {
   } catch {}
 }
 
+function codexRelayContextEnabled(process: ManagedProcess): boolean {
+  const config = process.meta?.config as RunnerSpawnConfig | undefined;
+  return config ? profileAllowsRelayFeature(config, "context") : true;
+}
+
+function codexLaunchContext(process: ManagedProcess): string | undefined {
+  const config = process.meta?.config as RunnerSpawnConfig | undefined;
+  const text = config?.systemPromptAppend?.trim();
+  if (!text || process.meta?.systemPromptAppendSent) return undefined;
+  process.meta = { ...(process.meta ?? {}), systemPromptAppendSent: true };
+  return [
+    "[agent-relay launch context]",
+    "The following context was attached when this provider session was launched. Treat it as background context, not as a user request and not as your own prior actions.",
+    text,
+  ].join("\n");
+}
+
 function isPidAlive(pid: number): boolean {
   try {
     process.kill(pid, 0);