agent-devkit 0.0.4 → 0.1.5

package/runtime/cli/aikit/memory.py

@@ -8,27 +8,140 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
-from cli.aikit.llm import config_home, config_path, load_config, save_config
+from cli.aikit.app_home import (
+    app_path,
+    cache_home,
+    ensure_app_home,
+    memory_home as app_memory_home,
+    sessions_home,
+    tasks_home,
+)
+from cli.aikit.llm import config_path, load_config, save_config
+
+
+SECRET_VALUE_PATTERN = re.compile(
+    r"(?i)\b("
+    r"sk-[a-z0-9_-]{12,}|"
+    r"npm_[a-z0-9]{12,}|"
+    r"gh[pousr]_[a-z0-9_]{12,}|"
+    r"xox[baprs]-[a-z0-9-]{12,}|"
+    r"AKIA[0-9A-Z]{12,}|"
+    r"ASIA[0-9A-Z]{12,}"
+    r")\b"
+)
+SECRET_ASSIGNMENT_PATTERN = re.compile(
+    r"(?i)([\"']?)([a-z0-9_]*(?:token|secret|password|passwd|pwd|senha|chave|api[_-]?key|private[_-]?key)[a-z0-9_]*)([\"']?)(\s*[:=]\s*)([\"']?)([^\s,;}\"']+)([\"']?)"
+)
+
+MEMORY_FILE_TEMPLATES: dict[str, str] = {
+    "profile.md": """# Profile
+
+Local user profile for Agent DevKit.
+
+## User
+
+- Name:
+- Primary language:
+- Timezone:
+
+## Notes
+
+- Add stable facts the agent should remember.
+""",
+    "personality.md": """# Personality
+
+Configured public identity and response style for Agent DevKit.
+
+## Agent
+
+- Name: Agent DevKit
+
+## Style
+
+- Tone: direct
+- Detail level: concise
+""",
+    "preferences.md": """# Preferences
+
+Reusable user preferences.
+
+## Defaults
+
+- Prefer local-first execution.
+- Ask before external writes.
+""",
+    "projects.md": """# Projects
+
+Frequently used projects and repositories.
+
+## Items
+
+- Add project names, paths, and non-secret references here.
+""",
+    "routines.md": """# Routines
+
+Recurring workflows, checks, and habits.
+
+## Items
+
+- Add routines that should be easy to reuse.
+""",
+    "napkin.md": """# Agent DevKit Napkin
+
+Curated local runbook entries promoted from repeated use.
+
+## Execution & Validation
+
+- Keep high-value reusable notes here.
+""",
+}
 
 
 def memory_home() -> Path:
-    return config_home() / "memory"
+    return app_memory_home()
+
+
+def ensure_memory() -> dict[str, Any]:
+    ensure_app_home()
+    home = memory_home()
+    home.mkdir(parents=True, exist_ok=True)
+    files: list[dict[str, Any]] = []
+    created: list[str] = []
+    for name, template in MEMORY_FILE_TEMPLATES.items():
+        path = home / name
+        if not path.exists():
+            path.write_text(template, encoding="utf-8")
+            created.append(str(path))
+        files.append({"name": name, "path": str(path), "exists": path.exists()})
+    return {
+        "kind": "memory-path",
+        "status": "ok",
+        "home": str(home),
+        "created": created,
+        "files": files,
+    }
 
 
 def normalize_prompt(prompt: str) -> str:
-    text = " ".join(prompt.lower().split())
+    text = " ".join(redact_secrets(prompt).lower().split())
     return text[:160]
 
 
+def redact_secrets(value: str) -> str:
+    redacted = SECRET_VALUE_PATTERN.sub("[REDACTED_SECRET]", value)
+    return SECRET_ASSIGNMENT_PATTERN.sub(r"\1\2\3\4\5[REDACTED_SECRET]\7", redacted)
+
+
 def napkin_context(root: Path, *, agent_id: str | None = None, source_id: str | None = None) -> dict[str, Any]:
     paths = [
         root / "vendor" / "skills" / "napkin" / "napkin.md",
+        memory_home() / "napkin.md",
         memory_home() / "global" / "napkin.md",
     ]
     if agent_id:
-        paths.append(memory_home() / "agents" / agent_id / "napkin.md")
+        paths.append(memory_home() / "agents" / sanitize_segment(agent_id) / "napkin.md")
     if source_id:
-        paths.append(memory_home() / "sources" / source_id / "napkin.md")
+        paths.append(memory_home() / "sources" / sanitize_segment(source_id) / "napkin.md")
     return {
         "loaded": any(path.exists() for path in paths),
         "paths": [
@@ -61,6 +174,7 @@ def record_usage(
 
 
 def show_memory(root: Path, *, agent_id: str | None = None, source_id: str | None = None) -> dict[str, Any]:
+    memory_paths = ensure_memory()
     config = load_config()
     memory = config.get("memory") if isinstance(config.get("memory"), dict) else {}
     usage = memory.get("usage") if isinstance(memory.get("usage"), dict) else {}
@@ -69,6 +183,7 @@ def show_memory(root: Path, *, agent_id: str | None = None, source_id: str | Non
         "status": "ok",
         "config_path": str(config_path()),
         "memory_home": str(memory_home()),
+        "files": memory_paths["files"],
         "usage": {
             "prompts": sorted_usage(usage.get("prompts") or {}),
             "routes": sorted_usage(usage.get("routes") or {}),
@@ -78,10 +193,19 @@ def show_memory(root: Path, *, agent_id: str | None = None, source_id: str | Non
     }
 
 
-def reset_memory(*, all_memory: bool = False, agent_id: str | None = None, source_id: str | None = None) -> dict[str, Any]:
+def reset_memory(
+    *,
+    all_memory: bool = False,
+    agent_id: str | None = None,
+    source_id: str | None = None,
+    reset_sessions: bool = False,
+    reset_tasks: bool = False,
+    reset_cache: bool = False,
+) -> dict[str, Any]:
     config = load_config()
     removed_paths: list[str] = []
-    if all_memory or not agent_id and not source_id:
+    scoped_reset = any([agent_id, source_id, reset_sessions, reset_tasks, reset_cache])
+    if all_memory or not scoped_reset:
         config.pop("memory", None)
         if memory_home().exists():
             removed_paths.append(str(memory_home()))
@@ -97,6 +221,14 @@ def reset_memory(*, all_memory: bool = False, agent_id: str | None = None, sourc
             usage.get("sources", {}).pop(source_id, None)
             path = memory_home() / "sources" / sanitize_segment(source_id)
             remove_path(path, removed_paths)
+    if all_memory or reset_sessions:
+        remove_path(sessions_home(), removed_paths)
+        remove_path(app_path("state", "active-session.json"), removed_paths)
+    if all_memory or reset_tasks:
+        remove_path(tasks_home(), removed_paths)
+    if all_memory or reset_cache:
+        remove_path(cache_home(), removed_paths)
+    ensure_app_home()
     written_path = save_config(config)
     return {
         "kind": "memory-reset",
@@ -104,9 +236,16 @@ def reset_memory(*, all_memory: bool = False, agent_id: str | None = None, sourc
         "config_path": str(written_path),
         "removed_paths": removed_paths,
         "sources_preserved": True,
+        "sessions_reset": bool(all_memory or reset_sessions),
+        "tasks_reset": bool(all_memory or reset_tasks),
+        "cache_reset": bool(all_memory or reset_cache),
     }
 
 
+def memory_path_payload() -> dict[str, Any]:
+    return ensure_memory()
+
+
 def increment_bucket(bucket: dict[str, Any], key: str, now: str) -> None:
     item = bucket.setdefault(key, {"count": 0, "first_seen": now, "last_seen": now})
     item["count"] = int(item.get("count") or 0) + 1
@@ -132,4 +271,5 @@ def remove_path(path: Path, removed_paths: list[str]) -> None:
 
 
 def sanitize_segment(value: str) -> str:
-    return re.sub(r"[^a-zA-Z0-9._-]+", "-", value)
+    sanitized = re.sub(r"[^a-zA-Z0-9._-]+", "-", value).strip(".-")
+    return sanitized or "item"

package/runtime/cli/aikit/model_router.py

@@ -0,0 +1,70 @@
+"""Task-to-model routing decisions for Agent DevKit."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from cli.aikit.llm import llm_preference, load_config
+from cli.aikit.ollama import ollama_status
+
+
+OPERATIONAL_PATTERN = re.compile(
+    r"(?i)\b(resum|sumari|classifi|extra(?:i|ir)|normaliz|compar|logs?|rascunho|agrupe|agrupar)\b"
+)
+HIGH_LEVEL_PATTERN = re.compile(
+    r"(?i)\b(arquitet|decid|aprovar|reprovar|especifica|requisit|implemente|codigo|c[oó]digo|documento|automac|deploy|seguran)\b"
+)
+
+
+def build_model_plan(prompt: str, *, route: dict[str, Any] | None = None) -> dict[str, Any]:
+    preference = llm_preference(load_config())
+    ollama = ollama_status()
+    local_available = ollama.get("status") == "ok"
+    operational = bool(OPERATIONAL_PATTERN.search(prompt))
+    high_level = bool(HIGH_LEVEL_PATTERN.search(prompt))
+    use_local = operational and local_available
+    return {
+        "kind": "model-plan",
+        "status": "planned",
+        "intent": route.get("intent") if route else "llm",
+        "primary_coordinators": coordinator_order(preference),
+        "local_llm_role": "operational-worker",
+        "local_llm_available": local_available,
+        "local_llm_provider": "ollama",
+        "local_llm_recommended": operational,
+        "local_llm_selected": use_local,
+        "delegation": {
+            "allowed": operational,
+            "selected": use_local,
+            "reason": local_reason(operational=operational, local_available=local_available, high_level=high_level),
+            "forbidden_actions": [
+                "final-review",
+                "external-write",
+                "permission-decision",
+                "architecture-decision",
+                "pr-approval",
+            ],
+        },
+        "fallback_order": preference.get("order") or [],
+        "route": route,
+    }
+
+
+def coordinator_order(preference: dict[str, Any]) -> list[str]:
+    order = list(preference.get("order") or [])
+    preferred = [item for item in order if item in {"claude-code", "codex-cli"}]
+    for item in ("claude-code", "codex-cli"):
+        if item not in preferred:
+            preferred.append(item)
+    return preferred
+
+
+def local_reason(*, operational: bool, local_available: bool, high_level: bool) -> str:
+    if operational and local_available and high_level:
+        return "Use Ollama for operational preprocessing; coordinator review remains mandatory."
+    if operational and local_available:
+        return "Task is operational and local Ollama is available."
+    if operational and not local_available:
+        return "Task is operational, but Ollama is not available; coordinator/API fallback should execute."
+    return "Task requires coordinator-level reasoning or review."

package/runtime/cli/aikit/notifications.py

@@ -0,0 +1,9 @@
+"""Notification payload helpers for local automations."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def terminal_notification(message: str) -> dict[str, Any]:
+    return {"type": "terminal", "message": message}

package/runtime/cli/aikit/ollama.py

@@ -0,0 +1,237 @@
+"""Ollama local LLM discovery and model management."""
+
+from __future__ import annotations
+
+import json
+import platform
+import shutil
+import subprocess
+import urllib.error
+import urllib.request
+from typing import Any
+
+
+OLLAMA_TIMEOUT_SECONDS = 120
+DEFAULT_BASE_URL = "http://localhost:11434"
+
+
+def ollama_status(*, base_url: str = DEFAULT_BASE_URL) -> dict[str, Any]:
+    binary = shutil.which("ollama")
+    version = command_output(["ollama", "--version"]) if binary else None
+    daemon = daemon_status(base_url) if binary else {"status": "unknown", "message": "Ollama binary is not installed."}
+    models = list_local_models(binary_available=bool(binary))
+    status = "ok" if binary else "missing"
+    return {
+        "kind": "ollama-status",
+        "status": status,
+        "binary": binary,
+        "version": first_line(version),
+        "base_url": base_url,
+        "daemon": daemon,
+        "models": models,
+        "model_count": len(models),
+        "install_plan": install_plan() if not binary else None,
+    }
+
+
+def ollama_models() -> dict[str, Any]:
+    binary = shutil.which("ollama")
+    items = list_local_models(binary_available=bool(binary))
+    return {
+        "kind": "ollama-models",
+        "status": "ok" if binary else "missing",
+        "binary": binary,
+        "items": items,
+        "recommended": recommended_models(installed={item["name"] for item in items}),
+    }
+
+
+def ollama_pull(model: str | None, *, yes: bool = False, dry_run: bool = False) -> dict[str, Any]:
+    if not model:
+        raise ValueError("ollama pull requires a model name")
+    binary = shutil.which("ollama")
+    command = ["ollama", "pull", model]
+    if dry_run or not yes:
+        return {
+            "kind": "ollama-pull",
+            "status": "planned" if dry_run else "needs-confirmation",
+            "ok": bool(dry_run),
+            "model": model,
+            "binary": binary,
+            "command": command,
+            "dry_run": dry_run,
+            "yes": yes,
+            "message": "Use --yes to pull the model." if not dry_run and not yes else "Dry-run only.",
+        }
+    if not binary:
+        return {
+            "kind": "ollama-pull",
+            "status": "missing",
+            "ok": False,
+            "model": model,
+            "command": command,
+            "message": "Ollama binary not found in PATH.",
+            "install_plan": install_plan(),
+            "exit_code": 2,
+        }
+    process = run_command(command, timeout=OLLAMA_TIMEOUT_SECONDS * 5)
+    return {
+        "kind": "ollama-pull",
+        "status": "ok" if process.returncode == 0 else "failed",
+        "ok": process.returncode == 0,
+        "model": model,
+        "binary": binary,
+        "command": command,
+        "exit_code": process.returncode,
+        "stdout": safe_tail(process.stdout),
+        "stderr": safe_tail(process.stderr),
+    }
+
+
+def ollama_update(*, yes: bool = False, dry_run: bool = False) -> dict[str, Any]:
+    command = update_command()
+    if dry_run or not yes:
+        return {
+            "kind": "ollama-update",
+            "status": "planned" if dry_run else "needs-confirmation",
+            "ok": bool(dry_run),
+            "command": command,
+            "dry_run": dry_run,
+            "yes": yes,
+            "message": "Use --yes to run the update command." if not dry_run and not yes else "Dry-run only.",
+        }
+    process = run_command(command, timeout=OLLAMA_TIMEOUT_SECONDS * 5, shell=True)
+    return {
+        "kind": "ollama-update",
+        "status": "ok" if process.returncode == 0 else "failed",
+        "ok": process.returncode == 0,
+        "command": command,
+        "exit_code": process.returncode,
+        "stdout": safe_tail(process.stdout),
+        "stderr": safe_tail(process.stderr),
+    }
+
+
+def list_local_models(*, binary_available: bool) -> list[dict[str, Any]]:
+    if not binary_available:
+        return []
+    output = command_output(["ollama", "list"])
+    if not output:
+        return []
+    return parse_ollama_list(output)
+
+
+def parse_ollama_list(output: str) -> list[dict[str, Any]]:
+    items: list[dict[str, Any]] = []
+    for line in output.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.lower().startswith("name "):
+            continue
+        parts = stripped.split()
+        if not parts:
+            continue
+        items.append(
+            {
+                "name": parts[0],
+                "id": parts[1] if len(parts) > 1 else None,
+                "size": parts[2] if len(parts) > 2 else None,
+                "modified": " ".join(parts[3:]) if len(parts) > 3 else None,
+            }
+        )
+    return items
+
+
+def recommended_models(*, installed: set[str]) -> list[dict[str, Any]]:
+    catalog = [
+        ("qwen2.5-coder", "coding", "operational code reading and generation"),
+        ("deepseek-coder", "coding", "code analysis and mechanical refactors"),
+        ("deepseek-r1", "reasoning", "local reasoning drafts with mandatory review"),
+        ("llama3.2", "general", "general local summaries and classification"),
+        ("mistral", "general", "lightweight operational summaries"),
+        ("gemma", "classification", "small extraction and classification tasks"),
+    ]
+    return [
+        {
+            "name": name,
+            "family": family,
+            "recommended_for": recommended_for,
+            "installed": any(item == name or item.startswith(f"{name}:") for item in installed),
+        }
+        for name, family, recommended_for in catalog
+    ]
+
+
+def daemon_status(base_url: str) -> dict[str, Any]:
+    url = base_url.rstrip("/") + "/api/tags"
+    try:
+        with urllib.request.urlopen(url, timeout=2) as response:  # noqa: S310 - local configurable daemon URL.
+            raw = response.read().decode("utf-8", errors="replace")
+    except urllib.error.URLError as exc:
+        return {"status": "unavailable", "message": str(exc.reason)}
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        return {"status": "unknown", "message": "Ollama daemon returned non-JSON response."}
+    return {"status": "ok", "models": len(payload.get("models") or []) if isinstance(payload, dict) else None}
+
+
+def install_plan() -> dict[str, Any]:
+    system = platform.system().lower()
+    if system == "darwin":
+        command = "brew install ollama"
+    elif system.startswith("win"):
+        command = "winget install Ollama.Ollama"
+    else:
+        command = "curl -fsSL https://ollama.com/install.sh | sh"
+    return {"platform": platform_key(), "command": command, "requires_opt_in": True}
+
+
+def update_command() -> str:
+    system = platform.system().lower()
+    if system == "darwin":
+        return "brew upgrade ollama"
+    if system.startswith("win"):
+        return "winget upgrade Ollama.Ollama"
+    return "curl -fsSL https://ollama.com/install.sh | sh"
+
+
+def platform_key() -> str:
+    system = platform.system().lower()
+    if system == "darwin":
+        return "darwin"
+    if system.startswith("win"):
+        return "windows"
+    return "linux"
+
+
+def command_output(command: list[str]) -> str | None:
+    try:
+        process = run_command(command, timeout=10)
+    except OSError:
+        return None
+    if process.returncode != 0:
+        return None
+    return process.stdout.strip() or process.stderr.strip()
+
+
+def run_command(command: list[str] | str, *, timeout: int, shell: bool = False) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        command,
+        shell=shell,
+        check=False,
+        text=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        timeout=timeout,
+    )
+
+
+def safe_tail(value: str | None, *, limit: int = 4000) -> str:
+    text = value or ""
+    return text[-limit:]
+
+
+def first_line(value: str | None) -> str | None:
+    if not value:
+        return None
+    return value.splitlines()[0]