agent-world 0.13.0 → 0.15.0

package/dist/core/web-fetch-tool.js

@@ -0,0 +1,491 @@
+/**
+ * Web Fetch Tool - Lightweight web retrieval with markdown normalization.
+ *
+ * Features:
+ * - Built-in `web_fetch` tool definition for world toolsets
+ * - URL validation with http/https scheme enforcement
+ * - Basic SSRF safeguards for loopback/private/link-local targets
+ * - Lightweight SPA bootstrap-data extraction from HTML script payloads
+ * - Markdown conversion via Turndown + GFM plugin
+ *
+ * Implementation Notes:
+ * - Uses native fetch in Node runtime; no browser automation dependencies
+ * - Does not execute page JavaScript; instead extracts embedded JSON state when available
+ * - Returns deterministic JSON string payloads for downstream tool consumers
+ * - Applies timeout and output-size bounds with explicit truncation metadata
+ *
+ * Recent Changes:
+ * - 2026-03-12: Restored private-target gating in the main execute path so blocked hosts require explicit approval before any network fetch starts.
+ * - 2026-03-12: Shared tool approval flow now persists durable approval prompt/resolution messages for replay-safe local/private access denials.
+ * - 2026-03-12: Removed permission level gating — web_fetch is now allowed at all levels (read/ask/auto), like read_file.
+ * - 2026-03-06: Removed `world.currentChatId` fallback from local/private access approvals; HITL approval now requires explicit `context.chatId`.
+ * - 2026-03-05: Added deterministic timeout-error mapping (`timeout_error`) for aborted fetches caused by per-request timeout limits.
+ * - 2026-03-05: Switched timeout/output bounds constants to shared reliability config.
+ * - 2026-02-28: Initial implementation of fetch-only web retrieval with Turndown conversion and SPA JSON heuristics.
+ */
+/// <reference path="./globals.d.ts" />
+import { lookup as dnsLookup } from 'dns/promises';
+import { isIP } from 'net';
+import TurndownService from 'turndown';
+import { gfm } from 'turndown-plugin-gfm';
+import { requestToolApproval } from './tool-approval.js';
+import { RELIABILITY_CONFIG } from './reliability-config.js';
+const DEFAULT_TIMEOUT_MS = RELIABILITY_CONFIG.webFetch.defaultTimeoutMs;
+const MAX_TIMEOUT_MS = RELIABILITY_CONFIG.webFetch.maxTimeoutMs;
+const DEFAULT_MAX_CHARS = RELIABILITY_CONFIG.webFetch.defaultMaxChars;
+const MAX_MAX_CHARS = RELIABILITY_CONFIG.webFetch.maxMaxChars;
+const MIN_TIMEOUT_MS = RELIABILITY_CONFIG.webFetch.minTimeoutMs;
+const LOCAL_APPROVE_OPTION = 'yes';
+const LOCAL_DENY_OPTION = 'no';
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+function toErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isAbortError(error) {
+    if (!error)
+        return false;
+    if (error instanceof DOMException && error.name === 'AbortError')
+        return true;
+    if (error instanceof Error && error.name === 'AbortError')
+        return true;
+    const message = toErrorMessage(error).toLowerCase();
+    return message.includes('aborted');
+}
+function parseUrlOrThrow(urlValue) {
+    if (typeof urlValue !== 'string' || !urlValue.trim()) {
+        throw new Error('invalid_url: url is required');
+    }
+    let parsed;
+    try {
+        parsed = new URL(urlValue.trim());
+    }
+    catch {
+        throw new Error('invalid_url: malformed URL');
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error('unsupported_scheme: only http/https URLs are allowed');
+    }
+    return parsed;
+}
+function isBlockedHostname(hostname) {
+    const normalized = hostname.trim().toLowerCase();
+    if (!normalized)
+        return true;
+    if (normalized === 'localhost' || normalized.endsWith('.localhost')) {
+        return true;
+    }
+    if (normalized === '0.0.0.0' || normalized === '::' || normalized === '[::]') {
+        return true;
+    }
+    if (normalized.endsWith('.local') || normalized.endsWith('.internal')) {
+        return true;
+    }
+    return false;
+}
+function isPrivateIpv4(ip) {
+    const parts = ip.split('.').map((part) => Number(part));
+    if (parts.length !== 4 || parts.some((part) => Number.isNaN(part))) {
+        return true;
+    }
+    if (parts[0] === 10)
+        return true;
+    if (parts[0] === 127)
+        return true;
+    if (parts[0] === 0)
+        return true;
+    if (parts[0] === 169 && parts[1] === 254)
+        return true;
+    if (parts[0] === 172 && parts[1] >= 16 && parts[1] <= 31)
+        return true;
+    if (parts[0] === 192 && parts[1] === 168)
+        return true;
+    return false;
+}
+function isPrivateIpv6(ip) {
+    const normalized = ip.toLowerCase();
+    if (normalized === '::1')
+        return true;
+    if (normalized.startsWith('fc') || normalized.startsWith('fd'))
+        return true;
+    if (normalized.startsWith('fe80:'))
+        return true;
+    return false;
+}
+async function getTargetBlockReason(url) {
+    if (isBlockedHostname(url.hostname)) {
+        return 'local/private hostnames are not allowed';
+    }
+    const hostname = url.hostname.replace(/^\[|\]$/g, '');
+    const ipVersion = isIP(hostname);
+    if (ipVersion === 4 && isPrivateIpv4(hostname)) {
+        return 'private network targets are not allowed';
+    }
+    if (ipVersion === 6 && isPrivateIpv6(hostname)) {
+        return 'private network targets are not allowed';
+    }
+    if (ipVersion !== 0) {
+        return null;
+    }
+    try {
+        const resolved = await dnsLookup(hostname, { all: true });
+        for (const entry of resolved) {
+            if ((entry.family === 4 && isPrivateIpv4(entry.address)) || (entry.family === 6 && isPrivateIpv6(entry.address))) {
+                return 'hostname resolved to a private network address';
+            }
+        }
+    }
+    catch (error) {
+        // DNS lookup can fail on transient infra issues; keep behavior permissive for public domains.
+    }
+    return null;
+}
+async function requestLocalAccessApproval(options) {
+    const resolution = await requestToolApproval({
+        world: options.world,
+        title: 'Allow local/private web_fetch access?',
+        message: [
+            `web_fetch requested URL: ${options.url.toString()}`,
+            `Blocked by default because: ${options.reason}`,
+            'Allow this request to proceed?',
+        ].join('\n'),
+        chatId: options.chatId,
+        toolCallId: options.toolCallId,
+        defaultOptionId: LOCAL_DENY_OPTION,
+        options: [
+            { id: LOCAL_APPROVE_OPTION, label: 'Yes', description: 'Allow this local/private fetch request.' },
+            { id: LOCAL_DENY_OPTION, label: 'No', description: 'Keep blocking this request.' },
+        ],
+        approvedOptionIds: [LOCAL_APPROVE_OPTION],
+        metadata: {
+            tool: 'web_fetch',
+            url: options.url.toString(),
+            blockedReason: options.reason,
+            ...(typeof options.toolCallId === 'string' && options.toolCallId.trim()
+                ? { toolCallId: options.toolCallId.trim() }
+                : {}),
+        },
+        agentName: options.agentName || null,
+        messages: options.messages,
+    });
+    return {
+        approved: resolution.approved,
+        reason: resolution.reason,
+    };
+}
+function decodeHtmlEntities(value) {
+    return value
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&amp;/g, '&');
+}
+function extractTitle(html) {
+    const match = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+    if (!match)
+        return null;
+    const title = decodeHtmlEntities(match[1].replace(/\s+/g, ' ').trim());
+    return title || null;
+}
+function stripNoiseHtml(html) {
+    return html
+        .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, '')
+        .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, '')
+        .replace(/<noscript\b[^>]*>[\s\S]*?<\/noscript>/gi, '')
+        .replace(/<svg\b[^>]*>[\s\S]*?<\/svg>/gi, '')
+        .replace(/<!--([\s\S]*?)-->/g, '');
+}
+function extractTextBodyFromHtml(html) {
+    const bodyMatch = html.match(/<body\b[^>]*>([\s\S]*?)<\/body>/i);
+    const source = bodyMatch ? bodyMatch[1] : html;
+    const withoutTags = source
+        .replace(/<\/(p|div|section|article|h[1-6]|li|tr|blockquote)>/gi, '\n')
+        .replace(/<br\s*\/?\s*>/gi, '\n')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/\s+\n/g, '\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .replace(/[ \t]{2,}/g, ' ')
+        .trim();
+    return decodeHtmlEntities(withoutTags);
+}
+function toSafeJsonSnippet(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+    const normalized = JSON.stringify(parsed, null, 2);
+    return normalized.length > 12000 ? `${normalized.slice(0, 12000)}\n...` : normalized;
+}
+function extractSpaBootstrapJson(html) {
+    const snippets = [];
+    const nextDataMatch = html.match(/<script[^>]*id=["']__NEXT_DATA__["'][^>]*>([\s\S]*?)<\/script>/i);
+    const nextData = nextDataMatch ? toSafeJsonSnippet(nextDataMatch[1]) : null;
+    if (nextData) {
+        snippets.push({ label: '__NEXT_DATA__', content: nextData });
+    }
+    const nuxtMatch = html.match(/<script[^>]*>\s*window\.__NUXT__\s*=\s*([\s\S]*?)<\/script>/i);
+    const nuxtData = nuxtMatch ? toSafeJsonSnippet(nuxtMatch[1].replace(/;\s*$/, '')) : null;
+    if (nuxtData) {
+        snippets.push({ label: 'window.__NUXT__', content: nuxtData });
+    }
+    const initialStateMatch = html.match(/<script[^>]*>\s*window\.__INITIAL_STATE__\s*=\s*([\s\S]*?)<\/script>/i);
+    const initialState = initialStateMatch ? toSafeJsonSnippet(initialStateMatch[1].replace(/;\s*$/, '')) : null;
+    if (initialState) {
+        snippets.push({ label: 'window.__INITIAL_STATE__', content: initialState });
+    }
+    return snippets;
+}
+function createTurndown(options) {
+    const service = new TurndownService({
+        headingStyle: 'atx',
+        codeBlockStyle: 'fenced',
+        bulletListMarker: '-',
+        emDelimiter: '_',
+        strongDelimiter: '**',
+        linkStyle: 'inlined',
+    });
+    service.use(gfm);
+    if (!options.includeLinks) {
+        service.addRule('stripLinks', {
+            filter: 'a',
+            replacement: (_content, node) => (node.textContent || '').trim(),
+        });
+    }
+    if (!options.includeImages) {
+        service.addRule('stripImages', {
+            filter: 'img',
+            replacement: () => '',
+        });
+    }
+    return service;
+}
+function applySizeLimit(markdown, maxChars) {
+    if (markdown.length <= maxChars) {
+        return { markdown, truncated: false };
+    }
+    return {
+        markdown: `${markdown.slice(0, maxChars)}\n\n...\n`,
+        truncated: true,
+    };
+}
+function buildUnsupportedResponse(url, response, timingMs) {
+    const result = {
+        url: url.toString(),
+        resolvedUrl: response.url || url.toString(),
+        status: response.status,
+        ok: response.ok,
+        contentType: response.headers.get('content-type'),
+        title: null,
+        mode: 'unsupported',
+        markdown: '',
+        limitationReason: 'unsupported_content_type',
+        truncated: false,
+        timingMs,
+    };
+    return JSON.stringify(result, null, 2);
+}
+async function executeWebFetch(args, context) {
+    const startedAt = Date.now();
+    const activeTimeoutMs = clamp(Number(args.timeoutMs ?? DEFAULT_TIMEOUT_MS), MIN_TIMEOUT_MS, MAX_TIMEOUT_MS);
+    let timedOut = false;
+    // web_fetch is allowed at all permission levels (read/ask/auto), like read_file.
+    try {
+        const target = parseUrlOrThrow(args.url);
+        const blockReason = await getTargetBlockReason(target);
+        if (blockReason) {
+            const world = context?.world;
+            const worldId = String(world?.id || '').trim();
+            if (!world || !worldId) {
+                throw new Error(`blocked_target: ${blockReason}`);
+            }
+            const chatId = typeof context?.chatId === 'string' && context.chatId.trim()
+                ? context.chatId.trim()
+                : null;
+            if (!chatId) {
+                throw new Error('blocked_target: local/private access approval requires an explicit chatId');
+            }
+            const approval = await requestLocalAccessApproval({
+                world,
+                url: target,
+                reason: blockReason,
+                chatId,
+                toolCallId: context?.toolCallId,
+                agentName: context?.agentName || null,
+                messages: context?.messages,
+            });
+            if (!approval.approved) {
+                if (approval.reason === 'timeout') {
+                    throw new Error('blocked_target: local/private access approval timed out');
+                }
+                throw new Error('blocked_target: local/private access denied');
+            }
+        }
+        const timeoutMs = activeTimeoutMs;
+        const maxChars = clamp(Number(args.maxChars ?? DEFAULT_MAX_CHARS), 2000, MAX_MAX_CHARS);
+        const includeLinks = args.includeLinks !== false;
+        const includeImages = args.includeImages === true;
+        const controller = new AbortController();
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeoutMs);
+        let response;
+        try {
+            response = await fetch(target.toString(), {
+                redirect: 'follow',
+                signal: controller.signal,
+                headers: {
+                    'user-agent': 'agent-world-web-fetch/1.0',
+                    accept: 'text/html,application/json,text/plain;q=0.9,*/*;q=0.8',
+                },
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const timingMs = Date.now() - startedAt;
+        const contentTypeHeader = response.headers.get('content-type');
+        const contentType = contentTypeHeader ? contentTypeHeader.toLowerCase() : '';
+        if (!response.ok) {
+            throw new Error(`http_error: ${response.status} ${response.statusText || 'request failed'}`);
+        }
+        if (!(contentType.includes('text/html') || contentType.includes('text/plain') || contentType.includes('application/json') || contentType === '')) {
+            return buildUnsupportedResponse(target, response, timingMs);
+        }
+        const payload = await response.text();
+        if (contentType.includes('application/json')) {
+            const jsonSnippet = toSafeJsonSnippet(payload) ?? payload.slice(0, 12000);
+            const markdown = ['# JSON Response', '```json', jsonSnippet, '```'].join('\n');
+            const limited = applySizeLimit(markdown, maxChars);
+            const result = {
+                url: target.toString(),
+                resolvedUrl: response.url || target.toString(),
+                status: response.status,
+                ok: response.ok,
+                contentType: contentTypeHeader,
+                title: null,
+                mode: 'json',
+                markdown: limited.markdown,
+                truncated: limited.truncated,
+                timingMs,
+            };
+            return JSON.stringify(result, null, 2);
+        }
+        if (contentType.includes('text/plain')) {
+            const markdown = ['```text', payload, '```'].join('\n');
+            const limited = applySizeLimit(markdown, maxChars);
+            const result = {
+                url: target.toString(),
+                resolvedUrl: response.url || target.toString(),
+                status: response.status,
+                ok: response.ok,
+                contentType: contentTypeHeader,
+                title: null,
+                mode: 'text',
+                markdown: limited.markdown,
+                truncated: limited.truncated,
+                timingMs,
+            };
+            return JSON.stringify(result, null, 2);
+        }
+        const title = extractTitle(payload);
+        const bootstrapSnippets = extractSpaBootstrapJson(payload);
+        const cleanedHtml = stripNoiseHtml(payload);
+        const turndown = createTurndown({ includeLinks, includeImages });
+        const contentMarkdown = turndown.turndown(cleanedHtml).trim();
+        const textBody = extractTextBodyFromHtml(cleanedHtml);
+        const sections = [];
+        if (title) {
+            sections.push(`# ${title}`);
+        }
+        if (contentMarkdown) {
+            sections.push(contentMarkdown);
+        }
+        if (bootstrapSnippets.length > 0) {
+            sections.push('## SPA Bootstrap Data');
+            for (const snippet of bootstrapSnippets) {
+                sections.push(`### ${snippet.label}`);
+                sections.push('```json');
+                sections.push(snippet.content);
+                sections.push('```');
+            }
+        }
+        let limitationReason;
+        let mode = 'html';
+        if (!contentMarkdown || contentMarkdown.length < 120) {
+            if (bootstrapSnippets.length > 0) {
+                mode = 'spa-data';
+            }
+            else if (textBody.length < 120) {
+                limitationReason = 'client_side_rendering_likely_no_bootstrap_data_found';
+            }
+        }
+        if (sections.length === 0) {
+            sections.push(textBody || 'No extractable text content found.');
+        }
+        const combined = sections.join('\n\n').trim();
+        const limited = applySizeLimit(combined, maxChars);
+        const result = {
+            url: target.toString(),
+            resolvedUrl: response.url || target.toString(),
+            status: response.status,
+            ok: response.ok,
+            contentType: contentTypeHeader,
+            title,
+            mode,
+            markdown: limited.markdown,
+            limitationReason,
+            truncated: limited.truncated,
+            timingMs,
+        };
+        return JSON.stringify(result, null, 2);
+    }
+    catch (error) {
+        if (timedOut || isAbortError(error)) {
+            return `Error: web_fetch failed - timeout_error: request exceeded ${activeTimeoutMs}ms`;
+        }
+        const message = toErrorMessage(error);
+        return `Error: web_fetch failed - ${message}`;
+    }
+}
+export function createWebFetchToolDefinition() {
+    return {
+        description: 'Fetch a URL and convert response content to markdown. Supports lightweight SPA data extraction from embedded JSON state without running a browser renderer.',
+        parameters: {
+            type: 'object',
+            properties: {
+                url: {
+                    type: 'string',
+                    description: 'Target URL to fetch. Only http/https schemes are allowed.',
+                },
+                timeoutMs: {
+                    type: 'number',
+                    description: `Request timeout in milliseconds (default: ${DEFAULT_TIMEOUT_MS}, max: ${MAX_TIMEOUT_MS}).`,
+                },
+                maxChars: {
+                    type: 'number',
+                    description: `Maximum markdown output characters (default: ${DEFAULT_MAX_CHARS}, max: ${MAX_MAX_CHARS}).`,
+                },
+                includeLinks: {
+                    type: 'boolean',
+                    description: 'When false, link URLs are stripped and only anchor text is kept (default: true).',
+                },
+                includeImages: {
+                    type: 'boolean',
+                    description: 'When true, image markdown is preserved (default: false).',
+                },
+            },
+            required: ['url'],
+            additionalProperties: false,
+        },
+        execute: async (args, _sequenceId, _parentToolCall, context) => executeWebFetch(args, context),
+    };
+}

package/dist/core/web-fetch-tool.js.map

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

package/dist/core/world-registry.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Core World Runtime Registry
+ *
+ * Purpose:
+ * - Provide storage-aware runtime tracking for active world runtimes.
+ * - Support idempotent runtime start with reference-counted consumers.
+ * - Offer deterministic stop/release behavior with optional refresh support.
+ *
+ * Key Features:
+ * - Composite runtime key: storageType + storagePath + worldId.
+ * - In-flight start deduplication per runtime key.
+ * - Consumer ref counting with last-release shutdown.
+ * - Runtime diagnostics snapshots for inspection.
+ *
+ * Implementation Notes:
+ * - The registry is runtime-process local and does not coordinate across processes.
+ * - Storage context defaults are sourced from environment when not provided.
+ *
+ * Recent Changes:
+ * - 2026-03-04: Runtime refresh now updates the registry's `world` reference.
+ *   - Prevents callers from receiving stale pre-refresh world instances.
+ * - 2026-03-03: Initial runtime registry implementation for canonical world runtime ownership.
+ */
+type StorageType = 'file' | 'sqlite' | 'memory';
+export interface WorldRuntimeStorageContext {
+    storageType: StorageType;
+    storagePath: string;
+}
+export interface ManagedWorldRuntime<TWorld> {
+    world: TWorld;
+    stop: () => Promise<void>;
+    refresh?: () => Promise<TWorld | void>;
+}
+export interface StartWorldRuntimeParams<TWorld> {
+    worldId: string;
+    consumerId: string;
+    storageType?: StorageType;
+    storagePath?: string;
+    createRuntime: () => Promise<ManagedWorldRuntime<TWorld>>;
+}
+export interface StartedWorldRuntime<TWorld> {
+    runtimeKey: string;
+    worldId: string;
+    storageType: StorageType;
+    storagePath: string;
+    world: TWorld;
+    refCount: number;
+    release: () => Promise<void>;
+    refresh: () => Promise<void>;
+}
+export interface WorldRuntimeSnapshot {
+    runtimeKey: string;
+    worldId: string;
+    storageType: StorageType;
+    storagePath: string;
+    startedAt: string;
+    refCount: number;
+    consumers: string[];
+}
+export declare function createWorldRuntimeKey(worldId: string, context: WorldRuntimeStorageContext): string;
+export declare function startWorldRuntime<TWorld>(params: StartWorldRuntimeParams<TWorld>): Promise<StartedWorldRuntime<TWorld>>;
+export declare function releaseWorldRuntime(params: {
+    runtimeKey?: string;
+    worldId?: string;
+    storageType?: StorageType;
+    storagePath?: string;
+    consumerId: string;
+}): Promise<void>;
+export declare function getWorldRuntime<TWorld>(params: {
+    worldId: string;
+    storageType?: StorageType;
+    storagePath?: string;
+}): StartedWorldRuntime<TWorld> | null;
+export declare function getWorldRuntimeByKey<TWorld>(runtimeKey: string): StartedWorldRuntime<TWorld> | null;
+export declare function listWorldRuntimeSnapshots(): WorldRuntimeSnapshot[];
+export declare function stopWorldRuntime(runtimeKey: string): Promise<void>;
+/**
+ * Stop all active world runtimes with the given worldId regardless of storage
+ * context. Used when a world is deleted so subsequent subscriptions do not
+ * reuse a stale runtime that was loaded for the previous incarnation.
+ */
+export declare function stopWorldRuntimesByWorldId(worldId: string): Promise<void>;
+export declare function stopAllWorldRuntimes(): Promise<void>;
+export {};

package/dist/core/world-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-registry.d.ts","sourceRoot":"","sources":["../../core/world-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AASH,KAAK,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEhD,MAAM,WAAW,0BAA0B;IACzC,WAAW,EAAE,WAAW,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB,CAAC,MAAM;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,uBAAuB,CAAC,MAAM;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,OAAO,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC;CAC3D;AAED,MAAM,WAAW,mBAAmB,CAAC,MAAM;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,WAAW,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,WAAW,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAiCD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,0BAA0B,GAAG,MAAM,CAIlG;AA2DD,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,uBAAuB,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAyD7H;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BhB;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,mBAAmB,CAAC,MAAM,CAAC,GAAG,IAAI,CAIrC;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,mBAAmB,CAAC,MAAM,CAAC,GAAG,IAAI,CAiBnG;AAED,wBAAgB,yBAAyB,IAAI,oBAAoB,EAAE,CAUlE;AAED,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMxE;AAED;;;;GAIG;AACH,wBAAsB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAY/E;AAED,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAK1D"}