@alexkroman1/aai 0.4.0 → 0.6.0

package/dist/sdk/protocol.d.ts

@@ -0,0 +1,218 @@
+/**
+ * WebSocket wire-format types shared by server and client.
+ *
+ * Note: this module is for internal use only and should not be used directly.
+ *
+ * @module
+ */
+import { z } from "zod";
+import type { WorkerConfig } from "./_internal_types.ts";
+import type { Message, StepInfo } from "./types.ts";
+/**
+ * Current protocol version for client-server compatibility checks.
+ *
+ * Increment this when making breaking changes to the wire protocol.
+ */
+export declare const PROTOCOL_VERSION = 1;
+/**
+ * Default sample rate for speech-to-text audio in Hz.
+ *
+ * This is the sample rate expected by the STT provider (AssemblyAI).
+ */
+export declare const DEFAULT_STT_SAMPLE_RATE = 16000;
+/**
+ * Default sample rate for text-to-speech audio in Hz.
+ *
+ * This is the sample rate produced by the TTS provider (Rime).
+ */
+export declare const DEFAULT_TTS_SAMPLE_RATE = 24000;
+/**
+ * Audio codec identifier used in the wire protocol.
+ *
+ * All audio frames are 16-bit signed PCM, little-endian, mono.
+ */
+export declare const AUDIO_FORMAT: "pcm16";
+/** Specification for binary audio frames exchanged over WebSocket. */
+export declare const AudioFrameSpec: {
+    /** Audio codec identifier sent in the `ready` message. */
+    readonly format: "pcm16";
+    /** Signed 16-bit integer samples. */
+    readonly bitsPerSample: 16;
+    /** Little-endian byte order. */
+    readonly endianness: "little";
+    /** Mono audio. */
+    readonly channels: 1;
+    /** Bytes per sample — derived from bitsPerSample and channels. */
+    readonly bytesPerSample: number;
+};
+/**
+ * KV operation request sent from the worker to the host via postMessage RPC.
+ *
+ * This is a discriminated union on the `op` field, representing the four
+ * key-value store operations available to sandboxed agent workers.
+ */
+export type KvRequest = {
+    op: "get";
+    key: string;
+} | {
+    op: "set";
+    key: string;
+    value: string;
+    ttl?: number | undefined;
+} | {
+    op: "del";
+    key: string;
+} | {
+    op: "list";
+    prefix: string;
+    limit?: number | undefined;
+    reverse?: boolean | undefined;
+};
+/** Zod schema for {@linkcode KvRequest}. */
+export declare const KvRequestBaseSchema: z.ZodType<KvRequest>;
+/** Default timeout for agent lifecycle hooks (onConnect, onTurn, etc). */
+export declare const HOOK_TIMEOUT_MS = 5000;
+/** Default timeout for tool execution in the worker. */
+export declare const TOOL_EXECUTION_TIMEOUT_MS = 30000;
+/** Error codes for categorizing session errors on the wire. */
+export type SessionErrorCode = "stt" | "llm" | "tts" | "tool" | "protocol" | "connection" | "audio" | "internal";
+/** Zod schema for {@linkcode SessionErrorCode}. */
+export declare const SessionErrorCodeSchema: z.ZodType<SessionErrorCode>;
+/**
+ * Discriminated union of all server→client session events.
+ *
+ * Sent via a single `event()` RPC method instead of one method per type.
+ */
+export type ClientEvent = {
+    type: "speech_started";
+} | {
+    type: "speech_stopped";
+} | {
+    type: "transcript";
+    text: string;
+    isFinal: false;
+} | {
+    type: "transcript";
+    text: string;
+    isFinal: true;
+    turnOrder?: number | undefined;
+} | {
+    type: "turn";
+    text: string;
+    turnOrder?: number | undefined;
+} | {
+    type: "chat";
+    text: string;
+} | {
+    type: "tool_call_start";
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+} | {
+    type: "tool_call_done";
+    toolCallId: string;
+    result: string;
+} | {
+    type: "tts_done";
+} | {
+    type: "cancelled";
+} | {
+    type: "reset";
+} | {
+    type: "error";
+    code: SessionErrorCode;
+    message: string;
+};
+/** Zod schema for {@linkcode ClientEvent}. */
+export declare const ClientEventSchema: z.ZodType<ClientEvent>;
+/**
+ * Typed interface for pushing session events to a connected client.
+ *
+ * For WebSocket sessions this sends JSON text frames and binary audio frames.
+ */
+export interface ClientSink {
+    /** Whether the underlying connection is open and accepting calls. */
+    readonly open: boolean;
+    /** Push a session event to the client. */
+    event(e: ClientEvent): void;
+    /** Send a single TTS audio chunk to the client. */
+    playAudioChunk(chunk: Uint8Array): void;
+    /** Signal that TTS audio is complete. */
+    playAudioDone(): void;
+}
+/** Supported audio formats for the wire protocol. */
+export type AudioFormatId = "pcm16";
+/** Protocol-level session config returned to the client on connect. */
+export type ReadyConfig = {
+    protocolVersion: number;
+    audioFormat: AudioFormatId;
+    sampleRate: number;
+    ttsSampleRate: number;
+    mode?: "s2s";
+};
+/** Client→server text messages (binary frames carry raw PCM16 audio). */
+export type ClientMessage = {
+    type: "audio_ready";
+} | {
+    type: "cancel";
+} | {
+    type: "reset";
+} | {
+    type: "history";
+    messages: readonly {
+        role: "user" | "assistant";
+        text: string;
+    }[];
+};
+/** Server→client text messages (binary frames carry raw PCM16 audio). */
+export type ServerMessage = ({
+    type: "config";
+} & ReadyConfig) | {
+    type: "audio_done";
+} | ClientEvent;
+/** Zod schema for {@linkcode ClientMessage}. */
+export declare const ClientMessageSchema: z.ZodType<ClientMessage>;
+/**
+ * API shape the host process exposes to the sandboxed worker.
+ *
+ * Since workers run with all permissions denied, they use this interface
+ * to proxy network requests and KV operations back to the host.
+ */
+export type HostApi = {
+    fetch(req: {
+        url: string;
+        method: string;
+        headers: Readonly<Record<string, string>>;
+        body: string | null;
+    }): Promise<{
+        status: number;
+        statusText: string;
+        headers: Record<string, string>;
+        body: string;
+    }>;
+    kv(req: KvRequest): Promise<{
+        result: unknown;
+    }>;
+    vectorSearch(req: {
+        query: string;
+        topK: number;
+    }): Promise<string>;
+};
+/** Combined turn configuration resolved from the worker before a turn starts. */
+export type TurnConfig = {
+    maxSteps?: number;
+    activeTools?: string[];
+};
+/** Worker-side RPC target interface (host calls these methods). */
+export interface WorkerRpcApi {
+    withEnv(env: Record<string, string>): WorkerRpcApi;
+    getConfig(): Promise<WorkerConfig>;
+    executeTool(name: string, args: Readonly<Record<string, unknown>>, sessionId: string | undefined, messages: readonly Message[] | undefined): Promise<string>;
+    onConnect(sessionId: string): Promise<void>;
+    onDisconnect(sessionId: string): Promise<void>;
+    onTurn(sessionId: string, text: string): Promise<void>;
+    onError(sessionId: string, error: string): void;
+    onStep(sessionId: string, step: StepInfo): Promise<void>;
+    resolveTurnConfig(sessionId: string): Promise<TurnConfig | null>;
+}
+//# sourceMappingURL=protocol.d.ts.map

package/dist/sdk/protocol.d.ts.map

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

package/dist/sdk/protocol.js

@@ -0,0 +1,140 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * WebSocket wire-format types shared by server and client.
+ *
+ * Note: this module is for internal use only and should not be used directly.
+ *
+ * @module
+ */
+import { z } from "zod";
+/**
+ * Current protocol version for client-server compatibility checks.
+ *
+ * Increment this when making breaking changes to the wire protocol.
+ */
+export const PROTOCOL_VERSION = 1;
+/**
+ * Default sample rate for speech-to-text audio in Hz.
+ *
+ * This is the sample rate expected by the STT provider (AssemblyAI).
+ */
+export const DEFAULT_STT_SAMPLE_RATE = 16_000;
+/**
+ * Default sample rate for text-to-speech audio in Hz.
+ *
+ * This is the sample rate produced by the TTS provider (Rime).
+ */
+export const DEFAULT_TTS_SAMPLE_RATE = 24_000;
+/**
+ * Audio codec identifier used in the wire protocol.
+ *
+ * All audio frames are 16-bit signed PCM, little-endian, mono.
+ */
+export const AUDIO_FORMAT = "pcm16";
+/**
+ * Binary audio frame specification. All audio exchanged over the WebSocket as
+ * binary frames MUST conform to this spec. Any change here is a breaking
+ * protocol change.
+ */
+const _bitsPerSample = 16;
+const _channels = 1;
+/** Specification for binary audio frames exchanged over WebSocket. */
+export const AudioFrameSpec = {
+    /** Audio codec identifier sent in the `ready` message. */
+    format: AUDIO_FORMAT,
+    /** Signed 16-bit integer samples. */
+    bitsPerSample: _bitsPerSample,
+    /** Little-endian byte order. */
+    endianness: "little",
+    /** Mono audio. */
+    channels: _channels,
+    /** Bytes per sample — derived from bitsPerSample and channels. */
+    bytesPerSample: (_bitsPerSample / 8) * _channels,
+};
+/** Zod schema for {@linkcode KvRequest}. */
+export const KvRequestBaseSchema = z.discriminatedUnion("op", [
+    z.object({ op: z.literal("get"), key: z.string().min(1) }),
+    z.object({
+        op: z.literal("set"),
+        key: z.string().min(1),
+        value: z.string(),
+        ttl: z.number().int().positive().optional(),
+    }),
+    z.object({ op: z.literal("del"), key: z.string().min(1) }),
+    z.object({
+        op: z.literal("list"),
+        prefix: z.string(),
+        limit: z.number().int().positive().optional(),
+        reverse: z.boolean().optional(),
+    }),
+]);
+// ─── Timeout constants ─────────────────────────────────────────────────────
+/** Default timeout for agent lifecycle hooks (onConnect, onTurn, etc). */
+export const HOOK_TIMEOUT_MS = 5_000;
+/** Default timeout for tool execution in the worker. */
+export const TOOL_EXECUTION_TIMEOUT_MS = 30_000;
+/** Zod schema for {@linkcode SessionErrorCode}. */
+export const SessionErrorCodeSchema = z.enum([
+    "stt",
+    "llm",
+    "tts",
+    "tool",
+    "protocol",
+    "connection",
+    "audio",
+    "internal",
+]);
+/** Zod schema for a transcript event (partial or final). */
+const TranscriptEventSchema = z.object({
+    type: z.literal("transcript"),
+    text: z.string(),
+    isFinal: z.boolean(),
+    turnOrder: z.number().int().nonnegative().optional(),
+});
+/** Zod schema for {@linkcode ClientEvent}. */
+export const ClientEventSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("speech_started") }),
+    z.object({ type: z.literal("speech_stopped") }),
+    TranscriptEventSchema,
+    z.object({
+        type: z.literal("turn"),
+        text: z.string(),
+        turnOrder: z.number().int().nonnegative().optional(),
+    }),
+    z.object({ type: z.literal("chat"), text: z.string() }),
+    z.object({
+        type: z.literal("tool_call_start"),
+        toolCallId: z.string(),
+        toolName: z.string(),
+        args: z.record(z.string(), z.unknown()),
+    }),
+    z.object({
+        type: z.literal("tool_call_done"),
+        toolCallId: z.string(),
+        result: z.string().max(4000),
+    }),
+    z.object({ type: z.literal("tts_done") }),
+    z.object({ type: z.literal("cancelled") }),
+    z.object({ type: z.literal("reset") }),
+    z.object({
+        type: z.literal("error"),
+        code: SessionErrorCodeSchema,
+        message: z.string(),
+    }),
+]);
+/** Zod schema for {@linkcode ClientMessage}. */
+export const ClientMessageSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("audio_ready") }),
+    z.object({ type: z.literal("cancel") }),
+    z.object({ type: z.literal("reset") }),
+    z.object({
+        type: z.literal("history"),
+        messages: z
+            .array(z.object({
+            role: z.enum(["user", "assistant"]),
+            text: z.string().max(100_000),
+        }))
+            .max(200),
+    }),
+]);
+//# sourceMappingURL=protocol.js.map

package/dist/sdk/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../sdk/protocol.ts"],"names":[],"mappings":"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"}

package/dist/sdk/runtime.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Pluggable interfaces for cross-runtime concerns.
+ *
+ * @module
+ */
+/** Runtime-agnostic structured logger. */
+export type Logger = {
+    info(msg: string, ctx?: Record<string, unknown>): void;
+    warn(msg: string, ctx?: Record<string, unknown>): void;
+    error(msg: string, ctx?: Record<string, unknown>): void;
+    debug(msg: string, ctx?: Record<string, unknown>): void;
+};
+/** Runtime-agnostic session metrics. */
+export type Metrics = {
+    sessionsTotal: {
+        inc(labels: Record<string, string>): void;
+    };
+    sessionsActive: {
+        inc(labels: Record<string, string>): void;
+        dec(labels: Record<string, string>): void;
+    };
+};
+/** Console-based logger that works in all runtimes. */
+export declare const consoleLogger: Logger;
+/** No-op metrics implementation for environments without monitoring. */
+export declare const noopMetrics: Metrics;
+/** Configuration for the AssemblyAI Speech-to-Speech connection. */
+export type S2SConfig = {
+    wssUrl: string;
+    inputSampleRate: number;
+    outputSampleRate: number;
+};
+/** Default S2S configuration pointing to AssemblyAI's production endpoint. */
+export declare const DEFAULT_S2S_CONFIG: S2SConfig;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/sdk/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../sdk/runtime.ts"],"names":[],"mappings":"AACA;;;;GAIG;AAIH,0CAA0C;AAC1C,MAAM,MAAM,MAAM,GAAG;IACnB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACvD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACvD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACzD,CAAC;AAEF,wCAAwC;AACxC,MAAM,MAAM,OAAO,GAAG;IACpB,aAAa,EAAE;QAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;KAAE,CAAC;IAC7D,cAAc,EAAE;QACd,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;QAC1C,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;KAC3C,CAAC;CACH,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,aAAa,EAAE,MAiB3B,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,WAAW,EAAE,OAGzB,CAAC;AAEF,oEAAoE;AACpE,MAAM,MAAM,SAAS,GAAG;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,EAAE,SAIhC,CAAC"}

package/dist/sdk/runtime.js

@@ -0,0 +1,46 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Pluggable interfaces for cross-runtime concerns.
+ *
+ * @module
+ */
+import { DEFAULT_TTS_SAMPLE_RATE } from "./protocol.js";
+/** Console-based logger that works in all runtimes. */
+export const consoleLogger = {
+    info(msg, ctx) {
+        if (ctx)
+            console.log(msg, ctx);
+        else
+            console.log(msg);
+    },
+    warn(msg, ctx) {
+        if (ctx)
+            console.warn(msg, ctx);
+        else
+            console.warn(msg);
+    },
+    error(msg, ctx) {
+        if (ctx)
+            console.error(msg, ctx);
+        else
+            console.error(msg);
+    },
+    debug(msg, ctx) {
+        if (ctx)
+            console.debug(msg, ctx);
+        else
+            console.debug(msg);
+    },
+};
+/** No-op metrics implementation for environments without monitoring. */
+export const noopMetrics = {
+    sessionsTotal: { inc() { } },
+    sessionsActive: { inc() { }, dec() { } },
+};
+/** Default S2S configuration pointing to AssemblyAI's production endpoint. */
+export const DEFAULT_S2S_CONFIG = {
+    wssUrl: "wss://speech-to-speech.us.assemblyai.com/v1/realtime",
+    inputSampleRate: DEFAULT_TTS_SAMPLE_RATE,
+    outputSampleRate: DEFAULT_TTS_SAMPLE_RATE,
+};
+//# sourceMappingURL=runtime.js.map

package/dist/sdk/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../sdk/runtime.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C;;;;GAIG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAmBxD,uDAAuD;AACvD,MAAM,CAAC,MAAM,aAAa,GAAW;IACnC,IAAI,CAAC,GAAG,EAAE,GAAG;QACX,IAAI,GAAG;YAAE,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;;YAC1B,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IACD,IAAI,CAAC,GAAG,EAAE,GAAG;QACX,IAAI,GAAG;YAAE,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;;YAC3B,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IACD,KAAK,CAAC,GAAG,EAAE,GAAG;QACZ,IAAI,GAAG;YAAE,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;;YAC5B,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IACD,KAAK,CAAC,GAAG,EAAE,GAAG;QACZ,IAAI,GAAG;YAAE,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;;YAC5B,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;CACF,CAAC;AAEF,wEAAwE;AACxE,MAAM,CAAC,MAAM,WAAW,GAAY;IAClC,aAAa,EAAE,EAAE,GAAG,KAAI,CAAC,EAAE;IAC3B,cAAc,EAAE,EAAE,GAAG,KAAI,CAAC,EAAE,GAAG,KAAI,CAAC,EAAE;CACvC,CAAC;AASF,8EAA8E;AAC9E,MAAM,CAAC,MAAM,kBAAkB,GAAc;IAC3C,MAAM,EAAE,sDAAsD;IAC9D,eAAe,EAAE,uBAAuB;IACxC,gBAAgB,EAAE,uBAAuB;CAC1C,CAAC"}

package/dist/sdk/s2s.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Speech-to-Speech WebSocket client for AssemblyAI's S2S API.
+ *
+ * Cross-runtime: accepts a WebSocket factory and Logger instead of
+ * importing `ws` or `@std/log` directly.
+ *
+ * @module
+ */
+import type { Logger, S2SConfig } from "./runtime.ts";
+/** Minimal WebSocket interface for the S2S client. */
+export type S2sWebSocket = {
+    readonly readyState: number;
+    send(data: string): void;
+    close(): void;
+    on(event: string, handler: (...args: unknown[]) => void): void;
+};
+/** Factory for creating WebSocket connections (e.g. the `ws` package). */
+export type CreateS2sWebSocket = (url: string, opts: {
+    headers: Record<string, string>;
+}) => S2sWebSocket;
+export type S2sSessionConfig = {
+    system_prompt: string;
+    tools: S2sToolSchema[];
+    greeting?: string;
+};
+export type S2sToolSchema = {
+    type: "function";
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+};
+export type S2sToolCall = {
+    call_id: string;
+    name: string;
+    args: Record<string, unknown>;
+};
+export type S2sHandle = EventTarget & {
+    sendAudio(audio: Uint8Array): void;
+    sendToolResult(callId: string, result: string): void;
+    updateSession(config: S2sSessionConfig): void;
+    resumeSession(sessionId: string): void;
+    close(): void;
+};
+export type ConnectS2sOptions = {
+    apiKey: string;
+    config: S2SConfig;
+    createWebSocket: CreateS2sWebSocket;
+    logger?: Logger;
+};
+/**
+ * Connect to AssemblyAI's Speech-to-Speech WebSocket API.
+ *
+ * Returns an {@linkcode S2sHandle} that extends EventTarget. Consumers
+ * listen for events: `ready`, `speech_started`, `speech_stopped`,
+ * `user_transcript_delta`, `user_transcript`, `reply_started`,
+ * `reply_done`, `audio`, `agent_transcript`, `tool_call`,
+ * `session_expired`, `error`, `close`.
+ */
+export declare function connectS2s(opts: ConnectS2sOptions): Promise<S2sHandle>;
+//# sourceMappingURL=s2s.d.ts.map

package/dist/sdk/s2s.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s2s.d.ts","sourceRoot":"","sources":["../../sdk/s2s.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAyBtD,sDAAsD;AACtD,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,IAAI,IAAI,CAAC;IACd,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;CAChE,CAAC;AAKF,0EAA0E;AAC1E,MAAM,MAAM,kBAAkB,GAAG,CAC/B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,KACtC,YAAY,CAAC;AAIlB,MAAM,MAAM,gBAAgB,GAAG;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG;IACpC,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACnC,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACrD,aAAa,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC9C,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,KAAK,IAAI,IAAI,CAAC;CACf,CAAC;AAIF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,CAAC;IAClB,eAAe,EAAE,kBAAkB,CAAC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,CA4KtE"}