@stigmer/runner 3.0.1

package/dist/shared/artifact-storage.js

@@ -0,0 +1,162 @@
+/**
+ * Artifact storage abstraction for the unified runner.
+ *
+ * Two backends:
+ * - Local: writes to the filesystem, served by stigmer-server (OSS mode).
+ * - Proxy: uses presigned URLs from the Stigmer Side-Channel Proxy (cloud mode).
+ *
+ * The runner never holds R2/S3 credentials — in cloud mode it calls the proxy
+ * to obtain a presigned upload URL, then PUTs content over plain HTTPS.
+ *
+ * DD-6: No direct R2 backend. Local + Proxy only.
+ */
+import { mkdir, writeFile, access } from "node:fs/promises";
+import { dirname, join } from "node:path";
+// ── Local Backend ────────────────────────────────────────────────────
+export class LocalArtifactStorage {
+    basePath;
+    serveUrlBase;
+    constructor(basePath, serveUrlBase) {
+        this.basePath = basePath;
+        this.serveUrlBase = serveUrlBase.replace(/\/+$/, "");
+    }
+    async upload(key, content, _contentType) {
+        const filePath = join(this.basePath, key);
+        await mkdir(dirname(filePath), { recursive: true });
+        await writeFile(filePath, content);
+        return key;
+    }
+    async getDownloadUrl(key) {
+        return `${this.serveUrlBase}/${key}`;
+    }
+    async exists(key) {
+        try {
+            await access(join(this.basePath, key));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+// ── Proxy Backend ────────────────────────────────────────────────────
+export class ProxyArtifactStorage {
+    baseUrl;
+    authToken;
+    constructor(proxyEndpoint, authToken) {
+        this.baseUrl = `${proxyEndpoint.replace(/\/+$/, "")}/v1/proxy/artifacts`;
+        this.authToken = authToken;
+    }
+    async upload(key, content, contentType) {
+        const ct = contentType ?? "application/octet-stream";
+        const presignResp = await fetch(`${this.baseUrl}/presigned-upload-url`, {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${this.authToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ key, content_type: ct }),
+        });
+        if (!presignResp.ok) {
+            throw new Error(`Failed to get presigned upload URL (HTTP ${presignResp.status}): ` +
+                await presignResp.text());
+        }
+        const data = await presignResp.json();
+        // Send exactly the headers the proxy signed. The presigner is the single
+        // source of truth for what must be on the wire: a SigV4 presigned PUT signs
+        // `content-type` (and `host`), so re-adding or duplicating any signed header
+        // changes its value and the store rejects the upload with
+        // `SignatureDoesNotMatch`. We therefore replay the signed set verbatim —
+        // never appending our own `Content-Type` when the signer already covered it.
+        // `host` is set by fetch from the URL and cannot be overridden, so drop it.
+        const signedHeaders = data.headers ?? {};
+        const uploadHeaders = {};
+        let contentTypeSigned = false;
+        for (const [name, value] of Object.entries(signedHeaders)) {
+            if (name.toLowerCase() === "host")
+                continue;
+            if (name.toLowerCase() === "content-type")
+                contentTypeSigned = true;
+            uploadHeaders[name] = value;
+        }
+        // Only set Content-Type ourselves if the presigner did NOT sign it (so the
+        // stored object still records the right type); when it IS signed, adding it
+        // would corrupt the signed value.
+        if (!contentTypeSigned) {
+            uploadHeaders["Content-Type"] = ct;
+        }
+        const putResp = await fetch(data.url, {
+            method: "PUT",
+            headers: uploadHeaders,
+            body: content,
+        });
+        if (!putResp.ok) {
+            throw new Error(`Presigned upload failed (HTTP ${putResp.status}): ` +
+                await putResp.text());
+        }
+        return key;
+    }
+    async getDownloadUrl(key) {
+        const resp = await fetch(`${this.baseUrl}/presigned-download-url`, {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${this.authToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ key }),
+        });
+        if (!resp.ok) {
+            throw new Error(`Failed to get presigned download URL (HTTP ${resp.status}): ` +
+                await resp.text());
+        }
+        const data = await resp.json();
+        return data.url;
+    }
+    async exists(key) {
+        try {
+            const resp = await fetch(`${this.baseUrl}/presigned-download-url`, {
+                method: "POST",
+                headers: {
+                    "Authorization": `Bearer ${this.authToken}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({ key }),
+            });
+            return resp.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+export function loadArtifactStorageConfig(config) {
+    // Storage follows transport, not execution location: if a proxy endpoint is
+    // configured, push artifacts through it (the proxy brokers R2). This holds for
+    // both cloud runners and the local desktop runner — the latter executes
+    // locally (mode === "local") yet still uploads via the proxy. An explicit
+    // ARTIFACT_STORAGE_TYPE always wins.
+    const envType = process.env.ARTIFACT_STORAGE_TYPE;
+    const type = envType === "proxy" ? "proxy" :
+        envType === "local" ? "local" :
+            config.proxyEndpoint ? "proxy" : "local";
+    return {
+        type,
+        localPath: process.env.LOCAL_ARTIFACT_PATH ?? "/var/stigmer/artifacts",
+        localServeUrl: process.env.LOCAL_ARTIFACT_SERVE_URL ?? "http://localhost:7235",
+        proxyEndpoint: type === "proxy" ? (config.proxyEndpoint ?? null) : null,
+        proxyAuthToken: type === "proxy" ? (config.stigmerToken ?? null) : null,
+    };
+}
+export function createArtifactStorage(cfg) {
+    if (cfg.type === "proxy") {
+        if (!cfg.proxyEndpoint) {
+            throw new Error("Proxy artifact storage requires STIGMER_PROXY_ENDPOINT");
+        }
+        if (!cfg.proxyAuthToken) {
+            throw new Error("Proxy artifact storage requires STIGMER_TOKEN");
+        }
+        return new ProxyArtifactStorage(cfg.proxyEndpoint, cfg.proxyAuthToken);
+    }
+    return new LocalArtifactStorage(cfg.localPath, cfg.localServeUrl);
+}
+//# sourceMappingURL=artifact-storage.js.map

package/dist/shared/artifact-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-storage.js","sourceRoot":"","sources":["../../src/shared/artifact-storage.ts"],"names":[],"mappings":"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"}

package/dist/shared/checkpointer/factory.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 type { BaseCheckpointSaver } from "@langchain/langgraph-checkpoint";
+import type { CheckpointerConfig } from "./types.js";
+export declare class CheckpointerCreationError extends Error {
+    readonly checkpointerType: string;
+    readonly cause?: Error;
+    constructor(type: string, message: string, cause?: Error);
+}
+/**
+ * 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 declare function createCheckpointer(config: CheckpointerConfig): Promise<BaseCheckpointSaver>;

package/dist/shared/checkpointer/factory.js

@@ -0,0 +1,55 @@
+/**
+ * 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 { HttpCheckpointSaver } from "./http-saver.js";
+export class CheckpointerCreationError extends Error {
+    checkpointerType;
+    cause;
+    constructor(type, message, cause) {
+        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) {
+    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 = config.type;
+            throw new CheckpointerCreationError(String(exhaustive), `Unknown checkpointer type. Valid types: memory, http`);
+        }
+    }
+}
+//# sourceMappingURL=factory.js.map

package/dist/shared/checkpointer/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../src/shared/checkpointer/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAG9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IACzC,gBAAgB,CAAS;IACzB,KAAK,CAAS;IAEvB,YAAY,IAAY,EAAE,OAAe,EAAE,KAAa;QACtD,KAAK,CAAC,oBAAoB,IAAI,kBAAkB,OAAO,EAAE,CAAC,CAAC;QAC3D,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC;QAC7B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAA0B;IAE1B,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,QAAQ;YACX,OAAO,CAAC,GAAG,CAAC,yDAAyD,CAAC,CAAC;YACvE,OAAO,IAAI,WAAW,EAAE,CAAC;QAE3B,KAAK,MAAM,CAAC,CAAC,CAAC;YACZ,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;gBAC1B,MAAM,IAAI,yBAAyB,CACjC,MAAM,EACN,iDAAiD,CAClD,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;gBACtB,MAAM,IAAI,yBAAyB,CACjC,MAAM,EACN,6CAA6C,CAC9C,CAAC;YACJ,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,mBAAmB,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;YAC9E,OAAO,CAAC,GAAG,CAAC,mDAAmD,MAAM,CAAC,aAAa,GAAG,CAAC,CAAC;YACxF,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,UAAU,GAAU,MAAM,CAAC,IAAI,CAAC;YACtC,MAAM,IAAI,yBAAyB,CACjC,MAAM,CAAC,UAAU,CAAC,EAClB,sDAAsD,CACvD,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/shared/checkpointer/http-saver.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 CheckpointTuple, type ChannelVersions } from "@langchain/langgraph-checkpoint";
+import type { CheckpointMetadata, PendingWrite } from "@langchain/langgraph-checkpoint";
+export declare class HttpCheckpointSaver extends BaseCheckpointSaver {
+    private readonly baseUrl;
+    private readonly headers;
+    constructor(proxyEndpoint: string, authToken: string);
+    private serializeTyped;
+    private deserializeTyped;
+    getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined>;
+    list(config: RunnableConfig, options?: CheckpointListOptions): AsyncGenerator<CheckpointTuple>;
+    put(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, _newVersions: ChannelVersions): Promise<RunnableConfig>;
+    deleteThread(threadId: string): Promise<void>;
+    putWrites(config: RunnableConfig, writes: PendingWrite[], taskId: string): Promise<void>;
+    private parseCheckpointDoc;
+    private parseCheckpointDocWithoutWrites;
+    private parseWrites;
+}

package/dist/shared/checkpointer/http-saver.js

@@ -0,0 +1,274 @@
+/**
+ * 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 { BaseCheckpointSaver, } from "@langchain/langgraph-checkpoint";
+function encodeB64(data) {
+    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) {
+    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;
+}
+function encodeBinary(payload) {
+    return { $binary: { base64: encodeB64(payload), subType: "00" } };
+}
+function decodeBinary(obj) {
+    return decodeB64(obj.$binary.base64);
+}
+function configThread(config) {
+    return config.configurable?.thread_id ?? "";
+}
+function configNs(config) {
+    return config.configurable?.checkpoint_ns ?? "";
+}
+function configCheckpointId(config) {
+    return config.configurable?.checkpoint_id;
+}
+function configOrg(config) {
+    return config.configurable?.org;
+}
+export class HttpCheckpointSaver extends BaseCheckpointSaver {
+    baseUrl;
+    headers;
+    constructor(proxyEndpoint, authToken) {
+        super();
+        this.baseUrl = `${proxyEndpoint.replace(/\/+$/, "")}/v1/proxy/checkpoints`;
+        this.headers = {
+            Authorization: `Bearer ${authToken}`,
+            "Content-Type": "application/json",
+        };
+    }
+    async serializeTyped(obj) {
+        const [typeTag, payload] = await this.serde.dumpsTyped(obj);
+        return [typeTag, encodeBinary(payload)];
+    }
+    async deserializeTyped(typeTag, binaryObj) {
+        const payload = decodeBinary(binaryObj);
+        return this.serde.loadsTyped(typeTag, payload);
+    }
+    async getTuple(config) {
+        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());
+        return this.parseCheckpointDoc(doc, threadId, checkpointNs);
+    }
+    async *list(config, options) {
+        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;
+        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());
+        for (const doc of data.checkpoints ?? []) {
+            yield await this.parseCheckpointDocWithoutWrites(doc);
+        }
+    }
+    async put(config, checkpoint, metadata, _newVersions) {
+        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 = {
+            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) {
+        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, writes, taskId) {
+        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 = {
+                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}`);
+        }
+    }
+    async parseCheckpointDoc(doc, threadId, checkpointNs) {
+        const cpType = doc.type ?? "json";
+        const checkpoint = (await this.deserializeTyped(cpType, doc.checkpoint));
+        const mdType = doc.metadata_type ?? cpType;
+        const metadata = doc.metadata
+            ? (await this.deserializeTyped(mdType, doc.metadata))
+            : undefined;
+        let parentConfig;
+        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()) : {});
+        return {
+            config: {
+                configurable: {
+                    thread_id: doc.thread_id,
+                    checkpoint_ns: doc.checkpoint_ns ?? "",
+                    checkpoint_id: doc.checkpoint_id,
+                },
+            },
+            checkpoint,
+            metadata,
+            parentConfig,
+            pendingWrites,
+        };
+    }
+    async parseCheckpointDocWithoutWrites(doc) {
+        const cpType = doc.type ?? "json";
+        const checkpoint = (await this.serde.loadsTyped(cpType, decodeBinary(doc.checkpoint)));
+        const mdType = doc.metadata_type ?? cpType;
+        const metadata = doc.metadata
+            ? (await this.serde.loadsTyped(mdType, decodeBinary(doc.metadata)))
+            : undefined;
+        let parentConfig;
+        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,
+        };
+    }
+    async parseWrites(data) {
+        const result = [];
+        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;
+    }
+}
+//# sourceMappingURL=http-saver.js.map

package/dist/shared/checkpointer/http-saver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-saver.js","sourceRoot":"","sources":["../../../src/shared/checkpointer/http-saver.ts"],"names":[],"mappings":"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"}

package/dist/shared/checkpointer/types.d.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;
+}

package/dist/shared/checkpointer/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/shared/checkpointer/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/shared/checkpointer/types.ts"],"names":[],"mappings":""}

package/dist/shared/connect-backfill.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Connect backfill for MCP servers without discovered capabilities.
+ *
+ * When an MCP server has empty discovered_capabilities, triggers the
+ * connect RPC to discover tools and classify approval policies via
+ * the LLM classifier. The connect RPC starts a Temporal workflow
+ * (discover + classify) and blocks until completion (~30 seconds).
+ *
+ * Backfill trigger: discovered_capabilities is empty or absent.
+ *
+ * Non-fatal: if connect fails for any server (permissions, timeout,
+ * unreachable), the original servers are kept and execution continues
+ * with empty policies. All tools from that server will require
+ * approval by default (fail-closed).
+ *
+ * This module is harness-agnostic — both ExecuteCursor and
+ * ExecuteDeepAgent use the same backfill logic. Each harness maps
+ * the returned ResolvedMcpServer[] into its SDK-specific format.
+ */
+import type { ResolvedMcpServer } from "./mcp-resolver.js";
+import type { StigmerClient } from "../client/stigmer-client.js";
+import type { McpServerUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+/**
+ * Check whether an MCP server needs a connect backfill.
+ *
+ * Returns true if the server has never been discovered (empty
+ * capabilities). Exported for testing.
+ */
+export declare function needsBackfill(server: ResolvedMcpServer): boolean;
+/**
+ * Run connect backfill for MCP servers that need it, then re-resolve
+ * to pick up the newly populated approval policies.
+ *
+ * Triggers the connect RPC synchronously for each server with empty
+ * discovered_capabilities. The RPC starts a Temporal workflow
+ * (discover + classify) and returns the updated McpServer.
+ *
+ * After at least one successful backfill, re-resolves ALL servers
+ * to pick up fresh policies. If no backfills succeed, returns the
+ * original servers unchanged.
+ */
+export declare function backfillMcpServersIfNeeded(client: StigmerClient, currentServers: ResolvedMcpServer[], usages: McpServerUsage[], envVars: Record<string, string>, org: string, onHeartbeat?: () => void, secretKeys?: ReadonlySet<string>): Promise<ResolvedMcpServer[]>;
+/**
+ * Extract the MCP server's required env vars from the execution
+ * environment. Returns only the keys declared in spec.env that are
+ * present in the merged environment.
+ *
+ * isSecret is derived from the MCP server's env declaration first,
+ * then from the execution-level secretKeys set, defaulting to false.
+ */
+export declare function extractRuntimeEnvForServer(server: {
+    spec?: {
+        env?: Record<string, unknown>;
+    };
+}, mergedEnv: Record<string, string>, secretKeys?: ReadonlySet<string>): Record<string, {
+    value: string;
+    isSecret: boolean;
+}> | undefined;