@team-agent/installer 0.1.10 → 0.2.0

package/src/team_agent/mcp_server/__init__.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from team_agent import runtime
+from team_agent.mcp_server.contracts import TOOLS
+from team_agent.mcp_server.normalize import (
+    _compact_tool_result,
+    _normalize_report_envelope,
+    _items,
+    _text,
+    _first_text,
+    _normalize_result_status,
+    _normalize_changes,
+    _normalize_change_kind,
+    _normalize_tests,
+    _normalize_test_status,
+    _normalize_risks,
+    _normalize_artifacts,
+    _normalize_next_actions,
+)
+from team_agent.mcp_server.server import dispatch, handle_mcp, main
+from team_agent.mcp_server.tools import TeamOrchestratorTools
+
+__all__ = [
+    'TeamOrchestratorTools',
+    'TOOLS',
+    'dispatch',
+    'handle_mcp',
+    'main',
+    '_compact_tool_result',
+    '_normalize_report_envelope',
+    '_items',
+    '_text',
+    '_first_text',
+    '_normalize_result_status',
+    '_normalize_changes',
+    '_normalize_change_kind',
+    '_normalize_tests',
+    '_normalize_test_status',
+    '_normalize_risks',
+    '_normalize_artifacts',
+    '_normalize_next_actions',
+]

package/src/team_agent/mcp_server/__main__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from team_agent.mcp_server.server import main
+
+
+if __name__ == "__main__":
+    main()

package/src/team_agent/mcp_server/contracts.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+
+TOOLS = [
+    {
+        "name": "assign_task",
+        "description": "Add or update a task in the team graph and deliver it to its assignee.",
+        "inputSchema": {
+            "type": "object",
+            "required": ["task"],
+            "properties": {
+                "task": {"type": "object"},
+                "message": {"type": "string"},
+            },
+        },
+    },
+    {
+        "name": "send_message",
+        "description": "Send a message to a teammate, the leader, or '*' for all other team members. Provide only target and content; Team Agent fills sender, task id, ack policy, and delivery metadata.",
+        "inputSchema": {
+            "type": "object",
+            "required": ["to", "content"],
+            "properties": {
+                "to": {
+                    "oneOf": [
+                        {"type": "string"},
+                        {"type": "array", "items": {"type": "string"}, "minItems": 1},
+                    ]
+                },
+                "content": {"type": "string"},
+            },
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "report_result",
+        "description": "Report task completion. Provide a short summary and optional status/details; Team Agent fills schema_version, task_id, and agent_id, and normalizes common change/test field aliases.",
+        "inputSchema": {
+            "type": "object",
+            "required": ["summary"],
+            "properties": {
+                "summary": {"type": "string"},
+                "status": {"type": "string", "enum": ["success", "blocked", "failed", "partial"]},
+                "changes": {"type": "array", "items": {"type": "object"}},
+                "tests": {"type": "array", "items": {"type": "object"}},
+                "risks": {"type": "array", "items": {"type": "object"}},
+                "artifacts": {"type": "array", "items": {"type": "object"}},
+                "next_actions": {"type": "array", "items": {"type": "object"}},
+            },
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "update_state",
+        "description": "Append a note to team state and rewrite team_state.md.",
+        "inputSchema": {
+            "type": "object",
+            "required": ["note"],
+            "properties": {"note": {"type": "string"}},
+        },
+    },
+    {
+        "name": "get_team_status",
+        "description": "Return machine-readable team status.",
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+    {
+        "name": "stop_agent",
+        "description": "Hard-stop one running worker while preserving its session for start_agent resume.",
+        "inputSchema": {
+            "type": "object",
+            "required": ["agent_id"],
+            "properties": {"agent_id": {"type": "string"}},
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "reset_agent",
+        "description": "Reset one worker to a fresh session. discard_session must be true.",
+        "inputSchema": {
+            "type": "object",
+            "required": ["agent_id", "discard_session"],
+            "properties": {
+                "agent_id": {"type": "string"},
+                "discard_session": {"type": "boolean"},
+            },
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "add_agent",
+        "description": "Add a first-class worker from a workspace-relative role file.",
+        "inputSchema": {
+            "type": "object",
+            "required": ["new_agent_id", "role_file_path"],
+            "properties": {
+                "new_agent_id": {"type": "string"},
+                "role_file_path": {"type": "string"},
+            },
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "fork_agent",
+        "description": "Fork a running worker using the provider's native branch/fork support.",
+        "inputSchema": {
+            "type": "object",
+            "required": ["source_agent_id", "as_agent_id"],
+            "properties": {
+                "source_agent_id": {"type": "string"},
+                "as_agent_id": {"type": "string"},
+                "label": {"type": "string"},
+            },
+            "additionalProperties": False,
+        },
+    },
+    {
+        "name": "request_human",
+        "description": "Ask the leader/user for human input.",
+        "inputSchema": {
+            "type": "object",
+            "required": ["question"],
+            "properties": {
+                "question": {"type": "string"},
+                "task_id": {"type": "string"},
+                "agent_id": {"type": "string"},
+            },
+        },
+    },
+    {
+        "name": "stuck_list",
+        "description": "List manually suppressed idle-triggered alerts for this team.",
+        "inputSchema": {"type": "object", "properties": {}, "additionalProperties": False},
+    },
+    {
+        "name": "stuck_cancel",
+        "description": "Suppress repeated stuck/idle alerts for one agent until meaningful agent state changes.",
+        "inputSchema": {
+            "type": "object",
+            "required": ["agent_id"],
+            "properties": {
+                "agent_id": {"type": "string"},
+                "alert_type": {"type": "string", "enum": ["stuck", "idle_fallback", "all"]},
+            },
+            "additionalProperties": False,
+        },
+    },
+]

package/src/team_agent/mcp_server/normalize.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def _compact_tool_result(result: dict[str, Any]) -> dict[str, Any]:
+    if result.get("ok") is False:
+        keys = [
+            "ok",
+            "status",
+            "reason",
+            "error",
+            "message_id",
+            "agent_id",
+            "new_agent_id",
+            "source_agent_id",
+            "role_file_sha",
+            "session_id",
+            "to",
+            "targets",
+            "delivered_count",
+            "failed_count",
+            "fallback_path",
+            "suggestion",
+        ]
+        compact = {key: result[key] for key in keys if key in result}
+        if str(result.get("status") or "").startswith("fanout_"):
+            for key in ("deliveries", "recipients"):
+                if key in result:
+                    compact[key] = result[key]
+        return compact
+    keys = [
+        "ok",
+        "status",
+        "message_id",
+        "to",
+        "targets",
+        "delivered_count",
+        "failed_count",
+        "submitted",
+        "visible",
+        "queued",
+        "durably_stored",
+        "result_id",
+        "task_id",
+        "agent_id",
+        "new_agent_id",
+        "source_agent_id",
+        "role_file_sha",
+        "session_id",
+        "leader_notified",
+        "notification_message_id",
+        "notification_status",
+        "notification_channel",
+        "notification_event_id",
+    ]
+    compact = {key: result[key] for key in keys if key in result}
+    if str(result.get("status") or "").startswith("fanout_"):
+        for key in ("deliveries", "recipients"):
+            if key in result:
+                compact[key] = result[key]
+    if "acknowledged_messages" in result:
+        compact["acknowledged_count"] = len(result.get("acknowledged_messages") or [])
+    return compact or {"ok": True}
+
+
+def _normalize_report_envelope(env: dict[str, Any]) -> dict[str, Any]:
+    summary = _text(env.get("summary")) or "completed"
+    return {
+        "schema_version": "result_envelope_v1",
+        "task_id": _text(env.get("task_id")) or "manual",
+        "agent_id": _text(env.get("agent_id")) or "unknown",
+        "status": _normalize_result_status(env.get("status")),
+        "summary": summary,
+        "changes": _normalize_changes(env.get("changes"), summary),
+        "tests": _normalize_tests(env.get("tests")),
+        "risks": _normalize_risks(env.get("risks")),
+        "artifacts": _normalize_artifacts(env.get("artifacts")),
+        "next_actions": _normalize_next_actions(env.get("next_actions")),
+    }
+
+
+def _items(value: Any) -> list[Any]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    return [value]
+
+
+def _text(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def _first_text(item: dict[str, Any], *keys: str) -> str | None:
+    for key in keys:
+        text = _text(item.get(key))
+        if text:
+            return text
+    return None
+
+
+def _normalize_result_status(value: Any) -> str:
+    text = (_text(value) or "success").lower().replace("-", "_").replace(" ", "_")
+    mapping = {
+        "ok": "success",
+        "done": "success",
+        "complete": "success",
+        "completed": "success",
+        "passed": "success",
+        "pass": "success",
+        "blocked": "blocked",
+        "block": "blocked",
+        "failed": "failed",
+        "fail": "failed",
+        "error": "failed",
+        "partial": "partial",
+        "partially_done": "partial",
+    }
+    return mapping.get(text, text if text in {"success", "blocked", "failed", "partial"} else "success")
+
+
+def _normalize_changes(value: Any, fallback_summary: str) -> list[dict[str, str]]:
+    changes: list[dict[str, str]] = []
+    for item in _items(value):
+        if not isinstance(item, dict):
+            continue
+        path = _first_text(item, "path", "file", "filepath", "filename")
+        if not path:
+            continue
+        description = _first_text(item, "description", "summary", "detail", "details", "message") or fallback_summary
+        changes.append(
+            {
+                "path": path,
+                "kind": _normalize_change_kind(_first_text(item, "kind", "type", "action"), description),
+                "description": description,
+            }
+        )
+    return changes
+
+
+def _normalize_change_kind(value: str | None, description: str) -> str:
+    text = (value or "").strip().lower().replace("-", "_").replace(" ", "_")
+    if text in {"created", "modified", "deleted", "observed"}:
+        return text
+    mapping = {
+        "create": "created",
+        "added": "created",
+        "add": "created",
+        "new": "created",
+        "changed": "modified",
+        "change": "modified",
+        "updated": "modified",
+        "update": "modified",
+        "edited": "modified",
+        "edit": "modified",
+        "removed": "deleted",
+        "remove": "deleted",
+        "delete": "deleted",
+        "observe": "observed",
+        "observed": "observed",
+        "inspected": "observed",
+        "inspect": "observed",
+    }
+    if text in mapping:
+        return mapping[text]
+    description_text = description.lower()
+    if any(word in description_text for word in ["created", "added", "new file"]):
+        return "created"
+    if any(word in description_text for word in ["deleted", "removed"]):
+        return "deleted"
+    if any(word in description_text for word in ["observed", "inspected", "verified"]):
+        return "observed"
+    return "modified"
+
+
+def _normalize_tests(value: Any) -> list[dict[str, str]]:
+    tests: list[dict[str, str]] = []
+    for item in _items(value):
+        if not isinstance(item, dict):
+            command = _text(item)
+            if command:
+                tests.append({"command": command, "status": "not_run"})
+            continue
+        command = _first_text(item, "command", "cmd", "name", "test")
+        if not command:
+            continue
+        test = {"command": command, "status": _normalize_test_status(item.get("status"))}
+        detail = _first_text(item, "detail", "output", "stdout", "stderr", "summary", "message")
+        if detail:
+            test["detail"] = detail
+        tests.append(test)
+    return tests
+
+
+def _normalize_test_status(value: Any) -> str:
+    text = (_text(value) or "not_run").lower().replace("-", "_").replace(" ", "_")
+    mapping = {
+        "pass": "passed",
+        "ok": "passed",
+        "success": "passed",
+        "fail": "failed",
+        "error": "failed",
+        "notrun": "not_run",
+        "not_run": "not_run",
+        "notrun_yet": "not_run",
+        "skip": "skipped",
+    }
+    return mapping.get(text, text if text in {"passed", "failed", "not_run", "skipped"} else "not_run")
+
+
+def _normalize_risks(value: Any) -> list[dict[str, str]]:
+    risks: list[dict[str, str]] = []
+    for item in _items(value):
+        if not isinstance(item, dict):
+            description = _text(item)
+            if description:
+                risks.append({"severity": "low", "description": description})
+            continue
+        description = _first_text(item, "description", "summary", "detail", "message")
+        if not description:
+            continue
+        severity = (_first_text(item, "severity", "level") or "low").lower()
+        if severity not in {"low", "medium", "high"}:
+            severity = "low"
+        risks.append({"severity": severity, "description": description})
+    return risks
+
+
+def _normalize_artifacts(value: Any) -> list[dict[str, str]]:
+    artifacts: list[dict[str, str]] = []
+    for item in _items(value):
+        if not isinstance(item, dict):
+            path = _text(item)
+            if path:
+                artifacts.append({"path": path, "description": path})
+            continue
+        path = _first_text(item, "path", "file", "filepath", "filename")
+        if not path:
+            continue
+        artifacts.append({"path": path, "description": _first_text(item, "description", "summary", "detail") or path})
+    return artifacts
+
+
+def _normalize_next_actions(value: Any) -> list[dict[str, str]]:
+    actions: list[dict[str, str]] = []
+    for item in _items(value):
+        if isinstance(item, dict):
+            description = _first_text(item, "description", "summary", "action", "todo", "message")
+        else:
+            description = _text(item)
+        if description:
+            actions.append({"description": description})
+    return actions

package/src/team_agent/mcp_server/server.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from team_agent.mcp_server.contracts import TOOLS
+from team_agent.mcp_server.tools import TeamOrchestratorTools
+
+
+ARGUMENT_ERROR_TYPES = (TypeError, ValueError, KeyError, AttributeError)
+
+
+def dispatch(tools: TeamOrchestratorTools, request: dict[str, Any]) -> dict[str, Any]:
+    tool = request.get("tool") or request.get("method")
+    args = request.get("arguments") or request.get("params") or {}
+    if tool == "assign_task":
+        return tools.assign_task(**args)
+    if tool == "send_message":
+        return tools.send_message(**args)
+    if tool == "report_result":
+        return tools.report_result(**args)
+    if tool == "update_state":
+        return tools.update_state(**args)
+    if tool == "get_team_status":
+        return tools.get_team_status()
+    if tool == "stop_agent":
+        return tools.stop_agent(**args)
+    if tool == "reset_agent":
+        return tools.reset_agent(**args)
+    if tool == "add_agent":
+        return tools.add_agent(**args)
+    if tool == "fork_agent":
+        return tools.fork_agent(**args)
+    if tool == "request_human":
+        return tools.request_human(**args)
+    if tool == "stuck_list":
+        return tools.stuck_list()
+    if tool == "stuck_cancel":
+        return tools.stuck_cancel(**args)
+    return _tool_error_result("unknown_tool", f"unknown tool {tool!r}", exc_type="UnknownTool")
+
+
+def handle_mcp(tools: TeamOrchestratorTools, request: dict[str, Any]) -> dict[str, Any] | None:
+    method = request.get("method")
+    msg_id = request.get("id")
+    if method and method.startswith("notifications/"):
+        return None
+    if method == "initialize":
+        return {
+            "jsonrpc": "2.0",
+            "id": msg_id,
+            "result": {
+                "protocolVersion": request.get("params", {}).get("protocolVersion", "2024-11-05"),
+                "capabilities": {"tools": {}},
+                "serverInfo": {"name": "team_orchestrator", "version": "0.1.4"},
+            },
+        }
+    if method == "tools/list":
+        return {"jsonrpc": "2.0", "id": msg_id, "result": {"tools": TOOLS}}
+    if method == "tools/call":
+        params = request.get("params", {})
+        name = params.get("name")
+        arguments = params.get("arguments") or {}
+        try:
+            result = dispatch(tools, {"tool": name, "arguments": arguments})
+        except ARGUMENT_ERROR_TYPES as exc:
+            result = _tool_exception_result(exc, "invalid_tool_arguments")
+        except Exception as exc:
+            result = _tool_exception_result(exc, "internal_runtime_error")
+        is_error = result.get("ok") is False
+        return {
+            "jsonrpc": "2.0",
+            "id": msg_id,
+            "result": {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": json.dumps(result, ensure_ascii=False),
+                    }
+                ],
+                "isError": is_error,
+            },
+        }
+    return {
+        "jsonrpc": "2.0",
+        "id": msg_id,
+        "error": {"code": -32601, "message": f"unknown method {method!r}"},
+    }
+
+
+def _tool_exception_result(exc: Exception, reason: str) -> dict[str, str | bool]:
+    return _tool_error_result(reason, _public_exception_message(exc), exc_type=type(exc).__name__)
+
+
+def _tool_error_result(reason: str, message: str, exc_type: str) -> dict[str, str | bool]:
+    return {
+        "ok": False,
+        "reason": reason,
+        "error_code": reason,
+        "exc_type": exc_type,
+        "message": message,
+        "error": message,
+    }
+
+
+def _public_exception_message(exc: Exception) -> str:
+    message = str(exc).replace("\n", " ").strip()
+    return message[:200] if message else type(exc).__name__
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(description="TeamSpec team_orchestrator MCP stdio server")
+    parser.add_argument("--workspace", default=".", help="Workspace containing .team/runtime")
+    args = parser.parse_args(argv)
+    tools = TeamOrchestratorTools(Path(args.workspace))
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            request = json.loads(line)
+            if request.get("jsonrpc") == "2.0":
+                response = handle_mcp(tools, request)
+                if response is None:
+                    continue
+                sys.stdout.write(json.dumps(response, ensure_ascii=False) + "\n")
+                sys.stdout.flush()
+                continue
+            result = dispatch(tools, request)
+            sys.stdout.write(json.dumps({"ok": result.get("ok", True), "result": result}, ensure_ascii=False) + "\n")
+            sys.stdout.flush()
+        except Exception as exc:  # MCP transports need errors surfaced on stdout.
+            if "request" in locals() and isinstance(request, dict) and request.get("jsonrpc") == "2.0":
+                sys.stdout.write(
+                    json.dumps(
+                        {
+                            "jsonrpc": "2.0",
+                            "id": request.get("id"),
+                            "error": {"code": -32000, "message": str(exc)},
+                        },
+                        ensure_ascii=False,
+                    )
+                    + "\n"
+                )
+            else:
+                sys.stdout.write(json.dumps({"ok": False, "error": str(exc)}, ensure_ascii=False) + "\n")
+            sys.stdout.flush()