agent-devkit 0.1.6 → 0.3.0

package/runtime/agents/generic-agent-builder/tests/test_runners.py

@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+"""Tests for the Generic Agent 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" / "generic-agent-builder"
+REPOSITORY_PATH = AGENT_DIR / "infra" / "integrations" / "generic-agent" / "generic_agent_repository.py"
+
+
+def load_repository_module():
+    spec = importlib.util.spec_from_file_location("generic_agent_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 GenericAgentBuilderRunnersTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.repository_module = load_repository_module()
+
+    def write_spec(
+        self,
+        root: Path,
+        *,
+        target_host: str = "generic",
+        target_project: Path | None = None,
+        domain_context: str = "Support triage for internal software projects.",
+    ) -> Path:
+        path = root / "generic-agent-spec.yaml"
+        target_project_line = f"target_project: {target_project}\n" if target_project else ""
+        path.write_text(
+            f"""
+target_host: {target_host}
+{target_project_line}agent_name: Support Review Agent
+purpose: >
+  Review support tickets and produce concise operational guidance.
+allowed_tools:
+  - shell
+  - file_search
+forbidden_actions:
+  - write secrets
+  - bypass host permissions
+domain_context: {domain_context}
+output_format: Markdown report with facts, risks and next steps.
+quality_gates:
+  - cite assumptions
+  - ask human before external writes
+""".lstrip(),
+            encoding="utf-8",
+        )
+        return path
+
+    def test_plan_generic_agent_returns_host_profile_without_writing(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            repository = self.repository_module.GenericAgentRepository(root=root)
+
+            result = repository.plan_generic_agent(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "ok")
+            self.assertEqual(result["target_host"], "generic")
+            planned_paths = {item["path"] for item in result["planned_artifacts"]}
+            self.assertIn("AGENTS.md", planned_paths)
+            self.assertFalse((root / "AGENTS.md").exists())
+
+    def test_plan_generic_agent_reports_needs_input_for_incomplete_spec(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = root / "generic-agent-spec.yaml"
+            spec_path.write_text("target_host: generic\n", encoding="utf-8")
+            repository = self.repository_module.GenericAgentRepository(root=root)
+
+            result = repository.plan_generic_agent(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "needs-input")
+            self.assertGreaterEqual(set(result["missing_fields"]), {"agent_name", "purpose", "domain_context"})
+
+    def test_generate_agent_instructions_contains_guardrails_and_limits(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root)
+            repository = self.repository_module.GenericAgentRepository(root=root)
+
+            result = repository.generate_agent_instructions(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "ok")
+            content = result["content"]
+            self.assertIn("## Role", content)
+            self.assertIn("## Workflow", content)
+            self.assertIn("## Guardrails", content)
+            self.assertIn("## Human Escalation", content)
+            self.assertIn("Ask a human", content)
+            self.assertIn("bypass host permissions", content)
+
+    def test_generate_skill_returns_skill_without_writing(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root, target_host="claude")
+            repository = self.repository_module.GenericAgentRepository(root=root)
+
+            result = repository.generate_skill(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "ok")
+            self.assertIn("---", result["content"])
+            self.assertIn("name: support-review-agent", result["content"])
+            self.assertIn("# Support Review Agent", result["content"])
+            self.assertFalse((root / "SKILL.md").exists())
+
+    def test_generate_project_agent_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.GenericAgentRepository(root=root)
+
+            result = repository.generate_project_agent_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.assertIn("AGENTS.md", planned_paths)
+            self.assertFalse((target_project / "AGENTS.md").exists())
+
+    def test_generate_project_agent_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.GenericAgentRepository(root=root)
+
+            result = repository.generate_project_agent_files(spec_path=spec_path, execute=True)
+
+            self.assertEqual(result["status"], "written")
+            self.assertTrue((target_project / "AGENTS.md").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_project_agent_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.GenericAgentRepository(root=root)
+            repository.generate_project_agent_files(spec_path=spec_path, execute=True)
+
+            result = repository.generate_project_agent_files(spec_path=spec_path, execute=True)
+
+            self.assertEqual(result["status"], "blocked")
+            self.assertEqual(result["reason"], "target_exists")
+
+    def test_plan_generic_agent_blocks_secret_marker(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            root = Path(tmpdir)
+            spec_path = self.write_spec(root, domain_context="Use API_KEY=abc during triage.")
+            repository = self.repository_module.GenericAgentRepository(root=root)
+
+            result = repository.plan_generic_agent(spec_path=spec_path)
+
+            self.assertEqual(result["status"], "blocked")
+            self.assertEqual(result["reason"], "forbidden_sensitive_marker")
+
+    def test_review_generic_agent_detects_missing_guardrails(self) -> None:
+        repository = self.repository_module.GenericAgentRepository(root=ROOT)
+
+        result = repository.review_generic_agent(text="# Agent\n\nAlways answer quickly.", target_host="generic")
+
+        self.assertFalse(result["valid"])
+        self.assertEqual(result["status"], "failed")
+        self.assertTrue(any("guardrail" in finding.lower() for finding in result["findings"]))
+
+    def test_plan_generic_agent_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",
+                    "generic-agent-builder",
+                    "plan-generic-agent",
+                    "--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["target_host"], "generic")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/runtime/agents/github-pr-reviewer/agent.yaml

@@ -26,8 +26,20 @@ capabilities:
   - create-review-automation
 
 write_policy:
-  read_operations: auto
-  comments: explicit_opt_in
-  approvals: explicit_opt_in
-  request_changes: explicit_opt_in
-  default_mode: report-only
+  read_operations: read_only
+  comments: confirm
+  approvals: confirm
+  request_changes: confirm
+  default_mode: read_only
+
+routing:
+  anchors:
+    - gh
+    - github
+    - pr
+    - prs
+    - pull
+    - request
+  intents:
+    - github.pr-review
+  priority: 50

package/runtime/agents/github-pr-reviewer/capabilities/create-review-automation/capability.yaml

@@ -4,7 +4,7 @@ name: Create review automation
 status: draft
 version: 0.1.0
 purpose: Criar task local diaria para revisar PRs pendentes em modo report-only.
-write_policy: local-write
+write_policy: local_write
 entrypoint:
   workflow: workflow.md
   output_template: ../../templates/pr-automation-output.md

package/runtime/agents/github-pr-reviewer/capabilities/inspect-pr/capability.yaml

@@ -4,7 +4,7 @@ name: Inspect PR
 status: draft
 version: 0.1.0
 purpose: Inspecionar metadados de uma Pull Request.
-write_policy: read-only
+write_policy: read_only
 entrypoint:
   workflow: workflow.md
   output_template: ../../templates/pr-inspection-output.md

package/runtime/agents/github-pr-reviewer/capabilities/list-review-requests/capability.yaml

@@ -4,7 +4,7 @@ name: List review requests
 status: draft
 version: 0.1.0
 purpose: Listar PRs aguardando revisao do usuario autenticado no GitHub CLI.
-write_policy: read-only
+write_policy: read_only
 entrypoint:
   workflow: workflow.md
   output_template: ../../templates/pr-list-output.md

package/runtime/agents/github-pr-reviewer/capabilities/review-pr-diff/capability.yaml

@@ -4,7 +4,7 @@ name: Review PR diff
 status: draft
 version: 0.1.0
 purpose: Carregar diff e gerar revisao report-only.
-write_policy: read-only
+write_policy: read_only
 entrypoint:
   workflow: workflow.md
   output_template: ../../templates/pr-review-output.md

package/runtime/agents/knowledge-author/AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS.md
+
+Instrucoes locais para o agente `knowledge-author`.
+
+- Transformar uso real em snapshots revisaveis, nao logs brutos.
+- Generalizar conteudo antes de propor contribuicao.
+- Remover segredos, PII desnecessaria e referencias locais indevidas.

package/runtime/agents/knowledge-author/README.md

@@ -0,0 +1,7 @@
+# knowledge-author
+
+Agente especialista em criar propostas de conhecimento reutilizavel para a
+knowledge base compartilhada.
+
+Ele converte sessoes, incidentes, PRs, runbooks e analises em snapshots
+sanitizados, rastreaveis e prontos para revisao.

package/runtime/agents/knowledge-author/agent.yaml

@@ -0,0 +1,37 @@
+id: knowledge-author
+kind: specialist-agent
+name: Knowledge Author
+version: 0.3.0
+status: draft
+owner: agent-devkit
+
+purpose: >
+  Criar snapshots de conhecimento reutilizavel a partir de uso real,
+  sanitizando dados sensiveis, generalizando aprendizados e enviando conteudo
+  apenas para revisao.
+
+routing:
+  anchors:
+    - knowledge snapshot create
+    - criar snapshot
+    - proposta de conhecimento
+  keywords:
+    - snapshot
+    - runbook
+    - learning
+    - generalizar
+  intents:
+    - knowledge.snapshot.create
+    - knowledge.snapshot.submit
+
+default_context:
+  - knowledge/system.md
+  - knowledge/context.md
+
+capabilities:
+  - create-knowledge-snapshot
+
+write_policy:
+  external_writes: blocked_by_default
+  default_mode: local_config_write
+  blocks_on_high_risk: confirm

package/runtime/agents/knowledge-author/capabilities/create-knowledge-snapshot/capability.yaml

@@ -0,0 +1,30 @@
+id: knowledge-author.create-knowledge-snapshot
+kind: capability
+name: Create knowledge snapshot
+version: 0.3.0
+status: draft
+purpose: Gerar snapshot revisavel, sanitizado e generalizavel a partir de conteudo operacional.
+entrypoint:
+  workflow: workflow.md
+write_policy: local_config_write
+inputs:
+  type: object
+  properties:
+    title:
+      type: string
+    content:
+      type: string
+    source:
+      type: string
+outputs:
+  type: object
+  artifacts:
+    - path: knowledge-base/snapshots/pending
+      kind: markdown
+      sensitive: false
+routing:
+  anchors:
+    - knowledge snapshot create
+    - criar snapshot
+  intents:
+    - knowledge.snapshot.create

package/runtime/agents/knowledge-author/capabilities/create-knowledge-snapshot/decision-rules.md

@@ -0,0 +1,6 @@
+# Regras De Decisao
+
+- Rejeitar conteudo puramente conversacional ou preferencia pessoal.
+- Sanitizar segredo, PII desnecessaria, URL privada e path local.
+- Exigir titulo, origem, escopo e utilidade recorrente.
+- Enviar apenas para revisao; nunca publicar diretamente.

package/runtime/agents/knowledge-author/capabilities/create-knowledge-snapshot/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Identificar aprendizado reutilizavel no conteudo de entrada.
+2. Remover detalhes sensiveis e especificidade excessiva.
+3. Classificar dominio, tags, origem e evidencias.
+4. Calcular score inicial de utilidade e generalidade.
+5. Gravar snapshot pendente para revisao.

package/runtime/agents/knowledge-author/infra/.gitkeep

@@ -0,0 +1 @@
+

package/runtime/agents/knowledge-author/knowledge/context.md

@@ -0,0 +1,4 @@
+# Contexto
+
+Snapshots sao propostas curadas. Eles devem capturar aprendizado operacional
+recorrente, nao copiar conversa, logs crus ou memoria pessoal.

package/runtime/agents/knowledge-author/knowledge/system.md

@@ -0,0 +1,4 @@
+# Sistema
+
+Voce escreve conhecimento compartilhavel com linguagem clara, rastreavel,
+sanitizada e pronta para revisao por `knowledge-reviewer`.

package/runtime/agents/knowledge-author/templates/.gitkeep

@@ -0,0 +1 @@
+

package/runtime/agents/knowledge-curator/AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS.md
+
+Instrucoes locais para o agente `knowledge-curator`.
+
+- Melhorar qualidade editorial sem assumir autoridade de publicacao.
+- Consolidar duplicados, propor arquivamento e manter taxonomia.
+- Reindexar apenas indices derivados da base canonica.

package/runtime/agents/knowledge-curator/README.md

@@ -0,0 +1,6 @@
+# knowledge-curator
+
+Agente especialista em curadoria continua da knowledge base compartilhada.
+
+Ele consolida duplicados, identifica lacunas, sugere refatoracoes, arquiva
+conhecimento obsoleto e mantem indices derivados.

package/runtime/agents/knowledge-curator/agent.yaml

@@ -0,0 +1,37 @@
+id: knowledge-curator
+kind: specialist-agent
+name: Knowledge Curator
+version: 0.3.0
+status: draft
+owner: agent-devkit
+
+purpose: >
+  Fazer curadoria continua da knowledge base, consolidando duplicados,
+  mantendo taxonomia, propondo arquivamentos e reindexando apenas dados
+  derivados da base canonica.
+
+routing:
+  anchors:
+    - knowledge curate
+    - curadoria de knowledge
+    - reindexar knowledge
+  keywords:
+    - curate
+    - taxonomy
+    - reindex
+    - duplicate
+  intents:
+    - knowledge.curate
+    - knowledge.reindex
+
+default_context:
+  - knowledge/system.md
+  - knowledge/context.md
+
+capabilities:
+  - curate-knowledge-base
+
+write_policy:
+  external_writes: blocked_by_default
+  default_mode: local_config_write
+  blocks_on_high_risk: confirm

package/runtime/agents/knowledge-curator/capabilities/curate-knowledge-base/capability.yaml

@@ -0,0 +1,29 @@
+id: knowledge-curator.curate-knowledge-base
+kind: capability
+name: Curate knowledge base
+version: 0.3.0
+status: draft
+purpose: Planejar curadoria, deduplicacao, arquivamento e reindexacao da knowledge base.
+entrypoint:
+  workflow: workflow.md
+write_policy: local_config_write
+inputs:
+  type: object
+  properties:
+    scope:
+      type: string
+    dry_run:
+      type: boolean
+outputs:
+  type: object
+  artifacts:
+    - path: knowledge-base/reviews
+      kind: markdown
+      sensitive: false
+routing:
+  anchors:
+    - knowledge curate
+    - reindex knowledge
+  intents:
+    - knowledge.curate
+    - knowledge.reindex

package/runtime/agents/knowledge-curator/capabilities/curate-knowledge-base/decision-rules.md

@@ -0,0 +1,6 @@
+# Regras De Decisao
+
+- Curadoria nao substitui aprovacao do `knowledge-owner`.
+- Arquivamento deve preservar rastreabilidade e auditoria.
+- Indices derivados podem ser apagados e recriados da base canonica.
+- Alteracoes editoriais de alto impacto exigem plano e revisao.

package/runtime/agents/knowledge-curator/capabilities/curate-knowledge-base/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Inventariar entradas, snapshots, reviews e indices.
+2. Detectar duplicidade, obsolescencia, lacunas e inconsistencias de tags.
+3. Propor consolidacao ou arquivamento com justificativa.
+4. Recriar indices derivados quando solicitado.
+5. Registrar plano de curadoria para revisao.

package/runtime/agents/knowledge-curator/infra/.gitkeep

@@ -0,0 +1 @@
+

package/runtime/agents/knowledge-curator/knowledge/context.md

@@ -0,0 +1,4 @@
+# Contexto
+
+A curadoria preserva qualidade da base ao longo do tempo. Ela trabalha sobre
+arquivos canonicos e indices derivados, sem publicar conteudo principal sozinha.

package/runtime/agents/knowledge-curator/knowledge/system.md

@@ -0,0 +1,4 @@
+# Sistema
+
+Voce melhora a organizacao e manutencao da knowledge base compartilhada sem
+assumir permissao de publicacao.

package/runtime/agents/knowledge-curator/templates/.gitkeep

@@ -0,0 +1 @@
+

package/runtime/agents/knowledge-generator/agent.yaml

@@ -39,7 +39,17 @@ agent_surface:
     - ../../vendor/skills/CATALOG.md
 
 write_policy:
-  read_operations: auto
-  knowledge_generation: ask_before_creating_output_directory
+  read_operations: read_only
+  knowledge_generation: output_only
   overwrite_operations: confirm
-  external_side_effects: unsupported
+  external_side_effects: blocked_by_default
+
+routing:
+  anchors:
+    - conhecimento
+    - documentacao
+    - knowledge
+    - runbook
+  intents:
+    - knowledge.generate
+  priority: 50

package/runtime/agents/knowledge-generator/capabilities/generate-knowledge/capability.yaml

@@ -29,4 +29,4 @@ integration:
   repository: ../../infra/integrations/local-source/knowledge_repository.py
   methods:
     - ../../infra/integrations/local-source/methods/generate-knowledge.yaml
-write_policy: ask_before_creating_output_directory
+write_policy: output_only

package/runtime/agents/knowledge-infra-builder/AGENTS.md

@@ -0,0 +1,8 @@
+# AGENTS.md
+
+Instrucoes locais para o agente `knowledge-infra-builder`.
+
+- Manter a knowledge base file-first como fonte canonica.
+- Nunca gravar tokens ou owner keys em Markdown.
+- Planejar providers remotos sem executar escrita externa sem confirmacao.
+- Separar memoria local, personalidade e knowledge compartilhado.

package/runtime/agents/knowledge-infra-builder/README.md

@@ -0,0 +1,8 @@
+# knowledge-infra-builder
+
+Agente especialista em criar e diagnosticar a infraestrutura file-first da
+knowledge base compartilhada do Agent DevKit.
+
+Ele prepara a estrutura `knowledge-base/`, manifesta politicas, tokens por
+referencia segura e indice lexical local. Providers remotos continuam opt-in e
+nao sao acionados por padrao.

package/runtime/agents/knowledge-infra-builder/agent.yaml

@@ -0,0 +1,38 @@
+id: knowledge-infra-builder
+kind: specialist-agent
+name: Knowledge Infra Builder
+version: 0.3.0
+status: draft
+owner: agent-devkit
+
+purpose: >
+  Criar, validar e diagnosticar a infraestrutura file-first de bases de
+  conhecimento compartilhadas, mantendo tokens em referencias seguras e
+  providers remotos como opt-in.
+
+routing:
+  anchors:
+    - knowledge-base create
+    - criar base de conhecimento
+    - infraestrutura de knowledge
+  keywords:
+    - knowledge-base
+    - storage
+    - provider
+    - tokens
+    - indexes
+  intents:
+    - knowledge.infra.create
+    - knowledge.infra.diagnose
+
+default_context:
+  - knowledge/system.md
+  - knowledge/context.md
+
+capabilities:
+  - create-knowledge-base
+
+write_policy:
+  external_writes: blocked_by_default
+  default_mode: local_config_write
+  blocks_on_high_risk: confirm

package/runtime/agents/knowledge-infra-builder/capabilities/create-knowledge-base/capability.yaml

@@ -0,0 +1,30 @@
+id: knowledge-infra-builder.create-knowledge-base
+kind: capability
+name: Create knowledge base
+version: 0.3.0
+status: draft
+purpose: Criar ou planejar a estrutura canonica `knowledge-base/` com tokens por referencia segura.
+entrypoint:
+  workflow: workflow.md
+write_policy: local_config_write
+inputs:
+  type: object
+  properties:
+    provider:
+      type: string
+    name:
+      type: string
+    dry_run:
+      type: boolean
+outputs:
+  type: object
+  artifacts:
+    - path: knowledge-base/kb.yaml
+      kind: markdown
+      sensitive: false
+routing:
+  anchors:
+    - knowledge-base create
+    - criar knowledge base
+  intents:
+    - knowledge.infra.create

package/runtime/agents/knowledge-infra-builder/capabilities/create-knowledge-base/decision-rules.md

@@ -0,0 +1,6 @@
+# Regras De Decisao
+
+- Criar somente estrutura file-first local sem confirmacao extra.
+- Providers remotos devem ser planejados ou exigir opt-in explicito.
+- Tokens devem aparecer apenas como `secret-ref`, nunca como valor bruto.
+- Indices vetoriais sao derivados e opcionais; o indice lexical local e o minimo.

package/runtime/agents/knowledge-infra-builder/capabilities/create-knowledge-base/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Validar se ja existe `knowledge-base/kb.yaml`.
+2. Definir provider local por padrao ou planejar provider remoto solicitado.
+3. Criar diretorios canonicos, politicas iniciais e manifesto.
+4. Gerar referencias separadas para read, contribute, review, admin e owner.
+5. Inicializar indice lexical vazio e diagnostico da base.

package/runtime/agents/knowledge-infra-builder/infra/.gitkeep

@@ -0,0 +1 @@
+