agent-devkit 0.0.4 → 0.1.5

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?",
+    ]

package/runtime/cli/aikit/provider_wizard.py

@@ -0,0 +1,19 @@
+"""Backward-compatible provider wizard wrapper."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.configuration_orchestrator import provider_setup_wizard
+
+
+def missing_source_wizard(prompt: str, route: dict[str, Any], *, root: Path | None = None) -> dict[str, Any]:
+    provider = str(route.get("provider") or "")
+    return provider_setup_wizard(
+        root or Path(__file__).resolve().parents[2],
+        provider,
+        prompt=prompt,
+        route=route,
+        reason="No reusable source is configured for this routed prompt.",
+    )

package/runtime/cli/aikit/providers.py

@@ -8,6 +8,7 @@ import re
 from pathlib import Path
 from typing import Any
 
+from cli.aikit.app_home import app_home, config_path as app_config_path, ensure_app_home
 from cli.aikit.credentials import CredentialResolverError, resolve_provider_credentials
 
 
@@ -454,14 +455,11 @@ def load_provider_config(provider_id: str) -> dict[str, Any]:
 
 
 def runtime_config_home() -> Path:
-    raw = os.environ.get("AIKIT_CONFIG_HOME") or os.environ.get("AI_DEVKIT_CONFIG_HOME")
-    if raw:
-        return Path(raw).expanduser().resolve()
-    return (Path.home() / ".ai-devkit").resolve()
+    return app_home()
 
 
 def runtime_config_path() -> Path:
-    return runtime_config_home() / "config.json"
+    return app_config_path()
 
 
 def load_runtime_config() -> dict[str, Any]:
@@ -479,6 +477,7 @@ def load_runtime_config() -> dict[str, Any]:
 
 
 def save_runtime_config(config: dict[str, Any]) -> Path:
+    ensure_app_home()
     path = runtime_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")

package/runtime/cli/aikit/review_gate.py

@@ -0,0 +1,40 @@
+"""Mandatory review gate decisions before completing agentic work."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+
+REVIEW_REQUIRED_PATTERN = re.compile(
+    r"(?i)\b(c[oó]digo|software|documento|spec|especifica|requisit|plano|automac|pr|pull request|deploy|infra|sql|banco|seguran)\b"
+)
+
+
+def build_review_gate(prompt: str, *, route: dict[str, Any] | None = None, model_plan: dict[str, Any] | None = None) -> dict[str, Any]:
+    required = bool(REVIEW_REQUIRED_PATTERN.search(prompt))
+    if route:
+        required = True
+    if model_plan and (model_plan.get("local_llm_selected") or model_plan.get("local_llm_recommended")):
+        required = True
+    return {
+        "kind": "review-gate",
+        "required": required,
+        "status": "pending" if required else "not-required",
+        "preferred_reviewers": ["claude-code", "codex-cli"],
+        "reason": (
+            "Deliverable or delegated local-LLM work requires coordinator review before completion."
+            if required
+            else "Prompt does not require a formal review gate."
+        ),
+        "route": route,
+    }
+
+
+def mark_reviewed(payload: dict[str, Any], *, reviewer: str | None = None, notes: str | None = None) -> dict[str, Any]:
+    gate = dict(payload)
+    if gate.get("required"):
+        gate["status"] = "reviewed"
+        gate["reviewer"] = reviewer or "coordinator"
+        gate["notes"] = notes or "Reviewed by the active coordinator before final response."
+    return gate

package/runtime/cli/aikit/scheduler.py

@@ -0,0 +1,18 @@
+"""Local scheduler entrypoints for Agent DevKit."""
+
+from __future__ import annotations
+
+from cli.aikit.tasks import scheduler_run_once
+
+
+def run_scheduler_once(*, dry_run: bool = False) -> dict:
+    return scheduler_run_once(dry_run=dry_run)
+
+
+def scheduler_daemon_plan() -> dict:
+    return {
+        "kind": "scheduler",
+        "status": "planned",
+        "daemon": True,
+        "message": "Scheduler daemon is not started by the MVP CLI. Use `agent scheduler run-once` from cron/systemd/launchd.",
+    }