feat: dynamic team mode — LLM-driven runtime team creation

[Million-mo]

Dynamic Team Mode

AI agents can create, manage, and dissolve teams at runtime through tool calls — spawning teammate sessions, sending messages, sharing a task board with dependency tracking, and collaborating via a shared blackboard. Stale team data is cleaned up automatically via a TTL background task.

What's New

• 14 team tools (9 universal + 5 lead-only):
  • Universal (all members): send_message, task_create, task_list, task_update, task_get, read_blackboard, write_blackboard, list_blackboard, team_status
  • Lead-only: team_create, team_delete, delete_blackboard, shutdown_request, team_add_member
• Role-aware tool filtering: Lead agents see all 14 tools; non-lead members see 9 tools with send_message broadcast (to="*") stripped from the description and blocked via regex pattern constraint (^[^*]+$)
• Protocol template injection: _DEFAULT_PROTOCOL_TEMPLATE renders per-member instructions with {member_name}, {team_name}, {role} placeholders, plus role-specific capability sections and an eligible agents list — injected via get_instructions() into the system prompt
• File-based team state (FileTeamState): atomic writes, file locks, optimistic locking for blackboard, path traversal prevention
• Per-session scoping: FileTeamState isolated by base_dir + team_id (stored in session metadata at team_create time)
• Bounds enforcement: max_members, max_member_turns, inbox_max_bytes, blackboard max_size_mb
• TTL cleanup: background task in AgentPool.__aenter__ that marks orphaned teams (active + TTL expired) and removes deleted teams (deleted + TTL expired), running every 10 minutes
• Per-session capability instantiation: shared TeamCommCapability at compile time (returns None instructions, no tool filtering), replaced by per-session instance at runtime with actual session metadata (renders template, filters tools by role)
• Watch mechanism: team_status and list_blackboard support blocking watch mode with configurable timeout and task-specific watching
• Task reminder: after_run() checks for unfinished tasks after a member's run completes, sending <team-message type="task_reminder"> to prompt completion
• Ephemeral members: team_add_member supports lifecycle="ephemeral" for auto-closing members when their run completes

How It Works

Two-Phase Capability Registration

1. Compile time (factory.py _compile_agent_capabilities): Creates a shared TeamCommCapability(session_metadata=None) — get_instructions() returns None, prepare_tools() returns all tools unfiltered
2. Runtime (factory.py create_session_agent): Sets session.metadata["team_role"] and ["team_member_name"], creates a new TeamCommCapability(session.metadata), and replaces the shared instance in agent._extra_capabilities

Prompt Injection

TeamCommCapability.get_instructions() returns three layers when session metadata is present:

1. Protocol template — rendered with team name, role, and member name
2. Role-specific capabilities — lead gets broadcast/team management instructions; members get "broadcast not available" guidance
3. Eligible agents list — agents available for team_create from member_eligible config

Tool Result Format

All tool returns use XML format for LLM parseability:

• Tasks: <task id="..." status="..." owner="...">...</task>
• Blackboard: <blackboard version="..." written_by="...">...</blackboard>
• Messages: <team-message from="..." type="private|broadcast|task_notification|task_reminder">...</team-message>

Hook Integration

No team-specific hooks. All 4 standard hook points (pre_turn, post_turn, pre_tool_use, post_tool_use) fire through HookAwareTurn for team tools identically to any other tool. Tool execution is logged to the Journal via _log_tool_execution() for crash recovery idempotency.

Config Flow

YAML team_mode: → AgentsManifest.team_mode (global)
                → BaseAgentConfig.team_mode (per-agent override)
                        │
                        ▼
              resolve_team_mode(global, agent) → TeamModeConfig
                        │
                ┌───────┴───────┐
                ▼               ▼
     factory.py compile      factory.py runtime
     shared capability       per-session replacement

Note: AgentContext.team_mode_config is declared but not set by the RunLoop's _inject_agent_context() in production (always None). The system operates through session metadata (team_id, team_base_dir) set by team_create, with team_mode_config as a fallback only.

Files Changed

New source files (3):

• src/agentpool_config/team_mode.py — TeamModeConfig Pydantic model with TeamBounds, BlackboardConfig, MemberSpec, _DEFAULT_PROTOCOL_TEMPLATE
• src/agentpool/capabilities/file_team_state.py — File-based persistence with atomic writes, file locks, optimistic locking, TTL cleanup
• src/agentpool/capabilities/team_comm_capability.py — TeamCommCapability(FunctionToolsetCapability) with 14 tools, role-aware filtering, protocol template injection, after_run() task reminders

Modified files (6):

• src/agentpool/capabilities/agent_context.py — added team_mode_config field
• src/agentpool/orchestrator/run.py — AgentContext construction (field defaults to None in production; session metadata is the primary config carrier)
• src/agentpool/models/manifest.py — added team_mode field to AgentsManifest
• src/agentpool_config/nodes.py — added team_mode field to BaseAgentConfig
• src/agentpool/host/factory.py — TeamCommCapability two-phase registration (compile-time shared + runtime per-session replacement)
• src/agentpool/delegation/pool.py — TTL cleanup task lifecycle (__aenter__ start, __aexit__ cancel)

Dependency: filelock>=3.13 added to pyproject.toml

Test Coverage

111 tests across 5 files (all pass):

• tests/test_team_mode_config.py — 10 unit tests (config model validation)
• tests/capabilities/test_file_team_state.py — 29 unit tests (file persistence, blackboard, tasks, cleanup)
• tests/capabilities/test_team_comm_capability.py — 59 unit tests (all 14 tools, bounds, role filtering)
• tests/integration/test_team_auto_init.py — 3 integration tests (auto_init lifecycle)
• tests/integration/test_team_mode.py — 10 integration tests (e2e lifecycle, coexistence)

Quality Gates

• ✅ ruff check — all pass
• ✅ ruff format --check — all pass
• ✅ mypy — 0 errors in new files
• ✅ No getattr/hasattr in new code
• ✅ No TODO/FIXME/HACK in new code
• ✅ RFC-0055 status updated to IMPLEMENTED

Documentation

• AGENTS.md — Team Mode section with config YAML, 14 tools table, protocol template explanation
• site/examples/team-translation/config.yml — translation team with auto_init
• site/examples/team-sales/config.yml — sales team with auto_init + blackboard
• site/examples/team-dev-squad/config.yml — dev squad with manual team_create
• docs/rfcs/draft/RFC-0055-dynamic-team-mode.md — RFC (status: IMPLEMENTED)

Design Decisions

1. Direct SessionPool access (no wrapper) — follows RunLoopDelegationService pattern
2. File-based persistence in tempdir — ephemeral, isolated by UUID, atomic writes
3. Binary priority — only DeliveryMode.STEER and DeliveryMode.QUEUE
4. Session metadata as primary config carrier — team_id and team_base_dir stored in session.metadata at team_create time; AgentContext.team_mode_config is a fallback only (not set by RunLoop in production)
5. Per-agent team_mode field — all agent types inherit via BaseAgentConfig
6. Per-session TeamCommCapability — shared at compile time (no instructions, no filtering), replaced at runtime with per-session instance (renders template, filters tools by role)
7. No team-specific hooks — standard HookAwareTurn applies to all team tools identically
8. Role-aware tool filtering at prepare_tools() — lead-only tools removed from non-lead members; send_message broadcast capability restricted via description + regex pattern

---

备份迁移自 SRC-PR#168 · 作者 @Leoyzen · 创建于 2026-07-16T11:24:44Z · head=feat/dynamic-team-mode base=main
源状态: merged · merge_commit_sha=ff1a6a7438eea053a9a03442282a96872a5c1a8e

[Million-mo]

评论 by @Leoyzen 于 2026-07-16T12:58:58Z（备份迁移）

架构问题记录

在 review 过程中发现三个架构层面的问题，记录在此供后续讨论和跟踪。

---

1. team_role metadata 未自动设置 — auto_init 在生产环境无法触发

问题：_maybe_auto_init() 检查 session.metadata.get("team_role") == "lead"，但在 ACP/OpenCode 的 session 创建路径中，没有任何地方自动设置 team_role。

追踪：

• Protocol server 创建 lead session → SessionPool.create_session(session_id, agent_name="coordinator", **metadata) → metadata 不含 team_role
• Factory create_session_agent() 创建 TeamCommCapability(config, agent_name, session.metadata) → 不修改 metadata
• 结果：team_role 永远是空字符串 → role != "lead" 永远为 True → auto_init 永远跳过

测试中 team_role 是手动塞进 metadata 的，所以测试通过但生产环境不工作。

修复方案：在 factory create_session_agent() 中，当 agent 在 lead_eligible 列表里时自动设置：

if resolved_tm.enabled and agent_name in resolved_tm.lead_eligible:
    session_state.metadata.setdefault("team_role", "lead")
    session_state.metadata.setdefault("team_member_name", agent_name)

---

2. auto_init 创建的 member session 未发布 SpawnSessionStart — protocol server 无法发现

问题：auto_init 和 team_create 通过 session_pool.create_session() + session_pool.send_message() 创建 member session，但没有发布 SpawnSessionStart 事件。Protocol server（ACP/OpenCode）的 _on_spawn_session_start() 钩子无法触发，不会为 member session 启动 event consumer。

影响：

• Member agent 确实会执行（RunHandle 启动 RunLoop，LLM 正常调用）
• 但 member session 的所有事件（stream tokens、tool calls 等）流到 EventBus 后没有消费者，事件被丢弃
• ACP/OpenCode 客户端看不到 member agent 的任何活动

对比：正常的 subagent delegation 路径通过 AgentContext.create_child_session() 创建子 session，会自动发布 SpawnSessionStart，protocol server 能正确发现并启动子消费者。

修复方案：在 create_session() 之后、send_message() 之前，发布 SpawnSessionStart 事件：

from agentpool.agents.events.events import SpawnSessionStart

spawn_event = SpawnSessionStart(
    child_session_id=member_session_id,
    parent_session_id=lead_session_id,
    tool_call_id="",
    spawn_mechanism="spawn",
    source_name=member.agent,
    source_type="agent",
    depth=1,
    description=f"Team member: {member.name}",
)
await session_pool.event_bus.publish(lead_session_id, spawn_event)

---

3. auto_init 可能是过度设计 — 考虑移除

问题：auto_init 的设计意图是"让 lead agent 不需要显式调用 team_create"，但：

1. auto_init 仍然依赖 LLM tool call — 它在每个 team tool 函数开头触发，但 tool call 本身就是 LLM 的决策。LLM 既然在调 tool，完全可以先调 team_create
2. ~175 LOC 重复代码 — _maybe_auto_init 几乎复制了 team_create 的全部逻辑
3. 12 个 tool 函数被污染 — 每个函数开头都要加 init_result = await self._maybe_auto_init(ctx)
4. 隐式副作用 — LLM 调用 send_message，team 被悄悄创建，LLM 不知道发生了什么
5. 结合问题 [PR #15] feat(file_edit): implement streaming file I/O with async operations, … #1 — auto_init 在生产环境根本触发不了

建议：移除 auto_init，改为在 team_create 中支持从 config 读取默认 member（当 members 参数为空时从 auto_init.members 读取）。这样：

• 减少 ~175 LOC
• 去掉 12 个 tool 函数中的 _maybe_auto_init 调用
• 行为对 LLM 完全透明（显式调用 team_create）
• 保留"从 YAML 配置读取 team 组成"的便利性

---

优先级

• [PR #15] feat(file_edit): implement streaming file I/O with async operations, … #1 是 blocker — 不修这个，auto_init 和 team_create 的 lead 权限检查在生产环境都不工作
• BackgroundTaskProvider async_mode 导致 agent 无法恢复运行及前端事件丢失 #2 是重要功能缺失 — 不修这个，member session 的活动对 protocol 客户端不可见
• Storage 功能不工作：重启后历史会话丢失（ACP & OpenCode 均受影响） #3 是架构简化 — 如果决定移除 auto_init，[PR #15] feat(file_edit): implement streaming file I/O with async operations, … #1 中 auto_init 相关的部分可以忽略，只需修 team_create 的 team_role 设置

[Million-mo]

评论 by @Leoyzen 于 2026-07-24T04:19:57Z（备份迁移）

Steer 消息丢失问题分析

在 team 模式测试中发现，member agent 经常卡住不执行 — Conductor 通过 send_message (STEER mode) 发消息给 member，消息看似投递成功（返回 message_id），但实际丢失，member 永远收不到，需要手动激活。

根因

RunHandle.steer() 在 active_agent_run is None 时，将消息写入 run_ctx.queued_steer_messages 列表，但该列表在整个代码库中从未被消费（只写不读）。消息随 RunHandle 销毁而永久丢失。

消息丢失的时间线

T0  NativeTurn while 循环到达 End 节点
T1  finally 块清除 active_agent_run = None  (turn.py:443)
T2  NativeTurn 继续构建 final_message, yield StreamCompleteEvent
    === 竞态窗口开始 ===
T3  Conductor 发 STEER → _route_message() 查 current_run_id → 找到 run（尚未清理）
T4  _route_message() 调用 run.steer(content)
T5  steer() 发现 active_agent_run is None → 写入 queued_steer_messages
    === 竞态窗口结束 ===
T6  _consume_run() 清理 _runs + current_run_id
T7  prompt_queue 为空 → session idle
T8  queued_steer_messages 随 RunHandle 丢弃 → 消息永久丢失

为什么 stale-run detection 没捕获

_route_message() 的 stale-run detection（session_controller_runs.py:535-538）检查 existing_run.complete_event.is_set()，但 complete_event 在 _consume_run() 后面的 _cleanup_run() 中才设置。在竞态窗口内，run 看起来还是"活跃"的。

关键代码位置

文件	行号	问题
agents/context.py	172	queued_steer_messages 定义 — 只写不读的死列表
orchestrator/run.py	646-650	steer() fallback 写入 queued_steer_messages
orchestrator/run.py	359-361	注释声称 _execute_turn() 会 drain，但实际没有
agents/native_agent/turn.py	443	finally 块清除 active_agent_run（竞态窗口起点）
orchestrator/session_controller_runs.py	535-538	stale-run detection 检查 complete_event，但时机太晚
orchestrator/session_controller_runs.py	241-263	_consume_run() 只检查 prompt_queue，不检查 feedback_queue

三个丢失场景

1. Turn 结束后的竞态窗口（最常见）：active_agent_run 被 finally 块清除，但 current_run_id 和 _runs 还没清理。_route_message() 认为成员"忙"，调用 steer()，消息进入死列表。

2. start() 中 feedback_queue drain 时机错误：RunHandle.start()（run.py:362-370）在 _execute_turn() 之前 drain feedback_queue，此时 active_agent_run 还没设置 → steer() 把消息写入 queued_steer_messages → 丢失。

3. 新 RunHandle 创建后、active_agent_run 设置前：_route_message() 创建新 RunHandle 后，第二个 STEER 到达 → steer() 看到 active_agent_run is None → 写入 queued_steer_messages → 丢失。

已有的测试 test_run_handle.py:1503 明确记录了这个已知缺陷：

"""Empty prompt drains feedback_queue but queued_steer_messages are never processed.
Known limitation: ... The steer messages are technically in
queued_steer_messages but no turn processes them.
"""

修复方案

方案 A: steer() fallback 改为写入 session.feedback_queue（推荐）

# run.py steer() lines 646-650, 替换:
# self.run_ctx.queued_steer_messages.append(fb.content_blocks)
# self.run_ctx.queued_steer_messages.append(fb.content)

# 改为:
if self.session is not None:
    self.session.feedback_queue.put_nowait(fb)

feedback_queue 是 SessionState 级别的队列，跨 RunHandle 存活。新 RunHandle 的 start() 已经会 drain feedback_queue（run.py:362-370）。

但场景 2 的问题仍需修复 — start() drain feedback_queue 时 active_agent_run 还没设置，消息会再次进入 queued_steer_messages。所以还需要方案 B 配合。

方案 B: NativeTurn.execute() 中 drain queued_steer_messages（配合 A）

# turn.py line 244 之后，active_agent_run 设置后立即添加:
if self._run_ctx._run_handle is not None:
    self._run_ctx._run_handle.active_agent_run = agent_run
    # Drain queued steer messages that arrived before active_agent_run was set.
    queued = self._run_ctx.queued_steer_messages
    if queued:
        self._run_ctx.queued_steer_messages = []
        for msg in queued:
            if isinstance(msg, list):
                agent_run.enqueue(*msg, priority="asap")
            else:
                agent_run.enqueue(msg, priority="asap")

这是 run.py:359 注释声称但从未实现的逻辑。

方案 C: _route_message() 增强 stale-run detection（可选加固）

# session_controller_runs.py:535-538, 在 complete_event 检查之外额外检查:
if session.current_run_id is not None:
    existing_run = self._runs.get(session.current_run_id)
    if existing_run is None or existing_run.complete_event.is_set() or existing_run.active_agent_run is None:
        session.set_current_run_id(None)

如果 active_agent_run is None，说明 turn 已结束但还没清理 — 视为 stale，走 idle 路径创建新 run。

推荐组合

方案 A + B：A 解决消息存活问题（feedback_queue 跨 RunHandle 存活），B 解决 start() drain 后消息再次进入死列表的问题。

可选加 C：进一步减少竞态窗口，让 _route_message() 更早检测到 stale run。

修复后应更新 test_run_handle.py:1503 的已知缺陷测试，验证消息不再丢失。