@elizaos/agent 0.25.9 → 2.0.0-alpha.151

package/packages/agent/src/runtime/trajectory-storage.js

@@ -0,0 +1,1026 @@
+/**
+ * Trajectory storage — write operations.
+ *
+ * Handles saving, updating, deleting trajectories, installing the database
+ * logger, and the DatabaseTrajectoryLogger service class.
+ */
+import path from "node:path";
+import { logger as coreLogger, Service, } from "@elizaos/core";
+import { asRecord, computeBySource, createBaseTrajectory, enqueueStepWrite, enrichTrajectoryLlmCall, ensureStep, ensureTrajectoriesTable, executeRawSql, extractInsightsFromResponse, extractRows, hasRuntimeDb, lastWritePromises, loadTrajectoryById, mergeMetadata, normalizeLlmCallPayload, normalizeProviderAccessPayload, normalizeStatus, normalizeStepId, normalizeTrajectoryMetadata, parseMetadata, patchedLoggers, pushChatExchange, readOrchestratorTrajectoryContext, resolveTrajectoryArchiveDirectory, resolveTrajectoryLogger, saveTrajectory, shouldEnableTrajectoryLoggingByDefault, shouldRunObservationExtraction, shouldSuppressNoInputEmbeddingCall, sqlQuote, stepWriteQueues, toArchiveSafeTimestamp, toNumber, toOptionalNumber, toText, truncateRecord, warnRuntime, writeCompressedJsonlRows, } from "./trajectory-internals.js";
+// ---------------------------------------------------------------------------
+// appendLlmCall / appendProviderAccess
+// ---------------------------------------------------------------------------
+async function appendLlmCall(runtime, stepId, params) {
+    if (shouldSuppressNoInputEmbeddingCall(params))
+        return;
+    const now = toNumber(params.timestamp, Date.now());
+    const trajectory = (await loadTrajectoryById(runtime, stepId)) ??
+        createBaseTrajectory(stepId, now);
+    trajectory.source = trajectory.source || "runtime";
+    trajectory.status =
+        trajectory.status === "active" ? "active" : trajectory.status;
+    const orchestratorCtx = readOrchestratorTrajectoryContext(runtime);
+    const fullResponse = toText(params.response, "");
+    const purpose = orchestratorCtx?.decisionType ?? toText(params.purpose, "action");
+    const insights = extractInsightsFromResponse(fullResponse, purpose);
+    const step = ensureStep(trajectory, stepId, now);
+    const call = enrichTrajectoryLlmCall({
+        callId: toText(params.callId, `${stepId}-call-${step.llmCalls.length + 1}`),
+        timestamp: now,
+        model: toText(params.model, "unknown"),
+        systemPrompt: toText(params.systemPrompt, ""),
+        userPrompt: toText(params.userPrompt ?? params.input, ""),
+        response: fullResponse,
+        temperature: toNumber(params.temperature, 0),
+        maxTokens: toNumber(params.maxTokens, 0),
+        purpose,
+        actionType: orchestratorCtx
+            ? "orchestrator.useModel"
+            : toText(params.actionType, "runtime.useModel"),
+        latencyMs: toNumber(params.latencyMs, 0),
+    });
+    const promptTokens = toOptionalNumber(params.promptTokens);
+    const completionTokens = toOptionalNumber(params.completionTokens);
+    if (promptTokens !== undefined)
+        call.promptTokens = promptTokens;
+    if (completionTokens !== undefined)
+        call.completionTokens = completionTokens;
+    step.llmCalls.push(call);
+    trajectory.startTime = Math.min(trajectory.startTime, now);
+    trajectory.endTime = Math.max(trajectory.endTime ?? now, now);
+    trajectory.updatedAt = new Date(now).toISOString();
+    if (insights.length > 0) {
+        const meta = (trajectory.metadata ?? {});
+        const existing = Array.isArray(meta.insights)
+            ? meta.insights
+            : [];
+        meta.insights = [...existing, ...insights].slice(-20);
+        trajectory.metadata = meta;
+    }
+    if (!orchestratorCtx &&
+        trajectory.source === "chat" &&
+        shouldRunObservationExtraction(runtime)) {
+        pushChatExchange(runtime, {
+            userPrompt: toText(params.userPrompt ?? params.input, ""),
+            response: fullResponse,
+            trajectoryId: trajectory.id,
+            timestamp: now,
+        });
+    }
+    if (orchestratorCtx) {
+        trajectory.source = "orchestrator";
+        const meta = (trajectory.metadata ?? {});
+        meta.orchestrator = {
+            decisionType: orchestratorCtx.decisionType,
+            ...(orchestratorCtx.sessionId && {
+                sessionId: orchestratorCtx.sessionId,
+            }),
+            ...(orchestratorCtx.taskLabel && {
+                taskLabel: orchestratorCtx.taskLabel,
+            }),
+            ...(orchestratorCtx.repo && {
+                repo: orchestratorCtx.repo,
+            }),
+            ...(orchestratorCtx.workdir && {
+                workdir: orchestratorCtx.workdir,
+            }),
+            ...(orchestratorCtx.originalTask && {
+                originalTask: orchestratorCtx.originalTask,
+            }),
+        };
+        trajectory.metadata = meta;
+    }
+    await saveTrajectory(runtime, trajectory);
+}
+async function appendProviderAccess(runtime, stepId, params) {
+    const now = toNumber(params.timestamp, Date.now());
+    const trajectory = (await loadTrajectoryById(runtime, stepId)) ??
+        createBaseTrajectory(stepId, now);
+    trajectory.source = trajectory.source || "runtime";
+    trajectory.status =
+        trajectory.status === "active" ? "active" : trajectory.status;
+    const step = ensureStep(trajectory, stepId, now);
+    const access = {
+        providerId: toText(params.providerId, `${stepId}-provider-${step.providerAccesses.length + 1}`),
+        providerName: toText(params.providerName, "unknown"),
+        timestamp: now,
+        data: truncateRecord(asRecord(params.data) ?? {}),
+        query: (() => {
+            const queryRecord = asRecord(params.query);
+            return queryRecord ? truncateRecord(queryRecord) : undefined;
+        })(),
+        purpose: toText(params.purpose, "provider"),
+    };
+    step.providerAccesses.push(access);
+    trajectory.startTime = Math.min(trajectory.startTime, now);
+    trajectory.endTime = Math.max(trajectory.endTime ?? now, now);
+    trajectory.updatedAt = new Date(now).toISOString();
+    await saveTrajectory(runtime, trajectory);
+}
+// ---------------------------------------------------------------------------
+// writeStartedTrajectoryStep / writeCompletedTrajectoryStep
+// ---------------------------------------------------------------------------
+async function writeStartedTrajectoryStep({ runtime, stepId, source, metadata, }) {
+    const now = Date.now();
+    const trajectory = (await loadTrajectoryById(runtime, stepId)) ??
+        createBaseTrajectory(stepId, now, source, metadata);
+    trajectory.source = source?.trim() || trajectory.source || "runtime";
+    trajectory.status = "active";
+    trajectory.metadata = mergeMetadata(trajectory.metadata, metadata);
+    trajectory.startTime = Math.min(trajectory.startTime, now);
+    trajectory.endTime = null;
+    ensureStep(trajectory, stepId, now);
+    trajectory.updatedAt = new Date(now).toISOString();
+    await saveTrajectory(runtime, trajectory);
+}
+async function writeCompletedTrajectoryStep({ runtime, stepId, status = "completed", source, metadata, }) {
+    const now = Date.now();
+    const trajectory = (await loadTrajectoryById(runtime, stepId)) ??
+        createBaseTrajectory(stepId, now, source, metadata);
+    trajectory.source = source?.trim() || trajectory.source || "runtime";
+    trajectory.status = normalizeStatus(status, "completed");
+    trajectory.metadata = mergeMetadata(trajectory.metadata, metadata);
+    trajectory.endTime = Math.max(trajectory.endTime ?? now, now);
+    trajectory.startTime = Math.min(trajectory.startTime, now);
+    ensureStep(trajectory, stepId, now);
+    trajectory.updatedAt = new Date(now).toISOString();
+    await saveTrajectory(runtime, trajectory);
+}
+function buildTrajectoryWhereClauses(options) {
+    const whereClauses = [];
+    if (options.source) {
+        whereClauses.push(`source = ${sqlQuote(options.source)}`);
+    }
+    if (options.status) {
+        whereClauses.push(`status = ${sqlQuote(options.status)}`);
+    }
+    if (options.scenarioId) {
+        whereClauses.push(`scenario_id = ${sqlQuote(options.scenarioId)}`);
+    }
+    if (options.batchId) {
+        whereClauses.push(`batch_id = ${sqlQuote(options.batchId)}`);
+    }
+    if (options.startDate) {
+        const startTime = new Date(options.startDate).getTime();
+        if (Number.isFinite(startTime)) {
+            whereClauses.push(`start_time >= ${startTime}`);
+        }
+    }
+    if (options.endDate) {
+        const endTime = new Date(options.endDate).getTime();
+        if (Number.isFinite(endTime)) {
+            whereClauses.push(`start_time <= ${endTime}`);
+        }
+    }
+    if (options.search) {
+        const searchPattern = `%${options.search.toLowerCase().replace(/[%_]/g, "\\$&")}%`;
+        const quotedPattern = sqlQuote(searchPattern);
+        whereClauses.push(`(
+        LOWER(COALESCE(id, '')) LIKE ${quotedPattern}
+        OR LOWER(COALESCE(scenario_id, '')) LIKE ${quotedPattern}
+        OR LOWER(COALESCE(batch_id, '')) LIKE ${quotedPattern}
+        OR LOWER(COALESCE(CAST(metadata AS TEXT), '')) LIKE ${quotedPattern}
+        OR LOWER(COALESCE(CAST(steps_json AS TEXT), '')) LIKE ${quotedPattern}
+      )`);
+    }
+    return whereClauses;
+}
+function buildTrajectoryWhereClause(options) {
+    const whereClauses = buildTrajectoryWhereClauses(options);
+    return whereClauses.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : "";
+}
+function rowToTrajectoryListItem(row, agentId) {
+    const r = asRecord(row);
+    if (!r)
+        return null;
+    const normalizedMetadata = normalizeTrajectoryMetadata(parseMetadata(r.metadata), {
+        scenarioId: r.scenario_id,
+        batchId: r.batch_id,
+    });
+    return {
+        id: toText(r.id ?? r.trajectory_id, ""),
+        agentId: toText(r.agent_id, agentId),
+        source: toText(r.source, "runtime"),
+        status: normalizeStatus(r.status, "completed"),
+        startTime: toNumber(r.start_time, Date.now()),
+        endTime: toOptionalNumber(r.end_time) ?? null,
+        durationMs: toOptionalNumber(r.duration_ms) ?? null,
+        stepCount: toNumber(r.step_count, 0),
+        llmCallCount: toNumber(r.llm_call_count, 0),
+        providerAccessCount: toNumber(r.provider_access_count, 0),
+        totalPromptTokens: toNumber(r.total_prompt_tokens, 0),
+        totalCompletionTokens: toNumber(r.total_completion_tokens, 0),
+        scenarioId: normalizedMetadata.scenarioId,
+        batchId: normalizedMetadata.batchId,
+        createdAt: toText(r.created_at, new Date(toNumber(r.start_time, Date.now())).toISOString()),
+        metadata: normalizedMetadata.metadata,
+    };
+}
+// ---------------------------------------------------------------------------
+// Public write API
+// ---------------------------------------------------------------------------
+export async function installDatabaseTrajectoryLogger(runtime) {
+    if (!hasRuntimeDb(runtime)) {
+        console.warn("[trajectory-persistence] installDatabaseTrajectoryLogger: no database adapter found on runtime");
+        return;
+    }
+    const logger = await resolveTrajectoryLogger(runtime);
+    if (!logger) {
+        console.warn("[trajectory-persistence] installDatabaseTrajectoryLogger: no logger found to patch");
+        return;
+    }
+    const loggerObject = logger;
+    if (patchedLoggers.has(loggerObject))
+        return;
+    const shouldEnableByDefault = shouldEnableTrajectoryLoggingByDefault();
+    const isEnabled = typeof logger.isEnabled === "function"
+        ? logger.isEnabled()
+        : shouldEnableByDefault;
+    if (typeof logger.setEnabled === "function" &&
+        isEnabled !== shouldEnableByDefault) {
+        try {
+            logger.setEnabled(shouldEnableByDefault);
+        }
+        catch {
+            // Ignore logger enable failures and continue.
+        }
+    }
+    if (Array.isArray(logger.llmCalls)) {
+        logger.llmCalls.splice(0, logger.llmCalls.length);
+    }
+    if (Array.isArray(logger.providerAccess)) {
+        logger.providerAccess.splice(0, logger.providerAccess.length);
+    }
+    const originalLogLlmCall = typeof logger.logLlmCall === "function"
+        ? logger.logLlmCall.bind(logger)
+        : null;
+    const originalLogProviderAccess = typeof logger.logProviderAccess === "function"
+        ? logger.logProviderAccess.bind(logger)
+        : null;
+    logger.logLlmCall = ((...args) => {
+        if (originalLogLlmCall) {
+            try {
+                originalLogLlmCall(...args);
+            }
+            catch (err) {
+                warnRuntime(runtime, "Trajectory logger logLlmCall threw", err);
+            }
+        }
+        const normalized = normalizeLlmCallPayload(args);
+        if (!normalized)
+            return;
+        const writePromise = enqueueStepWrite(runtime, normalized.stepId, async () => {
+            const tableReady = await ensureTrajectoriesTable(runtime);
+            if (!tableReady)
+                return;
+            await appendLlmCall(runtime, normalized.stepId, normalized.params);
+        });
+        const runtimeKey = runtime;
+        lastWritePromises.set(runtimeKey, writePromise);
+    });
+    logger.logProviderAccess = ((...args) => {
+        if (originalLogProviderAccess) {
+            try {
+                originalLogProviderAccess(...args);
+            }
+            catch (err) {
+                warnRuntime(runtime, "Trajectory logger logProviderAccess threw", err);
+            }
+        }
+        const normalized = normalizeProviderAccessPayload(args);
+        if (!normalized)
+            return;
+        const writePromise = enqueueStepWrite(runtime, normalized.stepId, async () => {
+            const tableReady = await ensureTrajectoriesTable(runtime);
+            if (!tableReady)
+                return;
+            await appendProviderAccess(runtime, normalized.stepId, normalized.params);
+        });
+        const runtimeKey = runtime;
+        lastWritePromises.set(runtimeKey, writePromise);
+    });
+    logger.getLlmCallLogs = () => [];
+    logger.getProviderAccessLogs = () => [];
+    const loggerAny = logger;
+    loggerAny.startTrajectory = async (stepIdOrAgentId, options) => {
+        const isLegacySignature = typeof options?.agentId === "string";
+        const stepId = isLegacySignature
+            ? stepIdOrAgentId
+            : `step-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const startMetadata = normalizeTrajectoryMetadata(options?.metadata, {
+            scenarioId: options?.scenarioId,
+            batchId: options?.batchId,
+        }).metadata;
+        const writePromise = enqueueStepWrite(runtime, stepId, async () => {
+            const tableReady = await ensureTrajectoriesTable(runtime);
+            if (!tableReady)
+                return;
+            await writeStartedTrajectoryStep({
+                runtime,
+                stepId,
+                source: options?.source ?? "chat",
+                metadata: startMetadata,
+            });
+        });
+        const runtimeKey = runtime;
+        lastWritePromises.set(runtimeKey, writePromise);
+        return stepId;
+    };
+    loggerAny.startStep = (trajectoryId) => {
+        return trajectoryId;
+    };
+    loggerAny.endTrajectory = async (stepIdOrTrajectoryId, status = "completed") => {
+        const writePromise = enqueueStepWrite(runtime, stepIdOrTrajectoryId, async () => {
+            const tableReady = await ensureTrajectoriesTable(runtime);
+            if (!tableReady)
+                return;
+            await writeCompletedTrajectoryStep({
+                runtime,
+                stepId: stepIdOrTrajectoryId,
+                status: status,
+            });
+        });
+        const runtimeKey = runtime;
+        lastWritePromises.set(runtimeKey, writePromise);
+    };
+    // Add query methods for API endpoints
+    loggerAny.listTrajectories = async (options = {}) => {
+        if (!hasRuntimeDb(runtime)) {
+            return { trajectories: [], total: 0, offset: 0, limit: 50 };
+        }
+        const tableReady = await ensureTrajectoriesTable(runtime);
+        if (!tableReady) {
+            return { trajectories: [], total: 0, offset: 0, limit: 50 };
+        }
+        const limit = Math.min(500, Math.max(1, options.limit ?? 50));
+        const offset = Math.max(0, options.offset ?? 0);
+        const whereClause = buildTrajectoryWhereClause(options);
+        try {
+            const countResult = await executeRawSql(runtime, `SELECT count(*) AS total FROM trajectories ${whereClause}`);
+            const countRow = asRecord(extractRows(countResult)[0]);
+            const total = toNumber(countRow?.total, 0);
+            const result = await executeRawSql(runtime, `SELECT * FROM trajectories ${whereClause} ORDER BY created_at DESC LIMIT ${limit} OFFSET ${offset}`);
+            const rows = extractRows(result);
+            const trajectories = rows
+                .map((row) => rowToTrajectoryListItem(row, runtime.agentId))
+                .filter(Boolean);
+            return { trajectories, total, offset, limit };
+        }
+        catch (err) {
+            console.error("[trajectory-persistence] listTrajectories error:", err);
+            return { trajectories: [], total: 0, offset, limit };
+        }
+    };
+    loggerAny.getTrajectoryDetail = async (trajectoryId) => {
+        if (!hasRuntimeDb(runtime))
+            return null;
+        const tableReady = await ensureTrajectoriesTable(runtime);
+        if (!tableReady)
+            return null;
+        const persisted = await loadTrajectoryById(runtime, trajectoryId);
+        if (!persisted)
+            return null;
+        return {
+            trajectoryId: persisted.id,
+            agentId: runtime.agentId,
+            startTime: persisted.startTime,
+            endTime: persisted.endTime ?? undefined,
+            durationMs: persisted.endTime
+                ? persisted.endTime - persisted.startTime
+                : undefined,
+            scenarioId: persisted.scenarioId,
+            batchId: persisted.batchId,
+            steps: persisted.steps.map((step) => ({
+                stepId: step.stepId,
+                timestamp: step.timestamp,
+                llmCalls: step.llmCalls.map((call) => enrichTrajectoryLlmCall(call)),
+                providerAccesses: step.providerAccesses,
+            })),
+            metrics: { finalStatus: persisted.status },
+            metadata: persisted.metadata,
+            stepsJson: JSON.stringify(persisted.steps),
+        };
+    };
+    loggerAny.getStats = async () => {
+        const emptyStats = {
+            totalTrajectories: 0,
+            totalLlmCalls: 0,
+            totalProviderAccesses: 0,
+            totalPromptTokens: 0,
+            totalCompletionTokens: 0,
+            averageDurationMs: 0,
+            bySource: {},
+            byModel: {},
+        };
+        if (!hasRuntimeDb(runtime))
+            return emptyStats;
+        const tableReady = await ensureTrajectoriesTable(runtime);
+        if (!tableReady)
+            return emptyStats;
+        try {
+            const aggResult = await executeRawSql(runtime, `SELECT
+          count(*) AS total,
+          COALESCE(sum(llm_call_count), 0) AS total_llm_calls,
+          COALESCE(sum(provider_access_count), 0) AS total_provider_accesses,
+          COALESCE(sum(total_prompt_tokens), 0) AS total_prompt_tokens,
+          COALESCE(sum(total_completion_tokens), 0) AS total_completion_tokens,
+          COALESCE(avg(duration_ms), 0) AS avg_duration_ms
+        FROM trajectories`);
+            const row = asRecord(extractRows(aggResult)[0]);
+            const bySource = await computeBySource(runtime);
+            return {
+                totalTrajectories: toNumber(row?.total, 0),
+                totalLlmCalls: toNumber(row?.total_llm_calls, 0),
+                totalProviderAccesses: toNumber(row?.total_provider_accesses, 0),
+                totalPromptTokens: toNumber(row?.total_prompt_tokens, 0),
+                totalCompletionTokens: toNumber(row?.total_completion_tokens, 0),
+                averageDurationMs: toNumber(row?.avg_duration_ms, 0),
+                bySource,
+                byModel: {},
+            };
+        }
+        catch {
+            return emptyStats;
+        }
+    };
+    // Add methods required by the trajectory-routes duck-type check
+    const loggerForRoutes = logger;
+    let _enabled = shouldEnableByDefault;
+    if (typeof loggerForRoutes.isEnabled !== "function") {
+        loggerForRoutes.isEnabled = () => _enabled;
+    }
+    if (typeof loggerForRoutes.setEnabled !== "function") {
+        loggerForRoutes.setEnabled = (enabled) => {
+            _enabled = enabled;
+        };
+    }
+    if (typeof loggerForRoutes.deleteTrajectories !== "function") {
+        loggerForRoutes.deleteTrajectories = async (trajectoryIds) => {
+            if (!hasRuntimeDb(runtime) || trajectoryIds.length === 0)
+                return 0;
+            const tableReady = await ensureTrajectoriesTable(runtime);
+            if (!tableReady)
+                return 0;
+            const ids = trajectoryIds.map((id) => sqlQuote(id)).join(", ");
+            try {
+                await executeRawSql(runtime, `DELETE FROM trajectories WHERE id IN (${ids})`);
+                return trajectoryIds.length;
+            }
+            catch {
+                return 0;
+            }
+        };
+    }
+    if (typeof loggerForRoutes.clearAllTrajectories !== "function") {
+        loggerForRoutes.clearAllTrajectories = async () => {
+            if (!hasRuntimeDb(runtime))
+                return 0;
+            const tableReady = await ensureTrajectoriesTable(runtime);
+            if (!tableReady)
+                return 0;
+            try {
+                const countResult = await executeRawSql(runtime, "SELECT count(*) AS total FROM trajectories");
+                const countRow = asRecord(extractRows(countResult)[0]);
+                const total = toNumber(countRow?.total, 0);
+                await executeRawSql(runtime, "DELETE FROM trajectories");
+                return total;
+            }
+            catch {
+                return 0;
+            }
+        };
+    }
+    if (typeof loggerForRoutes.exportTrajectories !== "function") {
+        loggerForRoutes.exportTrajectories = async (options) => {
+            if (!hasRuntimeDb(runtime)) {
+                return {
+                    filename: `trajectories.${options.format}`,
+                    data: options.format === "json" ? "[]" : "",
+                    mimeType: options.format === "json" ? "application/json" : "text/plain",
+                };
+            }
+            const tableReady = await ensureTrajectoriesTable(runtime);
+            if (!tableReady) {
+                return {
+                    filename: `trajectories.${options.format}`,
+                    data: options.format === "json" ? "[]" : "",
+                    mimeType: options.format === "json" ? "application/json" : "text/plain",
+                };
+            }
+            const whereClauses = [];
+            if (options.trajectoryIds && options.trajectoryIds.length > 0) {
+                const ids = options.trajectoryIds.map((id) => sqlQuote(id)).join(", ");
+                whereClauses.push(`id IN (${ids})`);
+            }
+            const whereClause = whereClauses.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : "";
+            try {
+                const result = await executeRawSql(runtime, `SELECT * FROM trajectories ${whereClause} ORDER BY created_at DESC`);
+                const rows = extractRows(result);
+                const data = JSON.stringify(rows, null, 2);
+                return {
+                    filename: "trajectories.json",
+                    data,
+                    mimeType: "application/json",
+                };
+            }
+            catch {
+                return {
+                    filename: "trajectories.json",
+                    data: "[]",
+                    mimeType: "application/json",
+                };
+            }
+        };
+    }
+    patchedLoggers.add(loggerObject);
+    void ensureTrajectoriesTable(runtime).catch((err) => {
+        coreLogger.warn(`[trajectory] Trajectories table init failed: ${err}`);
+    });
+}
+export async function startTrajectoryStepInDatabase({ runtime, stepId, source, metadata, }) {
+    if (!hasRuntimeDb(runtime))
+        return false;
+    const normalizedStepId = normalizeStepId(stepId);
+    if (!normalizedStepId)
+        return false;
+    const tableReady = await ensureTrajectoriesTable(runtime);
+    if (!tableReady)
+        return false;
+    await enqueueStepWrite(runtime, normalizedStepId, async () => {
+        await writeStartedTrajectoryStep({
+            runtime,
+            stepId: normalizedStepId,
+            source,
+            metadata,
+        });
+    });
+    return true;
+}
+export async function completeTrajectoryStepInDatabase({ runtime, stepId, status = "completed", source, metadata, }) {
+    if (!hasRuntimeDb(runtime))
+        return false;
+    const normalizedStepId = normalizeStepId(stepId);
+    if (!normalizedStepId)
+        return false;
+    const tableReady = await ensureTrajectoriesTable(runtime);
+    if (!tableReady)
+        return false;
+    await enqueueStepWrite(runtime, normalizedStepId, async () => {
+        await writeCompletedTrajectoryStep({
+            runtime,
+            stepId: normalizedStepId,
+            status,
+            source,
+            metadata,
+        });
+    });
+    return true;
+}
+export async function deletePersistedTrajectoryRows(runtime, trajectoryIds) {
+    if (!hasRuntimeDb(runtime))
+        return null;
+    const tableReady = await ensureTrajectoriesTable(runtime);
+    if (!tableReady)
+        return 0;
+    const normalized = trajectoryIds
+        .map((id) => id.trim())
+        .filter((id) => id.length > 0);
+    if (normalized.length === 0)
+        return 0;
+    const values = normalized.map((id) => sqlQuote(id)).join(", ");
+    try {
+        const result = await executeRawSql(runtime, `DELETE FROM trajectories WHERE id IN (${values}) RETURNING id`);
+        return extractRows(result).length;
+    }
+    catch {
+        try {
+            await executeRawSql(runtime, `DELETE FROM trajectories WHERE id IN (${values})`);
+            return normalized.length;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+export async function clearPersistedTrajectoryRows(runtime) {
+    if (!hasRuntimeDb(runtime))
+        return null;
+    const tableReady = await ensureTrajectoriesTable(runtime);
+    if (!tableReady)
+        return 0;
+    try {
+        const countResult = await executeRawSql(runtime, "SELECT count(*) AS total FROM trajectories");
+        const countRow = asRecord(extractRows(countResult)[0]);
+        const total = toNumber(countRow?.total, 0);
+        await executeRawSql(runtime, "DELETE FROM trajectories");
+        return total;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Wait for all pending trajectory writes to complete.
+ * Useful for tests to ensure writes are flushed before assertions.
+ */
+export async function flushTrajectoryWrites(runtime) {
+    const runtimeKey = runtime;
+    const perStep = stepWriteQueues.get(runtimeKey);
+    if (perStep) {
+        const pending = Array.from(perStep.values());
+        if (pending.length > 0) {
+            await Promise.all(pending);
+        }
+    }
+    const lastWrite = lastWritePromises.get(runtimeKey);
+    if (lastWrite) {
+        await lastWrite;
+    }
+}
+// ============================================================================
+// DatabaseTrajectoryLogger - Full implementation for trajectory-routes.ts
+// ============================================================================
+/**
+ * Database-backed trajectory logger service that implements the full API
+ * expected by trajectory-routes.ts.
+ */
+export class DatabaseTrajectoryLogger extends Service {
+    static serviceType = "trajectories";
+    capabilityDescription = "Database-backed trajectory logging service for LLM call persistence";
+    enabled = shouldEnableTrajectoryLoggingByDefault();
+    /**
+     * Static start method required by @elizaos/core runtime.
+     */
+    static async start(runtime) {
+        const service = new DatabaseTrajectoryLogger(runtime);
+        await service.initialize();
+        return service;
+    }
+    async initialize() {
+        if (hasRuntimeDb(this.runtime)) {
+            await ensureTrajectoriesTable(this.runtime);
+            // Fire-and-forget TTL pruning on startup
+            pruneOldTrajectories(this.runtime, 30)
+                .then((count) => {
+                if (count && count > 0) {
+                    console.warn(`[trajectory-persistence] Pruned ${count} trajectories older than 30 days`);
+                }
+            })
+                .catch(() => {
+                /* non-critical */
+            });
+        }
+    }
+    async stop() {
+        await flushTrajectoryWrites(this.runtime);
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    setEnabled(enabled) {
+        this.enabled = enabled;
+    }
+    async startTrajectory(stepIdOrAgentId, options) {
+        if (!this.enabled)
+            return stepIdOrAgentId;
+        const isLegacySignature = typeof options?.agentId === "string";
+        const stepId = isLegacySignature
+            ? stepIdOrAgentId
+            : `step-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const writePromise = enqueueStepWrite(this.runtime, stepId, async () => {
+            const tableReady = await ensureTrajectoriesTable(this.runtime);
+            if (!tableReady)
+                return;
+            await writeStartedTrajectoryStep({
+                runtime: this.runtime,
+                stepId,
+                source: options?.source ?? "chat",
+                metadata: options?.metadata,
+            });
+        });
+        const runtimeKey = this.runtime;
+        lastWritePromises.set(runtimeKey, writePromise);
+        return stepId;
+    }
+    startStep(trajectoryId) {
+        return trajectoryId;
+    }
+    async endTrajectory(stepIdOrTrajectoryId, status = "completed") {
+        if (!this.enabled)
+            return;
+        const writePromise = enqueueStepWrite(this.runtime, stepIdOrTrajectoryId, async () => {
+            const tableReady = await ensureTrajectoriesTable(this.runtime);
+            if (!tableReady)
+                return;
+            await writeCompletedTrajectoryStep({
+                runtime: this.runtime,
+                stepId: stepIdOrTrajectoryId,
+                status,
+            });
+        });
+        const runtimeKey = this.runtime;
+        lastWritePromises.set(runtimeKey, writePromise);
+    }
+    logLlmCall(params) {
+        if (!this.enabled)
+            return;
+        const normalized = normalizeLlmCallPayload([params]);
+        if (!normalized)
+            return;
+        const writePromise = enqueueStepWrite(this.runtime, normalized.stepId, async () => {
+            const tableReady = await ensureTrajectoriesTable(this.runtime);
+            if (!tableReady)
+                return;
+            await appendLlmCall(this.runtime, normalized.stepId, normalized.params);
+        });
+        const runtimeKey = this.runtime;
+        lastWritePromises.set(runtimeKey, writePromise);
+    }
+    logProviderAccess(params) {
+        if (!this.enabled)
+            return;
+        const normalized = normalizeProviderAccessPayload([params]);
+        if (!normalized)
+            return;
+        const writePromise = enqueueStepWrite(this.runtime, normalized.stepId, async () => {
+            const tableReady = await ensureTrajectoriesTable(this.runtime);
+            if (!tableReady)
+                return;
+            await appendProviderAccess(this.runtime, normalized.stepId, normalized.params);
+        });
+        const runtimeKey = this.runtime;
+        lastWritePromises.set(runtimeKey, writePromise);
+    }
+    getLlmCallLogs() {
+        return [];
+    }
+    getProviderAccessLogs() {
+        return [];
+    }
+    async listTrajectories(options) {
+        if (!hasRuntimeDb(this.runtime)) {
+            return { trajectories: [], total: 0, offset: 0, limit: 50 };
+        }
+        const tableReady = await ensureTrajectoriesTable(this.runtime);
+        if (!tableReady) {
+            return { trajectories: [], total: 0, offset: 0, limit: 50 };
+        }
+        const limit = Math.min(500, Math.max(1, options.limit ?? 50));
+        const offset = Math.max(0, options.offset ?? 0);
+        const whereClause = buildTrajectoryWhereClause(options);
+        try {
+            const countResult = await executeRawSql(this.runtime, `SELECT count(*) AS total FROM trajectories ${whereClause}`);
+            const countRow = asRecord(extractRows(countResult)[0]);
+            const total = toNumber(countRow?.total, 0);
+            const result = await executeRawSql(this.runtime, `SELECT * FROM trajectories ${whereClause} ORDER BY created_at DESC LIMIT ${limit} OFFSET ${offset}`);
+            const rows = extractRows(result);
+            const trajectories = rows
+                .map((row) => rowToTrajectoryListItem(row, this.runtime.agentId))
+                .filter(Boolean);
+            return { trajectories, total, offset, limit };
+        }
+        catch (err) {
+            console.error("[DatabaseTrajectoryLogger] listTrajectories error:", err);
+            return { trajectories: [], total: 0, offset, limit };
+        }
+    }
+    async getTrajectoryDetail(trajectoryId) {
+        if (!hasRuntimeDb(this.runtime))
+            return null;
+        const tableReady = await ensureTrajectoriesTable(this.runtime);
+        if (!tableReady)
+            return null;
+        const persisted = await loadTrajectoryById(this.runtime, trajectoryId);
+        if (!persisted)
+            return null;
+        return {
+            trajectoryId: persisted.id,
+            agentId: this.runtime.agentId,
+            startTime: persisted.startTime,
+            endTime: persisted.endTime ?? undefined,
+            durationMs: persisted.endTime
+                ? persisted.endTime - persisted.startTime
+                : undefined,
+            scenarioId: persisted.scenarioId,
+            batchId: persisted.batchId,
+            steps: persisted.steps.map((step) => ({
+                stepId: step.stepId,
+                timestamp: step.timestamp,
+                llmCalls: step.llmCalls.map((call) => enrichTrajectoryLlmCall(call)),
+                providerAccesses: step.providerAccesses,
+            })),
+            metrics: { finalStatus: persisted.status },
+            metadata: persisted.metadata,
+            stepsJson: JSON.stringify(persisted.steps),
+        };
+    }
+    async getStats() {
+        if (!hasRuntimeDb(this.runtime)) {
+            return { total: 0, byStatus: {}, bySource: {} };
+        }
+        const tableReady = await ensureTrajectoriesTable(this.runtime);
+        if (!tableReady) {
+            return { total: 0, byStatus: {}, bySource: {} };
+        }
+        try {
+            const countResult = await executeRawSql(this.runtime, "SELECT count(*) AS total FROM trajectories");
+            const countRow = asRecord(extractRows(countResult)[0]);
+            const total = toNumber(countRow?.total, 0);
+            const bySource = await computeBySource(this.runtime);
+            return {
+                total,
+                enabled: this.enabled,
+                byStatus: {},
+                bySource,
+            };
+        }
+        catch {
+            return { total: 0, byStatus: {}, bySource: {} };
+        }
+    }
+    async deleteTrajectories(trajectoryIds) {
+        const result = await deletePersistedTrajectoryRows(this.runtime, trajectoryIds);
+        return result ?? 0;
+    }
+    async clearAllTrajectories() {
+        const result = await clearPersistedTrajectoryRows(this.runtime);
+        return result ?? 0;
+    }
+    async exportTrajectories(options) {
+        const listResult = await this.listTrajectories({
+            limit: 10000,
+            startDate: options.startDate,
+            endDate: options.endDate,
+            scenarioId: options.scenarioId,
+            batchId: options.batchId,
+        });
+        let ids = listResult.trajectories.map((t) => t.id);
+        if (options.trajectoryIds && options.trajectoryIds.length > 0) {
+            const idSet = new Set(options.trajectoryIds);
+            ids = ids.filter((id) => idSet.has(id));
+        }
+        const trajectories = [];
+        for (const id of ids) {
+            const detail = await this.getTrajectoryDetail(id);
+            if (detail)
+                trajectories.push(detail);
+        }
+        if (options.format === "json") {
+            return {
+                filename: `trajectories-${Date.now()}.json`,
+                data: JSON.stringify(trajectories, null, 2),
+                mimeType: "application/json",
+            };
+        }
+        if (options.format === "csv") {
+            const rows = [
+                "id,agentId,startTime,endTime,status,llmCallCount,promptTokens,completionTokens",
+            ];
+            for (const t of trajectories) {
+                const llmCount = t.steps?.reduce((sum, s) => sum + (s.llmCalls?.length ?? 0), 0);
+                const promptTokens = t.steps?.reduce((sum, s) => sum +
+                    (s.llmCalls?.reduce((s2, c) => s2 + (c.promptTokens ?? 0), 0) ?? 0), 0);
+                const completionTokens = t.steps?.reduce((sum, s) => sum +
+                    (s.llmCalls?.reduce((s2, c) => s2 + (c.completionTokens ?? 0), 0) ??
+                        0), 0);
+                rows.push(`${t.trajectoryId},${t.agentId},${t.startTime},${t.endTime ?? ""},${t.metrics?.finalStatus ?? ""},${llmCount ?? 0},${promptTokens ?? 0},${completionTokens ?? 0}`);
+            }
+            return {
+                filename: `trajectories-${Date.now()}.csv`,
+                data: rows.join("\n"),
+                mimeType: "text/csv",
+            };
+        }
+        // Default to JSON for 'art' format
+        return {
+            filename: `trajectories-${Date.now()}.json`,
+            data: JSON.stringify(trajectories, null, 2),
+            mimeType: "application/json",
+        };
+    }
+}
+/**
+ * Create and register a database-backed trajectory logger service on the runtime.
+ */
+export function createDatabaseTrajectoryLogger(runtime) {
+    const logger = new DatabaseTrajectoryLogger(runtime);
+    return logger;
+}
+// ---------------------------------------------------------------------------
+// Archive / prune
+// ---------------------------------------------------------------------------
+async function exportRawTrajectoriesToCompressedArchive(runtime, cutoff, archivedAt) {
+    const rawRowsResult = await executeRawSql(runtime, `SELECT
+      id, id AS trajectory_id, agent_id, source, status, start_time, end_time,
+      duration_ms, step_count, llm_call_count, provider_access_count,
+      total_prompt_tokens, total_completion_tokens, total_reward, scenario_id,
+      batch_id, steps_json,
+      metadata, created_at, updated_at, episode_length, ai_judge_reward,
+      ai_judge_reasoning, archetype
+    FROM trajectories
+    WHERE created_at < ${sqlQuote(cutoff)}`);
+    const rawRows = extractRows(rawRowsResult)
+        .map((row) => asRecord(row))
+        .filter(Boolean);
+    if (rawRows.length === 0) {
+        return { archivePath: "", rowCount: 0 };
+    }
+    const archiveDir = await resolveTrajectoryArchiveDirectory();
+    const archiveName = `trajectories-before-${toArchiveSafeTimestamp(cutoff)}-archived-${toArchiveSafeTimestamp(archivedAt)}.jsonl.gz`;
+    const archivePath = path.join(archiveDir, archiveName);
+    await writeCompressedJsonlRows(archivePath, rawRows);
+    return { archivePath, rowCount: rawRows.length };
+}
+/**
+ * Archive and then delete trajectories older than `maxAgeDays`.
+ */
+export async function pruneOldTrajectories(runtime, maxAgeDays = 30) {
+    if (!hasRuntimeDb(runtime))
+        return null;
+    const tableReady = await ensureTrajectoriesTable(runtime);
+    if (!tableReady)
+        return 0;
+    const cutoff = new Date(Date.now() - maxAgeDays * 24 * 60 * 60 * 1000).toISOString();
+    const archivedAt = new Date().toISOString();
+    try {
+        // Step 1: Persist full training rows to compressed local archive.
+        let archivePath = "";
+        try {
+            const archived = await exportRawTrajectoriesToCompressedArchive(runtime, cutoff, archivedAt);
+            archivePath = archived.archivePath;
+            if (archived.rowCount > 0 && !archivePath) {
+                return 0;
+            }
+        }
+        catch (err) {
+            console.warn("[trajectory-persistence] Could not write compressed trajectory archive, skipping prune", err);
+            return null;
+        }
+        // Step 2: Copy summary rows to archive table (idempotent).
+        let summaryArchived = false;
+        try {
+            await executeRawSql(runtime, `INSERT OR IGNORE INTO trajectory_archive (
+          id, agent_id, source, status, start_time, end_time, duration_ms,
+          step_count, llm_call_count, provider_access_count,
+          total_prompt_tokens, total_completion_tokens, total_reward,
+          scenario_id, batch_id, metadata, observations, archive_blob_path,
+          created_at, updated_at, archived_at
+        )
+        SELECT
+          id, agent_id, source, status, start_time, end_time, duration_ms,
+          step_count, llm_call_count, provider_access_count,
+          total_prompt_tokens, total_completion_tokens, total_reward,
+          scenario_id, batch_id, metadata,
+          COALESCE(json_extract(metadata, '$.observations'), '[]'),
+          ${sqlQuote(archivePath)},
+          created_at, updated_at,
+          ${sqlQuote(archivedAt)}
+        FROM trajectories
+        WHERE created_at < ${sqlQuote(cutoff)}`);
+            summaryArchived = true;
+        }
+        catch {
+            // PostgreSQL uses ON CONFLICT DO NOTHING instead of INSERT OR IGNORE
+            try {
+                await executeRawSql(runtime, `INSERT INTO trajectory_archive (
+            id, agent_id, source, status, start_time, end_time, duration_ms,
+            step_count, llm_call_count, provider_access_count,
+            total_prompt_tokens, total_completion_tokens, total_reward,
+            scenario_id, batch_id, metadata, observations, archive_blob_path,
+            created_at, updated_at, archived_at
+          )
+          SELECT
+            id, agent_id, source, status, start_time, end_time, duration_ms,
+            step_count, llm_call_count, provider_access_count,
+            total_prompt_tokens, total_completion_tokens, total_reward,
+            scenario_id, batch_id, metadata,
+            COALESCE(metadata::json->>'observations', '[]'),
+            ${sqlQuote(archivePath)},
+            created_at, updated_at,
+            ${sqlQuote(archivedAt)}
+          FROM trajectories
+          WHERE created_at < ${sqlQuote(cutoff)}
+          ON CONFLICT (id) DO NOTHING`);
+                summaryArchived = true;
+            }
+            catch {
+                console.warn("[trajectory-persistence] Could not write summary trajectory archive rows");
+            }
+        }
+        if (!summaryArchived) {
+            console.warn("[trajectory-persistence] Summary archive insert failed, skipping prune delete");
+            return null;
+        }
+        // Step 3: Delete the archived rows from the main table.
+        const countResult = await executeRawSql(runtime, `SELECT count(*) AS total FROM trajectories WHERE created_at < ${sqlQuote(cutoff)}`);
+        const countRow = asRecord(extractRows(countResult)[0]);
+        const count = toNumber(countRow?.total, 0);
+        if (count > 0) {
+            await executeRawSql(runtime, `DELETE FROM trajectories WHERE created_at < ${sqlQuote(cutoff)}`);
+        }
+        return count;
+    }
+    catch {
+        return null;
+    }
+}