agent-desktop

¿Qué hace agent-desktop?

agent-desktop es una CLI que permite a un agente de IA observar y operar aplicaciones de escritorio a través del árbol de accesibilidad del sistema operativo. Es una herramienta, no un agente. Cada comando imprime un único envelope JSON (ok, data o error). El bucle de observar, actuar y verificar lo controlas tú.

Sintaxis de shell

Los ejemplos usan un shell POSIX. En PowerShell, pon entre comillas cada referencia ('@s8f3k2p9:e1'), porque un @token sin comillas es el operador de splatting. Usa $env:NOMBRE = 'valor' en lugar de export, y | ConvertFrom-Json en lugar de $(...) y jq. La habilidad para Windows tiene las formas de PowerShell.

Verificación previa

Ejecuta esto antes del primer comando de una tarea. Es el único lugar donde se instala la herramienta.

1. Ejecuta agent-desktop version. Si el código de salida es 0, la CLI está presente: ve al paso 4.

2. Si falta, instálala con npm. npm es la única ruta compatible:

   npm install -g agent-desktop

   No intentes con Homebrew, Scoop, un archivo descargado ni una versión anterior. Esta habilidad está escrita para la versión que npm resuelva. Si npm no está en PATH, ejecuta node -v y where npm (Windows) o which npm (macOS, Linux) e informa lo que encontraste. No adivines otro gestor de paquetes.

3. Vuelve a ejecutar agent-desktop version. Si aún falla, detente e informa al usuario: las últimas 20 líneas de la salida de instalación, si agent-desktop --help funciona, y el sistema operativo en el que estás. No recurras a capturas de pantalla ni automatización del ratón por tu cuenta.

4. Ejecuta agent-desktop status. Reporta la plataforma, permisos y supported_surfaces. En macOS, si falta un permiso de Accesibilidad, aparece aquí; dile al usuario que ejecute agent-desktop permissions --guide en lugar de intentar concederlo tú mismo.

5. Ejecuta agent-desktop skills get platform. Carga la habilidad para el sistema operativo donde se ejecuta el binario (macOS, Windows o Linux), y prevalece donde difiere de este archivo.

6. Para banderas y sintaxis, ejecuta agent-desktop <comando> --help. Esta habilidad nunca repite listas de banderas, por lo que --help siempre coincide con la versión instalada.

Si agent-desktop skills get desktop imprime reglas diferentes a este archivo, el binario tiene la razón: este archivo es una copia, el binario es lo que realmente estás manejando.

El bucle

Usa find cuando conozcas el rol o el nombre exacto. Si no, mapea primero la aplicación y profundiza en una región.

agent-desktop snapshot --skeleton --app "Notas" -i --compact   # mapa superficial, children_count en ramas cortadas
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact        # profundiza en una región
agent-desktop click @s8f3k2p9:e12                              # actúa sobre una referencia cualificada
agent-desktop snapshot --root @s8f3k2p9:e3 -i --compact        # verifica: vuelve a leer la misma región

• Una aplicación pequeña no necesita esqueleto. Toma una snapshot -i completa.
• -i mantiene solo los nodos interactivos, por lo que la etiqueta de texto estático de una fila se descarta. Para saber a qué fila pertenece un botón repetido, profundiza en el contenedor de esa fila con --root y omite -i. En Windows y Linux, esto lee la fila pero no hace que su botón sea accionable: un botón repetido en otras filas es un gemelo en la ventana y su referencia es rechazada (ver Referencias).
• Una profundización con --root agrega sus referencias al mismo id de instantánea. Las referencias fuera del subárbol profundizado, y la propia raíz profundizada, siguen siendo válidas; las referencias que ya estaban dentro son reemplazadas, por lo que una referencia antigua allí devuelve STALE_REF.
• Nunca hagas esqueleto de una superficie (--surface menú, hoja, alerta). Una superficie ya está enfocada.
• Una acción que abre un menú, hoja o alerta lo lista en data.surfaces. Apunta a esa superposición a continuación.
• Después de un paso asíncrono, usa wait (consulta references/commands-system.md). Una espera fija es una condición de carrera.

Referencias

• Las referencias de salida están cualificadas: @<id_instantánea>:e<N>, por ejemplo @s8f3k2p9:e1. Pásalas a comandos posteriores tal como están.
• Las referencias son válidas para una instantánea. Después de cualquier cambio en la interfaz, vuelve a profundizar en la región afectada o toma una nueva instantánea.
• Solo los elementos direccionables obtienen referencias. El texto estático y los contenedores inertes no.
• Un comando re-identifica el elemento antes de actuar. En macOS, la referencia lleva la dirección propia del elemento, por lo que gemelos idénticos conservan cada uno su referencia. En Windows y Linux, una referencia se resuelve solo cuando era el único elemento en la ventana que su instantánea capturó con su rol, id nativo, nombre y descripción, contado incluso por debajo de un esqueleto o corte de profundidad, y exactamente un elemento activo sigue coincidiendo. Los gemelos idénticos allí no tienen ruta de referencia: solo --headed mouse-click --xy X,Y puede elegir uno, toma el primer plano, y una sesión de Linux Wayland lo rechaza.
• STALE_REF: el elemento ha desaparecido o ya no coincide. details.kind es saved_ref_absent, o retained_object_stale en macOS. Toma una instantánea nueva y usa la nueva referencia.
• AMBIGUOUS_TARGET: apareció un elemento idéntico (saved_ref_ambiguous), o la referencia no se probó única en la captura (identity_not_unique). Repetir la referencia o volver a tomar una instantánea de gemelos idénticos da la misma negativa; actúa sobre un control que sea único en la ventana. identity_not_unique también sigue a una instantánea que no pudo leer toda la ventana a tiempo: vuelve a tomarla con un --timeout-ms mayor.
• TIMEOUT con details.kind: resolution_identity_unknown: una lectura en vivo no respondió, por lo que la identidad no está probada. No se envió nada; reintenta.
• SNAPSHOT_NOT_FOUND: el id de la instantánea expiró. Toma una instantánea de nuevo.

Entrega y reintento

Los resultados de las acciones llevan data.disposition y los errores llevan error.disposition, cada uno con delivery y retry. Los comandos de observación como snapshot no los tienen en caso de éxito; sus errores, y cada negativa de INVALID_ARGS, llevan not_delivered y retry: safe.

• Reintenta o sustituye una acción solo cuando disposition.retry es safe. Solo not_delivered es seguro.
• Cualquier otro valor de entrega significa que la acción pudo haberse ejecutado. Una repetición puede hacer clic, escribir o enviar dos veces, y toggle puede deshacerse a sí mismo.
• En un resultado que no es seguro, lee el estado en vivo (get, is, o una instantánea nueva) y decide a partir de eso. details.post_state ayuda cuando está presente.
• Ramifica según error.code y error.disposition. El mensaje y el texto de sugerencia pueden cambiar.
• details.retryable: false significa que esperar no puede cambiar el resultado. Prueba un enfoque diferente.

Sin cabeza y con cabeza

Las acciones por referencia son sin cabeza por defecto. Usan llamadas de accesibilidad semánticas y no toman el foco, mueven el cursor, sintetizan teclas ni usan el portapapeles. Si no existe una ruta semántica, la acción falla de forma segura. Usa la bandera global --headed solo cuando el usuario permita explícitamente la entrada física, como doble clic, hover, arrastrar o enfocar. Nunca cambies al modo con cabeza para recuperarte de un fallo sin cabeza. Las coordenadas sin procesar (--xy) nunca implican foco. Qué acciones necesitan --headed varía según el sistema operativo: lee la habilidad de la plataforma.

Referencias

Carga una solo cuando la necesites: agent-desktop skills get desktop <referencia>.

Referencia	Ábrela cuando
commands-observation	Necesites semántica de snapshot, find, get, is, screenshot, list-surfaces, árboles parciales o las reglas de --root
commands-interaction	Elijas entre click, type, set-value, select, toggle, scroll, press y mouse, o depures un error de acción
commands-system	Inicies o cierres aplicaciones, gestiones ventanas, uses el portapapeles, wait, batch, sesiones, cursores multi-agente, trazas o cargues habilidades
workflows	Quieras patrones probados (formularios, menús, diálogos, esperar una nueva ventana, desplazar-buscar, arrastrar) y la lista de anti-patrones