@team-agent/installer 0.2.11 → 0.3.0

package/crates/team-agent/src/messaging/helpers.rs

@@ -0,0 +1,209 @@
+//! 私有内部 helpers (status wire / envelope 校验 / scheduled kind 解析 / activity 信号
+//! 解析 / id 生成 / MessageStatusShadow 占位)。跨子模块/测试可见者升 `pub(crate)`。
+
+use std::sync::atomic::{AtomicU64, Ordering};
+
+use rusqlite::{params, OptionalExtension};
+
+use crate::message_store::MessageStore;
+
+use super::{
+    ActivityStatus, AgentActivity, DeliveryOutcome, DeliveryRefusal, DeliveryStatus,
+    MessagingError, ScheduledKind,
+};
+
+/// **PLACEHOLDER** — step 7 `messages.status` 行态 enum (`message_store` lane 的 `MessageStatus`)。
+/// step 7 已落地 core 但尚未导出该 enum (当前用裸 `&str`);本 lane 不猜其精确 variant 集,
+/// 用本地最小占位让 [`DeliveryOutcome::message_status`] 编得过。leader 集成时换成 step 7 的
+/// 权威 `MessageStatus`(`accepted`/`target_resolved`/`injected`/`visible`/`submitted`/
+/// `submitted_unverified`/`delivered`/`acknowledged`/`failed`/`queued_*` …)。
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MessageStatusShadow(pub String);
+
+static RESULT_COUNTER: AtomicU64 = AtomicU64::new(0);
+
+pub(crate) fn status_wire(status: DeliveryStatus) -> &'static str {
+    match status {
+        DeliveryStatus::Delivered => "delivered",
+        DeliveryStatus::Failed => "failed",
+        DeliveryStatus::Queued => "queued",
+        DeliveryStatus::Blocked => "blocked",
+        DeliveryStatus::Refused => "refused",
+        DeliveryStatus::RetryScheduled => "retry_scheduled",
+        DeliveryStatus::TrustAutoAnswerExhausted => "trust_auto_answer_exhausted",
+        DeliveryStatus::AlreadyDelivered => "already_delivered",
+        DeliveryStatus::FallbackLog => "fallback_log",
+        DeliveryStatus::BroadcastDelivered => "broadcast_delivered",
+        DeliveryStatus::BroadcastPartial => "broadcast_partial",
+        DeliveryStatus::FanoutDelivered => "fanout_delivered",
+        DeliveryStatus::FanoutPartial => "fanout_partial",
+    }
+}
+
+pub(crate) fn message_exists(store: &MessageStore, message_id: &str) -> Result<bool, MessagingError> {
+    let conn = crate::db::schema::open_db(store.db_path())?;
+    let found: Option<String> = conn
+        .query_row(
+            "select message_id from messages where message_id = ?1",
+            params![message_id],
+            |row| row.get(0),
+        )
+        .optional()?;
+    Ok(found.is_some())
+}
+
+pub(crate) fn next_result_id() -> String {
+    let n = RESULT_COUNTER.fetch_add(1, Ordering::Relaxed);
+    let nanos = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map_or(0, |d| d.as_nanos());
+    format!("res_{:012x}", (nanos ^ u128::from(n)) & 0xFFFF_FFFF_FFFF)
+}
+
+pub(crate) fn next_run_id() -> String {
+    let id = next_result_id();
+    id.chars().filter(|c| *c != '_').take(12).collect()
+}
+
+pub(crate) fn required_str<'a>(value: &'a serde_json::Value, key: &str) -> Result<&'a str, MessagingError> {
+    value
+        .get(key)
+        .and_then(|v| v.as_str())
+        .filter(|s| !s.is_empty())
+        .ok_or_else(|| MessagingError::Validation(format!("missing required field: {key}")))
+}
+
+pub(crate) fn validate_result_envelope(envelope: &serde_json::Value) -> Result<(), MessagingError> {
+    let schema = required_str(envelope, "schema_version")?;
+    if schema != "result_envelope_v1" {
+        return Err(MessagingError::Validation(format!(
+            "unsupported schema_version: {schema}"
+        )));
+    }
+    for key in ["task_id", "agent_id", "status", "summary"] {
+        let _ = required_str(envelope, key)?;
+    }
+    for key in ["changes", "tests", "risks", "artifacts", "next_actions"] {
+        if !envelope.get(key).is_some_and(serde_json::Value::is_array) {
+            return Err(MessagingError::Validation(format!("missing required array field: {key}")));
+        }
+    }
+    Ok(())
+}
+
+pub(crate) fn parse_scheduled_kind(kind: &str) -> Result<ScheduledKind, MessagingError> {
+    match kind {
+        "send" => Ok(ScheduledKind::Send),
+        "health_ping" => Ok(ScheduledKind::HealthPing),
+        "trust_retry" => Ok(ScheduledKind::TrustRetry),
+        other => Err(MessagingError::Validation(format!(
+            "unknown scheduled event kind: {other}"
+        ))),
+    }
+}
+
+pub(crate) fn working_seconds(scrollback: &str) -> Option<u64> {
+    let lower = scrollback.to_ascii_lowercase();
+    let start = lower.find("working (")?;
+    let rest = scrollback.get(start + "Working (".len()..)?;
+    let seconds = rest.split_once('s')?.0;
+    seconds.parse::<u64>().ok()
+}
+
+pub(crate) fn non_provider_command(command: &str) -> Option<&str> {
+    let base = command.rsplit('/').next().unwrap_or(command);
+    let normalized = base.to_ascii_lowercase();
+    match normalized.as_str() {
+        "" | "codex" | "claude" | "gemini" | "openai" | "team-agent" => None,
+        _ => Some(base),
+    }
+}
+
+pub(crate) fn latest_prompt_signal(scrollback: &str) -> Option<AgentActivity> {
+    let lower = scrollback.to_ascii_lowercase();
+    let idle_pos = latest_idle_prompt_pos(scrollback);
+    let working_pos = ["working", "thinking", "⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+        .iter()
+        .filter_map(|needle| lower.rfind(needle))
+        .max();
+    match (idle_pos, working_pos) {
+        (Some(i), Some(w)) if i > w => Some(idle_activity()),
+        (Some(_), None) => Some(idle_activity()),
+        (_, Some(_)) => Some(AgentActivity {
+            status: ActivityStatus::Working,
+            confidence: 0.9,
+            rationale: "working_indicator".to_string(),
+        }),
+        (None, None) => None,
+    }
+}
+
+fn latest_idle_prompt_pos(scrollback: &str) -> Option<usize> {
+    scrollback
+        .match_indices('❯')
+        .map(|(idx, _)| idx)
+        .chain(scrollback.match_indices('›').map(|(idx, _)| idx))
+        .max()
+}
+
+fn idle_activity() -> AgentActivity {
+    AgentActivity {
+        status: ActivityStatus::Idle,
+        confidence: 0.9,
+        rationale: "idle_prompt".to_string(),
+    }
+}
+
+/// `_fail_leader_delivery` (`leader.py:394`) — **diagnostic ONLY** (#230 I-4 退化):
+/// 历史上返回 `ok=True/status=FallbackLog/channel="fallback_inbox"` 被上游误读为
+/// "已交付的 fallback log"。现新 leader-delivery primitive(`leader_receiver::send_to_leader_receiver`)
+/// 不再调本函数。本函数保留只供老代码路径(scheduler / 兼容旧测试)使用,且其
+/// outcome **不被视为 success**(I-3 反向断言要求 `leader_receiver.rs` 源文件不得含
+/// `DeliveryStatus::FallbackLog` 或 `fallback_inbox` 字面量,所以本函数从 `leader_receiver.rs`
+/// 搬到本 helpers 模块,字面量在此被允许)。
+pub fn fail_leader_delivery(
+    workspace: &std::path::Path,
+    payload: &serde_json::Value,
+    reason: DeliveryRefusal,
+    error: Option<&str>,
+) -> Result<DeliveryOutcome, MessagingError> {
+    let store = MessageStore::open(workspace)?;
+    let sender = payload.get("sender").and_then(serde_json::Value::as_str).unwrap_or("system");
+    let content = payload.get("content").and_then(serde_json::Value::as_str).unwrap_or("");
+    let task_id = payload.get("task_id").and_then(serde_json::Value::as_str);
+    let message_id = match payload.get("message_id").and_then(serde_json::Value::as_str) {
+        Some(existing) => existing.to_string(),
+        None => store.create_message(task_id, sender, "leader", content, None, false, None)?,
+    };
+    store.mark(&message_id, "failed", error)?;
+    crate::event_log::EventLog::new(workspace).write(
+        "leader_receiver.delivery_failed",
+        serde_json::json!({"message_id": message_id, "reason": serde_json::to_value(reason).ok(), "error": error}),
+    )?;
+    Ok(DeliveryOutcome {
+        ok: true,
+        status: DeliveryStatus::FallbackLog,
+        message_status: MessageStatusShadow("failed".to_string()),
+        message_id: Some(message_id),
+        verification: None,
+        stage: None,
+        reason: Some(reason),
+        channel: Some("fallback_inbox".to_string()),
+    })
+}
+
+pub(crate) fn recent_rfc3339(ts: &str, max_age_seconds: i64) -> bool {
+    let Ok(parsed) = chrono::DateTime::parse_from_rfc3339(ts) else {
+        return false;
+    };
+    let age = chrono::Utc::now().signed_duration_since(parsed.with_timezone(&chrono::Utc));
+    age.num_seconds() <= max_age_seconds
+}
+
+pub(crate) fn stale_rfc3339(ts: &str, min_age_seconds: i64) -> bool {
+    let Ok(parsed) = chrono::DateTime::parse_from_rfc3339(ts) else {
+        return false;
+    };
+    let age = chrono::Utc::now().signed_duration_since(parsed.with_timezone(&chrono::Utc));
+    age.num_seconds() >= min_age_seconds
+}

package/crates/team-agent/src/messaging/leader_receiver.rs

@@ -0,0 +1,340 @@
+//! leader.py — leader pane 注入边界 + 恰好一次去重门 (card §21/§72)。
+
+use std::path::Path;
+
+use serde_json::Value;
+
+use crate::event_log::EventLog;
+use crate::message_store::{MessageStore, NotificationClaimParams};
+use crate::model::ids::{OwnerEpoch, TaskId};
+use crate::transport::Transport;
+
+use super::helpers::MessageStatusShadow;
+use super::{DeliveryOutcome, DeliveryRefusal, DeliveryStatus, MessagingError};
+
+/// `_send_to_leader_receiver` (`leader.py:69`) — **N31/N32 funnel primitive**:所有 leader-bound
+/// caller(send_message(to=leader) / report_result / request_human / idle reminder /
+/// broadcast-to-leader / peer-mirror / worker.abnormal_exit)统一经过这里。
+///
+/// 职责 = create_message + leader_notification_log dedup(result_id 时)+ audit + emit
+/// `deliver_to_leader.submit`(funnel 指纹,契约 grep 用)。**不**预 claim:状态留 `accepted`,
+/// 让后续 `deliver_pending_messages` 同一管道做物理 inject(MUST-13 单注入点,leader/worker 同路径
+/// → #229 step2-gate 的 trust-defer 对 leader pane 自然适用)。**不**调 `fail_leader_delivery`
+/// 走 fallback inbox 假绿:无可用 leader pane → 返 `Blocked + channel=rebind_required`(I-4)。
+#[allow(clippy::too_many_arguments)]
+pub fn send_to_leader_receiver(
+    workspace: &Path,
+    state: &serde_json::Value,
+    leader_id: &str,
+    content: &str,
+    task_id: Option<&TaskId>,
+    sender: &str,
+    requires_ack: bool,
+    result_id: Option<&str>,
+    event_log: &EventLog,
+) -> Result<DeliveryOutcome, MessagingError> {
+    let store = MessageStore::open(workspace)?;
+    let owner_team = active_team_key(workspace, state);
+    if requires_ack {
+        event_log.write(
+            "leader_receiver.no_ack_forced",
+            serde_json::json!({"sender": sender, "leader_id": leader_id, "result_id": result_id}),
+        )?;
+    }
+    let message_id = store.create_message(
+        task_id.map(TaskId::as_str),
+        sender,
+        leader_id,
+        content,
+        None,
+        false,
+        Some(&owner_team),
+    )?;
+    // #231 exactly-once across rebind: insert the leader_notification_log PK BEFORE the
+    // unbound-pane check. That way, if the result row gets blocked (I-4) and later the
+    // leader rebinds + reclaim replays this row, the dedup PK still gates any second
+    // report_result attempt with the same result_id (no duplicate notification).
+    if let Some(result_id) = result_id {
+        let claim = store.claim_leader_notification_delivery(NotificationClaimParams {
+            result_id,
+            owner_team_id: Some(&owner_team),
+            owner_epoch: owner_epoch_i64(state),
+            leader_session_uuid: leader_session_uuid(state),
+            proposed_message_id: &message_id,
+            envelope_hash: "",
+            pane_id: leader_pane_id(state),
+        })?;
+        if claim.status != "claimed_by_you" {
+            // Duplicate result_id: keep first winner's notified_message_id, drop this row
+            // by marking failed (deliver_pending will then skip it on its claim guard).
+            store.mark(&message_id, "failed", Some("already_notified_by"))?;
+            event_log.write(
+                "deliver_to_leader.submit",
+                serde_json::json!({
+                    "message_id": claim.notified_message_id,
+                    "leader_id": leader_id,
+                    "owner_team_id": owner_team,
+                    "result_id": result_id,
+                    "dedup": "already_notified_by",
+                }),
+            )?;
+            return Ok(DeliveryOutcome {
+                ok: true,
+                status: DeliveryStatus::AlreadyDelivered,
+                message_status: MessageStatusShadow("already_notified".to_string()),
+                message_id: Some(claim.notified_message_id),
+                verification: None,
+                stage: None,
+                reason: None,
+                channel: Some("leader_receiver".to_string()),
+            });
+        }
+    }
+    // #230 funnel fingerprint: deliver_to_leader.submit is emitted on EVERY funnel call,
+    // including the I-4 unbound case below — the worker's intent IS to submit to leader,
+    // the rebind path will replay this row through deliver_pending once the leader pane
+    // is bound. Emitting submit only on bound would skew the funnel audit and miss the
+    // exactly-once guarantee for blocked-then-reclaimed deliveries.
+    event_log.write(
+        "deliver_to_leader.submit",
+        serde_json::json!({
+            "message_id": message_id,
+            "leader_id": leader_id,
+            "owner_team_id": owner_team,
+            "sender": sender,
+            "result_id": result_id,
+        }),
+    )?;
+    // I-4: unbound leader pane → rebind_required (not the legacy diagnostic success).
+    // The row IS persisted (caller / rebind audit / future replay need the message_id),
+    // but marked `failed` so `deliver_pending_messages` does NOT pick it up — pane stays
+    // untouched, ok=false, channel=rebind_required. #231 auto-reclaim's
+    // requeue_after_claim_leader flips this row back to `accepted` after rebind, and
+    // deliver_pending replays it through the same pipeline (same message_id, exactly once).
+    let pane_attached = leader_pane_id(state)
+        .filter(|pane_id| leader_pane_is_live(workspace, pane_id))
+        .is_some();
+    if !pane_attached {
+        let _ = store.mark(&message_id, "failed", Some("leader_not_attached"));
+        event_log.write(
+            "leader_receiver.delivery_blocked",
+            serde_json::json!({
+                "message_id": message_id,
+                "sender": sender,
+                "leader_id": leader_id,
+                "owner_team_id": owner_team,
+                "reason": "leader_not_attached",
+                "channel": "rebind_required",
+                "action": "run team-agent claim-leader or team-agent takeover",
+            }),
+        )?;
+        return Ok(DeliveryOutcome {
+            ok: false,
+            status: DeliveryStatus::Blocked,
+            message_status: MessageStatusShadow("blocked".to_string()),
+            message_id: Some(message_id),
+            verification: None,
+            stage: None,
+            reason: Some(DeliveryRefusal::LeaderNotAttached),
+            channel: Some("rebind_required".to_string()),
+        });
+    }
+    event_log.write(
+        "leader_receiver.queued",
+        serde_json::json!({
+            "message_id": message_id,
+            "leader_id": leader_id,
+            "owner_team_id": owner_team,
+            "result_id": result_id,
+        }),
+    )?;
+    Ok(DeliveryOutcome {
+        ok: true,
+        status: DeliveryStatus::Queued,
+        message_status: MessageStatusShadow("accepted".to_string()),
+        message_id: Some(message_id),
+        verification: None,
+        stage: None,
+        reason: None,
+        channel: Some("leader_receiver".to_string()),
+    })
+}
+
+/// `claim_leader_receiver` (`leader.py:348`):认领/接管 leader pane + `owner_epoch++`。身份判定
+/// 借 step 10 原语 (`_target_matches_owner_identity`/`_leader_command_looks_usable`)。
+pub fn claim_leader_receiver(
+    workspace: &Path,
+    state: &mut serde_json::Value,
+    candidate: &serde_json::Value,
+    event_log: &EventLog,
+    confirm: bool,
+    expected_epoch: Option<OwnerEpoch>,
+) -> Result<serde_json::Value, MessagingError> {
+    if !confirm {
+        return Ok(serde_json::json!({
+            "ok": false,
+            "status": "refused",
+            "reason": "confirm_required",
+            "action": "team-agent claim-leader --confirm",
+        }));
+    }
+    if let Some(expected) = expected_epoch {
+        if owner_epoch(state).is_some_and(|current| current != expected.0) {
+            let owner_epoch = owner_epoch(state).unwrap_or(0);
+            let bound_pane_id = leader_pane_id(state).map(ToString::to_string);
+            let value = serde_json::json!({
+                "ok": false,
+                "status": "refused",
+                "reason": "owner_epoch_advanced",
+                "owner_epoch": owner_epoch,
+                "bound_pane_id": bound_pane_id,
+            });
+            event_log.write("leader_receiver.claim_refused", value.clone())?;
+            return Ok(value);
+        }
+    }
+    let candidate_pane = candidate.get("pane_id").and_then(Value::as_str);
+    if candidate_pane.is_some() && candidate_pane == leader_pane_id(state) {
+        return Ok(serde_json::json!({
+            "ok": true,
+            "status": "already_bound",
+            "pane_id": candidate_pane,
+            "owner_epoch": owner_epoch(state).unwrap_or(0),
+        }));
+    }
+    let next_epoch = owner_epoch(state).unwrap_or(0).saturating_add(1);
+    let Some(root) = state.as_object_mut() else {
+        return Err(MessagingError::Routing("runtime state root is not an object".to_string()));
+    };
+    let owner = root
+        .entry("team_owner")
+        .or_insert_with(|| serde_json::json!({}));
+    if let Some(owner) = owner.as_object_mut() {
+        owner.insert("owner_epoch".to_string(), serde_json::json!(next_epoch));
+    }
+    let receiver = root
+        .entry("leader_receiver")
+        .or_insert_with(|| serde_json::json!({}));
+    if let Some(receiver) = receiver.as_object_mut() {
+        receiver.insert("mode".to_string(), serde_json::json!("direct_tmux"));
+        receiver.insert("owner_epoch".to_string(), serde_json::json!(next_epoch));
+        copy_candidate_field(receiver, candidate, "pane_id");
+        copy_candidate_field(receiver, candidate, "provider");
+        copy_candidate_field(receiver, candidate, "leader_session_uuid");
+    }
+    crate::state::persist::save_runtime_state(workspace, state)?;
+    event_log.write(
+        "leader_receiver.claimed",
+        serde_json::json!({"owner_epoch": next_epoch, "candidate": candidate}),
+    )?;
+    let receiver = state
+        .get("leader_receiver")
+        .cloned()
+        .unwrap_or_else(|| candidate.clone());
+    Ok(serde_json::json!({
+        "ok": true,
+        "status": "claimed",
+        "leader_receiver": receiver,
+        "owner_epoch": next_epoch,
+    }))
+}
+
+/// `_mirror_peer_message_to_leader` (`leader.py:31`):peer→peer 消息镜像到 leader receiver。
+pub fn mirror_peer_message_to_leader(
+    workspace: &Path,
+    state: &serde_json::Value,
+    sender: &str,
+    recipient: &str,
+    content: &str,
+    task_id: Option<&TaskId>,
+    event_log: &EventLog,
+) -> Result<(), MessagingError> {
+    let _ = send_to_leader_receiver(
+        workspace,
+        state,
+        "leader",
+        content,
+        task_id,
+        sender,
+        false,
+        None,
+        event_log,
+    )?;
+    let _ = recipient;
+    Ok(())
+}
+
+pub(crate) fn active_team_key(workspace: &Path, state: &Value) -> String {
+    state
+        .get("active_team_key")
+        .and_then(Value::as_str)
+        .filter(|team| !team.is_empty())
+        .map(ToString::to_string)
+        .or_else(|| workspace.file_name().map(|name| name.to_string_lossy().to_string()))
+        .unwrap_or_else(|| "current".to_string())
+}
+
+fn owner_epoch(state: &Value) -> Option<u64> {
+    receiver_or_owner_field(state, "team_owner", "owner_epoch")
+        .and_then(Value::as_u64)
+        .or_else(|| receiver_or_owner_field(state, "leader_receiver", "owner_epoch").and_then(Value::as_u64))
+}
+
+fn receiver_or_owner_field<'a>(state: &'a Value, record: &str, field: &str) -> Option<&'a Value> {
+    state
+        .get(record)
+        .and_then(|v| v.get(field))
+        .or_else(|| {
+            let active = state.get("active_team_key").and_then(Value::as_str)?;
+            state
+                .get("teams")
+                .and_then(Value::as_object)
+                .and_then(|teams| teams.get(active))
+                .and_then(|team| team.get(record))
+                .and_then(|v| v.get(field))
+        })
+}
+
+fn leader_record_field<'a>(state: &'a Value, field: &str) -> Option<&'a Value> {
+    receiver_or_owner_field(state, "leader_receiver", field)
+        .or_else(|| receiver_or_owner_field(state, "team_owner", field))
+}
+
+fn owner_epoch_i64(state: &Value) -> Option<i64> {
+    owner_epoch(state).and_then(|epoch| i64::try_from(epoch).ok())
+}
+
+fn leader_session_uuid(state: &Value) -> Option<&str> {
+    leader_record_field(state, "leader_session_uuid").and_then(Value::as_str)
+}
+
+pub(crate) fn leader_pane_bound_but_not_live(workspace: &Path, state: &Value) -> bool {
+    leader_pane_id(state)
+        .is_some_and(|pane_id| !leader_pane_is_live(workspace, pane_id))
+}
+
+fn leader_pane_is_live(workspace: &Path, pane_id: &str) -> bool {
+    let mut targets = crate::tmux_backend::TmuxBackend::for_workspace(workspace)
+        .list_targets()
+        .unwrap_or_default();
+    targets.extend(
+        crate::tmux_backend::TmuxBackend::new()
+            .list_targets()
+            .unwrap_or_default(),
+    );
+    targets.iter().any(|target| target.pane_id.as_str() == pane_id)
+}
+
+fn leader_pane_id(state: &Value) -> Option<&str> {
+    leader_record_field(state, "pane_id").and_then(Value::as_str)
+}
+
+fn copy_candidate_field(
+    out: &mut serde_json::Map<String, Value>,
+    candidate: &Value,
+    key: &str,
+) {
+    if let Some(value) = candidate.get(key) {
+        out.insert(key.to_string(), value.clone());
+    }
+}