@superdurable/dex-agents 0.1.0 → 0.2.0

package/dist/src/agent-built-in-tools.d.ts

@@ -0,0 +1,81 @@
+import type { AgentPlanTask } from "./agent-session-values.js";
+/**
+ * Name of a built-in tool that the session itself handles.
+ *
+ * - `ask_user`: asks the user a question. The session raises a `question` interrupt, waits in
+ *   `AwaitQuestionAnswer`, and the answer becomes the tool result, so the model continues the same turn.
+ * - `durable_wait`: suspends the turn on a Dex Timer in `AwaitTimer`. No model call, coroutine, or
+ *   Worker holds the wait.
+ * - `write_todos`: replaces the session's {@link AgentPlan} with a new revision. `RunModel` records the
+ *   call in its own commit; no tool Step runs.
+ *
+ * Enable built-in tools with {@link AgentSessionOptions.builtInTools}. A runner offers the enabled ones
+ * to its model, from {@link builtInToolDefinitions}, like any other tool, and returns their calls in
+ * {@link ToolCallsRequested} like any other call. The session routes a call whose name is an enabled
+ * built-in tool to that tool's handling instead of a tool Step. An enabled built-in name is reserved.
+ * A disabled built-in name is an ordinary tool name.
+ */
+export type BuiltInTool = "ask_user" | "durable_wait" | "write_todos";
+/** Model-visible definition of one built-in tool, from {@link builtInToolDefinitions}. */
+export interface BuiltInToolDefinition {
+    /** Tool name as the model calls it. */
+    readonly name: BuiltInTool;
+    /** Tool description for the model; the same text as the Python core. */
+    readonly description: string;
+    /** JSON Schema of the tool arguments; the same schema as the Python core. */
+    readonly parameters: Readonly<Record<string, unknown>>;
+}
+/**
+ * Definitions of every built-in tool, with the same names, descriptions, and JSON Schemas as the Python
+ * core's `BUILT_IN_TOOL_DEFINITIONS`.
+ *
+ * A runner offers the definitions of {@link AgentTurnContext.enabledBuiltInTools} to its model. Adapters
+ * register them as tools without an implementation, which every adapter already does for deferred
+ * application tools.
+ *
+ * @example
+ * ```ts
+ * const offeredBuiltInTools = builtInToolDefinitions.filter((definition) =>
+ *   turn.enabledBuiltInTools?.has(definition.name) === true);
+ * ```
+ */
+export declare const builtInToolDefinitions: readonly BuiltInToolDefinition[];
+/** Every built-in tool name, in definition order. */
+export declare const builtInToolNames: readonly BuiltInTool[];
+/** Parsed arguments of an `ask_user` call. */
+export interface AskUserArguments {
+    readonly question: string;
+    readonly choices: readonly string[];
+    readonly allowsFreeText: boolean;
+}
+/** Parsed arguments of a `durable_wait` call. */
+export interface DurableWaitArguments {
+    readonly durationSeconds: number;
+    readonly reason: string;
+}
+/** Error of every `write_todos` call of a model response that has more than one; the same text as the Python core. */
+export declare const writeTodosCalledMoreThanOnce = "write_todos was called more than once in one response";
+/** Result of validating a built-in call's arguments: the parsed arguments or the model-visible error. */
+export type BuiltInArgumentsValidation<Arguments> = {
+    readonly isValid: true;
+    readonly arguments: Arguments;
+} | {
+    readonly isValid: false;
+    readonly error: string;
+};
+/** Reports whether text is empty or only whitespace, as Python's `not text.strip()` does. */
+export declare function isBlankText(text: string): boolean;
+export declare function isBuiltInTool(name: string): name is BuiltInTool;
+export declare function validateAskUserArguments(argumentsText: string): BuiltInArgumentsValidation<AskUserArguments>;
+/** A JSON number without a fraction, such as `2.0`, counts as an integer, as JSON Schema defines it. */
+export declare function validateDurableWaitArguments(argumentsText: string, maxDurableWaitSeconds: number): BuiltInArgumentsValidation<DurableWaitArguments>;
+/** Validates `write_todos` arguments; the error is `invalid todos: <reason>`, as in the Python core. */
+export declare function validateWriteTodosArguments(argumentsText: string): BuiltInArgumentsValidation<readonly AgentPlanTask[]>;
+/** Tool output after `write_todos` wrote tasks: `{"status":"updated","revision":<n>,"task_count":<k>}`. */
+export declare function buildPlanUpdatedOutput(revision: number, taskCount: number): string;
+/** Tool output after `write_todos` cleared the plan: `{"status":"cleared","revision":<n>}`. */
+export declare function buildPlanClearedOutput(revision: number): string;
+/** Tool output after the user answered `ask_user`: `{"status":"answered","answer":"<answer>"}`. */
+export declare function buildQuestionAnsweredOutput(answer: string): string;
+/** Tool output after a `durable_wait` Timer ended: `{"status":"completed","waited_seconds":<n>,"reason":"<reason>"}`. */
+export declare function buildDurableWaitCompletedOutput(waitedSeconds: number, reason: string): string;

package/dist/src/agent-built-in-tools.js

@@ -0,0 +1,246 @@
+// Copyright (c) 2026 Super Durable, Inc.
+//
+// Licensed under the Sustainable Use License 1.0.
+// You may not use this file except in compliance with the License.
+// See the LICENSE file in the repository root.
+//
+// SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
+/**
+ * Definitions of every built-in tool, with the same names, descriptions, and JSON Schemas as the Python
+ * core's `BUILT_IN_TOOL_DEFINITIONS`.
+ *
+ * A runner offers the definitions of {@link AgentTurnContext.enabledBuiltInTools} to its model. Adapters
+ * register them as tools without an implementation, which every adapter already does for deferred
+ * application tools.
+ *
+ * @example
+ * ```ts
+ * const offeredBuiltInTools = builtInToolDefinitions.filter((definition) =>
+ *   turn.enabledBuiltInTools?.has(definition.name) === true);
+ * ```
+ */
+export const builtInToolDefinitions = Object.freeze([
+    Object.freeze({
+        name: "ask_user",
+        description: "Ask the user one question and wait for the answer, which becomes this tool's result. Use it only " +
+            "when you cannot continue without information or a decision from the user. The wait can last hours " +
+            "or days.",
+        parameters: Object.freeze({
+            type: "object",
+            properties: {
+                question: { type: "string", description: "One concise question for the user." },
+                choices: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Answers the user can pick. Omit for a free-text answer.",
+                },
+                allows_free_text: {
+                    type: "boolean",
+                    description: "Whether the user may answer with text that is not one of the choices. Defaults to true.",
+                },
+            },
+            required: ["question"],
+            additionalProperties: false,
+        }),
+    }),
+    Object.freeze({
+        name: "durable_wait",
+        description: "Pause this turn for a number of whole seconds, then continue. Nothing runs during the wait. Use it " +
+            "to wait for something outside the conversation, such as a job that needs time to finish.",
+        parameters: Object.freeze({
+            type: "object",
+            properties: {
+                duration_seconds: { type: "integer", minimum: 1, description: "Whole seconds to wait." },
+                reason: { type: "string", description: "Why the turn waits, shown to the user." },
+            },
+            required: ["duration_seconds", "reason"],
+            additionalProperties: false,
+        }),
+    }),
+    Object.freeze({
+        name: "write_todos",
+        description: "Replace the plan with a complete, ordered list of tasks. Send every task each time, with its " +
+            "status. An empty list clears the plan. Keep the statuses current: mark a task in_progress when you " +
+            "start it and completed when it is done.",
+        parameters: Object.freeze({
+            type: "object",
+            properties: {
+                todos: {
+                    type: "array",
+                    description: "Every task of the plan, in order.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            content: { type: "string", description: "What the task does, in one short sentence." },
+                            status: {
+                                type: "string",
+                                enum: ["pending", "in_progress", "completed"],
+                                description: "Where the task stands.",
+                            },
+                        },
+                        required: ["content", "status"],
+                        additionalProperties: false,
+                    },
+                },
+            },
+            required: ["todos"],
+            additionalProperties: false,
+        }),
+    }),
+]);
+/** Every built-in tool name, in definition order. */
+export const builtInToolNames = Object.freeze(builtInToolDefinitions.map((definition) => definition.name));
+/** Error of every `write_todos` call of a model response that has more than one; the same text as the Python core. */
+export const writeTodosCalledMoreThanOnce = "write_todos was called more than once in one response";
+const planTaskStatuses = ["pending", "in_progress", "completed"];
+// The characters Python's str.isspace() accepts, so blank checks match the Python core exactly.
+const pythonWhitespaceOnly = /^[\t\n\v\f\r\x1c-\x1f \x85\xa0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]*$/u;
+/** Reports whether text is empty or only whitespace, as Python's `not text.strip()` does. */
+export function isBlankText(text) {
+    return pythonWhitespaceOnly.test(text);
+}
+export function isBuiltInTool(name) {
+    return builtInToolNames.includes(name);
+}
+export function validateAskUserArguments(argumentsText) {
+    const parsed = parseArgumentsObject("ask_user", argumentsText);
+    if (!parsed.isValid) {
+        return parsed;
+    }
+    const record = parsed.arguments;
+    const question = record["question"];
+    if (typeof question !== "string" || isBlankText(question)) {
+        return invalidArguments("ask_user", "question must be a non-empty string");
+    }
+    const choices = record["choices"] ?? [];
+    if (!Array.isArray(choices) || !choices.every((choice) => typeof choice === "string" && !isBlankText(choice))) {
+        return invalidArguments("ask_user", "choices must be a list of non-empty strings");
+    }
+    const allowsFreeText = record["allows_free_text"] ?? true;
+    if (typeof allowsFreeText !== "boolean") {
+        return invalidArguments("ask_user", "allows_free_text must be a boolean");
+    }
+    return {
+        isValid: true,
+        arguments: { question, choices: choices, allowsFreeText: allowsFreeText || choices.length === 0 },
+    };
+}
+/** A JSON number without a fraction, such as `2.0`, counts as an integer, as JSON Schema defines it. */
+export function validateDurableWaitArguments(argumentsText, maxDurableWaitSeconds) {
+    const parsed = parseArgumentsObject("durable_wait", argumentsText);
+    if (!parsed.isValid) {
+        return parsed;
+    }
+    const record = parsed.arguments;
+    const durationSeconds = record["duration_seconds"];
+    if (typeof durationSeconds !== "number" || !Number.isInteger(durationSeconds)) {
+        return invalidArguments("durable_wait", "duration_seconds must be an integer");
+    }
+    if (durationSeconds < 1 || durationSeconds > maxDurableWaitSeconds) {
+        return invalidArguments("durable_wait", `duration_seconds must be between 1 and ${maxDurableWaitSeconds}`);
+    }
+    const reason = record["reason"];
+    if (typeof reason !== "string") {
+        return invalidArguments("durable_wait", "reason must be a string");
+    }
+    return { isValid: true, arguments: { durationSeconds, reason } };
+}
+/** Validates `write_todos` arguments; the error is `invalid todos: <reason>`, as in the Python core. */
+export function validateWriteTodosArguments(argumentsText) {
+    let parsed;
+    try {
+        parsed = JSON.parse(argumentsText);
+    }
+    catch {
+        return invalidTodos("arguments must be a JSON object");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return invalidTodos("arguments must be a JSON object");
+    }
+    const [unknownName] = sortByCodePoint(Object.keys(parsed).filter((name) => name !== "todos"));
+    if (unknownName !== undefined) {
+        return invalidTodos(`unknown argument ${unknownName}`);
+    }
+    const todos = parsed["todos"];
+    if (!Array.isArray(todos)) {
+        return invalidTodos("todos must be a list");
+    }
+    const tasks = [];
+    for (const [index, todo] of todos.entries()) {
+        if (typeof todo !== "object" || todo === null || Array.isArray(todo)) {
+            return invalidTodos(`todos[${index}] must be an object`);
+        }
+        const [unknownField] = sortByCodePoint(Object.keys(todo).filter((name) => name !== "content" && name !== "status"));
+        if (unknownField !== undefined) {
+            return invalidTodos(`todos[${index}] has unknown field ${unknownField}`);
+        }
+        const { content, status } = todo;
+        if (typeof content !== "string" || isBlankText(content)) {
+            return invalidTodos(`todos[${index}].content must be a non-empty string`);
+        }
+        if (typeof status !== "string" || !planTaskStatuses.includes(status)) {
+            return invalidTodos(`todos[${index}].status must be pending, in_progress, or completed`);
+        }
+        tasks.push({ content, status: status });
+    }
+    return { isValid: true, arguments: tasks };
+}
+/** Tool output after `write_todos` wrote tasks: `{"status":"updated","revision":<n>,"task_count":<k>}`. */
+export function buildPlanUpdatedOutput(revision, taskCount) {
+    return JSON.stringify({ status: "updated", revision, task_count: taskCount });
+}
+/** Tool output after `write_todos` cleared the plan: `{"status":"cleared","revision":<n>}`. */
+export function buildPlanClearedOutput(revision) {
+    return JSON.stringify({ status: "cleared", revision });
+}
+/** Tool output after the user answered `ask_user`: `{"status":"answered","answer":"<answer>"}`. */
+export function buildQuestionAnsweredOutput(answer) {
+    return JSON.stringify({ status: "answered", answer });
+}
+/** Tool output after a `durable_wait` Timer ended: `{"status":"completed","waited_seconds":<n>,"reason":"<reason>"}`. */
+export function buildDurableWaitCompletedOutput(waitedSeconds, reason) {
+    return JSON.stringify({ status: "completed", waited_seconds: waitedSeconds, reason });
+}
+function invalidTodos(reason) {
+    return { isValid: false, error: `invalid todos: ${reason}` };
+}
+/** Sorted by code point, as Python's `sorted` orders strings, so both cores report the same name. */
+function sortByCodePoint(names) {
+    return [...names].sort(compareByCodePoint);
+}
+/** JavaScript's `<` compares UTF-16 code units, which orders characters above U+FFFF before U+E000. */
+function compareByCodePoint(left, right) {
+    const leftCodePoints = Array.from(left, (character) => character.codePointAt(0) ?? 0);
+    const rightCodePoints = Array.from(right, (character) => character.codePointAt(0) ?? 0);
+    const sharedLength = Math.min(leftCodePoints.length, rightCodePoints.length);
+    for (let index = 0; index < sharedLength; index += 1) {
+        const difference = (leftCodePoints[index] ?? 0) - (rightCodePoints[index] ?? 0);
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return leftCodePoints.length - rightCodePoints.length;
+}
+function parseArgumentsObject(builtInTool, argumentsText) {
+    let parsed;
+    try {
+        parsed = JSON.parse(argumentsText);
+    }
+    catch {
+        return invalidArguments(builtInTool, "arguments must be a JSON object");
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return invalidArguments(builtInTool, "arguments must be a JSON object");
+    }
+    const definition = builtInToolDefinitions.find((candidate) => candidate.name === builtInTool);
+    const allowedNames = Object.keys((definition?.parameters["properties"] ?? {}));
+    const [unknownName] = sortByCodePoint(Object.keys(parsed).filter((name) => !allowedNames.includes(name)));
+    if (unknownName !== undefined) {
+        return invalidArguments(builtInTool, `unknown argument ${unknownName}`);
+    }
+    return { isValid: true, arguments: parsed };
+}
+function invalidArguments(builtInTool, reason) {
+    return { isValid: false, error: `invalid ${builtInTool} arguments: ${reason}` };
+}
+//# sourceMappingURL=agent-built-in-tools.js.map

package/dist/src/agent-built-in-tools.js.map

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

package/dist/src/agent-context-compaction.d.ts

@@ -0,0 +1,108 @@
+import type { AgentEventWriter, AgentFrameworkRunner, DeferredToolOutcome, ModelCallMetadata } from "./agent-framework-runner.js";
+import type { AgentMessage, AgentUsage, ContextSummary, SessionSettings } from "./agent-session-values.js";
+/**
+ * When a session summarizes its earlier messages so the model input stays under the context window, passed
+ * as {@link AgentSessionOptions.compaction} or as `AgentDefinition.compaction` for a Stepwise agent.
+ *
+ * Before each model call, `RunModel` asks the runner for the size of the next model input. When it reaches
+ * {@link triggerRatio} of {@link contextWindowTokens}, `RunModel` makes no model call and moves to
+ * `CompactContext`, which folds the earlier messages into a {@link ContextSummary}, then back to
+ * `RunModel`. The runner must implement {@link AgentFrameworkRunner.estimateInputTokens},
+ * {@link AgentFrameworkRunner.selectCompactionCutoff}, and {@link AgentFrameworkRunner.summarizeContext};
+ * `createAgentSessionFlow` throws otherwise. Summarized messages stay stored until
+ * `AgentSessionOptions.retainedMessageLimit` deletes them; only the model input changes. Enable
+ * compaction only after every Worker of the Flow type runs a release with the `CompactContext` Step.
+ *
+ * @example
+ * ```ts
+ * const flow = createAgentSessionFlow(runner, "SupportAgent", {
+ *   compaction: { contextWindowTokens: 400_000 },
+ * });
+ * ```
+ */
+export interface CompactionPolicy {
+    /** The model's context window, in the tokens that the runner's `estimateInputTokens` counts. */
+    readonly contextWindowTokens: number;
+    /** Share of the window at which the session compacts before the next model call. Defaults to 0.85. */
+    readonly triggerRatio?: number;
+    /** Share of the window that the newest messages may keep unsummarized. Defaults to 0.3. */
+    readonly retainedRatio?: number;
+}
+/** A {@link CompactionPolicy} with every default filled in. */
+export interface ResolvedCompactionPolicy {
+    /** The model's context window in tokens. */
+    readonly contextWindowTokens: number;
+    /** Share of the window at which the session compacts. */
+    readonly triggerRatio: number;
+    /** Share of the window that the newest messages may keep. */
+    readonly retainedRatio: number;
+}
+/** What {@link AgentFrameworkRunner.summarizeContext} receives: the messages to fold into a new summary. */
+export interface ContextSummaryRequest {
+    /** Flow ID, which is the session ID. */
+    readonly flowId: string;
+    /** Turn ID of the running turn. */
+    readonly turnId: string;
+    /** One-based `CompactContext` attempt. */
+    readonly attempt: number;
+    /** Dex Step execution ID of the `CompactContext` Step, shared by all of its attempts. */
+    readonly stepExecutionId: string;
+    /** The summary so far, or `null` for the first one. Fold its text into the new summary. */
+    readonly previousSummary: ContextSummary | null;
+    /**
+     * The messages after the previous summary through {@link throughSequence}, in sequence order. No tool
+     * call is separated from its result.
+     */
+    readonly messages: readonly AgentMessage[];
+    /** Sequence of the last message to summarize. */
+    readonly throughSequence: number;
+    /** Events writer bound to the turn and attempt. Write no model text to it: the summary is not an answer. */
+    readonly events: AgentEventWriter;
+    /** Signal aborted when Dex cancels the attempt; pass it to the model call. */
+    readonly cancellationSignal: AbortSignal;
+    /** Absolute deadline of the current attempt, or `undefined` when Dex supplied none. */
+    readonly deadline: Date | undefined;
+    /**
+     * Tokens the summary call may use, the policy's `contextWindowTokens`, or `undefined` for no limit. A runner
+     * keeps the input below it, less what it reserves for the summary, such as its `maxOutputTokens`. The range
+     * can be larger after the window shrank or when compaction starts on a long session;
+     * leave out its oldest part rather than send an over-window request that fails every turn.
+     */
+    readonly inputTokenBudget?: number;
+    /**
+     * The {@link SessionSettings} the running turn started with, as `AgentTurnContext.sessionSettings` has them.
+     * Use them to choose the model that writes the summary. The session always sets it; treat `undefined` as `{}`.
+     */
+    readonly sessionSettings?: SessionSettings;
+    /**
+     * Records a heartbeat. The session already records one every 20 seconds while the summary runs.
+     * @returns A Promise that resolves when the Worker accepted the heartbeat.
+     */
+    heartbeat(): Promise<void>;
+}
+/** What {@link AgentFrameworkRunner.summarizeContext} returns. */
+export interface ContextSummaryResult {
+    /** Summary text; it must not be blank. It replaces the previous summary, so it includes what that one said. */
+    readonly text: string;
+    /** Usage of the summary model call; the session adds it to the session's usage. */
+    readonly usage: AgentUsage;
+    /**
+     * Model and response of the summary call, for the `CompactContext` attempt's `chat` span. When omitted,
+     * the span is named `chat`.
+     */
+    readonly modelCallMetadata?: ModelCallMetadata;
+}
+/** A runner that implements the three optional compaction methods. */
+export type ContextCompactionRunner = AgentFrameworkRunner<DeferredToolOutcome> & Required<Pick<AgentFrameworkRunner<DeferredToolOutcome>, "estimateInputTokens" | "selectCompactionCutoff" | "summarizeContext">>;
+/** Reports whether a runner implements every compaction method. */
+export declare function isContextCompactionRunner(runner: AgentFrameworkRunner<DeferredToolOutcome>): runner is ContextCompactionRunner;
+/**
+ * Fills in a compaction policy's defaults and checks it.
+ * @throws {RangeError} When `contextWindowTokens` is not a positive integer, or unless
+ * `0 < retainedRatio < triggerRatio <= 1`.
+ */
+export declare function resolveCompactionPolicy(policy: CompactionPolicy): ResolvedCompactionPolicy;
+/** Reports whether a model input of this size makes the session compact before the model call. */
+export declare function isCompactionTriggered(policy: ResolvedCompactionPolicy, estimatedInputTokens: number): boolean;
+/** Tokens that the newest messages may keep after compaction: the retained share of the window, rounded down. */
+export declare function readRetainedTokenBudget(policy: ResolvedCompactionPolicy): number;

package/dist/src/agent-context-compaction.js

@@ -0,0 +1,39 @@
+// Copyright (c) 2026 Super Durable, Inc.
+//
+// Licensed under the Sustainable Use License 1.0.
+// You may not use this file except in compliance with the License.
+// See the LICENSE file in the repository root.
+//
+// SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
+/** Reports whether a runner implements every compaction method. */
+export function isContextCompactionRunner(runner) {
+    return (typeof runner.estimateInputTokens === "function" &&
+        typeof runner.selectCompactionCutoff === "function" &&
+        typeof runner.summarizeContext === "function");
+}
+/**
+ * Fills in a compaction policy's defaults and checks it.
+ * @throws {RangeError} When `contextWindowTokens` is not a positive integer, or unless
+ * `0 < retainedRatio < triggerRatio <= 1`.
+ */
+export function resolveCompactionPolicy(policy) {
+    const contextWindowTokens = policy.contextWindowTokens;
+    if (!Number.isSafeInteger(contextWindowTokens) || contextWindowTokens <= 0) {
+        throw new RangeError("compaction.contextWindowTokens must be a positive integer");
+    }
+    const triggerRatio = policy.triggerRatio ?? 0.85;
+    const retainedRatio = policy.retainedRatio ?? 0.3;
+    if (!(retainedRatio > 0 && retainedRatio < triggerRatio && triggerRatio <= 1)) {
+        throw new RangeError("compaction needs 0 < retainedRatio < triggerRatio <= 1");
+    }
+    return Object.freeze({ contextWindowTokens, triggerRatio, retainedRatio });
+}
+/** Reports whether a model input of this size makes the session compact before the model call. */
+export function isCompactionTriggered(policy, estimatedInputTokens) {
+    return estimatedInputTokens >= policy.triggerRatio * policy.contextWindowTokens;
+}
+/** Tokens that the newest messages may keep after compaction: the retained share of the window, rounded down. */
+export function readRetainedTokenBudget(policy) {
+    return Math.floor(policy.retainedRatio * policy.contextWindowTokens);
+}
+//# sourceMappingURL=agent-context-compaction.js.map

package/dist/src/agent-context-compaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-context-compaction.js","sourceRoot":"","sources":["../../src/agent-context-compaction.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAgH1D,mEAAmE;AACnE,MAAM,UAAU,yBAAyB,CACvC,MAAiD;IAEjD,OAAO,CACL,OAAO,MAAM,CAAC,mBAAmB,KAAK,UAAU;QAChD,OAAO,MAAM,CAAC,sBAAsB,KAAK,UAAU;QACnD,OAAO,MAAM,CAAC,gBAAgB,KAAK,UAAU,CAC9C,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAwB;IAC9D,MAAM,mBAAmB,GAAG,MAAM,CAAC,mBAAmB,CAAC;IACvD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,mBAAmB,CAAC,IAAI,mBAAmB,IAAI,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,UAAU,CAAC,2DAA2D,CAAC,CAAC;IACpF,CAAC;IACD,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,IAAI,IAAI,CAAC;IACjD,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,IAAI,GAAG,CAAC;IAClD,IAAI,CAAC,CAAC,aAAa,GAAG,CAAC,IAAI,aAAa,GAAG,YAAY,IAAI,YAAY,IAAI,CAAC,CAAC,EAAE,CAAC;QAC9E,MAAM,IAAI,UAAU,CAAC,wDAAwD,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,mBAAmB,EAAE,YAAY,EAAE,aAAa,EAAE,CAAC,CAAC;AAC7E,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,qBAAqB,CAAC,MAAgC,EAAE,oBAA4B;IAClG,OAAO,oBAAoB,IAAI,MAAM,CAAC,YAAY,GAAG,MAAM,CAAC,mBAAmB,CAAC;AAClF,CAAC;AAED,iHAAiH;AACjH,MAAM,UAAU,uBAAuB,CAAC,MAAgC;IACtE,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,aAAa,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;AACvE,CAAC"}