@stigmer/runner 3.0.1

package/src/shared/checkpointer/__tests__/http-saver.test.ts

@@ -0,0 +1,176 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { HttpCheckpointSaver } from "../http-saver.js";
+import type { Checkpoint, CheckpointMetadata } from "@langchain/langgraph-checkpoint";
+
+const PROXY = "https://proxy.test";
+const TOKEN = "test-token";
+
+function makeConfig(overrides: Record<string, string> = {}) {
+  return {
+    configurable: {
+      thread_id: "thread-1",
+      checkpoint_ns: "",
+      checkpoint_id: "cp-1",
+      ...overrides,
+    },
+  };
+}
+
+async function serializeForProxy(obj: unknown): Promise<{ type: string; binary: Record<string, any> }> {
+  const helperSaver = new HttpCheckpointSaver(PROXY, TOKEN);
+  const [typeTag, payload] = await helperSaver.serde.dumpsTyped(obj);
+  const b64 = Buffer.from(payload).toString("base64");
+  return {
+    type: typeTag,
+    binary: { $binary: { base64: b64, subType: "00" } },
+  };
+}
+
+describe("HttpCheckpointSaver", () => {
+  let saver: HttpCheckpointSaver;
+  let fetchSpy: ReturnType<typeof vi.fn>;
+
+  beforeEach(() => {
+    saver = new HttpCheckpointSaver(PROXY, TOKEN);
+    fetchSpy = vi.fn();
+    vi.stubGlobal("fetch", fetchSpy);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe("getTuple", () => {
+    it("returns undefined on 404", async () => {
+      fetchSpy.mockResolvedValue({ status: 404, ok: false });
+      const result = await saver.getTuple(makeConfig());
+      expect(result).toBeUndefined();
+    });
+
+    it("throws on non-404 error", async () => {
+      fetchSpy.mockResolvedValue({
+        status: 500,
+        ok: false,
+        statusText: "Internal Server Error",
+      });
+      await expect(saver.getTuple(makeConfig())).rejects.toThrow("500");
+    });
+
+    it("includes authorization header", async () => {
+      fetchSpy.mockResolvedValue({ status: 404, ok: false });
+      await saver.getTuple(makeConfig());
+      const [url, opts] = fetchSpy.mock.calls[0];
+      expect(opts.headers.Authorization).toBe("Bearer test-token");
+      expect(url).toContain("/v1/proxy/checkpoints/checkpoint");
+    });
+  });
+
+  describe("put", () => {
+    it("sends checkpoint and metadata as $binary to the proxy", async () => {
+      fetchSpy.mockResolvedValue({ ok: true, json: () => Promise.resolve({}) });
+
+      const checkpoint: Checkpoint = {
+        v: 4,
+        id: "cp-new",
+        ts: new Date().toISOString(),
+        channel_values: {},
+        channel_versions: {},
+        versions_seen: {},
+      };
+      const metadata: CheckpointMetadata = {
+        source: "loop",
+        step: 0,
+        writes: null,
+        parents: {},
+      };
+
+      const result = await saver.put(makeConfig(), checkpoint, metadata, {});
+      expect(result.configurable?.checkpoint_id).toBe("cp-new");
+      expect(fetchSpy).toHaveBeenCalledOnce();
+
+      const [url, opts] = fetchSpy.mock.calls[0];
+      expect(url).toContain("/checkpoint");
+      expect(opts.method).toBe("PUT");
+
+      const body = JSON.parse(opts.body);
+      expect(body.thread_id).toBe("thread-1");
+      expect(body.checkpoint_id).toBe("cp-new");
+      expect(body.checkpoint.$binary).toBeDefined();
+      expect(body.metadata.$binary).toBeDefined();
+      expect(body.type).toBeDefined();
+    });
+  });
+
+  describe("putWrites", () => {
+    it("sends writes array with $binary values", async () => {
+      fetchSpy.mockResolvedValue({ ok: true, json: () => Promise.resolve({}) });
+
+      await saver.putWrites(
+        makeConfig(),
+        [["messages", { content: "hello" }]],
+        "task-1",
+      );
+
+      const [url, opts] = fetchSpy.mock.calls[0];
+      expect(url).toContain("/writes");
+      expect(opts.method).toBe("PUT");
+
+      const body = JSON.parse(opts.body);
+      expect(body.writes).toHaveLength(1);
+      expect(body.writes[0].task_id).toBe("task-1");
+      expect(body.writes[0].channel).toBe("messages");
+      expect(body.writes[0].value.$binary).toBeDefined();
+    });
+  });
+
+  describe("list", () => {
+    it("yields checkpoint tuples from proxy response", async () => {
+      const cp: Checkpoint = {
+        v: 4,
+        id: "cp-list-1",
+        ts: new Date().toISOString(),
+        channel_values: {},
+        channel_versions: {},
+        versions_seen: {},
+      };
+      const md: CheckpointMetadata = { source: "loop", step: 1, writes: null, parents: {} };
+      const cpSer = await serializeForProxy(cp);
+      const mdSer = await serializeForProxy(md);
+
+      fetchSpy.mockResolvedValue({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            checkpoints: [
+              {
+                thread_id: "thread-1",
+                checkpoint_ns: "",
+                checkpoint_id: "cp-list-1",
+                type: cpSer.type,
+                checkpoint: cpSer.binary,
+                metadata_type: mdSer.type,
+                metadata: mdSer.binary,
+              },
+            ],
+          }),
+      });
+
+      const results: any[] = [];
+      for await (const tuple of saver.list(makeConfig())) {
+        results.push(tuple);
+      }
+      expect(results).toHaveLength(1);
+      expect(results[0].config.configurable.checkpoint_id).toBe("cp-list-1");
+    });
+  });
+
+  describe("URL construction", () => {
+    it("strips trailing slashes from proxy endpoint", () => {
+      const s = new HttpCheckpointSaver("https://proxy.test///", "tok");
+      fetchSpy.mockResolvedValue({ status: 404, ok: false });
+      s.getTuple(makeConfig());
+      const [url] = fetchSpy.mock.calls[0];
+      expect(url).toContain("https://proxy.test/v1/proxy/checkpoints/checkpoint");
+    });
+  });
+});

package/src/shared/checkpointer/factory.ts

@@ -0,0 +1,73 @@
+/**
+ * Checkpointer factory — creates the appropriate LangGraph checkpoint
+ * saver based on runner configuration.
+ *
+ * Two backends:
+ * - memory: MemorySaver (ephemeral, zero-config) — for OSS / local mode
+ * - http: HttpCheckpointSaver (proxy-backed) — for cloud mode
+ *
+ * The returned saver is used by the deep agent activity (Phase 3).
+ * Cursor executions do not use LangGraph checkpointers — they rely on
+ * the Cursor SDK's native agent state persistence.
+ */
+
+import { MemorySaver } from "@langchain/langgraph-checkpoint";
+import type { BaseCheckpointSaver } from "@langchain/langgraph-checkpoint";
+import type { CheckpointerConfig } from "./types.js";
+import { HttpCheckpointSaver } from "./http-saver.js";
+
+export class CheckpointerCreationError extends Error {
+  readonly checkpointerType: string;
+  readonly cause?: Error;
+
+  constructor(type: string, message: string, cause?: Error) {
+    super(`Failed to create ${type} checkpointer: ${message}`);
+    this.name = "CheckpointerCreationError";
+    this.checkpointerType = type;
+    this.cause = cause;
+  }
+}
+
+/**
+ * Create the appropriate checkpoint saver for the given config.
+ *
+ * Unlike the Python version (which returns an async context manager),
+ * the JS MemorySaver and HttpCheckpointSaver do not require async
+ * initialization or cleanup. This function is kept async to accommodate
+ * future backends that might need setup (e.g. SQLite connection).
+ */
+export async function createCheckpointer(
+  config: CheckpointerConfig,
+): Promise<BaseCheckpointSaver> {
+  switch (config.type) {
+    case "memory":
+      console.log("Created MemorySaver checkpointer (ephemeral, in-memory)");
+      return new MemorySaver();
+
+    case "http": {
+      if (!config.proxyEndpoint) {
+        throw new CheckpointerCreationError(
+          "http",
+          "proxyEndpoint is required for HTTP checkpointer",
+        );
+      }
+      if (!config.authToken) {
+        throw new CheckpointerCreationError(
+          "http",
+          "authToken is required for HTTP checkpointer",
+        );
+      }
+      const saver = new HttpCheckpointSaver(config.proxyEndpoint, config.authToken);
+      console.log(`Created HttpCheckpointSaver checkpointer (proxy=${config.proxyEndpoint})`);
+      return saver;
+    }
+
+    default: {
+      const exhaustive: never = config.type;
+      throw new CheckpointerCreationError(
+        String(exhaustive),
+        `Unknown checkpointer type. Valid types: memory, http`,
+      );
+    }
+  }
+}

package/src/shared/checkpointer/http-saver.ts

@@ -0,0 +1,349 @@
+/**
+ * HTTP-backed LangGraph checkpoint saver.
+ *
+ * Routes checkpoint persistence through the Stigmer Side-Channel Proxy
+ * (api.stigmer.ai/v1/proxy) instead of connecting directly to MongoDB.
+ * The runner never touches MongoDB — the Java CheckpointerProxyController
+ * handles all database operations server-side.
+ *
+ * Serialization uses the LangGraph JsonPlusSerializer. Binary payloads
+ * are transported as MongoDB Extended JSON v2 $binary objects:
+ *
+ *   {"$binary": {"base64": "<base64-data>", "subType": "00"}}
+ *
+ * The Java proxy calls Document.parse(json) which handles $binary
+ * natively, and doc.toJson() emits the same format on reads.
+ */
+
+import type { RunnableConfig } from "@langchain/core/runnables";
+import {
+  BaseCheckpointSaver,
+  type Checkpoint,
+  type CheckpointListOptions,
+  type CheckpointPendingWrite,
+  type CheckpointTuple,
+  type ChannelVersions,
+} from "@langchain/langgraph-checkpoint";
+import type { CheckpointMetadata, PendingWrite } from "@langchain/langgraph-checkpoint";
+
+function encodeB64(data: Uint8Array): string {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(data).toString("base64");
+  }
+  let binary = "";
+  for (const byte of data) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+}
+
+function decodeB64(b64: string): Uint8Array {
+  if (typeof Buffer !== "undefined") {
+    return new Uint8Array(Buffer.from(b64, "base64"));
+  }
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+interface BinaryObj {
+  $binary: { base64: string; subType: string };
+}
+
+function encodeBinary(payload: Uint8Array): BinaryObj {
+  return { $binary: { base64: encodeB64(payload), subType: "00" } };
+}
+
+function decodeBinary(obj: BinaryObj): Uint8Array {
+  return decodeB64(obj.$binary.base64);
+}
+
+function configThread(config: RunnableConfig): string {
+  return (config.configurable?.thread_id as string) ?? "";
+}
+
+function configNs(config: RunnableConfig): string {
+  return (config.configurable?.checkpoint_ns as string) ?? "";
+}
+
+function configCheckpointId(config: RunnableConfig): string | undefined {
+  return config.configurable?.checkpoint_id as string | undefined;
+}
+
+function configOrg(config: RunnableConfig): string | undefined {
+  return config.configurable?.org as string | undefined;
+}
+
+export class HttpCheckpointSaver extends BaseCheckpointSaver {
+  private readonly baseUrl: string;
+  private readonly headers: Record<string, string>;
+
+  constructor(proxyEndpoint: string, authToken: string) {
+    super();
+    this.baseUrl = `${proxyEndpoint.replace(/\/+$/, "")}/v1/proxy/checkpoints`;
+    this.headers = {
+      Authorization: `Bearer ${authToken}`,
+      "Content-Type": "application/json",
+    };
+  }
+
+  private async serializeTyped(obj: unknown): Promise<[string, BinaryObj]> {
+    const [typeTag, payload] = await this.serde.dumpsTyped(obj);
+    return [typeTag, encodeBinary(payload)];
+  }
+
+  private async deserializeTyped(typeTag: string, binaryObj: BinaryObj): Promise<unknown> {
+    const payload = decodeBinary(binaryObj);
+    return this.serde.loadsTyped(typeTag, payload);
+  }
+
+  async getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined> {
+    const threadId = configThread(config);
+    const checkpointNs = configNs(config);
+    const checkpointId = configCheckpointId(config);
+
+    const params = new URLSearchParams({
+      thread_id: threadId,
+      checkpoint_ns: checkpointNs,
+    });
+    if (checkpointId) {
+      params.set("checkpoint_id", checkpointId);
+    }
+
+    const resp = await fetch(`${this.baseUrl}/checkpoint?${params}`, {
+      headers: this.headers,
+    });
+    if (resp.status === 404) return undefined;
+    if (!resp.ok) {
+      throw new Error(`Checkpoint GET failed: ${resp.status} ${resp.statusText}`);
+    }
+
+    const doc = (await resp.json()) as Record<string, any>;
+    return this.parseCheckpointDoc(doc, threadId, checkpointNs);
+  }
+
+  async *list(
+    config: RunnableConfig,
+    options?: CheckpointListOptions,
+  ): AsyncGenerator<CheckpointTuple> {
+    const threadId = configThread(config);
+    const checkpointNs = configNs(config);
+    const limit = options?.limit ?? 10;
+
+    const params = new URLSearchParams({
+      thread_id: threadId,
+      checkpoint_ns: checkpointNs,
+      limit: String(limit),
+    });
+    const beforeId = options?.before?.configurable?.checkpoint_id as string | undefined;
+    if (beforeId) {
+      params.set("before", beforeId);
+    }
+
+    const resp = await fetch(`${this.baseUrl}/checkpoints?${params}`, {
+      headers: this.headers,
+    });
+    if (!resp.ok) {
+      throw new Error(`Checkpoints list failed: ${resp.status} ${resp.statusText}`);
+    }
+
+    const data = (await resp.json()) as { checkpoints?: Record<string, any>[] };
+    for (const doc of data.checkpoints ?? []) {
+      yield await this.parseCheckpointDocWithoutWrites(doc);
+    }
+  }
+
+  async put(
+    config: RunnableConfig,
+    checkpoint: Checkpoint,
+    metadata: CheckpointMetadata,
+    _newVersions: ChannelVersions,
+  ): Promise<RunnableConfig> {
+    const threadId = configThread(config);
+    const checkpointNs = configNs(config);
+    const checkpointId = checkpoint.id;
+
+    const [cpType, cpBinary] = await this.serializeTyped(checkpoint);
+    const [mdType, mdBinary] = await this.serializeTyped(metadata);
+
+    const doc: Record<string, unknown> = {
+      thread_id: threadId,
+      checkpoint_ns: checkpointNs,
+      checkpoint_id: checkpointId,
+      parent_checkpoint_id: configCheckpointId(config),
+      type: cpType,
+      checkpoint: cpBinary,
+      metadata_type: mdType,
+      metadata: mdBinary,
+    };
+
+    const orgId = configOrg(config);
+    if (orgId) doc.org_id = orgId;
+
+    const resp = await fetch(`${this.baseUrl}/checkpoint`, {
+      method: "PUT",
+      headers: this.headers,
+      body: JSON.stringify(doc),
+    });
+    if (!resp.ok) {
+      throw new Error(`Checkpoint PUT failed: ${resp.status} ${resp.statusText}`);
+    }
+
+    return {
+      configurable: {
+        thread_id: threadId,
+        checkpoint_ns: checkpointNs,
+        checkpoint_id: checkpointId,
+      },
+    };
+  }
+
+  async deleteThread(threadId: string): Promise<void> {
+    const params = new URLSearchParams({ thread_id: threadId });
+    const resp = await fetch(`${this.baseUrl}/thread?${params}`, {
+      method: "DELETE",
+      headers: this.headers,
+    });
+    if (!resp.ok && resp.status !== 404) {
+      throw new Error(`Checkpoint DELETE thread failed: ${resp.status} ${resp.statusText}`);
+    }
+  }
+
+  async putWrites(
+    config: RunnableConfig,
+    writes: PendingWrite[],
+    taskId: string,
+  ): Promise<void> {
+    const threadId = configThread(config);
+    const checkpointNs = configNs(config);
+    const checkpointId = configCheckpointId(config);
+    const orgId = configOrg(config);
+
+    const docs = await Promise.all(writes.map(async ([channel, value], idx) => {
+      const [typeTag, binaryVal] = await this.serializeTyped(value);
+      const doc: Record<string, unknown> = {
+        thread_id: threadId,
+        checkpoint_ns: checkpointNs,
+        checkpoint_id: checkpointId,
+        task_id: taskId,
+        idx,
+        channel,
+        type: typeTag,
+        value: binaryVal,
+      };
+      if (orgId) doc.org_id = orgId;
+      return doc;
+    }));
+
+    const resp = await fetch(`${this.baseUrl}/writes`, {
+      method: "PUT",
+      headers: this.headers,
+      body: JSON.stringify({ writes: docs }),
+    });
+    if (!resp.ok) {
+      throw new Error(`Checkpoint writes PUT failed: ${resp.status} ${resp.statusText}`);
+    }
+  }
+
+  private async parseCheckpointDoc(
+    doc: Record<string, any>,
+    threadId: string,
+    checkpointNs: string,
+  ): Promise<CheckpointTuple> {
+    const cpType = doc.type ?? "json";
+    const checkpoint = (await this.deserializeTyped(cpType, doc.checkpoint)) as Checkpoint;
+
+    const mdType = doc.metadata_type ?? cpType;
+    const metadata = doc.metadata
+      ? ((await this.deserializeTyped(mdType, doc.metadata)) as CheckpointMetadata)
+      : undefined;
+
+    let parentConfig: RunnableConfig | undefined;
+    if (doc.parent_checkpoint_id) {
+      parentConfig = {
+        configurable: {
+          thread_id: doc.thread_id,
+          checkpoint_ns: doc.checkpoint_ns ?? "",
+          checkpoint_id: doc.parent_checkpoint_id,
+        },
+      };
+    }
+
+    const writesResp = await fetch(
+      `${this.baseUrl}/writes?${new URLSearchParams({
+        thread_id: threadId,
+        checkpoint_ns: checkpointNs,
+        checkpoint_id: doc.checkpoint_id,
+      })}`,
+      { headers: this.headers },
+    );
+    const pendingWrites = await this.parseWrites(
+      writesResp.ok ? (await writesResp.json()) as Record<string, any> : {},
+    );
+
+    return {
+      config: {
+        configurable: {
+          thread_id: doc.thread_id,
+          checkpoint_ns: doc.checkpoint_ns ?? "",
+          checkpoint_id: doc.checkpoint_id,
+        },
+      },
+      checkpoint,
+      metadata,
+      parentConfig,
+      pendingWrites,
+    };
+  }
+
+  private async parseCheckpointDocWithoutWrites(
+    doc: Record<string, any>,
+  ): Promise<CheckpointTuple> {
+    const cpType = doc.type ?? "json";
+    const checkpoint = (await this.serde.loadsTyped(cpType, decodeBinary(doc.checkpoint))) as Checkpoint;
+
+    const mdType = doc.metadata_type ?? cpType;
+    const metadata = doc.metadata
+      ? ((await this.serde.loadsTyped(mdType, decodeBinary(doc.metadata))) as CheckpointMetadata)
+      : undefined;
+
+    let parentConfig: RunnableConfig | undefined;
+    if (doc.parent_checkpoint_id) {
+      parentConfig = {
+        configurable: {
+          thread_id: doc.thread_id,
+          checkpoint_ns: doc.checkpoint_ns ?? "",
+          checkpoint_id: doc.parent_checkpoint_id,
+        },
+      };
+    }
+
+    return {
+      config: {
+        configurable: {
+          thread_id: doc.thread_id,
+          checkpoint_ns: doc.checkpoint_ns ?? "",
+          checkpoint_id: doc.checkpoint_id,
+        },
+      },
+      checkpoint,
+      metadata,
+      parentConfig,
+    };
+  }
+
+  private async parseWrites(
+    data: Record<string, any>,
+  ): Promise<CheckpointPendingWrite[]> {
+    const result: CheckpointPendingWrite[] = [];
+    for (const w of data.writes ?? []) {
+      const wType = w.type ?? "json";
+      const value = await this.serde.loadsTyped(wType, decodeBinary(w.value));
+      result.push([w.task_id, w.channel, value]);
+    }
+    return result;
+  }
+}

package/src/shared/checkpointer/types.ts

@@ -0,0 +1,12 @@
+/**
+ * Configuration for the checkpointer factory.
+ *
+ * Two backends are supported:
+ * - memory: ephemeral in-process storage (OSS / local development)
+ * - http: routes through the Stigmer Side-Channel Proxy (cloud)
+ */
+export interface CheckpointerConfig {
+  readonly type: "memory" | "http";
+  readonly proxyEndpoint?: string;
+  readonly authToken?: string;
+}