@northflare/runner 0.0.1

package/src/utils/StateManager.ts

@@ -0,0 +1,187 @@
+/**
+ * State Manager for persisting runner state
+ * 
+ * Manages persistent state including lastProcessedAt timestamp
+ * to enable proper catch-up on restart.
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { createLogger } from './logger';
+
+const logger = createLogger('StateManager');
+
+export interface RunnerState {
+  runnerId: string;
+  runnerUid: string | null;
+  lastProcessedAt: string | null; // ISO string
+  isActiveRunner: boolean;
+  updatedAt: string; // ISO string
+}
+
+export class StateManager {
+  private statePath: string;
+  private state: RunnerState | null = null;
+  private saveTimer: NodeJS.Timeout | null = null;
+
+  constructor(dataDir: string, runnerId: string) {
+    // Namespace state file by runnerId (stable external ID) to separate different users
+    const stateFile = `runner-state-${runnerId}.json`;
+    this.statePath = path.join(dataDir, stateFile);
+  }
+
+  /**
+   * Load state from disk
+   */
+  async loadState(): Promise<RunnerState | null> {
+    try {
+      const content = await fs.readFile(this.statePath, 'utf-8');
+      this.state = JSON.parse(content);
+      logger.info('Loaded runner state', {
+        runnerId: this.state?.runnerId,
+        runnerUid: this.state?.runnerUid,
+        lastProcessedAt: this.state?.lastProcessedAt,
+        isActiveRunner: this.state?.isActiveRunner,
+      });
+      return this.state;
+    } catch (error) {
+      if ((error as any).code === 'ENOENT') {
+        logger.debug('No state file found, starting fresh');
+        return null;
+      }
+      logger.error('Failed to load state file:', error);
+      return null;
+    }
+  }
+
+  /**
+   * Save state to disk
+   */
+  async saveState(state: RunnerState): Promise<void> {
+    this.state = state;
+    
+    // Cancel any pending save
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer);
+    }
+
+    // Debounce saves to avoid excessive disk writes
+    this.saveTimer = setTimeout(async () => {
+      try {
+        // Ensure directory exists
+        const dir = path.dirname(this.statePath);
+        await fs.mkdir(dir, { recursive: true });
+
+        // Update timestamp
+        state.updatedAt = new Date().toISOString();
+
+        // Write atomically by writing to temp file first
+        const tempPath = `${this.statePath}.tmp`;
+        await fs.writeFile(tempPath, JSON.stringify(state, null, 2), 'utf-8');
+        await fs.rename(tempPath, this.statePath);
+
+        logger.debug('Saved runner state', {
+          runnerId: state.runnerId,
+          lastProcessedAt: state.lastProcessedAt,
+          isActiveRunner: state.isActiveRunner,
+        });
+      } catch (error) {
+        logger.error('Failed to save state file:', error);
+        throw error;
+      }
+    }, 1000); // 1 second debounce
+  }
+
+  /**
+   * Update lastProcessedAt timestamp
+   */
+  async updateLastProcessedAt(timestamp: Date | string): Promise<void> {
+    if (!this.state) {
+      throw new Error('State not loaded');
+    }
+
+    const isoString = timestamp instanceof Date ? timestamp.toISOString() : timestamp;
+    
+    const updatedState: RunnerState = {
+      ...this.state,
+      lastProcessedAt: isoString,
+    };
+
+    await this.saveState(updatedState);
+  }
+
+  /**
+   * Update runner registration details
+   */
+  async updateRunnerRegistration(
+    runnerId: string,
+    runnerUid: string | null,
+    lastProcessedAt: Date | null
+  ): Promise<void> {
+    const state: RunnerState = this.state || {
+      runnerId: '',
+      runnerUid: null,
+      lastProcessedAt: null,
+      isActiveRunner: false,
+      updatedAt: new Date().toISOString(),
+    };
+
+    const updatedState: RunnerState = {
+      ...state,
+      runnerId,
+      runnerUid,
+      lastProcessedAt: lastProcessedAt ? lastProcessedAt.toISOString() : null,
+    };
+
+    await this.saveState(updatedState);
+  }
+
+  /**
+   * Update active runner status
+   */
+  async updateActiveStatus(isActive: boolean): Promise<void> {
+    if (!this.state) {
+      throw new Error('State not loaded');
+    }
+
+    const updatedState: RunnerState = {
+      ...this.state,
+      isActiveRunner: isActive,
+    };
+
+    await this.saveState(updatedState);
+  }
+
+  /**
+   * Get current state
+   */
+  getState(): RunnerState | null {
+    return this.state;
+  }
+
+  /**
+   * Get lastProcessedAt as Date
+   */
+  getLastProcessedAt(): Date | null {
+    if (!this.state || !this.state.lastProcessedAt) {
+      return null;
+    }
+    return new Date(this.state.lastProcessedAt);
+  }
+
+  /**
+   * Clear state (for testing or reset)
+   */
+  async clearState(): Promise<void> {
+    this.state = null;
+    try {
+      await fs.unlink(this.statePath);
+      logger.info('Cleared runner state');
+    } catch (error) {
+      if ((error as any).code !== 'ENOENT') {
+        logger.error('Failed to clear state file:', error);
+        throw error;
+      }
+    }
+  }
+}

package/src/utils/codex-sdk.js

@@ -0,0 +1,448 @@
+/* Example usage:
+query({
+  prompt: "Hello, how are you?",
+  options: {
+    pathToCodexExecutable: "./codex",
+    cwd: "/Users/joe/Documents/myproject/",
+    resume: "0199a99f-28aa-7872-96f6-24ce1e3a05fc", // Optional, resume from a previous session
+    configOverrides: {
+      model: "gpt-5-codex",
+      model_reasoning_effort: "high",
+      sandbox_mode: "danger-full-access",
+    }
+  }
+})
+
+Output:
+    sandbox_mode: "danger-full-access",
+  }
+}})
+
+Output:
+
+[
+  {
+    id: '',
+    msg: {
+      type: 'session_configured',
+      session_id: '0199a9ce-1f38-7332-b46b-9711279899f1',
+      model: 'gpt-5-codex',
+      reasoning_effort: 'high',
+      history_log_id: 1399031533,
+      history_entry_count: 475,
+      rollout_path: '/Users/toby/.codex/sessions/2025/10/03/rollout-2025-10-03T13-21-21-0199a9ce-1f38-7332-b46b-9711279899f1.jsonl'
+    }
+  },
+  {
+    id: 'submission-1',
+    msg: { type: 'task_started', model_context_window: 272000 }
+  },
+  {
+    id: 'submission-1',
+    msg: { type: 'token_count', info: null, rate_limits: [Object] }
+  },
+  {
+    id: 'submission-1',
+    msg: { type: 'agent_reasoning_section_break' }
+  },
+  {
+    id: 'submission-1',
+    msg: { type: 'agent_reasoning_delta', delta: '**Preparing' }
+  },
+  {
+    id: 'submission-1',
+    msg: { type: 'agent_reasoning_delta', delta: ' a' }
+  },
+  {
+    id: 'submission-1',
+    msg: { type: 'agent_reasoning_delta', delta: ' friendly' }
+  },
+  {
+    id: 'submission-1',
+    msg: { type: 'agent_reasoning_delta', delta: ' response' }
+  },
+  {
+    id: 'submission-1',
+    msg: { type: 'agent_reasoning_delta', delta: '**' }
+  },
+  {
+    id: 'submission-1',
+    msg: {
+      type: 'agent_reasoning',
+      text: '**Preparing a friendly response**'
+    }
+  },
+  {
+    id: 'submission-1',
+    msg: { type: 'agent_message_delta', delta: 'Hey' }
+  },
+  {
+    id: 'submission-1',
+    msg: { type: 'agent_message_delta', delta: ' there' }
+  },
+  {
+    id: 'submission-1',
+    msg: { type: 'agent_message_delta', delta: '!' }
+  },
+  {
+    id: 'submission-1',
+    msg: { type: 'agent_message_delta', delta: ' How' }
+  },
+  {
+    id: 'submission-1',
+    msg: { type: 'agent_message_delta', delta: ' can' }
+  },
+  {
+    id: 'submission-1',
+    msg: { type: 'agent_message_delta', delta: ' I' }
+  },
+  {
+    id: 'submission-1',
+    msg: { type: 'agent_message_delta', delta: ' help' }
+  },
+  {
+    id: 'submission-1',
+    msg: { type: 'agent_message_delta', delta: ' today' }
+  },
+  {
+    id: 'submission-1',
+    msg: { type: 'agent_message_delta', delta: '?' }
+  },
+  {
+    id: 'submission-1',
+    msg: {
+      type: 'agent_message',
+      message: 'Hey there! How can I help today?'
+    }
+  },
+  {
+    id: 'submission-1',
+    msg: { type: 'token_count', info: [Object], rate_limits: [Object] }
+  },
+  {
+    id: 'submission-1',
+    msg: {
+      type: 'task_complete',
+      last_agent_message: 'Hey there! How can I help today?'
+    }
+  }
+]
+  */
+
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+
+class ProcessTransport {
+  constructor(options = {}) {
+    const { command = "codex", args = [], cwd, env, onStderr } = options;
+
+    this.child = spawn(command, args, {
+      cwd,
+      env: { ...process.env, ...env },
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    if (!this.child.stdin || !this.child.stdout) {
+      throw new Error("Codex CLI requires piped stdin/stdout.");
+    }
+
+    if (this.child.stderr) {
+      const stderrHandler = (data) => {
+        if (onStderr) {
+          onStderr(data.toString());
+        } else {
+          process.stderr.write(data);
+        }
+      };
+      this.child.stderr.on("data", stderrHandler);
+    }
+
+    this.stdin = this.child.stdin;
+    this.stdout = this.child.stdout;
+    this.closed = false;
+
+    this.exitPromise = new Promise((resolve, reject) => {
+      this.child.once("exit", (code, signal) => {
+        if (code === 0 || signal === "SIGTERM" || signal === null) {
+          resolve({ code, signal });
+        } else {
+          const exitReason = signal ? `signal ${signal}` : `exit code ${code}`;
+          const error = new Error(
+            `codex process terminated with ${exitReason}`
+          );
+          error.code = code;
+          error.signal = signal;
+          reject(error);
+        }
+      });
+      this.child.once("error", (error) => {
+        reject(error);
+      });
+    });
+  }
+
+  async *readMessages() {
+    const rl = createInterface({ input: this.stdout });
+    try {
+      for await (const line of rl) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+          continue;
+        }
+        let parsed;
+        try {
+          parsed = JSON.parse(trimmed);
+        } catch (error) {
+          const parseError = new Error(
+            `Failed to parse Codex JSON output: ${error.message}\n${trimmed}`
+          );
+          parseError.cause = error;
+          throw parseError;
+        }
+        yield parsed;
+      }
+      await this.exitPromise;
+    } finally {
+      rl.close();
+    }
+  }
+
+  async write(payload) {
+    if (this.closed) {
+      throw new Error("Cannot write to closed Codex transport.");
+    }
+    if (!this.stdin || this.stdin.destroyed) {
+      throw new Error("Codex stdin is not available.");
+    }
+
+    const serialized =
+      typeof payload === "string" ? payload : JSON.stringify(payload);
+    const message = serialized.endsWith("\n") ? serialized : `${serialized}\n`;
+    const stream = this.stdin;
+
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        stream.off("error", handleError);
+        resolve();
+      };
+      const handleError = (error) => {
+        if (settled) return;
+        settled = true;
+        stream.off("drain", finish);
+        stream.off("error", handleError);
+        reject(error);
+      };
+
+      stream.once("error", handleError);
+      const ok = stream.write(message, finish);
+      if (!ok) {
+        stream.once("drain", finish);
+      }
+    });
+  }
+
+  async close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+
+    if (this.stdin && !this.stdin.destroyed) {
+      this.stdin.end();
+    }
+
+    if (this.child && !this.child.killed) {
+      this.child.kill("SIGTERM");
+    }
+
+    try {
+      await this.exitPromise;
+    } catch {
+      // Swallow shutdown errors when closing intentionally.
+    }
+  }
+
+  interruptProcess() {
+    if (this.child && !this.child.killed) {
+      this.child.kill("SIGINT");
+    }
+  }
+}
+
+class Query {
+  constructor(transport) {
+    this.transport = transport;
+    this._nextSubmissionId = 0;
+    this._sessionId = null;
+    this._writeError = null;
+    this._finished = false;
+    this._messageIterator = this._iterateMessages();
+  }
+
+  _generateSubmissionId() {
+    this._nextSubmissionId += 1;
+    return `submission-${this._nextSubmissionId}`;
+  }
+
+  _registerWrite(promise) {
+    promise.catch((error) => {
+      if (!this._writeError) {
+        this._writeError = error;
+        void this.transport.close();
+      }
+    });
+  }
+
+  async *_iterateMessages() {
+    try {
+      for await (const message of this.transport.readMessages()) {
+        if (this._writeError) {
+          throw this._writeError;
+        }
+        const msgType = message?.msg?.type;
+        if (!this._sessionId && msgType === "session_configured") {
+          this._sessionId = message.msg.session_id ?? null;
+        }
+        yield message;
+      }
+      if (this._writeError) {
+        throw this._writeError;
+      }
+    } finally {
+      this._finished = true;
+    }
+  }
+
+  [Symbol.asyncIterator]() {
+    return this._messageIterator;
+  }
+
+  next() {
+    if (this._writeError) {
+      return Promise.reject(this._writeError);
+    }
+    return this._messageIterator.next();
+  }
+
+  get sessionId() {
+    return this._sessionId;
+  }
+
+  async submit(op, id) {
+    if (!op || typeof op !== "object") {
+      throw new Error("submit expects a Codex op object.");
+    }
+    const submissionId = id ?? this._generateSubmissionId();
+    const submission = { id: submissionId, op };
+    await this.transport.write(submission);
+    return submissionId;
+  }
+
+  async submitRaw(submission) {
+    if (!submission || typeof submission !== "object") {
+      throw new Error("submitRaw expects a submission object.");
+    }
+    if (!submission.id || !submission.op) {
+      throw new Error("Submission must include `id` and `op` fields.");
+    }
+    await this.transport.write(submission);
+    return submission.id;
+  }
+
+  async submitUserMessage(text, { items, id } = {}) {
+    const messageItems = Array.isArray(items) ? [...items] : [];
+    if (typeof text === "string" && text.length > 0) {
+      messageItems.push({ type: "text", text });
+    }
+    if (messageItems.length === 0) {
+      throw new Error("submitUserMessage requires text or items.");
+    }
+    return this.submit({ type: "user_input", items: messageItems }, id);
+  }
+
+  async interrupt(id) {
+    return this.submit({ type: "interrupt" }, id);
+  }
+
+  async shutdown(id) {
+    return this.submit({ type: "shutdown" }, id);
+  }
+
+  async close() {
+    await this.transport.close();
+  }
+
+  kill() {
+    this.transport.interruptProcess();
+  }
+}
+
+function normalizeConfigOverrides(overrides) {
+  if (!overrides) {
+    return [];
+  }
+  if (Array.isArray(overrides)) {
+    return overrides;
+  }
+  if (typeof overrides === "object") {
+    return Object.entries(overrides).map(([key, value]) =>
+      value === undefined || value === null ? key : `${key}=${value}`
+    );
+  }
+  throw new Error("configOverrides must be an array or object.");
+}
+
+function buildSpawnConfig(options = {}) {
+  const {
+    pathToCodexExecutable,
+    resume,
+    configOverrides,
+    extraArgs,
+    cwd,
+    env,
+    stderr,
+  } = options;
+
+  const command = pathToCodexExecutable ?? "codex";
+  const args = ["proto"];
+
+  const overrides = normalizeConfigOverrides(configOverrides);
+  for (const override of overrides) {
+    args.push("-c", override);
+  }
+
+  if (resume) {
+    args.push("--resume", resume);
+  }
+
+  if (Array.isArray(extraArgs)) {
+    args.push(...extraArgs);
+  }
+
+  return {
+    command,
+    args,
+    cwd,
+    env,
+    onStderr: stderr,
+  };
+}
+
+export function query({ prompt, options = {} } = {}) {
+  const spawnConfig = buildSpawnConfig(options);
+  const transport = new ProcessTransport(spawnConfig);
+  const q = new Query(transport);
+
+  if (typeof prompt === "string" && prompt.trim().length > 0) {
+    q._registerWrite(q.submitUserMessage(prompt.trim()));
+  } else if (Array.isArray(prompt) && prompt.length > 0) {
+    q._registerWrite(q.submitUserMessage("", { items: prompt }));
+  }
+
+  return q;
+}
+
+export { Query };