@spinabot/brigade 0.1.2 → 1.0.1

package/dist/agents/tools/spawn-agents-tool.js

@@ -0,0 +1,267 @@
+/**
+ * `spawn_agents` tool — Primitive #6, Wave P1 parallel fan-out.
+ *
+ * The model calls this to delegate N self-contained sub-tasks IN PARALLEL.
+ * Each task becomes its own sub-agent run with the same persona but a
+ * minimal system prompt (mirroring `spawn_agent`). The tool blocks the
+ * parent turn until every child has settled (ok / aborted / timed-out /
+ * limit-refused / error) and returns an AGGREGATED result envelope so the
+ * model can synthesise across all replies in the next assistant turn.
+ *
+ * Use this when:
+ *   - The work decomposes cleanly into independent sub-tasks (research N
+ *     topics, audit M files, summarise K documents).
+ *   - You want parallel wall-clock — N children run concurrently up to
+ *     `maxChildrenPerParent`.
+ *   - You'd otherwise call `spawn_agent` sequentially in a tight loop.
+ *
+ * Sequential `spawn_agent` calls are fine for "must finish step 1 before
+ * step 2"; that's not what this is for.
+ *
+ * Implementation: each task is dispatched via the SAME runner as
+ * `spawn_agent` (`runSubagent`) inside `Promise.allSettled`. We do NOT
+ * implement batching for >maxChildrenPerParent — instead, we refuse the
+ * whole call up-front with a clear error so the model knows to split
+ * into multiple spawn_agents calls (or chunk its work). Batching is a
+ * future enhancement when we see the need.
+ *
+ * Cleanup is operator-controlled (same as `spawn_agent`) — never exposed
+ * in the schema.
+ */
+import { Type } from "typebox";
+import { DEFAULT_SUBAGENT_TIMEOUT_SECONDS, SubagentLimitError, resolveSubagentLimits, } from "../subagent-policy.js";
+import { loadConfig } from "../../core/config.js";
+import { jsonResult } from "./common.js";
+import { checkSessionToolAccess, } from "./sessions/shared.js";
+const ThinkingLevel = Type.Union([
+    Type.Literal("off"),
+    Type.Literal("low"),
+    Type.Literal("medium"),
+    Type.Literal("high"),
+]);
+const SpawnAgentsTask = Type.Object({
+    task: Type.String({
+        description: "What this sub-agent should do. Self-contained — it can't see the parent conversation or its siblings.",
+        minLength: 1,
+    }),
+    label: Type.Optional(Type.String({
+        description: "Short label (3-5 words). Shown in logs + the aggregated result envelope.",
+    })),
+    model: Type.Optional(Type.String({ description: "Model override for this child. Defaults to the parent's model." })),
+    thinking: Type.Optional(ThinkingLevel),
+    timeoutSeconds: Type.Optional(Type.Number({
+        description: `Per-child timeout in seconds. Default ${DEFAULT_SUBAGENT_TIMEOUT_SECONDS}s. Applies independently to each task.`,
+    })),
+});
+const SpawnAgentsParams = Type.Object({
+    tasks: Type.Array(SpawnAgentsTask, {
+        description: "List of independent tasks. Each one becomes its own sub-agent that runs in parallel. The total count must be ≤ maxChildrenPerParent (default 5).",
+        minItems: 1,
+    }),
+});
+export function makeSpawnAgentsTool(opts) {
+    return {
+        name: "spawn_agents",
+        label: "spawn sub-agents (parallel)",
+        displaySummary: "spawning sub-agents in parallel",
+        description: "SYNC blocking parallel fan-out. Dispatches N sub-agents in parallel, blocks until every child settles, " +
+            "and returns an aggregated envelope `{total, succeeded, failed, totalDurationMs, results: [{label, status, reply, ...}]}` " +
+            "so the next assistant turn can synthesise across replies. Use when the work decomposes into independent " +
+            "sub-tasks. Total tasks must be ≤ maxChildrenPerParent (default 5). For ONE child use spawn_agent; for fire-and-forget use sessions_spawn.",
+        parameters: SpawnAgentsParams,
+        async execute(_toolCallId, params, signal) {
+            const tasks = Array.isArray(params.tasks) ? params.tasks : [];
+            if (tasks.length === 0) {
+                return jsonResult({
+                    total: 0,
+                    succeeded: 0,
+                    failed: 0,
+                    totalDurationMs: 0,
+                    results: [],
+                });
+            }
+            // Resolve limits up-front so we can refuse oversize fan-outs with a
+            // concrete error message that names the operator's actual cap.
+            const cfg = loadConfig();
+            const limits = resolveSubagentLimits(cfg);
+            if (tasks.length > limits.maxChildrenPerParent) {
+                return jsonResult({
+                    total: tasks.length,
+                    succeeded: 0,
+                    failed: tasks.length,
+                    totalDurationMs: 0,
+                    results: tasks.map((t) => ({
+                        label: typeof t.label === "string" && t.label.trim() ? t.label : "sub-agent",
+                        status: "limit-refused",
+                        reason: "concurrent",
+                        error: `spawn_agents refused: ${tasks.length} tasks exceeds maxChildrenPerParent=${limits.maxChildrenPerParent}. Split into ≤${limits.maxChildrenPerParent}-task batches.`,
+                    })),
+                });
+            }
+            // Fail-closed access guard — same posture as spawn_agent. Unwired
+            // callers refuse every spawn unless `bypassAccessGuard:true` is set
+            // for trusted internal pathways (boot / cron / heartbeat).
+            if (opts.bypassAccessGuard !== true) {
+                if (!opts.visibility || !opts.a2aPolicy) {
+                    return jsonResult({
+                        total: tasks.length,
+                        succeeded: 0,
+                        failed: tasks.length,
+                        totalDurationMs: 0,
+                        results: tasks.map((t) => ({
+                            label: typeof t.label === "string" && t.label.trim() ? t.label : "sub-agent",
+                            status: "limit-refused",
+                            reason: "access-denied",
+                            error: "spawn_agents forbidden: session access policy not configured",
+                        })),
+                    });
+                }
+                const verdict = checkSessionToolAccess({
+                    action: "send",
+                    requesterSessionKey: opts.parentSessionKey,
+                    targetSessionKey: opts.parentSessionKey,
+                    visibility: opts.visibility,
+                    a2aPolicy: opts.a2aPolicy,
+                    ...(opts.spawnedKeys ? { spawnedKeys: opts.spawnedKeys } : {}),
+                });
+                if (!verdict.allowed) {
+                    return jsonResult({
+                        total: tasks.length,
+                        succeeded: 0,
+                        failed: tasks.length,
+                        totalDurationMs: 0,
+                        results: tasks.map((t) => ({
+                            label: typeof t.label === "string" && t.label.trim() ? t.label : "sub-agent",
+                            status: "limit-refused",
+                            reason: "access-denied",
+                            error: verdict.error,
+                        })),
+                    });
+                }
+            }
+            const combinedSignal = combineSignals(opts.parentSignal, signal);
+            // D2 — parent-abort fast-fail at the batch layer. If the parent run is
+            // already cancelled / out-of-budget by the time spawn_agents fires (the
+            // common case: a lead that exhausts its 300s budget on its own research,
+            // then emits a fan-out as its last act), refuse the WHOLE batch up-front
+            // with an honest envelope rather than dispatching children that each die
+            // on the dead signal in ~1ms and report back as fake `aborted` results.
+            if (combinedSignal?.aborted) {
+                return jsonResult({
+                    total: tasks.length,
+                    succeeded: 0,
+                    failed: tasks.length,
+                    totalDurationMs: 0,
+                    results: tasks.map((t) => ({
+                        label: typeof t.label === "string" && t.label.trim() ? t.label : "sub-agent",
+                        status: "limit-refused",
+                        reason: "parent-aborted",
+                        error: "spawn_agents not started: the parent run was already cancelled or out of budget before children could be dispatched. Answer directly with what you have, or fan out earlier in the turn — before spending the run's time budget.",
+                    })),
+                });
+            }
+            const { runSubagent } = await import("../subagent-runner.js");
+            const t0 = Date.now();
+            // Promise.allSettled is the right primitive here — one child's
+            // crash must not bring down the others; each result lands in the
+            // aggregated envelope independently.
+            const settled = await Promise.allSettled(tasks.map(async (t) => {
+                const label = typeof t.label === "string" && t.label.trim() ? t.label : "sub-agent";
+                const task = typeof t.task === "string" ? t.task : "";
+                const thinkingRaw = typeof t.thinking === "string" ? t.thinking : undefined;
+                const thinking = thinkingRaw === "off" ||
+                    thinkingRaw === "low" ||
+                    thinkingRaw === "medium" ||
+                    thinkingRaw === "high"
+                    ? thinkingRaw
+                    : undefined;
+                const modelOverride = typeof t.model === "string" && t.model.trim() ? t.model : undefined;
+                const timeoutSeconds = typeof t.timeoutSeconds === "number" && Number.isFinite(t.timeoutSeconds)
+                    ? Math.floor(t.timeoutSeconds)
+                    : undefined;
+                const effectiveModel = modelOverride ?? opts.parentModelId;
+                try {
+                    const result = await runSubagent({
+                        parentSessionKey: opts.parentSessionKey,
+                        parentAgentId: opts.parentAgentId,
+                        ...(opts.parentRunId !== undefined ? { parentRunId: opts.parentRunId } : {}),
+                        task,
+                        label,
+                        ...(opts.parentProvider !== undefined ? { provider: opts.parentProvider } : {}),
+                        ...(effectiveModel !== undefined ? { modelId: effectiveModel } : {}),
+                        ...(thinking !== undefined ? { thinkingLevel: thinking } : {}),
+                        ...(timeoutSeconds !== undefined ? { timeoutSeconds } : {}),
+                        ...(combinedSignal !== undefined ? { parentSignal: combinedSignal } : {}),
+                    });
+                    return {
+                        label,
+                        status: result.aborted ? (result.timedOut ? "timed-out" : "aborted") : "ok",
+                        childSessionKey: result.childSessionKey,
+                        durationMs: result.durationMs,
+                        reply: result.reply,
+                    };
+                }
+                catch (err) {
+                    if (err instanceof SubagentLimitError) {
+                        return {
+                            label,
+                            status: "limit-refused",
+                            reason: err.kind,
+                            error: err.message,
+                        };
+                    }
+                    return {
+                        label,
+                        status: "error",
+                        error: err instanceof Error ? err.message : String(err),
+                    };
+                }
+            }));
+            // allSettled never rejects — but pluck `value` for fulfilled and
+            // synthesise an error envelope for the rejected case (which can
+            // only happen if our own mapper above throws, which it shouldn't
+            // because everything is wrapped in try/catch).
+            const results = settled.map((s, i) => {
+                if (s.status === "fulfilled")
+                    return s.value;
+                const label = typeof tasks[i]?.label === "string" && tasks[i].label.trim()
+                    ? tasks[i].label
+                    : "sub-agent";
+                return {
+                    label,
+                    status: "error",
+                    error: s.reason instanceof Error ? s.reason.message : String(s.reason),
+                };
+            });
+            const succeeded = results.filter((r) => r.status === "ok").length;
+            const failed = results.length - succeeded;
+            return jsonResult({
+                total: results.length,
+                succeeded,
+                failed,
+                totalDurationMs: Date.now() - t0,
+                results,
+            });
+        },
+    };
+}
+function combineSignals(...signals) {
+    const live = signals.filter((s) => s !== undefined);
+    if (live.length === 0)
+        return undefined;
+    if (live.length === 1)
+        return live[0];
+    const anyFn = AbortSignal.any;
+    if (typeof anyFn === "function")
+        return anyFn(live);
+    const controller = new AbortController();
+    for (const s of live) {
+        if (s.aborted) {
+            controller.abort(s.reason);
+            break;
+        }
+        s.addEventListener("abort", () => controller.abort(s.reason), { once: true });
+    }
+    return controller.signal;
+}
+//# sourceMappingURL=spawn-agents-tool.js.map

package/dist/agents/tools/spawn-agents-tool.js.map

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

package/dist/agents/tools/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Brigade tool framework — type aliases.
+ *
+ * Brigade tools are Pi `AgentTool` objects with a thin Brigade-native
+ * extension. We re-export Pi's `AgentToolResult` and `AgentToolUpdateCallback`
+ * unchanged because they're already the right shape (`{content, details}`
+ * plus an `onUpdate` callback for streaming tools). The extension fields
+ * (`ownerOnly`, `displaySummary`) carry Brigade-specific metadata used by
+ * the TUI / gateway / future channels.
+ *
+ * Pi's `AgentTool<TParameters, TDetails>` already requires:
+ *   - `name: string`
+ *   - `description: string`
+ *   - `parameters: TSchema` (a TypeBox schema; Pi runs validation via
+ *     `@sinclair/typebox` before calling `execute`)
+ *   - `execute(toolCallId, params, signal?, onUpdate?) → Promise<AgentToolResult<TDetails>>`
+ *   - `label: string`
+ *
+ * Plus Pi optionally exposes `prepareArguments` (pre-validation shim) and
+ * a per-tool execution-mode override ("sequential" vs "parallel"). Brigade
+ * inherits all of these — no Brigade-specific overrides at the Pi layer.
+ *
+ * No AJV. Pi's TypeBox-driven validation is the schema layer; tool
+ * `execute` bodies use the `read*Param` helpers in `./common.ts` for any
+ * post-schema coercion / labelling that's nicer than catching AJV errors.
+ */
+import type { AgentTool } from "@mariozechner/pi-agent-core";
+import type { TSchema } from "typebox";
+export type { AgentToolResult, AgentToolUpdateCallback, } from "@mariozechner/pi-agent-core";
+/**
+ * Brigade-native extension of Pi's `AgentTool`. Adds two metadata fields
+ * the chat-surface uses:
+ *
+ *   - `ownerOnly` — when true, the tool refuses calls from non-owner
+ *     senders. Today (single-user v1) every sender is the owner, so this
+ *     is a no-op flag; reserved for Phase 2 (multi-user / channels).
+ *   - `displaySummary` — short one-liner shown in the TUI when the
+ *     tool dispatches, e.g. "reading <path>" or "running shell". When
+ *     omitted, the TUI falls back to the tool's `name`.
+ */
+export interface BrigadeTool<TParameters extends TSchema = TSchema, TDetails = unknown> extends AgentTool<TParameters, TDetails> {
+    ownerOnly?: boolean;
+    displaySummary?: string;
+}
+/**
+ * Existential-wrapped tool type for registries and arrays. Pi accepts
+ * `AgentTool<any, any>` in its `customTools` slot; the registry helpers
+ * use this alias to round-trip without dragging generics through every
+ * call site.
+ *
+ * The `any` is documented and isolated — tools opt in via `BrigadeTool`
+ * at definition time, then collapse to `AnyBrigadeTool` for storage.
+ */
+export type AnyBrigadeTool = BrigadeTool<any, unknown>;
+//# sourceMappingURL=types.d.ts.map

package/dist/agents/tools/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/agents/tools/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAK7D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,YAAY,EACX,eAAe,EACf,uBAAuB,GACvB,MAAM,6BAA6B,CAAC;AAErC;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW,CAC3B,WAAW,SAAS,OAAO,GAAG,OAAO,EACrC,QAAQ,GAAG,OAAO,CACjB,SAAQ,SAAS,CAAC,WAAW,EAAE,QAAQ,CAAC;IACzC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;GAQG;AAEH,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC"}

package/dist/agents/tools/types.js

@@ -0,0 +1,28 @@
+/**
+ * Brigade tool framework — type aliases.
+ *
+ * Brigade tools are Pi `AgentTool` objects with a thin Brigade-native
+ * extension. We re-export Pi's `AgentToolResult` and `AgentToolUpdateCallback`
+ * unchanged because they're already the right shape (`{content, details}`
+ * plus an `onUpdate` callback for streaming tools). The extension fields
+ * (`ownerOnly`, `displaySummary`) carry Brigade-specific metadata used by
+ * the TUI / gateway / future channels.
+ *
+ * Pi's `AgentTool<TParameters, TDetails>` already requires:
+ *   - `name: string`
+ *   - `description: string`
+ *   - `parameters: TSchema` (a TypeBox schema; Pi runs validation via
+ *     `@sinclair/typebox` before calling `execute`)
+ *   - `execute(toolCallId, params, signal?, onUpdate?) → Promise<AgentToolResult<TDetails>>`
+ *   - `label: string`
+ *
+ * Plus Pi optionally exposes `prepareArguments` (pre-validation shim) and
+ * a per-tool execution-mode override ("sequential" vs "parallel"). Brigade
+ * inherits all of these — no Brigade-specific overrides at the Pi layer.
+ *
+ * No AJV. Pi's TypeBox-driven validation is the schema layer; tool
+ * `execute` bodies use the `read*Param` helpers in `./common.ts` for any
+ * post-schema coercion / labelling that's nicer than catching AJV errors.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/agents/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/agents/tools/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG"}

package/dist/agents/tools/web-fetch-utils.d.ts

@@ -0,0 +1,114 @@
+/**
+ * HTML → markdown extraction utilities.
+ *
+ * Two-tier pipeline lifted from the upstream reference:
+ *
+ *   1. **Primary** — `extractReadableContent`: Mozilla Readability + linkedom
+ *      (both lazy-loaded so the agent loop doesn't pay the parse cost on a
+ *      cold start). Readability scores the DOM, picks the "article" node,
+ *      and returns its inner HTML; we then hand-roll that to markdown via
+ *      regex (NOT Turndown — Turndown is heavy + opinionated, the regex
+ *      pipeline below is ~80 LOC and good-enough for the LLM consumer).
+ *
+ *   2. **Fallback** — `extractBasicHtmlContent`: pure-regex visible-text
+ *      extraction used when Readability returns nothing (very-small pages,
+ *      single-page apps with no semantic markup, malformed HTML).
+ *
+ * `sanitizeHtml` runs BEFORE either extractor to strip hidden content,
+ * scripts/styles, and invisible-Unicode prompt-injection vectors. The
+ * sanitizer is the single most load-bearing thing in this file — without it
+ * an attacker page can hide instructions inside `<div hidden>...</div>` or
+ * style-hidden divs and the markdown converter would surface them.
+ */
+/**
+ * Pre-extraction sanitizer. Strips:
+ *   1. `<script>/<style>/<noscript>/<iframe>/<object>/<embed>/<canvas>/<svg>/<template>/<meta>/<link>` (tag + contents)
+ *   2. HTML comments
+ *   3. `<input type="hidden">`
+ *   4. Elements with `hidden` attribute, `aria-hidden="true"`, or inline-style
+ *      hidden patterns (`display:none`, `visibility:hidden`, `opacity:0`,
+ *      `font-size:0`, `text-indent:-9999px`, `clip-path: inset(50%)`,
+ *      `transform: scale(0)`, off-screen positioning)
+ *   5. Elements with `class*="sr-only"` / `visually-hidden` etc.
+ *   6. Invisible-Unicode codepoints in the final text (zero-width joiners,
+ *      RTL overrides, tag-namespace characters) — defends against
+ *      prompt-injection-via-glyph-substitution.
+ *
+ * Pure regex — no DOM parsing. Fast (one pass per pattern), no allocations
+ * beyond the working string. Some edge cases (e.g. self-closing tags
+ * inside attributes) aren't covered; the linkedom-backed extractor handles
+ * those because it's a real parser, and the sanitizer is "good enough"
+ * for the basic-HTML fallback path.
+ */
+export declare function sanitizeHtml(html: string): string;
+/**
+ * Remove invisible Unicode codepoints from final text — zero-width joiners,
+ * RTL/LTR overrides, tag-namespace characters. Hostile pages use these to
+ * smuggle instructions into seemingly-innocent prose. Apply to the FINAL
+ * markdown output, not the raw HTML (the HTML legitimately may contain
+ * &#8203;-style entities that decode to invisible chars).
+ */
+export declare function stripInvisibleUnicode(text: string): string;
+/**
+ * Scrub literal envelope marker tokens from incoming content. If an
+ * attacker page emits the exact open/close markers used by
+ * `wrapWebContent` inside its own body, it can pose as a marker boundary
+ * and trick the model into treating subsequent text as instructions.
+ *
+ * Defenses applied in order:
+ *   1. Strip invisible Unicode so zero-width chars can't break up the
+ *      marker token (e.g. `<<<EXTER​NAL_UNTRUSTED_CONTENT>>>` with a
+ *      ZWSP after the R wouldn't match a naive regex).
+ *   2. Normalize ASCII-homoglyphs (fullwidth, mathematical-style chars)
+ *      to their plain-ASCII equivalents before pattern matching.
+ *   3. Match-and-replace the canonical marker forms.
+ *
+ * Returns content with any marker (real or spoofed) redacted to a
+ * placeholder. NOTE: this normalization is per-call defensive — it does
+ * NOT mutate the document's actual text; only the spoof-suspicion paths
+ * see the normalized form.
+ */
+export declare function stripEnvelopeMarkers(text: string): string;
+/**
+ * Hand-rolled HTML→markdown via regex. NOT Turndown — Turndown is ~120 KB
+ * + opinions we don't need. This converter handles the ~12 tags that
+ * actually matter for LLM consumption (headings, paragraphs, links,
+ * lists, code, blockquotes, emphasis) and stuffs the rest as plain text.
+ *
+ * Input is expected to be ALREADY sanitized (no `<script>`/`<style>`).
+ */
+export declare function htmlToMarkdown(html: string): string;
+/**
+ * Decode the most common HTML entities. Not exhaustive — covers what
+ * actually appears in scraped pages 99% of the time.
+ */
+export declare function decodeHtmlEntities(input: string): string;
+export interface ExtractedContent {
+    title?: string;
+    text: string;
+    extractor: "readability" | "basic-html" | "raw-html" | "json" | "raw" | "cf-markdown";
+}
+/**
+ * Run Mozilla Readability on an HTML doc. Returns null when Readability
+ * gave us nothing useful (rare — Readability is forgiving). Caller should
+ * fall back to `extractBasicHtmlContent` on null.
+ */
+export declare function extractReadableContent(html: string, baseUrl: string): Promise<ExtractedContent | null>;
+/**
+ * Pure-regex fallback when Readability returns nothing. Strips all HTML and
+ * returns the visible text. Loses structure (no headings, no lists), but
+ * better than returning nothing — for small/SPA pages this is what the
+ * model gets.
+ */
+export declare function extractBasicHtmlContent(html: string): ExtractedContent;
+/** Strip markdown back to plain text (for the `extractMode: "text"` path). */
+export declare function markdownToText(md: string): string;
+/** Format text+title into a `truncateText`-able body. */
+export declare function composeFetchBody(extracted: ExtractedContent, opts: {
+    extractMode: "markdown" | "text";
+    maxChars: number;
+}): {
+    text: string;
+    truncated: boolean;
+};
+//# sourceMappingURL=web-fetch-utils.d.ts.map

package/dist/agents/tools/web-fetch-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-fetch-utils.d.ts","sourceRoot":"","sources":["../../../src/agents/tools/web-fetch-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAsFH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoBjD;AAkDD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA8B1D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAazD;AA2DD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkEnD;AA2CD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWxD;AAID,MAAM,WAAW,gBAAgB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,aAAa,GAAG,YAAY,GAAG,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,aAAa,CAAC;CACtF;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC3C,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACb,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAuDlC;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAWtE;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAiBjD;AAED,yDAAyD;AACzD,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,gBAAgB,EAAE,IAAI,EAAE;IAAE,WAAW,EAAE,UAAU,GAAG,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG;IAC5H,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;CACnB,CAIA"}