@team-agent/installer 0.2.11 → 0.3.0

package/crates/team-agent/src/leader/start.rs

@@ -0,0 +1,273 @@
+//! leader::start — leader_start_plan / start_leader / leader_session_name(派生 tmux session 名)。
+
+use std::collections::BTreeMap;
+use std::path::Path;
+use std::process::Command;
+
+use crate::provider::{get_adapter, Provider};
+use crate::tmux_backend::TmuxBackend;
+use crate::transport::{SessionName, Transport};
+
+use super::helpers::{
+    provider_wire, resolve_workspace_for_hash, sanitize_session_folder, sha1_hex_prefix,
+};
+use super::owner_bind::leader_identity_context;
+use super::{LeaderError, LeaderStartMode, LeaderStartPlan};
+
+// ── leader::start — leader_start_plan / start_leader / session 名 ──
+
+/// `leader_start_plan`(card §46;`__init__.py:82`)。计算 leader 启动计划
+/// (exec in-TMUX / new tmux session / attach existing)。provider 未安装 → `Err(Start)`。
+pub fn leader_start_plan(
+    provider: Provider,
+    provider_args: &[String],
+    workspace: &Path,
+    attach_existing: bool,
+    confirm_attach: bool,
+    attach_session: Option<&SessionName>,
+) -> Result<LeaderStartPlan, LeaderError> {
+    if attach_session.is_some() && !confirm_attach {
+        return Err(LeaderError::Start("--attach-session requires --confirm".to_string()));
+    }
+    if attach_existing && !confirm_attach {
+        return Err(LeaderError::Start("attach existing leader session requires confirm".to_string()));
+    }
+    let adapter = get_adapter(provider);
+    if !adapter.is_installed() {
+        let command_name = provider_command_name(provider);
+        return Err(LeaderError::Start(format!(
+            "Provider {} command '{}' not found",
+            provider_wire(provider),
+            command_name
+        )));
+    }
+    let identity = leader_identity_context(workspace, None, None)?;
+    let session_name = attach_session
+        .cloned()
+        .or_else(|| Some(leader_session_name(provider, workspace)));
+    let in_tmux = std::env::var_os("TMUX").is_some();
+    if !in_tmux {
+        ensure_tmux_installed()?;
+    }
+    let existing_session = if !in_tmux && !attach_existing && attach_session.is_none() {
+        match session_name.as_ref() {
+            Some(session) => tmux_session_exists(workspace, session)?,
+            None => false,
+        }
+    } else {
+        false
+    };
+    let mode = if in_tmux {
+        LeaderStartMode::ExecProvider
+    } else if attach_existing || attach_session.is_some() || existing_session {
+        LeaderStartMode::AttachExisting
+    } else {
+        LeaderStartMode::NewTmuxSession
+    };
+    let mut leader_env = BTreeMap::new();
+    leader_env.insert("TEAM_AGENT_LEADER_PROVIDER".to_string(), provider_wire(provider).to_string());
+    leader_env.insert(
+        "TEAM_AGENT_LEADER_SESSION_UUID".to_string(),
+        identity.leader_session_uuid.as_str().to_string(),
+    );
+    leader_env.insert(
+        "TEAM_AGENT_MACHINE_FINGERPRINT".to_string(),
+        identity.machine_fingerprint.clone(),
+    );
+    leader_env.insert(
+        "TEAM_AGENT_WORKSPACE".to_string(),
+        identity.workspace_abspath.to_string_lossy().into_owned(),
+    );
+    leader_env.insert("TEAM_AGENT_TEAM_ID".to_string(), identity.team_id.as_str().to_string());
+    let argv = start_argv(mode, provider, provider_args, workspace, session_name.as_ref(), &leader_env)?;
+    let plan_env = if mode == LeaderStartMode::ExecProvider {
+        merged_exec_env(&leader_env)
+    } else {
+        leader_env.clone()
+    };
+    Ok(LeaderStartPlan {
+        mode,
+        provider,
+        workspace: resolve_workspace_for_hash(workspace),
+        session_name,
+        argv,
+        leader_env: plan_env,
+        identity: Some(identity),
+        detached: false,
+    })
+}
+
+/// `start_leader`(card §46;`__init__.py:60`)。计算并执行 leader 启动计划(spawn + 信号处理)。
+/// 进程退出后 `Err`/退出码经 caller 处理(此处返 `Result` 替代 Python 的 `SystemExit`)。
+pub fn start_leader(
+    provider: Provider,
+    provider_args: &[String],
+    workspace: &Path,
+    attach_existing: bool,
+    confirm_attach: bool,
+    attach_session: Option<&SessionName>,
+) -> Result<(), LeaderError> {
+    let plan = leader_start_plan(
+        provider,
+        provider_args,
+        workspace,
+        attach_existing,
+        confirm_attach,
+        attach_session,
+    )?;
+    crate::event_log::EventLog::new(workspace).write(
+        super::LeaderEvent::LeaderStart.name(),
+        serde_json::json!({
+            "provider": super::helpers::provider_wire(plan.provider),
+            "mode": serde_json::to_value(plan.mode)?,
+            "session_name": plan.session_name.as_ref().map(|s| s.as_str().to_string()),
+        }),
+    )?;
+    Ok(())
+}
+
+/// `leader_session_name`(card §48;`__init__.py:186`)。确定派生 tmux session 名
+/// `team-agent-leader-<provider>-<folder>-<sha1[:8]>`(workspace.resolve() 的 sha1 前 8 hex)。
+pub fn leader_session_name(provider: Provider, workspace: &Path) -> SessionName {
+    let resolved = resolve_workspace_for_hash(workspace);
+    let folder_raw = resolved
+        .file_name()
+        .and_then(|n| n.to_str())
+        .unwrap_or("workspace");
+    let folder = sanitize_session_folder(folder_raw);
+    let hash = sha1_hex_prefix(resolved.to_string_lossy().as_bytes(), 8);
+    SessionName::new(format!(
+        "team-agent-leader-{}-{folder}-{hash}",
+        provider_wire(provider)
+    ))
+}
+
+fn start_argv(
+    mode: LeaderStartMode,
+    provider: Provider,
+    provider_args: &[String],
+    workspace: &Path,
+    session_name: Option<&SessionName>,
+    leader_env: &BTreeMap<String, String>,
+) -> Result<Vec<String>, LeaderError> {
+    let provider_cmd = provider_command_name(provider).to_string();
+    match mode {
+        LeaderStartMode::ExecProvider => {
+            let mut argv = vec![provider_cmd];
+            argv.extend(provider_args.iter().cloned());
+            Ok(argv)
+        }
+        LeaderStartMode::AttachExisting => {
+            let Some(session) = session_name else {
+                return Err(LeaderError::Start("attach session missing".to_string()));
+            };
+            Ok(vec![
+                "tmux".to_string(),
+                "attach-session".to_string(),
+                "-t".to_string(),
+                session.as_str().to_string(),
+            ])
+        }
+        LeaderStartMode::NewTmuxSession => {
+            let Some(session) = session_name else {
+                return Err(LeaderError::Start("leader session missing".to_string()));
+            };
+            let resolved_workspace = resolve_workspace_for_hash(workspace);
+            let mut exports = leader_export_assignments(leader_env);
+            if let Some(path) = std::env::var_os("PATH").and_then(|p| p.into_string().ok()) {
+                exports.push(shlex_quote(&format!("PATH={path}")));
+            }
+            let mut provider_argv = vec![provider_cmd];
+            provider_argv.extend(provider_args.iter().cloned());
+            let shell = format!(
+                "cd {} && export {} && exec {}",
+                shlex_quote(&resolved_workspace.to_string_lossy()),
+                exports.join(" "),
+                shell_join(&provider_argv)
+            );
+            Ok(vec![
+                "tmux".to_string(),
+                "new-session".to_string(),
+                "-s".to_string(),
+                session.as_str().to_string(),
+                "-n".to_string(),
+                provider_wire(provider).to_string(),
+                "-c".to_string(),
+                resolved_workspace.to_string_lossy().into_owned(),
+                "sh".to_string(),
+                "-lc".to_string(),
+                shell,
+            ])
+        }
+    }
+}
+
+fn ensure_tmux_installed() -> Result<(), LeaderError> {
+    match Command::new("tmux").arg("-V").output() {
+        Ok(output) if output.status.success() => Ok(()),
+        Ok(_) | Err(_) => Err(LeaderError::Start(
+            "tmux is not installed; install tmux 3.3+ or start the leader from an existing tmux pane"
+                .to_string(),
+        )),
+    }
+}
+
+fn provider_command_name(provider: Provider) -> &'static str {
+    match provider {
+        Provider::Claude | Provider::ClaudeCode => "claude",
+        Provider::Codex => "codex",
+        Provider::GeminiCli => "gemini",
+        Provider::Fake => "fake",
+    }
+}
+
+fn tmux_session_exists(workspace: &Path, session: &SessionName) -> Result<bool, LeaderError> {
+    TmuxBackend::for_workspace(workspace)
+        .has_session(session)
+        .map_err(|e| LeaderError::Start(format!("tmux has-session failed: {e}")))
+}
+
+fn leader_export_assignments(leader_env: &BTreeMap<String, String>) -> Vec<String> {
+    [
+        "TEAM_AGENT_LEADER_PROVIDER",
+        "TEAM_AGENT_LEADER_SESSION_UUID",
+        "TEAM_AGENT_MACHINE_FINGERPRINT",
+        "TEAM_AGENT_WORKSPACE",
+        "TEAM_AGENT_TEAM_ID",
+    ]
+    .iter()
+    .filter_map(|key| {
+        leader_env
+            .get(*key)
+            .map(|value| shlex_quote(&format!("{key}={value}")))
+    })
+    .collect()
+}
+
+fn merged_exec_env(leader_env: &BTreeMap<String, String>) -> BTreeMap<String, String> {
+    let mut env: BTreeMap<String, String> = std::env::vars().collect();
+    env.extend(leader_env.iter().map(|(key, value)| (key.clone(), value.clone())));
+    env
+}
+
+fn shell_join(args: &[String]) -> String {
+    args.iter().map(|arg| shlex_quote(arg)).collect::<Vec<_>>().join(" ")
+}
+
+fn shlex_quote(raw: &str) -> String {
+    if !raw.is_empty()
+        && raw
+            .bytes()
+            .all(|b| {
+                b.is_ascii_alphanumeric()
+                    || matches!(
+                        b,
+                        b'@' | b'%' | b'_' | b'+' | b'=' | b':' | b',' | b'.' | b'/' | b'-'
+                    )
+            })
+    {
+        raw.to_string()
+    } else {
+        format!("'{}'", raw.replace('\'', "'\"'\"'"))
+    }
+}

package/crates/team-agent/src/leader/takeover.rs

@@ -0,0 +1,235 @@
+//! leader::takeover — idle take-over 决策面:build_idle_nodes / leader_node /
+//! classify_provider_turn_state / evaluate_takeover_reminder / record_turn_open_after_delivery
+//! + provider-neutral wake 层(should_reread / on_file_changed / take_pending)。
+
+use std::path::PathBuf;
+
+use serde_json::{json, Value};
+
+use crate::provider::{Provider, RolloutPath, TurnState};
+
+use super::helpers::{parse_provider, provider_wire, read_rollout_text, turn_state_wire};
+use super::{
+    IdleNode, LeaderError, LeaderEvent, NodeRole, RereadDecision, RereadReason,
+    TakeoverReminderResult, TurnClassification, TurnStateClassifier, WakeWatchState,
+};
+
+// ── leader::idle — build_idle_nodes / push_idle_reminder(coordinator tick 面)──
+
+/// `build_idle_nodes`(card §50;`idle_takeover_wiring.py:20`)。从每个 live node 的 provider
+/// session-log 文件分类 turn 状态(**绝不读 pane 屏幕**)。
+/// **bug-085**:`rollout_path=None` → 该 node `Unknown`(不猜 idle);leader path/provider 缺
+/// 则省略 leader 节点(`_leader_node` 返 `None`)而非猜 idle。
+/// **MUST-NOT-13**:分类走 `read_turn_state`(provider_state trait,注入 mock),零 provider client。
+pub fn build_idle_nodes(
+    state: &Value,
+    classifier: &dyn TurnStateClassifier,
+) -> Result<Vec<IdleNode>, LeaderError> {
+    let mut nodes = Vec::new();
+    if let Some(agents) = state.get("agents").and_then(Value::as_object) {
+        for (node_id, agent) in agents {
+            if matches!(
+                agent.get("status").and_then(Value::as_str),
+                Some("stopped" | "paused")
+            ) {
+                continue;
+            }
+            let Some(provider) = agent.get("provider").and_then(Value::as_str).and_then(parse_provider) else {
+                continue;
+            };
+            let rollout_path = agent
+                .get("rollout_path")
+                .and_then(Value::as_str)
+                .map(|p| RolloutPath::new(PathBuf::from(p)));
+            let text = read_rollout_text(rollout_path.as_ref())?;
+            let classification = classifier.classify(provider, &text)?;
+            nodes.push(IdleNode {
+                node_id: node_id.clone(),
+                role: NodeRole::Worker,
+                state: classification.state,
+                turn_id: classification.turn_id,
+                annotations: classification.annotations,
+                provider: Some(provider),
+                auth_mode: agent.get("auth_mode").and_then(Value::as_str).map(str::to_string),
+                rollout_path,
+            });
+        }
+    }
+    if let Some(node) = leader_node(state, classifier)? {
+        nodes.push(node);
+    }
+    Ok(nodes)
+}
+
+/// `_leader_node`(`idle_takeover_wiring.py:77`)。leader 自身 transcript 分类(C13)。
+/// path 或 provider 缺 → `None`(省略而非猜 idle)。
+pub fn leader_node(
+    state: &Value,
+    classifier: &dyn TurnStateClassifier,
+) -> Result<Option<IdleNode>, LeaderError> {
+    let leader = state.get("leader");
+    let receiver = state.get("leader_receiver");
+    let provider = leader
+        .and_then(|l| l.get("provider"))
+        .and_then(Value::as_str)
+        .or_else(|| receiver.and_then(|r| r.get("provider")).and_then(Value::as_str))
+        .and_then(parse_provider);
+    let rollout_path = leader
+        .and_then(|l| l.get("rollout_path"))
+        .and_then(Value::as_str)
+        .or_else(|| receiver.and_then(|r| r.get("rollout_path")).and_then(Value::as_str))
+        .map(|p| RolloutPath::new(PathBuf::from(p)));
+    let (Some(provider), Some(rollout_path)) = (provider, rollout_path) else {
+        return Ok(None);
+    };
+    let text = read_rollout_text(Some(&rollout_path))?;
+    let classification = classifier.classify(provider, &text)?;
+    Ok(Some(IdleNode {
+        node_id: "leader".to_string(),
+        role: NodeRole::Leader,
+        state: classification.state,
+        turn_id: classification.turn_id,
+        annotations: classification.annotations,
+        provider: Some(provider),
+        auth_mode: None,
+        rollout_path: Some(rollout_path),
+    }))
+}
+
+// ── leader::idle facade re-export(验收契约 import 面:from team_agent.idle_takeover import ...）──
+
+/// `classify_provider_turn_state`(card §51;`idle_takeover.py:18`)。门面:分类一个 node 的 turn
+/// 状态;`state ∈ {unknown, abnormal}` 且有 event_sink → 写 `idle_takeover.classify`。
+/// **unknown ≠ idle** 命门下游(`TurnState` 穷尽)。
+pub fn classify_provider_turn_state(
+    provider: Provider,
+    session_log_text: &str,
+    classifier: &dyn TurnStateClassifier,
+    event_log: Option<&crate::event_log::EventLog>,
+) -> Result<TurnClassification, LeaderError> {
+    let classification = classifier.classify(provider, session_log_text)?;
+    if matches!(classification.state, TurnState::Unknown | TurnState::Abnormal) {
+        if let Some(log) = event_log {
+            log.write(
+                LeaderEvent::IdleTakeoverClassify.name(),
+                json!({
+                    "provider": provider_wire(provider),
+                    "state": turn_state_wire(classification.state),
+                    "reason": classification.reason,
+                }),
+            )?;
+        }
+    }
+    Ok(classification)
+}
+
+/// `evaluate_takeover_reminder`(card §51 facade re-export)。provider-neutral 谓词:全 idle 且
+/// armed-after-delegation 才 `should_ping`。**CROSS-LANE**:真逻辑在 provider-neutral `idle_predicate`
+/// (step 8 相邻),此为 leader facade 暴露面。
+pub fn evaluate_takeover_reminder(
+    nodes: &[IdleNode],
+    arm_state: &Value,
+) -> Result<TakeoverReminderResult, LeaderError> {
+    let _ = arm_state;
+    if nodes.is_empty() {
+        return Ok(TakeoverReminderResult {
+            should_ping: false,
+            message: None,
+            interrupted_nodes: Vec::new(),
+            reason: Some("no_nodes".to_string()),
+        });
+    }
+    if let Some(blocking) = nodes.iter().find(|n| !n.state.is_idle_for_takeover()) {
+        return Ok(TakeoverReminderResult {
+            should_ping: false,
+            message: None,
+            interrupted_nodes: Vec::new(),
+            reason: Some(format!("node_{}", turn_state_wire(blocking.state))),
+        });
+    }
+    let interrupted_nodes = nodes
+        .iter()
+        .filter(|n| n.state == TurnState::IdleInterrupted)
+        .map(|n| n.node_id.clone())
+        .collect();
+    Ok(TakeoverReminderResult {
+        should_ping: true,
+        message: Some("All active nodes appear idle; leader takeover may be appropriate.".to_string()),
+        interrupted_nodes,
+        reason: Some("all_idle_debounce_elapsed".to_string()),
+    })
+}
+
+/// `record_turn_open_after_delivery`(card §51 / §80;facade re-export)。take-over arm **只来自
+/// 真实投递的 turn-open 边**,不凭空 arm。**CROSS-LANE**:真逻辑在 `idle_predicate`(step 8 相邻)。
+pub fn record_turn_open_after_delivery(
+    arm_state: &mut Value,
+    node_id: &str,
+    turn_id: Option<&str>,
+) -> Result<(), LeaderError> {
+    if !arm_state.is_object() {
+        *arm_state = json!({});
+    }
+    if let Some(obj) = arm_state.as_object_mut() {
+        obj.insert("armed".to_string(), Value::Bool(true));
+        obj.insert("node_id".to_string(), Value::String(node_id.to_string()));
+        obj.insert(
+            "turn_id".to_string(),
+            turn_id.map_or(Value::Null, |id| Value::String(id.to_string())),
+        );
+    }
+    Ok(())
+}
+
+// ── leader::wake — provider-neutral wake 层(纯函数,不解析/不轮询/无 provider 名)──
+
+/// `should_reread`(card §52;`wake.py:16`)。决定是否值得重读 session 文件尾巴 + 为何。
+/// 纯函数:file 变了 / 静默超 debounce 且未在此 mtime 分类过。provider-neutral(C6)。
+pub fn should_reread(
+    last_mtime: Option<f64>,
+    current_mtime: Option<f64>,
+    last_classified_mtime: Option<f64>,
+    now: f64,
+    debounce_seconds: f64,
+) -> RereadDecision {
+    let _ = last_mtime;
+    let Some(current) = current_mtime else {
+        return RereadDecision { reread: false, reason: RereadReason::NoFile };
+    };
+    let Some(classified) = last_classified_mtime else {
+        return RereadDecision { reread: true, reason: RereadReason::NeverClassified };
+    };
+    if current != classified {
+        return RereadDecision { reread: true, reason: RereadReason::FileChanged };
+    }
+    let silent_for = (now - current).max(0.0);
+    if silent_for >= debounce_seconds {
+        RereadDecision { reread: false, reason: RereadReason::QuiescentAlreadyClassified }
+    } else {
+        RereadDecision { reread: false, reason: RereadReason::Unchanged }
+    }
+}
+
+/// `on_file_changed`(card §52;`wake.py:43`)。记录一个 node 的文件变更 wake(push 路径)。
+pub fn on_file_changed(
+    watch_state: Option<&WakeWatchState>,
+    node_id: &str,
+    mtime: f64,
+) -> WakeWatchState {
+    let mut state = watch_state.cloned().unwrap_or_default();
+    if !state.pending.iter().any(|p| p == node_id) {
+        state.pending.push(node_id.to_string());
+    }
+    state.pending.sort();
+    state.mtimes.insert(node_id.to_string(), mtime);
+    state
+}
+
+/// `take_pending`(card §52;`wake.py:53`)。排空自上次 drain 以来文件变更的 node 集。
+pub fn take_pending(watch_state: Option<&WakeWatchState>) -> (Vec<String>, WakeWatchState) {
+    let mut state = watch_state.cloned().unwrap_or_default();
+    let mut drained = state.pending.clone();
+    drained.sort();
+    state.pending.clear();
+    (drained, state)
+}