agent-devkit 0.0.4 → 0.1.5

package/runtime/cli/aikit/aliases.py

@@ -0,0 +1,196 @@
+"""Local command aliases for the canonical agent CLI."""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+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"}
+
+
+def aliases_config_path() -> Path:
+    return app_home() / "config" / "aliases.json"
+
+
+def aliases_bin_dir() -> Path:
+    return app_home() / "bin"
+
+
+def load_aliases() -> dict[str, Any]:
+    path = aliases_config_path()
+    if not path.exists():
+        return {"version": 1, "aliases": {}}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {"version": 1, "aliases": {}}
+    if not isinstance(data, dict):
+        return {"version": 1, "aliases": {}}
+    aliases = data.get("aliases")
+    if not isinstance(aliases, dict):
+        data["aliases"] = {}
+    data.setdefault("version", 1)
+    return data
+
+
+def save_aliases(config: dict[str, Any]) -> Path:
+    ensure_app_home()
+    path = aliases_config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(config, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    return path
+
+
+def list_aliases() -> dict[str, Any]:
+    ensure_app_home()
+    config = load_aliases()
+    items = []
+    invalid = []
+    for name, item in sorted(config.get("aliases", {}).items()):
+        if not isinstance(item, dict):
+            continue
+        try:
+            alias = validate_alias_name(name)
+        except ValueError:
+            invalid.append(name)
+            continue
+        items.append(alias_payload(alias, item))
+    return {"kind": "aliases", "status": "ok", "config_path": str(aliases_config_path()), "items": items, "invalid": invalid}
+
+
+def add_alias(name: str, *, force: bool = False) -> dict[str, Any]:
+    alias = validate_alias_name(name)
+    ensure_app_home()
+    target = alias_executable_path(alias)
+    existing = shutil.which(alias)
+    if existing and Path(existing).resolve() != target.resolve() and not force:
+        raise ValueError(f"alias command already exists on PATH: {existing}. Use --force to overwrite local alias only.")
+
+    config = load_aliases()
+    item = {"name": alias, "created_by": "agent-devkit"}
+    config.setdefault("aliases", {})[alias] = item
+    write_alias_shims(alias)
+    written_path = save_aliases(config)
+    payload = alias_payload(alias, item)
+    payload.update({"kind": "alias", "status": "added", "config_path": str(written_path)})
+    return payload
+
+
+def remove_alias(name: str) -> dict[str, Any]:
+    alias = validate_alias_name(name)
+    config = load_aliases()
+    removed = bool(config.get("aliases", {}).pop(alias, None))
+    removed_paths: list[str] = []
+    for path in alias_paths(alias):
+        if path.exists():
+            path.unlink()
+            removed_paths.append(str(path))
+    written_path = save_aliases(config)
+    return {
+        "kind": "alias",
+        "status": "removed" if removed or removed_paths else "missing",
+        "name": alias,
+        "config_path": str(written_path),
+        "removed_paths": removed_paths,
+    }
+
+
+def sync_aliases() -> dict[str, Any]:
+    ensure_app_home()
+    config = load_aliases()
+    synced: list[dict[str, Any]] = []
+    invalid: list[str] = []
+    for alias, item in sorted(config.get("aliases", {}).items()):
+        if not isinstance(item, dict):
+            continue
+        try:
+            safe_alias = validate_alias_name(alias)
+        except ValueError:
+            invalid.append(alias)
+            continue
+        write_alias_shims(safe_alias)
+        synced.append(alias_payload(safe_alias, item))
+    save_aliases(config)
+    return {"kind": "aliases", "status": "synced", "config_path": str(aliases_config_path()), "items": synced, "invalid": invalid}
+
+
+def validate_alias_name(name: str, *, allow_reserved: bool = False) -> str:
+    alias = name.strip()
+    if not ALIAS_PATTERN.fullmatch(alias):
+        raise ValueError("alias must start with a letter and contain only letters, numbers, hyphen or underscore")
+    if alias.lower() in RESERVED_ALIASES and not allow_reserved:
+        raise ValueError(f"alias is reserved: {alias}")
+    return alias
+
+
+def alias_payload(alias: str, item: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "name": alias,
+        "path": str(alias_executable_path(alias)),
+        "cmd_path": str(aliases_bin_dir() / f"{alias}.cmd"),
+        "ps1_path": str(aliases_bin_dir() / f"{alias}.ps1"),
+        "created_by": item.get("created_by"),
+    }
+
+
+def write_alias_shims(alias: str) -> None:
+    bin_dir = aliases_bin_dir()
+    bin_dir.mkdir(parents=True, exist_ok=True)
+    root = Path(__file__).resolve().parents[2]
+    agent_script = root / "agent"
+    python = sys.executable
+
+    posix = alias_executable_path(alias)
+    posix.write_text(
+        "\n".join(
+            [
+                "#!/usr/bin/env sh",
+                "set -eu",
+                f"AI_DEVKIT_INVOKED_AS={json.dumps(alias)} exec {json.dumps(python)} {json.dumps(str(agent_script))} \"$@\"",
+                "",
+            ]
+        ),
+        encoding="utf-8",
+    )
+    posix.chmod(0o755)
+
+    cmd = bin_dir / f"{alias}.cmd"
+    cmd.write_text(
+        "\r\n".join(
+            [
+                "@echo off",
+                f"set AI_DEVKIT_INVOKED_AS={alias}",
+                f'"{python}" "{agent_script}" %*',
+                "",
+            ]
+        ),
+        encoding="utf-8",
+    )
+
+    ps1 = bin_dir / f"{alias}.ps1"
+    ps1.write_text(
+        "\n".join(
+            [
+                f"$env:AI_DEVKIT_INVOKED_AS = {json.dumps(alias)}",
+                f"& {json.dumps(python)} {json.dumps(str(agent_script))} @args",
+                "",
+            ]
+        ),
+        encoding="utf-8",
+    )
+
+
+def alias_executable_path(alias: str) -> Path:
+    return aliases_bin_dir() / alias
+
+
+def alias_paths(alias: str) -> list[Path]:
+    return [alias_executable_path(alias), aliases_bin_dir() / f"{alias}.cmd", aliases_bin_dir() / f"{alias}.ps1"]

package/runtime/cli/aikit/app_home.py

@@ -0,0 +1,78 @@
+"""Local AI DevKit application home and filesystem layout helpers."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+APP_HOME_ENV = "AI_DEVKIT_CONFIG_HOME"
+LEGACY_APP_HOME_ENV = "AIKIT_CONFIG_HOME"
+DEFAULT_APP_HOME_NAME = ".ai-devkit"
+
+APP_DIRS = (
+    "bin",
+    "config",
+    "memory",
+    "sessions",
+    "tasks",
+    "policies",
+    "audit",
+    "secrets",
+    "cache",
+    "logs",
+    "state",
+)
+
+
+def app_home() -> Path:
+    """Return the configured Agent DevKit home directory."""
+    raw = os.environ.get(APP_HOME_ENV) or os.environ.get(LEGACY_APP_HOME_ENV)
+    if raw:
+        return Path(raw).expanduser().resolve()
+    return (Path.home() / DEFAULT_APP_HOME_NAME).resolve()
+
+
+def app_path(*parts: str) -> Path:
+    return app_home().joinpath(*parts)
+
+
+def ensure_app_home() -> Path:
+    """Create the application home skeleton and return its path."""
+    home = app_home()
+    home.mkdir(parents=True, exist_ok=True)
+    for name in APP_DIRS:
+        (home / name).mkdir(parents=True, exist_ok=True)
+    return home
+
+
+def config_path() -> Path:
+    return app_path("config.json")
+
+
+def memory_home() -> Path:
+    return app_path("memory")
+
+
+def sessions_home() -> Path:
+    return app_path("sessions")
+
+
+def tasks_home() -> Path:
+    return app_path("tasks")
+
+
+def audit_home() -> Path:
+    return app_path("audit")
+
+
+def policies_home() -> Path:
+    return app_path("policies")
+
+
+def secrets_home() -> Path:
+    return app_path("secrets")
+
+
+def cache_home() -> Path:
+    return app_path("cache")

package/runtime/cli/aikit/audit.py

@@ -0,0 +1,344 @@
+"""Local audit trail for Agent DevKit CLI executions."""
+
+from __future__ import annotations
+
+import getpass
+import json
+import re
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.app_home import audit_home, ensure_app_home
+from cli.aikit.memory import normalize_prompt, redact_secrets
+
+
+AUDIT_VERSION = 1
+
+
+def now_utc() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def now_iso() -> str:
+    return now_utc().isoformat()
+
+
+def ensure_audit_home() -> Path:
+    ensure_app_home()
+    home = audit_home()
+    home.mkdir(parents=True, exist_ok=True)
+    return home
+
+
+def audit_day_home(day: str | None = None) -> Path:
+    resolved_day = day or now_utc().date().isoformat()
+    path = ensure_audit_home() / resolved_day
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def record_audit(
+    *,
+    command: str | None,
+    args: dict[str, Any],
+    result: dict[str, Any] | None = None,
+    error: str | None = None,
+) -> dict[str, Any]:
+    created_at = now_iso()
+    execution_id = f"exec_{now_utc().strftime('%Y%m%d%H%M%S')}_{uuid.uuid4().hex[:8]}"
+    prompt = extract_prompt(args)
+    safe_result = redact_value(result or {})
+    entry = {
+        "version": AUDIT_VERSION,
+        "id": execution_id,
+        "created_at": created_at,
+        "user": safe_user(),
+        "command": command,
+        "prompt": redact_secrets(prompt) if prompt else None,
+        "prompt_normalized": normalize_prompt(prompt) if prompt else None,
+        "session": extract_session(safe_result),
+        "route": safe_result.get("route"),
+        "agent": extract_agent(safe_result, args),
+        "providers": extract_providers(safe_result),
+        "sources": extract_sources(safe_result),
+        "commands": extract_commands(safe_result),
+        "permissions": extract_permissions(safe_result),
+        "llm_backends": extract_llm_backends(safe_result),
+        "token_estimate": extract_token_estimate(safe_result),
+        "external_actions": extract_external_actions(safe_result),
+        "result": summarize_result(safe_result),
+        "error": redact_secrets(error) if error else None,
+        "redaction_applied": True,
+    }
+    day_home = audit_day_home(created_at[:10])
+    json_path = day_home / f"{execution_id}.json"
+    md_path = day_home / f"{execution_id}.md"
+    json_path.write_text(json.dumps(entry, ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    md_path.write_text(render_audit_md(entry), encoding="utf-8")
+    return {"id": execution_id, "json_path": str(json_path), "markdown_path": str(md_path)}
+
+
+def list_audits(limit: int = 20) -> dict[str, Any]:
+    items: list[dict[str, Any]] = []
+    for path in sorted(ensure_audit_home().glob("*/*.json"), reverse=True):
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(payload, dict):
+            continue
+        items.append(
+            {
+                "id": payload.get("id"),
+                "created_at": payload.get("created_at"),
+                "command": payload.get("command"),
+                "status": (payload.get("result") or {}).get("status"),
+                "ok": (payload.get("result") or {}).get("ok"),
+                "json_path": str(path),
+                "markdown_path": str(path.with_suffix(".md")),
+            }
+        )
+        if len(items) >= limit:
+            break
+    return {"kind": "audit", "status": "ok", "home": str(ensure_audit_home()), "items": items}
+
+
+def show_audit(execution_id: str) -> dict[str, Any]:
+    path = find_audit_json(execution_id)
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    return {
+        "kind": "audit-entry",
+        "status": "ok",
+        "id": payload.get("id"),
+        "entry": payload,
+        "json_path": str(path),
+        "markdown_path": str(path.with_suffix(".md")),
+    }
+
+
+def export_audit(execution_id: str, *, fmt: str = "md") -> dict[str, Any]:
+    path = find_audit_json(execution_id)
+    if fmt == "json":
+        content = path.read_text(encoding="utf-8")
+        export_path = path
+    elif fmt == "md":
+        md_path = path.with_suffix(".md")
+        content = md_path.read_text(encoding="utf-8") if md_path.exists() else render_audit_md(json.loads(path.read_text(encoding="utf-8")))
+        export_path = md_path
+    else:
+        raise ValueError("--format must be md or json")
+    return {
+        "kind": "audit-export",
+        "status": "ok",
+        "id": execution_id,
+        "format": fmt,
+        "path": str(export_path),
+        "content": content,
+    }
+
+
+def find_audit_json(execution_id: str) -> Path:
+    if not execution_id or "/" in execution_id or "\\" in execution_id:
+        raise ValueError(f"invalid audit execution id: {execution_id}")
+    matches = sorted(ensure_audit_home().glob(f"*/{execution_id}.json"))
+    if not matches:
+        prefix_matches = sorted(ensure_audit_home().glob(f"*/{execution_id}*.json"))
+        if len(prefix_matches) == 1:
+            return prefix_matches[0]
+        if len(prefix_matches) > 1:
+            raise ValueError(f"ambiguous audit execution id prefix: {execution_id}")
+        raise ValueError(f"audit execution not found: {execution_id}")
+    return matches[0]
+
+
+def redact_value(value: Any) -> Any:
+    if isinstance(value, str):
+        return redact_secrets(value)
+    if isinstance(value, list):
+        return [redact_value(item) for item in value]
+    if isinstance(value, tuple):
+        return [redact_value(item) for item in value]
+    if isinstance(value, dict):
+        redacted: dict[str, Any] = {}
+        for key, item in value.items():
+            key_text = str(key)
+            if secret_key(key_text):
+                redacted[key_text] = "[REDACTED_SECRET]"
+            else:
+                redacted[key_text] = redact_value(item)
+        return redacted
+    return value
+
+
+def secret_key(key: str) -> bool:
+    normalized = key.lower().replace("-", "_")
+    if normalized in {"token_estimate", "tokens", "prompt_tokens", "completion_tokens", "total_tokens"}:
+        return False
+    exact = {"token", "secret", "password", "passwd", "pwd", "api_key", "private_key", "pat"}
+    if normalized in exact:
+        return True
+    if normalized.endswith(("_token", "_secret", "_password", "_passwd", "_pwd", "_api_key", "_private_key", "_pat")):
+        return True
+    compact = re.sub(r"[^a-z0-9]+", "", key.lower())
+    if compact in {"tokenestimate", "tokens", "prompttokens", "completiontokens", "totaltokens"}:
+        return False
+    return any(marker in compact for marker in ("token", "secret", "password", "passwd", "apikey", "privatekey"))
+
+
+def extract_prompt(args: dict[str, Any]) -> str | None:
+    prompt = args.get("prompt")
+    if isinstance(prompt, list):
+        return " ".join(str(item) for item in prompt).strip()
+    return str(prompt).strip() if prompt else None
+
+
+def extract_session(result: dict[str, Any]) -> dict[str, Any] | None:
+    session = result.get("session")
+    if isinstance(session, dict):
+        return {
+            "id": session.get("id"),
+            "title": session.get("title"),
+            "project": session.get("project"),
+            "token_estimate": session.get("token_estimate"),
+        }
+    return None
+
+
+def extract_agent(result: dict[str, Any], args: dict[str, Any]) -> dict[str, Any]:
+    if isinstance(result.get("agent"), dict):
+        return result["agent"]
+    if result.get("agent_id"):
+        return {"id": result.get("agent_id")}
+    if args.get("agent"):
+        return {"id": args.get("agent")}
+    route = result.get("route") if isinstance(result.get("route"), dict) else {}
+    if route.get("agent_id"):
+        return {"id": route.get("agent_id"), "capability": route.get("capability_id")}
+    return {}
+
+
+def extract_providers(result: dict[str, Any]) -> Any:
+    if result.get("providers") is not None:
+        return result.get("providers")
+    route = result.get("route") if isinstance(result.get("route"), dict) else {}
+    provider = result.get("provider") or route.get("provider") or result.get("source_provider")
+    return {"used": [provider], "missing": [], "skipped": []} if provider else {"used": [], "missing": [], "skipped": []}
+
+
+def extract_sources(result: dict[str, Any]) -> list[Any]:
+    source = result.get("source")
+    if source:
+        return [source]
+    return []
+
+
+def extract_commands(result: dict[str, Any]) -> list[Any]:
+    commands = []
+    command = result.get("command")
+    if command:
+        commands.append(command)
+    for attempt in result.get("llm_backend_attempts") or []:
+        if isinstance(attempt, dict) and attempt.get("command"):
+            commands.append(attempt["command"])
+    return commands
+
+
+def extract_permissions(result: dict[str, Any]) -> list[Any]:
+    permissions = []
+    for key in ("permission", "permissions"):
+        if result.get(key):
+            permissions.append(result[key])
+    preview = result.get("preview") if isinstance(result.get("preview"), dict) else {}
+    if preview.get("permissions"):
+        permissions.append(preview["permissions"])
+    return permissions
+
+
+def extract_llm_backends(result: dict[str, Any]) -> list[Any]:
+    attempts = result.get("llm_backend_attempts")
+    if isinstance(attempts, list):
+        return attempts
+    backend = result.get("llm_backend")
+    return [{"id": backend}] if backend else []
+
+
+def extract_token_estimate(result: dict[str, Any]) -> int | None:
+    session = result.get("session") if isinstance(result.get("session"), dict) else {}
+    if session.get("token_estimate") is not None:
+        return int(session.get("token_estimate") or 0)
+    prompt_length = result.get("prompt_length")
+    return int(prompt_length / 4) if isinstance(prompt_length, int) else None
+
+
+def extract_external_actions(result: dict[str, Any]) -> list[dict[str, Any]]:
+    actions: list[dict[str, Any]] = []
+    preview = result.get("preview") if isinstance(result.get("preview"), dict) else {}
+    if preview.get("external_writes"):
+        actions.append({"type": preview.get("action_type"), "external_writes": True})
+    if result.get("external_action"):
+        actions.append(result["external_action"])
+    return actions
+
+
+def summarize_result(result: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "kind": result.get("kind"),
+        "status": result.get("status"),
+        "ok": result.get("ok"),
+        "exit_code": result.get("exit_code"),
+        "message": result.get("message"),
+        "mode": result.get("mode"),
+    }
+
+
+def safe_user() -> str:
+    try:
+        return redact_secrets(getpass.getuser())
+    except Exception:
+        return "unknown"
+
+
+def render_audit_md(entry: dict[str, Any]) -> str:
+    lines = [
+        f"# Audit {entry.get('id')}",
+        "",
+        f"- Created at: `{entry.get('created_at')}`",
+        f"- User: `{entry.get('user')}`",
+        f"- Command: `{entry.get('command')}`",
+        f"- Status: `{(entry.get('result') or {}).get('status')}`",
+        f"- OK: `{(entry.get('result') or {}).get('ok')}`",
+        "",
+        "## Prompt",
+        "",
+        entry.get("prompt") or "-",
+        "",
+        "## Agent",
+        "",
+        "```json",
+        json.dumps(entry.get("agent") or {}, ensure_ascii=False, indent=2, sort_keys=True),
+        "```",
+        "",
+        "## Providers",
+        "",
+        "```json",
+        json.dumps(entry.get("providers") or {}, ensure_ascii=False, indent=2, sort_keys=True),
+        "```",
+        "",
+        "## Permissions",
+        "",
+        "```json",
+        json.dumps(entry.get("permissions") or [], ensure_ascii=False, indent=2, sort_keys=True),
+        "```",
+        "",
+        "## Result",
+        "",
+        "```json",
+        json.dumps(entry.get("result") or {}, ensure_ascii=False, indent=2, sort_keys=True),
+        "```",
+    ]
+    if entry.get("error"):
+        lines.extend(["", "## Error", "", str(entry["error"])])
+    lines.append("")
+    return "\n".join(lines)