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

package/dist/structured_logging/stdio_capture.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Capture of `process.stdout` / `process.stderr` writes so stray
+ * `console.log` / direct writes emerge as structured-logging records tagged
+ * `source: "stdout"` / `"stderr"`.
+ */
+import { type Logger } from "log4js";
+import { ORIGINAL_WRITE_SLOT } from "./constants.js";
+type WriteFn = NodeJS.WriteStream["write"];
+type PatchableStream = NodeJS.WriteStream & {
+    [ORIGINAL_WRITE_SLOT]?: WriteFn;
+};
+/**
+ * Snapshot the original `write` on the first install and stash it on the
+ * stream under `ORIGINAL_WRITE_SLOT`. Subsequent calls return the same
+ * snapshot — matches the Python `_unwrap_logging_stream` recursion guard:
+ * the appender always writes via the snapshot, never via the patched
+ * `write` we've installed on top.
+ */
+export declare function snapshotOriginalWrite(stream: PatchableStream): WriteFn;
+/**
+ * Replacement for `process.stdout.write` / `process.stderr.write` that
+ * routes writes through a logger.
+ *
+ * Bare `console.log` / `process.stdout.write` calls (and any other code
+ * writing directly to the captured stream) are rewritten as log records
+ * tagged with `source: "stdout"` (or `"stderr"`) so the layout can mark
+ * them as such on the wire. Lines are buffered until newline, with a hard
+ * byte cap so a producer writing without `\n` cannot grow the buffer
+ * until OOM (see `MAX_BUFFER_BYTES`).
+ *
+ * Unlike the Python `LoggingStream` we do not need an `RLock` — Node's
+ * event loop is single-threaded, so concurrent `write()` calls can't
+ * interleave bytes mid-line. We also don't reproduce Python's
+ * `fileno()`/`buffer`/`encoding` delegation: we only patch the `write`
+ * method, leaving `process.stdout`'s fd / TTY introspection intact for
+ * subprocess piping, progress-bar libs, and grpc-internal logging.
+ */
+/** @internal — exported only for tests; not part of the public API. */
+export declare class LoggingStream {
+    private readonly logger;
+    private readonly level;
+    private readonly source;
+    private buffer;
+    constructor(logger: Logger, level: "info" | "warn", source: "stdout" | "stderr");
+    write(chunk: unknown, encodingOrCb?: unknown, maybeCb?: unknown): boolean;
+    /**
+     * Emit any buffered bytes that never got a trailing newline, then clear the
+     * buffer. Called on process exit so a final `console.log`/`process.stdout.
+     * write` without a `\n` right before shutdown is not lost — mirrors Python's
+     * `LoggingStream.flush()` (which the interpreter invokes when it flushes
+     * `sys.stdout` at shutdown). The same whitespace-only skip as `write()`
+     * applies: a blank tail is not worth a record.
+     */
+    flush(): void;
+    private emit;
+}
+export declare function patchStdio(): void;
+export {};
+//# sourceMappingURL=stdio_capture.d.ts.map

package/dist/structured_logging/stdio_capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio_capture.d.ts","sourceRoot":"","sources":["../../src/structured_logging/stdio_capture.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAe,EAAE,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAC;AAE7C,OAAO,EAIL,mBAAmB,EAEpB,MAAM,gBAAgB,CAAC;AAGxB,KAAK,OAAO,GAAG,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;AAC3C,KAAK,eAAe,GAAG,MAAM,CAAC,WAAW,GAAG;IAAE,CAAC,mBAAmB,CAAC,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEhF;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAMtE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,uEAAuE;AACvE,qBAAa,aAAa;IAItB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IALzB,OAAO,CAAC,MAAM,CAAM;gBAGD,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,MAAM,EAAE,QAAQ,GAAG,QAAQ;IAG9C,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO;IA4CzE;;;;;;;OAOG;IACH,KAAK,IAAI,IAAI;IAKb,OAAO,CAAC,IAAI;CAOb;AAED,wBAAgB,UAAU,IAAI,IAAI,CAwDjC"}

package/dist/structured_logging/stdio_capture.js

@@ -0,0 +1,164 @@
+/**
+ * Capture of `process.stdout` / `process.stderr` writes so stray
+ * `console.log` / direct writes emerge as structured-logging records tagged
+ * `source: "stdout"` / `"stderr"`.
+ */
+import log4js from "log4js";
+import { ACTIVE_CAPTURES, EXIT_FLUSH_REGISTERED, MAX_BUFFER_BYTES, ORIGINAL_WRITE_SLOT, STDIO_CAPTURE_CATEGORY, } from "./constants.js";
+import { truncateUtf8 } from "./serialize.js";
+/**
+ * Snapshot the original `write` on the first install and stash it on the
+ * stream under `ORIGINAL_WRITE_SLOT`. Subsequent calls return the same
+ * snapshot — matches the Python `_unwrap_logging_stream` recursion guard:
+ * the appender always writes via the snapshot, never via the patched
+ * `write` we've installed on top.
+ */
+export function snapshotOriginalWrite(stream) {
+    const existing = stream[ORIGINAL_WRITE_SLOT];
+    if (existing)
+        return existing;
+    const original = stream.write.bind(stream);
+    stream[ORIGINAL_WRITE_SLOT] = original;
+    return original;
+}
+/**
+ * Replacement for `process.stdout.write` / `process.stderr.write` that
+ * routes writes through a logger.
+ *
+ * Bare `console.log` / `process.stdout.write` calls (and any other code
+ * writing directly to the captured stream) are rewritten as log records
+ * tagged with `source: "stdout"` (or `"stderr"`) so the layout can mark
+ * them as such on the wire. Lines are buffered until newline, with a hard
+ * byte cap so a producer writing without `\n` cannot grow the buffer
+ * until OOM (see `MAX_BUFFER_BYTES`).
+ *
+ * Unlike the Python `LoggingStream` we do not need an `RLock` — Node's
+ * event loop is single-threaded, so concurrent `write()` calls can't
+ * interleave bytes mid-line. We also don't reproduce Python's
+ * `fileno()`/`buffer`/`encoding` delegation: we only patch the `write`
+ * method, leaving `process.stdout`'s fd / TTY introspection intact for
+ * subprocess piping, progress-bar libs, and grpc-internal logging.
+ */
+/** @internal — exported only for tests; not part of the public API. */
+export class LoggingStream {
+    logger;
+    level;
+    source;
+    buffer = "";
+    constructor(logger, level, source) {
+        this.logger = logger;
+        this.level = level;
+        this.source = source;
+    }
+    write(chunk, encodingOrCb, maybeCb) {
+        const text = typeof chunk === "string"
+            ? chunk
+            : Buffer.isBuffer(chunk)
+                ? chunk.toString(typeof encodingOrCb === "string"
+                    ? encodingOrCb
+                    : "utf-8")
+                : String(chunk ?? "");
+        if (text) {
+            this.buffer += text;
+            let newlineIdx = this.buffer.indexOf("\n");
+            while (newlineIdx !== -1) {
+                const line = this.buffer.slice(0, newlineIdx);
+                this.buffer = this.buffer.slice(newlineIdx + 1);
+                // Whitespace-only lines are uninteresting — emitting a JSON
+                // record with `message: "   "` adds noise and makes downstream
+                // filters work harder. Mirrors the `if line.strip()` filter in
+                // the Python LoggingStream; do not "fix" by removing it.
+                if (line.trim())
+                    this.emit(line);
+                newlineIdx = this.buffer.indexOf("\n");
+            }
+            // Force-emit a truncated record if a producer is writing without
+            // newlines — mirrors the exc_traceback truncation pattern. Slice
+            // by UTF-8 byte count via `truncateUtf8` so the cap reflects what
+            // Fluent Bit ships AND a partial multi-byte sequence at the cut
+            // point is dropped rather than turned into U+FFFD replacement bytes
+            // that would push the encoded payload back over the budget.
+            if (Buffer.byteLength(this.buffer, "utf-8") > MAX_BUFFER_BYTES) {
+                this.emit(truncateUtf8(this.buffer, MAX_BUFFER_BYTES));
+                this.buffer = "";
+            }
+        }
+        // Honor `write(chunk, cb)` and `write(chunk, encoding, cb)` callback
+        // signatures so callers waiting on drain semantics don't hang.
+        const cb = typeof encodingOrCb === "function" ? encodingOrCb : maybeCb;
+        if (typeof cb === "function")
+            cb();
+        return true;
+    }
+    /**
+     * Emit any buffered bytes that never got a trailing newline, then clear the
+     * buffer. Called on process exit so a final `console.log`/`process.stdout.
+     * write` without a `\n` right before shutdown is not lost — mirrors Python's
+     * `LoggingStream.flush()` (which the interpreter invokes when it flushes
+     * `sys.stdout` at shutdown). The same whitespace-only skip as `write()`
+     * applies: a blank tail is not worth a record.
+     */
+    flush() {
+        if (this.buffer.trim())
+            this.emit(this.buffer);
+        this.buffer = "";
+    }
+    emit(line) {
+        if (this.level === "warn") {
+            this.logger.warn({ source: this.source }, line);
+        }
+        else {
+            this.logger.info({ source: this.source }, line);
+        }
+    }
+}
+export function patchStdio() {
+    const stdoutStream = process.stdout;
+    const stderrStream = process.stderr;
+    // Snapshot before patching even though we don't reference the result
+    // here — ensures the slot is populated for the appender below, and
+    // protects against a re-install wrapping our already-patched `write`.
+    snapshotOriginalWrite(stdoutStream);
+    snapshotOriginalWrite(stderrStream);
+    // Pull from the dedicated capture category (configured at `trace` in
+    // installStructuredLogging) instead of the root logger — see the
+    // STDIO_CAPTURE_CATEGORY comment for why. Routing through the root would
+    // inherit the operator-set LOG_LEVEL and silently drop stray
+    // `console.log` lines when LOG_LEVEL=WARN/ERROR, which is the exact
+    // behaviour Python's `Logger.handle()` bypass was added to prevent.
+    const captureLogger = log4js.getLogger(STDIO_CAPTURE_CATEGORY);
+    const stdoutCapture = new LoggingStream(captureLogger, "info", "stdout");
+    const stderrCapture = new LoggingStream(captureLogger, "warn", "stderr");
+    stdoutStream.write = stdoutCapture.write.bind(stdoutCapture);
+    stderrStream.write = stderrCapture.write.bind(stderrCapture);
+    // Flush any buffered tail (a final write without a trailing newline) on
+    // process exit so it isn't lost — the parity counterpart to Python's stdout
+    // flush at interpreter shutdown. The handler is registered once per process
+    // (`Symbol.for` guards against stacking one on every re-install), but it
+    // must flush the *currently* installed capture streams, not the ones from
+    // the first install it happened to close over. So the streams live in a
+    // shared global slot that every patchStdio call overwrites, and the handler
+    // reads that slot at exit time.
+    const g = globalThis;
+    // Flush the outgoing streams before dropping the reference to them: a
+    // re-install replaces process.stdout.write, so a partial (newline-less) line
+    // buffered in the previous capture would otherwise never be emitted anywhere
+    // — it's not carried over to the new stream, and the exit handler only sees
+    // whatever is current in ACTIVE_CAPTURES.
+    const prev = g[ACTIVE_CAPTURES];
+    if (prev) {
+        prev.stdout.flush();
+        prev.stderr.flush();
+    }
+    g[ACTIVE_CAPTURES] = { stdout: stdoutCapture, stderr: stderrCapture };
+    if (!g[EXIT_FLUSH_REGISTERED]) {
+        g[EXIT_FLUSH_REGISTERED] = true;
+        process.on("exit", () => {
+            const active = g[ACTIVE_CAPTURES];
+            if (active) {
+                active.stdout.flush();
+                active.stderr.flush();
+            }
+        });
+    }
+}

package/dist/structured_logging/uncaught.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Process-level crash handling for the structured-logging pipeline.
+ *
+ * Exceptions use `uncaughtExceptionMonitor`: Node keeps printing and exiting, so
+ * this never owns termination, and monitors run before any handler the agent
+ * installed. Rejections need a real listener — a monitor stops seeing them once
+ * the agent registers its own handler.
+ */
+import type { Logger } from "log4js";
+/** @internal — exported only for tests; not part of the public API. */
+export declare const FALLBACK_EXIT_MS = 5000;
+/** Install the crash listeners. Idempotent — registered once per process. */
+export declare function installUncaughtExceptionHandlers(rootLogger: Logger): void;
+//# sourceMappingURL=uncaught.d.ts.map

package/dist/structured_logging/uncaught.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uncaught.d.ts","sourceRoot":"","sources":["../../src/structured_logging/uncaught.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAOrC,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAwCrC,6EAA6E;AAC7E,wBAAgB,gCAAgC,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAczE"}

package/dist/structured_logging/uncaught.js

@@ -0,0 +1,58 @@
+/**
+ * Process-level crash handling for the structured-logging pipeline.
+ *
+ * Exceptions use `uncaughtExceptionMonitor`: Node keeps printing and exiting, so
+ * this never owns termination, and monitors run before any handler the agent
+ * installed. Rejections need a real listener — a monitor stops seeing them once
+ * the agent registers its own handler.
+ */
+import { ACTIVE_ROOT_LOGGER, UNCAUGHT_HANDLERS_REGISTERED, } from "./constants.js";
+/** @internal — exported only for tests; not part of the public API. */
+export const FALLBACK_EXIT_MS = 5000;
+function currentLogger() {
+    return globalThis[ACTIVE_ROOT_LOGGER];
+}
+function toError(reason) {
+    if (reason instanceof Error)
+        return reason;
+    const err = new Error(String(reason), { cause: reason });
+    err.name = "NonErrorRejection";
+    return err;
+}
+function logCrash(err, label) {
+    currentLogger().error(err, `${label}: ${err.name}: ${err.message}`);
+}
+function exitSoon() {
+    if (process.stdout.writableLength === 0) {
+        process.exit(1);
+    }
+    else {
+        process.stdout.once("drain", () => process.exit(1));
+    }
+}
+function handleFatalRejection(err) {
+    logCrash(err, "Unhandled promise rejection");
+    process.stderr.write((err.stack ?? String(err)) + "\n");
+    // Only own termination when nothing else is listening — another listener may
+    // be deliberately recovering. The timer backstops exitSoon()'s drain wait.
+    if (process.listenerCount("unhandledRejection") <= 1) {
+        process.exitCode = 1;
+        exitSoon();
+        setTimeout(() => process.exit(1), FALLBACK_EXIT_MS).unref();
+    }
+}
+/** Install the crash listeners. Idempotent — registered once per process. */
+export function installUncaughtExceptionHandlers(rootLogger) {
+    const g = globalThis;
+    g[ACTIVE_ROOT_LOGGER] = rootLogger;
+    if (g[UNCAUGHT_HANDLERS_REGISTERED])
+        return;
+    g[UNCAUGHT_HANDLERS_REGISTERED] = true;
+    process.on("uncaughtExceptionMonitor", (value) => {
+        // Typed `Error`, but Node forwards whatever was thrown.
+        logCrash(toError(value), "Uncaught exception");
+    });
+    process.on("unhandledRejection", (reason) => {
+        handleFatalRejection(toError(reason));
+    });
+}

package/dist/structured_logging.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Structured JSON logging for the agent runtime log capture pipeline.
+ *
+ * Emits single-line JSON records on container stdout. Fluent Bit tails the
+ * container log, the Lua filter derives tenant/workspace keys from pod
+ * metadata, and writes gzipped batches to S3. The API Gateway
+ * `GET /admin/api/v1/agent-logs` endpoint reads them back.
+ *
+ * Activated by calling `installStructuredLogging()` at runner startup —
+ * typically gated by `STRUCTURED_LOGGING=true`. When inactive, the default
+ * log4js root in `logger.ts` is unaffected.
+ *
+ * This module is split into focused files under `structured_logging/`:
+ *
+ * - `constants.ts` — tunables and shared identifiers (service map, byte caps,
+ *   capture category, the `Symbol.for` write slot).
+ * - `env.ts` — the install-time env snapshot (`FormatterEnv`, `snapshotEnv`).
+ * - `serialize.ts` — the crash-proof `jsonSafeStringify` and UTF-8-aware
+ *   `truncateUtf8` helpers.
+ * - `layout.ts` — `buildStructuredLayout`, the log4js layout that renders the JSON
+ *   envelope (`StructuredJSONFormatter` in the Python port).
+ * - `stdio_capture.ts` — `LoggingStream` + `patchStdio`, which replace
+ *   `process.stdout.write` / `process.stderr.write` so stray `console.log` /
+ *   direct writes also emerge as structured-logging records tagged `source: "stdout"`
+ *   (INFO) or `"stderr"` (WARNING). Forcing stderr to ERROR was tried in
+ *   Python and backed out — every deprecation warning would have paged
+ *   on-call; WARNING is more honest.
+ * - `install.ts` — `installStructuredLogging`, the public entry point.
+ * - `uncaught.ts` — logs one ERROR summary per crash: an
+ *   `uncaughtExceptionMonitor` for exceptions, a real listener for rejections.
+ *   Installed by `installStructuredLogging`, not exported.
+ *
+ * Mirrors `agent_engine_runner_shared/structured_logging.py`. `_unwrap_logging_stream` maps
+ * to the snapshot of the original `write` stashed on a `Symbol.for` slot on the
+ * stream itself, so re-installing routes the custom appender back to the *real*
+ * stdout instead of recursing through the patched write.
+ *
+ * Unlike the Python port we do not replace `process.stdout` itself — Node
+ * code probes `process.stdout.fd` / `.isTTY` / `.columns` aggressively and a
+ * full replacement breaks subprocess piping, tqdm-style progress bars, and
+ * grpc-internal logging. We only patch `write`, which is enough to capture
+ * every byte that would otherwise hit the console.
+ */
+export { MAX_TRACEBACK_BYTES, MAX_BUFFER_BYTES, } from "./structured_logging/constants.js";
+export { LoggingStream } from "./structured_logging/stdio_capture.js";
+export { installStructuredLogging, type InstallStructuredLoggingArgs, } from "./structured_logging/install.js";
+export { FALLBACK_EXIT_MS } from "./structured_logging/uncaught.js";
+//# sourceMappingURL=structured_logging.d.ts.map

package/dist/structured_logging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured_logging.d.ts","sourceRoot":"","sources":["../src/structured_logging.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,EACL,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,uCAAuC,CAAC;AACtE,OAAO,EACL,wBAAwB,EACxB,KAAK,4BAA4B,GAClC,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC"}

package/dist/structured_logging.js

@@ -0,0 +1,47 @@
+/**
+ * Structured JSON logging for the agent runtime log capture pipeline.
+ *
+ * Emits single-line JSON records on container stdout. Fluent Bit tails the
+ * container log, the Lua filter derives tenant/workspace keys from pod
+ * metadata, and writes gzipped batches to S3. The API Gateway
+ * `GET /admin/api/v1/agent-logs` endpoint reads them back.
+ *
+ * Activated by calling `installStructuredLogging()` at runner startup —
+ * typically gated by `STRUCTURED_LOGGING=true`. When inactive, the default
+ * log4js root in `logger.ts` is unaffected.
+ *
+ * This module is split into focused files under `structured_logging/`:
+ *
+ * - `constants.ts` — tunables and shared identifiers (service map, byte caps,
+ *   capture category, the `Symbol.for` write slot).
+ * - `env.ts` — the install-time env snapshot (`FormatterEnv`, `snapshotEnv`).
+ * - `serialize.ts` — the crash-proof `jsonSafeStringify` and UTF-8-aware
+ *   `truncateUtf8` helpers.
+ * - `layout.ts` — `buildStructuredLayout`, the log4js layout that renders the JSON
+ *   envelope (`StructuredJSONFormatter` in the Python port).
+ * - `stdio_capture.ts` — `LoggingStream` + `patchStdio`, which replace
+ *   `process.stdout.write` / `process.stderr.write` so stray `console.log` /
+ *   direct writes also emerge as structured-logging records tagged `source: "stdout"`
+ *   (INFO) or `"stderr"` (WARNING). Forcing stderr to ERROR was tried in
+ *   Python and backed out — every deprecation warning would have paged
+ *   on-call; WARNING is more honest.
+ * - `install.ts` — `installStructuredLogging`, the public entry point.
+ * - `uncaught.ts` — logs one ERROR summary per crash: an
+ *   `uncaughtExceptionMonitor` for exceptions, a real listener for rejections.
+ *   Installed by `installStructuredLogging`, not exported.
+ *
+ * Mirrors `agent_engine_runner_shared/structured_logging.py`. `_unwrap_logging_stream` maps
+ * to the snapshot of the original `write` stashed on a `Symbol.for` slot on the
+ * stream itself, so re-installing routes the custom appender back to the *real*
+ * stdout instead of recursing through the patched write.
+ *
+ * Unlike the Python port we do not replace `process.stdout` itself — Node
+ * code probes `process.stdout.fd` / `.isTTY` / `.columns` aggressively and a
+ * full replacement breaks subprocess piping, tqdm-style progress bars, and
+ * grpc-internal logging. We only patch `write`, which is enough to capture
+ * every byte that would otherwise hit the console.
+ */
+export { MAX_TRACEBACK_BYTES, MAX_BUFFER_BYTES, } from "./structured_logging/constants.js";
+export { LoggingStream } from "./structured_logging/stdio_capture.js";
+export { installStructuredLogging, } from "./structured_logging/install.js";
+export { FALLBACK_EXIT_MS } from "./structured_logging/uncaught.js";

package/dist/tls_client.d.ts

@@ -0,0 +1,61 @@
+/**
+ * TLS client configuration for HTTPS connections with mTLS support.
+ *
+ * This module provides utilities for configuring fetch requests with mTLS
+ * (mutual TLS) when connecting to platform services over HTTPS. When TLS
+ * certificate paths are available via environment variables, the client will
+ * present its certificate to the server for authentication.
+ *
+ * Uses Undici's Agent (Node.js built-in fetch is backed by Undici) for proper
+ * dispatcher configuration with client certificates.
+ */
+/** Carry the active trace across a platform RPC without recording transport. */
+export declare function fetchPlatform(url: string, init: RequestInit, fetchImpl?: typeof fetch): Promise<Response>;
+export declare const TLS_AGENT_CACHE_MAX_ENTRIES = 32;
+/**
+ * Get fetch options configured for the given URL with mTLS support.
+ *
+ * If url uses HTTPS and TLS certificate environment variables are set
+ * (TLS_CERT_PATH, TLS_KEY_PATH, TLS_CA_CERT_PATH), returns options with
+ * an HTTPS agent configured for mTLS. For HTTP URLs or when certificates
+ * are not available, returns undefined (use default fetch behavior).
+ *
+ * The HTTPS agent is cached per base URL for connection pooling.
+ *
+ * Performance: checks the agent cache BEFORE reading certificate files to avoid
+ * blocking the event loop on filesystem I/O for every request. Certificate files
+ * are only read once per base URL when creating the agent, not on every fetch.
+ *
+ * Certificate rotation: In container mode (TLS_*_PATH), automatically detects
+ * cert-manager rotation by comparing file mtimes and invalidates the cached agent
+ * so the next request picks up renewed certificates. In VM mode (TLS_*_PEM), the
+ * env vars are static for the pod's lifetime, so rotation requires a pod restart.
+ *
+ * @param url - The target service URL (http:// or https://)
+ * @returns Fetch options with agent, or undefined for HTTP/no-TLS
+ * @throws Error if HTTPS is used but TLS configuration is incomplete
+ */
+export declare function getFetchOptionsWithTLS(url: string): RequestInit | undefined;
+/**
+ * Cleanup function to close all cached Undici agents.
+ * Should be called during graceful shutdown.
+ */
+export declare function closeAllTLSAgents(): void;
+/**
+ * Fetch options for a call that may legitimately run for minutes.
+ *
+ * Node's fetch is backed by Undici, whose default `headersTimeout` of 300s
+ * applies *independently* of any AbortSignal the caller passes. Since the OE
+ * holds `/tool/execute` open until the tool returns, response headers do not
+ * arrive until then — so without raising it here, a longer per-call deadline is
+ * silently capped at 300s and surfaces as `UND_ERR_HEADERS_TIMEOUT` rather than
+ * as the caller's own timeout. The connect budget stays short and is set
+ * explicitly rather than inherited.
+ *
+ * Applies to http:// as well as https://, since the cap is Undici's, not TLS's.
+ *
+ * @param url - The target service URL
+ * @param deadlineMs - The call's own deadline; headers/body budgets match it
+ */
+export declare function getFetchOptionsForLongCall(url: string, deadlineMs: number): RequestInit;
+//# sourceMappingURL=tls_client.d.ts.map

package/dist/tls_client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tls_client.d.ts","sourceRoot":"","sources":["../src/tls_client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAcH,gFAAgF;AAChF,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,WAAW,EACjB,SAAS,GAAE,OAAO,KAAa,GAC9B,OAAO,CAAC,QAAQ,CAAC,CAcnB;AAUD,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAyH9C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAwG3E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAOxC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,GACjB,WAAW,CAuBb"}