@team-agent/installer 0.2.11 → 0.3.0

package/crates/team-agent/src/main.rs

@@ -0,0 +1,41 @@
+//! `team-agent` 二进制入口。
+
+fn main() -> anyhow::Result<()> {
+    let mut args = std::env::args().skip(1);
+    let command = args.next();
+    if matches!(command.as_deref(), Some("fake-worker")) {
+        let mut workspace = None;
+        let mut agent_id = None;
+        while let Some(arg) = args.next() {
+            match arg.as_str() {
+                "--workspace" => workspace = args.next().map(std::path::PathBuf::from),
+                "--agent-id" => agent_id = args.next(),
+                other => return Err(anyhow::anyhow!("unknown fake-worker argument: {other}")),
+            }
+        }
+        let workspace = workspace
+            .ok_or_else(|| anyhow::anyhow!("fake-worker requires --workspace <path>"))?;
+        let agent_id = agent_id
+            .ok_or_else(|| anyhow::anyhow!("fake-worker requires --agent-id <id>"))?;
+        let stdin = std::io::stdin();
+        let stdout = std::io::stdout();
+        team_agent::fake_worker::run(&workspace, &agent_id, stdin.lock(), stdout.lock())
+            .map_err(|e| anyhow::anyhow!(e.to_string()))?;
+        return Ok(());
+    }
+    if matches!(command.as_deref(), Some("mcp-server")) {
+        let mut workspace = None;
+        while let Some(arg) = args.next() {
+            match arg.as_str() {
+                "--workspace" => workspace = args.next().map(std::path::PathBuf::from),
+                other => return Err(anyhow::anyhow!("unknown mcp-server argument: {other}")),
+            }
+        }
+        let workspace = workspace.unwrap_or(std::env::current_dir()?);
+        team_agent::mcp_server::main(&workspace, &[])?;
+        return Ok(());
+    }
+    let argv = std::env::args().skip(1).collect::<Vec<_>>();
+    let cwd = std::env::current_dir()?;
+    std::process::exit(team_agent::cli::run(&argv, &cwd).code());
+}

package/crates/team-agent/src/mcp_server/helpers.rs

@@ -0,0 +1,228 @@
+//! step 14a · mcp_server::helpers — pure regularization + shared free helpers.
+
+use std::io::Write as _;
+use std::path::Path;
+
+use serde::Serialize;
+use serde_json::Value;
+
+use crate::messaging::{DeliveryOutcome, MessageTarget};
+use crate::state::persist::load_runtime_state;
+
+use super::types::{NormalizedReportEnvelope, ToolError, ToolErrorReason};
+
+// ═══════════════════════════════════════════════════════════════════════════
+// MODULE HELPERS (tools.py:16-69) — pure regularization, contract-callable.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/// `_requires_ack_for_target` (`tools.py:16-19`): leader-only targets default to no
+/// ack; any non-leader target → requires ack.
+pub fn requires_ack_for_target(to: &MessageTarget) -> bool {
+    match to {
+        MessageTarget::Single(target) => !(target == "leader" || target == "Leader"),
+        MessageTarget::Broadcast => true,
+        MessageTarget::Fanout(targets) => targets
+            .iter()
+            .any(|target| !(target == "leader" || target == "Leader")),
+    }
+}
+
+/// `_is_worker_recipient` (`tools.py:22-27`): a single string target that is not
+/// `""`/`"*"`/`"leader"`/`"Leader"` → worker recipient (async accepted path).
+pub fn is_worker_recipient(to: &MessageTarget) -> bool {
+    match to {
+        MessageTarget::Single(target) => {
+            !(target.is_empty() || target == "*" || target == "leader" || target == "Leader")
+        }
+        MessageTarget::Broadcast | MessageTarget::Fanout(_) => false,
+    }
+}
+
+/// `_merge_tasks_by_id` (`tools.py:30-49`): dedupe a task list keyed by `id`,
+/// `prefer` entries winning on duplicates (so an earlier `done` is not regressed).
+pub fn merge_tasks_by_id(prefer: &[Value], fallback: &[Value]) -> Vec<Value> {
+    let mut seen = std::collections::BTreeSet::new();
+    let mut out = Vec::new();
+    for item in prefer.iter().chain(fallback.iter()) {
+        let Some(id) = item.get("id").and_then(Value::as_str) else {
+            continue;
+        };
+        if seen.insert(id.to_string()) && item.is_object() {
+            out.push(item.clone());
+        }
+    }
+    out
+}
+
+pub(crate) fn tool_error_reason_wire(reason: ToolErrorReason) -> &'static str {
+    match reason {
+        ToolErrorReason::UnknownTool => "unknown_tool",
+        ToolErrorReason::InvalidToolArguments => "invalid_tool_arguments",
+        ToolErrorReason::InternalRuntimeError => "internal_runtime_error",
+        ToolErrorReason::PeerNotInScope => "peer_not_in_scope",
+    }
+}
+
+pub(crate) fn normalize_token(value: Option<&str>) -> String {
+    value
+        .unwrap_or("")
+        .trim()
+        .to_ascii_lowercase()
+        .replace(['-', ' '], "_")
+}
+
+pub(crate) fn text_field(value: &Value, key: &str) -> Option<String> {
+    value.get(key).and_then(text_of_value)
+}
+
+pub(crate) fn text_of_value(value: &Value) -> Option<String> {
+    match value {
+        Value::Null => None,
+        Value::String(s) => non_empty_string(s).map(ToString::to_string),
+        Value::Number(n) => Some(n.to_string()),
+        Value::Bool(b) => Some(if *b { "True" } else { "False" }.to_string()),
+        Value::Array(_) | Value::Object(_) => None,
+    }
+}
+
+pub(crate) fn items_from_value(value: Option<&Value>) -> Vec<Value> {
+    match value {
+        Some(Value::Array(items)) => items.clone(),
+        Some(Value::Null) | None => Vec::new(),
+        Some(other) => vec![other.clone()],
+    }
+}
+
+pub(crate) fn non_empty_string(value: &str) -> Option<&str> {
+    let trimmed = value.trim();
+    if trimmed.is_empty() {
+        None
+    } else {
+        Some(trimmed)
+    }
+}
+
+pub(crate) fn enum_value<T: Serialize>(value: T) -> Value {
+    match serde_json::to_value(value) {
+        Ok(value) => value,
+        Err(_) => Value::Null,
+    }
+}
+
+pub(crate) fn json_dumps_default(value: &Value) -> String {
+    let mut bytes = Vec::new();
+    let mut ser = serde_json::Serializer::with_formatter(&mut bytes, PythonJsonFormatter);
+    if value.serialize(&mut ser).is_err() {
+        return "{}".to_string();
+    }
+    String::from_utf8(bytes).unwrap_or_else(|_| "{}".to_string())
+}
+
+struct PythonJsonFormatter;
+
+impl serde_json::ser::Formatter for PythonJsonFormatter {
+    fn begin_array_value<W: ?Sized + std::io::Write>(
+        &mut self,
+        writer: &mut W,
+        first: bool,
+    ) -> std::io::Result<()> {
+        if first {
+            Ok(())
+        } else {
+            writer.write_all(b", ")
+        }
+    }
+
+    fn begin_object_key<W: ?Sized + std::io::Write>(
+        &mut self,
+        writer: &mut W,
+        first: bool,
+    ) -> std::io::Result<()> {
+        if first {
+            Ok(())
+        } else {
+            writer.write_all(b", ")
+        }
+    }
+
+    fn begin_object_value<W: ?Sized + std::io::Write>(&mut self, writer: &mut W) -> std::io::Result<()> {
+        writer.write_all(b": ")
+    }
+}
+
+pub(crate) fn normalized_envelope_value(env: &NormalizedReportEnvelope) -> Value {
+    match serde_json::to_value(env) {
+        Ok(value) => value,
+        Err(_) => serde_json::json!({
+            "schema_version": "result_envelope_v1",
+            "task_id": env.task_id.as_str(),
+            "agent_id": env.agent_id.as_str(),
+            "status": "success",
+            "summary": env.summary,
+            "changes": [], "tests": [], "risks": [], "artifacts": [], "next_actions": []
+        }),
+    }
+}
+
+pub(crate) fn ensure_object(value: &mut Value) {
+    if !value.is_object() {
+        *value = Value::Object(serde_json::Map::new());
+    }
+}
+
+pub(crate) fn insert_array(obj: &mut serde_json::Map<String, Value>, key: &str, value: Option<&[Value]>) {
+    if let Some(items) = value {
+        obj.insert(key.to_string(), Value::Array(items.to_vec()));
+    }
+}
+
+pub(crate) fn tool_runtime_error(err: impl std::fmt::Display) -> ToolError {
+    ToolError::new(
+        ToolErrorReason::InternalRuntimeError,
+        ToolError::public_exception_message(&err.to_string(), "RuntimeError"),
+        "RuntimeError",
+    )
+}
+
+pub(crate) fn object_fields(value: Value) -> serde_json::Map<String, Value> {
+    match value {
+        Value::Object(map) => map,
+        other => {
+            let mut map = serde_json::Map::new();
+            map.insert("ok".to_string(), Value::Bool(true));
+            map.insert("value".to_string(), other);
+            map
+        }
+    }
+}
+
+pub(crate) fn delivery_outcome_value(out: &DeliveryOutcome) -> Value {
+    serde_json::json!({
+        "ok": out.ok,
+        "status": enum_value(out.status),
+        "message_id": out.message_id,
+    })
+}
+
+pub(crate) fn latest_task_for_assignee(workspace: &Path, agent_id: &str) -> Option<String> {
+    let state = load_runtime_state(workspace).ok()?;
+    let tasks = state.get("tasks").and_then(Value::as_array)?;
+    for task in tasks.iter().rev() {
+        let assignee = task.get("assignee").and_then(Value::as_str)?;
+        if assignee != agent_id {
+            continue;
+        }
+        let status = task
+            .get("status")
+            .and_then(Value::as_str)
+            .unwrap_or("")
+            .to_ascii_lowercase();
+        if matches!(status.as_str(), "done" | "success" | "failed" | "blocked" | "cancelled") {
+            continue;
+        }
+        if let Some(id) = task.get("id").and_then(text_of_value) {
+            return Some(id);
+        }
+    }
+    None
+}

package/crates/team-agent/src/mcp_server/mod.rs

@@ -0,0 +1,183 @@
+//! step 14a · mcp_server — stdio MCP server (`team_orchestrator`) over JSON-RPC 2.0.
+//!
+//! Card: `docs/phase0/subsystems/14-mcp_cli.md` (MCP half).
+//! Truth source (READ-ONLY) `team-agent-public` @ v0.2.11 / `439bef8`:
+//!   - `mcp_server/server.py`    — stdio loop + JSON-RPC route (`dispatch`/`handle_mcp`/`main`)
+//!   - `mcp_server/tools.py`     — `TeamOrchestratorTools`: the 12 typed tool handlers
+//!   - `mcp_server/contracts.py` — `TOOLS`: name/description/inputSchema (wire single-truth)
+//!   - `mcp_server/normalize.py` — result envelope / compact-result regularization
+//!   - `mcp_server/__init__.py`  — package re-export surface locked by boundary tests
+//!
+//! SCOPE — this is the TYPE + BEHAVIORAL-ENTRY-FN layer so RED contracts can both
+//! NAME the wire/envelope types AND CALL real handlers and assert against rich
+//! return values. It is "the thinnest shell": it owns the wire protocol shape, the
+//! tool-regularization rules, the error envelope, and identity/scope anchoring —
+//! everything durable is delegated to step 5/6/7/11/13. Bodies are
+//! `unimplemented!("step14 port: …")`.
+//!
+//! REUSE (do NOT redefine):
+//!   - [`MessageStore`] (step 7) — `request_human` creates the leader message row.
+//!   - [`EventLog`] (step 4) — `mcp.scope_resolved` / `mcp.send_message_refused` /
+//!     `mcp.identity_inference_failed` / `mcp.task_inference_failed` audit events.
+//!   - [`load_runtime_state`] / [`save_runtime_state`] (step 5 persist) — `assign_task`
+//!     / `update_state` read-modify-write; `get_visible_peers` reads team scope.
+//!   - [`messaging`] (step 11) — `send_message` / `report_result` / `collect` /
+//!     `stuck_list` / `stuck_cancel` delegated by the tool handlers.
+//!   - [`crate::model::enums`] (step 2) — [`ResultStatus`] / [`ChangeKind`] /
+//!     [`TestStatus`] / [`RiskSeverity`] are the normalized result-envelope value
+//!     enums; this layer ONLY does string-alias regularization onto them.
+//!   - [`AgentId`] / [`TaskId`] / [`TeamKey`] (step 2 ids) — identity/scope anchors.
+//!
+//! 铁律 (card §11, Rust 绝不重蹈 Python 坑):
+//!   - **scope 锚 env, 禁候选扫描** (C13-C17/bug-064/082): sender identity =
+//!     spawn-time `TEAM_AGENT_ID`; scope = `TEAM_AGENT_OWNER_TEAM_ID`. `to="*"`
+//!     defaults to the sender team; `scope="workspace"` is the only cross-team
+//!     opt-in. A peer not in scope → typed [`ToolError`] with
+//!     [`ToolErrorReason::PeerNotInScope`] — never leak other-team peer names.
+//!   - **错误信封冗余键** (server.py:98-106): `reason == error_code` and
+//!     `message == error` are byte-stable downstream contracts — preserved verbatim
+//!     in [`ToolError`]'s serialization, NOT "cleaned up".
+//!   - **notifications/* 不回包** (server.py:49-50): `notifications/*` → [`RpcMethod::
+//!     Notification`] → [`handle_mcp`] returns `None`; the loop `continue`s. Emitting
+//!     a frame here would corrupt the stdout JSON-RPC stream.
+//!   - **stdout 是传输通道** (server.py:135): every error is surfaced ON stdout as a
+//!     JSON-RPC frame; logs/warnings MUST go to stderr/file, never stdout.
+//!   - **worker-recipient 异步 accepted** (tools.py:176-183): a worker recipient with
+//!     a message_id → [`SendOutcome::WorkerAccepted`] carrying the byte-stable
+//!     `poll_via = "team-agent inbox <id>"`; leader/`*` → [`SendOutcome::Direct`].
+//!   - **兜底字符串字节级保留** (bug-085): `_infer_task_id` failure → `"manual"` (not
+//!     None); `_infer_agent_id` failure → `None` → caller routes to `"unknown"`.
+//!
+//! §10 deny: this subsystem is NOT a daemon/coordinator path, so the MCP shell does
+//! not force top-level `#![deny(unwrap/expect/panic)]` (leader decides at
+//! integration; card §109 carves out only `diagnose::comms::evaluate_idle_behavior`
+//! and `diagnose::orphan::*`, which live in the CLI/diagnose lane, not here). All
+//! fallible handlers return `Result<_, McpError>` regardless.
+
+// ROUND-0 skeleton: fn bodies are all unimplemented!() so imports/fields/methods are
+// not yet exercised; P2 porter removes this when implementing.
+#![allow(dead_code, unused_imports, unused_variables, clippy::result_large_err, clippy::doc_overindented_list_items, clippy::doc_lazy_continuation, clippy::io_other_error)]
+// §10:MCP stdio handlers 实现层禁 unwrap/expect/panic(unimplemented!() stub 不被拦);tests 子模块各自 allow。
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+use std::collections::BTreeSet;
+use std::io::Write as _;
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use thiserror::Error;
+
+// ── REUSE: step 2 model (ids + normalized-envelope value enums) ─────────────
+use crate::model::enums::{ChangeKind, ResultStatus, RiskSeverity, TestStatus};
+use crate::model::ids::{AgentId, TaskId, TeamKey};
+
+// ── REUSE: step 4 event_log / step 7 message_store ──────────────────────────
+use crate::event_log::EventLog;
+use crate::message_store::MessageStore;
+
+// ── REUSE: step 5 state persist / projection ────────────────────────────────
+use crate::state::persist::{load_runtime_state, save_runtime_state};
+
+// ── REUSE: step 11 messaging delegate surface ───────────────────────────────
+use crate::messaging::{self, DeliveryOutcome, MessageTarget, SendOptions};
+
+pub mod helpers;
+pub mod normalize;
+pub mod tools;
+pub mod types;
+pub mod wire;
+
+// ── re-export: 保持 `crate::mcp_server::X` 与 test `super::X` 解析不变 ─────────
+pub use helpers::*;
+pub use normalize::*;
+pub use tools::*;
+pub use types::*;
+pub use wire::*;
+
+// pub(crate) 子项 (normalize 的 list helpers、wire 的 dispatch_tool 等) 经此再导出,
+// 使 `#[cfg(test)] mod tests` 的 `use super::*` 与跨子模块引用解析不变。
+pub(crate) use helpers::{
+    delivery_outcome_value, ensure_object, enum_value, insert_array, latest_task_for_assignee,
+    non_empty_string, normalize_token, normalized_envelope_value, object_fields, text_field,
+    text_of_value, tool_error_reason_wire, tool_runtime_error,
+};
+pub(crate) use normalize::{
+    normalize_artifacts, normalize_changes, normalize_next_actions, normalize_risks, normalize_tests,
+};
+pub(crate) use wire::dispatch_tool;
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CROSS-DEP PLACEHOLDERS — step 13 lifecycle / team_state surface not yet in tree.
+// The 13/15 sibling lanes are in flight; do NOT guess their authoritative names.
+// Leader reconciles these at integration.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/// **PLACEHOLDER** — step 13 lifecycle `runtime.{stop,reset,add,fork}_agent`. The
+/// lifecycle lane is not yet in the tree; these tool handlers delegate to it. Minimal
+/// local stubs so the handler signatures compile and contracts can name the
+/// delegation. Leader swaps for the authoritative step-13 surface at integration.
+pub mod lifecycle_placeholder {
+    use super::*;
+
+    /// `runtime.stop_agent(workspace, agent_id)` (step 13).
+    pub fn stop_agent(workspace: &Path, agent_id: &str) -> Result<Value, McpError> {
+        let _ = workspace;
+        Ok(serde_json::json!({"ok": true, "status": "stopped", "agent_id": agent_id}))
+    }
+
+    /// `runtime.reset_agent(workspace, agent_id, discard_session)` (step 13).
+    pub fn reset_agent(workspace: &Path, agent_id: &str, discard_session: bool) -> Result<Value, McpError> {
+        let _ = workspace;
+        Ok(serde_json::json!({"ok": true, "status": "reset", "agent_id": agent_id, "discard_session": discard_session}))
+    }
+
+    /// `runtime.add_agent(workspace, new_agent_id, role_file_path)` (step 13).
+    pub fn add_agent(workspace: &Path, new_agent_id: &str, role_file_path: &str) -> Result<Value, McpError> {
+        let _ = workspace;
+        Ok(serde_json::json!({"ok": true, "status": "added", "agent_id": new_agent_id, "role_file_path": role_file_path}))
+    }
+
+    /// `runtime.fork_agent(workspace, source_agent_id, as_agent_id, label)` (step 13).
+    pub fn fork_agent(workspace: &Path, source_agent_id: &str, as_agent_id: &str, label: Option<&str>) -> Result<Value, McpError> {
+        let _ = workspace;
+        Ok(serde_json::json!({"ok": true, "status": "forked", "source_agent_id": source_agent_id, "agent_id": as_agent_id, "label": label}))
+    }
+
+    /// `runtime.status(workspace, as_json=true, compact=true)` (step 13 status
+    /// projection; `tools.py:328`).
+    pub fn runtime_status(workspace: &Path, compact: bool) -> Result<Value, McpError> {
+        let _ = (workspace, compact);
+        Ok(serde_json::json!({"ok": true, "status": "ok"}))
+    }
+
+    /// `state.write_team_state(workspace, spec, state)` (step 5/13 team_state.md
+    /// rewrite; `tools.py:324`). Step 5 persist exists, but this writer is not yet
+    /// exported; placeholder until the persist/lifecycle lane lands it.
+    pub fn write_team_state(workspace: &Path, spec: &Value, state: &Value) -> Result<PathBuf, McpError> {
+        let rel = spec
+            .get("context")
+            .and_then(|v| v.get("state_file"))
+            .and_then(Value::as_str)
+            .unwrap_or("team_state.md");
+        let path = workspace.join(rel);
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent)?;
+        }
+        let mut text = String::from("# Team State\n\n## Notes\n\n");
+        if let Some(notes) = state.get("notes").and_then(Value::as_array) {
+            for note in notes {
+                if let Some(note) = note.as_str() {
+                    text.push_str("- ");
+                    text.push_str(note);
+                    text.push('\n');
+                }
+            }
+        }
+        std::fs::write(&path, text)?;
+        Ok(path)
+    }
+}
+
+#[cfg(test)]
+mod tests;