agent-devkit 0.1.5 → 0.2.0

package/runtime/agents/execution-loop-builder/templates/loop-plan.md

@@ -0,0 +1,3 @@
+# Execution Loop Plan
+
+Plano de loop gerado para revisao antes de qualquer execucao.

package/runtime/agents/execution-loop-builder/templates/loop-readme.md

@@ -0,0 +1,3 @@
+# Execution Loop
+
+Instrucoes geradas para revisar e executar um loop local controlado.

package/runtime/agents/execution-loop-builder/templates/loop-review.md

@@ -0,0 +1,3 @@
+# Execution Loop Review
+
+Relatorio de seguranca e operacao do loop.

package/runtime/agents/execution-loop-builder/templates/loop-runner.py

@@ -0,0 +1,2 @@
+#!/usr/bin/env python3
+"""Generated execution loop runner."""

package/runtime/agents/execution-loop-builder/tests/test_runners.py

@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+"""Tests for the Execution Loop Builder runners."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+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" / "execution-loop-builder"
+REPOSITORY_PATH = (
+    AGENT_DIR
+    / "infra"
+    / "integrations"
+    / "execution-loop"
+    / "execution_loop_repository.py"
+)
+
+
+def load_repository_module():
+    spec = importlib.util.spec_from_file_location("execution_loop_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 ExecutionLoopBuilderRunnersTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.repository_module = load_repository_module()
+
+    def write_spec(
+        self,
+        root: Path,
+        *,
+        target_project: Path | None = None,
+        external_writes: bool = False,
+        dry_run_supported: bool = True,
+        idempotency_key: str = "",
+        command: str | None = None,
+        missing_budget: bool = False,
+    ) -> Path:
+        path = root / "loop-spec.yaml"
+        target_project_line = f"target_project: {target_project}\n" if target_project else ""
+        budget_block = "" if missing_budget else """
+budget:
+  max_iterations: 3
+  max_runtime_seconds: 120
+  max_llm_calls: 1
+"""
+        idempotency_line = f"  idempotency_key: {idempotency_key}\n" if idempotency_key else ""
+        step_block = (
+            f"  - id: cleanup\n    type: command\n    command: {json.dumps(command)}\n"
+            if command
+            else "  - id: list-prs\n    capability: github-pr-reviewer.list-review-requests\n"
+        )
+        path.write_text(
+            f"""
+id: daily-pr-review
+objective: Review pending PRs and produce a report.
+{target_project_line}trigger:
+  type: schedule
+  every: 30m
+{budget_block}side_effects:
+  external_writes: {str(external_writes).lower()}
+  dry_run_supported: {str(dry_run_supported).lower()}
+{idempotency_line}steps:
+{step_block}success_when:
+  - report_generated
+stop_when:
+  - no_items
+  - max_iterations_reached
+notify:
+  on: [failure, completion]
+  channels: [terminal]
+  max_per_run: 2
+""".lstrip(),
+            encoding="utf-8",
+        )
+        return path
+
+    def test_plan_execution_loop_returns_contract_without_writing(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            repository = self.repository_module.ExecutionLoopRepository(root=ROOT)
+
+            result = repository.plan_execution_loop(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "ok")
+            self.assertEqual(result["write_policy"], "read_only")
+            self.assertEqual(result["loop"]["id"], "daily-pr-review")
+            self.assertEqual(result["loop"]["max_iterations"], 3)
+            planned = {item["path"] for item in result["planned_artifacts"]}
+            self.assertIn("daily-pr-review/loop_runner.py", planned)
+            self.assertFalse((root / "daily-pr-review").exists())
+
+    def test_plan_reports_missing_required_budget(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root, missing_budget=True)
+            repository = self.repository_module.ExecutionLoopRepository(root=ROOT)
+
+            result = repository.plan_execution_loop(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "needs-input")
+            self.assertIn("budget", result["missing_fields"])
+
+    def test_plan_blocks_external_writes_without_dry_run(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root, external_writes=True, dry_run_supported=False)
+            repository = self.repository_module.ExecutionLoopRepository(root=ROOT)
+
+            result = repository.plan_execution_loop(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "blocked")
+            codes = {finding["code"] for finding in result["findings"]}
+            self.assertIn("external_write_without_dry_run", codes)
+
+    def test_generate_loop_runner_returns_content_without_writing(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            repository = self.repository_module.ExecutionLoopRepository(root=ROOT)
+
+            result = repository.generate_loop_runner(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "ok")
+            self.assertEqual(result["write_policy"], "output_only")
+            self.assertIn("LOOP_SPEC", result["content"])
+            self.assertIn("max_iterations", result["content"])
+            self.assertFalse((root / "loop_runner.py").exists())
+
+    def test_generate_loop_project_files_dry_run_and_execute(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            target_project = root / "target"
+            target_project.mkdir()
+            spec_path = self.write_spec(root, target_project=target_project)
+            repository = self.repository_module.ExecutionLoopRepository(root=ROOT)
+
+            planned = repository.generate_loop_project_files(spec_path=spec_path)
+            written = repository.generate_loop_project_files(spec_path=spec_path, execute=True)
+
+            self.assertEqual(planned["status"], "planned")
+            self.assertTrue(planned["dry_run"])
+            self.assertEqual(written["status"], "written")
+            runner = target_project / "daily-pr-review" / "loop_runner.py"
+            self.assertTrue(runner.exists())
+            py_compile.compile(str(runner), doraise=True)
+            for item in written["written_files"]:
+                self.assertTrue(Path(item["path"]).resolve().is_relative_to(target_project.resolve()))
+
+    def test_generate_loop_project_files_blocks_overwrite_without_permission(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            target_project = root / "target"
+            target_project.mkdir()
+            spec_path = self.write_spec(root, target_project=target_project)
+            repository = self.repository_module.ExecutionLoopRepository(root=ROOT)
+            repository.generate_loop_project_files(spec_path=spec_path, execute=True)
+
+            result = repository.generate_loop_project_files(spec_path=spec_path, execute=True)
+
+            self.assertEqual(result["status"], "blocked")
+            self.assertEqual(result["reason"], "target_exists")
+
+    def test_review_loop_safety_detects_text_risks(self) -> None:
+        repository = self.repository_module.ExecutionLoopRepository(root=ROOT)
+
+        result = repository.review_loop_safety(text="while true: rm -rf /tmp/x API_KEY=abc")
+
+        self.assertEqual(result["status"], "failed")
+        codes = {finding["code"] for finding in result["findings"]}
+        self.assertIn("missing_max_iterations", codes)
+        self.assertIn("missing_max_runtime_seconds", codes)
+        self.assertIn("missing_stop_when", codes)
+        self.assertIn("destructive_step", codes)
+        rendered = json.dumps(result)
+        self.assertNotIn("abc", rendered)
+
+    def test_review_loop_safety_detects_external_write_without_idempotency(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root, external_writes=True)
+            repository = self.repository_module.ExecutionLoopRepository(root=ROOT)
+
+            result = repository.review_loop_safety(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "failed")
+            codes = {finding["code"] for finding in result["findings"]}
+            self.assertIn("external_write_without_idempotency", codes)
+
+    def test_register_loop_task_dry_run_does_not_write_scheduler(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            os.environ["AI_DEVKIT_CONFIG_HOME"] = str(root / "home")
+            repository = self.repository_module.ExecutionLoopRepository(root=ROOT)
+            try:
+                result = repository.register_loop_task(spec_path=spec_path)
+            finally:
+                os.environ.pop("AI_DEVKIT_CONFIG_HOME", None)
+
+            self.assertEqual(result["status"], "planned")
+            self.assertTrue(result["dry_run"])
+            self.assertFalse((root / "home" / "tasks" / "tasks.json").exists())
+
+    def test_register_loop_task_execute_uses_local_scheduler(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            home = root / "home"
+            spec_path = self.write_spec(root)
+            old_home = os.environ.get("AI_DEVKIT_CONFIG_HOME")
+            os.environ["AI_DEVKIT_CONFIG_HOME"] = str(home)
+            repository = self.repository_module.ExecutionLoopRepository(root=ROOT)
+            try:
+                result = repository.register_loop_task(spec_path=spec_path, execute=True)
+            finally:
+                if old_home is None:
+                    os.environ.pop("AI_DEVKIT_CONFIG_HOME", None)
+                else:
+                    os.environ["AI_DEVKIT_CONFIG_HOME"] = old_home
+
+            self.assertEqual(result["status"], "registered")
+            self.assertEqual(result["task"]["id"], "daily-pr-review")
+            self.assertEqual(result["task"]["schedule"]["type"], "interval")
+            self.assertEqual(result["task"]["action"]["type"], "loop-runner")
+            self.assertFalse(result["task"]["action"]["external_writes"])
+
+    def test_plan_runner_is_executable_through_agent_cli(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+
+            result = subprocess.run(
+                [
+                    sys.executable,
+                    str(AGENT),
+                    "--json",
+                    "run",
+                    "execution-loop-builder",
+                    "plan-execution-loop",
+                    "--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["loop"]["id"], "daily-pr-review")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/runtime/agents/execution-reviewer/AGENTS.md

@@ -0,0 +1,8 @@
+# AGENTS.md
+
+Instrucoes locais para o agente `execution-reviewer`.
+
+Este agente revisa planos, resultados e entregas finais antes de conclusao.
+Ele deve procurar lacunas, risco operacional, ausencia de teste, fuga de
+credencial e divergencia de contrato.
+

package/runtime/agents/execution-reviewer/README.md

@@ -0,0 +1,13 @@
+# Execution Reviewer
+
+Agente de runtime responsavel por revisar plano, execucao e saida final de
+atividades multiagente.
+
+No runtime da CLI, este agente e acionado quando `review_gate.required = true`.
+A revisao deve ser executada por um backend independente do produtor da resposta,
+preferindo `claude-code` ou `codex-cli`.
+
+O reviewer deve responder com `REVIEW OK` para aprovar ou `REVIEW BLOCKED` para
+bloquear. Sem reviewer independente configurado, com decisao bloqueada, ou sem
+uma decisao explicita `REVIEW OK`, a CLI retorna `needs-review` e nao conclui a
+atividade como `ok`.

package/runtime/agents/execution-reviewer/agent.yaml

@@ -0,0 +1,27 @@
+id: execution-reviewer
+kind: runtime-agent
+name: Execution Reviewer
+version: 0.1.6
+status: draft
+owner: agent-devkit
+
+purpose: >
+  Revisar planos e resultados antes da conclusao, garantindo aderencia a
+  contrato, evidencias, ausencia de segredo e qualidade operacional.
+
+runtime_role:
+  kind: reviewer
+
+default_context:
+  - knowledge/system.md
+  - knowledge/context.md
+
+capabilities:
+  - review-final-output
+  - review-plan
+  - review-agent-result
+
+write_policy:
+  external_writes: blocked_by_default
+  default_mode: read_only
+  blocks_on_high_risk: confirm

package/runtime/agents/execution-reviewer/capabilities/review-agent-result/capability.yaml

@@ -0,0 +1,14 @@
+id: execution-reviewer.review-agent-result
+kind: capability
+name: Review Agent Result
+version: 0.1.6
+status: draft
+purpose: Revisar resultado individual de agente especialista.
+write_policy: read_only
+entrypoint:
+  workflow: workflow.md
+inputs:
+  required: [agent_id, result]
+  optional: [capability_id]
+outputs:
+  artifacts: [agent-result-review]

package/runtime/agents/execution-reviewer/capabilities/review-agent-result/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Resultado sem evidencia deve ser marcado como risco.
+- Erro de runner nao deve ser convertido em sucesso.
+- Saida de agente nao deve vazar segredo.
+

package/runtime/agents/execution-reviewer/capabilities/review-agent-result/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Verificar contrato da capability executada.
+2. Comparar output com entradas e evidencias.
+3. Marcar riscos, lacunas e erros.
+4. Encaminhar conclusao para revisao final.
+

package/runtime/agents/execution-reviewer/capabilities/review-final-output/capability.yaml

@@ -0,0 +1,14 @@
+id: execution-reviewer.review-final-output
+kind: capability
+name: Review Final Output
+version: 0.1.6
+status: draft
+purpose: Revisar saida final antes de concluir uma tarefa multiagente.
+write_policy: read_only
+entrypoint:
+  workflow: workflow.md
+inputs:
+  required: [result]
+  optional: [execution_plan, review_gate]
+outputs:
+  artifacts: [review-report]

package/runtime/agents/execution-reviewer/capabilities/review-final-output/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Bloquear conclusao se houver segredo bruto.
+- Bloquear conclusao se escrita externa ocorreu sem permissao.
+- Exigir evidencia para afirmacoes operacionais.
+

package/runtime/agents/execution-reviewer/capabilities/review-final-output/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Comparar resultado com o pedido original.
+2. Verificar se tasks planejadas foram executadas ou bloqueadas corretamente.
+3. Checar evidencias, testes e riscos.
+4. Aprovar, pedir correcao ou bloquear conclusao.
+

package/runtime/agents/execution-reviewer/capabilities/review-plan/capability.yaml

@@ -0,0 +1,14 @@
+id: execution-reviewer.review-plan
+kind: capability
+name: Review Plan
+version: 0.1.6
+status: draft
+purpose: Revisar plano multiagente antes de execucao sensivel.
+write_policy: read_only
+entrypoint:
+  workflow: workflow.md
+inputs:
+  required: [execution_plan]
+  optional: []
+outputs:
+  artifacts: [plan-review]

package/runtime/agents/execution-reviewer/capabilities/review-plan/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Plano nao pode referenciar agente inexistente.
+- Plano com provider obrigatorio ausente deve ficar `needs-input`.
+- Plano com escrita externa precisa permissao explicita.
+

package/runtime/agents/execution-reviewer/capabilities/review-plan/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Validar que todos os `agent_id` existem.
+2. Confirmar capabilities e providers necessarios.
+3. Identificar escrita externa e permissoes exigidas.
+4. Reportar ajustes antes da execucao.
+

package/runtime/agents/execution-reviewer/infra/README.md

@@ -0,0 +1,4 @@
+# Infra
+
+Este agente revisa artefatos locais e nao acessa sistemas externos diretamente.
+

package/runtime/agents/execution-reviewer/knowledge/context.md

@@ -0,0 +1,6 @@
+# Context
+
+Este agente e chamado pelo `review_task` do plano multiagente. Coordenadores
+como Claude/Codex podem ser revisores preferenciais, mas a superficie formal da
+revisao no Agent DevKit e este agente.
+

package/runtime/agents/execution-reviewer/knowledge/system.md

@@ -0,0 +1,18 @@
+# System
+
+Voce e o Execution Reviewer do Agent DevKit.
+
+Missao:
+
+- revisar plano antes de execucao quando necessario;
+- revisar resultado de agentes especialistas;
+- validar saida final antes de concluir;
+- apontar riscos, lacunas e evidencias ausentes.
+
+Guardrails:
+
+- nao executar escrita externa;
+- nao aprovar resultado sem evidencia;
+- bloquear conclusao quando houver segredo bruto, permissao ausente ou erro de
+  contrato.
+

package/runtime/agents/execution-reviewer/templates/README.md

@@ -0,0 +1,4 @@
+# Templates
+
+Templates futuros para relatorios de revisao.
+

package/runtime/agents/figma-ui-ux-product-designer/agent.yaml

@@ -84,13 +84,13 @@ agent_surface:
     - ../../vendor/plugins/CATALOG.md
 
 write_policy:
-  read_operations: auto
-  local_artifacts: ask_before_creating_output_directory
-  figma_create_file: confirm_with_yes_figma_write
-  figma_update_existing_file: confirm_with_yes_figma_write
+  read_operations: read_only
+  local_artifacts: output_only
+  figma_create_file: confirm
+  figma_update_existing_file: confirm
   figma_comments: confirm
   azure_card_comment: confirm
-  destructive_design_changes: forbidden_by_default
+  destructive_design_changes: blocked_by_default
 
 execution_quality_gates:
   direct_mode_requires:
@@ -104,3 +104,15 @@ execution_quality_gates:
     - inspected_node_ids
   forbidden_claims:
     - claim_created_or_updated_figma_without_bridge_result
+
+routing:
+  anchors:
+    - design
+    - figma
+    - tela
+    - ui
+    - ux
+    - wireframe
+  intents:
+    - design.ui-ux
+  priority: 50

package/runtime/agents/figma-ui-ux-product-designer/capabilities/analyze-product-context/capability.yaml

@@ -11,4 +11,4 @@ inputs:
   optional: [source, brief, depth, platform, scope, output_dir]
 outputs:
   artifacts: [design-brief.md, screen-inventory.md, open-design-questions.md, source-traceability.md]
-write_policy: ask_before_creating_output_directory
+write_policy: output_only

package/runtime/agents/figma-ui-ux-product-designer/capabilities/conduct-design-interview/capability.yaml

@@ -11,4 +11,4 @@ inputs:
   optional: [brief, source, platform, scope, target_audience, design_style, output_dir]
 outputs:
   artifacts: [design-brief.md, open-design-questions.md, source-traceability.md]
-write_policy: ask_before_creating_output_directory
+write_policy: output_only

package/runtime/agents/figma-ui-ux-product-designer/capabilities/conduct-design-review-session/capability.yaml

@@ -11,4 +11,4 @@ inputs:
   optional: [brief, feedback, figma_file_url, source, output_dir]
 outputs:
   artifacts: [feedback-triage.md, open-design-questions.md, design-quality-report.md]
-write_policy: ask_before_creating_output_directory
+write_policy: output_only

package/runtime/agents/figma-ui-ux-product-designer/capabilities/generate-dev-handoff/capability.yaml

@@ -11,4 +11,4 @@ inputs:
   optional: [brief, source, figma_file_url, output_dir]
 outputs:
   artifacts: [dev-handoff.md, design-brief.md, source-traceability.md]
-write_policy: ask_before_creating_output_directory
+write_policy: output_only

package/runtime/agents/figma-ui-ux-product-designer/capabilities/generate-user-journey-diagram/capability.yaml

@@ -14,4 +14,4 @@ outputs:
 integration:
   provider: figma
   tool: generate_diagram
-write_policy: ask_before_creating_output_directory
+write_policy: output_only

package/runtime/agents/figma-ui-ux-product-designer/capabilities/ingest-design-source/capability.yaml

@@ -12,4 +12,4 @@ inputs:
   optional: [brief, depth, output_dir]
 outputs:
   artifacts: [design-brief.md, screen-inventory.md, source-traceability.md, open-design-questions.md]
-write_policy: ask_before_creating_output_directory
+write_policy: output_only

package/runtime/agents/figma-ui-ux-product-designer/capabilities/triage-design-feedback/capability.yaml

@@ -12,4 +12,4 @@ inputs:
   optional: [figma_file_url, source, output_dir]
 outputs:
   artifacts: [feedback-triage.md, open-design-questions.md]
-write_policy: ask_before_creating_output_directory
+write_policy: output_only

package/runtime/agents/generic-agent-builder/AGENTS.md

@@ -0,0 +1,20 @@
+# Generic Agent Builder
+
+Instrucoes locais para trabalhar no agente `generic-agent-builder`.
+
+## Responsabilidade
+
+Este agente planeja, gera e revisa agentes genericos portaveis para uso fora do
+Agent DevKit. Ele nao cria agentes internos em `agents/<agent-id>/`; essa
+responsabilidade pertence ao agente `agent-devkit-agent-builder`.
+
+## Guardrails
+
+- Manter a saida portavel para Codex, Claude, Cursor, OpenCode ou hosts
+  genericos.
+- Nao gravar arquivos por padrao; usar dry-run para projetos destino.
+- Nao incluir segredos, tokens, URLs privadas ou contexto sensivel nos agentes
+  gerados.
+- Nao prometer ferramentas que o host alvo nao declarou como disponiveis.
+- Nao sobrescrever instrucoes existentes sem permissao explicita.
+- Nao criar arquivos fora do `target_project`.

package/runtime/agents/generic-agent-builder/README.md

@@ -0,0 +1,40 @@
+# Generic Agent Builder
+
+Agente especialista para planejar, gerar e revisar agentes genericos portaveis
+para projetos externos ao Agent DevKit.
+
+## Capabilities
+
+- `plan-generic-agent`: planeja contrato, host alvo, limites e artefatos sem
+  escrever arquivos.
+- `generate-agent-instructions`: gera instrucoes Markdown portaveis.
+- `generate-skill`: gera um `SKILL.md` portavel em modo output-only.
+- `generate-project-agent-files`: planeja ou escreve arquivos em um projeto
+  destino com dry-run por padrao.
+- `review-generic-agent`: revisa instrucoes de agente contra guardrails,
+  compatibilidade de host e sinais de segredo.
+
+## Contrato
+
+Entrada minima:
+
+```yaml
+target_host: codex | claude | cursor | opencode | generic
+target_project: /path/opcional
+agent_name: Support Review Agent
+purpose: Review support tickets and produce concise operational guidance.
+allowed_tools:
+  - shell
+forbidden_actions:
+  - bypass host permissions
+domain_context: Support triage for internal software projects.
+output_format: Markdown report with facts, risks and next steps.
+quality_gates:
+  - cite assumptions
+```
+
+## Limites
+
+Este agente nao instala plugins externos, nao cria MCP server e nao acopla o
+projeto destino ao runtime interno do Agent DevKit. Quando o destino precisar de
+MCP, ele apenas pode descrever a configuracao como texto revisavel.