naxe 0.1.0__py3-none-any.whl

naxe/auth.py

@@ -0,0 +1,19 @@
+import hashlib
+import os
+
+KEY_PREFIX = "naxe_sk_"
+
+
+def generate_key() -> str:
+    """Generate a random API key. Returns the raw key — shown once, never stored."""
+    return KEY_PREFIX + os.urandom(32).hex()
+
+
+def hash_key(raw_key: str) -> str:
+    """SHA-256 hash of the raw key. This is what gets stored in the DB."""
+    return hashlib.sha256(raw_key.encode()).hexdigest()
+
+
+def validate_key_format(key: str) -> bool:
+    """Check key has correct prefix and length (prefix + 64 hex chars)."""
+    return key.startswith(KEY_PREFIX) and len(key) == len(KEY_PREFIX) + 64

naxe/cli_config.py

@@ -0,0 +1,193 @@
+import os
+import sys
+
+from naxe.config import (
+    resolve_db_url, resolve_db_url_with_source, write_config_url, _CONFIG_FILE,
+    resolve_theme_with_source, write_theme, _THEME_FILE,
+)
+
+
+def main():
+    args = sys.argv[1:]
+
+    if not args:
+        print("Usage: naxe-config <command> [args]")
+        print()
+        print("Commands:")
+        print("  status                 Show DB connection, auth mode, and job summary")
+        print("  set-url <url>          Save a DB URL to ~/.config/naxe/config")
+        print("  get-url                Print the currently resolved DB URL and its source")
+        print("  set-theme <name>       Save a default theme to ~/.config/naxe/theme")
+        print("  get-theme              Print the currently resolved theme and its source")
+        print()
+        print("Agent commands:")
+        print("  register-agent <name>  Register a new agent and print its API key (shown once)")
+        print("  revoke-agent <name>    Revoke an agent's API key")
+        print("  list-agents            List all registered agents")
+        sys.exit(1)
+
+    command = args[0]
+
+    if command == "status":
+        _status()
+
+    elif command == "set-url":
+        if len(args) < 2:
+            print("Usage: naxe-config set-url <url>", file=sys.stderr)
+            sys.exit(1)
+        write_config_url(args[1])
+        print(f"Saved to {_CONFIG_FILE}")
+
+    elif command == "get-url":
+        url, source = resolve_db_url_with_source()
+        print(f"{url}  ({source})")
+
+    elif command == "set-theme":
+        if len(args) < 2:
+            print("Usage: naxe-config set-theme <name>", file=sys.stderr)
+            print("Built-in naxe themes: naxe, naxe-bold")
+            sys.exit(1)
+        write_theme(args[1])
+        print(f"Saved to {_THEME_FILE}")
+
+    elif command == "get-theme":
+        theme, source = resolve_theme_with_source()
+        print(f"{theme}  ({source})")
+
+    elif command == "register-agent":
+        if len(args) < 2:
+            print("Usage: naxe-config register-agent <name>", file=sys.stderr)
+            sys.exit(1)
+        _register_agent(args[1])
+
+    elif command == "revoke-agent":
+        if len(args) < 2:
+            print("Usage: naxe-config revoke-agent <name>", file=sys.stderr)
+            sys.exit(1)
+        _revoke_agent(args[1])
+
+    elif command == "list-agents":
+        _list_agents()
+
+    else:
+        print(f"Unknown command: {command}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _status() -> None:
+    from naxe.schema import get_connection
+    from naxe import store
+    from naxe.config import resolve_theme_with_source
+
+    url, url_source = resolve_db_url_with_source()
+    theme, theme_source = resolve_theme_with_source()
+
+    print(f"Database:  {url}")
+    print(f"           ({url_source})")
+
+    try:
+        conn = get_connection(url, readonly=True)
+    except Exception as e:
+        print(f"Status:    ✗ Cannot connect — {e}")
+        sys.exit(1)
+
+    print(f"Status:    ✓ Connected")
+
+    # Auth mode
+    try:
+        total_agents = conn.execute("SELECT COUNT(*) AS cnt FROM agents").fetchone()["cnt"]
+        active_agents = store.count_active_agents(conn)
+        if total_agents == 0:
+            print(f"Auth:      Open mode (no agents registered)")
+        else:
+            print(f"Auth:      Locked — {active_agents} active agent{'s' if active_agents != 1 else ''}, {total_agents - active_agents} revoked")
+    except Exception:
+        print(f"Auth:      Unknown (agents table not found — run CREATE TABLE manually)")
+
+    # Job summary
+    try:
+        total_jobs = conn.execute("SELECT COUNT(*) AS cnt FROM jobs").fetchone()["cnt"]
+        active_jobs = conn.execute(
+            "SELECT COUNT(*) AS cnt FROM jobs WHERE status NOT IN ('completed', 'cancelled')"
+        ).fetchone()["cnt"]
+        in_progress_tasks = conn.execute(
+            "SELECT COUNT(*) AS cnt FROM tasks WHERE status = 'in_progress'"
+        ).fetchone()["cnt"]
+        print(f"Jobs:      {active_jobs} active, {total_jobs} total")
+        if in_progress_tasks:
+            print(f"Tasks:     {in_progress_tasks} currently in progress")
+    except Exception:
+        print(f"Jobs:      Unknown (schema not initialised)")
+
+    print(f"Theme:     {theme}  ({theme_source})")
+
+
+def _register_agent(name: str) -> None:
+    from naxe.schema import get_connection
+    from naxe import store, auth
+    from naxe.auth import validate_key_format
+
+    conn = get_connection(resolve_db_url())
+
+    # If agents are already registered, caller must present a valid key
+    # (only an existing agent can register new ones on a locked DB)
+    n = store.count_active_agents(conn)
+    if n > 0:
+        raw_key = os.environ.get("NAXE_API_KEY", "")
+        if not raw_key:
+            print(
+                "naxe-config: NAXE_API_KEY is required to register a new agent when agents are already registered.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        if not validate_key_format(raw_key):
+            print("naxe-config: NAXE_API_KEY has invalid format.", file=sys.stderr)
+            sys.exit(1)
+        if store.get_agent_by_key_hash(conn, auth.hash_key(raw_key)) is None:
+            print("naxe-config: Invalid or revoked API key.", file=sys.stderr)
+            sys.exit(1)
+
+    raw_key = auth.generate_key()
+    try:
+        store.register_agent(conn, name, auth.hash_key(raw_key))
+        conn.commit()
+    except ValueError as e:
+        print(f"naxe-config: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Agent '{name}' registered.")
+    print(f"Key: {raw_key}")
+    print("Store this securely — it will not be shown again.")
+
+
+def _revoke_agent(name: str) -> None:
+    from naxe.schema import get_connection
+    from naxe import store
+
+    conn = get_connection(resolve_db_url())
+    revoked = store.revoke_agent(conn, name)
+    if revoked:
+        conn.commit()
+        print(f"Agent '{name}' revoked.")
+    else:
+        print(f"naxe-config: Agent '{name}' not found or already revoked.", file=sys.stderr)
+        sys.exit(1)
+
+
+def _list_agents() -> None:
+    from naxe.schema import get_connection
+    from naxe import store
+
+    conn = get_connection(resolve_db_url())
+    agents = store.list_agents(conn)
+
+    if not agents:
+        print("No agents registered. (Open mode — any caller is accepted.)")
+        return
+
+    print(f"{'Name':<24}  {'Created':<20}  Status")
+    print("-" * 56)
+    for a in agents:
+        status = "active" if a["active"] else "revoked"
+        created = str(a["created_at"])[:19]
+        print(f"{a['name']:<24}  {created:<20}  {status}")

naxe/config.py

@@ -0,0 +1,61 @@
+import os
+from pathlib import Path
+
+_CONFIG_FILE = Path.home() / ".config" / "naxe" / "config"
+_THEME_FILE = Path.home() / ".config" / "naxe" / "theme"
+
+DEFAULT_THEME = "naxe"
+
+
+def resolve_db_url() -> str:
+    if url := os.environ.get("NAXE_DB_URL"):
+        return url
+    if _CONFIG_FILE.exists():
+        url = _CONFIG_FILE.read_text().strip()
+        if url:
+            return url
+    if path := os.environ.get("NAXE_DB_PATH"):
+        return path
+    return "./naxe.db"
+
+
+def resolve_db_url_with_source() -> tuple[str, str]:
+    if url := os.environ.get("NAXE_DB_URL"):
+        return url, "env:NAXE_DB_URL"
+    if _CONFIG_FILE.exists():
+        url = _CONFIG_FILE.read_text().strip()
+        if url:
+            return url, f"config:{_CONFIG_FILE}"
+    if path := os.environ.get("NAXE_DB_PATH"):
+        return path, "env:NAXE_DB_PATH"
+    return "./naxe.db", "default"
+
+
+def write_config_url(url: str) -> None:
+    _CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True)
+    _CONFIG_FILE.write_text(url + "\n")
+
+
+def resolve_theme() -> str:
+    if theme := os.environ.get("NAXE_THEME"):
+        return theme.strip()
+    if _THEME_FILE.exists():
+        theme = _THEME_FILE.read_text().strip()
+        if theme:
+            return theme
+    return DEFAULT_THEME
+
+
+def resolve_theme_with_source() -> tuple[str, str]:
+    if theme := os.environ.get("NAXE_THEME"):
+        return theme.strip(), "env:NAXE_THEME"
+    if _THEME_FILE.exists():
+        theme = _THEME_FILE.read_text().strip()
+        if theme:
+            return theme, f"config:{_THEME_FILE}"
+    return DEFAULT_THEME, "default"
+
+
+def write_theme(theme: str) -> None:
+    _THEME_FILE.parent.mkdir(parents=True, exist_ok=True)
+    _THEME_FILE.write_text(theme + "\n")

naxe/handlers/__init__.py

@@ -0,0 +1,81 @@
+from naxe.handlers.jobs import (
+    handle_create_job,
+    handle_list_jobs,
+    handle_edit_job,
+    handle_get_job_status,
+    handle_cancel_job,
+    handle_pause_job,
+    handle_resume_job,
+)
+from naxe.handlers.tasks import (
+    handle_add_tasks,
+    handle_get_next_actions,
+    handle_claim_task,
+    handle_claim_next_action,
+    handle_complete_task,
+    handle_fail_task,
+    handle_heartbeat_task,
+    handle_update_task_progress,
+    handle_cancel_task,
+    handle_edit_task,
+    handle_requeue_task,
+)
+from naxe.handlers.dependencies import (
+    handle_add_job_dependency,
+    handle_set_job_concurrency,
+    handle_set_worktree_paths,
+)
+from naxe.handlers.approval import (
+    handle_request_approval,
+    handle_approve_task,
+    handle_reject_task,
+    handle_return_task,
+)
+from naxe.handlers.audit import (
+    handle_add_task_comment,
+    handle_get_task_comments,
+    handle_get_task_events,
+    handle_get_job_audit_trail,
+    handle_get_blocked_tasks,
+)
+from naxe.handlers.templates import (
+    handle_create_job_template,
+    handle_list_templates,
+    handle_instantiate_template,
+)
+
+DISPATCH = {
+    "create_job":          handle_create_job,
+    "list_jobs":           handle_list_jobs,
+    "edit_job":            handle_edit_job,
+    "get_job_status":      handle_get_job_status,
+    "cancel_job":          handle_cancel_job,
+    "pause_job":           handle_pause_job,
+    "resume_job":          handle_resume_job,
+    "add_tasks":           handle_add_tasks,
+    "get_next_actions":    handle_get_next_actions,
+    "claim_task":          handle_claim_task,
+    "claim_next_action":   handle_claim_next_action,
+    "complete_task":       handle_complete_task,
+    "fail_task":           handle_fail_task,
+    "heartbeat_task":      handle_heartbeat_task,
+    "update_task_progress": handle_update_task_progress,
+    "cancel_task":         handle_cancel_task,
+    "edit_task":           handle_edit_task,
+    "requeue_task":        handle_requeue_task,
+    "add_job_dependency":  handle_add_job_dependency,
+    "set_job_concurrency": handle_set_job_concurrency,
+    "set_worktree_paths":  handle_set_worktree_paths,
+    "request_approval":    handle_request_approval,
+    "approve_task":        handle_approve_task,
+    "reject_task":         handle_reject_task,
+    "return_task":         handle_return_task,
+    "add_task_comment":    handle_add_task_comment,
+    "get_task_comments":   handle_get_task_comments,
+    "get_task_events":     handle_get_task_events,
+    "get_job_audit_trail": handle_get_job_audit_trail,
+    "get_blocked_tasks":   handle_get_blocked_tasks,
+    "create_job_template": handle_create_job_template,
+    "list_templates":      handle_list_templates,
+    "instantiate_template": handle_instantiate_template,
+}

naxe/handlers/_common.py

@@ -0,0 +1,11 @@
+import json
+
+from mcp.types import TextContent
+
+
+def _ok(**kwargs) -> list[TextContent]:
+    return [TextContent(type="text", text=json.dumps(kwargs, default=str))]
+
+
+def _err(msg: str) -> list[TextContent]:
+    return [TextContent(type="text", text=json.dumps({"error": msg}))]

naxe/handlers/approval.py

@@ -0,0 +1,47 @@
+from typing import Any
+
+from naxe.handlers._common import _ok, _err
+from naxe import store
+
+
+def handle_request_approval(conn, arguments: dict) -> list:
+    task_id = arguments["task_id"]
+    agent_id = arguments["agent_id"]
+    task = store.request_approval(conn, task_id, agent_id, arguments.get("notes"))
+    if task is None:
+        return _err("Task not found or not eligible for approval request (must be in_progress and owned by this agent)")
+    return _ok(success=True, task=task)
+
+
+def handle_approve_task(conn, arguments: dict) -> list:
+    task_id = arguments["task_id"]
+    approver_id = arguments["approver_id"]
+    result = store.approve_task(conn, task_id, approver_id, arguments.get("notes"))
+    if result is None:
+        return _err("Task not found or not awaiting approval")
+    task = result["task"]
+    newly_unblocked = result["newly_unblocked"]
+    ret: dict[str, Any] = {"success": True, "task": task, "newly_unblocked": newly_unblocked}
+    if task and "_newly_unblocked_jobs" in task:
+        ret["newly_unblocked_jobs"] = task.pop("_newly_unblocked_jobs")
+    return _ok(**ret)
+
+
+def handle_reject_task(conn, arguments: dict) -> list:
+    task_id = arguments["task_id"]
+    approver_id = arguments["approver_id"]
+    reason = arguments["reason"]
+    task = store.reject_task(conn, task_id, approver_id, reason)
+    if task is None:
+        return _err("Task not found or not awaiting approval")
+    return _ok(success=True, task=task)
+
+
+def handle_return_task(conn, arguments: dict) -> list:
+    task_id = arguments["task_id"]
+    approver_id = arguments["approver_id"]
+    feedback = arguments["feedback"]
+    task = store.return_task(conn, task_id, approver_id, feedback)
+    if task is None:
+        return _err("Task not found or not awaiting approval")
+    return _ok(success=True, task=task)

naxe/handlers/audit.py

@@ -0,0 +1,48 @@
+from naxe.handlers._common import _ok, _err
+from naxe import store, resolver
+
+
+def handle_add_task_comment(conn, arguments: dict) -> list:
+    task_id = arguments["task_id"]
+    author_type = arguments["author_type"]
+    if author_type not in ("agent", "human"):
+        return _err("author_type must be 'agent' or 'human'")
+    comment = store.add_task_comment(
+        conn, task_id, arguments["author_id"], author_type, arguments["content"]
+    )
+    if comment is None:
+        return _err(f"Task '{task_id}' not found")
+    return _ok(success=True, comment=comment)
+
+
+def handle_get_task_comments(conn, arguments: dict) -> list:
+    task_id = arguments["task_id"]
+    task = store.get_task(conn, task_id)
+    if not task:
+        return _err(f"Task '{task_id}' not found")
+    comments = store.get_task_comments(conn, task_id, arguments.get("approval_round"))
+    return _ok(task_id=task_id, comments=comments)
+
+
+def handle_get_task_events(conn, arguments: dict) -> list:
+    task_id = arguments["task_id"]
+    if not store.get_task(conn, task_id):
+        return _err(f"Task '{task_id}' not found")
+    events = store.get_task_events(conn, task_id)
+    return _ok(task_id=task_id, events=events)
+
+
+def handle_get_job_audit_trail(conn, arguments: dict) -> list:
+    job = store.get_job(conn, arguments["job_id"])
+    if not job:
+        return _err(f"Job '{arguments['job_id']}' not found")
+    events = store.get_job_events(conn, job["id"])
+    return _ok(job_id=job["id"], events=events)
+
+
+def handle_get_blocked_tasks(conn, arguments: dict) -> list:
+    job = store.get_job(conn, arguments["job_id"])
+    if not job:
+        return _err(f"Job '{arguments['job_id']}' not found")
+    blocked = resolver.get_blocking_reasons(conn, job["id"])
+    return _ok(job_id=job["id"], blocked_tasks=blocked)

naxe/handlers/dependencies.py

@@ -0,0 +1,24 @@
+from naxe.handlers._common import _ok, _err
+from naxe import store
+
+
+def handle_add_job_dependency(conn, arguments: dict) -> list:
+    try:
+        store.add_job_dependency(conn, arguments["job_id"], arguments["depends_on_job_id"])
+    except ValueError as e:
+        return _err(str(e))
+    return _ok(success=True, job_id=arguments["job_id"], depends_on_job_id=arguments["depends_on_job_id"])
+
+
+def handle_set_job_concurrency(conn, arguments: dict) -> list:
+    updated = store.set_job_concurrency(conn, arguments["job_id"], arguments.get("max_workers"))
+    if updated is None:
+        return _err(f"Job '{arguments['job_id']}' not found")
+    return _ok(success=True, job=updated)
+
+
+def handle_set_worktree_paths(conn, arguments: dict) -> list:
+    updated = store.set_worktree_paths(conn, arguments["job_id"], arguments.get("paths", {}))
+    if updated is None:
+        return _err(f"Job '{arguments['job_id']}' not found")
+    return _ok(success=True, job=updated)

naxe/handlers/jobs.py

@@ -0,0 +1,114 @@
+from datetime import datetime, timezone
+from typing import Any
+
+from naxe.handlers._common import _ok, _err
+from naxe import store, resolver
+from naxe.schema import TaskStatus
+
+
+def handle_create_job(conn, arguments: dict) -> list:
+    job = store.create_job(
+        conn, arguments["name"],
+        arguments.get("max_workers"),
+        worktree=arguments.get("worktree", False),
+    )
+    return _ok(job_id=job["id"], job=job)
+
+
+def handle_list_jobs(conn, arguments: dict) -> list:
+    limit = arguments.get("limit", 50)
+    offset = arguments.get("offset", 0)
+    id_prefix = arguments.get("id_prefix")
+    page = store.list_jobs(conn, limit=limit, offset=offset, id_prefix=id_prefix)
+    result = []
+    for job in page["jobs"]:
+        tasks = store.get_tasks_for_job(conn, job["id"])
+        result.append({
+            **job,
+            "progress": {
+                "total": len(tasks),
+                "completed": sum(1 for t in tasks if t["status"] == TaskStatus.COMPLETED),
+                "in_progress": sum(1 for t in tasks if t["status"] == TaskStatus.IN_PROGRESS),
+                "pending": sum(1 for t in tasks if t["status"] == TaskStatus.PENDING),
+                "failed": sum(1 for t in tasks if t["status"] == TaskStatus.FAILED),
+            },
+        })
+    return _ok(jobs=result, total=page["total"], has_more=page["has_more"])
+
+
+def handle_edit_job(conn, arguments: dict) -> list:
+    updated = store.edit_job(conn, arguments["job_id"], arguments["name"])
+    if updated is None:
+        return _err(f"Job '{arguments['job_id']}' not found")
+    return _ok(success=True, job=updated)
+
+
+def handle_get_job_status(conn, arguments: dict) -> list:
+    job = store.get_job(conn, arguments["job_id"])
+    if not job:
+        return _err(f"Job '{arguments['job_id']}' not found")
+    job_id = job["id"]
+    tasks = store.get_tasks_for_job(conn, job_id)
+    blocked_tasks = resolver.get_blocking_reasons(conn, job_id)
+    blocked_map = {b["id"]: b["blocked_by"] for b in blocked_tasks}
+    for t in tasks:
+        if t["status"] == TaskStatus.PENDING and t["id"] in blocked_map:
+            t["blocked_by"] = blocked_map[t["id"]]
+        else:
+            t["blocked_by"] = []
+    now_iso = datetime.now(timezone.utc).isoformat()
+    for t in tasks:
+        status = t["status"]
+        if status == TaskStatus.PENDING and t["id"] in blocked_map:
+            t["display_status"] = "waiting_on"
+        elif status == TaskStatus.PENDING and t.get("start_date") and t["start_date"] > now_iso:
+            t["display_status"] = "scheduled"
+        elif status == TaskStatus.PENDING:
+            t["display_status"] = "next_action"
+        else:
+            t["display_status"] = status
+    progress = {
+        "total": len(tasks),
+        "completed": sum(1 for t in tasks if t["status"] == TaskStatus.COMPLETED),
+        "in_progress": sum(1 for t in tasks if t["status"] == TaskStatus.IN_PROGRESS),
+        "pending": sum(1 for t in tasks if t["status"] == TaskStatus.PENDING),
+        "failed": sum(1 for t in tasks if t["status"] == TaskStatus.FAILED),
+    }
+    dep_rows = conn.execute(
+        """SELECT jd.depends_on_job_id, j.name, j.status
+           FROM job_dependencies jd
+           JOIN jobs j ON j.id = jd.depends_on_job_id
+           WHERE jd.job_id = %s""",
+        (job_id,),
+    ).fetchall()
+    blocking_jobs = [
+        {"id": r["depends_on_job_id"], "name": r["name"], "status": r["status"]}
+        for r in dep_rows
+        if r["status"] != TaskStatus.COMPLETED
+    ]
+    active_workers = store.count_active_workers(conn, job_id)
+    return _ok(job=job, tasks=tasks, progress=progress, blocking_jobs=blocking_jobs, active_workers=active_workers)
+
+
+def handle_cancel_job(conn, arguments: dict) -> list:
+    job_id = arguments["job_id"]
+    if not store.get_job(conn, job_id):
+        return _err(f"Job '{job_id}' not found")
+    result = store.cancel_job(conn, job_id)
+    return _ok(success=True, **result)
+
+
+def handle_pause_job(conn, arguments: dict) -> list:
+    job_id = arguments["job_id"]
+    job = store.pause_job(conn, job_id, reason=arguments.get("reason"))
+    if job is None:
+        return _err(f"Job '{job_id}' not found")
+    return _ok(success=True, job=job)
+
+
+def handle_resume_job(conn, arguments: dict) -> list:
+    job_id = arguments["job_id"]
+    job = store.resume_job(conn, job_id)
+    if job is None:
+        return _err(f"Job '{job_id}' not found")
+    return _ok(success=True, job=job)