agent-devkit 0.1.5 → 0.2.0

package/runtime/agents/supabase-project-analyst/tests/test_runners.py

@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""Tests for the Supabase Project Analyst 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" / "supabase-project-analyst"
+REPOSITORY_PATH = (
+    AGENT_DIR
+    / "infra"
+    / "integrations"
+    / "supabase-project"
+    / "supabase_project_repository.py"
+)
+
+
+def load_repository_module():
+    spec = importlib.util.spec_from_file_location("supabase_project_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 SupabaseProjectAnalystRunnersTest(unittest.TestCase):
+    def setUp(self) -> None:
+        self.repository_module = load_repository_module()
+
+    def write_project(self, root: Path) -> Path:
+        supabase = root / "supabase"
+        migrations = supabase / "migrations"
+        functions = supabase / "functions" / "webhook"
+        migrations.mkdir(parents=True)
+        functions.mkdir(parents=True)
+        (supabase / "config.toml").write_text(
+            """
+project_id = "local-project"
+[api]
+schemas = ["public", "storage"]
+[auth]
+site_url = "http://localhost:3000"
+additional_redirect_urls = ["postgresql://user:pass@example.com/app"]
+""".lstrip(),
+            encoding="utf-8",
+        )
+        (root / ".env").write_text(
+            "SUPABASE_SERVICE_ROLE_KEY=secret-value\nSUPABASE_DB_URL=postgresql://user:pass@localhost/db\nSUPABASE_ANON_KEY=anon-secret\n",
+            encoding="utf-8",
+        )
+        (migrations / "20260101010101_init.sql").write_text(
+            """
+create table public.orders (
+  id uuid primary key,
+  user_id uuid not null,
+  raw_user_meta_data jsonb
+);
+
+create table public.public_notes (
+  id bigint generated always as identity primary key,
+  body text
+);
+alter table public.orders enable row level security;
+
+create policy "orders read" on public.orders
+for select to authenticated
+using (true);
+
+create policy "orders update" on public.orders
+for update to authenticated
+using ((select auth.uid()) = user_id);
+
+create policy "orders role" on public.orders
+for select
+using (auth.role() = 'authenticated');
+
+create policy "public files" on storage.objects
+for select to anon
+using (true);
+
+create view public.order_view as select * from public.orders;
+
+create function public.admin_orders()
+returns setof public.orders
+language sql
+security definer
+as $$
+  select * from public.orders;
+$$;
+
+grant select on public.orders to authenticated;
+drop table public.legacy_orders;
+""".lstrip(),
+            encoding="utf-8",
+        )
+        (functions / "index.ts").write_text(
+            """
+const serviceRole = Deno.env.get("SUPABASE_SERVICE_ROLE_KEY");
+const userMetadata = event.user.user_metadata.role;
+console.log(serviceRole, userMetadata);
+""".lstrip(),
+            encoding="utf-8",
+        )
+        return root
+
+    def test_inspect_supabase_project_reads_local_context_without_secret_values(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            project = self.write_project(Path(tmpdir))
+            repository = self.repository_module.SupabaseProjectRepository()
+
+            result = repository.inspect_supabase_project(project_path=project)
+
+            self.assertEqual(result["status"], "ok")
+            self.assertEqual(result["write_policy"], "read_only")
+            self.assertEqual(result["context"]["migrations_count"], 1)
+            self.assertEqual(result["context"]["edge_functions"], ["webhook"])
+            rendered = json.dumps(result)
+            self.assertNotIn("secret-value", rendered)
+            self.assertNotIn("anon-secret", rendered)
+            self.assertNotIn("postgresql://user:pass@localhost/db", rendered)
+            self.assertNotIn("postgresql://user:pass@example.com/app", rendered)
+
+    def test_audit_rls_policies_detects_common_supabase_risks(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            project = self.write_project(Path(tmpdir))
+            repository = self.repository_module.SupabaseProjectRepository()
+
+            result = repository.audit_rls_policies(project_path=project)
+
+            codes = {finding["code"] for finding in result["findings"]}
+            self.assertIn("exposed_table_without_rls", codes)
+            self.assertIn("authenticated_without_ownership", codes)
+            self.assertIn("deprecated_auth_role", codes)
+            self.assertIn("update_policy_without_with_check", codes)
+
+    def test_audit_auth_security_detects_metadata_and_service_role(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            project = self.write_project(Path(tmpdir))
+            repository = self.repository_module.SupabaseProjectRepository()
+
+            result = repository.audit_auth_security(project_path=project)
+
+            codes = {finding["code"] for finding in result["findings"]}
+            self.assertIn("user_metadata_authorization", codes)
+            self.assertIn("service_role_reference", codes)
+            self.assertIn("local_env_secret_present", codes)
+            rendered = json.dumps(result)
+            self.assertNotIn("secret-value", rendered)
+
+    def test_audit_storage_policies_detects_public_storage_policy(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            project = self.write_project(Path(tmpdir))
+            repository = self.repository_module.SupabaseProjectRepository()
+
+            result = repository.audit_storage_policies(project_path=project)
+
+            codes = {finding["code"] for finding in result["findings"]}
+            self.assertIn("storage_public_policy", codes)
+
+    def test_review_migrations_detects_dangerous_constructs(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            project = self.write_project(Path(tmpdir))
+            repository = self.repository_module.SupabaseProjectRepository()
+
+            result = repository.review_migrations(project_path=project)
+
+            codes = {finding["code"] for finding in result["findings"]}
+            self.assertIn("destructive_ddl", codes)
+            self.assertIn("security_definer_function", codes)
+            self.assertIn("view_without_security_invoker", codes)
+            self.assertIn("broad_grant_to_public_roles", codes)
+
+    def test_generate_supabase_report_consolidates_findings(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            project = self.write_project(Path(tmpdir))
+            repository = self.repository_module.SupabaseProjectRepository()
+
+            result = repository.generate_supabase_report(project_path=project)
+
+            self.assertEqual(result["status"], "ok")
+            self.assertEqual(result["write_policy"], "output_only")
+            self.assertGreater(result["summary"]["findings"], 5)
+            self.assertTrue(result["recommendations"])
+
+    def test_plan_supabase_fix_is_dry_run_and_does_not_apply_sql(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            project = self.write_project(Path(tmpdir))
+            repository = self.repository_module.SupabaseProjectRepository()
+
+            result = repository.plan_supabase_fix(project_path=project)
+
+            self.assertEqual(result["status"], "ok")
+            self.assertEqual(result["write_policy"], "dry_run")
+            self.assertFalse(result["apply_real"])
+            self.assertIn("execute_sql", result["blocked_actions"])
+            self.assertTrue(all(action["apply_real"] is False for action in result["actions"]))
+
+    def test_inspect_runner_is_executable_through_agent_cli(self) -> None:
+        with tempfile.TemporaryDirectory() as tmpdir:
+            project = self.write_project(Path(tmpdir))
+
+            result = subprocess.run(
+                [
+                    sys.executable,
+                    str(AGENT),
+                    "--json",
+                    "run",
+                    "supabase-project-analyst",
+                    "inspect-supabase-project",
+                    "--project-path",
+                    str(project),
+                ],
+                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["context"]["migrations_count"], 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/runtime/agents/task-orchestrator/AGENTS.md

@@ -0,0 +1,8 @@
+# AGENTS.md
+
+Instrucoes locais para o agente `task-orchestrator`.
+
+Este agente coordena planos multiagente. Ele nao executa operacoes de dominio
+diretamente; seleciona especialistas, configura dependencias pendentes e exige
+revisao final quando o trabalho envolve decisao, escrita, codigo ou documento.
+

package/runtime/agents/task-orchestrator/README.md

@@ -0,0 +1,7 @@
+# Task Orchestrator
+
+Agente de runtime responsavel por transformar prompts em planos multiagente,
+selecionar especialistas, coordenar execucao e encaminhar revisao final.
+
+Ele e a superficie versionada do coordenador usado por `agent "<prompt>"`.
+

package/runtime/agents/task-orchestrator/agent.yaml

@@ -0,0 +1,53 @@
+id: task-orchestrator
+kind: runtime-agent
+name: Task Orchestrator
+version: 0.1.6
+status: draft
+owner: agent-devkit
+
+purpose: >
+  Coordenar prompts livres, selecionar agentes especialistas, montar planos de
+  execucao, identificar configuracoes pendentes e acionar revisao final.
+
+runtime_role:
+  kind: coordinator
+
+agent_mode:
+  type: planner
+  max_steps: 5
+  max_specialists: 3
+  max_llm_calls: 1
+  timeout_seconds: 300
+  can_call_capabilities: true
+  can_call_llm: optional
+  can_request_user_input: true
+  external_writes: false
+  allowed_capabilities:
+    - provider-configurator/configure-provider-source
+    - local-llm-operator/select-local-worker
+    - execution-reviewer/review-final-output
+  stop_conditions:
+    - success
+    - needs-input
+    - blocked
+    - max-steps
+
+default_context:
+  - knowledge/system.md
+  - knowledge/context.md
+
+capabilities:
+  - plan-task
+  - select-specialists
+  - coordinate-execution
+
+agent_surface:
+  orchestrated_agents:
+    - provider-configurator/configure-provider-source
+    - local-llm-operator/select-local-worker
+    - execution-reviewer/review-final-output
+
+write_policy:
+  default_mode: confirm
+  external_writes: delegated
+  requires_review: confirm

package/runtime/agents/task-orchestrator/capabilities/coordinate-execution/capability.yaml

@@ -0,0 +1,15 @@
+id: task-orchestrator.coordinate-execution
+kind: capability
+name: Coordinate Execution
+version: 0.1.6
+status: draft
+purpose: Coordenar execucao de tarefas planejadas, bloqueios e revisao final.
+write_policy: delegated
+entrypoint:
+  workflow: workflow.md
+inputs:
+  required: [execution_plan]
+  optional: [dry_run]
+outputs:
+  artifacts: [orchestration-trace]
+

package/runtime/agents/task-orchestrator/capabilities/coordinate-execution/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Bloquear escrita externa sem permissao explicita.
+- Nao concluir plano com configuracao obrigatoria pendente.
+- Revisao final e obrigatoria para codigo, documentos, automacoes e decisoes.
+

package/runtime/agents/task-orchestrator/capabilities/coordinate-execution/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Verificar configuracoes pendentes.
+2. Executar apenas tarefas prontas e permitidas.
+3. Registrar tarefas executadas e bloqueadas.
+4. Acionar `execution-reviewer` quando a revisao for obrigatoria.
+

package/runtime/agents/task-orchestrator/capabilities/plan-task/capability.yaml

@@ -0,0 +1,14 @@
+id: task-orchestrator.plan-task
+kind: capability
+name: Plan Task
+version: 0.1.6
+status: draft
+purpose: Criar um plano multiagente a partir de um prompt livre.
+write_policy: read_only
+entrypoint:
+  workflow: workflow.md
+inputs:
+  required: [prompt]
+  optional: [dry_run, project]
+outputs:
+  artifacts: [execution-plan]

package/runtime/agents/task-orchestrator/capabilities/plan-task/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Preferir capability deterministica quando houver rota confiavel.
+- Pedir configuracao via `provider-configurator` quando faltar provider/source.
+- Nao chamar LLM para tarefas que podem ser roteadas localmente.
+

package/runtime/agents/task-orchestrator/capabilities/plan-task/workflow.md

@@ -0,0 +1,8 @@
+# Workflow
+
+1. Normalizar o prompt sem preservar segredos.
+2. Detectar rota deterministica quando existir.
+3. Selecionar agente de dominio e especialistas.
+4. Incluir configuracoes pendentes e revisao final.
+5. Retornar plano sem executar escrita externa.
+

package/runtime/agents/task-orchestrator/capabilities/select-specialists/capability.yaml

@@ -0,0 +1,14 @@
+id: task-orchestrator.select-specialists
+kind: capability
+name: Select Specialists
+version: 0.1.6
+status: draft
+purpose: Escolher agentes especialistas e capabilities candidatas para um plano.
+write_policy: read_only
+entrypoint:
+  workflow: workflow.md
+inputs:
+  required: [prompt]
+  optional: [route, domain_agent]
+outputs:
+  artifacts: [specialist-selection]

package/runtime/agents/task-orchestrator/capabilities/select-specialists/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Nao emitir `agent_id` inexistente em `agents/`.
+- Preferir agente especifico a agente generico.
+- Nao selecionar especialista apenas por substring ambigua.
+

package/runtime/agents/task-orchestrator/capabilities/select-specialists/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Carregar registry de agentes.
+2. Pontuar agentes por rota, ancora explicita e capabilities.
+3. Selecionar tarefas especialistas com `agent_id` e `capability_id` reais.
+4. Marcar tarefa primaria quando aplicavel.
+

package/runtime/agents/task-orchestrator/infra/README.md

@@ -0,0 +1,5 @@
+# Infra
+
+Este agente usa o runtime local do Agent DevKit e nao acessa sistemas externos
+diretamente.
+

package/runtime/agents/task-orchestrator/knowledge/context.md

@@ -0,0 +1,9 @@
+# Context
+
+O runtime Python executa a orquestracao, mas esta pasta define a superficie
+agent-native versionada do coordenador.
+
+Planos devem referenciar capabilities reais e manter rastreabilidade via
+`execution_plan`, `specialist_tasks`, `configuration_tasks`, `review_task` e
+`orchestration_trace`.
+

package/runtime/agents/task-orchestrator/knowledge/system.md

@@ -0,0 +1,20 @@
+# System
+
+Voce e o Task Orchestrator do Agent DevKit.
+
+Missao:
+
+- entender o pedido do usuario;
+- selecionar agentes especialistas;
+- criar plano de execucao pequeno e auditavel;
+- acionar configuracao quando faltar provider/source;
+- delegar tarefas operacionais para modelos locais quando apropriado;
+- exigir revisao final antes de concluir trabalho relevante.
+
+Guardrails:
+
+- nao executar escrita externa diretamente;
+- nao inventar configuracao ausente;
+- usar agentes reais registrados em `agents/`;
+- manter o plano agnostico de cliente, projeto e credenciais.
+

package/runtime/agents/task-orchestrator/templates/README.md

@@ -0,0 +1,4 @@
+# Templates
+
+Templates futuros do coordenador de tarefas.
+

package/runtime/agents/technical-integration-analyst/agent.yaml

@@ -53,7 +53,20 @@ agent_surface:
     - knowledge/policies.yaml
 
 write_policy:
-  read_operations: auto
-  artifact_generation: auto
+  read_operations: read_only
+  artifact_generation: read_only
   external_calls: confirm
   mutation_operations: confirm
+
+routing:
+  anchors:
+    - api
+    - integracao
+    - integration
+    - mcp
+    - rest
+    - sftp
+    - soap
+  intents:
+    - technical.integration.analysis
+  priority: 50

package/runtime/agents/topdesk-orchestrator/agent.yaml

@@ -48,7 +48,15 @@ agent_surface:
     - knowledge/policies.yaml
 
 write_policy:
-  read_operations: auto
+  read_operations: read_only
   create_operations: confirm
   update_operations: confirm
-  destructive_operations: unsupported
+  destructive_operations: blocked_by_default
+
+routing:
+  anchors:
+    - chamado
+    - topdesk
+  intents:
+    - topdesk.incident
+  priority: 50

package/runtime/cli/README.md

@@ -48,9 +48,36 @@ agent run azure-devops-orchestrator read-card --project "Projeto" --id 123 --inc
 backends. `agent providers` e `agent provider` leem o registry local de
 providers e diagnosticam metadados disponiveis no processo atual. `agent
 credential` resolve referencias de credenciais sem imprimir valores. `agent`
-e a entrada em linguagem natural e exige backend LLM configurado; se nao
-houver backend disponivel, retorna uma mensagem instrutiva para usar `agent run`
-ou configurar um backend.
+e a entrada em linguagem natural: ele cria um `execution_plan` multiagente,
+seleciona coordenador, especialistas, configurador de provider e revisor, e usa
+capabilities deterministicas quando a rota estiver pronta. Backend LLM so e
+necessario quando a tarefa nao puder ser resolvida por rota/capability local; se
+nao houver backend disponivel, retorna uma mensagem instrutiva para usar
+`agent run` ou configurar um backend.
+
+Em `--json`, respostas de `agent "<prompt>"` incluem:
+
+- `execution_plan`: contrato `ai-devkit.agentic-plan/v1`;
+- `specialist_tasks`: capabilities escolhidas por agente;
+- `configuration_tasks`: providers/fontes que precisam de opt-in;
+- `review_task`: revisao final exigida pelo runtime;
+- `orchestration_trace`: trilha resumida de coordenacao.
+
+Os papeis de runtime tambem sao agentes reais versionados em `agents/`:
+`task-orchestrator`, `provider-configurator`, `local-llm-operator` e
+`execution-reviewer`. Eles aparecem em `agent agents list` e suas capabilities
+podem ser inspecionadas como qualquer outro agente.
+
+Quando o plano identifica uma tarefa operacional repetitiva e ha Ollama
+configurado, o runtime delega essa parte ao `local-llm-operator` e injeta o
+resultado como contexto para o coordenador principal. Essa delegacao nunca faz
+escrita externa, aprovacao, decisao de permissao ou revisao final.
+
+Quando `review_gate.required = true`, a conclusao passa pelo
+`execution-reviewer` usando um reviewer independente, preferindo `claude-code`
+ou `codex-cli`. Sem reviewer configurado, quando o reviewer retorna
+`REVIEW BLOCKED`, ou quando nao retorna `REVIEW OK`, a execucao termina como
+`needs-review` e nao como `ok`.
 
 ## Instalacao global e por projeto
 
@@ -87,7 +114,7 @@ Destinos criados:
 
 - `.ai-devkit/config.yaml`: configuracao minima da instalacao, sem segredos.
 - `.ai-devkit/ai-devkit.lock`: lock por projeto com runtime, commit e perfis.
-- `~/.ai-devkit/runtime.lock`: lock global com runtime, commit e canal local.
+- `~/.agent-devkit/runtime.lock`: lock global com runtime, commit e canal local.
 - `.codex/plugins/ai-devkit`: bundle local do plugin Codex.
 - `.codex/skills/ai-devkit-router`: skill de roteamento para Codex.
 - `.claude/plugins/ai-devkit`: bundle local do plugin Claude Code.
@@ -124,7 +151,7 @@ agent install project --target . --host all --profiles sustentacao,infra
 
 Arquivos gerados:
 
-- global: `~/.ai-devkit/runtime.lock`
+- global: `~/.agent-devkit/runtime.lock`
 - projeto: `<project>/.ai-devkit/ai-devkit.lock`
 
 O lock registra `source`, `repository`, `ref`, `commit`, `git_ref`, `dirty`,
@@ -309,9 +336,17 @@ agent --llm claude-code "analise este incidente"
 agent --llm openai "crie um plano de testes"
 ```
 
-A configuracao padrao fica em `~/.ai-devkit/config.json`. Para automacao e
-testes, use `AIKIT_CONFIG_HOME` ou `AI_DEVKIT_CONFIG_HOME` para apontar outro
-diretorio.
+A configuracao padrao fica em `~/.agent-devkit/config.json`. Para automacao e
+testes, use `AGENT_DEVKIT_HOME`, `AI_DEVKIT_CONFIG_HOME` ou `AIKIT_CONFIG_HOME`
+para apontar outro diretorio. `~/.ai-devkit` continua aceito como home legado
+quando ja existir.
+
+Para migrar explicitamente o home legado para o caminho canonico:
+
+```bash
+agent config migrate-home --dry-run
+agent config migrate-home
+```
 
 ## Providers
 
@@ -337,7 +372,7 @@ agent provider unset topdesk
 `provider configure` grava apenas referencias seguras, como `env:VAR` e
 `env-file:/caminho#VAR`; valores de segredos nunca sao persistidos nem exibidos.
 Use `--session-only` para validar uma configuracao sem escrever em
-`~/.ai-devkit/config.json`. Arquivos passados com `--env-file` precisam conter
+`~/.agent-devkit/config.json`. Arquivos passados com `--env-file` precisam conter
 ao menos um campo reconhecido pelo provider selecionado.
 
 Quando um prompt ou capability exige uma source/provider ausente, o runtime
@@ -350,10 +385,31 @@ agent --json "analise o card 7914 do projeto sustentacao no azure"
 agent --json run topdesk-orchestrator read-incident --number "I 2606 001"
 ```
 
+Fluxo de continuidade:
+
+```bash
+agent wizard list
+agent wizard show <wizard-id>
+agent wizard answer <wizard-id> sim
+agent wizard answer <wizard-id> <resposta>
+agent wizard cancel <wizard-id>
+```
+
+Quando a ultima resposta valida e recebida, o wizard salva uma source
+reutilizavel em `~/.agent-devkit/config.json`, sem segredos em claro, e retoma o
+prompt original. Use `agent wizard answer <wizard-id> <resposta> --no-run` para
+salvar a configuracao sem retomar a execucao.
+
+Em terminal interativo, `agent "<prompt>"` conduz essas perguntas diretamente.
+Com `--json`, pipes ou automacao, ele retorna `needs-input` com `wizard_id` para
+que o fluxo seja continuado de forma explicita e nao bloqueante.
+
 ## Decisoes, ferramentas e integracoes
 
-Opt-ins e opt-outs ficam em `~/.ai-devkit/config/decisions.json` e podem ser
-gerenciados por comando ou prompt:
+Opt-ins e opt-outs ficam em `~/.agent-devkit/config/decisions.json` e podem ser
+gerenciados por comando ou prompt. O roteamento por prompt usa os catalogos de
+toolchain, providers, skills e backends LLM; nao depende de uma lista fixa de
+alvos.
 
 ```bash
 agent decisions list
@@ -364,9 +420,18 @@ agent integrations list
 agent skills list
 agent "mostre minhas decisoes"
 agent "desative o azure devops por enquanto"
+agent "desative topdesk"
+agent "habilite gh-cli"
+agent "desative a skill security-review"
+agent "desative openrouter"
 agent "reative o ollama"
+agent "liste llms"
+agent "esqueca minha decisao sobre anthropic"
 ```
 
+Quando um nome e ambiguo entre categorias, o retorno fica `needs-input` e inclui
+`matches` para o usuario informar a categoria ou o id exato.
+
 ## Credential Resolver
 
 O resolver de credenciais opera por referencias e origens, sem retornar valores

package/runtime/cli/aikit/__init__.py

@@ -1,3 +1,3 @@
 """Public CLI implementation for AI DevKit."""
 
-__version__ = "0.1.5"
+__version__ = "0.2.0"