mosscode 0.1.0__py3-none-any.whl

mosscode/teams/board.py

@@ -0,0 +1,230 @@
+"""The team's shared task list, tasks.json under its lock.
+
+Not agents/tasks.py: those are the one-shot sub-agents of a session (/tasks, task_output).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from dataclasses import asdict, dataclass, field, fields
+from pathlib import Path
+
+from .lock import TeamError, atomic_write, file_lock, load_json, now
+from .mailbox import LEAD
+
+STATUSES = ("pending", "in_progress", "completed")
+STATUS_LABELS = {"pending": "待办", "in_progress": "进行中", "completed": "已完成"}
+TASK_LIMIT = 200
+SUBJECT_LIMIT = 120
+DESCRIPTION_LIMIT = 20000
+
+
+@dataclass
+class TeamTask:
+    id: str
+    subject: str
+    description: str = ""
+    status: str = "pending"
+    owner: str = ""
+    blocked_by: list[str] = field(default_factory=list)
+    created: str = field(default_factory=now)
+    updated: str = field(default_factory=now)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> TeamTask:
+        known = {item.name for item in fields(cls)}
+        return cls(**{key: value for key, value in data.items() if key in known})
+
+
+@dataclass(frozen=True)
+class Updated:
+    task: TeamTask
+    ready: tuple[TeamTask, ...] = ()  # Pending tasks this update made ready.
+
+
+def _valid(data) -> bool:
+    return (
+        isinstance(data, dict)
+        and isinstance(data.get("tasks"), list)
+        and all(isinstance(item, dict) and isinstance(item.get("id"), str) for item in data["tasks"])
+    )
+
+
+def is_ready(task: TeamTask, tasks: dict[str, TeamTask]) -> bool:
+    """Every task it waits for is completed."""
+    return all(tasks[dep].status == "completed" for dep in task.blocked_by if dep in tasks)
+
+
+def blocks(task_id: str, tasks: Iterable[TeamTask]) -> list[str]:
+    """Derived, never stored."""
+    return [task.id for task in tasks if task_id in task.blocked_by]
+
+
+def _reaches(start: str, target: str, tasks: dict[str, TeamTask]) -> bool:
+    """Whether start waits, directly or not, for target."""
+    seen, stack = set(), [start]
+    while stack:
+        current = stack.pop()
+        if current == target:
+            return True
+        if current in seen or current not in tasks:
+            continue
+        seen.add(current)
+        stack.extend(tasks[current].blocked_by)
+    return False
+
+
+def _text(value: str, name: str, limit: int, *, required: bool = False) -> str:
+    value = value.strip()
+    if required and not value:
+        raise TeamError("invalid_task", f"{name} 不能为空。")
+    if len(value) > limit:
+        raise TeamError("invalid_task", f"{name} 最多 {limit} 字。")
+    return value
+
+
+class TaskBoard:
+    def __init__(self, path: Path, on_notice: Callable[[str], None] | None = None):
+        self.path = path
+        self.on_notice = on_notice
+
+    def _load(self) -> dict[str, TeamTask]:
+        data = load_json(self.path, lambda: {"v": 1, "tasks": []}, _valid, self.on_notice)
+        tasks = {}
+        for item in data["tasks"]:
+            try:
+                task = TeamTask.from_dict(item)
+            except TypeError:
+                continue
+            tasks[task.id] = task
+        return tasks
+
+    def _save(self, tasks: dict[str, TeamTask]) -> None:
+        atomic_write(self.path, {"v": 1, "tasks": [asdict(task) for task in tasks.values()]})
+
+    def list(self) -> list[TeamTask]:
+        return list(self._load().values())
+
+    def get(self, task_id: str) -> TeamTask:
+        task = self._load().get(task_id)
+        if task is None:
+            raise TeamError("unknown_task", f"没有编号为 {task_id} 的任务。")
+        return task
+
+    def create(
+        self,
+        subject: str,
+        description: str = "",
+        blocked_by: Iterable[str] = (),
+        *,
+        owner: str = "",
+        actor: str = LEAD,
+        participants: Iterable[str] = (),
+    ) -> TeamTask:
+        subject = _text(subject, "subject", SUBJECT_LIMIT, required=True)
+        description = _text(description, "description", DESCRIPTION_LIMIT)
+        with file_lock(self.path):
+            tasks = self._load()
+            if len(tasks) >= TASK_LIMIT:
+                raise TeamError("too_many_tasks", f"一个团队最多 {TASK_LIMIT} 个任务。")
+            deps = self._deps(blocked_by, tasks)
+            owner = self._owner(owner, actor, participants)
+            number = max((int(key) for key in tasks if key.isdigit()), default=0) + 1
+            task = TeamTask(str(number), subject, description, owner=owner, blocked_by=deps)
+            tasks[task.id] = task
+            self._save(tasks)
+        return task
+
+    def update(
+        self,
+        task_id: str,
+        *,
+        actor: str,
+        participants: Iterable[str] = (),
+        status: str | None = None,
+        owner: str | None = None,
+        subject: str | None = None,
+        description: str | None = None,
+        add_blocked_by: Iterable[str] = (),
+        remove_blocked_by: Iterable[str] = (),
+    ) -> Updated:
+        """The result lists the tasks that became ready."""
+        add_blocked_by, remove_blocked_by = list(add_blocked_by), list(remove_blocked_by)
+        with file_lock(self.path):
+            tasks = self._load()
+            task = tasks.get(task_id)
+            if task is None:
+                raise TeamError("unknown_task", f"没有编号为 {task_id} 的任务。")
+            lead = actor == LEAD
+            if not lead and task.owner not in {"", actor}:
+                raise TeamError("not_owner", f"任务 {task_id} 归 {task.owner} 负责，只有负责人或 Lead 能修改。")
+            if remove_blocked_by and not lead:
+                raise TeamError("lead_only", "只有 Lead 能移除依赖。")
+            before = {key: is_ready(item, tasks) for key, item in tasks.items() if item.status == "pending"}
+            if subject is not None:
+                task.subject = _text(subject, "subject", SUBJECT_LIMIT, required=True)
+            if description is not None:
+                task.description = _text(description, "description", DESCRIPTION_LIMIT)
+            if owner is not None:
+                task.owner = self._owner(owner, actor, participants)
+            if remove_blocked_by:
+                task.blocked_by = [dep for dep in task.blocked_by if dep not in remove_blocked_by]
+            for dep in self._deps(add_blocked_by, tasks):
+                if dep == task.id or _reaches(dep, task.id, tasks):
+                    raise TeamError("dependency_cycle", f"任务 {task.id} 依赖 {dep} 会形成循环依赖。")
+                if dep not in task.blocked_by:
+                    task.blocked_by.append(dep)
+            if status is not None:
+                self._move(task, status, actor, tasks)
+            task.updated = now()
+            self._save(tasks)
+        ready = tuple(
+            tasks[key]
+            for key, was in before.items()
+            if not was and tasks[key].status == "pending" and is_ready(tasks[key], tasks)
+        )
+        return Updated(task, ready)
+
+    @staticmethod
+    def _deps(blocked_by: Iterable[str], tasks: dict[str, TeamTask]) -> list[str]:
+        deps = []
+        for dep in blocked_by:
+            dep = str(dep).strip()
+            if dep not in tasks:
+                raise TeamError("unknown_task", f"依赖的任务 {dep} 不存在。")
+            if dep not in deps:
+                deps.append(dep)
+        return deps
+
+    @staticmethod
+    def _owner(owner: str, actor: str, participants: Iterable[str]) -> str:
+        """A member takes tasks for itself only; the lead assigns anyone on the roster."""
+        owner = owner.strip()
+        if not owner:
+            if actor != LEAD:
+                raise TeamError("lead_only", "只有 Lead 能清除负责人。")
+            return ""
+        if actor != LEAD and owner != actor:
+            raise TeamError("not_owner", "成员只能把任务领给自己。")
+        if owner != LEAD and owner not in set(participants):
+            raise TeamError("unknown_member", f"团队中没有成员 {owner}；先用 team_spawn 创建它，或先不填负责人。")
+        return owner
+
+    @staticmethod
+    def _move(task: TeamTask, status: str, actor: str, tasks: dict[str, TeamTask]) -> None:
+        """Forward only, and only once ready; the lead may send a task back to pending."""
+        if status not in STATUSES:
+            raise TeamError("invalid_task", f"状态只能是 {'、'.join(STATUSES)}。")
+        old, new = STATUSES.index(task.status), STATUSES.index(status)
+        if new < old:
+            if actor != LEAD or status != "pending":
+                raise TeamError("invalid_transition", "状态只能前进；只有 Lead 能把任务改回 pending。")
+        elif new > old:
+            if not is_ready(task, tasks):
+                waiting = [dep for dep in task.blocked_by if dep in tasks and tasks[dep].status != "completed"]
+                raise TeamError("task_blocked", f"任务 {task.id} 还在等待任务 {'、'.join(waiting)} 完成。")
+            if not task.owner:
+                if actor == LEAD:
+                    raise TeamError("no_owner", f"任务 {task.id} 没有负责人；先指定 owner。")
+                task.owner = actor
+        task.status = status

mosscode/teams/lock.py

@@ -0,0 +1,173 @@
+"""A lock file next to each data file, and writes a reader never sees half done.
+
+Every team file (config, tasks, mailboxes) is read, changed and written under its lock; the lock is
+held only for the file work, never across a model call.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+import secrets
+import time
+from collections.abc import Callable
+from contextlib import contextmanager
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+LOCK_RETRIES = 10
+BACKOFF = (0.005, 0.1)  # Seconds, random within.
+STALE_AFTER = 10.0  # Seconds; an older lock file belongs to a process that died holding it.
+DEADLINE = 5.0  # Seconds of waiting in all, however often the lock changed hands.
+REPLACE_RETRIES = 3
+
+
+class TeamError(Exception):
+    """A team operation that did not happen; code is the tool error code."""
+
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+def now() -> str:
+    return datetime.now().astimezone().isoformat(timespec="seconds")
+
+
+def _stale(lock: Path, after: float) -> bool:
+    try:
+        return time.time() - lock.stat().st_mtime > after
+    except OSError:
+        return False  # Gone already: the next attempt will tell.
+
+
+def _holder(lock: Path) -> str:
+    try:
+        return lock.read_text(encoding="utf-8")
+    except OSError:
+        return ""
+
+
+@contextmanager
+def file_lock(
+    path: Path,
+    *,
+    busy: str = "team_busy",
+    retries: int = LOCK_RETRIES,
+    stale: float = STALE_AFTER,
+    deadline: float = DEADLINE,
+):
+    """O_CREAT|O_EXCL on <file>.lock; retries with random backoff, then TeamError(busy).
+
+    The count starts again whenever the lock changed hands (others are making progress, it is not stuck),
+    within an overall deadline; a lock held by one holder throughout fails after `retries`.
+    """
+    lock = path.with_name(path.name + ".lock")
+    lock.parent.mkdir(parents=True, exist_ok=True)
+    token = f"{os.getpid()} {now()} {secrets.token_hex(4)}"
+    attempt, seen, start = 0, None, time.monotonic()
+    while True:
+        try:
+            fd = os.open(lock, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        except (FileExistsError, PermissionError):  # Windows: PermissionError while it is being deleted.
+            if _stale(lock, stale):
+                try:
+                    os.remove(lock)
+                except OSError:
+                    pass
+            holder = _holder(lock)
+            if holder and seen is not None and holder != seen:
+                attempt = 0
+            seen = holder or seen
+            if attempt >= retries or time.monotonic() - start > deadline:
+                raise TeamError(
+                    busy, f"{path.name} 正被其他进程使用，重试 {retries} 次后仍拿不到锁；稍后再试。"
+                ) from None
+            attempt += 1
+            time.sleep(random.uniform(*BACKOFF))
+            continue
+        try:
+            os.write(fd, token.encode("utf-8"))
+        finally:
+            os.close(fd)
+        break
+    try:
+        yield
+    finally:
+        _release(lock)
+
+
+def _release(lock: Path) -> None:
+    """Windows refuses to delete a file another waiter has open for reading its holder: retry briefly,
+    or the lock would stay until it is stale."""
+    for _ in range(40):
+        try:
+            os.remove(lock)
+            return
+        except FileNotFoundError:
+            return
+        except PermissionError:
+            time.sleep(0.005)
+        except OSError:
+            return
+
+
+def atomic_write(path: Path, data: Any) -> None:
+    """A temporary file in the same directory, then os.replace (retried briefly on Windows)."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(f"{path.name}.{os.getpid()}.tmp")
+    temporary.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+    try:
+        for attempt in range(REPLACE_RETRIES + 1):
+            try:
+                os.replace(temporary, path)
+                return
+            except PermissionError:  # Windows: another process has it open for a moment.
+                if attempt == REPLACE_RETRIES:
+                    raise
+                time.sleep(0.02)
+    finally:
+        if temporary.exists():
+            try:
+                temporary.unlink()
+            except OSError:
+                pass
+
+
+def read_text(path: Path) -> str:
+    """Readers without the lock (/team, peek) can meet os.replace mid-way on Windows: retry briefly."""
+    for attempt in range(REPLACE_RETRIES + 1):
+        try:
+            return path.read_text(encoding="utf-8")
+        except PermissionError:
+            if attempt == REPLACE_RETRIES:
+                raise
+            time.sleep(0.02)
+
+
+def load_json(
+    path: Path, default: Callable[[], Any], valid: Callable[[Any], bool], on_notice: Callable[[str], None] | None = None
+) -> Any:
+    """Missing -> default; unreadable or the wrong shape -> kept as <file>.corrupt-<time>, then default."""
+    try:
+        text = read_text(path)
+    except FileNotFoundError:
+        return default()
+    try:
+        data = json.loads(text)
+        if valid(data):
+            return data
+    except ValueError:
+        pass
+    kept = path.with_name(f"{path.name}.corrupt-{datetime.now().strftime('%Y%m%d-%H%M%S')}")
+    try:
+        os.replace(path, kept)
+        note = f"{path} 已损坏，原文件保留为 {kept.name}，按空文件继续。"
+    except OSError as exc:
+        note = f"{path} 已损坏，且无法改名保留（{exc}），按空文件继续。"
+    if on_notice is not None:
+        on_notice(note)
+    return default()

mosscode/teams/mailbox.py

@@ -0,0 +1,172 @@
+"""One JSON file of messages per participant, changed only under its lock."""
+
+from __future__ import annotations
+
+import secrets
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .lock import TeamError, atomic_write, file_lock, load_json, now
+
+LEAD = "lead"
+BROADCAST = "*"
+TYPES = (
+    "text",
+    "plan_approval_request",
+    "plan_approval_response",
+    "shutdown_request",
+    "shutdown_response",
+    "idle_notification",
+    "permission_response",
+)
+# permission_response: the user's answer, given in the lead's window, to a pane member's approval.
+LEAD_ONLY = frozenset({"plan_approval_response", "shutdown_request", "permission_response"})
+MEMBER_ONLY = frozenset({"shutdown_response", "plan_approval_request", "idle_notification"})
+# Sent for the model, never by it.
+RUNTIME_ONLY = frozenset({"plan_approval_request", "idle_notification", "permission_response"})
+EXTRA_FIELDS = {
+    "plan_approval_request": ("request_id", "plan"),
+    "plan_approval_response": ("request_id", "approve", "feedback"),
+    "shutdown_request": ("reason",),
+    "shutdown_response": ("request_id", "approve", "reason"),
+    "idle_notification": ("reason", "completed_tasks"),  # Its summary is the message's own.
+    "permission_response": ("request_id", "choice"),
+}
+BODY_LIMIT = 20000
+SUMMARY_LIMIT = 80
+KEEP_READ = 100
+UNREAD_LIMIT = 500
+
+
+@dataclass
+class Message:
+    sender: str
+    type: str
+    body: str = ""
+    summary: str = ""
+    id: str = field(default_factory=lambda: f"m-{secrets.token_hex(4)}")
+    timestamp: str = field(default_factory=now)
+    read: bool = False
+    extra: dict = field(default_factory=dict)  # The type's own fields.
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "from": self.sender,
+            "type": self.type,
+            "body": self.body,
+            "summary": self.summary,
+            "timestamp": self.timestamp,
+            "read": self.read,
+            **self.extra,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Message:
+        known = {"id", "from", "type", "body", "summary", "timestamp", "read"}
+        return cls(
+            sender=str(data.get("from", "")),
+            type=str(data.get("type", "text")),
+            body=str(data.get("body", "")),
+            summary=str(data.get("summary", "")),
+            id=str(data.get("id", "")),
+            timestamp=str(data.get("timestamp", "")),
+            read=bool(data.get("read", False)),
+            extra={key: value for key, value in data.items() if key not in known},
+        )
+
+
+def check(message: Message) -> None:
+    """What any message must satisfy, whoever sends it; TeamError otherwise."""
+    if message.type not in TYPES:
+        raise TeamError("invalid_message", f"未知的消息类型 {message.type}；可用：{'、'.join(TYPES)}。")
+    if message.type in LEAD_ONLY and message.sender != LEAD:
+        raise TeamError("invalid_message", f"只有 Lead 能发送 {message.type}。")
+    if message.type in MEMBER_ONLY and message.sender == LEAD:
+        raise TeamError("invalid_message", f"Lead 不能发送 {message.type}。")
+    if message.type == "text":
+        if not message.summary.strip():
+            raise TeamError("invalid_message", "text 消息必须有 summary（一句话摘要）。")
+        if len(message.summary) > SUMMARY_LIMIT:
+            raise TeamError("invalid_message", f"summary 最多 {SUMMARY_LIMIT} 字。")
+    if len(message.body) > BODY_LIMIT:
+        raise TeamError("invalid_message", f"正文最多 {BODY_LIMIT} 字，当前 {len(message.body)} 字。")
+    missing = [name for name in EXTRA_FIELDS.get(message.type, ()) if name not in message.extra]
+    if missing:
+        raise TeamError("invalid_message", f"{message.type} 消息缺少字段：{'、'.join(missing)}。")
+
+
+def _valid(data) -> bool:
+    return isinstance(data, list) and all(isinstance(item, dict) for item in data)
+
+
+def _trim(messages: list[dict]) -> list[dict]:
+    """Every unread message and the latest KEEP_READ read ones, in order."""
+    read = [index for index, item in enumerate(messages) if item.get("read")]
+    dropped = set(read[:-KEEP_READ]) if len(read) > KEEP_READ else set()
+    return [item for index, item in enumerate(messages) if index not in dropped]
+
+
+class Mailbox:
+    """The mailbox directory of one team: mailbox/<name>.json for each participant, lead included."""
+
+    def __init__(self, directory: Path, on_notice: Callable[[str], None] | None = None):
+        self.directory = directory
+        self.on_notice = on_notice
+
+    def path(self, name: str) -> Path:
+        return self.directory / f"{name}.json"
+
+    def _load(self, name: str) -> list[dict]:
+        return load_json(self.path(name), list, _valid, self.on_notice)
+
+    def send(self, to: str, message: Message) -> None:
+        """Append under the recipient's lock; TeamError when busy or full, never a silent drop."""
+        check(message)
+        path = self.path(to)
+        with file_lock(path, busy="mailbox_busy"):
+            messages = self._load(to)
+            if sum(1 for item in messages if not item.get("read")) >= UNREAD_LIMIT:
+                raise TeamError("mailbox_full", f"{to} 的未读消息已达 {UNREAD_LIMIT} 条，暂不能再发送。")
+            messages.append(message.to_dict())
+            atomic_write(path, _trim(messages))
+
+    def read_unread(self, name: str) -> list[Message]:
+        """The unread messages, marked read in the same locked step."""
+        path = self.path(name)
+        with file_lock(path, busy="mailbox_busy"):
+            messages = self._load(name)
+            unread = [item for item in messages if not item.get("read")]
+            if not unread:
+                return []
+            for item in unread:
+                item["read"] = True
+            atomic_write(path, _trim(messages))
+        return [Message.from_dict(item) for item in unread]
+
+    def take(self, name: str, kinds: frozenset[str] | set[str]) -> list[Message]:
+        """The unread messages of these types only, marked read; the rest stay unread (answers mid-turn)."""
+        path = self.path(name)
+        if not path.exists():
+            return []
+        with file_lock(path, busy="mailbox_busy"):
+            messages = self._load(name)
+            taken = [item for item in messages if not item.get("read") and item.get("type") in kinds]
+            if not taken:
+                return []
+            for item in taken:
+                item["read"] = True
+            atomic_write(path, _trim(messages))
+        return [Message.from_dict(item) for item in taken]
+
+    def discard_unread(self, name: str, kinds: frozenset[str] | set[str]) -> int:
+        """Mark stale unread messages of these types read (an old shutdown request or answer)."""
+        return len(self.take(name, kinds))
+
+    def peek(self, name: str) -> list[Message]:
+        """Every kept message, read or not; for /team. No lock: a reader sees the old file or the new one."""
+        return [Message.from_dict(item) for item in self._load(name)]
+
+    def unread_count(self, name: str) -> int:
+        return sum(1 for message in self.peek(name) if not message.read)