convex-durable-agents 0.1.7 → 0.2.0

package/README.md

@@ -56,7 +56,6 @@ Create a chat handler with your AI model and tools:
 import { z } from "zod";
 import { components, internal } from "./_generated/api";
 import { createActionTool, defineAgentApi, streamHandlerAction } from "convex-durable-agents";
-import { openai } from "@ai-sdk/openai";
 
 // Define the stream handler with your model and tools
 export const chatAgentHandler = streamHandlerAction(components.durableAgents, {
@@ -78,7 +77,7 @@ export const {
   sendMessage,
   getThread,
   listMessages,
-  listMessagesWithStreams,
+  streamUpdates,
   listThreads,
   deleteThread,
   resumeThread,
@@ -165,12 +164,13 @@ export const getWeather = internalAction({
 Use the React hooks to build your chat interface:
 
 ```tsx
-import { useAgentChat, getMessageKey } from "convex-durable-agents/react";
+import { useAgentChat } from "convex-durable-agents/react";
 import { api } from "../convex/_generated/api";
 
 function ChatView({ threadId }: { threadId: string }) {
   const { messages, status, isRunning, sendMessage, stop } = useAgentChat({
-    listMessages: api.chat.listMessagesWithStreams,
+    listMessages: api.chat.listMessages,
+    streamUpdates: api.chat.streamUpdates,
     getThread: api.chat.getThread,
     sendMessage: api.chat.sendMessage,
     stopThread: api.chat.stopThread,
@@ -181,7 +181,7 @@ function ChatView({ threadId }: { threadId: string }) {
   return (
     <div>
       {messages.map((msg) => (
-        <div key={getMessageKey(msg)}>
+        <div key={msg.metadata?.key}>
           <strong>{msg.role}:</strong> {msg.parts.map((p) => (p.type === "text" ? p.text : null))}
         </div>
       ))}
@@ -210,17 +210,18 @@ function ChatView({ threadId }: { threadId: string }) {
 
 Creates the full agent API with **public** functions that can be called directly from clients:
 
-- `createThread({ prompt? })` - Create a new conversation thread
+- `createThread({ prompt?, messages?, autoStart? })` - Create a new conversation thread
 - `sendMessage({ threadId, prompt })` - Send a message to a thread
+- `addMessage({ threadId, msg })` - Add a message to a thread without triggering the agent
 - `resumeThread({ threadId, prompt? })` - Resume a stopped/failed thread
 - `stopThread({ threadId })` - Stop a running thread
 - `getThread({ threadId })` - Get thread details
 - `listMessages({ threadId })` - List messages in a thread
-- `listMessagesWithStreams({ threadId, streamArgs? })` - List messages with streaming support
+- `streamUpdates({ threadId, fromSeq? })` - Get streaming message updates for real-time UI
 - `listThreads({ limit? })` - List all threads
 - `deleteThread({ threadId })` - Delete a thread
-- `addToolResult({ toolCallId, result })` - Add result for async tool
-- `addToolError({ toolCallId, error })` - Add error for async tool
+- `addToolResult({ threadId, toolCallId, result })` - Add result for async tool
+- `addToolError({ threadId, toolCallId, error })` - Add error for async tool
 
 **Options:**
 
@@ -229,6 +230,8 @@ type AgentApiOptions = {
   authorizationCallback?: (ctx: QueryCtx | MutationCtx | ActionCtx, threadId: string) => Promise<void> | void;
   workpoolEnqueueAction?: FunctionReference<"mutation", "internal">;
   toolExecutionWorkpoolEnqueueAction?: FunctionReference<"mutation", "internal">;
+  onStatusChange?: FunctionReference<"mutation", "internal">;
+  excludeSystemMessages?: boolean;
 };
 ```
 
@@ -237,9 +240,10 @@ type AgentApiOptions = {
 - `workpoolEnqueueAction` - Route agent and tool execution through a workpool for parallelism control
 - `toolExecutionWorkpoolEnqueueAction` - Override workpool for tool execution only (falls back to
   `workpoolEnqueueAction` if not set)
+- `onStatusChange` - Mutation callback invoked when thread status changes
+- `excludeSystemMessages` - Whether to exclude system messages from message lists (defaults to `true`)
 
-**Protected endpoints:** `sendMessage`, `resumeThread`, `stopThread`, `getThread`, `listMessages`,
-`listMessagesWithStreams`, `deleteThread`
+**Protected endpoints:** `sendMessage`, `resumeThread`, `stopThread`, `getThread`, `listMessages`, `deleteThread`
 
 **Example with ownership check:**
 
@@ -310,7 +314,7 @@ All-in-one hook for chat functionality that combines thread state with mutations
 
 ```ts
 const {
-  messages, // UIMessage[]
+  messages, // UIMessageWithConvexMetadata[]
   thread, // ThreadDoc | null
   status, // ThreadStatus
   isLoading, // boolean
@@ -322,13 +326,13 @@ const {
   stop, // () => Promise<null>
   resume, // (prompt?: string) => Promise<null>
 } = useAgentChat({
-  listMessages: api.chat.listMessagesWithStreams,
+  listMessages: api.chat.listMessages,
+  streamUpdates: api.chat.streamUpdates,
   getThread: api.chat.getThread,
   sendMessage: api.chat.sendMessage,
   stopThread: api.chat.stopThread,
   resumeThread: api.chat.resumeThread,
   threadId,
-  stream: true, // optional, defaults to true
 });
 
 // Send a message (threadId is automatically included)
@@ -341,13 +345,13 @@ await stop();
 await resume();
 ```
 
-#### `useThread(messagesQuery, threadQuery, args, options?)`
+#### `useThreadMessages(options)`
 
-Lower-level hook for thread status and messages (use `useAgentChat` for most cases):
+Lower-level hook for thread messages with streaming support (use `useAgentChat` for most cases):
 
 ```ts
 const {
-  messages, // UIMessage[]
+  messages, // UIMessageWithConvexMetadata[]
   thread, // ThreadDoc | null
   status, // ThreadStatus
   isLoading, // boolean
@@ -355,7 +359,12 @@ const {
   isComplete, // boolean
   isFailed, // boolean
   isStopped, // boolean
-} = useThread(api.chat.listMessagesWithStreams, api.chat.getThread, { threadId }, { stream: true });
+} = useThreadMessages({
+  messagesQuery: api.chat.listMessages,
+  streamingMessageUpdatesQuery: api.chat.streamUpdates,
+  threadQuery: api.chat.getThread,
+  threadId,
+});
 ```
 
 #### `useSmoothText(text, options?)`
@@ -369,24 +378,6 @@ const [visibleText, { cursor, isStreaming }] = useSmoothText(text, {
 });
 ```
 
-#### `useThreadStatus(query, args)`
-
-Subscribe to thread status changes:
-
-```ts
-const { thread, status, isRunning, isComplete, isFailed, isStopped } = useThreadStatus(api.chat.getThread, {
-  threadId,
-});
-```
-
-#### `useMessages(query, threadQuery, args)`
-
-Fetch and transform messages:
-
-```ts
-const { messages, isLoading, thread } = useMessages(api.chat.listMessages, api.chat.getThread, { threadId });
-```
-
 ## Thread Status
 
 Threads can be in one of these states:
@@ -479,9 +470,9 @@ defineAgentApi(components.durableAgents, internal.chat.chatAgentHandler, {
 ├─────────────────────────────────────────────────────────────┤
 │  defineAgentApi()          │  React Hooks                   │
 │  - createThread            │  - useAgentChat                │
-│  - sendMessage             │  - useThread                   │
-│  - stopThread              │  - useMessages                 │
-│  - resumeThread            │  - useSmoothText               │
+│  - sendMessage             │  - useThreadMessages           │
+│  - stopThread              │  - useSmoothText               │
+│  - resumeThread            │                                │
 ├─────────────────────────────────────────────────────────────┤
 │                   Durable Agent Component                    │
 ├──────────────┬──────────────┬──────────────┬────────────────┤

package/dist/client/api.d.ts

@@ -0,0 +1,124 @@
+import { type FunctionReference, type FunctionVisibility, type RegisteredMutation, type RegisteredQuery } from "convex/server";
+import { type Infer } from "convex/values";
+import type { ComponentApi } from "../component/_generated/component.js";
+import { vUIMessageOptId } from "../component/messages.js";
+import type { StreamingMessageUpdates } from "../component/streams.js";
+import { type ActionCtx, type MessageDoc, type MutationCtx, type QueryCtx, type ThreadDoc } from "./types.js";
+export type StreamArgs = {
+    kind: "list";
+} | {
+    kind: "deltas";
+    cursors: Array<{
+        streamId: string;
+        cursor: number;
+    }>;
+};
+export type StreamMessage = {
+    streamId: string;
+    status: "streaming" | "finished" | "aborted";
+    msgId: string;
+    threadId: string;
+    _creationTime: number;
+    baseMessageCreationTime?: number;
+    streamVersion: number;
+};
+export type StreamDelta = {
+    streamId: string;
+    seq: number;
+    start: number;
+    end: number;
+    parts: Array<unknown>;
+    _creationTime: number;
+    messageId?: string;
+    chunkCount: number;
+    schemaVersion: number;
+    ops?: Array<{
+        op: "append_part" | "replace_tool_call_part" | "skip_duplicate_step_start" | "skip_tail_duplicate_text";
+        partType?: string;
+        toolCallId?: string;
+        targetPartKey?: string;
+        targetIndexHint?: number;
+        reason?: string;
+    }>;
+};
+export type MessagesWithStreamsResult = {
+    messages: MessageDoc[];
+    streams?: {
+        kind: "list";
+        messages: StreamMessage[];
+    } | {
+        kind: "deltas";
+        deltas: StreamDelta[];
+    };
+};
+export type AgentApi<V extends FunctionVisibility = "public"> = {
+    createThread: RegisteredMutation<V, {
+        prompt?: string;
+    }, string>;
+    sendMessage: RegisteredMutation<V, {
+        threadId: string;
+        prompt: string;
+    }, null>;
+    addMessage: RegisteredMutation<V, {
+        threadId: string;
+        msg: Infer<typeof vUIMessageOptId>;
+    }, null>;
+    resumeThread: RegisteredMutation<V, {
+        threadId: string;
+        prompt?: string;
+    }, null>;
+    stopThread: RegisteredMutation<V, {
+        threadId: string;
+    }, null>;
+    getThread: RegisteredQuery<V, {
+        threadId: string;
+    }, ThreadDoc | null>;
+    listMessages: RegisteredQuery<V, {
+        threadId: string;
+    }, MessageDoc[]>;
+    streamUpdates: RegisteredQuery<V, {
+        threadId: string;
+        fromSeq?: number;
+    }, StreamingMessageUpdates>;
+    listThreads: RegisteredQuery<V, {
+        limit?: number;
+    }, ThreadDoc[]>;
+    deleteThread: RegisteredMutation<V, {
+        threadId: string;
+    }, null>;
+    addToolResult: RegisteredMutation<V, {
+        threadId: string;
+        toolCallId: string;
+        result: unknown;
+    }, null>;
+    addToolError: RegisteredMutation<V, {
+        threadId: string;
+        toolCallId: string;
+        error: string;
+    }, null>;
+};
+export type AgentApiOptions = {
+    /** Optional authorization callback for thread access control */
+    authorizationCallback?: (ctx: QueryCtx | MutationCtx | ActionCtx, threadId: string) => Promise<void> | void;
+    /** Optional: Function to enqueue actions via workpool (used for both stream handler and tools unless overridden) */
+    workpoolEnqueueAction?: FunctionReference<"mutation", "internal">;
+    /** Optional: Override workpool for tool execution only */
+    toolExecutionWorkpoolEnqueueAction?: FunctionReference<"mutation", "internal">;
+    /** Optional: Callback invoked when thread status changes */
+    onStatusChange?: FunctionReference<"mutation", "internal">;
+    /** Optional: Whether to exclude system messages from message lists */
+    excludeSystemMessages?: boolean;
+};
+/**
+ * Define a public agent API that can be called from clients.
+ */
+export declare function defineAgentApi(component: ComponentApi, ref: FunctionReference<"action", "internal" | "public", {
+    threadId: string;
+}>, options?: AgentApiOptions): AgentApi<"public">;
+/**
+ * Define an internal agent API that can only be called from other Convex functions.
+ */
+export declare function defineInternalAgentApi(component: ComponentApi, ref: FunctionReference<"action", "internal" | "public", {
+    threadId: string;
+}>, options?: AgentApiOptions): AgentApi<"internal">;
+//# sourceMappingURL=api.d.ts.map

package/dist/client/api.d.ts.map

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

package/dist/client/api.js

@@ -0,0 +1,269 @@
+import { actionGeneric, createFunctionHandle, internalActionGeneric, internalMutationGeneric, internalQueryGeneric, mutationGeneric, queryGeneric, } from "convex/server";
+import { v } from "convex/values";
+import { vUIMessageOptId } from "../component/messages.js";
+import { vMessageContent, vMessageRole } from "../component/schema.js";
+import { _vClientThreadDoc, } from "./types.js";
+// ============================================================================
+// Agent API Definition
+// ============================================================================
+async function checkThreadIsIdle(component, ctx, threadId) {
+    const thread = await ctx.runQuery(component.threads.get, { threadId });
+    if (!thread) {
+        throw new Error(`Thread ${threadId} not found`);
+    }
+    switch (thread.status) {
+        case "awaiting_tool_results":
+        case "streaming":
+            throw new Error(`Thread ${threadId} status=${thread.status}, cannot resume`);
+    }
+}
+async function serializeThreadOptions(options) {
+    const result = {};
+    if (options?.workpoolEnqueueAction) {
+        const handle = await createFunctionHandle(options.workpoolEnqueueAction);
+        result.workpoolEnqueueAction = handle.toString();
+    }
+    if (options?.toolExecutionWorkpoolEnqueueAction) {
+        const handle = await createFunctionHandle(options.toolExecutionWorkpoolEnqueueAction);
+        result.toolExecutionWorkpoolEnqueueAction = handle.toString();
+    }
+    if (options?.onStatusChange) {
+        const handle = await createFunctionHandle(options.onStatusChange);
+        result.onStatusChangeHandle = handle.toString();
+    }
+    return result;
+}
+function createAgentApi(component, ref, _action, query, mutation, options) {
+    const authorize = options?.authorizationCallback;
+    return {
+        createThread: mutation({
+            args: {
+                prompt: v.optional(v.string()),
+                messages: v.optional(v.array(v.object({ role: vMessageRole, content: vMessageContent }))),
+                autoStart: v.optional(v.boolean()),
+            },
+            returns: v.string(),
+            handler: async (ctx, args) => {
+                // Create a function handle that can be scheduled from within the component
+                const handle = await createFunctionHandle(ref);
+                // Serialize thread options (workpool + status callback)
+                const serializedOptions = await serializeThreadOptions(options);
+                const thread = await ctx.runMutation(component.threads.create, {
+                    streamFnHandle: handle,
+                    ...serializedOptions,
+                });
+                if (args.messages) {
+                    for (const message of args.messages) {
+                        await ctx.runMutation(component.messages.add, {
+                            threadId: thread._id,
+                            msg: {
+                                role: message.role,
+                                parts: message.content,
+                            },
+                        });
+                    }
+                }
+                if (args.prompt) {
+                    await ctx.runMutation(component.messages.add, {
+                        threadId: thread._id,
+                        msg: { role: "user", parts: [{ type: "text", text: args.prompt }] },
+                    });
+                }
+                if (args.autoStart || (args.autoStart == null && args.prompt != null)) {
+                    await ctx.runMutation(component.agent.continueStream, {
+                        threadId: thread._id,
+                    });
+                }
+                return thread._id;
+            },
+        }),
+        sendMessage: mutation({
+            args: {
+                threadId: v.string(),
+                prompt: v.string(),
+            },
+            returns: v.null(),
+            handler: async (ctx, args) => {
+                if (authorize)
+                    await authorize(ctx, args.threadId);
+                await checkThreadIsIdle(component, ctx, args.threadId);
+                await ctx.runMutation(component.messages.add, {
+                    threadId: args.threadId,
+                    msg: { role: "user", parts: [{ type: "text", text: args.prompt }] },
+                });
+                await ctx.runMutation(component.threads.resume, {
+                    threadId: args.threadId,
+                });
+                await ctx.scheduler.runAfter(0, component.agent.continueStream, {
+                    threadId: args.threadId,
+                });
+                return null;
+            },
+        }),
+        addMessage: mutation({
+            args: {
+                threadId: v.string(),
+                msg: vUIMessageOptId,
+            },
+            returns: v.union(v.string(), v.null()),
+            handler: async (ctx, args) => {
+                if (authorize)
+                    await authorize(ctx, args.threadId);
+                const msgId = await ctx.runMutation(component.messages.add, {
+                    threadId: args.threadId,
+                    msg: args.msg,
+                    overwrite: false,
+                });
+                return msgId ?? null;
+            },
+        }),
+        resumeThread: mutation({
+            args: {
+                threadId: v.string(),
+                prompt: v.optional(v.string()),
+            },
+            returns: v.null(),
+            handler: async (ctx, args) => {
+                if (authorize)
+                    await authorize(ctx, args.threadId);
+                const threadId = args.threadId;
+                await checkThreadIsIdle(component, ctx, threadId);
+                if (args.prompt) {
+                    await ctx.runMutation(component.messages.add, {
+                        threadId,
+                        msg: { role: "user", parts: [{ type: "text", text: args.prompt }] },
+                    });
+                }
+                await ctx.runMutation(component.threads.setStopSignal, {
+                    threadId,
+                    stopSignal: false,
+                });
+                await ctx.scheduler.runAfter(0, component.agent.continueStream, {
+                    threadId,
+                });
+                return null;
+            },
+        }),
+        stopThread: mutation({
+            args: {
+                threadId: v.string(),
+            },
+            returns: v.null(),
+            handler: async (ctx, args) => {
+                if (authorize)
+                    await authorize(ctx, args.threadId);
+                await ctx.runMutation(component.threads.setStopSignal, {
+                    threadId: args.threadId,
+                    stopSignal: true,
+                });
+                return null;
+            },
+        }),
+        getThread: query({
+            args: {
+                threadId: v.string(),
+            },
+            returns: v.union(_vClientThreadDoc, v.null()),
+            handler: async (ctx, args) => {
+                if (authorize)
+                    await authorize(ctx, args.threadId);
+                return ctx.runQuery(component.threads.get, {
+                    threadId: args.threadId,
+                });
+            },
+        }),
+        listMessages: query({
+            args: {
+                threadId: v.string(),
+            },
+            handler: async (ctx, args) => {
+                if (authorize)
+                    await authorize(ctx, args.threadId);
+                const messages = await ctx.runQuery(component.messages.list, {
+                    threadId: args.threadId,
+                    excludeSystemMessages: options?.excludeSystemMessages ?? true,
+                });
+                return messages;
+            },
+        }),
+        streamUpdates: query({
+            args: {
+                threadId: v.string(),
+                fromSeq: v.optional(v.number()),
+            },
+            handler: async (ctx, args) => {
+                return ctx.runQuery(component.streams.queryStreamingMessageUpdates, {
+                    threadId: args.threadId,
+                    fromSeq: args.fromSeq,
+                });
+            },
+        }),
+        listThreads: query({
+            args: {
+                limit: v.optional(v.number()),
+            },
+            handler: async (ctx, args) => {
+                return ctx.runQuery(component.threads.list, { limit: args.limit });
+            },
+        }),
+        deleteThread: mutation({
+            args: {
+                threadId: v.string(),
+            },
+            returns: v.null(),
+            handler: async (ctx, args) => {
+                if (authorize)
+                    await authorize(ctx, args.threadId);
+                await ctx.runMutation(component.threads.remove, {
+                    threadId: args.threadId,
+                });
+                return null;
+            },
+        }),
+        addToolResult: mutation({
+            args: {
+                threadId: v.string(),
+                toolCallId: v.string(),
+                result: v.any(),
+            },
+            returns: v.null(),
+            handler: async (ctx, args) => {
+                await ctx.runMutation(component.tool_calls.addToolResult, {
+                    threadId: args.threadId,
+                    toolCallId: args.toolCallId,
+                    result: args.result,
+                });
+                return null;
+            },
+        }),
+        addToolError: mutation({
+            args: {
+                threadId: v.string(),
+                toolCallId: v.string(),
+                error: v.string(),
+            },
+            returns: v.null(),
+            handler: async (ctx, args) => {
+                await ctx.runMutation(component.tool_calls.addToolError, {
+                    threadId: args.threadId,
+                    toolCallId: args.toolCallId,
+                    error: args.error,
+                });
+                return null;
+            },
+        }),
+    };
+}
+/**
+ * Define a public agent API that can be called from clients.
+ */
+export function defineAgentApi(component, ref, options) {
+    return createAgentApi(component, ref, actionGeneric, queryGeneric, mutationGeneric, options);
+}
+/**
+ * Define an internal agent API that can only be called from other Convex functions.
+ */
+export function defineInternalAgentApi(component, ref, options) {
+    return createAgentApi(component, ref, internalActionGeneric, internalQueryGeneric, internalMutationGeneric, options);
+}
+//# sourceMappingURL=api.js.map

package/dist/client/api.js.map

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

package/dist/client/handler.d.ts

@@ -0,0 +1,53 @@
+import { type ModelMessage, streamText, type UIMessage } from "ai";
+import { type FunctionReference } from "convex/server";
+import type { ComponentApi } from "../component/_generated/component.js";
+import { type ActionCtx, type DurableTool } from "./types.js";
+import { type UsageInfo } from "./usage.js";
+export type StreamingOptions = {
+    throttleMs?: number;
+    returnImmediately?: boolean;
+};
+export type MessageReceivedCallbackArgs = {
+    threadId: string;
+    streamId: string;
+    message: UIMessage;
+    usage: UsageInfo;
+    providerMetadata?: unknown;
+};
+export type MessageReceivedCallback = (ctx: ActionCtx, args: MessageReceivedCallbackArgs) => void | Promise<void>;
+export type TurnCompleteArgs = {
+    threadId: string;
+    streamId: string;
+    providerMetadata?: unknown;
+    finishReason?: string;
+};
+export type TurnCompleteCallback = (ctx: ActionCtx, args: TurnCompleteArgs) => void | Promise<void>;
+export type ErrorHandlerArgs = {
+    threadId: string;
+    streamId: string;
+    error: string;
+};
+export type ErrorHandlerCallback = (ctx: ActionCtx, args: ErrorHandlerArgs) => void | Promise<void>;
+export type StreamHandlerArgs = Omit<Parameters<typeof streamText>[0], "tools" | "messages" | "prompt"> & {
+    tools: Record<string, DurableTool<unknown, unknown>>;
+    /** Optional: Save streaming deltas to the database for real-time client updates */
+    saveStreamDeltas?: boolean | StreamingOptions;
+    /** Optional: Transform the messages before sending them to the model */
+    transformMessages?: (messages: ModelMessage[]) => ModelMessage[];
+    /** Optional: Callback invoked once per stream handler invocation with token usage (best-effort) */
+    onMessageComplete?: MessageReceivedCallback;
+    /** Optional: Callback when the LLM response is complete (LLM signaled end or turn or stop condition is met) */
+    onTurnComplete?: TurnCompleteCallback;
+    /** Optional: Callback when an error occurs during the stream handler invocation */
+    onError?: ErrorHandlerCallback;
+    /** Optional: Function to enqueue actions via workpool (used for both stream handler and tools unless overridden) */
+    workpoolEnqueueAction?: FunctionReference<"mutation", "internal">;
+    /** Optional: Override workpool for tool execution only */
+    toolExecutionWorkpoolEnqueueAction?: FunctionReference<"mutation", "internal">;
+};
+export type StreamHandlerArgsFactory = (ctx: ActionCtx, threadId: string) => StreamHandlerArgs | Promise<StreamHandlerArgs>;
+export declare function streamHandlerAction(component: ComponentApi, argsOrFactory: StreamHandlerArgs | StreamHandlerArgsFactory): import("convex/server").RegisteredAction<"internal", {
+    threadId: string;
+    streamId: string;
+}, Promise<null | undefined>>;
+//# sourceMappingURL=handler.d.ts.map

package/dist/client/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/client/handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,YAAY,EACjB,UAAU,EAGV,KAAK,SAAS,EACf,MAAM,IAAI,CAAC;AACZ,OAAO,EAAE,KAAK,iBAAiB,EAAgD,MAAM,eAAe,CAAC;AAErG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AAOzE,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAA0C,MAAM,YAAY,CAAC;AACtG,OAAO,EAAqD,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAM/F,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,CAAC;AAWF,MAAM,MAAM,2BAA2B,GAAG;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,SAAS,CAAC;IACnB,KAAK,EAAE,SAAS,CAAC;IACjB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,2BAA2B,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAElH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEpG,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEpG,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,QAAQ,CAAC,GAAG;IACxG,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD,mFAAmF;IACnF,gBAAgB,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAAC;IAC9C,wEAAwE;IACxE,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,CAAC;IACjE,mGAAmG;IACnG,iBAAiB,CAAC,EAAE,uBAAuB,CAAC;IAC5C,+GAA+G;IAC/G,cAAc,CAAC,EAAE,oBAAoB,CAAC;IACtC,mFAAmF;IACnF,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,oHAAoH;IACpH,qBAAqB,CAAC,EAAE,iBAAiB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IAClE,0DAA0D;IAC1D,kCAAkC,CAAC,EAAE,iBAAiB,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;CAChF,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG,CACrC,GAAG,EAAE,SAAS,EACd,QAAQ,EAAE,MAAM,KACb,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAEpD,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,YAAY,EACvB,aAAa,EAAE,iBAAiB,GAAG,wBAAwB;;;8BAgU5D"}