@kya-os/cli 1.8.1 → 1.8.3

package/dist/orchestrator/hub-dispatch.js

@@ -0,0 +1,257 @@
+/**
+ * The TUI's one control-plane action (review-loop P18 commit 4): dispatch
+ * a task to a connected agent.
+ *
+ * Trust boundary: this opens a short-lived, authenticated observer
+ * connection -- the SAME wire pattern `hub-observer.ts`'s long-lived
+ * `HubObserver` uses (contracts `./handshake`'s hello/challenge/proof
+ * frames, the #686 precedent), reusing its exported helpers rather than
+ * re-deriving the handshake. It sends exactly one `fleet.dispatch` frame,
+ * waits for exactly one `fleet.dispatch.result`, and closes -- no
+ * reconnect, no history, no long-lived state, because a TUI keystroke is
+ * a single request, not a subscription.
+ *
+ * `fleet.dispatch` here is NOT `@kya-os/compute`'s HTTP `fleet-mcp`
+ * surface (`packages/compute/src/didcomm/fleet-mcp.ts`), which is bearer-
+ * token/org-scoped and has no notion of a per-agent signing key. It is
+ * the wire-level message `packages/compute/src/didcomm/hub.ts` already
+ * handles directly on an admitted OBSERVER socket
+ * (`ws.on("message", ...)` inside `transport.onObserver`): a JSON frame
+ * `{ type: "fleet.dispatch", taskId, toDid, description, context?,
+ * timeoutMs? }`, answered with `{ type: "fleet.dispatch.result", taskId,
+ * status, response?, error?, ... }`. Reusing this existing hub-side
+ * handler is why this file adds nothing to `@kya-os/contracts` or
+ * `@kya-os/compute` -- the wire shape already exists and this PR's
+ * `Package:` line is `@kya-os/cli` alone.
+ *
+ * The hub proposes, the target's on-disk command allowlist (P17, epic
+ * decision 10) disposes: a refusal comes back as an ordinary
+ * `fleet.dispatch.result` with a non-"completed" status, which the caller
+ * renders as a refusal, not an error (see `AgentsView`'s handling of
+ * `status === "refused"`).
+ *
+ * @module cli/orchestrator/hub-dispatch
+ */
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import WebSocket from "ws";
+import { DIDCommChallengeSchema, DIDCommProofSchema } from "@kya-os/contracts/handshake";
+import { buildObserverHello, signChallenge, isPlaintextNonLoopback, LOOPBACK_HOSTS, } from "./hub-observer.js";
+import { signingKeyPath } from "../utils/dco/paths.js";
+import { parseEd25519SshPrivateKeyPem } from "../utils/dco/ssh-key.js";
+import { readHubConfig } from "../utils/hub-config.js";
+const DEFAULT_HANDSHAKE_TIMEOUT_MS = 10000;
+const DEFAULT_DISPATCH_TIMEOUT_MS = 30000;
+/**
+ * Opens one observer connection, authenticates if asked to, sends one
+ * `fleet.dispatch` frame for `targetDid`/`command`, and resolves with its
+ * `fleet.dispatch.result` -- or rejects on a connection/handshake/timeout
+ * failure. Always closes the socket before settling, on every path.
+ */
+export function dispatchTask(config, targetDid, command) {
+    return new Promise((resolve, reject) => {
+        const ws = (config.wsFactory ?? ((endpoint) => new WebSocket(endpoint)))(config.endpoint);
+        const taskId = randomUUID().slice(0, 8);
+        let settled = false;
+        let handshakeDone = false;
+        let dispatchTimer;
+        const finish = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(handshakeTimer);
+            if (dispatchTimer)
+                clearTimeout(dispatchTimer);
+            try {
+                ws.close();
+            }
+            catch {
+                /* already closing/closed */
+            }
+            if (outcome instanceof Error)
+                reject(outcome);
+            else
+                resolve(outcome);
+        };
+        const handshakeTimer = setTimeout(() => {
+            finish(new Error(`hub at ${config.endpoint} did not complete the observer handshake in time`));
+        }, config.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT_MS);
+        ws.on("open", () => {
+            try {
+                ws.send(JSON.stringify(buildObserverHello(config.identity)));
+            }
+            catch (err) {
+                finish(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+        ws.on("message", (raw) => {
+            void handleFrame(raw.toString());
+        });
+        async function handleFrame(text) {
+            let msg;
+            try {
+                const parsed = JSON.parse(text);
+                if (typeof parsed !== "object" || parsed === null)
+                    return;
+                msg = parsed;
+            }
+            catch {
+                return; // a frame we cannot parse is not a frame we can act on
+            }
+            const type = msg["type"];
+            if (type === "challenge") {
+                const challenge = DIDCommChallengeSchema.safeParse(msg);
+                if (!challenge.success || !config.identity)
+                    return;
+                try {
+                    const jws = await signChallenge(config.identity, challenge.data.nonce);
+                    ws.send(JSON.stringify(DIDCommProofSchema.parse({ type: "proof", jws })));
+                }
+                catch (err) {
+                    finish(err instanceof Error ? err : new Error(String(err)));
+                }
+                return;
+            }
+            // "snapshot" is the hub's readiness signal (same as HubObserver):
+            // the handshake is complete exactly once this arrives. Only send
+            // the dispatch frame on the FIRST snapshot -- a hub that (unusually)
+            // sent more than one must not trigger a second dispatch.
+            if (type === "snapshot" && !handshakeDone) {
+                handshakeDone = true;
+                clearTimeout(handshakeTimer);
+                try {
+                    ws.send(JSON.stringify({
+                        type: "fleet.dispatch",
+                        taskId,
+                        toDid: targetDid,
+                        description: command,
+                        timeoutMs: config.dispatchTimeoutMs ?? DEFAULT_DISPATCH_TIMEOUT_MS,
+                    }));
+                }
+                catch (err) {
+                    finish(err instanceof Error ? err : new Error(String(err)));
+                    return;
+                }
+                dispatchTimer = setTimeout(() => {
+                    finish(new Error("dispatch timed out waiting for a result"));
+                }, config.dispatchTimeoutMs ?? DEFAULT_DISPATCH_TIMEOUT_MS);
+                return;
+            }
+            if (type === "fleet.dispatch.result" && msg["taskId"] === taskId) {
+                const status = typeof msg["status"] === "string" ? msg["status"] : "unknown";
+                finish({
+                    taskId,
+                    status,
+                    response: typeof msg["response"] === "string" ? msg["response"] : undefined,
+                    error: typeof msg["error"] === "string" ? msg["error"] : undefined,
+                    // Allowlist, not a blacklist: `status` here is whatever the
+                    // target agent's own task-response body reports, forwarded
+                    // verbatim by the hub (dispatchAndWait in
+                    // packages/compute/src/didcomm/hub.ts has no fixed status enum
+                    // and no "failed" handling of its own). A blacklist of known
+                    // failure strings reads any UNANTICIPATED one -- including the
+                    // agent-reported "failed" itself -- as success. "completed" is
+                    // the one value both that hub code and fleet-server's HubClient
+                    // (packages/fleet-server/src/hub-client.ts, the other existing
+                    // consumer of this same fleet.dispatch.result message) treat as
+                    // an unambiguous success; that HubClient collapses everything
+                    // else to a failure the same way.
+                    ok: status === "completed",
+                });
+            }
+        }
+        ws.on("error", (err) => finish(err));
+        ws.on("close", (code, reason) => {
+            if (settled)
+                return;
+            finish(new Error(`hub closed the connection (${code}${reason.length ? `: ${reason.toString()}` : ""})`));
+        });
+    });
+}
+/**
+ * Is this endpoint loopback-only? Mirrors `isPlaintextNonLoopback`'s host
+ * set but answers a different question: that function asks "is this
+ * unencrypted AND remote" (a warn-but-allow case); this asks "is this
+ * unreachable from anywhere but this machine" (the ONLY case where
+ * connecting with no identity at all -- `--anonymous`-equivalent -- is
+ * appropriate for a write action like dispatch).
+ */
+export function isLoopbackEndpoint(endpoint) {
+    try {
+        return LOOPBACK_HOSTS.has(new URL(endpoint).hostname.toLowerCase());
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Builds the identity used to authenticate the dispatch connection, from
+ * the profile whose row is focused in the TUI. Every profile's key
+ * lives under `~/.mcpi/keys/<slug>` in the SSH-signing format
+ * `dco setup` writes (see `signing-key-writer.ts`); profiles never
+ * persist a raw seed on disk, so the seed is recovered from that SSH
+ * key via the same parser `dco fix` already uses to sign a fix
+ * attestation from the same file (`parseEd25519SshPrivateKeyPem`) rather
+ * than adding a second place that stores key material.
+ *
+ * Authenticating AS the profile being dispatched to -- rather than some
+ * separate "which of my identities is primary" concept, which does not
+ * exist anywhere else in this codebase -- is a deliberate scope
+ * decision: every profile under `~/.mcpi/keys/` belongs to the one
+ * operator running this TUI, so proving control of the row already in
+ * view is sufficient authorization and needs no new concept.
+ *
+ * Undefined if the key file is missing or not in the format this
+ * codebase writes -- the caller falls back to loopback-only anonymous
+ * dispatch in that case, matching `orchestrator daemon`'s own
+ * `--anonymous` precedent.
+ */
+export function resolveProfileIdentity(profile) {
+    try {
+        const pem = readFileSync(signingKeyPath(profile.slug), "utf-8");
+        const { seed } = parseEd25519SshPrivateKeyPem(pem);
+        return { did: profile.did, privateKey: seed.toString("base64") };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The TUI-facing entry point: resolve the hub and the dispatching
+ * identity, dispatch, and reduce every failure mode (no hub configured,
+ * no usable key on a non-loopback hub, a transport/handshake error) to
+ * the same `DispatchOutcome` shape the agents view renders -- so the UI
+ * never has to distinguish "the wire call threw" from "the wire call
+ * returned an unhappy status".
+ */
+export async function dispatchToProfile(profile, command, wsFactory) {
+    const hubConfig = readHubConfig();
+    if (!hubConfig) {
+        return { ok: false, status: "error", detail: "no hub configured (~/.mcpi/hub.json is absent)" };
+    }
+    const warning = isPlaintextNonLoopback(hubConfig.endpoint)
+        ? `${hubConfig.endpoint} is plaintext ws:// to a non-loopback host -- the DID, public key, and signed proof are sent unencrypted.`
+        : undefined;
+    const identity = resolveProfileIdentity(profile);
+    if (!identity && !isLoopbackEndpoint(hubConfig.endpoint)) {
+        return {
+            ok: false,
+            status: "error",
+            detail: `no usable signing key for ${profile.slug}, and ${hubConfig.endpoint} is not loopback`,
+            warning,
+        };
+    }
+    try {
+        const result = await dispatchTask({ endpoint: hubConfig.endpoint, identity, wsFactory }, profile.did, command);
+        return { ok: result.ok, status: result.status, detail: result.error ?? result.response, warning };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            status: "error",
+            detail: error instanceof Error ? error.message : String(error),
+            warning,
+        };
+    }
+}
+//# sourceMappingURL=hub-dispatch.js.map

package/dist/orchestrator/hub-dispatch.js.map

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

package/dist/orchestrator/hub-observer.d.ts

@@ -0,0 +1,201 @@
+/**
+ * A coordination hub, observed from outside its process.
+ *
+ * This is what makes the daemon host pluggable. `OrchestratorDaemon` takes a
+ * structural `EventSource` -- `onEvent` plus `getRecentEvents` -- rather than the
+ * concrete hub, so anything that can supply those two methods can drive it. In
+ * process, the hub itself supplies them. Here they come over a WebSocket, which
+ * lets the daemon run wherever the operator already runs things and attach to
+ * whichever hub they already point their agents at.
+ *
+ * The CLI deliberately does not depend on @kya-os/compute: compute is PID 1 in a
+ * Fly worker, this is a published CLI. So the observer protocol is spoken
+ * directly, against the wire format in @kya-os/contracts/handshake rather than
+ * a copy of it. (Not `/proof`: both a `proof.ts` and a `proof/index.ts` exist
+ * there, and Node and tsc disagree about which one that subpath means.)
+ *
+ * ## Why connect() waits for the snapshot
+ *
+ * `getRecentEvents` is synchronous, because in-process it reads an array. Over a
+ * socket the history arrives in a frame, so `connect()` does not resolve until
+ * that frame lands. A daemon started before it arrives would reconcile against
+ * an empty window and silently skip the recovery a restart exists to perform --
+ * the failure mode is a quiet no-op, which is the kind that survives review.
+ *
+ * @module cli/orchestrator/hub-observer
+ */
+import { type ObserverHello } from "@kya-os/contracts/handshake";
+import { type EventSource, type HubEventLike } from "./events.js";
+/** The identity fields this needs out of `.mcpi/identity.json`. */
+export interface ObserverIdentity {
+    did: string;
+    /** Raw Ed25519 seed, base64 — the shape identity.json stores. */
+    privateKey: string;
+}
+export interface HubObserverConfig {
+    /** e.g. `ws://127.0.0.1:18821`, normally from DIDCOMM_HUB_ENDPOINT. */
+    endpoint: string;
+    /** Omit to observe anonymously, which only a loopback hub will accept. */
+    identity?: ObserverIdentity;
+    /** How long to wait for the snapshot before giving up on a connection. */
+    handshakeTimeoutMs?: number;
+    /** Reconnect backoff ceiling. */
+    maxBackoffMs?: number;
+}
+/**
+ * Read an identity file, returning undefined rather than throwing.
+ *
+ * A missing or malformed identity is a normal state -- the operator may not have
+ * run `dco setup` -- and it only matters if the hub demands authentication. The
+ * hub's rejection message says far more about what is wrong than a parse error
+ * raised here would.
+ */
+export declare function readObserverIdentity(path: string): ObserverIdentity | undefined;
+/** The public JWK the hub needs to bind a did:key to the presented key. */
+export declare function publicJwkFor(identity: ObserverIdentity): string;
+/**
+ * The `observe` hello frame for an optional identity -- shared by every
+ * observer-wire client (this file's long-lived `HubObserver` and
+ * `hub-dispatch.ts`'s short-lived one-shot client), so the two cannot
+ * silently drift on what an anonymous vs. authenticated hello looks like.
+ */
+export declare function buildObserverHello(identity?: ObserverIdentity): ObserverHello;
+/** Sign the hub's challenge, per the wire format in contracts. */
+export declare function signChallenge(identity: ObserverIdentity, nonce: string): Promise<string>;
+/**
+ * Validate a raw `challenge` frame and, if well-formed, answer it: sign its
+ * nonce and build the wire `proof` frame to send back. Returns `undefined`
+ * for a frame that fails `DIDCommChallengeSchema` (not this caller's to
+ * handle -- the same "ignore, don't fail" choice both callers already made
+ * before this was factored out). Every caller of the observer
+ * `observe`/`challenge`/`proof` handshake shares this exact step -- {@link
+ * HubObserver}'s long-lived `connect()` and the one-shot
+ * `github-credential-anchor-sender.ts` -- so it lives here once rather than
+ * being reimplemented per caller.
+ */
+export declare function respondToObserverChallenge(identity: ObserverIdentity, rawChallenge: unknown): Promise<string | undefined>;
+/**
+ * Hosts that need no transport encryption because nothing off this machine
+ * can reach them. Both `::1` and `[::1]` are listed because `URL#hostname`
+ * keeps an IPv6 literal's brackets rather than stripping them.
+ */
+export declare const LOOPBACK_HOSTS: Set<string>;
+/**
+ * Is this an unencrypted `ws://` endpoint pointed somewhere other than this
+ * machine?
+ *
+ * A loopback hub genuinely does not need TLS -- nothing but this machine can
+ * see the socket. Anything else sends the DID, the public key, and the signed
+ * proof of possession over a transport anyone on the path can read; `wss://`
+ * is the production default for exactly this reason, and a plain `ws://` to a
+ * remote host is far more likely a dev config that escaped dev than a
+ * deliberate choice. An endpoint this cannot even parse is left alone: it
+ * fails at `connect()`, with a clearer error than anything said here.
+ */
+export declare function isPlaintextNonLoopback(endpoint: string): boolean;
+export declare class HubObserver implements EventSource {
+    private readonly config;
+    private ws;
+    private handlers;
+    private history;
+    private closedByUs;
+    private backoffMs;
+    /**
+     * Has a handshake ever completed?
+     *
+     * Reconnecting is only right after a connection that WORKED. Retrying a first
+     * failure means a misconfigured or unauthorised hub is retried forever in the
+     * background while the caller has already been told it failed -- a daemon that
+     * looks alive and records nothing, which is the outcome connect() rejects to
+     * avoid.
+     */
+    private hasConnected;
+    /** The pending reconnect. Held so close() can cancel it, not merely ignore it. */
+    private reconnectTimer;
+    /**
+     * Serializes `handleFrame` across messages.
+     *
+     * `ws.on("message")` fires and forgets (`void this.handleFrame(...)`), which
+     * was harmless while every frame finished synchronously within one tick.
+     * Retrying a replay's failed write does not: it `await`s a `setTimeout`, and
+     * without this queue a live frame arriving during that wait ran a SECOND,
+     * concurrent `handleFrame` -- pushing onto `this.history` right before the
+     * still-in-flight snapshot handler clobbered it with `this.history = window`,
+     * and dispatching that live event ahead of the gap it was meant to follow
+     * (review finding on #686). Chaining onto this instead makes every frame
+     * fully finish before the next one starts, socket-wide.
+     */
+    private frameQueue;
+    constructor(config: HubObserverConfig);
+    /** Queue a frame behind whatever is still being processed for this socket. */
+    private enqueueFrame;
+    /**
+     * Connect, authenticate if asked to, and resolve once the snapshot has landed.
+     *
+     * Rejects rather than retrying: a first connection that cannot authenticate is
+     * a configuration problem, and retrying it forever would leave a daemon that
+     * looks alive and records nothing. Reconnection after a WORKING connection is
+     * a different case and is handled silently below.
+     */
+    connect(): Promise<void>;
+    private handleFrame;
+    /**
+     * Hand one event to every handler, once.
+     *
+     * Shared by live delivery and reconnect replay (through {@link
+     * dispatchReplayed}) so the two cannot diverge -- a replay that skipped a
+     * handler would recover the journal and not the ticket status, which reads
+     * as the reactor having run and disagreed. Returns whether every handler
+     * succeeded, so a caller that can retry (replay) knows whether it needs to.
+     *
+     * This is now the ONLY place a handler's failure is caught. The handlers
+     * themselves (`registerJournalWriter`, `registerReviewReactor`) deliberately
+     * do not swallow their own write errors -- a handler that always reports
+     * success by catching internally makes `allOk` a lie, which is what made
+     * `dispatchReplayed`'s retry dead code against the real handlers even though
+     * it worked against a mock that threw directly.
+     */
+    private dispatch;
+    /**
+     * Dispatch one event from a reconnect's gap replay, retrying instead of
+     * letting a write failure disappear it.
+     *
+     * All handlers together, every attempt, not just the ones that failed: safe
+     * because journal ids are content-derived and verdicts are keyed on their
+     * subject, so re-dispatching an event a handler already wrote collapses
+     * rather than double-applying. SQLite's own `busy_timeout` already absorbs a
+     * same-instant lock collision between two writers; this covers whatever
+     * survives that -- a slower disk, any other transient failure -- during the
+     * one window where a dropped write has no later chance to be recovered.
+     */
+    private dispatchReplayed;
+    /**
+     * Schedule the next attempt.
+     *
+     * The timer is deliberately NOT unref'd, and that is the whole point. While
+     * reconnecting there is no socket, and in `kya-os orchestrator daemon` the
+     * socket is the only handle keeping the process alive -- the liveness beat is
+     * unref'd and the command holds no stdin. An unref'd timer here therefore let
+     * the process exit during the exact window it was supposed to be recovering
+     * in: a hub restart quietly killed the daemon, with no error and no exit
+     * message. This timer stands in for the socket, so it has to hold the loop
+     * exactly as the socket does.
+     *
+     * The rule the two now share: the observer owns the daemon's liveness while
+     * it is attached or trying to be, and everything else (the beat, the signal
+     * handlers) is incidental and stays unref'd.
+     */
+    private scheduleReconnect;
+    /**
+     * Is a reconnect scheduled -- i.e. is this observer still holding the process
+     * open on purpose? Distinguishes a cancelled timer from a merely neutered one,
+     * which is invisible from the outside and is the difference between a stopped
+     * daemon exiting and hanging.
+     */
+    hasPendingReconnect(): boolean;
+    onEvent(handler: (event: HubEventLike) => void): () => void;
+    getRecentEvents(limit?: number): HubEventLike[];
+    /** Stop observing. Idempotent, and suppresses the reconnect. */
+    close(): void;
+}
+//# sourceMappingURL=hub-observer.d.ts.map

package/dist/orchestrator/hub-observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub-observer.d.ts","sourceRoot":"","sources":["../../src/orchestrator/hub-observer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH,OAAO,EAML,KAAK,aAAa,EACnB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAsB,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAEtF,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,0EAA0E;IAC1E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iCAAiC;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAkB/E;AAED,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAG/D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,CAAC,EAAE,gBAAgB,GAAG,aAAa,CAK7E;AAED,kEAAkE;AAClE,wBAAsB,aAAa,CACjC,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,gBAAgB,EAC1B,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAK7B;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,aAAsD,CAAC;AAElF;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQhE;AAsBD,qBAAa,WAAY,YAAW,WAAW;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,EAAE,CAAwB;IAClC,OAAO,CAAC,QAAQ,CAA4C;IAC5D,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,SAAS,CAAO;IACxB;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY,CAAS;IAC7B,kFAAkF;IAClF,OAAO,CAAC,cAAc,CAA4C;IAClE;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,UAAU,CAAoC;gBAE1C,MAAM,EAAE,iBAAiB;IAIrC,8EAA8E;IAC9E,OAAO,CAAC,YAAY;IAUpB;;;;;;;OAOG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAyEV,WAAW;IA8FzB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,QAAQ;IAkBhB;;;;;;;;;;;OAWG;YACW,gBAAgB;IAa9B;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,iBAAiB;IAmBzB;;;;;OAKG;IACH,mBAAmB,IAAI,OAAO;IAI9B,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI;IAO3D,eAAe,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE;IAI/C,gEAAgE;IAChE,KAAK,IAAI,IAAI;CAYd"}