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

package/dist/hooks.js

@@ -0,0 +1,216 @@
+/**
+ * Framework hook registry for runner-shared.
+ *
+ * Most hooks are registered once at process startup by the framework SDK
+ * before the server starts. The workflow adapter is the exception: it is
+ * register-or-clear on every graph materialization so eligibility cannot
+ * leak from a durable graph into a later native one. Consumers in
+ * runner-shared call `get*()` instead of importing framework-specific
+ * modules directly.
+ *
+ * Type aliases use sdk-core interfaces where possible. The suspend handler
+ * remains loosely typed because its signature is framework-specific
+ * (e.g. langgraph's `interrupt` returns whatever the resume caller provides).
+ */
+import { resetCheckpointWorkspaceState } from "./checkpoint_workspace.js";
+let suspendHandler = null;
+let llmAdapterFactory = null;
+let instrumentor = null;
+let queryPlugin = null;
+let workflowAdapter = null;
+const llmRegistry = new Map();
+// Set while the framework SDK is executing the user's @app.entrypoint
+// builder function (see entrypointScope()). app.llm() must only be called
+// while this is true -- it must be reproducibly re-derivable by the Tool
+// Pod's startup registry construction (see docs/runner/README.md
+// "Execution lifecycle & secret availability"), so calls from module top
+// level, tool bodies, or any other function are rejected at the call site.
+let entrypointActive = false;
+/**
+ * Mark the dynamic extent of the user's @app.entrypoint call.
+ *
+ * **Framework-internal — user agent code must never call this.** Users only
+ * declare an entrypoint (`app.entrypoint(fn)`); the framework SDK wraps its
+ * own evaluation of that function (during AER graph construction and
+ * during Tool preparation, retried after failure) in this helper so
+ * that `registerLlm()` can reject `app.llm()` calls made outside the
+ * entrypoint. Tests that call `app.llm()`/`registerLlm()` directly (bypassing
+ * `app.entrypoint` + `getAgent()`) use it to simulate that framework
+ * evaluation.
+ */
+export function entrypointScope(fn) {
+    const previous = entrypointActive;
+    entrypointActive = true;
+    try {
+        return fn();
+    }
+    finally {
+        entrypointActive = previous;
+    }
+}
+export function registerSuspendHandler(handler) {
+    suspendHandler = handler;
+}
+export function getSuspendHandler() {
+    return suspendHandler;
+}
+export function registerLLMAdapterFactory(factory) {
+    llmAdapterFactory = factory;
+}
+export function getLLMAdapterFactory() {
+    if (llmAdapterFactory === null) {
+        throw new Error("No LLM adapter factory registered. Ensure the framework SDK calls registerLLMAdapterFactory() before run().");
+    }
+    return llmAdapterFactory;
+}
+export function registerInstrumentor(fn) {
+    instrumentor = fn;
+}
+export function getInstrumentor() {
+    return instrumentor;
+}
+/**
+ * Register the framework adapter's `AERQueryPlugin`.
+ *
+ * Mirrors Python's `TenantRuntime.register_query_plugin`. The AER's
+ * `/query/sessions` routes return 501 until a plugin is registered.
+ */
+export function registerQueryPlugin(plugin) {
+    queryPlugin = plugin;
+}
+/** Return the registered `AERQueryPlugin`, or `null` if none has been registered. */
+export function getQueryPlugin() {
+    return queryPlugin;
+}
+/**
+ * Declare that the materialized graph supports OE durable workflow routing.
+ *
+ * Call this or {@link clearWorkflowAdapter} on every `getAgent()` materialization
+ * so a later ineligible graph cannot reuse the previous request's identity.
+ */
+export function registerWorkflowAdapter(name, version) {
+    if (!name.trim() || !version.trim()) {
+        throw new Error("workflow adapter name and version must be non-empty");
+    }
+    workflowAdapter = { name, version };
+}
+/** Drop durable eligibility for the latest materialized graph. */
+export function clearWorkflowAdapter() {
+    workflowAdapter = null;
+}
+export function getWorkflowAdapter() {
+    return workflowAdapter;
+}
+/**
+ * Register an LLM by id. Throws on duplicate id.
+ *
+ * Framework SDKs call this from `app.llm()` for every LLM the agent uses.
+ * The unnamed-LLM convenience case is represented by registering 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.
+ */
+export function registerLlm(llmId, llm) {
+    if (!entrypointActive) {
+        throw new Error("app.llm(...) must be called inside the function decorated with " +
+            "@app.entrypoint. It was called outside the entrypoint's dynamic " +
+            "extent. Move this call inside your @app.entrypoint builder function.");
+    }
+    if (llmRegistry.has(llmId)) {
+        throw new Error(`llm_id ${JSON.stringify(llmId)} is already registered. ` +
+            "Each LLM must have a unique llm_id; pass app.llm(llm, llm_id='...') for each.");
+    }
+    llmRegistry.set(llmId, llm);
+}
+export function getNamedLlm(llmId) {
+    if (!llmRegistry.has(llmId)) {
+        throw new Error(`llm_id ${JSON.stringify(llmId)} not registered. ` +
+            "Call app.llm(llm, llm_id=...) for each LLM before run().");
+    }
+    return llmRegistry.get(llmId);
+}
+export function hasNamedLlms() {
+    return llmRegistry.size > 0;
+}
+export function resetLlmRegistry() {
+    llmRegistry.clear();
+}
+/** Return a shallow copy of the current registry. */
+export function snapshotLlmRegistry() {
+    return new Map(llmRegistry);
+}
+export function resetHooks() {
+    suspendHandler = null;
+    llmAdapterFactory = null;
+    instrumentor = null;
+    queryPlugin = null;
+    workflowAdapter = null;
+    llmRegistry.clear();
+    entrypointActive = false;
+    resetCheckpointWorkspaceState();
+}
+/**
+ * Run the user's agent entrypoint to populate the named-LLM registry.
+ *
+ * Resets the registry before invoking `graphBuilder.getAgent()` so
+ * import-time registrations don't collide if the entrypoint re-registers
+ * them. If the entrypoint registers nothing, restores the pre-reset snapshot
+ * so import-time-only agents still work.
+ *
+ * Returns false after failed construction, including when a snapshot is restored.
+ * Successful construction with no named LLMs is still complete.
+ *
+ * `onEntrypointError`, when supplied, receives the thrown value on that same
+ * path so the caller can attribute a later registry lookup miss to its real
+ * cause rather than to a missing `app.llm()` call.
+ *
+ * Shared by ToolServer.onStartup and ToolFunctionRunner._prepare — mirrors
+ * Python's ToolExecution.prepare() which both inherit.
+ *
+ * @internal — exported for server/ consumers; not part of the public API.
+ */
+export function populateLlmRegistryFromEntrypoint(graphBuilder, logger, warnings, onEntrypointError) {
+    if (graphBuilder === null || typeof graphBuilder.getAgent !== "function")
+        return true;
+    const preSnapshot = snapshotLlmRegistry();
+    resetLlmRegistry();
+    try {
+        // Call through the receiver -- graphBuilder.getAgent() (e.g. App.getAgent())
+        // reads its own instance state (e.g. `this.builderFn`), so storing the
+        // method in a local and invoking it unbound would drop `this` and throw.
+        entrypointScope(() => graphBuilder.getAgent?.());
+    }
+    catch (error) {
+        logger.warn(warnings.entrypointFailed);
+        // Discard partial registrations before restoring the last snapshot.
+        resetLlmRegistry();
+        if (preSnapshot.size > 0) {
+            // Runtime-owned restoration, not a user app.llm() call -- exempt from
+            // the entrypoint-scope requirement.
+            entrypointScope(() => {
+                for (const [llmId, llm] of preSnapshot)
+                    registerLlm(llmId, llm);
+            });
+            logger.info(`Entrypoint failed; restored ${preSnapshot.size} import-time registration(s)`);
+        }
+        // Let the caller remember the cause: a later lookup miss inside the LLM
+        // route is a symptom of this failure, and reporting it as a missing
+        // app.llm() call would misdirect the agent developer. Mirrors Python's
+        // _llm_registry_load_error.
+        onEntrypointError?.(error);
+        return false;
+    }
+    if (hasNamedLlms()) {
+        logger.info("Named LLM registry populated from user entrypoint");
+    }
+    else if (preSnapshot.size > 0) {
+        entrypointScope(() => {
+            for (const [llmId, llm] of preSnapshot)
+                registerLlm(llmId, llm);
+        });
+        logger.info(`Entrypoint registered no LLMs; restored ${preSnapshot.size} import-time registration(s)`);
+    }
+    else {
+        logger.warn(warnings.noLlmRegistered);
+    }
+    return true;
+}

package/dist/http_path.d.ts

@@ -0,0 +1,18 @@
+/**
+ * URL path helpers for outbound platform HTTP calls.
+ *
+ * Shared choke point for percent-encoding one path segment. Framework adapters
+ * must route every interpolated identifier through {@link quotePathSegment}
+ * instead of hand-rolling quoting: bare `encodeURIComponent` leaves
+ * `.`/`..` untouched and string-concatenated identifiers forge paths.
+ *
+ * Port of Python's `agent_engine_runner_shared/http_path.py`.
+ */
+/**
+ * Percent-encode one path segment; reject separators and `.` / `..`.
+ *
+ * Decode repeatedly before quoting so encoded, double-encoded, and mixed
+ * traversal forms cannot survive a later routing decode.
+ */
+export declare function quotePathSegment(value: string): string;
+//# sourceMappingURL=http_path.d.ts.map

package/dist/http_path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http_path.d.ts","sourceRoot":"","sources":["../src/http_path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAqBH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAmBtD"}

package/dist/http_path.js

@@ -0,0 +1,53 @@
+/**
+ * URL path helpers for outbound platform HTTP calls.
+ *
+ * Shared choke point for percent-encoding one path segment. Framework adapters
+ * must route every interpolated identifier through {@link quotePathSegment}
+ * instead of hand-rolling quoting: bare `encodeURIComponent` leaves
+ * `.`/`..` untouched and string-concatenated identifiers forge paths.
+ *
+ * Port of Python's `agent_engine_runner_shared/http_path.py`.
+ */
+const MAX_DECODE_ROUNDS = 8;
+function fullyDecode(value) {
+    let decoded = value;
+    for (let round = 0; round < MAX_DECODE_ROUNDS; round++) {
+        let next;
+        try {
+            next = decodeURIComponent(decoded);
+        }
+        catch {
+            // Malformed `%` sequences and invalid UTF-8 escapes are rejected the
+            // same as Python's `unquote(..., errors="strict")`.
+            throw new Error("URL path segment is invalid");
+        }
+        if (next === decoded)
+            return decoded;
+        decoded = next;
+    }
+    throw new Error("URL path segment is invalid");
+}
+/**
+ * Percent-encode one path segment; reject separators and `.` / `..`.
+ *
+ * Decode repeatedly before quoting so encoded, double-encoded, and mixed
+ * traversal forms cannot survive a later routing decode.
+ */
+export function quotePathSegment(value) {
+    const decoded = fullyDecode(value);
+    if (!decoded ||
+        decoded === "." ||
+        decoded === ".." ||
+        /[/\\?#]/.test(decoded)) {
+        throw new Error("URL path segment is invalid");
+    }
+    // `encodeURIComponent` keeps `! ' ( ) *` unescaped; Python's
+    // `quote(decoded, safe="")` does not. Match it so both runtimes produce
+    // byte-identical paths.
+    return encodeURIComponent(decoded)
+        .replaceAll("!", "%21")
+        .replaceAll("'", "%27")
+        .replaceAll("(", "%28")
+        .replaceAll(")", "%29")
+        .replaceAll("*", "%2A");
+}

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+export * from "./utils.js";
+export { getStoreDbName, resolveStoreDbName, resetStoreDbCache, } from "./db_config.js";
+export { resolveProjectScopedDb, resolveEffectiveDb, projectScopingRequired, } from "./db_naming.js";
+export { getLogger, setupLogging, type SetupLoggingArgs } from "./logger.js";
+export type { Logger } from "log4js";
+export { AERServer, ToolServer, LLMRegistryLoadError, ToolFunctionRunner, ToolFunctionRequestSchema, buildResultPayload, DEFAULT_PORTS, type ToolFunctionRequest, type ITenantRuntime, type GraphBuilderLike, type ServerToolFn, type AERQueryPlugin, } from "./server/index.js";
+export { chunkTypes } from "./server/index.js";
+export * from "./models.js";
+export * from "./guardrails_evaluator/index.js";
+export * from "./agent_config.js";
+export * from "./mcp_tools.js";
+export { DEFAULT_MCP_OAUTH_CLIENT_NAME, DEFAULT_MCP_OAUTH_REDIRECT_URI, mcpOauthCacheDir, mcpOauthCacheName, makeMcpOauthAuth, makeMcpClientCredentialsAuth, } from "./mcp_oauth.js";
+export { materializeMcpOauthSecretCache } from "./mcp_oauth_secret.js";
+export * from "./context.js";
+export { BUILTIN_TOOL_NAMES, registerBuiltinTools, WORKSPACE_DIR, filesystemLs, filesystemRead, filesystemWrite, filesystemEdit, filesystemGlob, filesystemGrep, filesystemDownload, shellExecute, } from "./toolpod_handlers.js";
+export * from "./hooks.js";
+export * from "./workflow/index.js";
+export { fetchPlatform, getFetchOptionsWithTLS } from "./tls_client.js";
+export { quotePathSegment } from "./http_path.js";
+export { resolveOeUrl } from "./server/oe_url.js";
+export { getCheckpointWorkspaceId, noteCheckpointWireWorkspaceId, resolveCheckpointWorkspaceId, resetCheckpointWorkspaceState, } from "./checkpoint_workspace.js";
+export { TenantRuntime, resolveListenHost, type TenantRuntimeOptions, type RegisterAndRunOptions, } from "./runtime.js";
+export { resolveEntrypoint, resolveImportTarget, runLauncher, boundText, writeTerminationMessage, setTerminationLogPathForTest, EXIT_IMPORT_ERROR, EXIT_NO_ENTRYPOINT, EXIT_STARTUP_CRASH, type ResolvedEntrypoint, } from "./launcher.js";
+export { PolicyDeniedException, TerminalExecutionError, ToolCallTimeoutError, ToolExecutionError, ExternalAPICallError, LLMInvocationError, OperationalStepAllocator, SecureToolWrapper, createSecureToolFunction, requestOeApproval, reportOeResult, extractUsage, extractPodUsage, type RequestOeApprovalArgs, type ReportOeResultArgs, type ExtractedUsage, type ToolResponseFormat, type OperationalStepSource, CALL_INTERRUPTED_ARTIFACT_KEY, } from "./secure_wrapper.js";
+export { SecureLLMProxy } from "./secure_llm_proxy.js";
+export { initErrorReporting, captureException, captureMessage, flush as flushErrorReporting, summarizeSubprocessFailure, subprocessOutputTail, type InitErrorReportingArgs, type CaptureExceptionArgs, type SubprocessFailure, } from "./error_reporting.js";
+export { emit, emitStep } from "./progress.js";
+export { Metrics, recordLatency, withMetrics, type LatencyStatsJson, } from "./metrics.js";
+export * from "./node_logger.js";
+export * from "./structured_logging.js";
+export * from "./tracing/index.js";
+export * from "./span_names.js";
+export { AppBoundRuntime, AppBoundCrudClient } from "./memory_appbound.js";
+export { ToolAPIErrorSchema, type ToolAPIError } from "./tool_api_error.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,41 @@
+// Copyright 2026 MongoDB, Inc.
+// SPDX-License-Identifier: Apache-2.0
+// agent-engine-runner-shared public API barrel
+export * from "./utils.js";
+export { getStoreDbName, resolveStoreDbName, resetStoreDbCache, } from "./db_config.js";
+export { resolveProjectScopedDb, resolveEffectiveDb, projectScopingRequired, } from "./db_naming.js";
+export { getLogger, setupLogging } from "./logger.js";
+export { AERServer, ToolServer, LLMRegistryLoadError, ToolFunctionRunner, ToolFunctionRequestSchema, buildResultPayload, DEFAULT_PORTS, } from "./server/index.js";
+export { chunkTypes } from "./server/index.js";
+export * from "./models.js";
+export * from "./guardrails_evaluator/index.js";
+export * from "./agent_config.js";
+export * from "./mcp_tools.js";
+export { DEFAULT_MCP_OAUTH_CLIENT_NAME, DEFAULT_MCP_OAUTH_REDIRECT_URI, mcpOauthCacheDir, mcpOauthCacheName, makeMcpOauthAuth, makeMcpClientCredentialsAuth, } from "./mcp_oauth.js";
+export { materializeMcpOauthSecretCache } from "./mcp_oauth_secret.js";
+export * from "./context.js";
+export { BUILTIN_TOOL_NAMES, registerBuiltinTools, WORKSPACE_DIR, filesystemLs, filesystemRead, filesystemWrite, filesystemEdit, filesystemGlob, filesystemGrep, filesystemDownload, shellExecute, } from "./toolpod_handlers.js";
+export * from "./hooks.js";
+export * from "./workflow/index.js";
+export { fetchPlatform, getFetchOptionsWithTLS } from "./tls_client.js";
+export { quotePathSegment } from "./http_path.js";
+export { resolveOeUrl } from "./server/oe_url.js";
+export { getCheckpointWorkspaceId, noteCheckpointWireWorkspaceId, resolveCheckpointWorkspaceId, resetCheckpointWorkspaceState, } from "./checkpoint_workspace.js";
+export { TenantRuntime, resolveListenHost, } from "./runtime.js";
+export { resolveEntrypoint, resolveImportTarget, runLauncher, boundText, writeTerminationMessage, setTerminationLogPathForTest, EXIT_IMPORT_ERROR, EXIT_NO_ENTRYPOINT, EXIT_STARTUP_CRASH, } from "./launcher.js";
+export { PolicyDeniedException, TerminalExecutionError, ToolCallTimeoutError, ToolExecutionError, ExternalAPICallError, LLMInvocationError, OperationalStepAllocator, SecureToolWrapper, createSecureToolFunction, requestOeApproval, reportOeResult, extractUsage, extractPodUsage, CALL_INTERRUPTED_ARTIFACT_KEY, } from "./secure_wrapper.js";
+export { SecureLLMProxy } from "./secure_llm_proxy.js";
+export { initErrorReporting, captureException, captureMessage, flush as flushErrorReporting, summarizeSubprocessFailure, subprocessOutputTail, } from "./error_reporting.js";
+export { emit, emitStep } from "./progress.js";
+// `metrics.ts` defines `logToolResult`/`logToolCall`/etc which collide with
+// the human-readable versions in `utils.ts`. Export the metrics surface
+// explicitly to keep the API surface clear: `Metrics`, `recordLatency`,
+// `withMetrics` are the canonical names; the structured `log*` helpers stay
+// internal (imported directly from `agent-engine-runner-shared/metrics`).
+export { Metrics, recordLatency, withMetrics, } from "./metrics.js";
+export * from "./node_logger.js";
+export * from "./structured_logging.js";
+export * from "./tracing/index.js";
+export * from "./span_names.js";
+export { AppBoundRuntime, AppBoundCrudClient } from "./memory_appbound.js";
+export { ToolAPIErrorSchema } from "./tool_api_error.js";

package/dist/launcher.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Launcher module for pipeline-built agent containers (TS port of
+ * `agent_engine_runner_shared/launcher.py`).
+ *
+ * Reads `AGENT_ENTRYPOINT` and starts the user's agent code. The generated
+ * Dockerfile CMD invokes this file directly:
+ *
+ *     CMD ["node", "/app/node_modules/@mongodb-js/agent-engine-runner-shared/dist/launcher.js"]
+ *
+ * Environment variables:
+ *   AGENT_ENTRYPOINT  Startup target in one of these forms:
+ *     1) `<module-specifier>:<export-name>` — module is dynamically
+ *        imported and the named export is invoked.
+ *     2) `<module-specifier>:<export-name>` where the export is not a
+ *        function but has a callable `run()` method — `.run()` is invoked.
+ *     3) `<module-specifier>` (no colon) — defaults to `:main`.
+ *
+ * Structured logging is installed at the start of `runLauncher()` (before
+ * import) so import-time and entrypoint failures emit `ERROR` records
+ * instead of raw stderr stacks. `TenantRuntime` re-installs later; that
+ * call is idempotent. After install, `console.error` is captured as
+ * WARNING, so failure paths must use the logger.
+ *
+ * Security note: `AGENT_ENTRYPOINT` is baked into the Dockerfile ENV at
+ * image-build time by the platform pipeline, not supplied by the user at
+ * container runtime. The dynamic `import()` here serves the same role as
+ * `node -e "import('module')"` — bootstrapping a known, pre-installed
+ * module — and is an intentional exception to the "no dynamic code
+ * execution in platform code" guideline.
+ */
+/**
+ * Kubernetes' default termination-message path (the "File"
+ * TerminationMessagePolicy Kubelet always checks first, before falling back
+ * to log-tail capture). Nothing in the deployed pod spec sets a custom
+ * terminationMessagePath, so the default applies. A mutable binding so tests
+ * can redirect it to a temp file.
+ */
+export declare let terminationLogPath: string;
+/** Test-only override, mirroring `setHomeDirForTest` in error_reporting.ts. */
+export declare function setTerminationLogPathForTest(path: string): void;
+/**
+ * Truncate `text` to at most `maxLines` lines or `maxBytes` UTF-8 bytes,
+ * whichever limit is hit first, appending a truncation marker when either
+ * limit was hit.
+ */
+export declare function boundText(text: string, maxBytes?: number, maxLines?: number): string;
+/**
+ * Record a bounded, redacted summary of a fatal startup error to the
+ * container's termination message before the process exits, so the real
+ * cause of the crash survives past this process's own stdout into
+ * `ContainerStatus.LastTerminationState.Terminated.Message` — the field the
+ * platform's crash diagnostics read, and from there into the
+ * customer-facing deploy timeline.
+ *
+ * This is customer code (container mode), so unlike the platform's own
+ * components the design intentionally keeps the full exception name,
+ * message, and stack — redacted, not summarized away — since that detail is
+ * what the customer needs to fix their own agent. Best-effort: if the write
+ * fails, nothing is lost beyond what
+ * `TerminationMessagePolicy: FallbackToLogsOnError` already provides.
+ */
+export declare function writeTerminationMessage(summary: string, err?: Error): void;
+/**
+ * Startup-failure exit codes. OE's readiness wait can observe a
+ * workload's real exit code once it exits (via fctr's Wait RPC) but not the
+ * exception that caused it, so the exit code itself is the only signal that
+ * reliably survives a startup crash to reach OE. Chosen to avoid every range
+ * fctr's own const.go already claims: 0/1 (generic), 64-78 (sysexits.h), and
+ * 128+signal (signal deaths, e.g. 137=SIGKILL, 143=SIGTERM).
+ *
+ * Frozen wire contract: OE's classification of a startup failure depends on
+ * these exact values, and they are duplicated in
+ * runner-shared/src/agent_engine_runner_shared/launcher.py. Changing either file breaks
+ * OE's ability to distinguish failure causes and/or cross-language parity —
+ * keep the two in lockstep.
+ */
+export declare const EXIT_IMPORT_ERROR = 82;
+export declare const EXIT_NO_ENTRYPOINT = 83;
+export declare const EXIT_STARTUP_CRASH = 84;
+export interface ResolvedEntrypoint {
+    modulePath: string;
+    exportName: string;
+}
+/**
+ * Resolve an AGENT_ENTRYPOINT module path to a value Node's dynamic `import()`
+ * can load.
+ *
+ * The platform bakes the `agent.yaml` `entrypoint` verbatim into
+ * AGENT_ENTRYPOINT (same contract as the Python launcher), so the common form
+ * is a dotted, Python-style module path — e.g. `agent_pkg.main` — that maps to
+ * the agent's *compiled* output `<agentRoot>/dist/agent_pkg/main.js`. Node ESM
+ * `import()` treats a dotted string as a bare package specifier and cannot
+ * resolve it, so we translate it here: dots → path separators, under the
+ * compiled `dist/` directory, with a `.js` suffix, returned as a `file://` URL
+ * (the portable form for importing an absolute path across platforms).
+ *
+ * `agentRoot` defaults to `process.cwd()`, which at runtime is the agent
+ * package root: the generated Dockerfile sets `WORKDIR` to the install target
+ * and the `CMD` runs the launcher from there. It is injectable for tests.
+ *
+ * A value that is already directly importable — a relative path, an absolute
+ * path, or any path-bearing specifier (one that contains a `/`) — is returned
+ * unchanged, so a pre-resolved entrypoint (or a test passing an absolute file
+ * path) still works and is never double-translated. A path-shape signal (not a
+ * file extension) is used deliberately: a dotted module path whose final
+ * segment happens to be `js`/`mjs`/`cjs` (e.g. `agent_pkg.cjs`) must still be
+ * translated, not mistaken for an already-importable file.
+ */
+export declare function resolveImportTarget(modulePath: string, agentRoot?: string): string;
+/**
+ * Parse `AGENT_ENTRYPOINT` into `{ modulePath, exportName }`.
+ *
+ * Exits the process with `EXIT_NO_ENTRYPOINT` if the env var is unset or
+ * malformed — matches Python `_resolve_entrypoint`'s equivalent exit code.
+ * Exported so tests can spawn this in a subprocess and assert on exit
+ * code / stderr.
+ */
+export declare function resolveEntrypoint(): ResolvedEntrypoint;
+/**
+ * Entry point invoked when this file is run directly:
+ *
+ *   `node /app/node_modules/@mongodb-js/agent-engine-runner-shared/dist/launcher.js`
+ *
+ * Exits the process with the exit code matching the failure category
+ * (see `EXIT_IMPORT_ERROR`/`EXIT_NO_ENTRYPOINT`/`EXIT_STARTUP_CRASH` above)
+ * on any error path; resolves normally after the user's target function or
+ * `.run()` returns.
+ */
+export declare function runLauncher(): Promise<void>;
+//# sourceMappingURL=launcher.d.ts.map

package/dist/launcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launcher.d.ts","sourceRoot":"","sources":["../src/launcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAcH;;;;;;GAMG;AACH,eAAO,IAAI,kBAAkB,QAAyB,CAAC;AAEvD,+EAA+E;AAC/E,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE/D;AAYD;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,MAAsC,EAChD,QAAQ,GAAE,MAAsC,GAC/C,MAAM,CA+BR;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAY1E;AAmBD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,eAAO,MAAM,kBAAkB,KAAK,CAAC;AACrC,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AA4BD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,MAAsB,GAChC,MAAM,CAWR;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,kBAAkB,CAkCtD;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAoFjD"}