@decentrys/agent 0.1.0

package/dist/model.d.ts

@@ -0,0 +1,256 @@
+/**
+ * AgentGuard — the types.
+ *
+ * Protect informs a person, who then decides. AgentGuard sits in front of
+ * something with no judgement that will do exactly what it was told, at
+ * machine speed, as many times as its loop runs. Three consequences shape
+ * everything in this file:
+ *
+ *  1. **A warning is not a control.** Protect deliberately warns and never
+ *     blocks, because the person holding the keys should decide. An agent
+ *     cannot heed a warning — a warning it ignores is an allow with extra
+ *     words. So AgentGuard's outcomes are `allow`, `require_human_approval`
+ *     and `deny`, and the middle one means *stop and hand this to a person*.
+ *
+ *  2. **The operator is not the agent.** Limits are set by a human ahead of
+ *     time. The agent must not be able to widen them — not by argument, not by
+ *     mutating the object it was handed, not by passing an override. That is
+ *     enforced structurally in `policy.ts` (`sealPolicy`, `narrowPolicy`),
+ *     not by convention.
+ *
+ *  3. **Every decision must survive being questioned later.** "The agent spent
+ *     the treasury" is answered by an audit record that names each rule, the
+ *     limit it enforced and the value it observed. An allow that cannot be
+ *     explained is as bad as a wrong one, so a passing rule is recorded just
+ *     as loudly as a failing one.
+ *
+ * The risk model is *not* reimplemented here. Classification, the seven risk
+ * levels and `applyPolicy` come from `@decentrys/protect` unchanged; this
+ * package adds the limits an autonomous actor needs and a human does not.
+ */
+import type { Assessment, Policy, RiskLevel } from '@decentrys/protect';
+export declare const AGENT_MODEL_VERSION = "agent-1.0.0";
+/**
+ * The kinds of action a policy can talk about.
+ *
+ * These are coarse on purpose. "May swap, may not approve" is a sentence an
+ * operator can write and check; "may call selector 0x095ea7b3" is not. An
+ * action whose type the integrator cannot determine is `unknown`, which is a
+ * first-class value rather than a default — see `deniedActions` below.
+ */
+export declare const AGENT_ACTION_TYPES: readonly ["transfer", "swap", "approve", "contract_call", "bridge", "stake", "unstake", "deploy", "sign_message", "unknown"];
+export type AgentActionType = (typeof AGENT_ACTION_TYPES)[number];
+export interface AgentAction {
+    /** Which agent proposes it. Limits are held per agent, not per process. */
+    agentId: string;
+    chain: string;
+    type: AgentActionType;
+    /** The wallet the agent signs with. */
+    from: string;
+    /** Counterparty or contract. Absent for a deploy or a bare message signature. */
+    to?: string;
+    /** Token contract, for a transfer, swap or approval. */
+    token?: string;
+    /** Base units, as a string. Numbers lose precision at these magnitudes. */
+    value?: string;
+    /**
+     * The action's value in USD, as the integrator prices it.
+     *
+     * **`undefined` is not zero.** An action with no value at all (a message
+     * signature, a zero-value call) should say `0`; leaving this out means "I do
+     * not know what this is worth", and a value cap cannot be enforced against
+     * an unknown. See `VALUE_UNKNOWN` in `policy.ts` for what happens then, and
+     * why it is the only defensible answer for an autonomous signer.
+     *
+     * AgentGuard never prices anything itself. Pricing belongs to whoever runs
+     * the agent, with the feed and the staleness rules they are willing to be
+     * accountable for.
+     */
+    valueUsd?: number;
+    /** EVM calldata. */
+    data?: string;
+    /** Non-EVM families carry their serialized payload here. */
+    raw?: string;
+    /** The site or service that asked for this, when there is one. */
+    origin?: string;
+    /** Base units, or `unlimited`. Only meaningful for `type: 'approve'`. */
+    approvalAmount?: string;
+    /** What the agent believes it is doing, in its own words. Recorded, never trusted. */
+    intent?: string;
+    /**
+     * Set by the caller so a retried action is not counted twice against a
+     * cumulative cap. Two calls carrying the same key reuse one reservation.
+     */
+    idempotencyKey?: string;
+    proposedAt?: string;
+}
+/** A cumulative limit: how much may be committed inside a rolling window. */
+export interface SpendWindow {
+    /** A name an operator recognises in an audit record — 'daily', 'per-hour'. */
+    label: string;
+    windowMs: number;
+    maxValueUsd: number;
+}
+/** A rate ceiling: how many actions may be admitted inside a rolling window. */
+export interface RateWindow {
+    label: string;
+    windowMs: number;
+    maxActions: number;
+}
+/**
+ * What an operator can express.
+ *
+ * Every field is optional and every omitted field means *unconstrained on that
+ * axis* — with one deliberate exception, `allowUnlimitedApprovals`, which
+ * defaults to refusing. An unlimited approval is the single action that turns
+ * a bounded mistake into an unbounded one, and defaulting it open would make
+ * the safe configuration the one you have to remember to write.
+ */
+export interface AgentPolicy {
+    /** Free text for the operator's own change control. Recorded in every decision. */
+    version?: string;
+    /**
+     * Bind this policy to one agent. When set, an action from a different
+     * `agentId` is denied rather than evaluated — a policy leaking across agents
+     * is how one agent's generous limits become another's.
+     */
+    agentId?: string;
+    /**
+     * Risk level → action, exactly the `Policy` type Protect uses. Merged over
+     * `DEFAULT_AGENT_RISK_POLICY`; see that constant for why the agent default
+     * differs from the consumer one.
+     */
+    risk?: Policy;
+    /** Shorthand: deny anything strictly above this level. Applied on top of `risk`. */
+    maxRiskLevel?: RiskLevel;
+    maxValuePerActionUsd?: number;
+    /** Rolling cumulative caps. Several may run at once — per-hour and per-day. */
+    spendWindows?: SpendWindow[];
+    /**
+     * When present, an allowlist: any counterparty not in it is denied. Absent
+     * means unconstrained, which is a real choice an operator may make and not
+     * one AgentGuard makes for them.
+     */
+    allowedCounterparties?: string[];
+    /** Always denied, even if also allowlisted. Denial wins. */
+    blockedCounterparties?: string[];
+    /** When present, an allowlist over the contract the action calls. */
+    allowedContracts?: string[];
+    /** When present, an allowlist over `token`. */
+    allowedTokens?: string[];
+    allowedActions?: AgentActionType[];
+    deniedActions?: AgentActionType[];
+    allowedChains?: string[];
+    /** Default `false`. Set true only if an unbounded allowance is genuinely intended. */
+    allowUnlimitedApprovals?: boolean;
+    /** An agent stuck in a loop is a real failure mode, not a hypothetical one. */
+    rateWindows?: RateWindow[];
+    /** Above this value, a human decides even when every other rule passes. */
+    humanApprovalAboveUsd?: number;
+    /** At or above this level, a human decides even when the risk policy allows. */
+    humanApprovalAtRiskLevel?: RiskLevel;
+    /** What to do when Decentrys could not be reached. Default `escalate`. */
+    failMode?: AgentFailMode;
+}
+/**
+ * What AgentGuard does when the risk check could not run.
+ *
+ * Protect offers `open | warn | closed` and defaults to `warn`, which is right
+ * for a wallet: tell the person, let them decide. **`warn` is not offered
+ * here, because there is nobody to warn.** A warning delivered to an
+ * autonomous process is an allow that logs.
+ *
+ *  - `open`     — proceed on operator-set limits alone.
+ *  - `escalate` — the local policy still applies and still binds; only the
+ *                 external risk check is missing, so a human decides. **Default.**
+ *  - `closed`   — stop.
+ *
+ * `escalate` is the default because it is the only one of the three that
+ * loses nothing. `open` signs unscreened transactions during exactly the
+ * window an attacker would choose to create. `closed` halts the agent
+ * completely, which for a liquidation or a market-making agent is its own
+ * loss and pushes operators to configure `open` to avoid it. `escalate`
+ * spends a human's attention instead of the treasury, and where an integrator
+ * has no approval path it degrades to a stop — the safe direction.
+ *
+ * Note that a local rule that *denies* still denies during an outage. An
+ * unreachable Decentrys removes one input; it does not suspend the operator's
+ * limits.
+ */
+export type AgentFailMode = 'open' | 'escalate' | 'closed';
+/**
+ * Three outcomes, never two.
+ *
+ * Collapsing `require_human_approval` into `deny` loses the difference between
+ * "this must not happen" and "a person needs to look at this", and an operator
+ * who cannot see that difference in the log cannot tune the policy.
+ */
+export type AgentVerdict = 'allow' | 'require_human_approval' | 'deny';
+/** The rules AgentGuard can apply. Stable identifiers — they end up in logs. */
+export declare const AGENT_RULES: readonly ["AGENT_BINDING", "ACTION_TYPE", "CHAIN", "COUNTERPARTY", "CONTRACT", "TOKEN", "APPROVAL_ALLOWANCE", "VALUE_PER_ACTION", "CUMULATIVE_SPEND", "RATE_LIMIT", "RISK_LEVEL", "ASSESSMENT_AVAILABILITY", "HUMAN_APPROVAL_THRESHOLD"];
+export type AgentRuleId = (typeof AGENT_RULES)[number];
+/**
+ * `not_configured` and `not_applicable` are distinct and both are recorded.
+ *
+ * "There was no counterparty allowlist" and "there was one and this
+ * counterparty was on it" produce the same allow and mean completely
+ * different things to whoever reads the record afterwards.
+ */
+export type RuleOutcome = 'pass' | 'fail' | 'escalate' | 'not_applicable' | 'not_configured';
+export interface RuleEvaluation {
+    rule: AgentRuleId;
+    outcome: RuleOutcome;
+    /** One sentence naming the limit and what was seen against it. */
+    statement: string;
+    /** The configured bound, when there was one. */
+    limit?: string | number;
+    /** What this action presented against that bound. */
+    observed?: string | number;
+}
+export interface AgentDecision {
+    /** Stable id for this decision, carried into the reservation and the log. */
+    decisionId: string;
+    agentId: string;
+    verdict: AgentVerdict;
+    /** The failing or escalating rules, in evaluation order. Empty on a clean allow. */
+    reasons: string[];
+    /**
+     * Every rule that was considered, passing ones included.
+     *
+     * This is what makes an *allow* explainable. A record that lists only what
+     * went wrong cannot answer "why was this permitted", which is the question
+     * asked after the money is gone.
+     */
+    evaluations: RuleEvaluation[];
+    /** The Protect assessment this decision used, when one was obtained. */
+    assessment?: Assessment;
+    /** Why no assessment was available, when none was. */
+    assessmentUnavailable?: string;
+    /** Fingerprint of the sealed policy in force, so the record is reproducible. */
+    policyFingerprint: string;
+    policyVersion?: string;
+    /**
+     * Present on `allow` and `require_human_approval`. Value and rate budget is
+     * held against this id until it is confirmed or released; see `ledger.ts`.
+     */
+    reservationId?: string;
+    /** A digest of the action, so a log entry can be tied to what was proposed. */
+    actionDigest: string;
+    modelVersion: string;
+    decidedAt: string;
+}
+/**
+ * What actually happened to a reserved action.
+ *
+ * Recorded separately from the decision, because "AgentGuard allowed it" and
+ * "the agent then executed it" are different facts and an audit trail that
+ * conflates them cannot show an allow that was never used.
+ */
+export interface AgentOutcomeRecord {
+    decisionId: string;
+    state: 'confirmed' | 'released' | 'expired';
+    txHash?: string;
+    note?: string;
+    at: string;
+}
+//# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

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

package/dist/model.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * AgentGuard — the types.
+ *
+ * Protect informs a person, who then decides. AgentGuard sits in front of
+ * something with no judgement that will do exactly what it was told, at
+ * machine speed, as many times as its loop runs. Three consequences shape
+ * everything in this file:
+ *
+ *  1. **A warning is not a control.** Protect deliberately warns and never
+ *     blocks, because the person holding the keys should decide. An agent
+ *     cannot heed a warning — a warning it ignores is an allow with extra
+ *     words. So AgentGuard's outcomes are `allow`, `require_human_approval`
+ *     and `deny`, and the middle one means *stop and hand this to a person*.
+ *
+ *  2. **The operator is not the agent.** Limits are set by a human ahead of
+ *     time. The agent must not be able to widen them — not by argument, not by
+ *     mutating the object it was handed, not by passing an override. That is
+ *     enforced structurally in `policy.ts` (`sealPolicy`, `narrowPolicy`),
+ *     not by convention.
+ *
+ *  3. **Every decision must survive being questioned later.** "The agent spent
+ *     the treasury" is answered by an audit record that names each rule, the
+ *     limit it enforced and the value it observed. An allow that cannot be
+ *     explained is as bad as a wrong one, so a passing rule is recorded just
+ *     as loudly as a failing one.
+ *
+ * The risk model is *not* reimplemented here. Classification, the seven risk
+ * levels and `applyPolicy` come from `@decentrys/protect` unchanged; this
+ * package adds the limits an autonomous actor needs and a human does not.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_RULES = exports.AGENT_ACTION_TYPES = exports.AGENT_MODEL_VERSION = void 0;
+exports.AGENT_MODEL_VERSION = 'agent-1.0.0';
+// ---------------------------------------------------------------------------
+// What an agent proposes to do
+// ---------------------------------------------------------------------------
+/**
+ * The kinds of action a policy can talk about.
+ *
+ * These are coarse on purpose. "May swap, may not approve" is a sentence an
+ * operator can write and check; "may call selector 0x095ea7b3" is not. An
+ * action whose type the integrator cannot determine is `unknown`, which is a
+ * first-class value rather than a default — see `deniedActions` below.
+ */
+exports.AGENT_ACTION_TYPES = [
+    'transfer',
+    'swap',
+    'approve',
+    'contract_call',
+    'bridge',
+    'stake',
+    'unstake',
+    'deploy',
+    'sign_message',
+    'unknown',
+];
+/** The rules AgentGuard can apply. Stable identifiers — they end up in logs. */
+exports.AGENT_RULES = [
+    'AGENT_BINDING',
+    'ACTION_TYPE',
+    'CHAIN',
+    'COUNTERPARTY',
+    'CONTRACT',
+    'TOKEN',
+    'APPROVAL_ALLOWANCE',
+    'VALUE_PER_ACTION',
+    'CUMULATIVE_SPEND',
+    'RATE_LIMIT',
+    'RISK_LEVEL',
+    'ASSESSMENT_AVAILABILITY',
+    'HUMAN_APPROVAL_THRESHOLD',
+];
+//# sourceMappingURL=model.js.map

package/dist/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;;;AAIU,QAAA,mBAAmB,GAAG,aAAa,CAAC;AAEjD,8EAA8E;AAC9E,+BAA+B;AAC/B,8EAA8E;AAE9E;;;;;;;GAOG;AACU,QAAA,kBAAkB,GAAG;IAChC,UAAU;IACV,MAAM;IACN,SAAS;IACT,eAAe;IACf,QAAQ;IACR,OAAO;IACP,SAAS;IACT,QAAQ;IACR,cAAc;IACd,SAAS;CACD,CAAC;AAqLX,gFAAgF;AACnE,QAAA,WAAW,GAAG;IACzB,eAAe;IACf,aAAa;IACb,OAAO;IACP,cAAc;IACd,UAAU;IACV,OAAO;IACP,oBAAoB;IACpB,kBAAkB;IAClB,kBAAkB;IAClB,YAAY;IACZ,YAAY;IACZ,yBAAyB;IACzB,0BAA0B;CAClB,CAAC"}

package/dist/policy.d.ts

@@ -0,0 +1,137 @@
+/**
+ * The policy engine.
+ *
+ * Two things live here, and keeping them together is deliberate.
+ *
+ * **Sealing** is how "the agent cannot widen its own limits" stops being a
+ * convention. An operator writes an `AgentPolicy` and calls `sealPolicy()`.
+ * What comes back is deep-frozen, cloned away from the caller's own arrays,
+ * and carries a fingerprint of its contents. `AgentGuard` accepts nothing
+ * else, exposes no setter, and records the fingerprint on every decision. An
+ * agent handed a reference to that object can read it and cannot change it,
+ * and a policy that changed between two decisions cannot pretend it did not.
+ *
+ * The only way to derive a new policy is `narrowPolicy()`, which takes the
+ * stricter of every field. There is no widening path in this file at all —
+ * not a guarded one, not an admin one. A capability that does not exist
+ * cannot be reached by a sufficiently persuasive prompt.
+ *
+ * **Evaluation** is a pure function. `evaluatePolicy()` performs no I/O and
+ * reads no clock it was not given, so the same action, policy, assessment and
+ * usage always produce the same decision. That is what makes an audit record
+ * checkable rather than merely readable: an investigator can re-run it.
+ */
+import { type Assessment, type Policy } from '@decentrys/protect';
+import { type AgentAction, type AgentDecision, type AgentPolicy } from './model';
+import type { AgentUsage } from './ledger';
+/**
+ * How risk levels map to behaviour when nobody is watching.
+ *
+ * Protect's consumer default warns from CAUTION upward and blocks only
+ * `KNOWN_MALICIOUS`, because a person is reading the warning. Neither half of
+ * that transfers:
+ *
+ *  - **`warn` is not available to an agent.** It is mapped out entirely; see
+ *    `sealPolicy`, which refuses a `warn` in an agent risk policy rather than
+ *    quietly reinterpreting it.
+ *  - **CAUTION stays `allow`, and that is not laziness.** CAUTION is reached
+ *    by a single SIGNIFICANT *capability* — a pausable token, an upgradeable
+ *    router. Most serious protocols have one. Escalating there would send a
+ *    human hundreds of approvals a day, and a human who approves 500
+ *    escalations approves the 501st unread. The Sentinel stage recorded the
+ *    same failure for alerts; it is worse here, because the 501st is the one
+ *    that empties the treasury. The capability is still recorded on the
+ *    decision, so it is visible without being an interrupt.
+ *  - **ELEVATED_RISK upward escalates**, because at that point actual threat
+ *    signals with evidence exist and a person can weigh them.
+ *  - **`KNOWN_MALICIOUS` denies, and a denial is not escalatable.** It is the
+ *    one level that requires analyst-verified evidence, and there is no value
+ *    at which signing to confirmed malicious infrastructure is the right call.
+ *
+ * `CRITICAL_THREAT` escalates rather than denies for the reason Protect draws
+ * the same line: severe evidence that no analyst has confirmed is exactly the
+ * case where a person should look at the evidence.
+ */
+export declare const DEFAULT_AGENT_RISK_POLICY: Required<Policy>;
+/**
+ * The brand, as a real runtime symbol rather than a `declare`d type-only one.
+ *
+ * A type-only brand is erased at compile time, so an object cast to
+ * `SealedPolicy` would satisfy every check and carry no mark at all. This
+ * symbol is module-private and never exported, so the only way to obtain an
+ * object bearing it is to call `sealPolicy()` — which clones and freezes.
+ */
+declare const SEALED_POLICY: unique symbol;
+export interface SealedPolicy {
+    /**
+     * Structural, not decorative. A plain object literal is not assignable to
+     * `SealedPolicy`, so there is no way to hand `AgentGuard` a policy that did
+     * not go through `sealPolicy()` — including from inside a tool an agent
+     * controls.
+     */
+    readonly [SEALED_POLICY]: true;
+    readonly policy: Readonly<AgentPolicy>;
+    /**
+     * A content fingerprint. Not a cryptographic commitment — it exists so two
+     * decisions can be shown to have run under the same rules, and so a policy
+     * that changed mid-incident cannot be described afterwards as unchanged.
+     */
+    readonly fingerprint: string;
+    /**
+     * Configurations that are legal but deserve to be said out loud — a policy
+     * that permits confirmed-malicious counterparties, or one with no limits at
+     * all. Surfaced rather than refused: policy belongs to the integrator.
+     */
+    readonly warnings: readonly string[];
+}
+export declare function sealPolicy(policy: AgentPolicy): SealedPolicy;
+/**
+ * Derive a stricter policy. There is no counterpart that loosens one.
+ *
+ * Every field is combined by taking the tighter side: caps become the minimum,
+ * allowlists intersect, blocklists union, windows accumulate, and
+ * `allowUnlimitedApprovals` is true only if both sides say so. So a
+ * restriction supplied at call time — including one an agent composed itself —
+ * can only ever reduce what is permitted.
+ */
+export declare function narrowPolicy(base: SealedPolicy, restriction: AgentPolicy): SealedPolicy;
+export interface EvaluatePolicyInput {
+    action: AgentAction;
+    policy: SealedPolicy;
+    /** The Protect assessment, when one was obtained. */
+    assessment?: Assessment | null;
+    /** Why no assessment was obtained. Drives the `failMode` rule. */
+    assessmentUnavailable?: string;
+    /** Committed spend and admitted actions so far. Absent means none recorded. */
+    usage?: AgentUsage;
+    now?: Date;
+    /** Supplied by the caller so a decision and its reservation share an id. */
+    decisionId?: string;
+}
+/**
+ * Evaluate an action against a sealed policy.
+ *
+ * Every rule is evaluated, including after one has already failed. Stopping at
+ * the first failure would produce a record saying an action exceeded its value
+ * cap while omitting that its counterparty was also confirmed malicious — and
+ * an operator reading that would tune the cap and ship the same hole.
+ *
+ * The verdict is the worst outcome any rule reached: one `fail` denies, one
+ * `escalate` sends it to a person, and everything else allows.
+ */
+export declare function evaluatePolicy(input: EvaluatePolicyInput): AgentDecision;
+/** `unlimited`, or a number large enough that no real supply could exhaust it. */
+export declare function isUnlimitedAllowance(amount: string): boolean;
+export declare function describeDuration(ms: number): string;
+/**
+ * FNV-1a over canonical JSON.
+ *
+ * A change detector, not a commitment. It answers "were these two decisions
+ * made under the same rules" without a dependency and without a claim it
+ * cannot support; anyone needing tamper evidence should sign the record.
+ */
+export declare function fingerprint(value: unknown): string;
+/** `crypto.randomUUID` where it exists; a monotonic fallback everywhere else. */
+export declare function newDecisionId(): string;
+export {};
+//# sourceMappingURL=policy.d.ts.map

package/dist/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAEL,KAAK,UAAU,EAAE,KAAK,MAAM,EAC7B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAEL,KAAK,WAAW,EAAwB,KAAK,aAAa,EAC1D,KAAK,WAAW,EAEjB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAM3C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAQtD,CAAC;AAqBF;;;;;;;GAOG;AACH,QAAA,MAAM,aAAa,EAAE,OAAO,MAA+C,CAAC;AAE5E,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,CAAC,aAAa,CAAC,EAAE,IAAI,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,CAwC5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,GAAG,YAAY,CAgCvF;AAMD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,YAAY,CAAC;IACrB,qDAAqD;IACrD,UAAU,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAC/B,kEAAkE;IAClE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,+EAA+E;IAC/E,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,aAAa,CA2ExE;AA4LD,kFAAkF;AAClF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAY5D;AAoPD,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAMnD;AAiJD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQlD;AAaD,iFAAiF;AACjF,wBAAgB,aAAa,IAAI,MAAM,CAKtC"}