agent-devkit 0.1.6 → 0.2.0

package/runtime/agents/playwright-automation-builder/knowledge/context.md

@@ -0,0 +1,19 @@
+# Contexto
+
+Playwright cobre automacao de navegador moderno, validacao visual, screenshots,
+traces, console logs e fluxos E2E locais.
+
+Use Playwright quando:
+
+- a tarefa e web;
+- nao ha API melhor;
+- nao ha requisito Selenium/Grid;
+- screenshots ou traces ajudam a validar o resultado;
+- seletores acessiveis existem ou podem ser definidos.
+
+Nao use Playwright para:
+
+- automacao desktop fora do navegador;
+- tarefas resolviveis por API/CLI sem browser;
+- Selenium Grid ou projetos legados WebDriver;
+- execucoes destrutivas sem ambiente controlado.

package/runtime/agents/playwright-automation-builder/knowledge/policies.yaml

@@ -0,0 +1,25 @@
+policies:
+  supported_scope: playwright-modern-web-automation
+  default_write_mode: dry_run
+  external_side_effects: blocked_by_default
+  secrets: never_persist
+  storage_state: never_commit_sensitive_state
+  target_project_boundary: required_for_writes
+  overwrite: blocked_without_explicit_permission
+  selector_preference:
+    - role
+    - label
+    - test_id
+    - text
+    - css
+  selector_avoid:
+    - absolute_xpath
+    - generated_class
+    - coordinates
+    - fixed_sleep
+  artifacts:
+    screenshots: supported
+    traces: supported
+    videos: optional
+    console_logs: supported
+  selenium_boundary: use_selenium_only_for_webdriver_legacy_or_grid

package/runtime/agents/playwright-automation-builder/knowledge/system.md

@@ -0,0 +1,19 @@
+# System
+
+Voce e o `playwright-automation-builder`, especialista em automacoes web
+modernas com Playwright.
+
+Seu papel e transformar uma necessidade web em contrato executavel,
+guardrails, script, artifacts e wrapper local revisavel. Use Playwright quando
+a tarefa for web e nao houver requisito tecnico para Selenium/WebDriver.
+
+## Regras
+
+1. Planeje antes de gerar script.
+2. Use dry-run por padrao.
+3. Exija `--execute` para abrir browser.
+4. Exija `--confirm` para side effects.
+5. Nao hardcode credenciais.
+6. Nao persistir storage state sensivel.
+7. Prefira seletores acessiveis e estaveis.
+8. Gere artifacts curtos, auditaveis e marcados como sensiveis quando aplicavel.

package/runtime/agents/playwright-automation-builder/templates/capability-wrapper.md

@@ -0,0 +1,4 @@
+# Capability Wrapper
+
+Use this template when wrapping a Playwright automation as an Agent DevKit
+capability.

package/runtime/agents/playwright-automation-builder/templates/playwright-automation.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+"""Generated Playwright automation template."""
+
+from __future__ import annotations
+
+
+def main() -> int:
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/agents/playwright-automation-builder/templates/playwright-readme.md

@@ -0,0 +1,13 @@
+# {{ automation_name }}
+
+{{ purpose }}
+
+## Usage
+
+```bash
+python playwright_automation.py --dry-run
+python playwright_automation.py --execute --headless
+```
+
+Use `--confirm` only after reviewing dry-run output when side effects are not
+read-only.

package/runtime/agents/playwright-automation-builder/templates/playwright-review-report.md

@@ -0,0 +1,9 @@
+# Playwright Review
+
+## Status
+
+{{ status }}
+
+## Findings
+
+{{ findings }}

package/runtime/agents/playwright-automation-builder/templates/playwright-test.py

@@ -0,0 +1,2 @@
+def test_playwright_automation_dry_run():
+    assert True

package/runtime/agents/playwright-automation-builder/tests/test_runners.py

@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+"""Tests for the Playwright Automation Builder runners."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import py_compile
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[3]
+AGENT = ROOT / "agent"
+AGENT_DIR = ROOT / "agents" / "playwright-automation-builder"
+REPOSITORY_PATH = AGENT_DIR / "infra" / "integrations" / "playwright-automation" / "playwright_automation_repository.py"
+
+
+def load_repository_module():
+    spec = importlib.util.spec_from_file_location("playwright_automation_repository", REPOSITORY_PATH)
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"cannot load repository from {REPOSITORY_PATH}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+class PlaywrightAutomationBuilderRunnersTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.repository_module = load_repository_module()
+
+    def write_spec(
+        self,
+        root: Path,
+        *,
+        automation_name: str = "Login Smoke Check",
+        target_project: Path | None = None,
+        side_effects: str = "read-only",
+        selector_kind: str = "role",
+        purpose: str = "Validate that a login page renders a submit button.",
+    ) -> Path:
+        path = root / "playwright-spec.yaml"
+        target_project_line = f"target_project: {target_project}\n" if target_project else ""
+        path.write_text(
+            f"""
+automation_name: {automation_name}
+{target_project_line}purpose: {purpose}
+target_url: https://example.test/login
+browser: chromium
+auth_strategy: none
+side_effects: {side_effects}
+selectors:
+  - name: submit
+    kind: {selector_kind}
+    value: button
+    name_value: Entrar
+steps:
+  - open target_url
+  - assert submit visible
+assertions:
+  - submit visible
+artifacts:
+  - screenshot
+  - trace
+  - report
+quality_gates:
+  - stable selectors are used
+""".lstrip(),
+            encoding="utf-8",
+        )
+        return path
+
+    def test_plan_playwright_automation_returns_plan_without_writing(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            repository = self.repository_module.PlaywrightAutomationRepository(root=root)
+
+            result = repository.plan_playwright_automation(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "ok")
+            self.assertEqual(result["automation"]["slug"], "login-smoke-check")
+            self.assertEqual(result["browser"], "chromium")
+            self.assertEqual(result["write_policy"], "read_only")
+            self.assertFalse((root / "playwright_automation.py").exists())
+            planned_paths = {item["path"] for item in result["planned_artifacts"]}
+            self.assertIn("playwright_automation.py", planned_paths)
+
+    def test_plan_reports_missing_fields(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = root / "playwright-spec.yaml"
+            spec_path.write_text("automation_name: incomplete\n", encoding="utf-8")
+            repository = self.repository_module.PlaywrightAutomationRepository(root=root)
+
+            result = repository.plan_playwright_automation(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "needs-input")
+            self.assertGreaterEqual(
+                set(result["missing_fields"]),
+                {"purpose", "browser", "selectors", "steps", "assertions", "auth_strategy", "side_effects"},
+            )
+
+    def test_plan_blocks_secret_marker(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root, purpose="Login with PASSWORD=abc in the page.")
+            repository = self.repository_module.PlaywrightAutomationRepository(root=root)
+
+            result = repository.plan_playwright_automation(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "blocked")
+            self.assertEqual(result["reason"], "forbidden_sensitive_marker")
+
+    def test_generate_playwright_script_contains_required_guardrails(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            repository = self.repository_module.PlaywrightAutomationRepository(root=root)
+
+            result = repository.generate_playwright_script(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "ok")
+            content = result["content"]
+            self.assertIn("sync_playwright", content)
+            self.assertIn("--dry-run", content)
+            self.assertIn("--execute", content)
+            self.assertIn("--headless", content)
+            self.assertIn("--browser", content)
+            self.assertIn("--screenshot-dir", content)
+            self.assertIn("--trace-dir", content)
+            self.assertIn("context.tracing.start", content)
+            py_compile.compile(str(self.write_temp_script(root, content)), doraise=True)
+
+    def test_generated_script_dry_run_does_not_import_playwright(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            repository = self.repository_module.PlaywrightAutomationRepository(root=root)
+            script_path = self.write_temp_script(root, repository.generate_playwright_script(spec_path=spec_path)["content"])
+
+            result = subprocess.run(
+                [sys.executable, str(script_path), "--dry-run"],
+                cwd=root,
+                check=False,
+                text=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                timeout=30,
+            )
+
+            self.assertEqual(result.returncode, 0, result.stderr)
+            payload = json.loads(result.stdout)
+            self.assertTrue(payload["dry_run"])
+            self.assertEqual(payload["plan"]["automation"], "login-smoke-check")
+
+    def test_generate_project_files_dry_run_and_execute(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            target_project = root / "target-project"
+            target_project.mkdir()
+            spec_path = self.write_spec(root, target_project=target_project)
+            repository = self.repository_module.PlaywrightAutomationRepository(root=root)
+
+            planned = repository.generate_playwright_project_files(spec_path=spec_path)
+            written = repository.generate_playwright_project_files(spec_path=spec_path, execute=True)
+
+            self.assertEqual(planned["status"], "planned")
+            self.assertTrue(planned["dry_run"])
+            self.assertEqual(written["status"], "written")
+            self.assertTrue((target_project / "login-smoke-check" / "playwright_automation.py").exists())
+
+    def test_run_playwright_check_is_plan_first_and_blocks_unconfirmed_side_effects(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            read_spec = self.write_spec(root)
+            submit_spec = self.write_spec(root, automation_name="Submit Form", side_effects="form-submit")
+            repository = self.repository_module.PlaywrightAutomationRepository(root=root)
+
+            planned = repository.run_playwright_check(spec_path=read_spec)
+            blocked = repository.run_playwright_check(spec_path=submit_spec, execute=True)
+
+            self.assertEqual(planned["status"], "planned")
+            self.assertTrue(planned["dry_run"])
+            self.assertEqual(blocked["status"], "blocked")
+            self.assertEqual(blocked["reason"], "confirmation_required")
+
+    def test_review_playwright_artifacts_detects_missing_and_accepts_generated_script(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            repository = self.repository_module.PlaywrightAutomationRepository(root=root)
+            script = repository.generate_playwright_script(spec_path=spec_path)["content"]
+
+            script_review = repository.review_playwright_artifacts(paths=[], text=script)
+            missing_review = repository.review_playwright_artifacts(paths=[root / "missing-trace.zip"])
+
+            self.assertTrue(script_review["valid"], script_review["findings"])
+            self.assertEqual(missing_review["status"], "failed")
+            self.assertTrue(any("missing" in finding for finding in missing_review["findings"]))
+
+    def test_wrap_playwright_as_capability_execute_writes_compilable_runner(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            target_project = root / "target-project"
+            target_project.mkdir()
+            spec_path = self.write_spec(root, target_project=target_project)
+            repository = self.repository_module.PlaywrightAutomationRepository(root=root)
+
+            result = repository.wrap_playwright_as_capability(
+                spec_path=spec_path,
+                agent_id="web-ops-agent",
+                capability_id="login-smoke-check",
+                execute=True,
+            )
+
+            self.assertEqual(result["status"], "written")
+            runner = target_project / "agents" / "web-ops-agent" / "capabilities" / "login-smoke-check" / "runner.py"
+            self.assertTrue(runner.exists())
+            py_compile.compile(str(runner), doraise=True)
+
+    def test_plan_playwright_automation_runner_is_executable_through_agent_cli(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            spec_path = self.write_spec(Path(tmpdir))
+
+            result = subprocess.run(
+                [
+                    sys.executable,
+                    str(AGENT),
+                    "--json",
+                    "run",
+                    "playwright-automation-builder",
+                    "plan-playwright-automation",
+                    "--spec",
+                    str(spec_path),
+                ],
+                cwd=ROOT,
+                check=False,
+                text=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                timeout=60,
+            )
+
+        self.assertEqual(result.returncode, 0, result.stderr or result.stdout)
+        payload = json.loads(result.stdout)
+        runner_payload = json.loads(payload["stdout"])
+        self.assertEqual(runner_payload["status"], "ok")
+        self.assertEqual(runner_payload["automation"]["slug"], "login-smoke-check")
+
+    def write_temp_script(self, root: Path, content: str) -> Path:
+        script = root / "playwright_automation.py"
+        script.write_text(content, encoding="utf-8")
+        return script
+
+
+if __name__ == "__main__":
+    unittest.main()

package/runtime/agents/postgres-data-analyzer/agent.yaml

@@ -88,5 +88,16 @@ agent_surface:
     - knowledge/policies.yaml
 
 write_policy:
-  read_operations: auto
-  write_operations: unsupported
+  read_operations: read_only
+  write_operations: blocked_by_default
+
+routing:
+  anchors:
+    - banco
+    - database
+    - postgres
+    - postgresql
+    - sql
+  intents:
+    - database.postgres.analysis
+  priority: 45

package/runtime/agents/presentation-deck-builder/agent.yaml

@@ -49,7 +49,18 @@ agent_surface:
     - ../../vendor/skills/CATALOG.md
 
 write_policy:
-  template_registration: ask_before_write
-  template_overwrite: prohibited_for_validated_versions
+  template_registration: confirm
+  template_overwrite: blocked_by_default
   deck_generation: output_only
-  external_side_effects: unsupported
+  external_side_effects: blocked_by_default
+
+routing:
+  anchors:
+    - apresentacao
+    - deck
+    - powerpoint
+    - presentation
+    - slides
+  intents:
+    - presentation.deck
+  priority: 50

package/runtime/agents/presentation-deck-builder/capabilities/create-template/capability.yaml

@@ -15,4 +15,4 @@ outputs:
 integration:
   repository: null
   methods: []
-write_policy: ask_before_write
+write_policy: confirm

package/runtime/agents/presentation-deck-builder/capabilities/create-template-version/capability.yaml

@@ -16,4 +16,4 @@ outputs:
 integration:
   repository: null
   methods: []
-write_policy: create_new_version
+write_policy: local_write

package/runtime/agents/presentation-deck-builder/capabilities/generate-template-input-file/capability.yaml

@@ -20,4 +20,4 @@ outputs:
 integration:
   repository: null
   methods: []
-write_policy: template_version_write
+write_policy: local_write

package/runtime/agents/presentation-deck-builder/capabilities/refine-template/capability.yaml

@@ -16,4 +16,4 @@ outputs:
 integration:
   repository: null
   methods: []
-write_policy: create_new_version
+write_policy: local_write

package/runtime/agents/presentation-deck-builder/capabilities/register-template/capability.yaml

@@ -25,4 +25,4 @@ outputs:
 integration:
   repository: null
   methods: []
-write_policy: ask_before_write
+write_policy: confirm

package/runtime/agents/presentation-deck-builder/knowledge/prompts/create-template.md

@@ -20,7 +20,7 @@ um template draft estruturado a partir de um brief.
 5. Marcar como `draft` — nunca `validated` automaticamente.
 
 ## RUBRICA / REGRAS DE DECISAO
-- `ask_before_write`: nao crie nenhum arquivo sem confirmacao.
+- `confirm`: nao crie nenhum arquivo sem confirmacao.
 - Nunca reutilize identidade visual de outro template sem pedido explicito.
 - Nunca marque como `validated` automaticamente.
 - Se brief for muito vago: perguntar ate ter informacao suficiente.

package/runtime/agents/presentation-deck-builder/knowledge/prompts/generate-template-input-file.md

@@ -19,7 +19,7 @@ de uma versao de template a partir do `slide-map.yaml`.
 
 ## RUBRICA / REGRAS DE DECISAO
 - Versao inexistente: erro imediato.
-- Regerar e idempotente (sobrescreve sem perguntar: write_policy template_version_write).
+- Regerar e idempotente (sobrescreve sem perguntar: write_policy local_write).
 
 ## SAIDA
 - "Input schema gerado: <path>/input-schema.xlsx"

package/runtime/agents/provider-configurator/agent.yaml

@@ -9,6 +9,9 @@ purpose: >
   Conduzir wizards agenticos de configuracao de providers e sources, coletando
   opt-in, campos de projeto e referencias seguras de credencial.
 
+runtime_role:
+  kind: provider-configurator
+
 default_context:
   - knowledge/system.md
   - knowledge/context.md
@@ -19,7 +22,6 @@ capabilities:
   - validate-provider-readiness
 
 write_policy:
-  config_writes: explicit_opt_in
-  stores_secret_values: never
-  default_mode: ask-first
-
+  config_writes: confirm
+  stores_secret_values: blocked_by_default
+  default_mode: confirm

package/runtime/agents/provider-configurator/capabilities/collect-provider-credentials/capability.yaml

@@ -4,7 +4,7 @@ name: Collect Provider Credentials
 version: 0.1.6
 status: draft
 purpose: Coletar referencias seguras para credenciais de provider.
-write_policy: local-config-write
+write_policy: local_config_write
 entrypoint:
   workflow: workflow.md
 inputs:
@@ -12,4 +12,3 @@ inputs:
   optional: [auth_method]
 outputs:
   artifacts: [credential-references]
-

package/runtime/agents/provider-configurator/capabilities/configure-provider-source/capability.yaml

@@ -4,7 +4,7 @@ name: Configure Provider Source
 version: 0.1.6
 status: draft
 purpose: Conduzir wizard para configurar uma source reutilizavel de provider.
-write_policy: local-config-write
+write_policy: local_config_write
 entrypoint:
   workflow: workflow.md
 inputs:
@@ -12,4 +12,3 @@ inputs:
   optional: [prompt, route, agent_id, capability_id, reason]
 outputs:
   artifacts: [source-config]
-

package/runtime/agents/provider-configurator/capabilities/validate-provider-readiness/capability.yaml

@@ -4,7 +4,7 @@ name: Validate Provider Readiness
 version: 0.1.6
 status: draft
 purpose: Validar se um provider ou source esta pronto para uso sem expor segredo.
-write_policy: read-only
+write_policy: read_only
 entrypoint:
   workflow: workflow.md
 inputs:
@@ -12,4 +12,3 @@ inputs:
   optional: [source_id]
 outputs:
   artifacts: [readiness-report]
-

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