chivgent 0.9.0 → 0.11.0

package/dist/shell/process.js

@@ -0,0 +1,134 @@
+/**
+ * How long to keep reading after a child exits.
+ *
+ * A short-lived command can exit while a descendant it detached still holds the
+ * stdout pipe and keeps writing. Finalising on `exit` would destroy the stream
+ * mid-write and silently drop that tail, so the timer is re-armed on every
+ * chunk: a descendant that is still writing keeps us reading, while a quiet
+ * inherited handle that never lets `close` fire still releases us.
+ */
+const POST_EXIT_IDLE_MS = 100;
+/**
+ * Kills a process and everything it spawned.
+ *
+ * Children are spawned detached, which makes each one a process group leader,
+ * so a negative pid signals the whole group. Killing only the direct child
+ * would leave its grandchildren running: stopping `npm test` would kill the npm
+ * process and leave the test workers holding CPU and ports.
+ */
+export function killProcessTree(pid) {
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        try {
+            process.kill(pid, "SIGKILL");
+        }
+        catch {
+            // Already gone.
+        }
+    }
+}
+const trackedPids = new Set();
+/** Detached children outlive the parent, so every pid is tracked until it exits. */
+export function trackChildPid(pid) {
+    trackedPids.add(pid);
+}
+export function untrackChildPid(pid) {
+    trackedPids.delete(pid);
+}
+/** Kills every command still running. Called when chivgent itself is shutting down. */
+export function killTrackedChildren() {
+    for (const pid of trackedPids) {
+        killProcessTree(pid);
+    }
+    trackedPids.clear();
+}
+/**
+ * Resolves with the exit code once the child has exited and its pipes have
+ * fallen idle. Rejects only when the process could not be spawned.
+ */
+export function waitForChildProcess(child) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let exited = false;
+        let exitCode = null;
+        let idleTimer;
+        let stdoutEnded = child.stdout === null;
+        let stderrEnded = child.stderr === null;
+        const cleanup = () => {
+            if (idleTimer !== undefined) {
+                clearTimeout(idleTimer);
+                idleTimer = undefined;
+            }
+            child.removeListener("error", onError);
+            child.removeListener("exit", onExit);
+            child.removeListener("close", onClose);
+            child.stdout?.removeListener("end", onStdoutEnd);
+            child.stderr?.removeListener("end", onStderrEnd);
+            child.stdout?.removeListener("data", onData);
+            child.stderr?.removeListener("data", onData);
+        };
+        const finalize = (code) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            cleanup();
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            resolve(code);
+        };
+        const finalizeIfPipesClosed = () => {
+            if (exited && !settled && stdoutEnded && stderrEnded) {
+                finalize(exitCode);
+            }
+        };
+        const armIdleTimer = () => {
+            if (idleTimer !== undefined) {
+                clearTimeout(idleTimer);
+            }
+            idleTimer = setTimeout(() => finalize(exitCode), POST_EXIT_IDLE_MS);
+        };
+        const onData = () => {
+            if (exited && !settled) {
+                armIdleTimer();
+            }
+        };
+        const onStdoutEnd = () => {
+            stdoutEnded = true;
+            finalizeIfPipesClosed();
+        };
+        const onStderrEnd = () => {
+            stderrEnded = true;
+            finalizeIfPipesClosed();
+        };
+        const onError = (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            cleanup();
+            reject(error);
+        };
+        const onExit = (code) => {
+            exited = true;
+            exitCode = code;
+            finalizeIfPipesClosed();
+            if (!settled) {
+                armIdleTimer();
+            }
+        };
+        const onClose = (code) => {
+            finalize(code);
+        };
+        child.stdout?.once("end", onStdoutEnd);
+        child.stderr?.once("end", onStderrEnd);
+        child.stdout?.on("data", onData);
+        child.stderr?.on("data", onData);
+        child.once("error", onError);
+        child.once("exit", onExit);
+        child.once("close", onClose);
+    });
+}
+//# sourceMappingURL=process.js.map

package/dist/shell/process.js.map

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

package/dist/shell/sanitize.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Strips characters that must not reach the transcript or the terminal.
+ *
+ * Commands print ANSI sequences, progress-bar control codes, and occasionally
+ * raw binary. Left alone those corrupt the session JSONL and scramble the
+ * terminal, so everything below 0x20 except tab, newline and carriage return is
+ * dropped, along with lone surrogates and Unicode format characters.
+ */
+export declare function sanitizeShellOutput(value: string): string;
+//# sourceMappingURL=sanitize.d.ts.map

package/dist/shell/sanitize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../src/shell/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAwBzD"}

package/dist/shell/sanitize.js

@@ -0,0 +1,34 @@
+/**
+ * Strips characters that must not reach the transcript or the terminal.
+ *
+ * Commands print ANSI sequences, progress-bar control codes, and occasionally
+ * raw binary. Left alone those corrupt the session JSONL and scramble the
+ * terminal, so everything below 0x20 except tab, newline and carriage return is
+ * dropped, along with lone surrogates and Unicode format characters.
+ */
+export function sanitizeShellOutput(value) {
+    let result = "";
+    for (const character of value) {
+        const code = character.codePointAt(0);
+        if (code === undefined) {
+            continue;
+        }
+        if (code === 0x09 || code === 0x0a || code === 0x0d) {
+            result += character;
+            continue;
+        }
+        if (code <= 0x1f || code === 0x7f) {
+            continue;
+        }
+        // Lone surrogates survive iteration only when unpaired.
+        if (code >= 0xd800 && code <= 0xdfff) {
+            continue;
+        }
+        if (code >= 0xfff9 && code <= 0xfffb) {
+            continue;
+        }
+        result += character;
+    }
+    return result;
+}
+//# sourceMappingURL=sanitize.js.map

package/dist/shell/sanitize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.js","sourceRoot":"","sources":["../../src/shell/sanitize.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,MAAM,SAAS,IAAI,KAAK,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;QACtC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,SAAS;QACX,CAAC;QACD,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YACpD,MAAM,IAAI,SAAS,CAAC;YACpB,SAAS;QACX,CAAC;QACD,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClC,SAAS;QACX,CAAC;QACD,wDAAwD;QACxD,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,EAAE,CAAC;YACrC,SAAS;QACX,CAAC;QACD,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,EAAE,CAAC;YACrC,SAAS;QACX,CAAC;QACD,MAAM,IAAI,SAAS,CAAC;IACtB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/shell/truncate.d.ts

@@ -0,0 +1,31 @@
+export declare const DEFAULT_MAX_LINES = 2000;
+export declare const DEFAULT_MAX_BYTES: number;
+export interface TruncationOptions {
+    readonly maxLines?: number;
+    readonly maxBytes?: number;
+}
+export interface TruncationResult {
+    readonly content: string;
+    readonly truncated: boolean;
+    readonly truncatedBy: "lines" | "bytes" | null;
+    readonly totalLines: number;
+    readonly totalBytes: number;
+    readonly outputLines: number;
+    readonly outputBytes: number;
+    /** True when the kept text starts mid-line because one line blew the budget. */
+    readonly lastLinePartial: boolean;
+    readonly maxLines: number;
+    readonly maxBytes: number;
+}
+export declare function countLines(content: string): number;
+/**
+ * Keeps the end of the content.
+ *
+ * Shell output is truncated from the tail because that is where the answer is:
+ * the failing assertion, the compiler's last error, the summary line. Reading a
+ * file wants the opposite, which is why `read_file` keeps its own line-range
+ * logic rather than sharing this one.
+ */
+export declare function truncateTail(content: string, options?: TruncationOptions): TruncationResult;
+export declare function formatSize(bytes: number): string;
+//# sourceMappingURL=truncate.d.ts.map

package/dist/shell/truncate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncate.d.ts","sourceRoot":"","sources":["../../src/shell/truncate.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,iBAAiB,OAAQ,CAAC;AACvC,eAAO,MAAM,iBAAiB,QAAY,CAAC;AAE3C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,gFAAgF;IAChF,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAoCD,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB,CAsElB;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQhD"}

package/dist/shell/truncate.js

@@ -0,0 +1,121 @@
+// Output truncation shared by the shell tool and anything else that has to fit
+// unbounded output into a bounded result.
+export const DEFAULT_MAX_LINES = 2_000;
+export const DEFAULT_MAX_BYTES = 50 * 1024;
+function byteLength(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+/** Splits on newlines, keeping the terminator on the line it belongs to. */
+function splitLines(content) {
+    if (content.length === 0) {
+        return [];
+    }
+    const lines = content.split("\n").map((line, index, all) => index === all.length - 1 ? line : `${line}\n`);
+    if (lines.at(-1) === "") {
+        lines.pop();
+    }
+    return lines;
+}
+/** Keeps whole characters, never splitting a multi-byte sequence. */
+function takeLastBytes(value, maxBytes) {
+    const characters = [...value];
+    let bytes = 0;
+    let index = characters.length;
+    while (index > 0) {
+        const size = byteLength(characters[index - 1] ?? "");
+        if (bytes + size > maxBytes) {
+            break;
+        }
+        bytes += size;
+        index -= 1;
+    }
+    return characters.slice(index).join("");
+}
+export function countLines(content) {
+    return splitLines(content).length;
+}
+/**
+ * Keeps the end of the content.
+ *
+ * Shell output is truncated from the tail because that is where the answer is:
+ * the failing assertion, the compiler's last error, the summary line. Reading a
+ * file wants the opposite, which is why `read_file` keeps its own line-range
+ * logic rather than sharing this one.
+ */
+export function truncateTail(content, options = {}) {
+    const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const totalBytes = byteLength(content);
+    const lines = splitLines(content);
+    const totalLines = lines.length;
+    if (totalLines <= maxLines && totalBytes <= maxBytes) {
+        return {
+            content,
+            truncated: false,
+            truncatedBy: null,
+            totalLines,
+            totalBytes,
+            outputLines: totalLines,
+            outputBytes: totalBytes,
+            lastLinePartial: false,
+            maxLines,
+            maxBytes,
+        };
+    }
+    let bytes = 0;
+    let index = lines.length;
+    let stoppedBy = "lines";
+    while (index > 0) {
+        if (lines.length - index >= maxLines) {
+            stoppedBy = "lines";
+            break;
+        }
+        const size = byteLength(lines[index - 1] ?? "");
+        if (bytes + size > maxBytes) {
+            stoppedBy = "bytes";
+            break;
+        }
+        bytes += size;
+        index -= 1;
+    }
+    // Not even one line fits: keep the tail of the last line so the result is
+    // never empty just because a command printed one enormous line.
+    if (index === lines.length) {
+        const partial = takeLastBytes(lines.at(-1) ?? "", maxBytes);
+        return {
+            content: partial,
+            truncated: true,
+            truncatedBy: "bytes",
+            totalLines,
+            totalBytes,
+            outputLines: partial.length === 0 ? 0 : 1,
+            outputBytes: byteLength(partial),
+            lastLinePartial: true,
+            maxLines,
+            maxBytes,
+        };
+    }
+    const kept = lines.slice(index);
+    return {
+        content: kept.join(""),
+        truncated: true,
+        truncatedBy: stoppedBy,
+        totalLines,
+        totalBytes,
+        outputLines: kept.length,
+        outputBytes: bytes,
+        lastLinePartial: false,
+        maxLines,
+        maxBytes,
+    };
+}
+export function formatSize(bytes) {
+    if (bytes < 1024) {
+        return `${bytes}B`;
+    }
+    if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    }
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+//# sourceMappingURL=truncate.js.map

package/dist/shell/truncate.js.map

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

package/dist/shell/types.d.ts

@@ -0,0 +1,33 @@
+/** Raised when a command was killed because its AbortSignal fired. */
+export declare class ShellAbortError extends Error {
+    constructor();
+}
+/** Raised when a command outlived the timeout it was given. */
+export declare class ShellTimeoutError extends Error {
+    readonly timeoutSeconds: number;
+    constructor(timeoutSeconds: number);
+}
+export declare class ShellUnavailableError extends Error {
+    constructor(message: string);
+}
+export interface ShellExecOptions {
+    /** Receives raw stdout and stderr chunks, interleaved in arrival order. */
+    readonly onData: (chunk: Buffer) => void;
+    readonly signal?: AbortSignal;
+    readonly timeoutSeconds?: number;
+    readonly env?: NodeJS.ProcessEnv;
+}
+export interface ShellExecResult {
+    /** null when the process was killed by a signal rather than exiting. */
+    readonly exitCode: number | null;
+}
+/**
+ * Pluggable command execution.
+ *
+ * Local `spawn` is one implementation. A container or an SSH backend is
+ * another, and the shell tool never needs to know which it has.
+ */
+export interface ShellOperations {
+    exec(command: string, cwd: string, options: ShellExecOptions): Promise<ShellExecResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/shell/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shell/types.ts"],"names":[],"mappings":"AAEA,sEAAsE;AACtE,qBAAa,eAAgB,SAAQ,KAAK;IACxC,cAKC;CACF;AAED,+DAA+D;AAC/D,qBAAa,iBAAkB,SAAQ,KAAK;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM;IAA3C,YAAqB,cAAc,EAAE,MAAM,EAG1C;CACF;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CACF,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CAAC;CAC7B"}

package/dist/shell/types.js

@@ -0,0 +1,26 @@
+// Shared contracts for shell execution.
+/** Raised when a command was killed because its AbortSignal fired. */
+export class ShellAbortError extends Error {
+    constructor() {
+        super("Command aborted");
+        // The Agent recognises this name and ends the run as aborted, exactly as
+        // it does for a cancelled Provider call.
+        this.name = "AbortError";
+    }
+}
+/** Raised when a command outlived the timeout it was given. */
+export class ShellTimeoutError extends Error {
+    timeoutSeconds;
+    constructor(timeoutSeconds) {
+        super(`Command timed out after ${timeoutSeconds} seconds`);
+        this.timeoutSeconds = timeoutSeconds;
+        this.name = "ShellTimeoutError";
+    }
+}
+export class ShellUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ShellUnavailableError";
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/shell/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/shell/types.ts"],"names":[],"mappings":"AAAA,wCAAwC;AAExC,sEAAsE;AACtE,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC;QACE,KAAK,CAAC,iBAAiB,CAAC,CAAC;QACzB,yEAAyE;QACzE,yCAAyC;QACzC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAED,+DAA+D;AAC/D,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACrB,cAAc;IAAnC,YAAqB,cAAsB;QACzC,KAAK,CAAC,2BAA2B,cAAc,UAAU,CAAC,CAAC;8BADxC,cAAc;QAEjC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF"}

package/dist/tools/bash.d.ts

@@ -0,0 +1,42 @@
+import type { Tool, ToolContext, ToolOutput } from "./tool.js";
+import { type ShellOperations } from "../shell/types.js";
+/** How often a running command may push an output snapshot. */
+export declare const OUTPUT_UPDATE_THROTTLE_MS = 100;
+export interface BashToolOptions {
+    readonly cwd: string;
+    /** Swap in a container or SSH backend without touching the tool. */
+    readonly operations?: ShellOperations;
+    readonly maxLines?: number;
+    readonly maxBytes?: number;
+    readonly tempDirectory?: string;
+    readonly throttleMs?: number;
+}
+export declare class BashTool implements Tool {
+    readonly name = "bash";
+    readonly description = "Run a shell command in the workspace root and return its combined stdout and stderr. Output is truncated to the last part of the run; the full output is written to a temp file when that happens. Not interactive: commands get no stdin.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly command: {
+                readonly type: "string";
+                readonly description: "Shell command to run in the workspace root. Not interactive: it has no stdin.";
+            };
+            readonly timeout: {
+                readonly type: "number";
+                readonly description: "Optional timeout in seconds. There is no default; set one for commands that may hang.";
+            };
+        };
+        readonly required: readonly ["command"];
+        readonly additionalProperties: false;
+    };
+    private readonly cwd;
+    private readonly operations;
+    private readonly maxLines?;
+    private readonly maxBytes?;
+    private readonly tempDirectory?;
+    private readonly throttleMs;
+    constructor(options: BashToolOptions);
+    execute(argumentsValue: unknown, context: ToolContext): Promise<ToolOutput>;
+    private finish;
+}
+//# sourceMappingURL=bash.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bash.d.ts","sourceRoot":"","sources":["../../src/tools/bash.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAI/D,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAE3B,+DAA+D;AAC/D,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAyB7C,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,qBAAa,QAAS,YAAW,IAAI;IACnC,QAAQ,CAAC,IAAI,UAAU;IACvB,QAAQ,CAAC,WAAW,gPAC2N;IAC/O,QAAQ,CAAC,WAAW;uBApCd,QAAQ;;qBAEZ,OAAO;yBACL,IAAI,EAAE,QAAQ;yBACd,WAAW,EACT,+EAA+E;;qBAEnF,OAAO;yBACL,IAAI,EAAE,QAAQ;yBACd,WAAW,EACT,uFAAuF;;;qCAGlF,SAAS;;MAuBe;IAEnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkB;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,YAAY,OAAO,EAAE,eAAe,EAanC;IAEK,OAAO,CACX,cAAc,EAAE,OAAO,EACvB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,UAAU,CAAC,CAmFrB;YAEa,MAAM;CAWrB"}