agent-devkit 0.1.5 → 0.2.0

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

@@ -0,0 +1,15 @@
+# Context
+
+Automacoes Python no Agent DevKit existem para poupar contexto de LLM em tarefas
+conhecidas e repetitivas. Elas devem ser pequenas, auditaveis e facilmente
+convertidas em capabilities quando se tornam parte do produto.
+
+Classificacao de idempotencia:
+
+- `safe-repeat`: pode rodar varias vezes sem novo efeito colateral.
+- `creates-artifact`: cria arquivo novo ou versionado.
+- `updates-local`: altera estado local.
+- `external-write`: altera sistema externo.
+- `destructive`: apaga ou sobrescreve dados.
+
+Essa classificacao orienta dry-run, confirmacao e `write_policy`.

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

@@ -0,0 +1,12 @@
+policies:
+  supported_scope: python-general-automation
+  out_of_scope_dependencies:
+    selenium: problem 16
+    pyautogui: problem 17
+    playwright: problem 27
+  default_write_mode: dry_run
+  external_side_effects: blocked_by_default
+  secrets: never_persist
+  target_project_boundary: required_for_writes
+  overwrite: blocked_without_explicit_permission
+  dependency_preference: standard_library_first

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

@@ -0,0 +1,19 @@
+# System
+
+Voce e o `python-automation-builder`, especialista em automacoes Python
+deterministicas.
+
+Seu trabalho e transformar uma tarefa repetitiva em um artefato executavel,
+seguro e revisavel. Toda automacao deve ter contrato de entrada/saida,
+`--dry-run`, confirmacao para side effects, logs claros, exit codes previsiveis
+e ausencia de segredo hardcoded.
+
+## Regras Principais
+
+- Planeje antes de gerar codigo.
+- Prefira standard library.
+- Bloqueie segredo, token, URL privada e dependencia fora do escopo deste
+  agente.
+- Nao gere Selenium, PyAutoGUI ou Playwright aqui.
+- Nao execute a automacao gerada.
+- Nao escreva fora do `target_project`.

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

@@ -0,0 +1,13 @@
+# Automation README
+
+## Uso
+
+```bash
+python automation.py --dry-run
+```
+
+## Guardrails
+
+- Sem segredo hardcoded.
+- Dry-run por padrao.
+- Escrita real exige confirmacao.

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

@@ -0,0 +1,13 @@
+# Python Automation Review
+
+## Resultado
+
+- Status:
+
+## Findings
+
+-
+
+## Riscos
+
+-

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

@@ -0,0 +1,9 @@
+import subprocess
+import sys
+from pathlib import Path
+
+
+def test_automation_dry_run():
+    script = Path(__file__).resolve().parents[1] / "automation.py"
+    result = subprocess.run([sys.executable, str(script), "--dry-run"], text=True, capture_output=True)
+    assert result.returncode == 0

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

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+"""Generated Python automation template."""
+
+import argparse
+import logging
+import sys
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--dry-run", action="store_true", default=True)
+    args = parser.parse_args()
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")
+    logging.info("dry_run=%s", args.dry_run)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,4 @@
+# Capability Wrapper
+
+Arquivos planejados para empacotar uma automacao Python como capability do
+Agent DevKit.

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

@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+"""Tests for the Python 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" / "python-automation-builder"
+REPOSITORY_PATH = AGENT_DIR / "infra" / "integrations" / "python-automation" / "python_automation_repository.py"
+
+
+def load_repository_module():
+    spec = importlib.util.spec_from_file_location("python_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 PythonAutomationBuilderRunnersTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.repository_module = load_repository_module()
+
+    def write_spec(
+        self,
+        root: Path,
+        *,
+        automation_name: str = "Report Cleanup",
+        target_project: Path | None = None,
+        dependencies: list[str] | None = None,
+        side_effects: str = "updates-local",
+        purpose: str = "Clean old generated reports and summarize the affected files.",
+        systems: str = "local filesystem",
+    ) -> Path:
+        path = root / "automation-spec.yaml"
+        target_project_line = f"target_project: {target_project}\n" if target_project else ""
+        dependency_lines = "\n".join(f"  - {item}" for item in (dependencies or []))
+        if not dependency_lines:
+            dependency_lines = "  - pathlib"
+        path.write_text(
+            f"""
+automation_name: {automation_name}
+{target_project_line}purpose: {purpose}
+inputs:
+  - reports_dir
+outputs:
+  - summary_json
+systems:
+  - {systems}
+frequency: daily
+risk: medium
+target_environment: local workstation
+side_effects: {side_effects}
+dependencies:
+{dependency_lines}
+quality_gates:
+  - dry-run lists affected paths
+  - exit codes are predictable
+""".lstrip(),
+            encoding="utf-8",
+        )
+        return path
+
+    def test_plan_python_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.PythonAutomationRepository(root=root)
+
+            result = repository.plan_python_automation(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "ok")
+            self.assertEqual(result["automation"]["slug"], "report-cleanup")
+            self.assertEqual(result["idempotency"], "updates-local")
+            self.assertEqual(result["write_policy"], "read_only")
+            planned_paths = {item["path"] for item in result["planned_artifacts"]}
+            self.assertIn("automation.py", planned_paths)
+            self.assertFalse((root / "automation.py").exists())
+
+    def test_plan_python_automation_reports_needs_input(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = root / "automation-spec.yaml"
+            spec_path.write_text("automation_name: incomplete\n", encoding="utf-8")
+            repository = self.repository_module.PythonAutomationRepository(root=root)
+
+            result = repository.plan_python_automation(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "needs-input")
+            self.assertGreaterEqual(
+                set(result["missing_fields"]),
+                {"purpose", "inputs", "outputs", "systems", "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="Use API_KEY=abc to call the service.")
+            repository = self.repository_module.PythonAutomationRepository(root=root)
+
+            result = repository.plan_python_automation(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "blocked")
+            self.assertEqual(result["reason"], "forbidden_sensitive_marker")
+
+    def test_plan_routes_browser_desktop_dependencies_out_of_scope(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root, dependencies=["selenium"])
+            repository = self.repository_module.PythonAutomationRepository(root=root)
+
+            result = repository.plan_python_automation(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "blocked")
+            self.assertEqual(result["reason"], "out_of_scope_dependency")
+            self.assertIn("problem 16", " ".join(result["next_steps"]).lower())
+
+    def test_generate_python_automation_returns_script_without_writing(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            repository = self.repository_module.PythonAutomationRepository(root=root)
+
+            result = repository.generate_python_automation(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "ok")
+            content = result["content"]
+            self.assertIn("argparse", content)
+            self.assertIn("--dry-run", content)
+            self.assertIn("--execute", content)
+            self.assertIn("--yes", content)
+            self.assertIn("redact", content)
+            self.assertIn("return 0", content)
+            self.assertFalse((root / "automation.py").exists())
+
+    def test_generate_automation_project_files_dry_run_does_not_write(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.PythonAutomationRepository(root=root)
+
+            result = repository.generate_automation_project_files(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "planned")
+            self.assertTrue(result["dry_run"])
+            planned_paths = {item["path"] for item in result["planned_files"]}
+            self.assertGreaterEqual(
+                planned_paths,
+                {
+                    "report-cleanup/automation.py",
+                    "report-cleanup/README.md",
+                    "report-cleanup/tests/test_automation.py",
+                },
+            )
+            self.assertFalse((target_project / "report-cleanup").exists())
+
+    def test_generate_automation_project_files_execute_writes_inside_target_project(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.PythonAutomationRepository(root=root)
+
+            result = repository.generate_automation_project_files(spec_path=spec_path, execute=True)
+
+            self.assertEqual(result["status"], "written")
+            self.assertTrue((target_project / "report-cleanup" / "automation.py").exists())
+            for item in result["written_files"]:
+                path = Path(item["path"]).resolve()
+                self.assertTrue(path.is_relative_to(target_project.resolve()), item["path"])
+
+    def test_generate_automation_project_files_blocks_overwrite_without_permission(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.PythonAutomationRepository(root=root)
+            repository.generate_automation_project_files(spec_path=spec_path, execute=True)
+
+            result = repository.generate_automation_project_files(spec_path=spec_path, execute=True)
+
+            self.assertEqual(result["status"], "blocked")
+            self.assertEqual(result["reason"], "target_exists")
+
+    def test_review_python_automation_detects_missing_dry_run(self) -> None:
+        repository = self.repository_module.PythonAutomationRepository(root=ROOT)
+
+        result = repository.review_python_automation(text="print('hello')", side_effects="updates-local")
+
+        self.assertFalse(result["valid"])
+        self.assertEqual(result["status"], "failed")
+        self.assertTrue(any("dry-run" in finding.lower() for finding in result["findings"]))
+
+    def test_review_python_automation_accepts_generated_script(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            repository = self.repository_module.PythonAutomationRepository(root=root)
+            script = repository.generate_python_automation(spec_path=spec_path)["content"]
+
+            result = repository.review_python_automation(text=script, side_effects="updates-local")
+
+            self.assertTrue(result["valid"], result["findings"])
+            self.assertEqual(result["findings"], [])
+
+    def test_wrap_automation_as_capability_dry_run_does_not_write(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.PythonAutomationRepository(root=root)
+
+            result = repository.wrap_automation_as_capability(
+                spec_path=spec_path,
+                agent_id="operations-agent",
+                capability_id="report-cleanup",
+            )
+
+            self.assertEqual(result["status"], "planned")
+            self.assertTrue(result["dry_run"])
+            planned_paths = {item["path"] for item in result["planned_files"]}
+            self.assertIn("agents/operations-agent/capabilities/report-cleanup/runner.py", planned_paths)
+            self.assertFalse((target_project / "agents").exists())
+
+    def test_wrap_automation_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.PythonAutomationRepository(root=root)
+
+            result = repository.wrap_automation_as_capability(
+                spec_path=spec_path,
+                agent_id="operations-agent",
+                capability_id="report-cleanup",
+                execute=True,
+            )
+
+            self.assertEqual(result["status"], "written")
+            runner = target_project / "agents" / "operations-agent" / "capabilities" / "report-cleanup" / "runner.py"
+            self.assertTrue(runner.exists())
+            py_compile.compile(str(runner), doraise=True)
+
+    def test_plan_python_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",
+                    "python-automation-builder",
+                    "plan-python-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"], "report-cleanup")
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,27 @@
+# Selenium Automation Builder
+
+Instrucoes locais para trabalhar no agente `selenium-automation-builder`.
+
+## Responsabilidade
+
+Este agente planeja, gera e revisa automacoes Selenium/WebDriver quando houver
+motivo tecnico para preferir Selenium a Playwright: legado, Selenium Grid,
+browser remoto corporativo, requisito WebDriver, extensoes de browser ou padrao
+de equipe existente.
+
+## Fora De Escopo
+
+- Playwright moderno e validacao visual rica: problema 27.
+- Automacao desktop com PyAutoGUI: problema 17.
+- Criar Selenium Grid ou instalar browsers/drivers.
+- Executar automacao real em browser durante geracao.
+
+## Guardrails
+
+- Exigir justificativa explicita para Selenium.
+- Usar waits explicitos com `WebDriverWait`.
+- Evitar `time.sleep` como mecanismo principal.
+- Gerar dry-run por padrao para side effects.
+- Exigir confirmacao para submissao, escrita externa ou acao destrutiva.
+- Capturar screenshot em falha.
+- Nao hardcodar credenciais.

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

@@ -0,0 +1,40 @@
+# Selenium Automation Builder
+
+Agente especialista para automacoes Selenium/WebDriver seguras e revisaveis.
+
+## Capabilities
+
+- `plan-selenium-automation`: planeja automacao Selenium sem escrever arquivos.
+- `generate-selenium-script`: gera script Python Selenium em modo output-only.
+- `generate-selenium-project-files`: planeja ou grava pacote local com dry-run
+  por padrao.
+- `review-selenium-script`: revisa waits, seletores, screenshots, timeouts,
+  credenciais e side effects.
+- `wrap-selenium-as-capability`: gera wrapper de capability em dry-run por
+  padrao.
+
+## Contrato
+
+```yaml
+automation_name: Legacy Login Check
+purpose: Check a legacy login page through WebDriver-compatible browser automation.
+target_url: https://example.test/login
+browser: chrome
+remote_url_env: SELENIUM_REMOTE_URL
+auth_strategy: env
+side_effects: read-only
+selenium_reasons:
+  - webdriver-required
+selectors:
+  - name: username
+    by: css
+    value: '[name="username"]'
+steps:
+  - open target_url
+  - wait for username
+```
+
+## Limites
+
+Este agente nao instala Selenium, browsers ou drivers. Ele gera artefatos
+revisaveis e scripts que fazem dry-run sem abrir browser.

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

@@ -0,0 +1,45 @@
+id: selenium-automation-builder
+kind: specialist-agent
+name: Selenium Automation Builder
+version: 0.1.0
+status: draft
+owner: agent-devkit
+purpose: >
+  Planejar, gerar, revisar e empacotar automacoes Selenium/WebDriver quando
+  houver requisito tecnico para usar Selenium em vez de Playwright.
+default_context:
+  - knowledge/system.md
+  - knowledge/context.md
+  - knowledge/policies.yaml
+env:
+  required: []
+  optional: []
+capabilities:
+  - plan-selenium-automation
+  - generate-selenium-script
+  - generate-selenium-project-files
+  - review-selenium-script
+  - wrap-selenium-as-capability
+agent_surface:
+  repositories:
+    - infra/integrations/selenium-automation/selenium_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:
+    - selenium-automation-builder
+    - selenium
+    - webdriver
+    - selenium-grid
+  intents:
+    - selenium-automation.plan
+    - selenium-automation.generate
+    - selenium-automation.review
+  priority: 50

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

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

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

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Nunca escrever fora de `target_project`.
+- Nao instalar Selenium ou drivers.
+- Incluir README, script, requirements e teste.
+- Sobrescrita exige permissao explicita.

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

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""Runner for selenium-automation-builder/generate-selenium-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" / "selenium-automation"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from selenium_automation_repository import SeleniumAutomationError, SeleniumAutomationRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate Selenium 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 = SeleniumAutomationRepository().generate_selenium_project_files(
+            spec_path=Path(args.spec),
+            execute=args.execute,
+            allow_overwrite=args.allow_overwrite,
+        )
+    except SeleniumAutomationError 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/selenium-automation-builder/capabilities/generate-selenium-project-files/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Ler e validar a spec.
+2. Exigir `target_project`.
+3. Retornar dry-run por padrao.
+4. Escrever apenas com `--execute` e confirmacao do runtime.
+5. Bloquear sobrescrita sem `--allow-overwrite`.

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

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

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

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Nao escrever em disco.
+- Nao usar `time.sleep` como espera principal.
+- Script deve compilar mesmo sem Selenium instalado.
+- Dry-run nao deve abrir browser.

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

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""Runner for selenium-automation-builder/generate-selenium-script."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "selenium-automation"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from selenium_automation_repository import SeleniumAutomationError, SeleniumAutomationRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate a Selenium Python script")
+    parser.add_argument("--spec", required=True)
+    args = parser.parse_args()
+
+    try:
+        result = SeleniumAutomationRepository().generate_selenium_script(spec_path=Path(args.spec))
+    except SeleniumAutomationError 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/selenium-automation-builder/capabilities/generate-selenium-script/workflow.md

@@ -0,0 +1,6 @@
+# Workflow
+
+1. Ler e validar a spec.
+2. Renderizar script com Selenium importado apenas na execucao real.
+3. Incluir dry-run, confirmacao, waits explicitos e screenshot em falha.
+4. Retornar script no stdout sem escrever arquivos.