@northflare/runner 0.0.7 → 0.0.9

package/lib/codex-sdk/jest.config.cjs

@@ -0,0 +1,31 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  preset: "ts-jest/presets/default-esm",
+  testEnvironment: "node",
+  extensionsToTreatAsEsm: [".ts"],
+  moduleNameMapper: {
+    "^(\\.{1,2}/.*)\\.js$": "$1",
+  },
+  testMatch: ["**/tests/**/*.test.ts"],
+  transform: {
+    "^.+\\.tsx?$": [
+      "ts-jest",
+      {
+        useESM: true,
+        tsconfig: "tsconfig.json",
+        diagnostics: {
+          ignoreCodes: [1343],
+        },
+        astTransformers: {
+          before: [
+            {
+              path: "ts-jest-mock-import-meta",
+              // Workaround for meta.url not working in jest
+              options: { metaObjectReplacement: { url: "file://" + __dirname + "/dist/index.js" } },
+            },
+          ],
+        },
+      },
+    ],
+  },
+};

package/lib/codex-sdk/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@northflare/codex-sdk",
+  "version": "0.0.0-dev",
+  "description": "TypeScript SDK for Codex APIs.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openai/codex.git",
+    "directory": "sdk/typescript"
+  },
+  "keywords": [
+    "openai",
+    "codex",
+    "sdk",
+    "typescript",
+    "api"
+  ],
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsup",
+    "build:watch": "tsup --watch",
+    "lint": "pnpm eslint \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "lint:fix": "pnpm eslint --fix \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "coverage": "jest --coverage",
+    "format": "prettier --check .",
+    "format:fix": "prettier --write ."
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.20.2",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.19.18",
+    "eslint": "^9.36.0",
+    "eslint-config-prettier": "^9.1.2",
+    "eslint-plugin-jest": "^29.0.1",
+    "eslint-plugin-node-import": "^1.0.5",
+    "jest": "^29.7.0",
+    "prettier": "^3.6.2",
+    "ts-jest": "^29.3.4",
+    "ts-jest-mock-import-meta": "^1.3.1",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "typescript-eslint": "^8.45.0",
+    "zod": "^3.24.2",
+    "zod-to-json-schema": "^3.24.6"
+  }
+}

package/lib/codex-sdk/samples/basic_streaming.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env -S NODE_NO_WARNINGS=1 pnpm ts-node-esm --files
+
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+import { Codex } from "@openai/codex-sdk";
+import type { ThreadEvent, ThreadItem } from "@openai/codex-sdk";
+import { codexPathOverride } from "./helpers.ts";
+
+const codex = new Codex({ codexPathOverride: codexPathOverride() });
+const thread = codex.startThread();
+const rl = createInterface({ input, output });
+
+const handleItemCompleted = (item: ThreadItem): void => {
+  switch (item.type) {
+    case "agent_message":
+      console.log(`Assistant: ${item.text}`);
+      break;
+    case "reasoning":
+      console.log(`Reasoning: ${item.text}`);
+      break;
+    case "command_execution": {
+      const exitText = item.exit_code !== undefined ? ` Exit code ${item.exit_code}.` : "";
+      console.log(`Command ${item.command} ${item.status}.${exitText}`);
+      break;
+    }
+    case "file_change": {
+      for (const change of item.changes) {
+        console.log(`File ${change.kind} ${change.path}`);
+      }
+      break;
+    }
+  }
+};
+
+const handleItemUpdated = (item: ThreadItem): void => {
+  switch (item.type) {
+    case "todo_list": {
+      console.log(`Todo:`);
+      for (const todo of item.items) {
+        console.log(`\t ${todo.completed ? "x" : " "} ${todo.text}`);
+      }
+      break;
+    }
+  }
+};
+
+const handleEvent = (event: ThreadEvent): void => {
+  switch (event.type) {
+    case "item.completed":
+      handleItemCompleted(event.item);
+      break;
+    case "item.updated":
+    case "item.started":
+      handleItemUpdated(event.item);
+      break;
+    case "turn.completed":
+      console.log(
+        `Used ${event.usage.input_tokens} input tokens, ${event.usage.cached_input_tokens} cached input tokens, ${event.usage.output_tokens} output tokens.`,
+      );
+      break;
+    case "turn.failed":
+      console.error(`Turn failed: ${event.error.message}`);
+      break;
+  }
+};
+
+const main = async (): Promise<void> => {
+  try {
+    while (true) {
+      const inputText = await rl.question(">");
+      const trimmed = inputText.trim();
+      if (trimmed.length === 0) {
+        continue;
+      }
+      const { events } = await thread.runStreamed(inputText);
+      for await (const event of events) {
+        handleEvent(event);
+      }
+    }
+  } finally {
+    rl.close();
+  }
+};
+
+main().catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(`Unexpected error: ${message}`);
+  process.exit(1);
+});

package/lib/codex-sdk/samples/helpers.ts

@@ -0,0 +1,8 @@
+import path from "node:path";
+
+export function codexPathOverride() {
+  return (
+    process.env.CODEX_EXECUTABLE ??
+    path.join(process.cwd(), "..", "..", "codex-rs", "target", "debug", "codex")
+  );
+}

package/lib/codex-sdk/samples/structured_output.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env -S NODE_NO_WARNINGS=1 pnpm ts-node-esm --files
+
+import { Codex } from "@openai/codex-sdk";
+
+import { codexPathOverride } from "./helpers.ts";
+
+const codex = new Codex({ codexPathOverride: codexPathOverride() });
+
+const thread = codex.startThread();
+
+const schema = {
+  type: "object",
+  properties: {
+    summary: { type: "string" },
+    status: { type: "string", enum: ["ok", "action_required"] },
+  },
+  required: ["summary", "status"],
+  additionalProperties: false,
+} as const;
+
+const turn = await thread.run("Summarize repository status", { outputSchema: schema });
+console.log(turn.finalResponse);

package/lib/codex-sdk/samples/structured_output_zod.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env -S NODE_NO_WARNINGS=1 pnpm ts-node-esm --files
+
+import { Codex } from "@openai/codex-sdk";
+import { codexPathOverride } from "./helpers.ts";
+import z from "zod";
+import zodToJsonSchema from "zod-to-json-schema";
+
+const codex = new Codex({ codexPathOverride: codexPathOverride() });
+const thread = codex.startThread();
+
+const schema = z.object({
+  summary: z.string(),
+  status: z.enum(["ok", "action_required"]),
+});
+
+const turn = await thread.run("Summarize repository status", {
+  outputSchema: zodToJsonSchema(schema, { target: "openAi" }),
+});
+console.log(turn.finalResponse);

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;