@northflare/runner 0.0.16 → 0.0.17

package/lib/codex-sdk/dist/tests/runStreamed.test.js

@@ -0,0 +1,153 @@
+import path from "node:path";
+import { describe, expect, it } from "@jest/globals";
+import { Codex } from "../src/codex";
+import { assistantMessage, responseCompleted, responseStarted, sse, startResponsesTestProxy, } from "./responsesProxy";
+const codexExecPath = path.join(process.cwd(), "..", "..", "codex-rs", "target", "debug", "codex");
+describe("Codex", () => {
+    it("returns thread events", async () => {
+        const { url, close } = await startResponsesTestProxy({
+            statusCode: 200,
+            responseBodies: [sse(responseStarted(), assistantMessage("Hi!"), responseCompleted())],
+        });
+        try {
+            const client = new Codex({ codexPathOverride: codexExecPath, baseUrl: url, apiKey: "test" });
+            const thread = client.startThread();
+            const result = await thread.runStreamed("Hello, world!");
+            const events = [];
+            for await (const event of result.events) {
+                events.push(event);
+            }
+            expect(events).toEqual([
+                {
+                    type: "thread.started",
+                    thread_id: expect.any(String),
+                },
+                {
+                    type: "turn.started",
+                },
+                {
+                    type: "item.completed",
+                    item: {
+                        id: "item_0",
+                        type: "agent_message",
+                        text: "Hi!",
+                    },
+                },
+                {
+                    type: "turn.completed",
+                    usage: {
+                        cached_input_tokens: 12,
+                        input_tokens: 42,
+                        output_tokens: 5,
+                    },
+                },
+            ]);
+            expect(thread.id).toEqual(expect.any(String));
+        }
+        finally {
+            await close();
+        }
+    });
+    it("sends previous items when runStreamed is called twice", async () => {
+        const { url, close, requests } = await startResponsesTestProxy({
+            statusCode: 200,
+            responseBodies: [
+                sse(responseStarted("response_1"), assistantMessage("First response", "item_1"), responseCompleted("response_1")),
+                sse(responseStarted("response_2"), assistantMessage("Second response", "item_2"), responseCompleted("response_2")),
+            ],
+        });
+        try {
+            const client = new Codex({ codexPathOverride: codexExecPath, baseUrl: url, apiKey: "test" });
+            const thread = client.startThread();
+            const first = await thread.runStreamed("first input");
+            await drainEvents(first.events);
+            const second = await thread.runStreamed("second input");
+            await drainEvents(second.events);
+            // Check second request continues the same thread
+            expect(requests.length).toBeGreaterThanOrEqual(2);
+            const secondRequest = requests[1];
+            expect(secondRequest).toBeDefined();
+            const payload = secondRequest.json;
+            const assistantEntry = payload.input.find((entry) => entry.role === "assistant");
+            expect(assistantEntry).toBeDefined();
+            const assistantText = assistantEntry?.content?.find((item) => item.type === "output_text")?.text;
+            expect(assistantText).toBe("First response");
+        }
+        finally {
+            await close();
+        }
+    });
+    it("resumes thread by id when streaming", async () => {
+        const { url, close, requests } = await startResponsesTestProxy({
+            statusCode: 200,
+            responseBodies: [
+                sse(responseStarted("response_1"), assistantMessage("First response", "item_1"), responseCompleted("response_1")),
+                sse(responseStarted("response_2"), assistantMessage("Second response", "item_2"), responseCompleted("response_2")),
+            ],
+        });
+        try {
+            const client = new Codex({ codexPathOverride: codexExecPath, baseUrl: url, apiKey: "test" });
+            const originalThread = client.startThread();
+            const first = await originalThread.runStreamed("first input");
+            await drainEvents(first.events);
+            const resumedThread = client.resumeThread(originalThread.id);
+            const second = await resumedThread.runStreamed("second input");
+            await drainEvents(second.events);
+            expect(resumedThread.id).toBe(originalThread.id);
+            expect(requests.length).toBeGreaterThanOrEqual(2);
+            const secondRequest = requests[1];
+            expect(secondRequest).toBeDefined();
+            const payload = secondRequest.json;
+            const assistantEntry = payload.input.find((entry) => entry.role === "assistant");
+            expect(assistantEntry).toBeDefined();
+            const assistantText = assistantEntry?.content?.find((item) => item.type === "output_text")?.text;
+            expect(assistantText).toBe("First response");
+        }
+        finally {
+            await close();
+        }
+    });
+    it("applies output schema turn options when streaming", async () => {
+        const { url, close, requests } = await startResponsesTestProxy({
+            statusCode: 200,
+            responseBodies: [
+                sse(responseStarted("response_1"), assistantMessage("Structured response", "item_1"), responseCompleted("response_1")),
+            ],
+        });
+        const schema = {
+            type: "object",
+            properties: {
+                answer: { type: "string" },
+            },
+            required: ["answer"],
+            additionalProperties: false,
+        };
+        try {
+            const client = new Codex({ codexPathOverride: codexExecPath, baseUrl: url, apiKey: "test" });
+            const thread = client.startThread();
+            const streamed = await thread.runStreamed("structured", { outputSchema: schema });
+            await drainEvents(streamed.events);
+            expect(requests.length).toBeGreaterThanOrEqual(1);
+            const payload = requests[0];
+            expect(payload).toBeDefined();
+            const text = payload.json.text;
+            expect(text).toBeDefined();
+            expect(text?.format).toEqual({
+                name: "codex_output_schema",
+                type: "json_schema",
+                strict: true,
+                schema,
+            });
+        }
+        finally {
+            await close();
+        }
+    });
+});
+async function drainEvents(events) {
+    let done = false;
+    do {
+        done = (await events.next()).done ?? false;
+    } while (!done);
+}
+//# sourceMappingURL=runStreamed.test.js.map

package/lib/codex-sdk/dist/tests/runStreamed.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runStreamed.test.js","sourceRoot":"","sources":["../../tests/runStreamed.test.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,38 @@
+import { CodexOptions } from "./codexOptions";
+import { CodexExec } from "./exec";
+import { Thread } from "./thread";
+import { ThreadOptions } from "./threadOptions";
+
+/**
+ * Codex is the main class for interacting with the Codex agent.
+ *
+ * Use the `startThread()` method to start a new thread or `resumeThread()` to resume a previously started thread.
+ */
+export class Codex {
+  private exec: CodexExec;
+  private options: CodexOptions;
+
+  constructor(options: CodexOptions = {}) {
+    this.exec = new CodexExec(options.codexPathOverride, options.env);
+    this.options = options;
+  }
+
+  /**
+   * Starts a new conversation with an agent.
+   * @returns A new thread instance.
+   */
+  startThread(options: ThreadOptions = {}): Thread {
+    return new Thread(this.exec, this.options, options);
+  }
+
+  /**
+   * Resumes a conversation with an agent based on the thread id.
+   * Threads are persisted in ~/.codex/sessions.
+   *
+   * @param id The id of the thread to resume.
+   * @returns A new thread instance.
+   */
+  resumeThread(id: string, options: ThreadOptions = {}): Thread {
+    return new Thread(this.exec, this.options, options, id);
+  }
+}

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

@@ -0,0 +1,10 @@
+export type CodexOptions = {
+  codexPathOverride?: string;
+  baseUrl?: string;
+  apiKey?: string;
+  /**
+   * Environment variables passed to the Codex CLI process. When provided, the SDK
+   * will not inherit variables from `process.env`.
+   */
+  env?: Record<string, string>;
+};

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

@@ -0,0 +1,80 @@
+// based on event types from codex-rs/exec/src/exec_events.rs
+
+import type { ThreadItem } from "./items";
+
+/** Emitted when a new thread is started as the first event. */
+export type ThreadStartedEvent = {
+  type: "thread.started";
+  /** The identifier of the new thread. Can be used to resume the thread later. */
+  thread_id: string;
+};
+
+/**
+ * Emitted when a turn is started by sending a new prompt to the model.
+ * A turn encompasses all events that happen while the agent is processing the prompt.
+ */
+export type TurnStartedEvent = {
+  type: "turn.started";
+};
+
+/** Describes the usage of tokens during a turn. */
+export type Usage = {
+  /** The number of input tokens used during the turn. */
+  input_tokens: number;
+  /** The number of cached input tokens used during the turn. */
+  cached_input_tokens: number;
+  /** The number of output tokens used during the turn. */
+  output_tokens: number;
+};
+
+/** Emitted when a turn is completed. Typically right after the assistant's response. */
+export type TurnCompletedEvent = {
+  type: "turn.completed";
+  usage: Usage;
+};
+
+/** Indicates that a turn failed with an error. */
+export type TurnFailedEvent = {
+  type: "turn.failed";
+  error: ThreadError;
+};
+
+/** Emitted when a new item is added to the thread. Typically the item is initially "in progress". */
+export type ItemStartedEvent = {
+  type: "item.started";
+  item: ThreadItem;
+};
+
+/** Emitted when an item is updated. */
+export type ItemUpdatedEvent = {
+  type: "item.updated";
+  item: ThreadItem;
+};
+
+/** Signals that an item has reached a terminal state—either success or failure. */
+export type ItemCompletedEvent = {
+  type: "item.completed";
+  item: ThreadItem;
+};
+
+/** Fatal error emitted by the stream. */
+export type ThreadError = {
+  message: string;
+};
+
+/** Represents an unrecoverable error emitted directly by the event stream. */
+export type ThreadErrorEvent = {
+  type: "error";
+  message: string;
+};
+
+/** Top-level JSONL events emitted by codex exec. */
+export type ThreadEvent =
+  | ThreadStartedEvent
+  | TurnStartedEvent
+  | TurnCompletedEvent
+  | TurnFailedEvent
+  | ItemStartedEvent
+  | ItemUpdatedEvent
+  | ItemCompletedEvent
+  | ThreadErrorEvent;

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";