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

package/dist/memory_writer.js

@@ -0,0 +1,171 @@
+/** Native-checkpoint conversation-turn ingestion for the TypeScript runner. */
+import { randomUUID } from "node:crypto";
+import { getLogger } from "./logger.js";
+import { normalizeContent } from "./utils.js";
+const logger = getLogger("agent_engine_runner_shared.memory_writer");
+/**
+ * Extract only the current turn from framework messages.
+ *
+ * The original user prompt is input, so many LangGraph update streams never
+ * emit it. Prepend it explicitly, then skip through an echoed copy when one is
+ * present so prior checkpoint history and the current prompt are not written
+ * twice. Resume legs suppress every user message because they carry no new
+ * user prompt.
+ */
+export function extractTurnMessages(message, resultMessages, includeUserTurn = true) {
+    const turns = [];
+    const normalizedMessage = normalizeContent(message);
+    if (includeUserTurn && message) {
+        turns.push({ role: "user", content: normalizedMessage });
+    }
+    let startIndex = 0;
+    for (let index = resultMessages.length - 1; index >= 0; index -= 1) {
+        const candidate = resultMessages[index];
+        if (candidate?.role === "user" &&
+            normalizeContent(candidate.content) === normalizedMessage) {
+            startIndex = index + 1;
+            break;
+        }
+    }
+    for (const resultMessage of resultMessages.slice(startIndex)) {
+        const content = normalizeContent(resultMessage.content);
+        if (resultMessage.role === "user") {
+            if (!includeUserTurn)
+                continue;
+            turns.push({ role: "user", content });
+            continue;
+        }
+        if (resultMessage.role === "assistant") {
+            const toolCalls = resultMessage.toolCalls?.map((toolCall) => ({
+                id: toolCall.id ?? "",
+                name: toolCall.name ?? "",
+                arguments: toolCall.args ?? {},
+            }));
+            if (!content && !toolCalls?.length)
+                continue;
+            turns.push({
+                role: "assistant",
+                content,
+                toolCalls: toolCalls ?? null,
+            });
+            continue;
+        }
+        if (resultMessage.role === "tool") {
+            const toolCallId = resultMessage.toolCallId ?? "";
+            turns.push({
+                role: "tool",
+                content,
+                toolCallId,
+                toolName: resultMessage.name ?? "",
+                isError: resultMessage.isError ?? false,
+            });
+        }
+    }
+    return turns;
+}
+function validateTurn(turn) {
+    if (turn.role === "user" && !turn.content) {
+        throw new Error("user memory turns require content");
+    }
+    if (turn.role === "tool" && !turn.content) {
+        throw new Error("tool memory turns require content");
+    }
+    if (turn.role === "tool" && !turn.toolCallId) {
+        throw new Error("tool memory turns require a tool call id");
+    }
+}
+/** Write one current-turn batch in message order. */
+async function writeTurnToMemory(runtime, args) {
+    const sessionId = args.sessionId?.trim();
+    if (!sessionId) {
+        logger.warn("session_id required for memory write; skipping turn write");
+        return;
+    }
+    const userId = args.userId?.trim();
+    if (!userId) {
+        logger.warn("user_id not set; skipping turn write");
+        return;
+    }
+    const turns = extractTurnMessages(args.message, args.resultMessages, args.includeUserTurn ?? true);
+    for (const turn of turns) {
+        validateTurn(turn);
+        await runtime.recordTurn({
+            ...turn,
+            sessionId,
+            userId,
+            // The adapter retries transport failures. Keep one key for all attempts
+            // of this individual turn so a committed response loss cannot duplicate it.
+            idempotencyKey: randomUUID(),
+        });
+    }
+}
+/**
+ * Process-wide, non-blocking turn writer.
+ *
+ * Batches are serialized so concurrent executions cannot interleave messages
+ * within a conversation turn. Failures are logged and swallowed: Memory is a
+ * best-effort side effect and must not replace an otherwise successful agent
+ * result. `drain` lets session release and graceful app replacement wait for
+ * already-queued writes.
+ */
+export class MemoryWriter {
+    runtime;
+    tail = Promise.resolve();
+    pending = 0;
+    closed = false;
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    get pendingWrites() {
+        return this.pending;
+    }
+    writeTurnAsync(args) {
+        if (this.closed) {
+            logger.warn("MemoryWriter is shut down; skipping turn write");
+            return;
+        }
+        this.pending += 1;
+        this.tail = this.tail
+            .then(() => writeTurnToMemory(this.runtime, args))
+            .catch((error) => {
+            const kind = error instanceof Error ? error.name : typeof error;
+            logger.warn(`Failed to write turn to memory (${kind})`);
+        })
+            .finally(() => {
+            this.pending -= 1;
+        });
+    }
+    async drain(timeoutMs) {
+        const deadline = timeoutMs === undefined ? null : Date.now() + Math.max(0, timeoutMs);
+        while (this.pending > 0) {
+            const pending = this.tail;
+            if (deadline === null) {
+                await pending;
+                continue;
+            }
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return false;
+            let timer;
+            const completed = await Promise.race([
+                pending.then(() => true),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(false), remaining);
+                }),
+            ]);
+            if (timer !== undefined)
+                clearTimeout(timer);
+            if (!completed)
+                return false;
+        }
+        return true;
+    }
+    async shutdown() {
+        if (this.closed) {
+            await this.drain();
+            return;
+        }
+        this.closed = true;
+        await this.drain();
+    }
+}

package/dist/metrics.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Metrics and observability for the Runner SDK.
+ *
+ * Ported from `agent_engine_runner_shared/metrics.py`. Provides:
+ *   - `Metrics` class — process-singleton latency/error/request counters.
+ *   - `recordLatency(operation, fn, labels?)` — async wrapper that measures duration.
+ *   - `withMetrics(operation, fn, opts?)` — HOF replacement for the Python decorator.
+ *   - `logToolCall`/`logToolResult`/`logLlmCall`/`logLlmResult`/`logExecutionEvent`
+ *     structured-log helpers.
+ *
+ * Node is single-threaded per event loop, so no explicit lock is needed for
+ * the counter maps (the GIL did the same job in Python).
+ */
+export interface LatencyStatsJson {
+    count: number;
+    total_ms: number;
+    min_ms: number;
+    max_ms: number;
+    avg_ms: number;
+}
+export declare class Metrics {
+    private static latencies;
+    private static errors;
+    private static requests;
+    static recordLatency(operation: string, durationMs: number, labels?: Record<string, string>): void;
+    static recordError(operation: string, labels?: Record<string, string>): void;
+    static getAll(): {
+        latencies: Record<string, LatencyStatsJson>;
+        errors: Record<string, number>;
+        requests: Record<string, number>;
+    };
+    static reset(): void;
+}
+/**
+ * Run `fn` and record its wall-clock duration as a latency metric.
+ * Errors propagate; their duration is still recorded.
+ */
+export declare function recordLatency<T>(operation: string, fn: () => Promise<T> | T, labels?: Record<string, string>): Promise<T>;
+/**
+ * Wrap a function to record latency (and optionally errors).
+ *
+ * Replacement for the Python `@with_metrics(...)` decorator. The returned
+ * function preserves the original signature and awaits any returned promise
+ * so async/sync code can use the same wrapper.
+ */
+export declare function withMetrics<A extends unknown[], R>(operation: string, fn: (...args: A) => R | Promise<R>, opts?: {
+    recordErrors?: boolean;
+}): (...args: A) => Promise<R>;
+export declare function logToolCall(args: {
+    executionId: string;
+    stepNumber: number;
+    toolName: string;
+    argumentKeys: string[];
+    isLocal: boolean;
+}): void;
+export declare function logToolResult(args: {
+    executionId: string;
+    stepNumber: number;
+    toolName: string;
+    status: string;
+    durationMs: number;
+    error?: string | null;
+}): void;
+export declare function logLlmCall(args: {
+    executionId: string;
+    stepNumber: number;
+    modelName: string;
+    messageCount: number;
+}): void;
+export declare function logLlmResult(args: {
+    executionId: string;
+    stepNumber: number;
+    modelName: string;
+    status: string;
+    durationMs: number;
+    toolCalls?: string[] | null;
+    error?: string | null;
+}): void;
+export declare function logExecutionEvent(args: {
+    executionId: string;
+    event: string;
+    details?: Record<string, unknown>;
+}): void;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.d.ts.map

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

package/dist/metrics.js

@@ -0,0 +1,205 @@
+/**
+ * Metrics and observability for the Runner SDK.
+ *
+ * Ported from `agent_engine_runner_shared/metrics.py`. Provides:
+ *   - `Metrics` class — process-singleton latency/error/request counters.
+ *   - `recordLatency(operation, fn, labels?)` — async wrapper that measures duration.
+ *   - `withMetrics(operation, fn, opts?)` — HOF replacement for the Python decorator.
+ *   - `logToolCall`/`logToolResult`/`logLlmCall`/`logLlmResult`/`logExecutionEvent`
+ *     structured-log helpers.
+ *
+ * Node is single-threaded per event loop, so no explicit lock is needed for
+ * the counter maps (the GIL did the same job in Python).
+ */
+import { getLogger } from "./logger.js";
+const logger = getLogger("agent_engine_runner_shared.metrics");
+class LatencyStats {
+    count = 0;
+    totalMs = 0;
+    minMs = Number.POSITIVE_INFINITY;
+    maxMs = 0;
+    record(durationMs) {
+        this.count += 1;
+        this.totalMs += durationMs;
+        if (durationMs < this.minMs)
+            this.minMs = durationMs;
+        if (durationMs > this.maxMs)
+            this.maxMs = durationMs;
+    }
+    get avgMs() {
+        return this.count > 0 ? this.totalMs / this.count : 0;
+    }
+    toJSON() {
+        return {
+            count: this.count,
+            total_ms: round2(this.totalMs),
+            min_ms: this.minMs === Number.POSITIVE_INFINITY ? 0 : round2(this.minMs),
+            max_ms: round2(this.maxMs),
+            avg_ms: round2(this.avgMs),
+        };
+    }
+}
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+function labelKey(operation, labels) {
+    const entries = Object.entries(labels).sort(([a], [b]) => a.localeCompare(b));
+    if (entries.length === 0)
+        return operation;
+    const labelStr = entries.map(([k, v]) => `${k}=${v}`).join(",");
+    return `${operation}:${labelStr}`;
+}
+export class Metrics {
+    static latencies = new Map();
+    static errors = new Map();
+    static requests = new Map();
+    static recordLatency(operation, durationMs, labels = {}) {
+        const key = labelKey(operation, labels);
+        let stats = this.latencies.get(key);
+        if (!stats) {
+            stats = new LatencyStats();
+            this.latencies.set(key, stats);
+        }
+        stats.record(durationMs);
+        this.requests.set(operation, (this.requests.get(operation) ?? 0) + 1);
+        logger.debug({
+            metric_type: "latency",
+            operation,
+            duration_ms: round2(durationMs),
+            ...labels,
+        }, "METRIC latency");
+    }
+    static recordError(operation, labels = {}) {
+        const key = labelKey(operation, labels);
+        this.errors.set(key, (this.errors.get(key) ?? 0) + 1);
+        logger.warn({
+            metric_type: "error",
+            operation,
+            ...labels,
+        }, "METRIC error");
+    }
+    static getAll() {
+        return {
+            latencies: Object.fromEntries(Array.from(this.latencies.entries()).map(([k, v]) => [k, v.toJSON()])),
+            errors: Object.fromEntries(this.errors),
+            requests: Object.fromEntries(this.requests),
+        };
+    }
+    static reset() {
+        this.latencies.clear();
+        this.errors.clear();
+        this.requests.clear();
+    }
+}
+/**
+ * Run `fn` and record its wall-clock duration as a latency metric.
+ * Errors propagate; their duration is still recorded.
+ */
+export async function recordLatency(operation, fn, labels = {}) {
+    const start = performance.now();
+    try {
+        return await fn();
+    }
+    finally {
+        Metrics.recordLatency(operation, performance.now() - start, labels);
+    }
+}
+/**
+ * Wrap a function to record latency (and optionally errors).
+ *
+ * Replacement for the Python `@with_metrics(...)` decorator. The returned
+ * function preserves the original signature and awaits any returned promise
+ * so async/sync code can use the same wrapper.
+ */
+export function withMetrics(operation, fn, opts = {}) {
+    const recordErrors = opts.recordErrors !== false;
+    return async (...args) => {
+        const start = performance.now();
+        try {
+            return await fn(...args);
+        }
+        catch (err) {
+            if (recordErrors)
+                Metrics.recordError(operation);
+            throw err;
+        }
+        finally {
+            Metrics.recordLatency(operation, performance.now() - start);
+        }
+    };
+}
+// =============================================================================
+// Structured Logging Helpers
+// =============================================================================
+export function logToolCall(args) {
+    logger.info({
+        event_type: "tool_call",
+        execution_id: args.executionId,
+        step_number: args.stepNumber,
+        tool_name: args.toolName,
+        is_local: args.isLocal,
+        argument_keys: args.argumentKeys,
+    }, `TOOL_CALL step=${args.stepNumber} tool=${args.toolName}`);
+}
+export function logToolResult(args) {
+    const ok = args.status === "success" ||
+        args.status === "suspend" ||
+        args.status === "cached";
+    const fields = {
+        event_type: "tool_result",
+        execution_id: args.executionId,
+        step_number: args.stepNumber,
+        tool_name: args.toolName,
+        status: args.status,
+        duration_ms: round2(args.durationMs),
+        error: args.error ?? null,
+    };
+    const msg = `TOOL_RESULT step=${args.stepNumber} tool=${args.toolName} status=${args.status}`;
+    if (ok)
+        logger.info(fields, msg);
+    else
+        logger.error(fields, msg);
+    Metrics.recordLatency("tool_execution", args.durationMs, {
+        tool_name: args.toolName,
+    });
+    if (args.status === "error")
+        Metrics.recordError("tool_execution", { tool_name: args.toolName });
+}
+export function logLlmCall(args) {
+    logger.info({
+        event_type: "llm_call",
+        execution_id: args.executionId,
+        step_number: args.stepNumber,
+        model_name: args.modelName,
+        message_count: args.messageCount,
+    }, `LLM_CALL step=${args.stepNumber} model=${args.modelName}`);
+}
+export function logLlmResult(args) {
+    const fields = {
+        event_type: "llm_result",
+        execution_id: args.executionId,
+        step_number: args.stepNumber,
+        model_name: args.modelName,
+        status: args.status,
+        duration_ms: round2(args.durationMs),
+        tool_calls: args.toolCalls ?? null,
+        error: args.error ?? null,
+    };
+    const msg = `LLM_RESULT step=${args.stepNumber} model=${args.modelName} status=${args.status}`;
+    if (args.status === "success")
+        logger.info(fields, msg);
+    else
+        logger.error(fields, msg);
+    Metrics.recordLatency("llm_call", args.durationMs, {
+        model_name: args.modelName,
+    });
+    if (args.status === "error")
+        Metrics.recordError("llm_call", { model_name: args.modelName });
+}
+export function logExecutionEvent(args) {
+    logger.info({
+        event_type: `execution_${args.event.toLowerCase()}`,
+        execution_id: args.executionId,
+        ...(args.details ?? {}),
+    }, `EXECUTION_${args.event} execution_id=${args.executionId.slice(0, 8)}...`);
+}