@zenalexa/unicli 0.210.0 → 0.212.1

package/dist/transport/adapters/cdp-browser.js

@@ -0,0 +1,240 @@
+/**
+ * CdpBrowserTransport — wraps the existing `BrowserPage` (an IPage impl)
+ * behind the TransportAdapter interface.
+ *
+ * The underlying `src/browser/page.ts` continues to serve the legacy
+ * yaml-runner paths; this wrapper exposes the same methods through the
+ * uniform envelope contract so the new bus-driven dispatch routes
+ * browser steps without duplicating the CDP client logic.
+ *
+ * Page acquisition is pluggable via the constructor `pageFactory` for
+ * testability. The default factory mirrors the yaml-runner strategy:
+ * try an already-running browser on CDP port, else auto-launch.
+ */
+import { err, exitCodeFor, ok } from "../../core/envelope.js";
+const CDP_STEPS = [
+    "navigate",
+    "evaluate",
+    "click",
+    "type",
+    "press",
+    "scroll",
+    "wait",
+    "snapshot",
+    "screenshot",
+];
+const CDP_CAPABILITY = {
+    steps: CDP_STEPS,
+    snapshotFormats: ["dom-ax", "screenshot"],
+    mutatesHost: true,
+};
+/** Default factory — connect or auto-launch Chrome via the existing launcher. */
+async function defaultPageFactory() {
+    const port = Number(process.env.CHROME_DEBUG_PORT ?? 9222);
+    const { BrowserPage } = await import("../../browser/page.js");
+    try {
+        const page = await BrowserPage.connect(port);
+        return page;
+    }
+    catch {
+        const { launchChrome } = await import("../../browser/launcher.js");
+        await launchChrome(port);
+        // Poll (5 attempts) — mirrors yaml-runner behavior.
+        let lastErr;
+        for (let attempt = 0; attempt < 5; attempt++) {
+            try {
+                return await BrowserPage.connect(port);
+            }
+            catch (e) {
+                lastErr = e;
+                await new Promise((r) => setTimeout(r, 500));
+            }
+        }
+        throw lastErr instanceof Error
+            ? lastErr
+            : new Error("failed to connect to Chrome");
+    }
+}
+/**
+ * CdpBrowserTransport wraps IPage to expose CDP browser primitives via
+ * the uniform TransportAdapter contract.
+ */
+export class CdpBrowserTransport {
+    kind = "cdp-browser";
+    capability = CDP_CAPABILITY;
+    pageFactory;
+    page;
+    closed = false;
+    constructor(opts = {}) {
+        this.pageFactory = opts.pageFactory ?? defaultPageFactory;
+    }
+    async open(_ctx) {
+        this.closed = false;
+        if (!this.page) {
+            this.page = await this.pageFactory();
+        }
+    }
+    async snapshot(opts) {
+        if (!this.page) {
+            return { format: "text", data: "" };
+        }
+        const format = opts?.format ?? "dom-ax";
+        if (format === "screenshot") {
+            const buf = await this.page.screenshot();
+            return { format: "screenshot", data: buf };
+        }
+        const dom = await this.page.snapshot();
+        return { format: "dom-ax", data: dom };
+    }
+    async action(req) {
+        const start = Date.now();
+        const page = this.page;
+        if (!page) {
+            return err({
+                transport: "cdp-browser",
+                step: 0,
+                action: req.kind,
+                reason: "transport not opened — call open() before action()",
+                suggestion: "invoke `transport.open(ctx)` before dispatching actions",
+                retryable: false,
+                exit_code: exitCodeFor("usage_error"),
+            });
+        }
+        try {
+            const envelope = await this.dispatch(page, req);
+            envelope.elapsedMs = Date.now() - start;
+            return envelope;
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return err({
+                transport: "cdp-browser",
+                step: 0,
+                action: req.kind,
+                reason: msg,
+                suggestion: "verify Chrome is reachable via CDP and the selector is valid",
+                retryable: /timeout|disconnected|ws /i.test(msg),
+                exit_code: exitCodeFor("generic_error"),
+            });
+        }
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.page) {
+            const p = this.page;
+            this.page = undefined;
+            try {
+                await p.close();
+            }
+            catch {
+                // Best-effort — close must be idempotent and non-throwing.
+            }
+        }
+    }
+    // ── dispatch ─────────────────────────────────────────────────────
+    async dispatch(page, req) {
+        const p = req.params;
+        switch (req.kind) {
+            case "navigate": {
+                const url = typeof p.url === "string" ? p.url : undefined;
+                if (!url)
+                    return missingParam("cdp-browser", "navigate", "url");
+                const settleMs = typeof p.settleMs === "number" ? p.settleMs : undefined;
+                const waitUntil = typeof p.waitUntil === "string" ? p.waitUntil : undefined;
+                await page.goto(url, {
+                    ...(settleMs !== undefined ? { settleMs } : {}),
+                    ...(waitUntil ? { waitUntil } : {}),
+                });
+                return ok(undefined);
+            }
+            case "evaluate": {
+                const script = typeof p.script === "string" ? p.script : undefined;
+                if (!script)
+                    return missingParam("cdp-browser", "evaluate", "script");
+                const data = await page.evaluate(script);
+                return ok(data);
+            }
+            case "click": {
+                const selector = typeof p.selector === "string" ? p.selector : undefined;
+                if (!selector)
+                    return missingParam("cdp-browser", "click", "selector");
+                await page.click(selector);
+                return ok(undefined);
+            }
+            case "type": {
+                const selector = typeof p.selector === "string" ? p.selector : undefined;
+                const text = typeof p.text === "string" ? p.text : undefined;
+                if (!selector)
+                    return missingParam("cdp-browser", "type", "selector");
+                if (text === undefined)
+                    return missingParam("cdp-browser", "type", "text");
+                await page.type(selector, text);
+                return ok(undefined);
+            }
+            case "press": {
+                const key = typeof p.key === "string" ? p.key : undefined;
+                if (!key)
+                    return missingParam("cdp-browser", "press", "key");
+                const modifiers = Array.isArray(p.modifiers)
+                    ? p.modifiers
+                    : undefined;
+                await page.press(key, modifiers);
+                return ok(undefined);
+            }
+            case "scroll": {
+                const direction = typeof p.direction === "string" ? p.direction : "down";
+                await page.scroll(direction);
+                return ok(undefined);
+            }
+            case "wait": {
+                if (typeof p.seconds === "number") {
+                    await page.wait(p.seconds);
+                }
+                else if (typeof p.selector === "string") {
+                    const timeout = typeof p.timeout === "number" ? p.timeout : undefined;
+                    await page.waitForSelector(p.selector, timeout);
+                }
+                else if (typeof p.condition === "string") {
+                    const timeout = typeof p.timeout === "number" ? p.timeout : undefined;
+                    await page.waitFor(p.condition, timeout);
+                }
+                else {
+                    return missingParam("cdp-browser", "wait", "seconds | selector | condition");
+                }
+                return ok(undefined);
+            }
+            case "snapshot": {
+                const dom = await page.snapshot();
+                return ok(dom);
+            }
+            case "screenshot": {
+                const buf = await page.screenshot();
+                return ok(buf);
+            }
+            default:
+                return err({
+                    transport: "cdp-browser",
+                    step: 0,
+                    action: req.kind,
+                    reason: `unsupported action "${req.kind}" for cdp-browser transport`,
+                    suggestion: `cdp-browser transport supports: ${CDP_STEPS.join(", ")}`,
+                    minimum_capability: `cdp-browser.${req.kind}`,
+                    exit_code: exitCodeFor("usage_error"),
+                });
+        }
+    }
+}
+function missingParam(transport, action, param) {
+    return err({
+        transport,
+        step: 0,
+        action,
+        reason: `missing required param \`${param}\``,
+        suggestion: `pass params.${param} to the ${action} action`,
+        retryable: false,
+        exit_code: exitCodeFor("usage_error"),
+    });
+}
+//# sourceMappingURL=cdp-browser.js.map

package/dist/transport/adapters/cdp-browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp-browser.js","sourceRoot":"","sources":["../../../src/transport/adapters/cdp-browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,wBAAwB,CAAC;AAc9D,MAAM,SAAS,GAAG;IAChB,UAAU;IACV,UAAU;IACV,OAAO;IACP,MAAM;IACN,OAAO;IACP,QAAQ;IACR,MAAM;IACN,UAAU;IACV,YAAY;CACJ,CAAC;AAEX,MAAM,cAAc,GAAe;IACjC,KAAK,EAAE,SAAS;IAChB,eAAe,EAAE,CAAC,QAAQ,EAAE,YAAY,CAA8B;IACtE,WAAW,EAAE,IAAI;CAClB,CAAC;AAWF,iFAAiF;AACjF,KAAK,UAAU,kBAAkB;IAC/B,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,IAAI,CAAC,CAAC;IAC3D,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,uBAAuB,CAAC,CAAC;IAC9D,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7C,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,2BAA2B,CAAC,CAAC;QACnE,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC;QACzB,oDAAoD;QACpD,IAAI,OAAgB,CAAC;QACrB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC;YAC7C,IAAI,CAAC;gBACH,OAAO,MAAM,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACzC,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,OAAO,GAAG,CAAC,CAAC;gBACZ,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC;QACD,MAAM,OAAO,YAAY,KAAK;YAC5B,CAAC,CAAC,OAAO;YACT,CAAC,CAAC,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IAC/C,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,mBAAmB;IACrB,IAAI,GAAkB,aAAa,CAAC;IACpC,UAAU,GAAe,cAAc,CAAC;IAEhC,WAAW,CAAuB;IAC3C,IAAI,CAAoB;IACxB,MAAM,GAAG,KAAK,CAAC;IAEvB,YAAY,OAAmC,EAAE;QAC/C,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,kBAAkB,CAAC;IAC5D,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAsB;QAC/B,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACf,IAAI,CAAC,IAAI,GAAG,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;QACvC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,IAGd;QACC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACf,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QACtC,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,EAAE,MAAM,IAAI,QAAQ,CAAC;QACxC,IAAI,MAAM,KAAK,YAAY,EAAE,CAAC;YAC5B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACzC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;QAC7C,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACvC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,MAAM,CAAc,GAAkB;QAC1C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,GAAG,CAAC;gBACT,SAAS,EAAE,aAAa;gBACxB,IAAI,EAAE,CAAC;gBACP,MAAM,EAAE,GAAG,CAAC,IAAI;gBAChB,MAAM,EAAE,oDAAoD;gBAC5D,UAAU,EAAE,yDAAyD;gBACrE,SAAS,EAAE,KAAK;gBAChB,SAAS,EAAE,WAAW,CAAC,aAAa,CAAC;aACtC,CAAC,CAAC;QACL,CAAC;QACD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAI,IAAI,EAAE,GAAG,CAAC,CAAC;YACnD,QAAQ,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;YACxC,OAAO,QAAQ,CAAC;QAClB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,GAAG,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACvD,OAAO,GAAG,CAAC;gBACT,SAAS,EAAE,aAAa;gBACxB,IAAI,EAAE,CAAC;gBACP,MAAM,EAAE,GAAG,CAAC,IAAI;gBAChB,MAAM,EAAE,GAAG;gBACX,UAAU,EACR,8DAA8D;gBAChE,SAAS,EAAE,2BAA2B,CAAC,IAAI,CAAC,GAAG,CAAC;gBAChD,SAAS,EAAE,WAAW,CAAC,eAAe,CAAC;aACxC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC;YACpB,IAAI,CAAC,IAAI,GAAG,SAAS,CAAC;YACtB,IAAI,CAAC;gBACH,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC;YAClB,CAAC;YAAC,MAAM,CAAC;gBACP,2DAA2D;YAC7D,CAAC;QACH,CAAC;IACH,CAAC;IAED,oEAAoE;IAE5D,KAAK,CAAC,QAAQ,CACpB,IAAW,EACX,GAAkB;QAElB,MAAM,CAAC,GAAG,GAAG,CAAC,MAAiC,CAAC;QAChD,QAAQ,GAAG,CAAC,IAAI,EAAE,CAAC;YACjB,KAAK,UAAU,CAAC,CAAC,CAAC;gBAChB,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;gBAC1D,IAAI,CAAC,GAAG;oBAAE,OAAO,YAAY,CAAC,aAAa,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;gBAChE,MAAM,QAAQ,GACZ,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;gBAC1D,MAAM,SAAS,GACb,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;gBAC5D,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE;oBACnB,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC/C,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACpC,CAAC,CAAC;gBACH,OAAO,EAAE,CAAC,SAAc,CAAC,CAAC;YAC5B,CAAC;YACD,KAAK,UAAU,CAAC,CAAC,CAAC;gBAChB,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;gBACnE,IAAI,CAAC,MAAM;oBAAE,OAAO,YAAY,CAAC,aAAa,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC;gBACtE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;gBACzC,OAAO,EAAE,CAAC,IAAS,CAAC,CAAC;YACvB,CAAC;YACD,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,MAAM,QAAQ,GACZ,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;gBAC1D,IAAI,CAAC,QAAQ;oBAAE,OAAO,YAAY,CAAC,aAAa,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;gBACvE,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;gBAC3B,OAAO,EAAE,CAAC,SAAc,CAAC,CAAC;YAC5B,CAAC;YACD,KAAK,MAAM,CAAC,CAAC,CAAC;gBACZ,MAAM,QAAQ,GACZ,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;gBAC1D,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;gBAC7D,IAAI,CAAC,QAAQ;oBAAE,OAAO,YAAY,CAAC,aAAa,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;gBACtE,IAAI,IAAI,KAAK,SAAS;oBACpB,OAAO,YAAY,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;gBACrD,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;gBAChC,OAAO,EAAE,CAAC,SAAc,CAAC,CAAC;YAC5B,CAAC;YACD,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;gBAC1D,IAAI,CAAC,GAAG;oBAAE,OAAO,YAAY,CAAC,aAAa,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;gBAC7D,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;oBAC1C,CAAC,CAAE,CAAC,CAAC,SAAsB;oBAC3B,CAAC,CAAC,SAAS,CAAC;gBACd,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;gBACjC,OAAO,EAAE,CAAC,SAAc,CAAC,CAAC;YAC5B,CAAC;YACD,KAAK,QAAQ,CAAC,CAAC,CAAC;gBACd,MAAM,SAAS,GACb,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;gBACzD,MAAM,IAAI,CAAC,MAAM,CAAC,SAA6C,CAAC,CAAC;gBACjE,OAAO,EAAE,CAAC,SAAc,CAAC,CAAC;YAC5B,CAAC;YACD,KAAK,MAAM,CAAC,CAAC,CAAC;gBACZ,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;oBAClC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;gBAC7B,CAAC;qBAAM,IAAI,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;oBAC1C,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;oBACtE,MAAM,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;gBAClD,CAAC;qBAAM,IAAI,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;oBAC3C,MAAM,OAAO,GAAG,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;oBACtE,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;gBAC3C,CAAC;qBAAM,CAAC;oBACN,OAAO,YAAY,CACjB,aAAa,EACb,MAAM,EACN,gCAAgC,CACjC,CAAC;gBACJ,CAAC;gBACD,OAAO,EAAE,CAAC,SAAc,CAAC,CAAC;YAC5B,CAAC;YACD,KAAK,UAAU,CAAC,CAAC,CAAC;gBAChB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAClC,OAAO,EAAE,CAAC,GAAQ,CAAC,CAAC;YACtB,CAAC;YACD,KAAK,YAAY,CAAC,CAAC,CAAC;gBAClB,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;gBACpC,OAAO,EAAE,CAAC,GAAQ,CAAC,CAAC;YACtB,CAAC;YACD;gBACE,OAAO,GAAG,CAAC;oBACT,SAAS,EAAE,aAAa;oBACxB,IAAI,EAAE,CAAC;oBACP,MAAM,EAAE,GAAG,CAAC,IAAI;oBAChB,MAAM,EAAE,uBAAuB,GAAG,CAAC,IAAI,6BAA6B;oBACpE,UAAU,EAAE,mCAAmC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;oBACrE,kBAAkB,EAAE,eAAe,GAAG,CAAC,IAAI,EAAE;oBAC7C,SAAS,EAAE,WAAW,CAAC,aAAa,CAAC;iBACtC,CAAC,CAAC;QACP,CAAC;IACH,CAAC;CACF;AAED,SAAS,YAAY,CACnB,SAAwB,EACxB,MAAc,EACd,KAAa;IAEb,OAAO,GAAG,CAAC;QACT,SAAS;QACT,IAAI,EAAE,CAAC;QACP,MAAM;QACN,MAAM,EAAE,4BAA4B,KAAK,IAAI;QAC7C,UAAU,EAAE,eAAe,KAAK,WAAW,MAAM,SAAS;QAC1D,SAAS,EAAE,KAAK;QAChB,SAAS,EAAE,WAAW,CAAC,aAAa,CAAC;KACtC,CAAC,CAAC;AACL,CAAC"}

package/dist/transport/adapters/cua.d.ts

@@ -0,0 +1,240 @@
+/**
+ * CuaTransport — screenshot + VLM "Computer Use" transport.
+ *
+ * Unlike the other transports, CUA has no single protocol — it wraps a
+ * pluggable "backend" that implements the primitive perception/action
+ * verbs against a real computer-use model or emulator. v0.212 ships four
+ * backends selected by `CUA_BACKEND`:
+ *
+ *   - `anthropic`   Anthropic `computer_20251124` beta tool, `ANTHROPIC_API_KEY`
+ *   - `trycua`      trycua/cua compute-server v0.1.9+, `TRYCUA_API_KEY`
+ *   - `opencua`     OpenCUA-72B via local vLLM, `OPENCUA_ENDPOINT`
+ *   - `scrapybara`  Scrapybara Computer API, `SCRAPYBARA_API_KEY`
+ *   - `mock`        in-memory stub used by tests and when no key is present
+ *
+ * The real network paths to each provider are stubbed in v0.212 — they are
+ * gated behind the corresponding env keys and throw a structured
+ * `config_error` envelope if selected without credentials. The MockBackend
+ * is always available so the offline test suite runs without secrets.
+ *
+ * Design contract:
+ *  - `action()` NEVER throws
+ *  - all backends implement the same primitive verb surface (below)
+ *  - selection is deterministic: `selectCuaBackend()` returns the same
+ *    backend for the same env — no hidden state
+ */
+import type { ActionRequest, ActionResult, Capability, Snapshot, SnapshotFormat, TransportAdapter, TransportContext, TransportKind } from "../types.js";
+/**
+ * Primitive verbs every CUA backend must implement. The transport never
+ * calls a backend method directly without wrapping the outcome in an
+ * envelope — all error paths flow through `CuaTransport.action()`.
+ */
+export interface CuaBackend {
+    readonly name: CuaBackendName;
+    snapshot(): Promise<{
+        base64: string;
+        width: number;
+        height: number;
+        mime?: string;
+    }>;
+    click(x: number, y: number, button?: "left" | "right"): Promise<void>;
+    type(text: string): Promise<void>;
+    key(key: string): Promise<void>;
+    scroll(dx: number, dy: number): Promise<void>;
+    drag(fromX: number, fromY: number, toX: number, toY: number): Promise<void>;
+    wait(ms: number): Promise<void>;
+    /**
+     * Optional: VLM "ask" primitive — let the model decide a boolean or
+     * short-string answer about the current screen. Backends that don't
+     * support it throw; `CuaTransport.action()` catches and envelopes.
+     */
+    ask?(question: string): Promise<string>;
+    /**
+     * Optional: launch a named application on the host (some backends ship
+     * their own sandbox and need an explicit launch command).
+     */
+    launch?(app: string): Promise<void>;
+}
+/** The four production backends + the offline test fallback. */
+export type CuaBackendName = "anthropic" | "trycua" | "opencua" | "scrapybara" | "mock";
+/**
+ * MockBackend — deterministic, offline CUA backend used when no provider
+ * credentials are present and by every test in this file. Records the
+ * sequence of calls on `history` so tests can assert against it without
+ * having to stub `fetch`.
+ */
+export declare class MockBackend implements CuaBackend {
+    readonly name: CuaBackendName;
+    readonly history: Array<{
+        verb: string;
+        args: unknown[];
+    }>;
+    private record;
+    snapshot(): Promise<{
+        base64: string;
+        width: number;
+        height: number;
+        mime: string;
+    }>;
+    click(x: number, y: number, button?: "left" | "right"): Promise<void>;
+    type(text: string): Promise<void>;
+    key(key: string): Promise<void>;
+    scroll(dx: number, dy: number): Promise<void>;
+    drag(fromX: number, fromY: number, toX: number, toY: number): Promise<void>;
+    wait(ms: number): Promise<void>;
+    ask(question: string): Promise<string>;
+    launch(app: string): Promise<void>;
+}
+/**
+ * Anthropic `computer_use` tool stub. Selected when `CUA_BACKEND=anthropic`
+ * and `ANTHROPIC_API_KEY` is set.
+ *
+ * IMPORTANT — two-layer architecture: the Anthropic Messages API is a
+ * planner, not a screen capture service. A production Anthropic backend
+ * MUST be composed with a screenshot source (macOS `screencapture`,
+ * trycua sandbox, scrapybara VM) because the model receives screenshots
+ * from the client and returns `tool_use` actions. v0.212 ships this as
+ * a stub; the composition layer lands in v0.213 via a new
+ * `AnthropicPlanner(screenshotSource)` constructor — see
+ * `docs/ROADMAP.md` > v0.213 "Gagarin".
+ *
+ * `tool_version` defaults to `"computer_20260301"` (the successor to
+ * `computer_20251124` in the Sonnet 4.6 rollout); override via env
+ * `ANTHROPIC_CUA_TOOL_VERSION` so operators can follow Anthropic's
+ * release cadence without a code change.
+ */
+export declare class AnthropicBackend implements CuaBackend {
+    readonly name: CuaBackendName;
+    readonly apiKey: string;
+    readonly model: string;
+    readonly toolVersion: string;
+    constructor(apiKey: string, model?: string, toolVersion?: string);
+    snapshot(): Promise<{
+        base64: string;
+        width: number;
+        height: number;
+        mime: string;
+    }>;
+    click(): Promise<void>;
+    type(): Promise<void>;
+    key(): Promise<void>;
+    scroll(): Promise<void>;
+    drag(): Promise<void>;
+    wait(ms: number): Promise<void>;
+    ask(): Promise<string>;
+}
+/** trycua/cua compute-server v0.1.9+. Activated when `CUA_BACKEND=trycua`. */
+export declare class TrycuaBackend implements CuaBackend {
+    readonly name: CuaBackendName;
+    readonly apiKey: string;
+    readonly endpoint: string;
+    constructor(apiKey: string, endpoint?: string);
+    snapshot(): Promise<{
+        base64: string;
+        width: number;
+        height: number;
+    }>;
+    click(): Promise<void>;
+    type(): Promise<void>;
+    key(): Promise<void>;
+    scroll(): Promise<void>;
+    drag(): Promise<void>;
+    wait(ms: number): Promise<void>;
+}
+/** OpenCUA-72B via local vLLM. Activated when `CUA_BACKEND=opencua`. */
+export declare class OpenCuaBackend implements CuaBackend {
+    private readonly endpoint;
+    readonly name: CuaBackendName;
+    constructor(endpoint: string);
+    snapshot(): Promise<{
+        base64: string;
+        width: number;
+        height: number;
+    }>;
+    click(): Promise<void>;
+    type(): Promise<void>;
+    key(): Promise<void>;
+    scroll(): Promise<void>;
+    drag(): Promise<void>;
+    wait(ms: number): Promise<void>;
+}
+/** Scrapybara Computer API. Activated when `CUA_BACKEND=scrapybara`. */
+export declare class ScrapybaraBackend implements CuaBackend {
+    readonly name: CuaBackendName;
+    readonly apiKey: string;
+    readonly endpoint: string;
+    constructor(apiKey: string, endpoint?: string);
+    snapshot(): Promise<{
+        base64: string;
+        width: number;
+        height: number;
+    }>;
+    click(): Promise<void>;
+    type(): Promise<void>;
+    key(): Promise<void>;
+    scroll(): Promise<void>;
+    drag(): Promise<void>;
+    wait(ms: number): Promise<void>;
+}
+/** Explicit env snapshot used by {@link selectCuaBackend} — injectable for tests. */
+export interface CuaEnv {
+    CUA_BACKEND?: string;
+    ANTHROPIC_API_KEY?: string;
+    TRYCUA_API_KEY?: string;
+    OPENCUA_ENDPOINT?: string;
+    SCRAPYBARA_API_KEY?: string;
+}
+/**
+ * Pure function — given an env snapshot, return the backend to use.
+ *
+ * Selection rules (first match wins):
+ *   1. `CUA_BACKEND=anthropic`  and ANTHROPIC_API_KEY  → AnthropicBackend
+ *   2. `CUA_BACKEND=trycua`     and TRYCUA_API_KEY     → TrycuaBackend
+ *   3. `CUA_BACKEND=opencua`    and OPENCUA_ENDPOINT   → OpenCuaBackend
+ *   4. `CUA_BACKEND=scrapybara` and SCRAPYBARA_API_KEY → ScrapybaraBackend
+ *   5. otherwise                                       → MockBackend
+ *
+ * If the user names a backend but the required env is missing, we return a
+ * MockBackend tagged with a `missing` sentinel so the caller can emit a
+ * structured `config_error` envelope on first use.
+ */
+export declare function selectCuaBackend(env?: CuaEnv): CuaBackend;
+export interface CuaTransportOptions {
+    backend?: CuaBackend;
+    env?: CuaEnv;
+}
+/**
+ * CuaTransport routes `cua_*` pipeline steps to the active backend, wraps
+ * every outcome in an envelope, and never throws from `action()`.
+ */
+export declare class CuaTransport implements TransportAdapter {
+    readonly kind: TransportKind;
+    readonly capability: Capability;
+    private backend;
+    private lastSnapshot;
+    constructor(opts?: CuaTransportOptions);
+    /** Introspect the active backend (used by tests + `cua_backend` step). */
+    get activeBackendName(): CuaBackendName;
+    /** Swap backends at runtime — the `cua_backend` step uses this. */
+    setBackend(backend: CuaBackend): void;
+    open(_ctx: TransportContext): Promise<void>;
+    snapshot(opts?: {
+        format?: SnapshotFormat;
+    }): Promise<Snapshot>;
+    action<T = unknown>(req: ActionRequest): Promise<ActionResult<T>>;
+    close(): Promise<void>;
+    private dispatch;
+    private envelopeFromBackendError;
+    private doSnapshot;
+    private doClick;
+    private doType;
+    private doKey;
+    private doScroll;
+    private doDrag;
+    private doWait;
+    private doAssert;
+    private doAsk;
+    private doBackendInfo;
+    private doLaunch;
+}
+//# sourceMappingURL=cua.d.ts.map

package/dist/transport/adapters/cua.d.ts.map

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