@team-agent/installer 0.3.21 → 0.3.23

package/crates/team-agent/src/transport/test_support.rs

@@ -33,6 +33,7 @@ struct OfflineState {
     default_liveness: PaneLiveness,
     calls: Vec<&'static str>,
     spawns: Vec<SpawnRecord>,
+    pane_titles: Vec<(String, String, String, String)>,
     inject_targets: Vec<Target>,
     inject_payloads: Vec<String>,
     tmux_endpoint: Option<String>,
@@ -52,6 +53,7 @@ impl Default for OfflineState {
             default_liveness: PaneLiveness::Unknown,
             calls: Vec::new(),
             spawns: Vec::new(),
+            pane_titles: Vec::new(),
             inject_targets: Vec::new(),
             inject_payloads: Vec::new(),
             tmux_endpoint: None,
@@ -149,6 +151,10 @@ impl OfflineTransport {
         })
     }
 
+    pub fn pane_title_records(&self) -> Vec<(String, String, String, String)> {
+        self.with_state(|state| state.pane_titles.clone())
+    }
+
     pub fn inject_targets(&self) -> Vec<Target> {
         self.with_state(|state| state.inject_targets.clone())
     }
@@ -350,6 +356,25 @@ impl Transport for OfflineTransport {
         }))
     }
 
+    fn configure_adaptive_pane_title(
+        &self,
+        session: &SessionName,
+        window: &WindowName,
+        pane: &PaneId,
+        title: &str,
+    ) -> Result<(), TransportError> {
+        self.with_state(|state| {
+            state.calls.push("configure_adaptive_pane_title");
+            state.pane_titles.push((
+                session.as_str().to_string(),
+                window.as_str().to_string(),
+                pane.as_str().to_string(),
+                title.to_string(),
+            ));
+        });
+        Ok(())
+    }
+
     fn set_session_env(
         &self,
         _session: &SessionName,

package/crates/team-agent/src/transport.rs

@@ -530,6 +530,17 @@ pub trait Transport: Send + Sync {
         session: &SessionName,
     ) -> Result<Vec<WindowName>, TransportError>;
 
+    fn configure_adaptive_pane_title(
+        &self,
+        session: &SessionName,
+        window: &WindowName,
+        pane: &PaneId,
+        title: &str,
+    ) -> Result<(), TransportError> {
+        let _ = (session, window, pane, title);
+        Ok(())
+    }
+
     /// tmux=`set-environment`;无 server-env 的后端(WezTerm/ConPTY)对 worker 内化为
     /// 「spawn 时注入」(`InternalizedAtSpawn`),对外部 leader pane 返回 typed 不支持
     /// (`UnsupportedForExternalPane`,§4c)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.3.21",
+  "version": "0.3.23",
   "description": "npx installer for Team Agent",
   "keywords": [
     "codex",
@@ -20,9 +20,9 @@
     "team-agent-installer": "npm/install.mjs"
   },
   "optionalDependencies": {
-    "@team-agent/cli-darwin-arm64": "0.3.21",
-    "@team-agent/cli-darwin-x64": "0.3.21",
-    "@team-agent/cli-linux-x64": "0.3.21"
+    "@team-agent/cli-darwin-arm64": "0.3.23",
+    "@team-agent/cli-darwin-x64": "0.3.23",
+    "@team-agent/cli-linux-x64": "0.3.23"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",

package/skills/team-agent/SKILL.md

@@ -158,6 +158,7 @@ For diagnosis, run `team-agent profile show deepseek --workspace . --json`; neve
 - Quick-start generated files stay inside the selected team directory, for example `.team/current/` or `.team/alpha/`; do not create or expect root `team.spec.yaml` or `team_state.md`.
 - Use `team-agent quick-start ./roles --team-id alpha` to create a second generated team under `.team/alpha/`, or pass an existing team directory directly such as `team-agent quick-start .team/alpha`.
 - `quick-start` is for fresh startup from role docs. If stored worker context already exists for that runtime session, follow the returned `team-agent restart . --team <session>` action to resume it. Use `--fresh` only when the user explicitly accepts new blank worker contexts.
+- If the user explicitly asks a worker to create or operate a nested child team, first read `references/team-in-team.md`. Child teams must use an independent child workspace, never the parent `.team/current`.
 - `team-agent send --watch-result coder "Do the bounded task"` sends a direct worker message, returns after delivery, and lets the coordinator collect/report completion asynchronously.
 - After `send --watch-result` succeeds, do not run `sleep`, `status`, `inbox`, or `collect` polling loops unless the user explicitly asks for diagnosis; the coordinator will notify the leader when the result arrives.
 - `team-agent send --task task_initial "Start"` routes by task.
@@ -214,7 +215,7 @@ Removing a worker at runtime is the symmetric `team-agent remove-agent <agent> -
 
 ## Worker Protocol
 
-Workers do not run nested Team Agent teams. Workers only provide the target and content for progress, and a short completion summary at the end:
+Workers normally do not run nested Team Agent teams. When the user or leader explicitly asks for a child team, follow `references/team-in-team.md`; otherwise workers only provide the target and content for progress, and a short completion summary at the end:
 
 ```text
 team_orchestrator.send_message(to="leader", content="short progress or blocker")

package/skills/team-agent/references/team-in-team.md

@@ -0,0 +1,127 @@
+# Team-In-Team Reference
+
+This reference is for explicitly requested nested Team Agent teams. Use it only when the user or leader asks a worker to create or operate a child team. For normal work, a worker should stay inside its parent team and report through `team_orchestrator`.
+
+## Safety Rules
+
+- Use the Team Agent framework skill and `team-agent` CLI. Do not use a provider's built-in agent-team feature when the user asked for Team Agent.
+- Never create a child team in the parent team's `.team/current` directory.
+- Never edit, delete, or reuse files under the parent team's `.team/current`.
+- Never shut down a team just because `.team/current` is already occupied. In a nested setup, that is probably the parent team; shutting it down can kill the main node.
+- A child team needs its own workspace directory. The role-doc directory is not the child workspace.
+- MCP tools are team-scoped. A worker must not try to widen `team_orchestrator.send_message` to another team.
+
+## Child Workspace
+
+Pick an independent directory before writing `TEAM.md` or agent role docs. A safe default is a child workspace under the parent workspace, but outside the parent `.team/current`:
+
+```bash
+PARENT_WORKSPACE="$PWD"
+case "$PARENT_WORKSPACE" in
+  */.team/current|*/.team/current/*)
+    echo "Refusing to create a child team from parent .team/current; cd to the parent workspace root first." >&2
+    exit 1
+    ;;
+esac
+CHILD_TEAM="child-review-team"
+CHILD_WORKSPACE="$PARENT_WORKSPACE/.team/children/review-$(date +%Y%m%d%H%M%S)"
+mkdir -p "$CHILD_WORKSPACE"
+cd "$CHILD_WORKSPACE"
+mkdir -p .team/current/agents
+```
+
+Then create the child team's files inside the child workspace:
+
+```bash
+cat > .team/current/TEAM.md <<'EOF'
+---
+name: child-review-team
+objective: Run a bounded child-team task and report to the parent worker.
+dangerous_auto_approve: false
+fast: false
+---
+
+Child team config only.
+EOF
+
+cat > .team/current/agents/reviewer.md <<'EOF'
+---
+name: reviewer
+role: Independent Reviewer
+provider: codex
+tools:
+  - fs_read
+  - fs_list
+  - mcp_team
+---
+
+Review only the files and instructions provided by the child-team leader.
+Report findings with team_orchestrator.report_result exactly once.
+EOF
+
+team-agent quick-start .team/current
+```
+
+If `quick-start` reports that `current` or a tmux session already exists, do not run `shutdown`. Move to a new child workspace or change the child team name.
+
+## Parent Protection
+
+The parent worker is also the child team's leader. Keep the two scopes separate:
+
+- Parent team: the worker talks upward with its parent `team_orchestrator` MCP tools.
+- Child team: the same worker talks downward with `team-agent send --workspace "$CHILD_WORKSPACE" --team "$CHILD_TEAM" ...`.
+
+Do not run child lifecycle commands against the parent workspace. Always pass the child workspace and team when operating the child team from the parent worker.
+
+## Parent-Child Messaging
+
+Use explicit two-hop routing.
+
+Parent leader to child worker:
+
+1. Parent leader sends the child-task instruction to the parent worker that owns the child team.
+2. Parent worker sends into the child team:
+
+```bash
+team-agent send reviewer "Review this patch and report findings" \
+  --workspace "$CHILD_WORKSPACE" \
+  --team "$CHILD_TEAM" \
+  --watch-result
+```
+
+Child worker to parent leader:
+
+1. Child worker reports to its child leader:
+
+```text
+team_orchestrator.send_message(to="leader", content="short progress")
+team_orchestrator.report_result(summary="short completion", status="success")
+```
+
+2. The parent worker, acting as child leader, relays the relevant summary upward to the parent leader with its parent-team MCP tools.
+
+Do not ask a child worker to send directly to a parent-team agent id. Current MCP scope is team-local and should refuse out-of-scope peers. Use CLI `--workspace` and `--team` only from the appropriate leader/operator side when crossing team boundaries.
+
+## Clean-Context Roles
+
+Asking for a clean-context role is a normal feature request when the user wants a blind reviewer, a fresh second opinion, or a role that forgets earlier conversation. It is not the same as failure recovery.
+
+For an existing worker that should restart with a blank provider context, the leader can use:
+
+```bash
+team-agent reset-agent "$AGENT_ID" --workspace "$WORKSPACE" --team "$TEAM" --discard-session --json
+```
+
+or the equivalent restart form:
+
+```bash
+team-agent restart-agent "$AGENT_ID" --workspace "$WORKSPACE" --team "$TEAM" --discard-session --json
+```
+
+Use this only when the user intentionally wants a clean context. For incident recovery, follow `recovery-runbook.md`, where context-preserving repair comes first.
+
+## Framework Gaps To Track
+
+- Nested mode needs a way to pin the framework Team Agent skill by absolute path, so providers do not choose their built-in agent-team feature.
+- A child-team worker should be prevented from shutting down the parent team by mistake.
+- Child team creation should avoid defaulting to the fragile parent `current` directory.