@massa-ai/core 1.2.1

package/dist/controllers/executor-controller.js

@@ -0,0 +1,229 @@
+/**
+ * Executor Controller — orchestration for execute / execute_file / batch_execute.
+ *
+ * Owns a single PolyglotExecutor instance and applies the intent progressive-
+ * disclosure pass (B3) on large outputs. The tool handlers are thin shims that
+ * delegate here; this layer composes the executor service + intent search.
+ *
+ * Trust model (re-stated because it is load-bearing): the executor runs
+ * USER-SUPPLIED code on the HOST as the current user. There is no OS-level
+ * sandbox. Timeouts, the env denylist, and execute_file's boundary/deny-glob
+ * guard are best-effort containment, NOT isolation.
+ */
+import { logger } from "@massa-ai/shared";
+import { cpus } from "node:os";
+import { PolyglotExecutor, intentSearch, renderIntentResult, DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS, runPool, } from "../services/executor/index.js";
+import { validateEnum } from "../tools/enum-validation.js";
+/** The 10 languages supported by the Polyglot executor (N6). */
+const EXECUTOR_LANGUAGES = [
+    "javascript",
+    "typescript",
+    "python",
+    "shell",
+    "ruby",
+    "go",
+    "rust",
+    "php",
+    "perl",
+    "r",
+];
+/**
+ * Hard cap on the number of commands a single batch_execute call may run.
+ * Without it, a 100k-command payload would spin up 100k temp dirs upfront
+ * (each shell command gets its own sandbox tmp dir) and exhaust /tmp / fds.
+ * 256 is generous for real gather passes (typically <50) while bounding abuse.
+ */
+const MAX_BATCH_COMMANDS = 256;
+/**
+ * Apply intent progressive disclosure to an ExecResult's stdout. When `intent`
+ * is set AND stdout exceeds the threshold, replace stdout with the trimmed
+ * intent summary + keep the raw output under a `truncated` field for audit.
+ * Otherwise return the result untouched.
+ */
+function applyIntent(result, intent) {
+    if (!intent || !result.stdout)
+        return result;
+    const ir = intentSearch(result.stdout, intent);
+    if (!ir.searched)
+        return result;
+    const rendered = renderIntentResult(ir, intent);
+    return {
+        ...result,
+        // Keep a bounded tail of the raw output so the agent isn't fully blind to
+        // the end of the run, but lead with the intent summary.
+        stdout: `${rendered}\n\n--- tail (last 512 chars) ---\n${result.stdout.slice(-512)}`,
+    };
+}
+export class ExecutorController {
+    static instance = null;
+    executor;
+    constructor(executor) {
+        this.executor = executor ?? new PolyglotExecutor();
+    }
+    static getInstance() {
+        if (!ExecutorController.instance) {
+            ExecutorController.instance = new ExecutorController();
+        }
+        return ExecutorController.instance;
+    }
+    /** For tests: reset the singleton (cleans up backgrounded processes). */
+    static resetInstance() {
+        ExecutorController.instance?.executor.cleanupBackgrounded();
+        ExecutorController.instance = null;
+    }
+    get runtimes() {
+        return this.executor.runtimes;
+    }
+    /** execute (ctx_execute). */
+    async execute(params) {
+        try {
+            const language = validateEnum("language", params.language, EXECUTOR_LANGUAGES);
+            const result = await this.executor.execute({
+                language,
+                code: params.code,
+                timeout: params.timeout,
+                background: params.background,
+                cwd: params.cwd,
+            });
+            const finalResult = applyIntent(result, params.intent);
+            const ok = !finalResult.timedOut && finalResult.exitCode === 0;
+            return {
+                success: ok,
+                data: {
+                    stdout: finalResult.stdout,
+                    stderr: finalResult.stderr,
+                    exitCode: finalResult.exitCode,
+                    timedOut: finalResult.timedOut,
+                    backgrounded: finalResult.backgrounded ?? false,
+                    command: finalResult.command,
+                    cwd: finalResult.cwd,
+                },
+            };
+        }
+        catch (error) {
+            logger.error("execute failed", error, {
+                language: params.language,
+            });
+            return {
+                success: false,
+                error: `execute failed: ${error.message}`,
+            };
+        }
+    }
+    /** execute_file (ctx_execute_file). */
+    async executeFile(params) {
+        try {
+            const language = validateEnum("language", params.language, EXECUTOR_LANGUAGES);
+            const result = await this.executor.executeFile({
+                path: params.path,
+                language,
+                code: params.code,
+                timeout: params.timeout,
+            });
+            // Boundary/deny-glob blocks come back as a result (not a throw) so the
+            // tool response stays success:false with a clear stderr.
+            const blocked = result.stderr?.startsWith("Blocked:");
+            if (blocked) {
+                return { success: false, error: result.stderr };
+            }
+            const finalResult = applyIntent(result, params.intent);
+            const ok = !finalResult.timedOut && finalResult.exitCode === 0;
+            return {
+                success: ok,
+                data: {
+                    stdout: finalResult.stdout,
+                    stderr: finalResult.stderr,
+                    exitCode: finalResult.exitCode,
+                    timedOut: finalResult.timedOut,
+                    command: finalResult.command,
+                    cwd: finalResult.cwd,
+                },
+            };
+        }
+        catch (error) {
+            logger.error("execute_file failed", error, {
+                path: params.path,
+                language: params.language,
+            });
+            return {
+                success: false,
+                error: `execute_file failed: ${error.message}`,
+            };
+        }
+    }
+    /**
+     * batch_execute (ctx_batch_execute) — run N shell commands via run-pool.
+     * Order is preserved (results[i] ↔ commands[i]); a failing command becomes a
+     * `rejected` entry, never aborting its siblings.
+     *
+     * Each command is itself run through the executor's `shell` language so it
+     * inherits the same timeout/env-denylist/byte-cap containment as `execute`.
+     */
+    async batchExecute(params) {
+        const { commands, concurrency, cwd, timeout } = params;
+        if (!Array.isArray(commands) || commands.length === 0) {
+            return { success: false, error: "commands must be a non-empty array." };
+        }
+        if (commands.length > MAX_BATCH_COMMANDS) {
+            return {
+                success: false,
+                error: `batch_execute accepts at most ${MAX_BATCH_COMMANDS} commands; received ${commands.length}. Split the batch or reduce the payload.`,
+            };
+        }
+        const effectiveConcurrency = concurrency && concurrency > 0 ? concurrency : Math.max(1, cpus().length);
+        const perTimeout = timeout ?? DEFAULT_TIMEOUT_MS;
+        try {
+            const poolResult = await runPool(commands.map((cmd) => ({
+                run: () => this.executor.execute({
+                    language: "shell",
+                    code: cmd,
+                    timeout: perTimeout,
+                    cwd,
+                }),
+            })), { concurrency: effectiveConcurrency });
+            const results = poolResult.settled.map((s, i) => {
+                if (s.status === "fulfilled") {
+                    const r = s.value;
+                    return {
+                        command: commands[i],
+                        stdout: r.stdout,
+                        stderr: r.stderr,
+                        exitCode: r.exitCode,
+                        timedOut: r.timedOut,
+                    };
+                }
+                return {
+                    command: commands[i],
+                    stdout: "",
+                    stderr: String(s.reason ?? "unknown error"),
+                    exitCode: null,
+                    timedOut: false,
+                };
+            });
+            const anyFailed = results.some((r) => r.exitCode !== 0 || r.timedOut);
+            // Auto-indexing of outputs (queries/query_scope) is a stub: the core
+            // value of this tool is parallel gather. A later task can index the
+            // combined stdout into the keyword/vector store if desired.
+            return {
+                success: !anyFailed,
+                data: {
+                    results,
+                    concurrency: poolResult.effectiveConcurrency,
+                    capped: poolResult.capped,
+                },
+            };
+        }
+        catch (error) {
+            logger.error("batch_execute failed", error);
+            return {
+                success: false,
+                error: `batch_execute failed: ${error.message}`,
+            };
+        }
+    }
+    /** Bound export for the controller layer. */
+    static get MAX_TIMEOUT_MS() {
+        return MAX_TIMEOUT_MS;
+    }
+}
+//# sourceMappingURL=executor-controller.js.map

package/dist/controllers/executor-controller.js.map

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

package/dist/controllers/graph-controller.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Graph Controller
+ *
+ * Orchestration layer for Symbol Graph traversal tools. Today it fronts
+ * trace_path (Phase 4 D2); future graph-walk tools (impact_analysis,
+ * architecture-map) land here too so they share seed-resolution and
+ * result-shaping logic.
+ *
+ * The controller keeps the tool handlers thin: input validation +
+ * result formatting live here, while the BFS traversal is owned by
+ * {@link TracePathService}.
+ */
+import type { TracePathResult, TraceDirection, TraceMode } from "../services/symbol/trace-path.js";
+import type { EdgeType } from "../services/symbol/symbol-graph.service.js";
+import type { ImpactAnalysisOptions, ImpactAnalysisResult, ImpactScope } from "../services/symbol/impact-analysis.js";
+import type { DefinitionLookupResult } from "../services/symbol/definition-lookup.js";
+import type { SymbolIdentityResolution } from "@massa-ai/shared";
+export interface TracePathInput {
+    projectId: string;
+    function_name?: string;
+    symbol?: string;
+    qualifiedName?: string;
+    direction?: TraceDirection;
+    mode?: TraceMode;
+    depth?: number;
+    include_tests?: boolean;
+    edge_types?: EdgeType[];
+}
+export interface TracePathOutput {
+    projectId: string;
+    symbol: string;
+    mode: TraceMode;
+    direction: TraceDirection;
+    edgeTypes: EdgeType[];
+    seeds: string[];
+    truncated: boolean;
+    nodes_total: number;
+    nodes_shown: number;
+    nodes_omitted: number;
+    nodeCount: number;
+    edgeCount: number;
+    chains: string[];
+    nodes: TracePathResult["nodes"];
+    edges: TracePathResult["edges"];
+    identity?: SymbolIdentityResolution;
+    /** Surfaced when the seed did not resolve — agent-actionable hint. */
+    notFoundHint?: string;
+}
+export interface ImpactAnalysisInput {
+    projectId: string;
+    projectPath: string;
+    scope?: ImpactScope;
+    base_branch?: string;
+    since?: string;
+    depth?: number;
+    paths?: string[];
+    /** Injectable diff runner (tests). */
+    diffRunner?: ImpactAnalysisOptions["diffRunner"];
+}
+export interface ImpactAnalysisOutput {
+    projectId: string;
+    scope: ImpactScope;
+    baseBranch?: string;
+    since?: string;
+    depth: number;
+    changedFileCount: number;
+    changedFiles: ImpactAnalysisResult["changedFiles"];
+    impactedCount: number;
+    truncated: boolean;
+    impacted: ImpactAnalysisResult["impacted"];
+    untrackedFiltered: number;
+    impacted_total: number;
+    impacted_shown: number;
+    impacted_omitted: number;
+    note?: string;
+}
+export declare class GraphController {
+    private static instance;
+    private constructor();
+    static getInstance(): GraphController;
+    /**
+     * Validate input, run the traversal via {@link TracePathService}, and shape
+     * the result for tool/API consumers. Returns `{ found: false, hint }` when
+     * the seed resolves to nothing (rather than an empty success).
+     */
+    tracePath(input: TracePathInput): Promise<{
+        found: true;
+        result: TracePathOutput;
+    } | {
+        found: false;
+        hint: string;
+        symbol: string;
+        projectId: string;
+        identityResolution?: Exclude<DefinitionLookupResult, {
+            status: "bare";
+        }>;
+    }>;
+    /**
+     * Run impact analysis via {@link ImpactAnalysisService}: scoped git diff →
+     * changed files → reverse traversal of importers + references → ranked
+     * impacted symbols. Returns the raw service result shaped for tool/API
+     * consumers.
+     */
+    analyzeImpact(input: ImpactAnalysisInput): Promise<ImpactAnalysisOutput>;
+}
+//# sourceMappingURL=graph-controller.d.ts.map

package/dist/controllers/graph-controller.d.ts.map

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

package/dist/controllers/graph-controller.js

@@ -0,0 +1,142 @@
+/**
+ * Graph Controller
+ *
+ * Orchestration layer for Symbol Graph traversal tools. Today it fronts
+ * trace_path (Phase 4 D2); future graph-walk tools (impact_analysis,
+ * architecture-map) land here too so they share seed-resolution and
+ * result-shaping logic.
+ *
+ * The controller keeps the tool handlers thin: input validation +
+ * result formatting live here, while the BFS traversal is owned by
+ * {@link TracePathService}.
+ */
+import { logger } from "@massa-ai/shared";
+import { tracePathService } from "../services/symbol/trace-path.js";
+import { impactAnalysisService } from "../services/symbol/impact-analysis.js";
+import { toSymbolIdentityResolution } from "../services/symbol/definition-lookup.js";
+export class GraphController {
+    static instance = null;
+    constructor() { }
+    static getInstance() {
+        if (!GraphController.instance) {
+            GraphController.instance = new GraphController();
+        }
+        return GraphController.instance;
+    }
+    /**
+     * Validate input, run the traversal via {@link TracePathService}, and shape
+     * the result for tool/API consumers. Returns `{ found: false, hint }` when
+     * the seed resolves to nothing (rather than an empty success).
+     */
+    async tracePath(input) {
+        const projectId = input.projectId;
+        const seed = input.function_name ?? input.symbol ?? input.qualifiedName;
+        if (!projectId)
+            throw new Error("projectId is required");
+        if (!seed)
+            throw new Error("function_name (or symbol/qualifiedName) is required");
+        const t0 = performance.now();
+        const result = await tracePathService.tracePath({
+            symbol: input.function_name ?? input.symbol ?? "",
+            function_name: input.function_name,
+            qualifiedName: input.qualifiedName,
+            projectId,
+            direction: input.direction,
+            mode: input.mode,
+            depth: input.depth,
+            include_tests: input.include_tests,
+            edge_types: input.edge_types,
+        });
+        logger.info("GraphController: trace_path", {
+            projectId,
+            symbol: seed,
+            mode: result.mode,
+            direction: result.direction,
+            seeds: result.seeds.length,
+            nodes: result.nodes.length,
+            edges: result.edges.length,
+            durationMs: Math.round(performance.now() - t0),
+        });
+        if (result.seeds.length === 0) {
+            return {
+                found: false,
+                symbol: seed,
+                projectId,
+                ...(result.identityResolution ? { identityResolution: result.identityResolution } : {}),
+                hint: "Use search_definitions(search=...) to find the exact name, or pass a fully-qualified name (qualifiedName='rel/path.ts#Name').",
+            };
+        }
+        return {
+            found: true,
+            result: {
+                projectId: result.projectId,
+                symbol: result.symbol,
+                mode: result.mode,
+                direction: result.direction,
+                edgeTypes: result.edgeTypes,
+                seeds: result.seeds,
+                truncated: result.truncated,
+                nodes_total: result.nodes_total,
+                nodes_shown: result.nodes_shown,
+                nodes_omitted: result.nodes_omitted,
+                nodeCount: result.nodes.length,
+                edgeCount: result.edges.length,
+                chains: result.chains,
+                nodes: result.nodes,
+                edges: result.edges,
+                ...(result.identityResolution
+                    ? { identity: toSymbolIdentityResolution(result.identityResolution) }
+                    : {}),
+            },
+        };
+    }
+    /**
+     * Run impact analysis via {@link ImpactAnalysisService}: scoped git diff →
+     * changed files → reverse traversal of importers + references → ranked
+     * impacted symbols. Returns the raw service result shaped for tool/API
+     * consumers.
+     */
+    async analyzeImpact(input) {
+        if (!input.projectId)
+            throw new Error("projectId is required");
+        if (!input.projectPath)
+            throw new Error("projectPath is required");
+        const t0 = performance.now();
+        const result = await impactAnalysisService.analyze({
+            projectId: input.projectId,
+            projectPath: input.projectPath,
+            scope: input.scope ?? "unstaged",
+            baseBranch: input.base_branch,
+            since: input.since,
+            depth: input.depth,
+            paths: input.paths,
+            diffRunner: input.diffRunner,
+        });
+        logger.info("GraphController: impact_analysis", {
+            projectId: input.projectId,
+            scope: result.scope,
+            changedFiles: result.changedFiles.length,
+            impacted: result.impacted.length,
+            truncated: result.truncated,
+            durationMs: Math.round(performance.now() - t0),
+        });
+        return {
+            projectId: result.projectId,
+            scope: result.scope,
+            baseBranch: result.baseBranch,
+            since: result.since,
+            depth: result.depth,
+            changedFileCount: result.changedFiles.length,
+            changedFiles: result.changedFiles,
+            impactedCount: result.impacted.length,
+            truncated: result.truncated,
+            impacted: result.impacted,
+            untrackedFiltered: result.untrackedFiltered,
+            impacted_total: result.impacted_total,
+            impacted_shown: result.impacted_shown,
+            impacted_omitted: result.impacted_omitted,
+            note: result.note,
+        };
+    }
+}
+//# sourceMappingURL=graph-controller.js.map

package/dist/controllers/graph-controller.js.map

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

package/dist/controllers/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @massa-ai/core - Controllers Export
+ *
+ * Orchestration layer between tools (thin MCP handlers) and
+ * services/data (domain logic + persistence).
+ */
+export { MemoryController } from "./memory-controller.js";
+export type { StoreMemoryInput, StoreMemoryResult, SearchMemoryInput, SearchMemoryResult, } from "./memory-controller.js";
+export { SearchController } from "./search-controller.js";
+export type { ProjectSearchInput, ProjectSearchResult, } from "./search-controller.js";
+export { ContextController } from "./context-controller.js";
+export type { GetOptimizedContextInput, OptimizedContextResult, } from "./context-controller.js";
+export { ExecutorController } from "./executor-controller.js";
+export { GraphController } from "./graph-controller.js";
+export type { TracePathInput, TracePathOutput } from "./graph-controller.js";
+export type { ImpactAnalysisInput, ImpactAnalysisOutput } from "./graph-controller.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/controllers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/controllers/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,YAAY,EACV,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,YAAY,EACV,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAE9D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7E,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/controllers/index.js

@@ -0,0 +1,12 @@
+/**
+ * @massa-ai/core - Controllers Export
+ *
+ * Orchestration layer between tools (thin MCP handlers) and
+ * services/data (domain logic + persistence).
+ */
+export { MemoryController } from "./memory-controller.js";
+export { SearchController } from "./search-controller.js";
+export { ContextController } from "./context-controller.js";
+export { ExecutorController } from "./executor-controller.js";
+export { GraphController } from "./graph-controller.js";
+//# sourceMappingURL=index.js.map

package/dist/controllers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/controllers/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAQ1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAM1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAM5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAE9D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/controllers/memory-controller.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Memory Controller
+ *
+ * Orchestration layer for memory operations.
+ * Composes MemoryRepository, MemoryService, MemoryGraphService,
+ * and the consolidation job.
+ *
+ * Tools (store_memory, search_memories) delegate here.
+ * This is the single entry point for all memory use cases.
+ */
+import { MemoryType, MemoryLevel } from "@massa-ai/shared";
+import type { MemoryRow } from "../data/memory/memory-repository.js";
+import { type ScoredMemory } from "../services/memory/memory-service.js";
+export interface StoreMemoryInput {
+    content: string;
+    type: MemoryType;
+    userId?: string;
+    sessionId?: string;
+    projectId?: string;
+    agentId?: string;
+    importance?: number;
+    tags?: string[];
+    linkTo?: string[];
+}
+export interface StoreMemoryResult {
+    memoryId: string;
+    stored: "local";
+    level: MemoryLevel;
+    type: MemoryType;
+}
+export interface SearchMemoryInput {
+    query: string;
+    userId?: string;
+    sessionId?: string;
+    projectId?: string;
+    agentId?: string;
+    types?: MemoryType[];
+    minImportance?: number;
+    limit?: number;
+    includePersistent?: boolean;
+    includeRelated?: boolean;
+}
+export interface SearchMemoryResult {
+    memories: ScoredMemory[];
+    relatedSummaries: Record<string, string>;
+    query: string;
+    total: number;
+}
+export interface UpdateMemoryInput {
+    id: string;
+    content?: string;
+    importance?: number;
+    tags?: string[];
+    /** When true, union `tags` with existing tags instead of replacing. */
+    mergeTags?: boolean;
+}
+export interface UpdateMemoryResult {
+    id: string;
+    updated: boolean;
+    memory?: Omit<MemoryRow, "embedding">;
+}
+export interface DeleteMemoryResult {
+    id: string;
+    deleted: boolean;
+}
+export declare class MemoryController {
+    private static instance;
+    private readonly repo;
+    private readonly service;
+    private readonly graph;
+    private constructor();
+    static getInstance(): MemoryController;
+    store(input: StoreMemoryInput): Promise<StoreMemoryResult>;
+    update(input: UpdateMemoryInput): Promise<UpdateMemoryResult>;
+    delete(id: string): Promise<DeleteMemoryResult>;
+    search(input: SearchMemoryInput): Promise<SearchMemoryResult>;
+}
+//# sourceMappingURL=memory-controller.d.ts.map

package/dist/controllers/memory-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-controller.d.ts","sourceRoot":"","sources":["../../src/controllers/memory-controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAU,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,sCAAsC,CAAC;AAQ9C,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,WAAW,CAAC;IACnB,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,uEAAuE;IACvE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,IAAI,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;CAClB;AAID,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAiC;IAExD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAyC;IAC9D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAE3C,OAAO;IAMP,MAAM,CAAC,WAAW,IAAI,gBAAgB;IAShC,KAAK,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAoF1D,MAAM,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAyD7D,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAc/C,MAAM,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CA6FpE"}