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

package/dist/query.d.ts

@@ -0,0 +1,103 @@
+/**
+ * LangGraph-backed implementation of runner-shared's `AERQueryPlugin`.
+ *
+ * Reads from the same MongoDB collections that LangGraph's `MongoDBSaver`
+ * writes to (`checkpoints`, `checkpoint_writes`). Deserialization is
+ * delegated to the saver's `serde` so this code does not need to know how
+ * LangGraph encodes state on disk.
+ *
+ * Port of Python's `agent_engine_sdk_langgraph/query.py`. One structural
+ * difference: the JS `MongoDBSaver` keeps its `Db` handle protected, so the
+ * plugin is constructed with the `MongoClient` + database name instead.
+ *
+ * Checkpoints are keyed by a workspace-scoped `thread_id` — see
+ * `thread_id.ts`. The plugin composes that scope onto the plain `session_id`
+ * it receives before querying, and strips it back off before returning.
+ * Reads never query the bare unscoped key when a workspace scope is known:
+ * bare keys are shared across every workspace on the store.
+ * An empty scope is legitimate only on explicitly unscoped runtimes (local
+ * dev / tests, no `APP_ID`), whose writes are bare-keyed to match. Managed
+ * runtimes carry `REQUIRE_PROJECT_SCOPED_DB` and reject a missing `APP_ID`.
+ */
+import type { MongoClient } from "mongodb";
+import type { MongoDBSaver } from "@langchain/langgraph-checkpoint-mongodb";
+import { type SessionMessagesResponse, type SessionsSummaryResponse } from "@mongodb-js/agent-engine-sdk";
+export interface LangGraphQueryPluginParams {
+    saver: MongoDBSaver;
+    client: MongoClient;
+    dbName: string;
+    workspaceId?: string;
+    workspaceIdResolver?: () => string | null | undefined;
+}
+/** AERQueryPlugin backed by LangGraph's MongoDBSaver. */
+export declare class LangGraphQueryPlugin {
+    private readonly saver;
+    private readonly checkpointsCollection;
+    private readonly writesCollection;
+    private readonly workspaceId;
+    private readonly workspaceIdResolver;
+    constructor(params: LangGraphQueryPluginParams);
+    /**
+     * Resolve the workspace scope for a read. "" is a legitimate scope — an
+     * explicitly unscoped runtime (local dev / tests, no APP_ID) whose
+     * checkpoints are bare-keyed by construction, matching the write path. The
+     * runner rejects this state when managed-runtime scoping is required. A
+     * resolver returning null/undefined signals a genuinely unresolvable scope
+     * (a custom resolver that cannot make that call) and fails closed rather
+     * than silently reading the shared store.
+     */
+    private effectiveWorkspaceId;
+    getSummariesForSessions(sessionIds: string[]): Promise<SessionsSummaryResponse>;
+    getMessagesForSession(sessionId: string): Promise<SessionMessagesResponse>;
+    /**
+     * Resolve a session's authoritative message list: the `messages` channel of
+     * the most recent checkpoint that carries a usable one, plus each message
+     * index's first-appearance timestamp. Returns null when no checkpoint has a
+     * usable `messages` channel.
+     *
+     * Both the messages endpoint and the sessions-list `message_count` derive
+     * from this so the two always agree — `message_count` reports the
+     * number of messages, not the number of checkpoints.
+     */
+    private loadAuthoritativeMessages;
+    /**
+     * Materialize a bounded checkpoint window across one or more thread keys.
+     *
+     * The scan is wrapped in a wall-clock deadline rather than checked between
+     * yields: the driver's `MongoClient` is constructed without socket/read
+     * timeouts, so a stalled cursor can leave the `for await` parked forever and
+     * an in-loop clock check would never run.
+     */
+    private collectCheckpointsForThreadIds;
+    private streamCheckpointsForThreadIds;
+    private aggregateSessionSummaries;
+    /**
+     * Count messages per session from the same authoritative list the messages
+     * endpoint returns, so a summary's `message_count` matches that endpoint
+     * exactly. Sessions with no usable checkpoint count as 0.
+     *
+     * Unlike the single-session messages endpoint — where a corrupt checkpoint
+     * rightly surfaces as a 500 — a failed read here degrades that one session's
+     * count to 0 and leaves the rest of the list intact. One unreadable session
+     * must not take down a summaries request naming hundreds of others.
+     */
+    private collectMessageCounts;
+    private collectPreviews;
+    /**
+     * Return the first non-empty human-message preview across `writes`.
+     *
+     * `writes` is the per-session accumulation from the preview pipeline,
+     * ordered oldest-first. Returns `""` if no write decodes to a human
+     * message with text content.
+     */
+    private firstNonEmptyHumanPreview;
+    /**
+     * Decode a single `checkpoint_writes` document and return the first
+     * human-authored text content it contains, truncated.
+     *
+     * Returns `""` for non-human writes, malformed writes, and any
+     * deserialization failures (logged at WARNING for observability).
+     */
+    private decodeHumanPreview;
+}
+//# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAwB,WAAW,EAAE,MAAM,SAAS,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAC;AAC5E,OAAO,EAIL,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAE7B,MAAM,8BAA8B,CAAC;AAwDtC,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACvD;AAED,yDAAyD;AACzD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAuB;IAC7D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAuB;IACxD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAEtB;gBAEF,MAAM,EAAE,0BAA0B;IAa9C;;;;;;;;OAQG;IACH,OAAO,CAAC,oBAAoB;IActB,uBAAuB,CAC3B,UAAU,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,uBAAuB,CAAC;IAS7B,qBAAqB,CACzB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,uBAAuB,CAAC;IAmBnC;;;;;;;;;OASG;YACW,yBAAyB;IAqCvC;;;;;;;OAOG;YACW,8BAA8B;YAU9B,6BAA6B;YAuB7B,yBAAyB;IA0CvC;;;;;;;;;OASG;YACW,oBAAoB;YAgCpB,eAAe;IAsC7B;;;;;;OAMG;YACW,yBAAyB;IAWvC;;;;;;OAMG;YACW,kBAAkB;CAiCjC"}