@northflare/runner 0.0.8 → 0.0.9

package/src/components/codex-sdk-manager.ts

@@ -0,0 +1,1248 @@
+import type { Thread, ThreadEvent, ThreadItem } from "@northflare/codex-sdk";
+import { IRunnerApp } from "../types/runner-interface";
+import { EnhancedRepositoryManager } from "./enhanced-repository-manager";
+import { ConversationContext, ConversationConfig, Message } from "../types";
+import { statusLineManager } from "../utils/status-line";
+import { console } from "../utils/console";
+import { expandEnv } from "../utils/expand-env";
+import { parseModelValue } from "../utils/model";
+import * as jwt from "jsonwebtoken";
+import fs from "fs/promises";
+import path from "path";
+
+let codexSdkPromise: Promise<typeof import("@northflare/codex-sdk")> | null =
+  null;
+// Use runtime dynamic import so the CommonJS build can load the ESM-only SDK.
+const dynamicImport = new Function(
+  "specifier",
+  "return import(specifier);"
+) as (specifier: string) => Promise<unknown>;
+
+async function loadCodexSdk() {
+  if (!codexSdkPromise) {
+    codexSdkPromise = dynamicImport("@northflare/codex-sdk") as Promise<
+      typeof import("@northflare/codex-sdk")
+    >;
+  }
+  return codexSdkPromise;
+}
+
+type CodexThreadState = {
+  thread: Thread;
+  abortController: AbortController | null;
+  runPromise: Promise<void> | null;
+};
+
+type ConversationDetails = {
+  id: string;
+  objectType: string;
+  objectId: string;
+  model: string;
+  globalInstructions: string;
+  workspaceInstructions: string;
+  permissionsMode: string;
+  agentSessionId?: string;
+  workspaceId?: string;
+  threadId?: string;
+};
+
+type NormalizedItemEvent = {
+  type: string;
+  content: any;
+  subtype?: string;
+  toolCalls?: any;
+  isError?: boolean;
+};
+
+export class CodexManager {
+  private runner: IRunnerApp;
+  private repositoryManager: EnhancedRepositoryManager;
+  private threadStates: Map<string, CodexThreadState> = new Map();
+
+  constructor(
+    runner: IRunnerApp,
+    repositoryManager: EnhancedRepositoryManager
+  ) {
+    this.runner = runner;
+    this.repositoryManager = repositoryManager;
+  }
+
+  async startConversation(
+    conversationObjectType: "Task" | "TaskPlan",
+    conversationObjectId: string,
+    config: ConversationConfig,
+    initialMessages: Message[],
+    conversationData?: ConversationDetails
+  ): Promise<ConversationContext> {
+    if (!conversationData?.id) {
+      throw new Error(
+        "startConversation requires conversationData with a valid conversation.id"
+      );
+    }
+
+    const conversationId = conversationData.id;
+    const agentSessionId = this.resolveSessionId(config, conversationData);
+
+    const rawModel =
+      conversationData?.model ||
+      (config as any)?.model ||
+      (config as any)?.defaultModel ||
+      "openai";
+    const { baseModel, reasoningEffort } = parseModelValue(rawModel);
+    const normalizedModel = baseModel || rawModel;
+
+    const metadata: Record<string, any> = {
+      instructionsInjected: false,
+      originalModelValue: rawModel,
+    };
+
+    if (reasoningEffort) {
+      metadata["modelReasoningEffort"] = reasoningEffort;
+    }
+
+    const context: ConversationContext = {
+      conversationId,
+      agentSessionId,
+      conversationObjectType,
+      conversationObjectId,
+      taskId:
+        conversationObjectType === "Task" ? conversationObjectId : undefined,
+      workspaceId: config.workspaceId,
+      status: "starting",
+      config,
+      startedAt: new Date(),
+      lastActivityAt: new Date(),
+      model: normalizedModel,
+      globalInstructions: conversationData.globalInstructions || "",
+      workspaceInstructions: conversationData.workspaceInstructions || "",
+      permissionsMode:
+        conversationData.permissionsMode ||
+        (config as any)?.permissionsMode ||
+        "all",
+      provider: "openai",
+      metadata,
+    };
+
+    this.runner.activeConversations_.set(conversationId, context);
+
+    console.log(`[CodexManager] Stored conversation context`, {
+      conversationId,
+      agentSessionId,
+      model: context.model,
+      permissionsMode: context.permissionsMode,
+    });
+
+    const workspacePath = await this.resolveWorkspacePath(context, config);
+
+    (context.metadata as Record<string, any>)["workspacePath"] = workspacePath;
+
+    const githubToken = context.workspaceId
+      ? await this.fetchGithubTokens(context.workspaceId)
+      : undefined;
+
+    const toolToken = this.generateToolToken(context);
+
+    let mcpServers: Record<string, any> | undefined;
+    if (config.mcpServers && Object.keys(config.mcpServers).length > 0) {
+      const expandedServers = expandEnv(config.mcpServers, {
+        TOOL_TOKEN: toolToken,
+      });
+      mcpServers = this.normalizeMcpServersForCodex(expandedServers);
+      console.log(
+        "[CodexManager] MCP servers configuration:",
+        JSON.stringify(mcpServers, null, 2)
+      );
+      (context.metadata as Record<string, any>)["mcpServers"] = mcpServers;
+    }
+
+    const configOverrides = this.buildConfigOverridesFromMcp(mcpServers);
+
+    const envVars = await this.buildEnvVars(config, githubToken, toolToken);
+
+    const { Codex } = await loadCodexSdk();
+    const codex = new Codex({
+      baseUrl:
+        (config as any)?.openaiBaseUrl ||
+        (config as any)?.codexBaseUrl ||
+        process.env["OPENAI_BASE_URL"],
+      apiKey:
+        (config as any)?.openaiApiKey ||
+        (config as any)?.codexApiKey ||
+        process.env["CODEX_API_KEY"] ||
+        process.env["OPENAI_API_KEY"],
+      env: envVars,
+    });
+
+    const threadOptions = {
+      model: context.model,
+      workingDirectory: workspacePath,
+      sandboxMode: this.mapSandboxMode(context.permissionsMode),
+      networkAccessEnabled: this.shouldEnableNetwork(context.permissionsMode),
+      webSearchEnabled: true,
+      // additionalDirectories: this.getAdditionalDirectories(config),
+      configOverrides,
+      skipGitRepoCheck: true,
+      modelReasoningEffort: reasoningEffort,
+    } as const;
+
+    console.log(
+      "[CodexManager] Thread options:",
+      JSON.stringify(threadOptions, null, 2)
+    );
+
+    const thread = agentSessionId
+      ? codex.resumeThread(agentSessionId, threadOptions)
+      : codex.startThread(threadOptions);
+
+    this.threadStates.set(conversationId, {
+      thread,
+      abortController: null,
+      runPromise: null,
+    });
+
+    context.conversation = thread;
+
+    // Send initial messages sequentially without waiting for completion
+    if (initialMessages?.length) {
+      for (const message of initialMessages) {
+        const text = this.normalizeToText(message.content);
+        const prompt = this.buildPromptForMessage(context, text, true);
+        this.launchTurn(context, prompt);
+      }
+    }
+
+    return context;
+  }
+
+  async stopConversation(
+    _agentSessionId: string,
+    context: ConversationContext,
+    isRunnerShutdown: boolean = false,
+    reason?: string
+  ): Promise<void> {
+    context.status = "stopping";
+
+    await this.abortActiveRun(context.conversationId);
+
+    try {
+      await this._finalizeConversation(
+        context,
+        false,
+        undefined,
+        reason || (isRunnerShutdown ? "runner_shutdown" : undefined)
+      );
+    } catch (error) {
+      console.error(
+        `[CodexManager] Error finalizing conversation ${context.conversationId}:`,
+        error
+      );
+    } finally {
+      this.threadStates.delete(context.conversationId);
+    }
+
+    context.status = "stopped";
+  }
+
+  async resumeConversation(
+    conversationObjectType: "Task" | "TaskPlan",
+    conversationObjectId: string,
+    agentSessionId: string,
+    config: ConversationConfig,
+    conversationData?: ConversationDetails,
+    resumeMessage?: string
+  ): Promise<string> {
+    console.log(`[CodexManager] Resuming conversation ${agentSessionId}`);
+
+    const context = await this.startConversation(
+      conversationObjectType,
+      conversationObjectId,
+      { ...config, sessionId: agentSessionId },
+      [],
+      conversationData
+    );
+
+    if (resumeMessage) {
+      const prompt = this.buildPromptForMessage(context, resumeMessage, false);
+      this.launchTurn(context, prompt);
+    }
+
+    return context.agentSessionId;
+  }
+
+  async sendUserMessage(
+    conversationId: string,
+    content: any,
+    config?: ConversationConfig,
+    conversationObjectType?: "Task" | "TaskPlan",
+    conversationObjectId?: string,
+    conversation?: any,
+    agentSessionIdOverride?: string
+  ): Promise<void> {
+    console.log(`[CodexManager] sendUserMessage called`, {
+      conversationId,
+      hasConfig: !!config,
+    });
+
+    let context = this.runner.getConversationContext(conversationId);
+
+    if (!context && conversation) {
+      const conversationDetails = conversation as ConversationDetails;
+      const resumeSessionId = this.resolveSessionId(
+        config,
+        conversationDetails,
+        agentSessionIdOverride
+      );
+      const startConfig: ConversationConfig = {
+        ...(config || {}),
+        workspaceId:
+          conversationDetails.workspaceId || config?.workspaceId || undefined,
+        ...(resumeSessionId ? { sessionId: resumeSessionId } : {}),
+      };
+
+      context = await this.startConversation(
+        (conversationObjectType as "Task" | "TaskPlan") ||
+          (conversationDetails.objectType as "Task" | "TaskPlan"),
+        conversationObjectId || conversationDetails.objectId,
+        startConfig,
+        [],
+        conversationDetails
+      );
+    }
+
+    if (!context) {
+      throw new Error(
+        `No active or fetchable conversation found for ${conversationId}`
+      );
+    }
+
+    await this.abortActiveRun(conversationId);
+
+    const messageText = this.normalizeToText(content);
+    const prompt = this.buildPromptForMessage(context, messageText, false);
+    this.launchTurn(context, prompt);
+
+    context.lastActivityAt = new Date();
+  }
+
+  private async buildEnvVars(
+    config: ConversationConfig,
+    githubToken?: string,
+    toolToken?: string
+  ): Promise<Record<string, string>> {
+    const envVars: Record<string, string> = {
+      ...(Object.fromEntries(
+        Object.entries(process.env).filter(([, value]) => value !== undefined)
+      ) as Record<string, string>),
+    };
+
+    if (config.codexAuth?.accessToken) {
+      envVars["OPENAI_ACCESS_TOKEN"] = config.codexAuth.accessToken;
+    } else if (config.accessToken) {
+      envVars["OPENAI_ACCESS_TOKEN"] = config.accessToken;
+    }
+
+    if (githubToken) {
+      envVars["GITHUB_TOKEN"] = githubToken;
+    }
+
+    if (toolToken) {
+      envVars["TOOL_TOKEN"] = toolToken;
+    }
+
+    if (process.env["DEBUG"] === "true") {
+      envVars["DEBUG"] = "1";
+    }
+
+    const codexHome = await this.ensureCodexAuthHome(config);
+    if (codexHome) {
+      envVars["CODEX_HOME"] = codexHome;
+    }
+
+    return envVars;
+  }
+
+  private async ensureCodexAuthHome(
+    config: ConversationConfig
+  ): Promise<string | null> {
+    if (!config.codexAuth) {
+      return null;
+    }
+
+    const runnerId = this.runner.getRunnerId();
+    const dataDir = this.runner.config_.dataDir;
+
+    if (!runnerId || !dataDir) {
+      console.warn(
+        "[CodexManager] Missing runnerId or dataDir; cannot prepare Codex auth directory"
+      );
+      return null;
+    }
+
+    const codexDir = path.join(dataDir, "codex", runnerId);
+    const authPayload = {
+      OPENAI_API_KEY: null,
+      tokens: {
+        id_token: config.codexAuth.idToken,
+        access_token: config.codexAuth.accessToken,
+        refresh_token: "",
+        account_id: config.codexAuth.accountId,
+      },
+      last_refresh: config.codexAuth.lastRefresh || new Date().toISOString(),
+    };
+
+    try {
+      await fs.mkdir(codexDir, { recursive: true });
+      await fs.writeFile(
+        path.join(codexDir, "auth.json"),
+        JSON.stringify(authPayload, null, 2),
+        "utf-8"
+      );
+      return codexDir;
+    } catch (error) {
+      console.error(
+        "[CodexManager] Failed to persist Codex auth configuration:",
+        error
+      );
+      throw new Error(
+        "Runner failed to persist Codex credentials. Check runner logs for details."
+      );
+    }
+  }
+
+  private buildPromptForMessage(
+    context: ConversationContext,
+    text: string,
+    forceInstructions: boolean
+  ): string {
+    const trimmed = text ?? "";
+    const instructions = this.getInstructionPrefix(context);
+
+    const metadata =
+      (context.metadata as Record<string, any>) || ({} as Record<string, any>);
+    const shouldInjectInstructions =
+      forceInstructions || !metadata["instructionsInjected"];
+
+    if (instructions && shouldInjectInstructions) {
+      metadata["instructionsInjected"] = true;
+      context.metadata = metadata;
+      return `${instructions}\n\n${trimmed}`.trim();
+    }
+
+    return trimmed;
+  }
+
+  private getInstructionPrefix(context: ConversationContext): string {
+    const parts: string[] = [];
+
+    if (context.globalInstructions) {
+      parts.push(
+        `<global-instructions>\n${context.globalInstructions}\n</global-instructions>`
+      );
+    }
+
+    if (context.workspaceInstructions) {
+      parts.push(
+        `<workspace-instructions>\n${context.workspaceInstructions}\n</workspace-instructions>`
+      );
+    }
+
+    return parts.join("\n\n");
+  }
+
+  private launchTurn(context: ConversationContext, prompt: string): void {
+    const state = this.threadStates.get(context.conversationId);
+
+    if (!state || !state.thread) {
+      throw new Error(
+        `Thread state missing for conversation ${context.conversationId}`
+      );
+    }
+
+    const abortController = new AbortController();
+    state.abortController = abortController;
+
+    context.lastActivityAt = new Date();
+
+    const runPromise = this.streamThreadEvents(
+      context,
+      state.thread,
+      prompt,
+      abortController
+    );
+
+    state.runPromise = runPromise;
+
+    runPromise
+      .catch((error) => {
+        if (!this.isAbortError(error)) {
+          console.error(
+            `[CodexManager] Run failed for ${context.conversationId}:`,
+            error
+          );
+          this._handleConversationError(context, error as Error);
+        }
+      })
+      .finally(() => {
+        if (state.runPromise === runPromise) {
+          state.runPromise = null;
+        }
+        if (state.abortController === abortController) {
+          state.abortController = null;
+        }
+      });
+  }
+
+  private async streamThreadEvents(
+    context: ConversationContext,
+    thread: Thread,
+    prompt: string,
+    abortController: AbortController
+  ): Promise<void> {
+    try {
+      const { events } = await thread.runStreamed(prompt, {
+        signal: abortController.signal,
+      });
+
+      for await (const event of events) {
+        await this.handleThreadEvent(context, event);
+      }
+    } catch (error) {
+      if (this.isAbortError(error)) {
+        console.log(
+          `[CodexManager] Turn aborted for ${context.conversationId}`
+        );
+        return;
+      }
+
+      throw error;
+    }
+  }
+
+  private async abortActiveRun(conversationId: string): Promise<void> {
+    const state = this.threadStates.get(conversationId);
+    if (!state || !state.runPromise) return;
+
+    if (state.abortController) {
+      state.abortController.abort();
+    }
+
+    try {
+      await state.runPromise;
+    } catch (error) {
+      if (!this.isAbortError(error)) {
+        console.warn(
+          `[CodexManager] Run aborted with error for ${conversationId}:`,
+          error
+        );
+      }
+    }
+  }
+
+  private async handleThreadEvent(
+    context: ConversationContext,
+    event: ThreadEvent
+  ): Promise<void> {
+    try {
+      switch (event.type) {
+        case "thread.started": {
+          await this.handleThreadStarted(context, event.thread_id);
+          break;
+        }
+        case "turn.started": {
+          context.status = "active";
+          await this.sendAgentMessage(context, "system", {
+            subtype: "turn.started",
+            content: [
+              {
+                type: "text",
+                text: `Turn started at ${new Date().toISOString()}`,
+              },
+            ],
+          });
+          break;
+        }
+        case "turn.completed": {
+          await this.sendAgentMessage(context, "result", {
+            subtype: "turn.completed",
+            content: [
+              {
+                type: "usage",
+                usage: event.usage,
+              },
+            ],
+          });
+          context.status = "stopped";
+          await this._finalizeConversation(context, false);
+          break;
+        }
+        case "turn.failed": {
+          const error = new Error(event.error?.message || "Turn failed");
+          await this.sendAgentMessage(context, "error", {
+            subtype: "turn.failed",
+            content: [
+              {
+                type: "text",
+                text: error.message,
+              },
+            ],
+            isError: true,
+          });
+          await this._handleConversationError(context, error);
+          context.status = "stopped";
+          await this._finalizeConversation(context, true, error, "turn_failed");
+          break;
+        }
+        case "item.started":
+        case "item.updated":
+        case "item.completed": {
+          await this.forwardItemEvent(
+            context,
+            event.item,
+            event.type.split(".")[1] as "started" | "updated" | "completed"
+          );
+          break;
+        }
+        case "error": {
+          const fatalError = new Error(event.message || "Unknown error");
+          await this.sendAgentMessage(context, "error", {
+            subtype: "thread.error",
+            content: [{ type: "text", text: fatalError.message }],
+            isError: true,
+          });
+          await this._handleConversationError(context, fatalError);
+          context.status = "stopped";
+          await this._finalizeConversation(
+            context,
+            true,
+            fatalError,
+            "thread_error"
+          );
+          break;
+        }
+      }
+    } catch (error) {
+      console.error("[CodexManager] Failed to handle thread event", {
+        event,
+        error,
+      });
+    }
+  }
+
+  private async forwardItemEvent(
+    context: ConversationContext,
+    item: ThreadItem,
+    phase: "started" | "updated" | "completed"
+  ): Promise<void> {
+    const normalized = this.normalizeItemEvent(context, item, phase);
+    if (!normalized) return;
+
+    const { subtype, content, isError, toolCalls, type } = normalized;
+    const payload: {
+      subtype?: string;
+      content: any;
+      toolCalls?: any;
+      isError?: boolean;
+    } = {
+      subtype,
+      content,
+      isError,
+    };
+
+    if (toolCalls) {
+      payload.toolCalls = toolCalls;
+    }
+
+    await this.sendAgentMessage(context, type, payload);
+  }
+
+  private normalizeItemEvent(
+    context: ConversationContext,
+    item: ThreadItem,
+    phase: "started" | "updated" | "completed"
+  ): NormalizedItemEvent | null {
+    switch (item.type) {
+      case "agent_message": {
+        if (phase !== "completed") return null;
+        return {
+          type: "assistant",
+          content: [
+            {
+              type: "text",
+              text: item.text || "",
+            },
+          ],
+        };
+      }
+      case "reasoning": {
+        return {
+          type: "thinking",
+          content: [
+            {
+              type: "thinking",
+              thinking: item.text,
+              text: item.text,
+              phase,
+            },
+          ],
+        };
+      }
+      case "command_execution": {
+        return {
+          type: "system",
+          subtype: `command_execution.${phase}`,
+          content: [
+            {
+              type: "command_execution",
+              command: item.command,
+              aggregated_output: item.aggregated_output,
+              exit_code: item.exit_code,
+              status: item.status,
+              phase,
+            },
+          ],
+        };
+      }
+      case "file_change": {
+        if (phase === "updated") return null;
+        return {
+          type: "system",
+          subtype: "file_change",
+          content: [
+            {
+              type: "file_change",
+              changes: item.changes,
+              status: item.status,
+            },
+          ],
+        };
+      }
+      case "mcp_tool_call": {
+        const toolName = this.buildMcpToolName(item.server, item.tool);
+        const toolUseId = this.buildToolUseId(context, item.id);
+
+        if (item.status === "in_progress" || phase !== "completed") {
+          return {
+            type: "assistant",
+            subtype: "tool_use",
+            content: [
+              {
+                toolCalls: [
+                  {
+                    id: toolUseId,
+                    name: toolName,
+                    arguments: item.arguments,
+                    server: item.server,
+                    tool: item.tool,
+                    status: item.status,
+                  },
+                ],
+                timestamp: new Date().toISOString(),
+              },
+            ],
+          };
+        }
+
+        if (item.status === "failed") {
+          return {
+            type: "error",
+            subtype: "tool_result",
+            content: [
+              {
+                type: "text",
+                text: item.error?.message || "Tool call failed",
+                tool_use_id: toolUseId,
+                tool_name: toolName,
+                timestamp: new Date().toISOString(),
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        return {
+          type: "tool_result",
+          subtype: "tool_result",
+          content: [
+            {
+              type: "tool_result",
+              subtype: "tool_result",
+              tool_use_id: toolUseId,
+              content: item.result?.content || [],
+              structured_content: item.result?.structured_content,
+              metadata: {
+                server: item.server,
+                tool: item.tool,
+                name: toolName,
+                original_tool_use_id: item.id,
+              },
+              timestamp: new Date().toISOString(),
+            },
+          ],
+        };
+      }
+      case "web_search": {
+        return {
+          type: "system",
+          subtype: `web_search.${phase}`,
+          content: [
+            {
+              type: "web_search",
+              query: item.query,
+              status: phase,
+            },
+          ],
+        };
+      }
+      case "todo_list": {
+        return {
+          type: "system",
+          subtype: "todo_list",
+          content: [
+            {
+              type: "todo_list",
+              items: item.items,
+              phase,
+            },
+          ],
+        };
+      }
+      case "error": {
+        return {
+          type: "error",
+          subtype: `item.${phase}`,
+          content: [
+            {
+              type: "text",
+              text: item.message,
+            },
+          ],
+          isError: true,
+        };
+      }
+      default:
+        return null;
+    }
+  }
+
+  private async sendAgentMessage(
+    context: ConversationContext,
+    type: string,
+    {
+      subtype,
+      content,
+      toolCalls,
+      isError,
+    }: {
+      subtype?: string;
+      content: any;
+      toolCalls?: any;
+      isError?: boolean;
+    }
+  ): Promise<void> {
+    const normalizedContent = Array.isArray(content)
+      ? content
+      : content
+        ? [content]
+        : [];
+
+    const payload = {
+      taskId: context.taskId,
+      conversationId: context.conversationId,
+      conversationObjectType: context.conversationObjectType,
+      conversationObjectId: context.conversationObjectId,
+      agentSessionId: context.agentSessionId,
+      type,
+      subtype,
+      content: normalizedContent,
+      toolCalls,
+      isError: Boolean(isError),
+      messageId: this.generateMessageId(context),
+      timestamp: new Date().toISOString(),
+    };
+
+    if (process.env["DEBUG"] === "true") {
+      console.log("[CodexManager] Sending message.agent", payload);
+    }
+
+    await this.runner.notify("message.agent", payload);
+  }
+
+  private async handleThreadStarted(
+    context: ConversationContext,
+    threadId: string
+  ): Promise<void> {
+    if (!threadId || threadId === context.agentSessionId) {
+      return;
+    }
+
+    const oldSessionId = context.agentSessionId;
+    context.agentSessionId = threadId;
+
+    await this.runner.notify("agentSessionId.changed", {
+      conversationId: context.conversationId,
+      conversationObjectType: context.conversationObjectType,
+      conversationObjectId: context.conversationObjectId,
+      oldAgentSessionId: oldSessionId,
+      newAgentSessionId: threadId,
+    });
+  }
+
+  private mapSandboxMode(
+    permissionsMode?: string
+  ): "read-only" | "workspace-write" | "danger-full-access" {
+    const mode = (permissionsMode || "").toLowerCase();
+    if (mode === "read" || mode === "read_only") {
+      return "read-only";
+    }
+    if (mode === "workspace" || mode === "workspace-write") {
+      return "workspace-write";
+    }
+    return "danger-full-access";
+  }
+
+  private shouldEnableNetwork(permissionsMode?: string): boolean {
+    const mode = (permissionsMode || "").toLowerCase();
+    return mode !== "read" && mode !== "read_only";
+  }
+
+  private getAdditionalDirectories(
+    config: ConversationConfig
+  ): string[] | undefined {
+    const additionalDirs: string[] = [];
+    if (config.runnerRepoPath) {
+      additionalDirs.push(config.runnerRepoPath);
+    }
+    return additionalDirs.length ? additionalDirs : undefined;
+  }
+
+  private buildConfigOverridesFromMcp(
+    mcpServers?: Record<string, any>
+  ): Record<string, unknown> | undefined {
+    if (!mcpServers) return undefined;
+    const overrides: Record<string, unknown> = {};
+
+    for (const [serverName, config] of Object.entries(mcpServers)) {
+      this.flattenOverrideObject(
+        `mcp_servers.${serverName}`,
+        config,
+        overrides
+      );
+    }
+
+    return Object.keys(overrides).length ? overrides : undefined;
+  }
+
+  private normalizeMcpServersForCodex(
+    mcpServers: Record<string, any>
+  ): Record<string, any> {
+    const normalized: Record<string, any> = {};
+    for (const [serverName, config] of Object.entries(mcpServers)) {
+      normalized[serverName] = this.stripAuthorizationHeader(config);
+    }
+    return normalized;
+  }
+
+  private buildMcpToolName(server?: string, tool?: string): string {
+    const safeServer = (server || "unknown").trim() || "unknown";
+    const safeTool = (tool || "unknown").trim() || "unknown";
+    return `mcp__${safeServer}__${safeTool}`;
+  }
+
+  private buildToolUseId(context: ConversationContext, rawId: string): string {
+    const scope =
+      context.agentSessionId ||
+      context.conversationId ||
+      context.conversationObjectId ||
+      "codex";
+    return `${scope}:${rawId}`;
+  }
+
+  private stripAuthorizationHeader(config: any): any {
+    if (!config || typeof config !== "object" || Array.isArray(config)) {
+      return config;
+    }
+
+    const normalized = { ...config };
+    if (
+      normalized.bearer_token_env_var &&
+      normalized.headers &&
+      typeof normalized.headers === "object" &&
+      !Array.isArray(normalized.headers)
+    ) {
+      const headers = { ...normalized.headers };
+      delete headers["Authorization"];
+      if (Object.keys(headers).length === 0) {
+        delete normalized.headers;
+      } else {
+        normalized.headers = headers;
+      }
+    }
+
+    return normalized;
+  }
+
+  private flattenOverrideObject(
+    prefix: string,
+    value: any,
+    target: Record<string, unknown>
+  ): void {
+    if (value === undefined) {
+      return;
+    }
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      target[prefix] = value;
+      return;
+    }
+
+    const entries = Object.entries(value);
+    if (!entries.length) {
+      target[prefix] = {};
+      return;
+    }
+
+    for (const [key, nested] of entries) {
+      this.flattenOverrideObject(`${prefix}.${key}`, nested, target);
+    }
+  }
+
+  private async resolveWorkspacePath(
+    context: ConversationContext,
+    config: ConversationConfig
+  ): Promise<string> {
+    let workspacePath: string;
+    const workspaceId = config.workspaceId;
+
+    if (config.runnerRepoPath) {
+      workspacePath = config.runnerRepoPath;
+      console.log(`[CodexManager] Using local workspace path ${workspacePath}`);
+
+      if (context.conversationObjectType === "Task") {
+        const taskHandle = await this.repositoryManager.createLocalTaskHandle(
+          context.conversationObjectId,
+          workspacePath
+        );
+        (context as any).taskHandle = taskHandle;
+      }
+      return workspacePath;
+    }
+
+    if (
+      context.conversationObjectType === "Task" &&
+      config.repository &&
+      workspaceId
+    ) {
+      if (!config.repository.url) {
+        throw new Error("Repository URL is required for task conversations");
+      }
+
+      const taskHandle = await this.repositoryManager.createTaskWorktree(
+        context.conversationObjectId,
+        workspaceId,
+        config.repository.url,
+        config.repository.branch,
+        config.githubToken
+      );
+      (context as any).taskHandle = taskHandle;
+      workspacePath = taskHandle.worktreePath;
+      return workspacePath;
+    }
+
+    if (config.repository && workspaceId) {
+      if (config.repository.type === "local" && config.repository.localPath) {
+        workspacePath = config.repository.localPath;
+        return workspacePath;
+      }
+
+      workspacePath = await this.repositoryManager.checkoutRepository(
+        workspaceId,
+        config.repository.url,
+        config.repository.branch,
+        config.githubToken
+      );
+      return workspacePath;
+    }
+
+    if (workspaceId) {
+      workspacePath =
+        await this.repositoryManager.getWorkspacePath(workspaceId);
+      return workspacePath;
+    }
+
+    return process.cwd();
+  }
+
+  private async fetchGithubTokens(
+    workspaceId: string
+  ): Promise<string | undefined> {
+    try {
+      const response = await fetch(
+        `${this.runner.config_.orchestratorUrl}/api/runner/tokens?workspaceId=${workspaceId}`,
+        {
+          method: "GET",
+          headers: {
+            Authorization: `Bearer ${process.env["NORTHFLARE_RUNNER_TOKEN"]}`,
+          },
+        }
+      );
+
+      if (!response.ok) {
+        console.error(
+          `[CodexManager] Failed to fetch GitHub tokens: ${response.status}`
+        );
+        return undefined;
+      }
+
+      const data = (await response.json()) as { githubToken?: string };
+      return data.githubToken;
+    } catch (error) {
+      console.error("[CodexManager] Error fetching GitHub tokens", error);
+      return undefined;
+    }
+  }
+
+  private generateToolToken(context: ConversationContext): string | undefined {
+    if (!context.config.mcpServers) return undefined;
+
+    const runnerToken = process.env["NORTHFLARE_RUNNER_TOKEN"];
+    const runnerUid = this.runner.getRunnerUid();
+
+    if (!runnerToken || !runnerUid) return undefined;
+
+    return jwt.sign(
+      {
+        conversationId: context.conversationId,
+        runnerUid,
+      },
+      runnerToken,
+      {
+        expiresIn: "60m",
+      }
+    );
+  }
+
+  private normalizeToText(value: any): string {
+    if (typeof value === "string") return value;
+    if (value == null) return "";
+
+    if (typeof value === "object") {
+      if (typeof (value as any).text === "string") {
+        return (value as any).text;
+      }
+      if (Array.isArray(value)) {
+        const texts = value
+          .map((entry) => {
+            if (
+              entry &&
+              typeof entry === "object" &&
+              typeof entry.text === "string"
+            ) {
+              return entry.text;
+            }
+            return null;
+          })
+          .filter((entry): entry is string => Boolean(entry));
+        if (texts.length) {
+          return texts.join(" ");
+        }
+      }
+      if (typeof (value as any).content === "string") {
+        return (value as any).content;
+      }
+    }
+
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return String(value);
+    }
+  }
+
+  private normalizeSessionId(value?: string | null): string | undefined {
+    if (!value) return undefined;
+    const trimmed = value.trim();
+    return trimmed.length ? trimmed : undefined;
+  }
+
+  private resolveSessionId(
+    config?: ConversationConfig,
+    conversationData?: ConversationDetails,
+    override?: string | null
+  ): string {
+    return (
+      this.normalizeSessionId(override) ||
+      this.normalizeSessionId(config?.sessionId) ||
+      this.normalizeSessionId(conversationData?.agentSessionId) ||
+      this.normalizeSessionId((conversationData as any)?.threadId) ||
+      this.normalizeSessionId((conversationData as any)?.sessionId) ||
+      ""
+    );
+  }
+
+  private isAbortError(error: unknown): boolean {
+    if (!error) return false;
+    return (
+      (error as any).name === "AbortError" ||
+      /aborted|abort/i.test((error as any).message || "")
+    );
+  }
+
+  private async _finalizeConversation(
+    context: ConversationContext,
+    hadError: boolean,
+    error?: any,
+    reason?: string
+  ): Promise<void> {
+    if ((context as any)._finalized) return;
+    (context as any)._finalized = true;
+
+    try {
+      await this.runner.notify("conversation.end", {
+        conversationId: context.conversationId,
+        conversationObjectType: context.conversationObjectType,
+        conversationObjectId: context.conversationObjectId,
+        agentSessionId: context.agentSessionId,
+        isError: hadError,
+        errorMessage: error?.message,
+        reason,
+      });
+    } catch (notifyError) {
+      console.error(
+        "[CodexManager] Failed to send conversation.end notification",
+        notifyError
+      );
+    }
+
+    this.threadStates.delete(context.conversationId);
+    this.runner.activeConversations_.delete(context.conversationId);
+    statusLineManager.updateActiveCount(this.runner.activeConversations_.size);
+  }
+
+  private async _handleConversationError(
+    context: ConversationContext,
+    error: Error
+  ): Promise<void> {
+    console.error(
+      `[CodexManager] Conversation error for ${context.conversationId}:`,
+      error
+    );
+
+    await this.runner.notify("error.report", {
+      conversationId: context.conversationId,
+      conversationObjectType: context.conversationObjectType,
+      conversationObjectId: context.conversationObjectId,
+      agentSessionId: context.agentSessionId,
+      errorType: "codex_error",
+      message: error.message,
+      details: {
+        stack: error.stack,
+        timestamp: new Date(),
+      },
+    });
+  }
+
+  private generateMessageId(context: ConversationContext): string {
+    return `${context.agentSessionId}-${Date.now()}-${Math.random()
+      .toString(36)
+      .slice(2)}`;
+  }
+}