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

package/dist/session_fork.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Session fork. See `docs/session-fork.md`.
+ *
+ * Port of Python's `agent_engine_sdk_langgraph/session_fork.py`. LangGraph.js has no
+ * synchronous `update_state` and no `task_id` parameter, so only the async
+ * `updateState` surface is wrapped and branch keys omit the task component.
+ */
+import type { RunnableConfig } from "@langchain/core/runnables";
+import type { CompiledStateGraph } from "@langchain/langgraph";
+import { currentAttemptContext } from "@mongodb-js/agent-engine-runner-shared";
+import type { RequestContext } from "@mongodb-js/agent-engine-sdk";
+import { type ResolveThreadIdHook } from "./thread_id.js";
+/** Response for forking a session into a new independent session. */
+export interface SessionForkResponse {
+    /** Identifier of the new branch session. */
+    sessionId: string;
+    /** Pending execution on the new branch session. */
+    executionId: string;
+}
+interface ForkableAgent {
+    compiledGraph: CompiledStateGraph<unknown, unknown>;
+    resolveThreadId?: ResolveThreadIdHook | null;
+}
+/** True once: dest should `invoke(null)`. See `docs/session-fork.md`. */
+export declare function takeContinueWithoutUserMessage(threadId: string): boolean;
+/**
+ * Create a branch session and copy the source checkpoint onto it.
+ *
+ * Port of Python's `fork_native_session`: the selected checkpoint and its
+ * replay plan are validated before CreateBranch, and the copy reuses this
+ * package's `copyCheckpoint` with that validated plan.
+ */
+export declare function forkNativeSession(graph: CompiledStateGraph<unknown, unknown>, args: {
+    ctx: RequestContext;
+    historyId: string | null;
+    resolveThreadId?: ResolveThreadIdHook | null;
+    state?: unknown;
+    asNode?: string | null;
+}): Promise<[SessionForkResponse, RunnableConfig]>;
+/**
+ * Create an OE-owned branch from a selected committed scratch checkpoint.
+ *
+ * Port of Python's `_fork_durable_session`.
+ */
+export declare function forkDurableSession(graph: CompiledStateGraph<unknown, unknown>, args: {
+    context: NonNullable<ReturnType<typeof currentAttemptContext>>;
+    config: RunnableConfig;
+    resolveThreadId?: ResolveThreadIdHook | null;
+}): Promise<[SessionForkResponse, RunnableConfig]>;
+/** Reject patches until OE can record one as a branch-local transition. */
+export declare function requireExactDurableBranch(state: unknown): void;
+/**
+ * Route live `updateState` through the persistence-specific session fork.
+ *
+ * See `docs/session-fork.md`.
+ */
+export declare function wrapSessionForkUpdateState(graph: CompiledStateGraph<unknown, unknown>, args: {
+    resolveThreadId: ResolveThreadIdHook | null;
+}): void;
+/** AER write plugin that forks a LangGraph session. */
+export declare class LangGraphForkPlugin {
+    private readonly getAgent;
+    private readonly workspaceIdResolver;
+    constructor(args: {
+        getAgent: () => ForkableAgent;
+        workspaceIdResolver: () => string;
+    });
+    forkSession(args: {
+        sessionId: string;
+        executionId: string;
+        historyId: string | null;
+        state?: unknown;
+    }): Promise<SessionForkResponse>;
+}
+export {};
+//# sourceMappingURL=session_fork.d.ts.map

package/dist/session_fork.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session_fork.d.ts","sourceRoot":"","sources":["../src/session_fork.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAEV,kBAAkB,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,qBAAqB,EAUtB,MAAM,wCAAwC,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAWnE,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAG9E,qEAAqE;AACrE,MAAM,WAAW,mBAAmB;IAClC,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,aAAa;IACrB,aAAa,EAAE,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACpD,eAAe,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAC9C;AAQD,yEAAyE;AACzE,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAIxE;AA8BD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,EAC3C,IAAI,EAAE;IACJ,GAAG,EAAE,cAAc,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,eAAe,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,GACA,OAAO,CAAC,CAAC,mBAAmB,EAAE,cAAc,CAAC,CAAC,CAuFhD;AA8BD;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,EAC3C,IAAI,EAAE;IACJ,OAAO,EAAE,WAAW,CAAC,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC,CAAC;IAC/D,MAAM,EAAE,cAAc,CAAC;IACvB,eAAe,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAC9C,GACA,OAAO,CAAC,CAAC,mBAAmB,EAAE,cAAc,CAAC,CAAC,CA4DhD;AAYD,2EAA2E;AAC3E,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAM9D;AA4BD;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,EAC3C,IAAI,EAAE;IAAE,eAAe,EAAE,mBAAmB,GAAG,IAAI,CAAA;CAAE,GACpD,IAAI,CA6DN;AAED,uDAAuD;AACvD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAC/C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAe;gBAEvC,IAAI,EAAE;QAChB,QAAQ,EAAE,MAAM,aAAa,CAAC;QAC9B,mBAAmB,EAAE,MAAM,MAAM,CAAC;KACnC;IAKK,WAAW,CAAC,IAAI,EAAE;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAoDjC"}

package/dist/session_fork.js

@@ -0,0 +1,428 @@
+/**
+ * Session fork. See `docs/session-fork.md`.
+ *
+ * Port of Python's `agent_engine_sdk_langgraph/session_fork.py`. LangGraph.js has no
+ * synchronous `update_state` and no `task_id` parameter, so only the async
+ * `updateState` surface is wrapped and branch keys omit the task component.
+ */
+import { createHash } from "node:crypto";
+import { currentAttemptContext, encodeProtoJson, fetchPlatform, getFetchOptionsWithTLS, getCurrentOeUrl, quotePathSegment, resolveOeUrl, StateSnapshotSchema, } from "@mongodb-js/agent-engine-runner-shared";
+import { checkpointReplayPlan, completedRootCheckpoint, copyCheckpoint, } from "./checkpoint_branch.js";
+import { OE_STEP_ORDINAL_METADATA_KEY, PlatformCheckpointer, } from "./platform_checkpointer.js";
+import { checkpointThreadId } from "./thread_id.js";
+import { channelValuesToStateSnapshot } from "./workflow_state.js";
+const CREATE_BRANCH_TIMEOUT_MS = 15_000;
+// Dest continue is process-local. Bound so unused dests cannot accumulate;
+// an evicted mark behaves like a dest execution that starts in another process.
+const CONTINUE_MARK_LIMIT = 256;
+const CONTINUE_WITHOUT_USER_MESSAGE = new Map();
+/** True once: dest should `invoke(null)`. See `docs/session-fork.md`. */
+export function takeContinueWithoutUserMessage(threadId) {
+    if (!CONTINUE_WITHOUT_USER_MESSAGE.has(threadId))
+        return false;
+    CONTINUE_WITHOUT_USER_MESSAGE.delete(threadId);
+    return true;
+}
+function armContinueWithoutUserMessage(threadId) {
+    if (CONTINUE_WITHOUT_USER_MESSAGE.has(threadId)) {
+        CONTINUE_WITHOUT_USER_MESSAGE.delete(threadId);
+    }
+    else if (CONTINUE_WITHOUT_USER_MESSAGE.size >= CONTINUE_MARK_LIMIT) {
+        const oldest = CONTINUE_WITHOUT_USER_MESSAGE.keys().next();
+        if (!oldest.done)
+            CONTINUE_WITHOUT_USER_MESSAGE.delete(oldest.value);
+    }
+    CONTINUE_WITHOUT_USER_MESSAGE.set(threadId, null);
+}
+function requireNonEmpty(value, what) {
+    if (!value || !value.trim()) {
+        throw new Error(`${what} is required to fork a session`);
+    }
+    return value;
+}
+function isEmptyValues(state) {
+    return (state === null ||
+        state === undefined ||
+        (typeof state === "object" && Object.keys(state).length === 0));
+}
+/**
+ * Create a branch session and copy the source checkpoint onto it.
+ *
+ * Port of Python's `fork_native_session`: the selected checkpoint and its
+ * replay plan are validated before CreateBranch, and the copy reuses this
+ * package's `copyCheckpoint` with that validated plan.
+ */
+export async function forkNativeSession(graph, args) {
+    if (currentAttemptContext() !== null) {
+        throw new Error("session fork is not supported on durable_workflow sessions");
+    }
+    const { ctx } = args;
+    const sessionId = requireNonEmpty(ctx.sessionId, "session identity");
+    const workspaceId = requireNonEmpty(ctx.workspaceId, "workspace identity");
+    const executionId = requireNonEmpty(ctx.executionId, "execution identity");
+    const source = await completedRootCheckpoint(graph, {
+        threadId: checkpointThreadId(ctx, args.resolveThreadId),
+        historyId: args.historyId,
+    });
+    const plan = await checkpointReplayPlan(graph, source);
+    const hasPatch = !isEmptyValues(args.state);
+    // Resolve and validate the patch node before CreateBranch: LangGraph would
+    // only reject an unknown or ambiguous target after the branch and copy
+    // already exist.
+    const patchNode = hasPatch ? (args.asNode ?? singleNodeName(graph)) : null;
+    if (hasPatch &&
+        args.asNode !== null &&
+        args.asNode !== undefined &&
+        !graphNodeNames(graph).includes(args.asNode)) {
+        throw new Error(`session fork state patch node "${args.asNode}" is not a node in this graph`);
+    }
+    if (hasPatch && patchNode === null) {
+        throw new Error("session fork state patch requires a destination node: " +
+            "pass asNode or fork a single-node graph");
+    }
+    const branch = await createNativeBranch({
+        orgId: tenantEnvId("ORG_ID"),
+        projectId: tenantEnvId("PROJECT_ID"),
+        workspaceId,
+        sessionId,
+        executionId,
+        branchKey: branchKey(source.checkpointId, args.state, args.asNode ?? null, null),
+        checkpointId: source.checkpointId,
+    });
+    const destThreadId = checkpointThreadId({
+        sessionId: branch.sessionId,
+        workspaceId,
+        executionId: branch.executionId,
+    }, args.resolveThreadId);
+    const destConfig = {
+        configurable: { thread_id: destThreadId, checkpoint_ns: "" },
+    };
+    // Python `fork_native_session` parity: copy onto the empty destination,
+    // then apply the optional patch. A populated destination (a repeated fork
+    // for the same branch key, or a destination left behind by a failed
+    // attempt) is sealed by `copyCheckpoint`'s empty-destination guard instead
+    // of being repaired, verified, or silently reused.
+    await copyCheckpoint(graph, destConfig, source, plan);
+    if (patchNode !== null) {
+        await graph.updateState(destConfig, args.state, patchNode);
+    }
+    const destCheckpointId = await latestCheckpointId(graph, destThreadId);
+    const finalConfig = {
+        ...destConfig,
+        configurable: {
+            ...destConfig.configurable,
+            checkpoint_id: destCheckpointId,
+        },
+    };
+    armContinueWithoutUserMessage(destThreadId);
+    return [branch, finalConfig];
+}
+async function latestCheckpointId(graph, threadId) {
+    const snapshot = await graph.getState({
+        configurable: { thread_id: threadId },
+    });
+    const checkpointId = snapshot.config.configurable?.["checkpoint_id"];
+    if (typeof checkpointId !== "string" || checkpointId === "") {
+        throw new Error("LangGraph branch point was not found");
+    }
+    return checkpointId;
+}
+/** Root-loop node names a state patch may target. */
+function graphNodeNames(graph) {
+    return Object.keys(graph.nodes ?? {}).filter((name) => !name.startsWith("__"));
+}
+function singleNodeName(graph) {
+    const names = graphNodeNames(graph);
+    return names.length === 1 ? (names[0] ?? null) : null;
+}
+/**
+ * Create an OE-owned branch from a selected committed scratch checkpoint.
+ *
+ * Port of Python's `_fork_durable_session`.
+ */
+export async function forkDurableSession(graph, args) {
+    const { context } = args;
+    const identity = context.workflowIdentity;
+    const scope = identity?.tenantScope;
+    if (!identity ||
+        !scope ||
+        !identity.sessionId ||
+        !identity.executionId ||
+        !scope.orgId ||
+        !scope.projectId ||
+        !scope.workspaceId) {
+        throw new Error("durable session fork requires complete OE attempt identity");
+    }
+    const checkpointer = graph.checkpointer;
+    if (!(checkpointer instanceof PlatformCheckpointer)) {
+        throw new Error("durable session fork requires the platform checkpointer");
+    }
+    const source = await checkpointer.getTuple(args.config);
+    if (source === undefined) {
+        throw new Error("durable branch point is not a committed root step");
+    }
+    const stepOrdinal = oeStepOrdinal(source.metadata);
+    // Materialized state adds unwritten reducer defaults absent from the OE hash.
+    const sourceState = channelValuesToStateSnapshot((source.checkpoint.channel_values ?? {}), context.replayMode);
+    const branchSource = `${identity.executionId}/step/${stepOrdinal}`;
+    const branch = await createDurableBranch({
+        orgId: scope.orgId,
+        projectId: scope.projectId,
+        workspaceId: scope.workspaceId,
+        sessionId: identity.sessionId,
+        executionId: identity.executionId,
+        branchKey: branchKey(branchSource, null, null, null),
+        stepOrdinal,
+        state: sourceState,
+    });
+    // RequestContext is request-local. Use a minimal value only to resolve the
+    // destination thread; the future branch invocation receives its own context.
+    const destConfig = {
+        configurable: {
+            thread_id: checkpointThreadId({
+                sessionId: branch.sessionId,
+                workspaceId: scope.workspaceId,
+                executionId: branch.executionId,
+            }, args.resolveThreadId),
+            checkpoint_ns: "",
+        },
+    };
+    return [branch, destConfig];
+}
+/** Read the absolute OE ordinal recorded with a committed scratch step. */
+function oeStepOrdinal(metadata) {
+    const values = (metadata ?? {});
+    const stepOrdinal = values[OE_STEP_ORDINAL_METADATA_KEY];
+    if (stepOrdinal === undefined || stepOrdinal === null) {
+        throw new Error("durable branch point is not a committed root step");
+    }
+    return Number(stepOrdinal);
+}
+/** Reject patches until OE can record one as a branch-local transition. */
+export function requireExactDurableBranch(state) {
+    if (!isEmptyValues(state)) {
+        throw new Error("durable_workflow session fork does not support an updateState patch");
+    }
+}
+function liveSource(config, snapshotConfig, resolveThreadId) {
+    if (currentAttemptContext() !== null)
+        return null;
+    const checkpointId = snapshotConfig.configurable?.["checkpoint_id"];
+    if (typeof checkpointId !== "string" || checkpointId === "")
+        return null;
+    const ctx = config.configurable?.["request_context"];
+    if (ctx === undefined || ctx === null)
+        return null;
+    if (!ctx.sessionId || !ctx.workspaceId || !ctx.executionId)
+        return null;
+    const threadId = config.configurable?.["thread_id"];
+    if (threadId !== checkpointThreadId(ctx, resolveThreadId))
+        return null;
+    return ctx;
+}
+function tenantEnvId(name) {
+    const value = (process.env[name] ?? "").trim();
+    if (!value) {
+        throw new Error(`${name} is required to fork a session`);
+    }
+    return value;
+}
+/**
+ * Route live `updateState` through the persistence-specific session fork.
+ *
+ * See `docs/session-fork.md`.
+ */
+export function wrapSessionForkUpdateState(graph, args) {
+    // Python wraps only when the graph exposes the async update surface; graph
+    // test doubles may omit it entirely.
+    const originalUpdate = graph.updateState;
+    if (typeof originalUpdate !== "function")
+        return;
+    const original = originalUpdate.bind(graph);
+    const originalGetState = graph.getState.bind(graph);
+    graph.updateState = async (config, values, asNode) => {
+        const attempt = currentAttemptContext();
+        if (attempt !== null) {
+            if (args.resolveThreadId !== null) {
+                throw new Error("session fork requires the default thread_id formula; " +
+                    "custom App.resolveThreadId is not supported on graph.updateState");
+            }
+            // CreateBranch hash-validates the selected committed snapshot. A
+            // state patch needs a separate branch-local transition contract.
+            requireExactDurableBranch(values);
+            const [, destConfig] = await forkDurableSession(graph, {
+                context: attempt,
+                config,
+                resolveThreadId: args.resolveThreadId,
+            });
+            return destConfig;
+        }
+        const snapshot = await originalGetState(config);
+        const ctx = liveSource(config, snapshot.config, args.resolveThreadId);
+        if (ctx !== null) {
+            if (args.resolveThreadId !== null) {
+                throw new Error("session fork requires the default thread_id formula; " +
+                    "custom App.resolveThreadId is not supported on graph.updateState");
+            }
+            const pinned = config.configurable?.["checkpoint_id"];
+            const snapshotId = snapshot.config.configurable?.["checkpoint_id"];
+            const historyId = typeof pinned === "string" && pinned !== ""
+                ? pinned
+                : typeof snapshotId === "string"
+                    ? snapshotId
+                    : null;
+            const [, destConfig] = await forkNativeSession(graph, {
+                ctx,
+                historyId,
+                resolveThreadId: null,
+                state: values,
+                asNode: asNode ?? null,
+            });
+            return destConfig;
+        }
+        return original(config, values, asNode);
+    };
+}
+/** AER write plugin that forks a LangGraph session. */
+export class LangGraphForkPlugin {
+    getAgent;
+    workspaceIdResolver;
+    constructor(args) {
+        this.getAgent = args.getAgent;
+        this.workspaceIdResolver = args.workspaceIdResolver;
+    }
+    async forkSession(args) {
+        const agent = this.getAgent();
+        const workspaceId = this.workspaceIdResolver();
+        const attempt = currentAttemptContext();
+        if (attempt !== null) {
+            const identity = attempt.workflowIdentity;
+            if (!identity ||
+                args.sessionId !== identity.sessionId ||
+                args.executionId !== identity.executionId ||
+                workspaceId !== (identity.tenantScope?.workspaceId ?? "")) {
+                throw new Error("durable fork request identity does not match the current OE attempt");
+            }
+            // Durable CreateBranch accepts the exact committed snapshot. Do not
+            // reinterpret an API state patch as part of that source snapshot.
+            requireExactDurableBranch(args.state);
+            const configurable = {
+                thread_id: checkpointThreadId({
+                    sessionId: args.sessionId,
+                    workspaceId,
+                    executionId: args.executionId,
+                }, agent.resolveThreadId ?? null),
+                checkpoint_ns: "",
+            };
+            if (args.historyId) {
+                configurable["checkpoint_id"] = args.historyId;
+            }
+            const [branch] = await forkDurableSession(agent.compiledGraph, {
+                context: attempt,
+                config: { configurable },
+                resolveThreadId: agent.resolveThreadId ?? null,
+            });
+            return branch;
+        }
+        const [branch] = await forkNativeSession(agent.compiledGraph, {
+            ctx: {
+                sessionId: args.sessionId,
+                workspaceId,
+                executionId: args.executionId,
+            },
+            historyId: args.historyId,
+            resolveThreadId: agent.resolveThreadId ?? null,
+            state: args.state,
+        });
+        return branch;
+    }
+}
+async function createNativeBranch(args) {
+    const body = { branch_key: args.branchKey };
+    if (args.checkpointId)
+        body["checkpoint_id"] = args.checkpointId;
+    return createBranch(args, body);
+}
+async function createDurableBranch(args) {
+    const body = {
+        branch_key: args.branchKey,
+        step_ordinal: args.stepOrdinal,
+        state: JSON.parse(encodeProtoJson(StateSnapshotSchema, args.state)),
+    };
+    return createBranch(args, body);
+}
+async function createBranch(args, body) {
+    const oeUrl = resolveOeUrl(getCurrentOeUrl() ?? "").replace(/\/$/, "");
+    if (!oeUrl) {
+        throw new Error("OE_URL is not configured; cannot fork a session");
+    }
+    const path = `/workflow/orgs/${quotePathSegment(args.orgId)}` +
+        `/projects/${quotePathSegment(args.projectId)}` +
+        `/workspaces/${quotePathSegment(args.workspaceId)}` +
+        `/sessions/${quotePathSegment(args.sessionId)}` +
+        `/executions/${quotePathSegment(args.executionId)}/branches`;
+    const url = `${oeUrl}${path}`;
+    const response = await fetchPlatform(url, {
+        ...getFetchOptionsWithTLS(url),
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(CREATE_BRANCH_TIMEOUT_MS),
+    });
+    if (response.status !== 200 && response.status !== 201) {
+        throw new Error(`CreateBranch failed with HTTP ${response.status}: ${(await response.text()).slice(0, 200)}`);
+    }
+    const payload = (await response.json());
+    const newSessionId = payload["session_id"];
+    const newExecutionId = payload["execution_id"];
+    if (typeof newSessionId !== "string" ||
+        typeof newExecutionId !== "string" ||
+        !newSessionId ||
+        !newExecutionId) {
+        throw new Error("CreateBranch response is missing session identity");
+    }
+    return { sessionId: newSessionId, executionId: newExecutionId };
+}
+const BRANCH_KEY_SAFE = /[^A-Za-z0-9._/-]+/g;
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * Canonicalize a state patch for hashing: plain-object keys are sorted so
+ * equivalent patches hash identically, while array order stays significant
+ * (Python `json.dumps(..., sort_keys=True)` parity). Non-plain values keep
+ * their own serialization contract.
+ */
+function canonicalStateValue(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalStateValue);
+    if (isPlainObject(value)) {
+        return Object.fromEntries(Object.keys(value)
+            .sort()
+            .map((key) => [key, canonicalStateValue(value[key])]));
+    }
+    return value;
+}
+/**
+ * Deterministic idempotency key for one fork: the same history, state patch,
+ * and node always map to the same branch, so retries reuse the OE branch.
+ */
+function branchKey(historyId, state, asNode, taskId) {
+    const payload = JSON.stringify({
+        state: isEmptyValues(state) ? null : canonicalStateValue(state),
+        asNode: asNode ?? "",
+        taskId: taskId ?? "",
+    });
+    const digest = createHash("sha256")
+        .update(`${historyId}\0${payload}`)
+        .digest("hex")
+        .slice(0, 16);
+    const safeHistory = historyId
+        .replace(BRANCH_KEY_SAFE, "-")
+        .replace(/^[-._/]+|[-._/]+$/g, "");
+    return `update-${safeHistory.slice(0, 64) || "latest"}-${digest}`;
+}
+//# sourceMappingURL=session_fork.js.map

package/dist/session_fork.js.map

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

package/dist/subagents.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Subagent spec validation for `createAgentEngineDeepAgent`.
+ *
+ * Hard-fails at agent construction time when a subagent spec uses a string
+ * model — string models bypass the `SecureWrappedLLM` seam and therefore the
+ * OE audit path. Kept in its own module (mirroring Python's `subagents.py`) so
+ * the validator has an importable surface for tests rather than being reachable
+ * only through the wrapper factory.
+ */
+import type { AnySubAgent } from "deepagents";
+/**
+ * Recursion is bounded so an adversarial spec (or an accidental cycle) can't
+ * blow the stack at agent-construction time.
+ */
+export declare const MAX_SUBAGENT_NESTING_DEPTH = 10;
+/**
+ * Walk the subagent tree, throwing on any string-model spec.
+ *
+ * String model specs would bypass OE routing because deepagents' `resolveModel`
+ * instantiates a raw provider client with no `SecureToolWrapper`. Only model
+ * instances (e.g. `SecureWrappedLLM`) are accepted.
+ *
+ * Spec kinds handled:
+ * - `CompiledSubAgent` (`runnable` set) — pre-built graph; the model is already
+ *   bound and unreadable here. Skipped.
+ * - `AsyncSubAgent` (`graphId` set) — remote graph we can't validate in-process.
+ *   Logged at WARNING and skipped — the receiving end must route through the OE.
+ * - Plain `SubAgent` — validated; a string `model` throws.
+ *
+ * The depth counter is held in a closure rather than a public parameter so
+ * callers cannot start recursion mid-tree and bypass the cap.
+ *
+ * @throws {Error} A subagent spec uses a string `model`, or nesting exceeds
+ *   {@link MAX_SUBAGENT_NESTING_DEPTH}.
+ */
+export declare function validateSubagentTree(subagents: readonly AnySubAgent[] | undefined): void;
+//# sourceMappingURL=subagents.d.ts.map

package/dist/subagents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagents.d.ts","sourceRoot":"","sources":["../src/subagents.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAY,MAAM,YAAY,CAAC;AAMxD;;;GAGG;AACH,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAK7C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,SAAS,WAAW,EAAE,GAAG,SAAS,GAC5C,IAAI,CAoCN"}

package/dist/subagents.js

@@ -0,0 +1,67 @@
+/**
+ * Subagent spec validation for `createAgentEngineDeepAgent`.
+ *
+ * Hard-fails at agent construction time when a subagent spec uses a string
+ * model — string models bypass the `SecureWrappedLLM` seam and therefore the
+ * OE audit path. Kept in its own module (mirroring Python's `subagents.py`) so
+ * the validator has an importable surface for tests rather than being reachable
+ * only through the wrapper factory.
+ */
+import { isAsyncSubAgent } from "deepagents";
+import { getLogger } from "@mongodb-js/agent-engine-runner-shared";
+const logger = getLogger("agent_engine_sdk_langgraph.subagents");
+/**
+ * Recursion is bounded so an adversarial spec (or an accidental cycle) can't
+ * blow the stack at agent-construction time.
+ */
+export const MAX_SUBAGENT_NESTING_DEPTH = 10;
+/**
+ * Walk the subagent tree, throwing on any string-model spec.
+ *
+ * String model specs would bypass OE routing because deepagents' `resolveModel`
+ * instantiates a raw provider client with no `SecureToolWrapper`. Only model
+ * instances (e.g. `SecureWrappedLLM`) are accepted.
+ *
+ * Spec kinds handled:
+ * - `CompiledSubAgent` (`runnable` set) — pre-built graph; the model is already
+ *   bound and unreadable here. Skipped.
+ * - `AsyncSubAgent` (`graphId` set) — remote graph we can't validate in-process.
+ *   Logged at WARNING and skipped — the receiving end must route through the OE.
+ * - Plain `SubAgent` — validated; a string `model` throws.
+ *
+ * The depth counter is held in a closure rather than a public parameter so
+ * callers cannot start recursion mid-tree and bypass the cap.
+ *
+ * @throws {Error} A subagent spec uses a string `model`, or nesting exceeds
+ *   {@link MAX_SUBAGENT_NESTING_DEPTH}.
+ */
+export function validateSubagentTree(subagents) {
+    const walk = (nodes, depth) => {
+        if (nodes === undefined)
+            return;
+        if (depth > MAX_SUBAGENT_NESTING_DEPTH) {
+            throw new Error(`SubAgent nesting exceeds maximum recursion depth (${MAX_SUBAGENT_NESTING_DEPTH})`);
+        }
+        for (const spec of nodes) {
+            // Pre-built graph — model already bound, nothing to validate.
+            if ("runnable" in spec)
+                continue;
+            // Remote graph — defer to the receiving end.
+            if (isAsyncSubAgent(spec)) {
+                logger.warn(`AsyncSubAgent '${spec.name ?? "<unnamed>"}' targets remote ` +
+                    `graphId='${spec.graphId}' — verify the remote graph routes ` +
+                    `through the OE for audit compliance`);
+                continue;
+            }
+            const sub = spec;
+            if (typeof sub.model === "string") {
+                throw new Error(`SubAgent '${sub.name ?? "<unnamed>"}' uses a string model spec ` +
+                    `('${sub.model}') which bypasses OE routing. Pass a model ` +
+                    `instance (e.g. SecureWrappedLLM via app.llm()) instead.`);
+            }
+            walk(sub.subagents, depth + 1);
+        }
+    };
+    walk(subagents, 0);
+}
+//# sourceMappingURL=subagents.js.map

package/dist/subagents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagents.js","sourceRoot":"","sources":["../src/subagents.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,wCAAwC,CAAC;AAEnE,MAAM,MAAM,GAAG,SAAS,CAAC,sCAAsC,CAAC,CAAC;AAEjE;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,CAAC;AAK7C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAA6C;IAE7C,MAAM,IAAI,GAAG,CACX,KAAyC,EACzC,KAAa,EACP,EAAE;QACR,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO;QAChC,IAAI,KAAK,GAAG,0BAA0B,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CACb,qDAAqD,0BAA0B,GAAG,CACnF,CAAC;QACJ,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,8DAA8D;YAC9D,IAAI,UAAU,IAAI,IAAI;gBAAE,SAAS;YACjC,6CAA6C;YAC7C,IAAI,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC1B,MAAM,CAAC,IAAI,CACT,kBAAkB,IAAI,CAAC,IAAI,IAAI,WAAW,mBAAmB;oBAC3D,YAAY,IAAI,CAAC,OAAO,qCAAqC;oBAC7D,qCAAqC,CACxC,CAAC;gBACF,SAAS;YACX,CAAC;YACD,MAAM,GAAG,GAAG,IAAwB,CAAC;YACrC,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAClC,MAAM,IAAI,KAAK,CACb,aAAa,GAAG,CAAC,IAAI,IAAI,WAAW,6BAA6B;oBAC/D,KAAK,GAAG,CAAC,KAAK,6CAA6C;oBAC3D,yDAAyD,CAC5D,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QACjC,CAAC;IACH,CAAC,CAAC;IAEF,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC;AACrB,CAAC"}