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

package/dist/node_logger.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Node execution logger — framework-neutral.
+ *
+ * Logs graph node traversals to the OE for observability. The OE writes them
+ * to MongoDB so persistence stays centralized.
+ *
+ * Mirrors Python `agent_engine_runner_shared/node_logger.py`. Extends `NullExecutionCallback`
+ * (from agent-engine-sdk) so future protocol additions don't break implementations
+ * that didn't override the new method.
+ */
+import { NullExecutionCallback } from "@mongodb-js/agent-engine-sdk";
+interface NodeCallbackOpts {
+    runId: string;
+    parentRunId?: string;
+    metadata?: Record<string, unknown>;
+    durationMs?: number;
+}
+export interface NodeExecutionLoggerOpts {
+    oeUrl: string;
+    executionId: string;
+    sessionId?: string | null;
+    userId?: string | null;
+    orgId?: string | null;
+    projectId?: string | null;
+}
+export declare class NodeExecutionLogger extends NullExecutionCallback {
+    private readonly oeUrl;
+    private readonly executionId;
+    private readonly sessionId;
+    private readonly userId;
+    private readonly orgId;
+    private readonly projectId;
+    private readonly nodeStartTimes;
+    constructor(opts: NodeExecutionLoggerOpts);
+    onNodeStart(nodeName: string, inputs: Record<string, unknown>, opts: NodeCallbackOpts): void;
+    onNodeEnd(nodeName: string, outputs: Record<string, unknown>, opts: NodeCallbackOpts): void;
+    onNodeError(nodeName: string, error: string, opts: NodeCallbackOpts): void;
+    onNodeSuspend(nodeName: string, opts: NodeCallbackOpts): void;
+    private serializeForJson;
+    private sendNodeEvent;
+}
+export {};
+//# sourceMappingURL=node_logger.d.ts.map

package/dist/node_logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node_logger.d.ts","sourceRoot":"","sources":["../src/node_logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAOrE,UAAU,gBAAgB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,qBAAa,mBAAoB,SAAQ,qBAAqB;IAC5D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAgC;gBAEnD,IAAI,EAAE,uBAAuB;IAUhC,WAAW,CAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,gBAAgB,GACrB,IAAI;IAaE,SAAS,CAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,IAAI,EAAE,gBAAgB,GACrB,IAAI;IAkBE,WAAW,CAClB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,gBAAgB,GACrB,IAAI;IAYE,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,IAAI;IAgBtE,OAAO,CAAC,gBAAgB;YAwBV,aAAa;CA4D5B"}

package/dist/node_logger.js

@@ -0,0 +1,158 @@
+/**
+ * Node execution logger — framework-neutral.
+ *
+ * Logs graph node traversals to the OE for observability. The OE writes them
+ * to MongoDB so persistence stays centralized.
+ *
+ * Mirrors Python `agent_engine_runner_shared/node_logger.py`. Extends `NullExecutionCallback`
+ * (from agent-engine-sdk) so future protocol additions don't break implementations
+ * that didn't override the new method.
+ */
+import { NullExecutionCallback } from "@mongodb-js/agent-engine-sdk";
+import { getLogger } from "./logger.js";
+import { fetchPlatform, getFetchOptionsWithTLS } from "./tls_client.js";
+const logger = getLogger("agent_engine_runner_shared.node_logger");
+export class NodeExecutionLogger extends NullExecutionCallback {
+    oeUrl;
+    executionId;
+    sessionId;
+    userId;
+    orgId;
+    projectId;
+    nodeStartTimes = new Map();
+    constructor(opts) {
+        super();
+        this.oeUrl = opts.oeUrl;
+        this.executionId = opts.executionId;
+        this.sessionId = opts.sessionId ?? null;
+        this.userId = opts.userId ?? null;
+        this.orgId = opts.orgId ?? null;
+        this.projectId = opts.projectId ?? null;
+    }
+    onNodeStart(nodeName, inputs, opts) {
+        const start = new Date();
+        this.nodeStartTimes.set(opts.runId, start);
+        void this.sendNodeEvent({
+            nodeName,
+            status: "started",
+            timestamp: start,
+            runId: opts.runId,
+            parentRunId: opts.parentRunId,
+            inputs,
+        });
+    }
+    onNodeEnd(nodeName, outputs, opts) {
+        const start = this.nodeStartTimes.get(opts.runId);
+        this.nodeStartTimes.delete(opts.runId);
+        const end = new Date();
+        const durationMs = opts.durationMs ??
+            (start !== undefined ? end.getTime() - start.getTime() : undefined);
+        void this.sendNodeEvent({
+            nodeName,
+            status: "success",
+            timestamp: end,
+            runId: opts.runId,
+            parentRunId: opts.parentRunId,
+            outputs,
+            durationMs,
+        });
+    }
+    onNodeError(nodeName, error, opts) {
+        this.nodeStartTimes.delete(opts.runId);
+        void this.sendNodeEvent({
+            nodeName,
+            status: "error",
+            timestamp: new Date(),
+            runId: opts.runId,
+            parentRunId: opts.parentRunId,
+            error,
+        });
+    }
+    onNodeSuspend(nodeName, opts) {
+        const start = this.nodeStartTimes.get(opts.runId);
+        this.nodeStartTimes.delete(opts.runId);
+        const end = new Date();
+        const durationMs = start !== undefined ? end.getTime() - start.getTime() : undefined;
+        void this.sendNodeEvent({
+            nodeName,
+            status: "suspend",
+            timestamp: end,
+            runId: opts.runId,
+            parentRunId: opts.parentRunId,
+            durationMs,
+        });
+    }
+    serializeForJson(obj) {
+        if (obj === null || obj === undefined)
+            return obj;
+        const t = typeof obj;
+        if (t === "string" || t === "number" || t === "boolean")
+            return obj;
+        if (Array.isArray(obj))
+            return obj.map((v) => this.serializeForJson(v));
+        if (t === "object") {
+            // Pydantic .dict() equivalent: if a custom toJSON exists, use it.
+            const maybeToJson = obj.toJSON;
+            if (typeof maybeToJson === "function") {
+                try {
+                    return maybeToJson.call(obj);
+                }
+                catch {
+                    /* fall through */
+                }
+            }
+            const out = {};
+            for (const [k, v] of Object.entries(obj)) {
+                out[k] = this.serializeForJson(v);
+            }
+            return out;
+        }
+        return String(obj);
+    }
+    async sendNodeEvent(event) {
+        const payload = {
+            execution_id: this.executionId,
+            node_name: event.nodeName,
+            status: event.status,
+            timestamp: event.timestamp.toISOString(),
+            run_id: event.runId,
+            parent_run_id: event.parentRunId ?? null,
+            session_id: this.sessionId,
+            user_id: this.userId,
+            org_id: this.orgId,
+            project_id: this.projectId,
+        };
+        if (event.inputs !== undefined)
+            payload["inputs"] = this.serializeForJson(event.inputs);
+        if (event.outputs !== undefined)
+            payload["outputs"] = this.serializeForJson(event.outputs);
+        if (event.error !== undefined)
+            payload["error"] = event.error;
+        if (event.durationMs !== undefined)
+            payload["duration_ms"] = event.durationMs;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 2000);
+        try {
+            const tlsOptions = getFetchOptionsWithTLS(this.oeUrl);
+            const response = await fetchPlatform(`${this.oeUrl}/node/execution`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify(payload),
+                signal: controller.signal,
+                ...tlsOptions,
+            });
+            // `fetch` only rejects on network/abort errors, not on HTTP error
+            // statuses — surface a non-2xx so an OE-side failure isn't silently
+            // swallowed. Stays non-fatal: node events are best-effort observability.
+            if (!response.ok) {
+                logger.debug({ status: response.status, node: event.nodeName }, "OE rejected node event");
+            }
+        }
+        catch (err) {
+            logger.debug({ err: err.message }, "Failed to send node event to OE");
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/owner_callback.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Owner-callback pre-attempt shared by every owner-preferred OE POST.
+ *
+ * Policy (mirrored by `agent_engine_runner_shared/owner_callback.py` and the async
+ * `_owner_delivered` in `agent_engine_runner_shared/server/http_retry.py` — keep in sync):
+ * the replica-specific owner URL gets exactly one best-effort POST before the
+ * trusted service URL. Any owner failure — a transport error, a redirect
+ * (never followed: the owner URL is only validated as a headless replica of
+ * the service origin, so a 3xx could forward the body elsewhere), or any
+ * other non-2xx — falls back to the service path. The owner is never retried
+ * and this helper never throws. Response bodies are never read or logged
+ * (externally influenced) and are cancelled so undici can reuse the
+ * connection.
+ */
+export declare function ownerDelivered(ownerUrl: string, init: RequestInit | (() => RequestInit), log: (message: string) => void): Promise<boolean>;
+//# sourceMappingURL=owner_callback.d.ts.map

package/dist/owner_callback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner_callback.d.ts","sourceRoot":"","sources":["../src/owner_callback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,WAAW,GAAG,CAAC,MAAM,WAAW,CAAC,EACvC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC7B,OAAO,CAAC,OAAO,CAAC,CAqBlB"}

package/dist/owner_callback.js

@@ -0,0 +1,40 @@
+/**
+ * Owner-callback pre-attempt shared by every owner-preferred OE POST.
+ *
+ * Policy (mirrored by `agent_engine_runner_shared/owner_callback.py` and the async
+ * `_owner_delivered` in `agent_engine_runner_shared/server/http_retry.py` — keep in sync):
+ * the replica-specific owner URL gets exactly one best-effort POST before the
+ * trusted service URL. Any owner failure — a transport error, a redirect
+ * (never followed: the owner URL is only validated as a headless replica of
+ * the service origin, so a 3xx could forward the body elsewhere), or any
+ * other non-2xx — falls back to the service path. The owner is never retried
+ * and this helper never throws. Response bodies are never read or logged
+ * (externally influenced) and are cancelled so undici can reuse the
+ * connection.
+ */
+import { fetchPlatform } from "./tls_client.js";
+import { discardResponseBody } from "./server/http_retry.js";
+export async function ownerDelivered(ownerUrl, init, log) {
+    let failure;
+    try {
+        // Build URL-specific TLS options inside the best-effort boundary. Reading
+        // rotated certificate files can fail before fetch starts and must still
+        // degrade to the trusted service path.
+        const requestInit = typeof init === "function" ? init() : init;
+        // fetchPlatform, not bare fetch: the owner attempt must carry the same
+        // W3C trace-context headers and tracing suppression as the service path.
+        const response = await fetchPlatform(ownerUrl, {
+            ...requestInit,
+            redirect: "manual",
+        });
+        await discardResponseBody(response);
+        if (response.ok)
+            return true;
+        failure = `HTTP ${response.status}`;
+    }
+    catch (e) {
+        failure = e instanceof Error ? e.message : String(e);
+    }
+    log(`owner URL ${ownerUrl} unusable (${failure}); falling back to service`);
+    return false;
+}

package/dist/progress.d.ts

@@ -0,0 +1,57 @@
+/**
+ * emit / emitStep — send a mid-execution chunk from within a tool function.
+ *
+ * Tool functions running inside a Tool Pod call these to stream events to the
+ * client while the tool is still executing. Both executionId and oeUrl are
+ * injected into the execution context by the Tool Pod server before the tool
+ * runs (see `server/tool.ts`).
+ *
+ * The call is best-effort: network errors are logged and swallowed so a failed
+ * chunk emit never aborts the tool. Mirrors `agent_engine_runner_shared/progress.py`.
+ *
+ * Unlike the Python port there is no module-level client to pool: TLS agent
+ * reuse and cert-rotation invalidation are already handled by
+ * `getFetchOptionsWithTLS` (tls_client.ts), which caches one keep-alive agent
+ * per origin — so a plain `fetch` here reuses the same pooled connection the
+ * Python `_get_client` machinery provides.
+ */
+/**
+ * Emit a chunk of the given event type to the client stream.
+ *
+ * General-purpose API. For the common textual-step case, prefer
+ * {@link emitStep}.
+ *
+ * @param event Chunk type identifier (e.g. `"step"`). Reserved infrastructure
+ *   event types (`done`, `error`, `text`, `subagent_start`, `subagent_end`)
+ *   reject with an `Error` to prevent tool code from prematurely closing or
+ *   spoofing the stream. The reserved-event check fires even outside an
+ *   execution context — a programmer error wins over the no-op.
+ *   `"custom_event"` is not Atlas Agent Engine custom events; those require
+ *   `emit_custom_event` and `features.use_custom_parser` in `agent.yaml`.
+ *   Gateway drops `chunk_type: "custom_event"` unless that feature is on.
+ * @param data Payload string for the event.
+ *
+ * Transport failures (including a non-2xx response) are logged at debug and
+ * swallowed — best-effort delivery must never abort the tool function. No-op
+ * outside an execution context.
+ */
+export declare function emit(event: string, data: string): Promise<void>;
+/**
+ * Emit a textual progress step from within a running tool function.
+ *
+ * Convenience wrapper around `emit("step", message)`.
+ *
+ * @example
+ * ```ts
+ * import { emitStep } from "@mongodb-js/agent-engine-runner-shared";
+ *
+ * app.tool({ isLocal: false })(async function crawlWebsite(url: string) {
+ *   await emitStep("Fetching page...");
+ *   const html = await fetch(url);
+ *   await emitStep(`Parsing links from ${url}...`);
+ *   return parse(html);
+ * });
+ * ```
+ */
+export declare function emitStep(message: string): Promise<void>;
+//# sourceMappingURL=progress.d.ts.map

package/dist/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA6EH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2CrE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7D"}

package/dist/progress.js

@@ -0,0 +1,140 @@
+/**
+ * emit / emitStep — send a mid-execution chunk from within a tool function.
+ *
+ * Tool functions running inside a Tool Pod call these to stream events to the
+ * client while the tool is still executing. Both executionId and oeUrl are
+ * injected into the execution context by the Tool Pod server before the tool
+ * runs (see `server/tool.ts`).
+ *
+ * The call is best-effort: network errors are logged and swallowed so a failed
+ * chunk emit never aborts the tool. Mirrors `agent_engine_runner_shared/progress.py`.
+ *
+ * Unlike the Python port there is no module-level client to pool: TLS agent
+ * reuse and cert-rotation invalidation are already handled by
+ * `getFetchOptionsWithTLS` (tls_client.ts), which caches one keep-alive agent
+ * per origin — so a plain `fetch` here reuses the same pooled connection the
+ * Python `_get_client` machinery provides.
+ */
+import { getCurrentExecutionId, getCurrentOeOwnerUrl, getCurrentOeUrl, reportOeOwnerUrlFailure, withExecutionSignal, } from "./context.js";
+import { getLogger } from "./logger.js";
+import { ownerDelivered } from "./owner_callback.js";
+import { DONE, ERROR, STEP, SUBAGENT_END, SUBAGENT_START, TEXT, } from "./server/chunk_types.js";
+import { fetchPlatform, getFetchOptionsWithTLS } from "./tls_client.js";
+const logger = getLogger("agent_engine_runner_shared.progress");
+// Short timeout: chunk emits are best-effort fire-and-forget. A slow or
+// unreachable OE must not delay the tool function itself.
+const PROGRESS_TIMEOUT_SECS = 5.0;
+// Chunk types reserved for infrastructure use. Tool code emitting these would
+// either close the SSE stream prematurely (DONE/ERROR are terminal) or spoof
+// infrastructure-only chunk types (TEXT/SUBAGENT_*).
+const RESERVED_EVENTS = new Set([
+    DONE,
+    ERROR,
+    TEXT,
+    SUBAGENT_START,
+    SUBAGENT_END,
+]);
+/**
+ * POST `body` to `ownerUrl` first, falling back to `serviceUrl`.
+ *
+ * Owner preference per {@link ownerDelivered}: one best-effort attempt against
+ * the replica-specific owner URL; any owner failure falls back to the trusted
+ * service URL and latches via {@link reportOeOwnerUrlFailure} so later emits
+ * in this execution skip the owner instead of re-paying its timeout. Returns
+ * `null` when the owner delivered (nothing left to inspect), else the service
+ * response. Best-effort: the caller inspects `resp.ok` and swallows failures.
+ */
+async function postChunkOwnerFirst(serviceUrl, ownerUrl, body) {
+    const init = (url) => ({
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body,
+        signal: withExecutionSignal(AbortSignal.timeout(PROGRESS_TIMEOUT_SECS * 1000)),
+        ...getFetchOptionsWithTLS(url),
+    });
+    if (ownerUrl !== null) {
+        if (await ownerDelivered(ownerUrl, () => init(ownerUrl), (msg) => logger.debug(`emit: ${msg}`))) {
+            return null;
+        }
+        reportOeOwnerUrlFailure();
+    }
+    return await fetchPlatform(serviceUrl, init(serviceUrl));
+}
+/**
+ * Emit a chunk of the given event type to the client stream.
+ *
+ * General-purpose API. For the common textual-step case, prefer
+ * {@link emitStep}.
+ *
+ * @param event Chunk type identifier (e.g. `"step"`). Reserved infrastructure
+ *   event types (`done`, `error`, `text`, `subagent_start`, `subagent_end`)
+ *   reject with an `Error` to prevent tool code from prematurely closing or
+ *   spoofing the stream. The reserved-event check fires even outside an
+ *   execution context — a programmer error wins over the no-op.
+ *   `"custom_event"` is not Atlas Agent Engine custom events; those require
+ *   `emit_custom_event` and `features.use_custom_parser` in `agent.yaml`.
+ *   Gateway drops `chunk_type: "custom_event"` unless that feature is on.
+ * @param data Payload string for the event.
+ *
+ * Transport failures (including a non-2xx response) are logged at debug and
+ * swallowed — best-effort delivery must never abort the tool function. No-op
+ * outside an execution context.
+ */
+export async function emit(event, data) {
+    if (RESERVED_EVENTS.has(event)) {
+        throw new Error(`emit: event '${event}' is reserved for infrastructure use; ` +
+            `choose a non-terminal event type such as 'step'`);
+    }
+    const executionId = getCurrentExecutionId();
+    const oeUrl = getCurrentOeUrl();
+    const ownerUrl = getCurrentOeOwnerUrl();
+    if (!executionId || !oeUrl)
+        return;
+    try {
+        const body = JSON.stringify({
+            execution_id: executionId,
+            chunk_type: event,
+            content: data,
+            metadata: {},
+        });
+        // Owner preference: the owner URL is already validated against oeUrl by the
+        // tool-pod server, so trust it as-is. Each request gets its own timeout
+        // signal combined with the execution-wide abort signal so an owner timeout
+        // cannot pre-abort the service fallback.
+        const resp = await postChunkOwnerFirst(`${oeUrl.replace(/\/$/, "")}/stream/chunk`, ownerUrl ? `${ownerUrl.replace(/\/$/, "")}/stream/chunk` : null, body);
+        if (resp !== null) {
+            // A non-2xx is surfaced at debug but not thrown — emit is fire-and-forget.
+            if (!resp.ok) {
+                logger.debug(`emit: OE returned HTTP ${resp.status} for chunk`);
+            }
+            // We never read the body; cancel it so undici can release/reuse the
+            // connection instead of leaking it under frequent emits.
+            await resp.body?.cancel();
+        }
+    }
+    catch (exc) {
+        // Best-effort: a failed chunk must never abort the tool function. Debug so
+        // operators can diagnose OE connectivity without noise.
+        logger.debug(`emit: failed to send chunk: ${String(exc)}`);
+    }
+}
+/**
+ * Emit a textual progress step from within a running tool function.
+ *
+ * Convenience wrapper around `emit("step", message)`.
+ *
+ * @example
+ * ```ts
+ * import { emitStep } from "@mongodb-js/agent-engine-runner-shared";
+ *
+ * app.tool({ isLocal: false })(async function crawlWebsite(url: string) {
+ *   await emitStep("Fetching page...");
+ *   const html = await fetch(url);
+ *   await emitStep(`Parsing links from ${url}...`);
+ *   return parse(html);
+ * });
+ * ```
+ */
+export async function emitStep(message) {
+    await emit(STEP, message);
+}

package/dist/runtime.d.ts

@@ -0,0 +1,131 @@
+/**
+ * TenantRuntime — framework-agnostic platform runtime for tenant agent
+ * applications.
+ *
+ * Port of `agent_engine_runner_shared/runtime.py`. Same Python class shape: the runtime
+ * discovers its role from `RUNNER_MODE`, wires logging / tracing / tools,
+ * and delegates to a framework SDK's `App` (the `GraphBuilderLike`) for
+ * graph construction.
+ *
+ * Scope deltas vs. Python (see `AGENTS.md` for rationale):
+ *   - No memory-server mode (`RuntimeMode` has `AER`, `TOOL`, and `TOOL_FUNCTION`).
+ *   - `setupTracing` owns the MongoClient build (async). Python builds it
+ *     inline in `_setup_tracing` (sync pymongo).
+ *   - `shutdown()` and SIGTERM/SIGINT wiring are TS additions — Python's
+ *     uvicorn handles signals itself; here we explicitly close the tracing
+ *     MongoClient before exit.
+ */
+import type { RuntimeAgentConfig } from "./agent_config.js";
+import { MemoryWriter } from "./memory_writer.js";
+import { type GraphBuilderLike, type ITenantRuntime, type ServerToolFn } from "./server/base.js";
+import { RuntimeMode } from "./utils.js";
+import type { BaseAgent, BaseExecutionCallback } from "@mongodb-js/agent-engine-sdk";
+/**
+ * Resolve the listen host from `APP_HOST`, defaulting to `"0.0.0.0"`.
+ *
+ * Matches Python's `_resolve_listen_host`: ECP stamps `APP_HOST` per
+ * executor type at deploy time (`"::"` for vm-mode, `"0.0.0.0"` for
+ * container-mode). Empty string normalises to the default — a shell that
+ * exports `APP_HOST=""` must not bind to `""`.
+ */
+export declare function resolveListenHost(): string;
+/** Resolve the server drain budget without changing the existing Tool policy. */
+export declare function shutdownGracePeriodMs(mode: RuntimeMode): number;
+export interface TenantRuntimeOptions {
+    /** Application name. Defaults to `"Agent"`. */
+    appName?: string;
+    /** Application version. Defaults to `"1.0.0"`. */
+    appVersion?: string;
+    /** MongoDB URI used for trace persistence. Falls back to `MONGODB_URI`. */
+    mongodbUri?: string | null;
+    /** Explicit database name for trace storage. Defaults to the platform store. */
+    databaseName?: string | null;
+    /** Collection name for trace storage. Defaults to `"traces"`. */
+    tracesCollectionName?: string;
+    /** @deprecated Ignored. The org is taken from the `ORG_ID` env var, which the platform injects. */
+    orgId?: string | null;
+    /** @deprecated Ignored. The project is taken from the `PROJECT_ID` env var, which the platform injects. */
+    projectId?: string | null;
+}
+/** Public options for `registerAndRun`. */
+export interface RegisterAndRunOptions {
+    /** Log level passed through to the underlying server. */
+    logLevel?: string;
+}
+/**
+ * Tenant Runtime SDK.
+ *
+ * Constructed once per process. `registerAndRun` wires the framework SDK's
+ * graph builder and starts the per-mode Fastify server.
+ */
+export declare class TenantRuntime implements ITenantRuntime {
+    readonly appName: string;
+    readonly appVersion: string;
+    readonly mode: RuntimeMode;
+    readonly orgId: string | null;
+    readonly projectId: string | null;
+    readonly memoryWriter: MemoryWriter | null;
+    graphBuilder: GraphBuilderLike | null;
+    tools: Record<string, ServerToolFn>;
+    toolDefinitions: Record<string, Record<string, unknown>>;
+    private readonly agentConfig;
+    private readonly mongodbUri;
+    private readonly databaseNameOverride;
+    private readonly tracesCollectionName;
+    private shutdownStarted;
+    private tracingReady;
+    constructor(opts?: TenantRuntimeOptions);
+    /** Parsed `agent.yaml` configuration. */
+    getAgentConfig(): RuntimeAgentConfig;
+    /** Resolved MongoDB URI: constructor option > `MONGODB_URI` env var > null. */
+    getMongodbUri(): string | null;
+    private initTracing;
+    getAgent(opts?: {
+        callbacks?: BaseExecutionCallback[];
+    }): BaseAgent;
+    warmUpAgent(): void;
+    /**
+     * Get the current user_id from execution context.
+     *
+     * @returns User ID from the current execution context, or null if not available
+     */
+    getCurrentUserId(): string | null;
+    getCurrentSessionId(): string | null;
+    /**
+     * Register a raw tool function and its metadata.
+     *
+     * This stores the function for Tool Pod execution and the metadata
+     * for routing decisions. It does NOT create any framework-specific
+     * tool objects — that is the responsibility of the framework SDK.
+     *
+     * @param name Tool name
+     * @param func Raw tool function
+     * @param metadata Tool metadata (is_local, network, timeout, etc.)
+     */
+    registerTool(name: string, func: ServerToolFn, metadata: Record<string, unknown>): void;
+    /**
+     * Get metadata for a registered tool.
+     *
+     * @param name Tool name
+     * @returns Tool metadata object (is_local, network, timeout, etc.)
+     *   or empty object if tool not found.
+     */
+    getToolMetadata(name: string): Record<string, unknown>;
+    /**
+     * Close the tracing MongoClient. Idempotent — safe to call from multiple
+     * signal handlers. TS-only addition: Python's uvicorn handles SIGTERM
+     * itself, so the Python `TenantRuntime` has no equivalent method.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Register the graph builder and start the mode-specific server.
+     *
+     * Resolves once Fastify is listening — the open socket keeps the Node
+     * event loop alive, matching the practical effect of Python's
+     * `asyncio.run(uvicorn.serve())` blocking until shutdown.
+     */
+    registerAndRun(graphBuilder?: GraphBuilderLike | null, options?: RegisterAndRunOptions): Promise<void>;
+    private normalizeRunKwargs;
+    private runAsync;
+}
+//# 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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"}