yeschef-cli 0.1.0__py3-none-any.whl

yeschef/hub/__init__.py

@@ -0,0 +1,16 @@
+"""Hub: SQLite store, agent REST/SSE API, and the FastMCP tool surface."""
+
+from .api import HubConfig, create_app
+from .app import app_factory, build_hub, config_from_env
+from .events import EventBus
+from .store import Store
+
+__all__ = [
+    "EventBus",
+    "HubConfig",
+    "Store",
+    "app_factory",
+    "build_hub",
+    "config_from_env",
+    "create_app",
+]

yeschef/hub/api.py

@@ -0,0 +1,595 @@
+"""Agent-facing REST + SSE API.
+
+Authentication: agents present the bearer token minted at registration. Admin token (if
+configured) unlocks registration and the cross-identity `/watch` stream.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Body, Depends, FastAPI, Header, Query, Request
+from fastapi.responses import HTMLResponse, JSONResponse, StreamingResponse
+
+from ..models import (
+    DEFAULT_TASK_TIMEOUT_S,
+    MAX_LONG_POLL_S,
+    AgentKind,
+    ErrorCode,
+    HubError,
+    RoomPolicy,
+    TaskState,
+    now,
+)
+from .store import Store
+
+SSE_KEEPALIVE_S = 15.0
+
+# Must live at module scope: `from __future__ import annotations` turns every annotation
+# into a string, and FastAPI resolves those against module globals only.
+AuthHeader = Annotated[str | None, Header(alias="Authorization")]
+
+
+@dataclass(slots=True)
+class HubConfig:
+    db_path: str = "~/.yeschef/hub.db"
+    admin_token: str | None = None
+    register_token: str | None = None
+    sweep_interval_s: float = 10.0
+    default_identity: str = "claude:local"
+    cors_origins: list[str] = field(default_factory=list)
+
+
+def _bearer(header: str | None) -> str | None:
+    if not header:
+        return None
+    scheme, _, token = header.partition(" ")
+    if scheme.lower() != "bearer" or not token:
+        return None
+    return token.strip()
+
+
+class Auth:
+    """Resolves the calling identity for agent-facing routes.
+
+    A hub with no tokens configured runs open on the LAN (and says so at startup). As
+    soon as any token is configured, reads and admin actions require one — otherwise
+    task specs and room transcripts would stay world-readable on a hub the operator
+    believes is locked down.
+    """
+
+    def __init__(self, store: Store, config: HubConfig) -> None:
+        self.store = store
+        self.config = config
+
+    @property
+    def enforced(self) -> bool:
+        return self.config.admin_token is not None or self.config.register_token is not None
+
+    def is_privileged(self, header: str | None) -> bool:
+        token = _bearer(header)
+        return token is not None and token == self.config.admin_token
+
+    def admin(self, header: str | None) -> None:
+        if self.config.admin_token is None:
+            return
+        if _bearer(header) != self.config.admin_token:
+            raise HubError(ErrorCode.UNAUTHORIZED, "admin token required", 401)
+
+    def reader(self, header: str | None) -> str | None:
+        """Any valid identity may read. Returns the caller's name, or None in open mode."""
+        if not self.enforced:
+            return None
+        token = _bearer(header)
+        if token is None:
+            raise HubError(ErrorCode.UNAUTHORIZED, "bearer token required", 401)
+        if token == self.config.admin_token:
+            return "admin"
+        name = self.store.identify_token(token)
+        if name is None:
+            raise HubError(ErrorCode.UNAUTHORIZED, "unknown token", 401)
+        return name
+
+    def agent(self, name: str, header: str | None) -> str:
+        token = _bearer(header)
+        if token is None:
+            raise HubError(ErrorCode.UNAUTHORIZED, "bearer token required", 401)
+        if self.config.admin_token is not None and token == self.config.admin_token:
+            return name
+        if not self.store.verify_token(name, token):
+            raise HubError(ErrorCode.UNAUTHORIZED, "invalid token for agent", 401)
+        self.store.heartbeat(name)
+        return name
+
+
+def _require_room_access(caller: str | None, room) -> None:
+    """Open mode (caller is None) reads freely; an authenticated caller must belong."""
+    if caller is None or caller == "admin":
+        return
+    if caller not in room.members:
+        raise HubError(ErrorCode.FORBIDDEN, "not a member of this room", 403)
+
+
+def build_router(store: Store, config: HubConfig) -> APIRouter:
+    router = APIRouter(prefix="/api/v1")
+    auth = Auth(store, config)
+
+    def as_agent(name: str, authorization: AuthHeader = None) -> str:
+        return auth.agent(name, authorization)
+
+    # ------------------------------------------------------------- agents
+
+    @router.post("/agents/register")
+    def register(payload: dict = Body(...), authorization: AuthHeader = None) -> dict:
+        bearer = _bearer(authorization)
+        gate_tokens = {t for t in (config.register_token, config.admin_token) if t}
+        privileged = bearer is not None and bearer in gate_tokens
+        if config.register_token is not None and not privileged:
+            raise HubError(ErrorCode.UNAUTHORIZED, "registration token required", 401)
+        # `kind` is not self-declared: a claude-kind agent is exempt from round-robin
+        # floor control, so anyone could otherwise register as one and talk without limit.
+        kind = AgentKind(payload.get("kind", AgentKind.WORKER))
+        if kind is not AgentKind.WORKER and not privileged:
+            raise HubError(ErrorCode.FORBIDDEN, "only workers may self-register", 403)
+        agent, token = store.register_agent(
+            name=payload["name"],
+            kind=kind,
+            node=payload.get("node"),
+            backend=payload.get("backend"),
+            tags=payload.get("tags") or [],
+            presented_token=None if privileged else bearer,
+            privileged=privileged,
+        )
+        return {"agent": agent.to_dict(), "token": token}
+
+    @router.post("/agents/{name}/heartbeat")
+    def heartbeat(name: str, agent: str = Depends(as_agent)) -> dict:
+        return {"ok": True, "agent": name}
+
+    @router.get("/agents")
+    def list_agents(kind: str | None = None, authorization: AuthHeader = None) -> dict:
+        auth.reader(authorization)
+        agents = store.list_agents(AgentKind(kind) if kind else None)
+        return {"agents": [a.to_dict() for a in agents]}
+
+    @router.get("/agents/{name}/events")
+    async def agent_events(
+        name: str, request: Request, agent: str = Depends(as_agent)
+    ) -> StreamingResponse:
+        return StreamingResponse(
+            _event_stream(store, name, request),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+        )
+
+    # -------------------------------------------------------------- rooms
+
+    @router.post("/rooms")
+    def create_room(payload: dict = Body(...), authorization: AuthHeader = None) -> dict:
+        creator = payload["as_agent"]
+        auth.agent(creator, authorization)
+        room = store.create_room(
+            topic=payload.get("topic", "room"),
+            created_by=creator,
+            participants=payload.get("participants") or [],
+            policy=RoomPolicy.from_dict(payload.get("policy")),
+            open_room=bool(payload.get("open")),
+        )
+        return {"room": room.to_dict()}
+
+    @router.get("/rooms")
+    def list_rooms(
+        as_agent: str | None = Query(None),
+        include_archived: bool = False,
+        authorization: AuthHeader = None,
+    ) -> dict:
+        """Rooms for one agent, or every room when called with the admin token."""
+        if as_agent:
+            auth.agent(as_agent, authorization)
+        else:
+            auth.admin(authorization)
+        rooms = store.list_rooms(agent=as_agent, include_archived=include_archived)
+        return {"rooms": [r.to_dict() for r in rooms]}
+
+    @router.get("/rooms/{room_id}")
+    def get_room(room_id: str, authorization: AuthHeader = None) -> dict:
+        caller = auth.reader(authorization)
+        room = store.require_room(room_id)
+        _require_room_access(caller, room)
+        return {"room": room.to_dict()}
+
+    @router.post("/rooms/{room_id}/join")
+    def join_room(
+        room_id: str, payload: dict = Body(...), authorization: AuthHeader = None
+    ) -> dict:
+        who = payload["as_agent"]
+        auth.agent(who, authorization)
+        privileged = auth.is_privileged(authorization)
+        return {"room": store.join_room(room_id, who, privileged=privileged).to_dict()}
+
+    @router.post("/rooms/{room_id}/leave")
+    def leave_room(
+        room_id: str, payload: dict = Body(...), authorization: AuthHeader = None
+    ) -> dict:
+        who = payload["as_agent"]
+        auth.agent(who, authorization)
+        store.leave_room(room_id, who)
+        return {"ok": True}
+
+    @router.post("/rooms/{room_id}/archive")
+    def archive_room(
+        room_id: str, payload: dict = Body(default={}), authorization: AuthHeader = None
+    ) -> dict:
+        who = payload.get("as_agent")
+        if who:
+            auth.agent(who, authorization)
+        else:
+            auth.admin(authorization)
+        reason = payload.get("reason") or f"archived by {who or 'admin'}"
+        privileged = who is None or auth.is_privileged(authorization)
+        archived = store.archive_room(room_id, reason, by=who, privileged=privileged)
+        return {"room": archived.to_dict()}
+
+    @router.post("/rooms/{room_id}/messages")
+    def post_message(
+        room_id: str, payload: dict = Body(...), authorization: AuthHeader = None
+    ) -> dict:
+        sender = payload["as_agent"]
+        auth.agent(sender, authorization)
+        message = store.post_message(
+            room_id=room_id,
+            sender=sender,
+            body=payload["body"],
+            data=payload.get("data"),
+            reply_to=payload.get("reply_to"),
+            mentions=payload.get("mentions"),
+            client_msg_id=payload.get("client_msg_id"),
+            tokens=payload.get("tokens"),
+        )
+        return {"message": message.to_dict()}
+
+    @router.post("/rooms/{room_id}/yield")
+    def yield_floor(
+        room_id: str, payload: dict = Body(...), authorization: AuthHeader = None
+    ) -> dict:
+        who = payload["as_agent"]
+        auth.agent(who, authorization)
+        return {"room": store.yield_floor(room_id, who).to_dict()}
+
+    @router.get("/rooms/{room_id}/messages")
+    def get_messages(
+        room_id: str,
+        after: int = 0,
+        limit: int = 100,
+        tail: bool = False,
+        authorization: AuthHeader = None,
+    ) -> dict:
+        caller = auth.reader(authorization)
+        _require_room_access(caller, store.require_room(room_id))
+        messages = store.fetch_messages(room_id, after_seq=after, limit=min(limit, 500), tail=tail)
+        return {"messages": [m.to_dict() for m in messages]}
+
+    @router.get("/inbox")
+    def inbox(
+        as_agent: str = Query(...),
+        after: int = 0,
+        limit: int = 100,
+        room_id: str | None = None,
+        authorization: AuthHeader = None,
+    ) -> dict:
+        auth.agent(as_agent, authorization)
+        messages, cursor = store.fetch_inbox(as_agent, after, min(limit, 500), room_id)
+        return {"messages": messages, "cursor": cursor}
+
+    # -------------------------------------------------------------- tasks
+
+    @router.post("/tasks")
+    def submit_task(payload: dict = Body(...), authorization: AuthHeader = None) -> dict:
+        creator = payload["as_agent"]
+        auth.agent(creator, authorization)
+        task = store.submit_task(
+            title=payload["title"],
+            spec=payload["spec"],
+            created_by=creator,
+            assignee=payload.get("assignee"),
+            selector=payload.get("selector"),
+            priority=int(payload.get("priority", 0)),
+            timeout_s=float(payload.get("timeout_s", DEFAULT_TASK_TIMEOUT_S)),
+            dedupe_key=payload.get("dedupe_key"),
+        )
+        return {"task": task.to_dict()}
+
+    @router.get("/tasks")
+    def list_tasks(
+        state: str | None = None,
+        assignee: str | None = None,
+        created_by: str | None = None,
+        limit: int = 100,
+        authorization: AuthHeader = None,
+    ) -> dict:
+        caller = auth.reader(authorization)
+        if caller is not None and caller != "admin" and not (assignee or created_by):
+            # A plain agent sees its own work, not the whole fleet's task specs.
+            own = store.list_tasks(state=TaskState(state) if state else None, assignee=caller)
+            mine = store.list_tasks(state=TaskState(state) if state else None, created_by=caller)
+            merged = {t.id: t for t in [*own, *mine]}
+            return {"tasks": [t.to_dict() for t in merged.values()][:limit]}
+        tasks = store.list_tasks(
+            state=TaskState(state) if state else None,
+            assignee=assignee,
+            created_by=created_by,
+            limit=limit,
+        )
+        return {"tasks": [t.to_dict() for t in tasks]}
+
+    @router.get("/tasks/next")
+    def next_task(as_agent: str = Query(...), authorization: AuthHeader = None) -> dict:
+        auth.agent(as_agent, authorization)
+        task = store.next_task_for(as_agent)
+        return {"task": task.to_dict() if task else None}
+
+    @router.get("/tasks/{task_id}")
+    def get_task(task_id: str, authorization: AuthHeader = None) -> dict:
+        caller = auth.reader(authorization)
+        task = store.require_task(task_id)
+        if (
+            caller is not None
+            and caller != "admin"
+            and caller
+            not in (
+                task.created_by,
+                task.assignee,
+            )
+        ):
+            raise HubError(ErrorCode.FORBIDDEN, "not your task", 403)
+        return {"task": task.to_dict(), "events": [e.to_dict() for e in store.task_events(task_id)]}
+
+    @router.post("/tasks/{task_id}/claim")
+    def claim_task(
+        task_id: str, payload: dict = Body(...), authorization: AuthHeader = None
+    ) -> dict:
+        who = payload["as_agent"]
+        auth.agent(who, authorization)
+        return {"task": store.claim_task(task_id, who).to_dict()}
+
+    @router.post("/tasks/{task_id}/progress")
+    def task_progress(
+        task_id: str, payload: dict = Body(...), authorization: AuthHeader = None
+    ) -> dict:
+        who = payload["as_agent"]
+        auth.agent(who, authorization)
+        task = store.update_progress(task_id, who, payload.get("pct"), payload.get("message"))
+        return {"task": task.to_dict()}
+
+    @router.post("/tasks/{task_id}/result")
+    def task_result(
+        task_id: str, payload: dict = Body(...), authorization: AuthHeader = None
+    ) -> dict:
+        who = payload["as_agent"]
+        auth.agent(who, authorization)
+        return {"task": store.complete_task(task_id, who, payload.get("result")).to_dict()}
+
+    @router.post("/tasks/{task_id}/fail")
+    def task_fail(
+        task_id: str, payload: dict = Body(...), authorization: AuthHeader = None
+    ) -> dict:
+        who = payload["as_agent"]
+        auth.agent(who, authorization)
+        return {
+            "task": store.fail_task(
+                task_id, who, payload.get("error", "unknown"), result=payload.get("result")
+            ).to_dict()
+        }
+
+    @router.post("/tasks/{task_id}/input_required")
+    def task_input_required(
+        task_id: str, payload: dict = Body(...), authorization: AuthHeader = None
+    ) -> dict:
+        who = payload["as_agent"]
+        auth.agent(who, authorization)
+        return {"task": store.request_input(task_id, who, payload["question"]).to_dict()}
+
+    @router.post("/tasks/{task_id}/input")
+    def task_input(
+        task_id: str, payload: dict = Body(...), authorization: AuthHeader = None
+    ) -> dict:
+        who = payload["as_agent"]
+        auth.agent(who, authorization)
+        return {"task": store.provide_input(task_id, who, payload["message"]).to_dict()}
+
+    @router.post("/tasks/{task_id}/cancel")
+    def task_cancel(
+        task_id: str, payload: dict = Body(default={}), authorization: AuthHeader = None
+    ) -> dict:
+        who = payload.get("as_agent")
+        if who:
+            auth.agent(who, authorization)
+        else:
+            auth.admin(authorization)
+        privileged = who is None or auth.is_privileged(authorization)
+        cancelled = store.cancel_task(task_id, who or "admin", privileged=privileged)
+        return {"task": cancelled.to_dict()}
+
+    # ---------------------------------------------------------- artifacts
+
+    @router.post("/artifacts")
+    def upload_artifact(payload: dict = Body(...), authorization: AuthHeader = None) -> dict:
+        who = payload["as_agent"]
+        auth.agent(who, authorization)
+        import base64
+
+        content = base64.b64decode(payload["content_b64"])
+        meta = store.save_artifact(
+            name=payload.get("name", "artifact"),
+            mime=payload.get("mime", "application/octet-stream"),
+            content=content,
+            created_by=who,
+        )
+        return {"artifact": meta}
+
+    @router.get("/artifacts/{artifact_id}")
+    def download_artifact(artifact_id: str, authorization: AuthHeader = None) -> dict:
+        auth.reader(authorization)
+        import base64
+
+        meta, content = store.get_artifact(artifact_id)
+        return {"artifact": meta, "content_b64": base64.b64encode(content).decode()}
+
+    # -------------------------------------------------------------- watch
+
+    @router.get("/watch")
+    async def watch(
+        request: Request, identity: str = Query(...), authorization: AuthHeader = None
+    ) -> StreamingResponse:
+        auth.admin(authorization)
+        store.ensure_identity(identity)
+        return StreamingResponse(
+            _event_stream(store, identity, request),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+        )
+
+    return router
+
+
+async def _event_stream(store: Store, agent: str, request: Request) -> AsyncIterator[str]:
+    """SSE stream. The open connection doubles as the agent's heartbeat."""
+    async with store.bus.subscribe(agent) as queue:
+        store.heartbeat(agent)
+        yield _sse({"kind": "connected", "agent": agent})
+        while True:
+            if await request.is_disconnected():
+                break
+            try:
+                event = await asyncio.wait_for(queue.get(), timeout=SSE_KEEPALIVE_S)
+            except TimeoutError:
+                store.heartbeat(agent)
+                yield ": keepalive\n\n"
+                continue
+            store.heartbeat(agent)
+            yield _sse(event)
+
+
+def _sse(payload: dict) -> str:
+    return f"data: {json.dumps(payload)}\n\n"
+
+
+def create_app(store: Store, config: HubConfig, mcp_app: Any | None = None) -> FastAPI:
+    @contextlib.asynccontextmanager
+    async def lifespan(app: FastAPI):
+        store.bus.bind(asyncio.get_running_loop())
+        sweeper = asyncio.create_task(_sweep_loop(store, config.sweep_interval_s))
+        try:
+            if mcp_app is not None and hasattr(mcp_app, "lifespan"):
+                async with mcp_app.lifespan(app):
+                    yield
+            else:
+                yield
+        finally:
+            sweeper.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await sweeper
+
+    app = FastAPI(title="yeschef hub", version="0.1.0", lifespan=lifespan)
+
+    @app.exception_handler(HubError)
+    async def hub_error_handler(request: Request, exc: HubError) -> JSONResponse:
+        return JSONResponse(status_code=exc.http_status, content=exc.to_dict())
+
+    @app.get("/healthz")
+    def healthz() -> dict:
+        agents = store.list_agents()
+        return {
+            "ok": True,
+            "agents": len(agents),
+            "online": sum(1 for a in agents if str(a.status()) == "online"),
+            "queued_tasks": len(store.list_tasks(state=TaskState.QUEUED)),
+            "lifetime": store.lifetime_stats(),
+        }
+
+    @app.get("/overview")
+    def overview() -> dict:
+        """Read-only fleet snapshot for the dashboard — curated to omit task specs and
+        result bodies, so it is safe to serve un-authenticated within the same
+        LAN/Tailscale boundary as /healthz (never expose the hub through a funnel)."""
+        ref = now()
+        agents = store.list_agents()
+        active: dict[str, int] = {}
+        for t in store.list_tasks(limit=500):
+            if t.state in (TaskState.CLAIMED, TaskState.WORKING, TaskState.INPUT_REQUIRED):
+                if t.assignee:
+                    active[t.assignee] = active.get(t.assignee, 0) + 1
+        workers = []
+        for a in agents:
+            if a.kind is not AgentKind.WORKER:
+                continue
+            d = a.to_dict(ref)
+            d["active_tasks"] = active.get(a.name, 0)
+            d["heartbeat_age_s"] = round(ref - a.last_seen, 1)
+            workers.append(d)
+        workers.sort(key=lambda w: (w["status"] != "online", w["name"]))
+
+        def task_row(t) -> dict:
+            return {
+                "id": t.id,
+                "title": t.title,
+                "state": str(t.state),
+                "assignee": t.assignee,
+                "selector": t.selector,
+                "progress": {"pct": t.progress_pct, "message": t.progress_msg},
+                "attempts": t.attempts,
+                "error": t.error,
+                "age_s": round(ref - t.created_at, 1) if t.created_at else None,
+                "ran_s": (
+                    round(t.finished_at - t.claimed_at, 1)
+                    if t.finished_at and t.claimed_at
+                    else None
+                ),
+                "files": len((t.result or {}).get("files") or []),
+            }
+
+        tasks = [task_row(t) for t in store.list_tasks(limit=60)]
+        rooms = [
+            {
+                "id": r.id,
+                "topic": r.topic,
+                "members": [m for m in r.members if not m.startswith(("claude:", "operator:"))],
+                "is_dm": r.dm_key is not None,
+                "archived": r.archived,
+                "archived_reason": r.archived_reason,
+            }
+            for r in store.list_rooms(include_archived=True)[:20]
+        ]
+        return {
+            "now": ref,
+            "workers": workers,
+            "sessions": [a.to_dict(ref) for a in agents if a.kind is AgentKind.CLAUDE],
+            "tasks": tasks,
+            "rooms": rooms,
+            "lifetime": store.lifetime_stats(),
+        }
+
+    @app.get("/", response_class=HTMLResponse)
+    def dashboard() -> str:
+        return (Path(__file__).with_name("dashboard.html")).read_text()
+
+    app.include_router(build_router(store, config))
+    if mcp_app is not None:
+        app.mount("/mcp", mcp_app)
+    return app
+
+
+async def _sweep_loop(store: Store, interval: float) -> None:
+    while True:
+        await asyncio.sleep(interval)
+        with contextlib.suppress(Exception):
+            await asyncio.to_thread(store.sweep)
+
+
+__all__ = ["HubConfig", "create_app", "build_router", "MAX_LONG_POLL_S"]

yeschef/hub/app.py

@@ -0,0 +1,43 @@
+"""Assemble the hub: one ASGI app serving /mcp for Claude Code and /api/v1 for agents."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastapi import FastAPI
+
+from .api import HubConfig, create_app
+from .events import EventBus
+from .store import Store
+
+
+def config_from_env() -> HubConfig:
+    from ..settings import env, home
+
+    return HubConfig(
+        db_path=env("DB", str(home() / "hub.db")),
+        admin_token=env("ADMIN_TOKEN"),
+        register_token=env("REGISTER_TOKEN"),
+        default_identity=env("IDENTITY", "claude:local"),
+    )
+
+
+def build_hub(config: HubConfig | None = None) -> tuple[FastAPI, Store]:
+    config = config or config_from_env()
+    db_path = (
+        config.db_path if config.db_path == ":memory:" else str(Path(config.db_path).expanduser())
+    )
+    store = Store(db_path, EventBus())
+
+    from .mcp_server import build_mcp
+
+    mcp = build_mcp(store, config)
+    mcp_app = mcp.http_app(path="/")
+    app = create_app(store, config, mcp_app=mcp_app)
+    return app, store
+
+
+def app_factory() -> FastAPI:
+    """Entry point for `uvicorn yeschef.hub.app:app_factory --factory`."""
+    app, _ = build_hub()
+    return app