agent-devkit 0.1.6 → 0.2.0

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.

package/runtime/agents/playwright-automation-builder/agent.yaml

@@ -0,0 +1,48 @@
+id: playwright-automation-builder
+kind: specialist-agent
+name: Playwright Automation Builder
+version: 0.1.0
+status: draft
+owner: agent-devkit
+purpose: >
+  Planejar, gerar, revisar, executar checks controlados e empacotar automacoes
+  Playwright para web moderna com screenshots, traces e guardrails.
+default_context:
+  - knowledge/system.md
+  - knowledge/context.md
+  - knowledge/policies.yaml
+env:
+  required: []
+  optional: []
+capabilities:
+  - plan-playwright-automation
+  - generate-playwright-script
+  - generate-playwright-project-files
+  - run-playwright-check
+  - review-playwright-artifacts
+  - wrap-playwright-as-capability
+agent_surface:
+  repositories:
+    - infra/integrations/playwright-automation/playwright_automation_repository.py
+  policies:
+    - knowledge/policies.yaml
+write_policy:
+  planning: read_only
+  generation: output_only
+  project_files: local_write
+  run_check: confirm
+  artifact_review: read_only
+  capability_wrapper: local_write
+  external_side_effects: blocked_by_default
+routing:
+  anchors:
+    - playwright-automation-builder
+    - playwright
+    - browser-automation
+    - web-automation
+  intents:
+    - playwright-automation.plan
+    - playwright-automation.generate
+    - playwright-automation.check
+    - playwright-automation.review
+  priority: 55

package/runtime/agents/playwright-automation-builder/capabilities/generate-playwright-project-files/capability.yaml

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

package/runtime/agents/playwright-automation-builder/capabilities/generate-playwright-project-files/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Escrita local deve ficar dentro de `target_project`.
+- Dry-run e o modo padrao.
+- Overwrite exige permissao explicita.
+- A capability nao executa browser.

package/runtime/agents/playwright-automation-builder/capabilities/generate-playwright-project-files/runner.py

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

@@ -0,0 +1,6 @@
+# Workflow
+
+1. Validar spec e `target_project`.
+2. Planejar arquivos por padrao.
+3. Escrever somente com `--execute`.
+4. Bloquear overwrite sem `--allow-overwrite`.

package/runtime/agents/playwright-automation-builder/capabilities/generate-playwright-script/capability.yaml

@@ -0,0 +1,18 @@
+id: playwright-automation-builder.generate-playwright-script
+kind: capability
+name: Generate Playwright Script
+version: 0.1.0
+status: draft
+purpose: Gerar script Playwright Python em output-only.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  output_template: ../../templates/playwright-automation.py
+inputs:
+  required:
+    - spec
+  optional: []
+outputs:
+  artifacts:
+    - playwright_automation.py
+write_policy: output_only

package/runtime/agents/playwright-automation-builder/capabilities/generate-playwright-script/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Nao escrever arquivos.
+- Nao executar browser.
+- O script gerado deve compilar sem Playwright instalado enquanto estiver em dry-run.
+- Credenciais devem ser referenciadas por env/storage state local, nunca embutidas.

package/runtime/agents/playwright-automation-builder/capabilities/generate-playwright-script/runner.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""Runner for playwright-automation-builder/generate-playwright-script."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "playwright-automation"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from playwright_automation_repository import PlaywrightAutomationError, PlaywrightAutomationRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate a Playwright automation script")
+    parser.add_argument("--spec", required=True)
+    args = parser.parse_args()
+    try:
+        result = PlaywrightAutomationRepository().generate_playwright_script(spec_path=Path(args.spec))
+    except PlaywrightAutomationError 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/playwright-automation-builder/capabilities/generate-playwright-script/workflow.md

@@ -0,0 +1,6 @@
+# Workflow
+
+1. Validar a spec pelo plano Playwright.
+2. Gerar script Python sem escrever no projeto.
+3. Expor dry-run, execute, confirm, browser, timeout, screenshots e traces.
+4. Retornar conteudo como artifact output-only.

package/runtime/agents/playwright-automation-builder/capabilities/plan-playwright-automation/capability.yaml

@@ -0,0 +1,18 @@
+id: playwright-automation-builder.plan-playwright-automation
+kind: capability
+name: Plan Playwright Automation
+version: 0.1.0
+status: draft
+purpose: Planejar automacao Playwright sem escrever arquivos nem abrir browser.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  output_template: ../../templates/playwright-readme.md
+inputs:
+  required:
+    - spec
+  optional: []
+outputs:
+  artifacts:
+    - playwright-automation-plan.json
+write_policy: read_only

package/runtime/agents/playwright-automation-builder/capabilities/plan-playwright-automation/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- `read-only` sempre planeja sem abrir navegador.
+- Seletores por role, label, text ou test id sao preferenciais.
+- CSS e XPath absoluto exigem warning ou refinamento.
+- Side effects reais nao sao executados nesta capability.

package/runtime/agents/playwright-automation-builder/capabilities/plan-playwright-automation/runner.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""Runner for playwright-automation-builder/plan-playwright-automation."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "playwright-automation"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from playwright_automation_repository import PlaywrightAutomationError, PlaywrightAutomationRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Plan a Playwright automation")
+    parser.add_argument("--spec", required=True)
+    args = parser.parse_args()
+    try:
+        result = PlaywrightAutomationRepository().plan_playwright_automation(spec_path=Path(args.spec))
+    except PlaywrightAutomationError 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/playwright-automation-builder/capabilities/plan-playwright-automation/workflow.md

@@ -0,0 +1,6 @@
+# Workflow
+
+1. Ler spec Playwright.
+2. Validar alvo, browser, auth, side effects, seletores, passos e assertions.
+3. Bloquear segredos hardcoded.
+4. Retornar plano, artifacts previstos, guardrails e perguntas pendentes.