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

package/dist/launcher.js

@@ -0,0 +1,325 @@
+/**
+ * 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.
+ */
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { getLogger, setupLogging } from "./logger.js";
+import { runWithCustomerOrigin } from "./context.js";
+import { redactText } from "./error_reporting.js";
+import { materializeMcpOauthSecretCache } from "./mcp_oauth_secret.js";
+import { getRuntimeMode } from "./utils.js";
+const logger = getLogger("agent_engine_runner_shared.launcher");
+/**
+ * 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 let terminationLogPath = "/dev/termination-log";
+/** Test-only override, mirroring `setHomeDirForTest` in error_reporting.ts. */
+export function setTerminationLogPathForTest(path) {
+    terminationLogPath = path;
+}
+/**
+ * 4 KiB / 40 lines, whichever is reached first — the same bound the deploy
+ * event pipeline applies (see pkg/logredaction.DefaultMaxBytes/DefaultMaxLines
+ * in the Go services, and `_bound_text` in the Python launcher; kept in sync
+ * by convention across all three, since there's no shared package for this
+ * across languages).
+ */
+const TERMINATION_MESSAGE_MAX_BYTES = 4 * 1024;
+const TERMINATION_MESSAGE_MAX_LINES = 40;
+/**
+ * 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 function boundText(text, maxBytes = TERMINATION_MESSAGE_MAX_BYTES, maxLines = TERMINATION_MESSAGE_MAX_LINES) {
+    const marker = "\n[truncated]";
+    let truncated = false;
+    const lines = text.split("\n");
+    if (lines.length > maxLines) {
+        text = lines.slice(0, maxLines).join("\n");
+        truncated = true;
+    }
+    const encoded = Buffer.from(text, "utf-8");
+    if (encoded.length > maxBytes) {
+        // toString("utf-8") on a boundary-split multi-byte sequence replaces the
+        // partial tail with U+FFFD rather than throwing, which is an acceptable
+        // (rare, cosmetic) outcome for a diagnostic message under a hard cap.
+        text = encoded.subarray(0, maxBytes).toString("utf-8");
+        truncated = true;
+    }
+    if (!truncated)
+        return text;
+    // Reserve headroom for `marker` so appending it below can't push the
+    // final write past maxBytes — kubelet's own read of /dev/termination-log
+    // is a blind byte-level cut that would otherwise mangle the tail,
+    // potentially the marker itself.
+    const budget = Math.max(0, maxBytes - marker.length);
+    const finalEncoded = Buffer.from(text, "utf-8");
+    if (finalEncoded.length > budget) {
+        text = finalEncoded.subarray(0, budget).toString("utf-8");
+    }
+    return `${text}${marker}`;
+}
+/**
+ * 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 function writeTerminationMessage(summary, err) {
+    let text = summary;
+    if (err !== undefined) {
+        text = `${summary}\n${err.stack ?? `${err.name}: ${err.message}`}`;
+    }
+    text = redactText(text);
+    text = boundText(text);
+    try {
+        writeFileSync(terminationLogPath, text, { encoding: "utf-8" });
+    }
+    catch {
+        // Best-effort — see doc comment above.
+    }
+}
+/**
+ * Log an ERROR, write a termination message via `writeTerminationMessage`,
+ * and exit. Routes every deployment-breaking launcher exit through one path
+ * — rather than instrumenting a hand-picked few — so the container's
+ * termination message always carries the real cause forward to
+ * `ContainerStatus.LastTerminationState.Terminated.Message`.
+ */
+function fatalWithTermination(summary, err, code = 1) {
+    if (err !== undefined) {
+        logger.error(err, `${summary}: ${err.message}`);
+    }
+    else {
+        logger.error(summary);
+    }
+    writeTerminationMessage(summary, err);
+    process.exit(code);
+}
+/**
+ * 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 const EXIT_IMPORT_ERROR = 82;
+export const EXIT_NO_ENTRYPOINT = 83;
+export const EXIT_STARTUP_CRASH = 84;
+/**
+ * Resolve RUNNER_MODE for the early structured-logging install, falling back
+ * to "aer" when unset or unrecognized. An unrecognized value would reach the
+ * record's `service` field verbatim, and `/agent-logs` drops anything outside
+ * `{agent-execution-runtime, tool-executor}` — so the crash log would vanish.
+ * AGENT_ENTRYPOINT pods only ever run aer/tool.
+ */
+function resolveRunnerMode() {
+    try {
+        return getRuntimeMode();
+    }
+    catch {
+        return "aer";
+    }
+}
+/**
+ * Normalize a thrown value to an `Error`: `layout.ts` only populates
+ * `exc_type`/`exc_message`/`exc_traceback` for a genuine `Error`, and casting
+ * a non-Error would make `.name`/`.message` read `undefined`.
+ */
+function toError(value) {
+    return value instanceof Error
+        ? value
+        : new Error(String(value), { cause: value });
+}
+/**
+ * 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 function resolveImportTarget(modulePath, agentRoot = process.cwd()) {
+    const alreadyImportable = modulePath.startsWith(".") ||
+        modulePath.startsWith("/") ||
+        modulePath.includes("/");
+    if (alreadyImportable) {
+        return modulePath;
+    }
+    const relPath = modulePath.split(".").join("/");
+    const absPath = resolve(agentRoot, "dist", `${relPath}.js`);
+    return pathToFileURL(absPath).href;
+}
+/**
+ * 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 function resolveEntrypoint() {
+    // Surrounding whitespace is stripped because the build pipeline extracts this
+    // value from agent.yaml with a shell pipeline: a file authored on Windows
+    // leaves a trailing CR that would otherwise become part of the export name
+    // looked up below.
+    const raw = (process.env["AGENT_ENTRYPOINT"] ?? "").trim();
+    if (!raw) {
+        fatalWithTermination("AGENT_ENTRYPOINT is not set", undefined, EXIT_NO_ENTRYPOINT);
+    }
+    let modulePath;
+    let exportName;
+    if (raw.includes(":")) {
+        const idx = raw.lastIndexOf(":");
+        modulePath = raw.slice(0, idx).trim();
+        exportName = raw.slice(idx + 1).trim();
+    }
+    else {
+        modulePath = raw;
+        exportName = "main";
+    }
+    if (!modulePath || !exportName) {
+        fatalWithTermination(`Invalid AGENT_ENTRYPOINT '${raw}': both module path and export name must be non-empty`, undefined, EXIT_NO_ENTRYPOINT);
+    }
+    return { modulePath, exportName };
+}
+/**
+ * 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 async function runLauncher() {
+    // Install before any import/entrypoint work. After this, console.error is
+    // captured as WARNING (not ERROR), so failure paths must use the logger.
+    setupLogging({ appName: "launcher", mode: resolveRunnerMode() });
+    // Decode platform-injected MCP OAuth secrets into the file cache before the
+    // agent module is imported, so any OAuth MCP client it constructs finds its
+    // token. Sets AGENTIC_MCP_OAUTH_DIR before mcp_oauth.ts resolves its cache
+    // dir on first (lazy) import.
+    try {
+        await materializeMcpOauthSecretCache();
+    }
+    catch (e) {
+        fatalWithTermination("Cannot materialize MCP OAuth credentials", toError(e));
+    }
+    const { modulePath, exportName } = resolveEntrypoint();
+    logger.info(`Launcher: importing ${modulePath}:${exportName}`);
+    const importTarget = resolveImportTarget(modulePath);
+    let mod;
+    try {
+        mod = (await runWithCustomerOrigin(() => import(importTarget)));
+    }
+    catch (e) {
+        // Include the resolved target so a cwd/WORKDIR mismatch or missing
+        // compiled file is visible during on-call debugging, not just the dotted
+        // module name the user wrote.
+        fatalWithTermination(`Cannot import module '${modulePath}' (resolved to '${importTarget}')`, toError(e), EXIT_IMPORT_ERROR);
+    }
+    const target = mod[exportName];
+    if (target === undefined) {
+        fatalWithTermination(`Module '${modulePath}' has no export '${exportName}'`, undefined, EXIT_NO_ENTRYPOINT);
+    }
+    // Preferred form module:function; compatibility form module:appObject with a
+    // callable .run(). Function first, so a callable export that also carries a
+    // .run property still invokes the export itself.
+    const run = target !== null && typeof target === "object"
+        ? target["run"]
+        : undefined;
+    const invoke = typeof target === "function"
+        ? target
+        : typeof run === "function"
+            ? run.bind(target)
+            : null;
+    if (invoke !== null) {
+        try {
+            // Scope covers the entrypoint's execution, not just its import —
+            // AsyncLocalStorage propagates across awaits inside the callback.
+            await runWithCustomerOrigin(() => invoke());
+        }
+        catch (e) {
+            fatalWithTermination(`Unhandled exception from agent entrypoint '${modulePath}:${exportName}'`, toError(e), EXIT_STARTUP_CRASH);
+        }
+        return;
+    }
+    fatalWithTermination(`'${modulePath}:${exportName}' is not callable and has no callable 'run()' method`, undefined, EXIT_NO_ENTRYPOINT);
+}
+// CLI entrypoint guard: only auto-run when invoked as `node launcher.js`,
+// not when imported as a library (e.g., from tests or barrel re-exports).
+const isCliEntry = process.argv[1] !== undefined &&
+    import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isCliEntry) {
+    runLauncher().catch((e) => {
+        fatalWithTermination("Launcher failed", toError(e));
+    });
+}

package/dist/logger.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Module logger factory for the Runner SDK.
+ *
+ * Wraps log4js to provide a Python-equivalent logging surface. log4js was
+ * chosen over pino because its named-category registry mirrors Python's
+ * `logging.getLogger(name)` semantics one-for-one: a global, hierarchical
+ * registry of named loggers with per-name level overrides — none of which
+ * pino offers natively. Reconfiguring the root via `setupLogging` is
+ * automatically visible to every previously-issued `getLogger()` reference,
+ * matching Python's behaviour without the Proxy-rebind dance pino required.
+ *
+ * Surface:
+ *
+ * - `getLogger("agent_engine_runner_shared.utils")` — named logger from the global
+ *   registry, equivalent to Python `logging.getLogger(__name__)`. The same
+ *   instance is returned on every call for a given name.
+ * - `setupLogging({mode, level, ...})` — configure the root. When
+ *   `STRUCTURED_LOGGING=true` delegates to `installStructuredLogging` so all
+ *   output emerges as single-line JSON matching the agent-log
+ *   contract; otherwise installs a human-readable pattern layout to stdout.
+ *   On-disk logging is not part of the production model — container stdout
+ *   is shipped to S3 by Fluent Bit, so a duplicate copy adds no value. When
+ *   `AGENTIC_DEV_MODES` is set (local dev-up compose stacks only), a
+ *   best-effort `dateFile` appender is added so the Local Dev UI log viewer
+ *   can read agent output from disk; it rotates daily and keeps 5 files,
+ *   mirroring Python's `TimedRotatingFileHandler`.
+ * - Noisy HTTP libraries (`undici`, `httpx`, `httpcore`, `urllib3`,
+ *   `fastify.access`, `uvicorn.access`) are silenced to `warn` — equivalent
+ *   to Python's `logging.getLogger("httpx").setLevel(WARNING)` block.
+ */
+import { type Logger } from "log4js";
+/**
+ * Mark the log4js root as already configured.
+ *
+ * Called by `installStructuredLogging` so that a direct `installStructuredLogging()`
+ * (the documented startup entrypoint) followed by `getLogger()` does NOT let
+ * `ensureDefaultConfig()` clobber the structured config with the
+ * human stdout appender. Without this the structured pipeline could be torn
+ * down — and re-running `log4js.configure` over patched stdio risks recursion.
+ */
+export declare function markConfigured(): void;
+/**
+ * Return a logger named after the caller's module.
+ *
+ * Mirrors Python `logging.getLogger(__name__)`. log4js maintains a global
+ * registry, so a later `setupLogging` reconfiguration is automatically
+ * visible to every previously-issued reference. First call performs a
+ * default configuration so module-scope `const logger = getLogger(__name__)`
+ * patterns work without an explicit `setupLogging` at startup.
+ */
+export declare function getLogger(name?: string): Logger;
+export interface SetupLoggingArgs {
+    /**
+     * Application name — surfaced in the install log line and used to name
+     * the dev-mode log file (`<appName>-<mode>.log`) when AGENTIC_DEV_MODES
+     * is set. Matches Python `app_name`.
+     */
+    appName?: string;
+    /** Runner mode (`aer` / `tool` / `orchestrator` / `memory-server`). */
+    mode?: string;
+    /** Log level — string ("debug", "info", ...) or `LOG_LEVEL` env when omitted. */
+    logLevel?: string | null;
+    /**
+     * Log directory — used only when `AGENTIC_DEV_MODES` is set to write
+     * a dev-mode file log alongside console output.
+     */
+    logDir?: string | null;
+    /** Unused — parity placeholder. */
+    backupCount?: number;
+}
+/**
+ * Configure the root logger. Mirrors `agent_engine_runner_shared.utils.setup_logging`.
+ *
+ * When `STRUCTURED_LOGGING=true` is set, delegates to
+ * `installStructuredLogging` so all output emerges as single-line JSON
+ * matching the agent-log contract. On-disk logging is not part of the
+ * production model — Fluent Bit ships container stdout to S3, so a
+ * duplicate copy adds no value. The exception is local dev: when
+ * `AGENTIC_DEV_MODES` is set (dev-up compose stacks only), a rotating file
+ * sink is attached alongside the console/structured output.
+ *
+ * Unlike Python's `setup_logging` we don't need to manually drop existing
+ * handlers before re-adding the console handler: `log4js.configure` fully
+ * replaces the prior `appenders`/`categories` config on each call, so a
+ * repeat call never accumulates duplicate writers. There's also no
+ * stdout/stderr handler-close hazard to guard against — log4js's `stdout`
+ * appender owns its own write path.
+ *
+ * @param args.appName     Application name — install line + dev log file name.
+ * @param args.mode        Runtime mode (aer, tool, orchestrator, memory-server).
+ * @param args.logLevel    Log level (default: from `LOG_LEVEL` env or INFO).
+ * @param args.logDir      Log directory for dev-mode file logging (only when AGENTIC_DEV_MODES is set).
+ * @param args.backupCount Unused — parity placeholder.
+ */
+export declare function setupLogging(args?: SetupLoggingArgs): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAe,EAAsB,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAC;AA4EjE;;;;;;;;GAQG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAG/C;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,mCAAmC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAuCD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,IAAI,GAAE,gBAAqB,GAAG,MAAM,CAyChE"}

package/dist/logger.js

@@ -0,0 +1,204 @@
+/**
+ * Module logger factory for the Runner SDK.
+ *
+ * Wraps log4js to provide a Python-equivalent logging surface. log4js was
+ * chosen over pino because its named-category registry mirrors Python's
+ * `logging.getLogger(name)` semantics one-for-one: a global, hierarchical
+ * registry of named loggers with per-name level overrides — none of which
+ * pino offers natively. Reconfiguring the root via `setupLogging` is
+ * automatically visible to every previously-issued `getLogger()` reference,
+ * matching Python's behaviour without the Proxy-rebind dance pino required.
+ *
+ * Surface:
+ *
+ * - `getLogger("agent_engine_runner_shared.utils")` — named logger from the global
+ *   registry, equivalent to Python `logging.getLogger(__name__)`. The same
+ *   instance is returned on every call for a given name.
+ * - `setupLogging({mode, level, ...})` — configure the root. When
+ *   `STRUCTURED_LOGGING=true` delegates to `installStructuredLogging` so all
+ *   output emerges as single-line JSON matching the agent-log
+ *   contract; otherwise installs a human-readable pattern layout to stdout.
+ *   On-disk logging is not part of the production model — container stdout
+ *   is shipped to S3 by Fluent Bit, so a duplicate copy adds no value. When
+ *   `AGENTIC_DEV_MODES` is set (local dev-up compose stacks only), a
+ *   best-effort `dateFile` appender is added so the Local Dev UI log viewer
+ *   can read agent output from disk; it rotates daily and keeps 5 files,
+ *   mirroring Python's `TimedRotatingFileHandler`.
+ * - Noisy HTTP libraries (`undici`, `httpx`, `httpcore`, `urllib3`,
+ *   `fastify.access`, `uvicorn.access`) are silenced to `warn` — equivalent
+ *   to Python's `logging.getLogger("httpx").setLevel(WARNING)` block.
+ */
+import log4js from "log4js";
+import { accessSync, constants, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { installStructuredLogging } from "./structured_logging.js";
+const NOISY_LOGGERS = ["undici", "fastify.access"];
+// Pattern matches Python's `setup_logging` console formatter shape:
+// `%(asctime)s | %(levelname)-8s | %(message)s`. The file variant adds the
+// category (mirroring Python's detailed file formatter).
+const HUMAN_PATTERN = "%d{yyyy-MM-dd hh:mm:ss} | %p | %c | %m";
+const FILE_PATTERN = "%d{yyyy-MM-dd hh:mm:ss} | %p | %c{1} | %m";
+// Daily rotation with 5 kept files, matching Python's TimedRotatingFileHandler
+// (which="midnight", backupCount=5). Keeps the dev log file bounded so a noisy
+// local agent cannot fill the host disk.
+const DEV_FILE_ROTATION = {
+    pattern: "yyyy-MM-dd",
+    numToKeep: 5,
+    keepFileExt: true,
+};
+function envLevel() {
+    return (process.env["LOG_LEVEL"] ?? "info").toLowerCase();
+}
+function noisyCategories() {
+    return Object.fromEntries(NOISY_LOGGERS.map((name) => [
+        name,
+        { appenders: ["console"], level: "warn" },
+    ]));
+}
+function buildHumanConfig(level, fileOpts) {
+    const appenders = {
+        console: {
+            type: "stdout",
+            layout: { type: "pattern", pattern: HUMAN_PATTERN },
+        },
+    };
+    const defaultAppenders = ["console"];
+    if (fileOpts) {
+        appenders.devFile = {
+            type: "dateFile",
+            filename: fileOpts.logPath,
+            layout: { type: "pattern", pattern: FILE_PATTERN },
+            ...DEV_FILE_ROTATION,
+        };
+        defaultAppenders.push("devFile");
+    }
+    return {
+        appenders,
+        categories: {
+            default: { appenders: defaultAppenders, level },
+            ...noisyCategories(),
+        },
+    };
+}
+let configured = false;
+function ensureDefaultConfig() {
+    if (configured)
+        return;
+    log4js.configure(buildHumanConfig(envLevel()));
+    configured = true;
+}
+/**
+ * Mark the log4js root as already configured.
+ *
+ * Called by `installStructuredLogging` so that a direct `installStructuredLogging()`
+ * (the documented startup entrypoint) followed by `getLogger()` does NOT let
+ * `ensureDefaultConfig()` clobber the structured config with the
+ * human stdout appender. Without this the structured pipeline could be torn
+ * down — and re-running `log4js.configure` over patched stdio risks recursion.
+ */
+export function markConfigured() {
+    configured = true;
+}
+/**
+ * Return a logger named after the caller's module.
+ *
+ * Mirrors Python `logging.getLogger(__name__)`. log4js maintains a global
+ * registry, so a later `setupLogging` reconfiguration is automatically
+ * visible to every previously-issued reference. First call performs a
+ * default configuration so module-scope `const logger = getLogger(__name__)`
+ * patterns work without an explicit `setupLogging` at startup.
+ */
+export function getLogger(name) {
+    ensureDefaultConfig();
+    return log4js.getLogger(name);
+}
+/**
+ * Keep the dev log file name inside the log directory. `appName`/`mode` are
+ * caller-supplied (`RuntimeOpts.appName`) and this is the one place the
+ * package writes to disk, so a value containing a path separator could
+ * otherwise redirect the write outside `logDir`. Separators and NUL are
+ * replaced; an empty result falls back to a default so the name stays
+ * deterministic.
+ */
+function sanitizeFileComponent(part, fallback) {
+    const cleaned = part.replace(/[/\\\0]/g, "_").trim();
+    return cleaned.length > 0 ? cleaned : fallback;
+}
+/**
+ * Best-effort mkdir + writability probe for the dev-mode log directory.
+ * Returns false (and warns) when the directory cannot be created or written
+ * so both logging paths skip the file appender instead of installing one
+ * that errors on every write. The write probe matters because
+ * `mkdirSync(recursive)` is a no-op success on an existing directory that
+ * happens to be read-only. Mirrors Python's warn-and-continue in
+ * `_install_file_handler`.
+ */
+function ensureLogDir(logDir) {
+    try {
+        mkdirSync(logDir, { recursive: true });
+        accessSync(logDir, constants.W_OK);
+        return true;
+    }
+    catch (err) {
+        // Pre-configuration diagnostic — the logger itself isn't set up yet,
+        // so warn on stderr rather than pulling in a default log4js config.
+        console.warn(`File logging disabled (logDir=${logDir} not writable: ${err instanceof Error ? err.message : String(err)}). Continuing with console output only.`);
+        return false;
+    }
+}
+/**
+ * Configure the root logger. Mirrors `agent_engine_runner_shared.utils.setup_logging`.
+ *
+ * When `STRUCTURED_LOGGING=true` is set, delegates to
+ * `installStructuredLogging` so all output emerges as single-line JSON
+ * matching the agent-log contract. On-disk logging is not part of the
+ * production model — Fluent Bit ships container stdout to S3, so a
+ * duplicate copy adds no value. The exception is local dev: when
+ * `AGENTIC_DEV_MODES` is set (dev-up compose stacks only), a rotating file
+ * sink is attached alongside the console/structured output.
+ *
+ * Unlike Python's `setup_logging` we don't need to manually drop existing
+ * handlers before re-adding the console handler: `log4js.configure` fully
+ * replaces the prior `appenders`/`categories` config on each call, so a
+ * repeat call never accumulates duplicate writers. There's also no
+ * stdout/stderr handler-close hazard to guard against — log4js's `stdout`
+ * appender owns its own write path.
+ *
+ * @param args.appName     Application name — install line + dev log file name.
+ * @param args.mode        Runtime mode (aer, tool, orchestrator, memory-server).
+ * @param args.logLevel    Log level (default: from `LOG_LEVEL` env or INFO).
+ * @param args.logDir      Log directory for dev-mode file logging (only when AGENTIC_DEV_MODES is set).
+ * @param args.backupCount Unused — parity placeholder.
+ */
+export function setupLogging(args = {}) {
+    const mode = args.mode ?? "aer";
+    const logLevel = args.logLevel ?? null;
+    const appName = args.appName ?? "runner";
+    const logDir = args.logDir ?? process.env["LOG_DIR"] ?? "./logs";
+    // Dev-only file logging: gated on AGENTIC_DEV_MODES (set exclusively by
+    // the CLI's dev-up compose templates) AND a usable log directory.
+    const devFileEnabled = !!process.env["AGENTIC_DEV_MODES"] && ensureLogDir(logDir);
+    const devLogPath = devFileEnabled
+        ? join(logDir, `${sanitizeFileComponent(appName, "runner")}-${sanitizeFileComponent(mode, "aer")}.log`)
+        : null;
+    if ((process.env["STRUCTURED_LOGGING"] ?? "").toLowerCase() === "true") {
+        // Pass `mode` through explicitly so the layout's `service` field
+        // reflects the caller's intent even if `RUNNER_MODE` env happens to
+        // be unset — without this, a `setupLogging({mode: "aer"})` call with
+        // no env would silently produce `service="agent-execution-runtime"`
+        // (the default), lying about which component emitted the line.
+        installStructuredLogging({
+            level: logLevel,
+            mode,
+            fileLogPath: devLogPath,
+        });
+        configured = true;
+        return log4js.getLogger();
+    }
+    const level = (logLevel ?? envLevel()).toLowerCase();
+    log4js.configure(buildHumanConfig(level, devLogPath ? { logPath: devLogPath } : undefined));
+    configured = true;
+    const root = log4js.getLogger();
+    root.info(`Logging initialized: level=${level.toUpperCase()}, file=${devLogPath ?? "<disabled>"}, mode=${mode}, app=${appName}`);
+    return root;
+}

package/dist/mcp_oauth.d.ts

@@ -0,0 +1,51 @@
+/**
+ * OAuth provider and file-backed token storage for remote MCP servers.
+ *
+ * Port of `agent_engine_runner_shared/mcp_oauth.py`, adapted to `@modelcontextprotocol/sdk`'s
+ * `OAuthClientProvider` interface — a lower-level, method-based contract
+ * (`tokens()`/`saveTokens()`/`clientInformation()`/...) rather than Python's
+ * httpx-`Auth`-flow-based `OAuthClientProvider`. The cache file format/path
+ * is kept byte-identical to the Python side so `agentengine dev mcp auth
+ * login/status/upload` (Go CLI) and this runtime read/write the same file
+ * regardless of which SDK the agent uses.
+ */
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type { RuntimeMCPServerConfig } from "./agent_config.js";
+export declare const DEFAULT_MCP_OAUTH_CLIENT_NAME = "Atlas Agent Engine Dev MCP Client";
+export declare const DEFAULT_MCP_OAUTH_REDIRECT_URI = "http://127.0.0.1:8765/callback";
+/**
+ * Cache directory, resolved at call time — not a module-level constant.
+ *
+ * `materializeMcpOauthSecretCache()` (in `mcp_oauth_secret.ts`) sets
+ * `AGENTIC_MCP_OAUTH_DIR` at startup. A frozen import-time const would capture
+ * the value from before that runs whenever this module is imported first (e.g.
+ * via the package barrel), so the reader and writer could resolve to different
+ * directories. Reading the env on each call keeps them in lockstep regardless
+ * of import order.
+ */
+export declare function mcpOauthCacheDir(): string;
+/**
+ * Return a collision-free cache basename scoped to alias and endpoint.
+ * agent.yaml imposes no charset on aliases, so uniqueness comes from hashing
+ * the raw alias whenever the readable form would lose information, and from
+ * the endpoint hash that stops the same alias sharing credentials across
+ * different MCP servers.
+ */
+export declare function mcpOauthCacheName(serverName: string, serverUrl: string): string;
+/**
+ * Return a non-interactive OAuth provider for a configured MCP server.
+ *
+ * `cacheDir` overrides `mcpOauthCacheDir()` — used by tests and any caller
+ * that needs an isolated cache location instead of the shared `agentengine dev`
+ * cache directory.
+ */
+export declare function makeMcpOauthAuth(serverName: string, config: RuntimeMCPServerConfig, cacheDir?: string): OAuthClientProvider;
+/**
+ * Return a client-credentials OAuth provider for a configured MCP server.
+ *
+ * `cacheDir` overrides `mcpOauthCacheDir()` — used by tests and any caller
+ * that needs an isolated cache location instead of the shared `agentengine dev`
+ * cache directory.
+ */
+export declare function makeMcpClientCredentialsAuth(serverName: string, config: RuntimeMCPServerConfig, cacheDir?: string): OAuthClientProvider;
+//# sourceMappingURL=mcp_oauth.d.ts.map