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

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

@@ -0,0 +1,251 @@
+import type { ActionResult, ProviderValue } from "./components";
+import type { Entity, Room, World } from "./environment";
+import type { ActionPlan as ProtoActionPlan, ActionPlanStep as ProtoActionPlanStep, ProviderCacheEntry as ProtoProviderCacheEntry, State as ProtoState, StateData as ProtoStateData, StateValues as ProtoStateValues, WorkingMemoryItem as ProtoWorkingMemoryItem } from "./proto.js";
+/**
+ * Allowed value types for state values (JSON-serializable)
+ */
+export type StateValue = string | number | boolean | null | ProviderValue | object | StateValue[] | {
+    [key: string]: StateValue;
+};
+export interface StructuredOutputFailure {
+    source: "dynamicPromptExecFromState";
+    kind: "model_error" | "parse_error" | "parse_problem" | "validation_error";
+    model: string;
+    format: "XML" | "JSON" | "TOON";
+    schemaFields: string[];
+    attempts: number;
+    maxRetries: number;
+    timestamp: number;
+    key?: string;
+    parseError?: string;
+    issues?: string[];
+    responsePreview?: string;
+}
+/** Single step in an action plan */
+export interface ActionPlanStep extends Omit<ProtoActionPlanStep, "$typeName" | "$unknown" | "result"> {
+    status: "pending" | "completed" | "failed";
+    result?: ActionResult;
+}
+/** Multi-step action plan */
+export interface ActionPlan extends Omit<ProtoActionPlan, "$typeName" | "$unknown" | "steps" | "metadata"> {
+    steps: ActionPlanStep[];
+    metadata?: Record<string, StateValue>;
+}
+/**
+ * Provider result cache entry
+ */
+export interface ProviderCacheEntry extends Omit<ProtoProviderCacheEntry, "$typeName" | "$unknown" | "values" | "data"> {
+    values?: Record<string, StateValue>;
+    data?: Record<string, StateValue>;
+}
+/**
+ * Working memory entry for multi-step action execution
+ */
+export interface WorkingMemoryEntry extends Omit<ProtoWorkingMemoryItem, "$typeName" | "$unknown" | "result" | "timestamp"> {
+    result: ActionResult;
+    timestamp: number;
+}
+/**
+ * Working memory record for temporary state during action execution
+ */
+export type WorkingMemory = Record<string, WorkingMemoryEntry>;
+/**
+ * Structured data cached in state by providers and actions.
+ * Common properties are typed for better DX while allowing dynamic extension.
+ */
+export interface StateData extends Omit<ProtoStateData, "$typeName" | "$unknown" | "room" | "world" | "entity" | "providers" | "actionPlan" | "actionResults" | "workingMemory"> {
+    /** Cached room data from providers */
+    room?: Room;
+    /** Cached world data from providers */
+    world?: World;
+    /** Cached entity data from providers */
+    entity?: Entity;
+    /** Provider results cache keyed by provider name */
+    providers?: Record<string, ProviderCacheEntry>;
+    /** Current action plan for multi-step actions */
+    actionPlan?: ActionPlan;
+    /** Results from previous action executions */
+    actionResults?: ActionResult[];
+    /** Working memory for temporary state during multi-step action execution */
+    workingMemory?: WorkingMemory;
+    /** Latest structured-output failure captured during this run */
+    structuredOutputFailure?: StructuredOutputFailure;
+    /** Allow dynamic properties for plugin extensions */
+    [key: string]: StateValue | undefined;
+}
+/**
+ * State values populated by providers
+ */
+export interface StateValues extends Omit<ProtoStateValues, "$typeName" | "$unknown" | "extra"> {
+    /** Agent name */
+    agentName?: string;
+    /** Action names available to the agent */
+    actionNames?: string;
+    /** Provider names used */
+    providers?: string;
+    /** Human-readable summary of the latest structured-output failure */
+    structuredOutputFailureSummary?: string;
+    /** Other dynamic values */
+    [key: string]: StateValue | undefined;
+}
+/**
+ * Represents the current state or context of a conversation or agent interaction.
+ * This interface is a container for various pieces of information that define the agent's
+ * understanding at a point in time.
+ */
+export interface State extends Omit<ProtoState, "$typeName" | "$unknown" | "values" | "data"> {
+    values: StateValues;
+    data: StateData;
+    [key: string]: StateValue | StateValues | StateData | undefined;
+}
+/**
+ * Schema row for dynamic prompt execution.
+ *
+ * WHY: dynamicPromptExecFromState generates structured prompts that ask the LLM
+ * to output specific fields. Each SchemaRow defines one field the LLM must produce.
+ * The schema also controls validation behavior for streaming scenarios.
+ *
+ * Schema rows are intentionally backwards-compatible with the original flat shape,
+ * but now also support nested objects and arrays so callers can describe structured
+ * payloads without embedding pseudo-schemas in prose strings.
+ *
+ * @example
+ * ```ts
+ * const schema: SchemaRow[] = [
+ *   { field: 'thought', description: 'Your internal reasoning' },
+ *   { field: 'text', description: 'Response to user', required: true },
+ *   {
+ *     field: 'facts',
+ *     description: 'Facts extracted from the conversation',
+ *     type: 'array',
+ *     items: {
+ *       description: 'One fact entry',
+ *       type: 'object',
+ *       properties: [
+ *         { field: 'claim', description: 'Fact claim', required: true },
+ *         { field: 'type', description: 'fact|opinion|preference', required: true },
+ *       ],
+ *     },
+ *   },
+ * ];
+ * ```
+ */
+export type SchemaValueType = "string" | "number" | "boolean" | "object" | "array";
+export type SchemaValueSpec = {
+    /** Description shown to LLM - explains what to put in this value */
+    description: string;
+    /**
+     * Expected value type.
+     *
+     * WHY: Flat string descriptions work for simple fields, but nested arrays/objects
+     * need explicit structure so prompt examples and validation can stay machine-readable.
+     */
+    type?: SchemaValueType;
+    /** If true, validation fails when value is empty/missing */
+    required?: boolean;
+    /**
+     * Object properties for `type: "object"`.
+     *
+     * WHY: Lets callers describe nested output directly instead of teaching the model
+     * an ad-hoc JSON shape through freeform prose.
+     */
+    properties?: SchemaRow[];
+    /**
+     * Item shape for `type: "array"`.
+     *
+     * WHY: Arrays often contain structured entries. This keeps the shape attached to
+     * the schema so examples, parsing, and validation can agree.
+     */
+    items?: SchemaValueSpec;
+};
+export type SchemaRow = SchemaValueSpec & {
+    /** Field name - will become an XML tag or JSON property */
+    field: string;
+    /**
+     * Control per-field validation codes for streaming (levels 0-1 only).
+     *
+     * WHY: Validation codes are UUID snippets that surround each field. If the LLM
+     * outputs the same code before and after a field, we know the context window
+     * wasn't truncated mid-field. This trades off token usage for reliability.
+     *
+     * Behavior by level:
+     * - Level 0 (Trusted): default false. Set to true to opt-in to per-field codes.
+     * - Level 1 (Progressive): default true. Set to false to opt-out of codes.
+     * - Levels 2-3: ignored for per-field wrapping. Those levels can use optional
+     *   checkpoint codes instead.
+     *
+     * Note: Only top-level schema rows use this today. Nested `properties` are still
+     * validated structurally, but they do not get their own streaming/validation wires.
+     */
+    validateField?: boolean;
+    /**
+     * Control whether this field's content is streamed to the consumer.
+     *
+     * WHY: Not all fields should be shown to users in real-time:
+     * - 'thought': Internal reasoning - might be verbose or confusing to show
+     * - 'actions': System field for action routing - not user-visible
+     * - 'text': The actual response - should definitely stream
+     *
+     * Default: true for 'text' field, false for others.
+     *
+     * Note: Only top-level schema rows are considered for streaming. Nested object/array
+     * members still flow through parsing/validation, but are not streamed independently.
+     */
+    streamField?: boolean;
+};
+/**
+ * Configuration for retry backoff timing.
+ *
+ * WHY: When retries happen, immediate retries can:
+ * - Overwhelm rate-limited APIs
+ * - Hit transient failures repeatedly
+ * - Waste resources on brief outages
+ *
+ * Backoff gives the system time to recover between attempts.
+ */
+export interface RetryBackoffConfig {
+    /**
+     * Initial delay in milliseconds before first retry.
+     * Default: 1000ms (1 second)
+     */
+    initialMs: number;
+    /**
+     * Multiplier for exponential backoff.
+     * delay = initialMs * multiplier^(retryCount - 1)
+     * Default: 2 (doubles each time)
+     */
+    multiplier: number;
+    /**
+     * Maximum delay in milliseconds.
+     * Caps exponential growth to prevent absurd wait times.
+     * Default: 30000ms (30 seconds)
+     */
+    maxMs: number;
+}
+/**
+ * Stream event types for validation-aware streaming.
+ * Rich consumers receive these typed events for custom UX handling.
+ */
+export type StreamEventType = "chunk" | "field_validated" | "retry_start" | "error" | "complete";
+/**
+ * Rich stream event for sophisticated consumers.
+ *
+ * WHY: Simple consumers just want text chunks. Advanced UIs want to know
+ * about validation progress, retries, and errors to show appropriate UI
+ * (spinners, clear partial content, error messages).
+ */
+export interface StreamEvent {
+    /** Event type (named eventType for cross-language consistency with Rust/Python) */
+    eventType: StreamEventType;
+    /** Field name (for chunk and field_validated events) */
+    field?: string;
+    /** Content chunk (for chunk events) */
+    chunk?: string;
+    /** Retry attempt number (for retry_start events) */
+    retryCount?: number;
+    /** Error message (for error events) */
+    error?: string;
+    /** Timestamp of the event */
+    timestamp: number;
+}
+//# sourceMappingURL=state.d.ts.map

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

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

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,93 @@
+/**
+ * Streaming type definitions.
+ *
+ * This module defines the interface contract for stream content extractors.
+ * Implementations are in utils/streaming.ts.
+ *
+ * VALIDATION-AWARE STREAMING:
+ * ---------------------------
+ * LLMs can silently truncate output when hitting token limits. This is catastrophic
+ * for structured outputs - you might stream half a broken response.
+ *
+ * Solution: Validation codes - short UUIDs the LLM must echo back. If the echoed
+ * code matches, we know that part wasn't truncated.
+ *
+ * Validation Levels:
+ * - 0 (Trusted): No codes, stream immediately. Fast but no safety.
+ * - 1 (Progressive): Per-field codes, stream as each field validates.
+ * - 2 (First Checkpoint): Code at start, buffer until validated.
+ * - 3 (Full): Codes at start AND end, maximum safety.
+ */
+/**
+ * Interface for stream content extractors.
+ *
+ * Implementations decide HOW to filter LLM output for streaming.
+ * Could be XML parsing, JSON parsing, plain text passthrough, or custom logic.
+ *
+ * The framework doesn't care about format - that's implementation choice.
+ *
+ * Usage: Create a new instance for each stream. Don't reuse instances.
+ *
+ * @example
+ * ```ts
+ * // Simple passthrough - streams everything as-is
+ * const extractor = new PassthroughExtractor();
+ *
+ * // XML tag extraction - extracts content from <text> tag
+ * const extractor = new XmlTagExtractor('text');
+ *
+ * // Action-aware XML (DefaultMessageService)
+ * const extractor = new ResponseStreamExtractor();
+ *
+ * // Custom implementation
+ * class MyExtractor implements IStreamExtractor {
+ *   private _done = false;
+ *   get done() { return this._done; }
+ *   push(chunk: string) { return this.myCustomLogic(chunk); }
+ * }
+ * ```
+ */
+export interface IStreamExtractor {
+    /** Whether extraction is complete (no more content expected from this stream) */
+    readonly done: boolean;
+    /**
+     * Process a chunk from the LLM stream.
+     * @param chunk - Raw chunk from LLM
+     * @returns Text to stream to client (empty string = nothing to stream yet)
+     */
+    push(chunk: string): string;
+    /**
+     * Flush any buffered content (called when stream ends).
+     * @returns Any remaining buffered content
+     */
+    flush?(): string;
+    /**
+     * Reset internal state for reuse (e.g., between retry attempts).
+     */
+    reset?(): void;
+}
+/**
+ * Interface for streaming retry state tracking.
+ *
+ * WHY: When streaming fails mid-response, we need to:
+ * 1. Know what was successfully streamed (for continuation prompts)
+ * 2. Know if the stream completed (don't retry complete streams)
+ * 3. Reset state for retry attempts
+ */
+export interface IStreamingRetryState {
+    /**
+     * Get all text that was successfully streamed.
+     * Use this for building continuation prompts on retry.
+     */
+    getStreamedText(): string;
+    /**
+     * Check if streaming completed successfully.
+     * If true, no retry needed. If false, can retry with continuation.
+     */
+    isComplete(): boolean;
+    /**
+     * Reset state for a new streaming attempt.
+     */
+    reset(): void;
+}
+//# sourceMappingURL=streaming.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/types/streaming.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,gBAAgB;IAChC,iFAAiF;IACjF,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAEvB;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAE5B;;;OAGG;IACH,KAAK,CAAC,IAAI,MAAM,CAAC;IAEjB;;OAEG;IACH,KAAK,CAAC,IAAI,IAAI,CAAC;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACpC;;;OAGG;IACH,eAAe,IAAI,MAAM,CAAC;IAE1B;;;OAGG;IACH,UAAU,IAAI,OAAO,CAAC;IAEtB;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;CACd"}

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

@@ -0,0 +1,21 @@
+/**
+ * Streaming type definitions.
+ *
+ * This module defines the interface contract for stream content extractors.
+ * Implementations are in utils/streaming.ts.
+ *
+ * VALIDATION-AWARE STREAMING:
+ * ---------------------------
+ * LLMs can silently truncate output when hitting token limits. This is catastrophic
+ * for structured outputs - you might stream half a broken response.
+ *
+ * Solution: Validation codes - short UUIDs the LLM must echo back. If the echoed
+ * code matches, we know that part wasn't truncated.
+ *
+ * Validation Levels:
+ * - 0 (Trusted): No codes, stream immediately. Fast but no safety.
+ * - 1 (Progressive): Per-field codes, stream as each field validates.
+ * - 2 (First Checkpoint): Code at start, buffer until validated.
+ * - 3 (Full): Codes at start AND end, maximum safety.
+ */
+export {};

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

@@ -0,0 +1,122 @@
+import type { Memory } from "./memory";
+import type { UUID } from "./primitives";
+import type { JsonValue, Task as ProtoTask, TaskMetadata as ProtoTaskMetadata, TaskStatus as ProtoTaskStatus } from "./proto.js";
+import type { IAgentRuntime } from "./runtime";
+import type { State } from "./state";
+import type { TriggerConfig, TriggerRunRecord } from "./trigger";
+/**
+ * Defines the contract for a Task Worker, which is responsible for executing a specific type of task.
+ * Task workers are registered with the `AgentRuntime` and are invoked when a `Task` of their designated `name` needs processing.
+ * WHY two gates: shouldRun (scheduler) has no message/state; canExecute (actions) has full context for auth (e.g. approval roles).
+ */
+export interface TaskWorker {
+    /** The unique name of the task type this worker handles. This name links `Task` instances to this worker. */
+    name: string;
+    /**
+     * The core execution logic for the task. This function is called by the runtime when a task needs to be processed.
+     * It receives the `AgentRuntime`, task-specific `options`, and the `Task` object itself.
+     * May return `{ nextInterval?: number }` to dynamically adjust the task's updateInterval (recurring tasks only).
+     * WHY return nextInterval: workers can adapt rate (e.g. back off under load) without separate updateTask calls.
+     */
+    execute: (runtime: IAgentRuntime, options: Record<string, JsonValue | object>, task: Task) => Promise<undefined | {
+        nextInterval?: number;
+    }>;
+    /**
+     * Called by the scheduler before each run -- "should this task run now?"
+     * If absent, the task always passes scheduler validation.
+     * WHY separate from execute: scheduler has no message/state; avoids loading context just to skip.
+     */
+    shouldRun?: (runtime: IAgentRuntime, task: Task) => Promise<boolean>;
+    /**
+     * Called by actions (e.g. choice) to check authorization -- "can this user trigger this task?"
+     * If absent, execution is always allowed.
+     * WHY separate from shouldRun: choice action has message/state for role checks (e.g. approval allowedRoles).
+     */
+    canExecute?: (runtime: IAgentRuntime, message: Memory, state: State) => Promise<boolean>;
+}
+/**
+ * Defines metadata associated with a `Task`.
+ * This can include scheduling information like `updateInterval` or UI-related details
+ * for presenting task options to a user.
+ * The `[key: string]: unknown;` allows for additional, unspecified metadata fields.
+ */
+export interface TaskMetadata extends Omit<ProtoTaskMetadata, "$typeName" | "$unknown" | "values"> {
+    targetEntityId?: string;
+    reason?: string;
+    priority?: "low" | "medium" | "high";
+    message?: string;
+    status?: string;
+    scheduledAt?: string;
+    snoozedAt?: string;
+    originalScheduledAt?: JsonValue;
+    createdAt?: string;
+    completedAt?: string;
+    completionNotes?: string;
+    lastExecuted?: string;
+    updatedAt?: number;
+    /** Optional. If the task is recurring, this specifies the interval in milliseconds between updates or executions. */
+    updateInterval?: number;
+    /** Optional. Original interval to restore on success when worker does not return nextInterval. WHY: backoff multiplies interval; we need the original base so we don't compound (exponential-of-exponential). */
+    baseInterval?: number;
+    /** Optional. Window (ms) before ideal next run when task may run. Earliest run = idealNextRun - notBefore. WHY: allows jitter/earlier run within a window. */
+    notBefore?: number;
+    /** Optional. Window (ms) after ideal next run; run is considered overdue after idealNextRun + notAfter. WHY: detect and log overdue tasks. */
+    notAfter?: number;
+    /** Optional. If true, the scheduler skips this task. WHY: operators pause/resume via API without deleting the task. */
+    paused?: boolean;
+    /** Optional. Consecutive failure count; reset to 0 on success. WHY: drive backoff and auto-pause after maxFailures. */
+    failureCount?: number;
+    /** Optional. Auto-pause after this many consecutive failures. undefined = 5. Use -1 (not Infinity; JSON loses it) to never auto-pause. WHY: prevent infinite retry storms; operators can resume after fixing. */
+    maxFailures?: number;
+    /** Optional. Last error message for debugging. WHY: getTaskStatus and logs show why a task failed. */
+    lastError?: string;
+    /**
+     * Optional. If true (default), the task will block the next scheduled execution while it's running.
+     * Set to false to allow overlapping executions (use with caution - can cause resource contention).
+     * @default true
+     */
+    blocking?: boolean;
+    /** Optional. Describes options or parameters that can be configured for this task, often for UI presentation. */
+    options?: {
+        name: string;
+        description: string;
+    }[];
+    /** Allows for other dynamic metadata properties related to the task. */
+    values?: Record<string, JsonValue | object>;
+    /** Optional. Trigger configuration for trigger-based tasks. */
+    trigger?: TriggerConfig;
+    /** Optional. History of trigger run records. */
+    triggerRuns?: TriggerRunRecord[];
+    [key: string]: JsonValue | object | undefined;
+}
+/**
+ * Represents a task to be performed, often in the background or at a later time.
+ * Tasks are managed by the `AgentRuntime` and processed by registered `TaskWorker`s.
+ * They can be associated with a room, world, and tagged for categorization and retrieval.
+ * The `IDatabaseAdapter` handles persistence of task data.
+ */
+export interface Task extends Omit<ProtoTask, "$typeName" | "$unknown" | "id" | "roomId" | "worldId" | "entityId" | "metadata" | "createdAt" | "updatedAt" | "dueAt" | "status"> {
+    id?: UUID;
+    roomId?: UUID;
+    worldId?: UUID;
+    entityId?: UUID;
+    /** Agent that owns this task. WHY: multi-tenant safety; getTasks can filter by agentId so each runtime only sees its tasks. */
+    agentId?: UUID;
+    metadata?: TaskMetadata;
+    createdAt?: number | bigint;
+    updatedAt?: number | bigint;
+    dueAt?: number | bigint;
+    status?: ProtoTaskStatus;
+}
+/**
+ * Status returned by TaskService.getTaskStatus for a single task.
+ * WHY: operators and UIs need nextRunAt, paused, lastError without reading raw task metadata.
+ */
+export interface TaskRunStatus {
+    task: Task | null;
+    paused: boolean;
+    executing: boolean;
+    nextRunAt?: number;
+    lastError?: string;
+}
+//# sourceMappingURL=task.d.ts.map

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

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

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,3 @@
+import type { DeriveKeyAttestationData, RemoteAttestationMessage, RemoteAttestationQuote, TEEMode, TeeAgent, TeePluginConfig, TeeType } from "./proto.js";
+export type { DeriveKeyAttestationData, RemoteAttestationMessage, RemoteAttestationQuote, TEEMode, TeeAgent, TeePluginConfig, TeeType, };
+//# sourceMappingURL=tee.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tee.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/types/tee.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,EACtB,OAAO,EACP,QAAQ,EACR,eAAe,EACf,OAAO,EACP,MAAM,YAAY,CAAC;AAEpB,YAAY,EACX,wBAAwB,EACxB,wBAAwB,EACxB,sBAAsB,EACtB,OAAO,EACP,QAAQ,EACR,eAAe,EACf,OAAO,GACP,CAAC"}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,15 @@
+import type { TestCase as ProtoTestCase, TestSuite as ProtoTestSuite } from "./proto.js";
+import type { IAgentRuntime } from "./runtime";
+/**
+ * Represents a test case for evaluating agent or plugin functionality.
+ */
+export interface TestCase extends Omit<ProtoTestCase, "$typeName" | "$unknown" | "handlerId"> {
+    fn: (runtime: IAgentRuntime) => Promise<void> | void;
+}
+/**
+ * Represents a suite of related test cases for an agent or plugin.
+ */
+export interface TestSuite extends Omit<ProtoTestSuite, "$typeName" | "$unknown" | "tests"> {
+    tests: TestCase[];
+}
+//# sourceMappingURL=testing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/types/testing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,QAAQ,IAAI,aAAa,EACzB,SAAS,IAAI,cAAc,EAC3B,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,QAChB,SAAQ,IAAI,CAAC,aAAa,EAAE,WAAW,GAAG,UAAU,GAAG,WAAW,CAAC;IACnE,EAAE,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACrD;AAED;;GAEG;AACH,MAAM,WAAW,SAChB,SAAQ,IAAI,CAAC,cAAc,EAAE,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC;IAChE,KAAK,EAAE,QAAQ,EAAE,CAAC;CAClB"}

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

@@ -0,0 +1 @@
+export {};