@team-agent/installer 0.1.0

package/src/team_agent/spec.py

@@ -0,0 +1,308 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from team_agent.errors import ValidationError
+from team_agent.permissions import CANONICAL_TOOLS, expand_tools
+from team_agent.profiles import AUTH_MODES
+from team_agent.simple_yaml import loads
+from team_agent.task_graph import find_dependency_cycle
+
+SUPPORTED_PROVIDERS = {"claude", "claude_code", "codex", "gemini_cli", "fake"}
+
+
+def load_yaml(path: Path) -> dict[str, Any]:
+    try:
+        data = loads(path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise ValidationError(f"Cannot read {path}: {exc}") from exc
+    except ValueError as exc:
+        raise ValidationError(f"Invalid YAML in {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ValidationError(f"{path} must contain a YAML object")
+    return data
+
+
+def load_spec(path: Path) -> dict[str, Any]:
+    spec = load_yaml(path)
+    validate_spec(spec, base_dir=path.parent)
+    return spec
+
+
+def validate_spec(spec: dict[str, Any], base_dir: Path | None = None) -> None:
+    messages = _basic_schema_errors(spec)
+    messages.extend(_semantic_errors(spec, base_dir or Path.cwd()))
+    if messages:
+        joined = "\n".join(f"- {m}" for m in messages)
+        raise ValidationError(f"team.spec.yaml validation failed:\n{joined}")
+
+
+RESULT_COLLECTION_SCHEMAS: dict[str, tuple[set[str], set[str]]] = {
+    "changes": ({"path", "kind", "description"}, {"path", "kind", "description"}),
+    "tests": ({"command", "status"}, {"command", "status", "detail"}),
+    "risks": ({"severity", "description"}, {"severity", "description"}),
+    "artifacts": ({"path", "description"}, {"path", "description"}),
+    "next_actions": ({"description"}, {"description"}),
+}
+
+
+def validate_result_envelope(envelope: dict[str, Any]) -> None:
+    errors = _result_schema_errors(envelope)
+    if errors:
+        joined = "\n".join(f"- {error}" for error in errors)
+        raise ValidationError(f"result_envelope_v1 validation failed:\n{joined}")
+
+
+def _basic_schema_errors(spec: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    root_keys = {"version", "team", "leader", "agents", "routing", "communication", "runtime", "context", "tasks"}
+    _check_keys(spec, "/", root_keys, root_keys, errors)
+    if spec.get("version") != 1:
+        errors.append("/version: must equal 1")
+    _check_keys(spec.get("team"), "/team", {"name", "mode", "objective", "workspace"}, {"name", "mode", "objective", "workspace"}, errors)
+    if spec.get("team", {}).get("mode") not in {"supervisor_worker", "swarm_limited"}:
+        errors.append("/team/mode: invalid mode")
+    _check_keys(
+        spec.get("leader"),
+        "/leader",
+        {"id", "role", "provider", "model", "tools", "context_policy"},
+        {"id", "role", "provider", "model", "tools", "context_policy"},
+        errors,
+    )
+    _check_context_policy(spec.get("leader", {}).get("context_policy"), errors)
+    if not isinstance(spec.get("agents"), list) or not spec.get("agents"):
+        errors.append("/agents: must be a non-empty list")
+    else:
+        for idx, agent in enumerate(spec["agents"]):
+            _check_agent(agent, f"/agents/{idx}", errors)
+    _check_routing(spec.get("routing"), errors)
+    _check_communication(spec.get("communication"), errors)
+    _check_runtime(spec.get("runtime"), errors)
+    _check_context(spec.get("context"), errors)
+    if not isinstance(spec.get("tasks"), list):
+        errors.append("/tasks: must be a list")
+    else:
+        for idx, task in enumerate(spec["tasks"]):
+            _check_task(task, f"/tasks/{idx}", errors)
+    return errors
+
+
+def _result_schema_errors(envelope: Any) -> list[str]:
+    errors: list[str] = []
+    required = {"schema_version", "task_id", "agent_id", "status", "summary", "changes", "tests", "risks", "artifacts", "next_actions"}
+    _check_keys(envelope, "/", required, required, errors)
+    if not isinstance(envelope, dict):
+        return errors
+    if envelope.get("schema_version") != "result_envelope_v1":
+        errors.append("/schema_version: must be result_envelope_v1")
+    for field in ["task_id", "agent_id", "summary"]:
+        if field in envelope and not isinstance(envelope[field], str):
+            errors.append(f"/{field}: must be a string")
+        elif field in envelope and not envelope[field]:
+            errors.append(f"/{field}: must not be empty")
+    if envelope.get("status") not in {"success", "blocked", "failed", "partial"}:
+        errors.append("/status: invalid result status")
+    if "schema" in envelope:
+        errors.append("/schema: use schema_version, not schema")
+    for field, (item_required, item_allowed) in RESULT_COLLECTION_SCHEMAS.items():
+        if field not in envelope:
+            continue
+        value = envelope[field]
+        if not isinstance(value, list):
+            errors.append(f"/{field}: must be a list")
+            continue
+        for idx, item in enumerate(value):
+            item_path = f"/{field}/{idx}"
+            _check_keys(item, item_path, item_required, item_allowed, errors)
+            if not isinstance(item, dict):
+                continue
+            if field == "changes" and item.get("kind") not in {"created", "modified", "deleted", "observed"}:
+                errors.append(f"{item_path}/kind: invalid change kind")
+            if field == "tests" and item.get("status") not in {"passed", "failed", "not_run", "skipped"}:
+                errors.append(f"{item_path}/status: invalid test status")
+            if field == "risks" and item.get("severity") not in {"low", "medium", "high"}:
+                errors.append(f"{item_path}/severity: invalid risk severity")
+            for key, child in item.items():
+                if key in item_allowed and not isinstance(child, str):
+                    errors.append(f"{item_path}/{key}: must be a string")
+    return errors
+
+
+def _check_agent(agent: Any, path: str, errors: list[str]) -> None:
+    required = {"id", "role", "provider", "model", "working_directory", "system_prompt", "tools", "permission_mode", "preferred_for", "avoid_for", "output_contract"}
+    allowed = required | {"paused", "auth_mode", "profile", "credential_ref"}
+    _check_keys(agent, path, required, allowed, errors)
+    if not isinstance(agent, dict):
+        return
+    _check_keys(agent.get("system_prompt"), f"{path}/system_prompt", {"inline", "file"}, {"inline", "file"}, errors)
+    _check_list(agent.get("tools"), f"{path}/tools", errors)
+    _check_list(agent.get("preferred_for"), f"{path}/preferred_for", errors)
+    _check_list(agent.get("avoid_for"), f"{path}/avoid_for", errors)
+    _check_keys(agent.get("output_contract"), f"{path}/output_contract", {"format", "required_fields"}, {"format", "required_fields"}, errors)
+    if agent.get("output_contract", {}).get("format") != "result_envelope_v1":
+        errors.append(f"{path}/output_contract/format: must be result_envelope_v1")
+
+
+def _check_context_policy(policy: Any, errors: list[str]) -> None:
+    _check_keys(
+        policy,
+        "/leader/context_policy",
+        {"keep_user_thread", "receive_worker_outputs", "max_worker_result_tokens"},
+        {"keep_user_thread", "receive_worker_outputs", "max_worker_result_tokens"},
+        errors,
+    )
+
+
+def _check_routing(routing: Any, errors: list[str]) -> None:
+    _check_keys(routing, "/routing", {"default_assignee", "rules"}, {"default_assignee", "rules"}, errors)
+    if not isinstance(routing, dict):
+        return
+    if not isinstance(routing.get("rules"), list):
+        errors.append("/routing/rules: must be a list")
+        return
+    for idx, rule in enumerate(routing["rules"]):
+        allowed = {"id", "when", "match", "assign_to", "priority"}
+        required = {"id", "assign_to", "priority"}
+        _check_keys(rule, f"/routing/rules/{idx}", required, allowed, errors)
+        if isinstance(rule, dict) and not (rule.get("when") or rule.get("match")):
+            errors.append(f"/routing/rules/{idx}: must include when or match")
+
+
+def _check_communication(comm: Any, errors: list[str]) -> None:
+    required = {"protocol", "topology", "worker_to_worker", "ack_timeout_sec", "result_format", "message_store"}
+    _check_keys(comm, "/communication", required, required, errors)
+    if not isinstance(comm, dict):
+        return
+    if comm.get("protocol") not in {"mcp_inbox", "file_bus"}:
+        errors.append("/communication/protocol: invalid protocol")
+    if comm.get("result_format") != "result_envelope_v1":
+        errors.append("/communication/result_format: must be result_envelope_v1")
+    _check_keys(comm.get("message_store"), "/communication/message_store", {"sqlite", "mirror_files"}, {"sqlite", "mirror_files"}, errors)
+
+
+def _check_runtime(runtime: Any, errors: list[str]) -> None:
+    required = {"backend", "display_backend", "session_name", "auto_launch", "require_user_approval_before_launch", "max_active_agents", "startup_order"}
+    allowed = required | {
+        "dangerous_auto_approve",
+        "auto_attach_leader",
+        "fast",
+        "tick_interval_sec",
+        "push_min_interval_sec",
+        "stuck_timeout_sec",
+    }
+    _check_keys(runtime, "/runtime", required, allowed, errors)
+    if not isinstance(runtime, dict):
+        return
+    if runtime.get("backend") not in {"tmux", "pty"}:
+        errors.append("/runtime/backend: invalid backend")
+    if runtime.get("display_backend") not in {"none", "tmux_attach", "iterm", "ghostty", "ghostty_window"}:
+        errors.append("/runtime/display_backend: invalid display backend")
+    if "dangerous_auto_approve" in runtime and not isinstance(runtime["dangerous_auto_approve"], bool):
+        errors.append("/runtime/dangerous_auto_approve: must be a boolean")
+    _check_list(runtime.get("startup_order"), "/runtime/startup_order", errors)
+
+
+def _check_context(context: Any, errors: list[str]) -> None:
+    required = {"state_file", "artifact_dir", "log_dir", "summarization"}
+    _check_keys(context, "/context", required, required, errors)
+    if isinstance(context, dict):
+        _check_keys(context.get("summarization"), "/context/summarization", {"worker_full_logs", "state_update"}, {"worker_full_logs", "state_update"}, errors)
+
+
+def _check_task(task: Any, path: str, errors: list[str]) -> None:
+    required = {"id", "title", "type", "assignee", "deps", "acceptance", "status"}
+    allowed = required | {"description", "requires_tools", "files", "risk", "retry_limit", "human_confirmation"}
+    _check_keys(task, path, required, allowed, errors)
+    if not isinstance(task, dict):
+        return
+    _check_list(task.get("deps"), f"{path}/deps", errors)
+    _check_list(task.get("acceptance"), f"{path}/acceptance", errors)
+    if task.get("status") not in {"pending", "ready", "running", "blocked", "needs_retry", "done", "failed", "cancelled"}:
+        errors.append(f"{path}/status: invalid task status")
+
+
+def _check_keys(obj: Any, path: str, required: set[str], allowed: set[str], errors: list[str]) -> None:
+    if not isinstance(obj, dict):
+        errors.append(f"{path}: must be an object")
+        return
+    missing = sorted(required - set(obj))
+    for key in missing:
+        errors.append(f"{path.rstrip('/')}/{key}: missing required field")
+    unknown = sorted(set(obj) - allowed)
+    for key in unknown:
+        errors.append(f"{path.rstrip('/')}/{key}: unknown field")
+
+
+def _check_list(value: Any, path: str, errors: list[str]) -> None:
+    if not isinstance(value, list):
+        errors.append(f"{path}: must be a list")
+
+
+def _semantic_errors(spec: dict[str, Any], base_dir: Path) -> list[str]:
+    errors: list[str] = []
+    leader = spec.get("leader", {})
+    agents = spec.get("agents", [])
+    agent_ids = {a.get("id") for a in agents if isinstance(a, dict)}
+    all_ids = set(agent_ids)
+    if leader.get("id"):
+        all_ids.add(leader["id"])
+
+    for path, provider in [("/leader/provider", leader.get("provider"))]:
+        if provider not in SUPPORTED_PROVIDERS:
+            errors.append(f"{path}: unknown provider {provider!r}")
+    for idx, agent in enumerate(agents):
+        provider = agent.get("provider")
+        if provider not in SUPPORTED_PROVIDERS:
+            errors.append(f"/agents/{idx}/provider: unknown provider {provider!r}")
+        auth_mode = agent.get("auth_mode")
+        if auth_mode is not None and auth_mode not in AUTH_MODES:
+            errors.append(f"/agents/{idx}/auth_mode: unknown auth_mode {auth_mode!r}")
+        prompt_file = agent.get("system_prompt", {}).get("file")
+        if prompt_file:
+            candidate = Path(prompt_file)
+            if not candidate.is_absolute():
+                candidate = base_dir / candidate
+            if not candidate.exists():
+                errors.append(f"/agents/{idx}/system_prompt/file: file not found: {candidate}")
+        for tool in expand_tools(agent.get("tools", [])):
+            if tool not in CANONICAL_TOOLS:
+                errors.append(f"/agents/{idx}/tools: unknown tool {tool!r}")
+
+    leader_tools = leader.get("tools", [])
+    for tool in expand_tools(leader_tools):
+        if tool not in CANONICAL_TOOLS:
+            errors.append(f"/leader/tools: unknown tool {tool!r}")
+
+    routing = spec.get("routing", {})
+    default_assignee = routing.get("default_assignee")
+    if default_assignee and default_assignee not in all_ids:
+        errors.append(f"/routing/default_assignee: unknown agent {default_assignee!r}")
+    for idx, rule in enumerate(routing.get("rules", [])):
+        target = rule.get("assign_to")
+        if target not in all_ids:
+            errors.append(f"/routing/rules/{idx}/assign_to: unknown agent {target!r}")
+
+    tasks = spec.get("tasks", [])
+    task_ids = {t.get("id") for t in tasks if isinstance(t, dict)}
+    for idx, task in enumerate(tasks):
+        assignee = task.get("assignee")
+        if assignee and assignee not in all_ids:
+            errors.append(f"/tasks/{idx}/assignee: unknown agent {assignee!r}")
+        for dep in task.get("deps", []):
+            if dep not in task_ids:
+                errors.append(f"/tasks/{idx}/deps: unknown dependency {dep!r}")
+
+    cycle = find_dependency_cycle(tasks)
+    if cycle:
+        errors.append(f"/tasks: dependency cycle detected: {' -> '.join(cycle)}")
+    return errors
+
+
+def workspace_from_spec(spec: dict[str, Any], spec_path: Path | None = None) -> Path:
+    raw = spec.get("team", {}).get("workspace") or "."
+    path = Path(raw)
+    if path.is_absolute():
+        return path
+    base = spec_path.parent if spec_path else Path.cwd()
+    return (base / path).resolve()

package/src/team_agent/state.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from team_agent.paths import runtime_dir
+from team_agent.simple_yaml import dumps
+
+
+SESSION_STATE_FIELDS = [
+    "session_id",
+    "rollout_path",
+    "captured_at",
+    "captured_via",
+    "attribution_confidence",
+    "spawn_cwd",
+]
+
+
+def runtime_state_path(workspace: Path) -> Path:
+    return runtime_dir(workspace) / "state.json"
+
+
+def load_runtime_state(workspace: Path) -> dict[str, Any]:
+    path = runtime_state_path(workspace)
+    if not path.exists():
+        return {"agents": {}, "tasks": [], "session_name": None}
+    state = json.loads(path.read_text(encoding="utf-8"))
+    for agent_state in state.get("agents", {}).values():
+        if isinstance(agent_state, dict):
+            for field in SESSION_STATE_FIELDS:
+                agent_state.setdefault(field, None)
+    return state
+
+
+def save_runtime_state(workspace: Path, state: dict[str, Any]) -> None:
+    path = runtime_state_path(workspace)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = path.with_suffix(path.suffix + ".tmp")
+    tmp_path.write_text(json.dumps(state, indent=2, ensure_ascii=False), encoding="utf-8")
+    os.replace(tmp_path, path)
+
+
+def write_team_state(workspace: Path, spec: dict[str, Any], runtime: dict[str, Any], results: list[dict[str, Any]] | None = None) -> Path:
+    path = workspace / spec.get("context", {}).get("state_file", "team_state.md")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lines = [
+        "# Team State",
+        "",
+        f"Updated: {datetime.now(timezone.utc).isoformat()}",
+        "",
+        "## Objective",
+        "",
+        spec.get("team", {}).get("objective", ""),
+        "",
+        "## Team",
+        "",
+        f"- Name: {spec.get('team', {}).get('name')}",
+        f"- Runtime session: {runtime.get('session_name')}",
+    ]
+    receiver = runtime.get("leader_receiver") or {}
+    if receiver:
+        if receiver.get("mode") == "direct_tmux":
+            lines.append(
+                f"- Leader receiver: direct tmux {receiver.get('pane_id')} "
+                f"({receiver.get('provider')}, {receiver.get('status')})"
+            )
+        else:
+            lines.append(f"- Leader inbox fallback: {receiver.get('session')}:{receiver.get('window')} ({receiver.get('status')})")
+            lines.append(f"- Leader inbox log: {receiver.get('path')}")
+    lines.extend(["", "## Agents", ""])
+    for agent in spec.get("agents", []):
+        status = runtime.get("agents", {}).get(agent["id"], {}).get("status", "unknown")
+        lines.append(f"- {agent['id']}: {agent['role']} on {agent['provider']} ({status})")
+    lines.extend(["", "## Task Graph", ""])
+    for task in runtime.get("tasks", spec.get("tasks", [])):
+        deps = ", ".join(task.get("deps", [])) or "none"
+        assignee = task.get("assignee") or "unassigned"
+        lines.append(f"- {task['id']} [{task.get('status', 'pending')}], assignee={assignee}, deps={deps}: {task['title']}")
+        if task.get("last_result_summary"):
+            lines.append(f"  Summary: {task['last_result_summary']}")
+        if task.get("artifact_refs"):
+            for ref in task["artifact_refs"]:
+                if isinstance(ref, dict):
+                    lines.append(f"  Artifact: {ref.get('path')} - {ref.get('description', '')}")
+                else:
+                    lines.append(f"  Artifact: INVALID artifact ref {ref!r}")
+    lines.extend(["", "## Latest Results", ""])
+    for result in results or []:
+        envelope = json.loads(result["envelope"]) if isinstance(result.get("envelope"), str) else result
+        lines.append(f"- {envelope.get('task_id')} from {envelope.get('agent_id')}: {envelope.get('status')} - {envelope.get('summary')}")
+    lines.extend(["", "## Blockers", ""])
+    blockers = [
+        task
+        for task in runtime.get("tasks", spec.get("tasks", []))
+        if task.get("status") in {"blocked", "failed", "needs_retry"}
+    ]
+    if blockers:
+        for task in blockers:
+            lines.append(f"- {task['id']}: {task.get('last_result_summary', task.get('title'))}")
+    else:
+        lines.append("- None")
+    lines.extend(["", "## Next Step", "", "- Continue routing ready tasks and collect result envelopes."])
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return path
+
+
+def write_spec(path: Path, spec: dict[str, Any]) -> None:
+    path.write_text(dumps(spec), encoding="utf-8")

package/src/team_agent/task_graph.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from typing import Any
+
+TASK_STATUSES = {
+    "pending",
+    "ready",
+    "running",
+    "blocked",
+    "needs_retry",
+    "done",
+    "failed",
+    "cancelled",
+}
+
+TERMINAL_TASK_STATUSES = {"done", "failed", "cancelled"}
+
+
+def find_dependency_cycle(tasks: list[dict[str, Any]]) -> list[str]:
+    graph = {t.get("id"): list(t.get("deps", [])) for t in tasks if t.get("id")}
+    visiting: set[str] = set()
+    visited: set[str] = set()
+    stack: list[str] = []
+
+    def visit(node: str) -> list[str] | None:
+        if node in visited:
+            return None
+        if node in visiting:
+            if node in stack:
+                return stack[stack.index(node) :] + [node]
+            return [node, node]
+        visiting.add(node)
+        stack.append(node)
+        for dep in graph.get(node, []):
+            if dep in graph:
+                cycle = visit(dep)
+                if cycle:
+                    return cycle
+        stack.pop()
+        visiting.remove(node)
+        visited.add(node)
+        return None
+
+    for node in graph:
+        cycle = visit(node)
+        if cycle:
+            return cycle
+    return []
+
+
+def ready_tasks(tasks: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    by_id = {t["id"]: t for t in tasks}
+    ready: list[dict[str, Any]] = []
+    for task in tasks:
+        if task.get("status", "pending") not in {"pending", "ready", "needs_retry"}:
+            continue
+        deps_done = all(by_id.get(dep, {}).get("status") == "done" for dep in task.get("deps", []))
+        if deps_done:
+            ready.append(task)
+    return ready
+
+
+def update_task_status(
+    tasks: list[dict[str, Any]],
+    task_id: str,
+    status: str,
+    summary: str | None = None,
+    artifact_refs: list[dict[str, Any]] | None = None,
+) -> None:
+    if status not in TASK_STATUSES:
+        raise ValueError(f"Unknown task status: {status}")
+    for task in tasks:
+        if task.get("id") == task_id:
+            task["status"] = status
+            if summary is not None:
+                task["last_result_summary"] = summary
+            if artifact_refs is not None:
+                task["artifact_refs"] = artifact_refs
+            return
+    raise KeyError(f"Unknown task id: {task_id}")

package/templates/team_state.md

@@ -0,0 +1,32 @@
+# Team State
+
+Updated: not launched
+
+## Objective
+
+Pending.
+
+## Team
+
+- Name: pending
+- Runtime session: pending
+
+## Agents
+
+- Pending launch.
+
+## Task Graph
+
+- Pending task graph.
+
+## Latest Results
+
+- None.
+
+## Blockers
+
+- None.
+
+## Next Step
+
+- Run `team-agent validate team.spec.yaml`, review permissions, then run `team-agent launch team.spec.yaml --yes`.