@team-agent/installer 0.1.10 → 0.2.0

package/src/team_agent/cli/parser.py

@@ -0,0 +1,470 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from team_agent import profiles
+from team_agent import runtime
+from team_agent.errors import TeamAgentError
+
+from team_agent.cli.commands import (
+    cmd_quick_start,
+    cmd_codex,
+    cmd_claude,
+    cmd_init,
+    cmd_validate,
+    cmd_compile,
+    cmd_profile_init,
+    cmd_profile_doctor,
+    cmd_profile_show,
+    cmd_launch,
+    cmd_preflight,
+    cmd_start,
+    cmd_wait_ready,
+    cmd_settle,
+    cmd_status,
+    cmd_approvals,
+    cmd_peek,
+    cmd_inbox,
+    cmd_sessions,
+    cmd_attach_leader,
+    cmd_takeover,
+    cmd_send,
+    cmd_collect,
+    cmd_diagnose,
+    cmd_repair_state,
+    cmd_validate_result,
+    cmd_doctor,
+    cmd_shutdown,
+    cmd_restart,
+    cmd_start_agent,
+    cmd_stop_agent,
+    cmd_reset_agent,
+    cmd_add_agent,
+    cmd_fork_agent,
+    cmd_remove_agent,
+    cmd_stuck_list,
+    cmd_stuck_cancel,
+    cmd_allow_peer_talk,
+    cmd_advanced,
+    cmd_install_skill,
+    cmd_run_overnight,
+
+)
+from team_agent.cli.e2e import cmd_e2e
+from team_agent.cli.helpers import (
+    _cli_error_payload,
+    _emit_cli_error,
+    _leader_launcher_args,
+    _provider_args,
+    emit,
+)
+
+
+SEND_ORDER_HINT = (
+    "options must appear before target/message. Use: "
+    "team-agent send --task <task_id> --json \"<message>\" or "
+    "team-agent send --no-ack --json <agent_id> \"<message>\""
+)
+
+
+class TeamAgentArgumentParser(argparse.ArgumentParser):
+    def error(self, message: str) -> None:
+        send_command = "send" in sys.argv[1:]
+        if (getattr(self, "send_order_hint", False) or send_command) and "unrecognized arguments" in message:
+            message = f"{message}\nHint: {SEND_ORDER_HINT}"
+        super().error(message)
+
+
+def main(argv: list[str] | None = None) -> None:
+    raw_argv = list(sys.argv[1:] if argv is None else argv)
+    if raw_argv and raw_argv[0] in {"codex", "claude"}:
+        _run_leader_passthrough(raw_argv[0], raw_argv[1:])
+        return
+
+    parser = TeamAgentArgumentParser(
+        prog="team-agent",
+        description="TeamSpec Agent Mode CLI",
+        epilog="See `team-agent advanced --help` for low-level commands (debugging only).",
+    )
+    sub = parser.add_subparsers(dest="command", required=True, parser_class=TeamAgentArgumentParser)
+
+    p = sub.add_parser("codex", help="Start a tmux-managed Codex leader in the current directory")
+    p.add_argument("provider_args", nargs=argparse.REMAINDER, help="Arguments passed through to codex")
+    p.set_defaults(func=cmd_codex)
+
+    p = sub.add_parser("claude", help="Start a tmux-managed Claude leader in the current directory")
+    p.add_argument("provider_args", nargs=argparse.REMAINDER, help="Arguments passed through to claude")
+    p.set_defaults(func=cmd_claude)
+
+    p = sub.add_parser("quick-start", help="Start a team from a role-doc directory")
+    p.add_argument("agents_dir")
+    p.add_argument("--name")
+    p.add_argument("--team-id", help="Store loose role docs under .team/<team-id> instead of .team/current")
+    p.add_argument("--yes", action="store_true")
+    p.add_argument("--fresh", action="store_true", help="Start fresh worker sessions even when prior runtime state exists")
+    add_json(p)
+    p.set_defaults(func=cmd_quick_start)
+
+    p = sub.add_parser("init", help=argparse.SUPPRESS)
+    p.add_argument("--workspace", default=".")
+    p.add_argument("--force", action="store_true")
+    add_json(p)
+    p.set_defaults(func=cmd_init)
+
+    p = sub.add_parser("validate", help=argparse.SUPPRESS)
+    p.add_argument("spec", nargs="?", default="team.spec.yaml")
+    add_json(p)
+    p.set_defaults(func=cmd_validate)
+
+    p = sub.add_parser("compile", help=argparse.SUPPRESS)
+    p.add_argument("--team", required=True, help="Team doc directory, for example .team/current")
+    p.add_argument("--out", default="team.spec.yaml")
+    add_json(p)
+    p.set_defaults(func=cmd_compile)
+
+    p = sub.add_parser("profile", help=argparse.SUPPRESS)
+    profile_sub = p.add_subparsers(dest="profile_command", required=True)
+    p_init = profile_sub.add_parser("init", help="Create an example profile template without real secrets")
+    p_init.add_argument("name")
+    p_init.add_argument("--workspace", default=".")
+    p_init.add_argument("--team", help="Team directory whose profiles/ directory should be used")
+    p_init.add_argument("--auth-mode", required=True, choices=sorted(profiles.AUTH_MODES))
+    add_json(p_init)
+    p_init.set_defaults(func=cmd_profile_init)
+    p_doctor = profile_sub.add_parser("doctor", help="Check whether a profile exists without printing secrets")
+    p_doctor.add_argument("name")
+    p_doctor.add_argument("--workspace", default=".")
+    p_doctor.add_argument("--team", help="Team directory whose profiles/ directory should be used")
+    add_json(p_doctor)
+    p_doctor.set_defaults(func=cmd_profile_doctor)
+    p_show = profile_sub.add_parser("show", help="Show redacted profile status without printing secrets")
+    p_show.add_argument("name")
+    p_show.add_argument("--workspace", default=".")
+    p_show.add_argument("--team", help="Team directory whose profiles/ directory should be used")
+    add_json(p_show)
+    p_show.set_defaults(func=cmd_profile_show)
+
+    p = sub.add_parser("launch", help=argparse.SUPPRESS)
+    p.add_argument("spec", nargs="?", default="team.spec.yaml")
+    p.add_argument("--yes", action="store_true", help="Confirm launch after permission summary review")
+    p.add_argument("--dry-run", action="store_true")
+    add_json(p)
+    p.set_defaults(func=cmd_launch)
+
+    p = sub.add_parser("preflight", help=argparse.SUPPRESS)
+    p.add_argument("--team", required=True)
+    add_json(p)
+    p.set_defaults(func=cmd_preflight)
+
+    p = sub.add_parser("start", help=argparse.SUPPRESS)
+    p.add_argument("--team", required=True)
+    p.add_argument("--yes", action="store_true")
+    add_json(p)
+    p.set_defaults(func=cmd_start)
+
+    p = sub.add_parser("wait-ready", help=argparse.SUPPRESS)
+    p.add_argument("--workspace", default=".")
+    p.add_argument("--timeout", type=int, default=120)
+    add_json(p)
+    p.set_defaults(func=cmd_wait_ready)
+
+    p = sub.add_parser("settle", help=argparse.SUPPRESS)
+    p.add_argument("--workspace", default=".")
+    add_json(p)
+    p.set_defaults(func=cmd_settle)
+
+    p = sub.add_parser("status", help="Show team runtime status")
+    p.add_argument("agent", nargs="?")
+    p.add_argument("--workspace", default=".")
+    p.add_argument("--detail", action="store_true", help="Include full raw runtime state in --json output")
+    add_json(p)
+    p.set_defaults(func=cmd_status)
+
+    p = sub.add_parser("approvals", help="Show structured pending worker approval prompts")
+    p.add_argument("agent", nargs="?")
+    p.add_argument("--workspace", default=".")
+    add_json(p)
+    p.set_defaults(func=cmd_approvals)
+
+    p = sub.add_parser("peek", help=argparse.SUPPRESS, description="Explicit raw-screen diagnostic only")
+    p.add_argument("agent")
+    p.add_argument("--workspace", default=".")
+    p.add_argument(
+        "--allow-raw-screen",
+        action="store_true",
+        help="Required after explicit user authorization to capture worker terminal output",
+    )
+    mode = p.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--head", type=int, help="Show the first N lines from the bounded recent capture")
+    mode.add_argument("--tail", type=int, help="Show the last N lines")
+    mode.add_argument("--search", help="Search the bounded recent capture and show matching context only")
+    p.add_argument("--context", type=int, default=3, help="Context lines around --search matches, max 10")
+    add_json(p)
+    p.set_defaults(func=cmd_peek)
+
+    p = sub.add_parser("inbox", help="Show message history for one agent")
+    p.add_argument("agent")
+    p.add_argument("--workspace", default=".")
+    p.add_argument("--limit", type=int, default=20)
+    add_json(p)
+    p.set_defaults(func=cmd_inbox)
+
+    p = sub.add_parser("sessions", help=argparse.SUPPRESS)
+    p.add_argument("--workspace", default=".")
+    add_json(p)
+    p.set_defaults(func=cmd_sessions)
+
+    p = sub.add_parser("attach-leader", help=argparse.SUPPRESS)
+    p.add_argument("--workspace", default=".")
+    p.add_argument("--pane", help="Explicit tmux pane id or target, for example %%173")
+    p.add_argument("--provider", default="codex")
+    add_json(p)
+    p.set_defaults(func=cmd_attach_leader)
+
+    p = sub.add_parser("takeover", help="Claim ownership of an existing team (multi-leader same workspace)")
+    p.add_argument("--workspace", default=".")
+    p.add_argument("--team", help="Explicit team/session selector when a workspace has multiple teams")
+    p.add_argument("--confirm", action="store_true", help="Required: confirm you intend to overwrite the recorded team_owner")
+    add_json(p)
+    p.set_defaults(func=cmd_takeover)
+
+    p = sub.add_parser(
+        "send",
+        help="Send a message to an agent, task assignee, or attached leader",
+        epilog=(
+            "Canonical examples:\n"
+            "  team-agent send --task <task_id> --json \"<message>\"\n"
+            "  team-agent send --no-ack --json <agent_id> \"<message>\""
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.send_order_hint = True
+    p.add_argument("target", nargs="?")
+    p.add_argument("message", nargs="+")
+    p.add_argument("--to", dest="targets", help="Comma-separated fan-out recipients, for example agent_a,agent_b")
+    p.add_argument("--workspace", default=".")
+    p.add_argument("--team", help="Explicit team/session target when a workspace has multiple teams")
+    p.add_argument("--task")
+    p.add_argument("--from", dest="sender", default="leader")
+    p.add_argument("--no-ack", action="store_true")
+    p.add_argument("--no-wait", action="store_true", help="Return after injection without visible verification")
+    p.add_argument(
+        "--watch-result",
+        action="store_true",
+        help="Return after delivery and let the coordinator collect/report the task result asynchronously",
+    )
+    p.add_argument("--timeout", type=float, default=30.0)
+    p.add_argument("--confirm-human", action="store_true", help="Confirm dispatch for a task marked human_confirmation: true")
+    add_json(p)
+    p.set_defaults(func=cmd_send)
+
+    p = sub.add_parser("collect", help=argparse.SUPPRESS)
+    p.add_argument("--workspace", default=".")
+    p.add_argument("--result-file")
+    add_json(p)
+    p.set_defaults(func=cmd_collect)
+
+    p = sub.add_parser("diagnose", help=argparse.SUPPRESS)
+    p.add_argument("--workspace", default=".")
+    add_json(p)
+    p.set_defaults(func=cmd_diagnose)
+
+    p = sub.add_parser("repair-state", help=argparse.SUPPRESS)
+    p.add_argument("--workspace", default=".")
+    p.add_argument("--task", required=True)
+    p.add_argument("--assignee")
+    p.add_argument("--status")
+    p.add_argument("--summary")
+    add_json(p)
+    p.set_defaults(func=cmd_repair_state)
+
+    p = sub.add_parser("validate-result", help=argparse.SUPPRESS)
+    p.add_argument("result", nargs="?", help="JSON string. If omitted, read stdin.")
+    p.add_argument("--file", help="Read JSON envelope from a file")
+    add_json(p)
+    p.set_defaults(func=cmd_validate_result)
+
+    p = sub.add_parser("doctor", help="Check local dependencies, providers, auth hints, tmux, and MCP")
+    p.add_argument("spec", nargs="?")
+    add_json(p)
+    p.set_defaults(func=cmd_doctor)
+
+    p = sub.add_parser("shutdown", help="Shutdown team tmux session and keep logs")
+    p.add_argument("--workspace", default=".")
+    p.add_argument("--team", help="Explicit team/session target when a workspace has multiple teams")
+    p.add_argument("--keep-logs", action="store_true", default=True)
+    add_json(p)
+    p.set_defaults(func=cmd_shutdown)
+
+    p = sub.add_parser("restart", help="Restart a stopped team from stored worker sessions")
+    p.add_argument("workspace", nargs="?", default=".")
+    p.add_argument("--team", help="Restart a specific stored team/session when the workspace has multiple teams")
+    p.add_argument("--allow-fresh", action="store_true", help="Allow fresh worker sessions if stored sessions cannot resume")
+    add_json(p)
+    p.set_defaults(func=cmd_restart)
+
+    p = sub.add_parser("start-agent", help="Start or repair one worker in the current team")
+    p.add_argument("agent")
+    p.add_argument("--workspace", default=".")
+    p.add_argument("--team", help="Explicit team/session target when a workspace has multiple teams")
+    p.add_argument("--force", action="store_true", help="Replace an existing tmux window for this worker")
+    p.add_argument("--allow-fresh", action="store_true", help="Allow a fresh session if the stored session cannot resume")
+    p.add_argument("--no-display", action="store_true", help="Do not open a Ghostty display window")
+    add_json(p)
+    p.set_defaults(func=cmd_start_agent)
+
+    p = sub.add_parser("stop-agent", help="Hard-stop one running worker while preserving its session for start-agent")
+    p.add_argument("agent")
+    p.add_argument("--workspace", default=".")
+    p.add_argument("--team", help="Explicit team/session target when a workspace has multiple teams")
+    add_json(p)
+    p.set_defaults(func=cmd_stop_agent)
+
+    p = sub.add_parser("reset-agent", help="Reset one worker to a fresh session after explicit confirmation")
+    p.add_argument("agent")
+    p.add_argument("--workspace", default=".")
+    p.add_argument("--team", help="Explicit team/session target when a workspace has multiple teams")
+    p.add_argument("--discard-session", action="store_true", help="Required: discard this worker's prior provider session")
+    p.add_argument("--no-display", action="store_true", help="Do not update a Ghostty display window")
+    add_json(p)
+    p.set_defaults(func=cmd_reset_agent)
+
+    p = sub.add_parser("add-agent", help="Add a first-class worker from an explicit workspace-relative role file")
+    p.add_argument("agent")
+    p.add_argument("--workspace", default=".")
+    p.add_argument("--team", help="Explicit team/session target when a workspace has multiple teams")
+    p.add_argument("--role-file", required=True, help="Workspace-relative YAML/Markdown agent entry")
+    p.add_argument("--no-display", action="store_true", help="Do not open a Ghostty display window")
+    add_json(p)
+    p.set_defaults(func=cmd_add_agent)
+
+    p = sub.add_parser("fork-agent", help="Fork a running worker using the provider's native branch/fork support")
+    p.add_argument("source_agent")
+    p.add_argument("--workspace", default=".")
+    p.add_argument("--team", help="Explicit team/session target when a workspace has multiple teams")
+    p.add_argument("--as", dest="as_agent", required=True, help="New worker agent id")
+    p.add_argument("--label", help="Optional audit label")
+    p.add_argument("--no-display", action="store_true", help="Do not open a Ghostty display window")
+    add_json(p)
+    p.set_defaults(func=cmd_fork_agent)
+
+    p = sub.add_parser("remove-agent", help="Remove one worker from runtime state and team spec")
+    p.add_argument("agent")
+    p.add_argument("--workspace", default=".")
+    p.add_argument("--team", help="Explicit team/session target when a workspace has multiple teams")
+    p.add_argument("--from-spec", action="store_true", help="Allow removing a spec-native worker")
+    p.add_argument("--confirm", action="store_true", help="Required with --from-spec")
+    p.add_argument("--force", action="store_true", help="Stop a running worker before removing it")
+    add_json(p)
+    p.set_defaults(func=cmd_remove_agent)
+
+    p = sub.add_parser("stuck-list", help="List manually suppressed idle-triggered alerts")
+    p.add_argument("--workspace", default=".")
+    add_json(p)
+    p.set_defaults(func=cmd_stuck_list)
+
+    p = sub.add_parser("stuck-cancel", help="Suppress repeated stuck/idle alerts for one agent")
+    p.add_argument("agent")
+    p.add_argument("--workspace", default=".")
+    p.add_argument("--alert-type", choices=["stuck", "idle_fallback", "all"], default="stuck")
+    add_json(p)
+    p.set_defaults(func=cmd_stuck_cancel)
+
+    p = sub.add_parser("install-skill", help=argparse.SUPPRESS)
+    p.add_argument("--target", choices=["codex", "claude", "all"], default="codex")
+    p.add_argument("--dest", help="Explicit destination directory; overrides --target")
+    p.add_argument("--dry-run", action="store_true")
+    add_json(p)
+    p.set_defaults(func=cmd_install_skill)
+
+    p = sub.add_parser("e2e", help=argparse.SUPPRESS)
+    p.add_argument("--providers", default="fake")
+    p.add_argument("--workspace")
+    p.add_argument("--real", action="store_true", help="Launch real provider CLIs; may use authenticated accounts")
+    add_json(p)
+    p.set_defaults(func=cmd_e2e)
+
+    p = sub.add_parser("allow-peer-talk", help=argparse.SUPPRESS)
+    p.add_argument("agent_a")
+    p.add_argument("agent_b")
+    p.add_argument("--workspace", default=".")
+    add_json(p)
+    p.set_defaults(func=cmd_allow_peer_talk)
+
+    p = sub.add_parser(
+        "run-overnight",
+        help="Run an orchestrator plan that advances on report_result and halts on failure",
+    )
+    p.add_argument("--workspace", default=".")
+    p.add_argument("--plan", help="Path to plan YAML (required unless --status without --plan-id)")
+    p.add_argument("--no-start", action="store_true", help="Persist plan state without dispatching stage 1 (default: dispatch)")
+    p.add_argument("--status", action="store_true", help="Show plan status instead of starting")
+    p.add_argument("--halt", action="store_true", help="Halt the plan named by --plan-id")
+    p.add_argument("--plan-id", help="Plan id for --status or --halt")
+    p.add_argument("--reason", default="user_requested", help="Halt reason for --halt")
+    add_json(p)
+    p.set_defaults(func=cmd_run_overnight)
+
+    p = sub.add_parser(
+        "advanced",
+        help=argparse.SUPPRESS,
+        description="Low-level Team Agent commands",
+        epilog=(
+            "Commands: init validate compile profile launch preflight start wait-ready settle "
+            "sessions attach-leader collect diagnose repair-state validate-result install-skill e2e"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.set_defaults(func=cmd_advanced)
+
+    sub._choices_actions = [  # type: ignore[attr-defined]
+        action for action in sub._choices_actions if action.help != argparse.SUPPRESS  # type: ignore[attr-defined]
+    ]
+    sub.metavar = "{codex,claude,quick-start,send,status,approvals,inbox,shutdown,restart,start-agent,stop-agent,reset-agent,add-agent,fork-agent,remove-agent,stuck-list,stuck-cancel,doctor}"
+
+    args = parser.parse_args(raw_argv)
+    try:
+        result = args.func(args)
+    except TeamAgentError as exc:
+        _emit_cli_error(exc, args)
+        raise SystemExit(1)
+    except Exception as exc:
+        _emit_cli_error(exc, args)
+        raise SystemExit(1)
+    emit(result, getattr(args, "json", False))
+    if isinstance(result, dict) and result.get("ok") is False:
+        raise SystemExit(1)
+
+
+def add_json(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--json", action="store_true", help="Emit stable machine-readable JSON")
+
+
+def _run_leader_passthrough(command: str, provider_args: list[str]) -> None:
+    if provider_args in (["-h"], ["--help"]):
+        print(f"usage: team-agent {command} [--attach --confirm | --attach-session SESSION --confirm] [args passed to {command}]")
+        print()
+        print(f"Start a tmux-managed {command} leader in the current directory.")
+        print("Default starts a new independent leader session; explicit attach requires --confirm.")
+        print(f"Use `team-agent {command} -- --help` to pass --help to the provider CLI.")
+        return
+    args = argparse.Namespace(command=command, workspace=".")
+    try:
+        provider = "codex" if command == "codex" else "claude_code"
+        launcher_args = _leader_launcher_args(provider_args)
+        runtime.start_leader(
+            provider,
+            _provider_args(launcher_args["provider_args"]),
+            Path.cwd().resolve(),
+            attach_existing=launcher_args["attach_existing"],
+            confirm_attach=launcher_args["confirm_attach"],
+            attach_session=launcher_args["attach_session"],
+        )
+    except TeamAgentError as exc:
+        _emit_cli_error(exc, args)
+        raise SystemExit(1)
+    except Exception as exc:
+        _emit_cli_error(exc, args)
+        raise SystemExit(1)

package/src/team_agent/compiler.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import copy
 from pathlib import Path
 from typing import Any
 
@@ -39,40 +40,19 @@ def compile_team(team_dir: Path, out_path: Path | None = None) -> dict[str, Any]
     routing_rules = []
     startup_order = []
     for role_doc in sorted(agents_dir.glob("*.md")):
-        meta, body = _read_front_matter(role_doc)
-        if "auth_mode" not in meta and default_auth_mode is not None:
-            meta["auth_mode"] = default_auth_mode
-        if "profile" not in meta and default_profile is not None:
-            meta["profile"] = default_profile
-        profile_model = _profile_model(workspace, meta.get("profile"), team_dir / "profiles")
-        if (
-            "model" not in meta
-            and not (meta.get("auth_mode") == "compatible_api" and profile_model)
-        ):
-            meta["model"] = _default_model_for_provider(meta.get("provider"), provider_models, default_model)
-        _validate_role_doc(role_doc, meta, body, profile_names, profile_model)
+        meta, body = _role_doc_meta_for_team(
+            role_doc,
+            team_meta,
+            workspace,
+            team_dir,
+            profile_names,
+            default_auth_mode,
+            default_profile,
+            provider_models,
+            default_model,
+        )
         agent_id = str(meta["name"])
-        tools = _normalize_tools(list(meta["tools"] or []))
-        agent = {
-            "id": agent_id,
-            "role": str(meta["role"]),
-            "provider": str(meta["provider"]),
-            "model": str(meta["model"]) if meta.get("model") is not None else None,
-            "auth_mode": str(meta["auth_mode"]),
-            "working_directory": str(workspace),
-            "system_prompt": {"inline": body.strip() or str(meta["role"]), "file": None},
-            "tools": tools,
-            "permission_mode": "restricted",
-            "preferred_for": [agent_id, str(meta["role"])],
-            "avoid_for": [],
-            "output_contract": {
-                "format": "result_envelope_v1",
-                "required_fields": ["task_id", "status", "summary", "artifacts"],
-            },
-        }
-        if meta.get("profile"):
-            agent["profile"] = str(meta["profile"])
-            agent["credential_ref"] = f"profile:{meta['profile']}"
+        agent = _agent_from_role_doc(meta, body, workspace, agent_id)
         agents.append(agent)
         routing_rules.append({"id": f"route-{agent_id}", "match": {"assignee": [agent_id]}, "assign_to": agent_id, "priority": 10})
         startup_order.append(agent_id)
@@ -155,6 +135,41 @@ def compile_team(team_dir: Path, out_path: Path | None = None) -> dict[str, Any]
     return {"ok": True, "team_dir": str(team_dir), "out": str(out_path) if out_path else None, "spec": spec}
 
 
+def compile_role_doc_agent(role_doc: Path, team_dir: Path, agent_id: str | None = None) -> dict[str, Any]:
+    meta, body = _read_front_matter(role_doc.resolve())
+    return compile_role_entry_agent(role_doc.resolve(), team_dir, meta, body, agent_id)
+
+
+def compile_role_entry_agent(
+    role_doc: Path,
+    team_dir: Path,
+    meta: dict[str, Any],
+    body: str,
+    agent_id: str | None = None,
+) -> dict[str, Any]:
+    team_dir = team_dir.resolve()
+    workspace = team_workspace(team_dir)
+    team_doc = team_dir / "TEAM.md"
+    if not team_doc.exists():
+        raise ValidationError(f"{team_doc}: missing TEAM.md")
+    profile_names = known_profiles(team_dir)
+    team_meta, _team_body = _read_front_matter(team_doc)
+    meta, body = _role_doc_meta_for_team(
+        role_doc,
+        team_meta,
+        workspace,
+        team_dir,
+        profile_names,
+        team_meta.get("default_auth_mode") or "subscription",
+        team_meta.get("default_profile"),
+        _provider_model_defaults(team_meta),
+        team_meta.get("default_model") or team_meta.get("model"),
+        role_meta=meta,
+        role_body=body,
+    )
+    return _agent_from_role_doc(meta, body, workspace, str(agent_id or meta["name"]))
+
+
 def _read_front_matter(path: Path) -> tuple[dict[str, Any], str]:
     text = path.read_text(encoding="utf-8")
     if not text.startswith("---\n"):
@@ -170,6 +185,56 @@ def _read_front_matter(path: Path) -> tuple[dict[str, Any], str]:
     return data, body
 
 
+def _role_doc_meta_for_team(
+    role_doc: Path,
+    team_meta: dict[str, Any],
+    workspace: Path,
+    team_dir: Path,
+    profile_names: set[str],
+    default_auth_mode: Any,
+    default_profile: Any,
+    provider_models: dict[str, str],
+    default_model: Any,
+    role_meta: dict[str, Any] | None = None,
+    role_body: str | None = None,
+) -> tuple[dict[str, Any], str]:
+    meta, body = (role_meta, role_body) if role_meta is not None and role_body is not None else _read_front_matter(role_doc)
+    meta = copy.deepcopy(meta)
+    if "auth_mode" not in meta and default_auth_mode is not None:
+        meta["auth_mode"] = default_auth_mode
+    if "profile" not in meta and default_profile is not None:
+        meta["profile"] = default_profile
+    profile_model = _profile_model(workspace, meta.get("profile"), team_dir / "profiles")
+    if "model" not in meta and not (meta.get("auth_mode") == "compatible_api" and profile_model):
+        meta["model"] = _default_model_for_provider(meta.get("provider"), provider_models, default_model)
+    _validate_role_doc(role_doc, meta, body, profile_names, profile_model)
+    return meta, body
+
+
+def _agent_from_role_doc(meta: dict[str, Any], body: str, workspace: Path, agent_id: str) -> dict[str, Any]:
+    agent = {
+        "id": agent_id,
+        "role": str(meta["role"]),
+        "provider": str(meta["provider"]),
+        "model": str(meta["model"]) if meta.get("model") is not None else None,
+        "auth_mode": str(meta["auth_mode"]),
+        "working_directory": str(workspace),
+        "system_prompt": {"inline": body.strip() or str(meta["role"]), "file": None},
+        "tools": _normalize_tools(list(meta["tools"] or [])),
+        "permission_mode": "restricted",
+        "preferred_for": [agent_id, str(meta["role"])],
+        "avoid_for": [],
+        "output_contract": {
+            "format": "result_envelope_v1",
+            "required_fields": ["task_id", "status", "summary", "artifacts"],
+        },
+    }
+    if meta.get("profile"):
+        agent["profile"] = str(meta["profile"])
+        agent["credential_ref"] = f"profile:{meta['profile']}"
+    return agent
+
+
 def _validate_role_doc(
     path: Path,
     meta: dict[str, Any],

package/src/team_agent/coordinator/__init__.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from typing import Any
+
+from team_agent.coordinator.lifecycle import (
+    coordinator_health,
+    coordinator_tick,
+    message_store_schema_health,
+    start_coordinator,
+    stop_coordinator,
+)
+from team_agent.coordinator.metadata import (
+    COORDINATOR_PROTOCOL_VERSION,
+    coordinator_metadata_ok,
+    pid_is_running,
+    read_coordinator_metadata,
+    write_coordinator_metadata,
+)
+from team_agent.coordinator.paths import (
+    coordinator_log_path,
+    coordinator_meta_path,
+    coordinator_pid_path,
+)
+
+__all__ = [
+    "COORDINATOR_PROTOCOL_VERSION",
+    "coordinator_health",
+    "coordinator_log_path",
+    "coordinator_meta_path",
+    "coordinator_metadata_ok",
+    "coordinator_pid_path",
+    "coordinator_tick",
+    "main",
+    "message_store_schema_health",
+    "pid_is_running",
+    "read_coordinator_metadata",
+    "start_coordinator",
+    "stop_coordinator",
+    "write_coordinator_metadata",
+]
+
+
+def __getattr__(name: str) -> Any:
+    # Lazy re-export of the daemon entry so the pyproject console_script
+    # `team-agent-coordinator = "team_agent.coordinator:main"` keeps
+    # resolving after the package split, without triggering the runtime
+    # <-> coordinator import cycle that an eager top-level
+    # `from team_agent.coordinator.__main__ import main` would cause
+    # (runtime imports coordinator/__init__ at module load).
+    if name == "main":
+        from team_agent.coordinator.__main__ import main as _main
+        return _main
+    raise AttributeError(f"module 'team_agent.coordinator' has no attribute {name!r}")