agent-devkit 0.1.0 → 0.1.6

package/runtime/agents/local-llm-operator/infra/README.md

@@ -0,0 +1,4 @@
+# Infra
+
+Este agente usa a integracao local com Ollama exposta pelo runtime.
+

package/runtime/agents/local-llm-operator/knowledge/context.md

@@ -0,0 +1,6 @@
+# Context
+
+O provider local principal e Ollama. Modelos locais sao preferidos apenas para
+trabalho operacional. O plano deve explicitar quando a delegacao local foi
+selecionada, recomendada ou recusada.
+

package/runtime/agents/local-llm-operator/knowledge/system.md

@@ -0,0 +1,18 @@
+# System
+
+Voce e o Local LLM Operator do Agent DevKit.
+
+Missao:
+
+- diagnosticar modelos locais;
+- selecionar worker local para tarefas operacionais;
+- delegar resumir, classificar, extrair, normalizar e comparar;
+- devolver resultado para revisao de coordenador.
+
+Guardrails:
+
+- nao tomar decisoes finais;
+- nao executar escrita externa;
+- nao aprovar PR, arquitetura, permissao ou deploy;
+- pedir fallback para Claude/Codex/API quando modelo local nao for adequado.
+

package/runtime/agents/local-llm-operator/templates/README.md

@@ -0,0 +1,4 @@
+# Templates
+
+Templates futuros para relatorios de delegacao local.
+

package/runtime/agents/provider-configurator/AGENTS.md

@@ -0,0 +1,8 @@
+# AGENTS.md
+
+Instrucoes locais para o agente `provider-configurator`.
+
+Este agente conduz configuracao sob demanda de providers e sources. Ele deve
+pedir opt-in, coletar uma resposta por vez e nunca armazenar valores brutos de
+segredos.
+

package/runtime/agents/provider-configurator/README.md

@@ -0,0 +1,5 @@
+# Provider Configurator
+
+Agente de runtime responsavel por configurar providers, credentials references
+e sources reutilizaveis quando uma capability precisa de acesso externo.
+

package/runtime/agents/provider-configurator/agent.yaml

@@ -0,0 +1,25 @@
+id: provider-configurator
+kind: runtime-agent
+name: Provider Configurator
+version: 0.1.6
+status: draft
+owner: agent-devkit
+
+purpose: >
+  Conduzir wizards agenticos de configuracao de providers e sources, coletando
+  opt-in, campos de projeto e referencias seguras de credencial.
+
+default_context:
+  - knowledge/system.md
+  - knowledge/context.md
+
+capabilities:
+  - configure-provider-source
+  - collect-provider-credentials
+  - validate-provider-readiness
+
+write_policy:
+  config_writes: explicit_opt_in
+  stores_secret_values: never
+  default_mode: ask-first
+

package/runtime/agents/provider-configurator/capabilities/collect-provider-credentials/capability.yaml

@@ -0,0 +1,15 @@
+id: provider-configurator.collect-provider-credentials
+kind: capability
+name: Collect Provider Credentials
+version: 0.1.6
+status: draft
+purpose: Coletar referencias seguras para credenciais de provider.
+write_policy: local-config-write
+entrypoint:
+  workflow: workflow.md
+inputs:
+  required: [provider]
+  optional: [auth_method]
+outputs:
+  artifacts: [credential-references]
+

package/runtime/agents/provider-configurator/capabilities/collect-provider-credentials/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Rejeitar valores que aparentem token, PAT, senha ou API key.
+- Preferir variavel de ambiente para credenciais simples.
+- Nunca imprimir credenciais resolvidas.
+

package/runtime/agents/provider-configurator/capabilities/collect-provider-credentials/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Listar metodos de autenticacao suportados pelo provider.
+2. Perguntar se o usuario usara variavel de ambiente, arquivo ou cadeia nativa.
+3. Validar que a resposta e referencia, nao segredo bruto.
+4. Retornar referencias para persistencia segura.
+

package/runtime/agents/provider-configurator/capabilities/configure-provider-source/capability.yaml

@@ -0,0 +1,15 @@
+id: provider-configurator.configure-provider-source
+kind: capability
+name: Configure Provider Source
+version: 0.1.6
+status: draft
+purpose: Conduzir wizard para configurar uma source reutilizavel de provider.
+write_policy: local-config-write
+entrypoint:
+  workflow: workflow.md
+inputs:
+  required: [provider]
+  optional: [prompt, route, agent_id, capability_id, reason]
+outputs:
+  artifacts: [source-config]
+

package/runtime/agents/provider-configurator/capabilities/configure-provider-source/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Nao criar source sem opt-in.
+- Nao persistir valor bruto de segredo.
+- Se o usuario negar, registrar decisao e seguir sem a ferramenta.
+

package/runtime/agents/provider-configurator/capabilities/configure-provider-source/workflow.md

@@ -0,0 +1,8 @@
+# Workflow
+
+1. Criar wizard persistente para o provider.
+2. Pedir opt-in ao usuario.
+3. Coletar campos de configuracao e referencias de credenciais.
+4. Criar source reutilizavel.
+5. Retomar o prompt original quando aplicavel.
+

package/runtime/agents/provider-configurator/capabilities/validate-provider-readiness/capability.yaml

@@ -0,0 +1,15 @@
+id: provider-configurator.validate-provider-readiness
+kind: capability
+name: Validate Provider Readiness
+version: 0.1.6
+status: draft
+purpose: Validar se um provider ou source esta pronto para uso sem expor segredo.
+write_policy: read-only
+entrypoint:
+  workflow: workflow.md
+inputs:
+  required: [provider]
+  optional: [source_id]
+outputs:
+  artifacts: [readiness-report]
+

package/runtime/agents/provider-configurator/capabilities/validate-provider-readiness/decision-rules.md

@@ -0,0 +1,6 @@
+# Decision Rules
+
+- Diagnostico nao deve vazar segredo.
+- Provider opcional ausente nao bloqueia plano quando houver fallback.
+- Provider obrigatorio ausente deve acionar wizard.
+

package/runtime/agents/provider-configurator/capabilities/validate-provider-readiness/workflow.md

@@ -0,0 +1,7 @@
+# Workflow
+
+1. Ler registry de provider/source.
+2. Verificar campos obrigatorios e referencias de credencial.
+3. Reportar `ok`, `partial` ou `missing`.
+4. Nao resolver nem exibir valores de segredo.
+

package/runtime/agents/provider-configurator/infra/README.md

@@ -0,0 +1,5 @@
+# Infra
+
+Este agente usa providers globais, source registry e decision store do runtime
+local.
+

package/runtime/agents/provider-configurator/knowledge/context.md

@@ -0,0 +1,8 @@
+# Context
+
+O estado dos wizards fica em `~/.agent-devkit/state/wizards`. A configuracao
+final de source fica em `~/.agent-devkit/config.json` com referencias seguras.
+`~/.ai-devkit` continua aceito como home legado quando ja existir.
+
+Este agente e global: nenhum agente de dominio deve implementar seu proprio
+fluxo de credencial hardcoded.

package/runtime/agents/provider-configurator/knowledge/system.md

@@ -0,0 +1,19 @@
+# System
+
+Voce e o Provider Configurator do Agent DevKit.
+
+Missao:
+
+- detectar provider/source ausente;
+- pedir opt-in antes de usar uma ferramenta externa;
+- coletar configuracao uma pergunta por vez;
+- criar source reutilizavel quando o usuario autorizar;
+- registrar opt-out persistente quando o usuario negar.
+
+Guardrails:
+
+- nunca salvar token, senha, PAT ou API key em claro;
+- aceitar apenas referencias como variavel de ambiente, arquivo local ou cadeia
+  nativa;
+- permitir que o agente siga sem a ferramenta quando o usuario negar.
+

package/runtime/agents/provider-configurator/templates/README.md

@@ -0,0 +1,4 @@
+# Templates
+
+Templates futuros para respostas de configuracao de provider.
+

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,31 @@
+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.
+
+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: plan-first
+  external_writes: delegated
+  requires_review: true
+

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,15 @@
+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,15 @@
+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/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`,
@@ -263,12 +290,19 @@ agent llm doctor openrouter
 ### Ollama local
 
 ```bash
+agent ollama status
+agent ollama models
+agent ollama pull qwen2.5-coder --dry-run
+agent ollama pull qwen2.5-coder --yes
 ollama serve
-ollama pull qwen2.5-coder
 agent llm configure ollama --base-url http://localhost:11434/v1 --model qwen2.5-coder --set-default
 agent llm doctor ollama
 ```
 
+Ollama e tratado como executor operacional local. Codex e Claude continuam como
+coordenadores/revisores preferenciais para decisao, especificacao, codigo,
+documentos, automacoes e fechamento de entrega.
+
 Backends suportados no MVP:
 
 - `openai`: API OpenAI ou endpoint OpenAI-compatible.
@@ -289,6 +323,8 @@ agent llm configure ollama --base-url http://localhost:11434/v1 --model qwen2.5-
 agent llm configure codex-cli --set-default
 agent llm configure claude-code --set-default
 agent llm set-default codex-cli
+agent llm disable ollama
+agent llm enable ollama
 agent llm doctor
 agent llm doctor openai
 ```
@@ -300,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
 
@@ -328,9 +372,66 @@ 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
+aciona o configurador global `provider-configurator` e retorna um wizard
+agentico com opt-in e perguntas progressivas em vez de sugerir um comando
+hardcoded:
+
+```bash
+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 `~/.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
+agent tools list
+agent tools disable azure-devops
+agent tools enable azure-devops
+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.0"
+__version__ = "0.1.6"