kernl 0.1.1

package/dist/tool/types.d.ts

@@ -0,0 +1,187 @@
+import { z, type ZodType } from "zod";
+import { Agent } from "../agent";
+import { Context, UnknownContext } from "../context";
+import { MCPServer } from "../mcp/base";
+import type { ToolCallState } from "@kernl/protocol";
+import type { FunctionTool, HostedTool } from "./tool";
+/**
+ * A tool that can be called by the model.
+ * @template TContext The context passed to the tool
+ */
+export type Tool<TContext = UnknownContext> = FunctionTool<TContext, any, any> | HostedTool;
+/**
+ * Configuration options for creating a tool.
+ *
+ * @param TContext The context of the tool
+ * @param TParameters The parameters of the tool
+ * @param TResult The result type of the tool
+ */
+export type ToolConfig<TContext = UnknownContext, TParameters extends ToolInputParameters = undefined, TResult = unknown> = {
+    /**
+     * Unique identifier for the tool (required)
+     */
+    id: string;
+    /**
+     * Optional friendly name for the tool
+     */
+    name?: string;
+    /**
+     * The description of the tool that helps the model understand when to use it.
+     */
+    description: string;
+    /**
+     * A Zod object schema describing the tool parameters, or undefined for string input.
+     */
+    parameters: TParameters;
+    /**
+     * Execution mode - 'blocking' waits for completion, 'async' lets the agent continue to execute while executing.
+     * Defaults to 'blocking'.
+     */
+    mode?: "blocking" | "async";
+    /**
+     * The function to invoke when the tool is called.
+     */
+    execute: ToolExecuteFunction<TContext, TParameters, TResult>;
+    /**
+     * The function to invoke when an error occurs while running the tool.
+     */
+    errorfn?: ToolErrorFunction | null;
+    /**
+     * Whether the tool requires human approval before it can be called.
+     */
+    requiresApproval?: boolean | ToolApprovalFunction<TParameters>;
+    /**
+     * Determines whether the tool should be exposed to the model for the current run.
+     */
+    isEnabled?: ToolEnabledOption<TContext>;
+};
+/**
+ * Context provided to toolkit filters during tool resolution.
+ */
+export interface ToolkitFilterContext<TContext = UnknownContext> {
+    context: Context<TContext>;
+    agent: Agent<TContext, any>;
+    toolkitId: string;
+}
+/**
+ * Toolkit-level filter for tools.
+ *
+ * Operates at the application layer on converted Tool objects.
+ * Use this for dynamic, context-aware filtering based on runtime state
+ * (e.g., user permissions, current workflow, etc.).
+ *
+ * This is the second filter in the pipeline (after MCPToolFilter for MCP tools).
+ *
+ * @example
+ * ```typescript
+ * const toolkit = new MCPToolkit({
+ *   id: "github",
+ *   server: githubServer,
+ *   filter: async (ctx, tool) => {
+ *     // Only allow read tools for non-admin users
+ *     if (!ctx.context.data.isAdmin) {
+ *       return tool.id.startsWith("read_");
+ *     }
+ *     return true;
+ *   }
+ * });
+ * ```
+ */
+export type ToolkitFilter<TContext = UnknownContext> = (context: ToolkitFilterContext<TContext>, tool: Tool<TContext>) => Promise<boolean> | boolean;
+/**
+ * Configuration for FunctionToolkit.
+ */
+export interface FunctionToolkitConfig<TContext = UnknownContext> {
+    /**
+     * Unique identifier for this toolkit.
+     */
+    id: string;
+    /**
+     * Array of tools to include in this toolkit.
+     */
+    tools: Tool<TContext>[];
+}
+/**
+ * Configuration for MCPToolkit.
+ */
+export interface MCPToolkitConfig<TContext = UnknownContext> {
+    /**
+     * Unique identifier for this toolkit.
+     */
+    id: string;
+    /**
+     * The MCP server instance to wrap.
+     */
+    server: MCPServer;
+    /**
+     * Toolkit-level filter to control which tools are exposed to the agent.
+     * Defaults to allowing all tools if not provided.
+     *
+     * This is applied after the server's toolFilter (if any). Use this for
+     * dynamic, context-aware filtering. Use server.toolFilter for static filtering.
+     */
+    filter?: ToolkitFilter<TContext>;
+}
+/**
+ * Type of tool
+ */
+export type ToolType = "function" | "hosted-tool";
+/**
+ * The result of invoking a function tool. Either the actual output of the execution or a tool
+ * approval request.
+ *
+ * These get passed for example to the `toolUseBehavior` option of the `Agent` constructor.
+ */
+export type ToolResult<TResult = unknown> = {
+    state: ToolCallState;
+    /**
+     * The result of the tool call.
+     */
+    result: TResult | undefined;
+    /**
+     * Error message if state is "error"
+     */
+    error: string | null;
+};
+/**
+ * The parameters of a tool.
+ * Either undefined (tool takes string input) or a Zod schema.
+ */
+export type ToolInputParameters = ZodType | undefined;
+/**
+ * The arguments to a tool - inferred from the Zod schema or string.
+ */
+export type ToolExecuteArgument<TParameters extends ToolInputParameters> = TParameters extends ZodType ? z.infer<TParameters> : string;
+/**
+ * The function to invoke when the tool is called.
+ *
+ * @param context An instance of the current RunContext
+ * @param params The arguments to the tool (see ToolExecuteArgument)
+ */
+export type ToolExecuteFunction<TContext = UnknownContext, TParameters extends ToolInputParameters = undefined, TResult = unknown> = (context: Context<TContext>, params: ToolExecuteArgument<TParameters>) => Promise<TResult> | TResult;
+/**
+ * A function that determines if a tool call should be approved.
+ *
+ * @param context The current execution context
+ * @param input The input to the tool
+ * @param callId The ID of the tool call
+ * @returns True if the tool call should be approved, false otherwise
+ */
+export type ToolApprovalFunction<TParameters extends ToolInputParameters> = (context: Context, input: ToolExecuteArgument<TParameters>, callId?: string) => Promise<boolean>;
+export type ToolEnabledFunction<TContext = UnknownContext> = (context: Context<TContext>, agent: Agent<any, any>) => Promise<boolean>;
+export type ToolEnabledPredicate<TContext = UnknownContext> = (args: {
+    context: Context<TContext>;
+    agent: Agent<any, any>;
+}) => boolean | Promise<boolean>;
+type ToolEnabledOption<Context = UnknownContext> = boolean | ToolEnabledPredicate<Context>;
+/**
+ * The function to invoke when an error occurs while running the tool. This can be used to define
+ * what the model should receive as tool output in case of an error. It can be used to provide
+ * for example additional context or a fallback value.
+ *
+ * @param context An instance of the current RunContext
+ * @param error The error that occurred
+ */
+export type ToolErrorFunction = (context: Context, error: Error | unknown) => string;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/tool/types.d.ts.map

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

package/dist/tool/types.js

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

package/dist/tools.d.ts

@@ -0,0 +1,362 @@
+import { z } from "zod";
+import type { Agent } from "./agent";
+import type { RunResult } from "./result";
+import { RunToolApprovalItem, RunToolCallOutputItem } from "./items";
+import * as protocol from "./types/proto";
+import { Context, UnknownContext } from "./context";
+export type { ToolOutputText, ToolOutputImage, ToolOutputFileContent, ToolCallStructuredOutput, ToolCallOutputContent, } from "./types/proto";
+/**
+ * A function that determines if a tool call should be approved.
+ *
+ * @param runContext The current run context
+ * @param input The input to the tool
+ * @param callId The ID of the tool call
+ * @returns True if the tool call should be approved, false otherwise
+ */
+export type ToolApprovalFunction<TParameters extends ToolInputParameters> = (context: Context, input: ToolExecuteArgument<TParameters>, callId?: string) => Promise<boolean>;
+export type ToolEnabledFunction<TContext = UnknownContext> = (context: Context<TContext>, agent: Agent<any, any>) => Promise<boolean>;
+type ToolEnabledPredicate<TContext = UnknownContext> = (args: {
+    context: Context<TContext>;
+    agent: Agent<any, any>;
+}) => boolean | Promise<boolean>;
+type ToolEnabledOption<Context = UnknownContext> = boolean | ToolEnabledPredicate<Context>;
+/**
+ * Exposes a function to the agent as a tool to be called
+ *
+ * @param Context The context of the tool
+ * @param Result The result of the tool
+ */
+export type FunctionTool<TContext = UnknownContext, TParameters extends ToolInputParameters = undefined, Result = unknown> = {
+    type: "function";
+    /**
+     * The name of the tool.
+     */
+    name: string;
+    /**
+     * The description of the tool that helps the model to understand when to use the tool
+     */
+    description: string;
+    /**
+     * A JSON schema describing the parameters of the tool.
+     */
+    parameters: JsonObjectSchema<any>;
+    /**
+     * Whether the tool is strict. If true, the model must try to strictly follow the schema (might result in slower response times).
+     */
+    strict: boolean;
+    /**
+     * The function to invoke when the tool is called.
+     */
+    invoke: (context: Context<TContext>, input: string, details?: {
+        toolCall: protocol.FunctionCallItem;
+    }) => Promise<string | Result>;
+    /**
+     * Whether the tool needs human approval before it can be called. If this is true, the run will result in an `interruption` that the
+     * program has to resolve by approving or rejecting the tool call.
+     */
+    needsApproval: ToolApprovalFunction<TParameters>;
+    /**
+     * Determines whether the tool should be made available to the model for the current run.
+     */
+    isEnabled: ToolEnabledFunction<Context>;
+};
+/**
+ * Exposes a computer to the model as a tool to be called
+ *
+ * @param Context The context of the tool
+ * @param Result The result of the tool
+ */
+export type ComputerTool = {
+    type: "computer";
+    /**
+     * The name of the tool.
+     */
+    name: "computer_use_preview" | string;
+};
+export type HostedMCPApprovalFunction<TContext = UnknownContext> = (context: Context<TContext>, data: RunToolApprovalItem) => Promise<{
+    approve: boolean;
+    reason?: string;
+}>;
+/**
+ * A hosted MCP tool that lets the model call a remote MCP server directly
+ * without a round trip back to your code.
+ */
+export type HostedMCPTool<TContext = UnknownContext> = HostedTool & {
+    name: "hosted_mcp";
+    providerData: ProviderData.HostedMCPTool<TContext>;
+};
+/**
+ * Creates a hosted MCP tool definition.
+ *
+ * @param options - Configuration for the hosted MCP tool, including server connection details
+ * and approval requirements.
+ */
+export declare function hostedMcpTool<TContext = UnknownContext>(options: {
+    allowedTools?: string[] | {
+        toolNames?: string[];
+    };
+} & ({
+    serverLabel: string;
+    serverUrl?: string;
+    authorization?: string;
+    headers?: Record<string, string>;
+} | {
+    serverLabel: string;
+    connectorId: string;
+    authorization?: string;
+    headers?: Record<string, string>;
+}) & ({
+    requireApproval?: never;
+} | {
+    requireApproval: "never";
+} | {
+    requireApproval: "always" | {
+        never?: {
+            toolNames: string[];
+        };
+        always?: {
+            toolNames: string[];
+        };
+    };
+    onApproval?: HostedMCPApprovalFunction<Context>;
+})): HostedMCPTool<Context>;
+/**
+ * A built-in hosted tool that will be executed directly by the model during the request and won't result in local code executions.
+ * Examples of these are `web_search_call` or `file_search_call`.
+ *
+ * @param Context The context of the tool
+ * @param Result The result of the tool
+ */
+export type HostedTool = {
+    type: "hosted_tool";
+    /**
+     * A unique name for the tool.
+     */
+    name: string;
+    /**
+     * Additional configuration data that gets passed to the tool
+     */
+    providerData?: Record<string, any>;
+};
+/**
+ * A tool that can be called by the model.
+ * @template Context The context passed to the tool
+ */
+export type Tool<Context = unknown> = FunctionTool<Context, any, any> | ComputerTool | HostedTool;
+/**
+ * The result of invoking a function tool. Either the actual output of the execution or a tool
+ * approval request.
+ *
+ * These get passed for example to the `toolUseBehavior` option of the `Agent` constructor.
+ */
+export type FunctionToolResult<TContext = UnknownContext, TParameters extends ToolInputParameters = any, Result = any> = {
+    type: "function_output";
+    /**
+     * The tool that was called.
+     */
+    tool: FunctionTool<TContext, TParameters, Result>;
+    /**
+     * The output of the tool call. This can be a string or a stringifable item.
+     */
+    output: string | unknown;
+    /**
+     * The run item representing the tool call output.
+     */
+    runItem: RunToolCallOutputItem;
+    /**
+     * The result returned when the tool execution runs another agent. Populated when the
+     * invocation originated from {@link Agent.asTool} and the nested agent completed a run.
+     */
+    agentRunResult?: RunResult<TContext, Agent<TContext, any>>;
+    /**
+     * Any interruptions collected while the nested agent executed. These are surfaced to allow
+     * callers to pause and resume workflows that require approvals.
+     */
+    interruptions?: RunToolApprovalItem[];
+} | {
+    /**
+     * Indicates that the tool requires approval before it can be called.
+     */
+    type: "function_approval";
+    /**
+     * The tool that is requiring to be approved.
+     */
+    tool: FunctionTool<TContext, TParameters, Result>;
+    /**
+     * The item representing the tool call that is requiring approval.
+     */
+    runItem: RunToolApprovalItem;
+} | {
+    /**
+     * Indicates that the tool requires approval before it can be called.
+     */
+    type: "hosted_mcp_tool_approval";
+    /**
+     * The tool that is requiring to be approved.
+     */
+    tool: HostedMCPTool<TContext>;
+    /**
+     * The item representing the tool call that is requiring approval.
+     */
+    runItem: RunToolApprovalItem;
+};
+/**
+ * The parameters of a tool.
+ *
+ * This can be a Zod schema, a JSON schema or undefined.
+ *
+ * If a Zod schema is provided, the arguments to the tool will automatically be parsed and validated
+ * against the schema.
+ *
+ * If a JSON schema is provided, the arguments to the tool will be passed as is.
+ *
+ * If undefined is provided, the arguments to the tool will be passed as a string.
+ */
+export type ToolInputParameters = undefined | ZodObjectLike | JsonObjectSchema<any>;
+/**
+ * The parameters of a tool that has strict mode enabled.
+ *
+ * This can be a Zod schema, a JSON schema or undefined.
+ *
+ * If a Zod schema is provided, the arguments to the tool will automatically be parsed and validated
+ * against the schema.
+ *
+ * If a JSON schema is provided, the arguments to the tool will be parsed as JSON but not validated.
+ *
+ * If undefined is provided, the arguments to the tool will be passed as a string.
+ */
+export type ToolInputParametersStrict = undefined | ZodObjectLike | JsonObjectSchemaStrict<any>;
+/**
+ * The parameters of a tool that has strict mode disabled.
+ *
+ * If a JSON schema is provided, the arguments to the tool will be parsed as JSON but not validated.
+ *
+ * Zod schemas are not supported without strict: true.
+ */
+export type ToolInputParametersNonStrict = undefined | JsonObjectSchemaNonStrict<any>;
+/**
+ * The arguments to a tool.
+ *
+ * The type of the arguments are derived from the parameters passed to the tool definition.
+ *
+ * If the parameters are passed as a JSON schema the type is `unknown`. For Zod schemas it will
+ * match the inferred Zod type. Otherwise the type is `string`
+ */
+export type ToolExecuteArgument<TParameters extends ToolInputParameters> = TParameters extends ZodObjectLike ? z.infer<TParameters> : TParameters extends JsonObjectSchema<any> ? unknown : string;
+/**
+ * The function to invoke when the tool is called.
+ *
+ * @param input The arguments to the tool (see ToolExecuteArgument)
+ * @param context An instance of the current RunContext
+ */
+type ToolExecuteFunction<TContext = UnknownContext, TParameters extends ToolInputParameters> = (context: Context<TContext>, input: ToolExecuteArgument<TParameters>, details?: {
+    toolCall: protocol.FunctionCallItem;
+}) => Promise<unknown> | unknown;
+/**
+ * The function to invoke when an error occurs while running the tool. This can be used to define
+ * what the model should receive as tool output in case of an error. It can be used to provide
+ * for example additional context or a fallback value.
+ *
+ * @param context An instance of the current RunContext
+ * @param error The error that occurred
+ */
+type ToolErrorFunction = (context: Context, error: Error | unknown) => Promise<string> | string;
+/**
+ * The options for a tool that has strict mode enabled.
+ *
+ * @param TParameters The parameters of the tool
+ * @param Context The context of the tool
+ */
+type StrictToolOptions<TParameters extends ToolInputParametersStrict, Context = UnknownContext> = {
+    /**
+     * The name of the tool. Must be unique within the agent.
+     */
+    name?: string;
+    /**
+     * The description of the tool. This is used to help the model understand when to use the tool.
+     */
+    description: string;
+    /**
+     * A Zod schema or JSON schema describing the parameters of the tool.
+     * If a Zod schema is provided, the arguments to the tool will automatically be parsed and validated
+     * against the schema.
+     */
+    parameters: TParameters;
+    /**
+     * Whether the tool is strict. If true, the model must try to strictly follow the schema (might result in slower response times).
+     */
+    strict?: true;
+    /**
+     * The function to invoke when the tool is called.
+     */
+    execute: ToolExecuteFunction<TParameters, Context>;
+    /**
+     * The function to invoke when an error occurs while running the tool.
+     */
+    errorFunction?: ToolErrorFunction | null;
+    /**
+     * Whether the tool needs human approval before it can be called. If this is true, the run will result in an `interruption` that the
+     * program has to resolve by approving or rejecting the tool call.
+     */
+    needsApproval?: boolean | ToolApprovalFunction<TParameters>;
+    /**
+     * Determines whether the tool should be exposed to the model for the current run.
+     */
+    isEnabled?: ToolEnabledOption<Context>;
+};
+/**
+ * The options for a tool that has strict mode disabled.
+ *
+ * @param TParameters The parameters of the tool
+ * @param Context The context of the tool
+ */
+type NonStrictToolOptions<TParameters extends ToolInputParametersNonStrict, TContext = UnknownContext> = {
+    /**
+     * The name of the tool. Must be unique within the agent.
+     */
+    name?: string;
+    /**
+     * The description of the tool. This is used to help the model understand when to use the tool.
+     */
+    description: string;
+    /**
+     * A JSON schema of the tool. To use a Zod schema, you need to use a `strict` schema.
+     */
+    parameters: TParameters;
+    /**
+     * Whether the tool is strict  If true, the model must try to strictly follow the schema (might result in slower response times).
+     */
+    strict: false;
+    /**
+     * The function to invoke when the tool is called.
+     */
+    execute: ToolExecuteFunction<TContext, TParameters>;
+    /**
+     * The function to invoke when an error occurs while running the tool.
+     */
+    errorFunction?: ToolErrorFunction | null;
+    /**
+     * Whether the tool needs human approval before it can be called. If this is true, the run will result in an `interruption` that the
+     * program has to resolve by approving or rejecting the tool call.
+     */
+    needsApproval?: boolean | ToolApprovalFunction<TParameters>;
+    /**
+     * Determines whether the tool should be exposed to the model for the current run.
+     */
+    isEnabled?: ToolEnabledOption<TContext>;
+};
+/**
+ * The options for a tool.
+ *
+ * @param TContext The context of the tool
+ * @param TParameters The parameters of the tool
+ */
+export type ToolOptions<TContext = UnknownContext, TParameters extends ToolInputParameters> = StrictToolOptions<Extract<TParameters, ToolInputParametersStrict>, TContext> | NonStrictToolOptions<Extract<TParameters, ToolInputParametersNonStrict>, TContext>;
+/**
+ * Exposes a function to the agent as a tool to be called
+ *
+ * @param options The options for the tool
+ * @returns A new tool
+ */
+export declare function tool<TContext = UnknownContext, TParameters extends ToolInputParameters = undefined, Result = string>(options: ToolOptions<TContext, TParameters>): FunctionTool<TContext, TParameters, Result>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAYrE,OAAO,KAAK,QAAQ,MAAM,eAAe,CAAC;AAE1C,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEpD,YAAY,EACV,cAAc,EACd,eAAe,EACf,qBAAqB,EACrB,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AAEvB;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,CAAC,WAAW,SAAS,mBAAmB,IAAI,CAC1E,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,mBAAmB,CAAC,WAAW,CAAC,EACvC,MAAM,CAAC,EAAE,MAAM,KACZ,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,MAAM,MAAM,mBAAmB,CAAC,QAAQ,GAAG,cAAc,IAAI,CAC3D,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,EAC1B,KAAK,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,KACnB,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,KAAK,oBAAoB,CAAC,QAAQ,GAAG,cAAc,IAAI,CAAC,IAAI,EAAE;IAC5D,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3B,KAAK,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;CACxB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEjC,KAAK,iBAAiB,CAAC,OAAO,GAAG,cAAc,IAC3C,OAAO,GACP,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAElC;;;;;GAKG;AACH,MAAM,MAAM,YAAY,CACtB,QAAQ,GAAG,cAAc,EACzB,WAAW,SAAS,mBAAmB,GAAG,SAAS,EACnD,MAAM,GAAG,OAAO,IACd;IACF,IAAI,EAAE,UAAU,CAAC;IACjB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,UAAU,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAClC;;OAEG;IACH,MAAM,EAAE,OAAO,CAAC;IAEhB;;OAEG;IACH,MAAM,EAAE,CACN,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;QAAE,QAAQ,EAAE,QAAQ,CAAC,gBAAgB,CAAA;KAAE,KAC9C,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IAE9B;;;OAGG;IACH,aAAa,EAAE,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAEjD;;OAEG;IACH,SAAS,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;CACzC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,UAAU,CAAC;IACjB;;OAEG;IACH,IAAI,EAAE,sBAAsB,GAAG,MAAM,CAAC;CAMvC,CAAC;AAkBF,MAAM,MAAM,yBAAyB,CAAC,QAAQ,GAAG,cAAc,IAAI,CACjE,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,EAC1B,IAAI,EAAE,mBAAmB,KACtB,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,aAAa,CAAC,QAAQ,GAAG,cAAc,IAAI,UAAU,GAAG;IAClE,IAAI,EAAE,YAAY,CAAC;IACnB,YAAY,EAAE,YAAY,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;CACpD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,GAAG,cAAc,EACrD,OAAO,EAAE;IACP,YAAY,CAAC,EAAE,MAAM,EAAE,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CACpD,GAEC,CAAG;IACG,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,GAED;IACE,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,CACJ,GACD,CACI;IAAE,eAAe,CAAC,EAAE,KAAK,CAAA;CAAE,GAC3B;IAAE,eAAe,EAAE,OAAO,CAAA;CAAE,GAC5B;IACE,eAAe,EACX,QAAQ,GACR;QACE,KAAK,CAAC,EAAE;YAAE,SAAS,EAAE,MAAM,EAAE,CAAA;SAAE,CAAC;QAChC,MAAM,CAAC,EAAE;YAAE,SAAS,EAAE,MAAM,EAAE,CAAA;SAAE,CAAC;KAClC,CAAC;IACN,UAAU,CAAC,EAAE,yBAAyB,CAAC,OAAO,CAAC,CAAC;CACjD,CACJ,GACF,aAAa,CAAC,OAAO,CAAC,CA4FxB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,aAAa,CAAC;IACpB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACpC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,IAAI,CAAC,OAAO,GAAG,OAAO,IAC9B,YAAY,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,CAAC,GAC/B,YAAY,GACZ,UAAU,CAAC;AAEf;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,CAC5B,QAAQ,GAAG,cAAc,EACzB,WAAW,SAAS,mBAAmB,GAAG,GAAG,EAC7C,MAAM,GAAG,GAAG,IAEV;IACE,IAAI,EAAE,iBAAiB,CAAC;IACxB;;OAEG;IACH,IAAI,EAAE,YAAY,CAAC,QAAQ,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;IAClD;;OAEG;IACH,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACzB;;OAEG;IACH,OAAO,EAAE,qBAAqB,CAAC;IAC/B;;;OAGG;IACH,cAAc,CAAC,EAAE,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC;IAC3D;;;OAGG;IACH,aAAa,CAAC,EAAE,mBAAmB,EAAE,CAAC;CACvC,GACD;IACE;;OAEG;IACH,IAAI,EAAE,mBAAmB,CAAC;IAC1B;;OAEG;IACH,IAAI,EAAE,YAAY,CAAC,QAAQ,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;IAClD;;OAEG;IACH,OAAO,EAAE,mBAAmB,CAAC;CAC9B,GACD;IACE;;OAEG;IACH,IAAI,EAAE,0BAA0B,CAAC;IACjC;;OAEG;IACH,IAAI,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC9B;;OAEG;IACH,OAAO,EAAE,mBAAmB,CAAC;CAC9B,CAAC;AAEN;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,mBAAmB,GAC3B,SAAS,GACT,aAAa,GACb,gBAAgB,CAAC,GAAG,CAAC,CAAC;AAE1B;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,yBAAyB,GACjC,SAAS,GACT,aAAa,GACb,sBAAsB,CAAC,GAAG,CAAC,CAAC;AAEhC;;;;;;GAMG;AACH,MAAM,MAAM,4BAA4B,GACpC,SAAS,GACT,yBAAyB,CAAC,GAAG,CAAC,CAAC;AAEnC;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,CAAC,WAAW,SAAS,mBAAmB,IACrE,WAAW,SAAS,aAAa,GAC7B,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,GACpB,WAAW,SAAS,gBAAgB,CAAC,GAAG,CAAC,GACvC,OAAO,GACP,MAAM,CAAC;AAEf;;;;;GAKG;AACH,KAAK,mBAAmB,CACtB,QAAQ,GAAG,cAAc,EACzB,WAAW,SAAS,mBAAmB,IACrC,CACF,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,EAC1B,KAAK,EAAE,mBAAmB,CAAC,WAAW,CAAC,EACvC,OAAO,CAAC,EAAE;IAAE,QAAQ,EAAE,QAAQ,CAAC,gBAAgB,CAAA;CAAE,KAC9C,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;AAEhC;;;;;;;GAOG;AACH,KAAK,iBAAiB,GAAG,CACvB,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,KAAK,GAAG,OAAO,KACnB,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;AAe9B;;;;;GAKG;AACH,KAAK,iBAAiB,CACpB,WAAW,SAAS,yBAAyB,EAC7C,OAAO,GAAG,cAAc,IACtB;IACF;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,UAAU,EAAE,WAAW,CAAC;IAExB;;OAEG;IACH,MAAM,CAAC,EAAE,IAAI,CAAC;IAEd;;OAEG;IACH,OAAO,EAAE,mBAAmB,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAEnD;;OAEG;IACH,aAAa,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAEzC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAE5D;;OAEG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;CACxC,CAAC;AAEF;;;;;GAKG;AACH,KAAK,oBAAoB,CACvB,WAAW,SAAS,4BAA4B,EAChD,QAAQ,GAAG,cAAc,IACvB;IACF;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,UAAU,EAAE,WAAW,CAAC;IAExB;;OAEG;IACH,MAAM,EAAE,KAAK,CAAC;IAEd;;OAEG;IACH,OAAO,EAAE,mBAAmB,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IAEpD;;OAEG;IACH,aAAa,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAEzC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC;IAE5D;;OAEG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;CACzC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CACrB,QAAQ,GAAG,cAAc,EACzB,WAAW,SAAS,mBAAmB,IAErC,iBAAiB,CAAC,OAAO,CAAC,WAAW,EAAE,yBAAyB,CAAC,EAAE,QAAQ,CAAC,GAC5E,oBAAoB,CAClB,OAAO,CAAC,WAAW,EAAE,4BAA4B,CAAC,EAClD,QAAQ,CACT,CAAC;AAEN;;;;;GAKG;AACH,wBAAgB,IAAI,CAClB,QAAQ,GAAG,cAAc,EACzB,WAAW,SAAS,mBAAmB,GAAG,SAAS,EACnD,MAAM,GAAG,MAAM,EAEf,OAAO,EAAE,WAAW,CAAC,QAAQ,EAAE,WAAW,CAAC,GAC1C,YAAY,CAAC,QAAQ,EAAE,WAAW,EAAE,MAAM,CAAC,CA4G7C"}