agent-devkit 0.1.6 → 0.3.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/agent.yaml

@@ -9,6 +9,29 @@ 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
@@ -25,7 +48,6 @@ agent_surface:
     - execution-reviewer/review-final-output
 
 write_policy:
-  default_mode: plan-first
+  default_mode: confirm
   external_writes: delegated
-  requires_review: true
-
+  requires_review: confirm

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

@@ -4,7 +4,7 @@ name: Plan Task
 version: 0.1.6
 status: draft
 purpose: Criar um plano multiagente a partir de um prompt livre.
-write_policy: read-only
+write_policy: read_only
 entrypoint:
   workflow: workflow.md
 inputs:
@@ -12,4 +12,3 @@ inputs:
   optional: [dry_run, project]
 outputs:
   artifacts: [execution-plan]
-

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

@@ -4,7 +4,7 @@ name: Select Specialists
 version: 0.1.6
 status: draft
 purpose: Escolher agentes especialistas e capabilities candidatas para um plano.
-write_policy: read-only
+write_policy: read_only
 entrypoint:
   workflow: workflow.md
 inputs:
@@ -12,4 +12,3 @@ inputs:
   optional: [route, domain_agent]
 outputs:
   artifacts: [specialist-selection]
-

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

@@ -199,6 +199,37 @@ O comando retorna erro apenas para problemas estruturais do runtime, como raiz
 inexistente. Provider opcional ausente, LLM sem chave ou CLI de host nao
 instalada aparecem no bloco de diagnostico e podem ser resolvidos sob demanda.
 
+## Onboarding
+
+Executar apenas `agent` inicia o status/wizard local. Para planejar setup sem
+executar instalacoes externas:
+
+```bash
+agent onboard minimal
+agent onboard complete
+```
+
+`minimal` cobre identidade, coordenador LLM, mini-cerebro Qwen3-0.6B via
+Ollama e memoria local. `complete` inclui tambem toolchain, providers/sources,
+catalogo de agentes, automacoes locais, tarefas, notificacoes, knowledge e
+memoria compartilhada. Instalacoes externas continuam exigindo opt-in.
+
+Backups locais de memoria e personalidade sao gerenciados por:
+
+```bash
+agent memory backup create --title "Antes da migracao"
+export AGENT_DEVKIT_BACKUP_PASSPHRASE="frase longa"
+agent memory backup create --title "Antes da migracao" --encrypted --passphrase-env AGENT_DEVKIT_BACKUP_PASSPHRASE
+agent memory backup list
+agent memory backup restore <backup-id> --yes
+agent memory backup restore --file ./backup.adkmb --passphrase-env AGENT_DEVKIT_BACKUP_PASSPHRASE --yes
+agent memory backup delete <backup-id> --yes
+```
+
+O backup criptografado gera um pacote portatil `.adkmb` e remove a copia local
+em claro dentro da pasta do backup. Esse fluxo nao executa upload remoto. Sync
+remoto continua exigindo provider, criptografia e opt-in explicito.
+
 ## Backends LLM
 
 O modo `agent "<prompt>"` exige um backend LLM. O Agent DevKit suporta tres
@@ -292,10 +323,10 @@ agent llm doctor openrouter
 ```bash
 agent ollama status
 agent ollama models
-agent ollama pull qwen2.5-coder --dry-run
-agent ollama pull qwen2.5-coder --yes
+agent ollama pull qwen3:0.6b --dry-run
+agent ollama pull qwen3:0.6b --yes
 ollama serve
-agent llm configure ollama --base-url http://localhost:11434/v1 --model qwen2.5-coder --set-default
+agent llm configure ollama --base-url http://localhost:11434/v1 --model qwen3:0.6b --set-default
 agent llm doctor ollama
 ```
 
@@ -319,7 +350,7 @@ agent llm list
 agent llm configure openai --api-key-env OPENAI_API_KEY --set-default
 agent llm configure anthropic --api-key-env ANTHROPIC_API_KEY --set-default
 agent llm configure openrouter --api-key-env OPENROUTER_API_KEY --set-default
-agent llm configure ollama --base-url http://localhost:11434/v1 --model qwen2.5-coder --set-default
+agent llm configure ollama --base-url http://localhost:11434/v1 --model qwen3:0.6b --set-default
 agent llm configure codex-cli --set-default
 agent llm configure claude-code --set-default
 agent llm set-default codex-cli

package/runtime/cli/aikit/__init__.py

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

package/runtime/cli/aikit/acceptance.py

@@ -0,0 +1,166 @@
+"""Objective acceptance criteria contract for Agent DevKit work."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+
+ACCEPTANCE_SECTIONS: list[dict[str, Any]] = [
+    {
+        "id": "contract",
+        "name": "Contrato",
+        "questions": [
+            "Qual superficie publica sera criada, alterada ou preservada?",
+            "Quais entradas, saidas, erros e limites ficam documentados?",
+        ],
+        "required": [
+            "manifest_or_public_api",
+            "inputs_outputs",
+            "error_contract",
+        ],
+    },
+    {
+        "id": "behavior",
+        "name": "Comportamento",
+        "questions": [
+            "Qual fluxo principal deve funcionar para o usuario ou agente chamador?",
+            "Quais tarefas conhecidas devem ser deterministicamente automatizadas?",
+        ],
+        "required": [
+            "happy_path",
+            "known_failure_modes",
+            "deterministic_scope",
+        ],
+    },
+    {
+        "id": "security",
+        "name": "Seguranca",
+        "questions": [
+            "Quais permissoes, escritas externas ou dados sensiveis podem ser tocados?",
+            "Quais guardrails impedem vazamento de segredo ou acao destrutiva?",
+        ],
+        "required": [
+            "permission_policy",
+            "secret_handling",
+            "external_write_policy",
+        ],
+    },
+    {
+        "id": "compatibility",
+        "name": "Compatibilidade",
+        "questions": [
+            "Quais comandos, aliases, manifests ou hosts existentes precisam continuar funcionando?",
+            "A mudanca exige migracao ou aceita comportamento legado?",
+        ],
+        "required": [
+            "backward_compatibility",
+            "migration_notes",
+            "host_compatibility",
+        ],
+    },
+    {
+        "id": "validation",
+        "name": "Validacao",
+        "questions": [
+            "Quais testes ou comandos focados provam o comportamento novo?",
+            "Quais validacoes manuais ou de CLI precisam ser executadas?",
+        ],
+        "required": [
+            "focused_tests",
+            "cli_smoke_test",
+            "validation_evidence",
+        ],
+    },
+    {
+        "id": "out_of_scope",
+        "name": "Fora de escopo",
+        "questions": [
+            "O que foi deliberadamente deixado para outro item?",
+            "Quais riscos residuais permanecem aceitos temporariamente?",
+        ],
+        "required": [
+            "deferred_items",
+            "residual_risks",
+        ],
+    },
+]
+
+
+GLOBAL_ACCEPTANCE_CRITERIA: list[str] = [
+    "A mudanca preserva o Agent DevKit como agente principal e trata agentes internos como modulos especialistas.",
+    "A implementacao privilegia automacoes deterministicas para tarefas conhecidas e usa LLM apenas quando decisao, conversa ou revisao exigem raciocinio aberto.",
+    "A instalacao continua simples, sem dependencia obrigatoria de host, LLM profissional ou servico externo especifico.",
+    "Contratos publicos ficam versionados em codigo ou manifesto, nao apenas em docs locais ignorados pelo Git.",
+    "Escritas externas, segredos e acoes destrutivas permanecem bloqueadas por padrao ou exigem permissao explicita.",
+]
+
+
+CHANGE_TYPE_ACCEPTANCE: dict[str, list[str]] = {
+    "agent": [
+        "Inclui agent.yaml valido, README, AGENTS.md e ownership claro do dominio.",
+        "Define capabilities publicas sem depender de contexto grande carregado por padrao.",
+        "Explicita quando usa runner deterministico, LLM externo, mini brain local ou intervencao humana.",
+    ],
+    "capability": [
+        "Inclui capability.yaml com entrada, saida, write_policy e runner quando executavel.",
+        "Mantem conhecimento detalhado sob demanda em knowledge/ ou templates/ da propria capability.",
+        "Tem validacao focada que exercita o caminho principal via agent run quando aplicavel.",
+    ],
+    "runner": [
+        "Recebe argumentos estruturados e retorna resultado estruturado ou erro explicito.",
+        "Evita parse textual fragil quando houver API, JSON, YAML ou biblioteca adequada.",
+        "Redige stdout, stderr e artefatos antes de persistir dados que possam conter segredos.",
+    ],
+    "integration": [
+        "Fica encapsulada em infra/integrations/<provider>/ ou camada global equivalente quando o provider for compartilhado.",
+        "Separa dry-run, leitura, escrita local e escrita externa.",
+        "Documenta autenticacao, variaveis de ambiente e modo offline quando existir.",
+    ],
+    "host_plugin": [
+        "Mantem adaptador fino para o host e delega logica de produto ao runtime do Agent DevKit.",
+        "Preserva compatibilidade com CLI e MCP quando a funcao tambem fizer sentido fora do host.",
+        "Nao torna Codex, Claude, OpenClaw, OpenCode ou outro host dependencia obrigatoria da instalacao base.",
+    ],
+    "core_change": [
+        "Atualiza contratos publicos, validadores e saida humana quando a semantica do runtime mudar.",
+        "Mantem compatibilidade de comandos publicos ou documenta migracao objetiva.",
+        "Inclui testes focados cobrindo a nova regra central e pelo menos um smoke test de CLI quando aplicavel.",
+    ],
+}
+
+
+DEFINITION_OF_DONE: list[str] = [
+    "Contrato, comportamento, seguranca, compatibilidade, validacao e fora de escopo foram avaliados.",
+    "A mudanca tem teste ou comando focado que prova o comportamento principal.",
+    "A saida publica continua compreensivel para humano e consumivel por automacao quando houver modo JSON.",
+    "Nenhum segredo, path local sensivel ou dependencia externa obrigatoria foi introduzido sem contrato.",
+    "Riscos residuais e itens adiados ficaram explicitos na spec, PR ou resposta de entrega.",
+]
+
+
+def acceptance_sections() -> list[str]:
+    """Return canonical acceptance section identifiers."""
+    return [section["id"] for section in ACCEPTANCE_SECTIONS]
+
+
+def change_type_acceptance() -> dict[str, list[str]]:
+    """Return acceptance criteria grouped by change type."""
+    return deepcopy(CHANGE_TYPE_ACCEPTANCE)
+
+
+def acceptance_model() -> dict[str, Any]:
+    """Return the canonical acceptance model exposed by public architecture output."""
+    return {
+        "schema_version": "ai-devkit.acceptance/v1",
+        "sections": deepcopy(ACCEPTANCE_SECTIONS),
+        "global_criteria": list(GLOBAL_ACCEPTANCE_CRITERIA),
+        "change_types": [
+            {
+                "id": change_type,
+                "criteria": list(criteria),
+            }
+            for change_type, criteria in CHANGE_TYPE_ACCEPTANCE.items()
+        ],
+        "definition_of_done": list(DEFINITION_OF_DONE),
+    }

package/runtime/cli/aikit/agent_executor.py

@@ -4,6 +4,12 @@ from __future__ import annotations
 
 from typing import Any, Callable
 
+from cli.aikit.write_policy import (
+    is_autonomous_safe_write_policy,
+    normalize_write_policy,
+    write_policy_public_fields,
+)
+
 
 RunCapability = Callable[[dict[str, Any], str, list[str]], dict[str, Any]]
 LoadAgent = Callable[[str], dict[str, Any]]
@@ -23,7 +29,7 @@ def execute_plan_tasks(
         if not task.get("executable"):
             blocked.append(blocked_task(task, "Capability has no executable runner."))
             continue
-        if str(task.get("write_policy") or "") not in {"read_only", "dry_run"}:
+        if not is_autonomous_safe_write_policy(task.get("write_policy")):
             blocked.append(blocked_task(task, "Capability requires explicit confirmation for external write effects."))
             continue
         try:
@@ -43,12 +49,17 @@ def execute_plan_tasks(
 def public_task_result(task: dict[str, Any], result: dict[str, Any]) -> dict[str, Any]:
     return {
         "id": task.get("id"),
+        "task_id": task.get("task_id") or task.get("id"),
         "agent_id": task.get("agent_id"),
         "capability_id": task.get("capability_id"),
+        "role": task.get("role"),
+        "depends_on": list(task.get("depends_on") or []),
+        "handoff": task.get("handoff") if isinstance(task.get("handoff"), dict) else {},
         "status": result.get("status"),
         "ok": bool(result.get("ok")),
         "provider": task.get("provider"),
-        "write_policy": task.get("write_policy"),
+        "write_policy": normalize_write_policy(task.get("write_policy")),
+        "write_policy_metadata": task_write_policy_metadata(task),
         "result": result,
     }
 
@@ -56,11 +67,23 @@ def public_task_result(task: dict[str, Any], result: dict[str, Any]) -> dict[str
 def blocked_task(task: dict[str, Any], reason: str) -> dict[str, Any]:
     return {
         "id": task.get("id"),
+        "task_id": task.get("task_id") or task.get("id"),
         "agent_id": task.get("agent_id"),
         "capability_id": task.get("capability_id"),
+        "role": task.get("role"),
+        "depends_on": list(task.get("depends_on") or []),
+        "handoff": task.get("handoff") if isinstance(task.get("handoff"), dict) else {},
         "status": "blocked",
         "ok": False,
         "provider": task.get("provider"),
-        "write_policy": task.get("write_policy"),
+        "write_policy": normalize_write_policy(task.get("write_policy")),
+        "write_policy_metadata": task_write_policy_metadata(task),
         "reason": reason,
     }
+
+
+def task_write_policy_metadata(task: dict[str, Any]) -> dict[str, Any]:
+    metadata = task.get("write_policy_metadata")
+    if isinstance(metadata, dict):
+        return metadata
+    return write_policy_public_fields(task.get("write_policy"))["write_policy_metadata"]