agent-devkit 0.1.6 → 0.2.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-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/local-llm-operator/agent.yaml

@@ -10,6 +10,9 @@ purpose: >
   repetitivas, mantendo coordenadores principais responsaveis por decisao,
   especificacao e revisao.
 
+runtime_role:
+  kind: local-worker
+
 default_context:
   - knowledge/system.md
   - knowledge/context.md
@@ -20,7 +23,6 @@ capabilities:
   - delegate-operational-task
 
 write_policy:
-  external_writes: never
-  default_mode: operational-worker
-  requires_coordinator_review: true
-
+  external_writes: blocked_by_default
+  default_mode: delegated
+  requires_coordinator_review: confirm

package/runtime/agents/local-llm-operator/capabilities/delegate-operational-task/capability.yaml

@@ -4,7 +4,7 @@ name: Delegate Operational Task
 version: 0.1.6
 status: draft
 purpose: Delegar uma tarefa operacional a modelo local e retornar resultado revisavel.
-write_policy: read-only
+write_policy: read_only
 entrypoint:
   workflow: workflow.md
 inputs:
@@ -12,4 +12,3 @@ inputs:
   optional: [model]
 outputs:
   artifacts: [delegated-result]
-

package/runtime/agents/local-llm-operator/capabilities/inspect-local-models/capability.yaml

@@ -4,7 +4,7 @@ name: Inspect Local Models
 version: 0.1.6
 status: draft
 purpose: Diagnosticar disponibilidade de Ollama e modelos locais instalados.
-write_policy: read-only
+write_policy: read_only
 entrypoint:
   workflow: workflow.md
 inputs:
@@ -12,4 +12,3 @@ inputs:
   optional: [model]
 outputs:
   artifacts: [local-model-report]
-

package/runtime/agents/local-llm-operator/capabilities/select-local-worker/capability.yaml

@@ -4,7 +4,7 @@ name: Select Local Worker
 version: 0.1.6
 status: draft
 purpose: Escolher se uma tarefa operacional pode ser delegada a LLM local.
-write_policy: read-only
+write_policy: read_only
 entrypoint:
   workflow: workflow.md
 inputs:
@@ -12,4 +12,3 @@ inputs:
   optional: [model_plan]
 outputs:
   artifacts: [local-worker-selection]
-

package/runtime/agents/n1-support-agent/agent.yaml

@@ -30,6 +30,35 @@ depends_on_agents:
   - aws-cloudwatch-log-analyzer
   - elasticsearch-log-analyzer
 
+agent_mode:
+  type: workflow
+  max_steps: 13
+  max_specialists: 13
+  max_llm_calls: 1
+  timeout_seconds: 600
+  can_call_capabilities: true
+  can_call_llm: optional
+  can_request_user_input: true
+  external_writes: false
+  allowed_capabilities:
+    - azure-devops-orchestrator/read-card
+    - azure-devops-orchestrator/update-card-tags
+    - azure-devops-orchestrator/move-card
+    - sqlserver-data-analyzer/run-readonly-query
+    - sqlserver-data-analyzer/trace-record
+    - bpo-analyser/analyze-proposal
+    - bpo-analyser/analyze-cpf-proposals
+    - bpo-analyser/find-latest-proposal-by-cpf
+    - bpo-analyser/consult-attached-documents
+    - n1-support-agent/route-customer-symptom
+    - topdesk-orchestrator/read-incident
+    - aws-cloudwatch-log-analyzer/search-log-events
+    - elasticsearch-log-analyzer/search-log-events
+  stop_conditions:
+    - needs-input
+    - blocked
+    - max-steps
+
 capabilities:
   - execute-n1-card-runbook
   - extract-card-entities
@@ -65,7 +94,17 @@ agent_surface:
     - knowledge/policies.yaml
 
 write_policy:
-  read_operations: auto
+  read_operations: read_only
   azure_tag_operations: confirm
   azure_move_operations: confirm
   external_mutations: confirm
+
+routing:
+  anchors:
+    - n1
+    - primeiro nivel
+    - suporte
+    - triagem
+  intents:
+    - support.n1
+  priority: 80

package/runtime/agents/n2-support-agent/agent.yaml

@@ -29,6 +29,34 @@ depends_on_agents:
   - aws-cloudwatch-log-analyzer
   - elasticsearch-log-analyzer
 
+agent_mode:
+  type: workflow
+  max_steps: 15
+  max_specialists: 12
+  max_llm_calls: 1
+  timeout_seconds: 900
+  can_call_capabilities: true
+  can_call_llm: optional
+  can_request_user_input: true
+  external_writes: false
+  allowed_capabilities:
+    - n1-support-agent/execute-n1-card-runbook
+    - azure-devops-orchestrator/read-card
+    - azure-devops-orchestrator/comment-card
+    - azure-devops-orchestrator/update-card-tags
+    - azure-devops-orchestrator/move-card
+    - azure-devops-orchestrator/assign-card
+    - azure-devops-orchestrator/attach-file
+    - bpo-analyser/analyze-proposal
+    - postgres-data-analyzer/run-readonly-query
+    - sqlserver-data-analyzer/run-readonly-query
+    - aws-cloudwatch-log-analyzer/search-log-events
+    - elasticsearch-log-analyzer/search-log-events
+  stop_conditions:
+    - needs-input
+    - blocked
+    - max-steps
+
 capabilities:
   - execute-n2-investigation
   - load-support-context
@@ -66,10 +94,21 @@ agent_surface:
     - knowledge/policies.yaml
 
 write_policy:
-  read_operations: auto
-  local_patch_plan: auto
+  read_operations: read_only
+  local_patch_plan: read_only
   azure_comment_operations: confirm
   azure_tag_operations: confirm
   azure_move_operations: confirm
   azure_attachment_operations: confirm
   external_mutations: confirm
+
+routing:
+  anchors:
+    - causa raiz
+    - n2
+    - patch
+    - root cause
+    - segundo nivel
+  intents:
+    - support.n2
+  priority: 80

package/runtime/agents/n2-support-agent/knowledge/policies.yaml

@@ -39,5 +39,5 @@ privacy:
   avoid_raw_personal_data_dumps: true
 
 write_policy:
-  azure_requires_execute: true
-  local_file_write_allowed_when_output_present: true
+  azure_requires_execute: confirm
+  local_file_write_allowed_when_output_present: confirm

package/runtime/agents/notification-operator/AGENTS.md

@@ -0,0 +1,11 @@
+# AGENTS.md
+
+Instrucoes especificas para o agente `notification-operator`.
+
+- Mantenha notificacoes como contrato runtime pequeno, deterministico e seguro.
+- Nao implemente canais remotos reais nesta fase; Slack, Teams, WhatsApp,
+  webhooks e MCP gateways ficam apenas como canais futuros ate existir provider
+  dedicado.
+- Payloads devem seguir o evento canonico exposto por `cli.aikit.notifications`.
+- Escritas locais de configuracao exigem capability explicita e nao devem
+  armazenar segredos.

package/runtime/agents/notification-operator/README.md

@@ -0,0 +1,15 @@
+# Notification Operator
+
+Agente runtime para formatar, enviar e configurar notificacoes locais de tarefas
+do Agent DevKit.
+
+Ele padroniza eventos como `task.completed`, `task.failed`, `task.blocked`,
+`wizard.waiting`, `review.required` e `artifact.generated`, mantendo canais
+remotos fora do escopo ate haver provider dedicado.
+
+## Capabilities
+
+- `format-task-completion-notification`: normaliza o payload canonico sem enviar
+  nada.
+- `send-task-completion-notification`: envia notificacao local apos confirmacao.
+- `configure-notification-channel`: configura canais locais suportados.

package/runtime/agents/notification-operator/agent.yaml

@@ -0,0 +1,43 @@
+id: notification-operator
+kind: runtime-agent
+name: Notification Operator
+version: 0.1.0
+status: draft
+owner: agent-devkit
+purpose: >
+  Padronizar, enviar e configurar notificacoes locais de conclusao, falha,
+  bloqueio e eventos operacionais de tarefas do Agent DevKit.
+runtime_role:
+  kind: local-worker
+  scope: runtime-notifications
+default_context:
+  - knowledge/system.md
+  - knowledge/context.md
+  - knowledge/policies.yaml
+env:
+  required: []
+  optional: []
+capabilities:
+  - format-task-completion-notification
+  - send-task-completion-notification
+  - configure-notification-channel
+agent_surface:
+  repositories: []
+  policies:
+    - knowledge/policies.yaml
+write_policy:
+  format: read_only
+  send: confirm
+  configure: local_config_write
+  remote_channels: blocked_by_default
+routing:
+  anchors:
+    - notification-operator
+    - notifications
+    - task-notification
+    - completion-notification
+  intents:
+    - notification.format
+    - notification.send
+    - notification.configure
+  priority: 70

package/runtime/agents/notification-operator/capabilities/configure-notification-channel/capability.yaml

@@ -0,0 +1,19 @@
+id: notification-operator.configure-notification-channel
+kind: capability
+name: Configure Notification Channel
+version: 0.1.0
+status: draft
+purpose: Configurar canais locais de notificacao do Agent DevKit.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+inputs:
+  required:
+    - channel
+  optional:
+    - enabled
+    - event_filter
+outputs:
+  artifacts:
+    - notification-channel-config.json
+write_policy: local_config_write

package/runtime/agents/notification-operator/capabilities/configure-notification-channel/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Configurar apenas canais locais suportados.
+- Nao persistir segredos nem tokens.
+- `local` deve ser tratado como alias de `desktop`.
+- Filtros de evento devem usar somente eventos suportados pelo runtime.

package/runtime/agents/notification-operator/capabilities/configure-notification-channel/runner.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""Runner for notification-operator/configure-notification-channel."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+ROOT = Path(__file__).resolve().parents[4]
+sys.path.insert(0, str(ROOT))
+
+from cli.aikit.notifications import configure_notification_channel  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Configure a local notification channel")
+    parser.add_argument("--channel", required=True)
+    parser.add_argument("--enabled", choices=["true", "false"])
+    parser.add_argument("--event-filter", action="append", default=[])
+    args = parser.parse_args()
+    enabled = None
+    if args.enabled is not None:
+        enabled = args.enabled == "true"
+    result = configure_notification_channel(args.channel, enabled=enabled, events=args.event_filter or None)
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0 if result.get("ok") is not False else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/agents/notification-operator/capabilities/configure-notification-channel/workflow.md

@@ -0,0 +1,6 @@
+# Workflow
+
+1. Validar canal informado.
+2. Aplicar `enabled` e filtros de eventos quando fornecidos.
+3. Persistir apenas configuracao local sem segredos.
+4. Retornar caminho do arquivo e configuracao efetiva.

package/runtime/agents/notification-operator/capabilities/format-task-completion-notification/capability.yaml

@@ -0,0 +1,25 @@
+id: notification-operator.format-task-completion-notification
+kind: capability
+name: Format Task Completion Notification
+version: 0.1.0
+status: draft
+purpose: Normalizar payload canonico de notificacao sem executar envio.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+inputs:
+  required:
+    - summary
+  optional:
+    - event
+    - status
+    - task_id
+    - title
+    - artifact
+    - next_step
+    - severity
+    - sensitive
+outputs:
+  artifacts:
+    - notification-event.json
+write_policy: read_only