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

package/dist/tracing/setup.js

@@ -0,0 +1,436 @@
+/**
+ * Tracing setup for Runner SDK.
+ *
+ * Ported from `agent_engine_runner_shared/tracing/setup.py`. Initializes OpenTelemetry
+ * with `BasicTracerProvider` and optionally a Mongo exporter. Calls the
+ * framework instrumentor hook
+ * registered via `agent_engine_runner_shared/hooks.ts:registerInstrumentor`.
+ */
+import { isSpanContextValid, propagation, trace } from "@opentelemetry/api";
+import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { BasicTracerProvider, BatchSpanProcessor, } from "@opentelemetry/sdk-trace-base";
+import { getCurrentExecutionId, getCurrentSessionId, getCurrentWorkspaceId, } from "../context.js";
+import { getInstrumentor } from "../hooks.js";
+import { getLogger } from "../logger.js";
+import { ContentPolicyOTLPSpanExporter, getContentCaptureMode, MongoDBSpanExporter, } from "./exporters.js";
+const logger = getLogger("agent_engine_runner_shared.tracing");
+let tracerProvider = null;
+// MongoClient instance built by `resolveTracingCollection`. Held here so
+// `shutdownTracing` can close the pool — `MongoDBSpanExporter.shutdown()`
+// is a no-op, so without this reference the client (and its connection
+// pool, monitor threads, heartbeat intervals) would leak until process exit.
+let tracingMongoClient = null;
+// In-flight initialization promise. `setupTracing` sets `tracerProvider` late
+// (after awaiting dynamic imports + the MongoClient connect), so the entry
+// guard alone can't stop concurrent callers from both running full setup —
+// which would open two Mongo clients and leak the first when the second
+// overwrites `tracingMongoClient`. Sharing this promise serializes them.
+let setupPromise = null;
+// MongoDB trace-store exporter state — mirrors Python's setup.py. The store
+// connection can fail at pod startup (e.g. a transient Atlas TLS error); without
+// retry the pod permanently lost database tracing for its whole lifetime.
+// `mongodbExporterAttached` tracks whether a MongoDB span processor
+// is live; `mongodbDegraded` marks a configured-but-unreachable store so /health
+// can surface DEGRADED. The retry timer re-attempts the connection in the
+// background and attaches the exporter on recovery.
+let mongodbExporterAttached = false;
+let mongodbDegraded = false;
+let retryTimer = null;
+// Stop signal for the background retry loop, mirroring Python's
+// `_retry_stop_event`. `shutdownTracing` sets this so an in-flight retry
+// attempt (past `retryTimer = null`, mid-`await resolveTracingCollection`)
+// can't reschedule a new timer or overwrite `tracingMongoClient` with a
+// client whose pool shutdown already closed — both would leak past shutdown.
+let retryStopped = false;
+// The lazy Mongo exporter registered with the tracer provider at setup time
+// when a store URI is configured. `BasicTracerProvider` (v2.x) takes span
+// processors only via its constructor — there is no `addSpanProcessor`, and
+// `setGlobalTracerProvider` rejects re-registration — so the provider is built
+// once with the lazy Mongo processor and the collection is wired in later by
+// `attachMongoTracing` once the store recovers. While the collection
+// is unset, `export` is a no-op.
+let lazyMongoExporter = null;
+class ExecutionContextSpanProcessor {
+    onStart(span, _parentContext) {
+        const sessionId = getCurrentSessionId();
+        const attributes = {
+            "execution.id": getCurrentExecutionId(),
+            "session.id": sessionId,
+            "thread.id": sessionId,
+            "workspace.id": getCurrentWorkspaceId(),
+        };
+        for (const [key, value] of Object.entries(attributes)) {
+            if (value)
+                span.setAttribute(key, value);
+        }
+    }
+    onEnd(_span) { }
+    shutdown() {
+        return Promise.resolve();
+    }
+    forceFlush() {
+        return Promise.resolve();
+    }
+}
+/** A SpanExporter whose Mongo collection is wired in after construction. */
+class LazyMongoSpanExporter {
+    inner = null;
+    setCollection(collection) {
+        this.inner = new MongoDBSpanExporter(collection);
+    }
+    export(spans, resultCallback) {
+        if (this.inner === null || spans.length === 0) {
+            resultCallback({ code: 0 });
+            return;
+        }
+        this.inner.export(spans, resultCallback);
+    }
+    shutdown() {
+        return this.inner?.shutdown() ?? Promise.resolve();
+    }
+    forceFlush() {
+        return this.inner?.forceFlush() ?? Promise.resolve();
+    }
+}
+async function resolveTracingCollection(args) {
+    if (!args.mongodbUri) {
+        return { collection: null, errorMessage: null };
+    }
+    const collName = args.mongodbCollectionName ?? "traces";
+    let client;
+    try {
+        const { MongoClient } = await import("mongodb");
+        client = new MongoClient(args.mongodbUri, {
+            serverSelectionTimeoutMS: 5000,
+        });
+        await client.connect();
+        // Mirrors Python's `client.admin.command("ping")` — surfaces a dead
+        // server immediately rather than waiting for the first span insert.
+        await client.db("admin").command({ ping: 1 });
+        // Resolve the per-project-scoped store DB now that a client exists, so
+        // traces land in the same database the OE reads.
+        const { resolveStoreDbName } = await import("../db_config.js");
+        const dbName = await resolveStoreDbName(client, args.mongodbDatabaseName ?? undefined);
+        // Retain the client so `shutdownTracing` can close it.
+        tracingMongoClient = client;
+        return {
+            collection: client.db(dbName).collection(collName),
+            errorMessage: null,
+        };
+    }
+    catch (err) {
+        // Close on failure so a half-open client doesn't leak. `connect()` may
+        // not have completed, but `close()` is safe to call on a never-connected
+        // client per the driver docs. The scrubbed error message is returned for
+        // the caller to log at the severity it chooses (ERROR at startup, DEBUG
+        // on retries) — this function stays log-free so retries don't spam.
+        if (client !== undefined) {
+            try {
+                await client.close();
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
+        return {
+            collection: null,
+            errorMessage: scrubCredentials(err.message),
+        };
+    }
+}
+/**
+ * Mask the userinfo of any `mongodb://` / `mongodb+srv://` URI embedded in a
+ * credential-bearing error message (driver parse/connect errors echo the raw
+ * connection string).
+ *
+ * The userinfo run is GREEDY up to the LAST '@' that a host-shaped token
+ * follows, so passwords containing an unescaped '@', space, or '/' are still
+ * fully masked — the old `:\/\/[^@\s]+@` pattern stopped at the first '@' and
+ * could not cross whitespace, leaking the password tail (or the whole
+ * userinfo) to the centralized log sink. The run is tempered so it never
+ * crosses into a second URI's scheme; when message text after the URI
+ * contains its own '@' the mask may extend to it — over-redaction is the
+ * fail-closed direction, a leak is not recoverable. Keep in sync with
+ * `scrub_credentials` in Python's `agent_engine_runner_shared/tracing/setup.py`.
+ *
+ * Accepts `unknown` and coerces: error paths hand this whatever a rejection
+ * carried (string throws, objects without a string `message`, undefined) —
+ * it must never throw itself, or a degraded trace store turns into a
+ * startup failure.
+ */
+export function scrubCredentials(message) {
+    // The run is [^"'] (any char except quotes): it still crosses embedded
+    // newlines in a password (a --stdin-set secret can carry one), but stops
+    // at a JSON string boundary — a credential echoed inside a compact JSON
+    // body must not fold later siblings into the mask.
+    return String(message).replace(/(mongodb(?:\+srv)?:\/\/)((?:(?!mongodb(?:\+srv)?:\/\/)[^"'])*)@(?=[^\s@/?#"'][^\s@?"']*(?:[/?#:\s"']|$))/gi, "$1***@");
+}
+/**
+ * Whether an OTLP endpoint was explicitly configured.
+ *
+ * `OTLPTraceExporter` defaults to `http://localhost:4318` when no endpoint
+ * env var is set, which would silently start exporting to a collector that
+ * doesn't exist in this cell architecture. Gate on explicit configuration so
+ * "no endpoint configured" truly means "no OTLP traffic." Mirrors Python's
+ * `_otlp_endpoint_configured`.
+ */
+function otlpEndpointConfigured() {
+    return Boolean(process.env["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"] ||
+        process.env["OTEL_EXPORTER_OTLP_ENDPOINT"]);
+}
+/**
+ * Upper bound (ms) on how long a `TenantRuntime.shutdown()` flush can spend
+ * waiting on the OTLP exporter. `TOOL_FUNCTION` mode calls `shutdown()`
+ * synchronously on every invocation (its process-exit flush timer is
+ * unref'd and would otherwise never fire), so an unreachable/slow collector
+ * would otherwise add up to the OTel default export timeout (10s) of tail
+ * latency to *every* one-shot invocation. Deliberately short relative to
+ * that default.
+ */
+const OTLP_EXPORT_TIMEOUT_MILLIS = 3000;
+/**
+ * Build the OTLP export span processor, if an endpoint was explicitly
+ * configured. Additive and never replaces Mongo. Content-capture redaction
+ * (`AGENTIC_PLATFORM_OTEL_CONTENT_CAPTURE`) applies only to this path.
+ * Guarded: a missing dependency or bad endpoint must not take down tracing
+ * setup entirely — mirrors Python's try/except around the same block.
+ */
+async function buildOtlpSpanProcessor() {
+    if (!otlpEndpointConfigured())
+        return null;
+    try {
+        const { OTLPTraceExporter } = await import("@opentelemetry/exporter-trace-otlp-http");
+        const contentCaptureMode = getContentCaptureMode();
+        if (contentCaptureMode === "full") {
+            logger.warn("AGENTIC_PLATFORM_OTEL_CONTENT_CAPTURE=full — OTLP export includes " +
+                "unredacted prompt/completion/tool content. This should only be " +
+                "set intentionally (e.g. local debugging).");
+        }
+        const otlpExporter = new ContentPolicyOTLPSpanExporter(new OTLPTraceExporter({ timeoutMillis: OTLP_EXPORT_TIMEOUT_MILLIS }), contentCaptureMode);
+        logger.info({ contentCaptureMode }, "Tracing: OTLP output enabled");
+        return new BatchSpanProcessor(otlpExporter);
+    }
+    catch (err) {
+        logger.warn({ err: err.message }, "Failed to set up OTLP exporter — OTLP export disabled, MongoDB tracing unaffected");
+        return null;
+    }
+}
+/** Retry interval (seconds) for the background trace-store reconnection. */
+function getRetryIntervalSeconds() {
+    const raw = Number(process.env["AGENTIC_TRACE_STORE_RETRY_INTERVAL_SECONDS"]);
+    return Number.isFinite(raw) && raw > 0 ? raw : 30;
+}
+export async function setupTracing(args = {}) {
+    if (tracerProvider !== null) {
+        logger.debug("Tracing already initialized");
+        return;
+    }
+    // Serialize concurrent callers onto the first call's promise. Cleared in
+    // `finally` so a degraded run (e.g. OTEL deps absent) can be retried later.
+    if (setupPromise !== null)
+        return setupPromise;
+    setupPromise = doSetupTracing(args).finally(() => {
+        setupPromise = null;
+    });
+    return setupPromise;
+}
+async function doSetupTracing(args) {
+    const serviceName = args.serviceName ?? "runner-sdk";
+    const spanProcessors = [new ExecutionContextSpanProcessor()];
+    const { collection, errorMessage } = await resolveTracingCollection(args);
+    if (args.mongodbUri) {
+        // A store URI was configured — register the lazy Mongo exporter up front
+        // (the provider is built once, below, with it in the processor list). If
+        // the store was reachable at startup, wire the collection in immediately;
+        // otherwise leave it unset and retry in the background.
+        const lazy = new LazyMongoSpanExporter();
+        lazyMongoExporter = lazy;
+        spanProcessors.push(new BatchSpanProcessor(lazy));
+        if (collection) {
+            lazy.setCollection(collection);
+            mongodbExporterAttached = true;
+            mongodbDegraded = false;
+            logger.info({ db: collection.dbName, collection: collection.collectionName }, "Tracing: MongoDB output enabled");
+        }
+        else {
+            mongodbDegraded = true;
+            const intervalSec = getRetryIntervalSeconds();
+            logger.error(`Trace store unavailable at startup; will retry every ${intervalSec}s. Error: ${errorMessage ?? "unknown"}`);
+            startMongoRetry(args);
+        }
+    }
+    const otlpProcessor = await buildOtlpSpanProcessor();
+    if (otlpProcessor !== null)
+        spanProcessors.push(otlpProcessor);
+    const provider = new BasicTracerProvider({
+        resource: resourceFromAttributes({
+            "service.name": serviceName,
+        }),
+        spanProcessors,
+    });
+    trace.setGlobalTracerProvider(provider);
+    tracerProvider = provider;
+    // Restrict the global propagator to W3C trace-context only, mirroring
+    // Python's set_global_textmap(TraceContextTextMapPropagator()). The API's
+    // own default (once anything registers a composite propagator, e.g. an
+    // auto-instrumentation package) also propagates Baggage, which would leak
+    // arbitrary unredacted key/value pairs onto every outbound call that goes
+    // through the global propagator once something starts writing to it.
+    // AER/Tool-Pod -> OE calls (tls_client.ts's fetchPlatform) already sidestep
+    // this by injecting through their own local propagator instance regardless
+    // of this setting, but this closes the gap for any future code path that
+    // uses the global API directly.
+    propagation.setGlobalPropagator(new W3CTraceContextPropagator());
+    runInstrumentor();
+    logger.info({ serviceName }, "Tracing enabled");
+}
+export function runInstrumentor() {
+    const instrumentor = getInstrumentor();
+    if (instrumentor === null) {
+        logger.warn("No instrumentor hook registered. Framework SDK should call registerInstrumentor() to enable tracing.");
+        return;
+    }
+    try {
+        instrumentor();
+        logger.info("Framework instrumentation enabled");
+    }
+    catch (err) {
+        logger.warn({ err: err.message }, "Framework instrumentor failed — tracing disabled");
+    }
+}
+export async function shutdownTracing() {
+    // Signal in-flight retry attempts to stop before tearing down the provider
+    // they attach exporters to. Set before clearing the timer so an attempt
+    // that resumes mid-shutdown sees the flag and cleans up its own client
+    // rather than rescheduling or overwriting `tracingMongoClient`.
+    retryStopped = true;
+    // Cleared unconditionally so a partially-failed setup
+    // (provider never created but retry scheduled) still cleans up.
+    if (retryTimer !== null) {
+        clearTimeout(retryTimer);
+        retryTimer = null;
+    }
+    if (tracerProvider !== null) {
+        await tracerProvider.shutdown();
+        tracerProvider = null;
+        logger.info("Tracing shutdown complete");
+    }
+    if (tracingMongoClient !== null) {
+        try {
+            await tracingMongoClient.close();
+        }
+        catch (err) {
+            logger.warn(`Tracing MongoClient close failed: ${err.message}`);
+        }
+        tracingMongoClient = null;
+    }
+    // Reset store-exporter state so a fresh setupTracing() in the same
+    // process (e.g. tests) starts clean.
+    mongodbExporterAttached = false;
+    mongodbDegraded = false;
+    lazyMongoExporter = null;
+}
+/**
+ * Snapshot of the database trace-store exporter for /health. Mirrors Python's
+ * `tracing_status`: `"attached"` (MongoDB span processor live), `"degraded"`
+ * (store URI configured but unreachable at startup, retrying), or `"disabled"`
+ * (no store URI configured, not a degradation).
+ */
+export function tracingStatus() {
+    if (mongodbExporterAttached)
+        return { database_exporter: "attached" };
+    if (mongodbDegraded)
+        return { database_exporter: "degraded" };
+    return { database_exporter: "disabled" };
+}
+/**
+ * Wire the recovered trace-store collection into the lazy Mongo exporter
+ * registered at setup time. Called from the background retry loop
+ * once a failed connection recovers. Idempotent — a no-op if already attached.
+ * New spans created after this call route to the store; spans emitted while the
+ * store was unreachable are not retroactively recovered.
+ */
+export function attachMongoTracing(collection) {
+    if (mongodbExporterAttached)
+        return;
+    if (lazyMongoExporter === null) {
+        logger.warn("Cannot attach MongoDB tracing: no store URI was configured at setup");
+        return;
+    }
+    lazyMongoExporter.setCollection(collection);
+    mongodbExporterAttached = true;
+    mongodbDegraded = false;
+    if (retryTimer !== null) {
+        clearTimeout(retryTimer);
+        retryTimer = null;
+    }
+    logger.info({ db: collection.dbName, collection: collection.collectionName }, "Tracing: MongoDB output attached (trace store recovered)");
+}
+/**
+ * Schedule a retry attempt. The timer is unref'd: TOOL_FUNCTION runtimes
+ * return after a single invocation without calling shutdownTracing, so a
+ * referenced retry timer would pin the event loop and keep the supposedly
+ * one-shot process alive while the store is down (Python's retry thread is a
+ * daemon for the same reason). The retry is best-effort background work — it
+ * must never be the handle keeping the process running.
+ */
+function scheduleRetry(attempt, intervalMs) {
+    const timer = setTimeout(attempt, intervalMs);
+    if (typeof timer.unref === "function")
+        timer.unref();
+    return timer;
+}
+/** Retry the trace-store connection in the background. */
+function startMongoRetry(args) {
+    if (mongodbExporterAttached)
+        return;
+    if (retryTimer !== null)
+        return;
+    retryStopped = false;
+    const intervalMs = getRetryIntervalSeconds() * 1000;
+    const runAttempt = async () => {
+        retryTimer = null;
+        if (mongodbExporterAttached || retryStopped)
+            return;
+        const { collection, errorMessage } = await resolveTracingCollection(args);
+        // Shutdown may have raced with this attempt while it was awaiting the
+        // store connection. `resolveTracingCollection` already assigned a fresh
+        // client to `tracingMongoClient` on success — close it so its pool
+        // doesn't leak, then bail without rescheduling.
+        if (retryStopped) {
+            if (tracingMongoClient !== null) {
+                try {
+                    await tracingMongoClient.close();
+                }
+                catch {
+                    // best-effort cleanup
+                }
+                tracingMongoClient = null;
+            }
+            return;
+        }
+        if (collection) {
+            attachMongoTracing(collection);
+        }
+        else {
+            logger.debug(`Trace store retry failed: ${errorMessage ?? "unknown"}`);
+            if (!mongodbExporterAttached && !retryStopped) {
+                retryTimer = scheduleRetry(runAttempt, intervalMs);
+            }
+        }
+    };
+    retryTimer = scheduleRetry(runAttempt, intervalMs);
+}
+export function getCurrentTraceContext() {
+    const span = trace.getActiveSpan();
+    if (!span)
+        return { traceId: null, spanId: null };
+    const ctx = span.spanContext();
+    if (!isSpanContextValid(ctx))
+        return { traceId: null, spanId: null };
+    return { traceId: ctx.traceId, spanId: ctx.spanId };
+}
+export function getTracer(name = "runner-sdk") {
+    return trace.getTracer(name);
+}

package/dist/utils.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Utility functions for Runner SDK.
+ */
+/** Runtime mode for the Runner SDK. */
+export declare enum RuntimeMode {
+    AER = "aer",
+    TOOL = "tool",
+    TOOL_FUNCTION = "tool_function"
+}
+/**
+ * Get the current runtime mode from environment variable.
+ *
+ * @returns RuntimeMode based on RUNNER_MODE environment variable.
+ * @throws Error If RUNNER_MODE is not set or is not a valid mode.
+ */
+export declare function getRuntimeMode(): RuntimeMode;
+/**
+ * Return `true` if `name` matches a platform-owned env var.
+ *
+ * Public-API view of the same membership check used by `tenantEnvVars`.
+ */
+export declare function isPlatformEnvVar(name: string): boolean;
+/**
+ * Return the tenant-owned subset of environment variables.
+ *
+ * `source` defaults to `process.env`. Names in `PLATFORM_ENV_VARS` or
+ * matching any prefix in `PLATFORM_ENV_VAR_PREFIXES` are excluded, so the
+ * result is safe to pass as the substitution mapping to
+ * `loadRuntimeAgentConfig({ envVars: ... })`.
+ */
+export declare function tenantEnvVars(source?: Record<string, string | undefined>): Record<string, string>;
+/** Get environment variable with default. */
+export declare function getEnv(name: string, defaultValue?: string): string;
+/** Get integer environment variable with default. */
+export declare function getEnvInt(name: string, defaultValue: number): number;
+/** Get float environment variable with default. */
+export declare function getEnvFloat(name: string, defaultValue: number): number;
+/** Get boolean environment variable with default. */
+export declare function getEnvBool(name: string, defaultValue?: boolean): boolean;
+/**
+ * Get the HTTP request timeout from environment.
+ *
+ * Uses RUNNER_REQUEST_TIMEOUT env var, defaults to 60.0 seconds.
+ */
+export declare function getRequestTimeout(): number;
+/**
+ * Get the tool-call read timeout from environment.
+ *
+ * The OE holds /tool/execute open until the tool result comes back, so this
+ * bounds the tool's own runtime rather than the handshake. It matches the OE's
+ * own tool deadline: a smaller value abandons a tool the platform is still
+ * happily running, leaving the SDK with no result to report.
+ *
+ * Uses RUNNER_TOOL_READ_TIMEOUT env var, defaults to 600.0 seconds.
+ */
+export declare function getToolReadTimeout(): number;
+export declare const LLM_MAX_RETRIES: number;
+export declare const LLM_INITIAL_BACKOFF: number;
+export declare const LLM_BACKOFF_MULTIPLIER: number;
+export declare const LLM_MAX_BACKOFF: number;
+/** Same-step retries of /tool/execute (and the SSE relay) after OE advertises retryable=true, and after an SSE transport disconnect. 1 initial + 2 extras; lockstep with Python. */
+export declare const OE_RETRYABLE_MAX_ATTEMPTS = 3;
+/**
+ * Wait after a dropped SSE connection so the next attempt can land after
+ * dispatch_heartbeat TTL (30s). Do not reuse HTTP Retry-After's 10s cap.
+ * Lockstep with Python.
+ */
+export declare const OE_DISPATCH_TAKEOVER_RETRY_DELAY_MS = 30000;
+export declare const OE_DISPATCH_RETRY_MAX_WAIT_MS = 60000;
+/** Honor a server-provided SSE retry_after_ms, capped. Absent means retry immediately. */
+export declare function oeStreamRetryDelayMs(retryAfterMs?: number | null): number;
+/** Sleep before an SSE same-URL retry. Tests spy this to avoid wall-clock waits. */
+export declare const oeStreamRetry: {
+    sleep(delayMs: number): Promise<void>;
+};
+export declare const LLM_READ_TIMEOUT: number;
+/** Classify provider failures before any LLM output has been exposed. */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Render an LLM provider error for display, without escaped-JSON text.
+ *
+ * Some provider SDKs attach the raw API error body as an object on the
+ * error or its `cause` (`.details`, `.body`). That object's values are
+ * often themselves JSON-encoded strings containing real newlines (e.g. a
+ * pretty-printed nested error payload), so `String()`/template-literal
+ * stringification ends up producing a repr that turns the newlines into
+ * literal `\n` sequences. Decode any JSON-encoded string values
+ * first and re-serialize with `JSON.stringify(..., null, 2)` so the result
+ * renders as readable, indented JSON instead.
+ */
+export declare function formatLlmError(error: unknown): string;
+/**
+ * True when an LLM provider error is an auth rejection (HTTP 401/403).
+ *
+ * Reads only the provider SDK's own status fields — `status` (openai-node /
+ * anthropic-node style), `status_code`, `response.status` /
+ * `response.status_code` (fetch/axios style), and an integer `code` —
+ * walking the `cause` chain because adapters occasionally re-throw. Text is
+ * never matched: the caller maps a positive result onto the wire-level
+ * credential error code, and anything unrecognized returns false so the
+ * failure keeps its existing generic classification.
+ */
+export declare function isLlmCredentialRejection(error: unknown): boolean;
+/**
+ * Normalize LLM message content to a string.
+ *
+ * LLM content can be:
+ * - A string (normal text)
+ * - A list (multimodal content with text and other parts)
+ * - null/undefined or empty
+ *
+ * This handles cases where LangChain's AIMessageChunk.content is a list
+ * of content blocks (e.g., from Gemini multimodal responses) rather than
+ * a simple string.
+ *
+ * @param content The content to normalize (string, list, or null/undefined)
+ * @returns A string representation of the content
+ */
+export declare function normalizeContent(content: unknown): string;
+/** Normalize streamed tool-call args into the wire-format string payload. */
+export declare function normalizeToolCallArgs(args: unknown): string | null;
+/**
+ * Trim a string tool-metadata value, collapsing blank/non-string to null.
+ *
+ * Shared by the framework SDKs' tool-wrapping code so metadata values written
+ * as "" or "  " are treated the same as absent rather
+ * than sent to the OE as a non-empty-looking but meaningless string.
+ */
+export declare function normalizeOptionalStr(value: unknown): string | null;
+/** Remove `<think>...</think>` blocks and unclosed `<think>` tails. */
+export declare function stripThinking(text: string): string;
+/**
+ * Filter `<think>` blocks from a stream of token chunks.
+ *
+ * Accumulates text in *buffer* until we can determine whether content
+ * is inside a thinking block. Returns `[streamable, newBuffer, inside]`
+ * where *streamable* is the text safe to send to the client.
+ */
+export declare function filterThinkingTokens(token: string, buffer: string, inside: boolean): [streamable: string, newBuffer: string, inside: boolean];
+/** Log a minor section separator (for individual operations). */
+export declare function logSeparator(): void;
+/** Log a major section separator (for execution boundaries). */
+export declare function logSection(): void;
+/**
+ * Log LLM conversation messages in a consistent format.
+ *
+ * @param messages List of message dicts or LangChain message objects
+ * @param prefix Log line prefix (e.g., "OE", "LLM", "AER")
+ * @param countOnly If true, only log message count (for info level)
+ */
+export declare function logLLMMessages(messages: unknown[], prefix?: string, countOnly?: boolean): void;
+/**
+ * Log an LLM response in a consistent format.
+ *
+ * @param result LLM response (dict or AIMessage)
+ * @param step Step number
+ * @param prefix Log line prefix
+ */
+export declare function logLLMResponse(result: unknown, step: number, prefix?: string): void;
+/**
+ * Redact sensitive fields from an arguments record.
+ *
+ * Returns a copy with each listed field replaced by "[REDACTED]"; unlisted
+ * fields pass through unchanged, and an empty list returns the input as-is.
+ */
+export declare function redactFields(data: Record<string, unknown>, fieldsToRedact: readonly string[]): Record<string, unknown>;
+/**
+ * Extract a tool's `redact_fields` policy from its registered definition.
+ * The definition is an opaque metadata record (framework-SDK populated), so
+ * non-string-array values degrade to no redaction rather than throwing.
+ */
+export declare function toolRedactFields(toolDefinitions: Record<string, Record<string, unknown>>, toolName: string | undefined): readonly string[];
+/**
+ * Log a tool execution request.
+ *
+ * @param toolName Name of the tool
+ * @param args Tool arguments
+ * @param step Step number
+ * @param prefix Log line prefix
+ * @param fieldsToRedact Catalog sensitive-field policy. Matching fields omit
+ *   even their type/length metadata; no values are logged.
+ */
+export declare function logToolRequest(toolName: string, args: Record<string, unknown>, step: number, prefix?: string, fieldsToRedact?: readonly string[]): void;
+/**
+ * Log a tool execution result.
+ *
+ * @param toolName Name of the tool
+ * @param step Step number
+ * @param status Execution status (success, error, suspend, interrupted)
+ * @param result Tool result
+ * @param error Error message if failed
+ * @param durationMs Execution duration in milliseconds
+ * @param prefix Log line prefix
+ */
+export declare function logToolResult(toolName: string, step: number, status: string, result?: unknown, error?: string | null, durationMs?: number, prefix?: string): void;
+/** Log that a cached result is being used (replay scenario). */
+export declare function logCachedResult(toolName: string, step: number, prefix?: string): void;
+/** Log that a tool call was blocked by policy. */
+export declare function logPolicyBlocked(toolName: string, step: number, reason: string, prefix?: string): void;
+/** Log the start of an execution. */
+export declare function logExecutionStart(executionId: string, inputKeys: string[], prefix?: string): void;
+/** Log an execution callback (completion/suspension/error). */
+export declare function logExecutionCallback(executionId: string, status: string, result?: unknown, error?: string | null, suspendReason?: string | null, prefix?: string): void;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

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