@massa-ai/core 1.2.1

package/dist/services/executor/intent-search.js

@@ -0,0 +1,195 @@
+/**
+ * Intent-driven progressive disclosure for execution output.
+ *
+ * When `execute` / `execute_file` output exceeds a threshold, returning it
+ * verbatim floods the agent's context window. Instead, when the caller passes
+ * an `intent` query, we:
+ *   1. chunk the output into sections (reuse the existing smart-chunker),
+ *   2. build a tiny IN-MEMORY keyword index (TF + title boost) over those
+ *      sections,
+ *   3. return ONLY the sections matching the intent query + a vocabulary-hint
+ *      list (top distinctive terms).
+ *
+ * This mirrors context-mode `intentSearch` (server.ts:1982) in shape but is
+ * self-contained — it does NOT touch the persistent FTS5/PG keyword store, so
+ * it can never OOM the shared e2e index or trigger a full-repo index. If
+ * `intent` is absent or output is below threshold, the output is returned
+ * verbatim (no indexing at all).
+ */
+import { smartChunk } from "../search/smart-chunker.js";
+/** Output ≥ this many bytes triggers intent search (when intent is set). */
+export const INTENT_SEARCH_THRESHOLD = 5_000; // ~80-100 lines
+/** Stopwords excluded from both indexing and vocabulary hints. */
+const STOPWORDS = new Set([
+    "the", "a", "an", "and", "or", "but", "if", "then", "else", "for", "of",
+    "to", "in", "on", "at", "by", "with", "from", "is", "are", "was", "were",
+    "be", "been", "being", "this", "that", "these", "those", "it", "its",
+    "as", "at", "use", "using", "used", "into", "not", "no", "yes", "true",
+    "false", "null", "none", "undefined", "function", "return", "var", "let",
+    "const", "import", "export", "class", "def", "func", "fn",
+]);
+/**
+ * Return the first line of a chunk's content that is NOT a smart-chunker
+ * metadata header (`// File:` / `// Section:`). Falls back to the first line
+ * if every line is a header.
+ */
+function firstContentLine(content) {
+    const lines = content.split("\n");
+    for (const line of lines) {
+        const t = line.trimStart();
+        if (!t)
+            continue;
+        if (t.startsWith("// File:") || t.startsWith("// Section:"))
+            continue;
+        return line;
+    }
+    return lines[0] ?? "";
+}
+/** Tokenize for indexing/querying: lowercase alphanumeric words ≥3 chars. */
+function tokenize(text) {
+    const matches = text.toLowerCase().match(/[a-z0-9_]{3,}/g) ?? [];
+    return matches.filter((w) => !STOPWORDS.has(w));
+}
+/**
+ * Build an in-memory index over the chunked output and rank sections against
+ * the intent query. Pure function — no side effects, no persistence.
+ */
+function searchSections(output, intent, maxResults) {
+    // Chunk as if it were a .txt file → fixed-size fallback chunker.
+    const chunks = smartChunk(output, "output.txt");
+    const sections = chunks.map((chunk) => {
+        const tokens = tokenize(chunk.content);
+        const termFreq = new Map();
+        let maxFreq = 0;
+        for (const t of tokens) {
+            const c = (termFreq.get(t) ?? 0) + 1;
+            termFreq.set(t, c);
+            if (c > maxFreq)
+                maxFreq = c;
+        }
+        return { chunk, termFreq, maxFreq: Math.max(1, maxFreq) };
+    });
+    const queryTerms = tokenize(intent);
+    if (queryTerms.length === 0) {
+        return { sections, results: sections.slice(0, maxResults) };
+    }
+    // Score each section by sum of normalized term frequencies for query terms.
+    // A title/label match adds a boost (labels carry high semantic signal).
+    const scored = sections
+        .map((s) => {
+        let score = 0;
+        for (const qt of queryTerms) {
+            const tf = s.termFreq.get(qt);
+            if (tf)
+                score += tf / s.maxFreq;
+        }
+        if (s.chunk.label) {
+            const labelTokens = new Set(tokenize(s.chunk.label));
+            for (const qt of queryTerms) {
+                if (labelTokens.has(qt))
+                    score += 0.5;
+            }
+        }
+        return { s, score };
+    })
+        .filter((x) => x.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, maxResults)
+        .map((x) => x.s);
+    return { sections, results: scored };
+}
+/**
+ * Extract the top distinctive terms across all sections (vocabulary hints for
+ * the agent). A term is "distinctive" when it appears in few sections but is
+ * frequent where it appears (high-ish IDF-like signal). Simple, bounded.
+ */
+function distinctiveTerms(sections, limit) {
+    const docFreq = new Map(); // term → # sections containing it
+    for (const s of sections) {
+        for (const term of s.termFreq.keys()) {
+            docFreq.set(term, (docFreq.get(term) ?? 0) + 1);
+        }
+    }
+    const total = sections.length || 1;
+    // Score = total occurrences / docFreq (terms concentrated in few docs rank
+    // higher). Cap docFreq divisor at 1 so we never divide by zero.
+    const scored = [];
+    const termTotals = new Map();
+    for (const s of sections) {
+        for (const [term, freq] of s.termFreq) {
+            termTotals.set(term, (termTotals.get(term) ?? 0) + freq);
+        }
+    }
+    for (const [term, total2] of termTotals) {
+        const df = docFreq.get(term) ?? 1;
+        scored.push({ term, score: total2 / Math.max(1, df) });
+    }
+    return scored
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit)
+        .map((x) => x.term);
+}
+/**
+ * Run intent search on `output` for `intent`. Returns the structured result;
+ * the caller decides how to render it.
+ *
+ * Returns `searched: false` (and empty arrays) when the output is too small
+ * or no intent was provided — in that case the caller returns output verbatim.
+ */
+export function intentSearch(output, intent, maxResults = 5) {
+    const totalBytes = Buffer.byteLength(output);
+    const totalLines = output.split("\n").length;
+    if (!intent || intent.trim().length === 0 || totalBytes < INTENT_SEARCH_THRESHOLD) {
+        return {
+            searched: false,
+            totalBytes,
+            totalLines,
+            matchedSections: [],
+            vocabularyHints: [],
+        };
+    }
+    const { sections, results } = searchSections(output, intent, maxResults);
+    const matchedSections = results.map((s) => ({
+        label: s.chunk.label ?? `lines ${s.chunk.lineStart}-${s.chunk.lineEnd}`,
+        lineStart: s.chunk.lineStart,
+        lineEnd: s.chunk.lineEnd,
+        // smart-chunker prepends `// File:` / `// Section:` context lines to each
+        // chunk's content; skip those so the preview shows real content, not the
+        // chunker's own metadata header.
+        preview: firstContentLine(s.chunk.content).slice(0, 120),
+    }));
+    const vocabularyHints = distinctiveTerms(sections, 10);
+    return {
+        searched: true,
+        totalBytes,
+        totalLines,
+        matchedSections,
+        vocabularyHints,
+    };
+}
+/**
+ * Render an IntentSearchResult as a human-readable summary string (the shape
+ * agents consume when intent search fires). Mirrors the context-mode layout.
+ */
+export function renderIntentResult(result, intent) {
+    if (!result.searched)
+        return "";
+    const lines = [];
+    lines.push(`Output trimmed via intent "${intent}" (${result.totalLines} lines, ${(result.totalBytes / 1024).toFixed(1)}KB).`);
+    if (result.matchedSections.length === 0) {
+        lines.push(`No sections matched intent "${intent}".`);
+    }
+    else {
+        lines.push(`${result.matchedSections.length} sections matched:`);
+        lines.push("");
+        for (const m of result.matchedSections) {
+            lines.push(`  - ${m.label} (L${m.lineStart}-${m.lineEnd}): ${m.preview}`);
+        }
+    }
+    if (result.vocabularyHints.length > 0) {
+        lines.push("");
+        lines.push(`Searchable terms: ${result.vocabularyHints.join(", ")}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=intent-search.js.map

package/dist/services/executor/intent-search.js.map

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

package/dist/services/executor/run-pool.d.ts

@@ -0,0 +1,53 @@
+/**
+ * runPool — generic in-flight-capped worker pool.
+ *
+ * Single concurrency primitive for the project: every "run N independent
+ * operations with at most M in flight" need routes here. Currently consumed
+ * by `batch_execute`; P2-T2 (web fetch + index) will reuse it.
+ *
+ * Design contract:
+ *   - Order-preserving: results[i] corresponds to jobs[i] regardless of
+ *     completion order. Implemented by writing into a fixed-index array.
+ *   - allSettled-shaped: one job throwing never strands its siblings. A job's
+ *     failure surfaces as a `rejected` entry, not a thrown promise.
+ *   - CPU-capped: `capByCpuCount` additionally clamps effective concurrency to
+ *     `os.cpus().length` for memory-pressure safety.
+ *   - Clamped to job count: requesting concurrency 8 for 3 jobs runs 3.
+ *   - STANDALONE: imports only `node:os`. Must NOT depend on executor or any
+ *     other massa-ai service so it stays a clean reusable export.
+ */
+/** A unit of work. `run()` is invoked exactly once per job. */
+export interface PoolJob<T> {
+    run(): Promise<T>;
+}
+export interface RunPoolOptions {
+    /** Hard concurrency cap (1-N). Auto-clamped to job count. */
+    concurrency: number;
+    /** Also clamp by `os.cpus().length`. Default false. */
+    capByCpuCount?: boolean;
+    /** Per-settled callback (progress / metrics). Optional. */
+    onSettled?: (idx: number, result: PromiseSettledResult<unknown>) => void;
+}
+export interface RunPoolResult<T> {
+    /** Per-index settled result, ordered by input index (NOT completion). */
+    settled: PromiseSettledResult<T>[];
+    /** Concurrency actually used after all caps applied. */
+    effectiveConcurrency: number;
+    /** True when effectiveConcurrency < requested concurrency. */
+    capped: boolean;
+}
+/**
+ * Run an array of jobs with bounded concurrency. Returns one settled result
+ * per input job, in input order.
+ *
+ * Implementation: a pool of `effectiveConcurrency` workers pulls the next
+ * index from a shared counter. Because each worker writes only to its claimed
+ * index, the output array is naturally order-preserving without sorting.
+ */
+export declare function runPool<T>(jobs: PoolJob<T>[], opts: RunPoolOptions): Promise<RunPoolResult<T>>;
+/**
+ * Convenience: extract only the fulfilled values, preserving order. Rejected
+ * entries are dropped (the caller already sees reasons via `settled`).
+ */
+export declare function fulfilledValues<T>(result: RunPoolResult<T>): T[];
+//# sourceMappingURL=run-pool.d.ts.map

package/dist/services/executor/run-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-pool.d.ts","sourceRoot":"","sources":["../../../src/services/executor/run-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,+DAA+D;AAC/D,MAAM,WAAW,OAAO,CAAC,CAAC;IACxB,GAAG,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;CAC1E;AAED,MAAM,WAAW,aAAa,CAAC,CAAC;IAC9B,yEAAyE;IACzE,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,EAAE,CAAC;IACnC,wDAAwD;IACxD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAC7B,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAClB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAoC3B;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GACvB,CAAC,EAAE,CAIL"}

package/dist/services/executor/run-pool.js

@@ -0,0 +1,71 @@
+/**
+ * runPool — generic in-flight-capped worker pool.
+ *
+ * Single concurrency primitive for the project: every "run N independent
+ * operations with at most M in flight" need routes here. Currently consumed
+ * by `batch_execute`; P2-T2 (web fetch + index) will reuse it.
+ *
+ * Design contract:
+ *   - Order-preserving: results[i] corresponds to jobs[i] regardless of
+ *     completion order. Implemented by writing into a fixed-index array.
+ *   - allSettled-shaped: one job throwing never strands its siblings. A job's
+ *     failure surfaces as a `rejected` entry, not a thrown promise.
+ *   - CPU-capped: `capByCpuCount` additionally clamps effective concurrency to
+ *     `os.cpus().length` for memory-pressure safety.
+ *   - Clamped to job count: requesting concurrency 8 for 3 jobs runs 3.
+ *   - STANDALONE: imports only `node:os`. Must NOT depend on executor or any
+ *     other massa-ai service so it stays a clean reusable export.
+ */
+import { cpus } from "node:os";
+/**
+ * Run an array of jobs with bounded concurrency. Returns one settled result
+ * per input job, in input order.
+ *
+ * Implementation: a pool of `effectiveConcurrency` workers pulls the next
+ * index from a shared counter. Because each worker writes only to its claimed
+ * index, the output array is naturally order-preserving without sorting.
+ */
+export async function runPool(jobs, opts) {
+    const { concurrency, capByCpuCount = false, onSettled } = opts;
+    if (jobs.length === 0) {
+        return { settled: [], effectiveConcurrency: 0, capped: false };
+    }
+    const requested = Math.max(1, Math.floor(concurrency));
+    const cpuCap = capByCpuCount ? Math.max(1, cpus().length) : requested;
+    const effectiveConcurrency = Math.min(requested, cpuCap, jobs.length);
+    const capped = effectiveConcurrency < requested;
+    const settled = new Array(jobs.length);
+    let nextIdx = 0;
+    async function worker() {
+        while (true) {
+            const idx = nextIdx++;
+            if (idx >= jobs.length)
+                return;
+            try {
+                const value = await jobs[idx].run();
+                settled[idx] = { status: "fulfilled", value };
+            }
+            catch (err) {
+                settled[idx] = { status: "rejected", reason: err };
+            }
+            onSettled?.(idx, settled[idx]);
+        }
+    }
+    const workers = [];
+    for (let w = 0; w < effectiveConcurrency; w++)
+        workers.push(worker());
+    // Belt-and-braces: workers already swallow their own errors, but
+    // allSettled guarantees no rejection escapes even if a worker throws.
+    await Promise.allSettled(workers);
+    return { settled, effectiveConcurrency, capped };
+}
+/**
+ * Convenience: extract only the fulfilled values, preserving order. Rejected
+ * entries are dropped (the caller already sees reasons via `settled`).
+ */
+export function fulfilledValues(result) {
+    return result.settled
+        .filter((r) => r.status === "fulfilled")
+        .map((r) => r.value);
+}
+//# sourceMappingURL=run-pool.js.map

package/dist/services/executor/run-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-pool.js","sourceRoot":"","sources":["../../../src/services/executor/run-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAyB/B;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,IAAkB,EAClB,IAAoB;IAEpB,MAAM,EAAE,WAAW,EAAE,aAAa,GAAG,KAAK,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAE/D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,oBAAoB,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACjE,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC;IACvD,MAAM,MAAM,GAAG,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACtE,MAAM,oBAAoB,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACtE,MAAM,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAAC;IAEhD,MAAM,OAAO,GAA8B,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAClE,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,KAAK,UAAU,MAAM;QACnB,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;YACtB,IAAI,GAAG,IAAI,IAAI,CAAC,MAAM;gBAAE,OAAO;YAC/B,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;gBACpC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;YAChD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;YACrD,CAAC;YACD,SAAS,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAoB,EAAE,CAAC;IACpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,oBAAoB,EAAE,CAAC,EAAE;QAAE,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IACtE,iEAAiE;IACjE,sEAAsE;IACtE,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAElC,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,EAAE,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAwB;IAExB,OAAO,MAAM,CAAC,OAAO;SAClB,MAAM,CAAC,CAAC,CAAC,EAAkC,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,WAAW,CAAC;SACvE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AACzB,CAAC"}

package/dist/services/executor/runtime.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Runtime detection — polyglot sandbox.
+ *
+ * Detects which language runtimes are installed on the host so the executor
+ * can pick the right interpreter/compiler per language. Rewritten fresh in TS
+ * (approach ported from context-mode `runtime.ts`); no code copied.
+ *
+ * Trust model: massa-ai is a LOCAL-DEV tool that runs user-supplied code on
+ * the host. Runtime detection here is best-effort and never escalates
+ * privilege — it only reports what `command -v` / `where` + a `--version`
+ * probe can see on PATH.
+ */
+export type Language = "javascript" | "typescript" | "python" | "shell" | "ruby" | "go" | "rust" | "php" | "perl" | "r";
+export interface RuntimeMap {
+    javascript: string | null;
+    typescript: string | null;
+    python: string | null;
+    shell: string;
+    ruby: string | null;
+    go: string | null;
+    rust: string | null;
+    php: string | null;
+    perl: string | null;
+    r: string | null;
+}
+export interface RuntimeInfo {
+    command: string;
+    available: boolean;
+    version: string;
+}
+/**
+ * Dependency seam so unit tests can mock the `which`-equivalent probe without
+ * spawning real shells. Production callers omit it.
+ */
+export interface DetectDeps {
+    commandExists?: (cmd: string) => boolean;
+    getVersion?: (cmd: string, args?: string[]) => string;
+}
+/**
+ * Default `command -v` / `where` probe. Returns true if the binary is on PATH.
+ * Kept deliberately cheap (no --version run) — availability for routing is
+ * enough; the executor itself surfaces real launch failures.
+ */
+export declare function commandExists(cmd: string): boolean;
+/**
+ * Stricter probe: requires `<cmd> --version` to exit 0. Filters out OS stubs
+ * (e.g. the Windows Store python alias that pops the Store instead of running).
+ */
+export declare function runnableExists(cmd: string, deps?: DetectDeps): boolean;
+/**
+ * Return the first line of `<cmd> --version` (or "unknown" if it can't be
+ * read within a short timeout). Exported so callers/tests can inspect versions.
+ */
+export declare function getVersion(cmd: string, args?: string[], deps?: DetectDeps): string;
+/**
+ * Detect all runtimes on the host. `shell` always resolves to a fallback
+ * (`sh` on POSIX, `cmd.exe` on Windows) even when nothing better is present,
+ * because a shell is the one runtime we can assume exists.
+ *
+ * `deps` is a test seam — production callers omit it.
+ */
+export declare function detectRuntimes(deps?: DetectDeps): RuntimeMap;
+/**
+ * Human-readable summary of detected runtimes (for diagnostics / tool output).
+ */
+export declare function getRuntimeSummary(runtimes: RuntimeMap): string;
+/**
+ * Languages that are actually runnable given the detected runtimes.
+ */
+export declare function getAvailableLanguages(runtimes: RuntimeMap): Language[];
+/**
+ * Resolve the spawn argv for a given language + temp script path. Throws a
+ * clear, actionable error when the language is unavailable (so the tool layer
+ * can surface it instead of an opaque ENOENT).
+ *
+ * Rust is special-cased with the sentinel `"__rust_compile_run__"` — the
+ * executor handles compile+run itself.
+ */
+export declare function buildCommand(runtimes: RuntimeMap, language: Language, filePath: string): string[];
+/** Temp-script file extension per language. */
+export declare const SCRIPT_EXT: Record<Language, string>;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/services/executor/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/services/executor/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,MAAM,QAAQ,GAChB,YAAY,GACZ,YAAY,GACZ,QAAQ,GACR,OAAO,GACP,MAAM,GACN,IAAI,GACJ,MAAM,GACN,KAAK,GACL,MAAM,GACN,GAAG,CAAC;AAER,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAID;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC;CACvD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAQlD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAST;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,MAAM,EAAkB,EAC9B,IAAI,CAAC,EAAE,UAAU,GAChB,MAAM,CA0BR;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,CAAC,EAAE,UAAU,GAAG,UAAU,CA2C5D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAiB9D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,UAAU,GAAG,QAAQ,EAAE,CAYtE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,UAAU,EACpB,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,MAAM,GACf,MAAM,EAAE,CA6DV;AAED,+CAA+C;AAC/C,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAW/C,CAAC"}