@elizaos/plugin-computeruse 2.0.0-beta.1 → 2.0.3-beta.3

package/dist/routes/computer-use-compat-routes.d.ts

@@ -21,7 +21,7 @@ type CompatRuntimeState = {
 export declare function handleComputerUseCompatRoutes(req: http.IncomingMessage, res: http.ServerResponse, state: CompatRuntimeState): Promise<boolean>;
 /**
  * Runtime plugin route adapter. The runtime plugin route bridge passes
- * `(req, res, runtime)` — wrap into a CompatRuntimeState stub for the
+ * `(req, res, runtime)` — wrap into a CompatRuntimeState adapter for the
  * shared dispatcher.
  */
 export declare function computerUseRouteHandler(): (req: unknown, res: unknown, runtime: unknown) => Promise<void>;

package/dist/routes/computer-use-compat-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"computer-use-compat-routes.d.ts","sourceRoot":"","sources":["../../src/routes/computer-use-compat-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAGlC,KAAK,kBAAkB,GAAG;IACxB,OAAO,EAAE;QACP,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;KACxC,GAAG,IAAI,CAAC;CACV,CAAC;AAyRF,wBAAsB,6BAA6B,CACjD,GAAG,EAAE,IAAI,CAAC,eAAe,EACzB,GAAG,EAAE,IAAI,CAAC,cAAc,EACxB,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,OAAO,CAAC,CA+JlB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,KAEnC,KAAK,OAAO,EACZ,KAAK,OAAO,EACZ,SAAS,OAAO,KACf,OAAO,CAAC,IAAI,CAAC,CAMjB"}
+{"version":3,"file":"computer-use-compat-routes.d.ts","sourceRoot":"","sources":["../../src/routes/computer-use-compat-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,KAAK,kBAAkB,GAAG;IACxB,OAAO,EAAE;QACP,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;KACxC,GAAG,IAAI,CAAC;CACV,CAAC;AA6RF,wBAAsB,6BAA6B,CACjD,GAAG,EAAE,IAAI,CAAC,eAAe,EACzB,GAAG,EAAE,IAAI,CAAC,cAAc,EACxB,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,OAAO,CAAC,CA+JlB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,KAEnC,KAAK,OAAO,EACZ,KAAK,OAAO,EACZ,SAAS,OAAO,KACf,OAAO,CAAC,IAAI,CAAC,CAMjB"}

package/dist/sandbox/docker-backend.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Docker sandbox backend.
+ *
+ * Spawns a Docker container with X11 + xdotool + scrot pre-installed (the
+ * caller must build or pull such an image — default name `cua/linux:latest`)
+ * and proxies every CUA op through `docker exec` against an in-container
+ * helper. The helper is a self-contained Python script that this backend
+ * `docker cp`s into the running container at `start()`.
+ *
+ * Why a helper instead of running each op as its own xdotool/scrot shell?
+ *   - Single entry point makes the wire format consistent across all ops.
+ *   - Saves us from re-encoding key/modifier mappings per call.
+ *   - Keeps the transport isolated from the driver operation mapping.
+ *
+ * The image MUST satisfy:
+ *   - python3 on PATH
+ *   - xdotool, scrot installed
+ *   - an X session reachable on $DISPLAY (or Xvfb running)
+ *   - bash on PATH
+ *
+ * We do NOT ship the image. The default name `cua/linux:latest` is a
+ * convention only; operators bring their own.
+ */
+import { type ChildProcessWithoutNullStreams } from "node:child_process";
+import { type SandboxBackend, type SandboxOp } from "./types.js";
+export interface DockerBackendOptions {
+    /** Container image (default `cua/linux:latest`). */
+    image: string;
+    /** Extra `docker run` args (mounts, networks, ...). Optional. */
+    runArgs?: string[];
+    /** Env vars exposed inside the container. */
+    env?: Record<string, string>;
+    /** Override the Docker CLI binary (default `docker`). */
+    dockerBinary?: string;
+    /**
+     * Override the helper transport. Tests inject a fake that bypasses the
+     * actual `docker exec` spawn. Production code does not pass this.
+     */
+    spawnExec?: (binary: string, args: string[]) => ChildProcessWithoutNullStreams;
+    /**
+     * Override the synchronous shell-out used for `docker run`/`docker rm`/
+     * `docker cp`. Tests inject a fake.
+     */
+    runShell?: (binary: string, args: string[]) => Promise<{
+        stdout: string;
+        stderr: string;
+        code: number;
+    }>;
+}
+export declare class DockerBackend implements SandboxBackend {
+    readonly name = "docker";
+    private containerId;
+    private helper;
+    private pending;
+    private stdoutBuffer;
+    private readonly image;
+    private readonly runArgs;
+    private readonly env;
+    private readonly dockerBinary;
+    private readonly spawnExec;
+    private readonly runShell;
+    constructor(options?: DockerBackendOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    invoke<TResult>(op: SandboxOp): Promise<TResult>;
+    private handleStdout;
+    private handleHelperExit;
+}
+//# sourceMappingURL=docker-backend.d.ts.map

package/dist/sandbox/docker-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docker-backend.d.ts","sourceRoot":"","sources":["../../src/sandbox/docker-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,KAAK,8BAA8B,EAAS,MAAM,oBAAoB,CAAC;AAIhF,OAAO,EACL,KAAK,cAAc,EAGnB,KAAK,SAAS,EACf,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,yDAAyD;IACzD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,SAAS,CAAC,EAAE,CACV,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EAAE,KACX,8BAA8B,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,EAAE,CACT,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EAAE,KACX,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChE;AAoMD,qBAAa,aAAc,YAAW,cAAc;IAClD,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,MAAM,CAA+C;IAC7D,OAAO,CAAC,OAAO,CAIN;IACT,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAW;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAyB;IAC7C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiD;IAC3E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgD;gBAE7D,OAAO,GAAE,oBAA+C;IAY9D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAgEtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBrB,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;IActD,OAAO,CAAC,YAAY;IAkCpB,OAAO,CAAC,gBAAgB;CAWzB"}

package/dist/sandbox/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Sandbox subsystem barrel + mode-selection seam.
+ *
+ * This module is the single dispatch site for picking between the host
+ * (`yolo`) execution path and a sandboxed (`sandbox`) execution path. Nothing
+ * downstream branches on `mode`; callers receive a `Driver` and use it.
+ *
+ *   - `createSandboxDriver(opts)` constructs a `SandboxDriver` wired to the
+ *     requested backend (`docker`). Throws
+ *     `SandboxBackendUnavailableError` if the backend cannot be constructed.
+ *   - `getCurrentDriver(runtime)` consults `ComputerUseService.getConfig()`
+ *     and returns either the host driver shim or a sandbox driver. This is
+ *     the canonical mode-selection seam; if you find yourself writing
+ *     `if (mode === 'sandbox')` somewhere, route through this instead.
+ */
+import type { IAgentRuntime } from "@elizaos/core";
+import type { ComputerUseMode, SandboxBackendName, SandboxBackendOptions, SandboxConfig } from "../types.js";
+import { type DockerBackendOptions } from "./docker-backend.js";
+import { SandboxDriver } from "./sandbox-driver.js";
+import { type Driver, type SandboxBackend } from "./types.js";
+export interface CreateSandboxDriverOptions {
+    backend: SandboxBackendName;
+    image: string;
+    options?: SandboxBackendOptions;
+    /**
+     * Test-only hook: inject a pre-built backend instead of constructing one.
+     * Production callers do not pass this.
+     */
+    backendOverride?: SandboxBackend;
+    /** Test-only Docker constructor overrides. */
+    dockerOverrides?: Pick<DockerBackendOptions, "spawnExec" | "runShell" | "dockerBinary">;
+}
+/**
+ * Construct a `SandboxDriver` for the requested backend. The driver is not
+ * started here — `SandboxDriver` lazily boots on first op so callers don't
+ * pay for a container start until they actually need one.
+ */
+export declare function createSandboxDriver(opts: CreateSandboxDriverOptions): SandboxDriver;
+/**
+ * Mode-selection seam. Returns either the host driver (yolo) or a sandbox
+ * driver (sandbox). Called by the dispatch layer; never branched on by
+ * callers.
+ *
+ * NOTE: when `mode === 'yolo'` we currently return `null`. The host
+ * `Driver`-shaped wrapper around `platform/driver.ts` lands in the same
+ * series as the rest of the dispatch refactor; the existing
+ * `ComputerUseService` calls into `platform/driver.ts` directly. Treat
+ * `null` as "use the legacy in-service host path".
+ */
+export declare function getCurrentDriver(runtime: IAgentRuntime): Driver | null;
+/** Resolve the `ComputerUseMode` from raw env input. Exported for testing. */
+export declare function resolveModeFromEnv(raw: string | undefined): ComputerUseMode;
+export type { DockerBackendOptions } from "./docker-backend.js";
+export { DockerBackend } from "./docker-backend.js";
+export { QEMUBackend, type QemuBackendOptions, type QemuLauncher, } from "./qemu-backend.js";
+export { type GuestRpcRequest, type GuestRpcResponse, HttpGuestTransport, RemoteGuestBackend, type RemoteGuestTransport, resolveGuestRpcUrl, sandboxOpToRpc, } from "./remote-guest.js";
+export { SandboxDriver } from "./sandbox-driver.js";
+export type { FileActionResult, ProcessInfoLite, ScreenRegion, TerminalActionResult, WindowInfo, } from "./surface-types.js";
+export { type Driver, type SandboxBackend, SandboxBackendUnavailableError, SandboxInvocationError, type SandboxOp, type ScrollDirection, } from "./types.js";
+export { isWindowsSandboxAvailable, WSBBackend, type WsbBackendOptions, type WsbLauncher, } from "./wsb-backend.js";
+export type { SandboxConfig };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,KAAK,EACV,eAAe,EACf,kBAAkB,EAClB,qBAAqB,EACrB,aAAa,EACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAiB,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE/E,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACL,KAAK,MAAM,EACX,KAAK,cAAc,EAEpB,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC;;;OAGG;IACH,eAAe,CAAC,EAAE,cAAc,CAAC;IACjC,8CAA8C;IAC9C,eAAe,CAAC,EAAE,IAAI,CACpB,oBAAoB,EACpB,WAAW,GAAG,UAAU,GAAG,cAAc,CAC1C,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,0BAA0B,GAC/B,aAAa,CAsCf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAmBtE;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,CAG3E;AAED,YAAY,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACL,WAAW,EACX,KAAK,kBAAkB,EACvB,KAAK,YAAY,GAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,KAAK,oBAAoB,EACzB,kBAAkB,EAClB,cAAc,GACf,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,oBAAoB,EACpB,UAAU,GACX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,KAAK,MAAM,EACX,KAAK,cAAc,EACnB,8BAA8B,EAC9B,sBAAsB,EACtB,KAAK,SAAS,EACd,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,yBAAyB,EACzB,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,WAAW,GACjB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,aAAa,EAAE,CAAC"}

package/dist/sandbox/qemu-backend.d.ts

@@ -0,0 +1,48 @@
+/**
+ * QEMU provider backend (#9170 M13).
+ *
+ * QEMU boots a full guest VM (any OS image) and forwards a host port to the
+ * in-guest computer-server (`-netdev user,hostfwd=tcp::<port>-:<port>`). The
+ * host then drives it over the generic remote-guest RPC (`{command,params}` →
+ * `{success,result}`) — see `remote-guest.ts`.
+ *
+ * Availability is gated on a `qemu-system-*` binary being present; absent, the
+ * backend throws `SandboxBackendUnavailableError` rather than silently falling
+ * back to the host. The launcher + transport are injectable so boot/teardown is
+ * unit-testable without a real hypervisor.
+ */
+import { RemoteGuestBackend, type RemoteGuestTransport } from "./remote-guest.js";
+/** Host-side controller for the QEMU VM lifecycle (injectable for tests). */
+export interface QemuLauncher {
+    /** Boot QEMU with the guest image + host-forwarded RPC port. */
+    launch(args: {
+        image: string;
+        rpcPort: number;
+    }): Promise<void>;
+    /** Power off / kill the VM. */
+    shutdown(): Promise<void>;
+    /** Probe whether a usable qemu-system binary exists. */
+    isAvailable(): boolean;
+}
+export interface QemuBackendOptions {
+    image: string;
+    rpcUrl?: string;
+    rpcPort?: number;
+    transport?: RemoteGuestTransport;
+    launcher?: QemuLauncher;
+    /** Availability override (tests). */
+    available?: boolean;
+}
+export declare class QEMUBackend extends RemoteGuestBackend {
+    readonly name = "qemu";
+    private readonly image;
+    private readonly rpcPort;
+    private readonly _transport;
+    private readonly launcher;
+    private started;
+    constructor(opts: QemuBackendOptions);
+    protected transport(): RemoteGuestTransport;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=qemu-backend.d.ts.map

package/dist/sandbox/qemu-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qemu-backend.d.ts","sourceRoot":"","sources":["../../src/sandbox/qemu-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAEL,kBAAkB,EAClB,KAAK,oBAAoB,EAE1B,MAAM,mBAAmB,CAAC;AAG3B,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,MAAM,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,+BAA+B;IAC/B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,wDAAwD;IACxD,WAAW,IAAI,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,qCAAqC;IACrC,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAID,qBAAa,WAAY,SAAQ,kBAAkB;IACjD,QAAQ,CAAC,IAAI,UAAU;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAC/C,OAAO,CAAC,OAAO,CAAS;gBAEZ,IAAI,EAAE,kBAAkB;IAoBpC,SAAS,CAAC,SAAS,IAAI,oBAAoB;IAIrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAK5B"}

package/dist/sandbox/remote-guest.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Remote-guest RPC seam (#9170 M13).
+ *
+ * trycua/cua's host talks to an in-guest `computer-server` over a single
+ * generic RPC: send `{command, params}` and get back `{success, result}`. Every
+ * VM/sandbox provider (Windows Sandbox, QEMU, cloud) is just a different way of
+ * (a) booting the guest and (b) transporting that one RPC.
+ *
+ * elizaOS already has a typed `SandboxOp` envelope and a Docker backend that
+ * speaks it. This module bridges the two: `RemoteGuestBackend` is a
+ * `SandboxBackend` whose `invoke(op)` translates the typed op into the generic
+ * `{command, params}` RPC, sends it through a pluggable `RemoteGuestTransport`,
+ * and maps the `{success, result}` response back. Provider backends (WSB, QEMU)
+ * subclass it and only supply boot/teardown + a transport.
+ *
+ * The transport is injectable so the whole path is unit-testable with a fake
+ * (no VM, no network), and so a provider can swap HTTP for virtio-serial etc.
+ */
+import { type SandboxBackend, type SandboxOp } from "./types.js";
+/** The generic cua RPC request: a command name + arbitrary params. */
+export interface GuestRpcRequest {
+    command: string;
+    params: Record<string, unknown>;
+}
+/** The generic cua RPC response. `result` is present on success. */
+export interface GuestRpcResponse {
+    success: boolean;
+    result?: unknown;
+    error?: string;
+}
+/** Transport for the `{command, params}` → `{success, result}` RPC. */
+export interface RemoteGuestTransport {
+    readonly name: string;
+    dispatch(request: GuestRpcRequest): Promise<GuestRpcResponse>;
+}
+/**
+ * Translate a typed `SandboxOp` into the generic cua `{command, params}` RPC.
+ * Pure — exported for unit tests. Command names follow cua's computer-server
+ * verb vocabulary so a stock cua guest answers them unchanged.
+ */
+export declare function sandboxOpToRpc(op: SandboxOp): GuestRpcRequest;
+/** HTTP transport: POSTs the RPC as JSON to a guest URL via `fetch`. */
+export declare class HttpGuestTransport implements RemoteGuestTransport {
+    readonly name = "http";
+    private readonly url;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(opts: {
+        url: string;
+        fetchImpl?: typeof fetch;
+        timeoutMs?: number;
+    });
+    dispatch(request: GuestRpcRequest): Promise<GuestRpcResponse>;
+}
+/**
+ * A `SandboxBackend` that speaks the generic remote-guest RPC. Subclasses
+ * (WSB, QEMU) supply boot/teardown and a transport; everything else — the
+ * op→RPC translation and the response unwrap — is shared here.
+ */
+export declare abstract class RemoteGuestBackend implements SandboxBackend {
+    abstract readonly name: string;
+    protected abstract transport(): RemoteGuestTransport;
+    abstract start(): Promise<void>;
+    abstract stop(): Promise<void>;
+    invoke<TResult>(op: SandboxOp): Promise<TResult>;
+}
+/** Resolve the guest RPC URL from explicit url → port → default. Pure. */
+export declare function resolveGuestRpcUrl(opts: {
+    rpcUrl?: string;
+    rpcPort?: number;
+}): string;
+//# sourceMappingURL=remote-guest.d.ts.map

package/dist/sandbox/remote-guest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-guest.d.ts","sourceRoot":"","sources":["../../src/sandbox/remote-guest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EACL,KAAK,cAAc,EAEnB,KAAK,SAAS,EACf,MAAM,YAAY,CAAC;AAEpB,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,uEAAuE;AACvE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC/D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,SAAS,GAAG,eAAe,CAkE7D;AAWD,wEAAwE;AACxE,qBAAa,kBAAmB,YAAW,oBAAoB;IAC7D,QAAQ,CAAC,IAAI,UAAU;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,IAAI,EAAE;QAChB,GAAG,EAAE,MAAM,CAAC;QACZ,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;QACzB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;IAMK,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAwBpE;AAED;;;;GAIG;AACH,8BAAsB,kBAAmB,YAAW,cAAc;IAChE,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC/B,SAAS,CAAC,QAAQ,CAAC,SAAS,IAAI,oBAAoB;IAEpD,QAAQ,CAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAC/B,QAAQ,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAExB,MAAM,CAAC,OAAO,EAAE,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;CAavD;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,MAAM,CAIT"}

package/dist/sandbox/sandbox-driver.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `SandboxDriver` — implements the host-equivalent `Driver` interface by
+ * proxying every CUA op to a `SandboxBackend`. The mode-selection seam in
+ * `services/computer-use-service.ts` instantiates either this or the host
+ * driver exactly once at start; nothing downstream knows which.
+ *
+ * Inspired by the architecture of trycua/cua's BaseComputer/BaseProvider split
+ * (MIT, https://github.com/trycua/cua) — but a clean re-implementation. We
+ * make no runtime dependency on the trycua Python library.
+ */
+import type { FileActionResult, ProcessInfoLite, ScreenRegion, TerminalActionResult, WindowInfo } from "./surface-types.js";
+import type { Driver, SandboxBackend, ScrollDirection } from "./types.js";
+export declare class SandboxDriver implements Driver {
+    private readonly backend;
+    readonly name: string;
+    private started;
+    constructor(backend: SandboxBackend);
+    /** Lazily boots the backend on first op. Idempotent. */
+    private ensureStarted;
+    mouseMove(x: number, y: number): Promise<void>;
+    mouseClick(x: number, y: number): Promise<void>;
+    mouseDoubleClick(x: number, y: number): Promise<void>;
+    mouseRightClick(x: number, y: number): Promise<void>;
+    mouseDrag(x1: number, y1: number, x2: number, y2: number): Promise<void>;
+    mouseScroll(x: number, y: number, direction: ScrollDirection, amount: number): Promise<void>;
+    keyboardType(text: string): Promise<void>;
+    keyboardKeyPress(key: string): Promise<void>;
+    keyboardHotkey(combo: string): Promise<void>;
+    screenshot(region?: ScreenRegion): Promise<Buffer>;
+    listWindows(): Promise<WindowInfo[]>;
+    focusWindow(windowId: string): Promise<void>;
+    listProcesses(): Promise<ProcessInfoLite[]>;
+    runCommand(command: string, options?: {
+        cwd?: string;
+        timeoutSeconds?: number;
+    }): Promise<TerminalActionResult>;
+    readFile(targetPath: string): Promise<FileActionResult>;
+    writeFile(targetPath: string, content: string): Promise<FileActionResult>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=sandbox-driver.d.ts.map

package/dist/sandbox/sandbox-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-driver.d.ts","sourceRoot":"","sources":["../../src/sandbox/sandbox-driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,oBAAoB,EACpB,UAAU,EACX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAkB1E,qBAAa,aAAc,YAAW,MAAM;IAI9B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,OAAO,CAAS;gBAEK,OAAO,EAAE,cAAc;IAIpD,wDAAwD;YAC1C,aAAa;IAQrB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK9C,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK/C,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrD,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpD,SAAS,CACb,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,IAAI,CAAC;IAKV,WAAW,CACf,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,SAAS,EAAE,eAAe,EAC1B,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC;IAaV,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKzC,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5C,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5C,UAAU,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAWlD,WAAW,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAQpC,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ5C,aAAa,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAU3C,UAAU,CACd,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GAClD,OAAO,CAAC,oBAAoB,CAAC;IAU1B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAQvD,SAAS,CACb,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,CAAC;IAStB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAK/B"}

package/dist/sandbox/surface-types.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Re-exports of the shared CUA surface types the driver layer consumes. Kept
+ * separate from `./types.ts` to keep the sandbox barrel free of churn when
+ * upstream `../types.ts` evolves.
+ */
+export type { FileActionResult, ScreenRegion, TerminalActionResult, WindowInfo, } from "../types.js";
+/**
+ * Subset of `ProcessInfo` exposed across the driver boundary. The full type
+ * lives in `platform/process-list.ts` which depends on host-only modules; we
+ * deliberately keep the sandbox surface minimal so backends don't have to
+ * reproduce any host-only fields.
+ */
+export interface ProcessInfoLite {
+    pid: number;
+    name: string;
+}
+//# sourceMappingURL=surface-types.d.ts.map

package/dist/sandbox/surface-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-types.d.ts","sourceRoot":"","sources":["../../src/sandbox/surface-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,oBAAoB,EACpB,UAAU,GACX,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd"}

package/dist/sandbox/types.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Driver / sandbox-backend types.
+ *
+ * The `Driver` interface is the single dispatch surface that both the yolo
+ * (host) path and the sandbox path implement. Anything that wants to drive a
+ * machine — host path or Docker container — implements this one shape. The mode-selection seam in
+ * `services/computer-use-service.ts` picks an instance once at start; nothing
+ * downstream branches on `mode`.
+ */
+import type { FileActionResult, ProcessInfoLite, ScreenRegion, TerminalActionResult, WindowInfo } from "./surface-types.js";
+export type ScrollDirection = "up" | "down" | "left" | "right";
+/**
+ * Single dispatch surface for a CUA executor (host or sandbox).
+ *
+ * Methods are deliberately kept narrow and primitive. The richer
+ * approval/normalisation/screenshot-after-action policy lives one layer up in
+ * `ComputerUseService`; the driver only knows how to talk to its target.
+ */
+export interface Driver {
+    /** Stable name for diagnostics + tests. */
+    readonly name: string;
+    mouseMove(x: number, y: number): Promise<void>;
+    mouseClick(x: number, y: number): Promise<void>;
+    mouseDoubleClick(x: number, y: number): Promise<void>;
+    mouseRightClick(x: number, y: number): Promise<void>;
+    mouseDrag(x1: number, y1: number, x2: number, y2: number): Promise<void>;
+    mouseScroll(x: number, y: number, direction: ScrollDirection, amount: number): Promise<void>;
+    keyboardType(text: string): Promise<void>;
+    keyboardKeyPress(key: string): Promise<void>;
+    keyboardHotkey(combo: string): Promise<void>;
+    screenshot(region?: ScreenRegion): Promise<Buffer>;
+    listWindows(): Promise<WindowInfo[]>;
+    focusWindow(windowId: string): Promise<void>;
+    listProcesses(): Promise<ProcessInfoLite[]>;
+    runCommand(command: string, options?: {
+        cwd?: string;
+        timeoutSeconds?: number;
+    }): Promise<TerminalActionResult>;
+    readFile(targetPath: string): Promise<FileActionResult>;
+    writeFile(targetPath: string, content: string): Promise<FileActionResult>;
+    /** Free any sandbox/container/process resources. Called once at service stop. */
+    dispose(): Promise<void>;
+}
+/**
+ * Backend-internal contract: the smallest surface a sandbox backend
+ * (Docker) must expose. The `SandboxDriver` proxies every
+ * `Driver` method through this. Keeping this separate from `Driver` lets the
+ * driver implement coordinate normalisation, screenshot decoding, etc. once
+ * for all backends.
+ */
+export interface SandboxBackend {
+    readonly name: string;
+    /** Boot the underlying sandbox (start container / VM, install helper). */
+    start(): Promise<void>;
+    /** Tear down the sandbox. Must be idempotent. */
+    stop(): Promise<void>;
+    /**
+     * Send one command to the in-sandbox helper and get a typed response.
+     * Backends are responsible for transport (docker exec, virtio-serial, ...).
+     */
+    invoke<TResult>(op: SandboxOp): Promise<TResult>;
+}
+/** Tagged operation envelope sent to the sandbox helper. */
+export type SandboxOp = {
+    kind: "screenshot";
+    region?: ScreenRegion;
+} | {
+    kind: "mouse_move";
+    x: number;
+    y: number;
+} | {
+    kind: "mouse_click";
+    x: number;
+    y: number;
+} | {
+    kind: "mouse_double_click";
+    x: number;
+    y: number;
+} | {
+    kind: "mouse_right_click";
+    x: number;
+    y: number;
+} | {
+    kind: "mouse_drag";
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+} | {
+    kind: "mouse_scroll";
+    x: number;
+    y: number;
+    direction: ScrollDirection;
+    amount: number;
+} | {
+    kind: "keyboard_type";
+    text: string;
+} | {
+    kind: "keyboard_key_press";
+    key: string;
+} | {
+    kind: "keyboard_hotkey";
+    combo: string;
+} | {
+    kind: "list_windows";
+} | {
+    kind: "focus_window";
+    window_id: string;
+} | {
+    kind: "list_processes";
+} | {
+    kind: "run_command";
+    command: string;
+    cwd?: string;
+    timeout_seconds?: number;
+} | {
+    kind: "read_file";
+    path: string;
+} | {
+    kind: "write_file";
+    path: string;
+    content: string;
+};
+/**
+ * Thrown when a backend cannot be constructed (for example, missing docker
+ * binary). Callers should bubble this to the operator so the
+ * misconfiguration is loud, never silent.
+ */
+export declare class SandboxBackendUnavailableError extends Error {
+    readonly backend: string;
+    constructor(message: string, backend: string);
+}
+/** Thrown when the in-sandbox helper returns a structured error. */
+export declare class SandboxInvocationError extends Error {
+    readonly op: SandboxOp["kind"];
+    constructor(message: string, op: SandboxOp["kind"]);
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/sandbox/wsb-backend.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Windows Sandbox (WSB) provider backend (#9170 M13).
+ *
+ * Windows Sandbox is a disposable, hardware-isolated Windows VM shipped with
+ * Windows Pro/Enterprise. The host launches it from a `.wsb` config that maps a
+ * folder and runs a logon command (here: start the in-guest computer-server),
+ * then drives it over the generic remote-guest RPC (`{command,params}` →
+ * `{success,result}`) — see `remote-guest.ts`.
+ *
+ * Availability is gated: WSB only exists on Windows with the optional feature
+ * installed. When absent, construction throws `SandboxBackendUnavailableError`
+ * so the misconfiguration is loud, never a silent host fallback.
+ *
+ * The launcher + transport are injectable so the boot/teardown logic is
+ * unit-testable without a real Windows Sandbox.
+ */
+import { RemoteGuestBackend, type RemoteGuestTransport } from "./remote-guest.js";
+/** Host-side controller for the WSB VM lifecycle (injectable for tests). */
+export interface WsbLauncher {
+    /** Launch Windows Sandbox with the computer-server logon command. */
+    launch(args: {
+        rpcPort: number;
+    }): Promise<void>;
+    /** Stop the running sandbox (best-effort; WSB tears down on close). */
+    shutdown(): Promise<void>;
+}
+export interface WsbBackendOptions {
+    rpcUrl?: string;
+    rpcPort?: number;
+    transport?: RemoteGuestTransport;
+    launcher?: WsbLauncher;
+    /** Availability override (tests). */
+    available?: boolean;
+}
+/** Best-effort probe: WSB exists only on Windows with the feature installed. */
+export declare function isWindowsSandboxAvailable(): boolean;
+export declare class WSBBackend extends RemoteGuestBackend {
+    readonly name = "wsb";
+    private readonly rpcPort;
+    private readonly _transport;
+    private readonly launcher;
+    private started;
+    constructor(opts?: WsbBackendOptions);
+    protected transport(): RemoteGuestTransport;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=wsb-backend.d.ts.map

package/dist/sandbox/wsb-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wsb-backend.d.ts","sourceRoot":"","sources":["../../src/sandbox/wsb-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAEL,kBAAkB,EAClB,KAAK,oBAAoB,EAE1B,MAAM,mBAAmB,CAAC;AAG3B,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,MAAM,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,uEAAuE;IACvE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,qCAAqC;IACrC,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAKD,gFAAgF;AAChF,wBAAgB,yBAAyB,IAAI,OAAO,CAGnD;AAED,qBAAa,UAAW,SAAQ,kBAAkB;IAChD,QAAQ,CAAC,IAAI,SAAS;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,OAAO,CAAS;gBAEZ,IAAI,GAAE,iBAAsB;IAoBxC,SAAS,CAAC,SAAS,IAAI,oBAAoB;IAIrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAMtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAK5B"}

package/dist/scene/a11y-provider.d.ts

@@ -0,0 +1,83 @@
+/**
+ * AccessibilityProvider — thin abstraction over platform-specific a11y trees.
+ *
+ * The scene-builder needs structured a11y nodes (role, label, bbox, actions)
+ * tagged with a stable id so the planner can say "click element a47" across
+ * turns. The existing `platform/a11y.ts::extractA11yTree()` returns a single
+ * flat string — useful for prompts but not structured. This module wraps it
+ * with a typed-node interface and adds:
+ *
+ *   - Native impls per-OS that prefer structured JSON output where the
+ *     platform supports it (AT-SPI emits structured data we just need to
+ *     marshal; UIA/AX similarly).
+ *   - A Wayland-compositor fallback (`hyprctl clients -j`, `swaymsg -t
+ *     get_tree`) so Linux Wayland-only environments still surface windowable
+ *     nodes even when AT-SPI is locked down.
+ *   - A `NullAccessibilityProvider` for platforms / contexts where a11y is
+ *     intentionally disabled (CI, headless runners).
+ *
+ * Stable id strategy:
+ *   - Each provider emits `a<displayId>-<seq>` IDs. The same logical element
+ *     keeps the same id across consecutive frames AS LONG AS the provider's
+ *     in-memory map is preserved — we re-key when role + label + bbox
+ *     intersect significantly with a previous frame's node. This is the
+ *     contract WS7's "click element a47" depends on.
+ *
+ * The Android `AccessibilityService` impl is owned by WS8 and registers via
+ * `setAccessibilityProvider()` at runtime — this module exposes the seam
+ * but does not ship a JS-side implementation.
+ */
+import type { SceneAxNode } from "./scene-types.js";
+export interface AccessibilityProvider {
+    readonly name: string;
+    /**
+     * Whether this provider can produce structured nodes on the current host.
+     * Used by `resolveAccessibilityProvider` to pick the best chain entry.
+     */
+    available(): boolean;
+    /**
+     * Capture the live a11y tree and return per-display node lists. Returns
+     * an empty array when no nodes are reachable (vs throwing) so the
+     * scene-builder always produces a Scene.
+     */
+    snapshot(): Promise<SceneAxNode[]>;
+}
+declare class NullAccessibilityProvider implements AccessibilityProvider {
+    readonly name = "null";
+    available(): boolean;
+    snapshot(): Promise<SceneAxNode[]>;
+}
+/**
+ * Replace the active provider (used by Android/WS8 to inject the native
+ * `AccessibilityService` adapter, and by tests).
+ */
+export declare function setAccessibilityProvider(provider: AccessibilityProvider): void;
+export declare function resolveAccessibilityProvider(): AccessibilityProvider;
+interface IdAssignerState {
+    seq: Map<number, number>;
+}
+export declare function makeIdAssigner(): IdAssignerState;
+export declare function assignAxId(state: IdAssignerState, displayId: number): string;
+export declare class LinuxAccessibilityProvider implements AccessibilityProvider {
+    readonly name = "linux";
+    available(): boolean;
+    snapshot(): Promise<SceneAxNode[]>;
+    private tryAtspi;
+    private tryWaylandCompositor;
+    private tryHyprland;
+    private trySway;
+}
+export declare function parseHyprlandClients(text: string): SceneAxNode[];
+export declare function parseSwayTree(text: string): SceneAxNode[];
+export declare class DarwinAccessibilityProvider implements AccessibilityProvider {
+    readonly name = "darwin";
+    available(): boolean;
+    snapshot(): Promise<SceneAxNode[]>;
+}
+export declare class WindowsAccessibilityProvider implements AccessibilityProvider {
+    readonly name = "win32";
+    available(): boolean;
+    snapshot(): Promise<SceneAxNode[]>;
+}
+export { NullAccessibilityProvider };
+//# sourceMappingURL=a11y-provider.d.ts.map

package/dist/scene/a11y-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a11y-provider.d.ts","sourceRoot":"","sources":["../../src/scene/a11y-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,SAAS,IAAI,OAAO,CAAC;IACrB;;;;OAIG;IACH,QAAQ,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;CACpC;AAED,cAAM,yBAA0B,YAAW,qBAAqB;IAC9D,QAAQ,CAAC,IAAI,UAAU;IACvB,SAAS,IAAI,OAAO;IAGd,QAAQ,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;CAGzC;AAID;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,qBAAqB,GAC9B,IAAI,CAEN;AAED,wBAAgB,4BAA4B,IAAI,qBAAqB,CAOpE;AAED,UAAU,eAAe;IACvB,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1B;AAED,wBAAgB,cAAc,IAAI,eAAe,CAEhD;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAK5E;AAID,qBAAa,0BAA2B,YAAW,qBAAqB;IACtE,QAAQ,CAAC,IAAI,WAAW;IAExB,SAAS,IAAI,OAAO;IAUd,QAAQ,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IASxC,OAAO,CAAC,QAAQ;IA0DhB,OAAO,CAAC,oBAAoB;IAa5B,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,OAAO;CAYhB;AAaD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAiChE;AAcD,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CA4CzD;AAuBD,qBAAa,2BAA4B,YAAW,qBAAqB;IACvE,QAAQ,CAAC,IAAI,YAAY;IAEzB,SAAS,IAAI,OAAO;IAId,QAAQ,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;CAuDzC;AAID,qBAAa,4BAA6B,YAAW,qBAAqB;IACxE,QAAQ,CAAC,IAAI,WAAW;IAExB,SAAS,IAAI,OAAO;IAId,QAAQ,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;CAqDzC;AAED,OAAO,EAAE,yBAAyB,EAAE,CAAC"}