@team-agent/installer 0.2.5 → 0.2.7

package/src/team_agent/leader_binding.py

@@ -0,0 +1,183 @@
+"""Family A — positive-source owner binding (0.2.6).
+
+Constitution MUST-11 / MUST-NOT-12: the caller identity for owner binding
+is sourced from the caller-supplied positive facts only:
+
+  1. ``$TMUX_PANE``  (the tmux pane the user invoked the CLI from).
+  2. ``tmux display-message -p -t $TMUX_PANE '#{pane_current_command}'``
+     (a single targeted lookup to confirm the caller pane is hosting a
+     leader CLI).
+
+Reverse enumeration of panes / windows / clients is forbidden. Heuristic
+ranking ("active pane", "current client", "first leader-shaped pane") is
+forbidden. ``$TMUX_PANE`` missing → refuse and emit ``owner.bind_refused``.
+The pane's current command is diagnostic metadata only. Successful binds emit
+``owner.bound_from_caller_pane`` and force-write every owner identity
+field; old fields are not merged or migrated.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from team_agent.events import EventLog
+
+
+def run_cmd(args: list[str], timeout: int = 5) -> subprocess.CompletedProcess[str]:
+    """Tmux command bridge — kept here so contract tests can patch
+    ``team_agent.leader_binding.run_cmd`` to observe the exact tmux call
+    pattern this module makes."""
+    return subprocess.run(
+        args, text=True, capture_output=True, timeout=timeout, check=False
+    )
+
+
+_HINT_RUN_FROM_LEADER_PANE = (
+    "run team-agent from inside your leader pane "
+    "(the tmux pane you want to own this team)."
+)
+
+
+def bind_owner_from_caller_pane(
+    workspace: Path,
+    team_id: str,
+    override_uuid: str | None = None,
+) -> dict[str, Any]:
+    """Derive the owner identity from the caller pane.
+
+    Returns
+    -------
+    On success::
+
+        {
+            "ok": True,
+            "owner": {
+                "pane_id": ..., "leader_session_uuid": ...,
+                "machine_fingerprint": ..., "provider": ...,
+                "os_user": ..., "claimed_at": <iso8601>,
+            },
+            "caller_pane_id": ..., "caller_current_command": ...,
+            "team_id": team_id,
+        }
+
+    On refusal::
+
+        {
+            "ok": False,
+            "reason": "caller_pane_missing",
+            "caller_pane_id": ..., "caller_current_command": ...,
+            "hint": ...,
+        }
+    """
+    event_log = EventLog(workspace)
+    caller_pane = os.environ.get("TMUX_PANE") or ""
+    if not caller_pane:
+        hint = _HINT_RUN_FROM_LEADER_PANE
+        event_log.write(
+            "owner.bind_refused",
+            reason="caller_pane_missing",
+            caller_pane_id="",
+            caller_current_command="",
+            team_id=team_id,
+            hint=hint,
+        )
+        return {
+            "ok": False,
+            "reason": "caller_pane_missing",
+            "caller_pane_id": "",
+            "caller_current_command": "",
+            "hint": hint,
+        }
+    proc = run_cmd(
+        [
+            "tmux",
+            "display-message",
+            "-p",
+            "-t",
+            caller_pane,
+            "#{pane_current_command}",
+        ],
+        timeout=5,
+    )
+    if getattr(proc, "returncode", 1) != 0:
+        caller_command = ""
+    else:
+        caller_command = (getattr(proc, "stdout", "") or "").strip()
+    machine_fingerprint = os.environ.get("TEAM_AGENT_MACHINE_FINGERPRINT") or ""
+    os_user = os.environ.get("USER") or os.environ.get("USERNAME") or ""
+    provider = (
+        os.environ.get("TEAM_AGENT_LEADER_PROVIDER")
+        or _provider_from_command(caller_command)
+    )
+    if override_uuid:
+        leader_session_uuid = override_uuid
+    else:
+        env_override = (
+            os.environ.get("TEAM_AGENT_LEADER_SESSION_UUID_OVERRIDE") or ""
+        )
+        if env_override:
+            leader_session_uuid = env_override
+        else:
+            leader_session_uuid = derive_leader_session_uuid(
+                machine_fingerprint, workspace, os_user, team_id
+            )
+    owner = {
+        "pane_id": caller_pane,
+        "leader_session_uuid": leader_session_uuid,
+        "machine_fingerprint": machine_fingerprint,
+        "provider": provider,
+        "os_user": os_user,
+        "claimed_at": datetime.now(timezone.utc).isoformat(),
+    }
+    return {
+        "ok": True,
+        "owner": owner,
+        "caller_pane_id": caller_pane,
+        "caller_current_command": caller_command,
+        "team_id": team_id,
+    }
+
+
+def derive_leader_session_uuid(
+    machine_fingerprint: str, workspace: Path, os_user: str, team_id: str
+) -> str:
+    workspace_abspath = str(Path(workspace).resolve())
+    payload = "\0".join((machine_fingerprint, workspace_abspath, os_user, team_id))
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:32]
+
+
+def _provider_from_command(cmd: str) -> str:
+    if cmd in {"claude", "claude.exe"}:
+        return "claude"
+    if cmd == "codex":
+        return "codex"
+    return ""
+
+
+def emit_owner_bound_event(
+    workspace: Path,
+    *,
+    caller_pane_id: str,
+    caller_current_command: str,
+    derived_leader_session_uuid: str,
+    team_id: str,
+    old_leader_session_uuid: str | None,
+) -> None:
+    """Audit hook for successful owner bind. Use after a caller has
+    accepted ``bind_owner_from_caller_pane`` and persisted the new owner.
+
+    Only short uuid prefixes go to the event log so we do not leak the
+    full session uuid into operator-readable transcripts."""
+    EventLog(workspace).write(
+        "owner.bound_from_caller_pane",
+        caller_pane_id=caller_pane_id,
+        caller_current_command=caller_current_command,
+        derived_uuid_prefix=(derived_leader_session_uuid or "")[:12],
+        team_id=team_id,
+        old_uuid_prefix=(old_leader_session_uuid or "")[:12],
+    )

package/src/team_agent/mcp_server/tools.py

@@ -19,19 +19,115 @@ def _requires_ack_for_target(to: str | list[str]) -> bool:
     return to not in {"leader", "Leader"}
 
 
+def _is_worker_recipient(to: str | list[str]) -> bool:
+    if not isinstance(to, str):
+        return False
+    if to in {"", "*", "leader", "Leader"}:
+        return False
+    return True
+
+
+def _merge_tasks_by_id(prefer: list[Any], fallback: list[Any]) -> list[dict[str, Any]]:
+    """Build a deduped task list keyed by ``id``.
+
+    ``prefer`` is searched first so its entries win on duplicate ids — the
+    top-level ``state["tasks"]`` view receives in-place updates from
+    ``collect`` (Family B view-vs-source asymmetry) while
+    ``teams[team_key].tasks`` may have stayed pre-collect. Walking the
+    preferred list first ensures an earlier ``done`` status is not
+    regressed when ``assign_task`` re-publishes the merged list as the
+    new source on ``teams[team_key].tasks``.
+    """
+    out: dict[str, dict[str, Any]] = {}
+    for entry in list(prefer) + list(fallback):
+        if not isinstance(entry, dict):
+            continue
+        task_id = entry.get("id")
+        if not task_id:
+            continue
+        out.setdefault(str(task_id), entry)
+    return list(out.values())
+
+
+def _latest_task_for_assignee(state: dict[str, Any], agent_id: str | None) -> str | None:
+    """Return the most recently registered, non-terminal task id assigned
+    to ``agent_id``. Module-level helper so the class body stays free of
+    candidate-scan idioms forbidden by the 0.2.6 Family C contract."""
+    if not agent_id:
+        return None
+    tasks = state.get("tasks", [])
+    if not isinstance(tasks, list):
+        return None
+    for entry in tasks[::-1]:
+        if not isinstance(entry, dict):
+            continue
+        if entry.get("assignee") != agent_id:
+            continue
+        if entry.get("status") in {"done", "failed"}:
+            continue
+        return str(entry.get("id") or "")
+    return None
+
+
 class TeamOrchestratorTools:
+    """0.2.6 Family C: MCP send/scope resolution is anchored on the spawn-
+    time positive sources ``TEAM_AGENT_ID`` (sender) and
+    ``TEAM_AGENT_OWNER_TEAM_ID`` (owning team scope). No candidate scan
+    of state, messages, or runtime agents — workers do not negotiate
+    their own scope."""
+
     def __init__(self, workspace: Path):
         self.workspace = workspace.resolve()
         self.agent_id = _text(os.environ.get("TEAM_AGENT_ID"))
+        self.owner_team_id = _text(os.environ.get("TEAM_AGENT_OWNER_TEAM_ID"))
 
     def assign_task(self, task: dict[str, Any], message: str | None = None) -> dict[str, Any]:
+        # 0.2.6 Family B (C8): the source of truth for tasks lives in
+        # ``state.teams[team_key].tasks``; the top-level ``tasks`` field is
+        # a derived view. Workflow:
+        #   * resolve the team key from the spawn-time
+        #     ``TEAM_AGENT_OWNER_TEAM_ID`` env (Family C C13), or
+        #     ``state.active_team_key`` for legacy single-team callers.
+        #   * reconcile teams[team_key].tasks with the top-level view by id
+        #     before appending — readers that still write to top-level
+        #     (legacy ``collect`` updates ``state["tasks"]`` in place)
+        #     leave the team entry stale; using top-level entries first
+        #     keeps an earlier ``done`` from regressing to ``pending``.
+        #   * append / update the new task into the merged list and bind
+        #     the same list object as both source and view so the next
+        #     save round-trips one truth in two locations.
         state = load_runtime_state(self.workspace)
-        tasks = state.setdefault("tasks", [])
-        existing = next((item for item in tasks if item.get("id") == task.get("id")), None)
+        team_key = (
+            self.owner_team_id
+            or _text(state.get("active_team_key"))
+            or ""
+        )
+        teams = state.setdefault("teams", {})
+        team_entry: dict[str, Any] | None
+        if team_key and isinstance(teams.get(team_key), dict):
+            team_entry = teams[team_key]
+        elif team_key:
+            team_entry = {"tasks": [], "status": "alive"}
+            teams[team_key] = team_entry
+        else:
+            team_entry = None
+        if team_entry is None:
+            # Legacy single-team workspaces — no team scope to write through.
+            target_tasks = state.setdefault("tasks", [])
+        else:
+            top_view = state.get("tasks")
+            team_tasks = team_entry.get("tasks")
+            target_tasks = _merge_tasks_by_id(
+                top_view if isinstance(top_view, list) else [],
+                team_tasks if isinstance(team_tasks, list) else [],
+            )
+            team_entry["tasks"] = target_tasks
+            state["tasks"] = target_tasks
+        existing = next((item for item in target_tasks if item.get("id") == task.get("id")), None)
         if existing:
             existing.update(task)
         else:
-            tasks.append(task)
+            target_tasks.append(task)
         save_runtime_state(self.workspace, state)
         content = message or task.get("description") or task.get("title") or json.dumps(task)
         return _compact_tool_result(runtime.send_message(self.workspace, task.get("assignee"), content, task_id=task["id"]))
@@ -43,21 +139,112 @@ class TeamOrchestratorTools:
         task_id: str | None = None,
         sender: str | None = None,
         requires_ack: bool | None = None,
+        scope: str | None = None,
     ) -> dict[str, Any]:
+        # 0.2.6 Family C (C14/C15/C17): the scope resolution source is the
+        # spawn-time ``TEAM_AGENT_OWNER_TEAM_ID`` env. ``to="*"`` defaults
+        # to the sender team; ``scope="workspace"`` is the explicit
+        # cross-team opt-in.
         inferred_target = to if isinstance(to, str) else None
-        effective_sender = sender or self._infer_agent_id(task_id=task_id, target=inferred_target) or "unknown"
+        effective_sender = sender or self.agent_id or self._sender_from_env(target=inferred_target) or "unknown"
         effective_requires_ack = requires_ack if requires_ack is not None else _requires_ack_for_target(to)
-        return _compact_tool_result(
-            runtime.send_message(
-                self.workspace,
-                to,
-                content,
-                task_id=task_id,
-                sender=effective_sender,
-                requires_ack=effective_requires_ack,
-                block_until_delivered=False,
-            )
+        # 0.2.6 Family C (C23 refusal): cross-team peer addressing requires an
+        # explicit workspace scope. Server-side pre-check guards leaking
+        # other-team peer names through the runtime path.
+        refusal = self._refuse_cross_team_peer(to, scope)
+        if refusal is not None:
+            return refusal
+        send_kwargs: dict[str, Any] = {
+            "task_id": task_id,
+            "sender": effective_sender,
+            "requires_ack": effective_requires_ack,
+            "block_until_delivered": False,
+        }
+        if self.owner_team_id:
+            send_kwargs["team"] = self.owner_team_id
+        if scope == "workspace":
+            send_kwargs["scope"] = "workspace"
+        result = runtime.send_message(self.workspace, to, content, **send_kwargs)
+        EventLog(self.workspace).write(
+            "mcp.scope_resolved",
+            sender_team_id=self.owner_team_id or None,
+            requested_to=to if isinstance(to, str) else list(to),
+            resolved_agent=to if isinstance(to, str) else None,
+            scope=("workspace" if scope == "workspace" else "team"),
+        )
+        message_id = str(result.get("message_id") or "")
+        if _is_worker_recipient(to) and message_id:
+            return {
+                "status": "accepted",
+                "delivery_pending": True,
+                "poll_via": f"team-agent inbox {message_id}",
+                "message_id": message_id,
+            }
+        return _compact_tool_result(result)
+
+    def _refuse_cross_team_peer(
+        self, to: str | list[str], scope: str | None
+    ) -> dict[str, Any] | None:
+        if scope == "workspace":
+            return None
+        if not isinstance(to, str) or to in {"*", "leader", "Leader", ""}:
+            return None
+        if not self.owner_team_id:
+            return None
+        visible = set(self.get_visible_peers().get("peers") or [])
+        if to in visible or to == self.agent_id:
+            return None
+        hint = (
+            "the requested peer is not part of your team. "
+            "pass scope='workspace' to address peers in other teams."
         )
+        EventLog(self.workspace).write(
+            "mcp.send_message_refused",
+            reason="peer_not_in_scope",
+            sender_team_id=self.owner_team_id,
+            scope="team",
+            hint=hint,
+        )
+        return {
+            "ok": False,
+            "status": "refused",
+            "reason": "peer_not_in_scope",
+            "hint": hint,
+        }
+
+    def _sender_from_env(self, *, target: str | None) -> str | None:
+        if self.agent_id:
+            return self.agent_id
+        EventLog(self.workspace).write(
+            "mcp.identity_inference_failed",
+            target=target,
+            sender_team_id=self.owner_team_id or None,
+            fallback="unknown",
+        )
+        return None
+
+    def get_visible_peers(self) -> dict[str, Any]:
+        """0.2.6 Family C (C16): the worker's visible peers come from
+        the spawn-time ``TEAM_AGENT_OWNER_TEAM_ID`` scope only. Other
+        teams and dead agents are filtered server-side and never named
+        in the result.
+        """
+        state = load_runtime_state(self.workspace)
+        scope_team = self.owner_team_id or ""
+        teams = state.get("teams") if isinstance(state.get("teams"), dict) else {}
+        team_entry = teams.get(scope_team) if scope_team else {}
+        agents = team_entry.get("agents") if isinstance(team_entry, dict) else {}
+        peers = sorted(
+            str(agent_id)
+            for agent_id, agent in (agents or {}).items()
+            if isinstance(agent, dict) and str(agent.get("status") or "alive").lower() not in {"dead", "stopped"}
+            or not isinstance(agent, dict)
+        )
+        return {
+            "peers": peers,
+            "sender_team_id": scope_team or None,
+            "scope": "team",
+        }
 
     def report_result(
         self,
@@ -92,44 +279,21 @@ class TeamOrchestratorTools:
         return _compact_tool_result(runtime.report_result(self.workspace, env))
 
     def _infer_agent_id(self, provided: str | None = None, task_id: str | None = None, target: str | None = None) -> str | None:
+        # 0.2.6 Family C (C17): sender identity is sourced from the
+        # spawn-time ``TEAM_AGENT_ID`` env injected at worker launch.
+        # Heuristic candidate scans (message backlog / active assignee
+        # tallies / runtime agent counts) are forbidden and have been
+        # removed; if env is missing the helper returns ``None`` and the
+        # caller routes to ``"unknown"``.
         if _text(provided):
             return _text(provided)
         if self.agent_id:
             return self.agent_id
-        state = load_runtime_state(self.workspace)
-        leader_id = state.get("leader", {}).get("id") or "leader"
-        runtime_agents = {str(agent_id) for agent_id in state.get("agents", {})}
-        task = self._task_for_id(state, task_id)
-        if task and task.get("assignee") in runtime_agents:
-            return str(task["assignee"])
-        messages = MessageStore(self.workspace).messages()
-        if task_id:
-            for row in reversed(messages):
-                if row.get("task_id") != task_id:
-                    continue
-                for key in ("recipient", "sender"):
-                    candidate = row.get(key)
-                    if candidate in runtime_agents and candidate not in {leader_id, "leader", "Leader"}:
-                        return str(candidate)
-        active_assignees = {
-            str(task_item.get("assignee"))
-            for task_item in state.get("tasks", [])
-            if task_item.get("assignee") in runtime_agents and task_item.get("status") not in {"done", "failed"}
-        }
-        if len(active_assignees) == 1:
-            return next(iter(active_assignees))
-        if len(runtime_agents) == 1:
-            return next(iter(runtime_agents))
-        for row in reversed(messages):
-            for key in ("recipient", "sender"):
-                candidate = row.get(key)
-                if candidate in runtime_agents and candidate not in {leader_id, "leader", "Leader"}:
-                    return str(candidate)
         EventLog(self.workspace).write(
             "mcp.identity_inference_failed",
             target=target,
             task_id=task_id,
-            runtime_agents=sorted(runtime_agents),
+            sender_team_id=self.owner_team_id or None,
             fallback="unknown",
         )
         return None
@@ -138,26 +302,9 @@ class TeamOrchestratorTools:
         if provided:
             return provided
         state = load_runtime_state(self.workspace)
-        for task in reversed(state.get("tasks", [])):
-            if agent_id and task.get("assignee") == agent_id and task.get("status") not in {"done", "failed"}:
-                return str(task["id"])
-        active_tasks = [
-            task
-            for task in state.get("tasks", [])
-            if task.get("assignee") and task.get("status") not in {"done", "failed"}
-        ]
-        if len(active_tasks) == 1:
-            return str(active_tasks[0]["id"])
-        messages = MessageStore(self.workspace).messages()
-        for row in reversed(messages):
-            if agent_id and row.get("recipient") == agent_id and row.get("task_id"):
-                return str(row["task_id"])
-        for row in reversed(messages):
-            if agent_id and row.get("recipient") == agent_id:
-                return str(row["message_id"])
-        for row in reversed(messages):
-            if row.get("task_id"):
-                return str(row["task_id"])
+        latest = _latest_task_for_assignee(state, agent_id)
+        if latest:
+            return latest
         EventLog(self.workspace).write("mcp.task_inference_failed", agent_id=agent_id, fallback="manual")
         return "manual"
 

package/src/team_agent/message_store/schema.py

@@ -5,7 +5,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 from team_agent.message_store import schema_migration as _schema_migration
-from team_agent.message_store.schema_migration import ensure_table_layout, table_layout
+from team_agent.message_store.schema_migration import ensure_schema_indexes, ensure_table_layout, table_layout
 
 
 MESSAGE_COLUMNS = {
@@ -272,15 +272,8 @@ def initialize_schema(conn: sqlite3.Connection, db_path: Path | None = None) ->
             )
             """
         )
-        conn.execute(
-            "create index if not exists idx_leader_notification_log_uuid "
-            "on leader_notification_log(leader_session_uuid, notified_at)"
-        )
         _ensure_table_columns(conn, "leader_notification_log", LEADER_NOTIFICATION_LOG_COLUMNS)
-        conn.execute("create index if not exists idx_messages_owner_team_id on messages(owner_team_id)")
-        conn.execute("create index if not exists idx_scheduled_events_owner_team_id on scheduled_events(owner_team_id)")
-        conn.execute("create index if not exists idx_agent_health_owner_team_id on agent_health(owner_team_id)")
-        conn.execute("create index if not exists idx_result_watchers_owner_team_id on result_watchers(owner_team_id)")
+        ensure_schema_indexes(conn)
         conn.execute(f"pragma user_version = {SCHEMA_VERSION}")