@elizaos/agent 2.0.0-alpha.97 → 2.0.0-beta.1

package/dist/packages/agent/src/runtime/trajectory-internals.js

@@ -0,0 +1,1281 @@
+/**
+ * Shared internal helpers for the trajectory persistence subsystem.
+ *
+ * This module contains types, utility functions, SQL helpers, schema management,
+ * and observation extraction logic used across trajectory-storage, trajectory-query,
+ * and trajectory-export modules. Not intended for direct external consumption.
+ */
+import { createHash } from "node:crypto";
+import { once } from "node:events";
+import { createWriteStream } from "node:fs";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { createGzip } from "node:zlib";
+import { composePrompt, logger as coreLogger, ModelType, observationExtractionTemplate, } from "@elizaos/core";
+import { asRecord } from "@elizaos/shared";
+export { asRecord };
+import { TRAJECTORY_STEP_SCRIPT_MAX_CHARS, } from "../types/trajectory.js";
+// ---------------------------------------------------------------------------
+// Module-level state
+// ---------------------------------------------------------------------------
+export const initializedRuntimes = new WeakSet();
+export const patchedLoggers = new WeakSet();
+export const stepWriteQueues = new WeakMap();
+export const lastWritePromises = new WeakMap();
+let cachedSqlRaw = null;
+// Module version - changes on each hot reload, ensuring schema checks run
+const SCHEMA_VERSION = Date.now();
+const schemaVersions = new WeakMap();
+export function toText(value, fallback = "") {
+    if (typeof value === "string")
+        return value;
+    if (value === undefined || value === null)
+        return fallback;
+    return String(value);
+}
+export function toOptionalText(value) {
+    const normalized = toText(value, "").trim();
+    return normalized.length > 0 ? normalized : undefined;
+}
+export function toNumber(value, fallback = 0) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string") {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return fallback;
+}
+export function toOptionalNumber(value) {
+    if (value === null || value === undefined)
+        return undefined;
+    const parsed = toNumber(value, Number.NaN);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+export function toOptionalBoolean(value) {
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "number")
+        return value !== 0;
+    if (typeof value !== "string")
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (["1", "true", "yes", "on", "enabled"].includes(normalized))
+        return true;
+    if (["0", "false", "no", "off", "disabled"].includes(normalized))
+        return false;
+    return undefined;
+}
+export function normalizeTrajectoryTag(value) {
+    const raw = toText(value, "").trim();
+    if (!raw)
+        return "";
+    return raw
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .toLowerCase()
+        .replace(/[^a-z0-9:]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .replace(/_+/g, "_");
+}
+function normalizeTrajectoryTagList(value) {
+    if (!Array.isArray(value))
+        return [];
+    const tags = [];
+    const seen = new Set();
+    for (const entry of value) {
+        const normalized = normalizeTrajectoryTag(entry);
+        if (!normalized || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        tags.push(normalized);
+    }
+    return tags;
+}
+const ORCHESTRATOR_STEP_TYPES = new Set([
+    "coordination",
+    "observation_extraction",
+    "orchestrator",
+    "turn_complete",
+]);
+export function inferTrajectoryLlmStepType(params) {
+    const existing = normalizeTrajectoryTag(params.stepType);
+    if (existing)
+        return existing;
+    const purpose = normalizeTrajectoryTag(params.purpose);
+    const actionType = normalizeTrajectoryTag(params.actionType);
+    if (purpose === "should_respond")
+        return "should_respond";
+    if (purpose === "compose_state" ||
+        purpose === "evaluation" ||
+        purpose === "reasoning" ||
+        purpose === "response" ||
+        purpose === "observation_extraction" ||
+        purpose === "turn_complete" ||
+        purpose === "coordination") {
+        return purpose;
+    }
+    if (actionType.startsWith("orchestrator_")) {
+        return "orchestrator";
+    }
+    if (purpose === "action")
+        return "action";
+    if (purpose && purpose !== "other")
+        return purpose;
+    if (actionType)
+        return actionType;
+    return purpose;
+}
+export function inferTrajectoryLlmTags(params) {
+    const stepType = inferTrajectoryLlmStepType(params);
+    const purpose = normalizeTrajectoryTag(params.purpose);
+    const actionType = normalizeTrajectoryTag(params.actionType);
+    const tags = normalizeTrajectoryTagList(params.tags);
+    const seen = new Set(tags);
+    const push = (value) => {
+        const normalized = normalizeTrajectoryTag(value);
+        if (!normalized || seen.has(normalized))
+            return;
+        seen.add(normalized);
+        tags.push(normalized);
+    };
+    push("llm");
+    if (stepType)
+        push(`step:${stepType}`);
+    if (purpose)
+        push(`purpose:${purpose}`);
+    if (actionType)
+        push(`action:${actionType}`);
+    if (stepType === "should_respond")
+        push("routing");
+    if (stepType === "compose_state")
+        push("context");
+    if (ORCHESTRATOR_STEP_TYPES.has(stepType) ||
+        actionType.startsWith("orchestrator_")) {
+        push("orchestrator");
+    }
+    return tags;
+}
+export function enrichTrajectoryLlmCall(call) {
+    const stepType = inferTrajectoryLlmStepType({
+        stepType: call.stepType,
+        purpose: call.purpose,
+        actionType: call.actionType,
+        model: call.model,
+    });
+    const tags = inferTrajectoryLlmTags({
+        stepType,
+        purpose: call.purpose,
+        actionType: call.actionType,
+        model: call.model,
+        tags: call.tags,
+    });
+    return {
+        ...call,
+        ...(stepType ? { stepType } : {}),
+        ...(tags.length > 0 ? { tags } : {}),
+    };
+}
+export function hasActionNamed(runtime, name) {
+    const actions = runtime.actions;
+    if (!Array.isArray(actions))
+        return false;
+    const target = name.trim().toUpperCase();
+    return actions.some((action) => {
+        const actionName = action?.name?.trim().toUpperCase() ?? "";
+        return actionName === target;
+    });
+}
+export function readRecordValue(record, keys) {
+    for (const key of keys) {
+        if (key in record)
+            return record[key];
+    }
+    return undefined;
+}
+export function parseJsonValue(value) {
+    if (typeof value !== "string")
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+const TRAJECTORY_SCENARIO_METADATA_KEYS = ["scenarioId", "scenario_id"];
+const TRAJECTORY_BATCH_METADATA_KEYS = ["batchId", "batch_id"];
+function readGroupingValue(metadata, keys) {
+    return toOptionalText(readRecordValue(metadata, keys));
+}
+export function resolveTrajectoryGrouping(metadata, fallback) {
+    const record = metadata ?? {};
+    const scenarioId = readGroupingValue(record, TRAJECTORY_SCENARIO_METADATA_KEYS) ??
+        toOptionalText(fallback?.scenarioId);
+    const batchId = readGroupingValue(record, TRAJECTORY_BATCH_METADATA_KEYS) ??
+        toOptionalText(fallback?.batchId);
+    return { scenarioId, batchId };
+}
+export function normalizeTrajectoryMetadata(metadata, fallback) {
+    const normalizedMetadata = {
+        ...(metadata ?? {}),
+    };
+    const { scenarioId, batchId } = resolveTrajectoryGrouping(normalizedMetadata, fallback);
+    if (scenarioId) {
+        normalizedMetadata.scenarioId = scenarioId;
+    }
+    else {
+        delete normalizedMetadata.scenarioId;
+    }
+    if (batchId) {
+        normalizedMetadata.batchId = batchId;
+    }
+    else {
+        delete normalizedMetadata.batchId;
+    }
+    return {
+        metadata: normalizedMetadata,
+        scenarioId,
+        batchId,
+    };
+}
+// ---------------------------------------------------------------------------
+// Truncation helpers
+// ---------------------------------------------------------------------------
+const DEFAULT_TRUNCATE_LIMIT = 500;
+export function truncateField(value, limit = DEFAULT_TRUNCATE_LIMIT) {
+    if (value.length <= limit * 2)
+        return value;
+    const removed = value.length - limit * 2;
+    return `${value.slice(0, limit)}\n[...truncated ${removed} chars...]\n${value.slice(-limit)}`;
+}
+export function truncateRecord(obj, limit = DEFAULT_TRUNCATE_LIMIT) {
+    const serialized = JSON.stringify(obj);
+    if (serialized.length <= limit * 2)
+        return obj;
+    return { _truncated: truncateField(serialized, limit) };
+}
+// ---------------------------------------------------------------------------
+// Script capture helpers
+// ---------------------------------------------------------------------------
+/**
+ * Cap a script source for inline persistence on a trajectory step. When the
+ * source exceeds `TRAJECTORY_STEP_SCRIPT_MAX_CHARS`, returns a truncated
+ * prefix together with the sha256 hex digest of the full source so callers
+ * can store the digest alongside.
+ */
+export function capScriptForPersistence(script) {
+    if (script.length <= TRAJECTORY_STEP_SCRIPT_MAX_CHARS) {
+        return { script };
+    }
+    const scriptHash = createHash("sha256").update(script, "utf8").digest("hex");
+    return {
+        script: script.slice(0, TRAJECTORY_STEP_SCRIPT_MAX_CHARS),
+        scriptHash,
+    };
+}
+// ---------------------------------------------------------------------------
+// Insight extraction
+// ---------------------------------------------------------------------------
+export function extractInsightsFromResponse(response, purpose) {
+    const insights = [];
+    const safeResponse = response.length > 100_000 ? response.slice(0, 100_000) : response;
+    const decisionPattern = /DECISION:[ \t]{0,1024}([^\n]{1,1024})/gi;
+    let match;
+    match = decisionPattern.exec(safeResponse);
+    while (match !== null) {
+        const decision = match[1];
+        if (decision) {
+            insights.push(decision.trim());
+        }
+        match = decisionPattern.exec(safeResponse);
+    }
+    const keyDecisionPattern = /"keyDecision"\s{0,32}:\s{0,32}"([^"]{1,1024})"/g;
+    match = keyDecisionPattern.exec(safeResponse);
+    while (match !== null) {
+        const keyDecision = match[1];
+        if (keyDecision) {
+            insights.push(keyDecision.trim());
+        }
+        match = keyDecisionPattern.exec(safeResponse);
+    }
+    if ((purpose === "turn-complete" || purpose === "coordination") &&
+        insights.length === 0) {
+        const reasoningMatch = safeResponse.match(/"reasoning"\s{0,32}:\s{0,32}"([^"]{20,200})"/);
+        const reasoning = reasoningMatch?.[1];
+        if (reasoning)
+            insights.push(reasoning.trim());
+    }
+    return insights;
+}
+// ---------------------------------------------------------------------------
+// Observation extraction
+// ---------------------------------------------------------------------------
+export function shouldRunObservationExtraction(runtime) {
+    const explicitSetting = runtime.getSetting("TRAJECTORY_OBSERVATION_EXTRACTION");
+    const explicitValue = toOptionalBoolean(explicitSetting);
+    if (explicitValue !== undefined)
+        return explicitValue;
+    if (hasActionNamed(runtime, "REFLECTION")) {
+        return false;
+    }
+    return true;
+}
+const OBSERVATION_BUFFER_THRESHOLD = 5;
+const OBSERVATION_FLUSH_INTERVAL_MS = 10 * 60 * 1000; // 10 minutes
+const observationBuffers = new WeakMap();
+const observationFlushTimers = new WeakMap();
+const observationFlushInProgress = new WeakMap();
+export const TRAJECTORY_ARCHIVE_DIRNAME = "trajectory-archive";
+function getObservationBuffer(runtime) {
+    const key = runtime;
+    let buffer = observationBuffers.get(key);
+    if (!buffer) {
+        buffer = [];
+        observationBuffers.set(key, buffer);
+    }
+    return buffer;
+}
+export function pushChatExchange(runtime, exchange) {
+    const buffer = getObservationBuffer(runtime);
+    buffer.push(exchange);
+    const key = runtime;
+    // Flush on threshold
+    if (buffer.length >= OBSERVATION_BUFFER_THRESHOLD) {
+        flushObservationBuffer(runtime).catch((err) => {
+            coreLogger.warn(`[trajectory] Observation buffer flush failed: ${err}`);
+        });
+        return;
+    }
+    // Set/reset flush timer
+    const existing = observationFlushTimers.get(key);
+    if (existing)
+        clearTimeout(existing);
+    observationFlushTimers.set(key, setTimeout(() => {
+        flushObservationBuffer(runtime).catch((err) => {
+            coreLogger.warn(`[trajectory] Observation buffer flush failed: ${err}`);
+        });
+    }, OBSERVATION_FLUSH_INTERVAL_MS));
+}
+export async function flushObservationBuffer(runtime) {
+    const key = runtime;
+    // Prevent concurrent flushes
+    if (observationFlushInProgress.get(key))
+        return [];
+    observationFlushInProgress.set(key, true);
+    const buffer = getObservationBuffer(runtime);
+    if (buffer.length === 0) {
+        observationFlushInProgress.set(key, false);
+        return [];
+    }
+    // Take the current buffer and reset
+    const exchanges = buffer.splice(0, buffer.length);
+    const timer = observationFlushTimers.get(key);
+    if (timer)
+        clearTimeout(timer);
+    // Build the extraction prompt
+    const exchangeText = exchanges
+        .map((e, i) => `Exchange ${i + 1}:\nUser: ${e.userPrompt.slice(0, 500)}\nAssistant: ${e.response.slice(0, 500)}`)
+        .join("\n\n");
+    const prompt = composePrompt({
+        state: { exchanges: exchangeText },
+        template: observationExtractionTemplate,
+    });
+    const runtimeRecord = runtime;
+    try {
+        // Tag the call to prevent recursion
+        runtimeRecord.__orchestratorTrajectoryCtx = {
+            source: "orchestrator",
+            decisionType: "observation-extraction",
+        };
+        const result = await runtime.useModel(ModelType.TEXT_SMALL, {
+            prompt,
+            maxTokens: 512,
+            temperature: 0,
+        });
+        // Parse the JSON response
+        const jsonMatch = result.match(/\[[\s\S]*\]/);
+        if (!jsonMatch)
+            return [];
+        const parsed = JSON.parse(jsonMatch[0]);
+        if (!Array.isArray(parsed))
+            return [];
+        const observations = parsed
+            .filter((s) => typeof s === "string" && s.length > 0)
+            .map((s) => s.slice(0, 150));
+        if (observations.length === 0)
+            return [];
+        // Write observations to the most recent trajectory in the batch
+        const lastExchange = exchanges[exchanges.length - 1];
+        if (!lastExchange) {
+            return observations;
+        }
+        const trajectory = await loadTrajectoryById(runtime, lastExchange.trajectoryId);
+        if (trajectory) {
+            const meta = (trajectory.metadata ?? {});
+            const existing = Array.isArray(meta.observations)
+                ? meta.observations
+                : [];
+            meta.observations = [...existing, ...observations].slice(-30);
+            trajectory.metadata = meta;
+            await saveTrajectory(runtime, trajectory);
+        }
+        return observations;
+    }
+    catch {
+        // Non-critical — observations are best-effort
+        return [];
+    }
+    finally {
+        delete runtimeRecord.__orchestratorTrajectoryCtx;
+        observationFlushInProgress.set(key, false);
+    }
+}
+// ---------------------------------------------------------------------------
+// SQL helpers
+// ---------------------------------------------------------------------------
+export function parseMetadata(value) {
+    const parsed = parseJsonValue(value);
+    const record = asRecord(parsed);
+    return record ?? {};
+}
+export function parseSteps(value) {
+    const parsed = parseJsonValue(value);
+    if (Array.isArray(parsed)) {
+        return parsed;
+    }
+    const record = asRecord(parsed);
+    if (!record)
+        return [];
+    const nested = parseJsonValue(readRecordValue(record, ["steps"]));
+    return Array.isArray(nested) ? nested : [];
+}
+export function sqlQuote(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+export function sqlNumber(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return "NULL";
+    return String(value);
+}
+export async function getSqlRaw() {
+    if (cachedSqlRaw)
+        return cachedSqlRaw;
+    const drizzle = (await import("drizzle-orm"));
+    cachedSqlRaw = drizzle.sql.raw;
+    return cachedSqlRaw;
+}
+export function getRuntimeDb(runtime) {
+    const adapterDb = runtime.adapter?.db;
+    // Legacy runtimes may expose `databaseAdapter` instead of `adapter`
+    const fallbackDb = runtime.databaseAdapter?.db;
+    const db = adapterDb || fallbackDb;
+    if (!db || typeof db.execute !== "function")
+        return null;
+    return db;
+}
+export function hasRuntimeDb(runtime) {
+    return Boolean(getRuntimeDb(runtime));
+}
+export async function executeRawSql(runtime, sqlText) {
+    const db = getRuntimeDb(runtime);
+    if (!db) {
+        throw new Error("runtime database adapter unavailable");
+    }
+    const raw = await getSqlRaw();
+    return db.execute(raw(sqlText));
+}
+export function extractRows(result) {
+    if (Array.isArray(result))
+        return result;
+    const record = asRecord(result);
+    if (!record)
+        return [];
+    return Array.isArray(record.rows) ? record.rows : [];
+}
+export async function computeBySource(runtime) {
+    try {
+        const result = await executeRawSql(runtime, "SELECT source, count(*) AS cnt FROM trajectories GROUP BY source");
+        const rows = extractRows(result);
+        const bySource = {};
+        for (const row of rows) {
+            const r = asRecord(row);
+            if (!r)
+                continue;
+            const src = typeof r.source === "string" ? r.source : "";
+            if (src)
+                bySource[src] = toNumber(r.cnt, 0);
+        }
+        return bySource;
+    }
+    catch {
+        return {};
+    }
+}
+export function warnRuntime(runtime, message, err) {
+    if (runtime.logger?.warn) {
+        runtime.logger.warn({ err, src: "eliza", subsystem: "trajectory-db" }, message);
+    }
+}
+// ---------------------------------------------------------------------------
+// Schema management
+// ---------------------------------------------------------------------------
+export async function ensureTrajectoriesTable(runtime) {
+    const key = runtime;
+    // Only skip if verified with current module version
+    if (schemaVersions.get(key) === SCHEMA_VERSION)
+        return true;
+    try {
+        // First, check if the table exists and has the correct schema
+        // by attempting to select all required columns
+        let needsRecreate = false;
+        try {
+            await executeRawSql(runtime, `SELECT id FROM trajectories LIMIT 1`);
+            // Table exists — try to add any missing columns via ALTER TABLE
+            // instead of dropping and losing all data.
+            const optionalColumns = [
+                { name: "trajectory_id", def: "TEXT" },
+                { name: "metadata", def: "TEXT NOT NULL DEFAULT '{}'" },
+                { name: "steps_json", def: "TEXT NOT NULL DEFAULT '[]'" },
+                { name: "scenario_id", def: "TEXT" },
+                { name: "batch_id", def: "TEXT" },
+                { name: "archetype", def: "TEXT" },
+                { name: "episode_length", def: "INTEGER" },
+                { name: "ai_judge_reward", def: "REAL" },
+                { name: "ai_judge_reasoning", def: "TEXT" },
+            ];
+            for (const col of optionalColumns) {
+                try {
+                    await executeRawSql(runtime, `ALTER TABLE trajectories ADD COLUMN ${col.name} ${col.def}`);
+                }
+                catch {
+                    // Column already exists — expected
+                }
+            }
+        }
+        catch {
+            // Table doesn't exist at all — create fresh (no data loss)
+            needsRecreate = true;
+            console.warn("[trajectory-persistence] Trajectories table does not exist, creating...");
+        }
+        await executeRawSql(runtime, `CREATE TABLE IF NOT EXISTS trajectories (
+        id TEXT PRIMARY KEY,
+        trajectory_id TEXT,
+        agent_id TEXT NOT NULL,
+        source TEXT NOT NULL DEFAULT 'runtime',
+        status TEXT NOT NULL DEFAULT 'completed',
+        start_time BIGINT NOT NULL,
+        end_time BIGINT,
+        duration_ms BIGINT,
+        step_count INTEGER NOT NULL DEFAULT 0,
+        llm_call_count INTEGER NOT NULL DEFAULT 0,
+        provider_access_count INTEGER NOT NULL DEFAULT 0,
+        total_prompt_tokens INTEGER NOT NULL DEFAULT 0,
+        total_completion_tokens INTEGER NOT NULL DEFAULT 0,
+        total_reward REAL NOT NULL DEFAULT 0,
+        scenario_id TEXT,
+        batch_id TEXT,
+        steps_json TEXT NOT NULL DEFAULT '[]',
+        metadata TEXT NOT NULL DEFAULT '{}',
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        episode_length INTEGER,
+        ai_judge_reward REAL,
+        ai_judge_reasoning TEXT,
+        archetype TEXT
+      )`);
+        // Archive table
+        await executeRawSql(runtime, `CREATE TABLE IF NOT EXISTS trajectory_archive (
+        id TEXT PRIMARY KEY,
+        agent_id TEXT NOT NULL,
+        source TEXT NOT NULL DEFAULT 'runtime',
+        status TEXT NOT NULL DEFAULT 'completed',
+        start_time BIGINT NOT NULL,
+        end_time BIGINT,
+        duration_ms BIGINT,
+        step_count INTEGER NOT NULL DEFAULT 0,
+        llm_call_count INTEGER NOT NULL DEFAULT 0,
+        provider_access_count INTEGER NOT NULL DEFAULT 0,
+        total_prompt_tokens INTEGER NOT NULL DEFAULT 0,
+        total_completion_tokens INTEGER NOT NULL DEFAULT 0,
+        total_reward REAL NOT NULL DEFAULT 0,
+        scenario_id TEXT,
+        batch_id TEXT,
+        metadata TEXT NOT NULL DEFAULT '{}',
+        observations TEXT NOT NULL DEFAULT '[]',
+        archive_blob_path TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        archived_at TEXT NOT NULL
+      )`);
+        // Best-effort forward migration for existing archive tables.
+        try {
+            await executeRawSql(runtime, `ALTER TABLE trajectory_archive ADD COLUMN archive_blob_path TEXT`);
+        }
+        catch {
+            // ignore when column already exists
+        }
+        // Best-effort forward migration for grouping columns.
+        try {
+            await executeRawSql(runtime, `ALTER TABLE trajectories ADD COLUMN scenario_id TEXT`);
+        }
+        catch {
+            // ignore when column already exists
+        }
+        try {
+            await executeRawSql(runtime, `CREATE INDEX IF NOT EXISTS idx_trajectories_scenario_id ON trajectories(scenario_id)`);
+        }
+        catch {
+            // ignore if index creation fails
+        }
+        try {
+            await executeRawSql(runtime, `ALTER TABLE trajectories ADD COLUMN batch_id TEXT`);
+        }
+        catch {
+            // ignore when column already exists
+        }
+        try {
+            await executeRawSql(runtime, `CREATE INDEX IF NOT EXISTS idx_trajectories_batch_id ON trajectories(batch_id)`);
+        }
+        catch {
+            // ignore if index creation fails
+        }
+        try {
+            await executeRawSql(runtime, `ALTER TABLE trajectory_archive ADD COLUMN scenario_id TEXT`);
+        }
+        catch {
+            // ignore when column already exists
+        }
+        try {
+            await executeRawSql(runtime, `ALTER TABLE trajectory_archive ADD COLUMN batch_id TEXT`);
+        }
+        catch {
+            // ignore when column already exists
+        }
+        if (needsRecreate) {
+            console.warn("[trajectory-persistence] Recreated trajectories table with updated schema");
+        }
+        schemaVersions.set(key, SCHEMA_VERSION);
+        initializedRuntimes.add(key);
+        return true;
+    }
+    catch (err) {
+        console.error("[trajectory-persistence] ensureTrajectoriesTable error:", err);
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Normalization helpers
+// ---------------------------------------------------------------------------
+export function normalizeStatus(value, fallback) {
+    const status = toText(value, "").toLowerCase();
+    if (status === "active" ||
+        status === "completed" ||
+        status === "error" ||
+        status === "timeout") {
+        return status;
+    }
+    return fallback;
+}
+export function normalizeStepId(value) {
+    const stepId = toText(value, "").trim();
+    return stepId.length > 0 ? stepId : null;
+}
+export function normalizeLlmCallPayload(args) {
+    if (args.length === 0)
+        return null;
+    if (typeof args[0] === "string") {
+        const stepId = normalizeStepId(args[0]);
+        const details = asRecord(args[1]);
+        if (!stepId || !details)
+            return null;
+        return {
+            stepId,
+            params: {
+                ...details,
+                stepId,
+            },
+        };
+    }
+    const params = asRecord(args[0]);
+    if (!params)
+        return null;
+    const stepId = normalizeStepId(params.stepId);
+    if (!stepId)
+        return null;
+    if (params.stepId === stepId) {
+        return {
+            stepId,
+            params,
+        };
+    }
+    return {
+        stepId,
+        params: {
+            ...params,
+            stepId,
+        },
+    };
+}
+export function normalizeProviderAccessPayload(args) {
+    if (args.length === 0)
+        return null;
+    if (typeof args[0] === "string") {
+        const stepId = normalizeStepId(args[0]);
+        const details = asRecord(args[1]);
+        if (!stepId || !details)
+            return null;
+        return {
+            stepId,
+            params: {
+                ...details,
+                stepId,
+            },
+        };
+    }
+    const params = asRecord(args[0]);
+    if (!params)
+        return null;
+    const stepId = normalizeStepId(params.stepId);
+    if (!stepId)
+        return null;
+    if (params.stepId === stepId) {
+        return {
+            stepId,
+            params,
+        };
+    }
+    return {
+        stepId,
+        params: {
+            ...params,
+            stepId,
+        },
+    };
+}
+export function isNumericVectorString(value) {
+    const trimmed = value.trim();
+    if (trimmed === "[array]")
+        return true;
+    if (!trimmed.startsWith("[") || !trimmed.endsWith("]"))
+        return false;
+    const inner = trimmed.slice(1, -1).trim();
+    if (!inner)
+        return false;
+    const parts = inner
+        .split(",")
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+    if (parts.length < 8)
+        return false;
+    const sampleSize = Math.min(parts.length, 16);
+    for (let i = 0; i < sampleSize; i += 1) {
+        const numeric = Number(parts[i]);
+        if (!Number.isFinite(numeric))
+            return false;
+    }
+    return true;
+}
+export function shouldSuppressNoInputEmbeddingCall(params) {
+    const model = toText(params.model, "").toLowerCase();
+    const actionType = toText(params.actionType, "").toLowerCase();
+    const purpose = toText(params.purpose, "").toLowerCase();
+    const isEmbedding = model.includes("embed") ||
+        actionType.includes("embed") ||
+        purpose.includes("embed");
+    if (!isEmbedding)
+        return false;
+    const userPrompt = toText(params.userPrompt ?? params.input, "").trim();
+    if (userPrompt.length > 0)
+        return false;
+    const response = toText(params.response, "");
+    if (!response.trim())
+        return true;
+    return isNumericVectorString(response);
+}
+export function isLegacyTrajectoryLogger(logger) {
+    return (typeof logger.listTrajectories === "function" &&
+        typeof logger.getTrajectoryDetail === "function");
+}
+export async function resolveTrajectoryLogger(runtime) {
+    const candidates = [];
+    const seen = new Set();
+    const push = (candidate) => {
+        if (!candidate || typeof candidate !== "object" || seen.has(candidate))
+            return;
+        seen.add(candidate);
+        candidates.push(candidate);
+    };
+    const byType = runtime.getServicesByType("trajectories");
+    if (Array.isArray(byType)) {
+        for (const item of byType)
+            push(item);
+    }
+    else {
+        push(byType);
+    }
+    push(runtime.getService("trajectories"));
+    if (candidates.length === 0)
+        return null;
+    let best = null;
+    let bestScore = -1;
+    for (const candidate of candidates) {
+        let score = 0;
+        if (isLegacyTrajectoryLogger(candidate))
+            score += 100;
+        if (typeof candidate.logLlmCall === "function")
+            score += 10;
+        if (typeof candidate.logProviderAccess === "function")
+            score += 10;
+        if (typeof candidate.getLlmCallLogs === "function")
+            score += 2;
+        if (typeof candidate.getProviderAccessLogs === "function")
+            score += 2;
+        if (score > bestScore) {
+            best = candidate;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+// ---------------------------------------------------------------------------
+// Trajectory data helpers
+// ---------------------------------------------------------------------------
+export function enqueueStepWrite(runtime, stepId, work) {
+    const runtimeKey = runtime;
+    let perStep = stepWriteQueues.get(runtimeKey);
+    if (!perStep) {
+        perStep = new Map();
+        stepWriteQueues.set(runtimeKey, perStep);
+    }
+    const previous = perStep.get(stepId) ?? Promise.resolve();
+    const current = previous
+        .catch(() => undefined)
+        .then(work)
+        .catch((err) => {
+        warnRuntime(runtime, "Failed to write trajectory update to database", err);
+    })
+        .finally(() => {
+        const latest = perStep?.get(stepId);
+        if (latest === current) {
+            perStep?.delete(stepId);
+        }
+    });
+    perStep.set(stepId, current);
+    return current;
+}
+export function createBaseTrajectory(stepId, now, source, metadata) {
+    const normalizedSource = source?.trim() || "runtime";
+    const createdAt = new Date(now).toISOString();
+    const normalizedMetadata = normalizeTrajectoryMetadata(metadata);
+    return {
+        id: stepId,
+        source: normalizedSource,
+        status: "active",
+        startTime: now,
+        endTime: null,
+        scenarioId: normalizedMetadata.scenarioId,
+        batchId: normalizedMetadata.batchId,
+        steps: [
+            {
+                stepId,
+                stepNumber: 0,
+                timestamp: now,
+                llmCalls: [],
+                providerAccesses: [],
+            },
+        ],
+        metadata: normalizedMetadata.metadata,
+        totalReward: 0,
+        createdAt,
+        updatedAt: createdAt,
+    };
+}
+export function ensureStep(trajectory, stepId, now) {
+    let step = trajectory.steps.find((item) => item.stepId === stepId);
+    if (!step) {
+        step = {
+            stepId,
+            stepNumber: trajectory.steps.length,
+            timestamp: now,
+            llmCalls: [],
+            providerAccesses: [],
+        };
+        trajectory.steps.push(step);
+    }
+    return step;
+}
+export function mergeMetadata(existing, incoming) {
+    if (!incoming)
+        return existing;
+    const merged = { ...existing };
+    for (const [key, value] of Object.entries(incoming)) {
+        if (value !== undefined)
+            merged[key] = value;
+    }
+    return normalizeTrajectoryMetadata(merged).metadata;
+}
+export function collectTrajectoryTimestamps(trajectory) {
+    const timestamps = [trajectory.startTime];
+    for (const step of trajectory.steps) {
+        timestamps.push(step.timestamp);
+        for (const call of step.llmCalls) {
+            timestamps.push(call.timestamp);
+        }
+        for (const access of step.providerAccesses) {
+            timestamps.push(access.timestamp);
+        }
+    }
+    return timestamps.filter((value) => Number.isFinite(value));
+}
+export function summarizeTrajectory(trajectory) {
+    const timestamps = collectTrajectoryTimestamps(trajectory);
+    const startTime = timestamps.length > 0 ? Math.min(...timestamps) : Date.now();
+    const endTime = timestamps.length > 0 ? Math.max(...timestamps) : startTime;
+    let llmCallCount = 0;
+    let providerAccessCount = 0;
+    let totalPromptTokens = 0;
+    let totalCompletionTokens = 0;
+    for (const step of trajectory.steps) {
+        llmCallCount += step.llmCalls.length;
+        providerAccessCount += step.providerAccesses.length;
+        for (const call of step.llmCalls) {
+            totalPromptTokens += call.promptTokens ?? 0;
+            totalCompletionTokens += call.completionTokens ?? 0;
+        }
+    }
+    return {
+        startTime,
+        endTime,
+        llmCallCount,
+        providerAccessCount,
+        totalPromptTokens,
+        totalCompletionTokens,
+    };
+}
+export function parsePersistedTrajectoryRow(row, fallbackId) {
+    const startTime = toNumber(readRecordValue(row, ["start_time", "startTime"]), Date.now());
+    const endTime = toOptionalNumber(readRecordValue(row, ["end_time", "endTime"])) ?? null;
+    const steps = parseSteps(readRecordValue(row, ["steps_json", "stepsJson", "steps"]));
+    const normalizedMetadata = normalizeTrajectoryMetadata(parseMetadata(readRecordValue(row, [
+        "metadata_json",
+        "metadataJson",
+        "metadata",
+        "meta",
+    ])), {
+        scenarioId: readRecordValue(row, ["scenario_id", "scenarioId"]),
+        batchId: readRecordValue(row, ["batch_id", "batchId"]),
+    });
+    return {
+        id: toText(readRecordValue(row, ["id", "trajectory_id", "trajectoryId"]), fallbackId),
+        source: toText(readRecordValue(row, ["source"]), "runtime"),
+        status: normalizeStatus(readRecordValue(row, ["status"]), "completed"),
+        startTime,
+        endTime,
+        scenarioId: normalizedMetadata.scenarioId,
+        batchId: normalizedMetadata.batchId,
+        steps,
+        metadata: normalizedMetadata.metadata,
+        totalReward: toNumber(readRecordValue(row, ["total_reward", "totalReward"]), 0),
+        createdAt: toText(readRecordValue(row, ["created_at", "createdAt"]), new Date(startTime).toISOString()),
+        updatedAt: toText(readRecordValue(row, ["updated_at", "updatedAt"]), new Date(endTime ?? startTime).toISOString()),
+    };
+}
+// ---------------------------------------------------------------------------
+// Core load/save (used by both storage and query modules)
+// ---------------------------------------------------------------------------
+export async function loadTrajectoryById(runtime, stepId) {
+    const safeId = sqlQuote(stepId);
+    try {
+        const result = await executeRawSql(runtime, `SELECT * FROM trajectories WHERE id = ${safeId} LIMIT 1`);
+        const rows = extractRows(result);
+        if (rows.length === 0)
+            return null;
+        const row = asRecord(rows[0]);
+        if (!row)
+            return null;
+        return parsePersistedTrajectoryRow(row, stepId);
+    }
+    catch {
+        return null;
+    }
+}
+export async function loadTrajectoryByStepId(runtime, stepId) {
+    const direct = await loadTrajectoryById(runtime, stepId);
+    if (direct) {
+        return direct;
+    }
+    const normalizedStepId = stepId.trim();
+    if (!normalizedStepId) {
+        return null;
+    }
+    const stepPattern = sqlQuote(`%"stepId":"${normalizedStepId}"%`);
+    try {
+        const result = await executeRawSql(runtime, `SELECT * FROM trajectories
+       WHERE COALESCE(steps_json, '') LIKE ${stepPattern}
+       ORDER BY updated_at DESC, created_at DESC
+       LIMIT 1`);
+        const rows = extractRows(result);
+        if (rows.length === 0)
+            return null;
+        const row = asRecord(rows[0]);
+        if (!row)
+            return null;
+        return parsePersistedTrajectoryRow(row, normalizedStepId);
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveTrajectory(runtime, trajectory) {
+    const normalizedMetadata = normalizeTrajectoryMetadata(trajectory.metadata, {
+        scenarioId: trajectory.scenarioId,
+        batchId: trajectory.batchId,
+    });
+    trajectory.metadata = normalizedMetadata.metadata;
+    trajectory.scenarioId = normalizedMetadata.scenarioId;
+    trajectory.batchId = normalizedMetadata.batchId;
+    const summary = summarizeTrajectory(trajectory);
+    const isActive = trajectory.status === "active";
+    const endTime = isActive ? null : (trajectory.endTime ?? summary.endTime);
+    const durationMs = typeof endTime === "number"
+        ? Math.max(0, endTime - summary.startTime)
+        : null;
+    const createdAt = trajectory.createdAt || new Date(summary.startTime).toISOString();
+    const updatedAt = trajectory.updatedAt || new Date(endTime ?? summary.endTime).toISOString();
+    const serializedSteps = sqlQuote(JSON.stringify(trajectory.steps));
+    const serializedMetadata = sqlQuote(JSON.stringify(trajectory.metadata));
+    const serializedCompatMetrics = sqlQuote(JSON.stringify({
+        episodeLength: trajectory.steps.length,
+        finalStatus: trajectory.status,
+        llmCallCount: summary.llmCallCount,
+        providerAccessCount: summary.providerAccessCount,
+        totalPromptTokens: summary.totalPromptTokens,
+        totalCompletionTokens: summary.totalCompletionTokens,
+    }));
+    const sql = `INSERT INTO trajectories (
+      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
+    ) VALUES (
+      ${sqlQuote(trajectory.id)},
+      ${sqlQuote(runtime.agentId)},
+      ${sqlQuote(trajectory.source)},
+      ${sqlQuote(trajectory.status)},
+      ${sqlNumber(summary.startTime)},
+      ${sqlNumber(endTime)},
+      ${sqlNumber(durationMs)},
+      ${sqlNumber(trajectory.steps.length)},
+      ${sqlNumber(summary.llmCallCount)},
+      ${sqlNumber(summary.providerAccessCount)},
+      ${sqlNumber(summary.totalPromptTokens)},
+      ${sqlNumber(summary.totalCompletionTokens)},
+      ${sqlNumber(trajectory.totalReward)},
+      ${trajectory.scenarioId ? sqlQuote(trajectory.scenarioId) : "NULL"},
+      ${trajectory.batchId ? sqlQuote(trajectory.batchId) : "NULL"},
+      ${serializedSteps},
+      ${serializedMetadata},
+      ${sqlQuote(createdAt)},
+      ${sqlQuote(updatedAt)},
+      ${sqlNumber(trajectory.steps.length)}
+    )
+    ON CONFLICT (id) DO UPDATE SET
+      agent_id = EXCLUDED.agent_id,
+      source = EXCLUDED.source,
+      status = EXCLUDED.status,
+      start_time = EXCLUDED.start_time,
+      end_time = EXCLUDED.end_time,
+      duration_ms = EXCLUDED.duration_ms,
+      step_count = EXCLUDED.step_count,
+      llm_call_count = EXCLUDED.llm_call_count,
+      provider_access_count = EXCLUDED.provider_access_count,
+      total_prompt_tokens = EXCLUDED.total_prompt_tokens,
+      total_completion_tokens = EXCLUDED.total_completion_tokens,
+      total_reward = EXCLUDED.total_reward,
+      scenario_id = EXCLUDED.scenario_id,
+      batch_id = EXCLUDED.batch_id,
+      steps_json = EXCLUDED.steps_json,
+      metadata = EXCLUDED.metadata,
+      created_at = EXCLUDED.created_at,
+      updated_at = EXCLUDED.updated_at,
+      episode_length = EXCLUDED.episode_length`;
+    const compatSql = `INSERT INTO trajectories (
+      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_json,
+      metrics_json,
+      created_at,
+      updated_at
+    ) VALUES (
+      ${sqlQuote(trajectory.id)},
+      ${sqlQuote(runtime.agentId)},
+      ${sqlQuote(trajectory.source)},
+      ${sqlQuote(trajectory.status)},
+      ${sqlNumber(summary.startTime)},
+      ${sqlNumber(endTime)},
+      ${sqlNumber(durationMs)},
+      ${sqlNumber(trajectory.steps.length)},
+      ${sqlNumber(summary.llmCallCount)},
+      ${sqlNumber(summary.providerAccessCount)},
+      ${sqlNumber(summary.totalPromptTokens)},
+      ${sqlNumber(summary.totalCompletionTokens)},
+      ${sqlNumber(trajectory.totalReward)},
+      ${trajectory.scenarioId ? sqlQuote(trajectory.scenarioId) : "NULL"},
+      ${trajectory.batchId ? sqlQuote(trajectory.batchId) : "NULL"},
+      ${serializedSteps},
+      ${serializedMetadata},
+      ${serializedCompatMetrics},
+      ${sqlQuote(createdAt)},
+      ${sqlQuote(updatedAt)}
+    )
+    ON CONFLICT (id) DO UPDATE SET
+      agent_id = EXCLUDED.agent_id,
+      source = EXCLUDED.source,
+      status = EXCLUDED.status,
+      start_time = EXCLUDED.start_time,
+      end_time = EXCLUDED.end_time,
+      duration_ms = EXCLUDED.duration_ms,
+      step_count = EXCLUDED.step_count,
+      llm_call_count = EXCLUDED.llm_call_count,
+      provider_access_count = EXCLUDED.provider_access_count,
+      total_prompt_tokens = EXCLUDED.total_prompt_tokens,
+      total_completion_tokens = EXCLUDED.total_completion_tokens,
+      total_reward = EXCLUDED.total_reward,
+      scenario_id = EXCLUDED.scenario_id,
+      batch_id = EXCLUDED.batch_id,
+      steps_json = EXCLUDED.steps_json,
+      metadata_json = EXCLUDED.metadata_json,
+      metrics_json = EXCLUDED.metrics_json,
+      created_at = EXCLUDED.created_at,
+      updated_at = EXCLUDED.updated_at`;
+    try {
+        await executeRawSql(runtime, sql);
+        return true;
+    }
+    catch (err) {
+        try {
+            await executeRawSql(runtime, compatSql);
+            return true;
+        }
+        catch (compatErr) {
+            console.error("[trajectory-persistence] saveTrajectory error:", {
+                modern: err instanceof Error ? err.message : String(err),
+                compat: compatErr instanceof Error ? compatErr.message : String(compatErr),
+            });
+            return false;
+        }
+    }
+}
+/**
+ * Read orchestrator trajectory context from the runtime, if set.
+ */
+export function readOrchestratorTrajectoryContext(runtime) {
+    if (!runtime || typeof runtime !== "object")
+        return undefined;
+    const ctx = runtime
+        .__orchestratorTrajectoryCtx;
+    if (!ctx || typeof ctx !== "object")
+        return undefined;
+    const candidate = ctx;
+    if (candidate.source !== "orchestrator" ||
+        typeof candidate.decisionType !== "string")
+        return undefined;
+    return candidate;
+}
+// ---------------------------------------------------------------------------
+// Archive helpers
+// ---------------------------------------------------------------------------
+export function resolvePreferredTrajectoryArchiveRoot() {
+    const explicitWorkspace = process.env.ELIZA_WORKSPACE_DIR?.trim();
+    if (explicitWorkspace)
+        return explicitWorkspace;
+    const workspaceRoot = process.env.ELIZA_WORKSPACE_ROOT?.trim();
+    if (workspaceRoot)
+        return workspaceRoot;
+    return path.join(os.homedir(), ".eliza", "workspace");
+}
+export async function ensureArchiveDirectory(dir) {
+    await fs.mkdir(dir, { recursive: true });
+}
+export async function resolveTrajectoryArchiveDirectory() {
+    const preferred = path.join(resolvePreferredTrajectoryArchiveRoot(), TRAJECTORY_ARCHIVE_DIRNAME);
+    try {
+        await ensureArchiveDirectory(preferred);
+        return preferred;
+    }
+    catch {
+        const fallback = path.join(process.env.TMPDIR || os.tmpdir(), "eliza", TRAJECTORY_ARCHIVE_DIRNAME);
+        await ensureArchiveDirectory(fallback);
+        return fallback;
+    }
+}
+export function toArchiveSafeTimestamp(isoTimestamp) {
+    return isoTimestamp.replace(/[:.]/g, "-");
+}
+export function stringifyArchiveRow(row) {
+    return JSON.stringify(row, (_key, value) => typeof value === "bigint" ? value.toString() : value);
+}
+export async function writeCompressedJsonlRows(archivePath, rows) {
+    const gzipStream = createGzip({ level: 9 });
+    const outStream = createWriteStream(archivePath);
+    gzipStream.pipe(outStream);
+    for (const row of rows) {
+        if (!gzipStream.write(`${stringifyArchiveRow(row)}\n`, "utf8")) {
+            await once(gzipStream, "drain");
+        }
+    }
+    gzipStream.end();
+    await once(outStream, "finish");
+}
+/**
+ * Trajectory persistence is unconditionally on. The only paths that disable it:
+ *
+ *   1. `NODE_ENV === "test"` — keeps the test runner free of background DB writes.
+ *   2. `ELIZA_DISABLE_TRAJECTORY_LOGGING=1` — explicit operator opt-out.
+ *
+ * We deliberately stopped honoring the legacy `ENABLE_TRAJECTORIES`,
+ * `ELIZA_TRAJECTORY_LOGGING`, `TRAJECTORY_LOGGING_ENABLED`, and
+ * `ELIZA_CLOUD_PROVISIONED` knobs: each represented a different historical
+ * attempt to gate persistence, and shipping multiple opt-in paths produced
+ * silent gaps where debugging and training data went missing. One opt-out,
+ * otherwise on.
+ */
+export function shouldEnableTrajectoryLoggingByDefault(env = process.env) {
+    if (env.NODE_ENV === "test")
+        return false;
+    if (env.ELIZA_DISABLE_TRAJECTORY_LOGGING === "1")
+        return false;
+    return true;
+}