@elizaos/agent 2.0.0-beta.2 → 2.0.11-beta.6

package/runtime/trajectory-persistence.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Trajectory persistence — main entry point.
+ *
+ * Re-exports the full public API from the decomposed sub-modules:
+ *   - trajectory-internals.ts       — shared internal helpers, types, utilities
+ *   - trajectory-storage.ts        — trajectory write operations
+ *   - trajectory-query.ts          — trajectory read operations
+ *   - trajectory-export.ts         — export and archive operations
+ *   - trajectory-steps-reader.ts   — CQRS reader for the dedicated steps table
+ *   - trajectory-steps-writer.ts   — CQRS writer for the dedicated steps table
+ *
+ * Types are defined in ../types/trajectory.ts.
+ *
+ * Step storage:
+ *   - Canonical store: `trajectory_steps` table (one row per step).
+ *   - Legacy fallback: `trajectories.steps_json` JSONB blob.
+ *   - Migration direction: forward only. On first boot after this change,
+ *     `ensureTrajectoriesTable` migrates rows from JSONB into the new table.
+ *     Writes go to both stores; reads prefer the new table and fall back
+ *     to JSONB.
+ *   - Scripts: no character cap on the dedicated `script` TEXT column.
+ *     The legacy `TRAJECTORY_STEP_SCRIPT_MAX_CHARS=4096` cap remains
+ *     applied to the JSONB fallback.
+ */
+export { computeBySource, extractInsightsFromResponse, extractRows, flushObservationBuffer, pushChatExchange, readOrchestratorTrajectoryContext, shouldEnableTrajectoryLoggingByDefault, shouldRunObservationExtraction, truncateField, truncateRecord, } from "./trajectory-internals.ts";
+export { loadPersistedTrajectoryRows } from "./trajectory-query.ts";
+export { DEFAULT_GET_STEPS_LIMIT, getSteps, loadAllStepsForTrajectory, MAX_GET_STEPS_LIMIT, type TrajectoryStepsPage, } from "./trajectory-steps-reader.ts";
+export { clearAllSteps, deleteStepsForTrajectories, replaceStepsForTrajectory, upsertStep, } from "./trajectory-steps-writer.ts";
+export { annotateTrajectoryStep, clearPersistedTrajectoryRows, completeTrajectoryStepInDatabase, createDatabaseTrajectoryLogger, DatabaseTrajectoryLogger, deletePersistedTrajectoryRows, flushTrajectoryWrites, installDatabaseTrajectoryLogger, pruneOldTrajectories, startTrajectoryStepInDatabase, } from "./trajectory-storage.ts";
+//# sourceMappingURL=trajectory-persistence.d.ts.map

package/runtime/trajectory-persistence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trajectory-persistence.d.ts","sourceRoot":"","sources":["../../src/runtime/trajectory-persistence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,EACL,eAAe,EACf,2BAA2B,EAC3B,WAAW,EACX,sBAAsB,EACtB,gBAAgB,EAChB,iCAAiC,EACjC,sCAAsC,EAEtC,8BAA8B,EAC9B,aAAa,EACb,cAAc,GACf,MAAM,2BAA2B,CAAC;AAInC,OAAO,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAIpE,OAAO,EACL,uBAAuB,EACvB,QAAQ,EACR,yBAAyB,EACzB,mBAAmB,EACnB,KAAK,mBAAmB,GACzB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,aAAa,EACb,0BAA0B,EAC1B,yBAAyB,EACzB,UAAU,GACX,MAAM,8BAA8B,CAAC;AAItC,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAC5B,gCAAgC,EAChC,8BAA8B,EAC9B,wBAAwB,EACxB,6BAA6B,EAC7B,qBAAqB,EACrB,+BAA+B,EAC/B,oBAAoB,EACpB,6BAA6B,GAC9B,MAAM,yBAAyB,CAAC"}

package/runtime/trajectory-persistence.js

@@ -0,0 +1,47 @@
+/**
+ * Trajectory persistence — main entry point.
+ *
+ * Re-exports the full public API from the decomposed sub-modules:
+ *   - trajectory-internals.ts       — shared internal helpers, types, utilities
+ *   - trajectory-storage.ts        — trajectory write operations
+ *   - trajectory-query.ts          — trajectory read operations
+ *   - trajectory-export.ts         — export and archive operations
+ *   - trajectory-steps-reader.ts   — CQRS reader for the dedicated steps table
+ *   - trajectory-steps-writer.ts   — CQRS writer for the dedicated steps table
+ *
+ * Types are defined in ../types/trajectory.ts.
+ *
+ * Step storage:
+ *   - Canonical store: `trajectory_steps` table (one row per step).
+ *   - Legacy fallback: `trajectories.steps_json` JSONB blob.
+ *   - Migration direction: forward only. On first boot after this change,
+ *     `ensureTrajectoriesTable` migrates rows from JSONB into the new table.
+ *     Writes go to both stores; reads prefer the new table and fall back
+ *     to JSONB.
+ *   - Scripts: no character cap on the dedicated `script` TEXT column.
+ *     The legacy `TRAJECTORY_STEP_SCRIPT_MAX_CHARS=4096` cap remains
+ *     applied to the JSONB fallback.
+ */
+// ---------------------------------------------------------------------------
+// Internal helpers (exported for testing / advanced consumers)
+// ---------------------------------------------------------------------------
+export { computeBySource, extractInsightsFromResponse, extractRows, flushObservationBuffer, pushChatExchange, readOrchestratorTrajectoryContext, shouldEnableTrajectoryLoggingByDefault, 
+// Testing helpers
+shouldRunObservationExtraction, truncateField, truncateRecord, } from "./trajectory-internals.js";
+// ---------------------------------------------------------------------------
+// Query — read operations
+// ---------------------------------------------------------------------------
+export { loadPersistedTrajectoryRows } from "./trajectory-query.js";
+// ---------------------------------------------------------------------------
+// Steps — CQRS reader/writer for the dedicated trajectory_steps table
+// ---------------------------------------------------------------------------
+export { DEFAULT_GET_STEPS_LIMIT, getSteps, loadAllStepsForTrajectory, MAX_GET_STEPS_LIMIT, } from "./trajectory-steps-reader.js";
+export { clearAllSteps, deleteStepsForTrajectories, replaceStepsForTrajectory, upsertStep, } from "./trajectory-steps-writer.js";
+// ---------------------------------------------------------------------------
+// Storage — write operations
+// ---------------------------------------------------------------------------
+export { annotateTrajectoryStep, clearPersistedTrajectoryRows, completeTrajectoryStepInDatabase, createDatabaseTrajectoryLogger, DatabaseTrajectoryLogger, deletePersistedTrajectoryRows, flushTrajectoryWrites, installDatabaseTrajectoryLogger, pruneOldTrajectories, startTrajectoryStepInDatabase, } from "./trajectory-storage.js";
+// ---------------------------------------------------------------------------
+// Export — archive operations (available via "./trajectory-export" for
+// advanced consumers; not re-exported here to preserve the original API surface)
+// ---------------------------------------------------------------------------

package/runtime/trajectory-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trajectory-query.d.ts","sourceRoot":"","sources":["../../src/runtime/trajectory-query.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAenD,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,aAAa,EACtB,OAAO,SAAO,GACb,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC,CAuB3C"}

package/runtime/trajectory-query.js

@@ -0,0 +1,29 @@
+/**
+ * Trajectory query — read operations.
+ *
+ * Handles listing, loading, searching, and filtering trajectories.
+ */
+import { logger } from "@elizaos/core";
+import { asRecord, ensureTrajectoriesTable, executeRawSql, extractRows, hasRuntimeDb, } from "./trajectory-internals.js";
+// ---------------------------------------------------------------------------
+// Public read API
+// ---------------------------------------------------------------------------
+export async function loadPersistedTrajectoryRows(runtime, maxRows = 5000) {
+    if (!hasRuntimeDb(runtime))
+        return null;
+    const tableReady = await ensureTrajectoriesTable(runtime);
+    if (!tableReady)
+        return [];
+    const safeLimit = Math.max(1, Math.min(10000, Math.trunc(maxRows)));
+    try {
+        const result = await executeRawSql(runtime, `SELECT * FROM trajectories ORDER BY created_at DESC LIMIT ${safeLimit}`);
+        const rows = extractRows(result);
+        return rows
+            .map((row) => asRecord(row))
+            .filter((row) => Boolean(row));
+    }
+    catch (error) {
+        logger.warn(`[trajectory-query] Failed to load trajectory rows (agent=${runtime.agentId}): ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}

package/runtime/trajectory-steps-reader.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Trajectory steps — read operations.
+ *
+ * CQRS reader for the dedicated `trajectory_steps` table. Returns plain
+ * domain `PersistedStep` records, never mutates state.
+ *
+ * The `trajectory_steps` table replaces the JSONB blob previously stored in
+ * `trajectories.steps_json`. Scripts are no longer capped at 4096 chars.
+ */
+import type { IAgentRuntime } from "@elizaos/core";
+import type { PersistedStep } from "./trajectory-internals.ts";
+export interface TrajectoryStepsPage {
+    steps: PersistedStep[];
+    total: number;
+    offset: number;
+    limit: number;
+}
+/**
+ * Default maximum number of steps to return in a single page. Callers can
+ * override with `limit`; values above `MAX_GET_STEPS_LIMIT` are clamped.
+ */
+export declare const DEFAULT_GET_STEPS_LIMIT = 100;
+export declare const MAX_GET_STEPS_LIMIT = 1000;
+/**
+ * Paginated reader for trajectory steps. Returns steps in ordinal order
+ * (the order they were appended to the trajectory).
+ *
+ * Returns an empty page when the runtime has no database or the table
+ * does not exist. The caller is responsible for ensuring the table is
+ * created (via `ensureTrajectoriesTable`) before calling.
+ */
+export declare function getSteps(runtime: IAgentRuntime, trajectoryId: string, offset?: number, limit?: number): Promise<TrajectoryStepsPage>;
+/**
+ * Load all steps for a trajectory. Used by the existing detail-record path
+ * that returns full step lists. Returns the canonical ordinal ordering.
+ *
+ * For large trajectories prefer `getSteps()` with pagination. This loads up
+ * to `MAX_GET_STEPS_LIMIT` steps in a single query.
+ */
+export declare function loadAllStepsForTrajectory(runtime: IAgentRuntime, trajectoryId: string): Promise<PersistedStep[]>;
+//# sourceMappingURL=trajectory-steps-reader.d.ts.map

package/runtime/trajectory-steps-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trajectory-steps-reader.d.ts","sourceRoot":"","sources":["../../src/runtime/trajectory-steps-reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAc/D,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAC3C,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAwDxC;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,aAAa,EACtB,YAAY,EAAE,MAAM,EACpB,MAAM,SAAI,EACV,KAAK,SAA0B,GAC9B,OAAO,CAAC,mBAAmB,CAAC,CA6C9B;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,aAAa,EACtB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,aAAa,EAAE,CAAC,CAkB1B"}

package/runtime/trajectory-steps-reader.js

@@ -0,0 +1,129 @@
+/**
+ * Trajectory steps — read operations.
+ *
+ * CQRS reader for the dedicated `trajectory_steps` table. Returns plain
+ * domain `PersistedStep` records, never mutates state.
+ *
+ * The `trajectory_steps` table replaces the JSONB blob previously stored in
+ * `trajectories.steps_json`. Scripts are no longer capped at 4096 chars.
+ */
+import { asRecord, executeRawSql, extractRows, hasRuntimeDb, parseJsonValue, readRecordValue, sqlQuote, toNumber, toOptionalNumber, toText, } from "./trajectory-internals.js";
+/**
+ * Default maximum number of steps to return in a single page. Callers can
+ * override with `limit`; values above `MAX_GET_STEPS_LIMIT` are clamped.
+ */
+export const DEFAULT_GET_STEPS_LIMIT = 100;
+export const MAX_GET_STEPS_LIMIT = 1000;
+function rowToPersistedStep(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;
+    const evaluatorName = typeof payloadRecord.evaluatorName === "string" &&
+        payloadRecord.evaluatorName.length > 0
+        ? payloadRecord.evaluatorName
+        : 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 } : {}),
+        ...(evaluatorName !== undefined ? { evaluatorName } : {}),
+    };
+}
+/**
+ * Paginated reader for trajectory steps. Returns steps in ordinal order
+ * (the order they were appended to the trajectory).
+ *
+ * Returns an empty page when the runtime has no database or the table
+ * does not exist. The caller is responsible for ensuring the table is
+ * created (via `ensureTrajectoriesTable`) before calling.
+ */
+export async function getSteps(runtime, trajectoryId, offset = 0, limit = DEFAULT_GET_STEPS_LIMIT) {
+    const normalizedOffset = Math.max(0, Math.trunc(offset));
+    const normalizedLimit = Math.max(1, Math.min(MAX_GET_STEPS_LIMIT, Math.trunc(limit)));
+    const empty = {
+        steps: [],
+        total: 0,
+        offset: normalizedOffset,
+        limit: normalizedLimit,
+    };
+    if (!hasRuntimeDb(runtime))
+        return empty;
+    const normalizedId = trajectoryId.trim();
+    if (!normalizedId)
+        return empty;
+    const safeId = sqlQuote(normalizedId);
+    const countResult = await executeRawSql(runtime, `SELECT count(*) AS total FROM trajectory_steps WHERE trajectory_id = ${safeId}`);
+    const countRow = asRecord(extractRows(countResult)[0]);
+    const total = toNumber(countRow?.total, 0);
+    if (total === 0)
+        return empty;
+    const pageResult = await executeRawSql(runtime, `SELECT * FROM trajectory_steps
+       WHERE trajectory_id = ${safeId}
+       ORDER BY ordinal ASC
+       LIMIT ${normalizedLimit} OFFSET ${normalizedOffset}`);
+    const rows = extractRows(pageResult);
+    const steps = rows
+        .map((row) => asRecord(row))
+        .filter((row) => Boolean(row))
+        .map(rowToPersistedStep);
+    return {
+        steps,
+        total,
+        offset: normalizedOffset,
+        limit: normalizedLimit,
+    };
+}
+/**
+ * Load all steps for a trajectory. Used by the existing detail-record path
+ * that returns full step lists. Returns the canonical ordinal ordering.
+ *
+ * For large trajectories prefer `getSteps()` with pagination. This loads up
+ * to `MAX_GET_STEPS_LIMIT` steps in a single query.
+ */
+export async function loadAllStepsForTrajectory(runtime, trajectoryId) {
+    const page = await getSteps(runtime, trajectoryId, 0, MAX_GET_STEPS_LIMIT);
+    if (page.total <= page.steps.length)
+        return page.steps;
+    const all = [...page.steps];
+    let offset = page.steps.length;
+    while (offset < page.total) {
+        const next = await getSteps(runtime, trajectoryId, offset, MAX_GET_STEPS_LIMIT);
+        if (next.steps.length === 0)
+            break;
+        all.push(...next.steps);
+        offset += next.steps.length;
+    }
+    return all;
+}

package/runtime/trajectory-steps-writer.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Trajectory steps — write operations.
+ *
+ * CQRS writer for the dedicated `trajectory_steps` table. Writers return
+ * `void` on success; failures throw or are swallowed by the caller's
+ * write-queue.
+ *
+ * Scripts are stored in a dedicated `script` TEXT column with no character
+ * cap (the legacy `TRAJECTORY_STEP_SCRIPT_MAX_CHARS=4096` cap applied only
+ * to inline JSON storage).
+ */
+import type { IAgentRuntime } from "@elizaos/core";
+import { type PersistedStep } from "./trajectory-internals.ts";
+/**
+ * Upsert a single step row. Idempotent on `id` (== step.stepId).
+ */
+export declare function upsertStep(runtime: IAgentRuntime, trajectoryId: string, step: PersistedStep, parentStepId?: string | null): Promise<void>;
+/**
+ * Replace the full step set for a trajectory in a single batch.
+ *
+ * Deletes existing rows for the trajectory, then inserts the provided
+ * steps. Used by the storage layer to keep the dedicated table in sync
+ * with the canonical in-memory step list.
+ */
+export declare function replaceStepsForTrajectory(runtime: IAgentRuntime, trajectoryId: string, steps: PersistedStep[]): Promise<void>;
+/**
+ * Delete all step rows for the given trajectory IDs. Returns the number
+ * of rows deleted, or `null` if the operation could not be performed.
+ */
+export declare function deleteStepsForTrajectories(runtime: IAgentRuntime, trajectoryIds: string[]): Promise<number | null>;
+/**
+ * Delete all step rows. Returns null if the operation failed.
+ */
+export declare function clearAllSteps(runtime: IAgentRuntime): Promise<number | null>;
+//# sourceMappingURL=trajectory-steps-writer.d.ts.map

package/runtime/trajectory-steps-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trajectory-steps-writer.d.ts","sourceRoot":"","sources":["../../src/runtime/trajectory-steps-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAGL,KAAK,aAAa,EAGnB,MAAM,2BAA2B,CAAC;AAmCnC;;GAEG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,aAAa,EACtB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,aAAa,EACnB,YAAY,GAAE,MAAM,GAAG,IAAW,GACjC,OAAO,CAAC,IAAI,CAAC,CA4Cf;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,aAAa,EACtB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,aAAa,EAAE,GACrB,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;;GAGG;AACH,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,aAAa,EACtB,aAAa,EAAE,MAAM,EAAE,GACtB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBxB;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAIxB"}

package/runtime/trajectory-steps-writer.js

@@ -0,0 +1,135 @@
+/**
+ * Trajectory steps — write operations.
+ *
+ * CQRS writer for the dedicated `trajectory_steps` table. Writers return
+ * `void` on success; failures throw or are swallowed by the caller's
+ * write-queue.
+ *
+ * Scripts are stored in a dedicated `script` TEXT column with no character
+ * cap (the legacy `TRAJECTORY_STEP_SCRIPT_MAX_CHARS=4096` cap applied only
+ * to inline JSON storage).
+ */
+import { executeRawSql, hasRuntimeDb, sqlNumber, sqlQuote, } from "./trajectory-internals.js";
+function serializeStepPayload(step) {
+    // Strip `script` from payload because it gets a dedicated column.
+    const { script: _script, ...rest } = step;
+    return JSON.stringify(rest);
+}
+function resolveStepType(step) {
+    if (step.kind === "llm" ||
+        step.kind === "action" ||
+        step.kind === "evaluator") {
+        return step.kind;
+    }
+    // Legacy rows defaulted to "llm" semantics.
+    return "llm";
+}
+function resolveStepName(step) {
+    // Evaluator steps carry their evaluator name explicitly so the trajectory
+    // viewer can identify the responsible evaluator without rummaging through
+    // llmCalls. Closes M14.
+    if (step.kind === "evaluator" && step.evaluatorName) {
+        return step.evaluatorName;
+    }
+    // Use the first llm-call purpose or provider-access name as a display label.
+    const firstCall = step.llmCalls[0];
+    if (firstCall?.purpose)
+        return firstCall.purpose;
+    const firstProvider = step.providerAccesses[0];
+    if (firstProvider?.providerName)
+        return firstProvider.providerName;
+    return null;
+}
+/**
+ * Upsert a single step row. Idempotent on `id` (== step.stepId).
+ */
+export async function upsertStep(runtime, trajectoryId, step, parentStepId = null) {
+    if (!hasRuntimeDb(runtime))
+        return;
+    const stepType = resolveStepType(step);
+    const name = resolveStepName(step);
+    const startedAt = Number.isFinite(step.timestamp) ? step.timestamp : null;
+    const endedAt = startedAt; // The legacy step shape only carried a single timestamp.
+    const payload = serializeStepPayload(step);
+    const script = typeof step.script === "string" ? step.script : null;
+    const sql = `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)},
+      ${parentStepId ? sqlQuote(parentStepId) : "NULL"},
+      ${sqlQuote(stepType)},
+      ${name ? sqlQuote(name) : "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`;
+    await executeRawSql(runtime, sql);
+}
+/**
+ * Replace the full step set for a trajectory in a single batch.
+ *
+ * Deletes existing rows for the trajectory, then inserts the provided
+ * steps. Used by the storage layer to keep the dedicated table in sync
+ * with the canonical in-memory step list.
+ */
+export async function replaceStepsForTrajectory(runtime, trajectoryId, steps) {
+    if (!hasRuntimeDb(runtime))
+        return;
+    const safeId = sqlQuote(trajectoryId);
+    await executeRawSql(runtime, `DELETE FROM trajectory_steps WHERE trajectory_id = ${safeId}`);
+    for (const step of steps) {
+        await upsertStep(runtime, trajectoryId, step, null);
+    }
+}
+/**
+ * Delete all step rows for the given trajectory IDs. Returns the number
+ * of rows deleted, or `null` if the operation could not be performed.
+ */
+export async function deleteStepsForTrajectories(runtime, trajectoryIds) {
+    if (!hasRuntimeDb(runtime))
+        return null;
+    const normalized = trajectoryIds
+        .map((id) => id.trim())
+        .filter((id) => id.length > 0);
+    if (normalized.length === 0)
+        return 0;
+    const values = normalized.map((id) => sqlQuote(id)).join(", ");
+    const result = await executeRawSql(runtime, `DELETE FROM trajectory_steps WHERE trajectory_id IN (${values}) RETURNING trajectory_id`);
+    // The result row count is an estimate; we don't strictly need it for
+    // correctness, callers use `deletePersistedTrajectoryRows` for the
+    // authoritative count.
+    if (Array.isArray(result))
+        return result.length;
+    return normalized.length;
+}
+/**
+ * Delete all step rows. Returns null if the operation failed.
+ */
+export async function clearAllSteps(runtime) {
+    if (!hasRuntimeDb(runtime))
+        return null;
+    await executeRawSql(runtime, "DELETE FROM trajectory_steps");
+    return 0;
+}

package/runtime/trajectory-storage.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Trajectory storage — write operations.
+ *
+ * Handles saving, updating, deleting trajectories, installing the database
+ * logger, and the DatabaseTrajectoryLogger service class.
+ */
+import { type IAgentRuntime, Service } from "@elizaos/core";
+import type { Trajectory, TrajectoryExportResult, TrajectoryListOptions, TrajectoryListResult, TrajectorySkillInvocation, TrajectoryStatus, TrajectoryStepKind } from "../types/trajectory.ts";
+import { type RuntimeTrajectoryExportOptions } from "./trajectory-export.ts";
+import { type CompleteStepOptions, type StartStepOptions } from "./trajectory-internals.ts";
+export type { CompleteStepOptions, StartStepOptions, } from "./trajectory-internals.ts";
+export declare function installDatabaseTrajectoryLogger(runtime: IAgentRuntime): Promise<void>;
+export declare function startTrajectoryStepInDatabase({ runtime, stepId, source, metadata, }: StartStepOptions): Promise<boolean>;
+/**
+ * Annotate an existing trajectory step with structural metadata (kind
+ * discriminator, script, child step IDs, used skills). Safe to call for any
+ * of the new trajectory step fields; passing `undefined` for a field leaves
+ * the existing value alone, while passing an explicit value overwrites.
+ */
+export declare function annotateTrajectoryStep({ runtime, stepId, kind, script, childSteps, appendChildSteps, usedSkills, appendSkillInvocations, evaluatorName, }: {
+    runtime: IAgentRuntime;
+    stepId: string;
+    kind?: TrajectoryStepKind;
+    script?: string;
+    /** Replace child steps wholesale. */
+    childSteps?: string[];
+    /** Append the given child step IDs (deduped, order preserved). */
+    appendChildSteps?: string[];
+    usedSkills?: string[];
+    /**
+     * Append per-skill invocation records (W1-T5 / M13). Multiple invocations
+     * inside the same step accumulate; callers do not need to know prior
+     * state.
+     */
+    appendSkillInvocations?: TrajectorySkillInvocation[];
+    /**
+     * Name of the evaluator that owns this step. Set when `kind === "evaluator"`
+     * so reviewers can identify the responsible evaluator. Closes M14.
+     */
+    evaluatorName?: string;
+}): Promise<boolean>;
+export declare function completeTrajectoryStepInDatabase({ runtime, stepId, status, source, metadata, }: CompleteStepOptions): Promise<boolean>;
+export declare function deletePersistedTrajectoryRows(runtime: IAgentRuntime, trajectoryIds: string[]): Promise<number | null>;
+export declare function clearPersistedTrajectoryRows(runtime: IAgentRuntime): Promise<number | null>;
+/**
+ * Wait for all pending trajectory writes to complete.
+ * Useful for tests to ensure writes are flushed before assertions.
+ */
+export declare function flushTrajectoryWrites(runtime: IAgentRuntime): Promise<void>;
+/**
+ * Database-backed trajectory logger service that implements the full API
+ * expected by trajectory-routes.ts.
+ */
+export declare class DatabaseTrajectoryLogger extends Service {
+    static serviceType: string;
+    capabilityDescription: string;
+    private enabled;
+    /**
+     * Static start method required by @elizaos/core runtime.
+     */
+    static start(runtime: IAgentRuntime): Promise<Service>;
+    initialize(): Promise<void>;
+    stop(): Promise<void>;
+    isEnabled(): boolean;
+    setEnabled(enabled: boolean): void;
+    startTrajectory(stepIdOrAgentId: string, options?: {
+        agentId?: string;
+        roomId?: string;
+        entityId?: string;
+        source?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<string>;
+    startStep(trajectoryId: string): string;
+    annotateStep(params: {
+        stepId: string;
+        kind?: TrajectoryStepKind;
+        script?: string;
+        childSteps?: string[];
+        appendChildSteps?: string[];
+        usedSkills?: string[];
+        appendSkillInvocations?: TrajectorySkillInvocation[];
+    }): Promise<void>;
+    endTrajectory(stepIdOrTrajectoryId: string, status?: TrajectoryStatus): Promise<void>;
+    logLlmCall(params: Record<string, unknown>): void;
+    logProviderAccess(params: Record<string, unknown>): void;
+    getLlmCallLogs(): readonly unknown[];
+    getProviderAccessLogs(): readonly unknown[];
+    listTrajectories(options: TrajectoryListOptions): Promise<TrajectoryListResult>;
+    getTrajectoryDetail(trajectoryId: string): Promise<Trajectory | null>;
+    getStats(): Promise<unknown>;
+    deleteTrajectories(trajectoryIds: string[]): Promise<number>;
+    clearAllTrajectories(): Promise<number>;
+    exportTrajectories(options: RuntimeTrajectoryExportOptions): Promise<TrajectoryExportResult>;
+}
+/**
+ * Create and register a database-backed trajectory logger service on the runtime.
+ */
+export declare function createDatabaseTrajectoryLogger(runtime: IAgentRuntime): DatabaseTrajectoryLogger;
+/**
+ * Archive and then delete trajectories older than `maxAgeDays`.
+ */
+export declare function pruneOldTrajectories(runtime: IAgentRuntime, maxAgeDays?: number): Promise<number | null>;
+//# sourceMappingURL=trajectory-storage.d.ts.map

package/runtime/trajectory-storage.d.ts.map

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