agent-devkit 0.1.6 → 0.3.0

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

package/runtime/agents/notification-operator/capabilities/format-task-completion-notification/decision-rules.md

@@ -0,0 +1,7 @@
+# Decision Rules
+
+- Nunca enviar notificacao nesta capability.
+- Usar `task.completed` quando o evento nao for informado.
+- Redigir segredos em `summary`, `artifact` e `next_step`.
+- Retornar `notification-event` mesmo quando o evento representar falha,
+  bloqueio ou artefato gerado.

package/runtime/agents/notification-operator/capabilities/format-task-completion-notification/runner.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""Runner for notification-operator/format-task-completion-notification."""
+
+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 format_notification_event  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Format a canonical task notification")
+    parser.add_argument("--summary", required=True)
+    parser.add_argument("--event", default="task.completed")
+    parser.add_argument("--status")
+    parser.add_argument("--task-id")
+    parser.add_argument("--title", default="Agent DevKit")
+    parser.add_argument("--artifact", action="append", default=[])
+    parser.add_argument("--next-step", action="append", default=[])
+    parser.add_argument("--severity", default="info")
+    parser.add_argument("--sensitive", action="store_true")
+    args = parser.parse_args()
+    result = format_notification_event(
+        {
+            "event": args.event,
+            "status": args.status,
+            "task_id": args.task_id,
+            "title": args.title,
+            "summary": args.summary,
+            "artifacts": args.artifact,
+            "next_steps": args.next_step,
+            "severity": args.severity,
+            "sensitive": args.sensitive,
+            "origin": "core",
+        }
+    )
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/agents/notification-operator/capabilities/format-task-completion-notification/workflow.md

@@ -0,0 +1,6 @@
+# Workflow
+
+1. Receber campos do evento de tarefa.
+2. Normalizar evento, severidade, status e listas.
+3. Redigir possiveis segredos.
+4. Retornar JSON canonico sem enviar notificacao.

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

@@ -0,0 +1,27 @@
+id: notification-operator.send-task-completion-notification
+kind: capability
+name: Send Task Completion Notification
+version: 0.1.0
+status: draft
+purpose: Enviar notificacao local de tarefa usando o contrato canonico.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+inputs:
+  required:
+    - summary
+    - confirm
+  optional:
+    - event
+    - status
+    - task_id
+    - title
+    - channel
+    - artifact
+    - next_step
+    - severity
+    - sensitive
+outputs:
+  artifacts:
+    - notification-delivery.json
+write_policy: confirm

package/runtime/agents/notification-operator/capabilities/send-task-completion-notification/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Envio exige `--confirm`.
+- Canais locais suportados sao `desktop`, `terminal`, `stdout` e `audit`.
+- Canais remotos devem retornar estado controlado, sem tentar envio real.
+- Falha de entrega nao deve ocultar payload canonico nem historico local.

package/runtime/agents/notification-operator/capabilities/send-task-completion-notification/runner.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""Runner for notification-operator/send-task-completion-notification."""
+
+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 send_notification  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Send a canonical task notification")
+    parser.add_argument("--summary", required=True)
+    parser.add_argument("--event", default="task.completed")
+    parser.add_argument("--status")
+    parser.add_argument("--task-id")
+    parser.add_argument("--title", default="Agent DevKit")
+    parser.add_argument("--channel", action="append", default=[])
+    parser.add_argument("--artifact", action="append", default=[])
+    parser.add_argument("--next-step", action="append", default=[])
+    parser.add_argument("--severity", default="info")
+    parser.add_argument("--sensitive", action="store_true")
+    parser.add_argument("--confirm", action="store_true")
+    args = parser.parse_args()
+    if not args.confirm:
+        print(
+            json.dumps(
+                {
+                    "kind": "task-notification-send",
+                    "status": "needs-confirmation",
+                    "ok": False,
+                    "message": "Sending notifications requires --confirm.",
+                    "write_policy": "confirm",
+                },
+                ensure_ascii=False,
+                indent=2,
+            )
+        )
+        return 2
+    result = send_notification(
+        {
+            "event": args.event,
+            "status": args.status,
+            "task_id": args.task_id,
+            "title": args.title,
+            "summary": args.summary,
+            "artifacts": args.artifact,
+            "next_steps": args.next_step,
+            "severity": args.severity,
+            "sensitive": args.sensitive,
+            "origin": "core",
+        },
+        force=True,
+        channels=args.channel or ["desktop"],
+    )
+    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/send-task-completion-notification/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Exigir confirmacao explicita antes de enviar.
+2. Normalizar payload canonico.
+3. Enviar apenas para canais locais suportados.
+4. Registrar tentativa no historico local de notificacoes.
+5. Retornar status de entrega sem falhar silenciosamente.

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

@@ -0,0 +1,6 @@
+# Infra
+
+Este agente usa diretamente o modulo local `cli.aikit.notifications`.
+
+Integracoes remotas futuras devem viver em `infra/integrations/<provider>/` e
+ser expostas por capabilities separadas com politica de escrita explicita.

package/runtime/agents/notification-operator/knowledge/context.md

@@ -0,0 +1,10 @@
+# Contexto
+
+O runtime suporta canais locais `desktop`, `terminal`, `stdout` e `audit`.
+`local` e alias de `desktop`; `console` e alias de `stdout`.
+
+Canais remotos como Slack, Teams, WhatsApp, webhooks e MCP gateway aparecem no
+catalogo como possibilidades futuras, mas nao sao implementados por este agente.
+
+O payload canonico contem `event`, `status`, `task_id`, `title`, `summary`,
+`artifacts`, `next_steps`, `severity`, `sensitive` e `origin`.

package/runtime/agents/notification-operator/knowledge/policies.yaml

@@ -0,0 +1,9 @@
+policies:
+  - id: notification.payload.canonical
+    rule: Sempre usar o contrato canonico de notificacao do runtime.
+  - id: notification.secrets.redaction
+    rule: Redigir segredos antes de renderizar, enviar ou registrar historico.
+  - id: notification.remote.blocked
+    rule: Nao enviar para canais remotos ate existir provider dedicado e permissao explicita.
+  - id: notification.local.best-effort
+    rule: Falha de notificacao local nao deve falhar a tarefa original.

package/runtime/agents/notification-operator/knowledge/system.md

@@ -0,0 +1,7 @@
+# System
+
+Voce e o Notification Operator do Agent DevKit.
+
+Sua funcao e transformar eventos de tarefas em notificacoes pequenas,
+redigidas e previsiveis. O agente nao decide tarefas de negocio, nao executa
+automacoes e nao envia mensagens remotas sem provider explicito.

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

@@ -0,0 +1,6 @@
+# Templates
+
+Diretorio reservado para templates de notificacao do `notification-operator`.
+
+Os formatos executaveis atuais vivem nas capabilities do agente; este arquivo
+mantem o contrato estrutural versionado para validacao e empacotamento.

package/runtime/agents/notification-operator/tests/test_runners.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Runner contracts for notification-operator."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+FORMAT_RUNNER = ROOT / "notification-operator" / "capabilities" / "format-task-completion-notification" / "runner.py"
+SEND_RUNNER = ROOT / "notification-operator" / "capabilities" / "send-task-completion-notification" / "runner.py"
+CONFIGURE_RUNNER = ROOT / "notification-operator" / "capabilities" / "configure-notification-channel" / "runner.py"
+RUNNER_TIMEOUT_SECONDS = int(os.environ.get("AI_DEVKIT_TEST_RUNNER_TIMEOUT_SECONDS", "60"))
+
+
+class NotificationOperatorRunnerTest(unittest.TestCase):
+    def run_python(self, script: Path, *args: str, env: dict[str, str]) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            [sys.executable, str(script), *args],
+            cwd=ROOT.parents[0],
+            env=os.environ | env,
+            check=False,
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            timeout=RUNNER_TIMEOUT_SECONDS,
+        )
+
+    def test_format_runner_returns_canonical_event(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            result = self.run_python(
+                FORMAT_RUNNER,
+                "--summary",
+                "done",
+                "--event",
+                "task.completed",
+                "--task-id",
+                "t1",
+                env={"AI_DEVKIT_CONFIG_HOME": tmpdir},
+            )
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        payload = json.loads(result.stdout)
+        self.assertEqual(payload["kind"], "notification-event")
+        self.assertEqual(payload["status"], "ok")
+        self.assertEqual(payload["task_id"], "t1")
+
+    def test_send_runner_requires_confirmation(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            result = self.run_python(
+                SEND_RUNNER,
+                "--summary",
+                "done",
+                "--channel",
+                "terminal",
+                env={"AI_DEVKIT_CONFIG_HOME": tmpdir},
+            )
+
+        self.assertEqual(result.returncode, 2)
+        payload = json.loads(result.stdout)
+        self.assertEqual(payload["status"], "needs-confirmation")
+        self.assertEqual(payload["write_policy"], "confirm")
+
+    def test_send_runner_can_send_terminal_when_confirmed(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            result = self.run_python(
+                SEND_RUNNER,
+                "--summary",
+                "done",
+                "--channel",
+                "terminal",
+                "--confirm",
+                env={"AI_DEVKIT_CONFIG_HOME": tmpdir},
+            )
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        payload = json.loads(result.stdout)
+        self.assertEqual(payload["status"], "sent")
+        self.assertEqual(payload["channel"], "terminal")
+
+    def test_configure_runner_configures_terminal_channel(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            result = self.run_python(
+                CONFIGURE_RUNNER,
+                "--channel",
+                "terminal",
+                "--enabled",
+                "true",
+                "--event-filter",
+                "task.completed",
+                env={"AI_DEVKIT_CONFIG_HOME": tmpdir},
+            )
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        payload = json.loads(result.stdout)
+        self.assertEqual(payload["status"], "configured")
+        self.assertEqual(payload["channel"], "terminal")
+        self.assertTrue(payload["channel_config"]["enabled"])
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,23 @@
+# AGENTS.md
+
+Instrucoes locais para trabalhar no agente `playwright-automation-builder`.
+
+## Escopo
+
+Este agente planeja, gera, revisa, executa checks locais controlados e empacota
+automacoes Playwright para web moderna.
+
+## Fronteiras
+
+- Selenium/WebDriver legado pertence ao `selenium-automation-builder`.
+- Automacoes desktop visuais pertencem ao `pyautogui-automation-builder`.
+- Automacoes Python sem browser pertencem ao `python-automation-builder`.
+- Execucao com side effects reais exige dry-run revisado e confirmacao.
+
+## Guardrails
+
+- Nunca hardcodar credenciais.
+- Nunca versionar `storage_state` sensivel.
+- Preferir seletores por role, label, text controlado ou test id.
+- Evitar coordenadas, sleeps fixos, XPath absoluto e classes geradas.
+- Capturar screenshots/traces como artifacts revisaveis.

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

@@ -0,0 +1,43 @@
+# Playwright Automation Builder
+
+Especialista em automacoes web modernas com Playwright.
+
+## Capabilities
+
+- `plan-playwright-automation`: planeja contrato, riscos, seletores e artifacts.
+- `generate-playwright-script`: gera script Python Playwright em output-only.
+- `generate-playwright-project-files`: planeja ou grava pacote local no projeto alvo.
+- `run-playwright-check`: executa check local somente quando confirmado.
+- `review-playwright-artifacts`: revisa screenshots, traces, logs e relatorios.
+- `wrap-playwright-as-capability`: empacota automacao como capability local.
+
+## Spec Minima
+
+```yaml
+automation_name: Login Smoke Check
+purpose: Validar que a tela de login renderiza e exibe o botao Entrar.
+target_url: https://example.test/login
+browser: chromium
+auth_strategy: none
+side_effects: read-only
+selectors:
+  - name: submit
+    kind: role
+    value: button
+    name_value: Entrar
+steps:
+  - open target_url
+  - assert submit visible
+assertions:
+  - submit visible
+artifacts:
+  - screenshot
+  - trace
+quality_gates:
+  - selectors prefer accessible roles
+```
+
+## Politica
+
+Playwright e o caminho preferencial para web moderna sem requisito de
+WebDriver/Grid. Selenium permanece para legado ou compatibilidade especifica.