@team-agent/installer 0.5.66 → 0.5.68

package/crates/team-agent/src/lifecycle/launch/spec_state.rs

@@ -1,3 +1,35 @@
+//! ---
+//! purpose: spec 的读取改写与 runtime state 初值物化，含 quick-start 的 owner 种入
+//! contract:
+//!   provides:
+//!     - name: initial_runtime_state
+//!       what: 由 spec 生成首份 runtime state 树，并种入 launched owner
+//!     - name: write_spec_atomic
+//!       what: 先写同目录临时文件再 rename，避免留下半截 spec
+//!     - name: spec_session_name
+//!       what: 取 runtime.session_name，缺省由 team 名派生
+//!     - name: spec_agents
+//!       what: 取 spec 里全部 agent id
+//!     - name: spec_routes
+//!       what: 对 spec 里每个 task 算出路由决策
+//!     - name: effective_runtime_config_for_worker_spawn
+//!       what: 由单个 agent 的 dangerously_skip_permissions 定出 bypass 审批结论
+//!   depends:
+//!     - crate::state::projection
+//!     - crate::state::identity
+//!     - crate::state::ownership
+//!     - crate::model::yaml
+//!     - crate::model::routing
+//!     - crate::provider::bypass_flags
+//!     - crate::lifecycle::launch::identity
+//!     - crate::lifecycle::launch::leader_context
+//!     - crate::lifecycle::launch::worker_env
+//! boundary:
+//!   - 只生成与改写数据，不 spawn 进程也不开显示
+//!   - bypass 只认单个 agent 自己的声明，不从 runtime 配置或 leader argv 全队继承
+//!   - spec 写盘一律走原子替换，不做就地截断写
+//! maturity: wired
+//! ---
 //!
 //! unit-8 (Stage 3) — `lifecycle::launch::spec_state` phase boundary.
 //!
@@ -40,6 +72,12 @@ use super::leader_context::{
 };
 use super::worker_env::spawn_timestamp;
 
+/// ---
+/// purpose: 由 spec 生成首份 runtime state 树
+/// params:
+///   team_key: 本团队的 runtime 键
+/// returns: 含 spec_path、workspace、team_dir、session_name、leader、agents、tasks 与 display_backend 的 state；随后按环境种入 launched owner，种不到则种一份 unbound owner
+/// ---
 pub(super) fn initial_runtime_state(
     spec: &Value,
     spec_path: &Path,
@@ -113,6 +151,12 @@ pub(super) fn initial_runtime_state(
     state
 }
 
+/// ---
+/// purpose: 从环境里的 caller 身份种入 launched owner
+/// params:
+///   state: 待改写的 state，成功时写入 owner 与 leader receiver
+/// returns: true 表示已种入，取不到 caller 身份或无 pane 时为 false
+/// ---
 pub(super) fn seed_launched_owner_from_env(state: &mut serde_json::Value) -> bool {
     let team_id = crate::state::projection::team_state_key(state);
     let Ok(caller) = crate::state::identity::caller_identity_from_env(
@@ -130,6 +174,13 @@ pub(super) fn seed_launched_owner_from_env(state: &mut serde_json::Value) -> boo
     )
 }
 
+/// ---
+/// purpose: 用给定的 caller 身份与 pane provider 查询函数种入 owner 与 leader receiver
+/// params:
+///   caller: 调用方身份，pane_id 为空则不种
+///   lookup_pane_provider: 由 pane 反查 provider 的函数，便于测试替换
+/// returns: true 表示已写入 owner 记录
+/// ---
 pub(super) fn seed_launched_owner_from_caller_with_provider_lookup(
     state: &mut serde_json::Value,
     caller: crate::state::owner_gate::CallerIdentity,
@@ -186,6 +237,10 @@ pub(super) fn seed_launched_owner_from_caller_with_provider_lookup(
     true
 }
 
+/// ---
+/// purpose: 判断环境里是否带有任一 leader 身份变量
+/// returns: pane id、session uuid、其 override 或 provider 任一非空即 true
+/// ---
 pub(super) fn has_positive_caller_leader_env() -> bool {
     env_nonempty("TEAM_AGENT_LEADER_PANE_ID")
         || env_nonempty("TEAM_AGENT_LEADER_SESSION_UUID")
@@ -193,12 +248,20 @@ pub(super) fn has_positive_caller_leader_env() -> bool {
         || env_nonempty("TEAM_AGENT_LEADER_PROVIDER")
 }
 
+/// ---
+/// purpose: 判断某环境变量存在且非空
+/// returns: 存在且非空为 true
+/// ---
 pub(super) fn env_nonempty(key: &str) -> bool {
     std::env::var(key)
         .ok()
         .is_some_and(|value| !value.is_empty())
 }
 
+/// ---
+/// purpose: 把 spec 的 tasks 列表转成 JSON 数组
+/// returns: 转换后的数组，没有 tasks 时为空数组
+/// ---
 pub(super) fn spec_tasks_json(spec: &Value) -> serde_json::Value {
     spec.get("tasks")
         .and_then(Value::as_list)
@@ -206,6 +269,10 @@ pub(super) fn spec_tasks_json(spec: &Value) -> serde_json::Value {
         .unwrap_or_else(|| serde_json::json!([]))
 }
 
+/// ---
+/// purpose: 把 YAML 值递归转成等价 JSON 值
+/// returns: 结构与标量一一对应的 JSON
+/// ---
 pub(super) fn yaml_value_to_json(value: &Value) -> serde_json::Value {
     match value {
         Value::Null => serde_json::Value::Null,
@@ -226,6 +293,11 @@ pub(super) fn yaml_value_to_json(value: &Value) -> serde_json::Value {
     }
 }
 
+/// ---
+/// purpose: 原子写 spec，先写带进程号后缀的临时文件再 rename 覆盖
+/// returns: 成功返回空值
+/// errors: 建父目录、写临时文件或 rename 失败时返回 StatePersist；rename 失败会删掉临时文件且原 spec 不动
+/// ---
 ///
 /// Set `runtime.session_name` on the compiled spec to `session_name`, creating the
 /// `runtime` map and/or the `session_name` entry if absent. Used by quick-start to
@@ -252,10 +324,18 @@ pub(crate) fn write_spec_atomic(spec_path: &Path, spec: &Value) -> Result<(), Li
     Ok(())
 }
 
+/// ---
+/// purpose: 就地把 spec 的 runtime.session_name 改成给定值
+/// ---
 pub(crate) fn override_spec_session_name(spec: &mut Value, session_name: &str) {
     override_spec_runtime_str(spec, "session_name", session_name);
 }
 
+/// ---
+/// purpose: 就地把 spec 里 team.workspace 与各 agent 的 working_directory 改成给定路径
+/// params:
+///   spec: 非 Map 时不动；只改已存在的字段，不新建
+/// ---
 pub(crate) fn override_spec_workspace(spec: &mut Value, workspace: &Path) {
     let workspace_s = workspace.to_string_lossy().to_string();
     let Value::Map(root) = spec else { return };
@@ -276,10 +356,19 @@ pub(crate) fn override_spec_workspace(spec: &mut Value, workspace: &Path) {
     }
 }
 
+/// ---
+/// purpose: 就地把 spec 的 runtime.display_backend 改成给定值
+/// ---
 pub(super) fn override_spec_display_backend(spec: &mut Value, display_backend: &str) {
     override_spec_runtime_str(spec, "display_backend", display_backend);
 }
 
+/// ---
+/// purpose: 就地写 spec 的 runtime 段下某个字符串字段
+/// params:
+///   spec: 非 Map 时不动
+/// returns: runtime 段缺失则新建，已存在同名键则覆盖，runtime 是非 Map 值则整段替换
+/// ---
 pub(super) fn override_spec_runtime_str(spec: &mut Value, key: &str, value: &str) {
     let Value::Map(root) = spec else { return };
     let runtime_slot = root
@@ -306,6 +395,10 @@ pub(super) fn override_spec_runtime_str(spec: &mut Value, key: &str, value: &str
     }
 }
 
+/// ---
+/// purpose: 定出本 spec 的 tmux session 名
+/// returns: runtime.session_name 的非空值；缺失时由 team.name 派生，team 名也缺失时用 agent 兜底
+/// ---
 pub(super) fn spec_session_name(spec: &Value) -> SessionName {
     if let Some(name) = spec
         .get("runtime")
@@ -325,6 +418,10 @@ pub(super) fn spec_session_name(spec: &Value) -> SessionName {
     SessionName::new(format!("team-{team_name}"))
 }
 
+/// ---
+/// purpose: 把 spec_session_name 以更宽可见性转出，供 layout 复用同一份实现
+/// returns: 同 spec_session_name
+/// ---
 ///
 /// 0.3.28 layout step 1: pub re-export of `spec_session_name` for the new
 /// `layout::sessions::worker_session_name` to delegate to. Single underlying
@@ -333,6 +430,10 @@ pub fn worker_session_name_pub(spec: &Value) -> SessionName {
     spec_session_name(spec)
 }
 
+/// ---
+/// purpose: 取出 spec 里全部 agent id
+/// returns: 按 spec 顺序的 agent id，无 id 字段的条目被跳过
+/// ---
 pub(super) fn spec_agents(spec: &Value) -> Vec<AgentId> {
     spec_agent_values(spec)
         .into_iter()
@@ -340,6 +441,10 @@ pub(super) fn spec_agents(spec: &Value) -> Vec<AgentId> {
         .collect()
 }
 
+/// ---
+/// purpose: 取出 spec 里全部 agent id 的集合，便于成员判定
+/// returns: 有序集合
+/// ---
 ///
 /// Bug 1 (0.4.2): expose spec agent id set so the restart path can filter
 /// state.agents to only the agents currently defined in the rebuilt spec.
@@ -351,6 +456,10 @@ pub(crate) fn spec_agent_id_set(spec: &Value) -> std::collections::BTreeSet<Stri
         .collect()
 }
 
+/// ---
+/// purpose: 取出 spec 的 agents 列表原始节点
+/// returns: 节点引用列表，字段缺失或类型不对时为空
+/// ---
 pub(super) fn spec_agent_values(spec: &Value) -> Vec<&Value> {
     spec.get("agents")
         .and_then(Value::as_list)
@@ -358,6 +467,10 @@ pub(super) fn spec_agent_values(spec: &Value) -> Vec<&Value> {
         .unwrap_or_default()
 }
 
+/// ---
+/// purpose: 对 spec 里每个 task 算出路由决策
+/// returns: 每个 task 的选中 agent 与理由，manual_override 恒为 false
+/// ---
 pub(super) fn spec_routes(spec: &Value) -> Vec<RoutingDecision> {
     spec.get("tasks")
         .and_then(Value::as_list)
@@ -378,6 +491,10 @@ pub(super) fn spec_routes(spec: &Value) -> Vec<RoutingDecision> {
         .unwrap_or_default()
 }
 
+/// ---
+/// purpose: 定出默认承接人
+/// returns: routing.default_assignee，缺失时取第一个 agent
+/// ---
 pub(super) fn spec_default_assignee(spec: &Value) -> Option<AgentId> {
     spec.get("routing")
         .and_then(|v| v.get("default_assignee"))
@@ -386,6 +503,12 @@ pub(super) fn spec_default_assignee(spec: &Value) -> Option<AgentId> {
         .or_else(|| spec_agents(spec).into_iter().next())
 }
 
+/// ---
+/// purpose: 由单个 YAML agent 的 dangerously_skip_permissions 定出 bypass 审批结论
+/// returns: 字段为 true 时 enabled 且来源记 RuntimeConfig，并带上该 provider 的 bypass argv；否则 Disabled
+/// errors: 当前实现不产生 Err
+/// contract_id: lifecycle.spec_state.effective_runtime_config
+/// ---
 /// 0.5.66 bypass 单源:从**单个 agent**(yaml spec)的 `dangerously_skip_permissions` 构造
 /// `DangerousApproval`(取代旧"runtime config + leader argv"全队一份)。
 /// true → source=RuntimeConfig(角色声明即用户明确同意,coordinator 的
@@ -423,6 +546,12 @@ pub(crate) fn effective_runtime_config_for_worker_spawn(
     })
 }
 
+/// ---
+/// purpose: 同上，但读的是 runtime state 里的 JSON agent 节点
+/// returns: 同 YAML 版
+/// errors: 当前实现不产生 Err
+/// contract_id: lifecycle.spec_state.effective_runtime_config
+/// ---
 /// 0.5.66 bypass 单源:restart/state 路径的 serde_json 版(agent 来自 state JSON)。
 pub(crate) fn effective_runtime_config_for_worker_spawn_json(
     agent: &serde_json::Value,
@@ -457,6 +586,10 @@ pub(crate) fn effective_runtime_config_for_worker_spawn_json(
     })
 }
 
+/// ---
+/// purpose: 给出 provider 的稳定 wire 名
+/// returns: 与 spec 写法一致的小写下划线名
+/// ---
 pub(crate) fn provider_display_str(provider: Provider) -> &'static str {
     match provider {
         Provider::Claude => "claude",
@@ -464,10 +597,16 @@ pub(crate) fn provider_display_str(provider: Provider) -> &'static str {
         Provider::Codex => "codex",
         Provider::Copilot => "copilot",
         Provider::GeminiCli => "gemini_cli",
+        Provider::Grok => "grok",
+        Provider::CursorAgent => "cursor_agent",
         Provider::Fake => "fake",
     }
 }
 
+/// ---
+/// purpose: 由 team 目录推出 workspace 根
+/// returns: 解析成功用解析值，失败时退到 team 目录的父目录，没有父目录则用 team 目录本身
+/// ---
 pub(super) fn team_workspace(team_dir: &Path) -> PathBuf {
     crate::model::paths::team_workspace(team_dir).unwrap_or_else(|_| {
         team_dir

package/crates/team-agent/src/lifecycle/launch/state_projection.rs

@@ -1,3 +1,32 @@
+//! ---
+//! purpose: 冷启后把席位实况投影进 runtime state，并做团队级合并、投影与 owner 清洗
+//! contract:
+//!   provides:
+//!     - name: persist_spawn_agent_state
+//!       what: 按 spawn 结果与 tmux 实况写出各席位状态，分 running/paused/spawn_failed
+//!     - name: save_launched_team_state_for_key
+//!       what: 把本次团队状态并入既有 state，投影后经 repository 落盘
+//!     - name: merge_workspace_team_state_with_key
+//!       what: 以显式团队键把本次状态并进 teams 表，不丢既有团队
+//!     - name: drop_worker_pane_seeded_owner
+//!       what: 识别出被 worker pane 误种的 owner 并改种 unbound owner
+//!   depends:
+//!     - crate::state::repository
+//!     - crate::state::projection
+//!     - crate::state::persist
+//!     - crate::state::ownership
+//!     - crate::tmux_backend
+//!     - crate::lifecycle::launch::agent_state
+//!     - crate::lifecycle::launch::identity
+//!     - crate::lifecycle::launch::leader_context
+//!     - crate::lifecycle::launch::spec_state
+//!     - crate::lifecycle::launch::worker_env
+//! boundary:
+//!   - 只写 state，不 spawn、不 kill、不开显示
+//!   - 落盘一律经 StateRepository 带写意图，不直接改文件
+//!   - owner 归属判不准时倒向 unbound，不认领他队的 pane
+//! maturity: wired
+//! ---
 //!
 use std::collections::{BTreeMap, BTreeSet};
 use std::path::{Path, PathBuf};
@@ -21,6 +50,14 @@ use super::leader_context::{
 use super::spec_state::{has_positive_caller_leader_env, spec_agent_values};
 use super::worker_env::{agent_is_paused, spawn_timestamp_for_agent};
 
+/// ---
+/// purpose: 把本次 spawn 的结果写成 runtime state 里的各席位状态
+/// params:
+///   started: 本次 spawn 成功返回的席位
+///   transport: 用于查活窗口与 pane pid
+/// returns: 成功返回空值。spec 里 paused 的席位记 paused，spawn 后窗口不在的记 spawn_failed，其余记 running
+/// errors: 读或写 runtime state 失败时返回 StatePersist
+/// ---
 pub(super) fn persist_spawn_agent_state(
     workspace: &Path,
     spec_path: &Path,
@@ -148,6 +185,10 @@ pub(super) fn persist_spawn_agent_state(
     save_launched_team_state_for_key(workspace, &state, Some(&team_id), None)
 }
 
+/// ---
+/// purpose: 给出各已起席位对应 pane 的进程号
+/// returns: agent_id 到 pane pid 的映射，查不到的席位不出现
+/// ---
 pub(super) fn pane_pids_by_started_agent(
     transport: &dyn Transport,
     started: &[StartedAgent],
@@ -165,6 +206,10 @@ pub(super) fn pane_pids_by_started_agent(
         .collect()
 }
 
+/// ---
+/// purpose: 由 agent id 找出它这次 spawn 的目标 pane
+/// returns: 命中的 pane 串，找不到时为空串
+/// ---
 pub(super) fn agent_id_to_pane_id<'a>(started: &'a [StartedAgent], agent_id: &str) -> &'a str {
     started
         .iter()
@@ -173,6 +218,12 @@ pub(super) fn agent_id_to_pane_id<'a>(started: &'a [StartedAgent], agent_id: &st
         .unwrap_or("")
 }
 
+/// ---
+/// purpose: 不带显式团队键地保存本次团队状态
+/// returns: 成功返回空值
+/// errors: 落盘失败时返回 StatePersist
+/// contract_id: lifecycle.state_projection.save_launched_team_state
+/// ---
 pub(super) fn save_launched_team_state(
     workspace: &Path,
     launched: &serde_json::Value,
@@ -180,6 +231,15 @@ pub(super) fn save_launched_team_state(
     save_launched_team_state_for_key(workspace, launched, None, None)
 }
 
+/// ---
+/// purpose: 保存本次团队状态的实体实现，含团队键钉死、owner 清洗、合并与投影
+/// params:
+///   team_key: 显式团队键，为空则由 state 推算
+///   added_agent_id: 本次新增席位 id，写进写意图
+/// returns: 成功返回空值
+/// errors: 落盘失败时返回 StatePersist
+/// contract_id: lifecycle.state_projection.save_launched_team_state
+/// ---
 pub(super) fn save_launched_team_state_for_key(
     workspace: &Path,
     launched: &serde_json::Value,
@@ -240,6 +300,11 @@ pub(super) fn save_launched_team_state_for_key(
         .map_err(|e| LifecycleError::StatePersist(e.to_string()))
 }
 
+/// ---
+/// purpose: 本次状态没写 leader 拓扑字段时，从既有状态里补回来
+/// params:
+///   launched: 就地补 is_external_leader 与 leader_client，已有同名键不覆盖
+/// ---
 pub(super) fn preserve_existing_leader_topology(
     existing: &serde_json::Value,
     launched_key: &str,
@@ -262,6 +327,11 @@ pub(super) fn preserve_existing_leader_topology(
     }
 }
 
+/// ---
+/// purpose: 无 leader 身份环境且 owner pane 形如首席 pane 时改种 unbound owner
+/// params:
+///   launched: 就地改写
+/// ---
 pub(super) fn drop_bare_worker_seeded_owner(launched: &mut serde_json::Value, launched_key: &str) {
     if has_positive_caller_leader_env() {
         return;
@@ -276,6 +346,10 @@ pub(super) fn drop_bare_worker_seeded_owner(launched: &mut serde_json::Value, la
     }
 }
 
+/// ---
+/// purpose: 以显式团队键把本次状态并进 teams 表
+/// returns: 合并后的 state；既有顶层 session 名为空或团队键相同时保留既有 teams 并覆盖本键，否则以既有状态为底再补进本次团队
+/// ---
 pub(super) fn merge_workspace_team_state_with_key(
     existing: &serde_json::Value,
     launched: &serde_json::Value,
@@ -360,6 +434,11 @@ mod merge_workspace_team_state_with_key_tests {
     }
 }
 
+/// ---
+/// purpose: 把 teams 表里本团队的绑定字段提到顶层
+/// params:
+///   launched: 就地补 leader_receiver、team_owner 与 owner_epoch，已有同名键不覆盖
+/// ---
 pub(super) fn promote_launched_binding_from_team_entry(
     launched: &mut serde_json::Value,
     launched_key: &str,
@@ -383,6 +462,11 @@ pub(super) fn promote_launched_binding_from_team_entry(
     }
 }
 
+/// ---
+/// purpose: 顶层 owner 的 pane 不像真实 pane 时把顶层绑定字段整组删掉
+/// params:
+///   state: 就地删 leader_receiver、team_owner 与 owner_epoch
+/// ---
 pub(super) fn drop_unbound_top_level_owner(state: &mut serde_json::Value) {
     let pane = state
         .get("team_owner")
@@ -399,6 +483,12 @@ pub(super) fn drop_unbound_top_level_owner(state: &mut serde_json::Value) {
     }
 }
 
+/// ---
+/// purpose: 本次 owner 的 pane 已属于别的团队时，改种 unbound owner 或整组删除
+/// params:
+///   existing: 既有 state，用于判断 pane 归属
+///   launched: 就地改写
+/// ---
 pub(super) fn drop_foreign_seeded_owner(
     existing: &serde_json::Value,
     launched_key: &str,
@@ -434,6 +524,13 @@ pub(super) fn drop_foreign_seeded_owner(
     }
 }
 
+/// ---
+/// purpose: 识别 owner 是被 worker 自己的 pane 误种的情形并改种 unbound owner
+/// params:
+///   started: 本次起的席位，用于判断 pane 是否属于 worker
+///   worker_tmux_socket: worker 侧 socket 名，与调用方 socket 比对
+/// returns: 只有在无 leader 身份环境、pane 与调用方 TMUX_PANE 相同且看起来是 worker pane 时才改种
+/// ---
 pub(super) fn drop_worker_pane_seeded_owner(
     launched: &mut serde_json::Value,
     launched_key: &str,
@@ -466,6 +563,10 @@ pub(super) fn drop_worker_pane_seeded_owner(
     }
 }
 
+/// ---
+/// purpose: 判断某 pane 是否像本次起的 worker 的 pane
+/// returns: 形如首席 pane，或与任一席位目标互为前缀时为 true
+/// ---
 pub(super) fn seeded_pane_looks_like_worker(pane: &str, started: &[StartedAgent]) -> bool {
     pane.ends_with("-first")
         || started.iter().any(|agent| {
@@ -475,6 +576,10 @@ pub(super) fn seeded_pane_looks_like_worker(pane: &str, started: &[StartedAgent]
         })
 }
 
+/// ---
+/// purpose: 给出 worker 侧使用的 tmux socket 名
+/// returns: transport 是 tmux 后端时按 workspace 推出 socket 名，否则 None
+/// ---
 pub(super) fn launched_worker_tmux_socket(
     transport: &dyn Transport,
     workspace: &Path,
@@ -486,6 +591,10 @@ pub(super) fn launched_worker_tmux_socket(
     }
 }
 
+/// ---
+/// purpose: 判断两侧 socket 是否一致或不可判
+/// returns: 两侧都已知时比相等；调用方已知而 worker 未知时为 false；调用方未知时一律为 true
+/// ---
 pub(super) fn tmux_sockets_match_or_unknown(
     caller_socket: Option<&str>,
     worker_socket: Option<&str>,