@mongodb-js/agent-engine-sdk-langgraph 0.11.3

package/dist/backends/toolpod.js

@@ -0,0 +1,451 @@
+/**
+ * AgentEngineToolPodBackend — routes deep-agent filesystem/shell ops through the
+ * secure path (SecureToolWrapper → Orchestration Engine → Tool Pod handlers).
+ *
+ * Port of Python `agent_engine_sdk_langgraph/backends/toolpod.py`, targeting
+ * deepagents' current V2 backend protocol (`SandboxBackendProtocolV2`): every
+ * method returns a structured Result object with an optional `error`, so a
+ * failure is surfaced through the same channel as success — never thrown into
+ * the graph and never leaking internal topology.
+ *
+ * The active `SecureToolWrapper` is read from the async-context store on every
+ * call (not captured at construction): LangGraph builds the backend on one task
+ * and invokes it on another, so a captured reference would be stale.
+ *
+ * Batch downloads (`downloadFiles`) fan out concurrently in native mode, with
+ * one `filesystem_download` call per file so OE policy and audit stay
+ * independent. Under a durable `AttemptContext` they stay sequential: unkeyed
+ * activities are exclusive on the attempt gate, and overlapping them raises
+ * CONFLICT.
+ */
+import { currentAttemptContext, getCurrentWrapper, getLogger, PolicyDeniedException, TerminalExecutionError, ToolCallTimeoutError, } from "@mongodb-js/agent-engine-runner-shared";
+const logger = getLogger("agent_engine_sdk_langgraph.backends.toolpod");
+const RETRYABLE = "[RETRYABLE]";
+const NON_RETRYABLE = "[NON-RETRYABLE]";
+const MAX_DOWNLOAD_WORKERS = 16;
+// Cluster-internal DNS suffixes (Kubernetes, consul, .local). Catches things
+// like `db.foo.svc.cluster.local` before the host:port pattern below does.
+const INTERNAL_DNS_RE = /\b[a-z0-9][a-z0-9.-]*\.(?:svc\.cluster\.local|cluster\.local|internal|local)\b/gi;
+// Bracketed IPv6 host:port (`[::1]:8080`, `[fd00::1]:27017`). Runs before the
+// alphanumeric host:port regex — that one's leading `[a-z0-9]` class can't
+// match `[`.
+const IPV6_HOST_PORT_RE = /\[[0-9a-fA-F:]+\]:\d{2,5}/g;
+// `host:port` where port is 2–5 digits. Runs after the DNS replacement so
+// `db.internal:27017` loses its port here rather than being orphaned.
+const HOST_PORT_RE = /\b[a-z0-9][a-z0-9.-]*:\d{2,5}\b/gi;
+// Any remaining multi-segment absolute path.
+const ABS_PATH_RE = /\/[^/\s"'()]+(?:\/[^/\s"'()]*)*/g;
+/**
+ * Strip internal topology (workspace path, cluster hostnames/ports, absolute
+ * paths) from a handler-supplied error string before it reaches the agent
+ * graph. Mirrors Python `_sanitize_handler_error`: the "no internal
+ * hostnames/ports/paths" invariant applies to handler errors, not only
+ * exception-derived ones. Order matters — host:port pairs are consumed before
+ * bare DNS names so a port is never left orphaned.
+ */
+function sanitizeHandlerError(message) {
+    let out = message;
+    const workspace = process.env["WORKSPACE_DIR"]?.replace(/\/+$/, "");
+    if (workspace)
+        out = out.split(workspace).join("<workspace>");
+    out = out.replace(IPV6_HOST_PORT_RE, "<host>");
+    out = out.replace(HOST_PORT_RE, "<host>");
+    out = out.replace(INTERNAL_DNS_RE, "<host>");
+    return out.replace(ABS_PATH_RE, "<path>");
+}
+/**
+ * Classify a thrown error as retryable or non-retryable and return a generic,
+ * topology-free description. Full details are logged by the caller; only this
+ * category string reaches the agent. Mirrors Python `_classify_error`.
+ *
+ * PolicyDenied and programming errors (TypeError/RangeError etc., and the
+ * "no wrapper in context" RuntimeError) are non-retryable — retrying with the
+ * same inputs can never succeed. Everything else defaults to retryable so the
+ * agent doesn't give up on a transient.
+ */
+function classifyError(exc) {
+    if (exc instanceof PolicyDeniedException) {
+        return `${NON_RETRYABLE} Policy denied this operation`;
+    }
+    if (exc instanceof TerminalExecutionError) {
+        return `${NON_RETRYABLE} This execution already ended`;
+    }
+    if (exc instanceof ToolCallTimeoutError) {
+        // Non-retryable: the call already consumed its whole deadline, so an
+        // automatic retry spends another full one to most likely fail the same way.
+        // The agent decides whether the work is worth re-attempting.
+        return `${NON_RETRYABLE} Operation timed out`;
+    }
+    if (exc instanceof TypeError ||
+        exc instanceof RangeError ||
+        exc instanceof ReferenceError ||
+        exc instanceof SyntaxError ||
+        exc instanceof MissingWrapperError) {
+        return `${NON_RETRYABLE} Programming error — retry will not help`;
+    }
+    return `${RETRYABLE} Operation failed`;
+}
+/** Raised when the backend is used outside an AER execution context. */
+class MissingWrapperError extends Error {
+}
+function getWrapper() {
+    const wrapper = getCurrentWrapper();
+    if (wrapper == null) {
+        throw new MissingWrapperError("No SecureToolWrapper in context — " +
+            "AgentEngineToolPodBackend must run inside AER execution");
+    }
+    return wrapper;
+}
+/** Truthy `error` field on a handler result, sanitized; else undefined. */
+function handlerError(result) {
+    const err = result["error"];
+    return err ? sanitizeHandlerError(String(err)) : undefined;
+}
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Human-readable type for protocol-violation messages (`typeof [] === "object"`). */
+function describeType(v) {
+    if (v === null)
+        return "null";
+    if (Array.isArray(v))
+        return "array";
+    return typeof v;
+}
+/**
+ * Backend that routes every operation through Atlas Agent Engine's secure path. Each
+ * method delegates to `SecureToolWrapper.executeTool`, which sends the request
+ * to the OE for policy approval and audit logging before it runs in the Tool
+ * Pod.
+ */
+export class AgentEngineToolPodBackend {
+    id = "agent-engine-toolpod";
+    /**
+     * Execute a Tool Pod handler through the secure wrapper. Returns the wire
+     * result on success, or a classified `[RETRYABLE]`/`[NON-RETRYABLE]` error
+     * string on failure (exceptions are logged and translated, never rethrown).
+     */
+    async call(toolName, args) {
+        try {
+            const wrapper = getWrapper();
+            const raw = await wrapper.executeTool(toolName, args, { isLocal: false });
+            if (isObject(raw))
+                return { ok: true, result: raw };
+            return {
+                ok: false,
+                error: `${NON_RETRYABLE} ${toolName} protocol violation: ` +
+                    `expected object, got ${describeType(raw)}`,
+            };
+        }
+        catch (exc) {
+            const msg = classifyError(exc);
+            logger.warn(`Tool call ${toolName} failed: ${String(exc)}`);
+            return { ok: false, error: msg };
+        }
+    }
+    // ------------------------------------------------------------------
+    // Read operations
+    // ------------------------------------------------------------------
+    async ls(path) {
+        const outcome = await this.call("filesystem_ls", { path });
+        if (!outcome.ok)
+            return { error: outcome.error };
+        const { result } = outcome;
+        const handlerErr = handlerError(result);
+        if (handlerErr !== undefined)
+            return { error: handlerErr };
+        const entries = result["entries"];
+        if (!Array.isArray(entries)) {
+            return {
+                error: `${NON_RETRYABLE} filesystem_ls protocol violation: 'entries' not an array`,
+            };
+        }
+        return mapFileInfos(entries, "filesystem_ls", "entry");
+    }
+    async read(filePath, offset = 0, limit = 2000) {
+        const outcome = await this.call("filesystem_read", {
+            file_path: filePath,
+            offset,
+            limit,
+        });
+        if (!outcome.ok)
+            return { error: outcome.error };
+        const { result } = outcome;
+        const handlerErr = handlerError(result);
+        if (handlerErr !== undefined)
+            return { error: handlerErr };
+        const content = result["content"];
+        if (typeof content !== "string") {
+            return {
+                error: `${NON_RETRYABLE} filesystem_read protocol violation: 'content' not a string`,
+            };
+        }
+        return { content, mimeType: "text/plain" };
+    }
+    /**
+     * Raw read is not backed by a dedicated wire handler; the Tool Pod exposes
+     * only line-oriented `filesystem_read`. We wrap its text content in a v2
+     * FileData so binary-unaware callers still work. Genuine binary reads should
+     * use `downloadFiles`, which carries raw bytes base64-encoded.
+     */
+    async readRaw(filePath) {
+        const res = await this.read(filePath);
+        if (res.error !== undefined)
+            return { error: res.error };
+        const now = new Date().toISOString();
+        const data = {
+            content: res.content ?? "",
+            mimeType: res.mimeType ?? "text/plain",
+            created_at: now,
+            modified_at: now,
+        };
+        return { data };
+    }
+    async grep(pattern, path, glob) {
+        const args = { pattern };
+        if (path != null)
+            args["path"] = path;
+        if (glob != null)
+            args["glob"] = glob;
+        const outcome = await this.call("filesystem_grep", args);
+        if (!outcome.ok)
+            return { error: outcome.error };
+        const { result } = outcome;
+        const handlerErr = handlerError(result);
+        if (handlerErr !== undefined)
+            return { error: handlerErr };
+        const raw = result["matches"];
+        if (!Array.isArray(raw)) {
+            return {
+                error: `${NON_RETRYABLE} filesystem_grep protocol violation: 'matches' not an array`,
+            };
+        }
+        const matches = [];
+        for (const m of raw) {
+            // Validate each element rather than coercing — an unchecked
+            // `Number(o["line"])` / `String(o["path"])` would silently yield `NaN` /
+            // `"undefined"` on a malformed element instead of surfacing the
+            // protocol violation, matching the array-shape checks above.
+            if (!isObject(m) ||
+                typeof m["path"] !== "string" ||
+                typeof m["line"] !== "number" ||
+                typeof m["text"] !== "string") {
+                return {
+                    error: `${NON_RETRYABLE} filesystem_grep protocol violation: malformed match (expected {path: string, line: number, text: string})`,
+                };
+            }
+            matches.push({ path: m["path"], line: m["line"], text: m["text"] });
+        }
+        return { matches };
+    }
+    async glob(pattern, path = "/") {
+        const outcome = await this.call("filesystem_glob", {
+            pattern,
+            path,
+        });
+        if (!outcome.ok)
+            return { error: outcome.error };
+        const { result } = outcome;
+        const handlerErr = handlerError(result);
+        if (handlerErr !== undefined)
+            return { error: handlerErr };
+        const raw = result["matches"];
+        if (!Array.isArray(raw)) {
+            return {
+                error: `${NON_RETRYABLE} filesystem_glob protocol violation: 'matches' not an array`,
+            };
+        }
+        return mapFileInfos(raw, "filesystem_glob", "match");
+    }
+    // ------------------------------------------------------------------
+    // Write operations
+    // ------------------------------------------------------------------
+    async write(filePath, content) {
+        const outcome = await this.call("filesystem_write", {
+            file_path: filePath,
+            content,
+        });
+        if (!outcome.ok)
+            return { error: outcome.error };
+        const { result } = outcome;
+        const handlerErr = handlerError(result);
+        if (handlerErr !== undefined)
+            return { error: handlerErr };
+        const path = result["path"];
+        if (typeof path !== "string") {
+            return {
+                error: `${NON_RETRYABLE} filesystem_write protocol violation: success response missing 'path' string`,
+            };
+        }
+        return { path };
+    }
+    async edit(filePath, oldString, newString, replaceAll = false) {
+        const outcome = await this.call("filesystem_edit", {
+            file_path: filePath,
+            old_string: oldString,
+            new_string: newString,
+            replace_all: replaceAll,
+        });
+        if (!outcome.ok)
+            return { error: outcome.error };
+        const { result } = outcome;
+        const handlerErr = handlerError(result);
+        if (handlerErr !== undefined)
+            return { error: handlerErr };
+        const occurrences = result["occurrences"];
+        if (typeof occurrences !== "number") {
+            return {
+                error: `${NON_RETRYABLE} filesystem_edit protocol violation: success response missing 'occurrences' int`,
+            };
+        }
+        return { path: filePath, occurrences };
+    }
+    // ------------------------------------------------------------------
+    // Shell execution
+    // ------------------------------------------------------------------
+    async execute(command) {
+        const outcome = await this.call("shell_execute", { command });
+        if (!outcome.ok) {
+            return { output: outcome.error, exitCode: 1, truncated: false };
+        }
+        const { result } = outcome;
+        // A framework error (e.g. missing /bin/sh) returns an `error` field
+        // alongside a non-zero exit_code and empty output. Surface the sanitized
+        // message — otherwise the agent sees only an empty output + exit code and
+        // loses the cause — and preserve the handler's exit code.
+        const handlerErr = handlerError(result);
+        if (handlerErr !== undefined) {
+            const code = result["exit_code"];
+            return {
+                output: handlerErr,
+                exitCode: typeof code === "number" ? code : 1,
+                truncated: false,
+            };
+        }
+        const output = result["output"];
+        const exitCode = result["exit_code"];
+        if (typeof output !== "string" || typeof exitCode !== "number") {
+            return {
+                output: `${NON_RETRYABLE} shell_execute protocol violation: response must contain str 'output' and int 'exit_code'`,
+                exitCode: 1,
+                truncated: false,
+            };
+        }
+        return {
+            output,
+            exitCode,
+            truncated: Boolean(result["truncated"]),
+        };
+    }
+    // ------------------------------------------------------------------
+    // Download / upload
+    // ------------------------------------------------------------------
+    /**
+     * Download a single path. Never throws: failures become error responses.
+     */
+    async downloadOne(path) {
+        const outcome = await this.call("filesystem_download", {
+            file_path: path,
+        });
+        if (!outcome.ok) {
+            return downloadError(path, outcome.error);
+        }
+        const { result } = outcome;
+        const handlerErr = handlerError(result);
+        if (handlerErr !== undefined) {
+            return downloadError(path, handlerErr);
+        }
+        const b64 = result["content_base64"];
+        if (typeof b64 !== "string") {
+            return downloadError(path, `${NON_RETRYABLE} filesystem_download protocol violation: success response missing 'content_base64' field`);
+        }
+        return {
+            path,
+            content: new Uint8Array(Buffer.from(b64, "base64")),
+            error: null,
+        };
+    }
+    /**
+     * Download files via the audited `filesystem_download` handler — one call per
+     * path so each is policy-checked and logged independently — then base64-decode
+     * the `content_base64` field into raw bytes. Responses preserve input order;
+     * on failure `content` is null and `error` carries a classified message.
+     *
+     * Native-mode batches fan out on a bounded worker pool so skills loading
+     * pays one round-trip of latency instead of a sum. Durable attempts stay
+     * sequential: unkeyed activities are exclusive under the attempt gate, and
+     * overlapping them raises CONFLICT.
+     */
+    async downloadFiles(paths) {
+        if (paths.length <= 1 || currentAttemptContext() != null) {
+            // Single path skips pool overhead. Durable attempts stay sequential:
+            // unkeyed activities are exclusive under the attempt gate, and
+            // overlapping them raises CONFLICT.
+            const responses = [];
+            for (const path of paths) {
+                responses.push(await this.downloadOne(path));
+            }
+            return responses;
+        }
+        return mapLimited(paths, MAX_DOWNLOAD_WORKERS, (path) => this.downloadOne(path));
+    }
+    async uploadFiles(files) {
+        // Return per-file classified errors rather than throwing — a raw throw
+        // would bypass the [RETRYABLE]/[NON-RETRYABLE] contract every other method
+        // honours. No wire handler exists for upload yet.
+        const err = `${NON_RETRYABLE} uploadFiles is not implemented`;
+        return files.map(([path]) => uploadError(path, err));
+    }
+}
+/**
+ * Map raw wire entries to `FileInfo[]`, validating each element. A malformed
+ * element (not an object, or a non-string `path`) fails the whole result with a
+ * protocol-violation error rather than coercing to `String(undefined)` — the
+ * same all-or-nothing contract the array-shape checks in `ls`/`glob` use.
+ * `handler`/`elem` name the source for the error message.
+ */
+function mapFileInfos(entries, handler, elem) {
+    const files = [];
+    for (const e of entries) {
+        if (!isObject(e) || typeof e["path"] !== "string") {
+            return {
+                error: `${NON_RETRYABLE} ${handler} protocol violation: malformed ${elem} (expected object with string 'path')`,
+            };
+        }
+        files.push({ path: e["path"], is_dir: Boolean(e["is_dir"]) });
+    }
+    return { files };
+}
+// `FileDownloadResponse.error` / `FileUploadResponse.error` are typed as a
+// `FileOperationError` enum in the deepagents protocol. We deliberately ship
+// richer strings — sanitized handler messages and [RETRYABLE]/[NON-RETRYABLE]
+// prefixes — so the agent can tell transients from contract bugs. The cast is
+// parked once on each helper instead of at every call site.
+function downloadError(path, err) {
+    return { path, content: null, error: err };
+}
+/**
+ * Run `fn` over `items` with at most `limit` in-flight promises. Result[i]
+ * corresponds to items[i] even when completions finish out of order.
+ */
+async function mapLimited(items, limit, fn) {
+    const results = new Array(items.length);
+    let cursor = 0;
+    async function worker() {
+        while (cursor < items.length) {
+            const index = cursor;
+            cursor += 1;
+            const item = items[index];
+            if (item === undefined)
+                return;
+            results[index] = await fn(item);
+        }
+    }
+    const workers = Math.min(limit, items.length);
+    await Promise.all(Array.from({ length: workers }, () => worker()));
+    return results;
+}
+function uploadError(path, err) {
+    return { path, error: err };
+}
+//# sourceMappingURL=toolpod.js.map

package/dist/backends/toolpod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolpod.js","sourceRoot":"","sources":["../../src/backends/toolpod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAkBH,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,SAAS,EACT,qBAAqB,EACrB,sBAAsB,EACtB,oBAAoB,GAErB,MAAM,wCAAwC,CAAC;AAEhD,MAAM,MAAM,GAAG,SAAS,CAAC,6CAA6C,CAAC,CAAC;AAExE,MAAM,SAAS,GAAG,aAAa,CAAC;AAChC,MAAM,aAAa,GAAG,iBAAiB,CAAC;AACxC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEhC,6EAA6E;AAC7E,2EAA2E;AAC3E,MAAM,eAAe,GACnB,kFAAkF,CAAC;AACrF,8EAA8E;AAC9E,2EAA2E;AAC3E,aAAa;AACb,MAAM,iBAAiB,GAAG,4BAA4B,CAAC;AACvD,0EAA0E;AAC1E,sEAAsE;AACtE,MAAM,YAAY,GAAG,mCAAmC,CAAC;AACzD,6CAA6C;AAC7C,MAAM,WAAW,GAAG,kCAAkC,CAAC;AAEvD;;;;;;;GAOG;AACH,SAAS,oBAAoB,CAAC,OAAe;IAC3C,IAAI,GAAG,GAAG,OAAO,CAAC;IAClB,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACpE,IAAI,SAAS;QAAE,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC9D,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,iBAAiB,EAAE,QAAQ,CAAC,CAAC;IAC/C,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IAC1C,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC;IAC7C,OAAO,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,aAAa,CAAC,GAAY;IACjC,IAAI,GAAG,YAAY,qBAAqB,EAAE,CAAC;QACzC,OAAO,GAAG,aAAa,+BAA+B,CAAC;IACzD,CAAC;IACD,IAAI,GAAG,YAAY,sBAAsB,EAAE,CAAC;QAC1C,OAAO,GAAG,aAAa,+BAA+B,CAAC;IACzD,CAAC;IACD,IAAI,GAAG,YAAY,oBAAoB,EAAE,CAAC;QACxC,qEAAqE;QACrE,4EAA4E;QAC5E,6DAA6D;QAC7D,OAAO,GAAG,aAAa,sBAAsB,CAAC;IAChD,CAAC;IACD,IACE,GAAG,YAAY,SAAS;QACxB,GAAG,YAAY,UAAU;QACzB,GAAG,YAAY,cAAc;QAC7B,GAAG,YAAY,WAAW;QAC1B,GAAG,YAAY,mBAAmB,EAClC,CAAC;QACD,OAAO,GAAG,aAAa,0CAA0C,CAAC;IACpE,CAAC;IACD,OAAO,GAAG,SAAS,mBAAmB,CAAC;AACzC,CAAC;AAED,wEAAwE;AACxE,MAAM,mBAAoB,SAAQ,KAAK;CAAG;AAE1C,SAAS,UAAU;IACjB,MAAM,OAAO,GAAG,iBAAiB,EAA8B,CAAC;IAChE,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;QACpB,MAAM,IAAI,mBAAmB,CAC3B,oCAAoC;YAClC,yDAAyD,CAC5D,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAaD,2EAA2E;AAC3E,SAAS,YAAY,CAAC,MAAkB;IACtC,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAC5B,OAAO,GAAG,CAAC,CAAC,CAAC,oBAAoB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7D,CAAC;AAED,SAAS,QAAQ,CAAC,CAAU;IAC1B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,sFAAsF;AACtF,SAAS,YAAY,CAAC,CAAU;IAC9B,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAC9B,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,OAAO,CAAC;IACrC,OAAO,OAAO,CAAC,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,yBAAyB;IAC3B,EAAE,GAAG,sBAAsB,CAAC;IAErC;;;;OAIG;IACK,KAAK,CAAC,IAAI,CAChB,QAAgB,EAChB,IAA6B;QAE7B,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;YAC7B,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;YAC1E,IAAI,QAAQ,CAAC,GAAG,CAAC;gBAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;YACpD,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,KAAK,EACH,GAAG,aAAa,IAAI,QAAQ,uBAAuB;oBACnD,wBAAwB,YAAY,CAAC,GAAG,CAAC,EAAE;aAC9C,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,GAAG,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;YAC/B,MAAM,CAAC,IAAI,CAAC,aAAa,QAAQ,YAAY,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC5D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;QACnC,CAAC;IACH,CAAC;IAED,qEAAqE;IACrE,kBAAkB;IAClB,qEAAqE;IAErE,KAAK,CAAC,EAAE,CAAC,IAAY;QACnB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3D,IAAI,CAAC,OAAO,CAAC,EAAE;YAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QACjD,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAC3B,MAAM,UAAU,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAE3D,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,OAAO;gBACL,KAAK,EAAE,GAAG,aAAa,2DAA2D;aACnF,CAAC;QACJ,CAAC;QACD,OAAO,YAAY,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,CAAC,CAAC;IACzD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,QAAgB,EAAE,MAAM,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI;QACnD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE;YACjD,SAAS,EAAE,QAAQ;YACnB,MAAM;YACN,KAAK;SACN,CAAC,CAAC;QACH,IAAI,CAAC,OAAO,CAAC,EAAE;YAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QACjD,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAC3B,MAAM,UAAU,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAE3D,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;QAClC,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAChC,OAAO;gBACL,KAAK,EAAE,GAAG,aAAa,6DAA6D;aACrF,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,CAAC;IAC7C,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAO,CAAC,QAAgB;QAC5B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACtC,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS;YAAE,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC;QACzD,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,IAAI,GAAa;YACrB,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,EAAE;YAC1B,QAAQ,EAAE,GAAG,CAAC,QAAQ,IAAI,YAAY;YACtC,UAAU,EAAE,GAAG;YACf,WAAW,EAAE,GAAG;SACjB,CAAC;QACF,OAAO,EAAE,IAAI,EAAE,CAAC;IAClB,CAAC;IAED,KAAK,CAAC,IAAI,CACR,OAAe,EACf,IAAoB,EACpB,IAAoB;QAEpB,MAAM,IAAI,GAA4B,EAAE,OAAO,EAAE,CAAC;QAClD,IAAI,IAAI,IAAI,IAAI;YAAE,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;QACtC,IAAI,IAAI,IAAI,IAAI;YAAE,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;QAEtC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,IAAI,CAAC,CAAC;QACzD,IAAI,CAAC,OAAO,CAAC,EAAE;YAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QACjD,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAC3B,MAAM,UAAU,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAE3D,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;QAC9B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,OAAO;gBACL,KAAK,EAAE,GAAG,aAAa,6DAA6D;aACrF,CAAC;QACJ,CAAC;QACD,MAAM,OAAO,GAAgB,EAAE,CAAC;QAChC,KAAK,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;YACpB,4DAA4D;YAC5D,yEAAyE;YACzE,gEAAgE;YAChE,6DAA6D;YAC7D,IACE,CAAC,QAAQ,CAAC,CAAC,CAAC;gBACZ,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ;gBAC7B,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ;gBAC7B,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ,EAC7B,CAAC;gBACD,OAAO;oBACL,KAAK,EAAE,GAAG,aAAa,4GAA4G;iBACpI,CAAC;YACJ,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACtE,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,OAAe,EAAE,IAAI,GAAG,GAAG;QACpC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE;YACjD,OAAO;YACP,IAAI;SACL,CAAC,CAAC;QACH,IAAI,CAAC,OAAO,CAAC,EAAE;YAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QACjD,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAC3B,MAAM,UAAU,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAE3D,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;QAC9B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,OAAO;gBACL,KAAK,EAAE,GAAG,aAAa,6DAA6D;aACrF,CAAC;QACJ,CAAC;QACD,OAAO,YAAY,CAAC,GAAG,EAAE,iBAAiB,EAAE,OAAO,CAAC,CAAC;IACvD,CAAC;IAED,qEAAqE;IACrE,mBAAmB;IACnB,qEAAqE;IAErE,KAAK,CAAC,KAAK,CAAC,QAAgB,EAAE,OAAe;QAC3C,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE;YAClD,SAAS,EAAE,QAAQ;YACnB,OAAO;SACR,CAAC,CAAC;QACH,IAAI,CAAC,OAAO,CAAC,EAAE;YAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QACjD,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAC3B,MAAM,UAAU,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAE3D,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;QAC5B,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,OAAO;gBACL,KAAK,EAAE,GAAG,aAAa,8EAA8E;aACtG,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,CAAC;IAClB,CAAC;IAED,KAAK,CAAC,IAAI,CACR,QAAgB,EAChB,SAAiB,EACjB,SAAiB,EACjB,UAAU,GAAG,KAAK;QAElB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE;YACjD,SAAS,EAAE,QAAQ;YACnB,UAAU,EAAE,SAAS;YACrB,UAAU,EAAE,SAAS;YACrB,WAAW,EAAE,UAAU;SACxB,CAAC,CAAC;QACH,IAAI,CAAC,OAAO,CAAC,EAAE;YAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QACjD,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAC3B,MAAM,UAAU,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAE3D,MAAM,WAAW,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;QAC1C,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;YACpC,OAAO;gBACL,KAAK,EAAE,GAAG,aAAa,iFAAiF;aACzG,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;IACzC,CAAC;IAED,qEAAqE;IACrE,kBAAkB;IAClB,qEAAqE;IAErE,KAAK,CAAC,OAAO,CAAC,OAAe;QAC3B,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QAC9D,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;YAChB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QAClE,CAAC;QACD,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAC3B,oEAAoE;QACpE,yEAAyE;QACzE,0EAA0E;QAC1E,0DAA0D;QAC1D,MAAM,UAAU,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,IAAI,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;YACjC,OAAO;gBACL,MAAM,EAAE,UAAU;gBAClB,QAAQ,EAAE,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBAC7C,SAAS,EAAE,KAAK;aACjB,CAAC;QACJ,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;QAChC,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;QACrC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC/D,OAAO;gBACL,MAAM,EAAE,GAAG,aAAa,2FAA2F;gBACnH,QAAQ,EAAE,CAAC;gBACX,SAAS,EAAE,KAAK;aACjB,CAAC;QACJ,CAAC;QACD,OAAO;YACL,MAAM;YACN,QAAQ;YACR,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;SACxC,CAAC;IACJ,CAAC;IAED,qEAAqE;IACrE,oBAAoB;IACpB,qEAAqE;IAErE;;OAEG;IACK,KAAK,CAAC,WAAW,CAAC,IAAY;QACpC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,qBAAqB,EAAE;YACrD,SAAS,EAAE,IAAI;SAChB,CAAC,CAAC;QACH,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;YAChB,OAAO,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAC5C,CAAC;QACD,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAC3B,MAAM,UAAU,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;QACxC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,OAAO,aAAa,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QACzC,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;QACrC,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC5B,OAAO,aAAa,CAClB,IAAI,EACJ,GAAG,aAAa,0FAA0F,CAC3G,CAAC;QACJ,CAAC;QACD,OAAO;YACL,IAAI;YACJ,OAAO,EAAE,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;YACnD,KAAK,EAAE,IAAI;SACZ,CAAC;IACJ,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,aAAa,CAAC,KAAe;QACjC,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,IAAI,qBAAqB,EAAE,IAAI,IAAI,EAAE,CAAC;YACzD,qEAAqE;YACrE,+DAA+D;YAC/D,oCAAoC;YACpC,MAAM,SAAS,GAA2B,EAAE,CAAC;YAC7C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,SAAS,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;YAC/C,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,UAAU,CAAC,KAAK,EAAE,oBAAoB,EAAE,CAAC,IAAI,EAAE,EAAE,CACtD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CACvB,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,WAAW,CACf,KAAkC;QAElC,uEAAuE;QACvE,2EAA2E;QAC3E,kDAAkD;QAClD,MAAM,GAAG,GAAG,GAAG,aAAa,iCAAiC,CAAC;QAC9D,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC;IACvD,CAAC;CACF;AAED;;;;;;GAMG;AACH,SAAS,YAAY,CACnB,OAAkB,EAClB,OAAe,EACf,IAAY;IAEZ,MAAM,KAAK,GAAe,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ,EAAE,CAAC;YAClD,OAAO;gBACL,KAAK,EAAE,GAAG,aAAa,IAAI,OAAO,kCAAkC,IAAI,uCAAuC;aAChH,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC;AAED,2EAA2E;AAC3E,6EAA6E;AAC7E,8EAA8E;AAC9E,8EAA8E;AAC9E,4DAA4D;AAC5D,SAAS,aAAa,CAAC,IAAY,EAAE,GAAW;IAC9C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAY,EAAE,CAAC;AACtD,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,UAAU,CACvB,KAAmB,EACnB,KAAa,EACb,EAA2B;IAE3B,MAAM,OAAO,GAAQ,IAAI,KAAK,CAAI,KAAK,CAAC,MAAM,CAAC,CAAC;IAChD,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,UAAU,MAAM;QACnB,OAAO,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YAC7B,MAAM,KAAK,GAAG,MAAM,CAAC;YACrB,MAAM,IAAI,CAAC,CAAC;YACZ,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO;YAC/B,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9C,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACnE,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,WAAW,CAAC,IAAY,EAAE,GAAW;IAC5C,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAY,EAAE,CAAC;AACvC,CAAC"}

package/dist/call_interrupt.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Per-call Stop opt-in for local (callback-routed) tools.
+ *
+ * Node has no preemptive cancel: the runtime can stop *waiting* on a tool
+ * body, but only the body can stop its own work. A tool branded with
+ * {@link withCallInterruptSupport} declares that its body consumes the
+ * per-call signal (via `getCallAbortSignal()` from
+ * `@mongodb-js/agent-engine-runner-shared`) and stops at its checkpoints.
+ * Only branded tools answer a per-call Stop with `interrupted`; unbranded
+ * tools honestly answer `not_cancellable` and run out.
+ */
+/**
+ * Brand a tool as supporting per-call interrupt. The body must honor the
+ * signal from `getCallAbortSignal()` — check `signal.aborted` between steps
+ * or pass the signal to APIs that accept one (`fetch`, streams).
+ *
+ * Returns the same tool for chaining at definition time.
+ */
+export declare function withCallInterruptSupport<T>(tool: T): T;
+//# sourceMappingURL=call_interrupt.d.ts.map

package/dist/call_interrupt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call_interrupt.d.ts","sourceRoot":"","sources":["../src/call_interrupt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAGtD"}

package/dist/call_interrupt.js

@@ -0,0 +1,23 @@
+/**
+ * Per-call Stop opt-in for local (callback-routed) tools.
+ *
+ * Node has no preemptive cancel: the runtime can stop *waiting* on a tool
+ * body, but only the body can stop its own work. A tool branded with
+ * {@link withCallInterruptSupport} declares that its body consumes the
+ * per-call signal (via `getCallAbortSignal()` from
+ * `@mongodb-js/agent-engine-runner-shared`) and stops at its checkpoints.
+ * Only branded tools answer a per-call Stop with `interrupted`; unbranded
+ * tools honestly answer `not_cancellable` and run out.
+ */
+/**
+ * Brand a tool as supporting per-call interrupt. The body must honor the
+ * signal from `getCallAbortSignal()` — check `signal.aborted` between steps
+ * or pass the signal to APIs that accept one (`fetch`, streams).
+ *
+ * Returns the same tool for chaining at definition time.
+ */
+export function withCallInterruptSupport(tool) {
+    tool.supportsCallInterrupt = true;
+    return tool;
+}
+//# sourceMappingURL=call_interrupt.js.map

package/dist/call_interrupt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"call_interrupt.js","sourceRoot":"","sources":["../src/call_interrupt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CAAI,IAAO;IAChD,IAA4C,CAAC,qBAAqB,GAAG,IAAI,CAAC;IAC3E,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/checkpoint_branch.d.ts

@@ -0,0 +1,58 @@
+/** Copy a LangGraph checkpoint branch point into a new thread. */
+import type { RunnableConfig } from "@langchain/core/runnables";
+import type { CompiledStateGraph } from "@langchain/langgraph";
+export interface LangGraphCheckpoint {
+    readonly threadId: string;
+    readonly checkpointId: string;
+}
+export declare function branchPointFromMetadata(metadata: Record<string, unknown> | null | undefined): LangGraphCheckpoint | undefined;
+export declare function checkpointMetadata(checkpoint: LangGraphCheckpoint | undefined): {
+    langgraph_checkpoint: {
+        thread_id: string;
+        checkpoint_id: string;
+    };
+} | undefined;
+/** Replay plan: the source supersteps a branch copy materializes in order. */
+export type CheckpointReplayPlan = Array<{
+    updates: Array<{
+        values?: unknown;
+        asNode?: string;
+    }>;
+}>;
+/**
+ * Load a completed root checkpoint, or fail closed.
+ *
+ * Fork validates this before CreateBranch so a missing or incomplete history
+ * point does not create a branch session (Python
+ * `completed_root_checkpoint` parity).
+ */
+export declare function completedRootCheckpoint(graph: CompiledStateGraph<unknown, unknown>, args: {
+    threadId: string;
+    historyId: string | null;
+}): Promise<LangGraphCheckpoint>;
+/**
+ * Build the copyable superstep plan, or raise before any destination write.
+ *
+ * Port of Python's `checkpoint_replay_plan`; fork builds this before
+ * CreateBranch so the copied snapshot is the one that was validated.
+ */
+export declare function checkpointReplayPlan(graph: CompiledStateGraph<unknown, unknown>, source: LangGraphCheckpoint): Promise<CheckpointReplayPlan>;
+/**
+ * Rebuild `source` in the empty thread named by `targetConfig`.
+ *
+ * `plan` is the pre-dispatch validated plan from `checkpointReplayPlan`;
+ * callers that validated before a side effect pass it so the copy can only
+ * materialize that snapshot.
+ */
+export declare function copyCheckpoint(graph: CompiledStateGraph<unknown, unknown>, targetConfig: RunnableConfig, source: LangGraphCheckpoint, plan?: CheckpointReplayPlan): Promise<void>;
+/** True when `config`'s thread has no checkpoints yet. */
+export declare function destinationThreadIsEmpty(graph: CompiledStateGraph<unknown, unknown>, config: RunnableConfig): Promise<boolean>;
+/**
+ * Copy `source` onto an empty dest thread.
+ *
+ * In-app fork already materializes dest; OE still dispatches later dest
+ * invokes with the source branch point. If dest already has checkpoints,
+ * leave it alone (Python `initialize_checkpoint_branch` parity).
+ */
+export declare function initializeCheckpointBranch(graph: CompiledStateGraph<unknown, unknown>, config: RunnableConfig, source: LangGraphCheckpoint): Promise<void>;
+//# sourceMappingURL=checkpoint_branch.d.ts.map

package/dist/checkpoint_branch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint_branch.d.ts","sourceRoot":"","sources":["../src/checkpoint_branch.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAGlE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAiB,MAAM,sBAAsB,CAAC;AAG9E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GACnD,mBAAmB,GAAG,SAAS,CAiBjC;AAED,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,mBAAmB,GAAG,SAAS,GAEzC;IACE,oBAAoB,EAAE;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH,GACD,SAAS,CAQZ;AAgGD,8EAA8E;AAC9E,MAAM,MAAM,oBAAoB,GAAG,KAAK,CAAC;IACvC,OAAO,EAAE,KAAK,CAAC;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACvD,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,EAC3C,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACnD,OAAO,CAAC,mBAAmB,CAAC,CAsB9B;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,EAC3C,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,oBAAoB,CAAC,CAoC/B;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,EAC3C,YAAY,EAAE,cAAc,EAC5B,MAAM,EAAE,mBAAmB,EAC3B,IAAI,CAAC,EAAE,oBAAoB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAyCf;AAED,0DAA0D;AAC1D,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,EAC3C,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,OAAO,CAAC,CAgBlB;AAED;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,EAC3C,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAGf"}