agent-devkit 0.0.3 → 0.1.0

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/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/permissions.py

@@ -0,0 +1,345 @@
+"""Local permission policy helpers for Agent DevKit."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.app_home import ensure_app_home, policies_home
+from cli.aikit.memory import redact_secrets
+
+
+PERMISSION_LEVELS = (
+    "read-only",
+    "draft-only",
+    "comment-with-approval",
+    "write-with-approval",
+    "auto-write",
+    "admin",
+)
+DEFAULT_PERMISSION_LEVEL = "read-only"
+PROVIDER_BY_AGENT = {
+    "github-pr-reviewer": "github",
+}
+ACTION_REQUIRED_LEVEL = {
+    "read": "read-only",
+    "draft": "draft-only",
+    "comment": "comment-with-approval",
+    "write": "write-with-approval",
+    "approve": "write-with-approval",
+    "request-changes": "write-with-approval",
+    "admin": "admin",
+}
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def ensure_policies_home() -> Path:
+    ensure_app_home()
+    home = policies_home()
+    home.mkdir(parents=True, exist_ok=True)
+    return home
+
+
+def permissions_json_path() -> Path:
+    return ensure_policies_home() / "permissions.json"
+
+
+def permissions_md_path() -> Path:
+    return ensure_policies_home() / "permissions.md"
+
+
+def empty_policy() -> dict[str, Any]:
+    return {
+        "version": 1,
+        "default_level": DEFAULT_PERMISSION_LEVEL,
+        "grants": [],
+    }
+
+
+def load_permissions() -> dict[str, Any]:
+    path = permissions_json_path()
+    if not path.exists():
+        policy = empty_policy()
+        save_permissions(policy)
+        return policy
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        backup = path.with_suffix(f".corrupt-{datetime.now(timezone.utc).strftime('%Y%m%d%H%M%S')}.json")
+        path.replace(backup)
+        data = empty_policy()
+    if not isinstance(data, dict):
+        data = empty_policy()
+    data.setdefault("version", 1)
+    data.setdefault("default_level", DEFAULT_PERMISSION_LEVEL)
+    if data.get("default_level") not in PERMISSION_LEVELS:
+        data["default_level"] = DEFAULT_PERMISSION_LEVEL
+    if not isinstance(data.get("grants"), list):
+        data["grants"] = []
+    return data
+
+
+def save_permissions(policy: dict[str, Any]) -> Path:
+    ensure_policies_home()
+    path = permissions_json_path()
+    path.write_text(json.dumps(policy, ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    permissions_md_path().write_text(render_permissions_md(policy), encoding="utf-8")
+    return path
+
+
+def show_permissions() -> dict[str, Any]:
+    policy = load_permissions()
+    return {
+        "kind": "permissions",
+        "status": "ok",
+        "default_level": policy["default_level"],
+        "levels": list(PERMISSION_LEVELS),
+        "grants": [public_grant(item) for item in policy["grants"] if isinstance(item, dict)],
+        "json_path": str(permissions_json_path()),
+        "markdown_path": str(permissions_md_path()),
+    }
+
+
+def grant_permission(
+    agent: str,
+    provider: str,
+    level: str,
+    *,
+    project: str | None = None,
+    task_id: str | None = None,
+) -> dict[str, Any]:
+    validate_level(level)
+    policy = load_permissions()
+    grants = [item for item in policy["grants"] if isinstance(item, dict)]
+    grant = find_grant(grants, agent=agent, provider=provider, project=project, task_id=task_id)
+    timestamp = now_iso()
+    if grant:
+        grant["level"] = level
+        grant["updated_at"] = timestamp
+    else:
+        grant = {
+            "agent": agent,
+            "provider": provider,
+            "level": level,
+            "project": project,
+            "task_id": task_id,
+            "created_at": timestamp,
+            "updated_at": timestamp,
+        }
+        grants.append(grant)
+    policy["grants"] = grants
+    path = save_permissions(policy)
+    return {
+        "kind": "permissions",
+        "status": "granted",
+        "grant": public_grant(grant),
+        "json_path": str(path),
+        "markdown_path": str(permissions_md_path()),
+    }
+
+
+def revoke_permission(
+    agent: str,
+    provider: str,
+    level: str | None = None,
+    *,
+    project: str | None = None,
+    task_id: str | None = None,
+) -> dict[str, Any]:
+    if level:
+        validate_level(level)
+    policy = load_permissions()
+    removed: list[dict[str, Any]] = []
+    kept: list[dict[str, Any]] = []
+    for item in policy["grants"]:
+        if not isinstance(item, dict):
+            continue
+        matches = (
+            item.get("agent") == agent
+            and item.get("provider") == provider
+            and item.get("project") == project
+            and item.get("task_id") == task_id
+            and (level is None or item.get("level") == level)
+        )
+        if matches:
+            removed.append(item)
+        else:
+            kept.append(item)
+    policy["grants"] = kept
+    path = save_permissions(policy)
+    return {
+        "kind": "permissions",
+        "status": "revoked" if removed else "not-found",
+        "removed": [public_grant(item) for item in removed],
+        "json_path": str(path),
+        "markdown_path": str(permissions_md_path()),
+    }
+
+
+def permission_check(
+    *,
+    agent: str | None,
+    provider: str | None,
+    action: str,
+    project: str | None = None,
+    task_id: str | None = None,
+) -> dict[str, Any]:
+    required = required_level_for_action(action)
+    resolved_provider = provider or provider_for_agent(agent)
+    policy = load_permissions()
+    grant = best_grant(
+        policy["grants"],
+        agent=agent,
+        provider=resolved_provider,
+        project=project,
+        task_id=task_id,
+    )
+    granted = normalize_level(grant.get("level") if grant else policy.get("default_level", DEFAULT_PERMISSION_LEVEL))
+    allowed = level_allows(granted, required)
+    return {
+        "kind": "permission-check",
+        "status": "allowed" if allowed else "blocked",
+        "ok": allowed,
+        "agent": agent,
+        "provider": resolved_provider,
+        "action": action,
+        "required_level": required,
+        "granted_level": granted,
+        "grant": public_grant(grant) if grant else None,
+        "default_level": policy.get("default_level", DEFAULT_PERMISSION_LEVEL),
+        "requires_permission": not allowed,
+    }
+
+
+def assert_permission(
+    *,
+    agent: str | None,
+    provider: str | None,
+    action: str,
+    project: str | None = None,
+    task_id: str | None = None,
+) -> dict[str, Any]:
+    return permission_check(agent=agent, provider=provider, action=action, project=project, task_id=task_id)
+
+
+def provider_for_agent(agent: str | None) -> str | None:
+    return PROVIDER_BY_AGENT.get(agent or "")
+
+
+def required_level_for_action(action: str) -> str:
+    return ACTION_REQUIRED_LEVEL.get(action, action if action in PERMISSION_LEVELS else "write-with-approval")
+
+
+def normalize_level(level: Any) -> str:
+    return str(level) if str(level) in PERMISSION_LEVELS else DEFAULT_PERMISSION_LEVEL
+
+
+def level_allows(granted: str, required: str) -> bool:
+    validate_level(granted)
+    validate_level(required)
+    return PERMISSION_LEVELS.index(granted) >= PERMISSION_LEVELS.index(required)
+
+
+def validate_level(level: str) -> None:
+    if level not in PERMISSION_LEVELS:
+        available = ", ".join(PERMISSION_LEVELS)
+        raise ValueError(f"unknown permission level: {level}. available: {available}")
+
+
+def best_grant(
+    grants: list[Any],
+    *,
+    agent: str | None,
+    provider: str | None,
+    project: str | None,
+    task_id: str | None,
+) -> dict[str, Any] | None:
+    candidates = [
+        item
+        for item in grants
+        if isinstance(item, dict)
+        and item.get("agent") == agent
+        and item.get("provider") == provider
+        and item.get("project") in {None, project}
+        and item.get("task_id") in {None, task_id}
+    ]
+    if not candidates:
+        return None
+    candidates.sort(key=grant_specificity, reverse=True)
+    return candidates[0]
+
+
+def find_grant(
+    grants: list[dict[str, Any]],
+    *,
+    agent: str,
+    provider: str,
+    project: str | None,
+    task_id: str | None,
+) -> dict[str, Any] | None:
+    for item in grants:
+        if (
+            item.get("agent") == agent
+            and item.get("provider") == provider
+            and item.get("project") == project
+            and item.get("task_id") == task_id
+        ):
+            return item
+    return None
+
+
+def grant_specificity(grant: dict[str, Any]) -> tuple[int, int]:
+    scope = int(bool(grant.get("project"))) + int(bool(grant.get("task_id")))
+    return scope, PERMISSION_LEVELS.index(normalize_level(grant.get("level")))
+
+
+def public_grant(grant: dict[str, Any] | None) -> dict[str, Any] | None:
+    if not grant:
+        return None
+    return {
+        "agent": grant.get("agent"),
+        "provider": grant.get("provider"),
+        "level": grant.get("level"),
+        "project": grant.get("project"),
+        "task_id": grant.get("task_id"),
+        "created_at": grant.get("created_at"),
+        "updated_at": grant.get("updated_at"),
+    }
+
+
+def render_permissions_md(policy: dict[str, Any]) -> str:
+    lines = [
+        "# Agent DevKit Permissions",
+        "",
+        f"- Default level: `{redact_secrets(str(policy.get('default_level') or DEFAULT_PERMISSION_LEVEL))}`",
+        "",
+        "## Levels",
+        "",
+    ]
+    for level in PERMISSION_LEVELS:
+        lines.append(f"- `{level}`")
+    lines.extend(["", "## Grants", ""])
+    grants = [item for item in policy.get("grants", []) if isinstance(item, dict)]
+    if not grants:
+        lines.append("- No explicit grants configured.")
+    for item in grants:
+        scope = []
+        if item.get("project"):
+            scope.append(f"project={item['project']}")
+        if item.get("task_id"):
+            scope.append(f"task={item['task_id']}")
+        scope_text = f" ({', '.join(scope)})" if scope else ""
+        lines.append(
+            "- "
+            f"`{redact_secrets(str(item.get('agent') or '-'))}` / "
+            f"`{redact_secrets(str(item.get('provider') or '-'))}` -> "
+            f"`{redact_secrets(str(item.get('level') or DEFAULT_PERMISSION_LEVEL))}`"
+            f"{scope_text}"
+        )
+    lines.append("")
+    return "\n".join(lines)

package/runtime/cli/aikit/personality.py

@@ -0,0 +1,123 @@
+"""Local Agent DevKit personality persistence."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.identity import DEFAULT_PUBLIC_NAME
+from cli.aikit.memory import MEMORY_FILE_TEMPLATES, ensure_memory, memory_home
+
+
+FIELD_LABELS = {
+    "agent_name": "Name",
+    "user_name": "User name",
+    "language": "Language",
+    "tone": "Tone",
+    "detail_level": "Detail level",
+}
+
+
+def personality_path() -> Path:
+    ensure_memory()
+    return memory_home() / "personality.md"
+
+
+def load_personality() -> dict[str, Any]:
+    path = personality_path()
+    text = path.read_text(encoding="utf-8") if path.exists() else ""
+    return {
+        "kind": "personality",
+        "status": "ok",
+        "path": str(path),
+        "agent_name": parse_field(text, FIELD_LABELS["agent_name"]) or DEFAULT_PUBLIC_NAME,
+        "user_name": parse_field(text, FIELD_LABELS["user_name"]),
+        "language": parse_field(text, FIELD_LABELS["language"]),
+        "tone": parse_field(text, FIELD_LABELS["tone"]) or "direct",
+        "detail_level": parse_field(text, FIELD_LABELS["detail_level"]) or "concise",
+        "questions": setup_questions(),
+    }
+
+
+def update_personality(
+    *,
+    agent_name: str | None = None,
+    user_name: str | None = None,
+    language: str | None = None,
+    tone: str | None = None,
+    detail_level: str | None = None,
+) -> dict[str, Any]:
+    current = load_personality()
+    values = {
+        "agent_name": clean_field(agent_name) or current.get("agent_name") or DEFAULT_PUBLIC_NAME,
+        "user_name": clean_field(user_name) if user_name is not None else current.get("user_name"),
+        "language": clean_field(language) if language is not None else current.get("language"),
+        "tone": clean_field(tone) or current.get("tone") or "direct",
+        "detail_level": clean_field(detail_level) or current.get("detail_level") or "concise",
+    }
+    path = personality_path()
+    path.write_text(render_personality(values), encoding="utf-8")
+    payload = load_personality()
+    payload["status"] = "updated"
+    return payload
+
+
+def reset_personality() -> dict[str, Any]:
+    path = personality_path()
+    path.write_text(MEMORY_FILE_TEMPLATES["personality.md"], encoding="utf-8")
+    payload = load_personality()
+    payload["status"] = "reset"
+    return payload
+
+
+def setup_personality() -> dict[str, Any]:
+    payload = load_personality()
+    payload["status"] = "needs-input"
+    payload["message"] = "Use `agent personality edit --name <nome>` to configure personality non-interactively."
+    return payload
+
+
+def render_personality(values: dict[str, Any]) -> str:
+    return f"""# Personality
+
+Configured public identity and response style for Agent DevKit.
+
+## Agent
+
+- Name: {values.get("agent_name") or DEFAULT_PUBLIC_NAME}
+- User name: {values.get("user_name") or ""}
+- Language: {values.get("language") or ""}
+
+## Style
+
+- Tone: {values.get("tone") or "direct"}
+- Detail level: {values.get("detail_level") or "concise"}
+"""
+
+
+def parse_field(text: str, label: str) -> str | None:
+    pattern = re.compile(rf"(?im)^[ \t]*-[ \t]*{re.escape(label)}[ \t]*:[ \t]*([^\r\n]*)[ \t]*$")
+    match = pattern.search(text)
+    if not match:
+        return None
+    value = match.group(1).strip()
+    return value or None
+
+
+def clean_field(value: str | None) -> str | None:
+    if value is None:
+        return None
+    cleaned = " ".join(str(value).split())
+    return cleaned or None
+
+
+def setup_questions() -> list[str]:
+    return [
+        "Como voce deseja que eu me chame?",
+        "Deseja criar um comando com esse nome para me chamar diretamente?",
+        "Como voce se chama?",
+        "Em qual idioma devo responder por padrao?",
+        "Voce prefere respostas curtas, detalhadas, criticas ou didaticas?",
+        "Qual backend LLM voce prefere como primario?",
+    ]