@trenchwork/erosolar 1.1.30 → 1.1.32

package/dist/tools/webTools.js

@@ -0,0 +1,332 @@
+/**
+ * Web Tools - Web search and content extraction capabilities
+ *
+ * Provides:
+ * - WebSearch: Search the web using Tavily
+ * - WebExtract: Extract and summarize content from URLs
+ */
+import { getSecretValue } from '../core/secretStore.js';
+import { buildError } from '../core/errors.js';
+/**
+ * Create web tools for search and extraction.
+ */
+export function createWebTools() {
+    return [
+        {
+            name: 'WebSearch',
+            description: 'Search the web for current/up-to-date information using Tavily. Use proactively for news, events, recent releases, library docs that may have changed, or any time-sensitive lookup. Works out of the box via the Erosolar-hosted proxy; set TAVILY_API_KEY for unlimited use.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    query: {
+                        type: 'string',
+                        description: 'The search query',
+                    },
+                    maxResults: {
+                        type: 'number',
+                        description: 'Maximum number of results to return (default: 5, max: 10)',
+                    },
+                    searchDepth: {
+                        type: 'string',
+                        enum: ['basic', 'advanced'],
+                        description: 'Search depth: basic (fast) or advanced (thorough). Default: basic',
+                    },
+                    includeAnswer: {
+                        type: 'boolean',
+                        description: 'Include AI-generated answer summary. Default: true',
+                    },
+                },
+                required: ['query'],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const query = args['query'];
+                if (typeof query !== 'string' || !query.trim()) {
+                    return 'Error: query is required';
+                }
+                const maxResults = Math.min(typeof args['maxResults'] === 'number' ? args['maxResults'] : 5, 10);
+                const searchDepth = args['searchDepth'] === 'advanced' ? 'advanced' : 'basic';
+                const includeAnswer = args['includeAnswer'] !== false;
+                try {
+                    const tavilyKey = getSecretValue('TAVILY_API_KEY');
+                    if (tavilyKey) {
+                        return await searchTavily(query, tavilyKey, { maxResults, searchDepth, includeAnswer });
+                    }
+                    // No local key — fall back to the Erosolar-hosted Tavily proxy so
+                    // the agent can search proactively out of the box. Counts against
+                    // the operator's Tavily quota; users wanting unlimited can set
+                    // TAVILY_API_KEY locally.
+                    return await searchTavilyViaProxy(query, { maxResults, searchDepth, includeAnswer });
+                }
+                catch (error) {
+                    return buildError('WebSearch', error, { query });
+                }
+            },
+        },
+        {
+            name: 'WebExtract',
+            description: 'Extract and summarize content from one or more URLs using Tavily. Use after WebSearch when you need the full content of a specific page (docs, articles, GitHub issues). Requires TAVILY_API_KEY.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    urls: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'URLs to extract content from (max 5)',
+                    },
+                    url: {
+                        type: 'string',
+                        description: 'Single URL to extract content from (alternative to urls array)',
+                    },
+                },
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                let urls = [];
+                if (Array.isArray(args['urls'])) {
+                    urls = args['urls'].filter((u) => typeof u === 'string');
+                }
+                else if (typeof args['url'] === 'string') {
+                    urls = [args['url']];
+                }
+                if (urls.length === 0) {
+                    return 'Error: at least one URL is required';
+                }
+                // Limit to 5 URLs
+                urls = urls.slice(0, 5);
+                const tavilyKey = getSecretValue('TAVILY_API_KEY');
+                if (!tavilyKey) {
+                    return 'WebExtract requires TAVILY_API_KEY to be configured. Use /secrets set TAVILY_API_KEY to configure.';
+                }
+                try {
+                    return await extractTavily(urls, tavilyKey);
+                }
+                catch (error) {
+                    return buildError('WebExtract', error, { urls: urls.join(', ') });
+                }
+            },
+        },
+        {
+            name: 'WebFetch',
+            description: 'Fetch the raw content of a single URL via HTTP GET. Returns the response body as text (HTML/JSON/plain). Use this when you need the LITERAL page content (e.g., reading a specific docs page, fetching a JSON API). For research / "what does the web say about X" queries, use WebSearch instead — Tavily returns clean summaries.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    url: { type: 'string', description: 'Absolute http(s):// URL to fetch.' },
+                    maxBytes: { type: 'number', description: 'Cap the response at this many bytes (default 200_000, max 2_000_000).' },
+                },
+                required: ['url'],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const url = args['url']?.trim();
+                if (!url)
+                    return 'Error: url is required.';
+                if (!/^https?:\/\//i.test(url))
+                    return 'Error: url must start with http:// or https://.';
+                const requestedCap = typeof args['maxBytes'] === 'number' ? args['maxBytes'] : 200_000;
+                const cap = Math.max(1024, Math.min(2_000_000, requestedCap));
+                try {
+                    // 30s upper bound — long enough for slow doc sites, short
+                    // enough that the user doesn't watch a stalled spinner.
+                    const controller = new AbortController();
+                    const timer = setTimeout(() => controller.abort(), 30_000);
+                    const res = await fetch(url, {
+                        redirect: 'follow',
+                        signal: controller.signal,
+                        headers: { 'User-Agent': 'erosolar-coder/WebFetch' },
+                    }).finally(() => clearTimeout(timer));
+                    if (!res.ok) {
+                        return `Error: HTTP ${res.status} ${res.statusText} fetching ${url}`;
+                    }
+                    const ctype = res.headers.get('content-type') || 'unknown';
+                    const buf = await res.arrayBuffer();
+                    const truncated = buf.byteLength > cap;
+                    const slice = truncated ? buf.slice(0, cap) : buf;
+                    // Decode as UTF-8. Binary content will look like garbage —
+                    // we're optimizing for HTML/text/JSON which dominates web
+                    // fetching.
+                    const text = new TextDecoder('utf-8', { fatal: false }).decode(slice);
+                    const headerLines = [
+                        `[WebFetch ${url}]`,
+                        `Status: ${res.status}  Content-Type: ${ctype}  Size: ${buf.byteLength} bytes${truncated ? ` (truncated to ${cap})` : ''}`,
+                        '',
+                    ];
+                    return headerLines.join('\n') + text;
+                }
+                catch (error) {
+                    if (error.name === 'AbortError') {
+                        return `Error: WebFetch timed out (30s) for ${url}`;
+                    }
+                    return buildError('WebFetch', error, { url });
+                }
+            },
+        },
+    ];
+}
+// Erosolar's hosted Tavily proxy (AWS API Gateway → Lambda). Lets the CLI
+// search out of the box for users who haven't set TAVILY_API_KEY locally;
+// counts against the operator's Tavily quota.
+const EROSOLAR_TAVILY_PROXY_URL = 'https://cfqeqx4lt9.execute-api.us-east-1.amazonaws.com/api/tavilySearch';
+/**
+ * Fallback for users without a local TAVILY_API_KEY: hit the Erosolar
+ * server-side proxy which uses the operator's key. Returns the same
+ * markdown shape as `searchTavily`. Errors propagate as a string for the
+ * tool harness to surface without crashing the agent loop.
+ */
+async function searchTavilyViaProxy(query, options) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 30_000);
+    try {
+        const res = await fetch(EROSOLAR_TAVILY_PROXY_URL, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                query,
+                maxResults: options.maxResults,
+                depth: options.searchDepth,
+                includeAnswer: options.includeAnswer,
+            }),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            if (res.status === 503) {
+                return 'WebSearch is temporarily unavailable on the Erosolar proxy. Set TAVILY_API_KEY locally with `/secrets set TAVILY_API_KEY` for unlimited use.';
+            }
+            throw new Error(`Erosolar Tavily proxy error: ${res.status} ${text.slice(0, 300)}`);
+        }
+        const data = (await res.json());
+        return formatTavilyResults(data, 'Tavily (via Erosolar)');
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'AbortError') {
+            throw new Error('WebSearch via Erosolar proxy timed out after 30 seconds');
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Search using Tavily API (recommended provider)
+ */
+async function searchTavily(query, apiKey, options) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 24 * 60 * 60 * 1000); // 24 hour timeout
+    try {
+        const response = await fetch('https://api.tavily.com/search', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                api_key: apiKey,
+                query,
+                search_depth: options.searchDepth,
+                include_answer: options.includeAnswer,
+                max_results: options.maxResults,
+            }),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`Tavily API error: ${response.status} ${text}`);
+        }
+        const data = (await response.json());
+        return formatTavilyResults(data, 'Tavily');
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'AbortError') {
+            throw new Error('Tavily search timed out after 30 seconds');
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+/**
+ * Extract content using Tavily Extract API
+ */
+async function extractTavily(urls, apiKey) {
+    const response = await fetch('https://api.tavily.com/extract', {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            api_key: apiKey,
+            urls,
+        }),
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`Tavily Extract API error: ${response.status} ${text}`);
+    }
+    const data = (await response.json());
+    return formatExtractResults(data);
+}
+/**
+ * Format Tavily search results with enhanced markdown formatting
+ */
+function formatTavilyResults(data, provider) {
+    const lines = [`[WebSearch via ${provider}]`, ''];
+    if (data.answer) {
+        lines.push('**Summary:**', data.answer, '');
+    }
+    if (!data.results || data.results.length === 0) {
+        lines.push('No results found.');
+        return lines.join('\n');
+    }
+    if (data.results.length > 0) {
+        lines.push('**Search Results:**');
+        lines.push('');
+        for (let i = 0; i < data.results.length; i++) {
+            const result = data.results[i];
+            // Format as numbered list with clickable title link
+            lines.push(`${i + 1}. **[${result.title}](${result.url})**`);
+            if (result.content) {
+                const snippet = result.content.length > 300
+                    ? result.content.slice(0, 300) + '...'
+                    : result.content;
+                lines.push(`   ${snippet}`);
+            }
+            if (result.published_date) {
+                lines.push(`   *Published: ${result.published_date}*`);
+            }
+            lines.push('');
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Format Tavily extract results with enhanced markdown formatting
+ */
+function formatExtractResults(data) {
+    const lines = ['[WebExtract via Tavily]', ''];
+    if (!data.results || data.results.length === 0) {
+        lines.push('No content extracted.');
+        return lines.join('\n');
+    }
+    for (let i = 0; i < data.results.length; i++) {
+        const result = data.results[i];
+        lines.push(`### Source ${i + 1}: [${result.url}](${result.url})`);
+        lines.push('');
+        if (result.raw_content) {
+            // Truncate very long content
+            const content = result.raw_content.length > 5000
+                ? result.raw_content.slice(0, 5000) + '\n\n*[Content truncated...]*'
+                : result.raw_content;
+            lines.push(content);
+        }
+        lines.push('');
+        if (i < data.results.length - 1) {
+            lines.push('---');
+            lines.push('');
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=webTools.js.map

package/dist/tools/webTools.js.map

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

package/dist/tools/worktreeTools.d.ts

@@ -0,0 +1,21 @@
+/**
+ * EnterWorktree / ExitWorktree — Claude-Code-parity isolation tools.
+ *
+ * Creates a temporary git worktree the agent can work in without
+ * disturbing the user's checkout, then cleans it up. Used by the
+ * sub-agent flow when `isolation: "worktree"` is requested, and
+ * directly by the agent for risky multi-file changes that should
+ * land as a single PR.
+ *
+ * Worktrees are created under <repoRoot>/.erosolar/worktrees/<id>/.
+ * The branch follows `erosolar/worktree/<id>` so a stale tree is
+ * easy to spot in `git branch`.
+ */
+import type { ToolDefinition } from '../core/toolRuntime.js';
+export declare function getWorktreeRegistry(): ReadonlyMap<string, {
+    path: string;
+    branch: string;
+}>;
+export declare function clearWorktreeRegistry(): void;
+export declare function createWorktreeTools(workingDir: string): ToolDefinition[];
+//# sourceMappingURL=worktreeTools.d.ts.map

package/dist/tools/worktreeTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktreeTools.d.ts","sourceRoot":"","sources":["../../src/tools/worktreeTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAwB7D,wBAAgB,mBAAmB,IAAI,WAAW,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAE3F;AAED,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,EAAE,CAqHxE"}

package/dist/tools/worktreeTools.js

@@ -0,0 +1,158 @@
+/**
+ * EnterWorktree / ExitWorktree — Claude-Code-parity isolation tools.
+ *
+ * Creates a temporary git worktree the agent can work in without
+ * disturbing the user's checkout, then cleans it up. Used by the
+ * sub-agent flow when `isolation: "worktree"` is requested, and
+ * directly by the agent for risky multi-file changes that should
+ * land as a single PR.
+ *
+ * Worktrees are created under <repoRoot>/.erosolar/worktrees/<id>/.
+ * The branch follows `erosolar/worktree/<id>` so a stale tree is
+ * easy to spot in `git branch`.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+const WORKTREE_REGISTRY = new Map();
+function repoRoot(workingDir) {
+    try {
+        const out = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            cwd: workingDir,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        return out.trim() || workingDir;
+    }
+    catch {
+        return workingDir;
+    }
+}
+function safeId(raw) {
+    const s = typeof raw === 'string' ? raw.trim() : '';
+    if (!s)
+        return `wt-${Date.now().toString(36)}`;
+    // Lock down to alnum/hyphen/underscore. Caller owns the ergonomic name.
+    return s.replace(/[^a-zA-Z0-9_-]/g, '-').slice(0, 64);
+}
+export function getWorktreeRegistry() {
+    return WORKTREE_REGISTRY;
+}
+export function clearWorktreeRegistry() {
+    WORKTREE_REGISTRY.clear();
+}
+export function createWorktreeTools(workingDir) {
+    return [
+        {
+            name: 'EnterWorktree',
+            description: 'Create a temporary git worktree for isolated changes. ' +
+                'Returns the worktree path; the agent should `cd` into it ' +
+                'or pass the path to subsequent file ops. Use for risky or ' +
+                'speculative changes that should not touch the live checkout.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    id: {
+                        type: 'string',
+                        description: 'Short ergonomic id for the worktree (alnum/-/_, ≤64 chars). ' +
+                            'Used in path and branch name. Auto-generated if omitted.',
+                    },
+                    base: {
+                        type: 'string',
+                        description: 'Branch or commit to base the worktree on. Defaults to HEAD.',
+                    },
+                },
+            },
+            handler: async (args) => {
+                const id = safeId(args['id']);
+                if (WORKTREE_REGISTRY.has(id)) {
+                    const existing = WORKTREE_REGISTRY.get(id);
+                    return `Worktree "${id}" already exists at ${existing.path} (branch ${existing.branch}).`;
+                }
+                const root = repoRoot(workingDir);
+                const wtRoot = join(root, '.erosolar', 'worktrees');
+                if (!existsSync(wtRoot)) {
+                    mkdirSync(wtRoot, { recursive: true });
+                }
+                const wtPath = join(wtRoot, id);
+                const branch = `erosolar/worktree/${id}`;
+                const base = typeof args['base'] === 'string' && args['base'].trim() ? args['base'].trim() : 'HEAD';
+                try {
+                    execFileSync('git', ['worktree', 'add', '-b', branch, wtPath, base], {
+                        cwd: root,
+                        stdio: ['ignore', 'pipe', 'pipe'],
+                    });
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return `EnterWorktree failed: ${msg}`;
+                }
+                WORKTREE_REGISTRY.set(id, { path: wtPath, branch });
+                return `Worktree "${id}" created at ${wtPath} on branch ${branch}.`;
+            },
+        },
+        {
+            name: 'ExitWorktree',
+            description: 'Remove a worktree previously created by EnterWorktree. ' +
+                'Pass `keepBranch: true` to preserve the branch (the worktree ' +
+                'directory is always removed). Use this once the changes have ' +
+                'been merged back or are no longer needed.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    id: { type: 'string', description: 'Worktree id from EnterWorktree.' },
+                    keepBranch: {
+                        type: 'boolean',
+                        description: 'Preserve the underlying branch after removing the worktree.',
+                    },
+                },
+                required: ['id'],
+            },
+            handler: async (args) => {
+                const id = safeId(args['id']);
+                const entry = WORKTREE_REGISTRY.get(id);
+                if (!entry) {
+                    return `No registered worktree with id "${id}". Use EnterWorktree first.`;
+                }
+                const root = repoRoot(workingDir);
+                try {
+                    execFileSync('git', ['worktree', 'remove', '--force', entry.path], {
+                        cwd: root,
+                        stdio: ['ignore', 'pipe', 'pipe'],
+                    });
+                }
+                catch {
+                    if (existsSync(entry.path)) {
+                        rmSync(entry.path, { recursive: true, force: true });
+                    }
+                }
+                if (!args['keepBranch']) {
+                    try {
+                        execFileSync('git', ['branch', '-D', entry.branch], {
+                            cwd: root,
+                            stdio: ['ignore', 'pipe', 'pipe'],
+                        });
+                    }
+                    catch {
+                        // Branch may already be gone or detached; non-fatal.
+                    }
+                }
+                WORKTREE_REGISTRY.delete(id);
+                return `Worktree "${id}" removed${args['keepBranch'] ? ' (branch retained)' : ''}.`;
+            },
+        },
+        {
+            name: 'ListWorktrees',
+            description: 'List active worktrees registered by EnterWorktree.',
+            parameters: { type: 'object', properties: {} },
+            handler: async () => {
+                if (WORKTREE_REGISTRY.size === 0) {
+                    return 'No active worktrees.';
+                }
+                const lines = Array.from(WORKTREE_REGISTRY.entries()).map(([id, e]) => `${id} → ${resolve(e.path)} (branch ${e.branch})`);
+                return lines.join('\n');
+            },
+        },
+    ];
+}
+//# sourceMappingURL=worktreeTools.js.map

package/dist/tools/worktreeTools.js.map

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

package/dist/ui/RenderGate.d.ts

@@ -0,0 +1,83 @@
+/**
+ * RenderGate — single-source-of-truth render scheduler for the terminal
+ * UI. Modeled on Claude Code's render-on-commit pattern (custom React
+ * reconciler with a dirty flag + double buffering): every state mutation
+ * calls markDirty(); a fixed-rate tick commits at most once per frame
+ * when state actually changed. The gate guarantees:
+ *
+ *   1. Animation-driven repaints (spinner, elapsed timer) happen every
+ *      frame regardless of whether stdin produced an event. The previous
+ *      design had multiple silent-drop paths inside the renderer
+ *      (renderThrottle / paste suppression / mode early-return); when ANY
+ *      of those flagged on, the screen froze until a keystroke fired.
+ *
+ *   2. State mutations are batched within a frame. Setting mode +
+ *      activity + status in the same JS turn results in ONE commit, not
+ *      three.
+ *
+ *   3. Re-entrant commits are impossible — the gate is locked while a
+ *      commit is in flight.
+ *
+ *   4. A best-effort defer hook (canCommitNow) lets the renderer ask the
+ *      gate to wait when an overlay rewrite would be unsafe (e.g.
+ *      mid-bracketed-paste). But deferral is hard-bounded: past
+ *      maxDeferMs the gate force-commits, so a stuck flag can never
+ *      freeze the UI again.
+ *
+ * This is purely additive: existing inline render calls (renderPrompt)
+ * keep working. The gate's tick is the safety net that ensures the
+ * screen stays in sync with state even when those inline calls early-
+ * return for reasons that wouldn't survive scrutiny.
+ */
+export interface RenderGateOptions {
+    /** Target frame rate. Claude Code's frame budget is ~30fps. */
+    fps?: number;
+    /** Run a single commit pass; called only when dirty. */
+    commit: () => void;
+    /**
+     * Optional pre-commit gate. Returning false defers this frame's
+     * commit. The gate enforces a hard upper bound on consecutive defers
+     * (maxDeferMs) so a stuck precondition can never freeze the UI.
+     */
+    canCommitNow?: () => boolean;
+    /** Hard upper bound on consecutive deferrals (default 1500 ms). */
+    maxDeferMs?: number;
+}
+export declare class RenderGate {
+    private dirty;
+    private rendering;
+    private readonly targetFrameMs;
+    private interval;
+    private commitCount;
+    private skipCount;
+    private forceCommitCount;
+    private deferStartedAt;
+    private readonly commitFn;
+    private readonly canCommitNow;
+    private readonly maxDeferMs;
+    private disposed;
+    constructor(opts: RenderGateOptions);
+    /** Start the frame-rate tick. Idempotent. */
+    start(): void;
+    /** Stop the tick. Safe to call repeatedly. */
+    stop(): void;
+    /** Mark state dirty. The next tick (or a flush()) will commit once. */
+    markDirty(): void;
+    /**
+     * Synchronous force-commit, ignoring deferral and the dirty flag.
+     * Use sparingly — for transitions where the next thing to happen
+     * (e.g. clearing the screen, reading user input) needs the new state
+     * already on the wire.
+     */
+    flush(): void;
+    private tick;
+    dispose(): void;
+    /** Telemetry — useful for debugging stuck-state issues. */
+    stats(): {
+        commitCount: number;
+        skipCount: number;
+        forceCommitCount: number;
+        dirty: boolean;
+    };
+}
+//# sourceMappingURL=RenderGate.d.ts.map

package/dist/ui/RenderGate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RenderGate.d.ts","sourceRoot":"","sources":["../../src/ui/RenderGate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC;IAC7B,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAa;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyB;IACtD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAS;gBAEb,IAAI,EAAE,iBAAiB;IAOnC,6CAA6C;IAC7C,KAAK,IAAI,IAAI;IAOb,8CAA8C;IAC9C,IAAI,IAAI,IAAI;IAOZ,uEAAuE;IACvE,SAAS,IAAI,IAAI;IAIjB;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAab,OAAO,CAAC,IAAI;IAgCZ,OAAO,IAAI,IAAI;IAKf,2DAA2D;IAC3D,KAAK,IAAI;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE;CAQ9F"}