agent-devkit 0.1.5 → 0.2.0

package/runtime/agents/docker-container-builder/knowledge/context.md

@@ -0,0 +1,21 @@
+# Contexto
+
+O agente opera sem provider externo no MVP. Ele usa apenas arquivos locais e
+specs YAML/JSON fornecidas pelo usuario.
+
+## Linguagens Suportadas No MVP
+
+- Python
+- Node.js
+- Go
+- Java
+- Unknown, com plano conservador e perguntas abertas
+
+## Artefatos
+
+- `Dockerfile`
+- `.dockerignore`
+- `docker-compose.yml`
+- `README.docker.md`
+
+Build e push sao apenas comandos sugeridos em planos dry-run.

package/runtime/agents/docker-container-builder/knowledge/policies.yaml

@@ -0,0 +1,13 @@
+policies:
+  supported_scope: docker-local-artifacts
+  default_write_mode: dry_run
+  docker_cli_execution: blocked_by_default
+  build_real: blocked_by_default
+  push_real: blocked_by_default
+  deploy_real: blocked_by_default
+  secrets: never_persist
+  dockerignore_required: true
+  non_root_user: prefer
+  target_project_boundary: required_for_writes
+  overwrite: blocked_without_explicit_permission
+  compose_scope: development_local_by_default

package/runtime/agents/docker-container-builder/knowledge/system.md

@@ -0,0 +1,21 @@
+# System
+
+Voce e o `docker-container-builder`, especialista em containerizacao Docker
+local.
+
+Seu trabalho e transformar um projeto ou spec em artefatos Docker seguros,
+revisaveis e portaveis. Voce pode analisar projetos, gerar conteudo de
+Dockerfile/compose, escrever arquivos locais somente quando explicitamente
+solicitado pelo runner e revisar riscos.
+
+## Regras Principais
+
+- Nao execute Docker CLI.
+- Nao faca build, push ou deploy real.
+- Sempre gere `.dockerignore` junto de `Dockerfile`.
+- Nao copie segredos, `.env`, `.ssh`, chaves privadas ou credenciais.
+- Prefira usuario nao-root.
+- Evite `latest` para alvo `prod`.
+- Compose gerado e para desenvolvimento local salvo declaracao explicita.
+- Nao gere `privileged`, `network_mode: host` ou bind mount de `/`.
+- Escrita local deve permanecer dentro de `target_project`.

package/runtime/agents/docker-container-builder/templates/container-plan.md

@@ -0,0 +1,4 @@
+# Container Plan
+
+Use este artefato para revisar os arquivos planejados antes de escrita local ou
+build manual.

package/runtime/agents/docker-container-builder/templates/container-review.md

@@ -0,0 +1,4 @@
+# Container Review
+
+Relatorio de riscos encontrados em Dockerfile, compose e configuracao de
+containerizacao.

package/runtime/agents/docker-container-builder/templates/docker-compose.md

@@ -0,0 +1,5 @@
+# docker-compose.yml
+
+```yaml
+{{content}}
+```

package/runtime/agents/docker-container-builder/templates/docker-readme.md

@@ -0,0 +1,3 @@
+# README Docker
+
+Instrucoes geradas para build e execucao local do container.

package/runtime/agents/docker-container-builder/templates/dockerfile.md

@@ -0,0 +1,5 @@
+# Dockerfile
+
+```dockerfile
+{{content}}
+```

package/runtime/agents/docker-container-builder/tests/test_runners.py

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""Tests for the Docker Container Builder runners."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+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" / "docker-container-builder"
+REPOSITORY_PATH = (
+    AGENT_DIR
+    / "infra"
+    / "integrations"
+    / "docker-container"
+    / "docker_container_repository.py"
+)
+
+
+def load_repository_module():
+    spec = importlib.util.spec_from_file_location("docker_container_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 DockerContainerBuilderRunnersTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.repository_module = load_repository_module()
+
+    def write_project(self, root: Path) -> Path:
+        (root / "requirements.txt").write_text("fastapi==0.115.0\nuvicorn==0.30.0\n", encoding="utf-8")
+        (root / "app.py").write_text(
+            """
+import os
+
+PORT = int(os.environ.get("PORT", "8000"))
+""".lstrip(),
+            encoding="utf-8",
+        )
+        (root / ".env").write_text("API_TOKEN=secret-value\n", encoding="utf-8")
+        return root
+
+    def write_spec(
+        self,
+        root: Path,
+        *,
+        target_project: Path | None = None,
+        language: str = "python",
+        target: str = "prod",
+        entrypoint: str = "python app.py",
+        image_tag: str = "1.0.0",
+        include_secret_value: bool = False,
+    ) -> Path:
+        path = root / "container-spec.yaml"
+        target_project_line = f"target_project: {target_project}\n" if target_project else ""
+        secret_line = "  - name: API_TOKEN\n    value: plain-secret\n" if include_secret_value else "  - PORT\n"
+        path.write_text(
+            f"""
+project_name: Orders API
+{target_project_line}language: {language}
+target: {target}
+entrypoint: {entrypoint}
+image_name: orders-api
+image_tag: {image_tag}
+ports:
+  - 8000
+environment:
+{secret_line}services:
+  - name: redis
+    image: redis:7.2-alpine
+    port: 6379
+include_compose: true
+""".lstrip(),
+            encoding="utf-8",
+        )
+        return path
+
+    def test_analyze_containerization_target_detects_python_project_and_risks(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            project = self.write_project(Path(tmpdir))
+            repository = self.repository_module.DockerContainerRepository(root=ROOT)
+
+            result = repository.analyze_containerization_target(project_path=project)
+
+            self.assertEqual(result["status"], "ok")
+            self.assertEqual(result["write_policy"], "read_only")
+            self.assertEqual(result["facts"]["language"], "python")
+            self.assertIn(".env", result["facts"]["sensitive_files"])
+            codes = {risk["code"] for risk in result["risks"]}
+            self.assertIn("sensitive_files_in_context", codes)
+
+    def test_generate_dockerfile_returns_content_without_writing(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            repository = self.repository_module.DockerContainerRepository(root=ROOT)
+
+            result = repository.generate_dockerfile(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "ok")
+            self.assertEqual(result["write_policy"], "output_only")
+            content = result["content"]
+            self.assertIn("FROM python:3.12-slim", content)
+            self.assertIn("USER appuser", content)
+            self.assertIn("EXPOSE 8000", content)
+            self.assertFalse((root / "Dockerfile").exists())
+
+    def test_generate_compose_avoids_privileged_and_embedded_secrets(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            repository = self.repository_module.DockerContainerRepository(root=ROOT)
+
+            result = repository.generate_compose(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "ok")
+            content = result["content"]
+            self.assertIn("services:", content)
+            self.assertIn('"8000:8000"', content)
+            self.assertNotIn("privileged", content.lower())
+            self.assertNotIn("plain-secret", content)
+
+    def test_generate_project_files_dry_run_does_not_write(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.DockerContainerRepository(root=ROOT)
+
+            result = repository.generate_container_project_files(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "planned")
+            self.assertTrue(result["dry_run"])
+            planned = {item["path"] for item in result["planned_files"]}
+            self.assertGreaterEqual(planned, {"Dockerfile", ".dockerignore", "README.docker.md", "docker-compose.yml"})
+            self.assertFalse((target_project / "Dockerfile").exists())
+
+    def test_generate_project_files_execute_writes_inside_target_project(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.DockerContainerRepository(root=ROOT)
+
+            result = repository.generate_container_project_files(spec_path=spec_path, execute=True)
+
+            self.assertEqual(result["status"], "written")
+            self.assertTrue((target_project / "Dockerfile").exists())
+            self.assertTrue((target_project / ".dockerignore").exists())
+            ignore = (target_project / ".dockerignore").read_text(encoding="utf-8")
+            self.assertIn(".env", ignore)
+            for item in result["written_files"]:
+                self.assertTrue(Path(item["path"]).resolve().is_relative_to(target_project.resolve()))
+
+    def test_generate_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.DockerContainerRepository(root=ROOT)
+            repository.generate_container_project_files(spec_path=spec_path, execute=True)
+
+            result = repository.generate_container_project_files(spec_path=spec_path, execute=True)
+
+            self.assertEqual(result["status"], "blocked")
+            self.assertEqual(result["reason"], "target_exists")
+
+    def test_review_docker_security_detects_high_risk_patterns(self) -> None:
+        repository = self.repository_module.DockerContainerRepository(root=ROOT)
+
+        result = repository.review_docker_security(
+            dockerfile_text="FROM python:latest\nCOPY . .\nENV API_KEY=abc\n",
+            compose_text="services:\n  app:\n    image: app\n    privileged: true\n",
+        )
+
+        self.assertEqual(result["status"], "failed")
+        codes = {finding["code"] for finding in result["findings"]}
+        self.assertIn("missing_non_root_user", codes)
+        self.assertIn("base_image_latest", codes)
+        self.assertIn("secret_marker_in_dockerfile", codes)
+        self.assertIn("compose_privileged", codes)
+        rendered = json.dumps(result)
+        self.assertNotIn("abc", rendered)
+
+    def test_plan_image_build_is_dry_run(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            repository = self.repository_module.DockerContainerRepository(root=ROOT)
+
+            result = repository.plan_image_build(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "ok")
+            self.assertEqual(result["write_policy"], "dry_run")
+            self.assertFalse(result["push_real"])
+            self.assertIn("docker build", result["blocked_actions"])
+            self.assertTrue(any(command.startswith("docker build") for command in result["commands_to_review"]))
+
+    def test_plan_blocks_hardcoded_secret_environment_value(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root, include_secret_value=True)
+            repository = self.repository_module.DockerContainerRepository(root=ROOT)
+
+            result = repository.plan_container_artifacts(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "blocked")
+            self.assertEqual(result["reason"], "hardcoded_secret_env_value")
+
+    def test_generate_dockerfile_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",
+                    "docker-container-builder",
+                    "generate-dockerfile",
+                    "--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.assertIn("Dockerfile", runner_payload["artifact"])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/runtime/agents/drawio-diagram-builder/agent.yaml

@@ -53,8 +53,17 @@ agent_surface:
 
 write_policy:
   source_reading: read_only
-  azure_card_reading: delegated_read_only
+  azure_card_reading: read_only
   diagram_generation: output_only
   refinement: output_only
   overwrite_operations: confirm
-  external_side_effects: unsupported
+  external_side_effects: blocked_by_default
+
+routing:
+  anchors:
+    - diagram
+    - diagrama
+    - drawio
+  intents:
+    - diagram.build
+  priority: 50

package/runtime/agents/drawio-diagram-builder/capabilities/execute-diagram-delivery/capability.yaml

@@ -17,4 +17,4 @@ outputs:
 integration:
   repository: ../../infra/integrations/drawio/drawio_renderer.py
   methods: []
-write_policy: ask_before_creating_output_directory
+write_policy: output_only

package/runtime/agents/drawio-diagram-builder/capabilities/read-azure-card-context/capability.yaml

@@ -17,4 +17,4 @@ outputs:
 integration:
   repository: null
   methods: []
-write_policy: delegated_read_only
+write_policy: read_only

package/runtime/agents/elasticsearch-log-analyzer/agent.yaml

@@ -50,5 +50,17 @@ agent_surface:
     - knowledge/policies.yaml
 
 write_policy:
-  read_operations: auto
-  write_operations: unsupported
+  read_operations: read_only
+  write_operations: blocked_by_default
+
+routing:
+  anchors:
+    - elastic
+    - elasticsearch
+    - index
+    - indice
+    - log
+    - logs
+  intents:
+    - logs.elasticsearch.analysis
+  priority: 55

package/runtime/agents/elasticsearch-log-analyzer/capabilities/analyze-service-errors/capability.yaml

@@ -23,3 +23,17 @@ integration:
     - ../../infra/integrations/elasticsearch/methods/aggregate-terms.yaml
     - ../../infra/integrations/elasticsearch/methods/aggregate-timeline.yaml
 write_policy: read_only
+
+routing:
+  anchors:
+    - elastic
+    - elasticsearch
+    - erro
+    - error
+    - service
+    - servico
+  intents:
+    - logs.error-analysis
+  examples:
+    - analise logs do elasticsearch para erro no servico
+  priority: 80

package/runtime/agents/excel-workbook-builder/agent.yaml

@@ -66,3 +66,13 @@ capabilities:
 capabilities_dir: capabilities
 templates_dir: templates
 infra_dir: infra
+
+routing:
+  anchors:
+    - excel
+    - planilha
+    - spreadsheet
+    - workbook
+  intents:
+    - spreadsheet.workbook
+  priority: 50

package/runtime/agents/excel-workbook-builder/capabilities/create-template/capability.yaml

@@ -12,4 +12,4 @@ inputs:
   optional: [template_id, output]
 outputs:
   artifacts: [template.xlsx]
-write_policy: ask_before_write
+write_policy: confirm

package/runtime/agents/excel-workbook-builder/capabilities/create-template/workflow.md

@@ -18,7 +18,7 @@ RACIOCÍNIO:
 
 REGRAS DE DECISÃO:
 - Nunca grave o template no projeto sem --yes-save ou autorização explícita
-  (write_policy: ask_before_write).
+  (write_policy: confirm).
 - Se o brief não define abas ou dados, pergunte antes de gerar.
 
 SAÍDA: template.xlsx no caminho --output (ou plano .md se Node ausente).

package/runtime/agents/excel-workbook-builder/capabilities/create-template-version/capability.yaml

@@ -12,4 +12,4 @@ inputs:
   optional: [base_version, template]
 outputs:
   artifacts: [template.xlsx]
-write_policy: create_new_version
+write_policy: local_write

package/runtime/agents/excel-workbook-builder/capabilities/generate-template-input-file/capability.yaml

@@ -11,5 +11,4 @@ inputs:
   optional: [template_version, templates_root]
 outputs:
   artifacts: [input-schema.xlsx, input-schema.md]
-write_policy: template_version_write
-
+write_policy: local_write

package/runtime/agents/excel-workbook-builder/capabilities/refine-template/capability.yaml

@@ -12,4 +12,4 @@ inputs:
   optional: [base_version]
 outputs:
   artifacts: [template.xlsx]
-write_policy: create_new_version
+write_policy: local_write

package/runtime/agents/excel-workbook-builder/capabilities/register-template/capability.yaml

@@ -11,5 +11,4 @@ inputs:
   optional: [name, version, status, templates_root, yes_save]
 outputs:
   artifacts: [template.xlsx, template.yaml, input-schema.xlsx, sheet-map.yaml]
-write_policy: ask_before_write
-
+write_policy: confirm

package/runtime/agents/excel-workbook-builder/capabilities/register-template/workflow.md

@@ -10,7 +10,7 @@ RACIOCÍNIO:
 1. Valide que --template-id é um slug válido (sem espaços ou caracteres especiais).
 2. Confirme que o template-id não está já registrado (list-templates).
 3. Confirme gravação com o usuário antes de executar (write_policy:
-   ask_before_write); só prossiga com --yes-save ou confirmação explícita.
+   confirm); só prossiga com --yes-save ou confirmação explícita.
 4. Crie a estrutura: templates/<id>/versions/<version>/ + template.yaml.
 5. Inspecione o .xlsx registrado e registre o sheet-map inicial.
 

package/runtime/agents/execution-loop-builder/AGENTS.md

@@ -0,0 +1,24 @@
+# Execution Loop Builder
+
+Instrucoes locais para trabalhar no agente `execution-loop-builder`.
+
+## Responsabilidade
+
+Este agente planeja, gera e revisa loops de execucao controlados: ciclos de
+planejar, executar, observar, revisar e parar por criterios claros.
+
+## Fora De Escopo
+
+- Executar capabilities reais dentro do loop gerado no MVP.
+- Criar orquestrador distribuido, fila cloud ou UI de monitoramento.
+- Permitir loop sem budget de tempo e iteracao.
+- Registrar loops de escrita externa como permissivos por padrao.
+
+## Guardrails
+
+- Todo loop deve ter `max_iterations`, `max_runtime_seconds` e `stop_when`.
+- Side effects externos exigem dry-run, idempotencia e permissao explicita.
+- Runner gerado deve persistir estado e auditoria por iteracao.
+- Notificacao deve ser limitada para evitar spam.
+- Registro no scheduler local so ocorre com `--execute`.
+- Loops destrutivos ficam bloqueados por padrao.

package/runtime/agents/execution-loop-builder/README.md

@@ -0,0 +1,19 @@
+# Execution Loop Builder
+
+Agente especialista em projetar loops de execucao pequenos, controlados e
+auditaveis.
+
+## Capabilities
+
+- `plan-execution-loop`: valida e planeja contrato de loop.
+- `generate-loop-runner`: gera runner Python output-only.
+- `generate-loop-project-files`: planeja ou escreve pacote local de loop.
+- `review-loop-safety`: revisa riscos de loop infinito, side effects,
+  budgets, notificacao e idempotencia.
+- `register-loop-task`: registra loop no scheduler local existente, apenas com
+  `--execute`.
+
+## Politica
+
+O agente nao executa as capabilities reais do loop no MVP. Ele gera contrato,
+runner seguro, auditoria local e registro de task para execucao controlada.

package/runtime/agents/execution-loop-builder/agent.yaml

@@ -0,0 +1,49 @@
+id: execution-loop-builder
+kind: specialist-agent
+name: Execution Loop Builder
+version: 0.1.0
+status: draft
+owner: agent-devkit
+purpose: >
+  Planejar, gerar, revisar e registrar loops de execucao controlados, com
+  budgets, criterios de parada, estado minimo, auditoria por iteracao e
+  guardrails para side effects.
+default_context:
+  - knowledge/system.md
+  - knowledge/context.md
+  - knowledge/policies.yaml
+env:
+  required: []
+  optional:
+    - AI_DEVKIT_CONFIG_HOME
+capabilities:
+  - plan-execution-loop
+  - generate-loop-runner
+  - generate-loop-project-files
+  - review-loop-safety
+  - register-loop-task
+agent_surface:
+  repositories:
+    - infra/integrations/execution-loop/execution_loop_repository.py
+  policies:
+    - knowledge/policies.yaml
+write_policy:
+  planning: read_only
+  runner_generation: output_only
+  project_files: local_write
+  review: read_only
+  scheduler_registration: local_write
+  real_loop_execution: blocked_by_default
+  external_writes: blocked_by_default
+routing:
+  anchors:
+    - execution-loop-builder
+    - execution-loop
+    - loop-engineering
+    - retry-loop
+    - scheduler-loop
+  intents:
+    - execution-loop.plan
+    - execution-loop.generate
+    - execution-loop.review
+  priority: 50

package/runtime/agents/execution-loop-builder/capabilities/generate-loop-project-files/capability.yaml

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

package/runtime/agents/execution-loop-builder/capabilities/generate-loop-project-files/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Escrita real requer `--execute`.
+- Sobrescrita requer `--allow-overwrite`.
+- Bloquear path absoluto e path traversal.
+- Nao executar o loop gerado.

package/runtime/agents/execution-loop-builder/capabilities/generate-loop-project-files/runner.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Runner for execution-loop-builder/generate-loop-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" / "execution-loop"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from execution_loop_repository import ExecutionLoopBuilderError, ExecutionLoopRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate execution loop 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 = ExecutionLoopRepository().generate_loop_project_files(
+            spec_path=Path(args.spec),
+            execute=args.execute,
+            allow_overwrite=args.allow_overwrite,
+        )
+    except ExecutionLoopBuilderError 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/execution-loop-builder/capabilities/generate-loop-project-files/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Carregar spec YAML/JSON.
+2. Validar `target_project`.
+3. Planejar arquivos do pacote local.
+4. Sem `--execute`, retornar dry-run.
+5. Com `--execute`, escrever apenas dentro de `target_project`.