@elizaos/agent 2.0.0-alpha.358 → 2.0.0-alpha.376

package/apps/app-training/src/routes/trajectory-routes.js

@@ -0,0 +1,910 @@
+/**
+ * Trajectory API routes for the Eliza Control UI.
+ *
+ * Provides endpoints for:
+ * - Listing and searching trajectories
+ * - Viewing trajectory details with LLM calls and provider accesses
+ * - Exporting trajectories to JSON, CSV, or ZIP
+ * - Deleting trajectories
+ * - Getting trajectory statistics
+ * - Enabling/disabling trajectory logging
+ *
+ * Uses the native trajectories service for data access.
+ */
+import { createZipArchive, enrichTrajectoryLlmCall, executeRawSql, extractRows, readJsonBody as parseJsonBody, saveTrajectory, sendJson, sendJsonError, } from "@elizaos/agent";
+// ============================================================================
+// Helpers
+// ============================================================================
+function isRouteCompatibleTrajectoryLogger(candidate) {
+    if (!candidate || typeof candidate !== "object")
+        return false;
+    const logger = candidate;
+    return (typeof logger.isEnabled === "function" &&
+        typeof logger.setEnabled === "function" &&
+        typeof logger.listTrajectories === "function" &&
+        typeof logger.getTrajectoryDetail === "function" &&
+        typeof logger.getStats === "function" &&
+        typeof logger.deleteTrajectories === "function" &&
+        typeof logger.clearAllTrajectories === "function" &&
+        typeof logger.exportTrajectories === "function");
+}
+function collectCandidates(runtimeLike) {
+    const seen = new Set();
+    const candidates = [];
+    const add = (candidate) => {
+        if (!candidate || seen.has(candidate))
+            return;
+        seen.add(candidate);
+        candidates.push(candidate);
+    };
+    if (typeof runtimeLike.getServicesByType === "function") {
+        const byType = runtimeLike.getServicesByType("trajectories");
+        if (Array.isArray(byType)) {
+            for (const candidate of byType) {
+                add(candidate);
+            }
+        }
+        else {
+            add(byType);
+        }
+    }
+    if (typeof runtimeLike.getService === "function") {
+        add(runtimeLike.getService("trajectories"));
+    }
+    return candidates;
+}
+function findCompatibleLogger(candidates) {
+    for (const candidate of candidates) {
+        if (isRouteCompatibleTrajectoryLogger(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+async function getTrajectoryLogger(runtime) {
+    const runtimeLike = runtime;
+    // Fast path: service already available.
+    const immediate = findCompatibleLogger(collectCandidates(runtimeLike));
+    if (immediate)
+        return immediate;
+    // The service may still be starting — wait for it if the runtime supports it.
+    const status = typeof runtimeLike.getServiceRegistrationStatus === "function"
+        ? runtimeLike.getServiceRegistrationStatus("trajectories")
+        : "unknown";
+    if ((status === "pending" || status === "registering") &&
+        typeof runtimeLike.getServiceLoadPromise === "function") {
+        try {
+            await Promise.race([
+                runtimeLike.getServiceLoadPromise("trajectories"),
+                new Promise((resolve) => setTimeout(resolve, 5000)),
+            ]);
+        }
+        catch {
+            // Service failed to start — fall through to return null.
+        }
+        // Re-check after waiting.
+        return findCompatibleLogger(collectCandidates(runtimeLike));
+    }
+    return null;
+}
+function toNullableString(value) {
+    return typeof value === "string" ? value : null;
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function toFiniteNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+function estimateTokenCount(text) {
+    return Math.max(1, Math.ceil(text.length / 4));
+}
+function buildDisplayMetadata(traj) {
+    const metadata = { ...(asRecord(traj.metadata) ?? {}) };
+    const calls = (traj.steps ?? []).flatMap((step) => step.llmCalls ?? []);
+    if (calls.length > 0 &&
+        !calls.every((call) => isSyntheticTrajectoryCall(call))) {
+        delete metadata.syntheticLlmCall;
+        delete metadata.syntheticLlmCallSource;
+    }
+    return metadata;
+}
+function normalizePersistedStatus(value) {
+    const normalized = String(value ?? "")
+        .trim()
+        .toLowerCase();
+    if (normalized === "active" ||
+        normalized === "completed" ||
+        normalized === "error" ||
+        normalized === "timeout") {
+        return normalized;
+    }
+    return normalized.length > 0 ? "completed" : "active";
+}
+function toPersistedTrajectory(traj) {
+    const metadata = buildDisplayMetadata(traj);
+    const status = normalizePersistedStatus(traj.metrics?.finalStatus ??
+        (typeof traj.endTime === "number" ? "completed" : "active"));
+    const persistedSteps = (traj.steps ?? []).map((step, index) => ({
+        stepId: typeof step.stepId === "string" && step.stepId.trim().length > 0
+            ? step.stepId.trim()
+            : `${traj.trajectoryId}-step-${index + 1}`,
+        stepNumber: index,
+        timestamp: typeof step.timestamp === "number" && Number.isFinite(step.timestamp)
+            ? step.timestamp
+            : traj.startTime,
+        llmCalls: (step.llmCalls ?? []).map((call, callIndex) => {
+            const normalizedCall = enrichTrajectoryLlmCall(call);
+            return {
+                callId: typeof normalizedCall.callId === "string" &&
+                    normalizedCall.callId.trim().length > 0
+                    ? normalizedCall.callId.trim()
+                    : `${traj.trajectoryId}-call-${index + 1}-${callIndex + 1}`,
+                timestamp: typeof normalizedCall.timestamp === "number" &&
+                    Number.isFinite(normalizedCall.timestamp)
+                    ? normalizedCall.timestamp
+                    : step.timestamp,
+                model: typeof normalizedCall.model === "string"
+                    ? normalizedCall.model
+                    : "unknown",
+                systemPrompt: typeof normalizedCall.systemPrompt === "string"
+                    ? normalizedCall.systemPrompt
+                    : "",
+                userPrompt: typeof normalizedCall.userPrompt === "string"
+                    ? normalizedCall.userPrompt
+                    : "",
+                response: typeof normalizedCall.response === "string"
+                    ? normalizedCall.response
+                    : "",
+                temperature: toFiniteNumber(normalizedCall.temperature) ?? 0,
+                maxTokens: toFiniteNumber(normalizedCall.maxTokens) ?? 0,
+                purpose: typeof normalizedCall.purpose === "string"
+                    ? normalizedCall.purpose
+                    : "",
+                actionType: typeof normalizedCall.actionType === "string"
+                    ? normalizedCall.actionType
+                    : "",
+                stepType: typeof normalizedCall.stepType === "string"
+                    ? normalizedCall.stepType
+                    : undefined,
+                tags: Array.isArray(normalizedCall.tags)
+                    ? normalizedCall.tags.filter((tag) => typeof tag === "string")
+                    : undefined,
+                latencyMs: toFiniteNumber(normalizedCall.latencyMs) ?? 0,
+                promptTokens: toFiniteNumber(normalizedCall.promptTokens) ?? undefined,
+                completionTokens: toFiniteNumber(normalizedCall.completionTokens) ?? undefined,
+            };
+        }),
+        providerAccesses: (step.providerAccesses ?? []).map((access, accessIndex) => ({
+            providerId: typeof access.providerId === "string" &&
+                access.providerId.trim().length > 0
+                ? access.providerId.trim()
+                : `${traj.trajectoryId}-provider-${index + 1}-${accessIndex + 1}`,
+            providerName: typeof access.providerName === "string"
+                ? access.providerName
+                : "unknown",
+            timestamp: typeof access.timestamp === "number" &&
+                Number.isFinite(access.timestamp)
+                ? access.timestamp
+                : step.timestamp,
+            data: asRecord(access.data) ?? {},
+            query: asRecord(access.query) ?? undefined,
+            purpose: typeof access.purpose === "string" ? access.purpose : "",
+        })),
+    }));
+    return {
+        id: traj.trajectoryId,
+        source: toNullableString(metadata.source) ?? "runtime",
+        status,
+        startTime: traj.startTime,
+        endTime: typeof traj.endTime === "number" ? traj.endTime : null,
+        scenarioId: typeof traj.scenarioId === "string" ? traj.scenarioId : undefined,
+        batchId: typeof traj.batchId === "string" ? traj.batchId : undefined,
+        steps: persistedSteps,
+        metadata,
+        totalReward: 0,
+        createdAt: new Date(traj.startTime).toISOString(),
+        updatedAt: new Date(typeof traj.endTime === "number" ? traj.endTime : Date.now()).toISOString(),
+    };
+}
+function listItemToUIRecord(item) {
+    const status = item.status === "timeout" || item.status === "error"
+        ? "error"
+        : item.status;
+    return {
+        id: item.id,
+        agentId: item.agentId,
+        roomId: null,
+        entityId: null,
+        conversationId: null,
+        source: item.source,
+        status: status,
+        startTime: item.startTime,
+        endTime: item.endTime,
+        durationMs: item.durationMs,
+        llmCallCount: item.llmCallCount,
+        providerAccessCount: item.providerAccessCount,
+        totalPromptTokens: item.totalPromptTokens,
+        totalCompletionTokens: item.totalCompletionTokens,
+        ...(item.scenarioId ? { scenarioId: item.scenarioId } : {}),
+        ...(item.batchId ? { batchId: item.batchId } : {}),
+        metadata: {
+            ...(item.metadata ?? {}),
+            ...(item.scenarioId ? { scenarioId: item.scenarioId } : {}),
+            ...(item.batchId ? { batchId: item.batchId } : {}),
+        },
+        createdAt: item.createdAt,
+        updatedAt: item.updatedAt ?? item.createdAt,
+    };
+}
+function trajectoryToUIDetail(traj) {
+    const finalStatus = traj.metrics?.finalStatus ?? "completed";
+    const normalizedEndTime = typeof traj.endTime === "number" && traj.endTime > 0 ? traj.endTime : null;
+    const status = finalStatus === "timeout" ||
+        finalStatus === "terminated" ||
+        finalStatus === "error"
+        ? "error"
+        : finalStatus === "completed"
+            ? "completed"
+            : normalizedEndTime
+                ? "completed"
+                : "active";
+    const llmCalls = [];
+    const providerAccesses = [];
+    let totalPromptTokens = 0;
+    let totalCompletionTokens = 0;
+    const steps = traj.steps || [];
+    const trajectoryId = String(traj.trajectoryId);
+    for (let i = 0; i < steps.length; i++) {
+        const step = steps[i];
+        const stepId = typeof step.stepId === "string" ? step.stepId : `step-${i}`;
+        // Process LLM Calls
+        const calls = step.llmCalls || [];
+        for (let j = 0; j < calls.length; j++) {
+            const call = enrichTrajectoryLlmCall(calls[j]);
+            llmCalls.push({
+                id: call.callId || `${stepId}-call-${j}`,
+                trajectoryId,
+                stepId,
+                model: call.model || "unknown",
+                systemPrompt: call.systemPrompt || "",
+                userPrompt: call.userPrompt || "",
+                response: call.response || "",
+                temperature: typeof call.temperature === "number" ? call.temperature : 0,
+                maxTokens: typeof call.maxTokens === "number" ? call.maxTokens : 0,
+                purpose: call.purpose || "",
+                actionType: call.actionType || "",
+                stepType: call.stepType || "",
+                tags: Array.isArray(call.tags)
+                    ? call.tags.filter((tag) => typeof tag === "string")
+                    : [],
+                latencyMs: call.latencyMs || 0,
+                promptTokens: call.promptTokens,
+                completionTokens: call.completionTokens,
+                timestamp: call.timestamp || step.timestamp,
+                createdAt: new Date(call.timestamp || step.timestamp).toISOString(),
+            });
+            totalPromptTokens += call.promptTokens || 0;
+            totalCompletionTokens += call.completionTokens || 0;
+        }
+        // Process Provider Accesses
+        const accesses = step.providerAccesses || [];
+        for (let k = 0; k < accesses.length; k++) {
+            const access = accesses[k];
+            providerAccesses.push({
+                id: access.providerId || `${stepId}-provider-${k}`,
+                trajectoryId,
+                stepId,
+                providerName: access.providerName || "unknown",
+                purpose: access.purpose || "",
+                data: access.data || {},
+                query: access.query,
+                timestamp: access.timestamp || step.timestamp,
+                createdAt: new Date(access.timestamp || step.timestamp).toISOString(),
+            });
+        }
+    }
+    const metadata = buildDisplayMetadata(traj);
+    const normalizedDurationMs = status === "active"
+        ? null
+        : typeof traj.durationMs === "number"
+            ? traj.durationMs
+            : null;
+    const updatedAtMs = normalizedEndTime ?? (traj.startTime || Date.now());
+    const trajectory = {
+        id: trajectoryId,
+        agentId: String(traj.agentId),
+        roomId: toNullableString(metadata.roomId),
+        entityId: toNullableString(metadata.entityId),
+        conversationId: toNullableString(metadata.conversationId),
+        source: toNullableString(metadata.source) ?? "chat",
+        status,
+        startTime: traj.startTime,
+        endTime: normalizedEndTime,
+        durationMs: normalizedDurationMs,
+        llmCallCount: llmCalls.length,
+        providerAccessCount: providerAccesses.length,
+        totalPromptTokens,
+        totalCompletionTokens,
+        metadata,
+        createdAt: new Date(traj.startTime).toISOString(),
+        updatedAt: new Date(updatedAtMs).toISOString(),
+    };
+    return { trajectory, llmCalls, providerAccesses };
+}
+function isSyntheticTrajectoryCall(call) {
+    const model = String(call.model ?? "").toLowerCase();
+    const systemPrompt = String(call.systemPrompt ?? "").toLowerCase();
+    const response = String(call.response ?? "").toLowerCase();
+    return (model.includes("synthetic") ||
+        systemPrompt.includes("[synthetic]") ||
+        response.includes("placeholder call inserted"));
+}
+function needsConversationBackfill(traj) {
+    const calls = (traj.steps ?? []).flatMap((step) => step.llmCalls ?? []);
+    if (calls.length === 0) {
+        return true;
+    }
+    return calls.every((call) => isSyntheticTrajectoryCall(call));
+}
+function extractMessageText(memory) {
+    if (!memory || typeof memory !== "object")
+        return "";
+    const content = memory.content;
+    return typeof content?.text === "string" ? content.text.trim() : "";
+}
+function isTextGenerationLogRow(type, body) {
+    if (!type.startsWith("useModel:"))
+        return false;
+    const modelType = typeof body.modelType === "string" && body.modelType.trim().length > 0
+        ? body.modelType.trim().toUpperCase()
+        : type.slice("useModel:".length).trim().toUpperCase();
+    return (modelType === "TEXT_SMALL" ||
+        modelType === "TEXT_LARGE" ||
+        modelType === "TEXT_COMPLETION" ||
+        modelType === "REASONING_SMALL" ||
+        modelType === "REASONING_LARGE");
+}
+async function maybeBackfillTrajectoryFromUseModelLogs(runtime, traj) {
+    if (!needsConversationBackfill(traj)) {
+        return traj;
+    }
+    const metadata = (traj.metadata ?? {});
+    const messageId = toNullableString(metadata.messageId);
+    const roomId = toNullableString(metadata.roomId);
+    if (!messageId && !roomId) {
+        return traj;
+    }
+    try {
+        const result = await executeRawSql(runtime, "SELECT type, body, room_id, created_at FROM logs ORDER BY created_at DESC LIMIT 500");
+        const rows = extractRows(result);
+        if (!Array.isArray(rows) || rows.length === 0) {
+            return traj;
+        }
+        const normalizedRows = rows
+            .map((row) => {
+            const record = asRecord(row);
+            if (!record)
+                return null;
+            const bodyValue = record.body;
+            const body = asRecord(bodyValue) ??
+                (typeof bodyValue === "string"
+                    ? asRecord(JSON.parse(bodyValue))
+                    : null);
+            if (!body)
+                return null;
+            return {
+                type: typeof record.type === "string" ? record.type : "",
+                roomId: toNullableString(record.room_id),
+                createdAt: typeof record.created_at === "string" ? record.created_at : null,
+                body,
+            };
+        })
+            .filter((row) => row !== null);
+        const runEventCandidates = normalizedRows.filter((row) => {
+            if (row.type !== "run_event")
+                return false;
+            const body = row.body;
+            if (typeof body.runId !== "string" || body.runId.trim().length === 0) {
+                return false;
+            }
+            if (messageId && body.messageId === messageId) {
+                return true;
+            }
+            const loggedRoomId = toNullableString(body.roomId) ?? row.roomId;
+            const startTime = toFiniteNumber(body.startTime);
+            const endTime = toFiniteNumber(body.endTime) ?? startTime;
+            return (!!roomId &&
+                loggedRoomId === roomId &&
+                startTime !== null &&
+                endTime !== null &&
+                endTime >= traj.startTime - 60_000 &&
+                startTime <= (traj.endTime ?? traj.startTime + 120_000) + 60_000);
+        });
+        if (runEventCandidates.length === 0) {
+            return traj;
+        }
+        runEventCandidates.sort((left, right) => {
+            const leftStart = toFiniteNumber(left.body.startTime) ?? 0;
+            const rightStart = toFiniteNumber(right.body.startTime) ?? 0;
+            return (Math.abs(leftStart - traj.startTime) -
+                Math.abs(rightStart - traj.startTime));
+        });
+        const runId = String(runEventCandidates[0].body.runId);
+        const useModelRows = normalizedRows
+            .filter((row) => row.body.runId === runId &&
+            isTextGenerationLogRow(row.type, row.body))
+            .sort((left, right) => {
+            const leftTs = toFiniteNumber(left.body.timestamp) ??
+                Date.parse(left.createdAt ?? "") ??
+                0;
+            const rightTs = toFiniteNumber(right.body.timestamp) ??
+                Date.parse(right.createdAt ?? "") ??
+                0;
+            return leftTs - rightTs;
+        });
+        if (useModelRows.length === 0) {
+            return traj;
+        }
+        const baseSteps = traj.steps && traj.steps.length > 0
+            ? traj.steps.map((step) => ({
+                ...step,
+                llmCalls: [],
+            }))
+            : [
+                {
+                    stepId: traj.trajectoryId,
+                    timestamp: traj.startTime,
+                    llmCalls: [],
+                    providerAccesses: [],
+                },
+            ];
+        const firstCallTimestamp = toFiniteNumber(useModelRows[0]?.body.timestamp) ?? traj.startTime;
+        baseSteps[0] = {
+            ...baseSteps[0],
+            timestamp: typeof baseSteps[0].timestamp === "number"
+                ? Math.min(baseSteps[0].timestamp, firstCallTimestamp)
+                : firstCallTimestamp,
+            llmCalls: useModelRows.map((row, index) => {
+                const body = row.body;
+                const systemPrompt = typeof body.systemPrompt === "string" ? body.systemPrompt : "";
+                const userPrompt = typeof body.prompt === "string" ? body.prompt : "";
+                const response = typeof body.response === "string" ? body.response : "";
+                const modelKey = typeof body.modelKey === "string" && body.modelKey.trim().length > 0
+                    ? body.modelKey.trim()
+                    : row.type.slice("useModel:".length);
+                const provider = typeof body.provider === "string" && body.provider.trim().length > 0
+                    ? body.provider.trim()
+                    : "";
+                const model = provider && modelKey?.toUpperCase().startsWith("TEXT_")
+                    ? `${provider}/${modelKey}`
+                    : modelKey || provider || "unknown";
+                return {
+                    callId: `${traj.trajectoryId}-log-${index + 1}`,
+                    timestamp: toFiniteNumber(body.timestamp) ??
+                        Date.parse(row.createdAt ?? "") ??
+                        firstCallTimestamp,
+                    model,
+                    systemPrompt,
+                    userPrompt,
+                    response,
+                    temperature: toFiniteNumber(body.temperature) ?? 0,
+                    maxTokens: toFiniteNumber(body.maxTokens) ?? 0,
+                    purpose: "chat",
+                    actionType: "runtime.useModel",
+                    latencyMs: Math.max(0, Math.round(toFiniteNumber(body.executionTime) ?? 0)) ??
+                        0,
+                    promptTokens: estimateTokenCount(systemPrompt + userPrompt),
+                    completionTokens: estimateTokenCount(response),
+                };
+            }),
+        };
+        const nextMetadata = {
+            ...metadata,
+            llmCallBackfillSource: "logs",
+        };
+        delete nextMetadata.syntheticLlmCall;
+        delete nextMetadata.syntheticLlmCallSource;
+        const enriched = {
+            ...traj,
+            steps: baseSteps,
+            metadata: nextMetadata,
+        };
+        try {
+            await saveTrajectory(runtime, toPersistedTrajectory(enriched));
+        }
+        catch {
+            // Best-effort persistence only; still return the enriched detail payload.
+        }
+        return enriched;
+    }
+    catch {
+        return traj;
+    }
+}
+async function maybeBackfillTrajectoryFromConversationMemory(runtime, traj) {
+    const metadata = (traj.metadata ?? {});
+    const roomId = toNullableString(metadata.roomId);
+    if (!roomId) {
+        return traj;
+    }
+    try {
+        const memories = await runtime.getMemories({
+            roomId,
+            tableName: "messages",
+            limit: 100,
+        });
+        if (!Array.isArray(memories) || memories.length === 0) {
+            return traj;
+        }
+        const sortedMemories = [...memories].sort((a, b) => Number(a.createdAt ?? 0) - Number(b.createdAt ?? 0));
+        const endTime = typeof traj.endTime === "number"
+            ? traj.endTime
+            : traj.startTime + 120_000;
+        const userMemory = [...sortedMemories].reverse().find((memory) => {
+            const createdAt = Number(memory.createdAt ?? 0);
+            if (!Number.isFinite(createdAt))
+                return false;
+            if (createdAt < traj.startTime - 60_000 || createdAt > endTime + 5_000) {
+                return false;
+            }
+            return (memory.entityId !== runtime.agentId &&
+                extractMessageText(memory).length > 0);
+        });
+        if (!userMemory) {
+            return traj;
+        }
+        const userCreatedAt = Number(userMemory.createdAt ?? traj.startTime);
+        const assistantMemory = sortedMemories.find((memory) => {
+            const createdAt = Number(memory.createdAt ?? 0);
+            if (!Number.isFinite(createdAt))
+                return false;
+            if (createdAt < userCreatedAt || createdAt > endTime + 30_000) {
+                return false;
+            }
+            return (memory.entityId === runtime.agentId &&
+                extractMessageText(memory).length > 0);
+        });
+        if (!assistantMemory) {
+            return traj;
+        }
+        const userPrompt = extractMessageText(userMemory);
+        const response = extractMessageText(assistantMemory);
+        if (!userPrompt || !response) {
+            return traj;
+        }
+        const normalizedUserPrompt = userPrompt.toLowerCase();
+        const normalizedResponse = response.toLowerCase();
+        const existingCalls = (traj.steps ?? []).flatMap((step) => step.llmCalls ?? []);
+        const alreadyCapturedConversation = existingCalls.some((call) => {
+            const callPrompt = String(call.userPrompt ?? "")
+                .trim()
+                .toLowerCase();
+            if (callPrompt &&
+                (callPrompt.includes(normalizedUserPrompt) ||
+                    normalizedUserPrompt.includes(callPrompt))) {
+                return true;
+            }
+            const callResponse = String(call.response ?? "")
+                .trim()
+                .toLowerCase();
+            return (callResponse.length > 0 &&
+                (callResponse.includes(normalizedResponse) ||
+                    normalizedResponse.includes(callResponse)));
+        });
+        if (alreadyCapturedConversation) {
+            return traj;
+        }
+        const baseSteps = traj.steps && traj.steps.length > 0
+            ? traj.steps.map((step) => ({
+                ...step,
+                llmCalls: [...(step.llmCalls ?? [])],
+            }))
+            : [
+                {
+                    stepId: traj.trajectoryId,
+                    timestamp: traj.startTime,
+                    llmCalls: [],
+                    providerAccesses: [],
+                },
+            ];
+        baseSteps[0] = {
+            ...baseSteps[0],
+            timestamp: typeof baseSteps[0].timestamp === "number"
+                ? baseSteps[0].timestamp
+                : userCreatedAt,
+            llmCalls: [
+                {
+                    callId: `${traj.trajectoryId}-conversation-memory`,
+                    timestamp: userCreatedAt,
+                    model: "eliza/conversation-memory-backfill",
+                    systemPrompt: "[backfilled from conversation memory because the trajectory logger did not capture the live LLM call]",
+                    userPrompt,
+                    response,
+                    purpose: "chat",
+                    actionType: "conversation-memory-backfill",
+                    latencyMs: Math.max(0, Number(assistantMemory.createdAt ?? endTime) - userCreatedAt),
+                },
+                ...(baseSteps[0].llmCalls ?? []),
+            ],
+        };
+        const nextMetadata = {
+            ...metadata,
+            llmCallBackfillSource: "conversation-memory",
+        };
+        delete nextMetadata.syntheticLlmCall;
+        delete nextMetadata.syntheticLlmCallSource;
+        const enriched = {
+            ...traj,
+            steps: baseSteps,
+            metadata: nextMetadata,
+        };
+        try {
+            await saveTrajectory(runtime, toPersistedTrajectory(enriched));
+        }
+        catch {
+            // Best-effort persistence only; still return the enriched detail payload.
+        }
+        return enriched;
+    }
+    catch {
+        return traj;
+    }
+}
+function normalizeSearchQuery(value) {
+    return String(value ?? "")
+        .trim()
+        .toLowerCase();
+}
+function trajectoryMatchesSearch(item, detail, search) {
+    const needle = normalizeSearchQuery(search);
+    if (!needle)
+        return true;
+    const parts = [item.id, item.source, item.status, item.createdAt];
+    const metadata = detail?.metadata;
+    if (metadata && Object.keys(metadata).length > 0) {
+        parts.push(JSON.stringify(metadata));
+    }
+    for (const step of detail?.steps ?? []) {
+        for (const call of step.llmCalls ?? []) {
+            parts.push(String(call.model ?? ""), String(call.systemPrompt ?? ""), String(call.userPrompt ?? ""), String(call.response ?? ""), String(call.purpose ?? ""), String(call.actionType ?? ""));
+        }
+        for (const access of step.providerAccesses ?? []) {
+            parts.push(String(access.providerName ?? ""), String(access.purpose ?? ""), JSON.stringify(access.data ?? {}), JSON.stringify(access.query ?? {}));
+        }
+    }
+    return parts.some((part) => part.toLowerCase().includes(needle));
+}
+async function applyRouteSearchFilter(runtime, logger, list, search) {
+    const filtered = await Promise.all(list.trajectories.map(async (item) => {
+        const detail = await logger.getTrajectoryDetail(item.id);
+        const hydrated = detail
+            ? await maybeBackfillTrajectoryFromConversationMemory(runtime, await maybeBackfillTrajectoryFromUseModelLogs(runtime, detail))
+            : null;
+        return trajectoryMatchesSearch(item, hydrated, search) ? item : null;
+    }));
+    return {
+        trajectories: filtered.filter((item) => !!item),
+        total: filtered.filter(Boolean).length,
+        offset: list.offset,
+        limit: list.limit,
+    };
+}
+// ============================================================================
+// Handlers
+// ============================================================================
+async function handleGetTrajectories(req, res, runtime) {
+    const logger = await getTrajectoryLogger(runtime);
+    if (!logger) {
+        sendJsonError(res, "Trajectories service not available", 503);
+        return;
+    }
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const options = {
+        limit: Math.min(500, Math.max(1, Number(url.searchParams.get("limit")) || 50)),
+        offset: Math.max(0, Number(url.searchParams.get("offset")) || 0),
+        source: url.searchParams.get("source") || undefined,
+        status: url.searchParams.get("status") || undefined,
+        startDate: url.searchParams.get("startDate") || undefined,
+        endDate: url.searchParams.get("endDate") || undefined,
+        search: url.searchParams.get("search") || undefined,
+        scenarioId: url.searchParams.get("scenarioId") || undefined,
+        batchId: url.searchParams.get("batchId") || undefined,
+        isTrainingData: url.searchParams.has("isTrainingData")
+            ? url.searchParams.get("isTrainingData") === "true"
+            : undefined,
+    };
+    const limit = options.limit ?? 50;
+    const offset = options.offset ?? 0;
+    const result = options.search
+        ? await applyRouteSearchFilter(runtime, logger, await logger.listTrajectories({
+            ...options,
+            search: undefined,
+            limit: 500,
+            offset: 0,
+        }), options.search)
+        : await logger.listTrajectories(options);
+    const pagedTrajectories = options.search
+        ? result.trajectories.slice(offset, offset + limit)
+        : result.trajectories;
+    const uiResult = {
+        trajectories: pagedTrajectories.map(listItemToUIRecord),
+        total: result.total,
+        offset,
+        limit,
+    };
+    sendJson(res, uiResult);
+}
+async function handleGetTrajectoryDetail(_req, res, runtime, trajectoryId) {
+    const logger = await getTrajectoryLogger(runtime);
+    if (!logger) {
+        sendJsonError(res, "Trajectories service not available", 503);
+        return;
+    }
+    const trajectory = await logger.getTrajectoryDetail(trajectoryId);
+    if (!trajectory) {
+        sendJsonError(res, `Trajectory "${trajectoryId}" not found`, 404);
+        return;
+    }
+    const uiDetail = trajectoryToUIDetail(await maybeBackfillTrajectoryFromConversationMemory(runtime, await maybeBackfillTrajectoryFromUseModelLogs(runtime, trajectory)));
+    sendJson(res, uiDetail);
+}
+async function handleGetStats(_req, res, runtime) {
+    const logger = await getTrajectoryLogger(runtime);
+    if (!logger) {
+        sendJsonError(res, "Trajectories service not available", 503);
+        return;
+    }
+    const stats = await logger.getStats();
+    sendJson(res, stats);
+}
+async function handleGetConfig(_req, res, runtime) {
+    const logger = await getTrajectoryLogger(runtime);
+    if (!logger) {
+        sendJsonError(res, "Trajectories service not available", 503);
+        return;
+    }
+    sendJson(res, {
+        enabled: logger.isEnabled(),
+    });
+}
+async function handlePutConfig(req, res, runtime) {
+    const logger = await getTrajectoryLogger(runtime);
+    if (!logger) {
+        sendJsonError(res, "Trajectories service not available", 503);
+        return;
+    }
+    const body = await parseJsonBody(req, res);
+    if (!body)
+        return;
+    if (typeof body.enabled === "boolean") {
+        logger.setEnabled(body.enabled);
+    }
+    sendJson(res, {
+        enabled: logger.isEnabled(),
+    });
+}
+async function handleExportTrajectories(req, res, runtime) {
+    const logger = await getTrajectoryLogger(runtime);
+    if (!logger) {
+        sendJsonError(res, "Trajectories service not available", 503);
+        return;
+    }
+    const body = await parseJsonBody(req, res);
+    if (!body)
+        return;
+    if (body.format === "zip") {
+        if (typeof logger.exportTrajectoriesZip !== "function") {
+            sendJsonError(res, "Trajectory ZIP export is unavailable in the active logger", 503);
+            return;
+        }
+        const zipOptions = {
+            includePrompts: body.includePrompts,
+            trajectoryIds: body.trajectoryIds,
+            startDate: body.startDate,
+            endDate: body.endDate,
+            scenarioId: body.scenarioId,
+            batchId: body.batchId,
+        };
+        const zipResult = await logger.exportTrajectoriesZip(zipOptions);
+        const archive = createZipArchive(zipResult.entries);
+        res.statusCode = 200;
+        res.setHeader("Content-Type", "application/zip");
+        res.setHeader("Content-Disposition", `attachment; filename="${zipResult.filename}"`);
+        res.end(archive);
+        return;
+    }
+    if (body.format !== "json" &&
+        body.format !== "csv" &&
+        body.format !== "art") {
+        sendJsonError(res, "Format must be 'json', 'csv', 'art', or 'zip'", 400);
+        return;
+    }
+    const result = await logger.exportTrajectories({
+        format: body.format,
+        includePrompts: body.includePrompts,
+        trajectoryIds: body.trajectoryIds,
+        startDate: body.startDate,
+        endDate: body.endDate,
+        scenarioId: body.scenarioId,
+        batchId: body.batchId,
+    });
+    res.statusCode = 200;
+    res.setHeader("Content-Type", result.mimeType);
+    res.setHeader("Content-Disposition", `attachment; filename="${result.filename}"`);
+    res.end(result.data);
+}
+async function handleDeleteTrajectories(req, res, runtime) {
+    const logger = await getTrajectoryLogger(runtime);
+    if (!logger) {
+        sendJsonError(res, "Trajectories service not available", 503);
+        return;
+    }
+    const body = await parseJsonBody(req, res);
+    if (!body)
+        return;
+    if (body.clearAll || body.all) {
+        const deletedCount = await logger.clearAllTrajectories();
+        sendJson(res, { deleted: deletedCount });
+        return;
+    }
+    if (Array.isArray(body.trajectoryIds) && body.trajectoryIds.length > 0) {
+        const deletedCount = await logger.deleteTrajectories(body.trajectoryIds);
+        sendJson(res, { deleted: deletedCount });
+        return;
+    }
+    sendJson(res, { deleted: 0 });
+}
+// ============================================================================
+// Main Router
+// ============================================================================
+export async function handleTrajectoryRoute(req, res, runtime, pathname, method) {
+    if (!pathname.startsWith("/api/trajectories"))
+        return false;
+    // GET /api/trajectories/config
+    if (pathname === "/api/trajectories/config" && method === "GET") {
+        await handleGetConfig(req, res, runtime);
+        return true;
+    }
+    // PUT /api/trajectories/config
+    if (pathname === "/api/trajectories/config" && method === "PUT") {
+        await handlePutConfig(req, res, runtime);
+        return true;
+    }
+    // POST /api/trajectories/export
+    if (pathname === "/api/trajectories/export" && method === "POST") {
+        await handleExportTrajectories(req, res, runtime);
+        return true;
+    }
+    // DELETE /api/trajectories
+    if (pathname === "/api/trajectories" && method === "DELETE") {
+        await handleDeleteTrajectories(req, res, runtime);
+        return true;
+    }
+    // GET /api/trajectories/stats
+    if (pathname === "/api/trajectories/stats" && method === "GET") {
+        await handleGetStats(req, res, runtime);
+        return true;
+    }
+    // GET /api/trajectories/:id
+    const detailMatch = pathname.match(/^\/api\/trajectories\/([^/]+)$/);
+    if (detailMatch && method === "GET") {
+        await handleGetTrajectoryDetail(req, res, runtime, detailMatch[1]);
+        return true;
+    }
+    // GET /api/trajectories
+    if (pathname === "/api/trajectories" && method === "GET") {
+        await handleGetTrajectories(req, res, runtime);
+        return true;
+    }
+    return false;
+}