@nookplot/runtime 0.5.123 → 0.5.124

package/dist/gpu.d.ts

@@ -0,0 +1,137 @@
+/**
+ * GPU marketplace manager for the Nookplot Agent Runtime SDK.
+ *
+ * Wraps GPU-specific operations: attestation (prepare+sign+relay),
+ * availability (heartbeats), and buyer challenges. Also provides
+ * read access to GPU listings and provider stats.
+ *
+ * @module gpu
+ */
+import type { ConnectionManager } from "./connection.js";
+/** Options for searching available GPUs. */
+export interface GpuSearchOptions {
+    gpuModel?: string;
+    minVram?: number;
+    status?: "online" | "degraded" | "any";
+    limit?: number;
+    offset?: number;
+}
+/** Input for submitting a GPU benchmark attestation. */
+export interface GpuAttestInput {
+    benchmarkHash: string;
+    gpuModel: string;
+    vramGb: number;
+    computeCapability?: string;
+    cudaVersion?: string;
+}
+/** Input for sending a heartbeat. */
+export interface GpuHeartbeatInput {
+    listingId: number;
+    status?: "idle" | "busy";
+    gpuModel?: string;
+    vramGb?: number;
+    gpuTempC?: number;
+    gpuUtilization?: number;
+    vramUsedGb?: number;
+    currentAgreementId?: number;
+}
+/** Input for renting a GPU (creating a service agreement). */
+export interface GpuRentInput {
+    listingId: number;
+    terms?: string;
+    durationHours?: number;
+    tokenAmount?: string;
+    tokenAddress?: string;
+}
+/** Input for batch GPU rental for swarms. */
+export interface GpuSwarmRentInput {
+    count: number;
+    minVram?: number;
+    gpuModel?: string;
+    terms?: string;
+    durationHours?: number;
+    tokenAmount?: string;
+}
+/** Input for creating a buyer challenge. */
+export interface GpuChallengeInput {
+    listingId: number;
+    providerAddress: string;
+    challengeInputCid: string;
+    expectedMinTflops?: number;
+}
+/** Input for submitting challenge results (provider). */
+export interface GpuChallengeSubmitInput {
+    challengeId: string;
+    challengeOutputCid: string;
+    actualTflops?: number;
+    wallTimeMs?: number;
+}
+export declare class GpuManager {
+    private readonly connection;
+    constructor(connection: ConnectionManager);
+    /**
+     * Search available GPUs with live status.
+     */
+    searchAvailable(opts?: GpuSearchOptions): Promise<unknown>;
+    /**
+     * Get availability for a specific listing.
+     */
+    getAvailability(listingId: number): Promise<unknown>;
+    /**
+     * Get a challenge by ID.
+     */
+    getChallenge(challengeId: string): Promise<unknown>;
+    /**
+     * Get a provider's challenge history and stats.
+     */
+    getProviderChallenges(address: string, limit?: number, offset?: number): Promise<unknown>;
+    /**
+     * Send a GPU heartbeat (provider).
+     */
+    heartbeat(input: GpuHeartbeatInput): Promise<unknown>;
+    /**
+     * Create a buyer challenge.
+     */
+    createChallenge(input: GpuChallengeInput): Promise<unknown>;
+    /**
+     * Submit challenge results (provider).
+     */
+    submitChallengeResult(input: GpuChallengeSubmitInput): Promise<unknown>;
+    /**
+     * Submit a GPU benchmark attestation on-chain.
+     */
+    submitAttestation(input: GpuAttestInput): Promise<{
+        txHash: string;
+    }>;
+    /**
+     * Update attestation with a new benchmark hash.
+     */
+    updateAttestation(benchmarkHash: string): Promise<{
+        txHash: string;
+    }>;
+    /**
+     * Revoke GPU attestation (voluntarily delist).
+     */
+    revokeAttestation(): Promise<{
+        txHash: string;
+    }>;
+    /**
+     * Rent a GPU by creating a ServiceMarketplace agreement.
+     * This is a convenience wrapper around the marketplace agreement flow
+     * specifically for GPU listings.
+     */
+    rentGpu(input: GpuRentInput): Promise<{
+        txHash: string;
+        agreementId?: string;
+    }>;
+    /**
+     * Rent multiple GPUs for a research swarm.
+     * Finds available GPUs matching criteria and creates agreements for each.
+     */
+    rentSwarmGpus(input: GpuSwarmRentInput): Promise<Array<{
+        listingId: number;
+        txHash: string;
+        error?: string;
+    }>>;
+}
+//# sourceMappingURL=gpu.d.ts.map

package/dist/gpu.d.ts.map

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

package/dist/gpu.js

@@ -0,0 +1,166 @@
+/**
+ * GPU marketplace manager for the Nookplot Agent Runtime SDK.
+ *
+ * Wraps GPU-specific operations: attestation (prepare+sign+relay),
+ * availability (heartbeats), and buyer challenges. Also provides
+ * read access to GPU listings and provider stats.
+ *
+ * @module gpu
+ */
+import { prepareSignRelay } from "./signing.js";
+export class GpuManager {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    // ============================================================
+    //  Read Operations
+    // ============================================================
+    /**
+     * Search available GPUs with live status.
+     */
+    async searchAvailable(opts) {
+        const params = new URLSearchParams();
+        if (opts?.gpuModel)
+            params.set("gpuModel", opts.gpuModel);
+        if (opts?.minVram !== undefined)
+            params.set("minVram", String(opts.minVram));
+        if (opts?.status)
+            params.set("status", opts.status);
+        if (opts?.limit !== undefined)
+            params.set("limit", String(opts.limit));
+        if (opts?.offset !== undefined)
+            params.set("offset", String(opts.offset));
+        const qs = params.toString();
+        return this.connection.request("GET", `/v1/gpu/availability${qs ? `?${qs}` : ""}`);
+    }
+    /**
+     * Get availability for a specific listing.
+     */
+    async getAvailability(listingId) {
+        return this.connection.request("GET", `/v1/gpu/availability/${listingId}`);
+    }
+    /**
+     * Get a challenge by ID.
+     */
+    async getChallenge(challengeId) {
+        return this.connection.request("GET", `/v1/gpu/challenge/${challengeId}`);
+    }
+    /**
+     * Get a provider's challenge history and stats.
+     */
+    async getProviderChallenges(address, limit = 20, offset = 0) {
+        return this.connection.request("GET", `/v1/gpu/providers/${address}/challenges?limit=${limit}&offset=${offset}`);
+    }
+    // ============================================================
+    //  Write Operations (off-chain)
+    // ============================================================
+    /**
+     * Send a GPU heartbeat (provider).
+     */
+    async heartbeat(input) {
+        return this.connection.request("POST", "/v1/gpu/heartbeat", input);
+    }
+    /**
+     * Create a buyer challenge.
+     */
+    async createChallenge(input) {
+        return this.connection.request("POST", "/v1/gpu/challenge", input);
+    }
+    /**
+     * Submit challenge results (provider).
+     */
+    async submitChallengeResult(input) {
+        return this.connection.request("POST", `/v1/gpu/challenge/${input.challengeId}/submit`, {
+            challengeOutputCid: input.challengeOutputCid,
+            actualTflops: input.actualTflops,
+            wallTimeMs: input.wallTimeMs,
+        });
+    }
+    // ============================================================
+    //  On-Chain Operations (prepare + sign + relay)
+    // ============================================================
+    /**
+     * Submit a GPU benchmark attestation on-chain.
+     */
+    async submitAttestation(input) {
+        return prepareSignRelay(this.connection, "/v1/prepare/gpu/attest", {
+            benchmarkHash: input.benchmarkHash,
+            gpuModel: input.gpuModel,
+            vramGb: input.vramGb,
+            computeCapability: input.computeCapability ?? "",
+            cudaVersion: input.cudaVersion ?? "",
+        });
+    }
+    /**
+     * Update attestation with a new benchmark hash.
+     */
+    async updateAttestation(benchmarkHash) {
+        return prepareSignRelay(this.connection, "/v1/prepare/gpu/update-attest", {
+            benchmarkHash,
+        });
+    }
+    /**
+     * Revoke GPU attestation (voluntarily delist).
+     */
+    async revokeAttestation() {
+        return prepareSignRelay(this.connection, "/v1/prepare/gpu/revoke", {});
+    }
+    // ============================================================
+    //  GPU Rental (convenience wrappers over ServiceMarketplace)
+    // ============================================================
+    /**
+     * Rent a GPU by creating a ServiceMarketplace agreement.
+     * This is a convenience wrapper around the marketplace agreement flow
+     * specifically for GPU listings.
+     */
+    async rentGpu(input) {
+        const deadline = Math.floor(Date.now() / 1000) + (input.durationHours ?? 24) * 3600;
+        return prepareSignRelay(this.connection, "/v1/prepare/service/agree", {
+            listingId: input.listingId,
+            terms: input.terms ?? "GPU rental via Nookplot marketplace",
+            deadline: String(deadline),
+            tokenAmount: input.tokenAmount ?? "0",
+            tokenAddress: input.tokenAddress,
+        });
+    }
+    /**
+     * Rent multiple GPUs for a research swarm.
+     * Finds available GPUs matching criteria and creates agreements for each.
+     */
+    async rentSwarmGpus(input) {
+        // Search for available GPUs
+        const result = await this.searchAvailable({
+            minVram: input.minVram,
+            gpuModel: input.gpuModel,
+            status: "online",
+            limit: input.count,
+        });
+        const gpus = result.gpus || [];
+        if (gpus.length < input.count) {
+            throw new Error(`Only ${gpus.length} GPUs available matching criteria (need ${input.count}). ` +
+                `Try reducing minVram or changing gpuModel.`);
+        }
+        const results = [];
+        for (const gpu of gpus.slice(0, input.count)) {
+            try {
+                const rental = await this.rentGpu({
+                    listingId: gpu.listing_id,
+                    terms: input.terms ?? `Swarm GPU rental (${input.count} GPUs)`,
+                    durationHours: input.durationHours,
+                    tokenAmount: input.tokenAmount,
+                });
+                results.push({ listingId: gpu.listing_id, txHash: rental.txHash });
+            }
+            catch (err) {
+                results.push({
+                    listingId: gpu.listing_id,
+                    txHash: "",
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return results;
+    }
+}
+//# sourceMappingURL=gpu.js.map

package/dist/gpu.js.map

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

package/dist/guardrails.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Guardrails — declarative per-action parameter validation.
+ *
+ * A guardrail is a function attached to a specific `actionType`. It can:
+ *   - **Pass** by returning `undefined` / nothing.
+ *   - **Mutate args** by returning `Partial<TArgs>` — declared keys overwrite,
+ *     undeclared keys are preserved.
+ *   - **Block** by throwing `InputGuardrailTripped` (input) or
+ *     `OutputGuardrailTripped` (output). The wrapped dispatcher converts any
+ *     other error into an `InputGuardrailTripped` so callers always observe
+ *     a single error class for "validation failure".
+ *
+ * This is a SEPARATE concern from `contentSafety` (string sanitizers) and
+ * `ContentScanner` (gateway threat-detection) — guardrails operate on typed
+ * arg objects scoped to a specific action, see those args, and can short-
+ * circuit the dispatch. All three layers can run on the same call.
+ *
+ * Composition order at the dispatcher (`runtime/src/autonomous.ts`
+ * `handleActionRequest`):
+ *   1. `action_start` hook fires.
+ *   2. `tool_input` hook fires.
+ *   3. Input guardrails run in declared order; first throw → `action_error`.
+ *   4. Action body executes.
+ *   5. `tool_output` hook fires.
+ *   6. Output guardrails run; first throw → `action_error`.
+ *   7. `action_end` hook fires.
+ *
+ * @example
+ * ```ts
+ * runtime.guardrails.register("send_dm", {
+ *   input: [
+ *     ({ to }) => {
+ *       if (!/^0x[0-9a-fA-F]{40}$/.test(to as string)) {
+ *         throw new InputGuardrailTripped("`to` must be a 0x-prefixed 40-hex address");
+ *       }
+ *     },
+ *     ({ content }) => ({ content: sanitizeForPrompt(content as string, 2000) }),
+ *   ],
+ * });
+ * ```
+ *
+ * @module guardrails
+ */
+import { type HookRegistry } from "./hooks.js";
+/** Base class for guardrail short-circuits. Catch this to handle either side. */
+export declare class GuardrailTripped extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when an input guardrail rejects or any guardrail callback throws
+ *  during the input phase. The dispatcher converts this into `action_error`. */
+export declare class InputGuardrailTripped extends GuardrailTripped {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when an output guardrail rejects. The dispatcher converts this
+ *  into `action_error` after the action body has already executed. */
+export declare class OutputGuardrailTripped extends GuardrailTripped {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * An input guardrail. Receives the (possibly mutated) args from prior
+ * guardrails. Returns `void` to pass, `Partial<TArgs>` to mutate, or throws
+ * `InputGuardrailTripped` to block.
+ *
+ * TS does not introspect parameter names — the caller declares which keys
+ * the guardrail accepts via the `Pick<TArgs, …>` type. Returned objects are
+ * shallow-merged onto args; undeclared keys in the return value are still
+ * applied (TS can't enforce param-binding at runtime), but agents should
+ * stick to the declared keys for parity with the Python `inspect.signature`
+ * extraction.
+ */
+export type InputGuardrail<TArgs extends Record<string, unknown> = Record<string, unknown>> = (args: TArgs) => void | undefined | Partial<TArgs> | Promise<void | undefined | Partial<TArgs>>;
+/**
+ * An output guardrail. Receives the action result. Returns `void` to pass,
+ * `Partial<TResult>` to mutate, or throws `OutputGuardrailTripped` to block.
+ *
+ * Output guardrails CANNOT replace the entire result — the merge is shallow
+ * AND `undefined` values in the return are filtered out before merge. This
+ * means a guardrail cannot silently drop security-critical fields (`txHash`,
+ * `signature`) by returning `{ txHash: undefined }`. To intentionally clear
+ * a field, throw `OutputGuardrailTripped` instead.
+ */
+export type OutputGuardrail<TResult = unknown> = (result: TResult) => void | undefined | Partial<TResult> | Promise<void | undefined | Partial<TResult>>;
+export interface GuardrailSet<TArgs extends Record<string, unknown> = Record<string, unknown>, TResult = unknown> {
+    input?: InputGuardrail<TArgs>[];
+    output?: OutputGuardrail<TResult>[];
+}
+/**
+ * Per-action guardrail registry. Keyed on `actionType` (the same string the
+ * dispatcher uses, e.g. `"send_dm"` or `"create_bounty"`). Multiple `register`
+ * calls APPEND — guardrails compose in registration order so an early
+ * mutation is visible to later validators.
+ *
+ * `runInput` / `runOutput` are the dispatcher integration points. They:
+ *   - Apply guardrails sequentially (not in parallel — order matters).
+ *   - Shallow-merge any returned `Partial<>` onto the working args.
+ *   - Re-throw `InputGuardrailTripped` / `OutputGuardrailTripped` as-is.
+ *   - Wrap any other thrown error in `InputGuardrailTripped` / `OutputGuardrailTripped`
+ *     with the original attached as `cause`.
+ *
+ * Tool hooks (`tool_input` / `tool_output`) are emitted by the dispatcher,
+ * not by the registry — keeps the emit point next to the action boundary.
+ */
+export declare class GuardrailRegistry {
+    private readonly inputs;
+    private readonly outputs;
+    private readonly hooks;
+    constructor(hooks?: HookRegistry);
+    /**
+     * Register one or more guardrails for an action. Returns a disposer that
+     * removes only the guardrails added by this call.
+     *
+     * `actionType` is deliberately typed as `string`, not a union of known
+     * action names. The registry does NOT validate against `ON_CHAIN_ACTIONS`
+     * — agents can attach guardrails to custom off-chain handlers, to internal
+     * action names, or to third-party actions added via SDK extension. The
+     * dispatcher only invokes guardrails whose key matches the actionType it's
+     * currently handling, so registering for an unknown key is harmless (the
+     * guardrail simply never runs).
+     *
+     * If you need strict validation — e.g. a CI check that a guardrail is
+     * actually wired to a real action — use {@link countInput} /
+     * {@link countOutput} in a test that asserts against the exported
+     * `ON_CHAIN_ACTIONS` set from `autonomous.ts`.
+     */
+    register<TArgs extends Record<string, unknown> = Record<string, unknown>, TResult = unknown>(actionType: string, set: GuardrailSet<TArgs, TResult>): () => void;
+    /** Number of registered input guardrails for an action (test inspection). */
+    countInput(actionType: string): number;
+    /** Number of registered output guardrails for an action (test inspection). */
+    countOutput(actionType: string): number;
+    /** Test helper. With no arg, clears all guardrails. */
+    clear(actionType?: string): void;
+    /**
+     * Run input guardrails in declared order and return the (possibly mutated)
+     * args. Throws `InputGuardrailTripped` if any guardrail rejects.
+     *
+     * The original `args` object is not mutated — a new shallow copy is
+     * returned even when no mutations occurred, to keep caller semantics
+     * predictable.
+     */
+    runInput<TArgs extends Record<string, unknown>>(actionType: string, args: TArgs): Promise<TArgs>;
+    /**
+     * Run output guardrails in declared order and return the (possibly
+     * mutated) result. Throws `OutputGuardrailTripped` on rejection. Like
+     * `runInput`, the working object is shallow-cloned for each mutation so
+     * the caller's `result` reference is untouched until the call returns.
+     */
+    runOutput<TResult>(actionType: string, result: TResult): Promise<TResult>;
+}
+/**
+ * Decorator-style wrapper for a single action handler. Convenient when an
+ * agent wants to attach guardrails to a one-off handler (a custom CLI tool,
+ * a unit-test fixture) without registering them globally.
+ *
+ * For the dispatcher integration, prefer `GuardrailRegistry.register()` +
+ * `registry.runInput` / `registry.runOutput` — that path is what
+ * `runtime/src/autonomous.ts:handleActionRequest` calls.
+ *
+ * @example
+ * ```ts
+ * const sendDm = withGuardrails(rawSendDm, {
+ *   input: [({ to }) => { if (!to.startsWith("0x")) throw new InputGuardrailTripped("bad addr"); }],
+ *   output: [({ messageId }) => { if (!messageId) throw new OutputGuardrailTripped("missing id"); }],
+ * });
+ * ```
+ */
+export declare function withGuardrails<TArgs extends Record<string, unknown>, TResult>(handler: (args: TArgs) => Promise<TResult> | TResult, opts: {
+    input?: InputGuardrail<TArgs>[];
+    output?: OutputGuardrail<TResult>[];
+}): (args: TArgs) => Promise<TResult>;
+/**
+ * Module singleton. `NookplotRuntime` exposes its own `runtime.guardrails`
+ * which is the same object as this — `import { guardrails } from
+ * "@nookplot/runtime"` and `runtime.guardrails` are interchangeable.
+ */
+export declare const guardrails: GuardrailRegistry;
+//# sourceMappingURL=guardrails.d.ts.map

package/dist/guardrails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrails.d.ts","sourceRoot":"","sources":["../src/guardrails.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,OAAO,EAAyB,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAItE,iFAAiF;AACjF,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAO3D;AAED;gFACgF;AAChF,qBAAa,qBAAsB,SAAQ,gBAAgB;gBAC7C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED;sEACsE;AACtE,qBAAa,sBAAuB,SAAQ,gBAAgB;gBAC9C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAID;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAC5F,IAAI,EAAE,KAAK,KACR,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;AAEpF;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,CAAC,OAAO,GAAG,OAAO,IAAI,CAC/C,MAAM,EAAE,OAAO,KACZ,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;AAExF,MAAM,WAAW,YAAY,CAC3B,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,OAAO,GAAG,OAAO;IAEjB,KAAK,CAAC,EAAE,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;IAChC,MAAM,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;CACrC;AAID;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;IAC9D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwC;IAChE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAEzB,KAAK,GAAE,YAA2B;IAI9C;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,EACzF,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,GAChC,MAAM,IAAI;IAgCb,6EAA6E;IAC7E,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAItC,8EAA8E;IAC9E,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAIvC,uDAAuD;IACvD,KAAK,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI;IAUhC;;;;;;;OAOG;IACG,QAAQ,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClD,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,KAAK,GACV,OAAO,CAAC,KAAK,CAAC;IAuBjB;;;;;OAKG;IACG,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;CAwBhF;AAsBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAC5B,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,OAAO,EAEP,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,EACpD,IAAI,EAAE;IACJ,KAAK,CAAC,EAAE,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;IAChC,MAAM,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;CACrC,GACA,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,CASnC;AAID;;;;GAIG;AACH,eAAO,MAAM,UAAU,mBAA0B,CAAC"}