agent-devkit 0.0.4 → 0.1.0

package/runtime/cli/aikit/tasks.py

@@ -0,0 +1,351 @@
+"""Local task and scheduler primitives for Agent DevKit."""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+from datetime import datetime, time, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.app_home import ensure_app_home, tasks_home
+from cli.aikit.memory import redact_secrets
+from cli.aikit.permissions import permission_check, provider_for_agent
+
+
+TASK_ID_PATTERN = re.compile(r"^[a-zA-Z0-9][a-zA-Z0-9_.-]*$")
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def ensure_tasks_home() -> Path:
+    ensure_app_home()
+    home = tasks_home()
+    (home / "history").mkdir(parents=True, exist_ok=True)
+    return home
+
+
+def tasks_path() -> Path:
+    return ensure_tasks_home() / "tasks.json"
+
+
+def history_path(task_id: str) -> Path:
+    return ensure_tasks_home() / "history" / f"{safe_task_id(task_id)}.md"
+
+
+def load_tasks() -> dict[str, Any]:
+    path = tasks_path()
+    if not path.exists():
+        return {"version": 1, "tasks": []}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return {"version": 1, "tasks": []}
+    if not isinstance(data, dict):
+        return {"version": 1, "tasks": []}
+    tasks = data.get("tasks")
+    if not isinstance(tasks, list):
+        data["tasks"] = []
+    data.setdefault("version", 1)
+    return data
+
+
+def save_tasks(data: dict[str, Any]) -> Path:
+    path = tasks_path()
+    path.write_text(json.dumps(data, ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return path
+
+
+def list_tasks() -> dict[str, Any]:
+    data = load_tasks()
+    return {
+        "kind": "tasks",
+        "status": "ok",
+        "path": str(tasks_path()),
+        "items": [public_task(item) for item in data["tasks"] if isinstance(item, dict)],
+    }
+
+
+def create_task(
+    *,
+    task_id: str | None = None,
+    title: str | None = None,
+    prompt: str | None = None,
+    schedule: dict[str, Any] | None = None,
+    action: dict[str, Any] | None = None,
+    permissions: dict[str, Any] | None = None,
+    notifications: list[dict[str, Any]] | None = None,
+    enabled: bool = True,
+) -> dict[str, Any]:
+    data = load_tasks()
+    raw_id = task_id or slugify(title or prompt or "task")
+    task_id = unique_task_id(raw_id, data)
+    created_at = now_iso()
+    task = {
+        "id": task_id,
+        "title": title or prompt or task_id,
+        "status": "enabled" if enabled else "disabled",
+        "created_at": created_at,
+        "updated_at": created_at,
+        "schedule": schedule or {"type": "manual"},
+        "action": action or {"type": "prompt", "prompt": redact_secrets(prompt or "")},
+        "permissions": permissions or {"mode": "report-only"},
+        "notifications": notifications or [{"type": "terminal"}],
+        "run_count": 0,
+    }
+    data["tasks"].append(task)
+    save_tasks(data)
+    append_history(task_id, f"Created task `{task_id}`.")
+    return {"kind": "task", "status": "created", "task": public_task(task), "path": str(tasks_path())}
+
+
+def show_task(task_id: str) -> dict[str, Any]:
+    task = find_task(task_id)
+    return {"kind": "task", "status": "ok", "task": public_task(task), "path": str(tasks_path())}
+
+
+def task_history(task_id: str) -> dict[str, Any]:
+    task = find_task(task_id)
+    path = history_path(str(task["id"]))
+    return {
+        "kind": "task-history",
+        "status": "ok",
+        "task": public_task(task),
+        "path": str(path),
+        "history": path.read_text(encoding="utf-8") if path.exists() else "",
+    }
+
+
+def run_task(task_id: str, *, dry_run: bool = False) -> dict[str, Any]:
+    data = load_tasks()
+    task = find_task_in_data(data, task_id)
+    if task.get("status") in {"paused", "disabled"}:
+        return {"kind": "task-run", "status": "skipped", "ok": False, "task": public_task(task), "message": "Task is not enabled.", "exit_code": 2}
+    preview = task_run_preview(task)
+    if dry_run:
+        return {"kind": "task-run", "status": "planned", "ok": True, "dry_run": True, "task": public_task(task), "preview": preview}
+    permission = task_external_write_permission(task)
+    if not permission["ok"]:
+        append_history(str(task["id"]), f"Blocked task `{task['id']}` because it requires external write permission.")
+        return {
+            "kind": "task-run",
+            "status": "blocked",
+            "ok": False,
+            "dry_run": False,
+            "task": public_task(task),
+            "preview": preview,
+            "permission": permission,
+            "requires_permission": True,
+            "message": "Task declares external_writes=true and does not have explicit external write permission.",
+            "exit_code": 2,
+        }
+    task["run_count"] = int(task.get("run_count") or 0) + 1
+    task["last_run_at"] = now_iso()
+    task["updated_at"] = task["last_run_at"]
+    save_tasks(data)
+    append_history(str(task["id"]), f"Executed task `{task['id']}` in local scheduler.")
+    return {"kind": "task-run", "status": "ok", "ok": True, "dry_run": False, "task": public_task(task), "preview": preview}
+
+
+def scheduler_run_once(*, dry_run: bool = False) -> dict[str, Any]:
+    data = load_tasks()
+    due = [item for item in data["tasks"] if isinstance(item, dict) and item.get("status") == "enabled" and task_is_due(item)]
+    runs = [run_task(str(item["id"]), dry_run=dry_run) for item in due]
+    return {"kind": "scheduler", "status": "ok", "dry_run": dry_run, "due_count": len(due), "runs": runs}
+
+
+def update_task_status(task_id: str, status: str) -> dict[str, Any]:
+    data = load_tasks()
+    task = find_task_in_data(data, task_id)
+    task["status"] = status
+    task["updated_at"] = now_iso()
+    save_tasks(data)
+    append_history(str(task["id"]), f"Status changed to `{status}`.")
+    return {"kind": "task", "status": "updated", "task": public_task(task), "path": str(tasks_path())}
+
+
+def update_task_schedule(task_id: str, *, every: str | None = None, cron: str | None = None) -> dict[str, Any]:
+    data = load_tasks()
+    task = find_task_in_data(data, task_id)
+    if every:
+        task["schedule"] = {"type": "interval", "every": every}
+    if cron:
+        task["schedule"] = {"type": "cron", "cron": cron}
+    task["updated_at"] = now_iso()
+    save_tasks(data)
+    append_history(str(task["id"]), "Schedule updated.")
+    return {"kind": "task", "status": "updated", "task": public_task(task), "path": str(tasks_path())}
+
+
+def delete_task(task_id: str, *, yes: bool = False) -> dict[str, Any]:
+    if not yes:
+        return {"kind": "task", "status": "needs-confirmation", "ok": False, "message": "Deleting a task requires --yes.", "exit_code": 2}
+    data = load_tasks()
+    task = find_task_in_data(data, task_id)
+    data["tasks"] = [item for item in data["tasks"] if not isinstance(item, dict) or item.get("id") != task.get("id")]
+    save_tasks(data)
+    append_history(str(task["id"]), "Task deleted.")
+    return {"kind": "task", "status": "deleted", "task": public_task(task), "path": str(tasks_path())}
+
+
+def reset_tasks() -> list[str]:
+    home = tasks_home()
+    removed: list[str] = []
+    if home.exists():
+        removed.append(str(home))
+        shutil.rmtree(home)
+    ensure_tasks_home()
+    return removed
+
+
+def public_task(task: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "id": task.get("id"),
+        "title": task.get("title"),
+        "status": task.get("status"),
+        "created_at": task.get("created_at"),
+        "updated_at": task.get("updated_at"),
+        "schedule": task.get("schedule") or {},
+        "action": task.get("action") or {},
+        "permissions": task.get("permissions") or {},
+        "notifications": task.get("notifications") or [],
+        "run_count": int(task.get("run_count") or 0),
+        "last_run_at": task.get("last_run_at"),
+    }
+
+
+def task_run_preview(task: dict[str, Any]) -> dict[str, Any]:
+    action = task.get("action") if isinstance(task.get("action"), dict) else {}
+    return {
+        "task_id": task.get("id"),
+        "action_type": action.get("type"),
+        "agent": action.get("agent"),
+        "capability": action.get("capability"),
+        "prompt": action.get("prompt"),
+        "external_writes": bool(action.get("external_writes")),
+        "permissions": task.get("permissions") or {},
+    }
+
+
+def task_requires_external_write_permission(task: dict[str, Any]) -> bool:
+    return not task_external_write_permission(task)["ok"]
+
+
+def task_is_due(task: dict[str, Any], *, now: datetime | None = None) -> bool:
+    now = now or datetime.now(timezone.utc)
+    schedule = task.get("schedule") if isinstance(task.get("schedule"), dict) else {}
+    schedule_type = schedule.get("type") or "manual"
+    if schedule_type == "manual":
+        return False
+    last_run_at = parse_iso_datetime(task.get("last_run_at"))
+    if schedule_type == "interval":
+        interval = parse_interval(str(schedule.get("every") or ""))
+        if interval is None:
+            return False
+        return last_run_at is None or last_run_at + interval <= now
+    if schedule_type == "daily":
+        scheduled_time = parse_time(str(schedule.get("time") or "00:00")) or time(0, 0)
+        if now.time().replace(tzinfo=None) < scheduled_time:
+            return False
+        return last_run_at is None or last_run_at.date() < now.date()
+    if schedule_type == "cron":
+        # Full cron parsing is outside the local MVP; run once after creation
+        # and require an external scheduler for precise recurrence.
+        return last_run_at is None
+    return False
+
+
+def parse_interval(value: str) -> timedelta | None:
+    match = re.fullmatch(r"\s*(\d+)\s*([mhd])\s*", value.lower())
+    if not match:
+        return None
+    amount = int(match.group(1))
+    unit = match.group(2)
+    if amount <= 0:
+        return None
+    if unit == "m":
+        return timedelta(minutes=amount)
+    if unit == "h":
+        return timedelta(hours=amount)
+    return timedelta(days=amount)
+
+
+def parse_time(value: str) -> time | None:
+    try:
+        return datetime.strptime(value, "%H:%M").time()
+    except ValueError:
+        return None
+
+
+def parse_iso_datetime(value: Any) -> datetime | None:
+    if not value:
+        return None
+    try:
+        parsed = datetime.fromisoformat(str(value))
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=timezone.utc)
+    return parsed.astimezone(timezone.utc)
+
+
+def task_external_write_permission(task: dict[str, Any]) -> dict[str, Any]:
+    action = task.get("action") if isinstance(task.get("action"), dict) else {}
+    permissions = task.get("permissions") if isinstance(task.get("permissions"), dict) else {}
+    if not bool(action.get("external_writes")):
+        return {"ok": True, "status": "allowed", "requires_permission": False}
+    if bool(permissions.get("external_writes_allowed")):
+        return {"ok": True, "status": "allowed", "source": "task-permission", "requires_permission": False}
+    agent = action.get("agent")
+    provider = action.get("provider") or provider_for_agent(str(agent) if agent else None)
+    check = permission_check(
+        agent=str(agent) if agent else None,
+        provider=str(provider) if provider else None,
+        action=str(permissions.get("required_action") or action.get("required_action") or "write"),
+        task_id=str(task.get("id") or ""),
+    )
+    return check
+
+
+def find_task(task_id: str) -> dict[str, Any]:
+    return find_task_in_data(load_tasks(), task_id)
+
+
+def find_task_in_data(data: dict[str, Any], task_id: str) -> dict[str, Any]:
+    resolved = safe_task_id(task_id)
+    for item in data.get("tasks", []):
+        if isinstance(item, dict) and item.get("id") == resolved:
+            return item
+    raise ValueError(f"task not found: {task_id}")
+
+
+def append_history(task_id: str, message: str) -> None:
+    path = history_path(task_id)
+    line = f"- {now_iso()} {redact_secrets(message)}\n"
+    with path.open("a", encoding="utf-8") as file:
+        file.write(line)
+
+
+def unique_task_id(task_id: str, data: dict[str, Any]) -> str:
+    base = safe_task_id(task_id)
+    existing = {item.get("id") for item in data.get("tasks", []) if isinstance(item, dict)}
+    if base not in existing:
+        return base
+    index = 2
+    while f"{base}-{index}" in existing:
+        index += 1
+    return f"{base}-{index}"
+
+
+def safe_task_id(task_id: str) -> str:
+    if not TASK_ID_PATTERN.fullmatch(task_id):
+        return slugify(task_id)
+    return task_id
+
+
+def slugify(value: str) -> str:
+    slug = re.sub(r"[^a-zA-Z0-9._-]+", "-", value.lower()).strip(".-")
+    return slug[:80] or "task"

package/runtime/cli/aikit/toolchain.py

@@ -0,0 +1,274 @@
+"""Toolchain discovery and controlled install planning."""
+
+from __future__ import annotations
+
+import platform
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+
+TOOLCHAIN_PATH = Path(__file__).resolve().parents[2] / "tooling" / "toolchain.yaml"
+INSTALL_TIMEOUT_SECONDS = 900
+
+
+def list_toolchain(root: Path | None = None) -> dict[str, Any]:
+    tools = load_toolchain(root)
+    return {
+        "kind": "toolchain",
+        "status": "ok",
+        "platform": platform_key(),
+        "path": str(toolchain_path(root)),
+        "items": [public_tool(tool_id, spec) for tool_id, spec in tools.items()],
+    }
+
+
+def doctor_toolchain(root: Path | None = None, tool_id: str | None = None) -> dict[str, Any]:
+    tools = select_tools(root, tool_id)
+    items = [tool_status(item_id, spec) for item_id, spec in tools.items()]
+    required_missing = [item["id"] for item in items if item.get("required") and item.get("status") == "missing"]
+    optional_missing = [item["id"] for item in items if not item.get("required") and item.get("status") == "missing"]
+    status = "ok"
+    if required_missing:
+        status = "missing"
+    elif optional_missing:
+        status = "partial"
+    return {
+        "kind": "toolchain-doctor",
+        "status": status,
+        "platform": platform_key(),
+        "path": str(toolchain_path(root)),
+        "required_missing": required_missing,
+        "optional_missing": optional_missing,
+        "items": items,
+    }
+
+
+def install_toolchain(
+    root: Path | None = None,
+    tool_id: str | None = None,
+    *,
+    dry_run: bool = False,
+    yes: bool = False,
+) -> dict[str, Any]:
+    tools = select_tools(root, tool_id)
+    platform_name = platform_key()
+    plans = []
+    for item_id, spec in tools.items():
+        current_status = tool_status(item_id, spec)
+        already_installed = current_status.get("status") == "ok"
+        command = None if already_installed else install_command(spec, platform_name)
+        plans.append(
+            {
+                "id": item_id,
+                "label": spec.get("label") or item_id,
+                "command": command,
+                "status": "already-installed" if already_installed else "planned",
+                "binary": current_status.get("binary"),
+                "executable": is_executable_install_command(command),
+            }
+        )
+
+    if dry_run:
+        return install_payload("planned", plans, dry_run=True, yes=yes, executed=[])
+    if not yes:
+        return install_payload(
+            "needs-confirmation",
+            plans,
+            dry_run=False,
+            yes=False,
+            executed=[],
+            message="External tool installation requires --yes. Use --dry-run to inspect the plan.",
+        )
+
+    executed: list[dict[str, Any]] = []
+    for plan in plans:
+        if plan["status"] == "already-installed":
+            executed.append({**plan, "status": "already-installed", "message": "Tool already available in PATH."})
+            continue
+        if not plan["executable"]:
+            executed.append({**plan, "status": "skipped", "message": "Manual installation instruction."})
+            continue
+        process = subprocess.run(
+            str(plan["command"]),
+            shell=True,
+            check=False,
+            text=True,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            timeout=INSTALL_TIMEOUT_SECONDS,
+        )
+        executed.append(
+            {
+                **plan,
+                "status": "installed" if process.returncode == 0 else "failed",
+                "exit_code": process.returncode,
+                "stdout": safe_tail(redact_environment_secrets(process.stdout)),
+                "stderr": safe_tail(redact_environment_secrets(process.stderr)),
+            }
+        )
+    status = "installed" if all(item["status"] in {"installed", "skipped", "already-installed"} for item in executed) else "failed"
+    return install_payload(status, plans, dry_run=False, yes=True, executed=executed)
+
+
+def setup_plan(root: Path | None = None, *, dry_run: bool = False, yes: bool = False) -> dict[str, Any]:
+    doctor = doctor_toolchain(root)
+    if yes and not dry_run:
+        install = install_toolchain(root, "all", dry_run=False, yes=True)
+    else:
+        install = install_toolchain(root, "all", dry_run=True, yes=yes)
+    status = install["status"] if yes and not dry_run else "planned"
+    return {
+        "kind": "setup",
+        "status": status,
+        "dry_run": dry_run,
+        "yes": yes,
+        "toolchain": doctor,
+        "install_plan": install["plans"],
+        "install": install,
+        "next_steps": [
+            "Run `agent toolchain doctor` to inspect local dependencies.",
+            "Run `agent toolchain install <tool> --dry-run` before installing external tools.",
+            "Use `agent setup personality` to configure local identity and style.",
+        ],
+    }
+
+
+def install_payload(
+    status: str,
+    plans: list[dict[str, Any]],
+    *,
+    dry_run: bool,
+    yes: bool,
+    executed: list[dict[str, Any]],
+    message: str | None = None,
+) -> dict[str, Any]:
+    payload = {
+        "kind": "toolchain-install",
+        "status": status,
+        "platform": platform_key(),
+        "dry_run": dry_run,
+        "yes": yes,
+        "stored_secret": False,
+        "plans": plans,
+        "executed": executed,
+    }
+    if message:
+        payload["message"] = message
+    return payload
+
+
+def load_toolchain(root: Path | None = None) -> dict[str, dict[str, Any]]:
+    path = toolchain_path(root)
+    try:
+        import yaml  # type: ignore
+    except ImportError:
+        return fallback_toolchain()
+    with path.open(encoding="utf-8") as file:
+        data = yaml.safe_load(file) or {}
+    tools = data.get("tools") if isinstance(data, dict) else {}
+    if not isinstance(tools, dict):
+        return {}
+    return {str(key): value for key, value in tools.items() if isinstance(value, dict)}
+
+
+def fallback_toolchain() -> dict[str, dict[str, Any]]:
+    return {
+        "node": {"label": "Node.js", "command": "node", "required": True, "install": {}},
+        "python": {"label": "Python", "command": "python3", "required": True, "install": {}},
+        "git": {"label": "Git", "command": "git", "required": True, "install": {}},
+    }
+
+
+def select_tools(root: Path | None, tool_id: str | None) -> dict[str, dict[str, Any]]:
+    tools = load_toolchain(root)
+    if not tool_id or tool_id == "all":
+        return tools
+    if tool_id not in tools:
+        available = ", ".join(sorted(tools)) or "none"
+        raise ValueError(f"unknown toolchain item: {tool_id}. available: {available}")
+    return {tool_id: tools[tool_id]}
+
+
+def public_tool(tool_id: str, spec: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "id": tool_id,
+        "label": spec.get("label") or tool_id,
+        "command": spec.get("command"),
+        "required": bool(spec.get("required")),
+        "install": install_command(spec, platform_key()),
+        "notes": spec.get("notes"),
+    }
+
+
+def tool_status(tool_id: str, spec: dict[str, Any]) -> dict[str, Any]:
+    command = str(spec.get("command") or "")
+    binary = shutil.which(command) if command else None
+    return {
+        **public_tool(tool_id, spec),
+        "status": "ok" if binary else "missing",
+        "binary": binary,
+        "version": read_version(binary),
+    }
+
+
+def read_version(binary: str | None) -> str | None:
+    if not binary:
+        return None
+    for args in ([binary, "--version"], [binary, "version"]):
+        try:
+            process = subprocess.run(args, check=False, text=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=5)
+        except (OSError, subprocess.TimeoutExpired):
+            continue
+        output = (process.stdout or process.stderr or "").strip()
+        if output:
+            return output.splitlines()[0]
+    return None
+
+
+def install_command(spec: dict[str, Any], platform_name: str) -> str | None:
+    install = spec.get("install")
+    if not isinstance(install, dict):
+        return None
+    command = install.get(platform_name) or install.get("default")
+    return str(command) if command else None
+
+
+def is_executable_install_command(command: str | None) -> bool:
+    if not command:
+        return False
+    manual_prefixes = ("See ", "Configure ", "Use ", "Open ", "Install manually")
+    return not command.startswith(manual_prefixes)
+
+
+def platform_key() -> str:
+    system = platform.system().lower()
+    if system == "darwin":
+        return "darwin"
+    if system.startswith("win"):
+        return "windows"
+    return "linux"
+
+
+def toolchain_path(root: Path | None = None) -> Path:
+    if root:
+        return root / "tooling" / "toolchain.yaml"
+    return TOOLCHAIN_PATH
+
+
+def safe_tail(value: str, limit: int = 2000) -> str:
+    text = value or ""
+    return text[-limit:]
+
+
+def redact_environment_secrets(value: str) -> str:
+    redacted = value or ""
+    for key, secret in os.environ.items():
+        if not secret:
+            continue
+        if not any(marker in key.upper() for marker in ("KEY", "TOKEN", "SECRET", "PASSWORD", "PASS", "PAT")):
+            continue
+        redacted = redacted.replace(secret, "[REDACTED]")
+    return redacted

package/runtime/providers/calendar.yaml

@@ -0,0 +1,28 @@
+id: calendar
+name: Calendar
+kind: local-source
+status: draft
+description: Local calendar provider for ICS-backed agenda queries.
+auth_methods: []
+config_fields:
+  - name: CALENDAR_SOURCE_REF
+    required: false
+    secret: false
+  - name: CALENDAR_TIMEZONE
+    required: false
+    secret: false
+health_check:
+  command: agent calendar today
+risk:
+  default: read-sensitive-local
+  writes: false
+fallbacks:
+  - configure_provider
+  - manual_steps
+capabilities:
+  read:
+    - calendar.today
+    - calendar.tomorrow
+    - calendar.list
+  write: []
+write: false

package/runtime/providers/github.yaml

@@ -0,0 +1,42 @@
+id: github
+name: GitHub
+kind: cli-provider
+status: draft
+description: GitHub provider backed by the official GitHub CLI.
+auth_methods:
+  - id: gh-auth
+    label: GitHub CLI auth
+    native: true
+    secret_fields: []
+  - id: token
+    label: GitHub token
+    secret_fields:
+      - GITHUB_TOKEN
+config_fields:
+  - name: GITHUB_TOKEN
+    required: false
+    secret: true
+  - name: GITHUB_HOST
+    required: false
+    secret: false
+detection:
+  env_any:
+    - GITHUB_TOKEN
+health_check:
+  command: gh auth status
+risk:
+  default: read
+  writes: true
+fallbacks:
+  - report_only
+  - manual_steps
+capabilities:
+  read:
+    - pr.list-review-requests
+    - pr.inspect
+    - pr.review-report
+  write:
+    - pr.comment
+    - pr.approve
+    - pr.request-changes
+write: true