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

[Leoyzen]

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

[gemini-code-assist]

Code Review

This pull request implements a dynamic team mode in AgentPool, allowing LLM agents to dynamically form, coordinate, and dissolve teams at runtime, supported by a file-based state store for inboxes, tasks, and blackboard entries. It also adds extensive Logfire span instrumentation to fix orphan traces in distributed tracing. The review feedback identifies several key issues to address: fixing Python < 3.11 compatibility by replacing 'datetime.UTC' with 'datetime.timezone.utc', ensuring parent directories are created for nested lock files to prevent 'FileNotFoundError', implementing proper cleanup of orphaned sessions on initialization or creation failures, and offloading blocking synchronous file I/O and lock operations to background threads via 'asyncio.to_thread' to avoid blocking the asyncio event loop.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[Leoyzen]

架构问题记录

在 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. 结合问题 feat: add dynamic instructions from ResourceProviders for context… #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 组成"的便利性

---

优先级

• feat: add dynamic instructions from ResourceProviders for context… #1 是 blocker — 不修这个，auto_init 和 team_create 的 lead 权限检查在生产环境都不工作
• feat(tools): implement extended tool definitions with native Pydantic… #2 是重要功能缺失 — 不修这个，member session 的活动对 protocol 客户端不可见
• feat(agent): implement history processors for PydanticAI integration … #3 是架构简化 — 如果决定移除 auto_init， feat: add dynamic instructions from ResourceProviders for context… #1 中 auto_init 相关的部分可以忽略，只需修 team_create 的 team_role 设置