@elizaos/ui 2.0.0-alpha.25 → 2.0.0-alpha.333

package/packages/typescript/src/features/trajectories/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../typescript/src/features/trajectories/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAIX,MAAM,EAEN,MAAM,aAAa,CAAC;AAqLrB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAwLhC,CAAC;AAEF,eAAe,kBAAkB,CAAC;AAMlC,cAAc,sBAAsB,CAAC;AAIrC,cAAc,cAAc,CAAC;AAI7B,cAAc,UAAU,CAAC;AAIzB,cAAc,gBAAgB,CAAC;AAI/B,cAAc,eAAe,CAAC;AAI9B,cAAc,kBAAkB,CAAC;AACjC,YAAY,EACX,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAClB,0BAA0B,EAC1B,yBAAyB,GACzB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAI5D,cAAc,SAAS,CAAC"}

package/packages/typescript/src/features/trajectories/index.js

@@ -0,0 +1,332 @@
+import crypto from "node:crypto";
+import { createUniqueUuid } from "../../entities";
+import { TrajectoriesService } from "./TrajectoriesService";
+const pendingTrajectoryStepByReplyId = new Map();
+const pendingTrajectoryStepByMessageId = new Map();
+const pendingTrajectoryMessageIdByStepId = new Map();
+const pendingTrajectoryEndTargetByStepId = new Map();
+function cleanupPendingTrajectory(runtime, trajectoryStepId) {
+    const sourceMessageId = pendingTrajectoryMessageIdByStepId.get(trajectoryStepId);
+    if (sourceMessageId) {
+        pendingTrajectoryStepByMessageId.delete(sourceMessageId);
+        pendingTrajectoryStepByReplyId.delete(createUniqueUuid(runtime, sourceMessageId));
+        pendingTrajectoryMessageIdByStepId.delete(trajectoryStepId);
+    }
+    pendingTrajectoryEndTargetByStepId.delete(trajectoryStepId);
+}
+async function endPendingTrajectory(runtime, trajectoryStepId, status) {
+    const logger = TrajectoriesService.resolveFromRuntime(runtime);
+    if (!logger) {
+        cleanupPendingTrajectory(runtime, trajectoryStepId);
+        return;
+    }
+    try {
+        const endTarget = pendingTrajectoryEndTargetByStepId.get(trajectoryStepId) ??
+            trajectoryStepId;
+        await logger.endTrajectory(endTarget, status);
+    }
+    finally {
+        cleanupPendingTrajectory(runtime, trajectoryStepId);
+    }
+}
+function getFinalStatusForRun(payload) {
+    if (payload.status === "timeout") {
+        return "timeout";
+    }
+    return payload.status === "completed" ? "completed" : "terminated";
+}
+const WEB_CONVERSATION_STRING_KEYS = [
+    "conversationId",
+    "scope",
+    "automationType",
+    "taskId",
+    "triggerId",
+    "workflowId",
+    "workflowName",
+    "draftId",
+    "pageId",
+    "sourceConversationId",
+    "terminalBridgeConversationId",
+];
+function asRecord(value) {
+    return value && typeof value === "object"
+        ? value
+        : undefined;
+}
+function readNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : undefined;
+}
+function copyJsonMetadataField(target, source, key) {
+    const value = source[key];
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        target[key] = value;
+    }
+}
+function readStoredWebConversation(roomMetadata) {
+    const stored = asRecord(asRecord(roomMetadata)?.webConversation);
+    if (!stored)
+        return undefined;
+    const webConversation = {};
+    for (const key of WEB_CONVERSATION_STRING_KEYS) {
+        const value = readNonEmptyString(stored[key]);
+        if (value)
+            webConversation[key] = value;
+    }
+    return Object.keys(webConversation).length > 0 ? webConversation : undefined;
+}
+async function buildTrajectoryMetadata(runtime, message, meta) {
+    const metadata = {
+        roomId: message.roomId,
+        entityId: message.entityId,
+    };
+    if (typeof message.id === "string" && message.id.length > 0) {
+        metadata.messageId = message.id;
+    }
+    const channelType = typeof meta.channelType === "string" && meta.channelType.length > 0
+        ? meta.channelType
+        : typeof message.content?.channelType === "string" &&
+            message.content.channelType.length > 0
+            ? message.content.channelType
+            : null;
+    if (channelType) {
+        metadata.channelType = channelType;
+    }
+    if (typeof meta.sessionKey === "string" && meta.sessionKey.length > 0) {
+        metadata.conversationId = meta.sessionKey;
+    }
+    for (const key of [
+        "taskId",
+        "surface",
+        "surfaceVersion",
+        "pageId",
+        "sourceConversationId",
+        "scenarioId",
+        "batchId",
+    ]) {
+        copyJsonMetadataField(metadata, meta, key);
+    }
+    try {
+        const room = await runtime.getRoom(message.roomId);
+        const webConversation = readStoredWebConversation(room?.metadata);
+        if (webConversation) {
+            metadata.webConversation = webConversation;
+            const scope = readNonEmptyString(webConversation.scope);
+            if (scope?.startsWith("page-")) {
+                if (!metadata.taskId)
+                    metadata.taskId = scope;
+                if (!metadata.surface)
+                    metadata.surface = "page-scoped";
+                if (!metadata.pageId && webConversation.pageId) {
+                    metadata.pageId = webConversation.pageId;
+                }
+                if (!metadata.sourceConversationId &&
+                    webConversation.sourceConversationId) {
+                    metadata.sourceConversationId = webConversation.sourceConversationId;
+                }
+            }
+        }
+    }
+    catch {
+        // Room metadata is enrichment; the trajectory itself should still be written.
+    }
+    return metadata;
+}
+/**
+ * Native trajectories plugin.
+ *
+ * Captures complete agent interaction trajectories for:
+ * - Debugging and analysis (UI viewing)
+ * - RL training data collection
+ * - Export to various formats (JSON, ART, CSV)
+ *
+ * Registers the native "trajectories" service so the runtime can automatically
+ * log LLM calls and provider accesses when trajectory capture is active.
+ */
+export const trajectoriesPlugin = {
+    name: "trajectories",
+    description: "Captures and persists complete agent interaction trajectories for debugging, analysis, and RL training. " +
+        "Records LLM calls, provider accesses, actions, environment state, and computes rewards.",
+    dependencies: ["@elizaos/plugin-sql"],
+    services: [TrajectoriesService],
+    events: {
+        MESSAGE_RECEIVED: [
+            async (payload) => {
+                const { runtime, message, source } = payload;
+                if (!message || !runtime)
+                    return;
+                // Ensure metadata is initialized
+                if (!message.metadata) {
+                    message.metadata = {
+                        type: "message",
+                    };
+                }
+                const meta = message.metadata;
+                const logger = TrajectoriesService.resolveFromRuntime(runtime);
+                if (!logger)
+                    return;
+                // Start trajectory
+                let trajectoryStepId = crypto.randomUUID();
+                meta.trajectoryStepId = trajectoryStepId;
+                try {
+                    const trajectoryMetadata = await buildTrajectoryMetadata(runtime, message, meta);
+                    const trajectoryId = await logger.startTrajectory(runtime.agentId, {
+                        source: source ?? meta.source ?? "chat",
+                        metadata: trajectoryMetadata,
+                    });
+                    const normalizedTrajectoryId = typeof trajectoryId === "string" && trajectoryId.trim().length > 0
+                        ? trajectoryId
+                        : null;
+                    if (normalizedTrajectoryId) {
+                        const runtimeStepId = logger.startStep(normalizedTrajectoryId, {
+                            timestamp: Date.now(),
+                            agentBalance: 0,
+                            agentPoints: 0,
+                            agentPnL: 0,
+                            openPositions: 0,
+                        });
+                        const normalizedStepId = typeof runtimeStepId === "string" &&
+                            runtimeStepId.trim().length > 0
+                            ? runtimeStepId
+                            : trajectoryStepId;
+                        trajectoryStepId = normalizedStepId;
+                        meta.trajectoryStepId = trajectoryStepId;
+                        pendingTrajectoryEndTargetByStepId.set(trajectoryStepId, normalizedTrajectoryId);
+                        if (typeof logger.flushWriteQueue === "function") {
+                            await logger.flushWriteQueue(normalizedTrajectoryId);
+                        }
+                    }
+                    else {
+                        // Fallback if startTrajectory returns empty/null
+                        // This path uses the stepId as the trajectoryId which matches legacy behavior
+                        // provided the logger supports it, but here we are using the new service.
+                        // If new service returns null, something is wrong, but we proceed best effort.
+                    }
+                    if (message.id) {
+                        const replyId = createUniqueUuid(runtime, message.id);
+                        pendingTrajectoryStepByReplyId.set(replyId, trajectoryStepId);
+                        pendingTrajectoryStepByMessageId.set(message.id, trajectoryStepId);
+                        pendingTrajectoryMessageIdByStepId.set(trajectoryStepId, message.id);
+                    }
+                }
+                catch (err) {
+                    runtime.logger?.warn({
+                        err,
+                        src: "trajectories",
+                        roomId: message.roomId,
+                    }, "Failed to start trajectory logging");
+                }
+            },
+        ],
+        MESSAGE_SENT: [
+            async (payload) => {
+                const { runtime, message } = payload;
+                if (!message || !runtime)
+                    return;
+                const meta = message.metadata;
+                const inReplyTo = typeof message.content === "object" &&
+                    message.content !== null &&
+                    "inReplyTo" in message.content &&
+                    typeof message.content.inReplyTo ===
+                        "string"
+                    ? message.content.inReplyTo
+                    : undefined;
+                let trajectoryStepId = meta?.trajectoryStepId;
+                if (!trajectoryStepId && inReplyTo) {
+                    trajectoryStepId = pendingTrajectoryStepByReplyId.get(inReplyTo);
+                }
+                if (!trajectoryStepId)
+                    return;
+                try {
+                    await endPendingTrajectory(runtime, trajectoryStepId, "completed");
+                }
+                catch (err) {
+                    runtime.logger?.warn({
+                        err,
+                        src: "trajectories",
+                        trajectoryStepId,
+                    }, "Failed to end trajectory logging");
+                }
+            },
+        ],
+        RUN_ENDED: [
+            async (payload) => {
+                const { runtime, messageId } = payload;
+                if (!runtime || !messageId)
+                    return;
+                const trajectoryStepId = pendingTrajectoryStepByMessageId.get(messageId);
+                if (!trajectoryStepId)
+                    return;
+                try {
+                    await endPendingTrajectory(runtime, trajectoryStepId, getFinalStatusForRun(payload));
+                }
+                catch (err) {
+                    runtime.logger?.warn({
+                        err,
+                        src: "trajectories",
+                        messageId,
+                        trajectoryStepId,
+                    }, "Failed to end trajectory logging on run completion");
+                }
+            },
+        ],
+        RUN_TIMEOUT: [
+            async (payload) => {
+                const { runtime, messageId } = payload;
+                if (!runtime || !messageId)
+                    return;
+                const trajectoryStepId = pendingTrajectoryStepByMessageId.get(messageId);
+                if (!trajectoryStepId)
+                    return;
+                try {
+                    await endPendingTrajectory(runtime, trajectoryStepId, "timeout");
+                }
+                catch (err) {
+                    runtime.logger?.warn({
+                        err,
+                        src: "trajectories",
+                        messageId,
+                        trajectoryStepId,
+                    }, "Failed to end trajectory logging on run timeout");
+                }
+            },
+        ],
+    },
+};
+export default trajectoriesPlugin;
+// ==========================================
+// ACTION-LEVEL INSTRUMENTATION
+// For manual trajectory collection in actions
+// ==========================================
+export * from "./action-interceptor";
+// ==========================================
+// TRAJECTORY FORMAT CONVERSION
+// ==========================================
+export * from "./art-format";
+// ==========================================
+// DATA EXPORT
+// ==========================================
+export * from "./export";
+// ==========================================
+// GAME-KNOWLEDGE REWARDS
+// ==========================================
+export * from "./game-rewards";
+// ==========================================
+// ADVANCED: Manual Instrumentation
+// ==========================================
+export * from "./integration";
+// ==========================================
+// OPTIONAL: Heuristic Rewards
+// ==========================================
+export * from "./reward-service";
+// ==========================================
+// SERVICE (Core trajectory logging)
+// ==========================================
+export { TrajectoriesService } from "./TrajectoriesService";
+// ==========================================
+// CORE TYPES
+// ==========================================
+export * from "./types";

package/packages/typescript/src/features/trajectories/integration.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Manual Instrumentation Helpers
+ *
+ * Advanced manual control for trajectory logging.
+ */
+import type { TrajectoriesService } from "./TrajectoriesService";
+import type { JsonValue } from "./types";
+export interface TrajectoryMetadata {
+    [key: string]: JsonValue;
+}
+export type FinalMetrics = Record<string, JsonValue> & {
+    totalReward?: number;
+    stepCount?: number;
+    successRate?: number;
+};
+export interface ProviderAccessData {
+    [key: string]: JsonValue;
+}
+export type WrappedFunctionArgs = JsonValue[];
+export declare function startAutonomousTick(trajectoryLogger: TrajectoriesService, context: {
+    agentId: string;
+    source?: string;
+    scenarioId?: string;
+    episodeId?: string;
+    batchId?: string;
+    metadata?: TrajectoryMetadata;
+}): Promise<string>;
+export declare function endAutonomousTick(trajectoryLogger: TrajectoriesService, trajectoryId: string, status?: "completed" | "terminated" | "error" | "timeout", finalMetrics?: FinalMetrics): Promise<void>;
+export declare function loggedLLMCall(trajectoryLogger: TrajectoriesService, trajectoryId: string, options: {
+    model: string;
+    modelVersion?: string;
+    systemPrompt: string;
+    userPrompt: string;
+    temperature?: number;
+    maxTokens?: number;
+    purpose?: string;
+    actionType?: string;
+}, llmCallFn: () => Promise<{
+    text: string;
+    reasoning?: string;
+    tokens?: {
+        prompt?: number;
+        completion?: number;
+    };
+    latencyMs?: number;
+}>): Promise<string>;
+export declare function logProviderAccess(trajectoryLogger: TrajectoriesService, trajectoryId: string, access: {
+    providerName: string;
+    data: ProviderAccessData;
+    purpose: string;
+    query?: ProviderAccessData;
+}): void;
+type AsyncFunction<TArgs extends JsonValue[], TResult extends JsonValue> = (...args: TArgs) => Promise<TResult>;
+export declare function withTrajectoryLogging<TArgs extends JsonValue[], TResult extends JsonValue>(fn: AsyncFunction<TArgs, TResult>, trajectoryLogger: TrajectoriesService, trajectoryId: string, context?: {
+    actionType?: string;
+    purpose?: string;
+}): AsyncFunction<TArgs, TResult>;
+export {};
+//# sourceMappingURL=integration.d.ts.map

package/packages/typescript/src/features/trajectories/integration.d.ts.map

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

package/packages/typescript/src/features/trajectories/integration.js

@@ -0,0 +1,83 @@
+/**
+ * Manual Instrumentation Helpers
+ *
+ * Advanced manual control for trajectory logging.
+ */
+import { logger } from "../../logger";
+export async function startAutonomousTick(trajectoryLogger, context) {
+    const trajectoryId = await trajectoryLogger.startTrajectory(context.agentId, {
+        source: context.source,
+        scenarioId: context.scenarioId,
+        episodeId: context.episodeId,
+        batchId: context.batchId,
+        metadata: context.metadata,
+    });
+    const envState = {
+        timestamp: Date.now(),
+        agentBalance: 0,
+        agentPoints: 0,
+        agentPnL: 0,
+        openPositions: 0,
+    };
+    trajectoryLogger.startStep(trajectoryId, envState);
+    logger.info({ trajectoryId, agentId: context.agentId }, "Started autonomous tick trajectory");
+    return trajectoryId;
+}
+export async function endAutonomousTick(trajectoryLogger, trajectoryId, status = "completed", finalMetrics) {
+    // Flush pending fire-and-forget writes (logLLMCall, completeStep) before
+    // endTrajectory reads the trajectory so recorded LLM calls are persisted.
+    const flush = trajectoryLogger
+        .flushWriteQueue;
+    if (typeof flush === "function") {
+        await flush(trajectoryId);
+    }
+    await trajectoryLogger.endTrajectory(trajectoryId, status, finalMetrics);
+    logger.info({ trajectoryId, status }, "Ended autonomous tick trajectory");
+}
+export async function loggedLLMCall(trajectoryLogger, trajectoryId, options, llmCallFn) {
+    const stepId = trajectoryLogger.getCurrentStepId(trajectoryId);
+    if (!stepId) {
+        logger.warn({ trajectoryId }, "No active step for LLM call");
+        const result = await llmCallFn();
+        return result.text;
+    }
+    const startTime = Date.now();
+    const result = await llmCallFn();
+    const latencyMs = Date.now() - startTime;
+    trajectoryLogger.logLLMCall(stepId, {
+        model: options.model,
+        modelVersion: options.modelVersion,
+        systemPrompt: options.systemPrompt,
+        userPrompt: options.userPrompt,
+        response: result.text,
+        reasoning: result.reasoning,
+        temperature: options.temperature || 0.7,
+        maxTokens: options.maxTokens || 8192,
+        purpose: options.purpose || "action",
+        actionType: options.actionType,
+        promptTokens: result.tokens?.prompt,
+        completionTokens: result.tokens?.completion,
+        latencyMs: result.latencyMs || latencyMs,
+    });
+    return result.text;
+}
+export function logProviderAccess(trajectoryLogger, trajectoryId, access) {
+    trajectoryLogger.logProviderAccessByTrajectoryId(trajectoryId, access);
+}
+export function withTrajectoryLogging(fn, trajectoryLogger, trajectoryId, context = {}) {
+    return async (...args) => {
+        const stepId = trajectoryLogger.getCurrentStepId(trajectoryId);
+        if (!stepId) {
+            return fn(...args);
+        }
+        const result = await fn(...args);
+        trajectoryLogger.completeStep(trajectoryId, stepId, {
+            actionType: context.actionType || "function_call",
+            actionName: fn.name || "anonymous",
+            parameters: { args: args },
+            success: true,
+            result: result !== undefined ? { result } : { result: null },
+        }, { reward: 0.05 });
+        return result;
+    };
+}

package/packages/typescript/src/features/trajectories/reward-service.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Heuristic Rewards
+ *
+ * Use heuristic scoring to score trajectories when game knowledge isn't available.
+ */
+import type { Trajectory } from "./types";
+export interface RewardServiceOptions {
+    archetype?: string;
+    useHeuristics?: boolean;
+}
+export declare class RewardService {
+    private options;
+    constructor(options?: RewardServiceOptions);
+    scoreTrajectory(trajectory: Trajectory): Promise<number>;
+    scoreTrajectoryGroup(trajectories: Trajectory[]): Promise<number[]>;
+    private computeHeuristicReward;
+    private normalizePnL;
+    private normalizeScore;
+    private normalizeScoresForGroup;
+}
+export declare function createRewardService(options?: RewardServiceOptions): RewardService;
+export declare function scoreTrajectory(trajectory: Trajectory): Promise<number>;
+export declare function scoreTrajectoryGroup(trajectories: Trajectory[]): Promise<number[]>;
+//# sourceMappingURL=reward-service.d.ts.map

package/packages/typescript/src/features/trajectories/reward-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reward-service.d.ts","sourceRoot":"","sources":["../../../../../../../typescript/src/features/trajectories/reward-service.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAoB,UAAU,EAAE,MAAM,SAAS,CAAC;AAE5D,MAAM,WAAW,oBAAoB;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,qBAAa,aAAa;IACzB,OAAO,CAAC,OAAO,CAAuB;gBAE1B,OAAO,GAAE,oBAAyB;IAIxC,eAAe,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAOxD,oBAAoB,CAAC,YAAY,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAkBzE,OAAO,CAAC,sBAAsB;IAwC9B,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,uBAAuB;CAW/B;AAED,wBAAgB,mBAAmB,CAClC,OAAO,GAAE,oBAAyB,GAChC,aAAa,CAEf;AAED,wBAAsB,eAAe,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAG7E;AAED,wBAAsB,oBAAoB,CACzC,YAAY,EAAE,UAAU,EAAE,GACxB,OAAO,CAAC,MAAM,EAAE,CAAC,CAGnB"}

package/packages/typescript/src/features/trajectories/reward-service.js

@@ -0,0 +1,89 @@
+/**
+ * Heuristic Rewards
+ *
+ * Use heuristic scoring to score trajectories when game knowledge isn't available.
+ */
+export class RewardService {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async scoreTrajectory(trajectory) {
+        if (this.options.useHeuristics !== false) {
+            return this.computeHeuristicReward(trajectory);
+        }
+        return this.computeHeuristicReward(trajectory);
+    }
+    async scoreTrajectoryGroup(trajectories) {
+        if (trajectories.length === 0) {
+            return [];
+        }
+        if (trajectories.length === 1) {
+            const first = trajectories[0];
+            if (!first)
+                return [];
+            const score = await this.scoreTrajectory(first);
+            return [this.normalizeScore(score)];
+        }
+        const rawScores = await Promise.all(trajectories.map((t) => this.scoreTrajectory(t)));
+        return this.normalizeScoresForGroup(rawScores);
+    }
+    computeHeuristicReward(trajectory) {
+        const components = trajectory.rewardComponents;
+        const metrics = trajectory.metrics;
+        let reward = 0;
+        let weightSum = 0;
+        // 1. P&L (weight 0.4)
+        if (metrics.finalPnL !== undefined) {
+            const pnlScore = this.normalizePnL(metrics.finalPnL);
+            reward += pnlScore * 0.4;
+            weightSum += 0.4;
+        }
+        // 2. Success rate (weight 0.3)
+        if (metrics.successRate !== undefined) {
+            const successScore = metrics.successRate * 2 - 1; // 0-1 -> -1..1
+            reward += successScore * 0.3;
+            weightSum += 0.3;
+        }
+        // 3. Completion (weight 0.2)
+        const completionScore = metrics.finalStatus === "completed" ? 1 : -0.5;
+        reward += completionScore * 0.2;
+        weightSum += 0.2;
+        // 4. Environment reward (weight 0.1)
+        if (components.environmentReward !== undefined) {
+            const envScore = Math.max(-1, Math.min(1, components.environmentReward));
+            reward += envScore * 0.1;
+            weightSum += 0.1;
+        }
+        if (weightSum > 0) {
+            reward = reward / weightSum;
+        }
+        return Math.max(-1, Math.min(1, reward));
+    }
+    normalizePnL(pnl) {
+        return Math.tanh(pnl / 500);
+    }
+    normalizeScore(score) {
+        return (score + 1) / 2;
+    }
+    normalizeScoresForGroup(scores) {
+        const min = Math.min(...scores);
+        const max = Math.max(...scores);
+        const range = max - min;
+        if (range === 0) {
+            return scores.map(() => 0.5);
+        }
+        return scores.map((s) => (s - min) / range);
+    }
+}
+export function createRewardService(options = {}) {
+    return new RewardService(options);
+}
+export async function scoreTrajectory(trajectory) {
+    const service = new RewardService();
+    return service.scoreTrajectory(trajectory);
+}
+export async function scoreTrajectoryGroup(trajectories) {
+    const service = new RewardService();
+    return service.scoreTrajectoryGroup(trajectories);
+}