@team-agent/installer 0.5.66 → 0.5.69

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

@@ -390,10 +390,19 @@ fn compile_role_agent_with_mode(
     let id = required_string(&meta, role_path, "name")?;
     let role = required_string(&meta, role_path, "role")?;
     let provider = required_string(&meta, role_path, "provider")?;
+    require_explicit_grok_role_model(&meta, role_path, &provider)?;
+    require_explicit_cursor_role_model(&meta, role_path, &provider)?;
+    require_explicit_pi_role_fields(&meta, role_path, &provider)?;
     let model = resolve_model(&meta, team_meta, &provider);
     let auth_mode = string_field(&meta, "auth_mode")
         .or_else(|| string_field(team_meta, "default_auth_mode"))
         .unwrap_or_else(|| "subscription".to_string());
+    if parse_canonical_provider(&provider) == Some(Provider::Pi) && auth_mode != "subscription" {
+        return Err(ModelError::Validation(format!(
+            "{}: Pi roles support subscription auth_mode only",
+            role_path.display()
+        )));
+    }
     if auth_mode != "subscription" && meta.get("profile").is_none() {
         return Err(ModelError::Validation(format!(
             "{}: profile is required when auth_mode is '{auth_mode}'",
@@ -476,13 +485,25 @@ fn compile_role_agent_with_mode(
             })
             .unwrap_or("");
         let provider_enum = parse_canonical_provider(provider_str).unwrap_or(Provider::Codex);
-        if effort.is_claude_only() && !is_claude_family(provider_enum) {
+        if effort.is_claude_only()
+            && !is_claude_family(provider_enum)
+            && provider_enum != Provider::Pi
+        {
             return Err(ModelError::Validation(format!(
                 "{}: effort '{}' is only supported by claude/claude_code (provider: {provider_str})",
                 role_path.display(),
                 effort.as_str()
             )));
         }
+        if provider_enum == Provider::CursorAgent {
+            return Err(ModelError::Validation(format!(
+                "{}: cursor_agent does not support effort '{}'. \
+The Cursor CLI has no `--effort` flag; the framework must not drop the field and still launch. \
+Remove effort from the role file (do not map it into `--model[effort=]` until that form is measured).",
+                role_path.display(),
+                effort.as_str()
+            )));
+        }
         agent_items.push(("effort", Value::Str(effort.as_str().to_string())));
     }
     Ok(CompiledRole {
@@ -550,12 +571,107 @@ fn required_string(meta: &Value, path: &Path, key: &str) -> Result<String, Model
     })
 }
 
-/// 0.5.66 bypass 单源:角色 md 的 `dangerously_skip_permissions` 必填 bool。
-/// 缺 = 编译失败(消息含硬串);非 bool = 同 fail-loud。
-fn required_dangerously_skip_permissions(
+/// 缺 model 时框架会填内建默认（grok 上是 grok-4），席位因此静默拿到
+/// 与角色文件无关的模型和上下文窗口，而 argv 看起来完全正常。
+/// 角色文件必须自己写死；内建默认、team 级默认、CLI 全局默认都是隐式来源。
+fn require_explicit_grok_role_model(
+    meta: &Value,
+    path: &Path,
+    provider: &str,
+) -> Result<(), ModelError> {
+    if parse_canonical_provider(provider) != Some(Provider::Grok) {
+        return Ok(());
+    }
+    if string_field(meta, "model").is_some_and(|value| !value.trim().is_empty()) {
+        return Ok(());
+    }
+    Err(ModelError::Validation(format!(
+        "{}: missing front matter field model. \
+Without an explicit model the framework fills a built-in default (grok-4 for grok), \
+so the seat silently gets a model and context window that are not in the role file, \
+while argv still looks normal. The role file must name the model itself; \
+built-in defaults, team-level defaults, and the Grok CLI global default are all implicit sources. Example:\n\
+model: grok-4.6",
+        path.display()
+    )))
+}
+
+/// 缺 model 时框架曾填 builtin `sonnet-4-thinking`，本机 shim 还会剥掉该默认。
+/// 角色必须自己写死；内建默认、team 级默认、CLI 全局默认都是隐式来源。
+fn require_explicit_cursor_role_model(
+    meta: &Value,
+    path: &Path,
+    provider: &str,
+) -> Result<(), ModelError> {
+    if parse_canonical_provider(provider) != Some(Provider::CursorAgent) {
+        return Ok(());
+    }
+    if string_field(meta, "model").is_some_and(|value| !value.trim().is_empty()) {
+        return Ok(());
+    }
+    Err(ModelError::Validation(format!(
+        "{}: missing front matter field model. \
+Without an explicit model the framework fills a built-in default (sonnet-4-thinking for cursor_agent), \
+so the seat silently gets a model that is not in the role file, while argv still looks normal. \
+The role file must name the model itself; built-in defaults, team-level defaults, and the Cursor CLI default are all implicit sources. Example:\n\
+model: sonnet-4-thinking",
+        path.display()
+    )))
+}
+
+fn require_explicit_pi_role_fields(
     meta: &Value,
     path: &Path,
-) -> Result<bool, ModelError> {
+    provider: &str,
+) -> Result<(), ModelError> {
+    if parse_canonical_provider(provider) != Some(Provider::Pi) {
+        return Ok(());
+    }
+    let model = string_field(meta, "model")
+        .filter(|value| !value.trim().is_empty())
+        .ok_or_else(|| {
+            ModelError::Validation(format!(
+                "{}: Pi roles require an explicit qualified exact model",
+                path.display()
+            ))
+        })?;
+    let (catalog, name) = model.trim().split_once('/').ok_or_else(|| {
+        ModelError::Validation(format!(
+            "{}: Pi roles require a qualified exact model such as provider/model",
+            path.display()
+        ))
+    })?;
+    if catalog.is_empty() || name.is_empty() || model.contains('*') {
+        return Err(ModelError::Validation(format!(
+            "{}: Pi roles require a qualified exact model",
+            path.display()
+        )));
+    }
+    if !string_field(meta, "effort").is_some_and(|value| !value.trim().is_empty()) {
+        return Err(ModelError::Validation(format!(
+            "{}: Pi roles require explicit effort",
+            path.display()
+        )));
+    }
+    let tools = required_tools(meta, path)?;
+    if !tools.iter().any(|tool| tool == "mcp_team") {
+        return Err(ModelError::Validation(format!(
+            "{}: Pi roles require mcp_team",
+            path.display()
+        )));
+    }
+    match meta.get("dangerously_skip_permissions") {
+        Some(Value::Bool(true)) => Ok(()),
+        _ => Err(ModelError::Validation(format!(
+            "{}: Pi roles require dangerously_skip_permissions: true",
+            path.display()
+        ))),
+    }
+}
+
+/// 0.5.66 bypass 单源:角色 md 的 `dangerously_skip_permissions` 必填 bool。
+/// 缺 = 编译失败(消息含硬串);非 bool = 同 fail-loud。
+fn required_dangerously_skip_permissions(meta: &Value, path: &Path) -> Result<bool, ModelError> {
     match meta.get("dangerously_skip_permissions") {
         Some(Value::Bool(value)) => Ok(*value),
         Some(_) => Err(ModelError::Validation(format!(

package/crates/team-agent/src/coordinator/backoff.rs

@@ -1,3 +1,29 @@
+//! ---
+//! purpose: coordinator daemon 进程的宿主——装配 transport/registry，跑主循环，把 tick 的崩溃收进退避与事件
+//! contract:
+//!   provides:
+//!     - name: run_daemon
+//!       what: `team-agent coordinator --workspace ..` 子进程入口：解析 transport、构造 Coordinator、进主循环
+//!     - name: backoff_sleep_sec
+//!       what: 连续失败次数到睡眠秒数的纯函数（5→10→20→40→60→60，封顶 BACKOFF_MAX_SEC）
+//!     - name: resolve_tick_interval
+//!       what: 解析 tick 间隔并顺带确保 message store schema 可打开
+//!   depends:
+//!     - super::health
+//!     - super::tick
+//!     - super::types
+//!     - super::conpty_shim
+//!     - crate::state::persist
+//!     - crate::transport_factory
+//!     - crate::tmux_backend
+//!     - crate::message_store
+//!     - crate::event_log
+//! boundary:
+//!   - 不做单次 tick 的编排内容，tick 体在 tick.rs
+//!   - 不决定健康与否，只消费 health.rs 的判定与路径
+//!   - transport 解析失败时降级为 tmux workspace 后端保活，但不静默——降级原因写进 boot metadata
+//! maturity: wired
+//! ---
 //!
 //! daemon 主循环面(`__main__.py`)—— 退避序列 + tick 间隔解析 + 子进程入口。
 
@@ -41,6 +67,13 @@ pub struct DaemonArgs {
 /// daemon 主循环(`main`,`__main__.py:25-98`)。写 pid/meta(source=boot)、装信号→STOP、孤儿自检、
 /// catch-all + 指数退避 + tick_error 去重/抑制、tick_recovered 重置、`result.stop || once` → break。
 /// §10:返 `Result`(顶层 bin 用 anyhow 收;§12 边界)。
+/// ---
+/// purpose: daemon 进程入口——解析 transport 后端、构造 Coordinator、跑主循环直到 stop 或 --once
+/// params:
+///   args: workspace（已 resolve）、once、tick_interval_sec、可选 team_key；team_key 为空时回落到 state.active_team_key
+/// returns: 主循环正常退出（收到 STOP、tick 报 stop、或 --once 跑完一轮）时为 Ok
+/// errors: 写 pid/metadata、事件日志或 tick 间隔解析失败时返回 DaemonError
+/// ---
 pub fn run_daemon(args: DaemonArgs) -> Result<(), DaemonError> {
     // CP-1: the daemon's whole tick surface (has_session / capture / inject / list_windows / kill)
     // runs through this backend. Prefer the persisted runtime endpoint so attached explicit-socket
@@ -123,6 +156,14 @@ pub fn run_daemon(args: DaemonArgs) -> Result<(), DaemonError> {
     run_daemon_with_coordinator_and_boot_tmux(&args, &coordinator, Some(tmux_metadata))
 }
 
+/// ---
+/// purpose: 用调用方已装配好的 Coordinator 跑主循环（测试与内部复用入口，跳过 transport 解析）
+/// params:
+///   args: 与 run_daemon 同一份参数
+///   coordinator: 已注入 provider registry 与 transport 的实例
+/// returns: 与 run_daemon 相同的主循环退出语义
+/// errors: 同 run_daemon
+/// ---
 pub(crate) fn run_daemon_with_coordinator(
     args: &DaemonArgs,
     coordinator: &Coordinator,
@@ -520,6 +561,13 @@ fn current_ppid() -> u32 {
 
 /// 计算 tick 间隔(`_tick_interval`,`__main__.py:104-115`)。读 spec `runtime.tick_interval_sec`,
 /// 缺失/出错 → `DEFAULT_TICK_INTERVAL_SEC`;并确保 schema 存在(`MessageStore(workspace)`)。
+/// ---
+/// purpose: 取本 workspace 的 tick 间隔秒数，并顺带确保 message store schema 可打开
+/// params:
+///   workspace: 已 resolve 的 workspace 根
+/// returns: tick 间隔秒数；当前实现恒为 DEFAULT_TICK_INTERVAL_SEC（spec 覆盖尚未接线）
+/// errors: MessageStore::open 失败时返回 TickError
+/// ---
 pub(super) fn resolve_tick_interval(workspace: &WorkspacePath) -> Result<f64, TickError> {
     let _ = MessageStore::open(workspace.as_path())?;
     Ok(DEFAULT_TICK_INTERVAL_SEC)
@@ -527,6 +575,13 @@ pub(super) fn resolve_tick_interval(workspace: &WorkspacePath) -> Result<f64, Ti
 
 /// 退避序列(`__main__.py:65`):`min(interval * 2^min(failures-1, 5), 60.0)` → 5→10→20→40→60→60s。
 /// unit test 锁死本序列(card §85)。**纯函数,无 I/O,可直接 impl 钉死**(但 ROUND-0 仍占位)。
+/// ---
+/// purpose: 由连续失败次数算出本轮该睡多少秒的纯函数
+/// params:
+///   interval: 基准 tick 间隔秒数
+///   consecutive_failures: 至今连续失败次数；0 与 1 同视为首次失败
+/// returns: interval * 2^min(failures-1, 5)，上限 BACKOFF_MAX_SEC
+/// ---
 pub(super) fn backoff_sleep_sec(interval: f64, consecutive_failures: u32) -> f64 {
     let failures = consecutive_failures.saturating_sub(1).min(5);
     let exp = i32::try_from(failures).unwrap_or(5);

package/crates/team-agent/src/coordinator/conpty_shim.rs

@@ -1,3 +1,30 @@
+//! ---
+//! purpose: Windows ConPTY shim 的生命周期主人——定位并启动 windows-shim.exe、做 Hello 握手、把可复用的连接与 pid/pipe 名记进 state
+//! contract:
+//!   provides:
+//!     - name: ensure_shim_running
+//!       what: 幂等入口：state 里记的 shim 还活着就重连，否则新起一个并握手
+//!     - name: reconnect_recorded_shim
+//!       what: 只按 state 记的 pipe 名重连并重做 Hello，绝不新起进程
+//!     - name: recorded_shim_pid
+//!       what: 读 state.transport.shim.pid，供停机路由
+//!     - name: recorded_shim_pipe_name
+//!       what: 读 state.transport.shim.pipe_name，供重连路由
+//!     - name: mark_transport_unavailable
+//!       what: shim 不可达时发 stale 家族事件并清掉 state 里的 pipe_ready
+//!   depends:
+//!     - conpty_transport
+//!     - crate::state::repository
+//!     - crate::state::persist
+//!     - crate::event_log
+//!     - crate::platform::process
+//! boundary:
+//!   - pipe_token 绝不落 state：只经子进程环境变量传递并留在本进程内存里，state 只记 pid/pipe_name/pipe_ready
+//!   - 终态失败不静默回落 tmux，交由调用方按传输不可用处理
+//!   - 重连只证明线协议可用，不做新的令牌认证
+//!   - 整个文件仅在 Windows 编译；非 Windows 调用方必须自己 cfg 门控
+//! maturity: wired
+//! ---
 //!
 //! Windows ConPTY shim lifecycle manager.
 //!
@@ -75,16 +102,28 @@ pub struct ShimHandle {
 impl ShimHandle {
     /// The connected pipe client, ready for the factory to wire into
     /// `ConPtyBackend`. Callable exactly once — takes ownership.
+    /// ---
+    /// purpose: 取走已完成 Hello 握手的管道客户端，交给传输后端接线
+    /// returns: 首次调用返回客户端并转移所有权；再次调用为 None
+    /// ---
     pub fn take_client(&mut self) -> Option<NamedPipeClient> {
         self.client.take()
     }
 
     /// The shim pid (for status + shutdown routing).
+    /// ---
+    /// purpose: 给出 shim 进程号，用于状态展示与停机路由
+    /// returns: 启动时记下的 pid；子进程句柄已被 detach 或 drop 后该值仍可读
+    /// ---
     pub fn pid(&self) -> u32 {
         self.pid
     }
 
     /// The pipe name the shim listens on.
+    /// ---
+    /// purpose: 给出 shim 正在监听的命名管道名
+    /// returns: 形如 team-agent-conpty-<hash>-<team> 的管道全名
+    /// ---
     pub fn pipe_name(&self) -> &str {
         &self.pipe_name
     }
@@ -95,6 +134,11 @@ impl ShimHandle {
     /// an explicit `platform::process::terminate_pid` via
     /// `recorded_shim_pid`. Without this call, going out of scope
     /// would terminate the shim and orphan every worker.
+    /// ---
+    /// purpose: 放弃对 shim 子进程的所有权，使本句柄析构时不再杀它
+    /// returns: shim 的 pid，供调用方日后按精确 pid 显式终止
+    /// ---
+    /// 不调用它就让句柄离开作用域，会连带杀掉 shim 并使全部 worker 变成孤儿。
     pub fn detach(mut self) -> u32 {
         // Forget the child so its own Drop doesn't run either. The
         // shim survives until an explicit kill.
@@ -453,6 +497,12 @@ fn finalize(
 /// `None` when no shim is currently registered (Unix / never-launched
 /// Windows worker). Callers use `platform::process::terminate_pid`
 /// on the returned pid.
+/// ---
+/// purpose: 从 state 读出已登记的 shim 进程号
+/// params:
+///   workspace: workspace 根
+/// returns: state.transport.shim.pid 存在且能转成 u32 时给值；没有登记过 shim（未起过或非 Windows 队）时为 None。只读状态，不做存活探测
+/// ---
 pub fn recorded_shim_pid(workspace: &Path) -> Option<u32> {
     let state = crate::state::repository::StateRepository::new(workspace)
         .load_workspace_if_exists_without_migrations()
@@ -466,6 +516,12 @@ pub fn recorded_shim_pid(workspace: &Path) -> Option<u32> {
 }
 
 /// Read `state.transport.shim.pipe_name` for reconnect routing.
+/// ---
+/// purpose: 从 state 读出已登记的 shim 管道名
+/// params:
+///   workspace: workspace 根
+/// returns: state.transport.shim.pipe_name 的字符串值；未登记时为 None
+/// ---
 pub fn recorded_shim_pipe_name(workspace: &Path) -> Option<String> {
     let state = crate::state::repository::StateRepository::new(workspace)
         .load_workspace_if_exists_without_migrations()
@@ -497,6 +553,15 @@ pub fn recorded_shim_pipe_name(workspace: &Path) -> Option<String> {
 /// This gives the "coord can die, shim survives" invariant: a fresh
 /// coord that finds a live shim just reconnects; a fresh coord that
 /// finds no shim spawns one.
+/// ---
+/// purpose: 保证本 (workspace, team) 有一个可用的 shim——这是 coordinator 侧唯一的 shim 所有权入口
+/// params:
+///   workspace: workspace 根
+///   team_key: 目标 team，进 Hello 请求的作用域
+///   workspace_hash: 管道名里用的 workspace 摘要
+/// returns: 已登记 pid 还活着且重连成功 → 复用原进程的句柄（不拥有子进程）；否则新起一个并握手，返回拥有子进程的句柄
+/// errors: 找不到 shim 可执行文件、spawn 失败、连接超时、Hello 失败或落盘 state 失败时返回对应 ShimError。重连失败不算错误，会直接落到新起那条路
+/// ---
 pub fn ensure_shim_running(
     workspace: &Path,
     team_key: &str,
@@ -541,6 +606,15 @@ pub fn ensure_shim_running(
 /// Handle returned from this fn has no owned child (the shim is
 /// somebody else's — usually a previous coord instance). `detach()`
 /// on the handle is a no-op for the child.
+/// ---
+/// purpose: 只重连 state 里已登记的 shim 并重做 Hello，用来证明线协议仍然可用
+/// params:
+///   workspace: workspace 根
+///   team_key: 目标 team，进 Hello 请求的作用域
+///   _workspace_hash: 未使用；管道名直接取自 state，不再重算
+/// returns: 连上且 Hello 回 ok 时给出不拥有子进程的句柄，对它调 detach 对子进程是空操作
+/// errors: state 里没有管道名或多次连接均失败 → ConnectTimeout；连上但 Hello 回 ok=false → HelloFailed。本函数绝不新起进程
+/// ---
 pub fn reconnect_recorded_shim(
     workspace: &Path,
     team_key: &str,
@@ -630,6 +704,14 @@ fn reconnect_hello(client: &mut NamedPipeClient, team_key: &str) -> Result<(), S
 /// The Windows-only `#[cfg]` gate is at the mod level (see
 /// `coordinator/mod.rs`); on Unix this file isn't compiled, so
 /// downstream callers must cfg-gate their reference themselves.
+/// ---
+/// purpose: 把「shim 不可达」这件事诚实地写出去——发 stale 家族事件，并清掉 state 里的就绪位
+/// params:
+///   workspace: workspace 根
+///   reason: 不可达原因，同时进事件与 state.transport.shim.unavailable_reason
+/// returns: 状态里本来就没有 shim 块时也返回 Ok。事件写入是尽力而为，写不出去不影响返回；清状态才是权威动作
+/// errors: 读写 state 失败时返回 StateError；state JSON 损坏时按空状态继续
+/// ---
 pub fn mark_transport_unavailable(workspace: &Path, reason: &str) -> Result<(), StateError> {
     // Best-effort event emission — a failed event write should not
     // fail the caller. The state-clearing step below is authoritative.