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

package/dist/context.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Per-execution context management using AsyncLocalStorage.
+ *
+ * Mirrors Python `agent_engine_runner_shared/context.py` which uses `contextvars.ContextVar`.
+ * Each concurrent execution gets its own isolated context frame, preventing
+ * cross-execution contamination of execution_id, wrapper, and OE URL.
+ *
+ * The single entry point is `runWithExecutionContext(store, fn)`, which runs
+ * `fn` inside an isolated frame via `AsyncLocalStorage#run`. The frame is a
+ * child that never mutates the parent and is torn down automatically when `fn`
+ * settles — even if `fn` throws or spawns async work via setTimeout/Promise.
+ *
+ * Node's `AsyncLocalStorage#enterWith` (a set/clear-token style) is deliberately
+ * avoided: it rebinds the current async frame in place, so the store leaks into
+ * the surrounding context and cannot be reliably restored. The Python
+ * `set_execution_context` / `clear_execution_context` token pair is collapsed
+ * into this callback form, which is the equivalent of Python's
+ * `set_execution_context(...)` + `try/finally clear_execution_context(...)`.
+ */
+import type { ToolAuthorization } from "./models.js";
+export interface ExecutionStore {
+    executionId: string | null;
+    wrapper: unknown | null;
+    oeUrl: string | null;
+    /**
+     * Validated replica-specific OE owner callback URL, or null when
+     * the request carried none / it failed validation. Owner-preferring
+     * transports (e.g. {@link module:progress}) send here first and fall back to
+     * `oeUrl` on any owner failure. Already validated against `oeUrl` by the
+     * caller (see `server/owner_url.ts`), so consumers trust it as-is.
+     */
+    oeOwnerUrl: string | null;
+    /**
+     * One-way owner-failure latch: once an owner pre-attempt fails, later
+     * owner-preferring posts in this execution skip the owner URL entirely
+     * instead of re-paying the pre-attempt timeout on every emit. A nested
+     * object for the same reason as `sessionFinish`: the reference survives
+     * store spreads (e.g. {@link runWithSuspendRequestContext}), a reassigned
+     * field would not. Mirrors the AER stream path's `onOwnerFailure` discard.
+     */
+    ownerUrlFailure: {
+        failed: boolean;
+    };
+    requestId: string | null;
+    /** Platform trace ID for log correlation. */
+    traceId: string | null;
+    userId: string | null;
+    sessionId: string | null;
+    workspaceId: string | null;
+    customHeaders: Record<string, string> | null;
+    executionMetadata: Record<string, unknown> | null;
+    /** Delegated credential injected by OE for tool execution. */
+    authorization: ToolAuthorization | null;
+    /** Opaque caller-provided invocation payload (the request body beyond `message`). */
+    payload: Record<string, unknown> | null;
+    /**
+     * Execution-wide abort signal (fires on the AER execution timeout). Combined
+     * into in-flight OE/LLM fetches via {@link withExecutionSignal} so a timeout
+     * cancels active network I/O instead of leaving it to run. Null outside an
+     * AER execution (e.g. a single Tool Pod call).
+     */
+    signal: AbortSignal | null;
+    /**
+     * Holder for a pending session-finish request. A nested object
+     * rather than a bare boolean: the AER reads it from the frame that started
+     * the run, while agent code deep in the call chain mutates it in place —
+     * the object reference is shared across that chain, a reassigned boolean
+     * field on the store would not be.
+     */
+    sessionFinish: {
+        requested: boolean;
+        closed: boolean;
+    };
+    /**
+     * Out-of-band suspend signal. Only the author-facing
+     * `suspendPayloadToJson` writes it, so untrusted tool-result content — which
+     * cannot reach this process-local frame — can never forge a HITL suspend. A
+     * nested holder for the same reason as `sessionFinish`: a tool offloaded to a
+     * worker thread mutates the shared object, not a reassigned store field.
+     */
+    suspendRequest: {
+        payload: Record<string, unknown> | null;
+    };
+}
+export interface OwnerUrlFailureState {
+    failed: boolean;
+}
+export type SessionFinishStatus = "requested" | "already_requested" | "unavailable";
+export interface SetExecutionContextArgs {
+    executionId: string;
+    wrapper: unknown;
+    oeUrl: string;
+    /** Validated replica-specific OE owner callback URL. */
+    oeOwnerUrl?: string | null;
+    ownerUrlFailure?: OwnerUrlFailureState;
+    requestId?: string | null;
+    traceId?: string | null;
+    userId?: string | null;
+    sessionId?: string | null;
+    workspaceId?: string | null;
+    customHeaders?: Record<string, string> | null;
+    authorization?: ToolAuthorization | null;
+    payload?: Record<string, unknown> | null;
+    signal?: AbortSignal | null;
+}
+/**
+ * Run `fn` with an isolated execution context frame.
+ *
+ * `storage.run` creates a child frame that never mutates the parent, so cleanup
+ * is automatic even if `fn` throws or spawns work via setTimeout/Promise. This
+ * is the equivalent of Python's `set_execution_context(...)` followed by a
+ * try/finally `clear_execution_context(...)`.
+ *
+ * @example
+ *   await runWithExecutionContext({ executionId, wrapper, oeUrl, userId }, async () => {
+ *     await runAgentLogic()  // getCurrentUserId() works anywhere in this call chain
+ *   })
+ */
+export declare function runWithExecutionContext<T>(args: SetExecutionContextArgs, fn: () => T): T;
+export declare function getCurrentExecutionId(): string | null;
+export declare function getCurrentWrapper(): unknown | null;
+export declare function getCurrentOeUrl(): string | null;
+/**
+ * Validated replica-specific OE owner callback URL for the current execution,
+ * or null when none was forwarded or a previous owner pre-attempt already
+ * failed (see {@link reportOeOwnerUrlFailure}). Owner-preferring transports
+ * send here first and fall back to {@link getCurrentOeUrl} on any owner
+ * failure.
+ */
+export declare function getCurrentOeOwnerUrl(): string | null;
+/**
+ * Mark the current execution's owner URL unusable. One-way: after this,
+ * {@link getCurrentOeOwnerUrl} returns null for the rest of the execution so
+ * repeated emits stop re-paying the pre-attempt timeout against a dead owner.
+ * Reads `storage.getStore()` directly (like {@link recordSuspendRequest}) so a
+ * call outside a run is a no-op instead of mutating the frozen fallback.
+ */
+export declare function reportOeOwnerUrlFailure(): void;
+export declare function getCurrentRequestId(): string | null;
+export declare function getCurrentTraceId(): string | null;
+export declare function getCurrentUserId(): string | null;
+export declare function getCurrentSessionId(): string | null;
+export declare function getCurrentWorkspaceId(): string | null;
+/** Delegated authorization for the current execution, if OE injected one. */
+export declare function getCurrentAuthorization(): ToolAuthorization | null;
+/**
+ * The opaque caller-provided invocation payload for the current execution
+ * (the request body beyond `message`), or null if none was forwarded.
+ */
+export declare function getCurrentPayload(): Record<string, unknown> | null;
+/**
+ * Caller-provided custom headers, with platform-internal `a2a-` entries
+ * stripped — agent code should never see A2A tokens or routing metadata.
+ * Internal platform code that needs the full set (e.g. the A2A client) should
+ * call {@link getAllCustomHeaders} instead.
+ */
+export declare function getCurrentCustomHeaders(): Record<string, string>;
+/** All custom headers including platform-internal `a2a-` entries. */
+export declare function getAllCustomHeaders(): Record<string, string>;
+export declare function getCurrentExecutionMetadata(): Record<string, unknown>;
+/**
+ * Combine a per-call `AbortSignal` (e.g. a request/read timeout) with the
+ * current execution's abort signal, if one is set. The returned signal aborts
+ * when *either* fires, so an execution-wide timeout cancels the in-flight OE/LLM
+ * fetch instead of leaving it to run until its own deadline. Returns
+ * `callSignal` unchanged when there is no execution signal (e.g. a Tool Pod
+ * call outside an AER execution). Mirrors the effect of Python's
+ * `asyncio.wait_for` cancelling in-flight I/O on timeout.
+ */
+export declare function withExecutionSignal(callSignal: AbortSignal): AbortSignal;
+export interface RecordMemoryMetadataArgs {
+    action: string;
+    memoryType: string;
+    content?: string;
+    relevanceScore?: number;
+    query?: string;
+}
+/**
+ * Attach explicit memory metadata to the current execution step, if one exists.
+ * Mutates the metadata object in-place (matching the Python behaviour).
+ */
+export declare function recordCurrentMemoryMetadata(args: RecordMemoryMetadataArgs): void;
+/**
+ * Record that the agent considers this session finished. Reads directly off
+ * `storage.getStore()` (not `current()`) so a call outside a run reports
+ * "unavailable" without ever touching the frozen `EMPTY_STORE` fallback.
+ * `wrapper` is null for Tool Pod / Function contexts (see server/tool.ts,
+ * server/function.ts) — only the AER holds the finish latch, so those
+ * contexts must also report "unavailable" rather than a misleading success.
+ */
+export declare function requestSessionFinish(): SessionFinishStatus;
+/**
+ * Close the current execution's session-finish latch.
+ *
+ * Called from the AER's `finally` once the execute frame ends (covers
+ * success, error, policy-denied, and suspend paths alike). After this,
+ * requestSessionFinish() reports "unavailable" instead of promising a
+ * release nothing will act on — e.g. a setTimeout or floating promise
+ * scheduled during the turn but resolving after it.
+ */
+export declare function closeSessionFinish(): void;
+export declare function isSessionFinishRequested(): boolean;
+/**
+ * Record an author-intended HITL suspend for the current tool call. Called
+ * only by `suspendPayloadToJson`, so the signal's provenance is the tool
+ * author's code, not tool-result data. Reads `storage.getStore()` directly so
+ * a call outside a run is a no-op instead of mutating the frozen fallback.
+ */
+export declare function recordSuspendRequest(payload: Record<string, unknown>): void;
+/**
+ * The suspend payload the current tool call requested via
+ * `suspendPayloadToJson`, or null if it did not. The Tool Pod reads this after
+ * the tool returns to decide whether to report `status: "suspend"`.
+ */
+export declare function getRequestedSuspend(): Record<string, unknown> | null;
+/** Run one in-process tool call with an isolated suspend marker. */
+export declare function runWithSuspendRequestContext<T>(fn: () => T): T;
+/** `"customer"` inside a customer-code boundary, else null. */
+export declare function getCurrentLogOrigin(): string | null;
+/**
+ * Mark the dynamic extent of customer agent/tool code for log attribution.
+ * Nested scopes are a no-op. Missing origin is unclassified, not proven
+ * platform-authored.
+ */
+export declare function runWithCustomerOrigin<T>(fn: () => T): T;
+/**
+ * The per-call stop signal for the in-flight callback-routed tool call.
+ * Defined only inside a tool body that declared call-interrupt support; a
+ * cooperative body checks it (or forwards it to `fetch` etc.) to stop at its
+ * next checkpoint. Undefined everywhere else.
+ */
+export declare function getCallAbortSignal(): AbortSignal | undefined;
+/** Run one callback-routed tool body with its per-call abort signal attached. */
+export declare function runWithCallAbortSignal<T>(signal: AbortSignal, fn: () => T): T;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

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

package/dist/context.js

@@ -0,0 +1,322 @@
+/**
+ * Per-execution context management using AsyncLocalStorage.
+ *
+ * Mirrors Python `agent_engine_runner_shared/context.py` which uses `contextvars.ContextVar`.
+ * Each concurrent execution gets its own isolated context frame, preventing
+ * cross-execution contamination of execution_id, wrapper, and OE URL.
+ *
+ * The single entry point is `runWithExecutionContext(store, fn)`, which runs
+ * `fn` inside an isolated frame via `AsyncLocalStorage#run`. The frame is a
+ * child that never mutates the parent and is torn down automatically when `fn`
+ * settles — even if `fn` throws or spawns async work via setTimeout/Promise.
+ *
+ * Node's `AsyncLocalStorage#enterWith` (a set/clear-token style) is deliberately
+ * avoided: it rebinds the current async frame in place, so the store leaks into
+ * the surrounding context and cannot be reliably restored. The Python
+ * `set_execution_context` / `clear_execution_context` token pair is collapsed
+ * into this callback form, which is the equivalent of Python's
+ * `set_execution_context(...)` + `try/finally clear_execution_context(...)`.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
+import { redactText } from "./error_reporting.js";
+// Frozen so accidental mutations to the fallback don't bleed into real stores.
+const EMPTY_STORE = Object.freeze({
+    executionId: null,
+    wrapper: null,
+    oeUrl: null,
+    oeOwnerUrl: null,
+    ownerUrlFailure: Object.freeze({ failed: false }),
+    requestId: null,
+    traceId: null,
+    userId: null,
+    sessionId: null,
+    workspaceId: null,
+    customHeaders: null,
+    executionMetadata: null,
+    authorization: null,
+    payload: null,
+    signal: null,
+    // closed: true — nothing outside a run can finish.
+    sessionFinish: Object.freeze({ requested: false, closed: true }),
+    suspendRequest: Object.freeze({ payload: null }),
+});
+const storage = new AsyncLocalStorage();
+function current() {
+    return storage.getStore() ?? EMPTY_STORE;
+}
+function buildStore(args) {
+    const parent = storage.getStore();
+    return {
+        executionId: args.executionId,
+        wrapper: args.wrapper,
+        oeUrl: args.oeUrl,
+        oeOwnerUrl: args.oeOwnerUrl ?? null,
+        ownerUrlFailure: args.ownerUrlFailure ??
+            (parent?.executionId === args.executionId
+                ? parent.ownerUrlFailure
+                : { failed: false }),
+        traceId: args.traceId ?? null,
+        requestId: args.requestId || `req-${randomUUID().replace(/-/g, "").slice(0, 12)}`,
+        userId: args.userId ?? null,
+        sessionId: args.sessionId ?? null,
+        workspaceId: args.workspaceId ?? null,
+        customHeaders: args.customHeaders ?? null,
+        executionMetadata: {},
+        authorization: args.authorization ?? null,
+        payload: args.payload ?? null,
+        signal: args.signal ?? null,
+        sessionFinish: { requested: false, closed: false },
+        suspendRequest: { payload: null },
+    };
+}
+/**
+ * Run `fn` with an isolated execution context frame.
+ *
+ * `storage.run` creates a child frame that never mutates the parent, so cleanup
+ * is automatic even if `fn` throws or spawns work via setTimeout/Promise. This
+ * is the equivalent of Python's `set_execution_context(...)` followed by a
+ * try/finally `clear_execution_context(...)`.
+ *
+ * @example
+ *   await runWithExecutionContext({ executionId, wrapper, oeUrl, userId }, async () => {
+ *     await runAgentLogic()  // getCurrentUserId() works anywhere in this call chain
+ *   })
+ */
+export function runWithExecutionContext(args, fn) {
+    return storage.run(buildStore(args), fn);
+}
+// =========================================================================
+// Accessors — read-only views of the current store
+// =========================================================================
+export function getCurrentExecutionId() {
+    return current().executionId;
+}
+export function getCurrentWrapper() {
+    return current().wrapper;
+}
+export function getCurrentOeUrl() {
+    return current().oeUrl;
+}
+/**
+ * Validated replica-specific OE owner callback URL for the current execution,
+ * or null when none was forwarded or a previous owner pre-attempt already
+ * failed (see {@link reportOeOwnerUrlFailure}). Owner-preferring transports
+ * send here first and fall back to {@link getCurrentOeUrl} on any owner
+ * failure.
+ */
+export function getCurrentOeOwnerUrl() {
+    const store = current();
+    return store.ownerUrlFailure.failed ? null : store.oeOwnerUrl;
+}
+/**
+ * Mark the current execution's owner URL unusable. One-way: after this,
+ * {@link getCurrentOeOwnerUrl} returns null for the rest of the execution so
+ * repeated emits stop re-paying the pre-attempt timeout against a dead owner.
+ * Reads `storage.getStore()` directly (like {@link recordSuspendRequest}) so a
+ * call outside a run is a no-op instead of mutating the frozen fallback.
+ */
+export function reportOeOwnerUrlFailure() {
+    const store = storage.getStore();
+    if (store !== undefined) {
+        store.ownerUrlFailure.failed = true;
+    }
+}
+export function getCurrentRequestId() {
+    return current().requestId;
+}
+export function getCurrentTraceId() {
+    return current().traceId;
+}
+export function getCurrentUserId() {
+    return current().userId;
+}
+export function getCurrentSessionId() {
+    return current().sessionId;
+}
+export function getCurrentWorkspaceId() {
+    return current().workspaceId;
+}
+/** Delegated authorization for the current execution, if OE injected one. */
+export function getCurrentAuthorization() {
+    return current().authorization;
+}
+/**
+ * The opaque caller-provided invocation payload for the current execution
+ * (the request body beyond `message`), or null if none was forwarded.
+ */
+export function getCurrentPayload() {
+    return current().payload;
+}
+/**
+ * Caller-provided custom headers, with platform-internal `a2a-` entries
+ * stripped — agent code should never see A2A tokens or routing metadata.
+ * Internal platform code that needs the full set (e.g. the A2A client) should
+ * call {@link getAllCustomHeaders} instead.
+ */
+export function getCurrentCustomHeaders() {
+    const headers = current().customHeaders ?? {};
+    return Object.fromEntries(Object.entries(headers).filter(([key]) => !key.startsWith("a2a-")));
+}
+/** All custom headers including platform-internal `a2a-` entries. */
+export function getAllCustomHeaders() {
+    return current().customHeaders ?? {};
+}
+export function getCurrentExecutionMetadata() {
+    return current().executionMetadata ?? {};
+}
+/**
+ * Combine a per-call `AbortSignal` (e.g. a request/read timeout) with the
+ * current execution's abort signal, if one is set. The returned signal aborts
+ * when *either* fires, so an execution-wide timeout cancels the in-flight OE/LLM
+ * fetch instead of leaving it to run until its own deadline. Returns
+ * `callSignal` unchanged when there is no execution signal (e.g. a Tool Pod
+ * call outside an AER execution). Mirrors the effect of Python's
+ * `asyncio.wait_for` cancelling in-flight I/O on timeout.
+ */
+export function withExecutionSignal(callSignal) {
+    const execSignal = current().signal;
+    return execSignal ? AbortSignal.any([callSignal, execSignal]) : callSignal;
+}
+/**
+ * Attach explicit memory metadata to the current execution step, if one exists.
+ * Mutates the metadata object in-place (matching the Python behaviour).
+ */
+export function recordCurrentMemoryMetadata(args) {
+    const metadata = storage.getStore()?.executionMetadata;
+    if (metadata === null || metadata === undefined) {
+        return;
+    }
+    const memory = {
+        action: args.action,
+        type: args.memoryType,
+    };
+    if (args.content) {
+        // Content and query are user/LLM-derived and this metadata is returned
+        // to the UI — scrub credential-shaped fragments before persisting.
+        memory["content"] = redactText(args.content);
+    }
+    if (args.relevanceScore !== undefined) {
+        memory["relevance_score"] = args.relevanceScore;
+    }
+    if (args.query) {
+        memory["query"] = redactText(args.query);
+    }
+    let memoryEvents = metadata["memory_events"];
+    if (!Array.isArray(memoryEvents)) {
+        memoryEvents = [];
+        metadata["memory_events"] = memoryEvents;
+    }
+    memoryEvents.push(memory);
+    metadata["memory"] = memory;
+}
+// =========================================================================
+// Session finish request
+// =========================================================================
+/**
+ * Record that the agent considers this session finished. Reads directly off
+ * `storage.getStore()` (not `current()`) so a call outside a run reports
+ * "unavailable" without ever touching the frozen `EMPTY_STORE` fallback.
+ * `wrapper` is null for Tool Pod / Function contexts (see server/tool.ts,
+ * server/function.ts) — only the AER holds the finish latch, so those
+ * contexts must also report "unavailable" rather than a misleading success.
+ */
+export function requestSessionFinish() {
+    const store = storage.getStore();
+    if (store === undefined || store.wrapper === null) {
+        return "unavailable";
+    }
+    // No lock: this function is synchronous and non-async, so it cannot be
+    // preempted mid-call by another callback on the same event loop turn.
+    // Only cross-turn ordering (this call vs. closeSessionFinish() from a
+    // *different* turn) matters, and that's a plain sequential read/write on
+    // this store's own object — never shared with another turn's store.
+    if (store.sessionFinish.closed) {
+        return "unavailable";
+    }
+    if (store.sessionFinish.requested) {
+        return "already_requested";
+    }
+    store.sessionFinish.requested = true;
+    return "requested";
+}
+/**
+ * Close the current execution's session-finish latch.
+ *
+ * Called from the AER's `finally` once the execute frame ends (covers
+ * success, error, policy-denied, and suspend paths alike). After this,
+ * requestSessionFinish() reports "unavailable" instead of promising a
+ * release nothing will act on — e.g. a setTimeout or floating promise
+ * scheduled during the turn but resolving after it.
+ */
+export function closeSessionFinish() {
+    const store = storage.getStore();
+    if (store !== undefined) {
+        store.sessionFinish.closed = true;
+    }
+}
+export function isSessionFinishRequested() {
+    return current().sessionFinish.requested;
+}
+// =========================================================================
+// Suspend request signal
+// =========================================================================
+/**
+ * Record an author-intended HITL suspend for the current tool call. Called
+ * only by `suspendPayloadToJson`, so the signal's provenance is the tool
+ * author's code, not tool-result data. Reads `storage.getStore()` directly so
+ * a call outside a run is a no-op instead of mutating the frozen fallback.
+ */
+export function recordSuspendRequest(payload) {
+    const store = storage.getStore();
+    if (store !== undefined) {
+        store.suspendRequest.payload = payload;
+    }
+}
+/**
+ * The suspend payload the current tool call requested via
+ * `suspendPayloadToJson`, or null if it did not. The Tool Pod reads this after
+ * the tool returns to decide whether to report `status: "suspend"`.
+ */
+export function getRequestedSuspend() {
+    return current().suspendRequest.payload;
+}
+/** Run one in-process tool call with an isolated suspend marker. */
+export function runWithSuspendRequestContext(fn) {
+    const store = storage.getStore();
+    if (store === undefined) {
+        return fn();
+    }
+    return storage.run({ ...store, suspendRequest: { payload: null } }, fn);
+}
+const CUSTOMER_ORIGIN = "customer";
+const customerOriginStorage = new AsyncLocalStorage();
+/** `"customer"` inside a customer-code boundary, else null. */
+export function getCurrentLogOrigin() {
+    return customerOriginStorage.getStore() === true ? CUSTOMER_ORIGIN : null;
+}
+/**
+ * Mark the dynamic extent of customer agent/tool code for log attribution.
+ * Nested scopes are a no-op. Missing origin is unclassified, not proven
+ * platform-authored.
+ */
+export function runWithCustomerOrigin(fn) {
+    if (customerOriginStorage.getStore() === true) {
+        return fn();
+    }
+    return customerOriginStorage.run(true, fn);
+}
+const callAbortStorage = new AsyncLocalStorage();
+/**
+ * The per-call stop signal for the in-flight callback-routed tool call.
+ * Defined only inside a tool body that declared call-interrupt support; a
+ * cooperative body checks it (or forwards it to `fetch` etc.) to stop at its
+ * next checkpoint. Undefined everywhere else.
+ */
+export function getCallAbortSignal() {
+    return callAbortStorage.getStore();
+}
+/** Run one callback-routed tool body with its per-call abort signal attached. */
+export function runWithCallAbortSignal(signal, fn) {
+    return callAbortStorage.run(signal, fn);
+}

package/dist/db_config.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Single source of truth for the consolidated data-plane database name.
+ *
+ * All platform-owned stores (execution logs, checkpoints, memory, traces)
+ * live in one database.  Override via the `MDB_AGENTIC_STORE_DB` environment
+ * variable; the default is `mdb_store`.
+ */
+import type { MongoClient } from "mongodb";
+/**
+ * Return the base (unscoped) consolidated data-plane database name.
+ *
+ * Reads `MDB_AGENTIC_STORE_DB` from the environment on every call so that
+ * late configuration (e.g. loading a .env file after import) is respected. For
+ * the per-project-scoped name use {@link resolveStoreDbName}.
+ */
+export declare function getStoreDbName(): string;
+/**
+ * Return the per-project-scoped store DB name, resolved once and cached.
+ *
+ * Applies the same resolution the OE uses ({@link resolveEffectiveDb}) against
+ * the live cluster, so the AER/SDK writers converge on the same database the OE
+ * reads. `base` defaults to {@link getStoreDbName}. Explicit values are
+ * returned exactly and skip discovery.
+ */
+export declare function resolveStoreDbName(client: MongoClient, base?: string): Promise<string>;
+/** Clear the memoized resolved store DB names (test seam). */
+export declare function resetStoreDbCache(): void;
+//# sourceMappingURL=db_config.d.ts.map

package/dist/db_config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db_config.d.ts","sourceRoot":"","sources":["../src/db_config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAM3C;;;;;;GAMG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAGvC;AASD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,WAAW,EACnB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CA2BjB;AAED,8DAA8D;AAC9D,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}

package/dist/db_config.js

@@ -0,0 +1,66 @@
+/**
+ * Single source of truth for the consolidated data-plane database name.
+ *
+ * All platform-owned stores (execution logs, checkpoints, memory, traces)
+ * live in one database.  Override via the `MDB_AGENTIC_STORE_DB` environment
+ * variable; the default is `mdb_store`.
+ */
+import { resolveEffectiveDb } from "./db_naming.js";
+const DEFAULT_DB_NAME = "mdb_store";
+const LEGACY_DEFAULT_DB_NAMES = ["mdb_agentic_store"];
+const ENV_VAR = "MDB_AGENTIC_STORE_DB";
+/**
+ * Return the base (unscoped) consolidated data-plane database name.
+ *
+ * Reads `MDB_AGENTIC_STORE_DB` from the environment on every call so that
+ * late configuration (e.g. loading a .env file after import) is respected. For
+ * the per-project-scoped name use {@link resolveStoreDbName}.
+ */
+export function getStoreDbName() {
+    const value = process.env[ENV_VAR]?.trim();
+    return value || DEFAULT_DB_NAME;
+}
+// Memoized per-project-resolved store DB names, keyed by base. Resolution needs
+// a connected MongoClient (to list databases), which is not available when
+// getStoreDbName runs during construction, so it is deferred to the first
+// consumer that has a client and cached process-wide. The cached value is a
+// Promise so concurrent callers share one listDatabases round trip per base.
+const resolvedStoreDb = {};
+/**
+ * Return the per-project-scoped store DB name, resolved once and cached.
+ *
+ * Applies the same resolution the OE uses ({@link resolveEffectiveDb}) against
+ * the live cluster, so the AER/SDK writers converge on the same database the OE
+ * reads. `base` defaults to {@link getStoreDbName}. Explicit values are
+ * returned exactly and skip discovery.
+ */
+export function resolveStoreDbName(client, base) {
+    if (base !== undefined && base !== "")
+        return Promise.resolve(base);
+    const configured = (process.env[ENV_VAR] ?? "").trim();
+    if (configured)
+        return Promise.resolve(configured);
+    const b = DEFAULT_DB_NAME;
+    if (!(b in resolvedStoreDb)) {
+        const lister = {
+            listDatabaseNames: async () => {
+                const res = await client.db().admin().listDatabases({ nameOnly: true });
+                return res.databases.map((d) => d.name);
+            },
+        };
+        resolvedStoreDb[b] = resolveEffectiveDb(lister, b, (process.env["PROJECT_ID"] ?? "").trim(), {
+            label: "agent store database",
+            legacyBases: LEGACY_DEFAULT_DB_NAMES,
+        }).catch((err) => {
+            // Don't cache a rejection — allow a later retry.
+            delete resolvedStoreDb[b];
+            throw err;
+        });
+    }
+    return resolvedStoreDb[b];
+}
+/** Clear the memoized resolved store DB names (test seam). */
+export function resetStoreDbCache() {
+    for (const key of Object.keys(resolvedStoreDb))
+        delete resolvedStoreDb[key];
+}