@team-agent/installer 0.5.71 → 0.5.73

package/Cargo.lock

@@ -581,7 +581,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.5.71"
+version = "0.5.73"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -9,7 +9,7 @@ members = ["crates/team-agent", "crates/win-conpty-phase0", "crates/conpty-trans
 
 [workspace.package]
 edition = "2021"
-version = "0.5.71"
+version = "0.5.73"
 license = "AGPL-3.0"
 rust-version = "1.95"
 

package/crates/team-agent/src/cli/adapters.rs

@@ -102,7 +102,7 @@ pub fn cmd_init(args: &InitArgs) -> Result<CmdResult, CliError> {
 
 /// `cmd_quick_start`(`commands.py:18`)。`--json` 或 `!ok` → 整 dict;否则 `result["summary"]`。
 pub fn cmd_quick_start(args: &QuickStartArgs) -> Result<CmdResult, CliError> {
-    let value = lifecycle_port::quick_start(
+    let mut value = lifecycle_port::quick_start(
         &args.workspace,
         &args.agents_dir,
         args.name.as_deref(),
@@ -111,6 +111,7 @@ pub fn cmd_quick_start(args: &QuickStartArgs) -> Result<CmdResult, CliError> {
         !args.no_display,
         args.backend.as_deref(),
     )?;
+    append_send_guidance(&mut value, &args.workspace, args.team_id.as_deref());
     let readiness = value.get("readiness").and_then(Value::as_object);
     let all_resumable_have_session = readiness
         .and_then(|readiness| readiness.get("all_resumable_have_session"))
@@ -156,18 +157,74 @@ fn quickstart_human(value: &Value) -> String {
         .and_then(Value::as_array)
         .map(|items| items.iter().filter_map(Value::as_str).collect())
         .unwrap_or_default();
-    if attach.is_empty() {
-        return append_reminder(summary.to_string(), crate::cli::QUICK_START_REMINDER);
-    }
+    let sends: Vec<&str> = value
+        .get("send_commands")
+        .and_then(Value::as_array)
+        .map(|items| items.iter().filter_map(Value::as_str).collect())
+        .unwrap_or_default();
     let mut out = String::from(summary);
-    out.push_str("\n\nattach:");
-    for cmd in attach {
-        out.push_str("\n  ");
-        out.push_str(cmd);
+    if !attach.is_empty() {
+        out.push_str("\n\nattach:");
+        for cmd in attach {
+            out.push_str("\n  ");
+            out.push_str(cmd);
+        }
+    }
+    if !sends.is_empty() {
+        out.push_str("\n\nsend:");
+        for cmd in sends {
+            out.push_str("\n  ");
+            out.push_str(cmd);
+        }
     }
     append_reminder(out, crate::cli::QUICK_START_REMINDER)
 }
 
+fn append_send_guidance(value: &mut Value, workspace: &Path, team: Option<&str>) {
+    if value.get("ok").and_then(Value::as_bool) != Some(true) {
+        return;
+    }
+    let agents = value
+        .get("agent_ids")
+        .and_then(Value::as_array)
+        .cloned()
+        .unwrap_or_default();
+    let commands: Vec<Value> = agents
+        .iter()
+        .filter_map(Value::as_str)
+        .filter_map(|agent| send_command(agent, workspace, team).map(Value::String))
+        .collect();
+    if !commands.is_empty() {
+        if let Some(object) = value.as_object_mut() {
+            object.insert("send_commands".to_string(), Value::Array(commands));
+        }
+    }
+}
+
+pub(crate) fn send_command(agent: &str, workspace: &Path, team: Option<&str>) -> Option<String> {
+    let workspace = workspace.to_str()?;
+    let mut command = format!(
+        "team-agent send {} \\\"MESSAGE\\\" --workspace {}",
+        shell_quote(agent),
+        shell_quote(workspace)
+    );
+    if let Some(team) = team {
+        command.push_str(" --team ");
+        command.push_str(&shell_quote(team));
+    }
+    Some(command)
+}
+
+fn shell_quote(value: &str) -> String {
+    if value.bytes().all(|byte| {
+        byte.is_ascii_alphanumeric() || matches!(byte, b'/' | b'.' | b'_' | b'-' | b':')
+    }) {
+        value.to_string()
+    } else {
+        format!("'{}'", value.replace('\'', "'\\''"))
+    }
+}
+
 fn append_reminder(text: String, reminder: &str) -> String {
     if text.is_empty() {
         reminder.to_string()
@@ -1550,8 +1607,9 @@ pub fn cmd_doctor(args: &DoctorArgs) -> Result<CmdResult, CliError> {
 mod tests {
     #![allow(clippy::unwrap_used)]
 
-    use super::{agent_pane_id, quickstart_human};
+    use super::{agent_pane_id, append_send_guidance, quickstart_human, send_command};
     use serde_json::json;
+    use std::path::{Path, PathBuf};
 
     // E13:happy 人类输出必须带 attach 块(此前 else 分支只打 summary 丢 attach_commands)。
     #[test]
@@ -1594,6 +1652,46 @@ mod tests {
         );
     }
 
+    #[test]
+    fn send_guidance_is_copyable_and_preserves_explicit_scope() {
+        let command = send_command("worker name; echo unsafe", Path::new("/tmp/my workspace"), Some("team-a"))
+            .unwrap();
+        assert_eq!(
+            command,
+            "team-agent send 'worker name; echo unsafe' \\\"MESSAGE\\\" --workspace '/tmp/my workspace' --team team-a"
+        );
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn non_utf8_workspace_fails_closed_without_send_guidance() {
+        use std::ffi::OsString;
+        use std::os::unix::ffi::OsStringExt;
+
+        let workspace = PathBuf::from(OsString::from_vec(b"/tmp/workspace-\xff".to_vec()));
+        assert!(send_command("worker", &workspace, None).is_none());
+        let mut value = json!({"ok": true, "agent_ids": ["worker"]});
+        append_send_guidance(&mut value, &workspace, None);
+        assert!(value.get("send_commands").is_none());
+    }
+
+    #[test]
+    fn quick_start_guidance_lists_every_known_agent_without_guessing() {
+        let mut value = json!({"ok": true, "agent_ids": ["sol", "luna"]});
+        append_send_guidance(&mut value, Path::new("/tmp/ws"), Some("team"));
+        let commands = value.get("send_commands").and_then(|v| v.as_array()).unwrap();
+        assert_eq!(commands.len(), 2);
+        assert!(commands[0].as_str().unwrap().contains("send sol"));
+        assert!(commands[1].as_str().unwrap().contains("send luna"));
+    }
+
+    #[test]
+    fn error_results_do_not_get_send_guidance() {
+        let mut value = json!({"ok": false, "agent_ids": ["worker"]});
+        append_send_guidance(&mut value, Path::new("/tmp/ws"), None);
+        assert!(value.get("send_commands").is_none());
+    }
+
     #[test]
     fn agent_pane_id_resolves_session_window_even_with_recorded_pane_id() {
         let state = json!({

package/crates/team-agent/src/cli/emit.rs

@@ -126,6 +126,15 @@ fn write_stdout_line(text: &str) -> std::io::Result<()> {
     stdout.write_all(b"\n")
 }
 
+#[cfg(test)]
+pub(crate) fn __test_dispatch(
+    command: &str,
+    args: &[String],
+    cwd: &Path,
+) -> Result<ExitCode, CliError> {
+    dispatch(command, args, cwd)
+}
+
 fn dispatch(command: &str, args: &[String], cwd: &Path) -> Result<ExitCode, CliError> {
     let Some(spec) = command_spec(command) else {
         return Ok(emit_unknown_subcommand_usage(command));
@@ -188,6 +197,7 @@ fn dispatch(command: &str, args: &[String], cwd: &Path) -> Result<ExitCode, CliE
         // (workspace, team_key) tuple and delegates to the E6 named-leader
         // delivery path — no separate route authority.
         "leaders" => cmd_leaders(&leaders_args(args, cwd)).map(emit_result),
+        "models" => cmd_models(&models_args(args)?).map(emit_result),
         "validate" => cmd_validate(&validate_args(args, cwd)).map(emit_result),
         "install-skill" => cmd_install_skill(&install_skill_args(args)?).map(emit_result),
         "profile" => cmd_profile(&profile_args(args, cwd)?).map(emit_result),
@@ -239,6 +249,7 @@ const DISPATCH_COMMANDS: &[&str] = &[
     "sessions",
     // 0.5.9 E7: host leader discovery command surface.
     "leaders",
+    "models",
     "validate",
     "install-skill",
     "profile",
@@ -291,7 +302,7 @@ pub(crate) fn default_help() -> String {
     append_help_section(
         &mut out,
         "Core",
-        &["quick-start", "send", "status", "collect", "results"],
+        &["quick-start", "send", "status", "collect", "results", "models"],
     );
     append_help_section(
         &mut out,
@@ -311,7 +322,8 @@ pub(crate) fn default_help() -> String {
         "Guided recovery",
         &["claim-leader", "takeover", "attach-leader"],
     );
-    out.push_str("\nProvider launchers:\n  team-agent codex|claude|copilot|grok|cursor|pi ...\n");
+    out.push_str("\nWorkflow: `team-agent models --provider pi`, then quick-start/add-agent/start-agent, then `team-agent send AGENT MESSAGE`.\n");
+    out.push_str("Provider launchers:\n  team-agent codex|claude|copilot|grok|cursor|pi ...\n");
     out.push_str("\nRun `team-agent <command> --help` for command flags.");
     out
 }
@@ -362,7 +374,7 @@ fn command_help(command: Option<&str>) -> String {
     match command {
         None => default_help(),
         Some("init") => compat_hidden_help("init", "usage: team-agent init [--workspace WORKSPACE] [--force] [--json]"),
-        Some("quick-start") => "usage: team-agent quick-start [TEAMDIR] [--workspace WORKSPACE] [--name NAME] [--team-id TEAM|--team TEAM] [--yes] [--no-display] [--backend tmux|conpty] [--json]\n\ndefaults: display_backend=adaptive; set display_backend: none in TEAM.md or pass --no-display to use one worker window per agent.\n\n--backend selects the worker transport (Phase 1d Batch 2): tmux (default on POSIX; unchanged behavior), conpty (Windows-native ConPTY worker transport; requires the shim binary and Windows host).".to_string(),
+        Some("quick-start") => "usage: team-agent quick-start [TEAMDIR] [--workspace WORKSPACE] [--name NAME] [--team-id TEAM|--team TEAM] [--yes] [--no-display] [--backend tmux|conpty] [--json]\n\ndefaults: display_backend=adaptive; set display_backend: none in TEAM.md or pass --no-display to use one worker window per agent.\n\n--backend selects the worker transport (Phase 1d Batch 2): tmux (default on POSIX; unchanged behavior), conpty (Windows-native ConPTY worker transport; requires the shim binary and Windows host).\n\nAfter a successful start, use the returned `send_commands` (or choose an agent explicitly) with `team-agent send AGENT MESSAGE`.".to_string(),
         Some("start") => compat_hidden_help("start", "usage: team-agent start [TEAMDIR] [--yes] [--fresh] [--json]"),
         Some("compile") => "usage: team-agent compile --team TEAM [--out FILE] [--json]".to_string(),
         Some("send") => concat!(
@@ -376,14 +388,15 @@ fn command_help(command: Option<&str>) -> String {
         .to_string(),
         Some("allow-peer-talk") => "usage: team-agent allow-peer-talk A B [--workspace WORKSPACE] [--json]".to_string(),
         Some("status") => "usage: team-agent status [AGENT] [--workspace WORKSPACE] [--team TEAM] [--summary|--json] [--detail]\n\n默认输出: worker,空闲|工作|错误；错误细分走 status --summary".to_string(),
+        Some("models") => "usage: team-agent models --provider pi [--search TEXT] [--json]\n\nPrints models.v1 exact role_model entries; each entry includes current=true|false. Catalog readiness is reported as auth=ok|not_ready with auth_basis=catalog_visibility.".to_string(),
         Some("stop") => compat_hidden_help("stop", "usage: team-agent stop [--workspace WORKSPACE] [--team TEAM] [--keep-logs] [--json]"),
         Some("shutdown") => "usage: team-agent shutdown [--workspace WORKSPACE] [--team TEAM] [--keep-logs] [--json]".to_string(),
         Some("restart") => "usage: team-agent restart [WORKSPACE] [--team TEAM] [--allow-fresh] [--session-converge-deadline SECONDS] [--json]".to_string(),
         Some("restart-agent") => compat_hidden_help("restart-agent", "usage: team-agent restart-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--discard-session] [--no-display] [--json]"),
         Some("reset-agent") => "usage: team-agent reset-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--discard-session] [--no-display] [--json]".to_string(),
-        Some("start-agent") => "usage: team-agent start-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--force] [--allow-fresh] [--no-display] [--json]".to_string(),
+        Some("start-agent") => "usage: team-agent start-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--force] [--allow-fresh] [--no-display] [--json]\n\nAfter a successful start, use the returned `send_commands` with `team-agent send AGENT MESSAGE`.".to_string(),
         Some("stop-agent") => "usage: team-agent stop-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
-        Some("add-agent") => "usage: team-agent add-agent AGENT --role-file FILE [--force] [--workspace WORKSPACE] [--team TEAM] [--no-display] [--json]".to_string(),
+        Some("add-agent") => "usage: team-agent add-agent AGENT --role-file FILE [--force] [--workspace WORKSPACE] [--team TEAM] [--no-display] [--json]\n\nAfter a successful add, use the returned `send_commands` with `team-agent send AGENT MESSAGE`.".to_string(),
         Some("clone-agent") => "usage: team-agent clone-agent SOURCE_AGENT --as AGENT [--label LABEL] [--workspace WORKSPACE] [--team TEAM] [--no-display] [--json]".to_string(),
         Some("fork-agent") => "usage: team-agent fork-agent SOURCE_AGENT --as AGENT [--label LABEL] [--workspace WORKSPACE] [--team TEAM] [--no-display] [--json]".to_string(),
         Some("remove-agent") => "usage: team-agent remove-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--from-spec] [--confirm] [--force] [--json]".to_string(),
@@ -1054,6 +1067,23 @@ fn quick_start_args(args: &[String], cwd: &Path) -> Result<QuickStartArgs, CliEr
     })
 }
 
+fn models_args(args: &[String]) -> Result<ModelsArgs, CliError> {
+    let parsed = parse_args(args);
+    let provider = parsed
+        .provider
+        .ok_or_else(|| CliError::Usage("models requires --provider pi".to_string()))?;
+    if provider != "pi" {
+        return Err(CliError::Usage(format!(
+            "models supports only --provider pi, got {provider:?}"
+        )));
+    }
+    Ok(ModelsArgs {
+        provider,
+        search: parsed.search,
+        json: parsed.json,
+    })
+}
+
 fn init_args(args: &[String], cwd: &Path) -> InitArgs {
     let parsed = parse_args(args);
     InitArgs {

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

@@ -60,6 +60,7 @@ pub mod emit;
 pub mod helpers;
 pub mod leader;
 pub mod leaders;
+pub mod models;
 pub mod named_address;
 pub mod profile;
 pub mod send;
@@ -73,6 +74,7 @@ pub use diagnose::*;
 pub use emit::*;
 pub use leader::*;
 pub use leaders::*;
+pub use models::*;
 pub use named_address::*;
 pub use profile::*;
 pub use send::*;
@@ -2641,9 +2643,48 @@ pub mod lifecycle_port {
             allow_fresh,
             team,
         ) {
-            Ok(report) => {
-                Ok(json!({"ok": true, "agent_id": agent, "report": format!("{report:?}")}))
+            Ok(crate::lifecycle::StartAgentOutcome::Running {
+                env,
+                start_mode,
+                target,
+                session_id,
+                new_session_id,
+                rollout_path,
+            }) => Ok(agent_action_value(
+                agent,
+                workspace,
+                team,
+                json!({
+                    "ok": true,
+                    "agent_id": env.agent_id.as_str(),
+                    "status": "running",
+                    "start_mode": start_mode,
+                    "target": target,
+                    "session_id": session_id.as_ref().map(|id| id.as_str()),
+                    "new_session_id": new_session_id.as_ref().map(|id| id.as_str()),
+                    "rollout_path": rollout_path
+                        .as_ref()
+                        .map(|path| path.as_path().to_string_lossy().to_string()),
+                    "coordinator_started": env.coordinator_started,
+                    "state_file": env.state_file.to_string_lossy(),
+                }),
+            )),
+            Ok(crate::lifecycle::StartAgentOutcome::Noop { env, target }) => {
+                Ok(agent_action_value(agent, workspace, team, json!({
+                    "ok": true,
+                    "agent_id": env.agent_id.as_str(),
+                    "status": "already_running",
+                    "target": target,
+                    "coordinator_started": env.coordinator_started,
+                    "state_file": env.state_file.to_string_lossy(),
+                })))
             }
+            Ok(crate::lifecycle::StartAgentOutcome::Paused { agent_id }) => Ok(json!({
+                "ok": false,
+                "agent_id": agent_id.as_str(),
+                "status": "paused",
+                "reason": "agent_paused",
+            })),
             Err(e) => Ok(error_value(e)),
         }
     }
@@ -2730,14 +2771,34 @@ pub mod lifecycle_port {
             team,
             force,
         ) {
-            Ok(report) => Ok(json!({
-                "ok": true,
-                "agent_id": agent,
-                "role_file": report.role_file.to_string_lossy(),
-            })),
+            Ok(report) => Ok(agent_action_value(
+                agent,
+                workspace,
+                team,
+                json!({
+                    "ok": true,
+                    "agent_id": report.env.agent_id.as_str(),
+                    "status": "running",
+                    "start_mode": report.start_mode,
+                    "role_file": report.role_file.to_string_lossy(),
+                    "coordinator_started": report.env.coordinator_started,
+                    "state_file": report.env.state_file.to_string_lossy(),
+                }),
+            )),
             Err(e) => Ok(error_value(e)),
         }
     }
+    fn agent_action_value(agent: &str, workspace: &Path, team: Option<&str>, mut value: Value) -> Value {
+        if value.get("ok").and_then(Value::as_bool) == Some(true) {
+            if let Some(object) = value.as_object_mut() {
+                if let Some(command) = super::adapters::send_command(agent, workspace, team) {
+                    object.insert("send_commands".to_string(), json!([command]));
+                }
+            }
+        }
+        value
+    }
+
     ///
     /// `runtime.fork_agent`(`cmd_fork_agent`;`--as` 必需)。
     pub fn fork_agent(
@@ -3014,6 +3075,15 @@ pub mod lifecycle_port {
     }
 
     fn error_value(error: crate::lifecycle::LifecycleError) -> Value {
+        if let crate::lifecycle::LifecycleError::PiModelPreflight {
+            requested,
+            candidates,
+            action,
+            not_ready,
+        } = error
+        {
+            return json!({"ok": false, "error": "pi model preflight failed", "pi": {"requested_model": requested, "candidates": candidates, "not_ready": not_ready, "action": action.clone(), "next_action": action}});
+        }
         let message = error.to_string();
         let mut payload = json!({"ok": false, "error": message});
         if let Some(next_action) = error_next_action(&message) {
@@ -3295,6 +3365,7 @@ pub mod lifecycle_port {
                     "reason": readiness_json.get("reason").cloned().unwrap_or(Value::Null),
                     "ready": readiness_json.get("ready").cloned().unwrap_or(Value::Bool(false)),
                     "session_name": session_name.as_str(),
+                    "agent_ids": launch.started.iter().map(|agent| agent.agent_id.as_str()).collect::<Vec<_>>(),
                     "dry_run": launch.dry_run,
                     "display_backend": display_backend,
                     "next_actions": next_actions,