@team-agent/installer 0.1.11 → 0.2.1

package/src/team_agent/diagnose/__init__.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from team_agent.diagnose.checks import (
+    compact_model_checks,
+    format_model_check_failures,
+    format_profile_check_failures,
+    format_profile_smoke_failures,
+    model_checks_for_agents,
+    profile_checks_for_agents,
+    profile_smoke_checks_for_agents,
+)
+from team_agent.diagnose.health import diagnose, doctor
+from team_agent.diagnose.preflight import (
+    ensure_profiles_for_roles,
+    preflight,
+    preflight_blockers,
+    preflight_next_actions,
+    start,
+)
+from team_agent.diagnose.quick_start import (
+    prepare_quick_start_team,
+    quick_start,
+    repair_state,
+    settle,
+    wait_ready,
+)
+
+__all__ = [
+    "compact_model_checks",
+    "diagnose",
+    "doctor",
+    "ensure_profiles_for_roles",
+    "format_model_check_failures",
+    "format_profile_check_failures",
+    "format_profile_smoke_failures",
+    "model_checks_for_agents",
+    "prepare_quick_start_team",
+    "preflight",
+    "preflight_blockers",
+    "preflight_next_actions",
+    "profile_checks_for_agents",
+    "profile_smoke_checks_for_agents",
+    "quick_start",
+    "repair_state",
+    "settle",
+    "start",
+    "wait_ready",
+]

package/src/team_agent/diagnose/checks.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from team_agent.profiles import effective_model, smoke_check_agent_profile, validate_agent_profile
+
+
+def profile_checks_for_agents(workspace: Path, agents: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [validate_agent_profile(workspace, agent) for agent in agents if not agent.get("paused")]
+
+
+def profile_smoke_checks_for_agents(workspace: Path, agents: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [smoke_check_agent_profile(workspace, agent) for agent in agents if not agent.get("paused")]
+
+
+def model_checks_for_agents(agents: list[dict[str, Any]], workspace: Path | None = None) -> list[dict[str, Any]]:
+    from team_agent.runtime import get_adapter
+    checks: list[dict[str, Any]] = []
+    for agent in agents:
+        if agent.get("paused"):
+            continue
+        if agent.get("auth_mode") == "compatible_api" and agent.get("provider") == "codex":
+            checks.append(
+                {
+                    "ok": True,
+                    "status": "profile_model_deferred_to_smoke",
+                    "provider": agent["provider"],
+                    "model": effective_model(agent, workspace),
+                    "agent_id": agent["id"],
+                }
+            )
+            continue
+        adapter = get_adapter(agent["provider"])
+        validator = getattr(adapter, "validate_model", None)
+        model = effective_model(agent, workspace)
+        if not callable(validator):
+            result = {"ok": True, "status": "not_checked", "provider": agent["provider"], "model": model}
+        else:
+            result = validator(model)
+            if not isinstance(result, dict):
+                result = {"ok": True, "status": "not_checked", "provider": agent["provider"], "model": model}
+        result = dict(result)
+        result.setdefault("provider", agent["provider"])
+        result.setdefault("model", model)
+        result["agent_id"] = agent["id"]
+        checks.append(result)
+    return checks
+
+
+def compact_model_checks(checks: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    compact: list[dict[str, Any]] = []
+    for item in checks:
+        compact.append(
+            {
+                key: item.get(key)
+                for key in ["agent_id", "provider", "model", "ok", "status", "reason", "suggested_model", "command"]
+                if key in item
+            }
+        )
+    return compact
+
+
+def format_model_check_failures(failures: list[dict[str, Any]]) -> str:
+    lines = ["model validation failed before starting worker windows:"]
+    for item in failures:
+        message = f"{item.get('agent_id')}: provider={item.get('provider')} model={item.get('model')!r}"
+        if item.get("suggested_model"):
+            message += f" is not an exact model id; use {item['suggested_model']!r}"
+        else:
+            message += f" is unsupported ({item.get('reason') or item.get('status')})"
+        lines.append(message)
+    return "\n".join(lines)
+
+
+def format_profile_check_failures(failures: list[dict[str, Any]]) -> str:
+    lines = ["profile validation failed before starting worker windows:"]
+    for item in failures:
+        message = f"{item.get('agent_id')}: profile={item.get('profile')!r} auth_mode={item.get('auth_mode')}"
+        if item.get("missing_required"):
+            message += f" missing {', '.join(item['missing_required'])}"
+        else:
+            message += f" failed ({item.get('reason') or item.get('status')})"
+        if item.get("suggestion"):
+            message += f"; {item['suggestion']}"
+        lines.append(message)
+    return "\n".join(lines)
+
+
+def format_profile_smoke_failures(failures: list[dict[str, Any]]) -> str:
+    lines = ["provider profile smoke check failed before starting worker windows:"]
+    for item in failures:
+        message = f"{item.get('agent_id')}: provider={item.get('provider')} profile={item.get('profile')!r}"
+        message += f" status={item.get('status')} reason={item.get('reason') or 'unknown'}"
+        if item.get("http_status"):
+            message += f" http_status={item['http_status']}"
+        if item.get("error"):
+            message += f"; {item['error']}"
+        message += "; fix the local profile file or model id, then start again"
+        lines.append(message)
+    return "\n".join(lines)

package/src/team_agent/diagnose/health.py

@@ -0,0 +1,241 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from team_agent.diagnose.checks import (
+    compact_model_checks,
+    model_checks_for_agents,
+    profile_checks_for_agents,
+)
+from team_agent.events import EventLog
+from team_agent.message_store import MessageStore
+from team_agent.paths import logs_dir, runtime_dir
+from team_agent.profiles import compact_profile_check
+from team_agent.spec import load_spec, workspace_from_spec
+from team_agent.state import load_runtime_state
+
+
+def diagnose(workspace: Path) -> dict[str, Any]:
+    from team_agent.runtime import (
+        _capture_has_team_orchestrator_mcp_prompt,
+        _leader_receiver_is_direct,
+        _tmux_session_exists,
+        _tmux_window_exists,
+        _validate_leader_receiver,
+        get_adapter,
+        run_cmd,
+        status,
+    )
+    _ = EventLog  # imported for symmetry / future use
+    state = load_runtime_state(workspace)
+    spec_path = Path(state.get("spec_path", workspace / "team.spec.yaml"))
+    spec = load_spec(spec_path) if spec_path.exists() else {}
+    store = MessageStore(workspace)
+    issues: list[dict[str, Any]] = []
+    suggested_repairs: list[dict[str, Any]] = [
+        {
+            "kind": "mcp_approval_prompt",
+            "action": "If a worker pane asks to allow team_orchestrator, select Allow for this session; then run team-agent collect.",
+        },
+        {
+            "kind": "codex_command_approval_prompt",
+            "action": "If a worker pane asks to run a shell command, approve only after checking the command; long servers should use pid/log/health-check protocol.",
+        },
+        {
+            "kind": "interrupted_worker",
+            "action": "Send: Continue from the current interrupted prompt. Do not redo completed work. Do the next bounded step, then report result_envelope_v1.",
+        },
+        {
+            "kind": "leader_receiver",
+            "action": "Worker-to-leader status requires a direct tmux leader receiver. Run team-agent attach-leader --workspace . --provider codex, or pass --pane <pane_id>.",
+        },
+        {
+            "kind": "process_list_unavailable",
+            "action": "If pgrep/lsof fail, use pid files, logs, and health-check URLs; record the environment blocker instead of retrying process-list commands.",
+        },
+    ]
+    session_name = state.get("session_name")
+    if session_name and not _tmux_session_exists(session_name):
+        issues.append(
+            {
+                "kind": "tmux_session_missing",
+                "session": session_name,
+                "reason": "tmux has no matching session",
+                "suggestion": "Run team-agent launch again or inspect .team/logs/events.jsonl for the shutdown/failure event.",
+            }
+        )
+    leader_receiver = state.get("leader_receiver", {})
+    if not _leader_receiver_is_direct(leader_receiver):
+        issues.append(
+            {
+                "kind": "leader_not_attached",
+                "mode": leader_receiver.get("mode", "fallback_inbox" if leader_receiver else "none"),
+                "suggestion": "Run team-agent attach-leader --workspace . --provider codex, or pass --pane <pane_id> for the existing Codex leader pane.",
+            }
+        )
+    else:
+        validation = _validate_leader_receiver(leader_receiver)
+        if not validation["ok"]:
+            issues.append(
+                {
+                    "kind": validation["reason"],
+                    "target": leader_receiver.get("pane_id"),
+                    "provider": leader_receiver.get("provider"),
+                    "error": validation.get("error"),
+                    "suggestion": "Run team-agent attach-leader --workspace . --provider codex again with a live Codex pane.",
+                }
+            )
+        elif validation.get("warning"):
+            issues.append(
+                {
+                    "kind": "leader_command_unexpected",
+                    "target": leader_receiver.get("pane_id"),
+                    "provider": leader_receiver.get("provider"),
+                    "command": validation.get("pane", {}).get("pane_current_command"),
+                    "warning": validation["warning"],
+                    "suggestion": "If this is not the real Codex leader pane, rerun attach-leader with --pane <pane_id>.",
+                }
+            )
+    for agent in spec.get("agents", []):
+        adapter = get_adapter(agent["provider"])
+        if not adapter.is_installed():
+            issues.append(
+                {
+                    "kind": "provider_missing",
+                    "agent_id": agent["id"],
+                    "provider": agent["provider"],
+                    "command": adapter.command_name,
+                    "suggestion": f"Install {adapter.command_name} and authenticate it before launch.",
+                }
+            )
+        mcp_path = runtime_dir(workspace) / "mcp" / f"{agent['id']}.json"
+        if not mcp_path.exists():
+            issues.append(
+                {
+                    "kind": "mcp_not_installed",
+                    "agent_id": agent["id"],
+                    "provider": agent["provider"],
+                    "path": str(mcp_path),
+                    "suggestion": "Run team-agent launch to regenerate provider MCP config.",
+                }
+            )
+        agent_state = state.get("agents", {}).get(agent["id"], {})
+        if agent_state.get("status") == "interrupted":
+            issues.append(
+                {
+                    "kind": "worker_interrupted",
+                    "agent_id": agent["id"],
+                    "suggestion": "Send the standard recovery prompt instead of redispatching the full task.",
+                }
+            )
+        window = agent_state.get("window", agent["id"])
+        if session_name and _tmux_window_exists(session_name, window):
+            proc = run_cmd(["tmux", "capture-pane", "-p", "-S", "-80", "-t", f"{session_name}:{window}"], timeout=5)
+            output = proc.stdout if proc.returncode == 0 else ""
+            if _capture_has_team_orchestrator_mcp_prompt(output):
+                issues.append(
+                    {
+                        "kind": "mcp_approval_prompt",
+                        "agent_id": agent["id"],
+                        "suggestion": "Team Agent will auto-approve allowlisted internal MCP prompts; if still blocked, inspect team-agent approvals.",
+                    }
+                )
+            if "Would you like to run the following command" in output:
+                issues.append(
+                    {
+                        "kind": "codex_command_approval_prompt",
+                        "agent_id": agent["id"],
+                        "suggestion": "Review and approve or reject the command in the worker pane; do not keep waiting silently.",
+                    }
+                )
+            if "Conversation interrupted" in output:
+                issues.append(
+                    {
+                        "kind": "worker_interrupted",
+                        "agent_id": agent["id"],
+                        "suggestion": "Send the standard recovery prompt instead of redispatching the full task.",
+                    }
+                )
+    timeout_sec = int(spec.get("communication", {}).get("ack_timeout_sec", 60)) if spec else 60
+    failed_messages = store.fail_timeouts(timeout_sec)
+    for message_id in failed_messages:
+        issues.append(
+            {
+                "kind": "message_ack_timeout",
+                "message_id": message_id,
+                "suggestion": "Check target worker status and scrollback; message stayed unacknowledged past timeout.",
+            }
+        )
+    return {
+        "ok": not issues,
+        "issues": issues,
+        "suggested_repairs": suggested_repairs,
+        "runtime": status(workspace, as_json=True),
+        "event_log": str(logs_dir(workspace) / "events.jsonl"),
+    }
+
+
+def doctor(spec_path: Path | None = None) -> dict[str, Any]:
+    from team_agent.runtime import _attach_team_profile_dirs, coordinator_health, get_adapter, shutil_which
+    providers = ["codex"]
+    spec = None
+    workspace = Path.cwd()
+    if spec_path:
+        spec = load_spec(spec_path)
+        workspace = workspace_from_spec(spec, spec_path)
+        _attach_team_profile_dirs(spec, spec_path, workspace)
+        providers = sorted({a["provider"] for a in spec.get("agents", []) if a["provider"] != "fake"})
+    checks: dict[str, Any] = {
+        "tmux": {
+            "installed": bool(shutil_which("tmux")),
+            "path": shutil_which("tmux"),
+        },
+        "workspace": str(workspace),
+        "workspace_is_git_repo": (workspace / ".git").exists(),
+        "providers": {},
+        "mcp": {
+            "server_command": shutil_which("team_orchestrator"),
+            "local_module": True,
+        },
+        "coordinator": coordinator_health(workspace),
+    }
+    for provider in providers:
+        adapter = get_adapter(provider)
+        checks["providers"][provider] = {
+            "command": adapter.command_name,
+            "installed": adapter.is_installed(),
+            "version": adapter.version(),
+            "auth": adapter.auth_hint(),
+        }
+    model_checks = model_checks_for_agents(spec.get("agents", []), workspace) if spec else []
+    if spec:
+        checks["models"] = compact_model_checks(model_checks)
+        profile_checks = profile_checks_for_agents(workspace, spec.get("agents", []))
+        checks["profiles"] = [compact_profile_check(item) for item in profile_checks]
+    missing_required = [
+        provider for provider, result in checks["providers"].items() if not result["installed"] and spec_path
+    ]
+    missing_auth = [
+        provider
+        for provider, result in checks["providers"].items()
+        if spec_path and result.get("auth", {}).get("status") == "missing"
+    ]
+    invalid_models = [item for item in model_checks if item.get("ok") is False]
+    invalid_profiles = [item for item in checks.get("profiles", []) if item.get("ok") is False]
+    checks["ok"] = (
+        checks["tmux"]["installed"]
+        and not missing_required
+        and not missing_auth
+        and not invalid_models
+        and not invalid_profiles
+    )
+    if missing_required:
+        checks["missing_required_providers"] = missing_required
+    if missing_auth:
+        checks["missing_provider_auth"] = missing_auth
+    if invalid_models:
+        checks["invalid_models"] = compact_model_checks(invalid_models)
+    if invalid_profiles:
+        checks["invalid_profiles"] = invalid_profiles
+    return checks

package/src/team_agent/diagnose/preflight.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+from team_agent.diagnose.checks import (
+    compact_model_checks,
+    model_checks_for_agents,
+    profile_checks_for_agents,
+    profile_smoke_checks_for_agents,
+)
+from team_agent.events import EventLog
+from team_agent.paths import logs_dir, team_workspace
+from team_agent.profiles import compact_profile_check
+from team_agent.rust_core import core_binary
+from team_agent.simple_yaml import dumps
+
+
+def preflight(team_dir: Path) -> dict[str, Any]:
+    from team_agent.compiler import compile_team
+    from team_agent.profiles import profile_dir
+    from team_agent.runtime import (
+        GHOSTTY_DISPLAY_BACKENDS,
+        _attach_team_profile_dirs,
+        _ghostty_command,
+        ensure_workspace_dirs,
+        shutil_which,
+    )
+
+    team_dir = team_dir.resolve()
+    workspace = team_workspace(team_dir)
+    ensure_workspace_dirs(workspace)
+    ensure_profiles_for_roles(team_dir)
+    event_log = EventLog(workspace)
+    checks: list[dict[str, Any]] = []
+    ok = True
+    spec = None
+    try:
+        compiled = compile_team(team_dir)
+        spec = compiled["spec"]
+        _attach_team_profile_dirs(spec, team_dir / "team.spec.yaml", workspace, team_dir)
+        checks.append({"name": "compile", "ok": True, "agents": [a["id"] for a in spec.get("agents", [])]})
+    except Exception as exc:
+        ok = False
+        checks.append({"name": "compile", "ok": False, "error": str(exc)})
+    tmux_path = shutil_which("tmux")
+    checks.append({"name": "tmux", "ok": bool(tmux_path), "path": tmux_path})
+    ok = ok and bool(tmux_path)
+    ghostty = _ghostty_command()
+    ghostty_check = {"name": "ghostty", "ok": bool(ghostty), "path": ghostty, "required": False}
+    if spec and spec.get("runtime", {}).get("display_backend") in GHOSTTY_DISPLAY_BACKENDS:
+        ghostty_check["required"] = True
+        ok = ok and bool(ghostty)
+    checks.append(ghostty_check)
+    if spec:
+        profile_checks = profile_checks_for_agents(workspace, spec.get("agents", []))
+        profile_failures = [item for item in profile_checks if item.get("ok") is False]
+        checks.append({"name": "profiles", "ok": not profile_failures, "checks": [compact_profile_check(item) for item in profile_checks]})
+        ok = ok and not profile_failures
+        smoke_checks = profile_smoke_checks_for_agents(workspace, spec.get("agents", []))
+        smoke_failures = [item for item in smoke_checks if item.get("ok") is False]
+        checks.append({"name": "profile_smoke", "ok": not smoke_failures, "checks": [compact_profile_check(item) for item in smoke_checks]})
+        ok = ok and not smoke_failures
+        model_checks = model_checks_for_agents(spec.get("agents", []), workspace)
+        model_failures = [item for item in model_checks if item.get("ok") is False]
+        checks.append({"name": "models", "ok": not model_failures, "checks": compact_model_checks(model_checks)})
+        ok = ok and not model_failures
+    core = core_binary()
+    checks.append(
+        {
+            "name": "rust_core",
+            "ok": True,
+            "required": False,
+            "available": bool(core),
+            "path": str(core) if core else None,
+            "status": "available" if core else "python_fallback",
+        }
+    )
+    checks.append({"name": "profile_dir", "ok": profile_dir(workspace).exists() or (team_dir / "profiles").exists()})
+    details_log = logs_dir(workspace) / f"preflight-{int(time.time())}.json"
+    details = {"team_dir": str(team_dir), "checks": checks}
+    details_log.write_text(json.dumps(details, indent=2, ensure_ascii=False), encoding="utf-8")
+    event_log.write("preflight.complete", ok=ok, details_log=str(details_log), checks=checks)
+    blockers = [] if ok else preflight_blockers(checks)
+    return {
+        "ok": ok,
+        "summary": "preflight passed" if ok else "preflight found blockers: " + "; ".join(blockers[:3]),
+        "next_actions": [f"team-agent start --team {team_dir} --yes --json"] if ok else preflight_next_actions(blockers),
+        "details_log": str(details_log),
+        "checks": checks,
+        "blockers": blockers,
+    }
+
+
+def start(team_dir: Path, yes: bool = False) -> dict[str, Any]:
+    from team_agent.compiler import compile_team
+    from team_agent.runtime import launch
+
+    team_dir = team_dir.resolve()
+    workspace = team_workspace(team_dir)
+    spec_path = team_dir / "team.spec.yaml"
+    compiled = compile_team(team_dir, spec_path)
+    if compiled["spec"].get("context", {}).get("state_file") == "team_state.md":
+        state_file = str(team_dir.relative_to(workspace) / "team_state.md") if team_dir.is_relative_to(workspace) else "team_state.md"
+        compiled["spec"]["context"]["state_file"] = state_file
+        spec_path.write_text(dumps(compiled["spec"]), encoding="utf-8")
+    launched = launch(spec_path, auto_approve=yes)
+    details_log = logs_dir(workspace) / f"start-{int(time.time())}.json"
+    details_log.write_text(json.dumps({"compile": compiled, "launch": launched}, indent=2, ensure_ascii=False), encoding="utf-8")
+    return {
+        "ok": bool(launched.get("ok")),
+        "summary": f"compiled {team_dir} and launched {len(launched.get('agents', []))} agents",
+        "next_actions": ["team-agent wait-ready --workspace . --timeout 120 --json"],
+        "details_log": str(details_log),
+        "spec": str(spec_path),
+        "launch": launched,
+    }
+
+
+def preflight_blockers(checks: list[dict[str, Any]]) -> list[str]:
+    blockers: list[str] = []
+    for check in checks:
+        if check.get("ok", True):
+            continue
+        name = check.get("name") or "check"
+        if name == "compile":
+            blockers.append(f"compile: {check.get('error')}")
+            continue
+        for item in check.get("checks", []) or []:
+            agent = item.get("agent_id") or item.get("profile") or "-"
+            reason = item.get("reason") or item.get("status") or "failed"
+            detail = f"{name}: {agent} {reason}"
+            if item.get("endpoint"):
+                detail += f" endpoint={item['endpoint']}"
+            if item.get("proxy_configured"):
+                detail += f" proxy={item.get('proxy_url') or item.get('proxy_scheme')}"
+            if item.get("proxy_source"):
+                detail += f" proxy_source={item['proxy_source']}"
+            if item.get("proxy_mode"):
+                detail += f" proxy_mode={item['proxy_mode']}"
+            if item.get("missing_required"):
+                detail += " missing=" + ",".join(item["missing_required"])
+            if item.get("effective_model"):
+                detail += f" model={item['effective_model']}"
+            if item.get("suggestion"):
+                detail += f" suggestion={item['suggestion']}"
+            blockers.append(detail)
+        if not check.get("checks"):
+            blockers.append(f"{name}: failed")
+    return blockers or ["unknown preflight blocker"]
+
+
+def preflight_next_actions(blockers: list[str]) -> list[str]:
+    actions = ["Fix failed checks, then rerun preflight."]
+    if any("proxy_connectivity_failed" in item for item in blockers):
+        actions.insert(0, "Allow the profile BASE_URL through the configured proxy, or disable the proxy for Team Agent startup.")
+    if any("proxy_source=ambient" in item for item in blockers):
+        actions.insert(0, "Current environment proxy is being used for this compatible_api worker; either fix that proxy for BASE_URL, set HTTPS_PROXY/HTTP_PROXY in the profile, or set PROXY_MODE=direct in the profile to bypass proxy for this worker.")
+    if any("missing=" in item or "profile_required_values_missing" in item for item in blockers):
+        actions.insert(
+            0,
+            "Ask the human user to fill the local profile file; agents must inspect only with `team-agent profile show <name> --workspace . --json` or the returned --team variant and must not read .team/*/profiles/*.env.",
+        )
+    if any("model_mismatch" in item or "does not match profile MODEL" in item for item in blockers):
+        actions.insert(0, "Keep the model in the profile MODEL field or make the role model exactly match it.")
+    return actions
+
+
+def ensure_profiles_for_roles(team_dir: Path) -> None:
+    from team_agent.compiler import _read_front_matter
+    from team_agent.profiles import ensure_profile_secret_boundary, ensure_profile_secret_boundary_dir, init_profile
+
+    workspace = team_workspace(team_dir)
+    profiles_dir = team_dir / "profiles"
+    profiles_dir.mkdir(parents=True, exist_ok=True)
+    ensure_profile_secret_boundary(workspace)
+    ensure_profile_secret_boundary_dir(profiles_dir)
+    for role_doc in sorted((team_dir / "agents").glob("*.md")):
+        meta, _ = _read_front_matter(role_doc)
+        profile = meta.get("profile")
+        auth_mode = meta.get("auth_mode") or "subscription"
+        if not profile:
+            continue
+        if not (profiles_dir / f"{profile}.env").exists() and not (profiles_dir / f"{profile}.example.env").exists():
+            init_profile(workspace, str(profile), str(auth_mode))
+            if auth_mode == "subscription":
+                body = f"AUTH_MODE=subscription\nPROFILE_NAME={profile}\n"
+            elif auth_mode == "official_api":
+                body = f"AUTH_MODE=official_api\nPROFILE_NAME={profile}\nAPI_KEY=\nMODEL=\n"
+            else:
+                body = f"AUTH_MODE={auth_mode}\nPROFILE_NAME={profile}\nBASE_URL=\nAPI_KEY=\nMODEL=\n"
+            (profiles_dir / f"{profile}.example.env").write_text(body, encoding="utf-8")