@team-agent/installer 0.1.11 → 0.2.0

package/src/team_agent/leader/__init__.py

@@ -0,0 +1,320 @@
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import signal
+import shlex
+import subprocess
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from team_agent.events import EventLog
+from team_agent.state import load_runtime_state, save_runtime_state
+
+
+def attach_leader(workspace: Path, pane: str | None = None, provider: str = "codex") -> dict[str, Any]:
+    from team_agent.message_store import MessageStore
+    from team_agent.runtime import _attach_leader_to_state, ensure_workspace_dirs
+    ensure_workspace_dirs(workspace)
+    state = load_runtime_state(workspace)
+    event_log = EventLog(workspace)
+    receiver, validation = _attach_leader_to_state(
+        workspace,
+        state,
+        pane=pane,
+        provider=provider,
+        event_log=event_log,
+        source="manual",
+    )
+    save_runtime_state(workspace, state)
+    requeued = MessageStore(workspace).requeue_delivery_exhausted_watchers()
+    if requeued:
+        event_log.write(
+            "leader_receiver.requeued_exhausted_watchers",
+            watcher_ids=requeued,
+            count=len(requeued),
+            trigger="attach_leader",
+        )
+        for watcher_id in requeued:
+            event_log.write(
+                "result_watcher.requeued",
+                watcher_id=watcher_id,
+                trigger="attach_leader",
+                new_pane_id=receiver.get("pane_id"),
+            )
+    return {
+        "ok": True,
+        "leader_receiver": receiver,
+        "validation": validation,
+        "requeued_exhausted_watchers": requeued,
+    }
+
+
+def start_leader(
+    provider: str,
+    provider_args: list[str],
+    workspace: Path,
+    *,
+    attach_existing: bool = False,
+    confirm_attach: bool = False,
+    attach_session: str | None = None,
+) -> None:
+    plan = leader_start_plan(
+        provider,
+        provider_args,
+        workspace,
+        attach_existing=attach_existing,
+        confirm_attach=confirm_attach,
+        attach_session=attach_session,
+    )
+    if plan["mode"] == "new_tmux_session" and not sys.stdin.isatty():
+        plan = dict(plan)
+        argv = list(plan["argv"])
+        argv.insert(2, "-d")
+        plan["argv"] = argv
+        plan["detached"] = True
+    EventLog(workspace).write(
+        "leader.start",
+        provider=provider,
+        workspace=str(workspace),
+        mode=plan["mode"],
+        session_name=plan.get("session_name"),
+        argv=plan["argv"],
+    )
+    _run_leader_plan(plan, workspace)
+
+
+def leader_start_plan(
+    provider: str,
+    provider_args: list[str],
+    workspace: Path,
+    *,
+    attach_existing: bool = False,
+    confirm_attach: bool = False,
+    attach_session: str | None = None,
+) -> dict[str, Any]:
+    from team_agent.runtime import (
+        RuntimeError,
+        _tmux_session_exists,
+        ensure_workspace_dirs,
+        get_adapter,
+        shutil_which,
+    )
+    workspace = workspace.resolve()
+    ensure_workspace_dirs(workspace)
+    adapter = get_adapter(provider)
+    if not adapter.is_installed():
+        raise RuntimeError(f"Provider {provider} command {adapter.command_name!r} not found")
+    argv = [adapter.command_name, *provider_args]
+    if attach_session:
+        if not confirm_attach:
+            raise RuntimeError("--attach-session requires --confirm")
+        return {
+            "mode": "attach_existing",
+            "provider": provider,
+            "workspace": str(workspace),
+            "session_name": attach_session,
+            "argv": ["tmux", "attach-session", "-t", attach_session],
+        }
+    if os.environ.get("TMUX"):
+        return {"mode": "exec_provider", "provider": provider, "workspace": str(workspace), "argv": argv}
+    if not shutil_which("tmux"):
+        raise RuntimeError("tmux is not installed; install tmux 3.3+ or start the leader from an existing tmux pane")
+    session_name = leader_session_name(provider, workspace)
+    if _tmux_session_exists(session_name):
+        return {
+            "mode": "attach_existing",
+            "provider": provider,
+            "workspace": str(workspace),
+            "session_name": session_name,
+            "argv": ["tmux", "attach-session", "-t", session_name],
+        }
+    exports = ""
+    if os.environ.get("PATH"):
+        exports = f"PATH={shlex.quote(os.environ['PATH'])} "
+    shell = f"cd {shlex.quote(str(workspace))} && {exports}exec {shlex.join(argv)}"
+    tmux_args = ["tmux", "new-session", "-s", session_name, "-n", provider, "-c", str(workspace)]
+    return {
+        "mode": "new_tmux_session",
+        "provider": provider,
+        "workspace": str(workspace),
+        "session_name": session_name,
+        "argv": [*tmux_args, "sh", "-lc", shell],
+        "detached": False,
+    }
+
+
+def _run_leader_plan(plan: dict[str, Any], workspace: Path) -> None:
+    session_name = plan.get("session_name")
+    proc: subprocess.Popen[Any] | None = None
+    sigints = 0
+
+    def stop_process_tree() -> None:
+        if session_name and plan["mode"] == "new_tmux_session":
+            subprocess.run(["tmux", "kill-session", "-t", str(session_name)], check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        if proc and proc.poll() is None:
+            proc.terminate()
+
+    def handle_sigint(signum: int, _frame: Any) -> None:
+        nonlocal sigints
+        sigints += 1
+        if proc and proc.poll() is None:
+            try:
+                proc.send_signal(signum)
+            except ProcessLookupError:
+                pass
+        if sigints >= 2:
+            stop_process_tree()
+
+    old_sigint = signal.signal(signal.SIGINT, handle_sigint)
+    try:
+        if plan["mode"] == "exec_provider":
+            os.chdir(workspace)
+        proc = subprocess.Popen(plan["argv"])
+        if plan.get("detached") and session_name:
+            proc.wait()
+            while _tmux_session_exists_local(str(session_name)):
+                time.sleep(0.2)
+        else:
+            proc.wait()
+    finally:
+        signal.signal(signal.SIGINT, old_sigint)
+        _print_team_running_reminder(workspace)
+    raise SystemExit(proc.returncode if proc else 1)
+
+
+def _tmux_session_exists_local(session_name: str) -> bool:
+    proc = subprocess.run(["tmux", "has-session", "-t", session_name], check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    return proc.returncode == 0
+
+
+def _print_team_running_reminder(workspace: Path) -> None:
+    state = load_runtime_state(workspace)
+    team_name = state.get("session_name")
+    if not team_name or not _tmux_session_exists_local(str(team_name)):
+        return
+    print(f"team {team_name} is still running; run team-agent shutdown to close it OR team-agent attach-leader to reconnect.")
+
+
+def leader_session_name(provider: str, workspace: Path) -> str:
+    digest = hashlib.sha1(str(workspace.resolve()).encode("utf-8")).hexdigest()[:8]
+    folder = re.sub(r"[^A-Za-z0-9_.-]", "_", workspace.name)[:48].strip("._-") or "workspace"
+    return f"team-agent-leader-{provider}-{folder}-{digest}"
+
+
+def attach_leader_to_state(
+    workspace: Path,
+    state: dict[str, Any],
+    pane: str | None,
+    provider: str,
+    event_log: EventLog,
+    source: str,
+    require_current: bool = False,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    from team_agent.runtime import (
+        RuntimeError,
+        _leader_command_provider,
+        _resolve_leader_pane,
+        _target_fingerprint,
+        _validate_leader_receiver,
+        get_adapter,
+    )
+    get_adapter(provider)
+    pane_info, discovery = _resolve_leader_pane(pane, provider, workspace=workspace, require_current=require_current)
+    inferred_provider = _leader_command_provider(pane_info.get("pane_current_command", ""))
+    receiver_provider = inferred_provider or provider
+    receiver = {
+        "mode": "direct_tmux",
+        "status": "attached",
+        "provider": receiver_provider,
+        "pane_id": pane_info["pane_id"],
+        "session_name": pane_info["session_name"],
+        "window_index": pane_info["window_index"],
+        "window_name": pane_info["window_name"],
+        "pane_index": pane_info["pane_index"],
+        "pane_tty": pane_info["pane_tty"],
+        "pane_current_command": pane_info["pane_current_command"],
+        "fingerprint": _target_fingerprint(pane_info),
+        "attached_at": datetime.now(timezone.utc).isoformat(),
+        "discovery": discovery,
+    }
+    if receiver_provider != provider:
+        receiver["requested_provider"] = provider
+    validation = _validate_leader_receiver(receiver)
+    if not validation["ok"]:
+        event_log.write(
+            "leader_receiver.attach_failed",
+            target=pane or pane_info.get("pane_id"),
+            discovery=discovery,
+            provider=provider,
+            reason=validation["reason"],
+            error=validation.get("error"),
+            source=source,
+        )
+        raise RuntimeError(f"leader pane validation failed: {validation['reason']}")
+    if validation.get("warning"):
+        receiver["warning"] = validation["warning"]
+    state["leader_receiver"] = receiver
+    event_log.write(
+        "leader_receiver.attached",
+        target=receiver["pane_id"],
+        session_name=receiver["session_name"],
+        window_index=receiver["window_index"],
+        window_name=receiver["window_name"],
+        pane_index=receiver["pane_index"],
+        pane_tty=receiver["pane_tty"],
+        pane_current_command=receiver["pane_current_command"],
+        provider=receiver_provider,
+        requested_provider=provider if receiver_provider != provider else None,
+        discovery=discovery,
+        source=source,
+    )
+    return receiver, validation
+
+
+def autobind_leader_receiver_from_env(
+    workspace: Path,
+    provider: str,
+    source: str,
+) -> dict[str, Any] | None:
+    tmux_pane = os.environ.get("TMUX_PANE")
+    if not tmux_pane:
+        return None
+    from team_agent.runtime import ensure_workspace_dirs
+    ensure_workspace_dirs(workspace)
+    state = load_runtime_state(workspace)
+    event_log = EventLog(workspace)
+    try:
+        receiver, _validation = attach_leader_to_state(
+            workspace,
+            state,
+            pane=tmux_pane,
+            provider=provider,
+            event_log=event_log,
+            source=source,
+        )
+    except Exception as exc:
+        event_log.write(
+            "leader_receiver.autobind_skipped",
+            pane=tmux_pane,
+            provider=provider,
+            source=source,
+            error=str(exc),
+        )
+        return None
+    save_runtime_state(workspace, state)
+    return receiver
+
+
+__all__ = [
+    "attach_leader",
+    "attach_leader_to_state",
+    "autobind_leader_receiver_from_env",
+    "leader_session_name",
+    "leader_start_plan",
+    "start_leader",
+]

package/src/team_agent/lifecycle/__init__.py

@@ -0,0 +1,5 @@
+"""Lifecycle/state/spec lane package.
+
+Future Team and Agent lifecycle orchestration moves here behind runtime.py
+facade wiring.
+"""

package/src/team_agent/lifecycle/agents.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+import copy
+from pathlib import Path
+from typing import Any
+
+from team_agent.errors import RuntimeError
+from team_agent.events import EventLog
+from team_agent.message_store import MessageStore
+from team_agent.spec import load_spec, validate_spec
+from team_agent.state import (
+    check_team_owner,
+    load_runtime_state,
+    resolve_team_scoped_state,
+    save_runtime_state,
+    save_team_scoped_state,
+    write_spec,
+    write_team_state,
+)
+
+
+def remove_agent(
+    workspace: Path,
+    agent_id: str,
+    *,
+    from_spec: bool = False,
+    confirm: bool = False,
+    force: bool = False,
+    team: str | None = None,
+) -> dict[str, Any]:
+    import team_agent.runtime as runtime
+
+    workspace = workspace.resolve()
+    state, refusal = resolve_team_scoped_state(workspace, team)
+    if refusal:
+        return refusal
+    gate = check_team_owner(state)
+    if gate:
+        return gate
+    spec_path = Path(state.get("spec_path", workspace / "team.spec.yaml"))
+    spec = load_spec(spec_path)
+    agent = _find_worker(spec, agent_id)
+    if not agent:
+        raise RuntimeError(f"unknown worker agent id: {agent_id}")
+
+    event_log = EventLog(workspace)
+    store = MessageStore(workspace)
+    agent_state = state.get("agents", {}).get(agent_id) or {}
+    dynamic_role_file = _dynamic_role_file(workspace, agent_id, agent_state)
+    dynamic_agent = bool(agent_state.get("dynamic_role_file") or agent.get("forked_from"))
+    running = _is_running(runtime, state, agent_id, agent_state)
+
+    if not dynamic_agent and not (from_spec and confirm):
+        return {"ok": False, "agent_id": agent_id, "status": "refused", "reason": "from_spec_confirm_required"}
+    if running and not force:
+        return {"ok": False, "agent_id": agent_id, "status": "refused", "reason": "force_required"}
+
+    rollback = _RemoveRollback(workspace, spec_path, spec, state, dynamic_role_file, store, agent_id, False)
+    stopped: dict[str, Any] | None = None
+    try:
+        if running and force:
+            stopped = runtime.stop_agent(workspace, agent_id, team=team)
+            rollback.restore_running = True
+            state, _refusal_after = resolve_team_scoped_state(workspace, team)
+        removed_state = copy.deepcopy(state)
+        removed_state.get("agents", {}).pop(agent_id, None)
+        save_team_scoped_state(workspace, removed_state)
+
+        removed_spec = copy.deepcopy(spec)
+        removed_spec["agents"] = [item for item in removed_spec.get("agents", []) if item.get("id") != agent_id]
+        startup_order = removed_spec.get("runtime", {}).get("startup_order")
+        if isinstance(startup_order, list):
+            removed_spec["runtime"]["startup_order"] = [item for item in startup_order if item != agent_id]
+        validate_spec(removed_spec, base_dir=spec_path.parent)
+        team_state_path = write_team_state(workspace, removed_spec, removed_state)
+        write_spec(spec_path, removed_spec)
+
+        role_file_removed = _remove_dynamic_role_file(dynamic_role_file, bool(agent_state.get("dynamic_role_file")))
+        _delete_agent_health(store, agent_id)
+    except Exception as exc:
+        rollback_result = rollback.restore(runtime, event_log)
+        event_log.write("remove_agent.rollback", agent_id=agent_id, ok=rollback_result["ok"], error=str(exc), rollback=rollback_result)
+        raise RuntimeError(f"remove-agent failed for {agent_id}: {exc}; rollback_ok={rollback_result['ok']}") from exc
+
+    runtime._save_team_runtime_snapshot(workspace, removed_state)
+    warning = None
+    try:
+        # Storage commit is authoritative; final success event logging is best-effort.
+        event_log.write(
+            "remove_agent.complete",
+            agent_id=agent_id,
+            from_spec=from_spec,
+            force=force,
+            stopped=stopped,
+            role_file_removed=role_file_removed,
+        )
+    except Exception as exc:
+        warning = f"remove-agent completed but success event logging failed: {exc}"
+    return {
+        "ok": True,
+        "agent_id": agent_id,
+        "status": "removed",
+        "from_spec": from_spec,
+        "force": force,
+        "stopped": stopped,
+        "state_file": str(team_state_path),
+        "role_file_removed": role_file_removed,
+        **({"warning": warning} if warning else {}),
+    }
+
+
+class _RemoveRollback:
+    def __init__(
+        self,
+        workspace: Path,
+        spec_path: Path,
+        spec: dict[str, Any],
+        state: dict[str, Any],
+        dynamic_role_file: Path,
+        store: MessageStore,
+        agent_id: str,
+        restore_running: bool,
+    ) -> None:
+        self.workspace = workspace
+        self.spec_path = spec_path
+        self.spec_text = spec_path.read_text(encoding="utf-8")
+        self.spec = copy.deepcopy(spec)
+        self.state = copy.deepcopy(state)
+        self.team_state_path = workspace / spec.get("context", {}).get("state_file", "team_state.md")
+        self.team_state_text = self.team_state_path.read_text(encoding="utf-8") if self.team_state_path.exists() else None
+        self.dynamic_role_file = dynamic_role_file
+        self.dynamic_role_bytes = dynamic_role_file.read_bytes() if dynamic_role_file.exists() else None
+        self.health = copy.deepcopy(store.agent_health().get(agent_id))
+        self.agent_id = agent_id
+        self.restore_running = restore_running
+
+    def restore(self, runtime: Any, event_log: EventLog) -> dict[str, Any]:
+        errors: list[str] = []
+        try:
+            self.spec_path.write_text(self.spec_text, encoding="utf-8")
+        except Exception as exc:
+            errors.append(f"spec:{exc}")
+        try:
+            save_team_scoped_state(self.workspace, self.state)
+        except Exception as exc:
+            errors.append(f"workspace_state:{exc}")
+        try:
+            if self.team_state_text is None:
+                self.team_state_path.unlink(missing_ok=True)
+            else:
+                self.team_state_path.parent.mkdir(parents=True, exist_ok=True)
+                self.team_state_path.write_text(self.team_state_text, encoding="utf-8")
+        except Exception as exc:
+            errors.append(f"team_state:{exc}")
+        try:
+            if self.dynamic_role_bytes is None:
+                self.dynamic_role_file.unlink(missing_ok=True)
+            else:
+                self.dynamic_role_file.parent.mkdir(parents=True, exist_ok=True)
+                self.dynamic_role_file.write_bytes(self.dynamic_role_bytes)
+        except Exception as exc:
+            errors.append(f"role_file:{exc}")
+        try:
+            _restore_agent_health(MessageStore(self.workspace), self.agent_id, self.health)
+        except Exception as exc:
+            errors.append(f"agent_health:{exc}")
+        if self.restore_running and not errors:
+            try:
+                runtime.start_agent(self.workspace, self.agent_id, force=True, allow_fresh=True)
+            except Exception as exc:
+                errors.append(f"worker_restore:{exc}")
+        result = {"ok": not errors, "errors": errors}
+        if errors:
+            event_log.write("remove_agent.rollback_failed", agent_id=self.agent_id, errors=errors)
+        return result
+
+
+def _find_worker(spec: dict[str, Any], agent_id: str) -> dict[str, Any] | None:
+    if spec.get("leader", {}).get("id") == agent_id:
+        return None
+    for agent in spec.get("agents", []):
+        if agent.get("id") == agent_id:
+            return agent
+    return None
+
+
+def _dynamic_role_file(workspace: Path, agent_id: str, agent_state: dict[str, Any]) -> Path:
+    raw = agent_state.get("dynamic_role_file")
+    if raw:
+        path = Path(str(raw))
+        return path if path.is_absolute() else workspace / path
+    return workspace / ".team" / "dynamic-role-files" / f"{agent_id}.md"
+
+
+def _is_running(runtime: Any, state: dict[str, Any], agent_id: str, agent_state: dict[str, Any]) -> bool:
+    if str(agent_state.get("status") or "").lower() in {"running", "busy"}:
+        return True
+    session_name = state.get("session_name")
+    window = agent_state.get("window") or agent_id
+    return bool(session_name and runtime._tmux_window_exists(str(session_name), str(window)))
+
+
+def _remove_dynamic_role_file(path: Path, required: bool) -> bool:
+    if path.exists():
+        path.unlink()
+        return True
+    if required:
+        raise RuntimeError(f"dynamic role file missing: {path}")
+    return False
+
+
+def _delete_agent_health(store: MessageStore, agent_id: str) -> None:
+    store.delete_agent_health(agent_id)
+
+
+def _restore_agent_health(store: MessageStore, agent_id: str, row: dict[str, Any] | None) -> None:
+    if not row:
+        _delete_agent_health(store, agent_id)
+        return
+    store.upsert_agent_health(
+        agent_id,
+        row.get("status") or "IDLE",
+        last_output_at=row.get("last_output_at"),
+        context_usage_pct=row.get("context_usage_pct"),
+        current_task_id=row.get("current_task_id"),
+    )