@northflare/runner 0.0.8 → 0.0.9

package/lib/codex-sdk/src/exec.ts

@@ -0,0 +1,336 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+
+import { SandboxMode, ModelReasoningEffort, ApprovalMode } from "./threadOptions";
+
+export type CodexExecArgs = {
+  input: string;
+
+  baseUrl?: string;
+  apiKey?: string;
+  threadId?: string | null;
+  images?: string[];
+  // --model
+  model?: string;
+  // --sandbox
+  sandboxMode?: SandboxMode;
+  // --cd
+  workingDirectory?: string;
+  // --add-dir
+  additionalDirectories?: string[];
+  // --skip-git-repo-check
+  skipGitRepoCheck?: boolean;
+  // --output-schema
+  outputSchemaFile?: string;
+  // --config model_reasoning_effort
+  modelReasoningEffort?: ModelReasoningEffort;
+  // AbortSignal to cancel the execution
+  signal?: AbortSignal;
+  // --config sandbox_workspace_write.network_access
+  networkAccessEnabled?: boolean;
+  // --config features.web_search_request
+  webSearchEnabled?: boolean;
+  // --config approval_policy
+  approvalPolicy?: ApprovalMode;
+  // Generic config overrides for `-c key=value`
+  configOverrides?: Record<string, unknown>;
+};
+
+const INTERNAL_ORIGINATOR_ENV = "CODEX_INTERNAL_ORIGINATOR_OVERRIDE";
+const TYPESCRIPT_SDK_ORIGINATOR = "codex_sdk_ts";
+const isDebugEnabled = process.env["DEBUG"] === "true";
+
+export class CodexExec {
+  private executablePath: string;
+  private envOverride?: Record<string, string>;
+
+  constructor(executablePath: string | null = null, env?: Record<string, string>) {
+    this.executablePath = executablePath || findCodexPath();
+    this.envOverride = env;
+  }
+
+  async *run(args: CodexExecArgs): AsyncGenerator<string> {
+    const commandArgs: string[] = ["exec", "--experimental-json"];
+
+    if (args.model) {
+      commandArgs.push("--model", args.model);
+    }
+
+    if (args.sandboxMode) {
+      commandArgs.push("--sandbox", args.sandboxMode);
+    }
+
+    if (args.workingDirectory) {
+      commandArgs.push("--cd", args.workingDirectory);
+    }
+
+    if (args.additionalDirectories?.length) {
+      for (const dir of args.additionalDirectories) {
+        commandArgs.push("--add-dir", dir);
+      }
+    }
+
+    if (args.skipGitRepoCheck) {
+      commandArgs.push("--skip-git-repo-check");
+    }
+
+    if (args.outputSchemaFile) {
+      commandArgs.push("--output-schema", args.outputSchemaFile);
+    }
+
+    if (args.modelReasoningEffort) {
+      commandArgs.push("--config", `model_reasoning_effort="${args.modelReasoningEffort}"`);
+    }
+
+    if (args.networkAccessEnabled !== undefined) {
+      commandArgs.push(
+        "--config",
+        `sandbox_workspace_write.network_access=${args.networkAccessEnabled}`,
+      );
+    }
+
+    if (args.webSearchEnabled !== undefined) {
+      commandArgs.push("--config", `features.web_search_request=${args.webSearchEnabled}`);
+    }
+
+    if (args.approvalPolicy) {
+      commandArgs.push("--config", `approval_policy="${args.approvalPolicy}"`);
+    }
+
+    if (args.configOverrides) {
+      for (const [key, value] of Object.entries(args.configOverrides)) {
+        const formatted = formatConfigValue(value);
+        commandArgs.push("--config", `${key}=${formatted}`);
+      }
+    }
+
+    if (args.images?.length) {
+      for (const image of args.images) {
+        commandArgs.push("--image", image);
+      }
+    }
+
+    if (args.threadId) {
+      commandArgs.push("resume", args.threadId);
+    }
+
+    if (isDebugEnabled) {
+      console.log("[CodexExec] Executable path:", this.executablePath);
+      console.log("[CodexExec] Command arguments:", commandArgs);
+    }
+
+    const env: Record<string, string> = {};
+    if (this.envOverride) {
+      Object.assign(env, this.envOverride);
+    } else {
+      for (const [key, value] of Object.entries(process.env)) {
+        if (value !== undefined) {
+          env[key] = value;
+        }
+      }
+    }
+    if (!env[INTERNAL_ORIGINATOR_ENV]) {
+      env[INTERNAL_ORIGINATOR_ENV] = TYPESCRIPT_SDK_ORIGINATOR;
+    }
+    if (args.baseUrl) {
+      env.OPENAI_BASE_URL = args.baseUrl;
+    }
+    if (args.apiKey) {
+      env.CODEX_API_KEY = args.apiKey;
+    }
+
+    const child = spawn(this.executablePath, commandArgs, {
+      env,
+      signal: args.signal,
+    });
+
+    let spawnError: unknown | null = null;
+    child.once("error", (err) => (spawnError = err));
+
+    if (!child.stdin) {
+      child.kill();
+      throw new Error("Child process has no stdin");
+    }
+    child.stdin.write(args.input);
+    child.stdin.end();
+
+    if (!child.stdout) {
+      child.kill();
+      throw new Error("Child process has no stdout");
+    }
+    const stderrChunks: Buffer[] = [];
+
+    if (child.stderr) {
+      child.stderr.on("data", (data) => {
+        stderrChunks.push(data);
+      });
+    }
+
+    const rl = readline.createInterface({
+      input: child.stdout,
+      crlfDelay: Infinity,
+    });
+
+    try {
+      for await (const line of rl) {
+        // `line` is a string (Node sets default encoding to utf8 for readline)
+        yield line as string;
+      }
+
+      const exitCode = new Promise((resolve, reject) => {
+        child.once("exit", (code) => {
+          if (code === 0) {
+            resolve(code);
+          } else {
+            const stderrBuffer = Buffer.concat(stderrChunks);
+            reject(
+              new Error(`Codex Exec exited with code ${code}: ${stderrBuffer.toString("utf8")}`),
+            );
+          }
+        });
+      });
+
+      if (spawnError) throw spawnError;
+      await exitCode;
+    } finally {
+      rl.close();
+      child.removeAllListeners();
+      try {
+        if (!child.killed) child.kill();
+      } catch {
+        // ignore
+      }
+    }
+  }
+}
+
+const scriptFileName = fileURLToPath(import.meta.url);
+const scriptDirName = path.dirname(scriptFileName);
+const require = createRequire(import.meta.url);
+
+function findCodexPath() {
+  const { platform, arch } = process;
+
+  let targetTriple = null;
+  switch (platform) {
+    case "linux":
+    case "android":
+      switch (arch) {
+        case "x64":
+          targetTriple = "x86_64-unknown-linux-musl";
+          break;
+        case "arm64":
+          targetTriple = "aarch64-unknown-linux-musl";
+          break;
+        default:
+          break;
+      }
+      break;
+    case "darwin":
+      switch (arch) {
+        case "x64":
+          targetTriple = "x86_64-apple-darwin";
+          break;
+        case "arm64":
+          targetTriple = "aarch64-apple-darwin";
+          break;
+        default:
+          break;
+      }
+      break;
+    case "win32":
+      switch (arch) {
+        case "x64":
+          targetTriple = "x86_64-pc-windows-msvc";
+          break;
+        case "arm64":
+          targetTriple = "aarch64-pc-windows-msvc";
+          break;
+        default:
+          break;
+      }
+      break;
+    default:
+      break;
+  }
+
+  if (!targetTriple) {
+    throw new Error(`Unsupported platform: ${platform} (${arch})`);
+  }
+
+  const vendorResolution = resolveUpstreamVendorRoot();
+  let vendorRoot: string;
+  if (vendorResolution.path) {
+    vendorRoot = vendorResolution.path;
+  } else {
+    vendorRoot = path.join(scriptDirName, "..", "vendor");
+    const reason = vendorResolution.reason ? `: ${vendorResolution.reason}` : "";
+    console.warn(
+      `[Codex SDK] Failed to resolve upstream vendor package${reason}, falling back to local vendor directory`,
+    );
+  }
+  const archRoot = path.join(vendorRoot, targetTriple);
+  const codexBinaryName = process.platform === "win32" ? "codex.exe" : "codex";
+  const binaryPath = path.join(archRoot, "codex", codexBinaryName);
+
+  return binaryPath;
+}
+
+function resolveUpstreamVendorRoot(): { path: string | null; reason?: string } {
+  let searchPaths: string[] | null = null;
+  try {
+    searchPaths = require.resolve.paths("@openai/codex-sdk");
+  } catch (error) {
+    return { path: null, reason: (error as Error)?.message || String(error) };
+  }
+
+  if (!searchPaths?.length) {
+    return { path: null, reason: "no module search paths returned" };
+  }
+
+  let locatedPackageRoot: string | null = null;
+  for (const basePath of searchPaths) {
+    if (!basePath) continue;
+    const packageRoot = path.join(basePath, "@openai/codex-sdk");
+    const packageJsonPath = path.join(packageRoot, "package.json");
+    if (!existsSync(packageJsonPath)) {
+      continue;
+    }
+
+    locatedPackageRoot = packageRoot;
+    const vendorPath = path.join(packageRoot, "vendor");
+    if (existsSync(vendorPath)) {
+      return { path: vendorPath };
+    }
+  }
+
+  if (locatedPackageRoot) {
+    return { path: null, reason: `vendor directory missing in ${locatedPackageRoot}` };
+  }
+
+  return {
+    path: null,
+    reason: `@openai/codex-sdk not found in node_modules search paths (${searchPaths.join(", ")})`,
+  };
+}
+
+function formatConfigValue(value: unknown): string {
+  if (typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (value === null || value === undefined) {
+    return "null";
+  }
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return JSON.stringify(String(value));
+  }
+}

package/lib/codex-sdk/src/index.ts

@@ -0,0 +1,39 @@
+export type {
+  ThreadEvent,
+  ThreadStartedEvent,
+  TurnStartedEvent,
+  TurnCompletedEvent,
+  TurnFailedEvent,
+  ItemStartedEvent,
+  ItemUpdatedEvent,
+  ItemCompletedEvent,
+  ThreadError,
+  ThreadErrorEvent,
+  Usage,
+} from "./events";
+export type {
+  ThreadItem,
+  AgentMessageItem,
+  ReasoningItem,
+  CommandExecutionItem,
+  FileChangeItem,
+  McpToolCallItem,
+  WebSearchItem,
+  TodoListItem,
+  ErrorItem,
+} from "./items";
+
+export { Thread } from "./thread";
+export type { RunResult, RunStreamedResult, Input, UserInput } from "./thread";
+
+export { Codex } from "./codex";
+
+export type { CodexOptions } from "./codexOptions";
+
+export type {
+  ThreadOptions,
+  ApprovalMode,
+  SandboxMode,
+  ModelReasoningEffort,
+} from "./threadOptions";
+export type { TurnOptions } from "./turnOptions";

package/lib/codex-sdk/src/items.ts

@@ -0,0 +1,127 @@
+// based on item types from codex-rs/exec/src/exec_events.rs
+
+import type { ContentBlock as McpContentBlock } from "@modelcontextprotocol/sdk/types.js";
+
+/** The status of a command execution. */
+export type CommandExecutionStatus = "in_progress" | "completed" | "failed";
+
+/** A command executed by the agent. */
+export type CommandExecutionItem = {
+  id: string;
+  type: "command_execution";
+  /** The command line executed by the agent. */
+  command: string;
+  /** Aggregated stdout and stderr captured while the command was running. */
+  aggregated_output: string;
+  /** Set when the command exits; omitted while still running. */
+  exit_code?: number;
+  /** Current status of the command execution. */
+  status: CommandExecutionStatus;
+};
+
+/** Indicates the type of the file change. */
+export type PatchChangeKind = "add" | "delete" | "update";
+
+/** A set of file changes by the agent. */
+export type FileUpdateChange = {
+  path: string;
+  kind: PatchChangeKind;
+};
+
+/** The status of a file change. */
+export type PatchApplyStatus = "completed" | "failed";
+
+/** A set of file changes by the agent. Emitted once the patch succeeds or fails. */
+export type FileChangeItem = {
+  id: string;
+  type: "file_change";
+  /** Individual file changes that comprise the patch. */
+  changes: FileUpdateChange[];
+  /** Whether the patch ultimately succeeded or failed. */
+  status: PatchApplyStatus;
+};
+
+/** The status of an MCP tool call. */
+export type McpToolCallStatus = "in_progress" | "completed" | "failed";
+
+/**
+ * Represents a call to an MCP tool. The item starts when the invocation is dispatched
+ * and completes when the MCP server reports success or failure.
+ */
+export type McpToolCallItem = {
+  id: string;
+  type: "mcp_tool_call";
+  /** Name of the MCP server handling the request. */
+  server: string;
+  /** The tool invoked on the MCP server. */
+  tool: string;
+  /** Arguments forwarded to the tool invocation. */
+  arguments: unknown;
+  /** Result payload returned by the MCP server for successful calls. */
+  result?: {
+    content: McpContentBlock[];
+    structured_content: unknown;
+  };
+  /** Error message reported for failed calls. */
+  error?: {
+    message: string;
+  };
+  /** Current status of the tool invocation. */
+  status: McpToolCallStatus;
+};
+
+/** Response from the agent. Either natural-language text or JSON when structured output is requested. */
+export type AgentMessageItem = {
+  id: string;
+  type: "agent_message";
+  /** Either natural-language text or JSON when structured output is requested. */
+  text: string;
+};
+
+/** Agent's reasoning summary. */
+export type ReasoningItem = {
+  id: string;
+  type: "reasoning";
+  text: string;
+};
+
+/** Captures a web search request. Completes when results are returned to the agent. */
+export type WebSearchItem = {
+  id: string;
+  type: "web_search";
+  query: string;
+};
+
+/** Describes a non-fatal error surfaced as an item. */
+export type ErrorItem = {
+  id: string;
+  type: "error";
+  message: string;
+};
+
+/** An item in the agent's to-do list. */
+export type TodoItem = {
+  text: string;
+  completed: boolean;
+};
+
+/**
+ * Tracks the agent's running to-do list. Starts when the plan is issued, updates as steps change,
+ * and completes when the turn ends.
+ */
+export type TodoListItem = {
+  id: string;
+  type: "todo_list";
+  items: TodoItem[];
+};
+
+/** Canonical union of thread items and their type-specific payloads. */
+export type ThreadItem =
+  | AgentMessageItem
+  | ReasoningItem
+  | CommandExecutionItem
+  | FileChangeItem
+  | McpToolCallItem
+  | WebSearchItem
+  | TodoListItem
+  | ErrorItem;

package/lib/codex-sdk/src/outputSchemaFile.ts

@@ -0,0 +1,40 @@
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export type OutputSchemaFile = {
+  schemaPath?: string;
+  cleanup: () => Promise<void>;
+};
+
+export async function createOutputSchemaFile(schema: unknown): Promise<OutputSchemaFile> {
+  if (schema === undefined) {
+    return { cleanup: async () => {} };
+  }
+
+  if (!isJsonObject(schema)) {
+    throw new Error("outputSchema must be a plain JSON object");
+  }
+
+  const schemaDir = await fs.mkdtemp(path.join(os.tmpdir(), "codex-output-schema-"));
+  const schemaPath = path.join(schemaDir, "schema.json");
+  const cleanup = async () => {
+    try {
+      await fs.rm(schemaDir, { recursive: true, force: true });
+    } catch {
+      // suppress
+    }
+  };
+
+  try {
+    await fs.writeFile(schemaPath, JSON.stringify(schema), "utf8");
+    return { schemaPath, cleanup };
+  } catch (error) {
+    await cleanup();
+    throw error;
+  }
+}
+
+function isJsonObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/lib/codex-sdk/src/thread.ts

@@ -0,0 +1,155 @@
+import { CodexOptions } from "./codexOptions";
+import { ThreadEvent, ThreadError, Usage } from "./events";
+import { CodexExec } from "./exec";
+import { ThreadItem } from "./items";
+import { ThreadOptions } from "./threadOptions";
+import { TurnOptions } from "./turnOptions";
+import { createOutputSchemaFile } from "./outputSchemaFile";
+
+/** Completed turn. */
+export type Turn = {
+  items: ThreadItem[];
+  finalResponse: string;
+  usage: Usage | null;
+};
+
+/** Alias for `Turn` to describe the result of `run()`. */
+export type RunResult = Turn;
+
+/** The result of the `runStreamed` method. */
+export type StreamedTurn = {
+  events: AsyncGenerator<ThreadEvent>;
+};
+
+/** Alias for `StreamedTurn` to describe the result of `runStreamed()`. */
+export type RunStreamedResult = StreamedTurn;
+
+/** An input to send to the agent. */
+export type UserInput =
+  | {
+      type: "text";
+      text: string;
+    }
+  | {
+      type: "local_image";
+      path: string;
+    };
+
+export type Input = string | UserInput[];
+
+/** Respesent a thread of conversation with the agent. One thread can have multiple consecutive turns. */
+export class Thread {
+  private _exec: CodexExec;
+  private _options: CodexOptions;
+  private _id: string | null;
+  private _threadOptions: ThreadOptions;
+
+  /** Returns the ID of the thread. Populated after the first turn starts. */
+  public get id(): string | null {
+    return this._id;
+  }
+
+  /* @internal */
+  constructor(
+    exec: CodexExec,
+    options: CodexOptions,
+    threadOptions: ThreadOptions,
+    id: string | null = null,
+  ) {
+    this._exec = exec;
+    this._options = options;
+    this._id = id;
+    this._threadOptions = threadOptions;
+  }
+
+  /** Provides the input to the agent and streams events as they are produced during the turn. */
+  async runStreamed(input: Input, turnOptions: TurnOptions = {}): Promise<StreamedTurn> {
+    return { events: this.runStreamedInternal(input, turnOptions) };
+  }
+
+  private async *runStreamedInternal(
+    input: Input,
+    turnOptions: TurnOptions = {},
+  ): AsyncGenerator<ThreadEvent> {
+    const { schemaPath, cleanup } = await createOutputSchemaFile(turnOptions.outputSchema);
+    const options = this._threadOptions;
+    const { prompt, images } = normalizeInput(input);
+    const generator = this._exec.run({
+      input: prompt,
+      baseUrl: this._options.baseUrl,
+      apiKey: this._options.apiKey,
+      threadId: this._id,
+      images,
+      model: options?.model,
+      sandboxMode: options?.sandboxMode,
+      workingDirectory: options?.workingDirectory,
+      skipGitRepoCheck: options?.skipGitRepoCheck,
+      outputSchemaFile: schemaPath,
+      modelReasoningEffort: options?.modelReasoningEffort,
+      signal: turnOptions.signal,
+      networkAccessEnabled: options?.networkAccessEnabled,
+      webSearchEnabled: options?.webSearchEnabled,
+      approvalPolicy: options?.approvalPolicy,
+      additionalDirectories: options?.additionalDirectories,
+      configOverrides: options?.configOverrides,
+    });
+    try {
+      for await (const item of generator) {
+        let parsed: ThreadEvent;
+        try {
+          parsed = JSON.parse(item) as ThreadEvent;
+        } catch (error) {
+          throw new Error(`Failed to parse item: ${item}`, { cause: error });
+        }
+        if (parsed.type === "thread.started") {
+          this._id = parsed.thread_id;
+        }
+        yield parsed;
+      }
+    } finally {
+      await cleanup();
+    }
+  }
+
+  /** Provides the input to the agent and returns the completed turn. */
+  async run(input: Input, turnOptions: TurnOptions = {}): Promise<Turn> {
+    const generator = this.runStreamedInternal(input, turnOptions);
+    const items: ThreadItem[] = [];
+    let finalResponse: string = "";
+    let usage: Usage | null = null;
+    let turnFailure: ThreadError | null = null;
+    for await (const event of generator) {
+      if (event.type === "item.completed") {
+        if (event.item.type === "agent_message") {
+          finalResponse = event.item.text;
+        }
+        items.push(event.item);
+      } else if (event.type === "turn.completed") {
+        usage = event.usage;
+      } else if (event.type === "turn.failed") {
+        turnFailure = event.error;
+        break;
+      }
+    }
+    if (turnFailure) {
+      throw new Error(turnFailure.message);
+    }
+    return { items, finalResponse, usage };
+  }
+}
+
+function normalizeInput(input: Input): { prompt: string; images: string[] } {
+  if (typeof input === "string") {
+    return { prompt: input, images: [] };
+  }
+  const promptParts: string[] = [];
+  const images: string[] = [];
+  for (const item of input) {
+    if (item.type === "text") {
+      promptParts.push(item.text);
+    } else if (item.type === "local_image") {
+      images.push(item.path);
+    }
+  }
+  return { prompt: promptParts.join("\n\n"), images };
+}