salt-agent-sdk 0.1.0 → 0.19.0

package/dist/delegations.js

@@ -18,7 +18,7 @@
 //    only channel available between two separately-hosted agents is the
 //    message text itself), and `register`'s timeout bounds each hop.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DELEGATION_TIMEOUT_MS = exports.MAX_DELEGATION_DEPTH = void 0;
+exports.FLOOR_REQUEST_MARKER = exports.DELEGATION_TIMEOUT_MS = exports.MAX_DELEGATION_DEPTH = void 0;
 exports.wrap = wrap;
 exports.parseIncoming = parseIncoming;
 exports.hasPending = hasPending;
@@ -27,6 +27,11 @@ exports.cancel = cancel;
 exports.resolveIfPending = resolveIfPending;
 exports.recordTrail = recordTrail;
 exports.drainTrail = drainTrail;
+exports.wrapConsult = wrapConsult;
+exports.stripConsultMarker = stripConsultMarker;
+exports.registerConsultAsker = registerConsultAsker;
+exports.consultAskerFor = consultAskerFor;
+const ids_js_1 = require("./ids.js");
 /** depth counts hops already taken; a call at depth >= this is refused, so a
  *  chain reaches at most MAX_DELEGATION_DEPTH+1 agents before the last one
  *  is forced to answer directly instead of delegating further. */
@@ -62,9 +67,12 @@ function parseIncoming(plaintext) {
 // concurrent delegation call into the same chat is a clean error (see
 // register below) rather than an ambiguous race over which reply belongs
 // to which caller.
+// Keyed by the lowercased chat id -- see identities.ts for why ids are
+// normalised before they are used as map keys.
 const pending = new Map();
+const mapKey = (id) => String(id).toLowerCase();
 function hasPending(chatId) {
-    return pending.has(chatId);
+    return pending.has(mapKey(chatId));
 }
 /**
  * Registers a wait for the next reply in `chatId` from `targetId`, and
@@ -73,15 +81,15 @@ function hasPending(chatId) {
  * if this chat already has a pending wait.
  */
 function register(chatId, targetId, timeoutMs) {
-    if (pending.has(chatId)) {
+    if (pending.has(mapKey(chatId))) {
         throw new Error("Already waiting on a reply from this agent in this chat -- wait for that to finish first.");
     }
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
-            pending.delete(chatId);
+            pending.delete(mapKey(chatId));
             reject(new Error(`No reply within ${Math.round(timeoutMs / 1000)}s -- the agent may be offline or slow.`));
         }, timeoutMs);
-        pending.set(chatId, { targetId, resolve, reject, timer });
+        pending.set(mapKey(chatId), { targetId, resolve, reject, timer });
     });
 }
 /**
@@ -90,11 +98,11 @@ function register(chatId, targetId, timeoutMs) {
  * registry entry doesn't leak (the caller throws its own error instead).
  */
 function cancel(chatId) {
-    const entry = pending.get(chatId);
+    const entry = pending.get(mapKey(chatId));
     if (!entry)
         return;
     clearTimeout(entry.timer);
-    pending.delete(chatId);
+    pending.delete(mapKey(chatId));
 }
 /**
  * Call right after decrypting an inbound message, before deciding whether
@@ -106,11 +114,16 @@ function cancel(chatId) {
  * entry on its own server.
  */
 function resolveIfPending(chatId, senderId, plaintext) {
-    const entry = pending.get(chatId);
-    if (!entry || entry.targetId !== senderId)
+    const entry = pending.get(mapKey(chatId));
+    // sameId, not `!==`: this decides whether an inbound message is THE reply
+    // being waited on. Comparing a uuid that came from a webhook body against one
+    // that came from a REST response is not guaranteed to match on casing, and a
+    // false negative here restarts the whole prompt cycle instead of completing
+    // the delegation.
+    if (!entry || !(0, ids_js_1.sameId)(entry.targetId, senderId))
         return false;
     clearTimeout(entry.timer);
-    pending.delete(chatId);
+    pending.delete(mapKey(chatId));
     entry.resolve(plaintext);
     return true;
 }
@@ -123,7 +136,7 @@ function resolveIfPending(chatId, senderId, plaintext) {
 // identities) never mix their trails.
 const trails = new Map();
 function trailKey(identityId, mainChatId) {
-    return `${identityId}:${mainChatId}`;
+    return `${mapKey(identityId)}:${mapKey(mainChatId)}`;
 }
 function recordTrail(identityId, mainChatId, entry) {
     const key = trailKey(identityId, mainChatId);
@@ -137,4 +150,47 @@ function drainTrail(identityId, mainChatId) {
     trails.delete(key);
     return entries;
 }
+// --- Consult lanes ---------------------------------------------------------
+//
+// A consult is a delegation that happens INLINE, in a lane off a chat both
+// parties are already in (actions.ts's consult_agent), rather than in a
+// separate 1:1 (delegate_to_agent). The reply-matching above (register/
+// resolveIfPending) is reused as-is -- consult_agent registers a pending
+// wait on the lane's own chat id exactly like delegate_to_agent does on a
+// delegation chat's id. What's new is the wire marker the CONSULT PROMPT
+// itself carries (stripped before the consulted agent's onMessage ever
+// sees it, same convention as the depth marker above), and a small
+// registry so the asking agent's OWN webhook.ts recognizes a request_floor
+// message arriving back in a lane it opened.
+const CONSULT_MARKER_RE = /^\[\[SALT-CONSULT room=[^\]\n]+\]\]\n/;
+/** Prefixes a consult prompt so the receiving end can strip it before the task text reaches that identity's agent logic. `roomId` is informational only -- the receiving side gets the authoritative room id from the lane's own `coaching_for_chat_id`, already server-verified. */
+function wrapConsult(roomId, text) {
+    return `[[SALT-CONSULT room=${roomId}]]\n${text}`;
+}
+/** Strips a leading SALT-CONSULT marker, if present. A no-op on anything else (an ordinary message, or an agent's plain-text reply). */
+function stripConsultMarker(text) {
+    return text.replace(CONSULT_MARKER_RE, "");
+}
+/** The exact marker request_floor (actions.ts) posts into a consult lane to ask the asker to hand off rather than keep relaying through the lane. webhook.ts treats a message starting with this as wire protocol -- never an onMessage prompt -- for whichever identity opened that lane. */
+exports.FLOOR_REQUEST_MARKER = "[[SALT-FLOOR-REQUEST]]";
+// laneChatId (lowercased) -> who opened it and from where. Bounded the same
+// way webhook.ts bounds its own dedup sets: a long-lived process consults a
+// great many lanes over time, and none of them need to be remembered once
+// they're old enough that a floor request on them is no longer plausible.
+const MAX_CONSULT_ASKERS = 2000;
+const consultAskers = new Map();
+/** Records that `askerId` opened `laneChatId` as a consult lane off `roomId`. Called by consult_agent right after the lane is opened. */
+function registerConsultAsker(laneChatId, askerId, roomId) {
+    const key = mapKey(laneChatId);
+    consultAskers.set(key, { askerId, roomId });
+    if (consultAskers.size > MAX_CONSULT_ASKERS) {
+        const oldest = consultAskers.keys().next().value;
+        if (oldest !== undefined)
+            consultAskers.delete(oldest);
+    }
+}
+/** Who opened `laneChatId` as a consult lane, and from where -- or undefined if this process didn't (or has forgotten). */
+function consultAskerFor(laneChatId) {
+    return consultAskers.get(mapKey(laneChatId));
+}
 //# sourceMappingURL=delegations.js.map

package/dist/delegations.js.map

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

package/dist/device/client.d.ts

@@ -0,0 +1,161 @@
+import { DeviceProtocolError, type ClickArgs, type DevicePauseReason, type DeviceResultOp, type FileResult, type ObservationResult, type ObserveArgs, type ScrollArgs, type ElementRef, type AppsResult, type Progress, type TaskResult } from "./protocol.js";
+import { type SaltId } from "../ids.js";
+/** Who the lane messages must be encrypted for: every reader's armored public
+ *  key. Carried by the `device_session_active` delivery. */
+export interface LaneReaders {
+    chatId: SaltId;
+    publicKeys: string[];
+}
+export type DeviceSessionStatus = "queued" | "requested" | "active" | "paused" | "ended";
+export interface DeviceSessionMeta {
+    id: SaltId;
+    device_id: SaltId;
+    agent_id: SaltId;
+    mandate_id: SaltId;
+    status: DeviceSessionStatus;
+    /** `queued` only: 1-based place in the device's queue. */
+    position?: number;
+    /** `paused` only. */
+    pause_reason?: DevicePauseReason;
+    chat?: {
+        id: SaltId;
+        readers: string[];
+    };
+    /** What the agent said it is doing when it opened (its own words, untrusted; null/absent when it gave none). */
+    intent?: string | null;
+}
+/** Thrown by a transport's openSession on `409 {code:"session_live", session_id}`:
+ *  this agent already has a live session on the device. open() reattaches. */
+export declare class DeviceSessionLiveError extends Error {
+    readonly sessionId: SaltId;
+    constructor(sessionId: SaltId);
+}
+/** A command was refused (or not sent) because the session is paused: the
+ *  person is using the machine, or a secure field needs them. Wait for the
+ *  `resumed` state (onState) and try again. */
+export declare class DevicePausedError extends DeviceProtocolError {
+    readonly reason: DevicePauseReason;
+    constructor(reason: DevicePauseReason);
+}
+/** What onState emits. */
+export type DeviceState = {
+    state: "queued";
+    position: number;
+} | {
+    state: "requested";
+} | {
+    state: "active";
+} | {
+    state: "paused";
+    reason: DevicePauseReason;
+} | {
+    state: "resumed";
+} | {
+    state: "ended";
+    reason: string;
+};
+/** The injected transport. httpDeviceTransport provides a real one. */
+export interface DeviceClientTransport {
+    /** POST /api/v1/devices/:id/sessions -> the created session: status
+     *  `requested` (device must approve locally), `active`, or `queued` (202,
+     *  another agent controls the device). Throws DeviceSessionLiveError on a 409
+     *  `session_live`. */
+    openSession(deviceId: SaltId, opts?: {
+        intent?: string;
+    }): Promise<DeviceSessionMeta>;
+    /** POST /api/v1/device_sessions/:sid/reattach -> {session, last_seq}. */
+    reattachSession?(sessionId: SaltId): Promise<{
+        session: DeviceSessionMeta;
+        last_seq: number;
+    }>;
+    /** GET /api/v1/device_sessions/:sid; used only to learn the lane readers when
+     *  a promotion delivery did not carry them. */
+    fetchSession?(sessionId: SaltId): Promise<DeviceSessionMeta>;
+    /** POST /api/v1/device_sessions/:sid/stop (subtract-only, idempotent). */
+    stopSession(sessionId: SaltId): Promise<void>;
+    /** Encrypt `plaintext` for the current lane readers and POST it as one lane
+     *  message. The transport owns the crypto and the readers; this module only
+     *  decides the plaintext. */
+    postCommand(plaintext: string, readers: LaneReaders): Promise<void>;
+}
+export interface DeviceClientOptions {
+    /** How long a session may sit in `requested` (waiting for the device's local
+     *  approval) before open() gives up. Does not run while `queued`. The server
+     *  ends an unanswered request after 2 minutes with `request_expired`;
+     *  default here is a touch longer so the server's own end reaches us first. */
+    approvalTimeoutMs?: number;
+    /** Per-command timeout waiting for a result. Default 30s. On timeout the
+     *  client sends `cancel {id}`. */
+    commandTimeoutMs?: number;
+    /** How long a command stays valid (header `exp`). Default COMMAND_TTL_MS. */
+    commandTtlMs?: number;
+}
+export interface DeviceResult {
+    op: DeviceResultOp;
+    body: unknown;
+}
+type Listener = (...args: unknown[]) => void;
+export interface DeviceClient {
+    /** Open a session. By default resolves when it is `active`, waiting through
+     *  `queued` (another agent controls the device) and `requested` (the device's
+     *  local approval) on `device_session` deliveries, never polling. Rejects if
+     *  the device declines, the request expires, or the mandate is gone. With
+     *  `{wait: false}` it returns at once with the state the server answered
+     *  (e.g. `queued` with `position`); watch onState for the rest. If this
+     *  agent already has a live session on the device (409 session_live) it
+     *  reattaches and continues at last_seq + 1. */
+    open(opts?: {
+        wait?: boolean;
+        intent?: string;
+    }): Promise<DeviceSessionMeta>;
+    observe(args?: ObserveArgs): Promise<ObservationResult>;
+    click(args: ClickArgs): Promise<void>;
+    type(text: string): Promise<void>;
+    key(keys: string[]): Promise<void>;
+    scroll(args: ScrollArgs): Promise<void>;
+    /** Confirm a named field/form through the accessibility layer (never a keystroke). */
+    submit(element: ElementRef): Promise<void>;
+    focusApp(app: string): Promise<void>;
+    listApps(): Promise<AppsResult>;
+    readFile(path: string): Promise<FileResult>;
+    writeFile(path: string, contentB64: string): Promise<void>;
+    /** Hand the computer ONE whole task (op `task`, grant `device.task`) and wait for its checked
+     *  result. `goal` is what the person asked for, in plain words (1..2000 characters); `doneWhen`
+     *  says how the device should check it worked (<= 500). The device does the work itself: command
+     *  output and screenshots never come back, only a `TaskResult` of words and numbers. Rejects with
+     *  `bad_args` before sending when the arguments are out of range, `unsupported` when the computer
+     *  cannot run tasks, `out_of_scope` without the grant or when the budget is spent. `onProgress`
+     *  gets each non-final line in order (at most one every 2 s, newest wins). Waits
+     *  `timeoutS + 30` s (default 180 + 30); on that timeout, or when `signal` aborts, it sends
+     *  `cancel` with the task's id as `re`. After an abort it waits up to 10 s for the device's
+     *  `stopped` result and resolves with it, else rejects. */
+    task(goal: string, opts?: {
+        doneWhen?: string;
+        maxSteps?: number;
+        timeoutS?: number;
+        onProgress?: (p: Progress) => void;
+        signal?: AbortSignal;
+    }): Promise<TaskResult>;
+    /** End the session (subtract-only). Safe to call more than once. */
+    stop(): Promise<void>;
+    /** The live session metadata, or null before open() / after it ended. */
+    session(): DeviceSessionMeta | null;
+    /** The pause reason while paused, else null. */
+    pausedReason(): DevicePauseReason | null;
+    /** Feed a `device_session` socket delivery in (promoted / queue_moved /
+     *  paused / resumed / ended, and the legacy active / ended types). The
+     *  consumer calls this from its dispatcher. */
+    handleDelivery(event: string, body: unknown): void;
+    /** Feed a decrypted lane message in (a result the device posted). Returns
+     *  true if it was a device result this client consumed. */
+    handleLaneMessage(plaintext: string): boolean;
+    on(event: "active" | "ended" | "ask", cb: Listener): void;
+    /** Session state changes: queued(position) / requested / active /
+     *  paused(reason) / resumed / ended(reason). Returns an unsubscribe. */
+    onState(cb: (s: DeviceState) => void): () => void;
+}
+export declare function createDeviceClient(transport: DeviceClientTransport, params: {
+    deviceId: SaltId;
+}, options?: DeviceClientOptions): DeviceClient;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/device/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/device/client.ts"],"names":[],"mappings":"AAiBA,OAAO,EAGL,mBAAmB,EAUnB,KAAK,SAAS,EAGd,KAAK,iBAAiB,EACtB,KAAK,cAAc,EAEnB,KAAK,UAAU,EAEf,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,UAAU,EAEf,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,UAAU,EAChB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAU,KAAK,MAAM,EAAE,MAAM,WAAW,CAAC;AAEhD;4DAC4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEzF,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qBAAqB;IACrB,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC,IAAI,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACzC,gHAAgH;IAChH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;8EAC8E;AAC9E,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBACf,SAAS,EAAE,MAAM;CAK9B;AAED;;+CAE+C;AAC/C,qBAAa,iBAAkB,SAAQ,mBAAmB;IACxD,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;gBACvB,MAAM,EAAE,iBAAiB;CAKtC;AAED,0BAA0B;AAC1B,MAAM,MAAM,WAAW,GACnB;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,KAAK,EAAE,WAAW,CAAA;CAAE,GACtB;IAAE,KAAK,EAAE,QAAQ,CAAA;CAAE,GACnB;IAAE,KAAK,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,GAC9C;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,GACpB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,uEAAuE;AACvE,MAAM,WAAW,qBAAqB;IACpC;;;0BAGsB;IACtB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACtF,yEAAyE;IACzE,eAAe,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,iBAAiB,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/F;mDAC+C;IAC/C,YAAY,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC7D,0EAA0E;IAC1E,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C;;iCAE6B;IAC7B,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrE;AAED,MAAM,WAAW,mBAAmB;IAClC;;;mFAG+E;IAC/E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;sCACkC;IAClC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,cAAc,CAAC;IACnB,IAAI,EAAE,OAAO,CAAC;CACf;AAkBD,KAAK,QAAQ,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;AAS7C,MAAM,WAAW,YAAY;IAC3B;;;;;;;oDAOgD;IAChD,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC7E,OAAO,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACxD,KAAK,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,sFAAsF;IACtF,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC5C,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D;;;;;;;;;+DAS2D;IAC3D,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK,IAAI,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC3H,OAAO,CAAC,UAAU,CAAC,CAAC;IACvB,oEAAoE;IACpE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,yEAAyE;IACzE,OAAO,IAAI,iBAAiB,GAAG,IAAI,CAAC;IACpC,gDAAgD;IAChD,YAAY,IAAI,iBAAiB,GAAG,IAAI,CAAC;IACzC;;mDAE+C;IAC/C,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IACnD;+DAC2D;IAC3D,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9C,EAAE,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,GAAG,KAAK,EAAE,EAAE,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1D;4EACwE;IACxE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACnD;AAED,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,qBAAqB,EAChC,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,EAC5B,OAAO,GAAE,mBAAwB,GAChC,YAAY,CAwhBd"}