agent-devkit 0.1.5 → 0.2.0

package/runtime/agents/pyautogui-automation-builder/AGENTS.md

@@ -0,0 +1,32 @@
+# PyAutoGUI Automation Builder
+
+Instrucoes locais para trabalhar no agente `pyautogui-automation-builder`.
+
+## Responsabilidade
+
+Este agente planeja, gera e revisa automacoes desktop com PyAutoGUI apenas
+quando nao houver API, CLI, MCP, automacao web ou automacao nativa mais segura
+disponivel. PyAutoGUI e tratado como ultimo recurso porque opera diretamente na
+interface grafica.
+
+## Fora De Escopo
+
+- Automacoes Python gerais: pertencem ao `python-automation-builder`.
+- Selenium/WebDriver: pertence ao `selenium-automation-builder`.
+- Playwright moderno e validacao visual rica: problema 27.
+- OCR/framework visual completo.
+- Execucao real de automacao desktop durante geracao.
+- Rodar PyAutoGUI em ambiente headless sem suporte grafico.
+
+## Guardrails
+
+- Exigir revisao de alternativas mais seguras antes de gerar.
+- Exigir aceite explicito de risco visual.
+- Bloquear operacoes destrutivas por padrao.
+- Gerar dry-run por padrao.
+- Exigir `--execute --confirm` para qualquer acao real.
+- Manter `pyautogui.FAILSAFE = True`.
+- Capturar screenshots antes/depois/erro.
+- Validar janela/tela esperada quando possivel.
+- Evitar coordenadas absolutas puras salvo ultimo recurso justificado.
+- Nao gravar senhas, tokens ou credenciais em codigo, logs ou screenshots.

package/runtime/agents/pyautogui-automation-builder/README.md

@@ -0,0 +1,44 @@
+# PyAutoGUI Automation Builder
+
+Agente especialista para automacoes desktop visuais com PyAutoGUI, usadas como
+ultimo recurso quando API, CLI, MCP, Playwright, Selenium ou automacao nativa do
+sistema operacional nao resolvem a tarefa.
+
+## Capabilities
+
+- `plan-desktop-automation`: planeja automacao desktop sem escrever arquivos.
+- `generate-pyautogui-script`: gera script PyAutoGUI em modo output-only.
+- `generate-pyautogui-project-files`: planeja ou escreve pacote local de
+  automacao.
+- `review-pyautogui-script`: revisa guardrails de um script PyAutoGUI.
+- `wrap-pyautogui-as-capability`: empacota automacao aprovada como capability.
+
+## Contrato De Entrada
+
+Specs YAML/JSON devem informar:
+
+- `automation_name`
+- `purpose`
+- `target_app`
+- `target_window`
+- `platform`
+- `steps`
+- `screen_preconditions`
+- `verification_strategy`
+- `safer_alternatives_checked`
+- `user_accepts_visual_risk`
+- `side_effects`
+- `coordinates_policy`
+
+## Exemplo
+
+```bash
+./agent --json run pyautogui-automation-builder plan-desktop-automation \
+  --spec desktop-spec.yaml
+```
+
+## Politica
+
+Scripts gerados nao executam a automacao por padrao. A execucao real exige
+`--execute --confirm`, screenshots e validacao visual basica. Operacoes
+destrutivas sao bloqueadas no planejamento.

package/runtime/agents/pyautogui-automation-builder/agent.yaml

@@ -0,0 +1,45 @@
+id: pyautogui-automation-builder
+kind: specialist-agent
+name: PyAutoGUI Automation Builder
+version: 0.1.0
+status: draft
+owner: agent-devkit
+purpose: >
+  Planejar, gerar, revisar e empacotar automacoes desktop com PyAutoGUI como
+  ultimo recurso, com dry-run, confirmacao forte, screenshots e failsafe.
+default_context:
+  - knowledge/system.md
+  - knowledge/context.md
+  - knowledge/policies.yaml
+env:
+  required: []
+  optional: []
+capabilities:
+  - plan-desktop-automation
+  - generate-pyautogui-script
+  - generate-pyautogui-project-files
+  - review-pyautogui-script
+  - wrap-pyautogui-as-capability
+agent_surface:
+  repositories:
+    - infra/integrations/pyautogui-automation/pyautogui_automation_repository.py
+  policies:
+    - knowledge/policies.yaml
+write_policy:
+  planning: read_only
+  generation: output_only
+  project_files: local_write
+  review: read_only
+  capability_wrapper: local_write
+  external_side_effects: blocked_by_default
+routing:
+  anchors:
+    - pyautogui-automation-builder
+    - pyautogui
+    - desktop-automation
+    - automacao-desktop
+  intents:
+    - desktop-automation.plan
+    - pyautogui.generate
+    - pyautogui.review
+  priority: 50

package/runtime/agents/pyautogui-automation-builder/capabilities/generate-pyautogui-project-files/capability.yaml

@@ -0,0 +1,20 @@
+id: pyautogui-automation-builder.generate-pyautogui-project-files
+kind: capability
+name: Generate PyAutoGUI Project Files
+version: 0.1.0
+status: draft
+purpose: Planejar ou escrever pacote local de automacao PyAutoGUI.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  output_template: ../../templates/pyautogui-readme.md
+inputs:
+  required:
+    - spec
+  optional:
+    - execute
+    - allow-overwrite
+outputs:
+  artifacts:
+    - pyautogui-project-files.json
+write_policy: local_write

package/runtime/agents/pyautogui-automation-builder/capabilities/generate-pyautogui-project-files/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Escrita local exige projeto alvo existente.
+- Caminhos absolutos ou fora do projeto sao bloqueados.
+- Overwrite exige permissao explicita.
+- Nunca executar a automacao desktop gerada durante a escrita dos arquivos.

package/runtime/agents/pyautogui-automation-builder/capabilities/generate-pyautogui-project-files/runner.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""Runner for pyautogui-automation-builder/generate-pyautogui-project-files."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "pyautogui-automation"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from pyautogui_automation_repository import PyAutoGUIAutomationError, PyAutoGUIAutomationRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate PyAutoGUI automation project files")
+    parser.add_argument("--spec", required=True)
+    parser.add_argument("--execute", action="store_true")
+    parser.add_argument("--allow-overwrite", action="store_true")
+    args = parser.parse_args()
+
+    try:
+        result = PyAutoGUIAutomationRepository().generate_pyautogui_project_files(
+            spec_path=Path(args.spec),
+            execute=args.execute,
+            allow_overwrite=args.allow_overwrite,
+        )
+    except PyAutoGUIAutomationError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/agents/pyautogui-automation-builder/capabilities/generate-pyautogui-project-files/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Validar spec com `plan-desktop-automation`.
+2. Exigir `target_project` para escrita.
+3. Em dry-run, retornar arquivos planejados sem escrever.
+4. Com `--execute`, escrever somente dentro de `target_project`.
+5. Bloquear overwrite sem `--allow-overwrite`.

package/runtime/agents/pyautogui-automation-builder/capabilities/generate-pyautogui-script/capability.yaml

@@ -0,0 +1,18 @@
+id: pyautogui-automation-builder.generate-pyautogui-script
+kind: capability
+name: Generate PyAutoGUI Script
+version: 0.1.0
+status: draft
+purpose: Gerar script Python PyAutoGUI em modo output-only.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  output_template: ../../templates/pyautogui-automation.py
+inputs:
+  required:
+    - spec
+  optional: []
+outputs:
+  artifacts:
+    - pyautogui_automation.py
+write_policy: output_only

package/runtime/agents/pyautogui-automation-builder/capabilities/generate-pyautogui-script/decision-rules.md

@@ -0,0 +1,7 @@
+# Decision Rules
+
+- Nao importar PyAutoGUI no caminho de dry-run.
+- Script deve conter `pyautogui.FAILSAFE = True`.
+- Script deve capturar screenshot antes/depois/erro.
+- Script deve validar janela/tela esperada quando possivel.
+- Script deve retornar exit codes previsiveis.

package/runtime/agents/pyautogui-automation-builder/capabilities/generate-pyautogui-script/runner.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""Runner for pyautogui-automation-builder/generate-pyautogui-script."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "pyautogui-automation"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from pyautogui_automation_repository import PyAutoGUIAutomationError, PyAutoGUIAutomationRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate a PyAutoGUI Python script")
+    parser.add_argument("--spec", required=True)
+    args = parser.parse_args()
+
+    try:
+        result = PyAutoGUIAutomationRepository().generate_pyautogui_script(spec_path=Path(args.spec))
+    except PyAutoGUIAutomationError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/agents/pyautogui-automation-builder/capabilities/generate-pyautogui-script/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Reutilizar o planejamento da spec.
+2. Gerar script sem escrever arquivo local.
+3. Manter dry-run como comportamento padrao.
+4. Exigir `--execute --confirm` para acao real.
+5. Incluir screenshots, failsafe, abort file, timeout e logs.

package/runtime/agents/pyautogui-automation-builder/capabilities/plan-desktop-automation/capability.yaml

@@ -0,0 +1,18 @@
+id: pyautogui-automation-builder.plan-desktop-automation
+kind: capability
+name: Plan Desktop Automation
+version: 0.1.0
+status: draft
+purpose: Planejar automacao desktop PyAutoGUI sem escrever arquivos.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  output_template: ../../templates/pyautogui-readme.md
+inputs:
+  required:
+    - spec
+  optional: []
+outputs:
+  artifacts:
+    - desktop-automation-plan.json
+write_policy: read_only

package/runtime/agents/pyautogui-automation-builder/capabilities/plan-desktop-automation/decision-rules.md

@@ -0,0 +1,8 @@
+# Decision Rules
+
+- PyAutoGUI e ultimo recurso.
+- Exigir `user_accepts_visual_risk: true`.
+- Bloquear `side_effects: destructive`.
+- Bloquear specs com segredo hardcoded.
+- Preferir reconhecimento por janela, regiao ou imagem a coordenadas absolutas.
+- Nao escrever arquivos nesta capability.

package/runtime/agents/pyautogui-automation-builder/capabilities/plan-desktop-automation/runner.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""Runner for pyautogui-automation-builder/plan-desktop-automation."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "pyautogui-automation"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from pyautogui_automation_repository import PyAutoGUIAutomationError, PyAutoGUIAutomationRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Plan a PyAutoGUI desktop automation")
+    parser.add_argument("--spec", required=True)
+    args = parser.parse_args()
+
+    try:
+        result = PyAutoGUIAutomationRepository().plan_desktop_automation(spec_path=Path(args.spec))
+    except PyAutoGUIAutomationError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/agents/pyautogui-automation-builder/capabilities/plan-desktop-automation/workflow.md

@@ -0,0 +1,9 @@
+# Workflow
+
+1. Carregar spec YAML/JSON.
+2. Validar alvo desktop, janela, passos, pre-condicoes e estrategia de
+   verificacao.
+3. Confirmar que alternativas mais seguras foram avaliadas.
+4. Bloquear quando existir API, CLI, MCP, Playwright, Selenium ou automacao
+   nativa aplicavel.
+5. Retornar plano read-only com riscos, guardrails e artefatos previstos.

package/runtime/agents/pyautogui-automation-builder/capabilities/review-pyautogui-script/capability.yaml

@@ -0,0 +1,20 @@
+id: pyautogui-automation-builder.review-pyautogui-script
+kind: capability
+name: Review PyAutoGUI Script
+version: 0.1.0
+status: draft
+purpose: Revisar script PyAutoGUI contra risco visual, failsafe e confirmacao.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  output_template: ../../templates/pyautogui-review-report.md
+inputs:
+  required: []
+  optional:
+    - input
+    - text
+    - side-effects
+outputs:
+  artifacts:
+    - pyautogui-review.json
+write_policy: read_only

package/runtime/agents/pyautogui-automation-builder/capabilities/review-pyautogui-script/decision-rules.md

@@ -0,0 +1,8 @@
+# Decision Rules
+
+- Script sem `pyautogui.FAILSAFE = True` falha na revisao.
+- Script com side effects precisa de `--execute` e `--confirm`.
+- Script deve expor `--dry-run`, `--screenshot-dir`, `--timeout` e
+  `--abort-file`.
+- Script deve capturar screenshot antes/depois/erro.
+- Coordenadas absolutas sem regiao/validacao devem gerar finding.

package/runtime/agents/pyautogui-automation-builder/capabilities/review-pyautogui-script/runner.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""Runner for pyautogui-automation-builder/review-pyautogui-script."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "pyautogui-automation"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from pyautogui_automation_repository import PyAutoGUIAutomationError, PyAutoGUIAutomationRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Review a PyAutoGUI automation script")
+    parser.add_argument("--input")
+    parser.add_argument("--text")
+    parser.add_argument("--side-effects", default="navigation")
+    args = parser.parse_args()
+
+    if not args.input and not args.text:
+        print("one of --input or --text is required", file=sys.stderr)
+        return 2
+
+    try:
+        text = Path(args.input).read_text(encoding="utf-8") if args.input else str(args.text)
+        result = PyAutoGUIAutomationRepository().review_pyautogui_script(
+            text=text,
+            side_effects=args.side_effects,
+        )
+    except (PyAutoGUIAutomationError, OSError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/agents/pyautogui-automation-builder/capabilities/review-pyautogui-script/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Ler script informado por `--input` ou `--text`.
+2. Verificar failsafe, dry-run, confirmacao, screenshots e abort.
+3. Apontar uso inseguro de coordenadas absolutas, segredo hardcoded ou falta de
+   validacao visual.
+4. Retornar JSON read-only com findings.

package/runtime/agents/pyautogui-automation-builder/capabilities/wrap-pyautogui-as-capability/capability.yaml

@@ -0,0 +1,22 @@
+id: pyautogui-automation-builder.wrap-pyautogui-as-capability
+kind: capability
+name: Wrap PyAutoGUI As Capability
+version: 0.1.0
+status: draft
+purpose: Planejar ou escrever wrapper de capability para automacao PyAutoGUI aprovada.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  output_template: ../../templates/capability-wrapper.md
+inputs:
+  required:
+    - spec
+    - agent-id
+    - capability-id
+  optional:
+    - execute
+    - allow-overwrite
+outputs:
+  artifacts:
+    - pyautogui-capability-wrapper-files.json
+write_policy: local_write

package/runtime/agents/pyautogui-automation-builder/capabilities/wrap-pyautogui-as-capability/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Capability gerada deve preservar dry-run por padrao.
+- Capability com side effects deve usar `confirm`.
+- Operacoes destrutivas continuam `blocked_by_default`.
+- Runner gerado nao deve executar PyAutoGUI no import.

package/runtime/agents/pyautogui-automation-builder/capabilities/wrap-pyautogui-as-capability/runner.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""Runner for pyautogui-automation-builder/wrap-pyautogui-as-capability."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "pyautogui-automation"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from pyautogui_automation_repository import PyAutoGUIAutomationError, PyAutoGUIAutomationRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Wrap a PyAutoGUI automation as an Agent DevKit capability")
+    parser.add_argument("--spec", required=True)
+    parser.add_argument("--agent-id", required=True)
+    parser.add_argument("--capability-id", required=True)
+    parser.add_argument("--execute", action="store_true")
+    parser.add_argument("--allow-overwrite", action="store_true")
+    args = parser.parse_args()
+
+    try:
+        result = PyAutoGUIAutomationRepository().wrap_pyautogui_as_capability(
+            spec_path=Path(args.spec),
+            agent_id=args.agent_id,
+            capability_id=args.capability_id,
+            execute=args.execute,
+            allow_overwrite=args.allow_overwrite,
+        )
+    except PyAutoGUIAutomationError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/agents/pyautogui-automation-builder/capabilities/wrap-pyautogui-as-capability/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Validar spec com planejamento PyAutoGUI.
+2. Validar `agent-id` e `capability-id` em kebab-case.
+3. Exigir `target_project`.
+4. Em dry-run, retornar arquivos planejados.
+5. Com `--execute`, escrever capability apenas dentro do projeto alvo.