@team-agent/installer 0.5.66 → 0.5.68

package/crates/team-agent/src/lifecycle/worker_command_context.rs

@@ -1,3 +1,23 @@
+//! ---
+//! purpose: 从 spec 里的一个 agent 定义，编译出 worker 启动所需的系统提示词与工具串
+//! contract:
+//!   provides:
+//!     - name: WorkerCommandAgent
+//!       what: 从 YAML 或 JSON 读出的单 agent 命令上下文
+//!     - name: compile_worker_system_prompt
+//!       what: 按身份、runtime 契约、通信模式、角色正文、输出契约、权限说明拼系统提示词
+//!     - name: resolved_tool_strings_for_command
+//!       what: 解析出该 agent 的工具串，声明了 bypass 时追加 dangerous_auto_approve 哨兵
+//!   depends:
+//!     - crate::model::permissions
+//!     - crate::communication_mode
+//!     - crate::provider::bypass_flags
+//! boundary:
+//!   - 只产出字符串，不 spawn 进程、不写盘
+//!   - bypass 只认 agent 自身声明，不从 team/runtime/leader argv 继承
+//!   - provider 没有 bypass argv 定义时报错，不静默降级
+//! maturity: wired
+//! ---
 use std::path::Path;
 
 use crate::communication_mode::CommunicationMode;
@@ -13,9 +33,9 @@ output. All communication must go through Team Agent MCP tools.
 
 ## Communication (mandatory)
 
-- Coordinate with teammate: team_orchestrator.send_message(to='<agent_id>', content='...')
-- Broadcast to all teammates: team_orchestrator.send_message(to='*', content='...')
-- Task complete: team_orchestrator.report_result(summary='...') — call exactly once
+- Coordinate with teammate: {send_message}(to='<agent_id>', content='...')
+- Broadcast to all teammates: {send_message}(to='*', content='...')
+- Task complete: {report_result}(summary='...') — call exactly once
 
 ## Rules
 
@@ -29,7 +49,7 @@ output. All communication must go through Team Agent MCP tools.
 // semantics (leader-attach dependence + fallback status) that the
 // generic runtime section deliberately leaves out.
 const RESULT_ENVELOPE_OUTPUT_CONTRACT: &str =
-    "Final completion must call team_orchestrator.report_result exactly once with a short summary \
+    "Final completion must call {report_result} exactly once with a short summary \
 and optional status/changes/tests; the MCP runtime injects the result into the attached leader pane. \
 If no leader is attached, the tool returns a fallback/failed result instead of completion.";
 
@@ -47,6 +67,16 @@ pub(crate) struct WorkerCommandAgent {
 }
 
 impl WorkerCommandAgent {
+/// ---
+/// purpose: 从 spec 的 YAML agent 节点读出命令上下文
+/// params:
+///   agent: 单个 agent 的 YAML 节点
+///   fallback_id: agent 节点没写 id 时的兜底 id
+///   provider: 已解析的 provider
+/// returns: 填好的 WorkerCommandAgent
+/// errors: communication_mode 取值非法时返回 LifecycleError
+/// contract_id: lifecycle.worker_command_agent.from_source
+/// ---
     pub(crate) fn from_yaml(
         agent: &crate::model::yaml::Value,
         fallback_id: Option<&str>,
@@ -101,6 +131,16 @@ impl WorkerCommandAgent {
         })
     }
 
+/// ---
+/// purpose: 从 runtime state 的 JSON agent 节点读出命令上下文
+/// params:
+///   agent: 单个 agent 的 JSON 节点
+///   fallback_id: agent 节点没写 id 时的兜底 id
+///   provider: 已解析的 provider
+/// returns: 填好的 WorkerCommandAgent
+/// errors: communication_mode 取值非法时返回 LifecycleError
+/// contract_id: lifecycle.worker_command_agent.from_source
+/// ---
     pub(crate) fn from_json(
         agent: &serde_json::Value,
         fallback_id: Option<&str>,
@@ -156,6 +196,11 @@ impl WorkerCommandAgent {
     }
 }
 
+/// ---
+/// purpose: 拼出 worker 的系统提示词，身份段必须排在最前
+/// returns: 各段以空行分隔的提示词，空段被丢弃
+/// errors: 角色正文读取失败或权限解析失败时返回 LifecycleError
+/// ---
 pub(crate) fn compile_worker_system_prompt(
     agent: &WorkerCommandAgent,
 ) -> Result<String, LifecycleError> {
@@ -163,13 +208,15 @@ pub(crate) fn compile_worker_system_prompt(
     // identity line anchors the very first section (live Python worker argv confirms).
     // C-1 cr verdict / B2 灵魂件 — identity 必须 FIRST(MUST-4 行为层守:空白上下文问
     // "你是谁"必须先答 Team Agent worker 身份)。runtime contract 跟后。
+    let send_message = mcp_tool_name(agent.provider, "team_orchestrator", "send_message");
+    let report_result = mcp_tool_name(agent.provider, "team_orchestrator", "report_result");
     let mut chunks = vec![
         identity_section(agent),
-        runtime_contract_section(),
-        agent.communication_mode.runtime_contract().to_string(),
+        runtime_contract_section(&send_message, &report_result),
+        agent.communication_mode.runtime_contract(&send_message),
         role_body(agent)?,
     ];
-    if let Some(contract) = output_contract(agent) {
+    if let Some(contract) = output_contract(agent, &report_result) {
         chunks.push(contract);
     }
     if let Some(notes) = permission_notes(agent)? {
@@ -182,6 +229,13 @@ pub(crate) fn compile_worker_system_prompt(
         .join("\n\n"))
 }
 
+/// ---
+/// purpose: 解析该 agent 最终生效的工具串
+/// params:
+///   provider: 用于查 bypass argv 定义的 provider
+/// returns: 排序后的工具串；agent 声明 bypass 时末尾追加 dangerous_auto_approve
+/// errors: 权限解析失败，或声明了 bypass 但该 provider 没有 bypass argv 定义时返回 RequirementUnmet
+/// ---
 pub(crate) fn resolved_tool_strings_for_command(
     agent: &WorkerCommandAgent,
     provider: Provider,
@@ -212,6 +266,22 @@ pub(crate) fn resolved_tool_strings_for_command(
     Ok(tools)
 }
 
+/// Provider-facing MCP tool name. Only verified call forms are filled in.
+/// Unverified providers keep the historical dotted spelling.
+fn mcp_tool_name(provider: Provider, server: &str, tool: &str) -> String {
+    match provider {
+        Provider::Claude | Provider::ClaudeCode => format!("mcp__{server}__{tool}"),
+        Provider::Grok => format!("{server}__{tool}"),
+        // CursorAgent / Codex / Copilot / GeminiCli / Fake: 未验证，沿用现状点号。
+        // CursorAgent 不可与 grok 同臂：仓库里没有活转录，`{server}__{tool}` 是推断。
+        Provider::CursorAgent
+        | Provider::Codex
+        | Provider::Copilot
+        | Provider::GeminiCli
+        | Provider::Fake => format!("{server}.{tool}"),
+    }
+}
+
 fn provider_display_name(provider: Provider) -> &'static str {
     match provider {
         Provider::Claude => "claude",
@@ -219,6 +289,8 @@ fn provider_display_name(provider: Provider) -> &'static str {
         Provider::Codex => "codex",
         Provider::Copilot => "copilot",
         Provider::GeminiCli => "gemini_cli",
+        Provider::Grok => "grok",
+        Provider::CursorAgent => "cursor_agent",
         Provider::Fake => "fake",
     }
 }
@@ -236,8 +308,10 @@ fn resolve_agent_permissions(
     .map_err(|e| LifecycleError::Compile(e.to_string()))
 }
 
-fn runtime_contract_section() -> String {
-    RUNTIME_CONTRACT_SECTION.to_string()
+fn runtime_contract_section(send_message: &str, report_result: &str) -> String {
+    RUNTIME_CONTRACT_SECTION
+        .replace("{send_message}", send_message)
+        .replace("{report_result}", report_result)
 }
 
 fn communication_mode(value: Option<&str>) -> Result<CommunicationMode, LifecycleError> {
@@ -271,9 +345,9 @@ fn role_body(agent: &WorkerCommandAgent) -> Result<String, LifecycleError> {
     Ok(chunks.join("\n\n"))
 }
 
-fn output_contract(agent: &WorkerCommandAgent) -> Option<String> {
+fn output_contract(agent: &WorkerCommandAgent, report_result: &str) -> Option<String> {
     (agent.output_contract_format.as_deref() == Some("result_envelope_v1"))
-        .then(|| RESULT_ENVELOPE_OUTPUT_CONTRACT.to_string())
+        .then(|| RESULT_ENVELOPE_OUTPUT_CONTRACT.replace("{report_result}", report_result))
 }
 
 fn permission_notes(agent: &WorkerCommandAgent) -> Result<Option<String>, LifecycleError> {

package/crates/team-agent/src/mcp_server/tests/scoped.rs

@@ -1,3 +1,73 @@
+/// ---
+/// purpose: scoped MCP no-compaction update_state filesystem contract
+/// contract:
+///   provides:
+///     - name: update_state_path_contracts
+///       what: proves the raw no-compaction response preserves its state-file path in an owned fixture
+///   depends:
+///     - name: mcp_state_fixture
+///       what: fixture-owned root and provenance from tests.rs
+/// boundary:
+///   - retain the raw {ok,state_file} result shape
+///   - the owned selector checks workspace, state-file, and runtime paths remain fixture-owned
+/// maturity: wired
+/// ---
+
+fn verify_cleanup_surviving_receipt(
+    receipt_path: &std::path::Path,
+    raw_workspace: &std::path::Path,
+    canonical_workspace: &std::path::Path,
+    state_file: &std::path::Path,
+    runtime_state: &std::path::Path,
+) {
+    let bytes = std::fs::read(receipt_path)
+        .expect("provenance receipt must survive fixture Drop");
+    let receipt: Value = serde_json::from_slice(&bytes).expect("provenance receipt must be JSON");
+    assert_eq!(receipt["schema"], json!("mcp-state-provenance-v1"));
+    let payload = &receipt["payload"];
+    let payload_bytes = serde_json::to_vec(payload).unwrap();
+    assert_eq!(
+        receipt["payload_sha256"],
+        json!(format!("{:x}", sha2::Sha256::digest(&payload_bytes)))
+    );
+    assert_eq!(
+        payload["raw_workspace"],
+        json!(raw_workspace.display().to_string())
+    );
+    assert_eq!(
+        payload["canonical_workspace"],
+        json!(canonical_workspace.display().to_string())
+    );
+    assert_eq!(
+        payload["resolved_state_file"],
+        json!(state_file.display().to_string())
+    );
+    assert_eq!(
+        payload["runtime_state_path"],
+        json!(runtime_state.display().to_string())
+    );
+    let facts = payload["facts"].as_array().unwrap();
+    for name in [
+        "root",
+        "raw_workspace",
+        "canonical_workspace",
+        "team_dir",
+        "runtime_dir",
+        "state_parent",
+        "runtime_state",
+        "state_file",
+    ] {
+        let fact = facts
+            .iter()
+            .find(|fact| fact["name"] == json!(name))
+            .unwrap_or_else(|| panic!("provenance fact missing: {name}"));
+        assert!(fact["path"].as_str().is_some());
+        assert!(fact["uid"].as_u64().is_some());
+        assert!(fact["mode"].as_u64().is_some());
+        assert!(fact["device"].as_u64().is_some());
+    }
+}
+
     #[test]
     fn dispatch_send_message_worker_accepted_returned_verbatim() {
         // A-7: accepted requires a REAL stored message_id (no fabricated ids), so the
@@ -52,8 +122,10 @@
     // state_file (not a golden whitelist key), so the key vanishes.
     #[test]
     fn update_state_state_file_survives_no_compaction() {
+        let fixture = McpStateFixture::new("writable");
+        let expected = fixture.state_file("team_state.md");
         let tools = TeamOrchestratorTools::with_identity(
-            &unique_ws("update-state-raw"),
+            &fixture.workspace,
             Some(AgentId::new("leader")),
             None,
         );
@@ -62,6 +134,33 @@
         assert!(v.get("state_file").and_then(Value::as_str).is_some(),
             "state_file must survive (update_state is not _compact_tool_result'd)");
         assert_eq!(keys(&v), vec!["ok", "state_file"]);
+        let returned_state_file = PathBuf::from(v["state_file"].as_str().unwrap());
+        assert_eq!(returned_state_file, expected);
+        let runtime_state = crate::state::persist::runtime_state_path(&fixture.workspace);
+        assert!(fixture.under_root(&returned_state_file));
+        assert!(fixture.under_root(&runtime_state));
+        let canonical_workspace =
+            crate::model::paths::canonical_run_workspace(&fixture.workspace).unwrap();
+        let receipt = fixture.record_provenance(&fixture.workspace, &returned_state_file);
+        let root = fixture.root.clone();
+        drop(fixture);
+        assert!(!root.exists(), "fixture root must be removed before receipt verification");
+        verify_cleanup_surviving_receipt(
+            &receipt,
+            &root.join("workspace"),
+            &canonical_workspace,
+            &returned_state_file,
+            &runtime_state,
+        );
+        let receipt_bytes = std::fs::read(&receipt).unwrap();
+        println!(
+            "F10_PROVENANCE_RECEIPT path={} sha256={:x} payload={}",
+            receipt.display(),
+            sha2::Sha256::digest(&receipt_bytes),
+            String::from_utf8_lossy(&receipt_bytes)
+        );
+        std::fs::remove_file(&receipt).unwrap();
+        assert!(!receipt.exists(), "cleanup must remove only the exact receipt path");
     }
 
     // ── #36 report_result setdefault: populated envelope keys WIN over args ─────

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

@@ -1,8 +1,26 @@
+//! ---
+//! purpose: MCP no-compaction contract test with fixture-owned workspace and path provenance
+//! contract:
+//!   provides:
+//!     - name: mcp_state_fixture
+//!       what: supplies explicit process-owned workspace and state-file paths without mutating process-global environment
+//!     - name: mcp_state_path_provenance
+//!       what: records raw/canonical workspace, resolved state path, and filesystem ownership facts
+//!   depends:
+//!     - crate::mcp_server::lifecycle_tools::state_status
+//!     - crate::state::selector
+//! boundary:
+//!   - the owned no-compaction test writes only within its fixture root
+//!   - this suite does not alter persistence semantics
+//! maturity: wired
+//! ---
 //! step 14a · mcp_server::tests — WAVE-2 RED contracts (Python v0.2.11 golden).
 #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
 
 use super::*;
 use serde_json::json;
+use sha2::{Digest, Sha256};
+use std::path::{Path, PathBuf};
 
 // ── helpers ──────────────────────────────────────────────────────────────
 
@@ -27,8 +45,7 @@ fn unique_ws(tag: &str) -> std::path::PathBuf {
     static N: AtomicU64 = AtomicU64::new(0);
     loop {
         let n = N.fetch_add(1, Ordering::Relaxed);
-        let p =
-            std::env::temp_dir().join(format!("ta-rs-mcp-{tag}-{}-{n}", std::process::id()));
+        let p = std::env::temp_dir().join(format!("ta-rs-mcp-{tag}-{}-{n}", std::process::id()));
         match std::fs::create_dir(&p) {
             Ok(()) => return p,
             Err(error) if error.kind() == ErrorKind::AlreadyExists => {}
@@ -37,6 +54,183 @@ fn unique_ws(tag: &str) -> std::path::PathBuf {
     }
 }
 
+static MCP_FIXTURE_SEQ: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
+
+/// One process-owned root for update_state tests. All paths are passed explicitly
+/// to the code under test; the fixture never changes process-global environment.
+struct McpStateFixture {
+    root: PathBuf,
+    workspace: PathBuf,
+    receipt: PathBuf,
+}
+
+impl McpStateFixture {
+    fn new(_tag: &str) -> Self {
+        let seq = MCP_FIXTURE_SEQ.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
+        let base = if cfg!(target_os = "macos") {
+            PathBuf::from("/private/tmp")
+        } else {
+            PathBuf::from("/tmp")
+        };
+        let raw_root = base.join(format!("ta-mcp-{}-{seq}", std::process::id()));
+        std::fs::create_dir(&raw_root).unwrap();
+        let root = std::fs::canonicalize(raw_root).unwrap();
+        let workspace = root.join("workspace");
+        let receipt = root
+            .parent()
+            .unwrap()
+            .join(format!("ta-mcp-receipt-{}-{seq}.json", std::process::id()));
+        std::fs::create_dir(&workspace).unwrap();
+
+        let fixture = Self {
+            root,
+            workspace,
+            receipt,
+        };
+        fixture.seed_spec("team_state.md");
+        crate::state::repository::StateRepository::new(&fixture.workspace)
+            .save(
+                crate::state::repository::StateWriteIntent::FakeE2eSeed,
+                &json!({
+                    "session_name": "mcp-fixture",
+                    "active_team_key": "current",
+                    "agents": {},
+                    "tasks": []
+                }),
+            )
+            .unwrap();
+        fixture
+    }
+
+    fn seed_spec(&self, state_file: &str) {
+        std::fs::write(
+            self.workspace.join("team.spec.yaml"),
+            format!(
+                "team:\n  name: mcp-fixture\n  objective: path contract\nagents: []\ntasks: []\ncontext:\n  state_file: {state_file}\n"
+            ),
+        )
+        .unwrap();
+    }
+
+    fn state_file(&self, relative: &str) -> PathBuf {
+        self.workspace.join(relative)
+    }
+
+    fn record_provenance(&self, raw_workspace: &Path, state_file: &Path) -> PathBuf {
+        let canonical_workspace =
+            crate::model::paths::canonical_run_workspace(raw_workspace).unwrap();
+        assert!(self.under_root(raw_workspace));
+        assert!(self.under_root(&canonical_workspace));
+        assert!(self.under_root(state_file));
+        let team_dir = self.workspace.join(".team");
+        let runtime_dir = team_dir.join("runtime");
+        let runtime_state = crate::state::persist::runtime_state_path(&self.workspace);
+        let paths = [
+            ("root", self.root.as_path()),
+            ("raw_workspace", raw_workspace),
+            ("canonical_workspace", canonical_workspace.as_path()),
+            ("team_dir", team_dir.as_path()),
+            ("runtime_dir", runtime_dir.as_path()),
+            ("state_parent", state_file.parent().unwrap()),
+            ("runtime_state", runtime_state.as_path()),
+        ];
+        let mut facts = paths
+            .into_iter()
+            .map(|(name, path)| {
+                let metadata = std::fs::symlink_metadata(path).unwrap();
+                json!({
+                    "name": name,
+                    "path": path.display().to_string(),
+                    "uid": metadata_uid(&metadata),
+                    "mode": metadata_mode(&metadata),
+                    "device": metadata_device(&metadata)
+                })
+            })
+            .collect::<Vec<_>>();
+        if let Ok(metadata) = std::fs::symlink_metadata(state_file) {
+            facts.push(json!({
+                "name": "state_file",
+                "path": state_file.display().to_string(),
+                "uid": metadata_uid(&metadata),
+                "mode": metadata_mode(&metadata),
+                "device": metadata_device(&metadata)
+            }));
+        }
+        let payload = json!({
+            "raw_workspace": raw_workspace.display().to_string(),
+            "canonical_workspace": canonical_workspace.display().to_string(),
+            "resolved_state_file": state_file.display().to_string(),
+            "runtime_state_path": runtime_state.display().to_string(),
+            "facts": facts
+        });
+        let payload_bytes = serde_json::to_vec(&payload).unwrap();
+        let payload_sha256 = format!("{:x}", Sha256::digest(&payload_bytes));
+        let receipt = json!({
+            "schema": "mcp-state-provenance-v1",
+            "payload": payload,
+            "payload_sha256": payload_sha256
+        });
+        let receipt_bytes = serde_json::to_vec_pretty(&receipt).unwrap();
+        use std::io::Write;
+        let mut file = std::fs::OpenOptions::new()
+            .write(true)
+            .create_new(true)
+            .open(&self.receipt)
+            .unwrap();
+        file.write_all(&receipt_bytes).unwrap();
+        file.sync_all().unwrap();
+        self.receipt.clone()
+    }
+
+    fn under_root(&self, path: &Path) -> bool {
+        let candidate = if path.exists() {
+            std::fs::canonicalize(path).unwrap()
+        } else {
+            path.to_path_buf()
+        };
+        candidate.starts_with(&self.root)
+    }
+}
+
+impl Drop for McpStateFixture {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.root);
+    }
+}
+
+#[cfg(unix)]
+fn metadata_uid(metadata: &std::fs::Metadata) -> u32 {
+    use std::os::unix::fs::MetadataExt;
+    metadata.uid()
+}
+
+#[cfg(not(unix))]
+fn metadata_uid(_: &std::fs::Metadata) -> u32 {
+    0
+}
+
+#[cfg(unix)]
+fn metadata_mode(metadata: &std::fs::Metadata) -> u32 {
+    use std::os::unix::fs::MetadataExt;
+    metadata.mode()
+}
+
+#[cfg(not(unix))]
+fn metadata_mode(_: &std::fs::Metadata) -> u32 {
+    0
+}
+
+#[cfg(unix)]
+fn metadata_device(metadata: &std::fs::Metadata) -> u64 {
+    use std::os::unix::fs::MetadataExt;
+    metadata.dev()
+}
+
+#[cfg(not(unix))]
+fn metadata_device(_: &std::fs::Metadata) -> u64 {
+    0
+}
+
 include!("tests/normalize.rs");
 include!("tests/wire.rs");
 include!("tests/send.rs");