agent-devkit 0.3.0 → 0.3.2

package/README.md

@@ -30,7 +30,7 @@ agent doctor
 Expected version for this release:
 
 ```text
-agent 0.3.0
+agent 0.3.2
 ```
 
 ## Quick Start
@@ -45,8 +45,15 @@ agent llm list
 agent commands list
 ```
 
-Agent DevKit `v0.3.0` also includes deterministic runtime discovery and
-integration commands:
+Agent DevKit `v0.3.2` includes the embedded Qwen2.5-0.5B mini-brain
+contract for local bootstrap conversations without Ollama, Claude, Codex or API
+keys. The npm package stays small; `agent setup mini-brain --yes` downloads the
+GGUF into `.agent-devkit/models` after explicit opt-in.
+When you rename the local agent, Agent DevKit now creates a matching command
+alias under `.agent-devkit/bin` and can add that directory to PATH with
+`agent alias path --yes`.
+The `v0.3.0` deterministic runtime discovery and integration commands remain
+available:
 
 ```bash
 agent roadmap
@@ -73,14 +80,15 @@ Run a natural-language task:
 agent "analise o problema relatado no card 9900"
 ```
 
-Natural-language mode requires an LLM backend. Deterministic commands such as
-`agent agents list`, `agent capabilities list`, `agent doctor`, `agent provider`
-and `agent run` do not require an LLM.
+Natural-language mode can start with the embedded mini-brain. Stronger
+coordinator/reviewer backends remain optional for higher-level work.
+Deterministic commands such as `agent agents list`, `agent capabilities list`,
+`agent doctor`, `agent provider` and `agent run` do not require an external LLM.
 
 Running `agent` without arguments starts the local onboarding status and wizard:
 memory, personality, LLM backends, Ollama, toolchain, sources and next actions.
-Use `agent onboard minimal` for identity, coordinator LLM, Qwen3-0.6B via
-Ollama and local memory. Use `agent onboard complete` to include toolchain,
+Use `agent onboard minimal` for identity, optional coordinator LLM, installable
+mini-brain and local memory. Use `agent onboard complete` to include toolchain,
 providers/sources, specialist catalog, local automations, tasks, notifications,
 knowledge and shared memory. Both commands return plans; external installs
 still require explicit opt-in.
@@ -97,6 +105,7 @@ Useful operational commands:
 agent plan "analyze Azure card 7914"
 agent execute --dry-run "summarize these logs"
 agent workflow install daily-pr-review --dry-run
+agent setup mini-brain --yes
 agent local-llm doctor
 agent local-llm install qwen3:0.6b --dry-run
 agent skill create my-skill --description "Local skill"
@@ -224,9 +233,11 @@ agent llm configure openrouter --api-key-env OPENROUTER_API_KEY --model openai/g
 agent llm doctor openrouter
 ```
 
-### Option F: Ollama local backend
+### Embedded mini-brain and Ollama local backend
 
 ```bash
+agent setup mini-brain --yes
+agent local-llm doctor
 agent ollama status
 agent ollama models
 agent ollama pull qwen3:0.6b --dry-run
@@ -236,8 +247,11 @@ agent llm configure ollama --base-url http://localhost:11434/v1 --model qwen3:0.
 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,
+Agent DevKit includes an installable embedded mini-brain for initial
+conversation, onboarding and setup without external authentication. The GGUF is
+downloaded to `.agent-devkit/models` only after opt-in. Ollama is still treated
+as an optional 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

package/package.json

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

package/runtime/README.md

@@ -65,8 +65,8 @@ agent secrets doctor
 agent mcp tools
 ```
 
-`agent onboard minimal` planeja o setup essencial: identidade, coordenador LLM,
-mini-cerebro Qwen3-0.6B via Ollama e memoria local. `agent onboard complete`
+`agent onboard minimal` planeja o setup essencial: identidade, coordenador LLM
+opcional, mini-cerebro local instalavel sob demanda e memoria local. `agent onboard complete`
 inclui tambem toolchain, providers/sources, catalogo de agentes, automacoes
 locais, tarefas, notificacoes, knowledge e memoria compartilhada. Ambos
 retornam plano deterministico; instalacoes externas continuam exigindo opt-in.
@@ -247,14 +247,23 @@ Uso:
 agent "roteie este pedido para o agente especialista adequado"
 ```
 
-### Opcao F: usar Ollama local
+### Mini cerebro embarcado e Ollama local
 
-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.
+O Agent DevKit vem com um mini cerebro local baseado no contrato
+`Qwen/Qwen2.5-0.5B-Instruct` para conversa inicial, onboarding, setup e tarefas
+simples sem depender de Claude, Codex, API externa ou Ollama. O pacote npm
+inclui o manifest do modelo; o GGUF e baixado para `.agent-devkit/models` sob
+demanda com `agent setup mini-brain --yes`.
+
+Ollama continua suportado como pool opcional de workers locais. O Agent DevKit
+consegue diagnosticar Ollama, listar modelos, planejar pull e usar o backend
+local como trabalhador operacional quando ele estiver configurado ou tiver
+modelos instalados. Claude/Codex continuam sendo os coordenadores e revisores
+preferenciais para decisao, especificacao e entrega final.
 
 ```bash
+agent setup mini-brain --yes
+agent local-llm doctor
 agent ollama status
 agent ollama models
 agent ollama pull qwen3:0.6b --dry-run
@@ -325,9 +334,10 @@ executa a task primaria pelo runner existente e revisa a conclusao pelo
 `review_gate`.
 
 Para tarefas operacionais como resumo, classificacao, extracao e normalizacao,
-o runtime pode delegar uma subtarefa limitada ao `local-llm-operator` usando
-Ollama. O resultado local aparece em `local_llm_execution` e e usado apenas como
-contexto de apoio pelo coordenador principal.
+o runtime pode usar o mini cerebro embarcado para bootstrap/conversa simples ou
+delegar uma subtarefa limitada ao `local-llm-operator` usando Ollama quando
+disponivel. O resultado local aparece em `local_llm_execution` e e usado apenas
+como contexto de apoio pelo coordenador principal.
 
 Quando `review_gate.required = true`, o Agent DevKit exige uma segunda revisao
 concreta pelo `execution-reviewer`, preferindo `claude-code` ou `codex-cli`.

package/runtime/cli/README.md

@@ -209,8 +209,8 @@ 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,
+`minimal` cobre identidade, coordenador LLM opcional, mini-cerebro local
+instalavel sob demanda 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.
 
@@ -232,9 +232,12 @@ remoto continua exigindo provider, criptografia e opt-in explicito.
 
 ## Backends LLM
 
-O modo `agent "<prompt>"` exige um backend LLM. O Agent DevKit suporta tres
+O modo `agent "<prompt>"` consegue conversar e orientar setup com o mini cerebro
+local depois que ele for instalado com opt-in. Para coordenacao/revisao mais forte, o Agent DevKit suporta estas
 familias de backend:
 
+- Mini cerebro local instalavel (`embedded-mini-brain`) para onboarding, setup e
+  conversa simples sem autenticacao externa.
 - CLIs oficiais autenticadas fora do Agent DevKit (`codex-cli` e
   `claude-code`).
 - APIs configuradas por referencia a variavel de ambiente (`openai`,
@@ -321,6 +324,8 @@ agent llm doctor openrouter
 ### Ollama local
 
 ```bash
+agent setup mini-brain --yes
+agent local-llm doctor
 agent ollama status
 agent ollama models
 agent ollama pull qwen3:0.6b --dry-run
@@ -330,12 +335,15 @@ agent llm configure ollama --base-url http://localhost:11434/v1 --model qwen3:0.
 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.
+O mini cerebro embarcado e a base inicial para conversa/setup sem dependencia
+externa. Ollama e tratado como executor operacional local opcional. Codex e
+Claude continuam como coordenadores/revisores preferenciais para decisao,
+especificacao, codigo, documentos, automacoes e fechamento de entrega.
 
 Backends suportados no MVP:
 
+- `embedded-mini-brain`: mini cerebro local embarcado para bootstrap e tarefas
+  simples.
 - `openai`: API OpenAI ou endpoint OpenAI-compatible.
 - `anthropic`: API Anthropic.
 - `openrouter`: API OpenRouter.

package/runtime/cli/aikit/__init__.py

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

package/runtime/cli/aikit/aliases.py

@@ -3,9 +3,11 @@
 from __future__ import annotations
 
 import json
+import os
 import re
 import shutil
 import sys
+import unicodedata
 from pathlib import Path
 from typing import Any
 
@@ -14,6 +16,8 @@ from cli.aikit.app_home import app_home, ensure_app_home
 
 ALIAS_PATTERN = re.compile(r"^[A-Za-z][A-Za-z0-9_-]{1,63}$")
 RESERVED_ALIASES = {"agent", "aikit", "ai-devkit", "python", "python3"}
+SHELL_BLOCK_BEGIN = "# >>> agent-devkit aliases >>>"
+SHELL_BLOCK_END = "# <<< agent-devkit aliases <<<"
 
 
 def aliases_config_path() -> Path:
@@ -84,6 +88,38 @@ def add_alias(name: str, *, force: bool = False) -> dict[str, Any]:
     return payload
 
 
+def ensure_alias_for_agent_name(agent_name: str, *, force: bool = False) -> dict[str, Any]:
+    suggested = suggest_alias_name(agent_name)
+    payload: dict[str, Any] = {
+        "kind": "alias",
+        "requested_name": agent_name,
+        "suggested_name": suggested,
+        "created": False,
+    }
+    if not suggested:
+        return {
+            **payload,
+            "status": "invalid",
+            "message": "Agent name cannot be converted to a safe command alias.",
+            "path_status": alias_path_status(),
+        }
+    try:
+        added = add_alias(suggested, force=force)
+    except ValueError as exc:
+        return {
+            **payload,
+            "name": suggested,
+            "status": "blocked",
+            "message": str(exc),
+            "path_status": alias_path_status(suggested),
+        }
+    added["created"] = True
+    added["requested_name"] = agent_name
+    added["suggested_name"] = suggested
+    added["path_status"] = alias_path_status(suggested)
+    return added
+
+
 def remove_alias(name: str) -> dict[str, Any]:
     alias = validate_alias_name(name)
     config = load_aliases()
@@ -138,6 +174,7 @@ def alias_payload(alias: str, item: dict[str, Any]) -> dict[str, Any]:
         "cmd_path": str(aliases_bin_dir() / f"{alias}.cmd"),
         "ps1_path": str(aliases_bin_dir() / f"{alias}.ps1"),
         "created_by": item.get("created_by"),
+        "path_status": alias_path_status(alias),
     }
 
 
@@ -194,3 +231,147 @@ def alias_executable_path(alias: str) -> Path:
 
 def alias_paths(alias: str) -> list[Path]:
     return [alias_executable_path(alias), aliases_bin_dir() / f"{alias}.cmd", aliases_bin_dir() / f"{alias}.ps1"]
+
+
+def suggest_alias_name(agent_name: str) -> str | None:
+    cleaned = " ".join(str(agent_name or "").split()).strip()
+    if not cleaned:
+        return None
+    try:
+        return validate_alias_name(cleaned)
+    except ValueError:
+        pass
+    ascii_name = unicodedata.normalize("NFKD", cleaned).encode("ascii", "ignore").decode("ascii")
+    alias = re.sub(r"[^A-Za-z0-9_-]+", "-", ascii_name).strip("-_")
+    if alias and not alias[0].isalpha():
+        alias = f"agent-{alias}"
+    if len(alias) == 1:
+        alias = f"{alias}-agent"
+    alias = alias[:64].strip("-_")
+    if not alias:
+        return None
+    try:
+        return validate_alias_name(alias)
+    except ValueError:
+        return None
+
+
+def alias_path_status(alias: str | None = None) -> dict[str, Any]:
+    bin_dir = aliases_bin_dir()
+    path_entries = os.environ.get("PATH", "").split(os.pathsep) if os.environ.get("PATH") else []
+    bin_dir_in_path = any(paths_equal(Path(entry), bin_dir) for entry in path_entries if entry)
+    found = shutil.which(alias) if alias else None
+    available = False
+    if alias and found:
+        try:
+            available = Path(found).resolve() in {path.resolve() for path in alias_paths(alias)}
+        except OSError:
+            available = False
+    plan = alias_path_setup_plan()
+    return {
+        "bin_dir": str(bin_dir),
+        "bin_dir_in_path": bin_dir_in_path,
+        "alias_available": available,
+        "found": found,
+        "setup_required": not bin_dir_in_path,
+        "setup": plan,
+    }
+
+
+def paths_equal(left: Path, right: Path) -> bool:
+    try:
+        return left.expanduser().resolve() == right.expanduser().resolve()
+    except OSError:
+        return left.expanduser() == right.expanduser()
+
+
+def alias_path_setup_plan() -> dict[str, Any]:
+    bin_dir = aliases_bin_dir()
+    if os.name == "nt":
+        return {
+            "platform": "windows",
+            "target": "user PATH",
+            "command": f'agent alias path --yes',
+            "description": f"Add {bin_dir} to the current user's PATH.",
+        }
+    profile = detect_shell_profile()
+    return {
+        "platform": "posix",
+        "target": str(profile),
+        "command": "agent alias path --yes",
+        "description": f"Add {bin_dir} to PATH for future shell sessions.",
+    }
+
+
+def setup_alias_path(*, yes: bool = False) -> dict[str, Any]:
+    status = alias_path_status()
+    payload: dict[str, Any] = {
+        "kind": "alias-path",
+        "bin_dir": status["bin_dir"],
+        "path_status": status,
+        "executed": False,
+    }
+    if not status["setup_required"]:
+        return {**payload, "status": "ok", "message": "Agent DevKit alias bin directory is already on PATH."}
+    if not yes:
+        return {
+            **payload,
+            "status": "needs-confirmation",
+            "message": "Run `agent alias path --yes` to make configured aliases available as shell commands.",
+        }
+    if os.name == "nt":
+        return install_windows_user_path(payload)
+    return install_posix_shell_path(payload)
+
+
+def install_posix_shell_path(payload: dict[str, Any]) -> dict[str, Any]:
+    profile = detect_shell_profile()
+    bin_dir = aliases_bin_dir()
+    profile.parent.mkdir(parents=True, exist_ok=True)
+    current = profile.read_text(encoding="utf-8") if profile.exists() else ""
+    export_line = f'export PATH="{bin_dir}:$PATH"'
+    block = f"\n{SHELL_BLOCK_BEGIN}\n{export_line}\n{SHELL_BLOCK_END}\n"
+    if str(bin_dir) not in current:
+        profile.write_text(current.rstrip() + block, encoding="utf-8")
+    return {
+        **payload,
+        "status": "updated",
+        "executed": True,
+        "profile": str(profile),
+        "message": "Alias PATH configured for future shell sessions. Restart the terminal or source the profile.",
+    }
+
+
+def install_windows_user_path(payload: dict[str, Any]) -> dict[str, Any]:
+    bin_dir = str(aliases_bin_dir())
+    try:
+        import winreg
+
+        with winreg.OpenKey(winreg.HKEY_CURRENT_USER, "Environment", 0, winreg.KEY_READ | winreg.KEY_WRITE) as key:
+            try:
+                current, value_type = winreg.QueryValueEx(key, "Path")
+            except FileNotFoundError:
+                current, value_type = "", winreg.REG_EXPAND_SZ
+            entries = [entry for entry in str(current).split(os.pathsep) if entry]
+            if not any(paths_equal(Path(entry), aliases_bin_dir()) for entry in entries):
+                new_value = os.pathsep.join([bin_dir, *entries])
+                winreg.SetValueEx(key, "Path", 0, value_type, new_value)
+    except OSError as exc:
+        return {**payload, "status": "failed", "executed": False, "message": str(exc)}
+    return {
+        **payload,
+        "status": "updated",
+        "executed": True,
+        "profile": "HKCU\\Environment\\Path",
+        "message": "Alias PATH configured for future Windows terminal sessions.",
+    }
+
+
+def detect_shell_profile() -> Path:
+    shell = Path(os.environ.get("SHELL", "")).name
+    home = Path.home()
+    if shell == "zsh":
+        return home / ".zshrc"
+    if shell == "bash":
+        return home / ".bashrc"
+    return home / ".profile"

package/runtime/cli/aikit/app_home.py

@@ -20,6 +20,7 @@ APP_DIRS = (
     "memory",
     "sessions",
     "tasks",
+    "models",
     "backups",
     "policies",
     "audit",

package/runtime/cli/aikit/cli_dispatch.py

@@ -7,7 +7,7 @@ from pathlib import Path
 from typing import Any
 
 from cli.aikit import __version__
-from cli.aikit.aliases import add_alias, list_aliases, remove_alias, sync_aliases
+from cli.aikit.aliases import add_alias, list_aliases, remove_alias, setup_alias_path, sync_aliases
 from cli.aikit.agentic_commands import agentic_execute, agentic_plan
 from cli.aikit.app_home import app_home_status, migrate_default_home
 from cli.aikit.architecture import architecture_contract
@@ -1530,6 +1530,10 @@ def dispatch_alias(args: argparse.Namespace) -> dict[str, Any]:
             if args.name:
                 raise DevKitError("alias sync does not accept a name")
             return sync_aliases()
+        if args.action == "path":
+            if args.name:
+                raise DevKitError("alias path does not accept a name")
+            return setup_alias_path(yes=args.yes)
     except ValueError as exc:
         raise DevKitError(str(exc)) from exc
     raise DevKitError(f"unsupported alias action: {args.action}")

package/runtime/cli/aikit/cli_parser.py

@@ -246,14 +246,15 @@ def build_parser(prog: str | None = None) -> argparse.ArgumentParser:
     setup_parser.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
     setup_parser.add_argument("--dry-run", action="store_true", help="show setup plan without installing external tools")
     setup_parser.add_argument("--yes", action="store_true", help="confirm setup actions")
-    setup_parser.add_argument("--set-default", action="store_true", help="make the mini-brain Ollama backend the default LLM")
+    setup_parser.add_argument("--set-default", action="store_true", help="make the embedded mini-brain the default LLM")
     setup_parser.add_argument("action", nargs="?", default="plan", choices=["plan", "personality", "mini-brain"])
 
     alias_parser = subparsers.add_parser("alias", help="manage local command aliases for agent")
     alias_parser.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS)
-    alias_parser.add_argument("action", nargs="?", default="list", choices=["add", "list", "remove", "sync"])
+    alias_parser.add_argument("action", nargs="?", default="list", choices=["add", "list", "remove", "sync", "path"])
     alias_parser.add_argument("name", nargs="?")
     alias_parser.add_argument("--force", action="store_true", help="allow replacing an existing local alias file")
+    alias_parser.add_argument("--yes", action="store_true", help="confirm alias PATH setup")
 
     session_parser = subparsers.add_parser("session", help="manage local conversation sessions")
     session_parser.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help=argparse.SUPPRESS)