@mongodb-js/agent-engine-runner-shared 0.11.3

package/dist/mcp_tools.js

@@ -0,0 +1,301 @@
+/**
+ * Framework-neutral helpers for remote MCP tool discovery and execution.
+ *
+ * Port of `agent_engine_runner_shared/mcp_tools.py`. Built directly on
+ * `@modelcontextprotocol/sdk` (mirroring Python's `mcp` PyPI package) rather
+ * than a framework-specific adapter, since the platform needs custom result
+ * normalization, egress host derivation, and the Tool-Pod/AER dispatch split
+ * that a framework wrapper doesn't support.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+const UNSAFE_TOOL_NAME_CHARS_RE = /[^a-zA-Z0-9_]/g;
+const LEADING_TRAILING_UNDERSCORES_RE = /^_+|_+$/g;
+const MAX_LIST_TOOL_PAGES = 100;
+const MAX_TOOLS_PER_SERVER = 10_000;
+/** Raised when remote MCP configuration cannot be resolved. */
+export class MCPConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MCPConfigError";
+    }
+}
+/** Raised when a remote MCP tool returns an MCP error result or a transport failure occurs. */
+export class MCPToolError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MCPToolError";
+    }
+}
+/** Return the server-prefixed SDK name for a remote MCP tool. */
+export function makeMcpSdkToolName(serverName, toolName) {
+    const serverPart = sanitizeToolNamePart(serverName);
+    const toolPart = sanitizeToolNamePart(toolName);
+    return `${serverPart}__${toolPart}`;
+}
+// Provider names can contain punctuation that downstream LLM tool-call APIs
+// reject, so the SDK exposes a stable identifier and keeps the original MCP
+// tool name only for the outbound tools/call request.
+function sanitizeToolNamePart(value) {
+    let sanitized = value
+        .trim()
+        .replace(UNSAFE_TOOL_NAME_CHARS_RE, "_")
+        .replace(LEADING_TRAILING_UNDERSCORES_RE, "");
+    if (sanitized === "") {
+        throw new MCPConfigError("mcp server and tool names must contain alphanumeric characters");
+    }
+    if (/^[0-9]/.test(sanitized)) {
+        sanitized = `mcp_${sanitized}`;
+    }
+    return sanitized;
+}
+/** Resolve headers for a remote MCP server without exposing secret values in config. */
+export function resolveMcpHeaders(serverName, config) {
+    const headers = { ...config.headers };
+    if (config.auth.type === "none" ||
+        config.auth.type === "oauth" ||
+        config.auth.type === "client_credentials") {
+        return headers;
+    }
+    const tokenEnv = config.auth.token_env;
+    if (tokenEnv === null) {
+        throw new MCPConfigError(`mcp server '${serverName}' auth.token_env is required`);
+    }
+    const token = process.env[tokenEnv];
+    if (token === undefined || token.trim() === "") {
+        throw new MCPConfigError(`mcp server '${serverName}' references missing env var ${tokenEnv}`);
+    }
+    headers["Authorization"] = `Bearer ${token.trim()}`;
+    return headers;
+}
+/** Resolve an MCP SDK OAuth provider for the configured auth mode, if any. */
+export async function resolveMcpAuth(serverName, config) {
+    if (config.auth.type === "none" || config.auth.type === "bearer_env") {
+        return undefined;
+    }
+    const { makeMcpOauthAuth, makeMcpClientCredentialsAuth } = await import("./mcp_oauth.js");
+    try {
+        if (config.auth.type === "oauth") {
+            return makeMcpOauthAuth(serverName, config);
+        }
+        if (config.auth.type === "client_credentials") {
+            return makeMcpClientCredentialsAuth(serverName, config);
+        }
+    }
+    catch (err) {
+        throw new MCPConfigError(err instanceof Error ? err.message : String(err));
+    }
+    throw new MCPConfigError(`mcp server '${serverName}' has unsupported auth.type ${config.auth.type}`);
+}
+/** Return the outbound hosts needed to reach a configured MCP server. */
+export function mcpServerNetworkHosts(config) {
+    const hosts = [new URL(config.url).hostname];
+    if (config.auth.token_url !== null) {
+        const tokenHost = new URL(config.auth.token_url).hostname;
+        if (!hosts.includes(tokenHost))
+            hosts.push(tokenHost);
+    }
+    return hosts;
+}
+/**
+ * Discover remote MCP tools for all configured servers.
+ *
+ * Mirrors common MCP client adapters: initialize each server, call
+ * `tools/list`, then expose the returned schemas as framework-native tools.
+ */
+export async function discoverMcpTools(config) {
+    const bindings = [];
+    const usedNames = new Map();
+    for (const [serverName, serverConfig] of Object.entries(config.servers)) {
+        let tools = await listServerTools(serverName, serverConfig);
+        const availableToolNames = new Set(tools.map((tool) => tool.name));
+        const allowedTools = serverConfig.allowed_tools;
+        if (allowedTools !== null) {
+            const missing = allowedTools
+                .filter((name) => !availableToolNames.has(name))
+                .sort();
+            if (missing.length > 0) {
+                throw new MCPConfigError(`mcp server '${serverName}' did not expose configured allowed_tools: ${missing.join(", ")}`);
+            }
+            const allowedSet = new Set(allowedTools);
+            tools = tools.filter((tool) => allowedSet.has(tool.name));
+        }
+        for (const tool of tools) {
+            const sdkToolName = makeMcpSdkToolName(serverName, tool.name);
+            const previous = usedNames.get(sdkToolName);
+            if (previous !== undefined) {
+                throw new MCPConfigError(`mcp tool name collision for '${sdkToolName}': ${previous} and ${serverName}.${tool.name}`);
+            }
+            usedNames.set(sdkToolName, `${serverName}.${tool.name}`);
+            bindings.push({
+                serverName,
+                toolName: tool.name,
+                sdkToolName,
+                description: tool.description ?? "",
+                inputSchema: tool.inputSchema,
+                serverConfig,
+            });
+        }
+    }
+    return bindings;
+}
+/**
+ * Map an SDK-visible tool name back to configured MCP call metadata.
+ *
+ * AER discovers remote MCP schemas at startup and exposes server-prefixed
+ * names such as `github__search_issues` to the LLM. Tool Pods skip
+ * `tools/list` startup discovery, so call-time execution resolves that SDK
+ * name against `agent.yaml` and calls the original MCP tool name.
+ */
+export function resolveConfiguredMcpToolBinding(config, sdkToolName, mcpServerName, mcpToolName) {
+    const serverConfig = config.servers[mcpServerName];
+    if (serverConfig === undefined)
+        return null;
+    const expectedSdkToolName = makeMcpSdkToolName(mcpServerName, mcpToolName);
+    if (expectedSdkToolName !== sdkToolName) {
+        throw new MCPConfigError(`mcp call metadata for '${mcpServerName}'.'${mcpToolName}' does not match '${sdkToolName}'`);
+    }
+    if (serverConfig.allowed_tools !== null &&
+        !serverConfig.allowed_tools.includes(mcpToolName)) {
+        throw new MCPConfigError(`mcp server '${mcpServerName}' tool '${mcpToolName}' is not in allowed_tools`);
+    }
+    return {
+        serverName: mcpServerName,
+        toolName: mcpToolName,
+        sdkToolName,
+        description: "",
+        inputSchema: {},
+        serverConfig,
+    };
+}
+/** Return whether `sdkToolName` belongs to a configured MCP server. */
+export function isConfiguredMcpSdkToolName(config, sdkToolName) {
+    for (const serverName of Object.keys(config.servers)) {
+        const serverPrefix = `${sanitizeToolNamePart(serverName)}__`;
+        if (sdkToolName.startsWith(serverPrefix) &&
+            sdkToolName.length > serverPrefix.length) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Execute a remote MCP tool and normalize its result. */
+export async function callMcpTool(binding, args) {
+    return withMcpSession(binding.serverName, binding.serverConfig, `tool '${binding.toolName}'`, async (client) => {
+        const result = await client.callTool({
+            name: binding.toolName,
+            arguments: args,
+        });
+        // `callTool()`'s return type also covers the deprecated `{ toolResult }`
+        // shape from pre-2025-06-18 servers; MCP tool servers we target return
+        // the standard `content`/`structuredContent`/`isError` shape.
+        return normalizeMcpToolResult(result);
+    }, MCPToolError);
+}
+/** Create the async callable used to invoke a discovered MCP tool. */
+export function makeMcpToolCallable(binding) {
+    return (args) => callMcpTool(binding, args);
+}
+/** Convert an MCP `CallToolResult` into a JSON-safe result, raising on an error result. */
+export function normalizeMcpToolResult(result) {
+    const content = result.content ?? [];
+    ensureJsonSafe("content", content);
+    const rawStructuredContent = result.structuredContent ?? null;
+    if (rawStructuredContent !== null) {
+        if (typeof rawStructuredContent !== "object" ||
+            Array.isArray(rawStructuredContent)) {
+            throw new MCPToolError("MCP tool returned structuredContent that is not an object");
+        }
+        ensureJsonSafe("structuredContent", rawStructuredContent);
+    }
+    const normalized = {
+        content,
+        structuredContent: rawStructuredContent,
+        isError: Boolean(result.isError),
+    };
+    if (result.isError) {
+        const textParts = [];
+        for (const block of content) {
+            if (block !== null && typeof block === "object") {
+                const b = block;
+                if (b["type"] === "text" &&
+                    typeof b["text"] === "string" &&
+                    b["text"]) {
+                    textParts.push(b["text"]);
+                }
+            }
+        }
+        if (textParts.length > 0) {
+            throw new MCPToolError(`MCP tool returned error: ${textParts.join("\n")}`);
+        }
+        throw new MCPToolError("MCP tool returned an error");
+    }
+    return normalized;
+}
+function ensureJsonSafe(fieldName, value) {
+    try {
+        JSON.stringify(value);
+    }
+    catch {
+        throw new MCPToolError(`MCP tool returned non-JSON-serializable ${fieldName}`);
+    }
+}
+async function listServerTools(serverName, config) {
+    return withMcpSession(serverName, config, "tools/list", async (client) => {
+        const tools = [];
+        let cursor;
+        for (let page = 0; page < MAX_LIST_TOOL_PAGES; page++) {
+            const result = await client.listTools({ cursor });
+            tools.push(...result.tools.map((tool) => ({
+                name: tool.name,
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+            })));
+            if (tools.length > MAX_TOOLS_PER_SERVER) {
+                throw new MCPConfigError(`mcp server '${serverName}' returned more than ${MAX_TOOLS_PER_SERVER} tools`);
+            }
+            cursor = result.nextCursor;
+            if (cursor === undefined)
+                return tools;
+        }
+        throw new MCPConfigError(`mcp server '${serverName}' tools/list exceeded ${MAX_LIST_TOOL_PAGES} pages`);
+    });
+}
+async function withMcpSession(serverName, config, operation, fn, 
+// Discovery (tools/list) failures are config-adjacent — they happen once at
+// startup against a server the tenant configured — so they wrap as
+// MCPConfigError. Invocation (tools/call) failures are per-call runtime
+// errors and wrap as MCPToolError, matching its docstring ("...or a
+// transport failure occurs") and Python's mcp_tools.py split between
+// _list_server_tools (MCPConfigError) and _call_mcp_tool (MCPToolError).
+transportErrorClass = MCPConfigError) {
+    const headers = resolveMcpHeaders(serverName, config);
+    const authProvider = await resolveMcpAuth(serverName, config);
+    const transport = new StreamableHTTPClientTransport(new URL(config.url), {
+        requestInit: {
+            headers,
+            signal: AbortSignal.timeout(config.timeout_seconds * 1000),
+        },
+        authProvider,
+    });
+    const client = new Client({
+        name: "agent-engine-runner",
+        version: "1.0.0",
+    });
+    try {
+        await client.connect(transport);
+        return await fn(client);
+    }
+    catch (err) {
+        if (err instanceof MCPConfigError || err instanceof MCPToolError)
+            throw err;
+        throw new transportErrorClass(mcpTransportErrorMessage(serverName, operation, err));
+    }
+    finally {
+        await client.close().catch(() => { });
+    }
+}
+function mcpTransportErrorMessage(serverName, operation, err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return `mcp server '${serverName}' ${operation} failed: ${message}`;
+}

package/dist/memory_appbound.d.ts

@@ -0,0 +1,42 @@
+/**
+ * App-bound memory adapters for the platform runtime.
+ *
+ * These let the unified `Memory` facade from `@mongodb-js/agent-engine-sdk-memory`
+ * run in app-bound mode (inside an agent, on the platform stack). App-bound memory
+ * routes through the Orchestration Engine's memory proxy, which serves the aliased
+ * memory routes (`/api/v1/memory/{turns,context,search}` plus the CRUD paths) and
+ * stamps org/project from the trusted execution context.
+ *
+ * So the adapters are thin: each call reads the current request context
+ * (`OE_URL`, execution id, user id, session id), builds a `MemoryClientAdapter`
+ * pointed at the OE with mTLS and the execution-id header, and delegates. Identity
+ * is ambient — `requestContext()` exposes the per-request user/session so the
+ * facade resolves them without the agent author threading them through.
+ */
+import { type ContextResponse, type CreateEpisodicResult, type CreateProceduralResult, type CreateSemanticResult, type CreateTaxonomicResult, type CustomMemoryRetrieveResult, type CustomMemorySaveResult, type MemoryChunk, type MemoryCrudClient, type MemoryRequestContext, type MemoryRuntime, type WriteTurnResult } from "@mongodb-js/agent-engine-sdk-memory";
+/** `MemoryRuntime` over the OE memory proxy, exposing ambient identity. */
+export declare class AppBoundRuntime implements MemoryRuntime {
+    /** Fresh identity from the runner context; blank fields are normalized by the facade. */
+    requestContext(): MemoryRequestContext | null;
+    recordTurn(args: Parameters<MemoryRuntime["recordTurn"]>[0]): Promise<WriteTurnResult>;
+    buildContext(args: Parameters<MemoryRuntime["buildContext"]>[0]): Promise<ContextResponse>;
+    searchSemantic(args: Parameters<MemoryRuntime["searchSemantic"]>[0]): Promise<MemoryChunk[]>;
+    searchEpisodes(args: Parameters<MemoryRuntime["searchEpisodes"]>[0]): Promise<MemoryChunk[]>;
+    searchTaxonomic(args: Parameters<MemoryRuntime["searchTaxonomic"]>[0]): Promise<MemoryChunk[]>;
+    discoverProcedures(args: Parameters<MemoryRuntime["discoverProcedures"]>[0]): Promise<Array<Record<string, unknown>>>;
+}
+/** `MemoryCrudClient` over the OE memory proxy. */
+export declare class AppBoundCrudClient implements MemoryCrudClient {
+    createSemantic(args: Parameters<MemoryCrudClient["createSemantic"]>[0]): Promise<CreateSemanticResult>;
+    getSemantic(args: Parameters<MemoryCrudClient["getSemantic"]>[0]): Promise<unknown | null>;
+    createEpisodic(args: Parameters<MemoryCrudClient["createEpisodic"]>[0]): Promise<CreateEpisodicResult>;
+    listEpisodic(args: Parameters<MemoryCrudClient["listEpisodic"]>[0]): Promise<unknown[]>;
+    createTaxonomic(args: Parameters<MemoryCrudClient["createTaxonomic"]>[0]): Promise<CreateTaxonomicResult>;
+    getTaxonomic(args: Parameters<MemoryCrudClient["getTaxonomic"]>[0]): Promise<unknown | null>;
+    getDistinctDomains(args: Parameters<MemoryCrudClient["getDistinctDomains"]>[0]): Promise<string[]>;
+    createProcedural(args: Parameters<MemoryCrudClient["createProcedural"]>[0]): Promise<CreateProceduralResult>;
+    getProcedural(args: Parameters<MemoryCrudClient["getProcedural"]>[0]): Promise<unknown | null>;
+    createCustom(args: Parameters<MemoryCrudClient["createCustom"]>[0]): Promise<CustomMemorySaveResult>;
+    retrieveCustom(args: Parameters<MemoryCrudClient["retrieveCustom"]>[0]): Promise<CustomMemoryRetrieveResult>;
+}
+//# sourceMappingURL=memory_appbound.d.ts.map

package/dist/memory_appbound.d.ts.map

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

package/dist/memory_appbound.js

@@ -0,0 +1,159 @@
+/**
+ * App-bound memory adapters for the platform runtime.
+ *
+ * These let the unified `Memory` facade from `@mongodb-js/agent-engine-sdk-memory`
+ * run in app-bound mode (inside an agent, on the platform stack). App-bound memory
+ * routes through the Orchestration Engine's memory proxy, which serves the aliased
+ * memory routes (`/api/v1/memory/{turns,context,search}` plus the CRUD paths) and
+ * stamps org/project from the trusted execution context.
+ *
+ * So the adapters are thin: each call reads the current request context
+ * (`OE_URL`, execution id, user id, session id), builds a `MemoryClientAdapter`
+ * pointed at the OE with mTLS and the execution-id header, and delegates. Identity
+ * is ambient — `requestContext()` exposes the per-request user/session so the
+ * facade resolves them without the agent author threading them through.
+ */
+import { MemoryClientAdapter, MemoryNotSupportedError, ContextResponseSchema, } from "@mongodb-js/agent-engine-sdk-memory";
+import { getCurrentExecutionId, getCurrentOeUrl, getCurrentSessionId, getCurrentUserId, getCurrentWorkspaceId, } from "./context.js";
+import { fetchPlatform, getFetchOptionsWithTLS } from "./tls_client.js";
+import { isMemoryReadOwnedByTool } from "./tool_memory_ownership.js";
+import { ActivityKind, WorkflowClient, allocateActivityOrdinal, currentAttemptContext, runSerialActivity, } from "./workflow/index.js";
+const EXECUTION_ID_HEADER = "X-Agent-Engine-Execution-Id";
+/** Legacy name, dual-sent during the rename transition; servers prefer EXECUTION_ID_HEADER. */
+const EXECUTION_ID_HEADER_LEGACY = "X-Agentic-Execution-Id";
+const AGENT_ID_HEADER = "X-Agent-Engine-Agent-Id";
+const AGENT_ID_HEADER_LEGACY = "X-Agentic-Agent-Id";
+/** The OE memory proxy serves the flat memory routes under this prefix. */
+const OE_MEMORY_PREFIX = "/api/v1/memory";
+/**
+ * Build a `MemoryClientAdapter` bound to the current request context.
+ *
+ * Reads `OE_URL` fresh per call because `app.memory` is a long-lived singleton
+ * over per-request context. mTLS options and the execution-id header are layered
+ * in so the OE can authenticate the connection and attribute the call.
+ */
+function adapterFromContext() {
+    const oeUrl = getCurrentOeUrl();
+    if (oeUrl === null || oeUrl.trim() === "") {
+        throw new MemoryNotSupportedError("app-bound memory is unavailable: no OE_URL in the current execution " +
+            "context (memory is only reachable while handling a platform request)");
+    }
+    const executionId = getCurrentExecutionId();
+    const headers = {};
+    if (executionId !== null && executionId !== "") {
+        headers[EXECUTION_ID_HEADER] = executionId;
+        headers[EXECUTION_ID_HEADER_LEGACY] = executionId;
+    }
+    const workspaceId = getCurrentWorkspaceId();
+    if (workspaceId !== null && workspaceId !== "") {
+        headers[AGENT_ID_HEADER] = workspaceId;
+        headers[AGENT_ID_HEADER_LEGACY] = workspaceId;
+    }
+    return new MemoryClientAdapter({
+        baseUrl: oeUrl,
+        apiPrefix: OE_MEMORY_PREFIX,
+        routeStyle: "aliased",
+        projectScoped: false,
+        headers,
+        fetchImpl: fetchPlatform,
+        requestExtras: () => getFetchOptionsWithTLS(oeUrl) ?? {},
+    });
+}
+/** Canonical JSON input used to identify a durable context read. */
+function buildContextActivityInput(args) {
+    const input = {
+        query: args.query,
+        user_id: args.userId ?? null,
+        session_id: args.sessionId ?? null,
+        visibility: args.visibility ?? null,
+        metadata_filter: args.metadataFilter ?? null,
+        enabled_sources: args.enabledSources == null ? null : [...args.enabledSources].sort(),
+    };
+    if (args.topK !== undefined)
+        input["top_k"] = args.topK;
+    if (args.maxTokens !== undefined)
+        input["max_tokens"] = args.maxTokens;
+    return input;
+}
+async function runBuildContextActivity(args, execute) {
+    if (currentAttemptContext() === null || isMemoryReadOwnedByTool()) {
+        return execute();
+    }
+    const oeUrl = getCurrentOeUrl();
+    if (oeUrl === null || oeUrl.trim() === "") {
+        throw new MemoryNotSupportedError("durable app-bound context reads require OE_URL in the current execution context");
+    }
+    const result = await runSerialActivity({
+        client: new WorkflowClient(oeUrl),
+        kind: ActivityKind.MEMORY,
+        name: "memory.build_context",
+        activityOrdinal: allocateActivityOrdinal(),
+        semanticInput: buildContextActivityInput(args),
+        execute,
+    });
+    return ContextResponseSchema.parse(result);
+}
+/** `MemoryRuntime` over the OE memory proxy, exposing ambient identity. */
+export class AppBoundRuntime {
+    /** Fresh identity from the runner context; blank fields are normalized by the facade. */
+    requestContext() {
+        return {
+            userId: getCurrentUserId(),
+            sessionId: getCurrentSessionId(),
+        };
+    }
+    async recordTurn(args) {
+        return adapterFromContext().recordTurn(args);
+    }
+    async buildContext(args) {
+        return runBuildContextActivity(args, () => adapterFromContext().buildContext(args));
+    }
+    async searchSemantic(args) {
+        return adapterFromContext().searchSemantic(args);
+    }
+    async searchEpisodes(args) {
+        return adapterFromContext().searchEpisodes(args);
+    }
+    async searchTaxonomic(args) {
+        return adapterFromContext().searchTaxonomic(args);
+    }
+    async discoverProcedures(args) {
+        return adapterFromContext().discoverProcedures(args);
+    }
+}
+/** `MemoryCrudClient` over the OE memory proxy. */
+export class AppBoundCrudClient {
+    async createSemantic(args) {
+        return adapterFromContext().createSemantic(args);
+    }
+    async getSemantic(args) {
+        return adapterFromContext().getSemantic(args);
+    }
+    async createEpisodic(args) {
+        return adapterFromContext().createEpisodic(args);
+    }
+    async listEpisodic(args) {
+        return adapterFromContext().listEpisodic(args);
+    }
+    async createTaxonomic(args) {
+        return adapterFromContext().createTaxonomic(args);
+    }
+    async getTaxonomic(args) {
+        return adapterFromContext().getTaxonomic(args);
+    }
+    async getDistinctDomains(args) {
+        return adapterFromContext().getDistinctDomains(args);
+    }
+    async createProcedural(args) {
+        return adapterFromContext().createProcedural(args);
+    }
+    async getProcedural(args) {
+        return adapterFromContext().getProcedural(args);
+    }
+    async createCustom(args) {
+        return adapterFromContext().createCustom(args);
+    }
+    async retrieveCustom(args) {
+        return adapterFromContext().retrieveCustom(args);
+    }
+}

package/dist/memory_writer.d.ts

@@ -0,0 +1,49 @@
+/** Native-checkpoint conversation-turn ingestion for the TypeScript runner. */
+import type { Message } from "@mongodb-js/agent-engine-sdk";
+import type { MemoryRuntime } from "@mongodb-js/agent-engine-sdk-memory";
+type RecordTurnArgs = Parameters<MemoryRuntime["recordTurn"]>[0];
+export interface WriteTurnArgs {
+    message: string;
+    resultMessages: readonly Message[];
+    userId?: string | null;
+    sessionId?: string | null;
+    includeUserTurn?: boolean;
+}
+export interface TurnMemoryWriter {
+    readonly pendingWrites: number;
+    writeTurnAsync(args: WriteTurnArgs): void;
+    drain(timeoutMs?: number): Promise<boolean>;
+    shutdown(): Promise<void>;
+}
+/**
+ * Extract only the current turn from framework messages.
+ *
+ * The original user prompt is input, so many LangGraph update streams never
+ * emit it. Prepend it explicitly, then skip through an echoed copy when one is
+ * present so prior checkpoint history and the current prompt are not written
+ * twice. Resume legs suppress every user message because they carry no new
+ * user prompt.
+ */
+export declare function extractTurnMessages(message: string, resultMessages: readonly Message[], includeUserTurn?: boolean): RecordTurnArgs[];
+/**
+ * Process-wide, non-blocking turn writer.
+ *
+ * Batches are serialized so concurrent executions cannot interleave messages
+ * within a conversation turn. Failures are logged and swallowed: Memory is a
+ * best-effort side effect and must not replace an otherwise successful agent
+ * result. `drain` lets session release and graceful app replacement wait for
+ * already-queued writes.
+ */
+export declare class MemoryWriter implements TurnMemoryWriter {
+    private readonly runtime;
+    private tail;
+    private pending;
+    private closed;
+    constructor(runtime: Pick<MemoryRuntime, "recordTurn">);
+    get pendingWrites(): number;
+    writeTurnAsync(args: WriteTurnArgs): void;
+    drain(timeoutMs?: number): Promise<boolean>;
+    shutdown(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=memory_writer.d.ts.map

package/dist/memory_writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory_writer.d.ts","sourceRoot":"","sources":["../src/memory_writer.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAI/E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAOzE,KAAK,cAAc,GAAG,UAAU,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAEjE,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,SAAS,OAAO,EAAE,CAAC;IACnC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,cAAc,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAAC;IAC1C,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,SAAS,OAAO,EAAE,EAClC,eAAe,UAAO,GACrB,cAAc,EAAE,CAwDlB;AAgDD;;;;;;;;GAQG;AACH,qBAAa,YAAa,YAAW,gBAAgB;IAKvC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,OAAO,CAAC,IAAI,CAAoC;IAChD,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,MAAM,CAAS;gBAEM,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC;IAEvE,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,cAAc,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAkBnC,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAyB3C,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAQhC"}