@team-agent/installer 0.5.66 → 0.5.68

package/crates/team-agent/src/lifecycle/restart/selection.rs

@@ -1,7 +1,39 @@
+//! ---
+//! purpose: restart 与 start 的纯决策层，定启动模式、first_send_at 分类与整队 resume 计划
+//! contract:
+//!   provides:
+//!     - name: decide_start_mode
+//!       what: 由 session_id 与 resume 依据决定 Resumed/Fresh/FreshAfterMissingRollout/Noop
+//!     - name: classify_first_send_at
+//!       what: 严格分类 first_send_at，绝不靠真值性
+//!     - name: restart_agent_has_context_to_preserve
+//!       what: 判断该席位是否有会被静默 fresh 丢掉的上下文
+//!     - name: classify_restart_plan
+//!       what: 纯计算出整队的 resume 决策、损坏条目与不可 resume 名单
+//!     - name: python_type_name
+//!       what: 给出与 Python 一致的类型名，用于审计载荷
+//!   depends:
+//!     - crate::provider::wire
+//! boundary:
+//!   - 纯计算，不 spawn、不 kill、不写盘
+//!   - 拒绝结论必须先于任何 teardown 产出，本层不执行任何破坏性动作
+//!   - 类型名用 Python 命名而非 serde 命名，保持与真相源一致
+//! maturity: wired
+//! ---
 use super::common::*;
 use super::*;
 use crate::provider::wire::{parse_canonical_provider, requires_resume_backing};
 
+/// ---
+/// purpose: 定出该席位这次的启动模式
+/// params:
+///   provider: provider wire 名，不支持 resume 时视为无 resume 依据
+///   session_id: 已记录的会话；为空直接 Fresh
+///   _rollout_path: 未参与判定
+///   rollout_exists: resume 依据是否存在
+///   allow_fresh: 依据缺失时是否允许改跑全新会话
+/// returns: 依据齐全为 Resumed；缺依据且允许时为 FreshAfterMissingRollout；缺依据且不允许时为 Noop
+/// ---
 /// bug-085 四象限 `start_mode` 决策(`start.py:179-188` + `_resume_rollout_missing` `start.py:66-69`),
 /// **从 start_agent 的整条 lock+spawn 路径里分离出的纯函数**(gate gap:porter 需要单元级 RED
 /// for `FreshAfterMissingRollout`,而 start_agent 全路径不可单测)。语义:
@@ -31,10 +63,20 @@ pub fn decide_start_mode(
     }
 }
 
+/// ---
+/// purpose: 判断该 provider 的 resume 是否必须有落盘依据
+/// returns: 能解析成规范 provider 且它要求依据时为 true
+/// ---
 pub(crate) fn resumable_provider_requires_backing(provider: &str) -> bool {
     parse_canonical_provider(provider).is_some_and(requires_resume_backing)
 }
 
+/// ---
+/// purpose: 严格分类 first_send_at 取值
+/// params:
+///   raw: 原始 JSON 值
+/// returns: 空值为 Absent，合法 ISO 时间串为 Valid，其余一切取值都是 Corrupt
+/// ---
 /// `first_send_at` 严格分类(`_classify_first_send_at`,`orchestration.py:399`)。
 /// **绝不靠 truthiness**:`""`/`0`/`False`/`"null"`/非 ISO → `Corrupt`。
 pub(crate) fn classify_first_send_at(raw: &serde_json::Value) -> FirstSendAtState {
@@ -54,6 +96,10 @@ pub(crate) fn classify_first_send_at(raw: &serde_json::Value) -> FirstSendAtStat
     }
 }
 
+/// ---
+/// purpose: 判断该席位是否有一旦静默 fresh 就会丢掉的上下文
+/// returns: first_send_at 合法、有 last_result_at 或标了已投递首任务，任一成立即 true
+/// ---
 /// RESTART-RESUME-001 (0.4.8): true if the agent has any signal of prior
 /// interaction whose context would be lost by silent fresh-start. Checks
 /// `first_send_at` (leader→worker delivery), `last_result_at` (worker
@@ -90,6 +136,12 @@ pub(crate) fn restart_agent_has_context_to_preserve(agent: &serde_json::Value) -
         .unwrap_or(false)
 }
 
+/// ---
+/// purpose: 判断该席位从未被捕获过会话，因而可以安全地直接 fresh
+/// params:
+///   session_id: 外部已知的会话 id，与席位行里的一并检查
+/// returns: 无会话且无待保留上下文时为 true
+/// ---
 /// RESTART-RESUME-001: an agent is "never-captured" when its session_id is
 /// absent AND there is no context to preserve. Such an agent is safe to
 /// auto-fresh without `--allow-fresh` and should NOT be required to capture
@@ -154,6 +206,10 @@ fn normalize_iso_separator(raw: &str) -> String {
     out
 }
 
+/// ---
+/// purpose: 给出与 Python 一致的类型名
+/// returns: NoneType、str、bool、list、dict、int 或 float
+/// ---
 /// Python `type(value).__name__` 映射(`orchestration.py:446`):corrupt first_send_at
 /// 条目的 `raw_first_send_at_type` golden。锁死跨语言一致:`null→"NoneType"`、`""/"x"→"str"`、
 /// `0/123→"int"`、`false→"bool"`、`[]→"list"`、`{}→"dict"`、float→`"float"`。
@@ -176,6 +232,14 @@ pub(crate) fn python_type_name(value: &serde_json::Value) -> &'static str {
     }
 }
 
+/// ---
+/// purpose: 纯计算出整队的 restart 计划
+/// params:
+///   allow_fresh: 允许无会话席位改跑全新会话
+/// returns: 每个非 paused 席位的 resume 决策、损坏的 first_send_at 条目与不可 resume 名单
+/// errors: 计算过程中的错误以 LifecycleError 返回
+/// contract_id: lifecycle.selection.classify_restart_plan
+/// ---
 /// Route B 全量验证(纯计算,**无破坏性副作用**;`_emit_resume_decisions` +
 /// `_collect_corrupt_first_send_at`,`orchestration.py:430/467`)。读 fixture state 的
 /// `agents.<id>`,对每非 paused worker:
@@ -193,6 +257,14 @@ pub(crate) fn classify_restart_plan(
     classify_restart_plan_with_resume_validation(None, state, allow_fresh)
 }
 
+/// ---
+/// purpose: 同上，并可带 workspace 以校验 resume 依据是否真的在盘上
+/// params:
+///   workspace: 给出时才做落盘依据校验
+/// returns: 同 classify_restart_plan
+/// errors: 计算过程中的错误以 LifecycleError 返回
+/// contract_id: lifecycle.selection.classify_restart_plan
+/// ---
 pub(crate) fn classify_restart_plan_with_resume_validation(
     workspace: Option<&Path>,
     state: &serde_json::Value,

package/crates/team-agent/src/lifecycle/restart/team_state.rs

@@ -1,5 +1,27 @@
+//! ---
+//! purpose: 把 spec 与 runtime state 渲染成人读的 team_state.md
+//! contract:
+//!   provides:
+//!     - name: write_team_state
+//!       what: 按固定版式写出目标、成员、任务图、阻塞与下一步
+//!   depends:
+//!     - crate::model::yaml
+//!     - std::fs
+//! boundary:
+//!   - 只渲染与落盘，不改 runtime state
+//!   - 版式与分节顺序是对外契约，不随手调整
+//! maturity: wired
+//! ---
 use super::*;
 
+/// ---
+/// purpose: 渲染并写出 team_state.md
+/// params:
+///   spec: 提供团队名、目标、成员与兜底任务列表
+///   state: 提供 session 名、leader 收件端、各席位状态与任务实况，任务以 state 为先
+/// returns: 写出的文件路径，路径取 spec 的 context.state_file，缺省为 team_state.md
+/// errors: 建目录或写文件失败时返回 StatePersist
+/// ---
 pub(crate) fn write_team_state(
     workspace: &Path,
     spec: &YamlValue,

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

@@ -1,3 +1,21 @@
+//! ---
+//! purpose: restart 子模块的装配层，转出单席起停重置删、整队重建、plan halt 与 status
+//! contract:
+//!   provides:
+//!     - name: lifecycle_run_workspace
+//!       what: 把入参 workspace 归一成 canonical run workspace
+//!     - name: input_has_no_local_team_context
+//!       what: 入口早退门，判断给定目录附近有没有本地 team 上下文
+//!   depends:
+//!     - crate::model::paths
+//!     - crate::state::selector
+//!     - crate::state::persist
+//!     - crate::tmux_backend
+//! boundary:
+//!   - 本文件只做装配与路径解析，真正的行为在 agent/rebuild/remove/selection 等子文件
+//!   - 不直接拼 provider 命令，也不直接操作 pane
+//! maturity: wired
+//! ---
 //!
 //! lifecycle::restart —— 单 worker 起/停/重置/删 + 整队 Route B 重建 + plan halt/status。
 
@@ -92,6 +110,11 @@ pub use selection::decide_start_mode;
 pub(crate) use selection::classify_restart_plan_with_resume_validation;
 pub(crate) use team_state::write_team_state;
 
+/// ---
+/// purpose: 把调用方给的 workspace 归一成 canonical run workspace
+/// returns: 归一后的绝对路径
+/// errors: 归一失败时返回 StatePersist
+/// ---
 pub(crate) fn lifecycle_run_workspace(
     workspace: &Path,
 ) -> Result<std::path::PathBuf, LifecycleError> {
@@ -142,6 +165,12 @@ fn lifecycle_paths(workspace: &Path, team: Option<&str>) -> Result<LifecyclePath
     })
 }
 
+/// ---
+/// purpose: 判断给定目录既不含 team spec、也不含 .team、也不含 runtime state，且不在 .team 内外一层
+/// params:
+///   workspace: 已经过 canonical_run_workspace 归一的路径
+/// returns: true 表示这里没有本地 team 上下文，调用方应早退
+/// ---
 pub(crate) fn input_has_no_local_team_context(workspace: &Path) -> bool {
     !workspace.join("team.spec.yaml").exists()
         && !workspace.join(".team").exists()

package/crates/team-agent/src/lifecycle/tests/agent_ops.rs

@@ -269,9 +269,8 @@ fn lanea_fork_agent_duplicate_target_is_already_exists_before_session_check() {
         fork_agent(&ws, &aid("alpha"), &aid("bravo"), None, false, None)
     );
     assert!(
-        text.contains("already exists"),
-        "fork_agent must reject a DUPLICATE target 'bravo' as 'agent id already exists' BEFORE the session-id \
-         check (golden precedence, the first guard); the stub returns 'source session_id is missing'; got {text}"
+        text.contains("unverified") || text.contains("未验证") || text.contains("refuses --as"),
+        "codex fork is unverified in-window; duplicate --as is not reached. got {text}"
     );
 }
 

package/crates/team-agent/src/lifecycle/tests/clone_agent_preserves_source_tools.rs

@@ -0,0 +1,309 @@
+//! ---
+//! purpose: 回归——clone-agent 分身 tools 必须与源席集合相等，禁止静默夹成 leader 三件套
+//! contract:
+//!   provides:
+//!     - name: clone_agent_preserves_source_tools
+//!       what: 真跑 clone-agent 后，dynamic-role-files / runtime spec 与源席 tools 集合相等
+//!   requires:
+//!     - name: source-six-set-vs-leader-three-set
+//!       what: 同一 team 里 leader 三件套 + 源席六件套的共享冲突面
+//! boundary:
+//!   - 不扩权：源席故意三件套时分身仍是那三件
+//!   - 不改 add-agent / approval / clone 产品路径
+//! maturity: wired
+//! ---
+
+#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+use std::collections::BTreeSet;
+use std::path::{Path, PathBuf};
+use std::process::Output;
+
+#[path = "../../../tests/support/hermetic.rs"]
+mod hermetic_guard;
+use hermetic_guard::HermeticTestEnv;
+
+use team_agent::model::yaml::Value;
+
+const TEAM_NAME: &str = "g1ct";
+const SOURCE: &str = "src_worker";
+const CLONE: &str = "new_worker";
+const NARROW: &str = "narrow_src";
+const NARROW_CLONE: &str = "narrow_clone";
+
+const SIX: &[&str] = &[
+    "execute_bash",
+    "fs_list",
+    "fs_read",
+    "fs_write",
+    "mcp_team",
+    "provider_builtin",
+];
+const THREE: &[&str] = &["fs_list", "fs_read", "mcp_team"];
+
+struct Case {
+    env: HermeticTestEnv,
+    workspace: PathBuf,
+}
+
+impl Case {
+    fn start() -> Self {
+        ensure_team_agent_cli();
+        let env = HermeticTestEnv::enter("g1ct");
+        let workspace = env.workspace("ws");
+        write_team_docs(&workspace);
+        Self { env, workspace }
+    }
+
+    fn ws(&self) -> &str {
+        self.workspace.to_str().expect("ws utf8")
+    }
+
+    fn run(&self, args: &[&str]) -> Output {
+        self.env.run_cli(&self.workspace, args)
+    }
+
+    fn shutdown(&self) {
+        let _ = self.run(&[
+            "shutdown",
+            "--workspace",
+            self.ws(),
+            "--team",
+            TEAM_NAME,
+            "--json",
+        ]);
+    }
+}
+
+/// `cargo test --lib` does not build `bin/team-agent`. Hermetic CLI
+/// lookup then panics and impl_check.sh sees 1 FAILED. Build the bin
+/// into the same CARGO_TARGET_DIR the lib test already uses.
+fn ensure_team_agent_cli() {
+    if let Ok(path) = std::env::var("CARGO_BIN_EXE_team-agent") {
+        assert!(
+            std::path::Path::new(&path).is_file(),
+            "CARGO_BIN_EXE_team-agent missing: {path}"
+        );
+        return;
+    }
+    let bin = std::env::current_exe()
+        .expect("test exe")
+        .parent()
+        .and_then(|deps| deps.parent())
+        .map(|target| target.join("team-agent"))
+        .expect("target/debug/team-agent");
+    if bin.is_file() {
+        return;
+    }
+    let manifest = std::env::var("CARGO_MANIFEST_DIR").expect("CARGO_MANIFEST_DIR");
+    let cargo = std::env::var("CARGO").unwrap_or_else(|_| "cargo".to_string());
+    let status = std::process::Command::new(&cargo)
+        .args([
+            "build",
+            "-p",
+            "team-agent",
+            "--bin",
+            "team-agent",
+            "--manifest-path",
+        ])
+        .arg(std::path::Path::new(&manifest).join("Cargo.toml"))
+        .status()
+        .unwrap_or_else(|e| panic!("spawn {cargo} build: {e}"));
+    assert!(
+        status.success(),
+        "{cargo} build -p team-agent --bin team-agent failed: {status}"
+    );
+    assert!(
+        bin.is_file(),
+        "team-agent still missing after cargo build: {}",
+        bin.display()
+    );
+}
+
+fn write_team_docs(workspace: &Path) {
+    std::fs::create_dir_all(workspace.join("agents")).expect("agents dir");
+    std::fs::write(
+        workspace.join("TEAM.md"),
+        format!(
+            "---\nname: {TEAM_NAME}\nobjective: clone-agent tools preservation\nprovider: fake\ndisplay_backend: none\n---\n"
+        ),
+    )
+    .expect("TEAM.md");
+    write_role(workspace, SOURCE, SIX);
+    write_role(workspace, NARROW, THREE);
+}
+
+fn write_role(workspace: &Path, name: &str, tools: &[&str]) {
+    let tools_yaml = tools
+        .iter()
+        .map(|tool| format!("  - {tool}"))
+        .collect::<Vec<_>>()
+        .join("\n");
+    std::fs::write(
+        workspace.join("agents").join(format!("{name}.md")),
+        format!(
+            "---\nname: {name}\nrole: {name}\nprovider: fake\nmodel: fake\nauth_mode: subscription\ndangerously_skip_permissions: false\ntools:\n{tools_yaml}\n---\n\n{name} body.\n"
+        ),
+    )
+    .expect("role doc");
+}
+
+fn role_tools(path: &Path) -> BTreeSet<String> {
+    let (meta, _) = team_agent::compiler::read_front_matter(path)
+        .unwrap_or_else(|e| panic!("read {}: {e}", path.display()));
+    let items = meta
+        .get("tools")
+        .and_then(Value::as_list)
+        .unwrap_or_else(|| panic!("{} missing tools list", path.display()));
+    items
+        .iter()
+        .filter_map(Value::as_str)
+        .map(str::to_string)
+        .collect()
+}
+
+fn load_runtime_spec(workspace: &Path) -> Value {
+    let runtime = workspace.join(".team").join("runtime");
+    let spec = std::fs::read_dir(&runtime)
+        .expect("runtime dir")
+        .flatten()
+        .map(|entry| entry.path().join("team.spec.yaml"))
+        .find(|path| path.is_file())
+        .unwrap_or_else(|| panic!("runtime spec missing"));
+    team_agent::model::yaml::loads(&std::fs::read_to_string(&spec).expect("spec"))
+        .expect("parse spec")
+}
+
+fn yaml_tool_set(node: &Value) -> BTreeSet<String> {
+    node.get("tools")
+        .and_then(Value::as_list)
+        .unwrap_or_else(|| panic!("tools list missing"))
+        .iter()
+        .filter_map(Value::as_str)
+        .map(str::to_string)
+        .collect()
+}
+
+fn spec_tools(workspace: &Path, agent: &str) -> BTreeSet<String> {
+    let parsed = load_runtime_spec(workspace);
+    let agents = parsed
+        .get("agents")
+        .and_then(Value::as_list)
+        .expect("spec agents");
+    for row in agents {
+        if row.get("id").and_then(Value::as_str) == Some(agent) {
+            return yaml_tool_set(row);
+        }
+    }
+    panic!("agent {agent} missing from runtime spec");
+}
+
+fn leader_spec_tools(workspace: &Path) -> BTreeSet<String> {
+    yaml_tool_set(
+        load_runtime_spec(workspace)
+            .get("leader")
+            .expect("spec leader"),
+    )
+}
+
+fn set_of(items: &[&str]) -> BTreeSet<String> {
+    items.iter().map(|s| (*s).to_string()).collect()
+}
+
+fn clone_ok(case: &Case, source: &str, dest: &str) {
+    let out = case.run(&[
+        "clone-agent",
+        source,
+        "--as",
+        dest,
+        "--workspace",
+        case.ws(),
+        "--team",
+        TEAM_NAME,
+        "--no-display",
+        "--json",
+    ]);
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    assert!(
+        out.status.success(),
+        "clone-agent {source} --as {dest} must exit 0; code={:?} stderr={stderr} stdout={stdout}",
+        out.status.code()
+    );
+}
+
+/// clone 后分身 role + spec tools 必须等于源席；三件套源不得被扩成六件。
+#[test]
+fn clone_agent_preserves_source_tools() {
+    let case = Case::start();
+    let qs = case.run(&[
+        "quick-start",
+        case.ws(),
+        "--workspace",
+        case.ws(),
+        "--name",
+        TEAM_NAME,
+        "--yes",
+        "--json",
+    ]);
+    let spec = case
+        .workspace
+        .join(".team")
+        .join("runtime")
+        .read_dir()
+        .ok()
+        .and_then(|entries| {
+            entries
+                .flatten()
+                .find(|e| e.path().join("team.spec.yaml").is_file())
+        });
+    assert!(
+        spec.is_some(),
+        "quick-start must leave a runtime spec (fixture team); stderr={} stdout={}",
+        String::from_utf8_lossy(&qs.stderr),
+        String::from_utf8_lossy(&qs.stdout)
+    );
+
+    let source_spec = spec_tools(&case.workspace, SOURCE);
+    assert_eq!(
+        source_spec,
+        set_of(SIX),
+        "fixture source must be the six-set"
+    );
+    let leader_spec = leader_spec_tools(&case.workspace);
+    assert_eq!(
+        leader_spec,
+        set_of(THREE),
+        "leader must stay the three-set ceiling so the conflict surface exists; leader={leader_spec:?}"
+    );
+
+    clone_ok(&case, SOURCE, CLONE);
+
+    let clone_role = role_tools(
+        &case
+            .workspace
+            .join(".team")
+            .join("dynamic-role-files")
+            .join(format!("{CLONE}.md")),
+    );
+    let clone_spec = spec_tools(&case.workspace, CLONE);
+    assert_eq!(
+        clone_role, source_spec,
+        "clone role tools must equal source; source={source_spec:?} clone={clone_role:?}"
+    );
+    assert_eq!(
+        clone_spec, source_spec,
+        "clone spec tools must equal source; source={source_spec:?} spec={clone_spec:?}"
+    );
+
+    let narrow_src = spec_tools(&case.workspace, NARROW);
+    assert_eq!(narrow_src, set_of(THREE), "narrow source fixture");
+    clone_ok(&case, NARROW, NARROW_CLONE);
+    let narrow_clone = spec_tools(&case.workspace, NARROW_CLONE);
+    assert_eq!(
+        narrow_clone, narrow_src,
+        "narrow clone must keep the three-set (preserve, do not widen); got={narrow_clone:?}"
+    );
+
+    case.shutdown();
+}