agent-devkit 0.1.0 → 0.1.5

package/README.md

@@ -26,7 +26,7 @@ agent doctor
 Expected version for this release:
 
 ```text
-agent 0.1.0
+agent 0.1.5
 ```
 
 ## Quick Start
@@ -173,12 +173,19 @@ agent llm doctor openrouter
 ### Option F: Ollama local backend
 
 ```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 is treated as an operational worker for repetitive local tasks. Codex and
+Claude remain the preferred coordinators and reviewers for high-level planning,
+software changes, documents, automation decisions and final review.
+
 ### Switch or override the backend
 
 ```bash
@@ -186,6 +193,8 @@ agent llm list
 agent llm set-default codex-cli
 agent llm set-default claude-code
 agent llm set-default openai
+agent llm disable ollama
+agent llm enable ollama
 agent llm doctor
 ```
 
@@ -210,6 +219,17 @@ Natural-language example:
 agent "analise o problema relatado no card 9900"
 ```
 
+If a required source or provider is not configured yet, prompt routing and
+capability execution return the global `provider-configurator` setup wizard
+instead of a hardcoded manual command:
+
+```bash
+agent --json "analise o card 7914 do projeto sustentacao no azure"
+agent --json run topdesk-orchestrator read-incident --number "I 2606 001"
+```
+
+The wizard asks for opt-in and collects one configuration item at a time.
+
 Deterministic example:
 
 ```bash
@@ -222,6 +242,26 @@ Inspect a capability contract before running it:
 agent inspect azure-devops-orchestrator read-card
 ```
 
+## Local Decisions And Tool Control
+
+Agent DevKit persists opt-in and opt-out decisions locally. You can inspect and
+change tools, integrations, skills and LLM availability from commands or natural
+language prompts:
+
+```bash
+agent decisions 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 "reative o ollama"
+```
+
+Decisions are stored under `~/.ai-devkit/config/decisions.json`; secret values
+are not stored there.
+
 ## Configure LLM Backends
 
 Agent DevKit stores references to credentials, not secret values. API keys stay

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-devkit",
-  "version": "0.1.0",
+  "version": "0.1.5",
   "description": "Agent DevKit CLI runtime for specialist AI agents, capabilities and provider-aware automations.",
   "type": "module",
   "license": "MIT",

package/runtime/README.md

@@ -204,11 +204,17 @@ agent "roteie este pedido para o agente especialista adequado"
 
 ### Opcao F: usar Ollama local
 
-Inicie o Ollama localmente e configure um endpoint compativel com OpenAI:
+O Agent DevKit consegue diagnosticar Ollama, listar modelos, planejar pull e
+usar o backend local como trabalhador operacional. Claude/Codex continuam sendo
+os coordenadores e revisores preferenciais para decisao, especificacao e entrega
+final.
 
 ```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
 ```
@@ -226,6 +232,8 @@ agent llm list
 agent llm set-default codex-cli
 agent llm set-default claude-code
 agent llm set-default openai
+agent llm disable ollama
+agent llm enable ollama
 agent llm doctor
 ```
 
@@ -309,6 +317,43 @@ Exemplo de uso deterministico com uma capability:
 agent run azure-devops-orchestrator read-card --project "Projeto" --id 9900 --include-comments
 ```
 
+## Configuracao agentica e decisoes locais
+
+Quando um prompt ou capability exige uma fonte ou provider ainda nao
+configurado, o `agent` nao deve mais parar apenas sugerindo um comando manual.
+Ele aciona o configurador global `provider-configurator`, retorna um wizard
+agentico com opt-in, perguntas progressivas e retomada do prompt original:
+
+```bash
+agent --json "analise o card 7914 do projeto sustentacao no azure"
+agent --json run topdesk-orchestrator read-incident --number "I 2606 001"
+```
+
+O usuario tambem pode controlar ferramentas, integracoes, skills e LLMs sem
+editar arquivos diretamente:
+
+```bash
+agent decisions list
+agent tools list
+agent tools disable azure-devops
+agent tools enable azure-devops
+agent integrations list
+agent skills list
+agent llm list
+```
+
+As mesmas operacoes podem ser feitas por prompt:
+
+```bash
+agent "mostre minhas decisoes"
+agent "desative o azure devops por enquanto"
+agent "reative o ollama"
+```
+
+Se o usuario negar ou desativar uma ferramenta, a decisao fica persistida em
+`~/.ai-devkit/config/decisions.json` e o agente segue sem usar essa ferramenta
+nas proximas sessoes ate reativacao explicita.
+
 Comandos uteis:
 
 ```bash

package/runtime/cli/README.md

@@ -263,12 +263,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 +296,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
 ```
@@ -331,6 +340,33 @@ Use `--session-only` para validar uma configuracao sem escrever em
 `~/.ai-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"
+```
+
+## Decisoes, ferramentas e integracoes
+
+Opt-ins e opt-outs ficam em `~/.ai-devkit/config/decisions.json` e podem ser
+gerenciados por comando ou prompt:
+
+```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 "reative o ollama"
+```
+
 ## 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.5"

package/runtime/cli/aikit/configuration_orchestrator.py

@@ -0,0 +1,291 @@
+"""Global configuration orchestration for missing providers and sources."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.decision_store import is_disabled
+from cli.aikit.providers import ProviderRegistryError, load_providers, provider_or_error
+
+
+PROJECT_PATTERN = re.compile(r"(?i)\bprojeto\s+([A-Za-z0-9._ -]{2,80}?)(?:\s+no\b|\s+na\b|\s+do\b|\s+da\b|$)")
+
+
+def provider_setup_wizard(
+    root: Path,
+    provider_id: str,
+    *,
+    prompt: str | None = None,
+    route: dict[str, Any] | None = None,
+    agent_id: str | None = None,
+    capability_id: str | None = None,
+    reason: str | None = None,
+) -> dict[str, Any]:
+    provider = load_provider(root, provider_id)
+    provider_name = str(provider.get("name") or provider_id)
+    intent = str((route or {}).get("intent") or capability_id or "provider-configuration")
+    suggested_project = infer_project(prompt or "")
+    source_context = bool(route and route.get("intent"))
+    suggested_source_id = suggest_source_id(provider_id, suggested_project)
+    disabled = is_disabled("tools", provider_id) or is_disabled("integrations", provider_id)
+    questions = build_questions(provider, suggested_project=suggested_project, suggested_source_id=suggested_source_id, include_source=source_context)
+    next_question = disabled_notice(provider_id, provider_name) if disabled else opt_in_question(provider_id, provider_name)
+    return {
+        "kind": "provider-setup-wizard",
+        "status": "denied-by-user" if disabled else "waiting-for-user",
+        "provider": provider_id,
+        "provider_name": provider_name,
+        "provider_kind": provider.get("kind"),
+        "intent": intent,
+        "agent_id": agent_id or (route or {}).get("agent_id"),
+        "capability_id": capability_id or (route or {}).get("capability_id"),
+        "reason": reason,
+        "resume_prompt": prompt,
+        "suggested_source_id": suggested_source_id if source_context else None,
+        "suggested_config": suggested_config(provider_id, suggested_project),
+        "next_question": next_question,
+        "questions": questions,
+        "credential_options": credential_options(provider),
+        "config_fields": public_config_fields(provider),
+        "auth_methods": public_auth_methods(provider),
+        "fallbacks": list(provider.get("fallbacks", []) or []),
+        "stores_secret": False,
+        "owner_agent": "provider-configurator",
+        "message": (
+            f"{provider_name} esta desativado. O agente seguira sem essa ferramenta ate voce reativar."
+            if disabled
+            else f"Para continuar, o agente precisa configurar ou autorizar {provider_name}."
+        ),
+    }
+
+
+def provider_wizard_from_requirement(
+    root: Path,
+    provider_id: str,
+    *,
+    agent_id: str | None = None,
+    capability_id: str | None = None,
+    reason: str | None = None,
+) -> dict[str, Any]:
+    return provider_setup_wizard(
+        root,
+        provider_id,
+        agent_id=agent_id,
+        capability_id=capability_id,
+        reason=reason or "Capability provider requirement is not configured.",
+    )
+
+
+def load_provider(root: Path, provider_id: str) -> dict[str, Any]:
+    try:
+        return provider_or_error(load_providers(root), provider_id)
+    except ProviderRegistryError:
+        return {
+            "id": provider_id,
+            "name": provider_id,
+            "kind": "unknown",
+            "config_fields": [],
+            "auth_methods": [],
+            "fallbacks": [],
+        }
+
+
+def build_questions(
+    provider: dict[str, Any],
+    *,
+    suggested_project: str | None,
+    suggested_source_id: str,
+    include_source: bool,
+) -> list[dict[str, Any]]:
+    questions: list[dict[str, Any]] = []
+    for field in provider.get("config_fields", []) or []:
+        if not isinstance(field, dict):
+            continue
+        name = str(field.get("name") or "").strip()
+        if not name:
+            continue
+        suggested_value = suggested_value_for_field(provider, name, suggested_project)
+        questions.append(
+            {
+                "id": field_question_id(provider["id"], name),
+                "type": "text",
+                "text": question_text(provider, name, suggested_value=suggested_value),
+                "config_key": name,
+                "env": name,
+                "required": bool(field.get("required")),
+                "secret": bool(field.get("secret")),
+                "default": field.get("default"),
+                "suggested_value": suggested_value,
+            }
+        )
+    auth_methods = public_auth_methods(provider)
+    if auth_methods:
+        questions.append(
+            {
+                "id": f"{provider_slug(str(provider['id']))}_auth",
+                "type": "select",
+                "text": "Como deseja autenticar?",
+                "options": [method["id"] for method in auth_methods] + ["env", "file", "skip"],
+                "auth_methods": auth_methods,
+            }
+        )
+    if include_source:
+        questions.append(
+            {
+                "id": "source_id",
+                "type": "text",
+                "text": "Qual nome local deseja dar para esta fonte?",
+                "suggested_value": suggested_source_id,
+            }
+        )
+        questions.append(
+            {
+                "id": "default_for_intent",
+                "type": "confirm",
+                "text": "Posso usar esta fonte como padrao para este tipo de pedido?",
+                "default": True,
+            }
+        )
+    if not questions:
+        questions.append(
+            {
+                "id": f"{provider_slug(str(provider['id']))}_confirm",
+                "type": "confirm",
+                "text": f"Posso tentar usar {provider.get('name') or provider['id']} com a cadeia de credenciais nativa?",
+                "default": False,
+            }
+        )
+    return questions
+
+
+def opt_in_question(provider_id: str, provider_name: str) -> dict[str, Any]:
+    return {
+        "id": f"{provider_slug(provider_id)}_opt_in",
+        "type": "confirm",
+        "text": f"Posso configurar ou autorizar {provider_name} para atender este pedido?",
+        "default": False,
+    }
+
+
+def disabled_notice(provider_id: str, provider_name: str) -> dict[str, Any]:
+    return {
+        "id": f"{provider_slug(provider_id)}_disabled",
+        "type": "notice",
+        "text": f"{provider_name} esta desativado por decisao do usuario. Reative para usar esta integracao.",
+        "default": False,
+    }
+
+
+def public_config_fields(provider: dict[str, Any]) -> list[dict[str, Any]]:
+    fields = []
+    for field in provider.get("config_fields", []) or []:
+        if not isinstance(field, dict):
+            continue
+        fields.append(
+            {
+                "name": field.get("name"),
+                "required": bool(field.get("required")),
+                "secret": bool(field.get("secret")),
+                "default": field.get("default"),
+            }
+        )
+    return fields
+
+
+def public_auth_methods(provider: dict[str, Any]) -> list[dict[str, Any]]:
+    methods = []
+    for method in provider.get("auth_methods", []) or []:
+        if not isinstance(method, dict):
+            continue
+        methods.append(
+            {
+                "id": method.get("id"),
+                "label": method.get("label") or method.get("id"),
+                "native": bool(method.get("native")),
+                "config_fields": list(method.get("config_fields", []) or []),
+                "secret_fields": list(method.get("secret_fields", []) or []),
+            }
+        )
+    return methods
+
+
+def credential_options(provider: dict[str, Any]) -> list[dict[str, Any]]:
+    options = []
+    for method in public_auth_methods(provider):
+        for secret_field in method.get("secret_fields") or []:
+            options.append(
+                {
+                    "id": f"env:{secret_field}",
+                    "label": f"Variavel de ambiente {secret_field}",
+                    "env": secret_field,
+                    "auth_method": method.get("id"),
+                    "stores_secret": False,
+                }
+            )
+    options.extend(
+        [
+            {"id": "file", "label": "Arquivo local de credencial", "stores_secret": False},
+            {"id": "native", "label": "Cadeia nativa ou CLI ja autenticada", "stores_secret": False},
+            {"id": "skip", "label": "Ignorar esta ferramenta", "stores_secret": False},
+        ]
+    )
+    seen: set[str] = set()
+    unique = []
+    for option in options:
+        option_id = str(option.get("id"))
+        if option_id not in seen:
+            seen.add(option_id)
+            unique.append(option)
+    return unique
+
+
+def suggested_config(provider_id: str, suggested_project: str | None) -> dict[str, Any]:
+    config: dict[str, Any] = {}
+    if provider_id == "azure-devops" and suggested_project:
+        config["project"] = suggested_project
+        config["AZURE_DEVOPS_PROJECT"] = suggested_project
+    return config
+
+
+def suggested_value_for_field(provider: dict[str, Any], name: str, suggested_project: str | None) -> str | None:
+    if provider.get("id") == "azure-devops" and name == "AZURE_DEVOPS_PROJECT" and suggested_project:
+        return suggested_project
+    return None
+
+
+def question_text(provider: dict[str, Any], name: str, *, suggested_value: str | None) -> str:
+    if provider.get("id") == "azure-devops" and name == "AZURE_DEVOPS_ORG":
+        return "Qual e a organizacao do Azure DevOps?"
+    if provider.get("id") == "azure-devops" and name == "AZURE_DEVOPS_PROJECT":
+        if suggested_value:
+            return f'O projeto e "{suggested_value}"? Se nao, informe o nome correto.'
+        return "Qual e o nome do projeto no Azure DevOps?"
+    label = name.replace("_", " ").lower()
+    return f"Informe {label} para {provider.get('name') or provider.get('id')}."
+
+
+def field_question_id(provider_id: str, name: str) -> str:
+    return f"{provider_slug(provider_id)}_{provider_slug(name)}"
+
+
+def infer_project(prompt: str) -> str | None:
+    match = PROJECT_PATTERN.search(prompt)
+    if not match:
+        return None
+    project = " ".join(match.group(1).strip(" .,_-").split())
+    return project or None
+
+
+def suggest_source_id(provider: str, project: str | None) -> str:
+    parts = [provider]
+    if project:
+        parts.append(project)
+    raw = "-".join(parts)
+    normalized = re.sub(r"[^a-z0-9._-]+", "-", raw.lower()).strip("-")
+    return normalized or provider_slug(provider)
+
+
+def provider_slug(provider: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "_", provider.lower()).strip("_") or "provider"

package/runtime/cli/aikit/decision_store.py

@@ -0,0 +1,158 @@
+"""Persistent local decisions for tools, integrations, skills and LLMs."""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.app_home import app_path, ensure_app_home
+
+
+DECISION_VERSION = 1
+VALID_CATEGORIES = {"tools", "integrations", "skills", "llms"}
+VALID_STATES = {"enabled", "disabled_by_user", "denied_by_user", "needs_setup", "unavailable", "available", "requires_permission"}
+ITEM_ID_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]*$")
+
+
+def decisions_path() -> Path:
+    ensure_app_home()
+    path = app_path("config", "decisions.json")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def empty_decisions() -> dict[str, Any]:
+    return {"version": DECISION_VERSION, "items": {}}
+
+
+def load_decisions() -> dict[str, Any]:
+    path = decisions_path()
+    if not path.exists():
+        return empty_decisions()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return empty_decisions()
+    if not isinstance(data, dict):
+        return empty_decisions()
+    data.setdefault("version", DECISION_VERSION)
+    if not isinstance(data.get("items"), dict):
+        data["items"] = {}
+    return data
+
+
+def save_decisions(data: dict[str, Any]) -> Path:
+    path = decisions_path()
+    path.write_text(json.dumps(data, ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return path
+
+
+def list_decisions(category: str | None = None) -> dict[str, Any]:
+    data = load_decisions()
+    items = [public_decision(item) for item in data.get("items", {}).values() if not category or item.get("category") == category]
+    items.sort(key=lambda item: (item["category"], item["id"]))
+    return {
+        "kind": "decisions",
+        "status": "ok",
+        "category": category,
+        "path": str(decisions_path()),
+        "items": items,
+    }
+
+
+def set_decision(
+    category: str,
+    item_id: str,
+    state: str,
+    *,
+    reason: str | None = None,
+    scope: str = "persistent",
+) -> dict[str, Any]:
+    validate_category(category)
+    validate_item_id(item_id)
+    if state not in VALID_STATES:
+        raise ValueError(f"invalid decision state: {state}")
+    data = load_decisions()
+    key = decision_key(category, item_id)
+    item = {
+        "key": key,
+        "category": category,
+        "id": item_id,
+        "state": state,
+        "scope": scope,
+        "reason": reason,
+        "updated_at": now_iso(),
+    }
+    existing = data["items"].get(key)
+    if isinstance(existing, dict) and existing.get("created_at"):
+        item["created_at"] = existing["created_at"]
+    else:
+        item["created_at"] = item["updated_at"]
+    data["items"][key] = item
+    path = save_decisions(data)
+    return {
+        "kind": "decision",
+        "status": "updated",
+        "path": str(path),
+        "item": public_decision(item),
+        "category": category,
+        "id": item_id,
+        "state": state,
+    }
+
+
+def get_decision(category: str, item_id: str) -> dict[str, Any] | None:
+    validate_category(category)
+    validate_item_id(item_id)
+    item = load_decisions().get("items", {}).get(decision_key(category, item_id))
+    return public_decision(item) if isinstance(item, dict) else None
+
+
+def reset_decisions(category: str | None = None) -> dict[str, Any]:
+    data = load_decisions()
+    if category:
+        validate_category(category)
+        data["items"] = {key: value for key, value in data.get("items", {}).items() if value.get("category") != category}
+    else:
+        data["items"] = {}
+    path = save_decisions(data)
+    return {"kind": "decisions-reset", "status": "reset", "category": category, "path": str(path)}
+
+
+def is_disabled(category: str, item_id: str) -> bool:
+    decision = get_decision(category, item_id)
+    return bool(decision and decision.get("state") in {"disabled_by_user", "denied_by_user"})
+
+
+def public_decision(item: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "category": item.get("category"),
+        "id": item.get("id"),
+        "state": item.get("state"),
+        "scope": item.get("scope"),
+        "reason": item.get("reason"),
+        "created_at": item.get("created_at"),
+        "updated_at": item.get("updated_at"),
+    }
+
+
+def decision_key(category: str, item_id: str) -> str:
+    return f"{category}:{item_id}"
+
+
+def validate_category(category: str) -> None:
+    if category not in VALID_CATEGORIES:
+        available = ", ".join(sorted(VALID_CATEGORIES))
+        raise ValueError(f"invalid decision category: {category}. available: {available}")
+
+
+def validate_item_id(item_id: str) -> None:
+    if not item_id or not ITEM_ID_PATTERN.fullmatch(item_id):
+        raise ValueError("item id must use letters, numbers, dots, dashes, underscores or colons")
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()