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

package/dist/runtime.d.ts

@@ -0,0 +1,336 @@
+/**
+ * LangChain SDK Runtime.
+ *
+ * Port of `agent_engine_sdk_langgraph/runtime.py`.
+ */
+import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import { type StructuredTool } from "@langchain/core/tools";
+import { type ZodType } from "zod";
+import { BaseApp, LLMToolSchema, type ToolDefinition } from "@mongodb-js/agent-engine-sdk";
+import { Memory } from "@mongodb-js/agent-engine-sdk-memory";
+import { RuntimeMode, type SessionFinishStatus } from "@mongodb-js/agent-engine-runner-shared";
+import type { AnyBackendProtocol } from "deepagents";
+import type { BaseCheckpointSaver } from "@langchain/langgraph";
+import { LangGraphBaseAgent } from "./agent.js";
+import type { PrepareAgentInput, ResolveThreadId } from "./agent.js";
+import { createAgentEngineDeepAgent, type CreateAgentEngineDeepAgentOptions } from "./deep_agent.js";
+import { PlatformCheckpointer } from "./platform_checkpointer.js";
+/** Options for {@link App.deepAgent}. */
+export interface DeepAgentOptions extends Omit<CreateAgentEngineDeepAgentOptions, "checkpointer" | "skillsBaseDir"> {
+    /**
+     * Checkpointer selection. Omitted (`undefined`) resolves to
+     * `app.checkpointer()` (MongoDB when configured, else none). `false` disables
+     * checkpointing. A `BaseCheckpointSaver` instance is used directly.
+     *
+     * Note the mapping differs from Python (`None` disables there): in TS,
+     * "disable" is `false`, and "use the default" is simply leaving it out.
+     */
+    checkpointer?: BaseCheckpointSaver | boolean;
+    /**
+     * Backend for filesystem/shell ops. Defaults to `AgentEngineToolPodBackend`, so
+     * every op is OE-audited and sandboxed in the Tool Pod. Pass a custom backend
+     * (e.g. deepagents' in-memory `StateBackend`) to override — note that doing so
+     * bypasses the OE audit path.
+     */
+    backend?: AnyBackendProtocol;
+}
+export type ToolDefinitionData = ToolDefinition;
+export interface AppOptions {
+    appName: string;
+    appVersion?: string;
+    mongodbUri?: string | null;
+    databaseName?: string | null;
+    tracesCollectionName?: string;
+    /** @deprecated Ignored. The org is taken from the `ORG_ID` env var, which the platform injects. */
+    orgId?: string | null;
+}
+export interface ToolDecoratorOptions {
+    isLocal?: boolean;
+    providerType?: string;
+    scopes?: readonly string[];
+    network?: readonly string[];
+    timeout?: number;
+    redactFields?: readonly string[];
+    /**
+     * Human-readable description shown to the LLM (mirrors Python's docstring).
+     * TypeScript has no docstring introspection, so callers pass it explicitly.
+     */
+    description?: string;
+    /**
+     * Zod schema describing the tool's arguments. Without it, the LLM has no
+     * structured view of the parameters and tool calling will fail. Mirrors the
+     * type hints + Pydantic-style auto-schema that Python's `@app.tool()`
+     * derives from the function signature.
+     */
+    schema?: ZodType;
+    /** Override the registered tool name. Defaults to the wrapped function's `name`. */
+    name?: string;
+}
+/**
+ * LangChain SDK for the Atlas Agent Engine.
+ *
+ * @example
+ * ```ts
+ * import { App } from '@mongodb-js/agent-engine-sdk-langgraph';
+ *
+ * const app = new App({ appName: 'My Agent' });
+ *
+ * app.tool()((args: { query: string }) => 'result');
+ *
+ * app.entrypoint(() => {
+ *   const llm = app.llm(chatModel);
+ *   const checkpointer = app.checkpointer();
+ *   const tools = app.getTools();
+ *   // Build LangGraph...
+ *   return graph;
+ * });
+ * ```
+ */
+export declare class App extends BaseApp {
+    private readonly runtime;
+    private builderFn;
+    private graphCache;
+    private prepareInputFn;
+    private resolveThreadIdFn;
+    private readonly toolDefs;
+    private readonly lcTools;
+    private mongoClient;
+    private _checkpointer;
+    private readonly mcpToolsReady;
+    private resolvedCheckpointDb;
+    private _memory;
+    /**
+     * Unified memory facade over app-bound adapters.
+     *
+     * Lazily constructed on first access and cached (a long-lived singleton over
+     * per-request context). Operations resolve the end-user and session from the
+     * ambient execution context, so agent code calls `app.memory.saveSemantic(...)`
+     * without threading identity through. Requests route through the OE memory
+     * proxy; memory is reachable only while handling a platform request.
+     */
+    get memory(): Memory;
+    constructor(options: AppOptions);
+    /**
+     * Resolved once configured MCP servers have been discovered and registered
+     * as tools. `TenantRuntime.runAsync()` awaits this (via `GraphBuilderLike.ready()`)
+     * before starting the server.
+     */
+    ready(): Promise<void>;
+    /**
+     * Discover configured MCP servers' tools and register them the same way
+     * `App.tool()` registers author-declared tools. Port of Python's
+     * `_register_mcp_tools_from_config`.
+     */
+    private registerMcpTools;
+    get agentConfig(): ReturnType<typeof this.runtime.getAgentConfig>;
+    getToolDefinitions(): ToolDefinitionData[];
+    tools(): unknown[];
+    private registerToolDefinition;
+    /**
+     * Register a tool function.
+     *
+     * Returns a function that, when applied to a tool function, registers it
+     * and returns the function unchanged. Mirrors Python's `@app.tool()` shape.
+     */
+    tool(options?: ToolDecoratorOptions): <F extends (...input: never[]) => unknown>(fn: F) => F;
+    /** Mark the graph builder function. */
+    entrypoint<F extends () => unknown>(fn: F): F;
+    /**
+     * Register a hook that builds the graph's starting input from the caller's
+     * `AgentInput` and `RequestContext` for a fresh execution. Resume stays
+     * platform-managed. Returns the function unchanged so it can be used as a
+     * decorator. Equivalent to the Python SDK's `@app.prepare_agent_input`.
+     */
+    prepareAgentInput<F extends PrepareAgentInput>(fn: F): F;
+    /**
+     * Register a hook that builds the LangGraph checkpoint `thread_id`.
+     *
+     * Callers manage Atlas Agent Engine `session_id` (and authenticated `user_id`). The
+     * agent owns how those map to the LangGraph checkpoint key. When registered,
+     * the hook's return value is used verbatim on every invocation — fresh and
+     * resume — with no workspace suffix appended. When no hook is registered,
+     * the adapter derives `session_id:workspace_id` as today.
+     *
+     * Custom keys are invisible to Atlas Agent Engine session-history queries
+     * (`/query/sessions*`), which still look up only the default
+     * session/workspace-derived keys. Agents that bypass workspace scoping also
+     * own collision isolation within the checkpoint database.
+     *
+     * Equivalent to the Python SDK's `@app.resolve_thread_id`.
+     *
+     * @example
+     * ```ts
+     * app.resolveThreadId((ctx) => `${ctx.sessionId}__${actorFrom(ctx.userId)}`);
+     * ```
+     */
+    resolveThreadId<F extends ResolveThreadId>(fn: F): F;
+    /**
+     * Build and return a `LangGraphBaseAgent` instance.
+     *
+     * Matches `GraphBuilderLike.getAgent({ callbacks? })` — agent-engine-runner-shared's
+     * `TenantRuntime.registerAndRun` introspects this method to compile the graph.
+     * Accepts an options object with an optional `callbacks` array, each wrapped
+     * in `LangGraphCallbackAdapter` before being passed to the graph.
+     */
+    getAgent(opts?: {
+        callbacks?: readonly unknown[];
+    }): LangGraphBaseAgent;
+    /**
+     * Return the materialized graph, building it at most once.
+     *
+     * `getAgent()` used to call the entrypoint on every `/execute` — real,
+     * measurable first-invoke latency. The graph carries no per-request
+     * state (callbacks/agent wrapper are still rebuilt fresh by every
+     * `getAgent()` call), so caching it is safe.
+     */
+    private getOrBuildGraph;
+    /**
+     * Build and cache the graph when explicitly requested. The TypeScript AER
+     * intentionally leaves construction on the existing lazy `/execute` path:
+     * this synchronous builder cannot run during standby warming without
+     * blocking the Node event loop and server health.
+     */
+    warmUp(): void;
+    /**
+     * Start the agent service.
+     *
+     * Async because the per-project store-DB name is resolved against the live
+     * cluster (an async listDatabases round trip in the Node driver) before the
+     * query plugin and checkpointer are wired, so AER writes land in the same
+     * database the OE reads. The synchronous framework hooks are still registered
+     * before the first `await`, preserving their ordering relative to startup.
+     */
+    run(options?: Record<string, unknown>): Promise<void>;
+    /**
+     * Resolve the store DB name once, before the checkpointer and query plugin
+     * are constructed. Honors `CHECKPOINT_DB_NAME` as an exact override (no
+     * project scoping). No-op outside AER mode or without a MongoDB URI when
+     * the override is unset (the checkpointer returns null in those cases).
+     */
+    private resolveCheckpointDbName;
+    /**
+     * Exact `CHECKPOINT_DB_NAME` override when set, else null.
+     * Shared by resolve / checkpointer / query plugin so the three paths cannot
+     * drift on trim/precedence.
+     */
+    private checkpointDbOverride;
+    /**
+     * Final MongoDBSaver / query-plugin database name for this app.
+     * Prefer the exact env override; otherwise the resolved (or base) store DB.
+     */
+    private checkpointDbName;
+    /**
+     * Register the LangGraph-backed `AERQueryPlugin` (AER mode only). A
+     * missing MongoDB URI or a failing checkpointer construction degrades to
+     * "no plugin" (routes return 501) instead of failing startup.
+     */
+    private registerQueryPlugin;
+    /**
+     * Register framework-specific hooks so agent-engine-runner-shared can dispatch to
+     * LangChain/LangGraph code without importing this package. Mirrors Python's
+     * `App._register_hooks` (static method).
+     */
+    private static registerHooks;
+    /**
+     * Wrap a LangChain LLM for audited I/O through the Orchestration Engine.
+     *
+     * In AER mode the LLM is wrapped in `SecureWrappedLLM`. In TOOL mode the raw
+     * LLM is returned unwrapped (the tool pod is the execution end of the chain).
+     *
+     * For agents with a single LLM, call without `llmId`. For agents with
+     * multiple LLMs every call must supply a unique `llmId`:
+     *   const fast    = app.llm(ChatOpenAI("gpt-5.4-mini"), "fast")
+     *   const primary = app.llm(ChatOpenAI("gpt-5.4"),      "primary")
+     * Unnamed calls register under the sentinel id `"__default__"`; a second
+     * unnamed call therefore raises the same duplicate-id error as a second
+     * named call with the same id.
+     */
+    llm(llm: BaseChatModel, llmId?: string): BaseChatModel;
+    /**
+     * Get the platform checkpointer for LangGraph.
+     *
+     * Lazily constructs and wraps a `MongoDBSaver` on first call in AER mode.
+     * Native sessions use that saver through the request-scoped platform
+     * wrapper. The underlying `MongoClient` is closed by `App.close()`.
+     *
+     * The database name is read from `CHECKPOINT_DB_NAME` when set (exact
+     * override, no project scoping). Otherwise the existing
+     * `MDB_AGENTIC_STORE_DB` / per-project store resolution is used
+     * (default: `"mdb_store"`). The URI comes from `MONGODB_URI` — the same
+     * source `TenantRuntime` uses internally.
+     *
+     * Mirrors Python `runtime.py:checkpointer()`.
+     */
+    checkpointer(): PlatformCheckpointer | null;
+    /**
+     * Build a deepagents graph pre-wired for Atlas Agent Engine AER.
+     *
+     * Wraps `llm` in `SecureWrappedLLM`, resolves relative skill paths, validates
+     * the subagent tree (string models are rejected — they would bypass OE
+     * routing), then delegates to deepagents' `createDeepAgent`.
+     *
+     * Each `skills` entry is a parent source directory. At runtime, deepagents
+     * lists it through the configured backend and treats each immediate child
+     * directory containing `SKILL.md` as one skill; discovery is not recursive.
+     * deepagents skips unreadable or unparsable frontmatter and skills missing
+     * `name` or `description`; it warns but may still load Agent Skills naming or
+     * directory-name violations.
+     *
+     * Mirrors Python `runtime.py:App.deep_agent()`.
+     *
+     * @throws {Error} `features.deep_agent` is not enabled, or a subagent spec
+     *   uses a string model, or nesting exceeds the recursion cap.
+     */
+    deepAgent(llm: BaseChatModel, options?: DeepAgentOptions): ReturnType<typeof createAgentEngineDeepAgent>;
+    /**
+     * Resolve the base directory for relative skill paths: the directory
+     * containing `agent.yaml`, optionally narrowed by the source-root-relative
+     * `AGENTIC_SKILLS_DIR` override.
+     */
+    private resolveSkillsBaseDir;
+    /** Release resources held by this App instance. */
+    close(): Promise<void>;
+    /**
+     * Get wrapped tools for LangGraph's `ToolNode`.
+     *
+     * In AER mode, every tool is wrapped with `SecureToolWrapper` (via
+     * `createSecureToolFunction`) so executions route through OE for logging
+     * and policy enforcement. In other modes, the raw LangChain tools are
+     * returned unchanged.
+     */
+    getTools(): readonly StructuredTool[];
+    /** Get tool schemas for `llm.bindTools()`. Always the unwrapped LangChain tools. */
+    getToolSchemas(): readonly unknown[];
+    /**
+     * Generate a suspend command. If a tool should suspend, return the result of
+     * this method instead of completing normally.
+     */
+    suspend(reason: string, context: Record<string, unknown>): string;
+    /**
+     * Mark this session finished so the platform frees its compute now.
+     *
+     * Call it when the agent is done with the session. The current turn keeps
+     * running and returns its result normally; once it completes, the platform
+     * cancels any live sub-agent runs and releases the session's AER and tool
+     * pods instead of holding them until the idle timeout expires.
+     *
+     * Safe to call more than once: the first call returns "requested", later
+     * ones "already_requested". Outside an agent run (local scripts, tool pods)
+     * there is no session to finish and the call returns "unavailable" without
+     * throwing. Calling it after the turn has already ended - e.g. from a
+     * setTimeout or a floating promise scheduled during the turn but resolving
+     * after it - also returns "unavailable": by then nothing is listening for
+     * the request anymore, so reporting "requested" would promise a release
+     * that will never happen.
+     *
+     * A turn that suspends for human review, or that fails, keeps its
+     * resources so it stays resumable and diagnosable; the session then falls
+     * back to the idle timeout.
+     */
+    finishSession(): SessionFinishStatus;
+    getCurrentUserId(): string | null;
+    getCurrentSessionId(): string | null;
+}
+export { LLMToolSchema };
+export { RuntimeMode };
+//# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

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