@wastedcode/claudemux 0.2.0

package/dist/agents/types.d.ts

@@ -0,0 +1,252 @@
+import type { ClassifierRules } from "../state/types.js";
+import type { Message, PromptChoice } from "../types.js";
+/**
+ * A single boot dialog: how to recognize it and how to respond.
+ *
+ * @remarks
+ * Used by `src/session/boot.ts`'s dialog loop. Dialogs are tried in order
+ * for each pane snapshot — the first matcher wins. `respond.kind === "throw"`
+ * is the escape hatch for dialogs that mean "this is a setup error, not an
+ * auto-answerable prompt" (e.g. `login-method` under claudemux, which means
+ * the user is not authenticated — see `LoginRequired`).
+ */
+export interface BootDialog {
+    /** Stable identifier; used in `DialogStuck.dialogId`. */
+    id: string;
+    /** Returns `true` when the pane text indicates this dialog. */
+    matches(paneText: string): boolean;
+    /**
+     * What to send to dismiss the dialog. `key` sends a single keystroke and
+     * advances; `throw` raises a typed error keyed by `errorClass`.
+     */
+    respond: {
+        kind: "key";
+        key: "Enter" | "1" | "2" | "y" | "n";
+    } | {
+        kind: "throw";
+        errorClass: "LoginRequired";
+    };
+    /**
+     * Optional authority gate. A gated dialog represents an authority grant
+     * (e.g. trusting a folder) that the substrate must NOT auto-answer by
+     * default — it fails closed. `boot.ts` throws the gate's error *before*
+     * sending the response key unless the consumer explicitly opted in via the
+     * matching `CreateOptions` flag. Dismissing it otherwise would make a
+     * silent policy decision for the caller (north-star: "report state, the
+     * consumer decides policy").
+     */
+    gate?: {
+        /** The `CreateOptions` boolean that must be `true` to auto-answer. */
+        option: "trustWorkspace";
+        /** The error thrown when the gate is closed (not opted in). */
+        errorClass: "WorkspaceUntrusted";
+    };
+}
+/**
+ * Everything the substrate needs to know about a specific agent. Adding
+ * `codex` later = add `src/agents/codex.ts` and export an `AgentDef`.
+ *
+ * The substrate never imports from `src/backends/**` here. Layering is
+ * grep-enforced.
+ */
+export interface AgentDef {
+    /** Stable identifier (e.g. `"claude"`). */
+    readonly name: string;
+    /**
+     * Resolve the spawn argv for this agent.
+     *
+     * @param o.cwd — the working directory (plumbed by the session/backend layer).
+     * @param o.extraArgs — caller-supplied flags, passed through verbatim.
+     * @param o.sessionId — the substrate-minted (or caller-supplied) conversation
+     *   id the agent should run under. The agent decides whether and how to inject
+     *   it (claude maps it to `--session-id`); a caller's own identity flag in
+     *   `extraArgs` wins over it. Neutral here — the flag *string* is the agent's.
+     * @param o.sessionIdExplicit — `true` only when the consumer explicitly chose
+     *   the id (`create({ agentSessionId })`), `false`/absent when it was minted.
+     *   An explicit id that conflicts with an `extraArgs` identity flag is a
+     *   caller error → the agent throws a typed `ClaudemuxError`; a minted id is
+     *   silently suppressed by such a flag instead.
+     * @param o.sessionName — the session's human label, for typed-error context
+     *   on the conflict path (the session has not been spawned yet).
+     * @returns `agentSessionId` — the id the argv will **actually** run under (the
+     *   injected id, a caller's `extraArgs` id, or `undefined` when the agent
+     *   cannot know it, e.g. a bare `--resume`). `create()` surfaces *this* value,
+     *   never the mint variable — single source of truth.
+     */
+    buildArgv(o: {
+        cwd: string;
+        extraArgs?: string[];
+        sessionId?: string;
+        sessionIdExplicit?: boolean;
+        /**
+         * Neutral "resume this existing conversation" request from the session
+         * layer's `resume()`. The agent maps it to its own resume flag (claude:
+         * `--resume <id>`) and surfaces that id as `agentSessionId`. Mutually
+         * exclusive with `sessionId`/an `extraArgs` identity flag (choosing the id
+         * twice → typed conflict). Keeps the vendor flag inside the agent seam.
+         */
+        resumeFrom?: string;
+        sessionName?: string;
+    }): {
+        cmd: string;
+        argv: string[];
+        env?: Record<string, string>;
+        agentSessionId?: string;
+    };
+    /** Boot orchestration knobs. */
+    readonly boot: {
+        /** Ordered list of dialogs to try on each snapshot during boot. */
+        readonly dialogs: ReadonlyArray<BootDialog>;
+        /**
+         * Returns `true` when the bottom-N pane text indicates the REPL is
+         * ready for input. Must qualify by line context — see
+         * `engineer/wiki/tmux-capture-pane-the-bottom-n-trap` ("same glyph,
+         * different roles").
+         */
+        isReady(paneTextBottomN: string): boolean;
+    };
+    /** Classifier predicates for this agent. */
+    readonly rules: ClassifierRules;
+    /**
+     * Permission-prompt handling — how to *answer* the tool-approval menu the
+     * classifier detects via `rules.permissionPrompt`. The SOLE owner of this
+     * agent's menu option-order (claude: `1` approve-once / `2` approve-for-session
+     * / `3` deny), so the neutral {@link PromptChoice} → keystroke mapping stays
+     * out of the agent-agnostic layers (grep-enforced, like the dialog keys). The
+     * handle's `respond(choice)` calls {@link respondKey} and fires the returned
+     * key; one keystroke selects-and-confirms (no Enter — verified against
+     * authenticated claude 2.1.162).
+     *
+     * Optional: an agent that declares none has `respond()` throw
+     * `PromptResponseUnsupported` rather than the substrate guessing a digit (a
+     * wrong guess could pick "allow all"). Pairs with a non-empty
+     * `rules.permissionPrompt` — detection without an answer mapping would surface
+     * `awaiting{permission-prompt}` with no way to act on it.
+     */
+    readonly permissionPrompt?: {
+        /** The keystroke that selects {@link PromptChoice} in this agent's menu. */
+        respondKey(choice: PromptChoice): "1" | "2" | "3";
+    };
+    /**
+     * Reading the agent's session transcript. The **sole owner** of this agent's
+     * transcript knowledge — both *where* the file lives and *how* its records
+     * parse — so every claude-version-fragile bit stays in one file
+     * (grep-enforced). The agent-agnostic Observer reads the file and feeds its
+     * lines here; it never knows the schema or the path rule.
+     *
+     * Optional by **graceful degrade**, not by incompleteness: the Observer has
+     * landed and uses this whenever it's present (it backs `messagesSince` /
+     * `turnComplete` and fuses into the belief). An agent that omits it simply has
+     * no transcript channel — reads return empty and observation leans on hooks +
+     * pane. (claude implements it; a future agent may not.)
+     */
+    readonly transcript?: {
+        /**
+         * Absolute path of the on-disk transcript for a session id, or `null` if
+         * not found. Located by id across the agent's session store — never by
+         * recomputing the fragile cwd→path rule.
+         */
+        locate(o: {
+            agentSessionId: string;
+            home?: string;
+        }): string | null;
+        /**
+         * Parse one transcript line into a neutral {@link Message}, or `null` for a
+         * metadata record, a blank line, or a partial/half-flushed line.
+         */
+        parseLine(line: string): Message | null;
+        /**
+         * The raw ancestry link (`id` + optional `parentId`) of **any** transcript
+         * record that carries an identity — including non-message records (e.g.
+         * `attachment`) that an agent may thread *between* a prompt and its reply.
+         * Returns `null` for blank/partial lines and records with no id.
+         *
+         * Lets the consumer reconstruct the *full* causal graph and so detect
+         * message descendants even when the chain passes through records
+         * {@link parseLine} drops. Optional: when absent, descendant detection falls
+         * back to links between surfaced messages only.
+         */
+        parseEdge?(line: string): {
+            id: string;
+            parentId?: string;
+        } | null;
+        /**
+         * True when `message` starts a new user turn (a typed prompt), false for
+         * tool-result feedback that is also recorded turn-side.
+         */
+        isTurnStart(message: Message): boolean;
+    };
+    /**
+     * Hook-based turn observation — the SOLE owner of this agent's hook
+     * vocabulary (which events to wire, the settings shape, the marker format).
+     * The agent emits turn markers to a claudemux-owned local rendezvous; the
+     * Observer reads them as deterministic phase edges (no pane-scraping). The
+     * spawn layer injects {@link spec}'s flag at launch; the Observer parses each
+     * rendezvous line with {@link parseMarker}. Both live here so the
+     * hook-event strings stay out of the agent-agnostic layers (grep-enforced).
+     *
+     * Optional by **graceful degrade**, not by incompleteness: injection (the
+     * spawn layer) and the Observer have landed and use this whenever it's present
+     * (the reliable observe channel). An agent that omits it — or `create({ hooks:
+     * false })` — degrades honestly to the best-effort pane fallback
+     * (`hookChannelHealthy: false`), never silently.
+     */
+    readonly hooks?: {
+        /**
+         * The launch flag that wires this agent's turn hooks to append markers to
+         * `rendezvousPath`. Inspectable (transparency) and the one place that knows
+         * the settings shape. e.g. `{ flag: "--settings", value: "<json>" }`.
+         */
+        spec(o: {
+            rendezvousPath: string;
+        }): {
+            flag: string;
+            value: string;
+        };
+        /** Parse one rendezvous marker line into a neutral {@link HookEdge}, or null. */
+        parseMarker(line: string): HookEdge | null;
+    };
+}
+/**
+ * A neutral, deterministic turn-lifecycle edge derived from an agent hook —
+ * the reliable observe signal (vs pane-scraping). `event` is backend-neutral;
+ * the Observer composes a sequence of these into phase / toolInFlight / done.
+ *
+ * Beyond the bare edge, a hook payload also carries data the Observer fuses with
+ * the transcript and pane. Those fields are surfaced here as **neutral** concepts
+ * (`transcriptPath`, `source`, `finalMessage`); the agent's `parseMarker` owns
+ * translating its vendor payload (e.g. claude's `transcript_path` /
+ * `last_assistant_message`) into them, so vendor field names never leak past the
+ * agent seam (grep-enforced). All are optional — present only on the edges that
+ * carry them, and only for agents whose hooks expose them.
+ */
+export interface HookEdge {
+    readonly event: "session-start" | "prompt-submit" | "tool-start" | "tool-end" | "stop" | "notification" | "pre-compact" | "other";
+    /** Epoch milliseconds the hook fired. */
+    readonly at: number;
+    /** The agent session id the hook reported, when present. */
+    readonly sessionId?: string;
+    /** Tool name for `tool-start`/`tool-end` edges, when present. */
+    readonly tool?: string;
+    /**
+     * The **authoritative** absolute path of the session's durable transcript, as
+     * the hook reported it. The Observer prefers this over recomputing/globbing
+     * the on-disk location (the path rule is fragile). Present on most edges.
+     */
+    readonly transcriptPath?: string;
+    /**
+     * Why the session started — only on a `session-start` edge. Lets the Observer
+     * distinguish a fresh boot from a resume (expect a history re-print) or a
+     * post-compaction continuation, without inspecting the screen.
+     */
+    readonly source?: "start" | "resume" | "clear" | "compact";
+    /**
+     * A preview of the turn's terminal assistant text, as the agent reported it on
+     * the `stop` edge — available *before* the transcript flushes that record.
+     * The Observer uses it to close the hook→transcript flush skew: on `stop` it
+     * polls the transcript until the durable reply is present, rather than reading
+     * stale content the instant the edge fires.
+     */
+    readonly finalMessage?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/agents/types.d.ts.map

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

package/dist/agents/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/agents/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":""}

package/dist/backends/tmux/capture.d.ts

@@ -0,0 +1,25 @@
+import { type TmuxExec } from "./exec.js";
+/**
+ * Capture the named session's pane text.
+ *
+ * Always uses `capture-pane -p` (the live visible region — proven unaffected
+ * by copy-mode and attached clients; see
+ * `docs/decisions/0003-capture-pane-invocation.md`). Bottom-N
+ * slicing happens **in code** via `output.split('\n').slice(-N)`, NEVER
+ * `capture-pane -S -N` — the latter returns `N + pane_height` lines, not
+ * bottom-N (see `engineer/wiki/tmux-capture-pane-the-bottom-n-trap`).
+ *
+ * `-e` flag is added only when the caller passes `ansi: true`; the default
+ * is plain text (which is what the classifier matches against anyway).
+ *
+ * A gone session surfaces as `SessionGone` via {@link runForSession} (the
+ * canonical per-session mapping). The substrate runs `remain-on-exit off`, so a
+ * dead pane is reaped rather than left annotated — there is no separate
+ * pane-dead path to handle.
+ */
+export declare function capturePane(exec: TmuxExec, target: string, opts?: {
+    ansi?: boolean;
+    lines?: number;
+    label?: string;
+}): Promise<string>;
+//# sourceMappingURL=capture.d.ts.map

package/dist/backends/tmux/capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../../src/backends/tmux/capture.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAiB,MAAM,WAAW,CAAC;AAEzD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,MAAM,EACd,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5D,OAAO,CAAC,MAAM,CAAC,CAejB"}

package/dist/backends/tmux/capture.js

@@ -0,0 +1,35 @@
+import { runForSession } from "./exec.js";
+/**
+ * Capture the named session's pane text.
+ *
+ * Always uses `capture-pane -p` (the live visible region — proven unaffected
+ * by copy-mode and attached clients; see
+ * `docs/decisions/0003-capture-pane-invocation.md`). Bottom-N
+ * slicing happens **in code** via `output.split('\n').slice(-N)`, NEVER
+ * `capture-pane -S -N` — the latter returns `N + pane_height` lines, not
+ * bottom-N (see `engineer/wiki/tmux-capture-pane-the-bottom-n-trap`).
+ *
+ * `-e` flag is added only when the caller passes `ansi: true`; the default
+ * is plain text (which is what the classifier matches against anyway).
+ *
+ * A gone session surfaces as `SessionGone` via {@link runForSession} (the
+ * canonical per-session mapping). The substrate runs `remain-on-exit off`, so a
+ * dead pane is reaped rather than left annotated — there is no separate
+ * pane-dead path to handle.
+ */
+export async function capturePane(exec, target, opts = {}) {
+    const label = opts.label ?? target;
+    const args = ["capture-pane", "-p"];
+    if (opts.ansi === true)
+        args.push("-e");
+    args.push("-t", target);
+    // Per-session read: a dead server means THIS session is gone (canonical
+    // SessionGone), matching the write path — not a divergent BackendUnreachable.
+    const r = await runForSession(exec, args, label);
+    if (opts.lines !== undefined && opts.lines > 0) {
+        const lines = r.stdout.split("\n");
+        return lines.slice(-opts.lines).join("\n");
+    }
+    return r.stdout;
+}
+//# sourceMappingURL=capture.js.map

package/dist/backends/tmux/capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.js","sourceRoot":"","sources":["../../../src/backends/tmux/capture.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,aAAa,EAAE,MAAM,WAAW,CAAC;AAEzD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAc,EACd,MAAc,EACd,OAA2D,EAAE;IAE7D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC;IACnC,MAAM,IAAI,GAAG,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;IACpC,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;QAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAExB,wEAAwE;IACxE,8EAA8E;IAC9E,MAAM,CAAC,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IAEjD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;QAC/C,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACnC,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,CAAC,CAAC,MAAM,CAAC;AAClB,CAAC"}

package/dist/backends/tmux/exec.d.ts

@@ -0,0 +1,105 @@
+import type { BackendEvent } from "../types.js";
+/**
+ * tmux stderr patterns that indicate "the backend's server is not reachable
+ * on this socket." Older tmux says `no server running on /tmp/.../sock`;
+ * tmux ≥3.3 says `error connecting to /tmp/.../sock (No such file or
+ * directory)`. We treat both as the same condition (server's gone).
+ *
+ * Single-source — callers (`sessions.ts`, `classifyTmuxFailure`) import
+ * from here so the regex can't drift.
+ */
+export declare function isNoServerStderr(text: string): boolean;
+export declare function isSessionGoneStderr(text: string): boolean;
+/**
+ * tmux stderr shape when `new-session -s <name>` races another process
+ * creating the same target. With the shared default socket (ADR 0006),
+ * concurrent `spawn`s of the same name are routine, and the TOCTOU window
+ * between `create()`'s exists-check and `backend.spawn()` means tmux —
+ * not the substrate's check — sometimes discovers the collision. The
+ * semantically-correct typed error is `SessionExists`, same as a check-time
+ * collision: the substrate refuses to silently adopt either way.
+ */
+export declare function isDuplicateSessionStderr(text: string): boolean;
+/**
+ * Raw result of one tmux invocation. Callers (sessions.ts, keys.ts,
+ * capture.ts) interpret this — typed errors are thrown at the caller, not
+ * here, because only the caller knows the session-name context for the error.
+ */
+export interface TmuxResult {
+    readonly exit: number;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly durationMs: number;
+}
+/**
+ * One executor instance per backend. Holds the private socket name and the
+ * observability emitter. Every tmux invocation goes through {@link run}; that
+ * is what enforces the `-f /dev/null` + `-L <socket>` discipline tree-wide.
+ *
+ * See `engineer/wiki/tmux-private-server-bootstrap` — bare `-L` does not
+ * prevent `~/.tmux.conf` reads; both flags are required.
+ */
+export declare class TmuxExec {
+    #private;
+    readonly socket: string;
+    constructor(socket: string);
+    /** Subscribe to every tmux invocation + result. Returns unsubscribe. */
+    onCommand(handler: (e: BackendEvent) => void): () => void;
+    /**
+     * Spawn `tmux -L <socket> -f /dev/null <args...>` and capture both streams —
+     * stdout for the op's payload (e.g. `capture-pane`), stderr for failure
+     * classification (`can't find …` → `SessionGone`, etc.).
+     *
+     * @throws `BackendUnreachable` — `spawn-failed` on spawn error (ENOENT,
+     *   EPIPE), `no-server` when the server isn't running on a connect-only
+     *   operation, `timeout` when the invocation doesn't return within
+     *   `opts.timeoutMs` (default {@link DEFAULT_EXEC_TIMEOUT_MS}). The
+     *   session-name field on the typed error is the *requested* session.
+     */
+    run(args: string[], opts?: {
+        sessionName?: string;
+        input?: string;
+        timeoutMs?: number;
+    }): Promise<TmuxResult>;
+}
+/**
+ * Classify a non-zero `TmuxResult` into a typed error. Callers use this when
+ * the operation was expected to succeed; for idempotent ops (kill), callers
+ * inspect `result.exit` + stderr directly and choose to swallow SessionGone.
+ *
+ * Returns `null` if the result looks successful (exit 0 with no error
+ * annotation on stdout), otherwise the right typed error to throw.
+ *
+ * `sessionName` is the requested target (so the error carries the right
+ * context even when tmux's stderr names something else).
+ *
+ * Order matters: `BackendUnreachable` (no server) > `SessionExists`
+ * (duplicate-session race) > `SessionGone` (target doesn't exist) >
+ * `BackendError` (unrecognized failure). The routine failure modes are
+ * promoted above `BackendError` so the substrate surfaces a clean typed
+ * error rather than the catch-all. As a structural backstop,
+ * `BackendError.message` itself does not embed the tmux argv (see
+ * `errors.ts`), so even an unclassified shape cannot leak the backend's
+ * vocabulary into user-facing text.
+ */
+export declare function classifyTmuxFailure(sessionName: string, argv: readonly string[], result: TmuxResult): Error | null;
+/** Is this the `no-server` {@link BackendUnreachable} (empty/down server)? */
+export declare function isNoServer(err: unknown): boolean;
+/**
+ * Run a tmux op that targets ONE named session, applying the **canonical
+ * per-session failure mapping** — the single place reads and writes share so the
+ * same crash can't surface as two different errors again (the read/write drift).
+ *
+ * From a single session's vantage, a `no-server` failure means *this session is
+ * gone* → {@link SessionGone}, NOT a distinct backend fault. (Registry ops —
+ * `list`/`exists` — keep treating no-server as plain absence; `BackendUnreachable`
+ * is left to mean a *real* backend fault: `spawn-failed` / `timeout`.) The
+ * canonical answer holds whether no-server arrives as a rejection (the common
+ * path) or as a returned non-zero result.
+ *
+ * Returns the raw {@link TmuxResult} on success; throws the typed error otherwise.
+ */
+export declare function runForSession(exec: TmuxExec, args: readonly string[], label: string, opts?: {
+    input?: string;
+}): Promise<TmuxResult>;
+//# sourceMappingURL=exec.d.ts.map

package/dist/backends/tmux/exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../../src/backends/tmux/exec.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAaD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE9D;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAaD;;;;;;;GAOG;AACH,qBAAa,QAAQ;;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGZ,MAAM,EAAE,MAAM;IAI1B,wEAAwE;IACxE,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI;IAIzD;;;;;;;;;;OAUG;IACG,GAAG,CACP,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACtE,OAAO,CAAC,UAAU,CAAC;CAiFvB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,UAAU,GACjB,KAAK,GAAG,IAAI,CAqBd;AAED,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEhD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5B,OAAO,CAAC,UAAU,CAAC,CAcrB"}