@elizaos/agent 2.0.0-beta.1 → 2.0.3-beta.2

package/runtime/trajectory-internals.js

@@ -0,0 +1,1720 @@
+/**
+ * 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, resolveStateDir, } 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 (err) {
+        warnRuntime(runtime, "[trajectory-persistence] observation flush failed", err);
+        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 (err) {
+        warnRuntime(runtime, "[trajectory-persistence] source aggregation failed", err);
+        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: "total_cache_read_input_tokens",
+                    def: "INTEGER NOT NULL DEFAULT 0",
+                },
+                {
+                    name: "total_cache_creation_input_tokens",
+                    def: "INTEGER NOT NULL DEFAULT 0",
+                },
+                { 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;
+            coreLogger.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_cache_read_input_tokens INTEGER NOT NULL DEFAULT 0,
+        total_cache_creation_input_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_cache_read_input_tokens INTEGER NOT NULL DEFAULT 0,
+        total_cache_creation_input_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
+        }
+        try {
+            await executeRawSql(runtime, `ALTER TABLE trajectory_archive ADD COLUMN total_cache_read_input_tokens INTEGER NOT NULL DEFAULT 0`);
+        }
+        catch {
+            // ignore when column already exists
+        }
+        try {
+            await executeRawSql(runtime, `ALTER TABLE trajectory_archive ADD COLUMN total_cache_creation_input_tokens INTEGER NOT NULL DEFAULT 0`);
+        }
+        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 (err) {
+            warnRuntime(runtime, "[trajectory-persistence] scenario index creation failed", err);
+        }
+        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 (err) {
+            warnRuntime(runtime, "[trajectory-persistence] batch index creation failed", err);
+        }
+        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
+        }
+        // Per-step rows; script column is unbounded TEXT (no legacy 4096-char cap).
+        await executeRawSql(runtime, `CREATE TABLE IF NOT EXISTS trajectory_steps (
+        id TEXT PRIMARY KEY,
+        trajectory_id TEXT NOT NULL,
+        ordinal INTEGER NOT NULL,
+        parent_step_id TEXT,
+        step_type TEXT NOT NULL DEFAULT 'llm',
+        name TEXT,
+        started_at BIGINT,
+        ended_at BIGINT,
+        payload TEXT NOT NULL DEFAULT '{}',
+        script TEXT
+      )`);
+        try {
+            await executeRawSql(runtime, `CREATE INDEX IF NOT EXISTS idx_trajectory_steps_trajectory_id ON trajectory_steps(trajectory_id)`);
+        }
+        catch (err) {
+            warnRuntime(runtime, "[trajectory-persistence] trajectory step index creation failed", err);
+        }
+        try {
+            await executeRawSql(runtime, `CREATE INDEX IF NOT EXISTS idx_trajectory_steps_ordinal ON trajectory_steps(trajectory_id, ordinal)`);
+        }
+        catch (err) {
+            warnRuntime(runtime, "[trajectory-persistence] trajectory step ordinal index creation failed", err);
+        }
+        // One-shot forward migration from steps_json into trajectory_steps.
+        // Idempotent: only migrates trajectories whose steps are absent from the
+        // dedicated table.
+        await forwardMigrateStepsJsonToRows(runtime);
+        if (needsRecreate) {
+            coreLogger.warn("[trajectory-persistence] Recreated trajectories table with updated schema");
+        }
+        schemaVersions.set(key, SCHEMA_VERSION);
+        initializedRuntimes.add(key);
+        return true;
+    }
+    catch (err) {
+        coreLogger.error("[trajectory-persistence] ensureTrajectoriesTable error:", err instanceof Error ? err.message : String(err));
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Forward migration: steps_json -> trajectory_steps
+//
+// Direction: ONE-WAY (legacy JSONB -> dedicated rows). Runs once per
+// runtime + schema version. After this migration runs, writes go to
+// both stores (rows are authoritative, `steps_json` is kept as a
+// best-effort fallback only). There is no reverse migration.
+// ---------------------------------------------------------------------------
+const stepsForwardMigrationRan = new WeakSet();
+async function forwardMigrateStepsJsonToRows(runtime) {
+    const key = runtime;
+    if (stepsForwardMigrationRan.has(key))
+        return;
+    stepsForwardMigrationRan.add(key);
+    try {
+        // Find trajectories that have steps_json content but no rows yet.
+        const result = await executeRawSql(runtime, `SELECT t.id AS id, CAST(t.steps_json AS TEXT) AS steps_json
+       FROM trajectories t
+       LEFT JOIN trajectory_steps s ON s.trajectory_id = t.id
+       WHERE s.id IS NULL
+         AND t.steps_json IS NOT NULL
+         AND CAST(t.steps_json AS TEXT) <> ''
+         AND CAST(t.steps_json AS TEXT) <> '[]'`);
+        const rows = extractRows(result);
+        if (rows.length === 0)
+            return;
+        let migrated = 0;
+        for (const row of rows) {
+            const record = asRecord(row);
+            if (!record)
+                continue;
+            const trajectoryId = toText(record.id, "");
+            if (!trajectoryId)
+                continue;
+            const stepsRaw = record.steps_json;
+            const parsed = parseJsonValue(stepsRaw);
+            if (!Array.isArray(parsed))
+                continue;
+            for (const stepValue of parsed) {
+                const step = asRecord(stepValue);
+                if (!step)
+                    continue;
+                const stepId = toText(step.stepId, "");
+                if (!stepId)
+                    continue;
+                const ordinal = toNumber(step.stepNumber, 0);
+                const startedAt = toOptionalNumber(step.timestamp);
+                const endedAt = startedAt;
+                const kindRaw = toText(step.kind, "");
+                const stepType = kindRaw === "llm" || kindRaw === "action" || kindRaw === "evaluator"
+                    ? kindRaw
+                    : "llm";
+                const script = typeof step.script === "string" && step.script.length > 0
+                    ? step.script
+                    : null;
+                const { script: _script, ...payloadObj } = step;
+                const payload = JSON.stringify(payloadObj);
+                try {
+                    await executeRawSql(runtime, `INSERT INTO trajectory_steps (
+              id, trajectory_id, ordinal, parent_step_id, step_type,
+              name, started_at, ended_at, payload, script
+            ) VALUES (
+              ${sqlQuote(stepId)},
+              ${sqlQuote(trajectoryId)},
+              ${sqlNumber(ordinal)},
+              NULL,
+              ${sqlQuote(stepType)},
+              NULL,
+              ${sqlNumber(startedAt ?? null)},
+              ${sqlNumber(endedAt ?? null)},
+              ${sqlQuote(payload)},
+              ${script !== null ? sqlQuote(script) : "NULL"}
+            )
+            ON CONFLICT (id) DO NOTHING`);
+                    migrated += 1;
+                }
+                catch (err) {
+                    // Continue migrating other steps on individual failures.
+                    warnRuntime(runtime, `forwardMigrateStepsJsonToRows: failed to insert step ${stepId} for trajectory ${trajectoryId}`, err);
+                }
+            }
+        }
+        if (migrated > 0) {
+            coreLogger.info(`[trajectory-persistence] Forward-migrated ${migrated} step rows from steps_json into trajectory_steps`);
+        }
+    }
+    catch (err) {
+        // Best-effort: failure here doesn't block new writes; legacy steps_json remains readable.
+        warnRuntime(runtime, "forwardMigrateStepsJsonToRows: migration query failed; legacy steps_json still readable", err);
+    }
+}
+// ---------------------------------------------------------------------------
+// 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 toOptionalEpochMs(value) {
+    const directNumber = toOptionalNumber(value);
+    if (directNumber !== undefined)
+        return directNumber;
+    const text = toOptionalText(value);
+    if (!text)
+        return undefined;
+    const parsed = Date.parse(text);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+export function normalizePersistedTrajectoryTiming(input) {
+    if (input.status === "active") {
+        return { endTime: null, durationMs: null };
+    }
+    const startTime = Number.isFinite(input.startTime) ? input.startTime : 0;
+    const existingEndTime = typeof input.endTime === "number" &&
+        Number.isFinite(input.endTime) &&
+        input.endTime > 0 &&
+        input.endTime >= startTime
+        ? input.endTime
+        : null;
+    const fallbackEndTime = startTime > 0 ? startTime : Date.now();
+    const endTime = existingEndTime ??
+        [
+            toOptionalEpochMs(input.updatedAt),
+            toOptionalEpochMs(input.createdAt),
+            fallbackEndTime,
+        ].find((candidate) => typeof candidate === "number" &&
+            Number.isFinite(candidate) &&
+            candidate > 0 &&
+            candidate >= startTime) ??
+        startTime;
+    const durationMs = existingEndTime !== null &&
+        typeof input.durationMs === "number" &&
+        Number.isFinite(input.durationMs) &&
+        input.durationMs >= 0
+        ? input.durationMs
+        : Math.max(0, endTime - startTime);
+    return { endTime, durationMs };
+}
+export function normalizePersistedUpdatedAt(input) {
+    const startTime = Number.isFinite(input.startTime) ? input.startTime : 0;
+    const floorTime = typeof input.endTime === "number" && Number.isFinite(input.endTime)
+        ? input.endTime
+        : startTime;
+    const updatedAtMs = toOptionalEpochMs(input.updatedAt);
+    const createdAtMs = toOptionalEpochMs(input.createdAt);
+    const timestamp = (typeof updatedAtMs === "number" &&
+        updatedAtMs > 0 &&
+        updatedAtMs >= floorTime
+        ? updatedAtMs
+        : null) ??
+        (typeof input.endTime === "number" &&
+            Number.isFinite(input.endTime) &&
+            input.endTime > 0
+            ? input.endTime
+            : null) ??
+        (typeof createdAtMs === "number" && createdAtMs > 0 ? createdAtMs : null) ??
+        (startTime > 0 ? startTime : Date.now());
+    return new Date(timestamp).toISOString();
+}
+export function normalizeStepId(value) {
+    const stepId = toText(value, "").trim();
+    return stepId.length > 0 ? stepId : null;
+}
+/** Fields in an LLM call payload that may carry PII / secrets. */
+const TRAJECTORY_REDACTABLE_FIELDS = [
+    "systemPrompt",
+    "userPrompt",
+    "prompt",
+    "input",
+    "response",
+    "reasoning",
+];
+function redactTrajectoryParams(params) {
+    let cloned = null;
+    for (const field of TRAJECTORY_REDACTABLE_FIELDS) {
+        const value = params[field];
+        if (typeof value !== "string" || value.length === 0)
+            continue;
+        const redacted = redactTrajectoryText(value);
+        if (redacted !== value) {
+            cloned ??= { ...params };
+            cloned[field] = redacted;
+        }
+    }
+    return cloned ?? params;
+}
+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: redactTrajectoryParams({
+                ...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: redactTrajectoryParams(params),
+        };
+    }
+    return {
+        stepId,
+        params: redactTrajectoryParams({
+            ...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;
+    let totalCacheReadInputTokens = 0;
+    let totalCacheCreationInputTokens = 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;
+            totalCacheReadInputTokens += call.cacheReadInputTokens ?? 0;
+            totalCacheCreationInputTokens += call.cacheCreationInputTokens ?? 0;
+        }
+    }
+    return {
+        startTime,
+        endTime,
+        llmCallCount,
+        providerAccessCount,
+        totalPromptTokens,
+        totalCompletionTokens,
+        totalCacheReadInputTokens,
+        totalCacheCreationInputTokens,
+    };
+}
+export function parsePersistedTrajectoryRow(row, fallbackId) {
+    const startTime = toNumber(readRecordValue(row, ["start_time", "startTime"]), Date.now());
+    const status = normalizeStatus(readRecordValue(row, ["status"]), "completed");
+    const rawCreatedAt = readRecordValue(row, ["created_at", "createdAt"]);
+    const rawUpdatedAt = readRecordValue(row, ["updated_at", "updatedAt"]);
+    const timing = normalizePersistedTrajectoryTiming({
+        status,
+        startTime,
+        endTime: toOptionalNumber(readRecordValue(row, ["end_time", "endTime"])) ?? null,
+        durationMs: toOptionalNumber(readRecordValue(row, ["duration_ms", "durationMs"])) ??
+            null,
+        createdAt: rawCreatedAt,
+        updatedAt: rawUpdatedAt,
+    });
+    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,
+        startTime,
+        endTime: timing.endTime,
+        scenarioId: normalizedMetadata.scenarioId,
+        batchId: normalizedMetadata.batchId,
+        steps,
+        metadata: normalizedMetadata.metadata,
+        totalReward: toNumber(readRecordValue(row, ["total_reward", "totalReward"]), 0),
+        createdAt: toText(rawCreatedAt, new Date(startTime).toISOString()),
+        updatedAt: normalizePersistedUpdatedAt({
+            startTime,
+            endTime: timing.endTime,
+            createdAt: rawCreatedAt,
+            updatedAt: rawUpdatedAt,
+        }),
+    };
+}
+// ---------------------------------------------------------------------------
+// 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;
+        const trajectory = parsePersistedTrajectoryRow(row, stepId);
+        // Prefer steps from the dedicated trajectory_steps table when present.
+        // Falls back to the legacy steps_json blob (already populated from
+        // parsePersistedTrajectoryRow) when the dedicated table has no rows.
+        const stepsFromTable = await loadAllStepsFromDedicatedTable(runtime, stepId);
+        if (stepsFromTable !== null) {
+            trajectory.steps = stepsFromTable;
+        }
+        return trajectory;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Internal helper — loads all step rows from the dedicated
+ * `trajectory_steps` table. Returns `null` when the table has no rows
+ * for the given trajectory (signal to fall back to the JSONB blob).
+ * Returns an empty array when the table exists but the trajectory
+ * legitimately has no steps yet.
+ */
+async function loadAllStepsFromDedicatedTable(runtime, trajectoryId) {
+    const safeId = sqlQuote(trajectoryId);
+    try {
+        const result = await executeRawSql(runtime, `SELECT * FROM trajectory_steps
+       WHERE trajectory_id = ${safeId}
+       ORDER BY ordinal ASC`);
+        const rows = extractRows(result);
+        if (rows.length === 0)
+            return null;
+        return rows
+            .map((row) => asRecord(row))
+            .filter((row) => Boolean(row))
+            .map(stepRowToPersistedStep);
+    }
+    catch {
+        return null;
+    }
+}
+function stepRowToPersistedStep(row) {
+    const payload = parseJsonValue(readRecordValue(row, ["payload"]));
+    const payloadRecord = asRecord(payload) ?? {};
+    const llmCalls = Array.isArray(payloadRecord.llmCalls)
+        ? payloadRecord.llmCalls
+        : [];
+    const providerAccesses = Array.isArray(payloadRecord.providerAccesses)
+        ? payloadRecord.providerAccesses
+        : [];
+    const childSteps = Array.isArray(payloadRecord.childSteps)
+        ? payloadRecord.childSteps
+        : undefined;
+    const usedSkills = Array.isArray(payloadRecord.usedSkills)
+        ? payloadRecord.usedSkills
+        : undefined;
+    const stepNumber = toNumber(readRecordValue(row, ["ordinal"]), 0);
+    const startedAt = toOptionalNumber(readRecordValue(row, ["started_at"]));
+    const endedAt = toOptionalNumber(readRecordValue(row, ["ended_at"]));
+    const kindRaw = toText(readRecordValue(row, ["step_type"]), "");
+    const kind = kindRaw === "llm" || kindRaw === "action" || kindRaw === "evaluator"
+        ? kindRaw
+        : undefined;
+    const scriptValue = readRecordValue(row, ["script"]);
+    const script = typeof scriptValue === "string" && scriptValue.length > 0
+        ? scriptValue
+        : undefined;
+    const scriptHash = typeof payloadRecord.scriptHash === "string"
+        ? payloadRecord.scriptHash
+        : undefined;
+    return {
+        stepId: toText(readRecordValue(row, ["id"]), ""),
+        stepNumber,
+        timestamp: startedAt ?? endedAt ?? Date.now(),
+        llmCalls,
+        providerAccesses,
+        ...(kind !== undefined ? { kind } : {}),
+        ...(childSteps !== undefined ? { childSteps } : {}),
+        ...(script !== undefined ? { script } : {}),
+        ...(scriptHash !== undefined ? { scriptHash } : {}),
+        ...(usedSkills !== undefined ? { usedSkills } : {}),
+    };
+}
+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 persistedEndTime = typeof trajectory.endTime === "number" &&
+        Number.isFinite(trajectory.endTime) &&
+        trajectory.endTime >= summary.startTime
+        ? trajectory.endTime
+        : undefined;
+    const summaryEndTime = Number.isFinite(summary.endTime) && summary.endTime >= summary.startTime
+        ? summary.endTime
+        : summary.startTime;
+    const endTime = isActive ? null : (persistedEndTime ?? summaryEndTime);
+    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,
+        totalCacheReadInputTokens: summary.totalCacheReadInputTokens,
+        totalCacheCreationInputTokens: summary.totalCacheCreationInputTokens,
+    }));
+    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_cache_read_input_tokens,
+      total_cache_creation_input_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(summary.totalCacheReadInputTokens)},
+      ${sqlNumber(summary.totalCacheCreationInputTokens)},
+      ${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_cache_read_input_tokens = EXCLUDED.total_cache_read_input_tokens,
+      total_cache_creation_input_tokens = EXCLUDED.total_cache_creation_input_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_cache_read_input_tokens,
+      total_cache_creation_input_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(summary.totalCacheReadInputTokens)},
+      ${sqlNumber(summary.totalCacheCreationInputTokens)},
+      ${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_cache_read_input_tokens = EXCLUDED.total_cache_read_input_tokens,
+      total_cache_creation_input_tokens = EXCLUDED.total_cache_creation_input_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`;
+    let saved = false;
+    try {
+        await executeRawSql(runtime, sql);
+        saved = true;
+    }
+    catch (err) {
+        try {
+            await executeRawSql(runtime, compatSql);
+            saved = true;
+        }
+        catch (compatErr) {
+            coreLogger.error(`[trajectory-persistence] saveTrajectory error: modern=${err instanceof Error ? err.message : String(err)} compat=${compatErr instanceof Error ? compatErr.message : String(compatErr)}`);
+            return false;
+        }
+    }
+    if (saved) {
+        // Mirror steps into the dedicated `trajectory_steps` table. Writes
+        // here are the new source of truth for step data; the JSONB blob in
+        // `trajectories.steps_json` is kept in lockstep for back-compat
+        // readers that still consume the legacy column.
+        try {
+            await replaceStepsForTrajectoryInternal(runtime, trajectory.id, trajectory.steps);
+        }
+        catch (err) {
+            warnRuntime(runtime, `saveTrajectory: failed to mirror steps into trajectory_steps for ${trajectory.id}`, err);
+        }
+    }
+    return saved;
+}
+async function replaceStepsForTrajectoryInternal(runtime, trajectoryId, steps) {
+    const safeId = sqlQuote(trajectoryId);
+    await executeRawSql(runtime, `DELETE FROM trajectory_steps WHERE trajectory_id = ${safeId}`);
+    for (const step of steps) {
+        const stepType = step.kind === "llm" || step.kind === "action" || step.kind === "evaluator"
+            ? step.kind
+            : "llm";
+        const script = typeof step.script === "string" && step.script.length > 0
+            ? step.script
+            : null;
+        const { script: _script, ...payloadObj } = step;
+        const payload = JSON.stringify(payloadObj);
+        const startedAt = Number.isFinite(step.timestamp) ? step.timestamp : null;
+        const endedAt = startedAt;
+        const firstCallPurpose = step.llmCalls[0]?.purpose ??
+            step.providerAccesses[0]?.providerName ??
+            null;
+        await executeRawSql(runtime, `INSERT INTO trajectory_steps (
+        id, trajectory_id, ordinal, parent_step_id, step_type,
+        name, started_at, ended_at, payload, script
+      ) VALUES (
+        ${sqlQuote(step.stepId)},
+        ${sqlQuote(trajectoryId)},
+        ${sqlNumber(step.stepNumber)},
+        NULL,
+        ${sqlQuote(stepType)},
+        ${firstCallPurpose ? sqlQuote(firstCallPurpose) : "NULL"},
+        ${sqlNumber(startedAt)},
+        ${sqlNumber(endedAt)},
+        ${sqlQuote(payload)},
+        ${script !== null ? sqlQuote(script) : "NULL"}
+      )
+      ON CONFLICT (id) DO UPDATE SET
+        trajectory_id = EXCLUDED.trajectory_id,
+        ordinal = EXCLUDED.ordinal,
+        parent_step_id = EXCLUDED.parent_step_id,
+        step_type = EXCLUDED.step_type,
+        name = EXCLUDED.name,
+        started_at = EXCLUDED.started_at,
+        ended_at = EXCLUDED.ended_at,
+        payload = EXCLUDED.payload,
+        script = EXCLUDED.script`);
+    }
+}
+/**
+ * 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(resolveStateDir(), "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;
+    // SOC2 O-5: in production NODE_ENV the default is OFF; operators must
+    // explicitly opt in via ELIZA_TRAJECTORY_LOGGING=1. Dev/unset NODE_ENV
+    // preserves the previous always-on behavior for the local debugging
+    // workflow.
+    if (env.NODE_ENV === "production") {
+        return env.ELIZA_TRAJECTORY_LOGGING === "1";
+    }
+    return true;
+}
+/**
+ * Coarse PII redaction applied to LLM prompts/responses before persistence
+ * (SOC2 O-5). Strips email addresses, common API/OAuth tokens, ETH/BTC
+ * addresses, and credit-card-shaped digit runs. Conservative — combine
+ * with workspace isolation rather than treating as a sole defence.
+ */
+const TRAJECTORY_REDACT_PATTERNS = [
+    {
+        re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+        label: "<EMAIL>",
+    },
+    { re: /sk-[A-Za-z0-9_-]{20,}/g, label: "<API_KEY>" },
+    { re: /(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}/g, label: "<GH_TOKEN>" },
+    { re: /xox[bpars]-[A-Za-z0-9-]{10,}/g, label: "<SLACK_TOKEN>" },
+    { re: /0x[a-fA-F0-9]{40}/g, label: "<ETH_ADDR>" },
+    { re: /\b[13][a-km-zA-HJ-NP-Z1-9]{25,34}\b/g, label: "<BTC_ADDR>" },
+    { re: /\b\d{13,19}\b/g, label: "<CARD>" },
+];
+export function redactTrajectoryText(value) {
+    if (typeof value !== "string")
+        return value;
+    if (value.length === 0)
+        return value;
+    let out = value;
+    for (const { re, label } of TRAJECTORY_REDACT_PATTERNS) {
+        out = out.replace(re, label);
+    }
+    return out;
+}