agent-devkit 0.2.0 → 0.3.0

package/runtime/cli/aikit/llm.py

@@ -77,7 +77,7 @@ BACKENDS: dict[str, LlmBackend] = {
         base_url_env="OLLAMA_BASE_URL",
         model_env="OLLAMA_MODEL",
         default_base_url="http://localhost:11434/v1",
-        default_model="qwen2.5-coder",
+        default_model="qwen3:0.6b",
         notes="Uses a local Ollama server through an OpenAI-compatible endpoint.",
     ),
     "codex-cli": LlmBackend(
@@ -387,18 +387,26 @@ def doctor_backend(backend: LlmBackend, config: dict[str, Any]) -> dict[str, Any
         }
 
     if backend.auth == "none":
-        base_url = configured.get("base_url") or env_value(backend.base_url_env) or backend.default_base_url
+        env_base_url = env_value(backend.base_url_env)
+        base_url = configured.get("base_url") or env_base_url or backend.default_base_url
         model = configured.get("model") or env_value(backend.model_env) or backend.default_model
+        binary = shutil.which(backend.id) if backend.id == "ollama" else None
+        local_available = bool(configured or env_base_url or binary)
         return {
             "id": backend.id,
             "display_name": backend.display_name,
             "kind": backend.kind,
-            "status": "ok" if base_url else "missing",
+            "status": "ok" if local_available else "missing",
             "configured": bool(configured),
             "base_url": base_url,
             "model": model,
+            "binary": binary,
             "health": "unchecked",
-            "message": "Local backend configured; daemon health is not probed by default.",
+            "message": (
+                "Local backend configured; daemon health is not probed by default."
+                if local_available
+                else "Local backend is not configured and no local binary was found in PATH."
+            ),
         }
 
     api_key_env = configured.get("api_key_env") or backend.api_key_env

package/runtime/cli/aikit/local_artifacts.py

@@ -0,0 +1,444 @@
+"""Local user-created skills, scripts and agent scaffolds."""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.app_home import app_home, ensure_app_home
+from cli.aikit.errors import DevKitError
+
+
+LOCAL_ARTIFACT_SCHEMA_VERSION = "agent-devkit.local-artifacts/v1"
+ID_PATTERN = re.compile(r"^[a-z0-9][a-z0-9._-]*$")
+
+
+def skill_create(skill_id: str | None, *, description: str | None = None, force: bool = False) -> dict[str, Any]:
+    item_id = require_id(skill_id, "skill id")
+    path = local_home("skills") / item_id
+    if path.exists() and not force:
+        raise DevKitError(f"local skill already exists: {item_id}")
+    path.mkdir(parents=True, exist_ok=True)
+    skill_path = path / "SKILL.md"
+    if force or not skill_path.exists():
+        skill_path.write_text(render_skill(item_id, description), encoding="utf-8")
+    return local_artifact_payload("local-skill", "created", item_id, path, write_policy="local_config_write")
+
+
+def skill_list() -> dict[str, Any]:
+    return local_artifact_list("local-skills", "skills", marker="SKILL.md")
+
+
+def skill_show(skill_id: str | None) -> dict[str, Any]:
+    return local_artifact_show("local-skill", "skills", require_id(skill_id, "skill id"), marker="SKILL.md")
+
+
+def skill_update(skill_id: str | None, *, description: str | None = None) -> dict[str, Any]:
+    item_id = require_id(skill_id, "skill id")
+    path = local_home("skills") / item_id
+    if not path.exists():
+        raise DevKitError(f"local skill not found: {item_id}")
+    (path / "SKILL.md").write_text(render_skill(item_id, description), encoding="utf-8")
+    return local_artifact_payload("local-skill", "updated", item_id, path, write_policy="local_config_write")
+
+
+def skill_delete(skill_id: str | None, *, yes: bool = False) -> dict[str, Any]:
+    item_id = require_id(skill_id, "skill id")
+    path = local_home("skills") / item_id
+    if not yes:
+        payload = local_artifact_payload("local-skill", "needs-confirmation", item_id, path, write_policy="local_config_write")
+        payload["ok"] = False
+        payload["exit_code"] = 2
+        return payload
+    shutil.rmtree(path, ignore_errors=True)
+    return local_artifact_payload("local-skill", "deleted", item_id, path, write_policy="local_config_write")
+
+
+def script_create(script_id: str | None, *, command: str | None = None, force: bool = False) -> dict[str, Any]:
+    item_id = require_id(script_id, "script id")
+    path = local_home("scripts") / f"{item_id}.sh"
+    if path.exists() and not force:
+        raise DevKitError(f"local script already exists: {item_id}")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(render_script(command), encoding="utf-8")
+    path.chmod(0o755)
+    return local_artifact_payload("local-script", "created", item_id, path, write_policy="local_write")
+
+
+def script_list() -> dict[str, Any]:
+    home = local_home("scripts")
+    items = [
+        local_artifact_item(path.stem, path, "local-script", enabled=True)
+        for path in sorted(home.glob("*.sh"))
+    ]
+    return {"kind": "local-scripts", "schema_version": LOCAL_ARTIFACT_SCHEMA_VERSION, "status": "ok", "home": str(home), "items": items}
+
+
+def script_run(script_id: str | None, *, dry_run: bool = False, yes: bool = False) -> dict[str, Any]:
+    item_id = require_id(script_id, "script id")
+    path = local_home("scripts") / f"{item_id}.sh"
+    if not path.exists():
+        raise DevKitError(f"local script not found: {item_id}")
+    if dry_run or not yes:
+        return {
+            "kind": "local-script-run",
+            "schema_version": LOCAL_ARTIFACT_SCHEMA_VERSION,
+            "status": "planned" if dry_run else "needs-confirmation",
+            "ok": bool(dry_run),
+            "id": item_id,
+            "path": str(path),
+            "command": [str(path)],
+            "write_policy": "local_write",
+            "message": "Use --yes to run the local script." if not dry_run and not yes else "Dry-run only.",
+            **({} if dry_run else {"exit_code": 2}),
+        }
+    process = subprocess.run([str(path)], check=False, text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=300)
+    return {
+        "kind": "local-script-run",
+        "schema_version": LOCAL_ARTIFACT_SCHEMA_VERSION,
+        "status": "ok" if process.returncode == 0 else "failed",
+        "ok": process.returncode == 0,
+        "id": item_id,
+        "path": str(path),
+        "exit_code": process.returncode,
+        "stdout": process.stdout[-4000:],
+        "stderr": process.stderr[-4000:],
+        "write_policy": "local_write",
+    }
+
+
+def local_agent_create(agent_id: str | None, *, description: str | None = None, force: bool = False) -> dict[str, Any]:
+    item_id = require_id(agent_id, "agent id")
+    path = local_home("agents") / item_id
+    if path.exists() and not force:
+        raise DevKitError(f"local agent already exists: {item_id}")
+    (path / "capabilities").mkdir(parents=True, exist_ok=True)
+    (path / "knowledge").mkdir(parents=True, exist_ok=True)
+    (path / "templates").mkdir(parents=True, exist_ok=True)
+    (path / "infra").mkdir(parents=True, exist_ok=True)
+    (path / "agent.yaml").write_text(render_agent_yaml(item_id, description), encoding="utf-8")
+    (path / "README.md").write_text(f"# {item_id}\n\n{description or 'Local Agent DevKit agent.'}\n", encoding="utf-8")
+    return local_artifact_payload("local-agent", "created", item_id, path, write_policy="local_config_write")
+
+
+def local_agent_validate(agent_id: str | None) -> dict[str, Any]:
+    item_id = require_id(agent_id, "agent id")
+    path = local_home("agents") / item_id
+    checks = [
+        {"id": "path-exists", "status": "passed" if path.exists() else "failed"},
+        {"id": "agent-yaml", "status": "passed" if (path / "agent.yaml").exists() else "failed"},
+        {"id": "capabilities-dir", "status": "passed" if (path / "capabilities").is_dir() else "failed"},
+        {"id": "knowledge-dir", "status": "passed" if (path / "knowledge").is_dir() else "failed"},
+    ]
+    return {
+        "kind": "local-agent-validation",
+        "schema_version": LOCAL_ARTIFACT_SCHEMA_VERSION,
+        "status": "passed" if all(check["status"] == "passed" for check in checks) else "failed",
+        "id": item_id,
+        "path": str(path),
+        "checks": checks,
+    }
+
+
+def local_agent_show(agent_id: str | None) -> dict[str, Any]:
+    item_id = require_id(agent_id, "agent id")
+    path = local_home("agents") / item_id
+    if not (path / "agent.yaml").exists():
+        raise DevKitError(f"local agent not found: {item_id}")
+    payload = local_artifact_payload("local-agent", "ok", item_id, path, write_policy="read_only")
+    payload["manifest"] = (path / "agent.yaml").read_text(encoding="utf-8")
+    readme = path / "README.md"
+    if readme.exists():
+        payload["readme"] = readme.read_text(encoding="utf-8")
+    return payload
+
+
+def local_agent_list() -> dict[str, Any]:
+    return local_artifact_list("local-agents", "agents", marker="agent.yaml")
+
+
+def local_automation_create(
+    automation_id: str | None,
+    *,
+    title: str | None = None,
+    prompt: str | None = None,
+    command: str | None = None,
+    every: str | None = None,
+    cron: str | None = None,
+    force: bool = False,
+) -> dict[str, Any]:
+    item_id = generated_id(automation_id, title, prefix="automation")
+    path = local_home("automations") / item_id
+    manifest = path / "automation.json"
+    if manifest.exists() and not force:
+        raise DevKitError(f"local automation already exists: {item_id}")
+    path.mkdir(parents=True, exist_ok=True)
+    payload = automation_manifest(item_id, title=title, prompt=prompt, command=command, every=every, cron=cron, enabled=True)
+    write_json(manifest, payload)
+    if command:
+        script_path = path / "run.sh"
+        script_path.write_text(render_script(command), encoding="utf-8")
+        script_path.chmod(0o755)
+    return local_automation_payload("created", item_id, path, payload)
+
+
+def local_automation_list() -> dict[str, Any]:
+    home = local_home("automations")
+    items = []
+    for manifest in sorted(home.glob("*/automation.json")):
+        payload = read_json(manifest)
+        item_id = str(payload.get("id") or manifest.parent.name)
+        items.append(
+            {
+                "id": item_id,
+                "kind": "local-automation",
+                "path": str(manifest.parent),
+                "enabled": payload.get("enabled") is True,
+                "title": payload.get("title"),
+                "schedule": payload.get("schedule") or {},
+                "write_policy": payload.get("write_policy") or "local_write",
+            }
+        )
+    return {"kind": "local-automations", "schema_version": LOCAL_ARTIFACT_SCHEMA_VERSION, "status": "ok", "home": str(home), "items": items}
+
+
+def local_automation_show(automation_id: str | None) -> dict[str, Any]:
+    item_id = require_id(automation_id, "automation id")
+    path = local_home("automations") / item_id
+    payload = read_required_automation(path, item_id)
+    return local_automation_payload("ok", item_id, path, payload)
+
+
+def local_automation_update(
+    automation_id: str | None,
+    *,
+    title: str | None = None,
+    prompt: str | None = None,
+    command: str | None = None,
+    every: str | None = None,
+    cron: str | None = None,
+) -> dict[str, Any]:
+    item_id = require_id(automation_id, "automation id")
+    path = local_home("automations") / item_id
+    current = read_required_automation(path, item_id)
+    current_schedule = current.get("schedule") if isinstance(current.get("schedule"), dict) else {"type": "manual"}
+    updated = automation_manifest(
+        item_id,
+        title=title if title is not None else str(current.get("title") or ""),
+        prompt=prompt if prompt is not None else current.get("prompt"),
+        command=command if command is not None else current.get("command"),
+        every=every,
+        cron=cron,
+        enabled=current.get("enabled") is not False,
+        created_at=str(current.get("created_at") or now_iso()),
+    )
+    if every is None and cron is None:
+        updated["schedule"] = current_schedule
+    write_json(path / "automation.json", updated)
+    return local_automation_payload("updated", item_id, path, updated)
+
+
+def local_automation_enable(automation_id: str | None, enabled: bool) -> dict[str, Any]:
+    item_id = require_id(automation_id, "automation id")
+    path = local_home("automations") / item_id
+    payload = read_required_automation(path, item_id)
+    payload["enabled"] = enabled
+    payload["updated_at"] = now_iso()
+    write_json(path / "automation.json", payload)
+    return local_automation_payload("enabled" if enabled else "disabled", item_id, path, payload)
+
+
+def local_automation_remove(automation_id: str | None, *, yes: bool = False) -> dict[str, Any]:
+    item_id = require_id(automation_id, "automation id")
+    path = local_home("automations") / item_id
+    if not yes:
+        payload = local_artifact_payload("local-automation", "needs-confirmation", item_id, path, write_policy="local_config_write")
+        payload["ok"] = False
+        payload["exit_code"] = 2
+        return payload
+    shutil.rmtree(path, ignore_errors=True)
+    return local_artifact_payload("local-automation", "removed", item_id, path, write_policy="local_config_write")
+
+
+def local_automation_validate(automation_id: str | None) -> dict[str, Any]:
+    item_id = require_id(automation_id, "automation id")
+    path = local_home("automations") / item_id
+    payload = read_json(path / "automation.json") if (path / "automation.json").exists() else {}
+    checks = [
+        {"id": "path-exists", "status": "passed" if path.exists() else "failed"},
+        {"id": "manifest-exists", "status": "passed" if (path / "automation.json").exists() else "failed"},
+        {"id": "has-action", "status": "passed" if payload.get("prompt") or payload.get("command") else "failed"},
+        {"id": "no-stored-secret", "status": "passed" if not contains_secret_like_text(json.dumps(payload, ensure_ascii=False)) else "failed"},
+    ]
+    return {
+        "kind": "local-automation-validation",
+        "schema_version": LOCAL_ARTIFACT_SCHEMA_VERSION,
+        "status": "passed" if all(check["status"] == "passed" for check in checks) else "failed",
+        "id": item_id,
+        "path": str(path),
+        "checks": checks,
+    }
+
+
+def local_home(*parts: str) -> Path:
+    ensure_app_home()
+    path = app_home() / "local" / Path(*parts)
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def local_artifact_list(kind: str, folder: str, *, marker: str) -> dict[str, Any]:
+    home = local_home(folder)
+    items = [
+        local_artifact_item(path.parent.name, path.parent, kind.removesuffix("s"), enabled=True)
+        for path in sorted(home.glob(f"*/{marker}"))
+    ]
+    return {"kind": kind, "schema_version": LOCAL_ARTIFACT_SCHEMA_VERSION, "status": "ok", "home": str(home), "items": items}
+
+
+def local_artifact_show(kind: str, folder: str, item_id: str, *, marker: str) -> dict[str, Any]:
+    path = local_home(folder) / item_id
+    marker_path = path / marker
+    if not marker_path.exists():
+        raise DevKitError(f"{kind} not found: {item_id}")
+    payload = local_artifact_payload(kind, "ok", item_id, path, write_policy="read_only")
+    payload["content"] = marker_path.read_text(encoding="utf-8")
+    return payload
+
+
+def local_artifact_payload(kind: str, status: str, item_id: str, path: Path, *, write_policy: str) -> dict[str, Any]:
+    return {
+        "kind": kind,
+        "schema_version": LOCAL_ARTIFACT_SCHEMA_VERSION,
+        "status": status,
+        "id": item_id,
+        "path": str(path),
+        "write_policy": write_policy,
+        "stored_secret": False,
+    }
+
+
+def local_artifact_item(item_id: str, path: Path, kind: str, *, enabled: bool) -> dict[str, Any]:
+    return {"id": item_id, "kind": kind, "path": str(path), "enabled": enabled}
+
+
+def require_id(value: str | None, label: str) -> str:
+    item_id = (value or "").strip()
+    if not ID_PATTERN.fullmatch(item_id):
+        raise DevKitError(f"{label} must use lowercase letters, numbers, dots, dashes or underscores")
+    return item_id
+
+
+def generated_id(value: str | None, title: str | None, *, prefix: str) -> str:
+    if value:
+        return require_id(value, f"{prefix} id")
+    raw = title or f"{prefix}-{datetime.now(timezone.utc).strftime('%Y%m%d%H%M%S')}"
+    slug = re.sub(r"[^a-z0-9._-]+", "-", raw.strip().lower()).strip("-._")
+    return require_id(slug or prefix, f"{prefix} id")
+
+
+def automation_manifest(
+    item_id: str,
+    *,
+    title: str | None,
+    prompt: Any,
+    command: Any,
+    every: str | None,
+    cron: str | None,
+    enabled: bool,
+    created_at: str | None = None,
+) -> dict[str, Any]:
+    schedule: dict[str, Any] = {"type": "manual"}
+    if every:
+        schedule = {"type": "interval", "every": every}
+    if cron:
+        schedule = {"type": "cron", "cron": cron}
+    now = now_iso()
+    return {
+        "schema_version": LOCAL_ARTIFACT_SCHEMA_VERSION,
+        "id": item_id,
+        "kind": "local-automation",
+        "title": title or item_id,
+        "prompt": prompt,
+        "command": command,
+        "schedule": schedule,
+        "enabled": enabled,
+        "write_policy": "local_write" if command else "local_config_write",
+        "external_writes": False,
+        "stored_secret": False,
+        "created_at": created_at or now,
+        "updated_at": now,
+    }
+
+
+def local_automation_payload(status: str, item_id: str, path: Path, manifest: dict[str, Any]) -> dict[str, Any]:
+    payload = local_artifact_payload("local-automation", status, item_id, path, write_policy=str(manifest.get("write_policy") or "local_config_write"))
+    payload["automation"] = manifest
+    return payload
+
+
+def read_required_automation(path: Path, item_id: str) -> dict[str, Any]:
+    manifest = path / "automation.json"
+    if not manifest.exists():
+        raise DevKitError(f"local automation not found: {item_id}")
+    return read_json(manifest)
+
+
+def read_json(path: Path) -> dict[str, Any]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def write_json(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def contains_secret_like_text(text: str) -> bool:
+    return bool(re.search(r"(?i)(api[_-]?key|token|secret|password|senha|pat)\s*[:=]", text))
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def render_skill(skill_id: str, description: str | None) -> str:
+    return f"""---
+name: {skill_id}
+description: {description or 'Local Agent DevKit skill.'}
+---
+
+# {skill_id}
+
+{description or 'Local skill created by Agent DevKit.'}
+"""
+
+
+def render_script(command: str | None) -> str:
+    body = command or "echo 'local script placeholder'"
+    return f"#!/usr/bin/env sh\nset -eu\n{body}\n"
+
+
+def render_agent_yaml(agent_id: str, description: str | None) -> str:
+    return json.dumps(
+        {
+            "id": agent_id,
+            "kind": "agent",
+            "name": agent_id,
+            "version": "0.1.0",
+            "status": "draft",
+            "purpose": description or "Local Agent DevKit agent.",
+            "default_context": ["knowledge/context.md"],
+            "capabilities": [],
+        },
+        ensure_ascii=False,
+        indent=2,
+    ) + "\n"

package/runtime/cli/aikit/local_llm.py

@@ -0,0 +1,161 @@
+"""Canonical local-LLM CLI surface over Ollama and mini-brain policy."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from typing import Any
+
+from cli.aikit.mini_brain import DEFAULT_OLLAMA_MODEL, mini_brain_contract
+from cli.aikit.model_router import build_model_plan
+from cli.aikit.ollama import ollama_models, ollama_pull, ollama_status
+
+
+LOCAL_LLM_SCHEMA_VERSION = "agent-devkit.local-llm/v1"
+LOCAL_WORKERS = (
+    ("local-classifier", "intent classification and routing hints"),
+    ("local-summarizer", "short summaries and extraction"),
+    ("local-coder", "mechanical code drafts with coordinator review"),
+    ("local-log-analyzer", "log clustering and evidence extraction"),
+    ("local-sql-helper", "SQL draft assistance with review required"),
+)
+
+
+def local_llm_list() -> dict[str, Any]:
+    status = ollama_status()
+    contract = mini_brain_contract(ollama_payload=status)
+    return {
+        "kind": "local-llm",
+        "schema_version": LOCAL_LLM_SCHEMA_VERSION,
+        "status": "ok",
+        "provider": "ollama",
+        "mini_brain": contract,
+        "workers": [{"id": worker_id, "purpose": purpose} for worker_id, purpose in LOCAL_WORKERS],
+        "models": {
+            "status": status.get("status"),
+            "count": status.get("model_count", 0),
+        },
+    }
+
+
+def local_llm_doctor() -> dict[str, Any]:
+    status = ollama_status()
+    contract = mini_brain_contract(ollama_payload=status)
+    model_plan = build_model_plan("resuma estes logs operacionais")
+    ok = status.get("status") == "ok" and contract.get("enabled") is True
+    return {
+        "kind": "local-llm-doctor",
+        "schema_version": LOCAL_LLM_SCHEMA_VERSION,
+        "status": "ok" if ok else "partial",
+        "provider": "ollama",
+        "ollama": status,
+        "mini_brain": contract,
+        "model_plan": {
+            "strategy": model_plan.get("strategy"),
+            "local_llm_recommended": model_plan.get("local_llm_recommended"),
+            "local_llm_selected": model_plan.get("local_llm_selected"),
+            "local_llm_role": model_plan.get("local_llm_role"),
+            "forbidden_actions": model_plan.get("forbidden_actions") or [],
+        },
+        "next_steps": local_llm_next_steps(status=status, mini_brain=contract),
+    }
+
+
+def local_llm_models() -> dict[str, Any]:
+    payload = ollama_models()
+    payload["kind"] = "local-llm-models"
+    payload["schema_version"] = LOCAL_LLM_SCHEMA_VERSION
+    payload["provider"] = "ollama"
+    return payload
+
+
+def local_llm_install(model: str | None, *, dry_run: bool = False, yes: bool = False) -> dict[str, Any]:
+    model = model or DEFAULT_OLLAMA_MODEL
+    payload = ollama_pull(model, dry_run=dry_run, yes=yes)
+    payload["kind"] = "local-llm-install"
+    payload["schema_version"] = LOCAL_LLM_SCHEMA_VERSION
+    payload["provider"] = "ollama"
+    return payload
+
+
+def local_llm_remove(model: str | None, *, dry_run: bool = False, yes: bool = False) -> dict[str, Any]:
+    model = model or DEFAULT_OLLAMA_MODEL
+    command = ["ollama", "rm", model]
+    binary = shutil.which("ollama")
+    if dry_run or not yes:
+        needs_confirmation = not dry_run and not yes
+        return {
+            "kind": "local-llm-remove",
+            "schema_version": LOCAL_LLM_SCHEMA_VERSION,
+            "status": "planned" if dry_run else "needs-confirmation",
+            "ok": bool(dry_run),
+            "exit_code": 2 if needs_confirmation else 0,
+            "provider": "ollama",
+            "model": model,
+            "binary": binary,
+            "command": command,
+            "dry_run": dry_run,
+            "yes": yes,
+            "message": "Use --yes to remove the local model." if not dry_run and not yes else "Dry-run only.",
+        }
+    if not binary:
+        return {
+            "kind": "local-llm-remove",
+            "schema_version": LOCAL_LLM_SCHEMA_VERSION,
+            "status": "missing",
+            "ok": False,
+            "provider": "ollama",
+            "model": model,
+            "command": command,
+            "message": "Ollama binary not found in PATH.",
+            "exit_code": 2,
+        }
+    process = subprocess.run(command, check=False, text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=120)
+    return {
+        "kind": "local-llm-remove",
+        "schema_version": LOCAL_LLM_SCHEMA_VERSION,
+        "status": "ok" if process.returncode == 0 else "failed",
+        "ok": process.returncode == 0,
+        "provider": "ollama",
+        "model": model,
+        "binary": binary,
+        "command": command,
+        "exit_code": process.returncode,
+        "stdout": process.stdout[-4000:],
+        "stderr": process.stderr[-4000:],
+    }
+
+
+def local_llm_benchmark(model: str | None = None) -> dict[str, Any]:
+    model = model or DEFAULT_OLLAMA_MODEL
+    status = ollama_status()
+    installed = {item.get("name") for item in status.get("models") or [] if isinstance(item, dict)}
+    available = status.get("status") == "ok" and model in installed
+    return {
+        "kind": "local-llm-benchmark",
+        "schema_version": LOCAL_LLM_SCHEMA_VERSION,
+        "status": "ready" if available else "planned",
+        "ok": available,
+        "provider": "ollama",
+        "model": model,
+        "checks": [
+            {"id": "ollama-binary", "status": "passed" if status.get("status") == "ok" else "failed"},
+            {"id": "model-installed", "status": "passed" if model in installed else "planned"},
+            {"id": "policy", "status": "passed", "message": "Benchmark is read-only and does not approve final work."},
+        ],
+        "next_steps": [] if available else [f"agent local-llm install {model} --yes"],
+    }
+
+
+def local_llm_next_steps(*, status: dict[str, Any], mini_brain: dict[str, Any]) -> list[str]:
+    steps: list[str] = []
+    if status.get("status") != "ok":
+        install_plan = status.get("install_plan") if isinstance(status.get("install_plan"), dict) else {}
+        command = install_plan.get("command")
+        if command:
+            steps.append(f"Install Ollama: {command}")
+    if not mini_brain.get("enabled"):
+        steps.append("agent setup mini-brain --yes")
+    if status.get("model_count", 0) < 1:
+        steps.append(f"agent local-llm install {DEFAULT_OLLAMA_MODEL} --yes")
+    return steps

package/runtime/cli/aikit/main.py

@@ -4,7 +4,9 @@
 from __future__ import annotations
 
 import json
+import os
 import sys
+import traceback
 
 from cli.aikit.cli_dispatch import dispatch, format_audit_warning, is_audit_warning, maybe_record_cli_audit
 from cli.aikit.cli_parser import DETERMINISTIC_COMMANDS, LLM_COMMANDS, build_parser
@@ -26,6 +28,19 @@ def main(argv: list[str] | None = None, *, prog: str | None = None) -> int:
             print(format_audit_warning(audit_result), file=sys.stderr)
         print(f"error: {exc}", file=sys.stderr)
         return 1
+    except Exception as exc:  # noqa: BLE001 - CLI boundary must not leak tracebacks by default.
+        if os.environ.get("AI_DEVKIT_DEBUG") == "1":
+            traceback.print_exc(file=sys.stderr)
+        else:
+            print(
+                f"error: internal error: {type(exc).__name__}. "
+                "Run with AI_DEVKIT_DEBUG=1 for traceback.",
+                file=sys.stderr,
+            )
+        audit_result = maybe_record_cli_audit(args, result=None, error=f"{type(exc).__name__}: {exc}")
+        if is_audit_warning(audit_result):
+            print(format_audit_warning(audit_result), file=sys.stderr)
+        return 1
 
     if result is None:
         return 0