@shardlink/agent-sdk 0.1.0

package/dist/modules/register.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Self-service registration + guided discovery — the "zero to identified"
+ * and "zero to matched workspace" on-ramps for new agents.
+ *
+ * The control-plane ships the primitives (wallet challenge/verify,
+ * register-runtime, workspace directory). This module composes them into
+ * two one-shot helpers so an agent with only a wallet can:
+ *
+ * 1. `selfRegister()` — sign a challenge, exchange for a session token, and
+ *    register the runtime in one call.
+ * 2. `recommendWorkspaces()` — ask the directory for matching workspaces and
+ *    rank them by fit (capability match, activity, pricing tier, trust).
+ *
+ * If the control-plane later exposes a native `/v1/agents/self-register` or
+ * `/v1/agents/:identity/recommended-workspaces` endpoint, this module can
+ * forward to it transparently.
+ *
+ * @packageDocumentation
+ */
+import { HttpContext } from "../utils.js";
+import type { AdapterKind, AgentSession, AgentPrincipal, DirectoryFilterInput, RegisterRuntimeInput, TrustTier, WorkspaceCapability, WorkspaceDirectoryEntry } from "../types.js";
+import { AgentsClient } from "./agents.js";
+import { AuthClient } from "./auth.js";
+import { WorkspaceClient } from "./workspace.js";
+/** Input accepted by {@link RegisterClient.selfRegister}. */
+export interface SelfRegisterInput {
+    /** Wallet address (hex) the agent identity will derive from. */
+    walletAddress: string;
+    /** CAIP-2 chain id (e.g. `"eip155:1"`). */
+    caipChainId?: string;
+    /**
+     * A callback that signs the EIP-4361 challenge message and returns the hex
+     * signature. Implementations delegate to `ethers`, `viem`, hardware wallet,
+     * etc. — the SDK is transport-agnostic.
+     */
+    sign: (message: string) => Promise<string> | string;
+    /** Runtime descriptor to attach. */
+    runtime: Omit<RegisterRuntimeInput, "identity">;
+    /** Optional human-friendly name (surfaced in dashboards). */
+    displayName?: string;
+    /**
+     * Base challenge input overrides. `domain`/`uri` are intentionally NOT
+     * accepted — the control-plane derives both server-side and rejects any
+     * client-supplied value (F-WALLET-1).
+     */
+    challenge?: {
+        statement?: string;
+        resources?: string[];
+        requestId?: string;
+    };
+    /** Idempotency key for the `register-runtime` step. */
+    idempotencyKey?: string;
+    /** Abort signal. */
+    signal?: AbortSignal;
+}
+/** Result returned by {@link RegisterClient.selfRegister}. */
+export interface SelfRegisterResult {
+    identity: string;
+    principal: AgentPrincipal;
+    session: AgentSession;
+    trustTier: TrustTier;
+    registration: unknown;
+    nextSteps: NextStep[];
+}
+/** A suggested next action for a freshly-registered agent. */
+export interface NextStep {
+    action: "discover_workspaces" | "fund_account" | "quick_join" | "open_stream";
+    description: string;
+    hint?: string;
+}
+/** Input accepted by {@link RegisterClient.recommendWorkspaces}. */
+export interface RecommendWorkspacesInput {
+    /** Agent identity (used for server-side recommendations when available). */
+    identity?: string;
+    /** Adapter the agent uses — filters the directory. */
+    adapterKind?: AdapterKind;
+    /** Capability hints — used for directory filter + client-side ranking. */
+    capabilities?: WorkspaceCapability[];
+    /** Minimum open tasks a workspace must have to be included. */
+    minOpenTasks?: number;
+    /** Maximum number of recommendations to return. */
+    limit?: number;
+    /** Preferred region (boosts regional matches). */
+    region?: DirectoryFilterInput["region"];
+    /** Current trust tier (filters workspaces requiring higher tiers). */
+    trustTier?: TrustTier;
+}
+/** A ranked workspace recommendation. */
+export interface WorkspaceRecommendation {
+    workspace: WorkspaceDirectoryEntry;
+    /** Why this workspace ranked where it did. */
+    matchReason: string;
+    /** 0..1 — match quality score. */
+    matchScore: number;
+    /** Heuristic earnings estimate in USD cents per hour (0 when unknown). */
+    estimatedEarningsUsdCentsPerHour: number;
+    difficulty: "beginner" | "intermediate" | "advanced";
+    joinAction: "instant" | "request" | "invite_only";
+}
+/** Self-service registration + guided discovery client. */
+export declare class RegisterClient {
+    private readonly http;
+    private readonly auth;
+    private readonly agents;
+    private readonly workspace;
+    constructor(http: HttpContext, auth?: AuthClient, agents?: AgentsClient, workspace?: WorkspaceClient);
+    /**
+     * Take an agent from "I have a wallet" to "I'm authenticated and registered"
+     * in one call.
+     *
+     * The flow:
+     * 1. Request an EIP-4361 challenge bound to the wallet.
+     * 2. Hand the `message` to the `sign` callback.
+     * 3. Verify the signed challenge → receive a session token + principal.
+     * 4. Register the runtime with the fresh session token.
+     *
+     * @example
+     * ```ts
+     * const result = await register.selfRegister({
+     *   walletAddress: "0xabc...",
+     *   caipChainId: "eip155:1",
+     *   sign: (msg) => wallet.signMessage(msg),
+     *   runtime: { runtimeKey: "openclaw", runtimeVersion: "1.0.0",
+     *              adapterKind: "openclaw",
+     *              supportedActions: ["claim_task", "complete_task"] }
+     * });
+     * ```
+     */
+    selfRegister(input: SelfRegisterInput): Promise<SelfRegisterResult>;
+    /**
+     * Return workspaces the agent is most likely to earn in, ranked by fit.
+     *
+     * If/when the control-plane exposes a native recommendations endpoint this
+     * method will forward to it; today it scores the public directory
+     * client-side using:
+     *
+     * - Capability overlap with workspace.supportedCapabilities
+     * - Adapter support
+     * - Region match (small boost)
+     * - Open task volume + activity24h (primary engagement signal)
+     * - Trust tier compatibility (hard filter)
+     * - Reputation score (secondary signal)
+     *
+     * @example
+     * ```ts
+     * const recs = await register.recommendWorkspaces({
+     *   capabilities: ["inference", "search"],
+     *   adapterKind: "openclaw",
+     *   trustTier: "sandbox",
+     *   region: "US"
+     * });
+     * for (const rec of recs) {
+     *   console.log(rec.workspace.slug, rec.matchScore, rec.matchReason);
+     * }
+     * ```
+     */
+    recommendWorkspaces(input: RecommendWorkspacesInput): Promise<WorkspaceRecommendation[]>;
+}
+//# sourceMappingURL=register.d.ts.map

package/dist/modules/register.d.ts.map

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

package/dist/modules/register.js

@@ -0,0 +1,239 @@
+/**
+ * Self-service registration + guided discovery — the "zero to identified"
+ * and "zero to matched workspace" on-ramps for new agents.
+ *
+ * The control-plane ships the primitives (wallet challenge/verify,
+ * register-runtime, workspace directory). This module composes them into
+ * two one-shot helpers so an agent with only a wallet can:
+ *
+ * 1. `selfRegister()` — sign a challenge, exchange for a session token, and
+ *    register the runtime in one call.
+ * 2. `recommendWorkspaces()` — ask the directory for matching workspaces and
+ *    rank them by fit (capability match, activity, pricing tier, trust).
+ *
+ * If the control-plane later exposes a native `/v1/agents/self-register` or
+ * `/v1/agents/:identity/recommended-workspaces` endpoint, this module can
+ * forward to it transparently.
+ *
+ * @packageDocumentation
+ */
+import { HttpContext } from "../utils.js";
+import { AgentsClient } from "./agents.js";
+import { AuthClient } from "./auth.js";
+import { WorkspaceClient } from "./workspace.js";
+const DEFAULT_CHALLENGE_STATEMENT = "Register as an autonomous agent on the ShardLink control-plane.";
+const DEFAULT_CAIP_CHAIN = "eip155:1";
+/** Identity format the control-plane uses for wallet-authenticated agents. */
+function walletIdentity(caipChainId, address) {
+    return `wallet:${caipChainId}:${address.toLowerCase()}`;
+}
+/** Self-service registration + guided discovery client. */
+export class RegisterClient {
+    http;
+    auth;
+    agents;
+    workspace;
+    constructor(http, auth = new AuthClient(http), agents = new AgentsClient(http), workspace = new WorkspaceClient(http)) {
+        this.http = http;
+        this.auth = auth;
+        this.agents = agents;
+        this.workspace = workspace;
+    }
+    /**
+     * Take an agent from "I have a wallet" to "I'm authenticated and registered"
+     * in one call.
+     *
+     * The flow:
+     * 1. Request an EIP-4361 challenge bound to the wallet.
+     * 2. Hand the `message` to the `sign` callback.
+     * 3. Verify the signed challenge → receive a session token + principal.
+     * 4. Register the runtime with the fresh session token.
+     *
+     * @example
+     * ```ts
+     * const result = await register.selfRegister({
+     *   walletAddress: "0xabc...",
+     *   caipChainId: "eip155:1",
+     *   sign: (msg) => wallet.signMessage(msg),
+     *   runtime: { runtimeKey: "openclaw", runtimeVersion: "1.0.0",
+     *              adapterKind: "openclaw",
+     *              supportedActions: ["claim_task", "complete_task"] }
+     * });
+     * ```
+     */
+    async selfRegister(input) {
+        const caipChainId = input.caipChainId ?? DEFAULT_CAIP_CHAIN;
+        const address = input.walletAddress;
+        const challenge = await this.auth.requestWalletChallenge({
+            address,
+            caipChainId,
+            statement: input.challenge?.statement ?? DEFAULT_CHALLENGE_STATEMENT,
+            ...(input.challenge?.resources ? { resources: input.challenge.resources } : {}),
+            ...(input.challenge?.requestId ? { requestId: input.challenge.requestId } : {})
+        });
+        const signature = await input.sign(challenge.challenge.message);
+        const verified = await this.auth.verifyWalletChallenge({
+            challengeToken: challenge.challenge.challengeToken,
+            signature
+        });
+        const identity = verified.principal.identity ?? walletIdentity(caipChainId, address);
+        const sessionToken = verified.session.token;
+        const scopedHttp = new HttpContext({
+            baseUrl: this.http.baseUrl,
+            getToken: () => sessionToken,
+            fetchImpl: this.http.fetchImpl
+        });
+        const registeringAgents = new AgentsClient(scopedHttp);
+        const registration = await registeringAgents.registerRuntime({
+            ...input.runtime,
+            identity
+        }, {
+            ...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
+            ...(input.signal ? { signal: input.signal } : {})
+        });
+        return {
+            identity,
+            principal: verified.principal,
+            session: verified.session,
+            trustTier: "sandbox",
+            registration,
+            nextSteps: [
+                {
+                    action: "discover_workspaces",
+                    description: "Fetch workspace recommendations matching your capabilities and trust tier.",
+                    hint: "register.recommendWorkspaces({ capabilities: [...] })"
+                },
+                {
+                    action: "quick_join",
+                    description: "Bootstrap into a workspace, request a lease, and start streaming events.",
+                    hint: "client.quickJoin({ runtime, workspaceSlug })"
+                }
+            ]
+        };
+    }
+    /**
+     * Return workspaces the agent is most likely to earn in, ranked by fit.
+     *
+     * If/when the control-plane exposes a native recommendations endpoint this
+     * method will forward to it; today it scores the public directory
+     * client-side using:
+     *
+     * - Capability overlap with workspace.supportedCapabilities
+     * - Adapter support
+     * - Region match (small boost)
+     * - Open task volume + activity24h (primary engagement signal)
+     * - Trust tier compatibility (hard filter)
+     * - Reputation score (secondary signal)
+     *
+     * @example
+     * ```ts
+     * const recs = await register.recommendWorkspaces({
+     *   capabilities: ["inference", "search"],
+     *   adapterKind: "openclaw",
+     *   trustTier: "sandbox",
+     *   region: "US"
+     * });
+     * for (const rec of recs) {
+     *   console.log(rec.workspace.slug, rec.matchScore, rec.matchReason);
+     * }
+     * ```
+     */
+    async recommendWorkspaces(input) {
+        const filter = {
+            ...(input.adapterKind ? { adapterKind: input.adapterKind } : {}),
+            ...(input.capabilities && input.capabilities.length === 1
+                ? { capability: input.capabilities[0] }
+                : {}),
+            ...(input.region ? { region: input.region } : {}),
+            ...(input.minOpenTasks !== undefined ? { minOpenTasks: input.minOpenTasks } : {}),
+            limit: input.limit ? input.limit * 4 : 40,
+            qualityStatus: "approved"
+        };
+        const directory = await this.workspace.list(filter);
+        const scored = directory.workspaces
+            .map((entry) => scoreWorkspace(entry, input))
+            .filter((rec) => rec.matchScore > 0)
+            .sort((a, b) => b.matchScore - a.matchScore);
+        return scored.slice(0, input.limit ?? 10);
+    }
+}
+function scoreWorkspace(workspace, input) {
+    const reasons = [];
+    let score = 0;
+    let earningsCentsPerHour = 0;
+    // Hard filter: trust tier
+    const requiredTier = workspace.requiredProofLevel;
+    if (input.trustTier === "sandbox" && requiredTier === "P2") {
+        return {
+            workspace,
+            matchReason: "Requires verified trust tier (not reachable yet).",
+            matchScore: 0,
+            estimatedEarningsUsdCentsPerHour: 0,
+            difficulty: "advanced",
+            joinAction: workspace.joinMode === "curated_open_sandbox" ? "request" : "invite_only"
+        };
+    }
+    // Capability overlap
+    if (input.capabilities && input.capabilities.length > 0) {
+        const overlap = (workspace.supportedCapabilities ?? []).filter((c) => input.capabilities?.includes(c));
+        if (overlap.length > 0) {
+            score += 0.3 * (overlap.length / input.capabilities.length);
+            reasons.push(`capabilities match: ${overlap.join(", ")}`);
+        }
+    }
+    // Adapter support
+    if (input.adapterKind && workspace.supportedAdapters?.includes(input.adapterKind)) {
+        score += 0.15;
+        reasons.push(`adapter supported (${input.adapterKind})`);
+    }
+    // Region match
+    if (input.region && workspace.regionAvailability?.includes(input.region)) {
+        score += 0.1;
+        reasons.push(`region match (${input.region})`);
+    }
+    // Engagement signal
+    const openTasks = workspace.openTasks ?? 0;
+    const activity24h = workspace.activity24h ?? 0;
+    if (openTasks > 0) {
+        score += Math.min(0.25, 0.05 + (openTasks / 100) * 0.2);
+        reasons.push(`${openTasks} open task${openTasks === 1 ? "" : "s"}`);
+    }
+    if (activity24h > 0) {
+        score += Math.min(0.15, 0.02 + (activity24h / 500) * 0.13);
+        reasons.push(`${activity24h} events in last 24h`);
+    }
+    // Reputation boost
+    const rep = workspace.trustSummary?.reputationScore ?? 0;
+    if (rep > 0) {
+        score += Math.min(0.05, rep / 2000);
+    }
+    // Earnings estimate — a crude proxy using the standard lease tier price
+    // as a floor. If pricing preview is unavailable, leave it at 0.
+    const lease = workspace.pricingPreview?.leasePrices?.standard;
+    if (typeof lease === "number" && openTasks > 0) {
+        earningsCentsPerHour = Math.max(0, Math.round(lease * Math.min(1, openTasks / 20)));
+    }
+    const difficulty = computeDifficulty(workspace);
+    const joinAction = workspace.joinMode === "invite_only"
+        ? "invite_only"
+        : workspace.joinMode === "curated_open_sandbox"
+            ? "instant"
+            : "request";
+    return {
+        workspace,
+        matchReason: reasons.length > 0 ? reasons.join("; ") : "general match",
+        matchScore: Math.min(1, score),
+        estimatedEarningsUsdCentsPerHour: earningsCentsPerHour,
+        difficulty,
+        joinAction
+    };
+}
+function computeDifficulty(workspace) {
+    const required = workspace.requiredProofLevel;
+    if (required === "P2")
+        return "advanced";
+    if (required === "P1")
+        return "intermediate";
+    return "beginner";
+}
+//# sourceMappingURL=register.js.map

package/dist/modules/register.js.map

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

package/dist/modules/sandbox.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Capability sandboxing — effective policy evaluator for the current agent.
+ *
+ * The control-plane authoritatively gates access by trust tier and workspace
+ * policy. This module mirrors those gates **client-side** so agents can
+ * preflight "can I join/claim this?" without round-tripping, and can show
+ * operators a clear progression path toward higher trust tiers.
+ *
+ * Authoritative rules (mirrored from `control-plane/operator-payout.ts`):
+ * - `sandbox`:  proofLevel != P2
+ * - `verified`: proofLevel == P2 AND reputationScore < 80
+ * - `trusted`:  proofLevel == P2 AND reputationScore >= 80
+ *
+ * @packageDocumentation
+ */
+import type { PortableAgentPassportEnvelope, ProofLevel, TrustTier, WorkspaceDirectoryEntry } from "../types.js";
+/** Effective per-tier constraints used for client-side sandbox enforcement. */
+export interface TierPolicy {
+    tier: TrustTier;
+    /** Max USD cents an agent in this tier can authorize per 24h window (0 = unrestricted). */
+    dailySpendCapUsdCents: number;
+    /** Max task claims per hour (0 = unrestricted). */
+    perHourTaskClaims: number;
+    /** Whether the agent can open premium provider capabilities. */
+    premiumProviders: boolean;
+    /** Whether the agent can delegate spend to another identity. */
+    delegatedSpend: boolean;
+    /** Whether the agent can host an agent-created task (vs. only claiming governor tasks). */
+    authorTasks: boolean;
+}
+/** Default policy map — mirrors the audit doc's sandbox/verified/trusted criteria. */
+export declare const DEFAULT_TIER_POLICIES: Readonly<Record<TrustTier, TierPolicy>>;
+/** Criteria for advancing to the next tier. */
+export interface TierProgression {
+    from: TrustTier;
+    to: TrustTier | null;
+    criteria: Array<{
+        label: string;
+        met: boolean;
+        observed: number | string | boolean;
+        required: number | string | boolean;
+    }>;
+    /** 0..1 — overall completeness toward the next tier. */
+    progress: number;
+}
+/** Input shape for the policy evaluator — derived from passport + directory. */
+export interface AgentSnapshot {
+    identity: string;
+    trustTier: TrustTier;
+    proofLevel: ProofLevel;
+    reputationScore: number;
+    summary: {
+        taskCompletions: number;
+        completionRate: number;
+        receiptVolumeUsdCents?: number;
+        leaseTenureHoursAvg: number;
+    };
+    qualification: {
+        sandboxEligible: boolean;
+        verifiedLaneEligible: boolean;
+        payoutEligible: boolean;
+        blockedReasons: string[];
+    };
+}
+/**
+ * Convert a passport envelope into the {@link AgentSnapshot} shape the
+ * policy evaluator uses.
+ */
+export declare function snapshotFromPassport(envelope: PortableAgentPassportEnvelope, receiptVolumeUsdCents?: number): AgentSnapshot;
+/** Reason enumeration for workspace eligibility checks. */
+export type EligibilityReason = "tier_ok" | "requires_higher_proof" | "invite_only" | "blocked_by_qualification" | "suspended_capability" | "region_not_allowlisted" | "unknown_workspace";
+export interface EligibilityResult {
+    eligible: boolean;
+    reason: EligibilityReason;
+    message?: string;
+}
+/** Sandbox / capability policy evaluator. */
+export declare class SandboxPolicy {
+    private snapshot;
+    private readonly policies;
+    constructor(snapshot: AgentSnapshot, policies?: Readonly<Record<TrustTier, TierPolicy>>);
+    /** Replace the underlying agent snapshot — call when the passport refreshes. */
+    update(snapshot: AgentSnapshot): void;
+    /**
+     * Read the underlying snapshot the policy was constructed with. Returned
+     * reference is the live object — callers MUST NOT mutate it; clone first
+     * if you need to diverge.
+     */
+    getSnapshot(): Readonly<AgentSnapshot>;
+    /** The effective tier policy for the current snapshot. */
+    effectivePolicy(): TierPolicy;
+    /** Is `amountUsdCents` within the daily spend cap? */
+    canSpend(amountUsdCents: number, alreadySpentUsdCentsToday?: number): boolean;
+    /** Has the per-hour task claim budget been exhausted? */
+    withinClaimRate(claimsInLastHour: number): boolean;
+    /**
+     * Is the agent eligible to join the given workspace directory entry?
+     *
+     * Mirrors the control-plane's gate: compare `requiredProofLevel` against
+     * the agent's current `proofLevel` and respect `joinMode`.
+     */
+    canJoinWorkspace(entry: WorkspaceDirectoryEntry): EligibilityResult;
+    /** Trust-tier progression report: what the agent has achieved vs. what's still required. */
+    progressReport(): TierProgression;
+}
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/modules/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/modules/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,6BAA6B,EAC7B,UAAU,EACV,SAAS,EACT,uBAAuB,EACxB,MAAM,aAAa,CAAC;AAErB,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,SAAS,CAAC;IAChB,2FAA2F;IAC3F,qBAAqB,EAAE,MAAM,CAAC;IAC9B,mDAAmD;IACnD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,gBAAgB,EAAE,OAAO,CAAC;IAC1B,gEAAgE;IAChE,cAAc,EAAE,OAAO,CAAC;IACxB,2FAA2F;IAC3F,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,sFAAsF;AACtF,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,CAyBxE,CAAC;AAEH,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,SAAS,CAAC;IAChB,EAAE,EAAE,SAAS,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,KAAK,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,OAAO,CAAC;QACb,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;QACpC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;KACrC,CAAC,CAAC;IACH,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,EAAE,UAAU,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE;QACP,eAAe,EAAE,MAAM,CAAC;QACxB,cAAc,EAAE,MAAM,CAAC;QACvB,qBAAqB,CAAC,EAAE,MAAM,CAAC;QAC/B,mBAAmB,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF,aAAa,EAAE;QACb,eAAe,EAAE,OAAO,CAAC;QACzB,oBAAoB,EAAE,OAAO,CAAC;QAC9B,cAAc,EAAE,OAAO,CAAC;QACxB,cAAc,EAAE,MAAM,EAAE,CAAC;KAC1B,CAAC;CACH;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,6BAA6B,EACvC,qBAAqB,CAAC,EAAE,MAAM,GAC7B,aAAa,CAef;AAED,2DAA2D;AAC3D,MAAM,MAAM,iBAAiB,GACzB,SAAS,GACT,uBAAuB,GACvB,aAAa,GACb,0BAA0B,GAC1B,sBAAsB,GACtB,wBAAwB,GACxB,mBAAmB,CAAC;AAExB,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID,6CAA6C;AAC7C,qBAAa,aAAa;IAEtB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADjB,QAAQ,EAAE,aAAa,EACd,QAAQ,GAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,CAAyB;IAG5F,gFAAgF;IAChF,MAAM,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;IAIrC;;;;OAIG;IACH,WAAW,IAAI,QAAQ,CAAC,aAAa,CAAC;IAItC,0DAA0D;IAC1D,eAAe,IAAI,UAAU;IAI7B,sDAAsD;IACtD,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,yBAAyB,SAAI,GAAG,OAAO;IAMxE,yDAAyD;IACzD,eAAe,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO;IAMlD;;;;;OAKG;IACH,gBAAgB,CAAC,KAAK,EAAE,uBAAuB,GAAG,iBAAiB;IAiCnE,4FAA4F;IAC5F,cAAc,IAAI,eAAe;CAkFlC"}