@smooai/smooth-operator-core 0.9.0 → 0.10.1

package/dist/extension/manifest.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Extension manifests — `extension.toml` discovery, merge, and `${env:VAR}`
+ * expansion. The TS sibling of the Rust host's `extension/manifest.rs`.
+ *
+ * - An extension lives in a directory holding an `extension.toml`.
+ * - Global extensions: `~/.smooth/extensions/<name>/extension.toml`
+ *   (or `$SMOOTH_HOME/extensions/...`).
+ * - Project extensions: `<workspace>/.smooth/extensions/<name>/extension.toml`.
+ * - On a name collision the **project entry wins** (the mcp.toml / plugin.toml
+ *   merge rule).
+ * - `[run] env` values support `${env:VAR}` expansion so secrets stay out of the
+ *   manifest.
+ * - A single malformed manifest is tolerated: it is collected as a failure and
+ *   the rest still load.
+ */
+/**
+ * Where a manifest was discovered. Project extensions only load in trusted
+ * workspaces; the host uses this to apply that policy.
+ */
+export type Scope = 'global' | 'project';
+/** How to launch the extension subprocess. */
+export interface RunSpec {
+    /** Executable to spawn (e.g. `node`, `python3`, an absolute path). */
+    command: string;
+    args: string[];
+    /** Extra env vars; values may reference `${env:VAR}`. */
+    env: Record<string, string>;
+}
+/**
+ * Capability declarations. The `events` list doubles as the host's dispatch
+ * filter — an extension only receives events it names here.
+ */
+export interface Capabilities {
+    events: string[];
+    tools: boolean;
+    commands: boolean;
+    ui: boolean;
+    exec: boolean;
+    kv: boolean;
+    bus: boolean;
+    session: boolean;
+}
+/** Resource directories the extension contributes (skills, prompts, themes). */
+export interface Resources {
+    skills?: string;
+    prompts?: string;
+    themes?: string;
+}
+/** A parsed `extension.toml`. */
+export interface ExtensionManifest {
+    name: string;
+    version: string;
+    /** Highest SEP protocol version the extension declares. Defaults to 1. */
+    protocol: number;
+    run: RunSpec;
+    capabilities: Capabilities;
+    resources: Resources;
+    /** Per-extension hook timeout override, in milliseconds. */
+    hookTimeoutMs?: number;
+    /** Optional: skip this extension without deleting its manifest. */
+    disabled: boolean;
+}
+/**
+ * A discovered extension: its manifest plus the directory it was found in
+ * (relative resources and `args` resolve against this root) and its scope.
+ */
+export interface DiscoveredExtension {
+    manifest: ExtensionManifest;
+    root: string;
+    scope: Scope;
+}
+/** A `(source, error message)` pair for a manifest that failed to parse. */
+export type ManifestFailure = [source: string, error: string];
+/**
+ * Parse a manifest from TOML text. Throws when the TOML is malformed or the
+ * required `name` / `version` / `[run] command` fields are missing — the same
+ * required set the Rust serde struct enforces.
+ */
+export declare function parseManifest(tomlText: string): ExtensionManifest;
+/** Load a manifest from `<dir>/extension.toml`. Throws if missing or malformed. */
+export declare function loadManifestDir(dir: string): ExtensionManifest;
+/**
+ * Return the `[run] env` map with `${env:VAR}` references expanded against the
+ * host's current environment. Unset variables expand to empty strings.
+ */
+export declare function resolvedEnv(manifest: ExtensionManifest): Record<string, string>;
+/**
+ * Default global extensions directory: `$SMOOTH_HOME/extensions` if set, else
+ * `~/.smooth/extensions`.
+ */
+export declare function defaultGlobalDir(): string | undefined;
+/** The project extensions directory for a workspace root. */
+export declare function projectDir(workspaceRoot: string): string;
+/**
+ * Discover every extension under `globalDir` and `projectDir`, merging by name
+ * with **project winning**. Either directory may be `undefined` or missing
+ * (treated as empty). Returns the chosen extensions plus a list of
+ * `(source, error)` for manifests that failed to parse — a single bad manifest
+ * never aborts discovery.
+ */
+export declare function discover(globalDir: string | undefined, projectDirPath: string | undefined): {
+    extensions: DiscoveredExtension[];
+    failures: ManifestFailure[];
+};
+/**
+ * Expand `${env:VAR}` references using the host's current environment. Unset
+ * variables expand to empty strings. Mirrors the Rust/MCP loader so the two
+ * config surfaces behave identically.
+ */
+export declare function expandEnv(input: string): string;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/extension/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/extension/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAOH;;;GAGG;AACH,MAAM,MAAM,KAAK,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEzC,8CAA8C;AAC9C,MAAM,WAAW,OAAO;IACpB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IACzB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,OAAO,CAAC;IACd,EAAE,EAAE,OAAO,CAAC;IACZ,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CACpB;AAED,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,iCAAiC;AACjC,MAAM,WAAW,iBAAiB;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,OAAO,CAAC;IACb,YAAY,EAAE,YAAY,CAAC;IAC3B,SAAS,EAAE,SAAS,CAAC;IACrB,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,EAAE,OAAO,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAChC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;CAChB;AAED,4EAA4E;AAC5E,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAc9D;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAwCjE;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAG9D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAI/E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAKrD;AAED,6DAA6D;AAC7D,wBAAgB,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,cAAc,EAAE,MAAM,GAAG,SAAS,GAAG;IAAE,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAAC,QAAQ,EAAE,eAAe,EAAE,CAAA;CAAE,CAgB9J;AAgCD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAmB/C"}

package/dist/extension/manifest.js

@@ -0,0 +1,190 @@
+/**
+ * Extension manifests — `extension.toml` discovery, merge, and `${env:VAR}`
+ * expansion. The TS sibling of the Rust host's `extension/manifest.rs`.
+ *
+ * - An extension lives in a directory holding an `extension.toml`.
+ * - Global extensions: `~/.smooth/extensions/<name>/extension.toml`
+ *   (or `$SMOOTH_HOME/extensions/...`).
+ * - Project extensions: `<workspace>/.smooth/extensions/<name>/extension.toml`.
+ * - On a name collision the **project entry wins** (the mcp.toml / plugin.toml
+ *   merge rule).
+ * - `[run] env` values support `${env:VAR}` expansion so secrets stay out of the
+ *   manifest.
+ * - A single malformed manifest is tolerated: it is collected as a failure and
+ *   the rest still load.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { parse as parseToml } from 'smol-toml';
+function asString(v, fallback = '') {
+    return typeof v === 'string' ? v : fallback;
+}
+function asStringArray(v) {
+    return Array.isArray(v) ? v.filter((x) => typeof x === 'string') : [];
+}
+function asBool(v) {
+    return v === true;
+}
+/**
+ * Parse a manifest from TOML text. Throws when the TOML is malformed or the
+ * required `name` / `version` / `[run] command` fields are missing — the same
+ * required set the Rust serde struct enforces.
+ */
+export function parseManifest(tomlText) {
+    const raw = parseToml(tomlText);
+    const name = asString(raw.name);
+    const version = asString(raw.version);
+    if (!name || !version)
+        throw new Error('extension.toml: `name` and `version` are required');
+    const runRaw = (raw.run ?? {});
+    const command = asString(runRaw.command);
+    if (!command)
+        throw new Error('extension.toml: `[run] command` is required');
+    const envRaw = (runRaw.env ?? {});
+    const env = {};
+    for (const [k, val] of Object.entries(envRaw))
+        env[k] = asString(val, String(val));
+    const capRaw = (raw.capabilities ?? {});
+    const resRaw = (raw.resources ?? {});
+    const manifest = {
+        name,
+        version,
+        protocol: typeof raw.protocol === 'number' ? raw.protocol : 1,
+        run: { command, args: asStringArray(runRaw.args), env },
+        capabilities: {
+            events: asStringArray(capRaw.events),
+            tools: asBool(capRaw.tools),
+            commands: asBool(capRaw.commands),
+            ui: asBool(capRaw.ui),
+            exec: asBool(capRaw.exec),
+            kv: asBool(capRaw.kv),
+            bus: asBool(capRaw.bus),
+            session: asBool(capRaw.session),
+        },
+        resources: {
+            skills: typeof resRaw.skills === 'string' ? resRaw.skills : undefined,
+            prompts: typeof resRaw.prompts === 'string' ? resRaw.prompts : undefined,
+            themes: typeof resRaw.themes === 'string' ? resRaw.themes : undefined,
+        },
+        disabled: asBool(raw.disabled),
+    };
+    if (typeof raw.hook_timeout_ms === 'number')
+        manifest.hookTimeoutMs = raw.hook_timeout_ms;
+    return manifest;
+}
+/** Load a manifest from `<dir>/extension.toml`. Throws if missing or malformed. */
+export function loadManifestDir(dir) {
+    const path = join(dir, 'extension.toml');
+    return parseManifest(readFileSync(path, 'utf8'));
+}
+/**
+ * Return the `[run] env` map with `${env:VAR}` references expanded against the
+ * host's current environment. Unset variables expand to empty strings.
+ */
+export function resolvedEnv(manifest) {
+    const out = {};
+    for (const [k, v] of Object.entries(manifest.run.env))
+        out[k] = expandEnv(v);
+    return out;
+}
+/**
+ * Default global extensions directory: `$SMOOTH_HOME/extensions` if set, else
+ * `~/.smooth/extensions`.
+ */
+export function defaultGlobalDir() {
+    const home = process.env.SMOOTH_HOME;
+    if (home)
+        return join(home, 'extensions');
+    const h = homedir();
+    return h ? join(h, '.smooth', 'extensions') : undefined;
+}
+/** The project extensions directory for a workspace root. */
+export function projectDir(workspaceRoot) {
+    return join(workspaceRoot, '.smooth', 'extensions');
+}
+/**
+ * Discover every extension under `globalDir` and `projectDir`, merging by name
+ * with **project winning**. Either directory may be `undefined` or missing
+ * (treated as empty). Returns the chosen extensions plus a list of
+ * `(source, error)` for manifests that failed to parse — a single bad manifest
+ * never aborts discovery.
+ */
+export function discover(globalDir, projectDirPath) {
+    const failures = [];
+    const byName = new Map();
+    // Global first, then project, so project overwrites on name collision.
+    for (const [dir, scope] of [
+        [globalDir, 'global'],
+        [projectDirPath, 'project'],
+    ]) {
+        if (!dir)
+            continue;
+        for (const found of scanDir(dir, scope, failures))
+            byName.set(found.manifest.name, found);
+    }
+    // Stable order so load-order-dependent hook chaining is deterministic.
+    const extensions = [...byName.values()].sort((a, b) => a.manifest.name.localeCompare(b.manifest.name));
+    return { extensions, failures };
+}
+/**
+ * Scan a single extensions directory: each immediate subdirectory holding an
+ * `extension.toml` is one extension.
+ */
+function scanDir(dir, scope, failures) {
+    const out = [];
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        // Missing dir is not an error — just no extensions from this scope.
+        return out;
+    }
+    for (const entry of entries) {
+        const root = join(dir, entry);
+        try {
+            if (!statSync(root).isDirectory())
+                continue;
+            if (!statSync(join(root, 'extension.toml')).isFile())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        try {
+            out.push({ manifest: loadManifestDir(root), root, scope });
+        }
+        catch (e) {
+            failures.push([root, e instanceof Error ? e.message : String(e)]);
+        }
+    }
+    return out;
+}
+/**
+ * Expand `${env:VAR}` references using the host's current environment. Unset
+ * variables expand to empty strings. Mirrors the Rust/MCP loader so the two
+ * config surfaces behave identically.
+ */
+export function expandEnv(input) {
+    let out = '';
+    let rest = input;
+    for (;;) {
+        const idx = rest.indexOf('${env:');
+        if (idx === -1)
+            break;
+        out += rest.slice(0, idx);
+        const after = rest.slice(idx + 6);
+        const end = after.indexOf('}');
+        if (end === -1) {
+            // Unterminated reference — keep it verbatim and stop.
+            out += rest.slice(idx);
+            return out;
+        }
+        const varName = after.slice(0, end);
+        out += process.env[varName] ?? '';
+        rest = after.slice(end + 1);
+    }
+    return out + rest;
+}
+//# sourceMappingURL=manifest.js.map

package/dist/extension/manifest.js.map

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

package/dist/extension/process.d.ts

@@ -0,0 +1,118 @@
+/**
+ * `ExtensionProcess` — one extension subprocess, its ndjson codec, and its
+ * request/response plumbing. The TS sibling of the Rust host's
+ * `extension/process.rs`.
+ *
+ * Framing is identical to MCP stdio: one JSON-RPC message per line on the child's
+ * stdin/stdout, stderr drained to host logging. Inbound responses route to their
+ * pending caller; inbound requests go to an {@link InboundHandler}.
+ *
+ * Restart is in-place ({@link ExtensionProcess.respawn}): a generation counter is
+ * bumped so a stale reader from the dead child can't resolve a request registered
+ * against the new child, and every in-flight request fails fast.
+ */
+/**
+ * Backoff schedule (ms) for restart attempts. After the third failed attempt the
+ * host marks the extension failed and stops trying.
+ */
+export declare const RESTART_BACKOFFS_MS: readonly number[];
+/** Idle interval (ms) after which the host should health-probe with `ping`. */
+export declare const PING_IDLE_MS = 60000;
+/**
+ * Bounded depth of the per-connection observe (`event`) lane. When a slow or
+ * stalled extension lets events pile past this, the OLDEST are shed and an
+ * `events_lost` marker is delivered on recovery — observe events are lossy by
+ * contract. Requests (hook/tool/ping/shutdown) are NEVER shed; they ride the
+ * reliable control lane (a direct stdin write).
+ */
+export declare const OBSERVE_QUEUE_CAP = 1024;
+/**
+ * Backoff (ms) for restart `attempt` (0-indexed). `undefined` once attempts are
+ * exhausted — the caller transitions the extension to failed.
+ */
+export declare function backoffFor(attempt: number): number | undefined;
+/**
+ * Handles ext→host requests and notifications. The default answers `ping` and
+ * rejects everything else with MethodNotFound; the host supplies a richer impl
+ * once ext→host methods (session/ui/kv/…) are wired.
+ */
+export interface InboundHandler {
+    handleRequest(method: string, params: unknown): Promise<unknown>;
+    handleNotification(method: string, params: unknown): void;
+}
+/** The trivial handler: ping only. Used when the host wires nothing richer. */
+export declare class DefaultInboundHandler implements InboundHandler {
+    handleRequest(method: string, _params: unknown): Promise<unknown>;
+    handleNotification(_method: string, _params: unknown): void;
+}
+/** How to launch the subprocess. The manifest owns the full shape; this is what `spawn` needs. */
+export interface SpawnSpec {
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+    /** Working directory for the child (the extension's root). */
+    cwd?: string;
+}
+/** One extension subprocess. */
+export declare class ExtensionProcess {
+    private readonly spec;
+    private readonly handler;
+    private readonly pending;
+    private generation;
+    private nextId;
+    private alive;
+    private conn;
+    private constructor();
+    /** Spawn the subprocess and start its reader. Throws if it can't be spawned. */
+    static spawn(spec: SpawnSpec, handler: InboundHandler): ExtensionProcess;
+    private startConnection;
+    /** Parse and route one inbound line. */
+    private dispatchLine;
+    private handleInboundRequest;
+    /**
+     * Send a request and await its response, bounded by `timeoutMs`. Rejects if
+     * the connection is dead, the request times out (it also sends `$/cancel`), or
+     * the extension replies with a JSON-RPC error.
+     */
+    request(method: string, params: unknown, timeoutMs: number): Promise<unknown>;
+    /**
+     * Best-effort `$/cancel` for an in-flight request `id`. The peer SHOULD stop
+     * work; a cancel for an already-answered id is a harmless no-op.
+     */
+    cancel(id: number): void;
+    /** Send a fire-and-forget notification on the reliable control lane. */
+    notify(method: string, params: unknown): void;
+    /**
+     * Enqueue an observe `event` on the bounded, lossy lane. Assigns the frame a
+     * per-connection sequence; sheds the oldest queued event (tracked for the next
+     * `events_lost` marker) rather than block or grow unbounded when the extension
+     * is not draining its stdin. Never throws — a shed event is the contract.
+     */
+    sendEvent(event: string, context: unknown, payload: unknown): void;
+    /** Whether the connection is currently believed alive. */
+    isAlive(): boolean;
+    /** Current generation (increments on every successful respawn). */
+    getGeneration(): number;
+    /** Health-probe with `ping`; resolves `true` if answered within `timeoutMs`. */
+    pingHealth(timeoutMs: number): Promise<boolean>;
+    /**
+     * Kill and re-spawn the child in place. Bumps the generation (invalidating any
+     * stale reader and failing every in-flight request), then starts a fresh
+     * connection. `nextId` is NOT reset, so ids never collide across generations.
+     */
+    respawn(): void;
+    /**
+     * Graceful shutdown: send `shutdown`, wait up to `graceMs` for the reply, then
+     * force-kill. Always leaves the process dead.
+     */
+    shutdown(graceMs: number): Promise<void>;
+    /** Serialize a frame as ndjson to the child stdin. Returns false on any error. */
+    private writeFrame;
+    /** Drain the observe lane to stdin, honoring backpressure via `drain`. */
+    private pumpObserve;
+    /** Fail every pending request with the same error message. */
+    private failAllPending;
+    /** Tear down the current connection's child + readers. */
+    private abortConnection;
+}
+//# sourceMappingURL=process.d.ts.map

package/dist/extension/process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../../src/extension/process.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,MAAM,EAAwB,CAAC;AAE1E,+EAA+E;AAC/E,eAAO,MAAM,YAAY,QAAS,CAAC;AAEnC;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE9D;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC3B,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CAC7D;AAED,+EAA+E;AAC/E,qBAAa,qBAAsB,YAAW,cAAc;IAClD,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAIvE,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;CAC9D;AAED,kGAAkG;AAClG,MAAM,WAAW,SAAS;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,8DAA8D;IAC9D,GAAG,CAAC,EAAE,MAAM,CAAC;CAChB;AAkED,gCAAgC;AAChC,qBAAa,gBAAgB;IAQrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAR5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IACtD,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,IAAI,CAAa;IAEzB,OAAO;IAOP,gFAAgF;IAChF,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,gBAAgB;IAIxE,OAAO,CAAC,eAAe;IAsCvB,wCAAwC;IACxC,OAAO,CAAC,YAAY;YA2BN,oBAAoB;IAYlC;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAsB7E;;;OAGG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIxB,wEAAwE;IACxE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI;IAI7C;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAKlE,0DAA0D;IAC1D,OAAO,IAAI,OAAO;IAIlB,mEAAmE;IACnE,aAAa,IAAI,MAAM;IAIvB,gFAAgF;IAC1E,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASrD;;;;OAIG;IACH,OAAO,IAAI,IAAI;IASf;;;OAGG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU9C,kFAAkF;IAClF,OAAO,CAAC,UAAU;IAclB,0EAA0E;IAC1E,OAAO,CAAC,WAAW;IA4BnB,8DAA8D;IAC9D,OAAO,CAAC,cAAc;IAStB,0DAA0D;IAC1D,OAAO,CAAC,eAAe;CAY1B"}