ARK CUA

O que ARK CUA faz?

Opere o ARK CUA através da CLI Python empacotada. Mantenha todo o acesso ao gateway dentro da CLI e nunca solicite uma chave de API AgentPlan no chat.

Superfície de comandos

python3 <skill-dir>/scripts/cua.py <comando> [opções]

Analise o único objeto JSON impresso por cada invocação:

• Sucesso: ok: true, com data e às vezes next.
• Falha: ok: false, com error.code e às vezes next.setup_command.

Leia references/commands.md para comandos não essenciais. Leia references/auth.md, references/outcomes.md ou references/troubleshooting.md apenas quando o estado correspondente ocorrer.

Fluxo de trabalho principal

1. Execute auth status.
2. Em AUTH_REQUIRED, TOKEN_EXPIRED ou REFRESH_FAILED, repasse o setup_command retornado. Peça ao usuário para executá-lo em seu próprio terminal local e inserir a chave de API AgentPlan através do prompt oculto. Nunca execute o login interativo a partir de uma sessão de agente e nunca aceite a chave no chat.
3. Após o usuário confirmar que o login foi concluído, execute auth status novamente.
4. Execute delegate --objective "<solicitação do usuário>" uma vez. Preserve o objetivo do usuário sem planejá-lo ou decompor.
5. Registre data.invocation_id; nunca envie a mesma solicitação novamente.
6. Conduza data.outcome até o estado terminal:
   • in_progress: execute next.command e continue monitorando.
   • needs_input: repasse data.input_request.question literalmente e, em seguida, envie a resposta do usuário com answer.
   • completed: use data.result.text como o resultado autoritativo.
   • failed: relate a falha; repita apenas quando solicitado e seguro.
   • cancelled: relate o cancelamento.

Se a criação da tarefa retornar ACTIVE_RUN_CONFLICT, a nova solicitação não foi iniciada. Pare, informe ao usuário que o desktop está ocupado e não repita nem inspecione a tarefa existente, a menos que o usuário peça explicitamente.

Rotear intenções especiais

• Desktop específico ou contexto reutilizável: use desktop list, task run, context e task continue.
• Entrega de arquivo local: remova apenas a redação de entrega local do objetivo CUA, faça o CUA exportar um artefato registrado e, em seguida, use artifact list e artifact save.
• Inspeção de saúde ou configuração: use ping, diagnose ou model get; não crie uma tarefa apenas para testar a disponibilidade.
• Parar uma tarefa ativa: use cancel apenas quando o usuário pedir explicitamente.

Segurança e integridade dos resultados

• Use o gateway empacotado em assets/config.json; permita as mesmas substituições por chamada e ambiente que ap-cua-skill.
• Configure as credenciais exatamente como ap-cua-skill: resolva --api-key, depois AP_CUA_AGENTPLAN_API_KEY, AGENTPLAN_API_KEY ou ARK_API_KEY e, em seguida, use o prompt oculto do terminal local quando nenhuma chave estiver disponível de outra forma. Valide e armazene as credenciais bem-sucedidas no cache local 0600.
• Nunca exponha chaves de API, conteúdo do cache, cabeçalhos de autorização, respostas do usuário ou bytes de artefatos.
• Nunca infira conclusão a partir de texto de progresso ou de um estado não terminal.
• Trate result.text como autoritativo apenas quando outcome == completed.
• Recuse-se a sobrescrever arquivos locais existentes. Exija um novo caminho de saída para artifact save.
• Rejeite respostas HTML/intersticiais como artefatos e não as escreva no disco.
• Não aceite texto base64 ou um link de compartilhamento externo como um arquivo baixado; exija um artefato registrado.
• Não ignore perguntas do CUA, modifique configurações persistentes do modelo, gerencie agendamentos, exponha tickets de acesso ao desktop ou invoque operações de reinicialização/restauração do desktop.