@agirails/sdk 3.4.1 → 4.0.0-beta.0

package/dist/cli/index.js

@@ -41,6 +41,7 @@ function getVersion() {
 // Import commands
 const init_1 = require("./commands/init");
 const pay_1 = require("./commands/pay");
+const request_1 = require("./commands/request");
 const tx_1 = require("./commands/tx");
 const balance_1 = require("./commands/balance");
 const mint_1 = require("./commands/mint");
@@ -65,6 +66,7 @@ const autopublish_1 = require("./commands/autopublish");
 const health_1 = require("./commands/health");
 const repair_1 = require("./commands/repair");
 const serve_1 = require("./commands/serve");
+const agent_1 = require("./commands/agent");
 // ============================================================================
 // Program Setup
 // ============================================================================
@@ -91,6 +93,7 @@ program
 // Core commands (most used)
 program.addCommand((0, init_1.createInitCommand)());
 program.addCommand((0, pay_1.createPayCommand)());
+program.addCommand((0, request_1.createRequestCommand)());
 program.addCommand((0, tx_1.createTxCommand)());
 program.addCommand((0, balance_1.createBalanceCommand)());
 program.addCommand((0, mint_1.createMintCommand)());
@@ -125,7 +128,13 @@ program.addCommand((0, autopublish_1.createAutopublishCommand)());
 program.addCommand((0, health_1.createHealthCommand)());
 // On-chain shape repair (drop phantom services, update endpoint, toggle flags)
 program.addCommand((0, repair_1.createRepairCommand)());
-// AIP-2.1 provider daemon (long-running quote-channel server)
+// AIP-2.1 provider daemon — channel-driven, no HTTP listener (3.5.0)
+program.addCommand((0, agent_1.createAgentCommand)());
+// AIP-2.1 quote-channel HTTP daemon. Since 4.0.0, `actp serve` focuses
+// solely on the AIP-2.1 quote channel surface — on-chain INITIATED tx
+// detection is handled by `actp agent` (or `new Agent()` programmatically).
+// Running `actp serve` alongside `actp agent` is the canonical split.
+// See `src/cli/commands/serve.ts` header for scope; PRD §5.10.
 program.addCommand((0, serve_1.createServeCommand)());
 // ============================================================================
 // Error Handling

package/dist/cli/index.js.map

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

package/dist/cli/lib/resolveAgent.d.ts

@@ -0,0 +1,67 @@
+/**
+ * resolveAgent — slug → on-chain agent identity lookup for CLI commands.
+ *
+ * PRD-event-driven-provider-listening §5.7 + §A.6. Backs the new
+ * `actp test` onboarding flow (`runRequest` targets a known-named agent
+ * rather than a user-supplied address) and is reusable for future
+ * built-in references to SDK-published agents.
+ *
+ * ## Resolution order
+ *
+ * 1. **Env var override.** If the slug has a registered env var in
+ *    `ENV_OVERRIDES` and the value is set, parse it as an Ethereum
+ *    address. This is the rotation escape hatch: if a known agent's
+ *    wallet is compromised or rotated, operators set
+ *    `ACTP_SENTINEL_ADDRESS=0x...` and recover without an SDK republish.
+ * 2. **Constant table.** Per-network mapping in `KNOWN_AGENTS`. Returns
+ *    a checksummed address.
+ * 3. **Miss.** Throws `AgentNotFoundError`.
+ *
+ * ## NOT in scope for this helper
+ *
+ * - Generic on-chain `AgentRegistry.resolveAgent` lookup. Deferred (PRD §11)
+ *   because the SDK currently has no full agent-registry view and the
+ *   built-in slugs (just `sentinel` today) cover Phase 0.
+ * - The `agirails.app/a/<slug>` URL form used by `actp pay` / `actp request`
+ *   for arbitrary user-supplied slugs. That path goes through the
+ *   `discoverAgents` HTTP API; this helper is for SDK-internal known names.
+ *
+ * @module cli/lib/resolveAgent
+ */
+export type ResolvedAgentSource = 'env' | 'table';
+export interface ResolvedAgent {
+    /** Canonical slug used to look up the agent (e.g. `'sentinel'`). */
+    slug: string;
+    /** Checksummed Ethereum address. */
+    address: string;
+    /** Network the resolution applies to. */
+    network: string;
+    /** Where the address came from — useful for diagnostic logging. */
+    source: ResolvedAgentSource;
+}
+export declare class AgentNotFoundError extends Error {
+    readonly slug: string;
+    readonly network: string;
+    constructor(slug: string, network: string);
+}
+export declare class InvalidAgentAddressError extends Error {
+    readonly envVar: string;
+    readonly value: string;
+    constructor(envVar: string, value: string);
+}
+/**
+ * Resolve a known agent slug on a given network.
+ *
+ * @throws {InvalidAgentAddressError} when an env var override is set to a
+ *         non-address value.
+ * @throws {AgentNotFoundError} when no override is set and no table entry
+ *         exists for the (slug, network) pair.
+ *
+ * @example
+ * ```ts
+ * const sentinel = resolveAgent('sentinel', 'base-sepolia');
+ * console.log(sentinel.address, sentinel.source);
+ * ```
+ */
+export declare function resolveAgent(slug: string, network: string): ResolvedAgent;
+//# sourceMappingURL=resolveAgent.d.ts.map

package/dist/cli/lib/resolveAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveAgent.d.ts","sourceRoot":"","sources":["../../../src/cli/lib/resolveAgent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,OAAO,CAAC;AAElD,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAED,qBAAa,kBAAmB,SAAQ,KAAK;aACf,IAAI,EAAE,MAAM;aAAkB,OAAO,EAAE,MAAM;gBAA7C,IAAI,EAAE,MAAM,EAAkB,OAAO,EAAE,MAAM;CAO1E;AAED,qBAAa,wBAAyB,SAAQ,KAAK;aACrB,MAAM,EAAE,MAAM;aAAkB,KAAK,EAAE,MAAM;gBAA7C,MAAM,EAAE,MAAM,EAAkB,KAAK,EAAE,MAAM;CAO1E;AAyBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,aAAa,CAsBzE"}

package/dist/cli/lib/resolveAgent.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * resolveAgent — slug → on-chain agent identity lookup for CLI commands.
+ *
+ * PRD-event-driven-provider-listening §5.7 + §A.6. Backs the new
+ * `actp test` onboarding flow (`runRequest` targets a known-named agent
+ * rather than a user-supplied address) and is reusable for future
+ * built-in references to SDK-published agents.
+ *
+ * ## Resolution order
+ *
+ * 1. **Env var override.** If the slug has a registered env var in
+ *    `ENV_OVERRIDES` and the value is set, parse it as an Ethereum
+ *    address. This is the rotation escape hatch: if a known agent's
+ *    wallet is compromised or rotated, operators set
+ *    `ACTP_SENTINEL_ADDRESS=0x...` and recover without an SDK republish.
+ * 2. **Constant table.** Per-network mapping in `KNOWN_AGENTS`. Returns
+ *    a checksummed address.
+ * 3. **Miss.** Throws `AgentNotFoundError`.
+ *
+ * ## NOT in scope for this helper
+ *
+ * - Generic on-chain `AgentRegistry.resolveAgent` lookup. Deferred (PRD §11)
+ *   because the SDK currently has no full agent-registry view and the
+ *   built-in slugs (just `sentinel` today) cover Phase 0.
+ * - The `agirails.app/a/<slug>` URL form used by `actp pay` / `actp request`
+ *   for arbitrary user-supplied slugs. That path goes through the
+ *   `discoverAgents` HTTP API; this helper is for SDK-internal known names.
+ *
+ * @module cli/lib/resolveAgent
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAgent = exports.InvalidAgentAddressError = exports.AgentNotFoundError = void 0;
+const ethers_1 = require("ethers");
+class AgentNotFoundError extends Error {
+    constructor(slug, network) {
+        super(`Agent '${slug}' is not registered for network '${network}'. ` +
+            `Known agents on this network: ${listKnownAgents(network).join(', ') || '(none)'}.`);
+        this.slug = slug;
+        this.network = network;
+        this.name = 'AgentNotFoundError';
+    }
+}
+exports.AgentNotFoundError = AgentNotFoundError;
+class InvalidAgentAddressError extends Error {
+    constructor(envVar, value) {
+        super(`Env var ${envVar} contains an invalid Ethereum address: "${value}". ` +
+            `Expected a 0x-prefixed 40-character hex string.`);
+        this.envVar = envVar;
+        this.value = value;
+        this.name = 'InvalidAgentAddressError';
+    }
+}
+exports.InvalidAgentAddressError = InvalidAgentAddressError;
+/**
+ * Built-in slug → address table. Lookups are case-insensitive on the slug.
+ * Add an entry here only for SDK-shipped reference agents that callers
+ * should be able to reach without external discovery (e.g. Sentinel's
+ * Base Sepolia identity used by `actp test`).
+ */
+const KNOWN_AGENTS = Object.freeze({
+    sentinel: Object.freeze({
+        // Source of truth: Public Agents/seed-sentinel/sentinel.md (wallet field),
+        // committed at agent publish time. If Sentinel rotates, set
+        // ACTP_SENTINEL_ADDRESS or republish the SDK.
+        'base-sepolia': '0x3813A642C57CF3c20ff1170C0646c309B4bf6d64',
+    }),
+});
+/**
+ * Slug → env var name. Lets operators override the constant table without
+ * republishing the SDK. Match key casing to `KNOWN_AGENTS`.
+ */
+const ENV_OVERRIDES = Object.freeze({
+    sentinel: 'ACTP_SENTINEL_ADDRESS',
+});
+/**
+ * Resolve a known agent slug on a given network.
+ *
+ * @throws {InvalidAgentAddressError} when an env var override is set to a
+ *         non-address value.
+ * @throws {AgentNotFoundError} when no override is set and no table entry
+ *         exists for the (slug, network) pair.
+ *
+ * @example
+ * ```ts
+ * const sentinel = resolveAgent('sentinel', 'base-sepolia');
+ * console.log(sentinel.address, sentinel.source);
+ * ```
+ */
+function resolveAgent(slug, network) {
+    const normalizedSlug = slug.trim().toLowerCase();
+    // 1. Env var override path — rotation escape hatch (PRD §A.6).
+    //    Trim before testing for empty so a botched shell export
+    //    (`export ACTP_SENTINEL_ADDRESS=' '`) falls through to the constant
+    //    table instead of throwing InvalidAgentAddressError — the operator's
+    //    intent was clearly "no override", and surfacing a "not an address"
+    //    error for whitespace would be misleading.
+    const envVar = ENV_OVERRIDES[normalizedSlug];
+    if (envVar) {
+        const raw = process.env[envVar]?.trim();
+        if (raw !== undefined && raw !== '') {
+            if (!(0, ethers_1.isAddress)(raw))
+                throw new InvalidAgentAddressError(envVar, raw);
+            return { slug: normalizedSlug, address: (0, ethers_1.getAddress)(raw), network, source: 'env' };
+        }
+    }
+    // 2. Constant table.
+    const addr = KNOWN_AGENTS[normalizedSlug]?.[network];
+    if (!addr)
+        throw new AgentNotFoundError(normalizedSlug, network);
+    return { slug: normalizedSlug, address: (0, ethers_1.getAddress)(addr), network, source: 'table' };
+}
+exports.resolveAgent = resolveAgent;
+/**
+ * List the slugs that have a constant-table entry on the given network.
+ * Used by `AgentNotFoundError` for a helpful "did you mean..." hint.
+ */
+function listKnownAgents(network) {
+    return Object.keys(KNOWN_AGENTS).filter((slug) => KNOWN_AGENTS[slug][network] !== undefined);
+}
+//# sourceMappingURL=resolveAgent.js.map

package/dist/cli/lib/resolveAgent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveAgent.js","sourceRoot":"","sources":["../../../src/cli/lib/resolveAgent.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;;;AAEH,mCAA+C;AAe/C,MAAa,kBAAmB,SAAQ,KAAK;IAC3C,YAA4B,IAAY,EAAkB,OAAe;QACvE,KAAK,CACH,UAAU,IAAI,oCAAoC,OAAO,KAAK;YAC9D,iCAAiC,eAAe,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,GAAG,CACpF,CAAC;QAJwB,SAAI,GAAJ,IAAI,CAAQ;QAAkB,YAAO,GAAP,OAAO,CAAQ;QAKvE,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AARD,gDAQC;AAED,MAAa,wBAAyB,SAAQ,KAAK;IACjD,YAA4B,MAAc,EAAkB,KAAa;QACvE,KAAK,CACH,WAAW,MAAM,2CAA2C,KAAK,KAAK;YACtE,iDAAiD,CAClD,CAAC;QAJwB,WAAM,GAAN,MAAM,CAAQ;QAAkB,UAAK,GAAL,KAAK,CAAQ;QAKvE,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AARD,4DAQC;AAED;;;;;GAKG;AACH,MAAM,YAAY,GAA+D,MAAM,CAAC,MAAM,CAAC;IAC7F,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC;QACtB,2EAA2E;QAC3E,4DAA4D;QAC5D,8CAA8C;QAC9C,cAAc,EAAE,4CAA4C;KAC7D,CAAC;CACH,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,aAAa,GAAqC,MAAM,CAAC,MAAM,CAAC;IACpE,QAAQ,EAAE,uBAAuB;CAClC,CAAC,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,SAAgB,YAAY,CAAC,IAAY,EAAE,OAAe;IACxD,MAAM,cAAc,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAEjD,+DAA+D;IAC/D,6DAA6D;IAC7D,wEAAwE;IACxE,yEAAyE;IACzE,wEAAwE;IACxE,+CAA+C;IAC/C,MAAM,MAAM,GAAG,aAAa,CAAC,cAAc,CAAC,CAAC;IAC7C,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC;QACxC,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;YACpC,IAAI,CAAC,IAAA,kBAAS,EAAC,GAAG,CAAC;gBAAE,MAAM,IAAI,wBAAwB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;YACrE,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,IAAA,mBAAU,EAAC,GAAG,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QACpF,CAAC;IACH,CAAC;IAED,qBAAqB;IACrB,MAAM,IAAI,GAAG,YAAY,CAAC,cAAc,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;IACrD,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,kBAAkB,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;IACjE,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,IAAA,mBAAU,EAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AACvF,CAAC;AAtBD,oCAsBC;AAED;;;GAGG;AACH,SAAS,eAAe,CAAC,OAAe;IACtC,OAAO,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,SAAS,CAAC,CAAC;AAC/F,CAAC"}

package/dist/cli/lib/runRequest.d.ts

@@ -0,0 +1,114 @@
+/**
+ * runRequest — Level 1 requester flow (PRD §5.6).
+ *
+ * Shared helper for `actp request` and (via §5.7) `actp test`. Distinct from
+ * `src/level0/request.ts`: that function is the Level 0 simple API with one
+ * monolithic delivery timeout; runRequest splits the lifecycle into a
+ * **quote phase** (capped by `quoteTimeoutMs`, default 30s) and a **delivery
+ * phase** (capped by `deliveryTimeoutMs`, default 5min), and reports each
+ * state transition so the CLI can show progress.
+ *
+ * ## Scope (4.0.0): poll-only, autoAccept-friendly path
+ *
+ * `runRequest` polls `runtime.getTransaction(txId)` to observe state
+ * transitions and relies on a provider whose `shouldAutoAccept` returns
+ * `true` to drive INITIATED → COMMITTED on its own side (provider calls
+ * `linkEscrow` from `Agent.handleIncomingTransaction`). This is the
+ * Sentinel onboarding path the PRD targets.
+ *
+ * It does **not** implement PRD §5.6 step 6's `counteraccept.v1` envelope
+ * over `NegotiationChannel`. Multi-round counter-offer negotiation (which
+ * BuyerOrchestrator uses) is out of scope here. A future commit on the
+ * 4.x track will wire `subscribeTxId` + send the envelope when:
+ *   - the provider returns a quote that differs from the requester's offer, or
+ *   - the requester wants explicit accept-with-different-amount control.
+ *
+ * For Sentinel + autoAccept, the polling path is functionally equivalent
+ * to the negotiated path and ~80 LOC simpler.
+ *
+ * ## PRD §5.6 invariants enforced here
+ *  - On-chain `serviceDescription` is the bytes32 routing key
+ *    `keccak256(toUtf8Bytes(serviceName.trim()))`. Never JSON.
+ *  - Requester immediately settles after DELIVERED (kernel allows this
+ *    without waiting for the dispute window; ACTPKernel.sol:700-704).
+ *  - Quote-timeout exit is non-zero (code 2 at the CLI layer). The TX
+ *    remains on-chain INITIATED for the caller to cancel manually.
+ *  - `--input` / `--metadata` are out of scope for 4.0.0; provider sees
+ *    `job.input = {}`. Future `agirails.request.v1` envelope on
+ *    `NegotiationChannel` will restore that path (PRD §11).
+ *
+ * @module cli/lib/runRequest
+ */
+import { TransactionState } from '../../runtime/types/MockState';
+export type RequestNetwork = 'mock' | 'testnet' | 'mainnet';
+export interface RunRequestOptions {
+    /** Provider — checksummed or lowercase Ethereum address. */
+    provider: string;
+    /** Amount in USDC, human-readable (e.g. "0.05"). */
+    amount: string;
+    /** Service name. On-chain key is `keccak256(toUtf8Bytes(name))`. */
+    service: string;
+    /** Deadline as ISO 8601 string OR unix seconds. Default: now + 1h. */
+    deadline?: string | number;
+    /** Target network. Default 'testnet'. */
+    network?: RequestNetwork;
+    /** Quote-phase timeout in milliseconds. Default 30_000 (PRD §5.6). */
+    quoteTimeoutMs?: number;
+    /** Delivery-phase timeout in milliseconds. Default 300_000 (5min). */
+    deliveryTimeoutMs?: number;
+    /**
+     * Auto-accept any quote without prompting. 4.0.0 has no
+     * interactive-confirm UI yet, so this is effectively always true.
+     * Reserved for forward compatibility with interactive flows.
+     */
+    autoAccept?: boolean;
+    /** Override requester wallet (testnet/mainnet); resolved via keystore if omitted. */
+    privateKey?: string;
+    /** Override JSON-RPC URL. Falls back to network default. */
+    rpcUrl?: string;
+    /** Custom state directory for mock mode. */
+    stateDirectory?: string;
+    /** Called for every state transition the requester observes. */
+    onTransition?: (state: TransactionState, txId: string, ts: Date) => void;
+}
+export declare class QuoteTimeoutError extends Error {
+    readonly txId: string;
+    readonly timeoutMs: number;
+    constructor(txId: string, timeoutMs: number);
+}
+export declare class DeliveryTimeoutError extends Error {
+    readonly txId: string;
+    readonly timeoutMs: number;
+    readonly lastState: TransactionState;
+    constructor(txId: string, timeoutMs: number, lastState: TransactionState);
+}
+export interface RunRequestResult {
+    /** On-chain transaction id (bytes32 hex). */
+    txId: string;
+    /** Final state observed before runRequest returned. */
+    finalState: TransactionState;
+    /** Total time from createTransaction to settle/return, in ms. */
+    elapsedMs: number;
+    /** Decoded delivery payload, when available. */
+    payload?: unknown;
+    /** Whether the requester settled the escrow before returning. */
+    settled: boolean;
+}
+/**
+ * Execute a Level 1 negotiated request end-to-end.
+ *
+ * @example
+ * ```ts
+ * const r = await runRequest({
+ *   provider: '0x3813...d64',
+ *   amount: '0.05',
+ *   service: 'onboarding',
+ *   network: 'testnet',
+ *   onTransition: (state, txId, ts) =>
+ *     console.log(`[${ts.toISOString()}] ${state.padEnd(12)} ${txId}`),
+ * });
+ * console.log(r.payload);
+ * ```
+ */
+export declare function runRequest(opts: RunRequestOptions): Promise<RunRequestResult>;
+//# sourceMappingURL=runRequest.d.ts.map

package/dist/cli/lib/runRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runRequest.d.ts","sourceRoot":"","sources":["../../../src/cli/lib/runRequest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAKH,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGjE,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;AAE5D,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,yCAAyC;IACzC,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,qFAAqF;IACrF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,KAAK,IAAI,CAAC;CAC1E;AAED,qBAAa,iBAAkB,SAAQ,KAAK;aACd,IAAI,EAAE,MAAM;aAAkB,SAAS,EAAE,MAAM;gBAA/C,IAAI,EAAE,MAAM,EAAkB,SAAS,EAAE,MAAM;CAQ5E;AAED,qBAAa,oBAAqB,SAAQ,KAAK;aAE3B,IAAI,EAAE,MAAM;aACZ,SAAS,EAAE,MAAM;aACjB,SAAS,EAAE,gBAAgB;gBAF3B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,gBAAgB;CAQ9C;AAED,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,UAAU,EAAE,gBAAgB,CAAC;IAC7B,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iEAAiE;IACjE,OAAO,EAAE,OAAO,CAAC;CAClB;AAKD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAsJnF"}