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

package/packages/typescript/src/streaming-context.js

@@ -0,0 +1,160 @@
+/**
+ * Streaming context management for automatic streaming in useModel calls.
+ *
+ * Follows the OpenTelemetry ContextManager pattern:
+ * - Interface for context management
+ * - Platform-specific implementations (Node.js AsyncLocalStorage, Browser Stack)
+ * - Auto-detected at runtime - no separate entry points needed
+ *
+ * @see https://opentelemetry.io/docs/languages/js/context/
+ */
+/**
+ * Stack-based context manager for browser environments.
+ * Safe because browser typically has 1 runtime per request.
+ * Supports nested contexts via stack push/pop.
+ */
+class StackContextManager {
+    stack = [];
+    run(context, fn) {
+        this.stack.push(context);
+        try {
+            return fn();
+        }
+        finally {
+            this.stack.pop();
+        }
+    }
+    active() {
+        return this.stack.length > 0
+            ? this.stack[this.stack.length - 1]
+            : undefined;
+    }
+}
+// Global singleton - auto-configured on first access
+let globalContextManager = null;
+function isNodeEnvironment() {
+    return (typeof process !== "undefined" &&
+        typeof process.versions !== "undefined" &&
+        typeof process.versions.node !== "undefined");
+}
+// Initialize synchronously to avoid the race where early calls use the
+// StackContextManager fallback (which doesn't propagate through async/await).
+function initContextManagerSync() {
+    if (isNodeEnvironment()) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { AsyncLocalStorage } = require("node:async_hooks");
+            const storage = new AsyncLocalStorage();
+            return {
+                run(context, fn) {
+                    return storage.run(context, fn);
+                },
+                active() {
+                    return storage.getStore();
+                },
+            };
+        }
+        catch {
+            // AsyncLocalStorage unavailable — fall back to stack
+        }
+    }
+    return new StackContextManager();
+}
+function getOrCreateContextManager() {
+    if (!globalContextManager) {
+        globalContextManager = initContextManagerSync();
+    }
+    return globalContextManager;
+}
+/**
+ * Set the global streaming context manager.
+ * Can be used to override the auto-detected manager.
+ *
+ * @param manager - The context manager to use globally
+ */
+export function setStreamingContextManager(manager) {
+    globalContextManager = manager;
+}
+/**
+ * Get the global streaming context manager.
+ * Auto-detects and creates the appropriate manager on first access.
+ */
+export function getStreamingContextManager() {
+    return getOrCreateContextManager();
+}
+/**
+ * Run a function with a streaming context.
+ * All useModel calls within this function will automatically use streaming.
+ *
+ * @example
+ * ```typescript
+ * await runWithStreamingContext(
+ *   { onStreamChunk: async (chunk) => sendSSE(chunk), messageId },
+ *   async () => {
+ *     // All useModel calls here will stream automatically
+ *     await runtime.processMessage(message);
+ *   }
+ * );
+ * ```
+ *
+ * @param context - The streaming context with onStreamChunk callback
+ * @param fn - The function to run with streaming context
+ * @returns The result of the function
+ */
+export function runWithStreamingContext(context, fn) {
+    return getOrCreateContextManager().run(context, fn);
+}
+/**
+ * Get the currently active streaming context.
+ * Called by useModel to check if automatic streaming should be enabled.
+ *
+ * @returns The current streaming context or undefined
+ */
+export function getStreamingContext() {
+    return getOrCreateContextManager().active();
+}
+// ---------------------------------------------------------------------------
+// useModel → chunk callback delivery (dedupe `model_stream_chunk` hooks)
+// ---------------------------------------------------------------------------
+// The same provider chunk is often forwarded from useModel's textStream loop *and* from
+// DefaultMessageService. Without a turn-scoped marker, pipeline hooks would run twice per
+// token (inflated metrics, duplicate side effects). Node uses AsyncLocalStorage depth so
+// nested async work stays scoped; non-Node has no ALS store and returns depth 0 (no skip).
+// See docs/PIPELINE_HOOKS.md § "Stream hook dedupe (Node)".
+let modelStreamChunkDeliveryDepthStorage = null;
+let modelStreamChunkDeliveryStorageInitialized = false;
+function getModelStreamChunkDeliveryStorage() {
+    if (!modelStreamChunkDeliveryStorageInitialized) {
+        modelStreamChunkDeliveryStorageInitialized = true;
+        if (isNodeEnvironment()) {
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-require-imports
+                const { AsyncLocalStorage } = require("node:async_hooks");
+                modelStreamChunkDeliveryDepthStorage = new AsyncLocalStorage();
+            }
+            catch {
+                modelStreamChunkDeliveryDepthStorage = null;
+            }
+        }
+    }
+    return modelStreamChunkDeliveryDepthStorage;
+}
+/**
+ * While `> 0`, the runtime is inside `useModel`'s delivery of one `textStream` chunk to
+ * `paramsChunk` / `ctxChunk` (after `model_stream_chunk` with `source: "use_model"`).
+ * `DefaultMessageService` skips its own `model_stream_chunk` (`source: "message_service"`) in
+ * this window so the same raw token is not processed twice. Non-Node environments return `0`.
+ */
+export function getModelStreamChunkDeliveryDepth() {
+    const s = getModelStreamChunkDeliveryStorage();
+    return s?.getStore() ?? 0;
+}
+/** Wrap `paramsChunk` / `ctxChunk` invocations from `useModel`'s stream loop. */
+export function runInsideModelStreamChunkDelivery(fn) {
+    const s = getModelStreamChunkDeliveryStorage();
+    if (!s) {
+        return fn();
+    }
+    const parent = s.getStore() ?? 0;
+    return s.run(parent + 1, fn);
+}

package/packages/typescript/src/trajectory-context.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Trajectory context management for benchmark/training traces.
+ *
+ * Node.js: AsyncLocalStorage for async-safe propagation (initialized
+ * synchronously to avoid race with first message processing).
+ * Browser: stack-based fallback.
+ */
+export interface TrajectoryContext {
+    trajectoryStepId?: string;
+    /** Current runtime run identifier associated with the active trajectory step. */
+    runId?: string;
+    /** Room context for pipeline/model hooks emitted during trajectory logging. */
+    roomId?: string;
+    /** Source message identifier associated with the active trajectory context. */
+    messageId?: string;
+    /** Pipeline stage purpose for trajectory logging (e.g. "should_respond", "response", "action", "evaluation"). */
+    purpose?: string;
+    /**
+     * Step ID of the parent trajectory step, when the current step was
+     * dispatched from inside another (e.g. an action invoked through
+     * `executeCode`). Persistence layers use this to attach child step IDs
+     * to the parent's `childSteps` array.
+     */
+    parentStepId?: string;
+}
+export interface ITrajectoryContextManager {
+    run<T>(context: TrajectoryContext | undefined, fn: () => T | Promise<T>): T | Promise<T>;
+    active(): TrajectoryContext | undefined;
+}
+export declare function setTrajectoryContextManager(manager: ITrajectoryContextManager): void;
+export declare function getTrajectoryContextManager(): ITrajectoryContextManager;
+export declare function runWithTrajectoryContext<T>(context: TrajectoryContext | undefined, fn: () => T | Promise<T>): T | Promise<T>;
+export declare function getTrajectoryContext(): TrajectoryContext | undefined;
+/**
+ * Set the pipeline purpose on the current trajectory context.
+ * Mutates in place so nested useModel calls pick up the correct stage.
+ */
+export declare function setTrajectoryPurpose(purpose: string): void;
+//# sourceMappingURL=trajectory-context.d.ts.map

package/packages/typescript/src/trajectory-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trajectory-context.d.ts","sourceRoot":"","sources":["../../../../../typescript/src/trajectory-context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IACjC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iHAAiH;IACjH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,yBAAyB;IACzC,GAAG,CAAC,CAAC,EACJ,OAAO,EAAE,iBAAiB,GAAG,SAAS,EACtC,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACtB,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAClB,MAAM,IAAI,iBAAiB,GAAG,SAAS,CAAC;CACxC;AAwFD,wBAAgB,2BAA2B,CAC1C,OAAO,EAAE,yBAAyB,GAChC,IAAI,CAKN;AAED,wBAAgB,2BAA2B,IAAI,yBAAyB,CAEvE;AAED,wBAAgB,wBAAwB,CAAC,CAAC,EACzC,OAAO,EAAE,iBAAiB,GAAG,SAAS,EACtC,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACtB,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAEhB;AAED,wBAAgB,oBAAoB,IAAI,iBAAiB,GAAG,SAAS,CAEpE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAG1D"}

package/packages/typescript/src/trajectory-context.js

@@ -0,0 +1,85 @@
+class StackContextManager {
+    stack = [];
+    run(context, fn) {
+        this.stack.push(context);
+        try {
+            return fn();
+        }
+        finally {
+            this.stack.pop();
+        }
+    }
+    active() {
+        return this.stack.length > 0
+            ? this.stack[this.stack.length - 1]
+            : undefined;
+    }
+}
+// Initialize the context manager synchronously in Node.js so that
+// AsyncLocalStorage is available before the first message is processed.
+// The previous lazy async init (.then()) caused a race: the stack-based
+// fallback was used for early messages, which doesn't propagate context
+// through async/await — so logLlmCall never saw the trajectory step ID.
+let globalContextManager = null;
+const TRAJECTORY_CONTEXT_MANAGER_KEY = Symbol.for("elizaos.trajectoryContextManager");
+function isNodeEnvironment() {
+    return (typeof process !== "undefined" &&
+        typeof process.versions !== "undefined" &&
+        typeof process.versions.node !== "undefined");
+}
+function initContextManagerSync() {
+    if (isNodeEnvironment()) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { AsyncLocalStorage } = require("node:async_hooks");
+            const storage = new AsyncLocalStorage();
+            return {
+                run(context, fn) {
+                    return storage.run(context, fn);
+                },
+                active() {
+                    return storage.getStore();
+                },
+            };
+        }
+        catch {
+            // AsyncLocalStorage unavailable — fall back to stack
+        }
+    }
+    return new StackContextManager();
+}
+function getOrCreateContextManager() {
+    if (!globalContextManager) {
+        const globalManager = globalThis[TRAJECTORY_CONTEXT_MANAGER_KEY];
+        if (globalManager) {
+            globalContextManager = globalManager;
+        }
+        else {
+            globalContextManager = initContextManagerSync();
+            globalThis[TRAJECTORY_CONTEXT_MANAGER_KEY] = globalContextManager;
+        }
+    }
+    return globalContextManager;
+}
+export function setTrajectoryContextManager(manager) {
+    globalContextManager = manager;
+    globalThis[TRAJECTORY_CONTEXT_MANAGER_KEY] = manager;
+}
+export function getTrajectoryContextManager() {
+    return getOrCreateContextManager();
+}
+export function runWithTrajectoryContext(context, fn) {
+    return getOrCreateContextManager().run(context, fn);
+}
+export function getTrajectoryContext() {
+    return getOrCreateContextManager().active();
+}
+/**
+ * Set the pipeline purpose on the current trajectory context.
+ * Mutates in place so nested useModel calls pick up the correct stage.
+ */
+export function setTrajectoryPurpose(purpose) {
+    const ctx = getOrCreateContextManager().active();
+    if (ctx)
+        ctx.purpose = purpose;
+}

package/packages/typescript/src/trajectory-utils.d.ts

@@ -0,0 +1,73 @@
+import type { IAgentRuntime } from "./types/runtime";
+export type TrajectoryFinalStatus = "completed" | "error" | "timeout" | "terminated";
+export type TrajectoryLlmCallDetails = {
+    model: string;
+    modelVersion?: string;
+    systemPrompt: string;
+    userPrompt: string;
+    response: string;
+    reasoning?: string;
+    temperature: number;
+    maxTokens: number;
+    purpose: string;
+    actionType: string;
+    latencyMs: number;
+    promptTokens?: number;
+    completionTokens?: number;
+};
+type TrajectoryStartOptions = {
+    source?: string;
+    metadata?: Record<string, unknown>;
+};
+type TrajectoryStepState = {
+    timestamp: number;
+    agentBalance: number;
+    agentPoints: number;
+    agentPnL: number;
+    openPositions: number;
+};
+type TrajectoryStepKindLike = "llm" | "action" | "executeCode";
+export type TrajectoryAnnotateParams = {
+    stepId: string;
+    kind?: TrajectoryStepKindLike;
+    script?: string;
+    childSteps?: string[];
+    appendChildSteps?: string[];
+    usedSkills?: string[];
+};
+type TrajectoryLoggerLike = {
+    isEnabled?: () => boolean;
+    startTrajectory?: (agentId: string, options?: TrajectoryStartOptions) => Promise<string> | string;
+    startStep?: (trajectoryId: string, state: TrajectoryStepState) => string;
+    endTrajectory?: (stepIdOrTrajectoryId: string, status?: TrajectoryFinalStatus, finalMetrics?: Record<string, unknown>) => Promise<void> | void;
+    flushWriteQueue?: (trajectoryId: string) => Promise<void> | void;
+    logLlmCall?: (params: {
+        stepId: string;
+    } & TrajectoryLlmCallDetails) => void;
+    /**
+     * Optional. When implemented (DatabaseTrajectoryLogger does), lets a caller
+     * extend an existing step row with the new schema fields (kind, script,
+     * childSteps, usedSkills). The plugin-executecode action uses this to
+     * record its parent step + collected child step IDs without depending
+     * directly on @elizaos/agent.
+     */
+    annotateStep?: (params: TrajectoryAnnotateParams) => Promise<void> | void;
+};
+type StandaloneTrajectoryOptions = {
+    source: string;
+    metadata?: Record<string, unknown>;
+    successStatus?: TrajectoryFinalStatus;
+    errorStatus?: Exclude<TrajectoryFinalStatus, "completed">;
+};
+export declare function resolveTrajectoryLogger(runtime: IAgentRuntime): TrajectoryLoggerLike | null;
+export declare function withStandaloneTrajectory<T>(runtime: IAgentRuntime | null | undefined, options: StandaloneTrajectoryOptions, callback: () => Promise<T> | T): Promise<T>;
+/**
+ * Annotate a trajectory step via whichever trajectory logger service is
+ * registered on the runtime. Returns true when an annotate-capable service
+ * was found and called; false when no compatible service exists or it is
+ * disabled. Errors from the underlying service are propagated.
+ */
+export declare function annotateActiveTrajectoryStep(runtime: IAgentRuntime | null | undefined, params: TrajectoryAnnotateParams): Promise<boolean>;
+export declare function logActiveTrajectoryLlmCall(runtime: IAgentRuntime | null | undefined, details: TrajectoryLlmCallDetails): boolean;
+export {};
+//# sourceMappingURL=trajectory-utils.d.ts.map

package/packages/typescript/src/trajectory-utils.d.ts.map

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

package/packages/typescript/src/trajectory-utils.js

@@ -0,0 +1,124 @@
+import { getTrajectoryContext, runWithTrajectoryContext, } from "./trajectory-context";
+function isTrajectoryLoggerCandidate(value) {
+    return !!value && typeof value === "object";
+}
+export function resolveTrajectoryLogger(runtime) {
+    const candidates = [];
+    const seen = new Set();
+    const push = (candidate) => {
+        if (!isTrajectoryLoggerCandidate(candidate) || seen.has(candidate)) {
+            return;
+        }
+        seen.add(candidate);
+        candidates.push(candidate);
+    };
+    push(runtime.getService("trajectories"));
+    for (const candidate of runtime.getServicesByType("trajectories")) {
+        push(candidate);
+    }
+    let best = null;
+    let bestScore = -1;
+    for (const candidate of candidates) {
+        let score = 0;
+        if (typeof candidate.startTrajectory === "function")
+            score += 100;
+        if (typeof candidate.startStep === "function")
+            score += 10;
+        if (typeof candidate.endTrajectory === "function")
+            score += 10;
+        if (typeof candidate.logLlmCall === "function")
+            score += 10;
+        if (typeof candidate.flushWriteQueue === "function")
+            score += 2;
+        if (score > bestScore) {
+            best = candidate;
+            bestScore = score;
+        }
+    }
+    return bestScore > 0 ? best : null;
+}
+export async function withStandaloneTrajectory(runtime, options, callback) {
+    const activeStepId = getTrajectoryContext()?.trajectoryStepId;
+    if (!runtime ||
+        (typeof activeStepId === "string" && activeStepId.trim() !== "")) {
+        return await callback();
+    }
+    const trajectoryLogger = resolveTrajectoryLogger(runtime);
+    if (!trajectoryLogger ||
+        typeof trajectoryLogger.startTrajectory !== "function" ||
+        typeof trajectoryLogger.endTrajectory !== "function" ||
+        (typeof trajectoryLogger.isEnabled === "function" &&
+            !trajectoryLogger.isEnabled())) {
+        return await callback();
+    }
+    const trajectoryId = String(await trajectoryLogger.startTrajectory(runtime.agentId, {
+        source: options.source,
+        metadata: options.metadata,
+    })).trim();
+    if (!trajectoryId) {
+        return await callback();
+    }
+    const stepId = typeof trajectoryLogger.startStep === "function"
+        ? String(trajectoryLogger.startStep(trajectoryId, {
+            timestamp: Date.now(),
+            agentBalance: 0,
+            agentPoints: 0,
+            agentPnL: 0,
+            openPositions: 0,
+        })).trim() || trajectoryId
+        : trajectoryId;
+    let completed = false;
+    try {
+        const result = await runWithTrajectoryContext({ trajectoryStepId: stepId }, () => callback());
+        completed = true;
+        return result;
+    }
+    finally {
+        if (typeof trajectoryLogger.flushWriteQueue === "function") {
+            await trajectoryLogger.flushWriteQueue(trajectoryId);
+        }
+        await trajectoryLogger.endTrajectory(trajectoryId, completed
+            ? (options.successStatus ?? "completed")
+            : (options.errorStatus ?? "error"));
+    }
+}
+/**
+ * Annotate a trajectory step via whichever trajectory logger service is
+ * registered on the runtime. Returns true when an annotate-capable service
+ * was found and called; false when no compatible service exists or it is
+ * disabled. Errors from the underlying service are propagated.
+ */
+export async function annotateActiveTrajectoryStep(runtime, params) {
+    if (!runtime)
+        return false;
+    const trajectoryLogger = resolveTrajectoryLogger(runtime);
+    if (!trajectoryLogger ||
+        typeof trajectoryLogger.annotateStep !== "function" ||
+        (typeof trajectoryLogger.isEnabled === "function" &&
+            !trajectoryLogger.isEnabled())) {
+        return false;
+    }
+    await trajectoryLogger.annotateStep(params);
+    return true;
+}
+export function logActiveTrajectoryLlmCall(runtime, details) {
+    if (!runtime) {
+        return false;
+    }
+    const stepId = getTrajectoryContext()?.trajectoryStepId;
+    if (!(typeof stepId === "string" && stepId.trim() !== "")) {
+        return false;
+    }
+    const trajectoryLogger = resolveTrajectoryLogger(runtime);
+    if (!trajectoryLogger ||
+        typeof trajectoryLogger.logLlmCall !== "function" ||
+        (typeof trajectoryLogger.isEnabled === "function" &&
+            !trajectoryLogger.isEnabled())) {
+        return false;
+    }
+    trajectoryLogger.logLlmCall({
+        stepId: stepId.trim(),
+        ...details,
+    });
+    return true;
+}

package/packages/typescript/src/types/agent.d.ts

@@ -0,0 +1,62 @@
+import type { KnowledgeSourceItem } from "./knowledge";
+import type { Content } from "./primitives";
+import type { JsonValue, Agent as ProtoAgent, AgentStatus as ProtoAgentStatus, Character as ProtoCharacter, CharacterSettings as ProtoCharacterSettingsType, MessageExample as ProtoMessageExample, MessageExampleGroup as ProtoMessageExampleGroup } from "./proto.js";
+import type { State } from "./state";
+export type TemplateType = string | ((params: {
+    state: State | Record<string, string | number | boolean | null | undefined> | object;
+}) => string);
+/**
+ * Example message for demonstration
+ */
+export interface MessageExample extends Omit<ProtoMessageExample, "$typeName" | "$unknown" | "content"> {
+    content: Content;
+}
+export interface MessageExampleGroup extends Omit<ProtoMessageExampleGroup, "$typeName" | "$unknown" | "examples"> {
+    examples: MessageExample[];
+}
+export type CharacterSettings = Omit<ProtoCharacterSettingsType, "$typeName" | "$unknown" | "secrets"> & {
+    ENABLE_AUTONOMY?: boolean | string;
+    DISABLE_BASIC_CAPABILITIES?: boolean | string;
+    ENABLE_EXTENDED_CAPABILITIES?: boolean | string;
+    ADVANCED_CAPABILITIES?: boolean | string;
+    ENABLE_TRUST?: boolean | string;
+    ENABLE_SECRETS_MANAGER?: boolean | string;
+    ENABLE_PLUGIN_MANAGER?: boolean | string;
+    ENABLE_KNOWLEDGE?: boolean | string;
+    ENABLE_RELATIONSHIPS?: boolean | string;
+    ENABLE_TRAJECTORIES?: boolean | string;
+    secrets?: Record<string, string | boolean | number>;
+    [key: string]: JsonValue | undefined;
+};
+export type ProtoCharacterSettings = ProtoCharacterSettingsType;
+export type Character = Partial<Omit<ProtoCharacter, "$typeName" | "$unknown" | "settings" | "messageExamples" | "knowledge" | "secrets">> & {
+    settings?: CharacterSettings;
+    secrets?: Record<string, string | number | boolean>;
+    messageExamples?: MessageExampleGroup[];
+    knowledge?: KnowledgeSourceItem[];
+    /** Enable advanced planning capabilities for this character */
+    advancedPlanning?: boolean;
+    /** Enable advanced memory capabilities for this character */
+    advancedMemory?: boolean;
+};
+export declare enum AgentStatus {
+    ACTIVE = "active",
+    INACTIVE = "inactive"
+}
+/**
+ * Represents an operational agent, extending the `Character` definition with runtime status and timestamps.
+ * While `Character` defines the blueprint, `Agent` represents an instantiated and potentially running version.
+ * It includes:
+ * - `enabled`: A boolean indicating if the agent is currently active or disabled.
+ * - `status`: The current operational status, typically `AgentStatus.ACTIVE` or `AgentStatus.INACTIVE`.
+ * - `createdAt`, `updatedAt`: Timestamps for when the agent record was created and last updated in the database.
+ * This interface is primarily used by the `IDatabaseAdapter` for agent management.
+ */
+export interface Agent extends Character, Omit<ProtoAgent, "$typeName" | "$unknown" | "character" | "status" | "createdAt" | "updatedAt" | "secrets"> {
+    status?: AgentStatus | ProtoAgentStatus;
+    createdAt: number | bigint;
+    updatedAt: number | bigint;
+    /** Arbitrary metadata persisted alongside the agent record. */
+    metadata?: Record<string, unknown>;
+}
+//# sourceMappingURL=agent.d.ts.map

package/packages/typescript/src/types/agent.d.ts.map

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

package/packages/typescript/src/types/agent.js

@@ -0,0 +1,5 @@
+export var AgentStatus;
+(function (AgentStatus) {
+    AgentStatus["ACTIVE"] = "active";
+    AgentStatus["INACTIVE"] = "inactive";
+})(AgentStatus || (AgentStatus = {}));