@hoilab/ada-cli 0.84.21 → 0.85.0

package/dist/core/computer/driver.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Instalación, estado y permisos del motor de control del ordenador.
+ *
+ * El motor es nuestro fork de pi-computer-use, que vive en `motor/`. Este
+ * fichero es lo que usan el comando `ada-cli computer`, la ruta de API del
+ * escritorio y el panel de Ajustes — las tres superficies comparten esto para
+ * que el control del ordenador no sea una función solo del escritorio.
+ *
+ * Antes esto hablaba por CLI con `open-computer-use`. Aquel motor tenía seis
+ * acciones y le faltaban las dos que importan: esperar y buscar. El detalle del
+ * cambio está en `vendor/computer-use/PROCEDENCIA.md`.
+ */
+/** Versión del fork. Sube cuando traigamos cambios de aguas arriba. */
+export declare const VERSION_MOTOR = "0.5.0-ada.1";
+/**
+ * Los dos permisos de macOS, por separado.
+ *
+ * Van separados porque son DOS paneles distintos de Ajustes del Sistema y hay
+ * que conceder los dos. Un único botón "conceder permisos" solo puede abrir uno
+ * de ellos, y deja al usuario creyendo que ya está.
+ */
+export type PermisoMac = "accesibilidad" | "pantalla";
+export interface EstadoMotor {
+    instalado: boolean;
+    version?: string;
+    /**
+     * `true` solo donde el sistema exige permisos explícitos — hoy, macOS.
+     *
+     * En Linux y Windows el motor funciona sin conceder nada. Sin esta
+     * distinción, la ausencia de las líneas de permisos se leería como
+     * "denegado" y la interfaz avisaría de un problema inventado en dos de las
+     * tres plataformas.
+     */
+    permisosRelevantes: boolean;
+    accesibilidad?: boolean;
+    grabacionPantalla?: boolean;
+    /**
+     * macOS dice que la Grabación de pantalla está concedida, pero al intentar
+     * capturar de verdad falla.
+     *
+     * Significa casi siempre que el permiso pertenece a OTRA identidad de
+     * aplicación — el caso típico al cambiar el identificador de paquete, o al
+     * venir de una versión anterior firmada distinto. Sin distinguirlo, la
+     * interfaz enseñaría "falta permiso" mientras el usuario ve el interruptor
+     * encendido en Ajustes, y no hay forma de salir de ahí.
+     */
+    pantallaDeOtraApp?: boolean;
+    /**
+     * No se pudo PREGUNTAR por los permisos (el demonio no contestó).
+     *
+     * Es distinto de "denegados", y confundirlos se ve en pantalla: sin esto, un
+     * timeout del demonio hacía que el panel dijera "macOS sigue negando
+     * permisos" y ofreciera los dos pasos para concederlos. El usuario iba a
+     * Ajustes del Sistema, veía los interruptores YA encendidos, y se quedaba sin
+     * saber qué hacer. El remedio de verdad es reintentar o reiniciar el motor.
+     */
+    consultaFallida?: boolean;
+    /**
+     * Qué panel de Ajustes se acaba de abrir, si se abrió alguno.
+     *
+     * Lo pone solo `pedirPermisos`. Sirve para dos cosas: que la interfaz pueda
+     * decir a cuál ha mandado al usuario, y que se pueda COMPROBAR que no se
+     * abre ninguno cuando no toca. Sin este campo, "no abrir el panel" y
+     * "abrirlo y que falle" se ven exactamente igual desde fuera — y una prueba
+     * que no distingue esos dos casos no prueba nada.
+     */
+    panelAbierto?: PermisoMac;
+    detalle?: string;
+}
+/**
+ * ¿Está el motor listo?
+ *
+ * Se comprueban el helper y los permisos por separado porque fallan por
+ * separado: el helper puede estar instalado y macOS seguir negando la
+ * Accesibilidad. Decir solo "no funciona" dejaría al usuario sin saber qué
+ * arreglar, y en macOS lo que falla casi siempre son los permisos.
+ */
+export declare function estadoDelMotor(opciones?: OpcionesEstado): Promise<EstadoMotor>;
+export interface OpcionesEstado {
+    plataforma?: string;
+    /**
+     * Dónde buscar el helper. Solo lo cambian las pruebas: la rama "no está
+     * instalado" decide qué botón enseña Ajustes, y en una máquina donde SÍ está
+     * instalado no habría forma de recorrerla.
+     */
+    rutaHelper?: string;
+}
+export interface ResultadoInstalacion {
+    ok: boolean;
+    salida: string;
+}
+/**
+ * Instala el helper nativo.
+ *
+ * En macOS lo instala como aplicación FIRMADA en `~/Applications`, porque los
+ * permisos de Accesibilidad se conceden a una aplicación, no a un binario
+ * suelto. La firma es local (ad-hoc): vale para uso propio, pero distribuir
+ * Ada a terceros pediría un certificado de Apple.
+ */
+export declare function instalarMotor(opciones?: {
+    timeoutMs?: number;
+}): Promise<ResultadoInstalacion>;
+/**
+ * Pide los permisos del sistema.
+ *
+ * Abre el panel de Accesibilidad de macOS y relee el estado DESPUÉS: el usuario
+ * tarda en conceder, y dar por buenos unos permisos sin comprobarlos sería
+ * enseñar un punto verde falso.
+ *
+ * Ojo con una consecuencia del fork: al cambiar el identificador de paquete a
+ * `com.hoilab.ada-computer-use`, macOS lo trata como una aplicación NUEVA y
+ * pedirá permisos aunque el original los tuviera. Es lo correcto — es otra
+ * aplicación — pero conviene decírselo al usuario en vez de que parezca un
+ * fallo.
+ */
+export declare function pedirPermisos(opciones?: OpcionesEstado & {
+    permiso?: PermisoMac;
+}): Promise<EstadoMotor>;
+/**
+ * Reléelo todo después de que el usuario haya concedido algo.
+ *
+ * Reinicia el helper ANTES de mirar, y esa es toda la gracia: macOS cachea los
+ * permisos POR PROCESO. Un helper que arrancó sin Accesibilidad sigue creyendo
+ * que no la tiene aunque acabes de concederla. Sin este reinicio, el usuario
+ * concede, pulsa "volver a comprobar", sigue en rojo, y concluye que está roto
+ * — cuando lo único que pasa es que nadie se lo ha preguntado de nuevo al
+ * sistema.
+ */
+export declare function recomprobarPermisos(opciones?: OpcionesEstado): Promise<EstadoMotor>;
+//# sourceMappingURL=driver.d.ts.map

package/dist/core/computer/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../../src/core/computer/driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAQH,wEAAuE;AACvE,eAAO,MAAM,aAAa,gBAAgB,CAAC;AAI3C;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,eAAe,GAAG,UAAU,CAAC;AAQtD,MAAM,WAAW,WAAW;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,kBAAkB,EAAE,OAAO,CAAC;IAC5B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;;;;OASG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAmDD;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,QAAQ,GAAE,cAAmB,GAAG,OAAO,CAAC,WAAW,CAAC,CAiDxF;AAED,MAAM,WAAW,cAAc;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACpC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,QAAQ,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAOxG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CAAC,QAAQ,GAAE,cAAc,GAAG;IAAE,OAAO,CAAC,EAAE,UAAU,CAAA;CAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CAqClH;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,GAAE,cAAmB,GAAG,OAAO,CAAC,WAAW,CAAC,CAS7F","sourcesContent":["/**\n * Instalación, estado y permisos del motor de control del ordenador.\n *\n * El motor es nuestro fork de pi-computer-use, que vive en `motor/`. Este\n * fichero es lo que usan el comando `ada-cli computer`, la ruta de API del\n * escritorio y el panel de Ajustes — las tres superficies comparten esto para\n * que el control del ordenador no sea una función solo del escritorio.\n *\n * Antes esto hablaba por CLI con `open-computer-use`. Aquel motor tenía seis\n * acciones y le faltaban las dos que importan: esperar y buscar. El detalle del\n * cambio está en `vendor/computer-use/PROCEDENCIA.md`.\n */\n\nimport { spawn } from \"node:child_process\";\nimport { existsSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { HELPER_APP_PATH, macosHelper } from \"./motor/platform/macos/helper.ts\";\n\n/** Versión del fork. Sube cuando traigamos cambios de aguas arriba. */\nexport const VERSION_MOTOR = \"0.5.0-ada.1\";\n\nconst MAX_SALIDA = 4 * 1024 * 1024;\n\n/**\n * Los dos permisos de macOS, por separado.\n *\n * Van separados porque son DOS paneles distintos de Ajustes del Sistema y hay\n * que conceder los dos. Un único botón \"conceder permisos\" solo puede abrir uno\n * de ellos, y deja al usuario creyendo que ya está.\n */\nexport type PermisoMac = \"accesibilidad\" | \"pantalla\";\n\n/** El nombre que entiende el helper para cada panel. */\nconst PANEL: Record<PermisoMac, string> = {\n\taccesibilidad: \"accessibility\",\n\tpantalla: \"screenRecording\",\n};\n\nexport interface EstadoMotor {\n\tinstalado: boolean;\n\tversion?: string;\n\t/**\n\t * `true` solo donde el sistema exige permisos explícitos — hoy, macOS.\n\t *\n\t * En Linux y Windows el motor funciona sin conceder nada. Sin esta\n\t * distinción, la ausencia de las líneas de permisos se leería como\n\t * \"denegado\" y la interfaz avisaría de un problema inventado en dos de las\n\t * tres plataformas.\n\t */\n\tpermisosRelevantes: boolean;\n\taccesibilidad?: boolean;\n\tgrabacionPantalla?: boolean;\n\t/**\n\t * macOS dice que la Grabación de pantalla está concedida, pero al intentar\n\t * capturar de verdad falla.\n\t *\n\t * Significa casi siempre que el permiso pertenece a OTRA identidad de\n\t * aplicación — el caso típico al cambiar el identificador de paquete, o al\n\t * venir de una versión anterior firmada distinto. Sin distinguirlo, la\n\t * interfaz enseñaría \"falta permiso\" mientras el usuario ve el interruptor\n\t * encendido en Ajustes, y no hay forma de salir de ahí.\n\t */\n\tpantallaDeOtraApp?: boolean;\n\t/**\n\t * No se pudo PREGUNTAR por los permisos (el demonio no contestó).\n\t *\n\t * Es distinto de \"denegados\", y confundirlos se ve en pantalla: sin esto, un\n\t * timeout del demonio hacía que el panel dijera \"macOS sigue negando\n\t * permisos\" y ofreciera los dos pasos para concederlos. El usuario iba a\n\t * Ajustes del Sistema, veía los interruptores YA encendidos, y se quedaba sin\n\t * saber qué hacer. El remedio de verdad es reintentar o reiniciar el motor.\n\t */\n\tconsultaFallida?: boolean;\n\t/**\n\t * Qué panel de Ajustes se acaba de abrir, si se abrió alguno.\n\t *\n\t * Lo pone solo `pedirPermisos`. Sirve para dos cosas: que la interfaz pueda\n\t * decir a cuál ha mandado al usuario, y que se pueda COMPROBAR que no se\n\t * abre ninguno cuando no toca. Sin este campo, \"no abrir el panel\" y\n\t * \"abrirlo y que falle\" se ven exactamente igual desde fuera — y una prueba\n\t * que no distingue esos dos casos no prueba nada.\n\t */\n\tpanelAbierto?: PermisoMac;\n\tdetalle?: string;\n}\n\nfunction ejecutar(cmd: string, args: string[], timeoutMs: number): Promise<{ code: number; salida: string }> {\n\treturn new Promise((resolve) => {\n\t\tlet hijo: ReturnType<typeof spawn>;\n\t\ttry {\n\t\t\thijo = spawn(cmd, args, { stdio: [\"ignore\", \"pipe\", \"pipe\"] });\n\t\t} catch (error) {\n\t\t\tresolve({ code: -1, salida: error instanceof Error ? error.message : String(error) });\n\t\t\treturn;\n\t\t}\n\t\tlet salida = \"\";\n\t\tlet resuelto = false;\n\t\tconst fin = (code: number) => {\n\t\t\tif (resuelto) return;\n\t\t\tresuelto = true;\n\t\t\tclearTimeout(reloj);\n\t\t\tresolve({ code, salida });\n\t\t};\n\t\tconst reloj = setTimeout(() => {\n\t\t\thijo.kill(\"SIGKILL\");\n\t\t\tfin(124);\n\t\t}, timeoutMs);\n\t\tconst recoger = (t: Buffer) => {\n\t\t\tif (salida.length < MAX_SALIDA) salida += t.toString(\"utf8\");\n\t\t};\n\t\thijo.stdout?.on(\"data\", recoger);\n\t\thijo.stderr?.on(\"data\", recoger);\n\t\thijo.on(\"error\", (e) => {\n\t\t\tsalida += e.message;\n\t\t\tfin(-1);\n\t\t});\n\t\thijo.on(\"close\", (c) => fin(c ?? 0));\n\t});\n}\n\n/** El script que instala y firma el helper nativo. */\nfunction rutaDelInstalador(): string {\n\t// `vendor/computer-use/scripts/` desde `src/core/computer/`.\n\treturn join(\n\t\tdirname(fileURLToPath(import.meta.url)),\n\t\t\"..\",\n\t\t\"..\",\n\t\t\"..\",\n\t\t\"vendor\",\n\t\t\"computer-use\",\n\t\t\"scripts\",\n\t\t\"setup-helper.mjs\",\n\t);\n}\n\n/**\n * ¿Está el motor listo?\n *\n * Se comprueban el helper y los permisos por separado porque fallan por\n * separado: el helper puede estar instalado y macOS seguir negando la\n * Accesibilidad. Decir solo \"no funciona\" dejaría al usuario sin saber qué\n * arreglar, y en macOS lo que falla casi siempre son los permisos.\n */\nexport async function estadoDelMotor(opciones: OpcionesEstado = {}): Promise<EstadoMotor> {\n\tconst plataforma = opciones.plataforma ?? process.platform;\n\tconst permisosRelevantes = plataforma === \"darwin\";\n\n\tif (!permisosRelevantes) {\n\t\t// Fuera de macOS no hay .app que comprobar; el helper es un binario suelto\n\t\t// y su ausencia se descubre al usarlo.\n\t\treturn { instalado: true, permisosRelevantes, version: VERSION_MOTOR };\n\t}\n\n\tconst rutaHelper = opciones.rutaHelper ?? HELPER_APP_PATH;\n\tif (!existsSync(rutaHelper)) {\n\t\treturn {\n\t\t\tinstalado: false,\n\t\t\tpermisosRelevantes,\n\t\t\tdetalle: `No está instalado el helper en ${rutaHelper}`,\n\t\t};\n\t}\n\n\ttry {\n\t\tawait macosHelper.ensureDaemon();\n\t\t// `checkPermissions`, no `diagnostics`: el primero hace una sonda VIVA de\n\t\t// ScreenCaptureKit; el segundo lee lo que dice la base de datos TCC. No es\n\t\t// lo mismo, y justo cuando difieren es cuando el usuario está atascado.\n\t\tconst p = await macosHelper.command<{\n\t\t\taccessibility?: boolean;\n\t\t\tscreenRecordingCapturable?: boolean;\n\t\t\tscreenRecordingPreflight?: boolean;\n\t\t}>(\"checkPermissions\", {});\n\t\tconst captura = p.screenRecordingCapturable === true;\n\t\tconst enTcc = p.screenRecordingPreflight === true;\n\t\treturn {\n\t\t\tinstalado: true,\n\t\t\tpermisosRelevantes,\n\t\t\tversion: VERSION_MOTOR,\n\t\t\taccesibilidad: p.accessibility === true,\n\t\t\tgrabacionPantalla: captura,\n\t\t\tpantallaDeOtraApp: enTcc && !captura,\n\t\t\tdetalle: `accesibilidad=${p.accessibility === true}, pantalla=${captura}${enTcc && !captura ? \" (concedida a otra app)\" : \"\"}`,\n\t\t};\n\t} catch (error) {\n\t\treturn {\n\t\t\tinstalado: true,\n\t\t\tpermisosRelevantes,\n\t\t\tversion: VERSION_MOTOR,\n\t\t\tconsultaFallida: true,\n\t\t\tdetalle: error instanceof Error ? error.message : String(error),\n\t\t};\n\t}\n}\n\nexport interface OpcionesEstado {\n\tplataforma?: string;\n\t/**\n\t * Dónde buscar el helper. Solo lo cambian las pruebas: la rama \"no está\n\t * instalado\" decide qué botón enseña Ajustes, y en una máquina donde SÍ está\n\t * instalado no habría forma de recorrerla.\n\t */\n\trutaHelper?: string;\n}\n\nexport interface ResultadoInstalacion {\n\tok: boolean;\n\tsalida: string;\n}\n\n/**\n * Instala el helper nativo.\n *\n * En macOS lo instala como aplicación FIRMADA en `~/Applications`, porque los\n * permisos de Accesibilidad se conceden a una aplicación, no a un binario\n * suelto. La firma es local (ad-hoc): vale para uso propio, pero distribuir\n * Ada a terceros pediría un certificado de Apple.\n */\nexport async function instalarMotor(opciones: { timeoutMs?: number } = {}): Promise<ResultadoInstalacion> {\n\tconst instalador = rutaDelInstalador();\n\tif (!existsSync(instalador)) {\n\t\treturn { ok: false, salida: `No encuentro el instalador en ${instalador}` };\n\t}\n\tconst r = await ejecutar(\"node\", [instalador, \"--postinstall\"], opciones.timeoutMs ?? 300_000);\n\treturn { ok: r.code === 0, salida: r.salida.trim() };\n}\n\n/**\n * Pide los permisos del sistema.\n *\n * Abre el panel de Accesibilidad de macOS y relee el estado DESPUÉS: el usuario\n * tarda en conceder, y dar por buenos unos permisos sin comprobarlos sería\n * enseñar un punto verde falso.\n *\n * Ojo con una consecuencia del fork: al cambiar el identificador de paquete a\n * `com.hoilab.ada-computer-use`, macOS lo trata como una aplicación NUEVA y\n * pedirá permisos aunque el original los tuviera. Es lo correcto — es otra\n * aplicación — pero conviene decírselo al usuario en vez de que parezca un\n * fallo.\n */\nexport async function pedirPermisos(opciones: OpcionesEstado & { permiso?: PermisoMac } = {}): Promise<EstadoMotor> {\n\tconst plataforma = opciones.plataforma ?? process.platform;\n\tif (plataforma !== \"darwin\") return estadoDelMotor(opciones);\n\n\tconst antes = await estadoDelMotor(opciones);\n\tif (!antes.instalado) return antes;\n\n\t// Sin permiso explícito, el primero que falte. Así el CLI sigue siendo un\n\t// comando y la interfaz puede pedir uno concreto.\n\tconst permiso: PermisoMac = opciones.permiso ?? (antes.accesibilidad ? \"pantalla\" : \"accesibilidad\");\n\n\ttry {\n\t\t// PRIMERO registrar. Esto provoca la petición de Accesibilidad y un\n\t\t// intento real de captura, y el efecto que importa es que\n\t\t// `ada-computer-use.app` queda LISTADA en los dos paneles. Sin esto, el\n\t\t// usuario abre Ajustes y tiene que añadir la aplicación con el \"+\",\n\t\t// buscándola por la ruta. Con esto solo tiene que dar al interruptor.\n\t\tawait macosHelper.command(\"registerPermissions\", {}, { timeoutMs: 15_000 });\n\t} catch {\n\t\t// Que no se pueda registrar no impide abrir el panel; el usuario lo\n\t\t// tendrá más incómodo, no imposible.\n\t}\n\n\tlet abierto = true;\n\ttry {\n\t\tawait macosHelper.command(\"openPermissionPane\", { kind: PANEL[permiso] });\n\t} catch {\n\t\t// Si el helper no puede abrirlo, se abre por URL. Es lo que hacíamos\n\t\t// antes y funciona; solo que no deja la app listada.\n\t\tconst url =\n\t\t\tpermiso === \"accesibilidad\"\n\t\t\t\t? \"x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility\"\n\t\t\t\t: \"x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture\";\n\t\tabierto = (await ejecutar(\"open\", [url], 15_000)).code === 0;\n\t}\n\n\treturn { ...(await estadoDelMotor(opciones)), panelAbierto: abierto ? permiso : undefined };\n}\n\n/**\n * Reléelo todo después de que el usuario haya concedido algo.\n *\n * Reinicia el helper ANTES de mirar, y esa es toda la gracia: macOS cachea los\n * permisos POR PROCESO. Un helper que arrancó sin Accesibilidad sigue creyendo\n * que no la tiene aunque acabes de concederla. Sin este reinicio, el usuario\n * concede, pulsa \"volver a comprobar\", sigue en rojo, y concluye que está roto\n * — cuando lo único que pasa es que nadie se lo ha preguntado de nuevo al\n * sistema.\n */\nexport async function recomprobarPermisos(opciones: OpcionesEstado = {}): Promise<EstadoMotor> {\n\tconst plataforma = opciones.plataforma ?? process.platform;\n\tif (plataforma !== \"darwin\") return estadoDelMotor(opciones);\n\ttry {\n\t\tawait macosHelper.restart();\n\t} catch {\n\t\t// Si no reinicia, se mira igual: un dato viejo es mejor que un error.\n\t}\n\treturn estadoDelMotor(opciones);\n}\n"]}

package/dist/core/computer/driver.js

@@ -0,0 +1,206 @@
+/**
+ * Instalación, estado y permisos del motor de control del ordenador.
+ *
+ * El motor es nuestro fork de pi-computer-use, que vive en `motor/`. Este
+ * fichero es lo que usan el comando `ada-cli computer`, la ruta de API del
+ * escritorio y el panel de Ajustes — las tres superficies comparten esto para
+ * que el control del ordenador no sea una función solo del escritorio.
+ *
+ * Antes esto hablaba por CLI con `open-computer-use`. Aquel motor tenía seis
+ * acciones y le faltaban las dos que importan: esperar y buscar. El detalle del
+ * cambio está en `vendor/computer-use/PROCEDENCIA.md`.
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { HELPER_APP_PATH, macosHelper } from "./motor/platform/macos/helper.js";
+/** Versión del fork. Sube cuando traigamos cambios de aguas arriba. */
+export const VERSION_MOTOR = "0.5.0-ada.1";
+const MAX_SALIDA = 4 * 1024 * 1024;
+/** El nombre que entiende el helper para cada panel. */
+const PANEL = {
+    accesibilidad: "accessibility",
+    pantalla: "screenRecording",
+};
+function ejecutar(cmd, args, timeoutMs) {
+    return new Promise((resolve) => {
+        let hijo;
+        try {
+            hijo = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+        }
+        catch (error) {
+            resolve({ code: -1, salida: error instanceof Error ? error.message : String(error) });
+            return;
+        }
+        let salida = "";
+        let resuelto = false;
+        const fin = (code) => {
+            if (resuelto)
+                return;
+            resuelto = true;
+            clearTimeout(reloj);
+            resolve({ code, salida });
+        };
+        const reloj = setTimeout(() => {
+            hijo.kill("SIGKILL");
+            fin(124);
+        }, timeoutMs);
+        const recoger = (t) => {
+            if (salida.length < MAX_SALIDA)
+                salida += t.toString("utf8");
+        };
+        hijo.stdout?.on("data", recoger);
+        hijo.stderr?.on("data", recoger);
+        hijo.on("error", (e) => {
+            salida += e.message;
+            fin(-1);
+        });
+        hijo.on("close", (c) => fin(c ?? 0));
+    });
+}
+/** El script que instala y firma el helper nativo. */
+function rutaDelInstalador() {
+    // `vendor/computer-use/scripts/` desde `src/core/computer/`.
+    return join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "vendor", "computer-use", "scripts", "setup-helper.mjs");
+}
+/**
+ * ¿Está el motor listo?
+ *
+ * Se comprueban el helper y los permisos por separado porque fallan por
+ * separado: el helper puede estar instalado y macOS seguir negando la
+ * Accesibilidad. Decir solo "no funciona" dejaría al usuario sin saber qué
+ * arreglar, y en macOS lo que falla casi siempre son los permisos.
+ */
+export async function estadoDelMotor(opciones = {}) {
+    const plataforma = opciones.plataforma ?? process.platform;
+    const permisosRelevantes = plataforma === "darwin";
+    if (!permisosRelevantes) {
+        // Fuera de macOS no hay .app que comprobar; el helper es un binario suelto
+        // y su ausencia se descubre al usarlo.
+        return { instalado: true, permisosRelevantes, version: VERSION_MOTOR };
+    }
+    const rutaHelper = opciones.rutaHelper ?? HELPER_APP_PATH;
+    if (!existsSync(rutaHelper)) {
+        return {
+            instalado: false,
+            permisosRelevantes,
+            detalle: `No está instalado el helper en ${rutaHelper}`,
+        };
+    }
+    try {
+        await macosHelper.ensureDaemon();
+        // `checkPermissions`, no `diagnostics`: el primero hace una sonda VIVA de
+        // ScreenCaptureKit; el segundo lee lo que dice la base de datos TCC. No es
+        // lo mismo, y justo cuando difieren es cuando el usuario está atascado.
+        const p = await macosHelper.command("checkPermissions", {});
+        const captura = p.screenRecordingCapturable === true;
+        const enTcc = p.screenRecordingPreflight === true;
+        return {
+            instalado: true,
+            permisosRelevantes,
+            version: VERSION_MOTOR,
+            accesibilidad: p.accessibility === true,
+            grabacionPantalla: captura,
+            pantallaDeOtraApp: enTcc && !captura,
+            detalle: `accesibilidad=${p.accessibility === true}, pantalla=${captura}${enTcc && !captura ? " (concedida a otra app)" : ""}`,
+        };
+    }
+    catch (error) {
+        return {
+            instalado: true,
+            permisosRelevantes,
+            version: VERSION_MOTOR,
+            consultaFallida: true,
+            detalle: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Instala el helper nativo.
+ *
+ * En macOS lo instala como aplicación FIRMADA en `~/Applications`, porque los
+ * permisos de Accesibilidad se conceden a una aplicación, no a un binario
+ * suelto. La firma es local (ad-hoc): vale para uso propio, pero distribuir
+ * Ada a terceros pediría un certificado de Apple.
+ */
+export async function instalarMotor(opciones = {}) {
+    const instalador = rutaDelInstalador();
+    if (!existsSync(instalador)) {
+        return { ok: false, salida: `No encuentro el instalador en ${instalador}` };
+    }
+    const r = await ejecutar("node", [instalador, "--postinstall"], opciones.timeoutMs ?? 300_000);
+    return { ok: r.code === 0, salida: r.salida.trim() };
+}
+/**
+ * Pide los permisos del sistema.
+ *
+ * Abre el panel de Accesibilidad de macOS y relee el estado DESPUÉS: el usuario
+ * tarda en conceder, y dar por buenos unos permisos sin comprobarlos sería
+ * enseñar un punto verde falso.
+ *
+ * Ojo con una consecuencia del fork: al cambiar el identificador de paquete a
+ * `com.hoilab.ada-computer-use`, macOS lo trata como una aplicación NUEVA y
+ * pedirá permisos aunque el original los tuviera. Es lo correcto — es otra
+ * aplicación — pero conviene decírselo al usuario en vez de que parezca un
+ * fallo.
+ */
+export async function pedirPermisos(opciones = {}) {
+    const plataforma = opciones.plataforma ?? process.platform;
+    if (plataforma !== "darwin")
+        return estadoDelMotor(opciones);
+    const antes = await estadoDelMotor(opciones);
+    if (!antes.instalado)
+        return antes;
+    // Sin permiso explícito, el primero que falte. Así el CLI sigue siendo un
+    // comando y la interfaz puede pedir uno concreto.
+    const permiso = opciones.permiso ?? (antes.accesibilidad ? "pantalla" : "accesibilidad");
+    try {
+        // PRIMERO registrar. Esto provoca la petición de Accesibilidad y un
+        // intento real de captura, y el efecto que importa es que
+        // `ada-computer-use.app` queda LISTADA en los dos paneles. Sin esto, el
+        // usuario abre Ajustes y tiene que añadir la aplicación con el "+",
+        // buscándola por la ruta. Con esto solo tiene que dar al interruptor.
+        await macosHelper.command("registerPermissions", {}, { timeoutMs: 15_000 });
+    }
+    catch {
+        // Que no se pueda registrar no impide abrir el panel; el usuario lo
+        // tendrá más incómodo, no imposible.
+    }
+    let abierto = true;
+    try {
+        await macosHelper.command("openPermissionPane", { kind: PANEL[permiso] });
+    }
+    catch {
+        // Si el helper no puede abrirlo, se abre por URL. Es lo que hacíamos
+        // antes y funciona; solo que no deja la app listada.
+        const url = permiso === "accesibilidad"
+            ? "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"
+            : "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture";
+        abierto = (await ejecutar("open", [url], 15_000)).code === 0;
+    }
+    return { ...(await estadoDelMotor(opciones)), panelAbierto: abierto ? permiso : undefined };
+}
+/**
+ * Reléelo todo después de que el usuario haya concedido algo.
+ *
+ * Reinicia el helper ANTES de mirar, y esa es toda la gracia: macOS cachea los
+ * permisos POR PROCESO. Un helper que arrancó sin Accesibilidad sigue creyendo
+ * que no la tiene aunque acabes de concederla. Sin este reinicio, el usuario
+ * concede, pulsa "volver a comprobar", sigue en rojo, y concluye que está roto
+ * — cuando lo único que pasa es que nadie se lo ha preguntado de nuevo al
+ * sistema.
+ */
+export async function recomprobarPermisos(opciones = {}) {
+    const plataforma = opciones.plataforma ?? process.platform;
+    if (plataforma !== "darwin")
+        return estadoDelMotor(opciones);
+    try {
+        await macosHelper.restart();
+    }
+    catch {
+        // Si no reinicia, se mira igual: un dato viejo es mejor que un error.
+    }
+    return estadoDelMotor(opciones);
+}
+//# sourceMappingURL=driver.js.map

package/dist/core/computer/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../../../src/core/computer/driver.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Instalación, estado y permisos del motor de control del ordenador.\n *\n * El motor es nuestro fork de pi-computer-use, que vive en `motor/`. Este\n * fichero es lo que usan el comando `ada-cli computer`, la ruta de API del\n * escritorio y el panel de Ajustes — las tres superficies comparten esto para\n * que el control del ordenador no sea una función solo del escritorio.\n *\n * Antes esto hablaba por CLI con `open-computer-use`. Aquel motor tenía seis\n * acciones y le faltaban las dos que importan: esperar y buscar. El detalle del\n * cambio está en `vendor/computer-use/PROCEDENCIA.md`.\n */\n\nimport { spawn } from \"node:child_process\";\nimport { existsSync } from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { HELPER_APP_PATH, macosHelper } from \"./motor/platform/macos/helper.ts\";\n\n/** Versión del fork. Sube cuando traigamos cambios de aguas arriba. */\nexport const VERSION_MOTOR = \"0.5.0-ada.1\";\n\nconst MAX_SALIDA = 4 * 1024 * 1024;\n\n/**\n * Los dos permisos de macOS, por separado.\n *\n * Van separados porque son DOS paneles distintos de Ajustes del Sistema y hay\n * que conceder los dos. Un único botón \"conceder permisos\" solo puede abrir uno\n * de ellos, y deja al usuario creyendo que ya está.\n */\nexport type PermisoMac = \"accesibilidad\" | \"pantalla\";\n\n/** El nombre que entiende el helper para cada panel. */\nconst PANEL: Record<PermisoMac, string> = {\n\taccesibilidad: \"accessibility\",\n\tpantalla: \"screenRecording\",\n};\n\nexport interface EstadoMotor {\n\tinstalado: boolean;\n\tversion?: string;\n\t/**\n\t * `true` solo donde el sistema exige permisos explícitos — hoy, macOS.\n\t *\n\t * En Linux y Windows el motor funciona sin conceder nada. Sin esta\n\t * distinción, la ausencia de las líneas de permisos se leería como\n\t * \"denegado\" y la interfaz avisaría de un problema inventado en dos de las\n\t * tres plataformas.\n\t */\n\tpermisosRelevantes: boolean;\n\taccesibilidad?: boolean;\n\tgrabacionPantalla?: boolean;\n\t/**\n\t * macOS dice que la Grabación de pantalla está concedida, pero al intentar\n\t * capturar de verdad falla.\n\t *\n\t * Significa casi siempre que el permiso pertenece a OTRA identidad de\n\t * aplicación — el caso típico al cambiar el identificador de paquete, o al\n\t * venir de una versión anterior firmada distinto. Sin distinguirlo, la\n\t * interfaz enseñaría \"falta permiso\" mientras el usuario ve el interruptor\n\t * encendido en Ajustes, y no hay forma de salir de ahí.\n\t */\n\tpantallaDeOtraApp?: boolean;\n\t/**\n\t * No se pudo PREGUNTAR por los permisos (el demonio no contestó).\n\t *\n\t * Es distinto de \"denegados\", y confundirlos se ve en pantalla: sin esto, un\n\t * timeout del demonio hacía que el panel dijera \"macOS sigue negando\n\t * permisos\" y ofreciera los dos pasos para concederlos. El usuario iba a\n\t * Ajustes del Sistema, veía los interruptores YA encendidos, y se quedaba sin\n\t * saber qué hacer. El remedio de verdad es reintentar o reiniciar el motor.\n\t */\n\tconsultaFallida?: boolean;\n\t/**\n\t * Qué panel de Ajustes se acaba de abrir, si se abrió alguno.\n\t *\n\t * Lo pone solo `pedirPermisos`. Sirve para dos cosas: que la interfaz pueda\n\t * decir a cuál ha mandado al usuario, y que se pueda COMPROBAR que no se\n\t * abre ninguno cuando no toca. Sin este campo, \"no abrir el panel\" y\n\t * \"abrirlo y que falle\" se ven exactamente igual desde fuera — y una prueba\n\t * que no distingue esos dos casos no prueba nada.\n\t */\n\tpanelAbierto?: PermisoMac;\n\tdetalle?: string;\n}\n\nfunction ejecutar(cmd: string, args: string[], timeoutMs: number): Promise<{ code: number; salida: string }> {\n\treturn new Promise((resolve) => {\n\t\tlet hijo: ReturnType<typeof spawn>;\n\t\ttry {\n\t\t\thijo = spawn(cmd, args, { stdio: [\"ignore\", \"pipe\", \"pipe\"] });\n\t\t} catch (error) {\n\t\t\tresolve({ code: -1, salida: error instanceof Error ? error.message : String(error) });\n\t\t\treturn;\n\t\t}\n\t\tlet salida = \"\";\n\t\tlet resuelto = false;\n\t\tconst fin = (code: number) => {\n\t\t\tif (resuelto) return;\n\t\t\tresuelto = true;\n\t\t\tclearTimeout(reloj);\n\t\t\tresolve({ code, salida });\n\t\t};\n\t\tconst reloj = setTimeout(() => {\n\t\t\thijo.kill(\"SIGKILL\");\n\t\t\tfin(124);\n\t\t}, timeoutMs);\n\t\tconst recoger = (t: Buffer) => {\n\t\t\tif (salida.length < MAX_SALIDA) salida += t.toString(\"utf8\");\n\t\t};\n\t\thijo.stdout?.on(\"data\", recoger);\n\t\thijo.stderr?.on(\"data\", recoger);\n\t\thijo.on(\"error\", (e) => {\n\t\t\tsalida += e.message;\n\t\t\tfin(-1);\n\t\t});\n\t\thijo.on(\"close\", (c) => fin(c ?? 0));\n\t});\n}\n\n/** El script que instala y firma el helper nativo. */\nfunction rutaDelInstalador(): string {\n\t// `vendor/computer-use/scripts/` desde `src/core/computer/`.\n\treturn join(\n\t\tdirname(fileURLToPath(import.meta.url)),\n\t\t\"..\",\n\t\t\"..\",\n\t\t\"..\",\n\t\t\"vendor\",\n\t\t\"computer-use\",\n\t\t\"scripts\",\n\t\t\"setup-helper.mjs\",\n\t);\n}\n\n/**\n * ¿Está el motor listo?\n *\n * Se comprueban el helper y los permisos por separado porque fallan por\n * separado: el helper puede estar instalado y macOS seguir negando la\n * Accesibilidad. Decir solo \"no funciona\" dejaría al usuario sin saber qué\n * arreglar, y en macOS lo que falla casi siempre son los permisos.\n */\nexport async function estadoDelMotor(opciones: OpcionesEstado = {}): Promise<EstadoMotor> {\n\tconst plataforma = opciones.plataforma ?? process.platform;\n\tconst permisosRelevantes = plataforma === \"darwin\";\n\n\tif (!permisosRelevantes) {\n\t\t// Fuera de macOS no hay .app que comprobar; el helper es un binario suelto\n\t\t// y su ausencia se descubre al usarlo.\n\t\treturn { instalado: true, permisosRelevantes, version: VERSION_MOTOR };\n\t}\n\n\tconst rutaHelper = opciones.rutaHelper ?? HELPER_APP_PATH;\n\tif (!existsSync(rutaHelper)) {\n\t\treturn {\n\t\t\tinstalado: false,\n\t\t\tpermisosRelevantes,\n\t\t\tdetalle: `No está instalado el helper en ${rutaHelper}`,\n\t\t};\n\t}\n\n\ttry {\n\t\tawait macosHelper.ensureDaemon();\n\t\t// `checkPermissions`, no `diagnostics`: el primero hace una sonda VIVA de\n\t\t// ScreenCaptureKit; el segundo lee lo que dice la base de datos TCC. No es\n\t\t// lo mismo, y justo cuando difieren es cuando el usuario está atascado.\n\t\tconst p = await macosHelper.command<{\n\t\t\taccessibility?: boolean;\n\t\t\tscreenRecordingCapturable?: boolean;\n\t\t\tscreenRecordingPreflight?: boolean;\n\t\t}>(\"checkPermissions\", {});\n\t\tconst captura = p.screenRecordingCapturable === true;\n\t\tconst enTcc = p.screenRecordingPreflight === true;\n\t\treturn {\n\t\t\tinstalado: true,\n\t\t\tpermisosRelevantes,\n\t\t\tversion: VERSION_MOTOR,\n\t\t\taccesibilidad: p.accessibility === true,\n\t\t\tgrabacionPantalla: captura,\n\t\t\tpantallaDeOtraApp: enTcc && !captura,\n\t\t\tdetalle: `accesibilidad=${p.accessibility === true}, pantalla=${captura}${enTcc && !captura ? \" (concedida a otra app)\" : \"\"}`,\n\t\t};\n\t} catch (error) {\n\t\treturn {\n\t\t\tinstalado: true,\n\t\t\tpermisosRelevantes,\n\t\t\tversion: VERSION_MOTOR,\n\t\t\tconsultaFallida: true,\n\t\t\tdetalle: error instanceof Error ? error.message : String(error),\n\t\t};\n\t}\n}\n\nexport interface OpcionesEstado {\n\tplataforma?: string;\n\t/**\n\t * Dónde buscar el helper. Solo lo cambian las pruebas: la rama \"no está\n\t * instalado\" decide qué botón enseña Ajustes, y en una máquina donde SÍ está\n\t * instalado no habría forma de recorrerla.\n\t */\n\trutaHelper?: string;\n}\n\nexport interface ResultadoInstalacion {\n\tok: boolean;\n\tsalida: string;\n}\n\n/**\n * Instala el helper nativo.\n *\n * En macOS lo instala como aplicación FIRMADA en `~/Applications`, porque los\n * permisos de Accesibilidad se conceden a una aplicación, no a un binario\n * suelto. La firma es local (ad-hoc): vale para uso propio, pero distribuir\n * Ada a terceros pediría un certificado de Apple.\n */\nexport async function instalarMotor(opciones: { timeoutMs?: number } = {}): Promise<ResultadoInstalacion> {\n\tconst instalador = rutaDelInstalador();\n\tif (!existsSync(instalador)) {\n\t\treturn { ok: false, salida: `No encuentro el instalador en ${instalador}` };\n\t}\n\tconst r = await ejecutar(\"node\", [instalador, \"--postinstall\"], opciones.timeoutMs ?? 300_000);\n\treturn { ok: r.code === 0, salida: r.salida.trim() };\n}\n\n/**\n * Pide los permisos del sistema.\n *\n * Abre el panel de Accesibilidad de macOS y relee el estado DESPUÉS: el usuario\n * tarda en conceder, y dar por buenos unos permisos sin comprobarlos sería\n * enseñar un punto verde falso.\n *\n * Ojo con una consecuencia del fork: al cambiar el identificador de paquete a\n * `com.hoilab.ada-computer-use`, macOS lo trata como una aplicación NUEVA y\n * pedirá permisos aunque el original los tuviera. Es lo correcto — es otra\n * aplicación — pero conviene decírselo al usuario en vez de que parezca un\n * fallo.\n */\nexport async function pedirPermisos(opciones: OpcionesEstado & { permiso?: PermisoMac } = {}): Promise<EstadoMotor> {\n\tconst plataforma = opciones.plataforma ?? process.platform;\n\tif (plataforma !== \"darwin\") return estadoDelMotor(opciones);\n\n\tconst antes = await estadoDelMotor(opciones);\n\tif (!antes.instalado) return antes;\n\n\t// Sin permiso explícito, el primero que falte. Así el CLI sigue siendo un\n\t// comando y la interfaz puede pedir uno concreto.\n\tconst permiso: PermisoMac = opciones.permiso ?? (antes.accesibilidad ? \"pantalla\" : \"accesibilidad\");\n\n\ttry {\n\t\t// PRIMERO registrar. Esto provoca la petición de Accesibilidad y un\n\t\t// intento real de captura, y el efecto que importa es que\n\t\t// `ada-computer-use.app` queda LISTADA en los dos paneles. Sin esto, el\n\t\t// usuario abre Ajustes y tiene que añadir la aplicación con el \"+\",\n\t\t// buscándola por la ruta. Con esto solo tiene que dar al interruptor.\n\t\tawait macosHelper.command(\"registerPermissions\", {}, { timeoutMs: 15_000 });\n\t} catch {\n\t\t// Que no se pueda registrar no impide abrir el panel; el usuario lo\n\t\t// tendrá más incómodo, no imposible.\n\t}\n\n\tlet abierto = true;\n\ttry {\n\t\tawait macosHelper.command(\"openPermissionPane\", { kind: PANEL[permiso] });\n\t} catch {\n\t\t// Si el helper no puede abrirlo, se abre por URL. Es lo que hacíamos\n\t\t// antes y funciona; solo que no deja la app listada.\n\t\tconst url =\n\t\t\tpermiso === \"accesibilidad\"\n\t\t\t\t? \"x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility\"\n\t\t\t\t: \"x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture\";\n\t\tabierto = (await ejecutar(\"open\", [url], 15_000)).code === 0;\n\t}\n\n\treturn { ...(await estadoDelMotor(opciones)), panelAbierto: abierto ? permiso : undefined };\n}\n\n/**\n * Reléelo todo después de que el usuario haya concedido algo.\n *\n * Reinicia el helper ANTES de mirar, y esa es toda la gracia: macOS cachea los\n * permisos POR PROCESO. Un helper que arrancó sin Accesibilidad sigue creyendo\n * que no la tiene aunque acabes de concederla. Sin este reinicio, el usuario\n * concede, pulsa \"volver a comprobar\", sigue en rojo, y concluye que está roto\n * — cuando lo único que pasa es que nadie se lo ha preguntado de nuevo al\n * sistema.\n */\nexport async function recomprobarPermisos(opciones: OpcionesEstado = {}): Promise<EstadoMotor> {\n\tconst plataforma = opciones.plataforma ?? process.platform;\n\tif (plataforma !== \"darwin\") return estadoDelMotor(opciones);\n\ttry {\n\t\tawait macosHelper.restart();\n\t} catch {\n\t\t// Si no reinicia, se mira igual: un dato viejo es mejor que un error.\n\t}\n\treturn estadoDelMotor(opciones);\n}\n"]}

package/dist/core/computer/motor/actions.d.ts

@@ -0,0 +1,109 @@
+import type { MouseButtonName, UiAction } from "./contract.ts";
+import type { OutlineNode } from "./outline.ts";
+export type ActionTarget = {
+    ref: string;
+} | {
+    x: number;
+    y: number;
+} | {
+    focus: {
+        x: number;
+        y: number;
+    };
+};
+export type PreparedAction = {
+    action: "press" | "click";
+    target: ActionTarget;
+    params: {
+        button?: MouseButtonName;
+        clickCount?: number;
+    };
+    establishesFocus: boolean;
+    usesCurrentFocus: false;
+    needsForeground: boolean;
+} | {
+    action: "setText";
+    target: ActionTarget;
+    params: {
+        text: string;
+    };
+    establishesFocus: false;
+    usesCurrentFocus: false;
+    needsForeground: false;
+} | {
+    action: "typeText";
+    target: ActionTarget;
+    params: {
+        text: string;
+    };
+    establishesFocus: false;
+    usesCurrentFocus: boolean;
+    needsForeground: false;
+} | {
+    action: "keypress";
+    target: ActionTarget;
+    params: {
+        keys: string[];
+    };
+    establishesFocus: false;
+    usesCurrentFocus: boolean;
+    needsForeground: false;
+} | {
+    action: "scroll";
+    target: ActionTarget;
+    params: {
+        scrollX: number;
+        scrollY: number;
+    };
+    establishesFocus: false;
+    usesCurrentFocus: false;
+    needsForeground: false;
+} | {
+    action: "drag";
+    target: ActionTarget;
+    params: {
+        path: Array<{
+            x: number;
+            y: number;
+        }>;
+    };
+    establishesFocus: false;
+    usesCurrentFocus: false;
+    needsForeground: false;
+} | {
+    action: "moveMouse";
+    target: ActionTarget;
+    params: Record<string, never>;
+    establishesFocus: false;
+    usesCurrentFocus: false;
+    needsForeground: false;
+} | {
+    action: "wait";
+    params: {
+        ms: number;
+    };
+    establishesFocus: false;
+    usesCurrentFocus: false;
+    needsForeground: false;
+};
+export interface ActionState {
+    currentFocus: boolean;
+}
+export interface ActionEnvironment {
+    headless: boolean;
+    image?: {
+        width: number;
+        height: number;
+    };
+    node(ref: string): OutlineNode;
+    center(node: OutlineNode): {
+        x: number;
+        y: number;
+    };
+    validatePoint(x: number, y: number, label?: string): void;
+}
+export declare function prepareAction(action: UiAction, state: ActionState, env: ActionEnvironment): PreparedAction;
+export declare function canRetryInForeground(action: PreparedAction, outcome: "worked" | "didnt" | "unknown", headless: boolean): boolean;
+export declare function outcomeAfterCheck(current: "worked" | "didnt" | "unknown", check: "verified" | "preexisting" | "failed"): "worked" | "didnt" | "unknown";
+export declare function outcomeAfterObservedValues(current: "worked" | "didnt" | "unknown", actions: UiAction[], valueForRef: (ref: string) => string | undefined): "worked" | "didnt" | "unknown";
+//# sourceMappingURL=actions.d.ts.map

package/dist/core/computer/motor/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../../../../src/core/computer/motor/actions.ts"],"names":[],"mappings":"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","sourcesContent":["import type { MouseButtonName, UiAction } from \"./contract.ts\";\nimport type { OutlineNode } from \"./outline.ts\";\nimport { toFiniteNumber } from \"./platform/coerce.ts\";\n\nexport type ActionTarget = { ref: string } | { x: number; y: number } | { focus: { x: number; y: number } };\n\nexport type PreparedAction =\n\t| {\n\t\t\taction: \"press\" | \"click\";\n\t\t\ttarget: ActionTarget;\n\t\t\tparams: { button?: MouseButtonName; clickCount?: number };\n\t\t\testablishesFocus: boolean;\n\t\t\tusesCurrentFocus: false;\n\t\t\tneedsForeground: boolean;\n\t  }\n\t| {\n\t\t\taction: \"setText\";\n\t\t\ttarget: ActionTarget;\n\t\t\tparams: { text: string };\n\t\t\testablishesFocus: false;\n\t\t\tusesCurrentFocus: false;\n\t\t\tneedsForeground: false;\n\t  }\n\t| {\n\t\t\taction: \"typeText\";\n\t\t\ttarget: ActionTarget;\n\t\t\tparams: { text: string };\n\t\t\testablishesFocus: false;\n\t\t\tusesCurrentFocus: boolean;\n\t\t\tneedsForeground: false;\n\t  }\n\t| {\n\t\t\taction: \"keypress\";\n\t\t\ttarget: ActionTarget;\n\t\t\tparams: { keys: string[] };\n\t\t\testablishesFocus: false;\n\t\t\tusesCurrentFocus: boolean;\n\t\t\tneedsForeground: false;\n\t  }\n\t| {\n\t\t\taction: \"scroll\";\n\t\t\ttarget: ActionTarget;\n\t\t\tparams: { scrollX: number; scrollY: number };\n\t\t\testablishesFocus: false;\n\t\t\tusesCurrentFocus: false;\n\t\t\tneedsForeground: false;\n\t  }\n\t| {\n\t\t\taction: \"drag\";\n\t\t\ttarget: ActionTarget;\n\t\t\tparams: { path: Array<{ x: number; y: number }> };\n\t\t\testablishesFocus: false;\n\t\t\tusesCurrentFocus: false;\n\t\t\tneedsForeground: false;\n\t  }\n\t| {\n\t\t\taction: \"moveMouse\";\n\t\t\ttarget: ActionTarget;\n\t\t\tparams: Record<string, never>;\n\t\t\testablishesFocus: false;\n\t\t\tusesCurrentFocus: false;\n\t\t\tneedsForeground: false;\n\t  }\n\t| {\n\t\t\taction: \"wait\";\n\t\t\tparams: { ms: number };\n\t\t\testablishesFocus: false;\n\t\t\tusesCurrentFocus: false;\n\t\t\tneedsForeground: false;\n\t  };\n\nexport interface ActionState {\n\tcurrentFocus: boolean;\n}\n\nexport interface ActionEnvironment {\n\theadless: boolean;\n\timage?: { width: number; height: number };\n\tnode(ref: string): OutlineNode;\n\tcenter(node: OutlineNode): { x: number; y: number };\n\tvalidatePoint(x: number, y: number, label?: string): void;\n}\n\nfunction mouseButton(value: unknown): MouseButtonName {\n\treturn value === \"right\" || value === \"middle\" ? value : \"left\";\n}\n\nfunction clickCount(value: unknown, fallback = 1): number {\n\treturn Math.max(1, Math.min(3, Math.round(toFiniteNumber(value, fallback))));\n}\n\nfunction scrollDelta(value: unknown): number {\n\treturn Math.max(-10_000, Math.min(10_000, Math.round(toFiniteNumber(value, 0))));\n}\n\nfunction keys(value: unknown): string[] {\n\tif (!Array.isArray(value) || value.length === 0) throw new Error(\"keypress.keys must contain at least one key.\");\n\treturn value.map((key) => String(key));\n}\n\nfunction path(value: UiAction[\"path\"], env: ActionEnvironment): Array<{ x: number; y: number }> {\n\tif (!Array.isArray(value) || value.length < 2) throw new Error(\"drag.path must contain at least two points.\");\n\treturn value.map((point, index) => {\n\t\tconst x = Array.isArray(point) ? toFiniteNumber(point[0], NaN) : toFiniteNumber(point?.x, NaN);\n\t\tconst y = Array.isArray(point) ? toFiniteNumber(point[1], NaN) : toFiniteNumber(point?.y, NaN);\n\t\tenv.validatePoint(x, y, `Drag point ${index + 1}`);\n\t\treturn { x, y };\n\t});\n}\n\nfunction nativeTarget(action: UiAction, operation: PreparedAction[\"action\"], env: ActionEnvironment): ActionTarget {\n\tif (action.ref?.trim()) {\n\t\tconst node = env.node(action.ref.trim());\n\t\tconst semanticClick = operation === \"click\" || operation === \"press\";\n\t\tif (semanticClick && node.isTextInput) {\n\t\t\tconst point = env.center(node);\n\t\t\tenv.validatePoint(point.x, point.y);\n\t\t\treturn point;\n\t\t}\n\t\tconst onlyIncidentalActions = node.actions.every(\n\t\t\t(candidate) => candidate === \"AXShowMenu\" || candidate === \"AXScrollToVisible\",\n\t\t);\n\t\tif (\n\t\t\tnode.wireRef &&\n\t\t\t!node.pictureOnly &&\n\t\t\t(!semanticClick || node.canPress || node.canFocus || node.canSetValue || !onlyIncidentalActions)\n\t\t) {\n\t\t\treturn { ref: node.wireRef };\n\t\t}\n\t\tconst point = env.center(node);\n\t\tenv.validatePoint(point.x, point.y);\n\t\treturn point;\n\t}\n\tconst x = toFiniteNumber(action.x, NaN);\n\tconst y = toFiniteNumber(action.y, NaN);\n\tif (Number.isFinite(x) && Number.isFinite(y)) {\n\t\tenv.validatePoint(x, y);\n\t\treturn { x, y };\n\t}\n\tif (operation === \"drag\" && action.path?.length) return path(action.path, env)[0];\n\tthrow new Error(`${operation} requires either ref or both x and y.`);\n}\n\nfunction focusedTarget(env: ActionEnvironment): ActionTarget {\n\tif (!env.image) throw new Error(\"Focused keyboard input requires an image-bearing state.\");\n\treturn { focus: { x: Math.floor(env.image.width / 2), y: Math.floor(env.image.height / 2) } };\n}\n\nfunction containsEditable(node: OutlineNode): boolean {\n\tif (node.canSetValue || node.role.toLowerCase().includes(\"text\")) return true;\n\treturn node.children.some(containsEditable);\n}\n\nexport function prepareAction(action: UiAction, state: ActionState, env: ActionEnvironment): PreparedAction {\n\tconst operation = action.action;\n\tconst usesCurrentFocus =\n\t\t!env.headless && state.currentFocus && !action.ref && (operation === \"typeText\" || operation === \"keypress\");\n\tconst target = usesCurrentFocus ? focusedTarget(env) : nativeTarget(action, operation, env);\n\tconst establishesFocus =\n\t\t!env.headless &&\n\t\tBoolean(action.ref) &&\n\t\t(operation === \"click\" || operation === \"press\") &&\n\t\tcontainsEditable(env.node(action.ref!));\n\tconst needsForeground = !env.headless && (operation === \"click\" || operation === \"press\") && \"x\" in target;\n\n\tswitch (operation) {\n\t\tcase \"press\":\n\t\tcase \"click\":\n\t\t\treturn {\n\t\t\t\taction: operation,\n\t\t\t\ttarget,\n\t\t\t\tparams: { button: mouseButton(action.button), clickCount: clickCount(action.clickCount) },\n\t\t\t\testablishesFocus,\n\t\t\t\tusesCurrentFocus: false,\n\t\t\t\tneedsForeground,\n\t\t\t};\n\t\tcase \"setText\":\n\t\t\treturn {\n\t\t\t\taction: operation,\n\t\t\t\ttarget,\n\t\t\t\tparams: { text: action.text ?? \"\" },\n\t\t\t\testablishesFocus: false,\n\t\t\t\tusesCurrentFocus: false,\n\t\t\t\tneedsForeground: false,\n\t\t\t};\n\t\tcase \"typeText\":\n\t\t\treturn {\n\t\t\t\taction: operation,\n\t\t\t\ttarget,\n\t\t\t\tparams: { text: action.text ?? \"\" },\n\t\t\t\testablishesFocus: false,\n\t\t\t\tusesCurrentFocus,\n\t\t\t\tneedsForeground: false,\n\t\t\t};\n\t\tcase \"keypress\":\n\t\t\treturn {\n\t\t\t\taction: operation,\n\t\t\t\ttarget,\n\t\t\t\tparams: { keys: keys(action.keys) },\n\t\t\t\testablishesFocus: false,\n\t\t\t\tusesCurrentFocus,\n\t\t\t\tneedsForeground: false,\n\t\t\t};\n\t\tcase \"scroll\":\n\t\t\treturn {\n\t\t\t\taction: operation,\n\t\t\t\ttarget,\n\t\t\t\tparams: { scrollX: scrollDelta(action.scrollX), scrollY: scrollDelta(action.scrollY) },\n\t\t\t\testablishesFocus: false,\n\t\t\t\tusesCurrentFocus: false,\n\t\t\t\tneedsForeground: false,\n\t\t\t};\n\t\tcase \"drag\":\n\t\t\treturn {\n\t\t\t\taction: operation,\n\t\t\t\ttarget,\n\t\t\t\tparams: { path: path(action.path, env) },\n\t\t\t\testablishesFocus: false,\n\t\t\t\tusesCurrentFocus: false,\n\t\t\t\tneedsForeground: false,\n\t\t\t};\n\t\tcase \"moveMouse\":\n\t\t\treturn {\n\t\t\t\taction: operation,\n\t\t\t\ttarget,\n\t\t\t\tparams: {},\n\t\t\t\testablishesFocus: false,\n\t\t\t\tusesCurrentFocus: false,\n\t\t\t\tneedsForeground: false,\n\t\t\t};\n\t}\n}\n\nexport function canRetryInForeground(\n\taction: PreparedAction,\n\toutcome: \"worked\" | \"didnt\" | \"unknown\",\n\theadless: boolean,\n): boolean {\n\treturn !headless && outcome === \"didnt\" && (action.action === \"typeText\" || action.action === \"keypress\");\n}\n\nexport function outcomeAfterCheck(\n\tcurrent: \"worked\" | \"didnt\" | \"unknown\",\n\tcheck: \"verified\" | \"preexisting\" | \"failed\",\n): \"worked\" | \"didnt\" | \"unknown\" {\n\tif (check === \"verified\") return \"worked\";\n\tif (check === \"failed\") return \"didnt\";\n\treturn current;\n}\n\nexport function outcomeAfterObservedValues(\n\tcurrent: \"worked\" | \"didnt\" | \"unknown\",\n\tactions: UiAction[],\n\tvalueForRef: (ref: string) => string | undefined,\n): \"worked\" | \"didnt\" | \"unknown\" {\n\tif (actions.length === 0 || actions.some((action) => action.action !== \"setText\" || !action.ref)) return current;\n\tconst matches = actions.every((action) => valueForRef(action.ref!) === (action.text ?? \"\"));\n\treturn matches ? \"worked\" : current;\n}\n"]}