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

package/dist/span_names.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Stable span names for the first-invoke lifecycle. There is no manual
+ * `llm.call` span; LangChain's auto-instrumentation already covers it.
+ */
+export declare const AER_BUILD_AGENT = "aer.build_agent";
+export declare const GRAPH_BUILD = "graph.build";
+export declare const MODEL_REQUEST_PREPARE = "request.prepare";
+export declare const MODEL_RESPONSE_PROCESS = "response.process";
+export declare const SKILLS_MIDDLEWARE_BEFORE_AGENT = "skills.middleware";
+export declare const ATTR_COLD_START = "cold_start";
+export declare const ATTR_CACHE_HIT = "cache_hit";
+export declare const ATTR_SKILLS_SOURCE_COUNT = "skills.source_count";
+export declare const ATTR_SKILLS_LOADED_COUNT = "skills.loaded_count";
+export declare const OPENINFERENCE_SPAN_KIND = "openinference.span.kind";
+/** OpenInference span kinds, matching the Python SDK's `OpenInferenceSpanKind`. */
+export declare const OpenInferenceSpanKind: {
+    readonly AGENT: "AGENT";
+    readonly CHAIN: "CHAIN";
+    readonly TOOL: "TOOL";
+};
+//# sourceMappingURL=span_names.d.ts.map

package/dist/span_names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"span_names.d.ts","sourceRoot":"","sources":["../src/span_names.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,eAAe,oBAAoB,CAAC;AACjD,eAAO,MAAM,WAAW,gBAAgB,CAAC;AAGzC,eAAO,MAAM,qBAAqB,oBAAoB,CAAC;AACvD,eAAO,MAAM,sBAAsB,qBAAqB,CAAC;AAMzD,eAAO,MAAM,8BAA8B,sBAAsB,CAAC;AAGlE,eAAO,MAAM,eAAe,eAAe,CAAC;AAC5C,eAAO,MAAM,cAAc,cAAc,CAAC;AAC1C,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAC9D,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAO9D,eAAO,MAAM,uBAAuB,4BAA4B,CAAC;AAEjE,mFAAmF;AACnF,eAAO,MAAM,qBAAqB;;;;CAIxB,CAAC"}

package/dist/span_names.js

@@ -0,0 +1,31 @@
+/**
+ * Stable span names for the first-invoke lifecycle. There is no manual
+ * `llm.call` span; LangChain's auto-instrumentation already covers it.
+ */
+export const AER_BUILD_AGENT = "aer.build_agent";
+export const GRAPH_BUILD = "graph.build";
+// Children of the existing LangChain auto-instrumented span.
+export const MODEL_REQUEST_PREPARE = "request.prepare";
+export const MODEL_RESPONSE_PROCESS = "response.process";
+// Wraps deepagents' createSkillsMiddleware beforeAgent hook as a single
+// span. Its list/download calls happen inside a third-party package, so
+// this attributes total time to the hook without inventing internal
+// phases that don't exist in code we own.
+export const SKILLS_MIDDLEWARE_BEFORE_AGENT = "skills.middleware";
+// Low-cardinality only; never prompts/completions/secrets.
+export const ATTR_COLD_START = "cold_start";
+export const ATTR_CACHE_HIT = "cache_hit";
+export const ATTR_SKILLS_SOURCE_COUNT = "skills.source_count";
+export const ATTR_SKILLS_LOADED_COUNT = "skills.loaded_count";
+// Not written as `export const X = "...";` directly: this repo's
+// no-LangChain-imports lint scans for quoted strings on `export`/`import`
+// lines as a proxy for import specifiers, and would misread this literal
+// as an OpenInference import.
+const openinferenceSpanKindAttr = "openinference.span.kind";
+export const OPENINFERENCE_SPAN_KIND = openinferenceSpanKindAttr;
+/** OpenInference span kinds, matching the Python SDK's `OpenInferenceSpanKind`. */
+export const OpenInferenceSpanKind = {
+    AGENT: "AGENT",
+    CHAIN: "CHAIN",
+    TOOL: "TOOL",
+};

package/dist/structured_logging/constants.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared constants for the structured-logging module.
+ */
+export declare const SERVICE_BY_MODE: Record<string, string>;
+/** @internal — exported only for tests; not part of the public API. */
+export declare const MAX_TRACEBACK_BYTES = 8192;
+/** @internal — exported only for tests; not part of the public API. */
+export declare const MAX_BUFFER_BYTES = 65536;
+export declare const DEFAULT_RECORD_SOURCE = "node-logging";
+export declare const STDIO_CAPTURE_CATEGORY = "agent_engine_runner_shared.stdio_capture";
+export declare const NOISY_LOGGER_NAMES: ReadonlyArray<string>;
+export declare const ORIGINAL_WRITE_SLOT: unique symbol;
+export declare const EXIT_FLUSH_REGISTERED: unique symbol;
+export declare const ACTIVE_CAPTURES: unique symbol;
+export declare const UNCAUGHT_HANDLERS_REGISTERED: unique symbol;
+export declare const ACTIVE_ROOT_LOGGER: unique symbol;
+//# sourceMappingURL=constants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/structured_logging/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAMlD,CAAC;AAKF,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAOxC,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,QAAQ,CAAC;AAOtC,eAAO,MAAM,qBAAqB,iBAAiB,CAAC;AAYpD,eAAO,MAAM,sBAAsB,6CACS,CAAC;AAI7C,eAAO,MAAM,kBAAkB,EAAE,aAAa,CAAC,MAAM,CAOpD,CAAC;AAOF,eAAO,MAAM,mBAAmB,eAE/B,CAAC;AAIF,eAAO,MAAM,qBAAqB,eAEjC,CAAC;AAOF,eAAO,MAAM,eAAe,eAE3B,CAAC;AAIF,eAAO,MAAM,4BAA4B,eAExC,CAAC;AAIF,eAAO,MAAM,kBAAkB,eAE9B,CAAC"}

package/dist/structured_logging/constants.js

@@ -0,0 +1,71 @@
+/**
+ * Shared constants for the structured-logging module.
+ */
+// Map RUNNER_MODE values to the canonical service identifier on the log line.
+export const SERVICE_BY_MODE = {
+    orchestrator: "orchestration-engine",
+    aer: "agent-execution-runtime",
+    tool: "tool-executor",
+    tool_function: "tool-executor",
+    "memory-server": "memory-server",
+};
+// Truncation for the formatted stack embedded in fields.exc_traceback.
+// Long traces explode the JSON line size and choke Fluent Bit's batch
+// pipeline; 8 KiB is enough to retain the call site and outer frames.
+/** @internal — exported only for tests; not part of the public API. */
+export const MAX_TRACEBACK_BYTES = 8192;
+// Cap on LoggingStream's per-stream pending buffer. A library that writes a
+// huge payload without `\n` (binary blob accidentally hitting stdout, a
+// multi-MB stack from a native module, a misbehaving progress-bar lib)
+// would otherwise grow the buffer until process OOM. 64 KiB is well above
+// any reasonable log line and far below a runaway producer.
+/** @internal — exported only for tests; not part of the public API. */
+export const MAX_BUFFER_BYTES = 65536;
+// Source value attached to log records by LoggingStream. For records that
+// come straight from `logger.*` (i.e. not stdout/stderr capture) we default
+// to `node-logging`. Mirrors the Python `_RECORD_SOURCE_ATTR` /
+// `_DEFAULT_RECORD_SOURCE` constants; the value travels on the `source`
+// field of the extras object passed to `logger.info({source}, msg)`.
+export const DEFAULT_RECORD_SOURCE = "node-logging";
+// Dedicated log4js category for stdout/stderr capture. Pinned to `trace` in
+// the configuration (see install.ts) so captured records emerge regardless of
+// the operator-set `LOG_LEVEL`. Python achieves the same effect by calling
+// `Logger.handle(record)` from its `LoggingStream._emit` — which bypasses
+// `isEnabledFor` (structured_logging.py:269-280 + 347-350 comment). log4js
+// has no per-call bypass, but it does have per-category levels, so we route
+// captures through a separate category whose level is held below the lowest
+// LoggingStream emit level (info). Result: a stray `console.log` still ships
+// as a JSON record even when an operator flips `LOG_LEVEL=ERROR` to chase an
+// issue — same property Python guarantees.
+export const STDIO_CAPTURE_CATEGORY = "agent_engine_runner_shared.stdio_capture";
+// Mirrors Python's `for noisy in ("httpx", "httpcore", "urllib3")` silencing
+// block. Node-native names kept too.
+export const NOISY_LOGGER_NAMES = [
+    "undici",
+    "fastify.access",
+    "httpx",
+    "httpcore",
+    "urllib3",
+    "uvicorn.access",
+];
+// Symbol slot used to stash the original `write` function on
+// `process.stdout` / `process.stderr` before we patch them. `Symbol.for`
+// shares the slot across module instances, so a double-install (or a tester
+// reloading the module) finds the prior snapshot instead of wrapping the
+// already-patched write — which would recurse to RangeError.
+export const ORIGINAL_WRITE_SLOT = Symbol.for("agent_engine_runner_shared.original_write");
+// Guard so the process-exit buffer-flush handler is registered only once per
+// process, even across re-installs / a module reload (see patchStdio).
+export const EXIT_FLUSH_REGISTERED = Symbol.for("agent_engine_runner_shared.structured_logging_exit_flush");
+// Slot holding the currently-installed capture streams. The exit handler is
+// registered once and reads this slot at exit time (rather than closing over
+// the first install's streams), so a re-install's trailing buffer is the one
+// that gets flushed. Shared across module reloads via `Symbol.for`, matching
+// the one-shot exit handler it feeds.
+export const ACTIVE_CAPTURES = Symbol.for("agent_engine_runner_shared.structured_logging_active_captures");
+// Registers the crash listeners once — `process.on` is additive, so a repeat
+// install would log the same crash twice.
+export const UNCAUGHT_HANDLERS_REGISTERED = Symbol.for("agent_engine_runner_shared.structured_logging_uncaught_handlers_registered");
+// Read by those listeners at fire time, so a re-install logs through the
+// current logger rather than the first install's.
+export const ACTIVE_ROOT_LOGGER = Symbol.for("agent_engine_runner_shared.structured_logging_active_root_logger");

package/dist/structured_logging/env.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Install-time snapshot of the pod/runner environment that decorates every
+ * structured-logging record (service, component, tenant/project, pod name).
+ */
+export declare function envOrNull(name: string): string | null;
+export declare function serviceFor(mode: string | null): string;
+export declare function resolveLevel(level?: string | null): string;
+export interface FormatterEnv {
+    service: string;
+    component: string;
+    tenantId: string | null;
+    projectId: string | null;
+    workspaceIdEnv: string | null;
+    bootId: string | null;
+    podName: string | null;
+}
+export declare function snapshotEnv(mode: string | null): FormatterEnv;
+//# sourceMappingURL=env.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/structured_logging/env.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGrD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAGtD;AAED,wBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAE1D;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,YAAY,CAqB7D"}

package/dist/structured_logging/env.js

@@ -0,0 +1,39 @@
+/**
+ * Install-time snapshot of the pod/runner environment that decorates every
+ * structured-logging record (service, component, tenant/project, pod name).
+ */
+import { SERVICE_BY_MODE } from "./constants.js";
+export function envOrNull(name) {
+    const v = process.env[name];
+    return v && v.length > 0 ? v : null;
+}
+export function serviceFor(mode) {
+    if (!mode)
+        return "agent-execution-runtime";
+    return SERVICE_BY_MODE[mode.toLowerCase()] ?? mode.toLowerCase();
+}
+export function resolveLevel(level) {
+    return (level ?? envOrNull("LOG_LEVEL") ?? "info").toLowerCase();
+}
+export function snapshotEnv(mode) {
+    // Env vars (RUNNER_MODE, ORG_ID, PROJECT_ID, WORKSPACE_ID, AGENTIC_BOOT_ID,
+    // POD_NAME) are snapshotted here at install time, not re-read per record —
+    // every log event goes through the layout and re-resolving env on each call
+    // would noticeably load the hot path. Callers must ensure the pod env is
+    // set before `installStructuredLogging()` runs; if the install runs before
+    // the entrypoint stamps env, the layout caches stale (or missing) values for
+    // the process lifetime. The `mode` arg lets callers override
+    // RUNNER_MODE explicitly — useful when the pod env happens to be unset
+    // but the caller knows its mode (e.g. `setupLogging` passes its `mode=`
+    // arg through).
+    const resolvedMode = mode ?? envOrNull("RUNNER_MODE");
+    return {
+        service: serviceFor(resolvedMode),
+        component: (resolvedMode ?? "agent").toLowerCase(),
+        tenantId: envOrNull("ORG_ID"),
+        projectId: envOrNull("PROJECT_ID"),
+        workspaceIdEnv: envOrNull("WORKSPACE_ID"),
+        bootId: envOrNull("AGENTIC_BOOT_ID"),
+        podName: envOrNull("POD_NAME") ?? envOrNull("HOSTNAME"),
+    };
+}

package/dist/structured_logging/install.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Public entry point: `installStructuredLogging()` wires the structured-logging layout
+ * into log4js as a custom appender, silences noisy HTTP loggers, and (unless
+ * disabled) patches stdout/stderr capture.
+ */
+import { type Logger } from "log4js";
+export interface InstallStructuredLoggingArgs {
+    /**
+     * Log level — string name (`"DEBUG"`, `"info"`). Defaults to `LOG_LEVEL`
+     * env var, then INFO. Must be honored on rollout because operators
+     * continue to flip `LOG_LEVEL=DEBUG` to chase issues.
+     */
+    level?: string | null;
+    /**
+     * Runner mode (`"orchestrator"`, `"aer"`, `"tool"`, `"memory-server"`)
+     * used to derive `service` and `fields.component` on the wire. Takes
+     * precedence over `RUNNER_MODE` env var when set; falls back to env
+     * when `null`. Lets `setupLogging(mode=...)` callers stay authoritative
+     * even if pod env hasn't been stamped.
+     */
+    mode?: string | null;
+    /**
+     * Set to `false` to skip `process.stdout` / `process.stderr` patching.
+     * Useful in tests that share a Node process across cases, or in callers
+     * that own their own stdio routing. Defaults to `true` (matches Python).
+     */
+    captureStdio?: boolean;
+    /**
+     * Absolute path for a dev-mode `dateFile` appender alongside the
+     * structured stdout appender. When set, a second log4js appender writes
+     * human-readable records to this path, rotating daily and keeping the
+     * last 5 files (Python `TimedRotatingFileHandler` parity). Only used by
+     * `setupLogging` when `AGENTIC_DEV_MODES` is set; left unset in
+     * production, where Fluent Bit is the only sink.
+     */
+    fileLogPath?: string | null;
+}
+/**
+ * Install structured logging on the log4js root.
+ *
+ * Behaves like the Python SDK's `install_structured_logging`:
+ *
+ * - Idempotent: re-installing routes the appender through the snapshotted
+ *   original `stdout.write` (stashed under `ORIGINAL_WRITE_SLOT`), so it
+ *   keeps writing to the real stdout instead of recursing through a
+ *   patched write.
+ * - Silences noisy HTTP libraries (see `NOISY_LOGGER_NAMES`) — equivalent
+ *   to Python's `logging.getLogger("httpx").setLevel(WARNING)` block.
+ * - Patches `process.stdout.write` / `process.stderr.write` (unless
+ *   `captureStdio: false`) so stray writes emerge as structured-logging records
+ *   tagged with `source: "stdout"` (INFO) or `source: "stderr"` (WARNING).
+ *   stderr was deliberately *not* mapped to ERROR — Python had to back that
+ *   out because every deprecation warning would have paged on-call.
+ */
+export declare function installStructuredLogging(args?: InstallStructuredLoggingArgs): Logger;
+//# sourceMappingURL=install.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/structured_logging/install.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAe,EAEb,KAAK,MAAM,EAEZ,MAAM,QAAQ,CAAC;AAwBhB,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,GAAE,4BAAiC,GACtC,MAAM,CA0ER"}

package/dist/structured_logging/install.js

@@ -0,0 +1,107 @@
+/**
+ * Public entry point: `installStructuredLogging()` wires the structured-logging layout
+ * into log4js as a custom appender, silences noisy HTTP loggers, and (unless
+ * disabled) patches stdout/stderr capture.
+ */
+import log4js from "log4js";
+import { markConfigured } from "../logger.js";
+import { NOISY_LOGGER_NAMES, STDIO_CAPTURE_CATEGORY } from "./constants.js";
+import { resolveLevel, snapshotEnv } from "./env.js";
+import { buildStructuredLayout } from "./layout.js";
+import { patchStdio, snapshotOriginalWrite } from "./stdio_capture.js";
+import { installUncaughtExceptionHandlers } from "./uncaught.js";
+// Custom log4js appender — writes via the snapshotted original stdout write so
+// it doesn't recurse through our patched `process.stdout.write`.
+function buildAppenderModule(layout) {
+    return {
+        configure: () => {
+            const originalWrite = snapshotOriginalWrite(process.stdout);
+            return (event) => {
+                originalWrite(layout(event) + "\n");
+            };
+        },
+    };
+}
+/**
+ * Install structured logging on the log4js root.
+ *
+ * Behaves like the Python SDK's `install_structured_logging`:
+ *
+ * - Idempotent: re-installing routes the appender through the snapshotted
+ *   original `stdout.write` (stashed under `ORIGINAL_WRITE_SLOT`), so it
+ *   keeps writing to the real stdout instead of recursing through a
+ *   patched write.
+ * - Silences noisy HTTP libraries (see `NOISY_LOGGER_NAMES`) — equivalent
+ *   to Python's `logging.getLogger("httpx").setLevel(WARNING)` block.
+ * - Patches `process.stdout.write` / `process.stderr.write` (unless
+ *   `captureStdio: false`) so stray writes emerge as structured-logging records
+ *   tagged with `source: "stdout"` (INFO) or `source: "stderr"` (WARNING).
+ *   stderr was deliberately *not* mapped to ERROR — Python had to back that
+ *   out because every deprecation warning would have paged on-call.
+ */
+export function installStructuredLogging(args = {}) {
+    const env = snapshotEnv(args.mode ?? null);
+    const level = resolveLevel(args.level);
+    const layout = buildStructuredLayout(env);
+    const appenderModule = buildAppenderModule(layout);
+    // `enableCallStack: true` makes log4js attach `fileName`/`lineNumber`/
+    // `functionName` to each LoggingEvent — required for the layout to emit
+    // `fields.filename` / `fields.lineno` / `fields.funcName` for logger-
+    // sourced records (Python parity, see layout above). It's set per-
+    // category in log4js (no global toggle), so enable on every category we
+    // configure including the noisy ones — a noisy library that does fire a
+    // WARN is exactly the case where the call site is useful to keep.
+    const noisyCategories = Object.fromEntries(NOISY_LOGGER_NAMES.map((name) => [
+        name,
+        { appenders: ["structured"], level: "warn", enableCallStack: true },
+    ]));
+    const appenders = {
+        // log4js accepts an inline module object for `type` — its `configure`
+        // function is invoked once at `log4js.configure(...)` time and
+        // returns the appender function used for every record.
+        structured: { type: appenderModule },
+    };
+    if (args.fileLogPath) {
+        appenders.devFile = {
+            type: "dateFile",
+            filename: args.fileLogPath,
+            layout: {
+                type: "pattern",
+                pattern: "%d{yyyy-MM-dd hh:mm:ss} | %p | %c | %m",
+            },
+            // Daily rotation, 5 kept files — Python TimedRotatingFileHandler parity.
+            pattern: "yyyy-MM-dd",
+            numToKeep: 5,
+            keepFileExt: true,
+        };
+    }
+    const defaultAppenders = args.fileLogPath
+        ? ["structured", "devFile"]
+        : ["structured"];
+    const config = {
+        appenders,
+        categories: {
+            default: { appenders: defaultAppenders, level, enableCallStack: true },
+            // Stdio capture category pinned to `trace` so emits never get
+            // filtered by the operator-set `LOG_LEVEL`. Mirrors Python's
+            // `Logger.handle()` bypass; see STDIO_CAPTURE_CATEGORY comment.
+            // `enableCallStack` deliberately off — the call site for a captured
+            // line is always `LoggingStream.emit`, which is noise, and the
+            // layout already suppresses fields.filename/lineno/funcName when
+            // source !== DEFAULT_RECORD_SOURCE.
+            [STDIO_CAPTURE_CATEGORY]: { appenders: defaultAppenders, level: "trace" },
+            ...noisyCategories,
+        },
+    };
+    log4js.configure(config);
+    // Keep `logger.ts` state in sync: a later `getLogger()` must not re-run
+    // `ensureDefaultConfig()` and replace this structured-logging config with the human
+    // stdout appender (which would also re-`configure` over patched stdio).
+    markConfigured();
+    const rootLogger = log4js.getLogger();
+    if (args.captureStdio !== false)
+        patchStdio();
+    installUncaughtExceptionHandlers(rootLogger);
+    rootLogger.debug({ source: "node-logging" }, "structured logging installed");
+    return rootLogger;
+}

package/dist/structured_logging/layout.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The structured-logging layout: turns a `LoggingEvent` into the single-line JSON
+ * envelope (timestamp, level, logger, message, service, tenant/project/
+ * workspace/execution/session ids, pod, source, fields).
+ */
+import type { LoggingEvent } from "log4js";
+import type { FormatterEnv } from "./env.js";
+export declare function buildStructuredLayout(env: FormatterEnv): (event: LoggingEvent) => string;
+//# sourceMappingURL=layout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../src/structured_logging/layout.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAU3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAuE7C,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,YAAY,GAChB,CAAC,KAAK,EAAE,YAAY,KAAK,MAAM,CA+EjC"}

package/dist/structured_logging/layout.js

@@ -0,0 +1,144 @@
+/**
+ * The structured-logging layout: turns a `LoggingEvent` into the single-line JSON
+ * envelope (timestamp, level, logger, message, service, tenant/project/
+ * workspace/execution/session ids, pod, source, fields).
+ */
+import { basename } from "node:path";
+import { getCurrentExecutionId, getCurrentLogOrigin, getCurrentTraceId, getCurrentSessionId, getCurrentWorkspaceId, } from "../context.js";
+import { DEFAULT_RECORD_SOURCE, MAX_TRACEBACK_BYTES } from "./constants.js";
+import { jsonSafeStringify, truncateUtf8 } from "./serialize.js";
+// log4js spells some levels differently from Python's stdlib `logging`
+// (WARN vs WARNING, FATAL vs CRITICAL, TRACE has no stdlib peer). The Splunk
+// dashboards and the playground UI logs tab were built against the Python
+// SDK's level strings, so normalize log4js names to the stdlib names here —
+// otherwise a TypeScript agent's warnings would ship as `"WARN"` and miss a
+// `level=WARNING` filter / render inconsistently next to Python agents.
+const LEVEL_NAME_BY_LOG4JS = {
+    WARN: "WARNING",
+    FATAL: "CRITICAL",
+    TRACE: "DEBUG",
+};
+function normalizeLevelName(levelStr) {
+    return LEVEL_NAME_BY_LOG4JS[levelStr] ?? levelStr;
+}
+/**
+ * Split log4js's `event.data` into a message string, an `extra` field bag,
+ * and an optional `Error`. Matches the common call shape used in this
+ * codebase: `logger.info({...extra}, "message")`. If no leading object is
+ * present, all args are stringified and joined.
+ */
+function parseEventData(data) {
+    let extra = {};
+    let parts = data;
+    let err;
+    const first = data[0];
+    if (first &&
+        typeof first === "object" &&
+        !(first instanceof Error) &&
+        !Array.isArray(first)) {
+        extra = { ...first };
+        parts = data.slice(1);
+    }
+    else if (first instanceof Error) {
+        err = first;
+        parts = data.slice(1);
+    }
+    const extraErr = extra["err"];
+    if (extraErr instanceof Error) {
+        err = extraErr;
+        delete extra["err"];
+    }
+    const message = parts
+        .map((p) => {
+        if (typeof p === "string")
+            return p;
+        // Use the cycle/BigInt-safe serializer — a BigInt or circular value in a
+        // non-leading message arg must not throw and take down the log line.
+        try {
+            return jsonSafeStringify(p) ?? String(p);
+        }
+        catch {
+            return String(p);
+        }
+    })
+        .join(" ");
+    return { message, extra, err };
+}
+export function buildStructuredLayout(env) {
+    // Tenant context is read from the AsyncLocalStorage contextvars in
+    // `context.ts` at layout time so records emitted from inside an
+    // execution carry executionId/sessionId automatically; records emitted
+    // outside an execution (startup, idle) leave those fields `null`.
+    return (event) => {
+        const { message, extra, err } = parseEventData(event.data);
+        // Intentional divergence from the Python formatter: structured_logging.py
+        // ignores `extra=` kwargs on `logger.info(...)`, so Python callers have
+        // no way to attach structured key/value pairs to `fields`. log4js's
+        // idiomatic call shape *is* `logger.info({...extra}, "msg")`, so we
+        // spread the first-arg object into `fields` and let TS callers do what
+        // Python callers cannot. The `source` key is special-cased below and
+        // stripped from `fields` so it never appears twice on the wire.
+        const fields = {
+            component: env.component,
+            ...extra,
+        };
+        if (err) {
+            // Capture the formatted stack so on-call can debug from the
+            // archived JSON without reproducing. Truncated to keep S3 batch
+            // sizes manageable; truncation is marked so consumers know the
+            // tail was cut.
+            fields["exc_type"] = err.name;
+            fields["exc_message"] = err.message;
+            if (err.stack)
+                fields["exc_traceback"] = truncateUtf8(err.stack, MAX_TRACEBACK_BYTES);
+        }
+        const source = typeof extra["source"] === "string"
+            ? extra["source"]
+            : DEFAULT_RECORD_SOURCE;
+        delete fields["source"];
+        // Match Python's `record.filename` / `record.lineno` / `record.funcName`
+        // (structured_logging.py:125-128): include caller-site info only for
+        // logger-emitted records, not for stdout/stderr capture lines whose
+        // call site is the producer that wrote to the stream — meaningless for
+        // debugging. log4js populates these on LoggingEvent only when
+        // `enableCallStack: true` is set on the category (done in the
+        // configuration below); generating a stack trace per record is not free
+        // but the volume is bounded by LOG_LEVEL filtering on the default
+        // category, which keeps the cost acceptable in the steady state.
+        if (source === DEFAULT_RECORD_SOURCE) {
+            if (event.fileName)
+                // Python's `LogRecord.filename` is the basename, not the full path.
+                // log4js returns the absolute path (or a `file://` URL under ESM);
+                // `basename` handles both string forms.
+                fields["filename"] = basename(event.fileName);
+            if (typeof event.lineNumber === "number")
+                fields["lineno"] = event.lineNumber;
+            if (event.functionName)
+                fields["funcName"] = event.functionName;
+        }
+        const origin = getCurrentLogOrigin();
+        const traceId = getCurrentTraceId();
+        return jsonSafeStringify({
+            timestamp: event.startTime.toISOString(),
+            level: normalizeLevelName(event.level.levelStr),
+            logger: event.categoryName,
+            message,
+            service: env.service,
+            tenantId: env.tenantId,
+            projectId: env.projectId,
+            workspaceId: getCurrentWorkspaceId() ?? env.workspaceIdEnv,
+            executionId: getCurrentExecutionId(),
+            sessionId: getCurrentSessionId(),
+            bootId: env.bootId,
+            podName: env.podName,
+            source,
+            fields,
+            ...(origin !== null ? { origin } : {}),
+            ...(traceId &&
+                /^[0-9a-f]{32}$/.test(traceId) &&
+                traceId !== "0".repeat(32)
+                ? { traceId }
+                : {}),
+        });
+    };
+}

package/dist/structured_logging/serialize.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Serialization helpers shared by the layout and the stdout-capture stream:
+ * a crash-proof JSON stringifier and a UTF-8-aware truncator.
+ */
+/**
+ * Stringify the structured-logging envelope with the same robustness Python gets from
+ * `json.dumps(entry, default=str)`. Two failure modes the bare
+ * `JSON.stringify` would otherwise expose:
+ *
+ *   - `TypeError: Do not know how to serialize a BigInt` — any extras
+ *     value that happens to be a BigInt (e.g. nanosecond timings,
+ *     64-bit IDs) crashes the appender for the whole record.
+ *   - `TypeError: Converting circular structure to JSON` — a caller
+ *     accidentally passes a node from a graph (Error.cause chains in
+ *     newer Node, langgraph state) and takes down logging for that line.
+ *
+ * The replacer coerces BigInt to a decimal string and replaces objects that
+ * are their own ancestor (a true reference cycle) with the sentinel
+ * `"[Circular]"`. Tracking the ancestor chain rather than a flat seen-set
+ * means a DAG — the same object referenced from multiple siblings, e.g. an
+ * array of identical items — serializes in full instead of being falsely
+ * truncated to `"[Circular]"`. A fresh `ancestors` stack per call means
+ * independent records can't poison each other.
+ */
+export declare function jsonSafeStringify(value: unknown): string;
+export declare function truncateUtf8(text: string, maxBytes: number): string;
+//# sourceMappingURL=serialize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../src/structured_logging/serialize.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAcxD;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAgBnE"}

package/dist/structured_logging/serialize.js

@@ -0,0 +1,61 @@
+/**
+ * Serialization helpers shared by the layout and the stdout-capture stream:
+ * a crash-proof JSON stringifier and a UTF-8-aware truncator.
+ */
+/**
+ * Stringify the structured-logging envelope with the same robustness Python gets from
+ * `json.dumps(entry, default=str)`. Two failure modes the bare
+ * `JSON.stringify` would otherwise expose:
+ *
+ *   - `TypeError: Do not know how to serialize a BigInt` — any extras
+ *     value that happens to be a BigInt (e.g. nanosecond timings,
+ *     64-bit IDs) crashes the appender for the whole record.
+ *   - `TypeError: Converting circular structure to JSON` — a caller
+ *     accidentally passes a node from a graph (Error.cause chains in
+ *     newer Node, langgraph state) and takes down logging for that line.
+ *
+ * The replacer coerces BigInt to a decimal string and replaces objects that
+ * are their own ancestor (a true reference cycle) with the sentinel
+ * `"[Circular]"`. Tracking the ancestor chain rather than a flat seen-set
+ * means a DAG — the same object referenced from multiple siblings, e.g. an
+ * array of identical items — serializes in full instead of being falsely
+ * truncated to `"[Circular]"`. A fresh `ancestors` stack per call means
+ * independent records can't poison each other.
+ */
+export function jsonSafeStringify(value) {
+    const ancestors = [];
+    return JSON.stringify(value, function (_key, v) {
+        if (typeof v === "bigint")
+            return v.toString();
+        if (typeof v !== "object" || v === null)
+            return v;
+        // `this` is the object `v` was reached through. Unwind ancestors that are
+        // no longer on the path to `v` so only genuine back-references remain.
+        while (ancestors.length > 0 && ancestors[ancestors.length - 1] !== this) {
+            ancestors.pop();
+        }
+        if (ancestors.includes(v))
+            return "[Circular]";
+        ancestors.push(v);
+        return v;
+    });
+}
+export function truncateUtf8(text, maxBytes) {
+    // Encode to bytes for the size check so the budget reflects what Fluent
+    // Bit actually ships — slicing the string by char count would let a
+    // non-ASCII traceback blow past the limit. Walk back from `maxBytes` to
+    // the last UTF-8 sequence boundary before decoding: Node's
+    // `Buffer.toString("utf-8")` REPLACES a partial sequence at the cut
+    // point with U+FFFD (3 bytes each), which would expand the result past
+    // the budget. Walking back over continuation bytes (`10xxxxxx`,
+    // i.e. `byte & 0xc0 === 0x80`) drops the partial sequence so the
+    // decoded body is strictly `<= maxBytes`. Mirrors Python's
+    // `errors="ignore"` decode at structured_logging.py:146.
+    const buf = Buffer.from(text, "utf-8");
+    if (buf.length <= maxBytes)
+        return text;
+    let cut = maxBytes;
+    while (cut > 0 && ((buf[cut] ?? 0) & 0xc0) === 0x80)
+        cut--;
+    return buf.subarray(0, cut).toString("utf-8") + "...(truncated)";
+}