@qjp88995/agent-runtime 0.0.0-stage → 0.1.0

package/dist/builtins/todo.tool.d.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { AgentTool } from '../tools/agent-tool.base.js';
+import type { ToolMeta } from '../tools/tool-meta.js';
+import type { ToolRegistry } from '../tools/tool-registry.js';
+import { type ToolOut } from '../tools/tool-result.js';
+import { type TodoItem } from './todo-schema.js';
+declare const InputSchema: z.ZodObject<{
+    todos: z.ZodArray<z.ZodObject<{
+        content: z.ZodString;
+        status: z.ZodEnum<{
+            pending: "pending";
+            completed: "completed";
+            in_progress: "in_progress";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type Input = z.infer<typeof InputSchema>;
+interface Out {
+    todos: TodoItem[];
+}
+/**
+ * 待办清单记账工具的登记信息。
+ *
+ * **它没有 service、不写任何表、没有副作用**——这次调用的入参就是清单本身的
+ * 存放处（判据全文见 `todo-schema.ts`）。所以 `run()` 里除了
+ * 一道守卫之外无事可做，这不是没写完。
+ *
+ * 它同时是第一个声明 `accounting: true` 的工具：记账不算「做了别的事」，
+ * 夹在两次相同调用中间不该打断重复调用链的计数（见 `runtime/loop-reminder.ts`）。
+ */
+export declare const TODO_TOOL_META: ToolMeta;
+/** 待办清单记账工具（原名见 `TODO_FORMER_NAMES`）。 */
+export declare class TodoTool extends AgentTool<Input, Out> {
+    readonly inputSchema: z.ZodObject<{
+        todos: z.ZodArray<z.ZodObject<{
+            content: z.ZodString;
+            status: z.ZodEnum<{
+                pending: "pending";
+                completed: "completed";
+                in_progress: "in_progress";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    protected run(input: Input): Promise<ToolOut<Out>>;
+    /**
+     * 回执**只给一行计数，不复述整份清单**。
+     *
+     * 清单原文就在这次调用的入参里，模型下一步照样看得见；把它在输出里再抄一遍
+     * 是纯粹的重复计费。而这条回执本身还会在裁剪时被换成存根（入参不会），
+     * 所以复述的那份清单是活不过裁剪的那一份。
+     */
+    protected render(out: {
+        kind: 'ok';
+    } & Out): string;
+}
+/** 登记 `Todo`。 */
+export declare function registerTodoTool(tools: ToolRegistry): TodoTool;
+export {};
+//# sourceMappingURL=todo.tool.d.ts.map

package/dist/builtins/todo.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"todo.tool.d.ts","sourceRoot":"","sources":["../../src/builtins/todo.tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAExD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAa,KAAK,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EACL,KAAK,QAAQ,EAGd,MAAM,kBAAkB,CAAC;AAE1B,QAAA,MAAM,WAAW;;;;;;;;;iBAIf,CAAC;AACH,KAAK,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEzC,UAAU,GAAG;IACX,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AASD;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,EAAE,QAqB5B,CAAC;AAEF,yCAAyC;AACzC,qBAAa,QAAS,SAAQ,SAAS,CAAC,KAAK,EAAE,GAAG,CAAC;IACjD,QAAQ,CAAC,WAAW;;;;;;;;;sBAAe;IAEnC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAkBlD;;;;;;OAMG;IACH,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE;QAAE,IAAI,EAAE,IAAI,CAAA;KAAE,GAAG,GAAG,GAAG,MAAM;CAiCpD;AAED,iBAAiB;AACjB,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,QAAQ,CAI9D"}

package/dist/builtins/todo.tool.js

@@ -0,0 +1,107 @@
+import { z } from 'zod';
+import { AgentTool } from '../tools/agent-tool.base.js';
+import { TODO_FORMER_NAMES, TODO_TOOL_NAME } from '../tools/builtin-names.js';
+import { toolError } from '../tools/tool-result.js';
+import { TodoListSchema, } from './todo-schema.js';
+const InputSchema = z.object({
+    todos: TodoListSchema.describe('完整的待办清单，按执行顺序排列。每次都要给全份——本次入参会整份取代上一份。'),
+});
+/** 状态 → 回执里的说法。清单本身的顺序不动，这只是计数时的分组名。 */
+const STATUS_LABELS = {
+    in_progress: '进行中',
+    pending: '未开始',
+    completed: '已完成',
+};
+/**
+ * 待办清单记账工具的登记信息。
+ *
+ * **它没有 service、不写任何表、没有副作用**——这次调用的入参就是清单本身的
+ * 存放处（判据全文见 `todo-schema.ts`）。所以 `run()` 里除了
+ * 一道守卫之外无事可做，这不是没写完。
+ *
+ * 它同时是第一个声明 `accounting: true` 的工具：记账不算「做了别的事」，
+ * 夹在两次相同调用中间不该打断重复调用链的计数（见 `runtime/loop-reminder.ts`）。
+ */
+export const TODO_TOOL_META = {
+    name: TODO_TOOL_NAME,
+    formerNames: TODO_FORMER_NAMES,
+    description: '把当前任务拆成一份待办清单，并在推进过程中随时更新它。多步骤、要跨很多次' +
+        '工具调用才能收尾的活儿用它记账：既让你自己不丢步骤，用户也能在界面上看到' +
+        '进度。**每次都要发完整清单**——只改一条的状态也要把其余各条一并带上，' +
+        '本次入参会整份取代上一份。' +
+        '**列清单之前先把要用户拍板的事问清**（范围、粒度、口径这类），或者自己定' +
+        '一个合理默认并写明；不要开工之后做到一半再回头问。' +
+        '**一条一条来**：开始做某一条时把它置 in_progress，这一条的正文写完就立刻' +
+        '再调一次把它置 completed、把下一条置 in_progress，然后才写下一条——' +
+        '不要把几条的内容写在同一段正文里再一起改状态；同一时刻至多一条 in_progress。' +
+        '**列了清单就意味着你会连续做完它**：做完一条紧接着做下一条，不要每完成' +
+        '一条就停下来问「要不要继续」——只有需要用户提供信息或做决定时才停，并说清' +
+        '在等什么。**结束回复之前必须结账**：正文交付的条目，正文写完就算做完，' +
+        '收尾前把它置 completed，不要留到用户下一句话再改。' +
+        '三两步就能答完的请求不必用它，为此记账反而更慢。',
+    category: 'system',
+    // 纯记账、零副作用 → 对重复调用链透明（见 `ToolMeta.accounting`）。
+    accounting: true,
+};
+/** 待办清单记账工具（原名见 `TODO_FORMER_NAMES`）。 */
+export class TodoTool extends AgentTool {
+    inputSchema = InputSchema;
+    run(input) {
+        const running = input.todos.filter(t => t.status === 'in_progress');
+        // 至多一条「进行中」。**拒绝而不是替它挑一条**：多条并行进行中在界面上会让
+        // 「现在做到哪了」这个问题失去唯一答案，而模型实际上就是一次做一件事。
+        // 反过来**零条是合法的**——全部做完的那一次，以及刚列出计划还没动手的那
+        // 一次，都没有进行中的条目，把它也拦掉会逼出一条假的 in_progress。
+        if (running.length > 1) {
+            return Promise.resolve(toolError(`同一时刻至多一条待办可以是 in_progress，这次给了 ${running.length} 条：` +
+                `${running.map(t => t.content).join('、')}。` +
+                '挑一条正在做的置 in_progress，其余退回 pending。'));
+        }
+        return Promise.resolve({ kind: 'ok', todos: input.todos });
+    }
+    /**
+     * 回执**只给一行计数，不复述整份清单**。
+     *
+     * 清单原文就在这次调用的入参里，模型下一步照样看得见；把它在输出里再抄一遍
+     * 是纯粹的重复计费。而这条回执本身还会在裁剪时被换成存根（入参不会），
+     * 所以复述的那份清单是活不过裁剪的那一份。
+     */
+    render(out) {
+        if (out.todos.length === 0) {
+            return '待办清单已清空。';
+        }
+        const counts = new Map();
+        for (const t of out.todos) {
+            counts.set(t.status, (counts.get(t.status) ?? 0) + 1);
+        }
+        // 按 STATUS_LABELS 的键序（进行中 → 未开始 → 已完成）报，且**零的那档不报**
+        // ——「已完成 0 条」是噪音，而没有进行中的条目本就是合法状态。
+        const parts = Object.keys(STATUS_LABELS)
+            .filter(s => (counts.get(s) ?? 0) > 0)
+            .map(s => `${STATUS_LABELS[s]} ${counts.get(s) ?? 0}`);
+        const summary = `待办清单已更新，共 ${out.todos.length} 条（${parts.join(' / ')}）。`;
+        // 有进行中的那条就顺带提一句结账。**放在回执里而不是只写在 description**：
+        // 模型读这句话的时刻恰好是它要动手做这条的前一刻，而 description 在几十轮
+        // 之前的 system prompt 里。真正的兜底在收尾时（`extensions/todo-settle.hook.ts`），
+        // 这句是零成本的那一层——它管用一次，就省下一整轮换轮。
+        const running = out.todos.find(t => t.status === 'in_progress');
+        if (!running)
+            return summary;
+        const remaining = out.todos.filter(t => t.status === 'pending').length;
+        // 还有没开始的就顺带说「接着做别问」：模型最常见的走样是做完一条停下来问
+        // 「要不要继续」（会话 621632d1），而它读这句话的时刻正是决定做完这条之后
+        // 干什么的时刻。
+        const next = remaining > 0
+            ? `更新完再写下一条（还有 ${remaining} 条没开始），一条一条来，不要停下来问要不要继续。`
+            : '';
+        return (`${summary}「${running.content}」进行中——只写这一条的内容，写完立刻` +
+            `再调一次 Todo 把它置 completed（用正文交付的也算做完）。${next}`);
+    }
+}
+/** 登记 `Todo`。 */
+export function registerTodoTool(tools) {
+    const tool = new TodoTool();
+    tools.register(TODO_TOOL_META, tool);
+    return tool;
+}
+//# sourceMappingURL=todo.tool.js.map

package/dist/builtins/todo.tool.js.map

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

package/dist/context/context-budget-tracker.d.ts

@@ -0,0 +1,185 @@
+import { type ModelMessage } from 'ai';
+import type { TurnHookRegistry } from '../hooks/turn-hook.registry.js';
+import type { TurnContext, TurnHookImpl, TurnHookMeta } from '../hooks/turn-hook.types.js';
+import type { ContextStore } from '../ports/context-store.js';
+import { type Logger } from '../ports/logger.js';
+import { type ContextPressure, type ContextRelief } from '../turn/context-pressure.js';
+import { type ProjectionOptions } from '../turn/parts-to-model-messages.js';
+import type { LlmHandles } from '../turn/turn-run.js';
+/**
+ * 一个 tick 的上下文预算管家。
+ *
+ * **持有轮初那批行的快照，全程不再查库拿历史**。两条理由，都不是性能：
+ *
+ * 1. 「本轮已开的行不许进阴影区」——快照里根本没有本轮的行（`loadContext` 跑在
+ *    第一次 `drainInbox` 之前，本轮的用户消息那时还在 inbox 里），这条因此是
+ *    结构上成立的，不靠谁记得去判断。
+ * 2. 重新查库投影会把 drain 消息的**围栏**抹掉（内存里那些用的是 `modelParts`，
+ *    与落库的 `parts` 不同）。这也是 `ContextRelief` 只替换头部的原因。
+ */
+export declare class ContextBudgetTracker {
+    private readonly deps;
+    private rows;
+    private storedRows;
+    private prunedUpto;
+    private compactedUpto;
+    /**
+     * 上一条还活着的 checkpoint 行的 seq（没有则 null）。
+     *
+     * 新的压缩切点**必须覆盖它**：留着它就会同时存在两份摘要，而投影层只提头一条，
+     * 另一条会按 seq 落在保留段中间——同一段历史被讲两遍，且其中一遍是过期的。
+     */
+    private checkpointSeq;
+    private baseline;
+    /** 已经报过一次「模型没填容量」的 warn，别每步刷一条。 */
+    private warnedNoCapacity;
+    /**
+     * 本 tick 已经尝试过几次压缩。
+     *
+     * **失败的也算**：一个不肯好好写摘要的模型，重试第三次多半还是那样，而每次
+     * 都是一整个上下文的全量请求 —— 空转的代价与真压缩一样贵。
+     */
+    private compactionAttempts;
+    constructor(deps: {
+        store: ContextStore;
+        logger: Logger;
+        sessionId: string;
+        /** 该模型的上下文窗口；null = 未知。 */
+        maxContextTokens: number | null;
+        /** 该模型的单次最大输出；null = 运营没填（见 `computeContextThreshold`）。 */
+        maxOutputTokens: number | null;
+        reserveFactor: number;
+        retainRatio: number;
+        /**
+         * 本轮所用的模型句柄与推理参数。**压缩刻意沿用本会话当前的模型**，不走
+         * `ai-feature` 那套「平台自己的小 LLM 调用」：换模型 = 前缀缓存全丢，把
+         * 「逐字重放前缀」那条设计的收益直接抵消掉。
+         */
+        llm: LlmHandles;
+        /**
+         * 投影时额外登记的提醒类行（`ProjectionOptions.reminderKinds`）。**宿主当轮注入
+         * 时怎么包，这里就得登记**，否则经 tracker 重放时它以裸用户文字喂给模型。
+         */
+        projection?: Pick<ProjectionOptions, 'reminderKinds' | 'toolNameAliases'>;
+    });
+    /** `TurnHost.loadContext`：投影出带裁剪与压缩的历史，同时留下本轮要用的快照。 */
+    load(): Promise<ModelMessage[]>;
+    /**
+     * 快照的投影，可选只取 `seq ≤ upto` 的那一段（算 `replaces` 用）。
+     *
+     * 收成一个方法而不是各处各写一次 `partsToModelMessages(...)`：**两个指针必须
+     * 一起传**，漏掉压缩指针那一处会把已经压掉的行重新投出来，而症状只是「压缩
+     * 好像没生效」。
+     *
+     * **checkpoint 行不受 `upto` 约束**：它的 seq 是全场最大的，而投影层把它提到了
+     * 历史最前面 —— `messages` 的头部因此是「checkpoint + 前 upto 条」。按 seq 卡掉
+     * 它，算出来的 `replaces` 就比真实头部少一条，splice 会把尾部整体错位一格。
+     */
+    private project;
+    /**
+     * 本轮的触发线。**也给前端**（经 `TurnResult.contextThreshold` 落进
+     * metadata）——界面上那个「快满了」的变色判据必须与这里同源，各写一个 0.8
+     * 的结果是界面说「还早」而日志里已经在裁了。
+     */
+    thresholdOf(maxContextTokens: number): number;
+    /** 本轮的触发线；容量未知时为 null（那时压根不做主动裁剪）。 */
+    get threshold(): number | null;
+    /**
+     * `beforeModelCall` 的正体：超阈值就腾空间，返回新的头部。
+     *
+     * **两级，顺序固定**：先裁剪（免模型、零成本、单次就能吃掉长会话的大头），
+     * 裁到头仍不够才压缩（要花一次全量请求）。免模型的路径永远该先跑，模型摘要
+     * 是兜底 —— 裁剪把压缩的触发频率压得很低正是期望的结果。
+     */
+    relieve(pressure: ContextPressure): Promise<ContextRelief | null>;
+    /**
+     * 还在上下文里的那段历史有多大（按 `字符数 / 4` 估）。
+     *
+     * **只在溢出补救那条路上用**：那时可能连模型窗口都不知道（`max_context_tokens`
+     * 没填），拿不到触发线，也就没有「触发线 × 保留比例」这个口径。用历史自己的
+     * 规模当分母是这种情况下唯一站得住的做法——刚刚撞爆过，所以它约等于窗口。
+     *
+     * 注意这是**原始行**的规模：裁剪已经把一部分正文换成存根了，故这是个高估，
+     * 方向是「多腾一点」。撞爆之后宁可多腾。
+     */
+    private estimatedHistoryTokens;
+    /**
+     * 尚未被压缩掉的那部分快照。**切点只能在这里面算** —— 已经压掉的行在模型眼里
+     * 不存在了，把它们算进保留预算会让预算凭空少一块，切点随之偏晚。
+     */
+    private survivingRows;
+    /** 第一级：把裁剪指针往前推。腾不动返回 null（交给压缩）。 */
+    private prune;
+    /**
+     * 第二级：让模型把前面那段历史写成一份交接说明，整段换成一条 checkpoint。
+     *
+     * **失败一律返回 null、不抛。** 主动的阈值检查里超线不等于撞爆，这一轮多半
+     * 照样发得出去；为了「上下文快满了」把一轮本来能成的对话打死，比什么都不做更
+     * 糟。真撞爆的那条路（溢出补救）自己会判定必要性——它拿到 null 就把 provider
+     * 的原始错误原样抛出，抛错的判断权在内核那一侧，不在这里。
+     */
+    private compact;
+}
+/**
+ * tracker 在 `TurnContext.turnState` 里的键。**导出**：宿主按它预置
+ * （`createContextBudgetTracker` 的用法示例），插件按它取用，两边分叉的症状是上下文预算
+ * 静默关闭——没有报错，只有会话在某一天撞爆 context window。
+ */
+export declare const CONTEXT_BUDGET_TURN_STATE_KEY = "context-budget";
+/** 宿主不给时的缺省参数（照抄 dsh 跑过真实负载的那一组）。 */
+export declare const CONTEXT_BUDGET_DEFAULTS: {
+    /** 预留几倍的最大输出（见 `ThresholdInput.reserveFactor`）。 */
+    readonly reserveFactor: 1;
+    /** 腾空间时保留触发线的多大比例给最近的历史。 */
+    readonly retainRatio: 0.16;
+};
+/**
+ * 建本轮的 tracker。宿主在 `TurnHost` 里这样接：
+ *
+ * ```ts
+ * const budget = createContextBudgetTracker({ store, sessionId, llm, maxContextTokens, … });
+ * const host: TurnHost = {
+ *   loadContext: () => budget.load(),
+ *   turnState: new Map([[CONTEXT_BUDGET_TURN_STATE_KEY, budget]]),
+ *   …
+ * };
+ * // 终态：budget.threshold 落进 metadata，界面的「快满了」与这里同源。
+ * ```
+ *
+ * **tracker 由宿主建、经 `turnState` 交给钩子**，钩子自己不建：它同时是
+ * `loadContext` 的投影源与终态 `contextThreshold` 的来源，三方必须是同一个实例；
+ * 且切点跑在第一次 drain 之后，那时懒建出来的快照会把本轮的用户消息算进可裁剪的
+ * 阴影区。
+ *
+ * 阈值参数在 agent-base 里走系统参数（只有真实负载上才知道合不合适，调它们不该
+ * 要一次发版）；这里由宿主传入，宿主自己决定从哪读。
+ */
+export declare function createContextBudgetTracker(opts: {
+    store: ContextStore;
+    sessionId: string;
+    llm: LlmHandles;
+    /** 该模型的上下文窗口；null = 未知（此时只做溢出补救、不主动腾）。 */
+    maxContextTokens: number | null;
+    /** 该模型的单次最大输出；null = 未知（按窗口 20% 假设）。 */
+    maxOutputTokens: number | null;
+    reserveFactor?: number;
+    retainRatio?: number;
+    logger?: Logger;
+    /** 宿主登记的提醒类行（见 `ProjectionOptions.reminderKinds`）。 */
+    projection?: Pick<ProjectionOptions, 'reminderKinds' | 'toolNameAliases'>;
+}): ContextBudgetTracker;
+export declare const CONTEXT_BUDGET_HOOK_META: TurnHookMeta;
+/**
+ * 上下文预算的 `beforeModelCall` 钩子：取宿主预置的 tracker，把压力转给它。
+ *
+ * **单例点**——两个插件先后替换 `messages` 的头部，第二个看到的已经不是原始
+ * 历史，它算出的 `replaces` 对不上任何一段真实前缀。
+ */
+export declare class ContextBudgetHook implements TurnHookImpl {
+    private readonly logger;
+    constructor(logger?: Logger);
+    beforeModelCall(ctx: TurnContext, pressure: ContextPressure): Promise<ContextRelief | null>;
+}
+/** 把上下文预算钩子挂到注册表上。 */
+export declare function registerContextBudgetHook(hooks: TurnHookRegistry, logger?: Logger): void;
+//# sourceMappingURL=context-budget-tracker.d.ts.map

package/dist/context/context-budget-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-tracker.d.ts","sourceRoot":"","sources":["../../src/context/context-budget-tracker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,IAAI,CAAC;AAErD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,KAAK,EACV,WAAW,EACX,YAAY,EACZ,YAAY,EACb,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAc,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC1E,OAAO,EAAE,KAAK,MAAM,EAAgB,MAAM,oBAAoB,CAAC;AAG/D,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,aAAa,EAEnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAoCtD;;;;;;;;;;GAUG;AACH,qBAAa,oBAAoB;IAwB7B,OAAO,CAAC,QAAQ,CAAC,IAAI;IAvBvB,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,UAAU,CAAoB;IACtC,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,aAAa,CAAuB;IAC5C;;;;;OAKG;IACH,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,QAAQ,CAAuB;IACvC,mCAAmC;IACnC,OAAO,CAAC,gBAAgB,CAAS;IACjC;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB,CAAK;gBAGZ,IAAI,EAAE;QACrB,KAAK,EAAE,YAAY,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,2BAA2B;QAC3B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,2DAA2D;QAC3D,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,aAAa,EAAE,MAAM,CAAC;QACtB,WAAW,EAAE,MAAM,CAAC;QACpB;;;;WAIG;QACH,GAAG,EAAE,UAAU,CAAC;QAChB;;;WAGG;QACH,UAAU,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,eAAe,GAAG,iBAAiB,CAAC,CAAC;KAC3E;IAGH,uDAAuD;IACjD,IAAI,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAerC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,OAAO;IAef;;;;OAIG;IACH,WAAW,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM;IAQ7C,sCAAsC;IACtC,IAAI,SAAS,IAAI,MAAM,GAAG,IAAI,CAG7B;IAED;;;;;;OAMG;IACG,OAAO,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IA8CvE;;;;;;;;;OASG;IACH,OAAO,CAAC,sBAAsB;IAK9B;;;OAGG;IACH,OAAO,CAAC,aAAa;IAKrB,qCAAqC;YACvB,KAAK;IAgCnB;;;;;;;OAOG;YACW,OAAO;CAoGtB;AAED;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,mBAAmB,CAAC;AAW9D,qCAAqC;AACrC,eAAO,MAAM,uBAAuB;IAClC,mDAAmD;;IAEnD,4BAA4B;;CAEpB,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE;IAC/C,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,UAAU,CAAC;IAChB,0CAA0C;IAC1C,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,wCAAwC;IACxC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,UAAU,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,eAAe,GAAG,iBAAiB,CAAC,CAAC;CAC3E,GAAG,oBAAoB,CAYvB;AAED,eAAO,MAAM,wBAAwB,EAAE,YActC,CAAC;AAEF;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,YAAY;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,GAAE,MAAyB;IAE9D,eAAe,CACb,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,eAAe,GACxB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;CAajC;AAED,sBAAsB;AACtB,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,gBAAgB,EACvB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI,CAEN"}