mosscode 0.1.0__py3-none-any.whl

mosscode/teams/__init__.py

@@ -0,0 +1,216 @@
+"""Long-lived agent teams of one project, stored under ~/.mosscode/projects/<key>/teams/<team>/."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Callable
+from dataclasses import asdict, dataclass, field, fields
+from pathlib import Path
+from typing import Literal
+
+from ..paths import project_dir
+from ..worktree.meta import process_alive
+from ..worktree.names import RESERVED
+from .board import TaskBoard
+from .lock import TeamError, atomic_write, file_lock, now, read_text
+from .mailbox import BROADCAST, LEAD, Mailbox
+
+__all__ = [
+    "BROADCAST",
+    "LEAD",
+    "Member",
+    "Team",
+    "TeamError",
+    "TeamStore",
+    "list_teams",
+    "teams_root",
+    "validate_member_name",
+    "validate_team_name",
+]
+
+NAME = re.compile(r"[a-z0-9][a-z0-9-]{0,31}")
+VERSION = 1
+
+
+def _validate(name: str, what: str) -> str | None:
+    """None when usable, otherwise the reason."""
+    if not NAME.fullmatch(name or ""):
+        return f"{what}只能含小写字母、数字和 -，1–32 个字符，以字母或数字开头"
+    if name in RESERVED:
+        return f"{name} 是 Windows 保留的设备名"
+    return None
+
+
+def validate_team_name(name: str) -> str | None:
+    return _validate(name, "团队名")
+
+
+def validate_member_name(name: str) -> str | None:
+    if name in {LEAD, BROADCAST}:
+        return f"成员名不能是 {name}"
+    return _validate(name, "成员名")
+
+
+def teams_root(project: Path, home: Path | None = None) -> Path:
+    """Next to the project's sessions, so the same key finds both."""
+    return project_dir(project, home) / "teams"
+
+
+@dataclass
+class Member:
+    name: str
+    agent_type: str
+    backend: Literal["in-process", "windows-terminal", "tmux"] = "in-process"
+    backend_reason: str = ""
+    status: Literal["running", "idle", "stopped"] = "stopped"
+    require_plan_approval: bool = False
+    approved: bool = False  # Its plan was approved; a revived member keeps it.
+    mode: str = "default"  # Written by the lead, read by a pane member each turn.
+    model: str = ""
+    worktree: dict | None = None  # {"name", "path", "branch"}; None works in the project directory.
+    pid: int | None = None
+    heartbeat: str | None = None
+    pane: str | None = None  # tmux pane id.
+    transcript: str = ""  # Relative to the team directory.
+    prompt: str = ""
+    usage: dict = field(default_factory=dict)
+    created: str = field(default_factory=now)
+    error: str = ""  # Written by a pane member that could not start.
+    last_tool: str = ""  # Written by a pane member while it runs.
+    window: str = ""  # The Windows Terminal team window its tab is in.
+    approvals: list = field(default_factory=list)  # A pane member's requests waiting for an answer.
+
+    def agent_id(self, team: str) -> str:
+        return f"{self.name}@{team}"
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Member:
+        known = {item.name for item in fields(cls)}
+        return cls(**{key: value for key, value in data.items() if key in known})
+
+
+@dataclass
+class Team:
+    name: str
+    description: str = ""
+    created: str = field(default_factory=now)
+    lead: dict | None = None  # {"pid", "session", "since"} of the process holding it.
+    members: list[Member] = field(default_factory=list)
+    project: str = ""  # The main project directory; a pane member loads its rules and agents there.
+
+    def member(self, name: str) -> Member | None:
+        return next((member for member in self.members if member.name == name), None)
+
+    def names(self) -> tuple[str, ...]:
+        return tuple(member.name for member in self.members)
+
+    def to_dict(self) -> dict:
+        data = asdict(self)
+        data["v"] = VERSION
+        for item, member in zip(data["members"], self.members):
+            item["agent_id"] = member.agent_id(self.name)
+        return data
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Team:
+        members = [Member.from_dict(item) for item in data.get("members", []) if isinstance(item, dict)]
+        return cls(
+            name=str(data["name"]),
+            description=str(data.get("description", "")),
+            created=str(data.get("created", "")),
+            lead=data.get("lead") or None,
+            members=members,
+            project=str(data.get("project", "")),
+        )
+
+
+def _valid(data) -> bool:
+    return isinstance(data, dict) and isinstance(data.get("name"), str) and isinstance(data.get("members", []), list)
+
+
+class TeamStore:
+    """One team directory: config.json, tasks.json, mailbox/, transcripts/."""
+
+    def __init__(self, directory: Path, on_notice: Callable[[str], None] | None = None):
+        self.directory = directory
+        self.name = directory.name
+        self.on_notice = on_notice
+        self.config = directory / "config.json"
+        self.mailbox = Mailbox(directory / "mailbox", on_notice)
+        self.board = TaskBoard(directory / "tasks.json", on_notice)
+        self.transcripts = directory / "transcripts"
+
+    @classmethod
+    def at(cls, root: Path, name: str, on_notice: Callable[[str], None] | None = None) -> TeamStore:
+        problem = validate_team_name(name)
+        if problem:
+            raise TeamError("invalid_name", f"团队名 {name} 不可用：{problem}。")
+        return cls(root / name, on_notice)
+
+    def exists(self) -> bool:
+        return self.config.exists()
+
+    def create(self, description: str = "") -> Team:
+        """A new team; team_exists when the directory already has one (the caller opens it instead)."""
+        with file_lock(self.config):
+            if self.config.exists():
+                raise TeamError("team_exists", f"团队 {self.name} 已存在。")
+            team = Team(self.name, description.strip())
+            self.transcripts.mkdir(parents=True, exist_ok=True)
+            self.mailbox.directory.mkdir(parents=True, exist_ok=True)
+            atomic_write(self.config, team.to_dict())
+        return team
+
+    def _read(self) -> Team:
+        """Unlike a mailbox, a broken config is left where it is, not replaced: the roster would be lost."""
+        try:
+            data = json.loads(read_text(self.config))
+        except FileNotFoundError:
+            raise TeamError("no_team", f"团队 {self.name} 不存在。") from None
+        except (OSError, ValueError) as exc:
+            raise TeamError("team_corrupt", f"团队 {self.name} 的记录无法读取（{self.config}：{exc}）。") from None
+        if not _valid(data):
+            raise TeamError("team_corrupt", f"团队 {self.name} 的记录格式不对（{self.config}）。")
+        return Team.from_dict(data)
+
+    def load(self) -> Team:
+        return self._read()
+
+    def modify(self, change: Callable[[Team], object]) -> Team:
+        """Re-read, change, write, all under the lock; another process's writes are never lost."""
+        with file_lock(self.config):
+            team = self._read()
+            change(team)
+            atomic_write(self.config, team.to_dict())
+        return team
+
+    def acquire(self, pid: int, session: str = "", project: str = "") -> Team:
+        """The lead process takes the team; team_held while another live process has it."""
+
+        def take(team: Team) -> None:
+            holder = team.lead or {}
+            other = int(holder.get("pid") or 0)
+            if other and other != pid and process_alive(other):
+                raise TeamError(
+                    "team_held", f"团队 {team.name} 正由另一个 MossCode 进程（PID {other}）作为 Lead 使用。"
+                )
+            team.lead = {"pid": pid, "session": session, "since": now()}
+            if project:
+                team.project = project
+
+        return self.modify(take)
+
+    def release(self, pid: int) -> Team:
+        def drop(team: Team) -> None:
+            if team.lead and int(team.lead.get("pid") or 0) == pid:
+                team.lead = None
+
+        return self.modify(drop)
+
+
+def list_teams(root: Path) -> list[TeamStore]:
+    """Every directory with a config.json, by name."""
+    if not root.is_dir():
+        return []
+    return [TeamStore(path) for path in sorted(root.iterdir()) if (path / "config.json").is_file()]

mosscode/teams/backends.py

@@ -0,0 +1,259 @@
+"""Where a member runs — in the lead's process, or in a terminal pane of its own.
+
+A pane member is another MossCode process (`--team-dir/--team-member`). The lead starts it, waits for
+it to write its pid into the team record, and later reads its status and heartbeat from there.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import shlex
+import shutil
+import signal
+import subprocess
+import sys
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from ..worktree.meta import process_alive
+from .lock import TeamError
+
+IN_PROCESS, WINDOWS_TERMINAL, TMUX = "in-process", "windows-terminal", "tmux"
+# A pane member is a tab of its team's window, or a tmux window of its own.
+LABELS = {IN_PROCESS: "进程内", WINDOWS_TERMINAL: "Windows Terminal 标签页", TMUX: "tmux 窗口"}
+IN_PROCESS_REASON = "进程内运行，与 Lead 共用这个窗口"
+START_TIMEOUT = 20.0  # Seconds for a pane member to write its pid.
+HEARTBEAT = 5.0  # Seconds between a pane member's heartbeats.
+FRESH = 15.0  # A heartbeat at most this old means the member is still at work.
+LAUNCH_TIMEOUT = 15.0  # Seconds for wt/tmux itself to return.
+
+Run = Callable[..., subprocess.CompletedProcess]
+
+
+@dataclass(frozen=True)
+class Choice:
+    backend: str
+    reason: str
+
+
+def _tmux_missing(env: Mapping[str, str], which) -> str:
+    if not env.get("TMUX"):
+        return "MossCode 不在 tmux 会话中（环境变量 TMUX 为空）"
+    if not which("tmux"):
+        return "找不到 tmux 命令"
+    return ""
+
+
+def _wt_missing(env: Mapping[str, str], which) -> str:
+    if not env.get("WT_SESSION"):
+        return "MossCode 不在 Windows Terminal 中运行（环境变量 WT_SESSION 为空）"
+    if not which("wt"):
+        return "找不到 wt.exe"
+    return ""
+
+
+def _but(missing: str) -> str:
+    return ("但 " if missing[:1].isascii() else "但") + missing  # 但 MossCode…, 但找不到…
+
+
+def detect_backend(mode: str, env: Mapping[str, str] | None = None, which=shutil.which) -> Choice:
+    """Auto picks tmux, then Windows Terminal, then in-process; an explicit pane backend that
+    cannot run is an error, never a quiet fallback."""
+    env = os.environ if env is None else env
+    if mode == IN_PROCESS:
+        return Choice(IN_PROCESS, "teammate_mode: in-process；" + IN_PROCESS_REASON)
+    if mode == TMUX:
+        missing = _tmux_missing(env, which)
+        if missing:
+            raise TeamError(
+                "backend_unavailable",
+                f"teammate_mode 是 tmux，{_but(missing)}；没有改用其他后端。"
+                "在 tmux 中启动 MossCode，或把 teammate_mode 改为 auto / in-process。",
+            )
+        return Choice(TMUX, "teammate_mode: tmux")
+    if mode == WINDOWS_TERMINAL:
+        missing = _wt_missing(env, which)
+        if missing:
+            raise TeamError(
+                "backend_unavailable",
+                f"teammate_mode 是 windows-terminal，{_but(missing)}；没有改用其他后端。"
+                "在 Windows Terminal 中启动 MossCode，或把 teammate_mode 改为 auto / in-process。",
+            )
+        return Choice(WINDOWS_TERMINAL, "teammate_mode: windows-terminal")
+    if not _tmux_missing(env, which):
+        return Choice(TMUX, "auto：检测到 tmux")
+    if not _wt_missing(env, which):
+        return Choice(WINDOWS_TERMINAL, "auto：检测到 Windows Terminal")
+    return Choice(IN_PROCESS, "auto：不在 tmux 或 Windows Terminal 中；" + IN_PROCESS_REASON)
+
+
+def member_arguments(
+    team_dir: Path, name: str, config: str | Path | None = None, provider: str | None = None
+) -> list[str]:
+    """What follows `python -m mosscode`; the configuration by path, never a key."""
+    arguments = ["--team-dir", str(team_dir), "--team-member", name]
+    if config:
+        arguments += ["--config", str(Path(config).resolve())]
+    if provider:
+        arguments += ["--provider", provider]
+    return arguments
+
+
+def team_window(team_dir: Path) -> str:
+    """One Windows Terminal window per team; the digest keeps same-named teams of other projects apart."""
+    digest = hashlib.sha1(os.path.normcase(str(Path(team_dir).resolve())).encode("utf-8")).hexdigest()[:6]
+    return f"mosscode-{Path(team_dir).name}-{digest}"
+
+
+def heartbeat_age(stamp: str | None) -> float | None:
+    if not stamp:
+        return None
+    try:
+        return (datetime.now().astimezone() - datetime.fromisoformat(stamp)).total_seconds()
+    except (TypeError, ValueError):
+        return None
+
+
+def member_alive(pid: int | None, heartbeat: str | None, fresh: float = FRESH) -> bool:
+    """Its process runs and it reported recently."""
+    age = heartbeat_age(heartbeat)
+    return bool(pid) and process_alive(int(pid)) and age is not None and age <= fresh
+
+
+def kill_tree(pid: int, run: Run = subprocess.run) -> None:
+    """The member and whatever it started."""
+    if not pid or pid == os.getpid():
+        return
+    if os.name == "nt":
+        run(["taskkill", "/PID", str(pid), "/T", "/F"], capture_output=True, timeout=LAUNCH_TIMEOUT)
+        return
+    try:
+        group = os.getpgid(pid)
+    except OSError:
+        return
+    try:
+        if group != os.getpgid(0):
+            os.killpg(group, signal.SIGKILL)
+        else:
+            os.kill(pid, signal.SIGKILL)
+    except OSError:
+        pass
+
+
+class PaneBackend:
+    name = ""
+
+    def __init__(self, run: Run = subprocess.run, which=shutil.which, python: str | None = None):
+        self.run, self.which = run, which
+        self.python = python or sys.executable
+
+    def command(
+        self, cwd: Path, arguments: list[str], *, member: str = "", team: str = "", window: str = ""
+    ) -> list[str]:
+        raise NotImplementedError
+
+    def launch(
+        self, cwd: Path, arguments: list[str], *, member: str = "", team: str = "", window: str = ""
+    ) -> str | None:
+        """Start the member's pane; the pane id when the terminal reports one."""
+        command = self.command(cwd, arguments, member=member, team=team, window=window)
+        try:
+            done = self.run(command, capture_output=True, text=True, timeout=LAUNCH_TIMEOUT)
+        except (OSError, subprocess.SubprocessError) as exc:
+            raise TeamError("backend_failed", f"无法启动{LABELS[self.name]}：{exc}") from None
+        if done.returncode != 0:
+            output = ((done.stderr or "") + (done.stdout or "")).strip()
+            raise TeamError(
+                "backend_failed",
+                f"{LABELS[self.name]}启动失败（退出码 {done.returncode}）" + (f"：{output}" if output else "。"),
+            )
+        return self.pane(done.stdout or "")
+
+    def pane(self, output: str) -> str | None:
+        return None
+
+    def kill(self, pid: int | None, pane: str | None) -> None:
+        if pid:
+            try:
+                kill_tree(int(pid), self.run)
+            except (OSError, subprocess.SubprocessError):
+                pass
+
+
+class WindowsTerminalBackend(PaneBackend):
+    """A tab of the team's own window (`-w <name>` makes it the first time), so
+    the lead's window is never split. The tab runs mosscode.teams.pane, which always exits 0, so it
+    closes after a normal exit and after taskkill alike; the window closes with its last tab."""
+
+    name = WINDOWS_TERMINAL
+
+    def command(
+        self, cwd: Path, arguments: list[str], *, member: str = "", team: str = "", window: str = ""
+    ) -> list[str]:
+        wt = self.which("wt") or "wt"
+        title = ["--title", f"{member} · {team}", "--suppressApplicationTitle"] if member else []
+        rest = [
+            "-w",
+            window or "0",
+            "new-tab",
+            *title,
+            "-d",
+            str(cwd),
+            "--",
+            self.python,
+            "-m",
+            "mosscode.teams.pane",
+            *arguments,
+        ]
+        return [wt, *(escape_wt(item) for item in rest)]
+
+
+def escape_wt(argument: str) -> str:
+    """wt splits its command line at every `;` (a new subcommand); `\\;` is a literal one."""
+    return argument.replace(";", "\\;")
+
+
+class TmuxBackend(PaneBackend):
+    """A window of its own in the current tmux session, not switched to; kill-pane closes it."""
+
+    name = TMUX
+
+    def command(
+        self, cwd: Path, arguments: list[str], *, member: str = "", team: str = "", window: str = ""
+    ) -> list[str]:
+        tmux = self.which("tmux") or "tmux"
+        named = ["-n", member] if member else []
+        return [
+            tmux,
+            "new-window",
+            "-d",
+            *named,
+            "-P",
+            "-F",
+            "#{pane_id} #{pane_pid}",
+            "-c",
+            str(cwd),
+            shlex.join([self.python, "-m", "mosscode", *arguments]),
+        ]
+
+    def pane(self, output: str) -> str | None:
+        parts = output.strip().split()
+        return parts[0] if parts else None
+
+    def kill(self, pid: int | None, pane: str | None) -> None:
+        super().kill(pid, pane)
+        if pane:
+            try:
+                self.run(
+                    [self.which("tmux") or "tmux", "kill-pane", "-t", pane], capture_output=True, timeout=LAUNCH_TIMEOUT
+                )
+            except (OSError, subprocess.SubprocessError):
+                pass
+
+
+def pane_backend(name: str, run: Run = subprocess.run, which=shutil.which, python: str | None = None) -> PaneBackend:
+    backend = {WINDOWS_TERMINAL: WindowsTerminalBackend, TMUX: TmuxBackend}[name]
+    return backend(run, which, python)