@team-agent/installer 0.5.49 → 0.5.51

package/crates/team-agent/src/cli/send/presentation.rs

@@ -0,0 +1,333 @@
+use crate::cli::{CliError, CmdOutput, CmdResult, ExitCode};
+use crate::messaging::{
+    DeliveryOutcome, DeliveryRefusal, DeliveryStage, DeliveryStatus, MessageTarget, SendOptions,
+};
+use serde_json::{json, Value};
+
+pub(super) fn watch_notice_json(target: &MessageTarget, opts: &SendOptions) -> Value {
+    let agent_id = match target {
+        MessageTarget::Single(agent) => agent.clone(),
+        MessageTarget::Broadcast => "*".to_string(),
+        MessageTarget::Fanout(recipients) => recipients
+            .first()
+            .cloned()
+            .unwrap_or_else(|| "-".to_string()),
+    };
+    json!({
+        "status": "registered",
+        "watcher_id": format!("watch-{agent_id}"),
+        "task_id": opts.task_id.as_ref().map(|t| t.as_str().to_string()),
+        "agent_id": agent_id,
+        "notice": "Team Agent will collect the result and notify the leader when this task reports completion."
+    })
+}
+
+/// 0.5.45 naming-addressing (design §3.5, RED-2/RED-3 positional):
+/// after `messaging::send_message` refuses with `target_not_in_team`
+/// for a Single non-special short id, attach scope-safe advisory
+/// suggestions to the outbound JSON envelope. Candidate source =
+/// selected team's projected `agents` map (never the raw workspace
+/// `teams`) so sibling teams cannot leak. Zero DB write, zero inject
+/// — the refusal exit code is unchanged.
+pub(super) fn attach_positional_typo_suggestions(
+    value: &mut Value,
+    target: &MessageTarget,
+    selected_state: &Value,
+) {
+    use crate::model::name_similarity::{rank, Candidate};
+    let requested = match target {
+        MessageTarget::Single(id) if id != "*" && id != "leader" => id.clone(),
+        _ => return,
+    };
+    let Some(obj) = value.as_object_mut() else {
+        return;
+    };
+    if obj.get("reason").and_then(Value::as_str) != Some("target_not_in_team") {
+        return;
+    }
+    let team_key = selected_state
+        .get("active_team_key")
+        .or_else(|| selected_state.get("team_key"))
+        .and_then(Value::as_str)
+        .unwrap_or("");
+    let candidates: Vec<Candidate<String>> = selected_state
+        .get("agents")
+        .and_then(Value::as_object)
+        .map(|agents| {
+            agents
+                .keys()
+                .map(|agent_id| Candidate {
+                    match_key: agent_id.clone(),
+                    stable_key: agent_id.clone(),
+                    payload: agent_id.clone(),
+                })
+                .collect()
+        })
+        .unwrap_or_default();
+    let ranked = rank(&requested, &candidates);
+    let candidate_values: Vec<Value> = ranked
+        .iter()
+        .map(|agent_id| {
+            json!({
+                "name": agent_id,
+                "team_key": team_key,
+                "agent_id": agent_id,
+                "advisory": true,
+            })
+        })
+        .collect();
+    obj.insert("requested_name".to_string(), json!(requested));
+    if let Some(best) = ranked.first() {
+        obj.insert("suggested_name".to_string(), json!(best));
+    }
+    obj.insert("candidates".to_string(), Value::Array(candidate_values));
+}
+
+pub(super) fn delivery_outcome_json(
+    outcome: &DeliveryOutcome,
+    target: &MessageTarget,
+    content: &str,
+    opts: &SendOptions,
+) -> Value {
+    // Pre-release 0.4.0 user directive: send result MUST NOT carry the
+    // message body — neither in human form (cli/emit.rs) NOR in --json.
+    // External consumers who need the message content read it via `inbox`,
+    // not from the send response. We surface `content_length_bytes` as a
+    // size sanity field so callers can verify the body size they intended
+    // to send arrived intact without exposing the body itself.
+    let target_wire = target_json(target);
+    json!({
+        "ok": outcome.ok,
+        "status": delivery_status_wire(outcome.status),
+        "delivery_status": api_delivery_status(outcome),
+        "delivered": delivery_proven(outcome.status),
+        "target": target_wire,
+        "agent_id": first_target(target),
+        "content_length_bytes": content.len(),
+        "sender": opts.sender,
+        "message_id": outcome.message_id,
+        "message_status": outcome.message_status.0,
+        "verification": outcome.verification,
+        "stage": outcome.stage.map(delivery_stage_wire),
+        "reason": outcome.reason.map(delivery_refusal_wire),
+        "channel": outcome.channel,
+    })
+}
+
+pub(super) fn api_delivery_status(outcome: &DeliveryOutcome) -> &'static str {
+    if delivery_proven(outcome.status) {
+        return "delivered";
+    }
+    if matches!(outcome.status, DeliveryStatus::Queued) && outcome.message_status.0 == "accepted" {
+        return "pending";
+    }
+    delivery_status_wire(outcome.status)
+}
+
+pub(super) fn delivery_proven(status: DeliveryStatus) -> bool {
+    matches!(
+        status,
+        DeliveryStatus::Delivered
+            | DeliveryStatus::AlreadyDelivered
+            | DeliveryStatus::BroadcastDelivered
+            | DeliveryStatus::FanoutDelivered
+    )
+}
+
+pub(super) fn add_send_reminder_if_ok(value: &mut Value) {
+    if value.get("ok").and_then(Value::as_bool) != Some(true) {
+        return;
+    }
+    let reminder = send_reminder_for_value(value);
+    if let Some(obj) = value.as_object_mut() {
+        obj.insert("reminder".to_string(), json!(reminder));
+    }
+}
+
+/// E6 (0.5.9 offline-mailbox-toname-design §§3.1/6.2/8, real-machine
+/// escape evidence
+/// `.team/artifacts/0.5.9-subscription-gate.md` +
+/// `.team/evidence/0.5.9-subscription-gate-20260707T143241Z-4645/`):
+/// when the `--to-name <ws>::<team>/leader` resolver refused with
+/// `leader_not_attached`, decide whether the target team is still alive
+/// (worker + coordinator running without a bound leader) and, if so,
+/// enqueue the mailbox row so `attach-leader` replays it exactly once.
+///
+/// Only queues for third-party senders (sender workspace ≠ target
+/// workspace). Owner-scope refusals stay refused so status/diagnose can
+/// keep pushing the operator toward `attach-leader`.
+pub(super) fn cmd_send_result(value: Value, as_json: bool) -> CmdResult {
+    let exit = if value.get("ok").and_then(Value::as_bool) == Some(false) {
+        ExitCode::Error
+    } else {
+        ExitCode::Ok
+    };
+    if as_json {
+        CmdResult::from_json(value, true)
+    } else {
+        CmdResult {
+            output: CmdOutput::Human(send_human_output(&value)),
+            exit,
+            as_json: false,
+        }
+    }
+}
+
+pub(super) fn send_human_output(value: &Value) -> String {
+    let mut parts = vec![
+        send_human_field(value, "ok"),
+        format!("status: {}", send_human_status(value)),
+        send_human_field(value, "message_id"),
+        format!("target: {}", send_human_target(value)),
+    ];
+    for key in ["verification", "stage", "reason", "channel"] {
+        if !value.get(key).is_none_or(Value::is_null) {
+            parts.push(send_human_field(value, key));
+        }
+    }
+    // 0.5.45 naming-addressing (design §3.4/§3.5, RED-3 positional):
+    // when the refusal envelope carries a scope-safe suggestion,
+    // surface it verbatim in human output so users can copy the
+    // right short id. `requested_name` echoes the typo, `suggested_
+    // name` is the copyable canonical.
+    if let Some(requested) = value
+        .get("requested_name")
+        .and_then(Value::as_str)
+        .filter(|s| !s.is_empty())
+    {
+        parts.push(format!("requested_name: {requested}"));
+    }
+    if let Some(suggested) = value
+        .get("suggested_name")
+        .and_then(Value::as_str)
+        .filter(|s| !s.is_empty())
+    {
+        parts.push(format!(
+            "Did you mean `{suggested}`? suggested_name: {suggested}"
+        ));
+    }
+    parts.join(" ")
+}
+
+pub(super) fn send_human_field(value: &Value, key: &str) -> String {
+    let rendered = value
+        .get(key)
+        .map(send_human_value)
+        .unwrap_or_else(|| "None".to_string());
+    format!("{key}: {rendered}")
+}
+
+pub(super) fn send_human_target(value: &Value) -> String {
+    ["target", "agent_id", "pane_id", "to_name"]
+        .iter()
+        .find_map(|key| value.get(*key).filter(|v| !v.is_null()))
+        .map(send_human_value)
+        .unwrap_or_else(|| "None".to_string())
+}
+
+pub(super) fn send_human_status(value: &Value) -> String {
+    value
+        .get("status")
+        .map(send_human_value)
+        .unwrap_or_else(|| {
+            if value.get("ok").and_then(Value::as_bool) == Some(true) {
+                "delivered".to_string()
+            } else {
+                "failed".to_string()
+            }
+        })
+}
+
+pub(super) fn send_human_value(value: &Value) -> String {
+    let text = match value {
+        Value::Null => "None".to_string(),
+        Value::Bool(true) => "True".to_string(),
+        Value::Bool(false) => "False".to_string(),
+        Value::Number(n) => n.to_string(),
+        Value::String(s) => s.clone(),
+        Value::Array(_) | Value::Object(_) => {
+            serde_json::to_string(value).unwrap_or_else(|_| "None".to_string())
+        }
+    };
+    text.replace(['\r', '\n'], " ")
+}
+
+pub(super) fn send_reminder_for_value(value: &Value) -> &'static str {
+    let delivered = value.get("delivered").and_then(Value::as_bool);
+    let status = value.get("status").and_then(Value::as_str);
+    let delivery_status = value.get("delivery_status").and_then(Value::as_str);
+    if delivered == Some(false)
+        || matches!(status, Some("queued"))
+        || matches!(delivery_status, Some("pending"))
+    {
+        "Message queued; coordinator will notify when the worker receives it. Do not poll the worker terminal with capture-pane."
+    } else {
+        crate::cli::SEND_REMINDER
+    }
+}
+
+pub(super) fn target_json(target: &MessageTarget) -> Value {
+    match target {
+        MessageTarget::Single(agent) => json!(agent),
+        MessageTarget::Broadcast => json!("*"),
+        MessageTarget::Fanout(recipients) => json!(recipients),
+    }
+}
+
+pub(super) fn first_target(target: &MessageTarget) -> String {
+    match target {
+        MessageTarget::Single(agent) => agent.clone(),
+        MessageTarget::Broadcast => "*".to_string(),
+        MessageTarget::Fanout(recipients) => recipients.first().cloned().unwrap_or_default(),
+    }
+}
+
+pub(super) fn delivery_status_wire(status: DeliveryStatus) -> &'static str {
+    match status {
+        DeliveryStatus::Delivered => "delivered",
+        DeliveryStatus::Failed => "failed",
+        DeliveryStatus::Queued => "queued",
+        DeliveryStatus::Blocked => "blocked",
+        DeliveryStatus::Refused => "refused",
+        DeliveryStatus::Degraded => "degraded",
+        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(super) fn delivery_refusal_wire(reason: DeliveryRefusal) -> &'static str {
+    match reason {
+        DeliveryRefusal::TargetNotInTeam => "target_not_in_team",
+        DeliveryRefusal::HumanConfirmationRequired => "human_confirmation_required",
+        DeliveryRefusal::MissingPermissions => "missing_permissions",
+        DeliveryRefusal::RecipientBusy => "recipient_busy",
+        DeliveryRefusal::UnknownRecipient => "unknown_recipient",
+        DeliveryRefusal::TmuxTargetMissing => "tmux_target_missing",
+        DeliveryRefusal::MessageAlreadyClaimed => "message_already_claimed",
+        DeliveryRefusal::LeaderNotAttached => "leader_not_attached",
+        DeliveryRefusal::CoordinatorUnavailable => "coordinator_unavailable",
+        DeliveryRefusal::NoCallerPane => "no_caller_pane",
+        DeliveryRefusal::TeamOwnerMismatch => "team_owner_mismatch",
+        DeliveryRefusal::Ambiguous => "ambiguous",
+        DeliveryRefusal::RecipientPaneInNonInputMode => "recipient_pane_in_non_input_mode",
+        DeliveryRefusal::SessionDrift => "session_drift",
+        DeliveryRefusal::Duplicate => "duplicate",
+        DeliveryRefusal::RoutingAmbiguous => "routing_ambiguous",
+        DeliveryRefusal::EmptyTargetList => "empty_target_list",
+    }
+}
+
+pub(super) fn delivery_stage_wire(stage: DeliveryStage) -> &'static str {
+    match stage {
+        DeliveryStage::TrustAutoAnswerDismissalWait => "trust_auto_answer_dismissal_wait",
+        DeliveryStage::Inject => "inject",
+        DeliveryStage::Submit => "submit",
+        DeliveryStage::VisibleCheck => "visible_check",
+    }
+}

package/crates/team-agent/src/cli/send/resolve.rs

@@ -0,0 +1,361 @@
+use super::mailbox::maybe_enqueue_offline_leader_mailbox;
+use super::persist::persist_resolved_target;
+use crate::cli::{CliError, SendArgs};
+use crate::messaging::{MessageTarget, TrustedSender};
+use serde_json::{json, Value};
+
+pub(super) fn warn_send_alias(flag: &str) {
+    let spec = crate::cli::spec::command_spec("send");
+    let sunset = spec
+        .and_then(|spec| spec.sunset)
+        .unwrap_or("next compatibility release");
+    let action = spec
+        .and_then(|spec| spec.action)
+        .unwrap_or("use positional logical TARGET addressing");
+    eprintln!("warning: {flag} is deprecated; sunset: {sunset}; action: {action}");
+}
+
+pub(super) fn logical_to_from_args(
+    args: &SendArgs,
+    host_leader_to: Option<&str>,
+) -> Result<String, CliError> {
+    if args.to_name.is_some()
+        && (args.target.is_some() || args.targets.is_some() || args.to_leader.is_some())
+    {
+        return Err(CliError::Usage(
+            "--to-name and --pane/TARGET/--to are mutually exclusive".to_string(),
+        ));
+    }
+    let supplied = [
+        args.target.is_some(),
+        args.targets.is_some(),
+        args.to_name.is_some(),
+        args.to_leader.is_some(),
+    ]
+    .into_iter()
+    .filter(|present| *present)
+    .count();
+    if supplied > 1 {
+        return Err(CliError::Usage(
+            "TARGET, --targets, --to-name, and --to-leader are mutually exclusive".to_string(),
+        ));
+    }
+    let logical_to = if args.to_leader.is_some() {
+        host_leader_to.unwrap_or_default().to_string()
+    } else if let Some(name) = args.to_name.as_deref() {
+        name.to_string()
+    } else if let Some(targets) = args.targets.as_deref() {
+        targets.to_string()
+    } else {
+        args.target.clone().unwrap_or_default()
+    };
+    if args.target.is_none() && supplied > 0 && args.message.is_empty() {
+        if args.to_name.is_some() {
+            return Err(CliError::Usage(
+                "--to-name requires a non-empty message".to_string(),
+            ));
+        }
+        return Err(CliError::Usage(
+            "send requires a non-empty message after logical TO".to_string(),
+        ));
+    }
+    Ok(logical_to)
+}
+
+pub(super) fn resolve_host_leader_alias(
+    name: &str,
+) -> Result<(String, crate::leader::registry::LeaderRegistryEntry), Value> {
+    let classified = crate::leader::registry::list_validated_no_gc();
+    let candidates = classified
+        .iter()
+        .filter(|(entry, _, _)| {
+            entry.delivery_name == name
+                || entry.qualified_name == name
+                || entry.stable_qualified_name == name
+                || entry.aliases.iter().any(|alias| alias == name)
+        })
+        .map(|(entry, _, _)| entry.clone())
+        .collect::<Vec<_>>();
+    if candidates.is_empty() {
+        return Err(json!({
+            "ok": false,
+            "status": "refused",
+            "reason": "leader_name_not_found",
+            "requested_name": name,
+            "resolved_via": "host_leader_registry",
+            "candidates": Vec::<Value>::new(),
+            "workspace_hash": null,
+            "stable_qualified_name": null,
+            "channel": "leader_mailbox",
+            "delivered": false,
+            "message_status": "queued_until_leader_attach",
+            "action": "run `team-agent leaders` to see registered leaders; inspect queued leader messages with `team-agent inbox`; retry with a qualified name",
+            "registry_stale": false,
+        }));
+    }
+    if candidates.len() > 1 {
+        let candidates = candidates
+            .iter()
+            .map(|entry| {
+                json!({
+                    "name": entry.qualified_name,
+                    "workspace": entry.workspace.display().to_string(),
+                    "team_key": entry.team_key,
+                    "workspace_hash": entry.workspace_hash,
+                    "stable_qualified_name": entry.stable_qualified_name,
+                })
+            })
+            .collect::<Vec<_>>();
+        return Err(json!({
+            "ok": false,
+            "status": "refused",
+            "reason": "name_ambiguous",
+            "requested_name": name,
+            "resolved_via": "host_leader_registry",
+            "candidates": candidates,
+            "channel": "leader_mailbox",
+            "delivered": false,
+            "action": "run `team-agent leaders` and retry with the qualified name",
+        }));
+    }
+    let entry = candidates[0].clone();
+    let (status, reason) = crate::leader::registry::classify(&entry);
+    if status == "STALE" {
+        let team_alive = crate::state::persist::load_runtime_state(&entry.workspace)
+            .ok()
+            .and_then(|state| {
+                state
+                    .get("teams")
+                    .and_then(Value::as_object)
+                    .and_then(|teams| teams.get(&entry.team_key))
+                    .and_then(|team| team.get("status"))
+                    .and_then(Value::as_str)
+                    .map(|status| status == "alive" || status.is_empty())
+            })
+            .unwrap_or(false);
+        if !team_alive {
+            return Err(json!({
+                "ok": false,
+                "status": "refused",
+                "reason": "registry_stale",
+                "requested_name": name,
+                "resolved_via": "host_leader_registry",
+                "stale_reason": reason,
+                "workspace_hash": entry.workspace_hash,
+                "stable_qualified_name": entry.stable_qualified_name,
+                "channel": "leader_mailbox",
+                "delivered": false,
+                "action": "target team is not alive; run `team-agent leaders` for current state",
+            }));
+        }
+    }
+    let logical_to = format!("{}::{}/leader", entry.workspace.display(), entry.team_key);
+    Ok((logical_to, entry))
+}
+
+pub(super) fn decorate_host_leader_alias(
+    value: &mut Value,
+    entry: &crate::leader::registry::LeaderRegistryEntry,
+) {
+    let Some(object) = value.as_object_mut() else {
+        return;
+    };
+    object.insert("resolved_via".to_string(), json!("host_leader_registry"));
+    object.insert("to_leader".to_string(), json!(entry.qualified_name));
+    object.insert("requested_name".to_string(), json!(entry.delivery_name));
+    object.insert("workspace_hash".to_string(), json!(entry.workspace_hash));
+    object.insert(
+        "stable_qualified_name".to_string(),
+        json!(entry.stable_qualified_name),
+    );
+}
+
+pub(super) fn send_to_logical_to(
+    args: &SendArgs,
+    logical_to: &str,
+    content: &str,
+) -> Result<Value, CliError> {
+    let names = logical_to
+        .split(',')
+        .map(str::trim)
+        .filter(|name| !name.is_empty())
+        .collect::<Vec<_>>();
+    if names.is_empty() || names.len() != logical_to.split(',').count() {
+        return Err(CliError::Usage(
+            "logical TO comma-list contains an empty recipient".to_string(),
+        ));
+    }
+
+    let mut resolved = Vec::with_capacity(names.len());
+    for name in names {
+        match crate::cli::named_address::resolve_name_for_cli(
+            &args.workspace,
+            name,
+            args.team.as_deref(),
+        ) {
+            Ok((recipient, _transport)) => resolved.push(recipient),
+            Err(mut error) => {
+                adapt_positional_bare_error(args, name, &mut error);
+                if matches!(
+                    error.kind,
+                    crate::cli::named_address::NamedAddressErrorKind::StateNotFound
+                ) {
+                    return Ok(resolution_refusal_json(&error, logical_to, content, args));
+                }
+                if resolved.is_empty() && !logical_to.contains(',') {
+                    if let Some(value) = maybe_enqueue_offline_leader_mailbox(
+                        &args.workspace,
+                        name,
+                        content,
+                        args.sender.as_str(),
+                        args.task.as_deref(),
+                        &error,
+                    )? {
+                        return Ok(value);
+                    }
+                }
+                if args.json {
+                    return Ok(error.to_json());
+                }
+                return Err(CliError::Usage(error.n38_message()));
+            }
+        }
+    }
+
+    if resolved.len() == 1 {
+        return send_to_resolved_name(args, &resolved[0], content);
+    }
+
+    let first = &resolved[0];
+    let one_scope = resolved.iter().all(|recipient| {
+        recipient.target_workspace == first.target_workspace && recipient.team_key == first.team_key
+    });
+    if one_scope {
+        let recipients = resolved
+            .iter()
+            .map(logical_recipient_id)
+            .collect::<Result<Vec<_>, _>>()?;
+        let target = MessageTarget::Fanout(recipients);
+        return persist_resolved_target(args, first, &target, content);
+    }
+
+    let mut results = Vec::with_capacity(resolved.len());
+    for recipient in &resolved {
+        results.push(send_to_resolved_name(args, recipient, content)?);
+    }
+    let ok = results
+        .iter()
+        .all(|value| value.get("ok").and_then(Value::as_bool) == Some(true));
+    let message_id = results
+        .iter()
+        .rev()
+        .find_map(|value| value.get("message_id").and_then(Value::as_str))
+        .map(str::to_string);
+    Ok(json!({
+        "ok": ok,
+        "status": if ok { "fanout_delivered" } else { "fanout_partial" },
+        "delivery_status": if ok { "pending" } else { "fanout_partial" },
+        "delivered": false,
+        "target": logical_to.split(',').map(str::trim).collect::<Vec<_>>(),
+        "content_length_bytes": content.len(),
+        "sender": args.sender,
+        "message_id": message_id,
+        "results": results,
+    }))
+}
+
+pub(super) fn resolution_refusal_json(
+    error: &crate::cli::named_address::NamedAddressError,
+    logical_to: &str,
+    content: &str,
+    args: &SendArgs,
+) -> Value {
+    let mut value = error.to_json();
+    if let Some(object) = value.as_object_mut() {
+        object.insert("delivery_status".to_string(), json!("refused"));
+        object.insert("delivered".to_string(), json!(false));
+        object.insert("target".to_string(), json!(logical_to));
+        object.insert("agent_id".to_string(), json!(logical_to));
+        object.insert("content_length_bytes".to_string(), json!(content.len()));
+        object.insert("sender".to_string(), json!(args.sender));
+        object.insert("message_id".to_string(), Value::Null);
+        object.insert("message_status".to_string(), json!("refused"));
+        object.insert("verification".to_string(), Value::Null);
+        object.insert("stage".to_string(), Value::Null);
+        object.insert("channel".to_string(), Value::Null);
+    }
+    value
+}
+
+pub(super) fn adapt_positional_bare_error(
+    args: &SendArgs,
+    name: &str,
+    error: &mut crate::cli::named_address::NamedAddressError,
+) {
+    if args.target.as_deref() != Some(name)
+        || args.team.is_none()
+        || name.contains('/')
+        || name.contains(':')
+        || name.contains(',')
+    {
+        return;
+    }
+    error.requested_name = Some(name.to_string());
+    for candidate in &mut error.candidates {
+        let agent_id = candidate
+            .get("agent_id")
+            .and_then(Value::as_str)
+            .map(str::to_string);
+        if let (Some(object), Some(agent_id)) = (candidate.as_object_mut(), agent_id) {
+            object.insert("name".to_string(), json!(agent_id));
+        }
+    }
+    error.suggested_name = error
+        .suggested_name
+        .as_deref()
+        .and_then(|suggested| suggested.rsplit('/').next())
+        .map(str::to_string);
+    if let Some(suggested) = error.suggested_name.as_deref() {
+        error.action = format!("Did you mean `{suggested}`? Retry with `{suggested}` as TO.");
+    }
+}
+
+pub(super) fn logical_recipient_id(
+    resolved: &crate::cli::named_address::ResolvedNamedAddress,
+) -> Result<String, CliError> {
+    match resolved.target_kind {
+        crate::cli::named_address::NamedTargetKind::Worker => resolved
+            .agent_id
+            .clone()
+            .ok_or_else(|| CliError::Runtime("resolved worker is missing agent id".to_string())),
+        crate::cli::named_address::NamedTargetKind::Leader => Ok("leader".to_string()),
+        crate::cli::named_address::NamedTargetKind::SessionWindow => Err(CliError::Usage(
+            "named session/window delivery is sunset; use a logical agent or leader name"
+                .to_string(),
+        )),
+    }
+}
+
+pub(super) fn send_to_resolved_name(
+    args: &SendArgs,
+    resolved: &crate::cli::named_address::ResolvedNamedAddress,
+    content: &str,
+) -> Result<Value, CliError> {
+    let recipient = logical_recipient_id(resolved)?;
+    if let Some(warning) = &resolved.warning {
+        eprintln!("warning: {warning}");
+    }
+    let target = MessageTarget::Single(recipient);
+    let mut value = persist_resolved_target(args, resolved, &target, content)?;
+    if args.to_name.is_some() || args.to_leader.is_some() {
+        if let Some(obj) = value.as_object_mut() {
+            obj.insert("to_name".to_string(), json!(resolved.raw_name));
+            obj.insert(
+                "target_workspace".to_string(),
+                json!(resolved.target_workspace.display().to_string()),
+            );
+            obj.insert("team_key".to_string(), json!(resolved.team_key));
+        }
+    }
+    Ok(value)
+}