knit-sdk 0.1.0__py3-none-any.whl

knit/__init__.py

@@ -0,0 +1,6 @@
+"""Knit Agent SDK — Build agents that connect to the Knit hub."""
+
+from knit.agent import KnitAgent
+from knit.daemon import KnitDaemon, detect_clis
+
+__all__ = ["KnitAgent", "KnitDaemon", "detect_clis"]

knit/__main__.py

@@ -0,0 +1,10 @@
+"""``python -m knit`` — Run a Knit agent from config."""
+
+
+def main() -> None:
+    print("Knit Agent SDK — use the SDK programmatically or run an example:")
+    print("  python -m knit.examples.simple_agent")
+
+
+if __name__ == "__main__":
+    main()

knit/agent.py

@@ -0,0 +1,602 @@
+"""KnitAgent — SDK for building agents on the Knit agent hub.
+
+Provides two modes:
+
+1. **Conversational** (Claude Code, Codex, Cursor) — use individual API methods
+   as needed during a conversation.  Call ``heartbeat()`` and ``list_tasks()``
+   when the user asks.
+
+2. **Continuous** (OpenClaw, daemons, long-running processes) — call
+   ``agent.serve(handle_task=my_handler)`` to run forever, automatically
+   heartbeating, polling for open tasks, and managing their full lifecycle.
+
+Example (continuous)::
+
+    agent = KnitAgent(
+        name="code-reviewer",
+        hub_url="http://localhost:8000/api/v1",
+        api_key="sk_live_abc123",
+        description="Reviews PRs for security issues",
+        capabilities=[{"type": "code_review", "config": {}}],
+    )
+    agent.register()
+
+    def review_code(task: dict) -> dict:
+        # Do the actual work here
+        return {"summary": "Found 3 issues", "status": "completed"}
+
+    agent.serve(handle_task=review_code)  # blocks forever
+"""
+
+from __future__ import annotations
+
+import logging
+import signal
+import threading
+import time
+from concurrent.futures import Future, ThreadPoolExecutor
+from contextlib import contextmanager
+from typing import Any, Callable
+
+import httpx
+
+logger = logging.getLogger("knit-sdk")
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+
+class KnitError(Exception):
+    """Base exception for Knit SDK errors."""
+
+
+class KnitAPIError(KnitError):
+    """Raised when the Knit API returns a non-2xx response."""
+
+    def __init__(self, status_code: int, message: str):
+        self.status_code = status_code
+        self.message = message
+        super().__init__(f"[{status_code}] {message}")
+
+
+# ---------------------------------------------------------------------------
+# TaskContext — wraps accept → progress → result lifecycle
+# ---------------------------------------------------------------------------
+
+
+class TaskContext:
+    """Context manager for a single task's lifecycle.
+
+    Handles accept, in_progress transition, and result submission
+    automatically.  The user's ``with`` block does the actual work::
+
+        with agent.task_context(task) as ctx:
+            ctx.progress("Reviewing files...", 25)
+            result = do_work(task)
+            ctx.progress("Done", 100)
+            ctx.set_result(summary="All good", status="completed")
+    """
+
+    def __init__(self, agent: KnitAgent, task: dict) -> None:
+        self._agent = agent
+        self._task = task
+        self._task_id: str = task["id"]
+        self._result: dict[str, Any] | None = None
+        self._accepted = False
+
+    @property
+    def task(self) -> dict:
+        return self._task
+
+    @property
+    def task_id(self) -> str:
+        return self._task_id
+
+    def progress(self, message: str, progress_pct: int = 0) -> dict:
+        """Send a progress update.  First call transitions to in_progress."""
+        try:
+            return self._agent.send_progress(
+                self._task_id, message, progress_pct
+            )
+        except KnitError:
+            logger.warning("Progress update failed for %s", self._task_id)
+            return {}
+
+    def set_result(
+        self,
+        summary: str,
+        status: str = "completed",
+        logs: str = "",
+        metrics: dict[str, Any] | None = None,
+    ) -> None:
+        """Record the result to submit on exit."""
+        self._result = {
+            "summary": summary,
+            "status": status,
+            "logs": logs,
+            "metrics": metrics or {},
+        }
+
+    def __enter__(self) -> TaskContext:
+        try:
+            self._agent.accept_task(self._task_id)
+            self._accepted = True
+        except KnitAPIError as exc:
+            logger.warning("Accept failed for %s: %s", self._task_id, exc)
+            raise
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
+        if exc_type is not None:
+            # Exception in the with block — submit as failed
+            try:
+                self._agent.submit_result(
+                    task_id=self._task_id,
+                    summary=f"Task failed: {exc_val}",
+                    status="failed",
+                    logs=str(exc_val),
+                )
+            except KnitError:
+                logger.exception(
+                    "Failed to submit failure result for %s", self._task_id
+                )
+            return False  # re-raise
+
+        if self._result is not None:
+            try:
+                self._agent.submit_result(
+                    task_id=self._task_id,
+                    summary=self._result["summary"],
+                    status=self._result.get("status", "completed"),
+                    logs=self._result.get("logs", ""),
+                    metrics=self._result.get("metrics", {}),
+                )
+            except KnitError:
+                logger.exception(
+                    "Failed to submit result for %s", self._task_id
+                )
+        elif self._accepted:
+            # Accepted but no result set — submit a default completion
+            try:
+                self._agent.submit_result(
+                    task_id=self._task_id,
+                    summary="Task completed.",
+                    status="completed",
+                )
+            except KnitError:
+                logger.exception(
+                    "Failed to submit default result for %s", self._task_id
+                )
+        return False
+
+
+# ---------------------------------------------------------------------------
+# KnitAgent
+# ---------------------------------------------------------------------------
+
+
+class KnitAgent:
+    """A Knit agent that connects to a hub, polls for tasks, and reports results.
+
+    Supports both conversational (individual API calls) and continuous
+    (``serve()``) modes.
+
+    Example::
+
+        agent = KnitAgent(
+            name="my-bot",
+            hub_url="http://localhost:8000/api/v1",
+            api_key="sk_live_abc123",
+            description="A sample agent",
+            capabilities=[{"type": "code_review", "config": {}}],
+        )
+        resp = agent.register()
+        print(resp["agent_id"])
+    """
+
+    def __init__(
+        self,
+        name: str,
+        hub_url: str,
+        api_key: str,
+        description: str = "",
+        capabilities: list[dict] | None = None,
+    ):
+        self.name = name
+        self.base_url = hub_url.rstrip("/")
+        self.api_key = api_key
+        self.description = description
+        self.capabilities = capabilities or []
+
+        self.agent_id: str | None = None
+
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            },
+        )
+
+        # Heartbeat loop state
+        self._heartbeat_thread: threading.Thread | None = None
+        self._heartbeat_stop: threading.Event | None = None
+
+        # Serve state
+        self._serve_stop: threading.Event | None = None
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _request(self, method: str, path: str, **kwargs) -> dict:
+        try:
+            resp = self._client.request(method, path, **kwargs)
+        except httpx.RequestError as exc:
+            raise KnitError(f"Request failed: {exc}") from exc
+
+        if not resp.is_success:
+            detail = resp.json().get("detail") if resp.text else None
+            if isinstance(detail, dict):
+                msg = detail.get("message", resp.text)
+            elif isinstance(detail, str):
+                msg = detail
+            else:
+                msg = resp.text or resp.reason_phrase
+            raise KnitAPIError(resp.status_code, msg)
+
+        body = resp.json()
+        if "data" in body:
+            return body["data"]
+        return body
+
+    def _get(self, path: str, **kwargs) -> dict | list:
+        return self._request("GET", path, **kwargs)
+
+    def _post(self, path: str, **kwargs) -> dict:
+        return self._request("POST", path, **kwargs)
+
+    def _patch(self, path: str, **kwargs) -> dict:
+        return self._request("PATCH", path, **kwargs)
+
+    # ------------------------------------------------------------------
+    # Public API methods
+    # ------------------------------------------------------------------
+
+    def register(self) -> dict:
+        """Register this agent with the hub (first-time only).
+
+        Sends ``POST /agents/register``.  Saves ``agent_id`` on the instance.
+        """
+        body: dict[str, Any] = {
+            "name": self.name,
+            "description": self.description,
+        }
+        if self.capabilities:
+            body["capabilities"] = self.capabilities
+
+        data = self._post("/agents/register", json=body)
+        self.agent_id = str(data["agent_id"])
+        logger.info("Agent %s registered: %s", self.name, self.agent_id)
+        return data
+
+    def heartbeat(
+        self, status: str = "online", message: str | None = None
+    ) -> dict:
+        """Send a heartbeat ping. ``POST /agents/heartbeat``"""
+        body: dict[str, Any] = {"status": status}
+        if message is not None:
+            body["message"] = message
+        return self._post("/agents/heartbeat", json=body)
+
+    def list_tasks(self, status: str | None = None) -> list[dict]:
+        """List tasks. ``GET /tasks`` (agent-scoped)."""
+        params: dict[str, Any] = {}
+        if status:
+            params["status"] = status
+        return self._get("/tasks", params=params)  # type: ignore[return-value]
+
+    def get_task(self, task_id: str) -> dict:
+        """Get full task details. ``GET /tasks/{task_id}``"""
+        return self._get(f"/tasks/{task_id}")  # type: ignore[return-value]
+
+    def accept_task(self, task_id: str) -> dict:
+        """Accept a task. ``POST /tasks/{task_id}/accept``"""
+        return self._post(f"/tasks/{task_id}/accept")
+
+    def decline_task(self, task_id: str, reason: str = "") -> dict:
+        """Decline a task. ``POST /tasks/{task_id}/decline``"""
+        body: dict[str, Any] = {}
+        if reason:
+            body["reason"] = reason
+        return self._post(f"/tasks/{task_id}/decline", json=body)
+
+    def update_status(
+        self, task_id: str, status: str, reason: str = ""
+    ) -> dict:
+        """Update task status. ``PATCH /tasks/{task_id}/status``"""
+        body: dict[str, Any] = {"status": status}
+        if reason:
+            body["reason"] = reason
+        return self._patch(f"/tasks/{task_id}/status", json=body)
+
+    def send_progress(
+        self, task_id: str, message: str, progress_pct: int = 0
+    ) -> dict:
+        """Send a progress update. ``POST /tasks/{task_id}/progress``"""
+        body: dict[str, Any] = {
+            "message": message,
+            "progress_pct": progress_pct,
+        }
+        return self._post(f"/tasks/{task_id}/progress", json=body)
+
+    def submit_result(
+        self,
+        task_id: str,
+        summary: str,
+        status: str = "completed",
+        artifacts: list[dict] | None = None,
+        logs: str = "",
+        metrics: dict | None = None,
+    ) -> dict:
+        """Submit final result. ``POST /tasks/{task_id}/result``"""
+        body: dict[str, Any] = {
+            "status": status,
+            "summary": summary,
+            "logs": logs,
+            "metrics": metrics or {},
+            "artifacts": artifacts or [],
+        }
+        return self._post(f"/tasks/{task_id}/result", json=body)
+
+    # ------------------------------------------------------------------
+    # Task lifecycle helpers
+    # ------------------------------------------------------------------
+
+    def task_context(self, task: dict) -> TaskContext:
+        """Return a context manager that handles the full task lifecycle.
+
+        Usage::
+
+            with agent.task_context(task) as ctx:
+                ctx.progress("Starting...", 5)
+                result = do_work(task)
+                ctx.progress("Done", 100)
+                ctx.set_result(summary="All done", status="completed")
+
+        The context manager automatically:
+        - Accepts the task on entry
+        - Submits the result on normal exit (using the value from ``set_result``)
+        - Submits a failure result if the block raises an exception
+        """
+        return TaskContext(self, task)
+
+    def handle_task(
+        self,
+        task: dict,
+        handler: Callable[[dict, TaskContext], dict | None],
+    ) -> bool:
+        """Handle a single task through its full lifecycle.
+
+        Accepts the task, calls ``handler(task, ctx)``, and submits the result.
+        Progress updates from inside the handler are sent via ``ctx.progress()``.
+
+        The handler can return a result dict directly, or call
+        ``ctx.set_result()`` inside the handler.
+
+        Returns True if the task was handled successfully, False on error.
+        """
+        task_id = task.get("id", "unknown")
+        title = task.get("title", task_id)
+        logger.info("Handling task: %s (%s)", title, task_id)
+
+        try:
+            with self.task_context(task) as ctx:
+                result = handler(task, ctx)
+                if result is not None:
+                    ctx.set_result(
+                        summary=result.get("summary", "Done."),
+                        status=result.get("status", "completed"),
+                        logs=result.get("logs", ""),
+                        metrics=result.get("metrics"),
+                    )
+            return True
+        except KnitAPIError as exc:
+            logger.error(
+                "API error handling task %s: %s", task_id, exc
+            )
+            return False
+        except Exception:
+            logger.exception(
+                "Unexpected error handling task %s", task_id
+            )
+            return False
+
+    # ------------------------------------------------------------------
+    # Heartbeat loop
+    # ------------------------------------------------------------------
+
+    def start_heartbeat_loop(
+        self, interval: int = 30, message: str | None = None
+    ) -> None:
+        """Start a background daemon thread that sends heartbeats every
+        *interval* seconds.
+        """
+        if self._heartbeat_thread is not None:
+            return
+
+        self._heartbeat_stop = threading.Event()
+
+        def _loop() -> None:
+            while not self._heartbeat_stop.wait(interval):  # type: ignore[union-attr]
+                try:
+                    self.heartbeat(status="online", message=message)
+                    logger.debug("Heartbeat sent")
+                except KnitError:
+                    logger.warning("Heartbeat failed", exc_info=True)
+
+        self._heartbeat_thread = threading.Thread(target=_loop, daemon=True)
+        self._heartbeat_thread.start()
+        logger.info(
+            "Heartbeat loop started (every %ds)", interval
+        )
+
+    def stop_heartbeat_loop(self) -> None:
+        """Stop the heartbeat background thread."""
+        if self._heartbeat_stop is not None:
+            self._heartbeat_stop.set()
+        if self._heartbeat_thread is not None:
+            self._heartbeat_thread.join(timeout=5)
+            self._heartbeat_thread = None
+            self._heartbeat_stop = None
+            logger.info("Heartbeat loop stopped")
+
+    # ------------------------------------------------------------------
+    # Continuous agent loop — ``serve()``
+    # ------------------------------------------------------------------
+
+    def serve(
+        self,
+        handle_task: Callable[[dict, TaskContext], dict | None],
+        *,
+        poll_interval: int = 10,
+        heartbeat_interval: int = 30,
+        heartbeat_message: str | None = None,
+        task_status: str = "open",
+        max_parallel: int = 1,
+        run_once: bool = False,
+    ) -> None:
+        """Run the agent continuously — poll, heartbeat, handle tasks.
+
+        This is the **main entry point for long-running agents** (daemons,
+        OpenClaw, background processes).  It blocks until interrupted.
+
+        Args:
+            handle_task: Called as ``handle_task(task_dict, ctx)`` for each
+                open task.  Use ``ctx.progress()`` to report progress and
+                ``ctx.set_result()`` to set the final result.  May also
+                return a result dict directly.
+            poll_interval: Seconds between task polls (default 10).
+            heartbeat_interval: Seconds between heartbeats (default 30).
+            heartbeat_message: Optional static message for heartbeats.
+            task_status: Task status to poll for (default ``"open"``).
+            max_parallel: Max concurrent task handlers (default 1).  Set > 1
+                to handle multiple tasks at once using a thread pool.
+            run_once: If True, poll once and return.  Useful for cron jobs.
+
+        Example::
+
+            def my_handler(task, ctx):
+                ctx.progress("Starting work...", 5)
+                # ... do the actual work ...
+                ctx.progress("All done", 100)
+                return {"summary": "Reviewed 12 files", "status": "completed"}
+
+            agent.serve(my_handler)
+        """
+        logger.info(
+            "Starting serve loop: poll_every=%ds, heartbeat_every=%ds, "
+            "max_parallel=%d",
+            poll_interval, heartbeat_interval, max_parallel,
+        )
+
+        # Start background heartbeat
+        self.start_heartbeat_loop(
+            interval=heartbeat_interval, message=heartbeat_message
+        )
+
+        # Set up signal handling for clean shutdown
+        self._serve_stop = threading.Event()
+
+        def _on_signal(signum: int, frame: Any) -> None:
+            logger.info("Received signal %d, shutting down...", signum)
+            self._serve_stop.set()  # type: ignore[union-attr]
+
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            try:
+                signal.signal(sig, _on_signal)
+            except (ValueError, OSError):
+                pass  # Not in main thread (e.g. OpenClaw) — that's fine
+
+        executor = (
+            ThreadPoolExecutor(max_workers=max_parallel)
+            if max_parallel > 1
+            else None
+        )
+
+        try:
+            while not self._serve_stop.is_set():
+                try:
+                    tasks = self.list_tasks(status=task_status)
+                    if tasks:
+                        logger.info("Found %d open task(s)", len(tasks))
+                        for task in tasks:
+                            if self._serve_stop.is_set():
+                                break
+                            if executor is not None:
+                                executor.submit(
+                                    self.handle_task, task, handle_task
+                                )
+                            else:
+                                self.handle_task(task, handle_task)
+                except KnitError:
+                    logger.warning(
+                        "Poll cycle failed, retrying in %ds...",
+                        poll_interval,
+                        exc_info=True,
+                    )
+
+                if run_once:
+                    break
+
+                self._serve_stop.wait(poll_interval)
+        finally:
+            logger.info("Serve loop stopped")
+            self.stop_heartbeat_loop()
+            if executor is not None:
+                executor.shutdown(wait=True)
+
+    # ------------------------------------------------------------------
+    # Legacy poll-and-handle (kept for backward compatibility)
+    # ------------------------------------------------------------------
+
+    def poll_and_handle(
+        self,
+        callback: Callable[[dict], Any],
+        interval: int = 10,
+        task_status: str = "open",
+    ) -> None:
+        """Poll for tasks and call ``callback(task)`` for each.
+
+        **Deprecated:** Prefer ``serve(handle_task=...)`` for new code.
+        It handles the full lifecycle automatically.
+
+        This method blocks indefinitely.
+        """
+        while True:
+            try:
+                tasks = self.list_tasks(status=task_status)
+                for task in tasks:
+                    callback(task)
+            except KnitError:
+                logger.warning("Poll cycle failed", exc_info=True)
+            time.sleep(interval)
+
+    # ------------------------------------------------------------------
+    # Cleanup
+    # ------------------------------------------------------------------
+
+    def close(self) -> None:
+        """Stop heartbeats, signal serve loop, close HTTP client."""
+        if self._serve_stop is not None:
+            self._serve_stop.set()
+        self.stop_heartbeat_loop()
+        self._client.close()
+
+    def __enter__(self) -> KnitAgent:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()

knit/cli.py

@@ -0,0 +1,541 @@
+"""Knit CLI — manage tasks, agents, projects, and autopilots from the terminal.
+
+Usage::
+
+    # Set auth (agent API key for task operations)
+    export KNIT_API_KEY=sk_live_xxx
+    knit task list --status open
+
+    # Set auth (JWT token for admin operations)
+    export KNIT_JWT_TOKEN=<jwt_from_login>
+    knit project list
+    knit autopilot trigger <id>
+
+    # Or use --token on individual commands
+    knit agent approve <id> --token $(knit auth login)
+
+    # Run the daemon
+    knit daemon start
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import Any
+
+import httpx
+
+from knit.agent import KnitAgent
+
+DEFAULT_HUB = os.getenv("KNIT_HUB_URL", "http://localhost:8000/api/v1")
+
+
+# ---------------------------------------------------------------------------
+# Auth helpers
+# ---------------------------------------------------------------------------
+
+
+def _get_agent() -> KnitAgent:
+    """Create a KnitAgent from env vars."""
+    api_key = os.getenv("KNIT_API_KEY")
+    if not api_key:
+        print("Error: KNIT_API_KEY environment variable is required for agent operations.", file=sys.stderr)
+        sys.exit(1)
+    return KnitAgent(
+        name="knit-cli",
+        hub_url=os.getenv("KNIT_HUB_URL", DEFAULT_HUB),
+        api_key=api_key,
+    )
+
+
+def _get_admin_client(token: str | None = None) -> httpx.Client | None:
+    """Create an httpx client with JWT auth."""
+    token = token or os.getenv("KNIT_JWT_TOKEN")
+    if not token:
+        return None
+    hub = os.getenv("KNIT_HUB_URL", DEFAULT_HUB)
+    return httpx.Client(
+        base_url=hub.rstrip("/"),
+        headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
+    )
+
+
+def _admin_request(method: str, path: str, token: str | None = None,
+                    json_data: dict | None = None, params: dict | None = None) -> Any:
+    """Make an authenticated request with a JWT token (admin operations)."""
+    client = _get_admin_client(token)
+    if not client:
+        print("Error: --token or KNIT_JWT_TOKEN required (admin operation).\n"
+              "Run `knit auth login` to get a token, then set KNIT_JWT_TOKEN.", file=sys.stderr)
+        sys.exit(1)
+    try:
+        resp = client.request(method, path, json=json_data, params=params)
+        if not resp.is_success:
+            detail = {}
+            try:
+                detail = resp.json().get("detail", {}) or {}
+            except Exception:
+                pass
+            msg = detail.get("message", resp.text) if isinstance(detail, dict) else str(detail)
+            raise Exception(f"[{resp.status_code}] {msg}")
+        body = resp.json()
+        if "data" in body:
+            return body["data"]
+        return body
+    finally:
+        client.close()
+
+
+# ---------------------------------------------------------------------------
+# Output helpers
+# ---------------------------------------------------------------------------
+
+
+def _output(data: Any, raw: bool = False) -> None:
+    """Print output — JSON for scripts, pretty for humans."""
+    if raw:
+        print(json.dumps(data, indent=2, default=str))
+    elif isinstance(data, list):
+        for item in data:
+            _print_item(item)
+    elif isinstance(data, dict):
+        _print_item(data)
+    else:
+        print(data)
+
+
+def _print_item(item: dict) -> None:
+    """Print a single item in human-readable format."""
+    name = item.get("title") or item.get("name") or item.get("id", "?")
+    project = item.get("project_id", "")
+    project_str = f" [{project[:8]}]" if project else ""
+    status = item.get("status") or item.get("registration_status", "")
+    priority = item.get("priority", "")
+    tags = []
+    if priority:
+        tags.append(priority.upper())
+    if status:
+        tags.append(status)
+    tag_str = f" [{', '.join(tags)}]" if tags else ""
+    print(f"  {item.get('id', '?'):>12}  {name}{project_str}{tag_str}")
+
+
+# ---------------------------------------------------------------------------
+# Subcommands
+# ---------------------------------------------------------------------------
+
+
+def cmd_auth(args: argparse.Namespace) -> None:
+    """Handle ``knit auth <subcommand>``."""
+    if args.sub == "login":
+        hub = os.getenv("KNIT_HUB_URL", DEFAULT_HUB)
+        with httpx.Client(base_url=hub.rstrip("/")) as client:
+            resp = client.post("/auth/login", json={
+                "email": args.email,
+                "password": args.password,
+            })
+            if resp.is_success:
+                data = resp.json().get("data", {})
+                print(data.get("access_token", ""))
+            else:
+                detail = resp.json().get("detail", {})
+                msg = detail.get("message", resp.text) if isinstance(detail, dict) else str(detail)
+                print(f"Login failed: {msg}", file=sys.stderr)
+                sys.exit(1)
+
+
+def cmd_task(args: argparse.Namespace) -> None:
+    """Handle ``knit task <subcommand>``."""
+    agent = _get_agent()
+
+    if args.sub == "list":
+        tasks = agent.list_tasks(status=args.status)
+        print(f"Tasks ({len(tasks)}):")
+        if tasks:
+            _output(tasks, raw=args.raw)
+        return
+
+    if args.sub == "get":
+        task = agent.get_task(args.task_id)
+        _output(task, raw=args.raw)
+        return
+
+    if args.sub == "create":
+        body = {
+            "project_id": args.project_id,
+            "title": args.title,
+            "description": args.description or "",
+            "priority": args.priority or "p2",
+        }
+        if args.assign_to:
+            body["assigned_to_agent_id"] = args.assign_to
+        resp = agent._post("/tasks", json=body)
+        print(f"Created: {resp['id']} — {resp['title']}")
+        _output(resp, raw=args.raw)
+        return
+
+    if args.sub == "accept":
+        task = agent.accept_task(args.task_id)
+        print(f"Accepted: {task['id']} ({task['status']})")
+        return
+
+    if args.sub == "progress":
+        resp = agent.send_progress(args.task_id, args.message, args.pct)
+        print(f"Progress: {args.pct}% — {args.message}")
+        return
+
+    if args.sub == "result":
+        resp = agent.submit_result(
+            task_id=args.task_id,
+            summary=args.summary,
+            status=args.status or "completed",
+            logs=args.logs or "",
+            metrics={"cli": True},
+        )
+        print(f"Result submitted: {resp.get('status', 'done')}")
+        return
+
+
+def cmd_agent(args: argparse.Namespace) -> None:
+    """Handle ``knit agent <subcommand>``."""
+    # agent = _get_agent()  # moved inside subcommands
+
+    if args.sub == "me":
+        agent = _get_agent()
+        profile = agent._get("/agents/me")
+        _output(profile, raw=args.raw)
+        return
+
+    if args.sub == "register":
+        hub = os.getenv("KNIT_HUB_URL", DEFAULT_HUB)
+        body = {"name": args.name, "description": args.description or ""}
+        if args.capabilities:
+            body["capabilities"] = [{"type": c} for c in args.capabilities]
+        import httpx as _httpx
+        with _httpx.Client(base_url=hub.rstrip("/")) as _client:
+            _resp = _client.post("/agents/register", json=body)
+            if not _resp.is_success:
+                detail = _resp.json().get("detail", {}) or {}
+                msg = detail.get("message", _resp.text) if isinstance(detail, dict) else str(detail)
+                print(f"Registration failed: {msg}", file=sys.stderr)
+                sys.exit(1)
+            _body = _resp.json()
+            if "data" in _body:
+                _body = _body["data"]
+        print(f"Registered: {_body['agent_id']}")
+        print(f"API Key (save this — shown once): {_body['api_key']}")
+        return
+
+    if args.sub == "heartbeat":
+        agent = _get_agent()
+        resp = agent.heartbeat(status=args.status or "online", message=args.message)
+        d = resp if isinstance(resp, dict) else {}
+        print(f"Heartbeat: {d.get('status', 'ok')}")
+        if "pending_tasks" in d:
+            print(f"  Pending tasks: {d['pending_tasks']}")
+        if "active_tasks" in d:
+            print(f"  Active tasks: {d['active_tasks']}")
+        if "recent_events" in d and d["recent_events"]:
+            print(f"  Recent events: {len(d['recent_events'])}")
+        return
+
+    if args.sub == "approve":
+        token = args.token or os.getenv("KNIT_JWT_TOKEN")
+        if not token:
+            print("Error: --token or KNIT_JWT_TOKEN required (admin operation).\n"
+                  "Run: export KNIT_JWT_TOKEN=$(knit auth login)", file=sys.stderr)
+            sys.exit(1)
+        resp = _admin_request("POST", f"/agents/{args.agent_id}/approve", token)
+        print(f"Approved agent: {args.agent_id}")
+        return
+
+
+def cmd_project(args: argparse.Namespace) -> None:
+    """Handle ``knit project <subcommand>``."""
+
+    if args.sub == "list":
+        client = _get_admin_client(args.token)
+        if client:
+            try:
+                projects = _admin_request("GET", "/projects", args.token)
+            finally:
+                client.close()
+        else:
+            agent = _get_agent()
+            projects = agent._get("/projects")
+            if isinstance(projects, list):
+                pass  # OK, agent API key worked for this endpoint
+            else:
+                print("Warning: Some project data may not be visible with agent API key.\n"
+                      "Set KNIT_JWT_TOKEN for full access.", file=sys.stderr)
+        items = projects if isinstance(projects, list) else projects.get("data", [])
+        print(f"Projects ({len(items)}):")
+        _output(items, raw=args.raw)
+        return
+
+    if args.sub == "create":
+        body = {"name": args.name}
+        if args.description:
+            body["description"] = args.description
+        resp = _admin_request("POST", "/projects", args.token, json_data=body)
+        print(f'Created project: {resp.get("id", "?")} -- {args.name}')
+        return
+
+    if args.sub == "resources":
+        return
+
+    if args.sub == "resources":
+        pid = args.project_id
+        if args.sub_sub == "list":
+            resources = _admin_request("GET", f"/projects/{pid}/resources", args.token)
+            items = resources if isinstance(resources, list) else resources.get("data", [])
+            print(f"Resources ({len(items)}):")
+            for r in items:
+                print(f"  {r.get('id','?'):>12}  {r.get('resource_type','?'):12} {r.get('name','')}")
+            return
+        if args.sub_sub == "add":
+            body = {
+                "resource_type": args.resource_type,
+                "name": args.name,
+                "value": args.value,
+            }
+            if args.display_value:
+                body["display_value"] = args.display_value
+            resp = _admin_request("POST", f"/projects/{pid}/resources", args.token, json_data=body)
+            print(f"Added resource: {resp.get('id','?')[:8]}... — {args.name}")
+            return
+
+    if args.sub == "members":
+        pid = args.project_id
+        if args.sub_sub == "list":
+            members = _admin_request("GET", f"/projects/{pid}/members", args.token)
+            items = members if isinstance(members, list) else members.get("data", [])
+            print(f"Members ({len(items)}):")
+            for m in items:
+                name = m.get("name", m.get("user_id") or m.get("agent_id") or "?")
+                mtype = m.get("member_type", "?")
+                role = m.get("role", "?")
+                print(f"  {name:20} {mtype:6} [{role}]")
+            return
+        if args.sub_sub == "add":
+            body: dict[str, Any] = {"role": args.role}
+            if args.agent_id:
+                body["member_type"] = "agent"
+                body["agent_id"] = args.agent_id
+            elif args.user_id:
+                body["member_type"] = "human"
+                body["user_id"] = args.user_id
+            else:
+                print("Error: specify --agent-id or --user-id", file=sys.stderr)
+                sys.exit(1)
+            resp = _admin_request("POST", f"/projects/{pid}/members", args.token, json_data=body)
+            print(f"Added member to project {pid[:8]}...")
+            return
+
+
+def cmd_autopilot(args: argparse.Namespace) -> None:
+    """Handle ``knit autopilot <subcommand>``."""
+
+    if args.sub == "list":
+        params: dict[str, str] = {}
+        if args.project_id:
+            params["project_id"] = args.project_id
+        resp = _admin_request("GET", "/autopilots", args.token, params=params)
+        items = resp if isinstance(resp, list) else resp.get("data", [])
+        print(f"Autopilots ({len(items)}):")
+        for a in items:
+            status = "active" if a.get("is_active") else "paused"
+            print(f"  {a.get('id','?'):>12}  {a.get('name','')} [{status}]")
+        return
+
+    if args.sub == "create":
+        body = {"project_id": args.project_id, "name": args.name}
+        if args.cron:
+            body["cron_expression"] = args.cron
+        if args.assign_to:
+            body["assigned_to_agent_id"] = args.assign_to
+        if args.title_template:
+            body["title_template"] = args.title_template
+        if args.priority:
+            body["priority"] = args.priority
+        resp = _admin_request("POST", "/autopilots", args.token, json_data=body)
+        d = resp if isinstance(resp, dict) else {}
+        print(f'Created autopilot: {d.get("id", "?")} -- {args.name}')
+        return
+
+    if args.sub == "trigger":
+        resp = _admin_request("POST", f"/autopilots/{args.autopilot_id}/trigger", args.token)
+        d = resp if isinstance(resp, dict) else {}
+        print(f"Triggered: task {d.get('task_id','?')[:8]}... created")
+        return
+
+    if args.sub == "runs":
+        resp = _admin_request("GET", f"/autopilots/{args.autopilot_id}/runs", args.token)
+        items = resp if isinstance(resp, list) else resp.get("data", [])
+        print(f"Runs ({len(items)}):")
+        for r in items:
+            print(f"  status={r.get('status','?')} task={r.get('task_id','?')[:8]}... at={r.get('run_at','?')[:19]}")
+        return
+
+
+# ---------------------------------------------------------------------------
+# Root parser
+# ---------------------------------------------------------------------------
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="knit", description="Knit agent CLI")
+    parser.add_argument("--raw", action="store_true", help="JSON output")
+    parser.add_argument("--token", help="JWT token (for admin operations; also reads KNIT_JWT_TOKEN)")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # ── auth ──────────────────────────────────────────
+    au = sub.add_parser("auth", help="Authentication")
+    ausub = au.add_subparsers(dest="sub", required=True)
+    al = ausub.add_parser("login", help="Login and print JWT token")
+    al.add_argument("--email", default="admin@knit.dev")
+    al.add_argument("--password", default="password123")
+
+    # ── task ──────────────────────────────────────────
+    t = sub.add_parser("task", help="Manage tasks")
+    tsub = t.add_subparsers(dest="sub", required=True)
+
+    tp = tsub.add_parser("list", help="List tasks")
+    tp.add_argument("--status", help="Filter by status")
+    tp.add_argument("--project-id", help="Filter by project")
+
+    tsub.add_parser("get", help="Get task detail").add_argument("task_id")
+
+    tc = tsub.add_parser("create", help="Create a task")
+    tc.add_argument("--project-id", required=True)
+    tc.add_argument("--title", required=True)
+    tc.add_argument("--description")
+    tc.add_argument("--priority", choices=["p0", "p1", "p2", "p3"])
+    tc.add_argument("--assign-to", dest="assign_to", help="Agent ID")
+
+    tsub.add_parser("accept", help="Accept a task").add_argument("task_id")
+
+    tp2 = tsub.add_parser("progress", help="Report progress")
+    tp2.add_argument("task_id")
+    tp2.add_argument("--message", required=True)
+    tp2.add_argument("--pct", type=int, default=50)
+
+    tr = tsub.add_parser("result", help="Submit result")
+    tr.add_argument("task_id")
+    tr.add_argument("--summary", required=True)
+    tr.add_argument("--status", choices=["completed", "failed"])
+    tr.add_argument("--logs")
+
+    # ── agent ─────────────────────────────────────────
+    a = sub.add_parser("agent", help="Manage agent identity")
+    asub = a.add_subparsers(dest="sub", required=True)
+
+    asub.add_parser("me", help="Show profile")
+
+    ar = asub.add_parser("register", help="Register this agent")
+    ar.add_argument("--name", required=True)
+    ar.add_argument("--description")
+    ar.add_argument("--capabilities", nargs="*")
+
+    ah = asub.add_parser("heartbeat", help="Send heartbeat")
+    ah.add_argument("--status", choices=["online", "busy", "offline"])
+    ah.add_argument("--message")
+
+    aapp = asub.add_parser("approve", help="Approve a pending agent (admin)")
+    aapp.add_argument("agent_id")
+
+    # ── project ───────────────────────────────────────
+    p = sub.add_parser("project", help="Manage projects")
+    psub = p.add_subparsers(dest="sub", required=True)
+
+    psub.add_parser("list", help="List projects")
+
+    pc = psub.add_parser("create", help="Create a project")
+    pc.add_argument("--name", required=True)
+    pc.add_argument("--description")
+
+    pr = psub.add_parser("resources", help="Manage project resources")
+    pr.add_argument("project_id")
+    prsub = pr.add_subparsers(dest="sub_sub", required=True)
+    prsub.add_parser("list", help="List resources")
+    pra = prsub.add_parser("add", help="Add a resource")
+    pra.add_argument("--type", dest="resource_type", required=True,
+                     choices=["github_repo", "url", "document", "env_var"])
+    pra.add_argument("--name", required=True)
+    pra.add_argument("--value", required=True)
+    pra.add_argument("--display-value", dest="display_value")
+
+    pm = psub.add_parser("members", help="Manage project members")
+    pm.add_argument("project_id")
+    pmsub = pm.add_subparsers(dest="sub_sub", required=True)
+    pml = pmsub.add_parser("list", help="List members")
+    pma = pmsub.add_parser("add", help="Add a member")
+    pma.add_argument("--agent-id", help="Agent ID to add")
+    pma.add_argument("--user-id", help="User ID to add")
+    pma.add_argument("--role", default="member", choices=["admin", "member", "viewer"])
+
+    # ── autopilot ─────────────────────────────────────
+    ap = sub.add_parser("autopilot", help="Manage autopilots")
+    apsub = ap.add_subparsers(dest="sub", required=True)
+
+    apl = apsub.add_parser("list", help="List autopilots")
+    apl.add_argument("--project-id")
+
+    apc = apsub.add_parser("create", help="Create an autopilot")
+    apc.add_argument("--project-id", required=True)
+    apc.add_argument("--name", required=True)
+    apc.add_argument("--cron")
+    apc.add_argument("--assign-to", dest="assign_to")
+    apc.add_argument("--title-template", dest="title_template")
+    apc.add_argument("--priority", choices=["p0", "p1", "p2", "p3"])
+
+    apsub.add_parser("trigger", help="Trigger an autopilot").add_argument("autopilot_id")
+    apsub.add_parser("runs", help="Show run history").add_argument("autopilot_id")
+
+    # ── daemon ────────────────────────────────────────
+    d = sub.add_parser("daemon", help="Run the agent daemon")
+    dsub = d.add_subparsers(dest="sub", required=True)
+    ds = dsub.add_parser("start", help="Start the daemon")
+    ds.add_argument("--hub", default=os.getenv("KNIT_HUB_URL", DEFAULT_HUB))
+    ds.add_argument("--api-key", default=os.getenv("KNIT_API_KEY", ""))
+    ds.add_argument("--name", default="knit-daemon")
+    ds.add_argument("--poll-interval", type=int, default=10)
+
+    return parser
+
+
+def main() -> None:
+    """CLI entry point — dispatches to the right subcommand handler."""
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    if args.command == "daemon":
+        from knit.daemon import _daemon_main
+        _daemon_main(args)
+        return
+
+    handlers = {
+        "auth": cmd_auth,
+        "task": cmd_task,
+        "agent": cmd_agent,
+        "project": cmd_project,
+        "autopilot": cmd_autopilot,
+    }
+
+    handler = handlers.get(args.command)
+    if handler:
+        try:
+            handler(args)
+        except Exception as e:
+            print(f"Error: {e}", file=sys.stderr)
+            sys.exit(1)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

knit/daemon.py

@@ -0,0 +1,175 @@
+"""Agent daemon — autonomous Knit agent that auto-discovers and executes tasks.
+
+Usage::
+
+    knit daemon start --hub http://localhost:8000 --api-key sk_live_xxx
+
+The daemon heartbeats, polls for tasks, and executes them via the best
+available CLI agent on PATH (claude, codex, openclaw, etc.).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import subprocess
+import sys
+from typing import Any
+
+from knit.agent import KnitAgent, TaskContext
+
+logger = logging.getLogger("knit-daemon")
+
+# ---------------------------------------------------------------------------
+# CLI auto-detection
+# ---------------------------------------------------------------------------
+
+_CLI_CANDIDATES = ["claude", "codex", "copilot", "openclaw", "opencode", "hermes", "gemini", "pi"]
+
+
+def detect_clis() -> list[str]:
+    """Return CLI agents found on PATH."""
+    return [c for c in _CLI_CANDIDATES if shutil.which(c)]
+
+
+# ---------------------------------------------------------------------------
+# KnitDaemon
+# ---------------------------------------------------------------------------
+
+
+class KnitDaemon:
+    """A background agent that auto-discovers, executes, and reports on tasks.
+
+    Wraps ``KnitAgent`` from the SDK and adds automatic CLI detection,
+    subprocess execution, and SSE-based event listening.
+    """
+
+    def __init__(
+        self,
+        hub_url: str,
+        api_key: str,
+        name: str = "knit-daemon",
+        description: str = "Daemon agent that auto-executes assigned tasks",
+    ):
+        self.agent = KnitAgent(
+            name=name,
+            hub_url=hub_url.rstrip("/"),
+            api_key=api_key,
+            description=description,
+        )
+        self.available_clis: list[str] = []
+        self._name = name
+
+    def detect(self) -> list[str]:
+        """Auto-detect available agent CLIs on PATH."""
+        self.available_clis = detect_clis()
+        return self.available_clis
+
+    def execute(self, task: dict, ctx: TaskContext) -> dict[str, Any]:
+        """Execute a task by spawning the best available CLI agent.
+
+        The task context (title + description) is fed as a prompt.
+        Stdout/stderr are captured and returned as the task result.
+        """
+        if not self.available_clis:
+            self.detect()
+        if not self.available_clis:
+            logger.warning("No agent CLI found on PATH")
+            return {"summary": "No agent CLI available (tried: claude, codex, etc.)", "status": "failed"}
+
+        cli = self.available_clis[0]
+        prompt = self._build_prompt(task)
+        logger.info("Executing task %s via %s", task.get("id", "?"), cli)
+
+        ctx.progress(f"Starting execution via {cli}...", 5)
+
+        try:
+            result = subprocess.run(
+                [cli, "-p", prompt],
+                capture_output=True, text=True, timeout=600,
+            )
+        except subprocess.TimeoutExpired:
+            logger.warning("Task %s timed out after 600s", task.get("id", "?"))
+            return {"summary": "Task timed out after 600 seconds", "status": "failed", "logs": "Timeout"}
+        except FileNotFoundError:
+            logger.error("CLI %s not found despite detection", cli)
+            return {"summary": f"CLI {cli} not found", "status": "failed"}
+
+        ctx.progress("Execution complete, submitting result...", 95)
+
+        return {
+            "summary": result.stdout[:2000] or "(no stdout)",
+            "status": "completed" if result.returncode == 0 else "failed",
+            "logs": (result.stdout + "\n--- stderr ---\n" + result.stderr)[:5000],
+            "metrics": {
+                "return_code": result.returncode,
+                "output_bytes": len(result.stdout),
+            },
+        }
+
+    def _build_prompt(self, task: dict) -> str:
+        """Build a task prompt from the task description."""
+        parts = [f"Task: {task['title']}"]
+        if task.get("description"):
+            parts.append("")
+            parts.append(task["description"])
+        parts.append("")
+        parts.append("Complete this task. Report your findings and any code changes.")
+        return "\n".join(parts)
+
+    def serve(self, poll_interval: int = 10) -> None:
+        """Run the daemon: detect CLIs, heartbeat, poll, execute."""
+        found = self.detect()
+        print(f"Knit daemon starting. Detected CLIs: {found or '(none)'}")
+        if not found:
+            print("Install one of: claude, codex, openclaw, opencode")
+        print(f"Connected to hub at {self.agent.base_url}")
+        print("Press Ctrl+C to stop\n")
+
+        self.agent.start_heartbeat_loop(message=f"Daemon online, CLIs: {found}")
+        self.agent.serve(
+            handle_task=lambda t, ctx: self.execute(t, ctx),
+            poll_interval=poll_interval,
+        )
+
+
+# ---------------------------------------------------------------------------
+# CLI entry point
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    """CLI entry point (backward compatible — calls _daemon_main)."""
+    import argparse
+    parser = argparse.ArgumentParser(description="Knit Agent Daemon")
+    parser.add_argument("--hub", default=os.getenv("KNIT_HUB_URL", "http://localhost:8000/api/v1"),
+                        help="Knit hub base URL")
+    parser.add_argument("--api-key", required=True,
+                        help="Agent API key (sk_live_...)")
+    parser.add_argument("--name", default="knit-daemon",
+                        help="Agent name displayed in the hub")
+    parser.add_argument("--poll-interval", type=int, default=10,
+                        help="Seconds between task polls")
+
+    args = parser.parse_args()
+    _daemon_main(args)
+
+
+def _daemon_main(args: argparse.Namespace) -> None:
+    """Run the daemon from parsed CLI args."""
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s [%(name)s] %(levelname)s: %(message)s",
+    )
+
+    daemon = KnitDaemon(
+        hub_url=args.hub,
+        api_key=args.api_key,
+        name=args.name,
+    )
+    daemon.serve(poll_interval=args.poll_interval)
+
+
+if __name__ == "__main__":
+    main()

knit_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: knit-sdk
+Version: 0.1.0
+Summary: Python SDK for building agents on the Knit agent hub
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"

knit_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+knit/__init__.py,sha256=LbEzJbv8yAwYE8JuFsMYRfjn1lKfbI2Y7mNrLz2w9qM,204
+knit/__main__.py,sha256=kmd6JzWDphjDgtQfRop4z5aEBxMkAaIDn7B3626geEA,253
+knit/agent.py,sha256=iUbNKTigKS_oDCOo1qoqztUQcwOa0wDY-fR46OFGMmI,21103
+knit/cli.py,sha256=aiXMEWEJiwEbQY8xecrfyqeD3o5qQ33gae0gmhl4kAg,20987
+knit/daemon.py,sha256=zBEsDD721dLzYfRi9fdNGub_NTC06u2hCYfXedzOQ54,6144
+knit_sdk-0.1.0.dist-info/METADATA,sha256=-2l1Sf1cwYs_k0Excr-mKrhHvztR--rfNOzW26nxchg,313
+knit_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+knit_sdk-0.1.0.dist-info/entry_points.txt,sha256=geJwCYNp6Fy9Z0lJGNxqAkShqbHt0fUGAYtZN5Kn0Wk,39
+knit_sdk-0.1.0.dist-info/top_level.txt,sha256=B4a3-UpmAKcaTdMJf1bUs6ViNd5lWuZv_zY7h7J9khE,5
+knit_sdk-0.1.0.dist-info/RECORD,,

knit_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

knit_sdk-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+knit = knit.cli:main

knit_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+knit