@hy-sde-org/dsh-code-runtime-kernels 0.1.0-rc.8

package/dist/core/protocol.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Versionless, hostile-peer wire protocol shared by the persistent Node.js and Python kernels.
+ * The host treats every kernel frame as forged (the peer runs MODEL CODE and
+ * can emit anything); inbound frames are re-validated field by field before
+ * use. The kernel-side reader is our co-shipped code and may trust host
+ * messages, mirroring the worker-thread backend's asymmetry. Both
+ * process-boundary kernels speak the same NDJSON shape, so the single host
+ * driver in `kernel.ts` stays generic.
+ * @module @hy-sde-org/dsh-code-runtime-kernels/src/core/protocol
+ */
+import type { CodeBindingErrorClass, CodeJsonValue } from '@deepseek-ai/dsh-code-runtime';
+/** One binding global materialized inside the kernel for a run. */
+export interface KernelNamespaceDescriptor {
+    /** The program-visible global identifier (validated by the provider). */
+    global: string;
+    /** The callable member names; functions themselves stay host-side. */
+    names: string[];
+    /** Optional typed-rejection contract (name + member-name property). */
+    errorClass?: CodeBindingErrorClass;
+}
+/** Host -> kernel: execute one program against this run's namespaces. */
+export interface KernelExecMessage {
+    type: 'exec';
+    /** Run correlation id (a non-empty string, e.g. the session's run id). */
+    id: string;
+    /** The program source, body-of-async-function semantics, kernel language. */
+    code: string;
+    /** Binding globals to materialize for this run. */
+    namespaces: KernelNamespaceDescriptor[];
+    /** Optional working directory applied before execution. */
+    cwd?: string;
+    /** Optional environment overrides applied before execution. */
+    env?: Record<string, string>;
+}
+/** Host -> kernel: the answer to one {@link KernelCallFrame}. */
+export interface KernelReplyMessage {
+    type: 'reply';
+    id: string;
+    /** The call's correlation sequence, echoed from the frame. */
+    seq: number;
+    ok: boolean;
+    /** The lossless-JSON resolution, present when `ok` is true. */
+    value?: CodeJsonValue;
+    /** The rejection message, present when `ok` is false. */
+    message?: string;
+    /** The rejected member name, surfaced onto the program-side error. */
+    name?: string;
+}
+/** Host -> kernel: graceful shutdown request. */
+export interface KernelExitMessage {
+    type: 'exit';
+}
+/** Every message the host sends. */
+export type KernelHostMessage = KernelExecMessage | KernelReplyMessage | KernelExitMessage;
+/** Kernel -> host: the bootstrap handshake, emitted once at startup. */
+export interface ReadyFrame {
+    type: 'ready';
+    pid: number;
+}
+/** Kernel -> host: a run accepted the exec frame. */
+export interface StartedFrame {
+    type: 'started';
+    id: string;
+}
+/** Kernel -> host: captured program output for a run. */
+export interface LogFrame {
+    type: 'log';
+    id: string;
+    text: string;
+    /** 'stdout' or 'stderr'; purely informational, both land in `logs`. */
+    stream?: string;
+}
+/** Kernel -> host: the program invoked one binding call. */
+export interface CallFrame {
+    type: 'call';
+    id: string;
+    seq: number;
+    /** The namespace global the call targets. */
+    global: string;
+    /** The member name within the namespace. */
+    name: string;
+    /** The single argument, already lossless JSON. */
+    args: CodeJsonValue;
+}
+/** Kernel -> host: an uncaught program exception. */
+export interface ErrorFrame {
+    type: 'error';
+    id: string;
+    ename: string;
+    evalue: string;
+    traceback: string[];
+}
+/**
+ * Kernel -> host: the run settled. Program failures (exception, invalid
+ * completion) land here as `status: 'error'`; budget/abort/substrate outcomes
+ * are observed host-side (a cancelled run carries `cancelled: true`).
+ */
+export interface DoneFrame {
+    type: 'done';
+    id: string;
+    status: 'ok' | 'error';
+    /** The lossless-JSON completion value, present on a clean run with one. */
+    value?: CodeJsonValue;
+    /** The session's execution count after this run; informational. */
+    executionCount?: number;
+    /** True when the host interrupted the run. */
+    cancelled?: boolean;
+    /** True when the completion could not be represented as lossless JSON. */
+    invalidOutput?: boolean;
+    /** The failure or protocol message, when any. */
+    message?: string;
+}
+/** Every frame the kernel sends. */
+export type KernelFrame = ReadyFrame | StartedFrame | LogFrame | CallFrame | ErrorFrame | DoneFrame;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/core/protocol.d.ts.map

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

package/dist/core/protocol.js

@@ -0,0 +1,12 @@
+/**
+ * Versionless, hostile-peer wire protocol shared by the persistent Node.js and Python kernels.
+ * The host treats every kernel frame as forged (the peer runs MODEL CODE and
+ * can emit anything); inbound frames are re-validated field by field before
+ * use. The kernel-side reader is our co-shipped code and may trust host
+ * messages, mirroring the worker-thread backend's asymmetry. Both
+ * process-boundary kernels speak the same NDJSON shape, so the single host
+ * driver in `kernel.ts` stays generic.
+ * @module @hy-sde-org/dsh-code-runtime-kernels/src/core/protocol
+ */
+export {};
+//# sourceMappingURL=protocol.js.map

package/dist/core/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/core/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/core/session.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Persistent-session registry, language-generic (shared by the Python and
+ * JavaScript kernels). Maps a `sessionId` to one kernel whose namespace and
+ * event-loop state survive every run in the session; on `reset` the old kernel
+ * is shut down before a fresh one answers; at disposal every kernel is
+ * terminated to quiescence. One exec at a time per session (a kernel
+ * serializes stdin), so concurrent runs for the same session queue on a
+ * per-session promise chain.
+ * @module @hy-sde-org/dsh-code-runtime-kernels/src/core/session
+ */
+import type { CodeBindingNamespace } from '@deepseek-ai/dsh-code-runtime';
+import type { KernelExecResult, KernelHost } from './kernel.ts';
+/** Session-management knobs on top of the per-kernel start config. */
+export interface SessionRegistryConfig {
+    /** Label for error messages (e.g. `python kernel`). */
+    label: string;
+    /** Spawn a fresh kernel for a newly acquired session (provider-resolved executable + timeouts). */
+    start: () => Promise<KernelHost>;
+    /** Reap a session whose kernel sits unused for this long; 0 disables. */
+    sessionIdleMs: number;
+}
+/** Options for one registered-session run. */
+export interface SessionRunOptions {
+    /** Discard prior kernel state and start fresh before this run. */
+    reset?: boolean;
+    /** Abort source; SIGINT is raised inside the kernel on abort. */
+    signal?: AbortSignal;
+    /** Per-run working directory override. */
+    cwd?: string;
+    /** Per-run environment overrides. */
+    env?: Record<string, string>;
+}
+/**
+ * Registers sessions and schedules every run onto its session's serialization
+ * tail. A session kernel that died mid-run (or was killed settling a prior
+ * run) is replaced with a fresh one and the run retried once, like omp's
+ * kernel-session registry — state loss on a hard kill is the accepted cost.
+ */
+export declare class SessionRegistry {
+    #private;
+    constructor(config: SessionRegistryConfig);
+    /** Register (or return) the session for an id and run the work on its tail. */
+    executeOnSession(sessionId: string, code: string, bindings: CodeBindingNamespace[], options?: SessionRunOptions): Promise<KernelExecResult>;
+    /** Shut down and drop one session's kernel. */
+    close(sessionId: string): Promise<void>;
+    /** Terminate every kernel and drop every session (runtime disposal). */
+    disposeAll(): Promise<void>;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/core/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/core/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AACzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAW/D,sEAAsE;AACtE,MAAM,WAAW,qBAAqB;IACpC,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAA;IACb,mGAAmG;IACnG,KAAK,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAA;IAChC,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,iEAAiE;IACjE,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,qCAAqC;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC7B;AAED;;;;;GAKG;AACH,qBAAa,eAAe;;gBAKd,MAAM,EAAE,qBAAqB;IAIzC,+EAA+E;IACzE,gBAAgB,CACpB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,oBAAoB,EAAE,EAChC,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,gBAAgB,CAAC;IAsB5B,+CAA+C;IACzC,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU7C,wEAAwE;IAClE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAqGlC"}

package/dist/core/session.js

@@ -0,0 +1,153 @@
+/**
+ * Persistent-session registry, language-generic (shared by the Python and
+ * JavaScript kernels). Maps a `sessionId` to one kernel whose namespace and
+ * event-loop state survive every run in the session; on `reset` the old kernel
+ * is shut down before a fresh one answers; at disposal every kernel is
+ * terminated to quiescence. One exec at a time per session (a kernel
+ * serializes stdin), so concurrent runs for the same session queue on a
+ * per-session promise chain.
+ * @module @hy-sde-org/dsh-code-runtime-kernels/src/core/session
+ */
+/**
+ * Registers sessions and schedules every run onto its session's serialization
+ * tail. A session kernel that died mid-run (or was killed settling a prior
+ * run) is replaced with a fresh one and the run retried once, like omp's
+ * kernel-session registry — state loss on a hard kill is the accepted cost.
+ */
+export class SessionRegistry {
+    #sessions = new Map();
+    #config;
+    #disposed = false;
+    constructor(config) {
+        this.#config = config;
+    }
+    /** Register (or return) the session for an id and run the work on its tail. */
+    async executeOnSession(sessionId, code, bindings, options = {}) {
+        if (this.#disposed) {
+            return {
+                status: 'error', logs: [], cancelled: false, invalidOutput: false,
+                message: `${this.#config.label} session registry disposed`, killed: true,
+            };
+        }
+        let session = this.#sessions.get(sessionId);
+        if (session === undefined) {
+            session = { kernel: null, queue: Promise.resolve() };
+            this.#sessions.set(sessionId, session);
+        }
+        const run = () => this.#runOnSession(session, sessionId, code, bindings, options);
+        session.queue = session.queue.then(run, run);
+        try {
+            return (await session.queue);
+        }
+        finally {
+            this.#maybeReap(sessionId);
+        }
+    }
+    /** Shut down and drop one session's kernel. */
+    async close(sessionId) {
+        const session = this.#sessions.get(sessionId);
+        if (session === undefined)
+            return;
+        this.#sessions.delete(sessionId);
+        clearTimeout(session.idleTimer);
+        const kernel = session.kernel;
+        session.kernel = null;
+        if (kernel !== null)
+            await kernel.shutdown().catch(() => { });
+    }
+    /** Terminate every kernel and drop every session (runtime disposal). */
+    async disposeAll() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        const sessions = [...this.#sessions.values()];
+        this.#sessions.clear();
+        const kernels = [];
+        for (const session of sessions) {
+            clearTimeout(session.idleTimer);
+            if (session.kernel !== null)
+                kernels.push(session.kernel);
+            session.kernel = null;
+        }
+        await Promise.allSettled(kernels.map(kernel => kernel.shutdown()));
+    }
+    #maybeReap(sessionId) {
+        if (this.#disposed)
+            return;
+        if (this.#config.sessionIdleMs <= 0)
+            return;
+        const session = this.#sessions.get(sessionId);
+        if (session === undefined || session.kernel === null)
+            return;
+        clearTimeout(session.idleTimer);
+        session.idleTimer = setTimeout(() => {
+            void this.close(sessionId);
+        }, this.#config.sessionIdleMs);
+        session.idleTimer.unref();
+    }
+    async #acquireKernel(sessionId, session) {
+        if (session.kernel !== null && session.kernel.isAlive())
+            return session.kernel;
+        const previous = session.kernel;
+        if (previous !== null) {
+            await previous.shutdown().catch(() => { });
+            session.kernel = null;
+        }
+        if (this.#disposed) {
+            throw new Error(`${this.#config.label} session registry disposed while acquiring kernel`);
+        }
+        if (this.#sessions.get(sessionId) !== session) {
+            throw new Error(`${this.#config.label} session invalidated while acquiring kernel`);
+        }
+        const kernel = await this.#config.start();
+        // oxlint-disable-next-line typescript/no-unnecessary-condition -- set by disposeAll elsewhere
+        if (this.#disposed) {
+            await kernel.shutdown().catch(() => { });
+            throw new Error(`${this.#config.label} session registry disposed while acquiring kernel`);
+        }
+        if (this.#sessions.get(sessionId) !== session) {
+            await kernel.shutdown().catch(() => { });
+            throw new Error(`${this.#config.label} session invalidated while acquiring kernel`);
+        }
+        session.kernel = kernel;
+        return kernel;
+    }
+    async #runOnSession(session, sessionId, code, bindings, options) {
+        if (options.reset === true) {
+            // Reset first, then acquire: prior kernel state is discarded and its
+            // shutdown completes before the fresh kernel answers this run.
+            const previous = session.kernel;
+            if (previous !== null) {
+                session.kernel = null;
+                clearTimeout(session.idleTimer);
+                await previous.shutdown().catch(() => { });
+            }
+        }
+        let kernel = await this.#acquireKernel(sessionId, session);
+        const first = await this.#executeOnce(kernel, sessionId, code, bindings, options);
+        // A kernel that died or was killed settling the run is replaced once and
+        // the run retried; otherwise return what we got.
+        const needsRetry = first.killed && session === this.#sessions.get(sessionId);
+        if (!needsRetry)
+            return first;
+        await kernel.shutdown().catch(() => { });
+        if (session !== this.#sessions.get(sessionId))
+            return first;
+        kernel = await this.#acquireKernel(sessionId, session);
+        const second = await this.#executeOnce(kernel, sessionId, code, bindings, options);
+        if (second.killed) {
+            // Give up restoring state: report the second outcome with the first's
+            // message so the caller sees that retries also died.
+            return { ...second, message: second.message || first.message };
+        }
+        return second;
+    }
+    #executeOnce(kernel, sessionId, code, bindings, options) {
+        return kernel.execute(sessionId, code, bindings, {
+            ...options.signal !== undefined ? { signal: options.signal } : {},
+            ...options.cwd !== undefined ? { cwd: options.cwd } : {},
+            ...options.env !== undefined ? { env: options.env } : {},
+        });
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/core/session.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,135 @@
+/**
+ * `run_kernel_code` — the persistent kernel tool for DeepSeek Harness,
+ * self-contained (no upstream harness changes required, same as the sibling
+ * dsh-tool-ast plugin). One long-lived `python3` or `node` subprocess per
+ * `session` keeps state across calls; runs without a session are one-shot
+ * (a fresh kernel spawning for exactly one program). The host driver, session
+ * registry, and output ledger in `core/` are shared by both languages; each
+ * language's runner program lives in `src/python` / `src/nodejs`.
+ * This is process confinement, not a security boundary: model code has
+ * bash-equivalent trust.
+ * @module @hy-sde-org/dsh-code-runtime-kernels
+ */
+import { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { CodeBindingNamespace, CodeJsonValue, CodeRunResult } from '@deepseek-ai/dsh-code-runtime';
+import type { TerminalCallView, TerminalResultView, ToolResult } from '@deepseek-ai/dsh-tools';
+/** Cordis plugin name for loader diagnostics. */
+export declare const name = "code-runtime-kernels";
+/** Services this plugin requires: the tool registry and the system-prompt builder. */
+export declare const inject: readonly ["tools", "systemPrompt"];
+/**
+ * Plugin config: which languages are enabled, and every execution cap
+ * (changeable from any cordis.yml that mounts this plugin).
+ */
+export interface Config {
+    /** Enabled languages; kernels of disabled languages are refused at call time. */
+    languages?: ('python' | 'typescript')[];
+    /** Explicit python executable. Defaults to `python3` on PATH (fails loud at first spawn when absent). */
+    pythonPath?: string;
+    /** Explicit node executable. Defaults to `node` on PATH (fails loud at first spawn when absent). */
+    nodePath?: string;
+    /** Cooperative tool-call timeout budget (ms) for `run_kernel_code` (default 30000). */
+    toolTimeoutMs?: number;
+    /** Wall-clock ceiling per run: the backstop for a cell nothing can interrupt synchronously. */
+    maxWallMs?: number;
+    /** Hard cap on combined serialized log-, completion-, and failure-message bytes. */
+    maxOutputBytes?: number;
+    /** Reap a session idle for at least this many ms; `0` disables reaping. */
+    sessionIdleMs?: number;
+    /** Wait after SIGINT before SIGTERM, then the same again before SIGKILL. */
+    interruptEscalationMs?: number;
+    /** Wait for the bootstrap `ready` handshake before failing the kernel. */
+    startupTimeoutMs?: number;
+    /** Grace period for the kernel to exit after an `exit` frame. */
+    shutdownGraceMs?: number;
+}
+/** Schemastery schema for {@link Config}: defaults filled at load time. */
+export declare const Config: z<Config>;
+/** One run request against the persistent kernels; `sessionId`/`reset` mirror the seam's persistence contract. */
+export interface KernelRunRequest {
+    /** Which kernel to run the program in (`'python'` presents as `language: python`, `'typescript'` as the SDK). */
+    language: 'python' | 'typescript';
+    /** The program source. Typescript runs as an async-function body (top-level `await`/`return` work); python runs as a module (top-level `await` works, the last expression is the value). */
+    code: string;
+    /** Optional persistent-kernel identity: runs sharing one keep kernel state. */
+    sessionId?: string;
+    /** Discard the session's prior kernel state before this run. */
+    reset?: boolean;
+    /** Abort the run host-side; in-flight binding calls are the caller's to settle. */
+    signal?: AbortSignal;
+    /** Optional host functions exposed to the program, one global object per namespace. */
+    bindings?: CodeBindingNamespace[];
+}
+/**
+ * The outcome vocabulary of `run_kernel_code` and {@link KernelManager.run}:
+ * the code-execution seam's result envelope plus the session execution count
+ * (upstream's `CodeRunResult` has no persistent-session fields, so this plugin
+ * owns the additive `executionCount` surface).
+ */
+export type KernelRunResult = CodeRunResult & {
+    executionCount?: number;
+};
+/**
+ * Owns the two persistent kernel registries and maps one `KernelRunRequest`
+ * onto the same outcome vocabulary as the code-execution seam
+ * (`CodeRunResult` + `CodeRunFailure` kinds), so programs behave like the
+ * seam's persistent backends. Exported for programmatic use and the tests; the
+ * model-facing surface is the `run_kernel_code` tool registered in `apply`.
+ */
+export declare class KernelManager {
+    #private;
+    constructor(config: Config);
+    /** Terminate every session kernel to quiescence (plugin teardown). */
+    teardown(): Promise<void>;
+    /**
+     * Execute one program. Program outcomes resolve with `error` as a result
+     * field; the method rejects only for contract misuse (an unknown language, a
+     * disposed manager, an invalid binding namespace). With a non-empty
+     * `sessionId` the program runs in that session's persistent kernel and
+     * `executionCount` is reported; `reset: true` discards prior state first.
+     */
+    run(request: KernelRunRequest): Promise<KernelRunResult>;
+    /**
+     * Map a kernel outcome onto the failure taxonomy through the output ledger.
+     * Budget expiry owns a run that hit the wall clock (whether or not the
+     * kernel survived to acknowledge it); everything else interrupted is an
+     * abort; a died kernel is an abort unless the budget already owns the run.
+     */
+    private finalize;
+    /** Reject malformed binding globals or typed-error declarations as contract misuse. */
+    private validateBindings;
+}
+/** Tool argument records and output value types for `run_kernel_code`. */
+export interface RunKernelCodeArgs {
+    language: 'python' | 'typescript';
+    code: string;
+    session?: string;
+    reset?: boolean;
+}
+/** The value `run_kernel_code` resolves: the seam's result envelope plus the execution count. */
+export type RunKernelCodeValue = KernelRunResult;
+/** The persisted `presentationMeta` projection of one run result (a structurally-literal type so it stays JSON-value-assignable). */
+export type RunKernelCodeMeta = {
+    summary: string;
+    value?: CodeJsonValue;
+    error?: {
+        kind: string;
+        message: string;
+    };
+    executionCount?: number;
+    logs: string[];
+};
+/** Project the durable, replayable presentation payload for a completed run. */
+export declare function runKernelCodeMeta(value: RunKernelCodeValue): RunKernelCodeMeta;
+/** Present a pending `run_kernel_code` call as a terminal card (a cell is a foreground command). */
+export declare function presentRunKernelCodeCall(args: RunKernelCodeArgs): TerminalCallView;
+/** Present a completed run from its persisted meta as a terminal card, or undefined on failure. */
+export declare function presentRunKernelCodeResult(_args: RunKernelCodeArgs, result: ToolResult): TerminalResultView | undefined;
+/**
+ * Cordis plugin `apply`: resolve config, own the kernel manager (disposed with
+ * the plugin), and register `run_kernel_code` against `ctx.tools` so a plain
+ * upstream harness exposes the persistent kernels with zero source changes.
+ */
+export declare function apply(ctx: Context, config: Config): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC7C,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAOxC,OAAO,KAAK,EACV,oBAAoB,EACpB,aAAa,EAEb,aAAa,EACd,MAAM,+BAA+B,CAAA;AAEtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAO9F,iDAAiD;AACjD,eAAO,MAAM,IAAI,yBAAyB,CAAA;AAE1C,sFAAsF;AACtF,eAAO,MAAM,MAAM,oCAAqC,CAAA;AAExD;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,iFAAiF;IACjF,SAAS,CAAC,EAAE,CAAC,QAAQ,GAAG,YAAY,CAAC,EAAE,CAAA;IACvC,yGAAyG;IACzG,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,oGAAoG;IACpG,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uFAAuF;IACvF,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,+FAA+F;IAC/F,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,oFAAoF;IACpF,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,2EAA2E;IAC3E,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,4EAA4E;IAC5E,qBAAqB,CAAC,EAAE,MAAM,CAAA;IAC9B,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAUD,2EAA2E;AAC3E,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAW3B,CAAA;AAgBF,kHAAkH;AAClH,MAAM,WAAW,gBAAgB;IAC/B,iHAAiH;IACjH,QAAQ,EAAE,QAAQ,GAAG,YAAY,CAAA;IACjC,4LAA4L;IAC5L,IAAI,EAAE,MAAM,CAAA;IACZ,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,mFAAmF;IACnF,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,oBAAoB,EAAE,CAAA;CAClC;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG;IAAE,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA;AAsEzE;;;;;;GAMG;AACH,qBAAa,aAAa;;gBAMZ,MAAM,EAAE,MAAM;IAiD1B,sEAAsE;IAChE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAK/B;;;;;;OAMG;IACG,GAAG,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IAkG9D;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;IA2BhB,uFAAuF;IACvF,OAAO,CAAC,gBAAgB;CA6BzB;AAYD,0EAA0E;AAC1E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,QAAQ,GAAG,YAAY,CAAA;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,iGAAiG;AACjG,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAA;AAiBhD,qIAAqI;AACrI,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;IACzC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,IAAI,EAAE,MAAM,EAAE,CAAA;CACf,CAAA;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,kBAAkB,GAAG,iBAAiB,CAU9E;AAED,oGAAoG;AACpG,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,iBAAiB,GAAG,gBAAgB,CAMlF;AAED,mGAAmG;AACnG,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,iBAAiB,EAAE,MAAM,EAAE,UAAU,GAAG,kBAAkB,GAAG,SAAS,CAavH;AAED;;;;GAIG;AACH,wBAAsB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoEvE"}