@team-agent/installer 0.2.11 → 0.3.0

package/crates/team-agent/src/model/enums.rs

@@ -0,0 +1,311 @@
+//! §19 散字符串态 → 穷尽 enum。每个 variant 与 Python 字符串**一一对应**(`#[serde]`
+//! rename 到精确字符串),保证 spec/state/event 序列化字节不漂移(§7)。
+//!
+//! 值全部取自真相源 v0.2.11:`spec.py:13/116/156/172/174/176/229/255`、
+//! `profiles/constants.py:6`、`task_graph.py:5-16`、`permissions.py:5-14/44-50`、
+//! `display/backend.py:7-9`、`compiler.py:80`。
+
+use serde::{Deserialize, Serialize};
+
+/// provider(`SUPPORTED_PROVIDERS` `spec.py:13`)。**血泪 §3/陷阱 #4**:`claude` vs
+/// `claude_code` 不能漏归一(原 Python 漏 → take-over 全死)。Rust 穷尽 match 防漏。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Provider {
+    Claude,
+    ClaudeCode,
+    Codex,
+    GeminiCli,
+    Fake,
+}
+
+/// auth 模式(`AUTH_MODES` `profiles/constants.py:6`)。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum AuthMode {
+    Subscription,
+    OfficialApi,
+    CompatibleApi,
+}
+
+/// task 状态(`TASK_STATUSES` `task_graph.py:5-16`)。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum TaskStatus {
+    Pending,
+    Ready,
+    Running,
+    Blocked,
+    NeedsRetry,
+    Done,
+    Failed,
+    Cancelled,
+}
+
+impl TaskStatus {
+    /// `TERMINAL_TASK_STATUSES = {done, failed, cancelled}`(`task_graph.py:16`)。
+    pub fn is_terminal(self) -> bool {
+        matches!(self, Self::Done | Self::Failed | Self::Cancelled)
+    }
+}
+
+/// result-envelope 顶层 status(`spec.py:156`)。**与 `TaskStatus` 不同集合**(success≠done)。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ResultStatus {
+    Success,
+    Blocked,
+    Failed,
+    Partial,
+}
+
+/// envelope `changes[].kind`(`spec.py:172`)。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ChangeKind {
+    Created,
+    Modified,
+    Deleted,
+    Observed,
+}
+
+/// envelope `tests[].status`(`spec.py:174`)。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum TestStatus {
+    Passed,
+    Failed,
+    NotRun,
+    Skipped,
+}
+
+/// `risks[].severity` + task.risk(`spec.py:176`)。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum RiskSeverity {
+    Low,
+    Medium,
+    High,
+}
+
+/// team mode(`spec.py:116`)。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum TeamMode {
+    SupervisorWorker,
+    SwarmLimited,
+}
+
+/// comm protocol(`spec.py:229`)。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CommProtocol {
+    McpInbox,
+    FileBus,
+}
+
+/// terminal/session backend(`spec.py:255`)。§8:Windows 无原生 tmux → 能力门在 step 9,
+/// enum 在此定义(Windows 原生经 WezTerm 后端,见 transport-backend-design.md)。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Backend {
+    Tmux,
+    Pty,
+}
+
+/// display backend(`VALID_DISPLAY_BACKENDS` `display/backend.py:7-9`)。
+/// **`adaptive` 在代码集里但不在 JSON schema enum** —— 以代码为准(陷阱 #5)。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum DisplayBackend {
+    None,
+    TmuxAttach,
+    Iterm,
+    Ghostty,
+    GhosttyWindow,
+    GhosttyWorkspace,
+    Adaptive,
+}
+
+impl DisplayBackend {
+    /// `DISPLAY_BACKENDS_WITH_WORKER_VIEWS = GHOSTTY_* | {adaptive}`(`display/backend.py:8`)。
+    pub fn has_worker_views(self) -> bool {
+        matches!(
+            self,
+            Self::Ghostty | Self::GhosttyWindow | Self::GhosttyWorkspace | Self::Adaptive
+        )
+    }
+}
+
+/// agent permission mode(schema `agent.permission_mode`;compiler 恒发 `restricted`)。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PermissionMode {
+    Restricted,
+    Ask,
+    Trusted,
+}
+
+/// 规范化 tool(`CANONICAL_TOOLS` `permissions.py:5-14`)。别名(`fs_*`/`@builtin`/`*`)
+/// 在 `expand_tools` 展开 —— 那是单独的 alias 输入枚举,不在此(step 2 后续)。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Tool {
+    FsRead,
+    FsWrite,
+    FsList,
+    ExecuteBash,
+    GitDiff,
+    Network,
+    McpTeam,
+    ProviderBuiltin,
+}
+
+/// provider×tool enforcement(`PROVIDER_ENFORCEMENT` `permissions.py:44-65`)。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum Enforcement {
+    Hard,
+    PromptOnly,
+}
+
+/// tmux pane 存活态(`state.py:336-341`)。**`Unknown` 既不可当 dead 也不可当 live**
+/// (owner-gate `state.py:382` 用 `!= LIVE`)—— 穷尽 match,不 fallthrough(§11)。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PaneLiveness {
+    Live,
+    Dead,
+    Unknown,
+}
+
+/// context 策略 `receive_worker_outputs`。**已知三方 drift**(陷阱 #5):JSON schema 限
+/// `{summary_only,structured_only,full_on_request}`,但 compiler 发
+/// `business_messages_and_short_summaries`,且 `spec.py` 不校验该值。
+/// → 保留 passthrough(`Other`),序列化回原字节,**不拒未知值**(§7)。
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(from = "String", into = "String")]
+pub enum ReceiveWorkerOutputs {
+    SummaryOnly,
+    StructuredOnly,
+    FullOnRequest,
+    /// passthrough:未知值原样保留(含 compiler 的 drift 默认值)。
+    Other(String),
+}
+
+impl From<String> for ReceiveWorkerOutputs {
+    fn from(s: String) -> Self {
+        match s.as_str() {
+            "summary_only" => Self::SummaryOnly,
+            "structured_only" => Self::StructuredOnly,
+            "full_on_request" => Self::FullOnRequest,
+            _ => Self::Other(s),
+        }
+    }
+}
+
+impl From<ReceiveWorkerOutputs> for String {
+    fn from(v: ReceiveWorkerOutputs) -> Self {
+        match v {
+            ReceiveWorkerOutputs::SummaryOnly => "summary_only".to_string(),
+            ReceiveWorkerOutputs::StructuredOnly => "structured_only".to_string(),
+            ReceiveWorkerOutputs::FullOnRequest => "full_on_request".to_string(),
+            ReceiveWorkerOutputs::Other(s) => s,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used)]
+    use super::*;
+
+    /// 序列化字节 == Python 精确字符串(挑 rename 不平凡的 variant 逐一钉)。
+    #[test]
+    fn enums_serialize_to_exact_python_strings() {
+        let cases: &[(String, &str)] = &[
+            (serde_json::to_string(&Provider::ClaudeCode).unwrap(), "\"claude_code\""),
+            (serde_json::to_string(&Provider::GeminiCli).unwrap(), "\"gemini_cli\""),
+            (serde_json::to_string(&AuthMode::CompatibleApi).unwrap(), "\"compatible_api\""),
+            (serde_json::to_string(&TaskStatus::NeedsRetry).unwrap(), "\"needs_retry\""),
+            (serde_json::to_string(&TestStatus::NotRun).unwrap(), "\"not_run\""),
+            (serde_json::to_string(&TeamMode::SupervisorWorker).unwrap(), "\"supervisor_worker\""),
+            (serde_json::to_string(&CommProtocol::McpInbox).unwrap(), "\"mcp_inbox\""),
+            (serde_json::to_string(&DisplayBackend::TmuxAttach).unwrap(), "\"tmux_attach\""),
+            (serde_json::to_string(&DisplayBackend::GhosttyWorkspace).unwrap(), "\"ghostty_workspace\""),
+            (serde_json::to_string(&DisplayBackend::Adaptive).unwrap(), "\"adaptive\""),
+            (serde_json::to_string(&Tool::ExecuteBash).unwrap(), "\"execute_bash\""),
+            (serde_json::to_string(&Tool::ProviderBuiltin).unwrap(), "\"provider_builtin\""),
+            (serde_json::to_string(&Enforcement::PromptOnly).unwrap(), "\"prompt_only\""),
+            (serde_json::to_string(&PaneLiveness::Unknown).unwrap(), "\"unknown\""),
+            (serde_json::to_string(&Backend::Pty).unwrap(), "\"pty\""),
+        ];
+        for (got, want) in cases {
+            assert_eq!(got, want);
+        }
+    }
+
+    #[test]
+    fn provider_all_five_round_trip() {
+        for s in ["claude", "claude_code", "codex", "gemini_cli", "fake"] {
+            let json = format!("\"{s}\"");
+            let p: Provider = serde_json::from_str(&json).unwrap();
+            assert_eq!(serde_json::to_string(&p).unwrap(), json);
+        }
+    }
+
+    #[test]
+    fn unknown_provider_string_is_rejected() {
+        // 与 receive_worker_outputs 不同:Provider 是封闭集,未知值必须 Err(不 passthrough)。
+        assert!(serde_json::from_str::<Provider>("\"copilot\"").is_err());
+    }
+
+    #[test]
+    fn task_status_terminal_set() {
+        for s in [TaskStatus::Done, TaskStatus::Failed, TaskStatus::Cancelled] {
+            assert!(s.is_terminal());
+        }
+        for s in [
+            TaskStatus::Pending,
+            TaskStatus::Ready,
+            TaskStatus::Running,
+            TaskStatus::Blocked,
+            TaskStatus::NeedsRetry,
+        ] {
+            assert!(!s.is_terminal());
+        }
+    }
+
+    #[test]
+    fn display_backend_worker_views() {
+        for b in [
+            DisplayBackend::Ghostty,
+            DisplayBackend::GhosttyWindow,
+            DisplayBackend::GhosttyWorkspace,
+            DisplayBackend::Adaptive,
+        ] {
+            assert!(b.has_worker_views());
+        }
+        for b in [DisplayBackend::None, DisplayBackend::TmuxAttach, DisplayBackend::Iterm] {
+            assert!(!b.has_worker_views());
+        }
+    }
+
+    #[test]
+    fn receive_worker_outputs_passthrough_preserves_drift_value() {
+        // compiler 发的 drift 值必须原样保留(byte 不丢),不被拒。
+        let drift = "\"business_messages_and_short_summaries\"";
+        let v: ReceiveWorkerOutputs = serde_json::from_str(drift).unwrap();
+        assert_eq!(v, ReceiveWorkerOutputs::Other("business_messages_and_short_summaries".to_string()));
+        assert_eq!(serde_json::to_string(&v).unwrap(), drift);
+        // 已知值仍映射到 variant。
+        assert_eq!(
+            serde_json::from_str::<ReceiveWorkerOutputs>("\"structured_only\"").unwrap(),
+            ReceiveWorkerOutputs::StructuredOnly
+        );
+        assert_eq!(
+            serde_json::to_string(&ReceiveWorkerOutputs::SummaryOnly).unwrap(),
+            "\"summary_only\""
+        );
+    }
+}

package/crates/team-agent/src/model/errors.rs

@@ -0,0 +1,17 @@
+//! 用户面错误。
+//!
+//! 陷阱 #6(02-model 卡):Python `errors.py` 用自定义 `RuntimeError` **遮蔽**内建
+//! `RuntimeError`。Rust 无此坑,但**必须保留两类区分**:`Validation`(spec/envelope/输入)
+//! vs `Runtime`(运行期/team 解析),别合并成一个。§12:lib 层用 `thiserror`。
+
+use thiserror::Error;
+
+#[derive(Debug, Error, Clone, PartialEq, Eq)]
+pub enum ModelError {
+    /// spec / result-envelope / 输入校验失败 —— 对应 Python `ValidationError`。
+    #[error("validation error: {0}")]
+    Validation(String),
+    /// 运行期 / team 解析 / 身份派生失败 —— 对应 Python(自定义)`RuntimeError`。
+    #[error("runtime error: {0}")]
+    Runtime(String),
+}

package/crates/team-agent/src/model/ids.rs

@@ -0,0 +1,155 @@
+//! §3 id newtypes —— Python 把 agent/task/team id 全用裸 `str` 混传(route/owner-gate/
+//! tasks 串台)。newtype 让"混传"编不过。serde `transparent` 保证序列化字节 == 裸字符串。
+
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+
+use crate::model::errors::ModelError;
+
+/// 透明 String newtype:序列化/反序列化与裸字符串字节一致。
+macro_rules! string_newtype {
+    ($(#[$doc:meta])* $name:ident) => {
+        $(#[$doc])*
+        #[derive(Debug, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
+        #[serde(transparent)]
+        pub struct $name(pub String);
+
+        impl $name {
+            pub fn new(s: impl Into<String>) -> Self {
+                Self(s.into())
+            }
+            pub fn as_str(&self) -> &str {
+                &self.0
+            }
+        }
+        impl std::fmt::Display for $name {
+            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+                f.write_str(&self.0)
+            }
+        }
+        impl From<&str> for $name {
+            fn from(s: &str) -> Self {
+                Self(s.to_string())
+            }
+        }
+    };
+}
+
+string_newtype!(
+    /// agent id。leader 默认 `"leader"` 但 spec 可改 —— 不硬编码。
+    AgentId
+);
+string_newtype!(
+    /// task id。deps/assignee/cycle 按 str 比对,易与 AgentId 串台 → newtype 防混。
+    TaskId
+);
+string_newtype!(
+    /// multi-team 指针 key(`team_state_key()`)。
+    TeamKey
+);
+
+/// owner epoch(§3)。first-time bind 写 0(`state.py:454,461`)。
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct OwnerEpoch(pub u64);
+
+impl OwnerEpoch {
+    /// first-time leader bind 的 epoch。
+    pub const FIRST: OwnerEpoch = OwnerEpoch(0);
+}
+
+/// leader 身份/owner epoch 一等公民。公式锁死(`state.py:34-38`),跨 Python/Rust
+/// 影子交叉验证靠它,**一字节不能改**(§7)。
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct LeaderSessionUuid(String);
+
+impl LeaderSessionUuid {
+    const SEP: char = '\0';
+
+    /// `sha256(NUL.join([fp, ws, user, team]).encode("utf-8")).hexdigest()[:32]`。
+    /// 任一输入含 NUL → `Err`(Python `state.py:36-37` raise ValueError)。
+    pub fn derive(
+        machine_fingerprint: &str,
+        workspace_abspath: &str,
+        os_user: &str,
+        team_id: &str,
+    ) -> Result<Self, ModelError> {
+        let parts = [machine_fingerprint, workspace_abspath, os_user, team_id];
+        if parts.iter().any(|p| p.contains(Self::SEP)) {
+            return Err(ModelError::Validation(
+                "leader_session_uuid inputs must not contain NUL".to_string(),
+            ));
+        }
+        let joined = parts.join("\0");
+        let digest = Sha256::digest(joined.as_bytes());
+        let hex: String = digest.iter().map(|b| format!("{b:02x}")).collect();
+        // hexdigest()[:32] —— sha256 恒 64 hex,take(32) 无 panic 风险。
+        Ok(LeaderSessionUuid(hex.chars().take(32).collect()))
+    }
+
+    pub fn as_str(&self) -> &str {
+        &self.0
+    }
+}
+
+impl std::fmt::Display for LeaderSessionUuid {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used)]
+    use super::*;
+
+    // golden 值由 Python 真相源 `derive_leader_session_uuid` 算出(team-agent-public@439bef8)。
+    // 这是 §4.2「行为 diff 双跑」对该函数的字节锁。
+    #[test]
+    fn leader_session_uuid_matches_python_golden() {
+        assert_eq!(
+            LeaderSessionUuid::derive("fp-abc", "/ws/proj", "alice", "team-1")
+                .unwrap()
+                .as_str(),
+            "5742d595dbb2f5a16608f68c3050127b"
+        );
+        assert_eq!(
+            LeaderSessionUuid::derive("", "", "", "").unwrap().as_str(),
+            "709e80c88487a2411e1ee4dfb9f22a86"
+        );
+        assert_eq!(
+            LeaderSessionUuid::derive("m", "/Users/alauda/x", "root", "default")
+                .unwrap()
+                .as_str(),
+            "92c5e32dc5710ea095f956bfb594bc6b"
+        );
+    }
+
+    #[test]
+    fn leader_session_uuid_rejects_nul_in_any_part() {
+        assert!(LeaderSessionUuid::derive("a\0b", "w", "u", "t").is_err());
+        assert!(LeaderSessionUuid::derive("w", "x", "u\0", "t").is_err());
+    }
+
+    #[test]
+    fn leader_session_uuid_is_32_lowercase_hex() {
+        let u = LeaderSessionUuid::derive("x", "y", "z", "w").unwrap();
+        assert_eq!(u.as_str().len(), 32);
+        assert!(u.as_str().chars().all(|c| c.is_ascii_hexdigit()));
+    }
+
+    #[test]
+    fn id_newtypes_serialize_as_bare_string() {
+        assert_eq!(serde_json::to_string(&AgentId::new("leader")).unwrap(), "\"leader\"");
+        assert_eq!(serde_json::from_str::<TaskId>("\"t1\"").unwrap(), TaskId::new("t1"));
+        assert_eq!(TeamKey::from("default").as_str(), "default");
+    }
+
+    #[test]
+    fn owner_epoch_first_is_zero_and_serializes_as_int() {
+        assert_eq!(OwnerEpoch::FIRST.0, 0);
+        assert_eq!(serde_json::to_string(&OwnerEpoch(3)).unwrap(), "3");
+        assert_eq!(serde_json::from_str::<OwnerEpoch>("0").unwrap(), OwnerEpoch::FIRST);
+    }
+}

package/crates/team-agent/src/model/mod.rs

@@ -0,0 +1,22 @@
+//! step 2 · model — typed bedrock (REWRITE_PROMPT.md §6 step 2).
+//!
+//! 纯数据 + 纯函数核心:Python 的散字符串 / `dict[str,Any]` 在此变 §3 id-newtype +
+//! §19 穷尽 enum。真相源 `team-agent-public` @ v0.2.11 (439bef8);序列化与 Python
+//! **字节级一致**(§7),靠 golden 值 / fixture 双跑锁死。
+//!
+//! §10 + 02-model 卡 §152:纯层没有 panic 的理由 —— 整个 `model` deny
+//! unwrap/expect/panic;所有校验/解析返 `Result`,所有 `Option` 穷尽 match。
+//! (clippy tool-lint;`cargo build`/`test` 下被忽略,`cargo clippy` 下强制。)
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+pub mod enums;
+pub mod errors;
+pub mod ids;
+pub mod paths;
+pub mod permissions;
+pub mod routing;
+pub mod spec;
+pub mod task_graph;
+pub mod yaml;
+
+pub use errors::ModelError;