@stigmer/runner 3.0.1

package/src/ipc-protocol-fixtures.ts

@@ -0,0 +1,117 @@
+// Golden wire-shape examples for the manager-mode IPC contract — one representative
+// instance per message. This is the single source the cross-language mirrors assert
+// against (Rust `protocol.rs`, Go `unified_runner.go`): the generator script serializes
+// `buildFixtures()` to `fixtures/ipc-protocol.generated.json`, and each mirror's tests
+// read that artifact. Because every sample is typed against an `Ipc*` interface from
+// `ipc-protocol.ts`, renaming or retyping a field there fails `tsc` here — that compile
+// error is what binds the fixtures to the contract. Full rules: docs/ipc-protocol.md.
+
+import {
+  IPC_PROTOCOL_VERSION,
+  buildReadyMessage,
+  type IpcAddSession,
+  type IpcAddWorkflowExecution,
+  type IpcError,
+  type IpcReady,
+  type IpcRemoveSession,
+  type IpcRemoveWorkflowExecution,
+  type IpcSessionAdded,
+  type IpcSessionRemoved,
+  type IpcShutdown,
+  type IpcShutdownComplete,
+  type IpcTokenUpdated,
+  type IpcUpdateToken,
+  type IpcWorkflowExecutionAdded,
+  type IpcWorkflowExecutionRemoved,
+} from "./ipc-protocol.js";
+
+// Stable example identifiers shared by every mirror's tests. Keep them in sync with the
+// values hard-coded in protocol.rs and ipc_fixtures_test.go — they are part of the golden
+// artifact, so a change here regenerates the fixture and the mirrors must match it.
+const SESSION_ID = "ses_example";
+const EXECUTION_ID = "wfe_example";
+const TOKEN = "tok_example";
+
+/** The full golden fixture set: the protocol version plus every command and response. */
+export interface IpcFixtures {
+  ipcProtocolVersion: number;
+  commands: {
+    addSession: IpcAddSession;
+    removeSession: IpcRemoveSession;
+    addWorkflowExecution: IpcAddWorkflowExecution;
+    removeWorkflowExecution: IpcRemoveWorkflowExecution;
+    updateTokenSet: IpcUpdateToken;
+    updateTokenCleared: IpcUpdateToken;
+    shutdown: IpcShutdown;
+  };
+  responses: {
+    ready: IpcReady;
+    // A pre-version-1 runner that omits `protocolVersion`. Not an `IpcReady` (which now
+    // requires the field), so it is typed as the legacy subset — hosts must treat it as
+    // version 1. This is the backward-compatibility contract every host mirror tests.
+    readyLegacy: Omit<IpcReady, "protocolVersion">;
+    sessionAdded: IpcSessionAdded;
+    sessionRemoved: IpcSessionRemoved;
+    workflowExecutionAdded: IpcWorkflowExecutionAdded;
+    workflowExecutionRemoved: IpcWorkflowExecutionRemoved;
+    tokenUpdated: IpcTokenUpdated;
+    error: IpcError;
+    shutdownComplete: IpcShutdownComplete;
+  };
+}
+
+// Builds the golden fixture set. `ready` uses the real builder so the artifact reflects
+// the message the runner actually emits; every other message is a typed literal. Insertion
+// order here is the artifact's key order — keep it stable so the freshness guard's textual
+// diff stays meaningful (consumers compare semantically and do not depend on it).
+export function buildFixtures(): IpcFixtures {
+  return {
+    ipcProtocolVersion: IPC_PROTOCOL_VERSION,
+    commands: {
+      addSession: { type: "addSession", sessionId: SESSION_ID },
+      removeSession: { type: "removeSession", sessionId: SESSION_ID },
+      addWorkflowExecution: {
+        type: "addWorkflowExecution",
+        executionId: EXECUTION_ID,
+      },
+      removeWorkflowExecution: {
+        type: "removeWorkflowExecution",
+        executionId: EXECUTION_ID,
+      },
+      updateTokenSet: { type: "updateToken", token: TOKEN },
+      updateTokenCleared: { type: "updateToken", token: null },
+      shutdown: { type: "shutdown" },
+    },
+    responses: {
+      ready: buildReadyMessage(),
+      readyLegacy: { type: "ready" },
+      sessionAdded: {
+        type: "sessionAdded",
+        sessionId: SESSION_ID,
+        taskQueue: `session:${SESSION_ID}`,
+      },
+      sessionRemoved: { type: "sessionRemoved", sessionId: SESSION_ID },
+      workflowExecutionAdded: {
+        type: "workflowExecutionAdded",
+        executionId: EXECUTION_ID,
+        taskQueue: `wfexec:${EXECUTION_ID}`,
+      },
+      workflowExecutionRemoved: {
+        type: "workflowExecutionRemoved",
+        executionId: EXECUTION_ID,
+      },
+      tokenUpdated: { type: "tokenUpdated" },
+      error: { type: "error", message: "boom", fatal: true },
+      shutdownComplete: { type: "shutdownComplete" },
+    },
+  };
+}
+
+/**
+ * Serializes the fixtures to the exact text written to disk: 2-space JSON with a trailing
+ * newline. Centralized so the writer and the `--check` guard format identically — any
+ * difference would make the textual freshness diff falsely fail.
+ */
+export function serializeFixtures(): string {
+  return `${JSON.stringify(buildFixtures(), null, 2)}\n`;
+}

package/src/ipc-protocol.ts

@@ -0,0 +1,113 @@
+// Canonical machine-readable definition of the manager-mode IPC contract.
+// The runner emits these messages; the Rust host crate (crates/stigmer-runner-host/src/
+// protocol.rs) and the Go integration harness (unified_runner.go) hand-mirror them. Those
+// mirrors are kept honest by golden fixtures generated from this file via
+// ipc-protocol-fixtures.ts (run `make gen-ipc-fixtures`). Full spec and the rule for keeping
+// all definitions in sync: docs/ipc-protocol.md.
+
+// Integer protocol version advertised in the `ready` handshake. Bump ONLY on a
+// breaking change (removed/renamed message, changed field type, changed lifecycle
+// guarantee) — additive fields never bump it. Hosts read this to decide compatibility;
+// the runner never reads a version from the host (one-way advertisement).
+export const IPC_PROTOCOL_VERSION = 1;
+
+// ─── Commands (host → runner) ───────────────────────────────────────────────
+
+export interface IpcAddSession {
+  type: "addSession";
+  sessionId: string;
+}
+
+export interface IpcRemoveSession {
+  type: "removeSession";
+  sessionId: string;
+}
+
+export interface IpcAddWorkflowExecution {
+  type: "addWorkflowExecution";
+  executionId: string;
+}
+
+export interface IpcRemoveWorkflowExecution {
+  type: "removeWorkflowExecution";
+  executionId: string;
+}
+
+export interface IpcUpdateToken {
+  type: "updateToken";
+  token: string | null;
+}
+
+export interface IpcShutdown {
+  type: "shutdown";
+}
+
+export type IpcCommand =
+  | IpcAddSession
+  | IpcRemoveSession
+  | IpcAddWorkflowExecution
+  | IpcRemoveWorkflowExecution
+  | IpcUpdateToken
+  | IpcShutdown;
+
+// ─── Responses (runner → host) ──────────────────────────────────────────────
+
+export interface IpcReady {
+  type: "ready";
+  protocolVersion: number;
+}
+
+export interface IpcSessionAdded {
+  type: "sessionAdded";
+  sessionId: string;
+  taskQueue: string;
+}
+
+export interface IpcSessionRemoved {
+  type: "sessionRemoved";
+  sessionId: string;
+}
+
+export interface IpcWorkflowExecutionAdded {
+  type: "workflowExecutionAdded";
+  executionId: string;
+  taskQueue: string;
+}
+
+export interface IpcWorkflowExecutionRemoved {
+  type: "workflowExecutionRemoved";
+  executionId: string;
+}
+
+export interface IpcError {
+  type: "error";
+  message: string;
+  fatal: boolean;
+}
+
+export interface IpcTokenUpdated {
+  type: "tokenUpdated";
+}
+
+export interface IpcShutdownComplete {
+  type: "shutdownComplete";
+}
+
+export type IpcResponse =
+  | IpcReady
+  | IpcSessionAdded
+  | IpcSessionRemoved
+  | IpcWorkflowExecutionAdded
+  | IpcWorkflowExecutionRemoved
+  | IpcTokenUpdated
+  | IpcError
+  | IpcShutdownComplete;
+
+// ─── Message builders ────────────────────────────────────────────────────────
+
+// `ready` is the only message carrying protocol metadata, so it is the only one with a
+// constructor — a pure, importable seam the unit test asserts against (main.ts itself
+// self-executes and is not unit-testable). Every other message is a trivial inline literal.
+export function buildReadyMessage(): IpcReady {
+  return { type: "ready", protocolVersion: IPC_PROTOCOL_VERSION };
+}

package/src/main.ts

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for the unified runner service.
+ *
+ * Two modes of operation:
+ *
+ * 1. Static mode (default): Reads configuration from environment variables,
+ *    initializes OTel, creates a single-queue runner. Used by CLI daemon and
+ *    customer deployments.
+ *
+ * 2. Manager mode (STIGMER_RUNNER_MODE=manager): Reads JSON commands from
+ *    stdin, manages per-session Workers dynamically. Used by the desktop app
+ *    via the IPC protocol. Responses go to stdout; logs go to stderr.
+ *
+ * OTel is initialized here (not in the factory) because it mutates
+ * global state that the consumer should control when embedding the
+ * runner as a library.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+import { createInterface } from "node:readline";
+import { loadConfig } from "./config.js";
+import { initTracing, initMetrics } from "./otel.js";
+import { createStigmerRunner } from "./runner.js";
+import { createStigmerRunnerManager } from "./runner-manager.js";
+import type { StigmerRunnerManager } from "./runner-manager.js";
+import { buildReadyMessage } from "./ipc-protocol.js";
+import type { IpcCommand, IpcResponse } from "./ipc-protocol.js";
+
+import { handleUnhandledRejection, setExecutionContextRef } from "./activities/execute-cursor/rejection-capture.js";
+
+process.on("unhandledRejection", (reason) => {
+  handleUnhandledRejection(reason);
+});
+
+process.on("uncaughtException", (err) => {
+  console.error("Uncaught exception in runner:", err);
+});
+
+// ─── IPC Helpers ─────────────────────────────────────────────────────────────
+
+function sendIpc(msg: IpcResponse): void {
+  process.stdout.write(JSON.stringify(msg) + "\n");
+}
+
+// ─── Manager Mode ────────────────────────────────────────────────────────────
+
+async function runManagerMode(config: import("./config.js").Config): Promise<void> {
+  // In manager mode, redirect console.log to stderr so stdout is reserved for IPC
+  const originalLog = console.log;
+  console.log = (...args: unknown[]) => {
+    process.stderr.write(args.map(String).join(" ") + "\n");
+  };
+
+  let manager: StigmerRunnerManager;
+  try {
+    manager = await createStigmerRunnerManager({
+      temporalAddress: config.temporalAddress,
+      temporalNamespace: config.temporalNamespace,
+      stigmerEndpoint: config.stigmerBackendEndpoint,
+      stigmerToken: config.stigmerToken ?? undefined,
+      cursorApiKey: config.cursorApiKey || undefined,
+      workspaceRootDir: config.workspaceRootDir,
+      maxConcurrentActivitiesPerSession: config.maxConcurrentActivities,
+      proxyEndpoint: config.proxyEndpoint ?? undefined,
+      primaryModel: config.primaryModel,
+      checkpointerType: config.checkpointerType,
+      checkpointerProxyEndpoint: config.checkpointerProxyEndpoint ?? undefined,
+      cloudModeEnabled: config.cloudModeEnabled,
+      executionMode: config.mode,
+    });
+  } catch (err) {
+    sendIpc({
+      type: "error",
+      message: `Failed to initialize runner manager: ${err}`,
+      fatal: true,
+    });
+    process.exit(1);
+  }
+
+  sendIpc(buildReadyMessage());
+
+  const rl = createInterface({ input: process.stdin });
+
+  for await (const line of rl) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+    let cmd: IpcCommand;
+    try {
+      cmd = JSON.parse(trimmed) as IpcCommand;
+    } catch {
+      sendIpc({
+        type: "error",
+        message: `Invalid JSON: ${trimmed}`,
+        fatal: false,
+      });
+      continue;
+    }
+
+    try {
+      switch (cmd.type) {
+        case "addSession": {
+          await manager.addSession(cmd.sessionId);
+          sendIpc({
+            type: "sessionAdded",
+            sessionId: cmd.sessionId,
+            taskQueue: `session:${cmd.sessionId}`,
+          });
+          break;
+        }
+        case "removeSession": {
+          await manager.removeSession(cmd.sessionId);
+          sendIpc({ type: "sessionRemoved", sessionId: cmd.sessionId });
+          break;
+        }
+        case "addWorkflowExecution": {
+          await manager.addWorkflowExecution(cmd.executionId);
+          sendIpc({
+            type: "workflowExecutionAdded",
+            executionId: cmd.executionId,
+            taskQueue: `wfexec:${cmd.executionId}`,
+          });
+          break;
+        }
+        case "removeWorkflowExecution": {
+          await manager.removeWorkflowExecution(cmd.executionId);
+          sendIpc({ type: "workflowExecutionRemoved", executionId: cmd.executionId });
+          break;
+        }
+        case "updateToken": {
+          manager.updateToken(cmd.token);
+          sendIpc({ type: "tokenUpdated" });
+          break;
+        }
+        case "shutdown": {
+          await manager.shutdown();
+          sendIpc({ type: "shutdownComplete" });
+          rl.close();
+          return;
+        }
+        default: {
+          sendIpc({
+            type: "error",
+            message: `Unknown command type: ${(cmd as any).type}`,
+            fatal: false,
+          });
+        }
+      }
+    } catch (err) {
+      sendIpc({
+        type: "error",
+        message: `Command ${cmd.type} failed: ${err}`,
+        fatal: false,
+      });
+    }
+  }
+
+  // stdin closed (parent process died) — shut down gracefully
+  await manager.shutdown();
+}
+
+// ─── Static Mode ─────────────────────────────────────────────────────────────
+
+async function runStaticMode(config: import("./config.js").Config): Promise<void> {
+  const otelShutdown = await initTracing("stigmer-runner");
+  const metricsShutdown = await initMetrics("stigmer-runner");
+
+  const runner = await createStigmerRunner({
+    taskQueue: config.taskQueue,
+    temporalAddress: config.temporalAddress,
+    temporalNamespace: config.temporalNamespace,
+    stigmerEndpoint: config.stigmerBackendEndpoint,
+    stigmerToken: config.stigmerToken ?? undefined,
+    cursorApiKey: config.cursorApiKey || undefined,
+    workspaceRootDir: config.workspaceRootDir,
+    maxConcurrentActivities: config.maxConcurrentActivities,
+    proxyEndpoint: config.proxyEndpoint ?? undefined,
+    primaryModel: config.primaryModel,
+    checkpointerType: config.checkpointerType,
+    checkpointerProxyEndpoint: config.checkpointerProxyEndpoint ?? undefined,
+    cloudModeEnabled: config.cloudModeEnabled,
+    // Honor the operator's MODE env (resolved into config.mode) instead of
+    // re-deriving execution location from the proxy. This keeps static mode
+    // consistent with manager mode, which already passes config.mode.
+    executionMode: config.mode,
+  });
+
+  let shutdownRequested = false;
+  const shutdown = (signal: string) => {
+    if (shutdownRequested) {
+      console.warn("Shutdown already in progress, ignoring duplicate signal");
+      return;
+    }
+    shutdownRequested = true;
+    console.log(`Received ${signal}, stopping worker gracefully...`);
+    runner.shutdown();
+  };
+
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => shutdown("SIGINT"));
+
+  await runner.start();
+
+  if (metricsShutdown) {
+    await metricsShutdown();
+  }
+  if (otelShutdown) {
+    await otelShutdown();
+  }
+}
+
+// ─── Build Fingerprint Check ─────────────────────────────────────────────────
+
+/**
+ * Compares the dist/.build-fingerprint against the current src/ hash.
+ * Exits the process if the runner binary is stale — silently running
+ * old code causes structured output failures, naming mismatches, and
+ * hours of wasted debugging time.
+ *
+ * If the fingerprint file is missing (first build, CI, integration
+ * tests using tsx), the check is skipped gracefully.
+ */
+function checkBuildFreshness(): void {
+  try {
+    const runnerRoot = new URL("../", import.meta.url).pathname;
+    const fpPath = join(runnerRoot, "dist", ".build-fingerprint");
+
+    let stored: { hash: string; builtAt: string };
+    try {
+      stored = JSON.parse(readFileSync(fpPath, "utf-8"));
+    } catch {
+      return;
+    }
+
+    const srcDir = join(runnerRoot, "src");
+    const tsFiles = collectTsFiles(srcDir).sort();
+    const hash = createHash("sha256");
+    for (const file of tsFiles) {
+      hash.update(relative(runnerRoot, file));
+      hash.update(readFileSync(file));
+    }
+    const currentHash = hash.digest("hex").slice(0, 16);
+
+    if (currentHash !== stored.hash) {
+      console.error(
+        `\n` +
+        `!!! STALE RUNNER BUILD — REFUSING TO START !!!\n` +
+        `    dist/ was built at ${stored.builtAt} (hash ${stored.hash})\n` +
+        `    src/ has changed since (current hash ${currentHash})\n` +
+        `\n` +
+        `    Run 'make build-runner' or 'make desktop-dev' to rebuild.\n`,
+      );
+      process.exit(78);
+    }
+  } catch {
+    // Missing fingerprint (tsx, CI, first build) — allow startup
+  }
+}
+
+function collectTsFiles(dir: string, files: string[] = []): string[] {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name === "__tests__") continue;
+      collectTsFiles(fullPath, files);
+    } else if (entry.name.endsWith(".ts")) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+// ─── Entry Point ─────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  checkBuildFreshness();
+
+  const config = loadConfig();
+
+  // Route ALL Cursor SDK traffic through the Stigmer proxy in proxy mode.
+  //
+  // CURSOR_BACKEND_URL controls:
+  //   1. connect-node Connect RPC transport (AgentService/Run BiDi stream)
+  //   2. Token exchange (fetch to ${baseUrl}/auth/exchange_user_api_key)
+  //   3. CloudApiClient REST (fetch to ${baseUrl}/v1/models, agent CRUD)
+  //
+  // Setting it to proxyEndpoint makes connect-node send the BiDi stream to
+  // the proxy, where path routing (Caddy/Istio) dispatches /agent.v1* to the
+  // Netty BiDi proxy on port 8082.
+  //
+  // Side-effect: REST calls (#2, #3) also target proxyEndpoint via fetch.
+  // The fetch interceptor detects these (proxy-endpoint host, non-Connect path)
+  // and rewrites them to /v1/proxy/cursor/{upstream_host}{path} for Tomcat.
+  //
+  // CURSOR_API_BASE_URL is also set for completeness — older SDK versions
+  // may read it for token exchange instead of CURSOR_BACKEND_URL.
+  if (config.proxyEndpoint) {
+    const proxyBase = config.proxyEndpoint.replace(/\/+$/, "");
+    process.env.CURSOR_BACKEND_URL = proxyBase;
+    process.env.CURSOR_API_BASE_URL = proxyBase;
+  }
+
+  const runnerMode = process.env.STIGMER_RUNNER_MODE === "manager" ? "manager" : "static";
+  console.warn(
+    `[runner] mode=${runnerMode}, proxy=${config.proxyEndpoint ?? "none"}, ` +
+    `hasToken=${!!config.stigmerToken}, workspace=${config.workspaceRootDir}, ` +
+    `taskQueue=${config.taskQueue}`,
+  );
+
+  if (runnerMode === "manager") {
+    await runManagerMode(config);
+  } else {
+    await runStaticMode(config);
+  }
+}
+
+main().catch((err) => {
+  console.error("Fatal error in runner:", err);
+  process.exit(1);
+});