agent-devkit 0.1.6 → 0.2.0

package/runtime/agents/automation-architect/tests/test_runners.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Tests for automation-architect runners and repository."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import subprocess
+import sys
+import unittest
+from pathlib import Path
+
+from cli.aikit.orchestrator import build_execution_plan
+
+
+ROOT = Path(__file__).resolve().parents[3]
+AGENT = ROOT / "agent"
+AGENT_DIR = ROOT / "agents" / "automation-architect"
+REPOSITORY_PATH = AGENT_DIR / "infra" / "integrations" / "automation-architecture" / "automation_architecture_repository.py"
+
+
+def load_repository_class():
+    spec = importlib.util.spec_from_file_location("automation_architecture_repository", REPOSITORY_PATH)
+    if spec is None or spec.loader is None:
+        raise RuntimeError("Could not load automation architecture repository")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module.AutomationArchitectureRepository
+
+
+AutomationArchitectureRepository = load_repository_class()
+
+
+class AutomationArchitectTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.repository = AutomationArchitectureRepository()
+
+    def test_classifies_api_and_file_automation_as_python(self) -> None:
+        result = self.repository.classify_automation_request(
+            request="Automatize a coleta via API REST e salve o resultado em CSV local."
+        )
+
+        self.assertEqual(result["status"], "ok")
+        self.assertEqual(result["automation_type"], "python")
+        self.assertEqual(result["recommended_agent"], "python-automation-builder")
+        self.assertTrue(result["available_delegate"])
+
+    def test_explicit_selenium_requirement_wins_over_generic_web(self) -> None:
+        result = self.repository.classify_automation_request(
+            request="Automatize login web legado usando Selenium WebDriver e grid."
+        )
+
+        self.assertEqual(result["automation_type"], "selenium")
+        self.assertEqual(result["recommended_capability"], "plan-selenium-automation")
+
+    def test_web_without_api_recommends_playwright_builder(self) -> None:
+        result = self.repository.classify_automation_request(
+            request="Automatize preenchimento de formulario em site sem API documentada."
+        )
+
+        self.assertEqual(result["automation_type"], "playwright")
+        self.assertTrue(result["available_delegate"])
+        self.assertEqual(result["recommended_agent"], "playwright-automation-builder")
+        self.assertEqual(result["recommended_capability"], "plan-playwright-automation")
+
+    def test_desktop_visual_automation_requires_confirmation(self) -> None:
+        result = self.repository.classify_automation_request(
+            request="Automatize cliques na janela desktop com mouse e screenshots."
+        )
+
+        self.assertEqual(result["automation_type"], "pyautogui")
+        self.assertTrue(result["requires_confirmation"])
+        self.assertIn("desktop visual automation is fragile and must be a last resort", result["risks"])
+
+    def test_delegation_is_manual_contract_only(self) -> None:
+        result = self.repository.delegate_automation_build(
+            request="Automatize leitura de arquivos CSV locais com script Python."
+        )
+
+        self.assertEqual(result["kind"], "automation-delegation")
+        self.assertTrue(result["manual_only"])
+        self.assertEqual(result["delegation"]["agent_id"], "python-automation-builder")
+        self.assertIn("agent run python-automation-builder plan-python-automation", result["delegation"]["manual_command"])
+
+    def test_playwright_delegation_contract_points_to_builder(self) -> None:
+        result = self.repository.delegate_automation_build(
+            request="Automatize um smoke test web com Playwright para validar formulario de login."
+        )
+
+        self.assertEqual(result["kind"], "automation-delegation")
+        self.assertEqual(result["delegation"]["agent_id"], "playwright-automation-builder")
+        self.assertEqual(result["delegation"]["capability_id"], "plan-playwright-automation")
+        self.assertIn("agent run playwright-automation-builder plan-playwright-automation", result["delegation"]["manual_command"])
+
+    def test_plan_without_request_returns_needs_input(self) -> None:
+        result = self.repository.plan_automation_solution()
+
+        self.assertEqual(result["status"], "needs-input")
+        self.assertEqual(result["missing_fields"], ["request"])
+
+    def test_generic_automation_prompt_routes_to_architect(self) -> None:
+        plan = build_execution_plan(ROOT, "Automatize esta tarefa operacional escolhendo a melhor tecnologia.", dry_run=True)
+
+        self.assertEqual(plan["routing_decision"]["selected_agent_id"], "automation-architect")
+        self.assertEqual(plan["domain_agent"]["id"], "automation-architect")
+
+    def test_classify_runner_is_executable_through_agent_cli(self) -> None:
+        result = subprocess.run(
+            [
+                str(AGENT),
+                "--json",
+                "run",
+                "automation-architect",
+                "classify-automation-request",
+                "--request",
+                "Automatize coleta via API REST e gere JSON local.",
+            ],
+            cwd=ROOT,
+            check=False,
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            timeout=30,
+        )
+
+        self.assertEqual(result.returncode, 0, result.stderr)
+        payload = json.loads(result.stdout)
+        self.assertEqual(payload["status"], "ok")
+        runner_payload = json.loads(payload["stdout"])
+        self.assertEqual(runner_payload["automation_type"], "python")
+        self.assertEqual(runner_payload["recommended_agent"], "python-automation-builder")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/runtime/agents/aws-architecture-analyst/agent.yaml

@@ -52,7 +52,20 @@ agent_surface:
     - ../../vendor/skills/CATALOG.md
 
 write_policy:
-  read_operations: auto
-  artifact_generation: auto
-  aws_mutations: unsupported
-  external_side_effects: unsupported
+  read_operations: read_only
+  artifact_generation: read_only
+  aws_mutations: blocked_by_default
+  external_side_effects: blocked_by_default
+
+routing:
+  anchors:
+    - architecture
+    - arquitetura
+    - aws
+    - observability
+    - resiliencia
+    - vpc
+    - workload
+  intents:
+    - aws.architecture.analysis
+  priority: 50

package/runtime/agents/aws-cloudwatch-log-analyzer/agent.yaml

@@ -49,5 +49,15 @@ agent_surface:
     - knowledge/policies.yaml
 
 write_policy:
-  read_operations: auto
-  write_operations: unsupported
+  read_operations: read_only
+  write_operations: blocked_by_default
+
+routing:
+  anchors:
+    - aws
+    - cloudwatch
+    - log
+    - logs
+  intents:
+    - logs.cloudwatch.analysis
+  priority: 60

package/runtime/agents/aws-cloudwatch-log-analyzer/capabilities/analyze-service-error/capability.yaml

@@ -39,4 +39,20 @@ integration:
   methods:
     - ../../infra/integrations/aws-cloudwatch/methods/filter-log-events.yaml
 
+runtime:
+  provider: aws
+
 write_policy: read_only
+
+routing:
+  anchors:
+    - cloudwatch
+    - erro
+    - error
+    - service
+    - servico
+  intents:
+    - logs.error-analysis
+  examples:
+    - analise logs do cloudwatch para erro no servico
+  priority: 80

package/runtime/agents/aws-lambda-builder/AGENTS.md

@@ -0,0 +1,27 @@
+# AWS Lambda Builder
+
+Instrucoes locais para trabalhar no agente `aws-lambda-builder`.
+
+## Responsabilidade
+
+Este agente planeja, gera, revisa, empacota localmente e cria planos de deploy
+para projetos AWS Lambda. Ele produz artefatos revisaveis e nao executa deploy
+real.
+
+## Fora De Escopo
+
+- Invocar Lambdas existentes: pertence ao `aws-operations-operator`.
+- Deploy real ou mutacao AWS.
+- Criar conta AWS, roles reais ou infraestrutura completa.
+- Instalar dependencias automaticamente.
+- Suporte completo a todos os runtimes ou CDK completo.
+
+## Guardrails
+
+- Deploy real e sempre fora da primeira fase.
+- Nunca chamar `aws`, `sam deploy`, `serverless deploy` ou `cdk deploy`.
+- Bloquear segredos hardcoded.
+- Bloquear IAM wildcard sem justificativa.
+- Gerar testes locais e fixtures de evento.
+- Empacotamento local deve ser dry-run por padrao.
+- Escrita local deve ficar dentro de `target_project`.

package/runtime/agents/aws-lambda-builder/README.md

@@ -0,0 +1,21 @@
+# AWS Lambda Builder
+
+Agente especialista para gerar projetos AWS Lambda seguros e revisaveis, com
+handler, fixture de evento, testes locais, template SAM, revisao de seguranca,
+empacotamento local e plano de deploy sem aplicar mudancas na AWS.
+
+## Capabilities
+
+- `plan-lambda`: planeja Lambda sem escrever arquivos.
+- `generate-lambda-project`: planeja ou escreve projeto Lambda local.
+- `review-lambda-security`: revisa IAM, secrets, env vars e configuracao.
+- `package-lambda`: empacota projeto local em zip sem publicar.
+- `deploy-lambda-plan`: gera plano de deploy sem executar.
+
+## Exemplo
+
+```bash
+./agent --json run aws-lambda-builder plan-lambda --spec lambda-spec.yaml
+```
+
+Deploy real nao e executado por este agente.

package/runtime/agents/aws-lambda-builder/agent.yaml

@@ -0,0 +1,46 @@
+id: aws-lambda-builder
+kind: specialist-agent
+name: AWS Lambda Builder
+version: 0.1.0
+status: draft
+owner: agent-devkit
+purpose: >
+  Planejar, gerar, revisar, empacotar localmente e criar planos de deploy para
+  projetos AWS Lambda seguros e revisaveis, sem executar deploy real.
+default_context:
+  - knowledge/system.md
+  - knowledge/context.md
+  - knowledge/policies.yaml
+env:
+  required: []
+  optional: []
+capabilities:
+  - plan-lambda
+  - generate-lambda-project
+  - review-lambda-security
+  - package-lambda
+  - deploy-lambda-plan
+agent_surface:
+  repositories:
+    - infra/integrations/aws-lambda/aws_lambda_repository.py
+  policies:
+    - knowledge/policies.yaml
+write_policy:
+  planning: read_only
+  project_generation: local_write
+  security_review: read_only
+  package_local: local_write
+  deploy_plan: dry_run
+  deploy_real: blocked_by_default
+routing:
+  anchors:
+    - aws-lambda-builder
+    - lambda-builder
+    - aws-lambda
+    - serverless
+    - sam
+  intents:
+    - aws.lambda.plan
+    - aws.lambda.generate
+    - aws.lambda.review
+  priority: 50

package/runtime/agents/aws-lambda-builder/capabilities/deploy-lambda-plan/capability.yaml

@@ -0,0 +1,18 @@
+id: aws-lambda-builder.deploy-lambda-plan
+kind: capability
+name: Deploy Lambda Plan
+version: 0.1.0
+status: draft
+purpose: Gerar plano de deploy AWS Lambda sem aplicar mudancas.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  output_template: ../../templates/lambda-deploy-plan.md
+inputs:
+  required:
+    - spec
+  optional: []
+outputs:
+  artifacts:
+    - lambda-deploy-plan.json
+write_policy: dry_run

package/runtime/agents/aws-lambda-builder/capabilities/deploy-lambda-plan/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Nunca executar deploy real.
+- Nao chamar AWS CLI, SAM, Serverless ou CDK.
+- Plano deve listar pre-requisitos, IAM, env vars e rollback.
+- Deploy real pertence a capability futura com `write_policy: confirm`.

package/runtime/agents/aws-lambda-builder/capabilities/deploy-lambda-plan/runner.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""Runner for aws-lambda-builder/deploy-lambda-plan."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "aws-lambda"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from aws_lambda_repository import AwsLambdaBuilderError, AwsLambdaRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate an AWS Lambda deploy plan")
+    parser.add_argument("--spec", required=True)
+    args = parser.parse_args()
+
+    try:
+        result = AwsLambdaRepository().deploy_lambda_plan(spec_path=Path(args.spec))
+    except AwsLambdaBuilderError 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/aws-lambda-builder/capabilities/deploy-lambda-plan/workflow.md

@@ -0,0 +1,6 @@
+# Workflow
+
+1. Validar spec com `plan-lambda`.
+2. Gerar comandos sugeridos e checklist sem executar.
+3. Declarar `deploy_real: false`.
+4. Incluir rollback, validacao e riscos.

package/runtime/agents/aws-lambda-builder/capabilities/generate-lambda-project/capability.yaml

@@ -0,0 +1,20 @@
+id: aws-lambda-builder.generate-lambda-project
+kind: capability
+name: Generate Lambda Project
+version: 0.1.0
+status: draft
+purpose: Planejar ou escrever projeto AWS Lambda local.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  output_template: ../../templates/lambda-readme.md
+inputs:
+  required:
+    - spec
+  optional:
+    - execute
+    - allow-overwrite
+outputs:
+  artifacts:
+    - lambda-project-files.json
+write_policy: local_write

package/runtime/agents/aws-lambda-builder/capabilities/generate-lambda-project/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Nao instalar dependencias.
+- Nao chamar AWS CLI.
+- Gerar handler, fixture de evento, teste local, README e template SAM.
+- Escrita local fica restrita ao projeto destino.

package/runtime/agents/aws-lambda-builder/capabilities/generate-lambda-project/runner.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""Runner for aws-lambda-builder/generate-lambda-project."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "aws-lambda"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from aws_lambda_repository import AwsLambdaBuilderError, AwsLambdaRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate an AWS Lambda project")
+    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 = AwsLambdaRepository().generate_lambda_project(
+            spec_path=Path(args.spec),
+            execute=args.execute,
+            allow_overwrite=args.allow_overwrite,
+        )
+    except AwsLambdaBuilderError 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/aws-lambda-builder/capabilities/generate-lambda-project/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Validar spec com `plan-lambda`.
+2. Exigir `target_project` existente.
+3. Em dry-run, retornar arquivos planejados.
+4. Com `--execute`, escrever somente dentro de `target_project`.
+5. Bloquear overwrite sem `--allow-overwrite`.

package/runtime/agents/aws-lambda-builder/capabilities/package-lambda/capability.yaml

@@ -0,0 +1,22 @@
+id: aws-lambda-builder.package-lambda
+kind: capability
+name: Package Lambda
+version: 0.1.0
+status: draft
+purpose: Empacotar projeto Lambda localmente em zip, sem deploy.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  output_template: ../../templates/lambda-package.md
+inputs:
+  required:
+    - project-path
+  optional:
+    - output-dir
+    - execute
+    - allow-overwrite
+outputs:
+  artifacts:
+    - lambda-package.json
+    - lambda.zip
+write_policy: local_write

package/runtime/agents/aws-lambda-builder/capabilities/package-lambda/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Nao instalar dependencias.
+- Nao fazer upload.
+- Nao chamar AWS CLI.
+- Excluir caches, `.git`, `.env` e artefatos temporarios.

package/runtime/agents/aws-lambda-builder/capabilities/package-lambda/runner.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""Runner for aws-lambda-builder/package-lambda."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "aws-lambda"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from aws_lambda_repository import AwsLambdaBuilderError, AwsLambdaRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Package an AWS Lambda project locally")
+    parser.add_argument("--project-path", required=True)
+    parser.add_argument("--output-dir")
+    parser.add_argument("--execute", action="store_true")
+    parser.add_argument("--allow-overwrite", action="store_true")
+    args = parser.parse_args()
+
+    try:
+        result = AwsLambdaRepository().package_lambda(
+            project_path=Path(args.project_path),
+            output_dir=Path(args.output_dir) if args.output_dir else None,
+            execute=args.execute,
+            allow_overwrite=args.allow_overwrite,
+        )
+    except AwsLambdaBuilderError 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/aws-lambda-builder/capabilities/package-lambda/workflow.md

@@ -0,0 +1,6 @@
+# Workflow
+
+1. Validar projeto local.
+2. Em dry-run, listar arquivos que entrariam no zip.
+3. Com `--execute`, gerar zip local em `output_dir`.
+4. Bloquear overwrite sem `--allow-overwrite`.

package/runtime/agents/aws-lambda-builder/capabilities/plan-lambda/capability.yaml

@@ -0,0 +1,18 @@
+id: aws-lambda-builder.plan-lambda
+kind: capability
+name: Plan Lambda
+version: 0.1.0
+status: draft
+purpose: Planejar projeto AWS Lambda sem escrever arquivos.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  output_template: ../../templates/lambda-plan.md
+inputs:
+  required:
+    - spec
+  optional: []
+outputs:
+  artifacts:
+    - lambda-plan.json
+write_policy: read_only

package/runtime/agents/aws-lambda-builder/capabilities/plan-lambda/decision-rules.md

@@ -0,0 +1,7 @@
+# Decision Rules
+
+- Nao escrever arquivos.
+- Suportar inicialmente apenas Python e Node.js.
+- Deploy real fica fora do escopo.
+- IAM deve ser minimo ou justificado.
+- Secrets devem ser referencias, nunca valores hardcoded.

package/runtime/agents/aws-lambda-builder/capabilities/plan-lambda/runner.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""Runner for aws-lambda-builder/plan-lambda."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "aws-lambda"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from aws_lambda_repository import AwsLambdaBuilderError, AwsLambdaRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Plan an AWS Lambda project")
+    parser.add_argument("--spec", required=True)
+    args = parser.parse_args()
+
+    try:
+        result = AwsLambdaRepository().plan_lambda(spec_path=Path(args.spec))
+    except AwsLambdaBuilderError 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/aws-lambda-builder/capabilities/plan-lambda/workflow.md

@@ -0,0 +1,6 @@
+# Workflow
+
+1. Carregar spec YAML/JSON.
+2. Validar runtime, trigger, contrato de entrada/saida, IAM e observabilidade.
+3. Bloquear segredos hardcoded e IAM wildcard sem justificativa.
+4. Retornar plano read-only com artefatos previstos e riscos.

package/runtime/agents/aws-lambda-builder/capabilities/review-lambda-security/capability.yaml

@@ -0,0 +1,18 @@
+id: aws-lambda-builder.review-lambda-security
+kind: capability
+name: Review Lambda Security
+version: 0.1.0
+status: draft
+purpose: Revisar spec Lambda contra IAM, secrets, env vars e operacao segura.
+entrypoint:
+  runner: runner.py
+  workflow: workflow.md
+  output_template: ../../templates/lambda-security-review.md
+inputs:
+  required:
+    - spec
+  optional: []
+outputs:
+  artifacts:
+    - lambda-security-review.json
+write_policy: read_only

package/runtime/agents/aws-lambda-builder/capabilities/review-lambda-security/decision-rules.md

@@ -0,0 +1,7 @@
+# Decision Rules
+
+- Secret hardcoded falha a revisao.
+- IAM wildcard sem justificativa falha a revisao.
+- Resource `*` gera finding.
+- Triggers assicronos devem recomendar DLQ/destination.
+- Nao executar comandos externos.

package/runtime/agents/aws-lambda-builder/capabilities/review-lambda-security/runner.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""Runner for aws-lambda-builder/review-lambda-security."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+REPOSITORY_DIR = Path(__file__).resolve().parents[2] / "infra" / "integrations" / "aws-lambda"
+sys.path.insert(0, str(REPOSITORY_DIR))
+
+from aws_lambda_repository import AwsLambdaBuilderError, AwsLambdaRepository  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Review AWS Lambda security")
+    parser.add_argument("--spec", required=True)
+    args = parser.parse_args()
+
+    try:
+        result = AwsLambdaRepository().review_lambda_security(spec_path=Path(args.spec))
+    except AwsLambdaBuilderError 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/aws-lambda-builder/capabilities/review-lambda-security/workflow.md

@@ -0,0 +1,5 @@
+# Workflow
+
+1. Carregar spec.
+2. Avaliar IAM, env vars, secrets, timeout, memory, logs, retries e DLQ.
+3. Retornar findings read-only.