ARK CUA

¿Qué hace ARK CUA?

Opera ARK CUA a través de la CLI de Python empaquetada. Mantén todo el acceso a la gateway dentro de la CLI y nunca solicites una clave de API de AgentPlan en el chat.

Superficie de comandos

python3 <directorio-de-la-habilidad>/scripts/cua.py <comando> [opciones]

Analiza el único objeto JSON que imprime cada invocación:

• Éxito: ok: true, con data y a veces next.
• Fallo: ok: false, con error.code y a veces next.setup_command.

Lee references/commands.md para comandos no principales. Lee references/auth.md, references/outcomes.md o references/troubleshooting.md solo cuando ocurra el estado correspondiente.

Flujo de trabajo principal

1. Ejecuta auth status.
2. En caso de AUTH_REQUIRED, TOKEN_EXPIRED o REFRESH_FAILED, reenvía el setup_command devuelto. Pide al usuario que lo ejecute en su propia terminal local e introduzca la clave de API de AgentPlan a través del prompt oculto. Nunca ejecutes el inicio de sesión interactivo desde una sesión de agente y nunca aceptes la clave en el chat.
3. Después de que el usuario confirme que el inicio de sesión se ha completado, ejecuta auth status nuevamente.
4. Ejecuta delegate --objective "<solicitud del usuario>" una vez. Preserva la solicitud del usuario sin planificarla ni descomponerla.
5. Registra data.invocation_id; nunca envíes la misma solicitud nuevamente.
6. Monitorea data.outcome hasta que sea terminal:
   • in_progress: ejecuta next.command y continúa supervisando.
   • needs_input: reenvía data.input_request.question textualmente, luego envía la respuesta del usuario con answer.
   • completed: usa data.result.text como el resultado autoritativo.
   • failed: reporta el fallo; reintenta solo cuando se solicite y sea seguro.
   • cancelled: reporta la cancelación.

Si la creación de la tarea devuelve ACTIVE_RUN_CONFLICT, la nueva solicitud no se inició. Detente, informa al usuario que el escritorio está ocupado y no reintentes ni inspecciones la tarea existente a menos que el usuario lo solicite explícitamente.

Rutas para intenciones especiales

• Escritorio específico o contexto reutilizable: usa desktop list, task run, context y task continue.
• Entrega de archivos locales: elimina solo la redacción de entrega local del objetivo de CUA, haz que CUA exporte un artefacto registrado, luego usa artifact list y artifact save.
• Inspección de salud o configuración: usa ping, diagnose o model get; no crees una tarea solo para probar la disponibilidad.
• Detener una tarea activa: usa cancel solo cuando el usuario lo solicite explícitamente.

Seguridad e integridad de los resultados

• Usa la gateway empaquetada en assets/config.json; permite las mismas sobrescrituras por llamada y de entorno que ap-cua-skill.
• Configura las credenciales exactamente como ap-cua-skill: resuelve --api-key, luego AP_CUA_AGENTPLAN_API_KEY, AGENTPLAN_API_KEY o ARK_API_KEY, luego usa el prompt oculto de la terminal local cuando no haya clave disponible. Valida y almacena las credenciales exitosas en la caché local con permisos 0600.
• Nunca expongas claves de API, contenido de la caché, encabezados de autorización, respuestas del usuario ni bytes de artefactos.
• Nunca infieras la finalización a partir de texto de progreso o un estado no terminal.
• Trata result.text como autoritativo solo cuando outcome == completed.
• Rechaza sobrescribir archivos locales existentes. Exige una nueva ruta de salida para artifact save.
• Rechaza respuestas HTML/intersticiales como artefactos y no las escribas en el disco.
• No aceptes texto en base64 ni un enlace de uso compartido externo como archivo descargado; requiere un artefacto registrado.
• No omitas preguntas de CUA, modifiques configuraciones persistentes del modelo, administres horarios, expongas tickets de acceso al escritorio ni invoques operaciones de reinicio/reinicialización del escritorio.