@northflare/runner 0.0.16 → 0.0.17

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 };
+}

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

@@ -0,0 +1,18 @@
+export type ApprovalMode = "never" | "on-request" | "on-failure" | "untrusted";
+
+export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+
+export type ModelReasoningEffort = "minimal" | "low" | "medium" | "high" | "xhigh";
+
+export type ThreadOptions = {
+  model?: string;
+  sandboxMode?: SandboxMode;
+  workingDirectory?: string;
+  skipGitRepoCheck?: boolean;
+  modelReasoningEffort?: ModelReasoningEffort;
+  networkAccessEnabled?: boolean;
+  webSearchEnabled?: boolean;
+  approvalPolicy?: ApprovalMode;
+  additionalDirectories?: string[];
+  configOverrides?: Record<string, unknown>;
+};

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

@@ -0,0 +1,6 @@
+export type TurnOptions = {
+  /** JSON schema describing the expected agent output. */
+  outputSchema?: unknown;
+  /** AbortSignal to cancel the turn. */
+  signal?: AbortSignal;
+};

package/lib/codex-sdk/tests/abort.test.ts

@@ -0,0 +1,165 @@
+import path from "node:path";
+
+import { describe, expect, it } from "@jest/globals";
+
+import { Codex } from "../src/codex";
+
+import {
+  assistantMessage,
+  responseCompleted,
+  responseStarted,
+  shell_call as shellCall,
+  sse,
+  SseResponseBody,
+  startResponsesTestProxy,
+} from "./responsesProxy";
+
+const codexExecPath = path.join(process.cwd(), "..", "..", "codex-rs", "target", "debug", "codex");
+
+function* infiniteShellCall(): Generator<SseResponseBody> {
+  while (true) {
+    yield sse(responseStarted(), shellCall(), responseCompleted());
+  }
+}
+
+describe("AbortSignal support", () => {
+  it("aborts run() when signal is aborted", async () => {
+    const { url, close } = await startResponsesTestProxy({
+      statusCode: 200,
+      responseBodies: infiniteShellCall(),
+    });
+
+    try {
+      const client = new Codex({ codexPathOverride: codexExecPath, baseUrl: url, apiKey: "test" });
+      const thread = client.startThread();
+
+      // Create an abort controller and abort it immediately
+      const controller = new AbortController();
+      controller.abort("Test abort");
+
+      // The operation should fail because the signal is already aborted
+      await expect(thread.run("Hello, world!", { signal: controller.signal })).rejects.toThrow();
+    } finally {
+      await close();
+    }
+  });
+
+  it("aborts runStreamed() when signal is aborted", async () => {
+    const { url, close } = await startResponsesTestProxy({
+      statusCode: 200,
+      responseBodies: infiniteShellCall(),
+    });
+
+    try {
+      const client = new Codex({ codexPathOverride: codexExecPath, baseUrl: url, apiKey: "test" });
+      const thread = client.startThread();
+
+      // Create an abort controller and abort it immediately
+      const controller = new AbortController();
+      controller.abort("Test abort");
+
+      const { events } = await thread.runStreamed("Hello, world!", { signal: controller.signal });
+
+      // Attempting to iterate should fail
+      let iterationStarted = false;
+      try {
+        for await (const event of events) {
+          iterationStarted = true;
+          // Should not get here
+          expect(event).toBeUndefined();
+        }
+        // If we get here, the test should fail
+        throw new Error(
+          "Expected iteration to throw due to aborted signal, but it completed successfully",
+        );
+      } catch (error) {
+        // We expect an error to be thrown
+        expect(iterationStarted).toBe(false); // Should fail before any iteration
+        expect(error).toBeDefined();
+      }
+    } finally {
+      await close();
+    }
+  });
+
+  it("aborts run() when signal is aborted during execution", async () => {
+    const { url, close } = await startResponsesTestProxy({
+      statusCode: 200,
+      responseBodies: infiniteShellCall(),
+    });
+
+    try {
+      const client = new Codex({ codexPathOverride: codexExecPath, baseUrl: url, apiKey: "test" });
+      const thread = client.startThread();
+
+      const controller = new AbortController();
+
+      // Start the operation and abort it immediately after
+      const runPromise = thread.run("Hello, world!", { signal: controller.signal });
+
+      // Abort after a tiny delay to simulate aborting during execution
+      setTimeout(() => controller.abort("Aborted during execution"), 10);
+
+      // The operation should fail
+      await expect(runPromise).rejects.toThrow();
+    } finally {
+      await close();
+    }
+  });
+
+  it("aborts runStreamed() when signal is aborted during iteration", async () => {
+    const { url, close } = await startResponsesTestProxy({
+      statusCode: 200,
+      responseBodies: infiniteShellCall(),
+    });
+
+    try {
+      const client = new Codex({ codexPathOverride: codexExecPath, baseUrl: url, apiKey: "test" });
+      const thread = client.startThread();
+
+      const controller = new AbortController();
+
+      const { events } = await thread.runStreamed("Hello, world!", { signal: controller.signal });
+
+      // Abort during iteration
+      let eventCount = 0;
+      await expect(
+        (async () => {
+          for await (const event of events) {
+            void event; // Consume the event
+            eventCount++;
+            // Abort after first event
+            if (eventCount === 5) {
+              controller.abort("Aborted during iteration");
+            }
+            // Continue iterating - should eventually throw
+          }
+        })(),
+      ).rejects.toThrow();
+    } finally {
+      await close();
+    }
+  });
+
+  it("completes normally when signal is not aborted", 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 controller = new AbortController();
+
+      // Don't abort - should complete successfully
+      const result = await thread.run("Hello, world!", { signal: controller.signal });
+
+      expect(result.finalResponse).toBe("Hi!");
+      expect(result.items).toHaveLength(1);
+    } finally {
+      await close();
+    }
+  });
+});

package/lib/codex-sdk/tests/codexExecSpy.ts

@@ -0,0 +1,37 @@
+import * as child_process from "node:child_process";
+
+jest.mock("node:child_process", () => {
+  const actual = jest.requireActual<typeof import("node:child_process")>("node:child_process");
+  return { ...actual, spawn: jest.fn(actual.spawn) };
+});
+
+const actualChildProcess =
+  jest.requireActual<typeof import("node:child_process")>("node:child_process");
+const spawnMock = child_process.spawn as jest.MockedFunction<typeof actualChildProcess.spawn>;
+
+export function codexExecSpy(): {
+  args: string[][];
+  envs: (Record<string, string> | undefined)[];
+  restore: () => void;
+} {
+  const previousImplementation = spawnMock.getMockImplementation() ?? actualChildProcess.spawn;
+  const args: string[][] = [];
+  const envs: (Record<string, string> | undefined)[] = [];
+
+  spawnMock.mockImplementation(((...spawnArgs: Parameters<typeof child_process.spawn>) => {
+    const commandArgs = spawnArgs[1];
+    args.push(Array.isArray(commandArgs) ? [...commandArgs] : []);
+    const options = spawnArgs[2] as child_process.SpawnOptions | undefined;
+    envs.push(options?.env as Record<string, string> | undefined);
+    return previousImplementation(...spawnArgs);
+  }) as typeof actualChildProcess.spawn);
+
+  return {
+    args,
+    envs,
+    restore: () => {
+      spawnMock.mockClear();
+      spawnMock.mockImplementation(previousImplementation);
+    },
+  };
+}