yeschef-cli 0.1.0__py3-none-any.whl

yeschef/models.py

@@ -0,0 +1,431 @@
+"""Shared types for hub, SDK, and harness.
+
+Task states deliberately mirror the MCP Tasks extension vocabulary (SEP-2663) so the
+tool surface can be upgraded to spec-native tasks without renaming anything.
+"""
+
+from __future__ import annotations
+
+import secrets
+import time
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+_ALPHABET = "23456789abcdefghjkmnpqrstuvwxyz"
+
+
+def now() -> float:
+    """Hub-assigned UTC epoch seconds. Agents never write times."""
+    return time.time()
+
+
+def _iso(ts: float | None) -> str | None:
+    if not ts:
+        return None
+    import datetime as _dt
+
+    return _dt.datetime.fromtimestamp(ts, _dt.UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def new_id(prefix: str, length: int = 10) -> str:
+    body = "".join(secrets.choice(_ALPHABET) for _ in range(length))
+    return f"{prefix}_{body}"
+
+
+class TaskState(StrEnum):
+    QUEUED = "queued"
+    CLAIMED = "claimed"
+    WORKING = "working"
+    INPUT_REQUIRED = "input_required"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+    @property
+    def terminal(self) -> bool:
+        return self in (TaskState.COMPLETED, TaskState.FAILED, TaskState.CANCELLED)
+
+    @property
+    def active(self) -> bool:
+        """Held by an agent — subject to heartbeat reclamation."""
+        return self in (TaskState.CLAIMED, TaskState.WORKING, TaskState.INPUT_REQUIRED)
+
+
+class AgentKind(StrEnum):
+    WORKER = "worker"
+    CLAUDE = "claude"
+
+
+class AgentStatus(StrEnum):
+    ONLINE = "online"
+    BUSY = "busy"
+    OFFLINE = "offline"
+
+
+class TurnPolicy(StrEnum):
+    FREE = "free"
+    ROUND_ROBIN = "round_robin"
+
+
+class ReplyWhen(StrEnum):
+    MENTIONED = "mentioned"
+    ROUND_ROBIN = "round_robin"
+    ALWAYS = "always"
+
+
+class EventKind(StrEnum):
+    MESSAGE = "message"
+    TASK_ASSIGNED = "task_assigned"
+    TASK_CANCELLED = "task_cancelled"
+    TASK_UPDATED = "task_updated"
+    ROOM_INVITE = "room_invite"
+    FLOOR_GRANTED = "floor_granted"
+    ROOM_ARCHIVED = "room_archived"
+    SHUTDOWN = "shutdown"
+
+
+class ErrorCode(StrEnum):
+    NOT_FOUND = "not_found"
+    CONFLICT = "conflict"
+    FORBIDDEN = "forbidden"
+    UNAUTHORIZED = "unauthorized"
+    INVALID = "invalid"
+    POLICY_EXCEEDED = "policy_exceeded"
+
+
+class HubError(Exception):
+    """Error that crosses the wire as {"error": {"code", "message"}}."""
+
+    def __init__(self, code: ErrorCode, message: str, http_status: int = 400) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.http_status = http_status
+
+    def to_dict(self) -> dict:
+        return {"error": {"code": str(self.code), "message": self.message}}
+
+
+def not_found(what: str) -> HubError:
+    return HubError(ErrorCode.NOT_FOUND, f"{what} not found", 404)
+
+
+HEARTBEAT_TTL_S = 30.0
+"""Agent considered offline after this long without a heartbeat or open event stream."""
+
+MAX_LONG_POLL_S = 60.0
+"""Cap on any explicit wait, staying clear of Claude Code's ~2 min auto-background."""
+
+MAX_ARTIFACT_BYTES = 32 * 1024 * 1024
+
+DEFAULT_TASK_TIMEOUT_S = 3600.0
+
+INPUT_REQUIRED_TTL_S = 30 * 60.0
+"""A parked question fails the task after this long — stranded input_required tasks
+sat for 41 minutes with nobody notified before this existed."""
+
+DEFAULT_MAX_ROOM_MESSAGES = 200
+"""Backstop applied to any room created without a message cap.
+
+The point is not the number — it is that no room is ever unbounded. Two agents set to
+reply on every message will otherwise talk to each other until the hardware gives out.
+"""
+
+DEFAULT_ROOM_IDLE_TIMEOUT_S = 24 * 3600.0
+"""Backstop applied to any room created without an idle timeout."""
+
+
+@dataclass(slots=True)
+class ToolCall:
+    """A model's request to run a worker-side tool.
+
+    Lives here rather than in `agent.backends` so `tools` and `agent` can both use it
+    without importing each other.
+    """
+
+    id: str
+    name: str
+    arguments: dict
+
+
+@dataclass(slots=True)
+class ToolResult:
+    call_id: str
+    name: str
+    content: str
+    is_error: bool = False
+
+
+@dataclass(slots=True)
+class RoomPolicy:
+    """Hub-enforced guards. Every autonomous room is bounded by construction."""
+
+    turn_policy: TurnPolicy = TurnPolicy.FREE
+    max_messages: int | None = None
+    max_total_tokens: int | None = None
+    idle_timeout_s: float | None = None
+    stop_phrase: str | None = None
+
+    def to_dict(self) -> dict:
+        return {
+            "turn_policy": str(self.turn_policy),
+            "max_messages": self.max_messages,
+            "max_total_tokens": self.max_total_tokens,
+            "idle_timeout_s": self.idle_timeout_s,
+            "stop_phrase": self.stop_phrase,
+        }
+
+    @classmethod
+    def from_dict(cls, raw: dict | None) -> RoomPolicy:
+        raw = raw or {}
+        return cls(
+            turn_policy=TurnPolicy(raw.get("turn_policy") or TurnPolicy.FREE),
+            max_messages=raw.get("max_messages"),
+            max_total_tokens=raw.get("max_total_tokens"),
+            idle_timeout_s=raw.get("idle_timeout_s"),
+            stop_phrase=raw.get("stop_phrase"),
+        )
+
+    def bounded(
+        self,
+        max_messages: int = DEFAULT_MAX_ROOM_MESSAGES,
+        idle_timeout_s: float = DEFAULT_ROOM_IDLE_TIMEOUT_S,
+    ) -> RoomPolicy:
+        """Return this policy with backstops filled in where the caller left gaps.
+
+        Every room goes through here, so an unbounded conversation cannot be created
+        by omission — only a caller who names a larger explicit limit gets one.
+        """
+        return RoomPolicy(
+            turn_policy=self.turn_policy,
+            max_messages=self.max_messages if self.max_messages is not None else max_messages,
+            max_total_tokens=self.max_total_tokens,
+            idle_timeout_s=(
+                self.idle_timeout_s if self.idle_timeout_s is not None else idle_timeout_s
+            ),
+            stop_phrase=self.stop_phrase,
+        )
+
+
+@dataclass(slots=True)
+class Agent:
+    name: str
+    kind: AgentKind
+    node: str | None = None
+    backend: str | None = None
+    tags: list[str] = field(default_factory=list)
+    last_seen: float = 0.0
+    created_at: float = 0.0
+
+    def status(self, ref: float | None = None) -> AgentStatus:
+        ref = ref if ref is not None else now()
+        if ref - self.last_seen > HEARTBEAT_TTL_S:
+            return AgentStatus.OFFLINE
+        return AgentStatus.ONLINE
+
+    def matches(self, selector: str) -> bool:
+        """`name` match, or `tag:value` / bare tag selector.
+
+        `a|b` is a union: any part matching means the agent matches, so tag-faithful
+        dispatch can still spill onto idle capacity (`tier:fast|tier:build`).
+        """
+        return any(
+            part == "*" or part == self.name or part in self.tags
+            for part in (p.strip() for p in selector.split("|"))
+            if part
+        )
+
+    def to_dict(self, ref: float | None = None) -> dict:
+        return {
+            "name": self.name,
+            "kind": str(self.kind),
+            "node": self.node,
+            "backend": self.backend,
+            "tags": list(self.tags),
+            "status": str(self.status(ref)),
+            "heartbeat_age_s": round((ref if ref is not None else now()) - self.last_seen, 1),
+            "last_seen": self.last_seen,
+            "created_at": self.created_at,
+        }
+
+
+@dataclass(slots=True)
+class Room:
+    id: str
+    topic: str
+    created_by: str
+    open: bool = False
+    policy: RoomPolicy = field(default_factory=RoomPolicy)
+    archived: bool = False
+    archived_reason: str | None = None
+    dm_key: str | None = None
+    floor_holder: str | None = None
+    created_at: float = 0.0
+    members: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "topic": self.topic,
+            "created_by": self.created_by,
+            "open": self.open,
+            "is_dm": self.dm_key is not None,
+            "floor_holder": self.floor_holder,
+            "policy": self.policy.to_dict(),
+            "archived": self.archived,
+            "archived_reason": self.archived_reason,
+            "members": list(self.members),
+            "created_at": self.created_at,
+        }
+
+
+@dataclass(slots=True)
+class Message:
+    id: str
+    room_id: str
+    seq: int
+    sender: str
+    body: str
+    data: dict | None = None
+    reply_to: str | None = None
+    mentions: list[str] = field(default_factory=list)
+    created_at: float = 0.0
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "room_id": self.room_id,
+            "seq": self.seq,
+            "sender": self.sender,
+            "body": self.body,
+            "data": self.data,
+            "reply_to": self.reply_to,
+            "mentions": list(self.mentions),
+            "created_at": self.created_at,
+        }
+
+
+@dataclass(slots=True)
+class Task:
+    id: str
+    title: str
+    spec: str
+    created_by: str
+    state: TaskState = TaskState.QUEUED
+    assignee: str | None = None
+    selector: str | None = None
+    priority: int = 0
+    timeout_s: float = DEFAULT_TASK_TIMEOUT_S
+    dedupe_key: str | None = None
+    project: str | None = None
+    output_mode: str | None = None
+    data: str | None = None
+    input_required_at: float | None = None
+    room_id: str | None = None
+    progress_pct: float | None = None
+    progress_msg: str | None = None
+    result: dict | None = None
+    error: str | None = None
+    attempts: int = 0
+    created_at: float = 0.0
+    claimed_at: float | None = None
+    finished_at: float | None = None
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "spec": self.spec,
+            "created_by": self.created_by,
+            "state": str(self.state),
+            "assignee": self.assignee,
+            "selector": self.selector,
+            "project": self.project,
+            "output_mode": self.output_mode,
+            "data": self.data,
+            "priority": self.priority,
+            "timeout_s": self.timeout_s,
+            "room_id": self.room_id,
+            "progress": {"pct": self.progress_pct, "message": self.progress_msg},
+            "result": self.result,
+            "error": self.error,
+            "attempts": self.attempts,
+            "created_at": self.created_at,
+            "claimed_at": self.claimed_at,
+            "finished_at": self.finished_at,
+            "created_iso": _iso(self.created_at),
+            "claimed_iso": _iso(self.claimed_at),
+            "finished_iso": _iso(self.finished_at),
+        }
+
+    def to_summary(self) -> dict:
+        """Slim view for acks, waits, and listings — no spec or result bodies.
+
+        The spec is text the caller wrote and the result has its own tool; echoing
+        either in every reply re-bills an orchestrating model for its own words on
+        each poll of a long task.
+        """
+        return {
+            "id": self.id,
+            "title": self.title,
+            "state": str(self.state),
+            "assignee": self.assignee,
+            "created_by": self.created_by,
+            "project": self.project,
+            "priority": self.priority or None,
+            "room_id": self.room_id,
+            "progress": {"pct": self.progress_pct, "message": self.progress_msg},
+            "error": self.error,
+            "attempts": self.attempts,
+            "created_at": self.created_at,
+            "finished_at": self.finished_at,
+            "input_expires_at": (
+                round(
+                    (self.input_required_at or self.claimed_at or self.created_at)
+                    + INPUT_REQUIRED_TTL_S,
+                    1,
+                )
+                if str(self.state) == "input_required"
+                else None
+            ),
+            "flags": [
+                k
+                for k in (
+                    "truncated",
+                    "no_files",
+                    "all_tools_failed",
+                    "code_in_text_only",
+                    "unverified_claims",
+                    "tool_text_unparsed",
+                    "echoes_spec",
+                    "partial",
+                )
+                if (self.result or {}).get(k)
+            ]
+            or None,
+            "age_s": round(now() - self.created_at, 1) if self.created_at else None,
+            "ran_s": (
+                round(self.finished_at - self.claimed_at, 1)
+                if self.finished_at and self.claimed_at
+                else None
+            ),
+            "files": len((self.result or {}).get("files") or []),
+        }
+
+
+@dataclass(slots=True)
+class TaskEvent:
+    id: str
+    task_id: str
+    kind: str
+    payload: dict
+    created_at: float
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "task_id": self.task_id,
+            "kind": self.kind,
+            "payload": self.payload,
+            "created_at": self.created_at,
+        }

yeschef/procs.py

@@ -0,0 +1,109 @@
+"""Track detached hub/agent processes so one terminal can start and stop the fleet.
+
+Best-effort process supervision: enough for `up --detach` / `join --detach` / `down`
+on a workstation, not a replacement for the launchd and systemd units under
+examples/deploy/ for a real deployment.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+import subprocess
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from .settings import home
+
+
+def _run_dir() -> Path:
+    path = home() / "run"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+@dataclass(slots=True)
+class Proc:
+    label: str
+    pid: int
+    kind: str  # "hub" | "agent"
+    log: str
+    command: list[str]
+
+
+def _record_path(label: str) -> Path:
+    safe = label.replace("/", "_").replace(":", "_")
+    return _run_dir() / f"{safe}.json"
+
+
+def spawn(label: str, kind: str, command: list[str]) -> Proc:
+    """Start a detached child that outlives this process, logging to a file."""
+    existing = get(label)
+    if existing and is_alive(existing.pid):
+        raise RuntimeError(f"'{label}' is already running (pid {existing.pid})")
+
+    log_path = _run_dir() / f"{label.replace('/', '_').replace(':', '_')}.log"
+    log_file = open(log_path, "ab")  # noqa: SIM115 - handed to the child, closed on exit
+    kwargs: dict = {"stdout": log_file, "stderr": subprocess.STDOUT, "stdin": subprocess.DEVNULL}
+    if os.name == "nt":
+        kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP  # type: ignore[attr-defined]
+    else:
+        kwargs["start_new_session"] = True
+
+    process = subprocess.Popen(command, **kwargs)  # noqa: S603 - command is built by us
+    log_file.close()
+    proc = Proc(label=label, pid=process.pid, kind=kind, log=str(log_path), command=command)
+    _record_path(label).write_text(json.dumps(asdict(proc), indent=2))
+    return proc
+
+
+def is_alive(pid: int) -> bool:
+    if os.name == "nt":
+        out = subprocess.run(["tasklist", "/FI", f"PID eq {pid}"], capture_output=True, text=True)
+        return str(pid) in out.stdout
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def get(label: str) -> Proc | None:
+    path = _record_path(label)
+    if not path.exists():
+        return None
+    raw = json.loads(path.read_text())
+    return Proc(**raw)
+
+
+def list_all() -> list[Proc]:
+    return [Proc(**json.loads(p.read_text())) for p in sorted(_run_dir().glob("*.json"))]
+
+
+def stop(label: str) -> bool:
+    proc = get(label)
+    if proc is None:
+        return False
+    if is_alive(proc.pid):
+        try:
+            if os.name == "nt":
+                os.kill(proc.pid, signal.CTRL_BREAK_EVENT)  # type: ignore[attr-defined]
+            else:
+                os.kill(proc.pid, signal.SIGTERM)
+        except (ProcessLookupError, PermissionError):
+            pass
+    _record_path(proc.label).unlink(missing_ok=True)
+    return True
+
+
+def stop_all() -> list[str]:
+    return [proc.label for proc in list_all() if stop(proc.label)]
+
+
+def cli_executable() -> list[str]:
+    """How to re-invoke this CLI for a detached child."""
+    return [sys.executable, "-m", "yeschef"]