feat: implement meeting protocol system (#123)

CLAUDE.md

@@ -46,7 +46,7 @@ src/ai_company/
   api/            # FastAPI REST + WebSocket routes
   budget/         # Per-agent cost tracking and spending controls
   cli/            # Typer CLI commands
-  communication/  # Message bus, dispatcher, messenger, channels, delegation, loop prevention
+  communication/  # Message bus, dispatcher, messenger, channels, delegation, loop prevention, meeting protocol
   config/         # YAML company config loading and validation
   core/           # Shared domain models and base classes
   engine/         # Agent orchestration, execution loops, parallel execution, task lifecycle, recovery, and shutdown
@@ -82,7 +82,7 @@ src/ai_company/
 - **Every module** with business logic MUST have: `from ai_company.observability import get_logger` then `logger = get_logger(__name__)`
 - **Never** use `import logging` / `logging.getLogger()` / `print()` in application code
 - **Variable name**: always `logger` (not `_logger`, not `log`)
-- **Event names**: always use constants from the domain-specific module under `ai_company.observability.events` (e.g. `PROVIDER_CALL_START` from `events.provider`, `BUDGET_RECORD_ADDED` from `events.budget`). Import directly: `from ai_company.observability.events.<domain> import EVENT_CONSTANT`
+- **Event names**: always use constants from the domain-specific module under `ai_company.observability.events` (e.g. `PROVIDER_CALL_START` from `events.provider`, `BUDGET_RECORD_ADDED` from `events.budget`, `MEETING_STARTED` from `events.meeting`). Import directly: `from ai_company.observability.events.<domain> import EVENT_CONSTANT`
 - **Structured kwargs**: always `logger.info(EVENT, key=value)` — never `logger.info("msg %s", val)`
 - **All error paths** must log at WARNING or ERROR with context before raising
 - **All state transitions** must log at INFO

DESIGN_SPEC.md

@@ -578,7 +578,7 @@ When a loop is detected, the framework:
 3. Escalates to the sender's manager (or human if at top of hierarchy)
 4. Logs the loop for analytics and process improvement
 
-> **Current state (M4 in-progress):** The communication foundation is implemented: `MessageBus` protocol with `InMemoryMessageBus` backend (asyncio queues, pull-model `receive()`), `MessageDispatcher` for concurrent handler routing via `asyncio.TaskGroup`, `AgentMessenger` per-agent facade (auto-fills sender/timestamp/ID, deterministic direct-channel naming `@{sorted_a}:{sorted_b}`), and `DeliveryEnvelope` for delivery tracking. Loop prevention (§5.5) is implemented: `DelegationGuard` orchestrates five mechanisms (ancestry, depth, dedup, rate limit, circuit breaker) with `LoopPreventionConfig`. Hierarchical delegation is implemented via `DelegationService` with `HierarchyResolver` and `AuthorityValidator`. Task model extended with `parent_task_id` and `delegation_chain` fields. Conflict resolution (§5.6) and meeting protocol (§5.7) are planned for later M4 work.
+> **Current state (M4 in-progress):** The communication foundation is implemented: `MessageBus` protocol with `InMemoryMessageBus` backend (asyncio queues, pull-model `receive()`), `MessageDispatcher` for concurrent handler routing via `asyncio.TaskGroup`, `AgentMessenger` per-agent facade (auto-fills sender/timestamp/ID, deterministic direct-channel naming `@{sorted_a}:{sorted_b}`), and `DeliveryEnvelope` for delivery tracking. Loop prevention (§5.5) is implemented: `DelegationGuard` orchestrates five mechanisms (ancestry, depth, dedup, rate limit, circuit breaker) with `LoopPreventionConfig`. Hierarchical delegation is implemented via `DelegationService` with `HierarchyResolver` and `AuthorityValidator`. Task model extended with `parent_task_id` and `delegation_chain` fields. Meeting protocol (§5.7) is implemented with all 3 protocols (round-robin, position papers, structured phases) via `MeetingOrchestrator` in `communication/meeting/`. Conflict resolution (§5.6) is planned for later M4 work.
 
 ### 5.6 Conflict Resolution Protocol
 
@@ -650,7 +650,7 @@ conflict_resolution:
 
 Meetings (§5.1 Pattern 3) follow configurable protocols that determine how agents interact during structured multi-agent conversations. Different meeting types naturally suit different protocols. All protocols implement a `MeetingProtocol` protocol, making the system extensible — new protocols can be registered and selected per meeting type. Cost bounds are enforced by `duration_tokens` in meeting config (§5.4).
 
-> **MVP: Not in M3.** Meetings are an M4 feature. Round-Robin (Protocol 1) is the initial default.
+> **Current state (M4 complete):** All 3 meeting protocols are implemented in `communication/meeting/`: `RoundRobinProtocol`, `PositionPapersProtocol`, and `StructuredPhasesProtocol`. The `MeetingOrchestrator` runs meetings end-to-end with token budget enforcement via `TokenBudgetTracker`. All protocols implement the `MeetingProtocol` protocol interface.
 
 #### Protocol 1: Round-Robin Transcript
 
@@ -694,10 +694,10 @@ Meeting split into phases with targeted participation:
 
 ```yaml
 meeting_protocol: "structured_phases"
+auto_create_tasks: true              # action items become tasks (top-level, applies to any protocol)
 structured_phases:
   skip_discussion_if_no_conflicts: true
   max_discussion_tokens: 1000
-  auto_create_tasks: true          # action items become tasks
 ```
 
 - Cost-efficient — parallel input, discussion only when needed
@@ -2415,6 +2415,19 @@ ai-company/
 │       │   │   ├── models.py      # GuardCheckOutcome
 │       │   │   └── rate_limit.py  # DelegationRateLimiter (per-pair)
 │       │   ├── message.py          # Message model
+│       │   ├── meeting/             # Meeting protocol subsystem
+│       │   │   ├── __init__.py    # Package exports
+│       │   │   ├── _prompts.py    # LLM prompt templates for meeting phases
+│       │   │   ├── _token_tracker.py # TokenBudgetTracker for duration_tokens enforcement
+│       │   │   ├── config.py      # MeetingConfig, protocol-specific config models
+│       │   │   ├── enums.py       # MeetingProtocolType, MeetingPhase enums
+│       │   │   ├── errors.py      # Meeting error hierarchy
+│       │   │   ├── models.py      # MeetingRecord, AgendaItem, ActionItem, etc.
+│       │   │   ├── orchestrator.py # MeetingOrchestrator (runs meetings end-to-end)
+│       │   │   ├── position_papers.py # PositionPapersProtocol implementation
+│       │   │   ├── protocol.py    # MeetingProtocol protocol interface
+│       │   │   ├── round_robin.py # RoundRobinProtocol implementation
+│       │   │   └── structured_phases.py # StructuredPhasesProtocol implementation
 │       │   ├── messenger.py        # AgentMessenger per-agent facade
 │       │   └── subscription.py     # Subscription + DeliveryEnvelope models
 │       ├── memory/                  # Agent memory system (M5, stubs only)
@@ -2438,6 +2451,7 @@ ai-company/
 │       │   │   ├── correlation.py # CORRELATION_* constants
 │       │   │   ├── execution.py   # EXECUTION_* constants
 │       │   │   ├── git.py         # GIT_* constants
+│       │   │   ├── meeting.py    # MEETING_* constants
 │       │   │   ├── parallel.py    # PARALLEL_* constants
 │       │   │   ├── personality.py # PERSONALITY_* constants
 │       │   │   ├── prompt.py      # PROMPT_* constants

src/ai_company/communication/__init__.py

@@ -65,12 +65,43 @@
     check_ancestry,
     check_delegation_depth,
 )
+from ai_company.communication.meeting import (
+    ActionItem,
+    AgentCaller,
+    AgentResponse,
+    MeetingAgenda,
+    MeetingAgendaItem,
+    MeetingAgentError,
+    MeetingBudgetExhaustedError,
+    MeetingContribution,
+    MeetingError,
+    MeetingMinutes,
+    MeetingOrchestrator,
+    MeetingParticipantError,
+    MeetingPhase,
+    MeetingProtocol,
+    MeetingProtocolConfig,
+    MeetingProtocolNotFoundError,
+    MeetingProtocolType,
+    MeetingRecord,
+    MeetingStatus,
+    PositionPapersConfig,
+    PositionPapersProtocol,
+    RoundRobinConfig,
+    RoundRobinProtocol,
+    StructuredPhasesConfig,
+    StructuredPhasesProtocol,
+    TaskCreator,
+)
 from ai_company.communication.message import Attachment, Message, MessageMetadata
 from ai_company.communication.messenger import AgentMessenger
 from ai_company.communication.subscription import DeliveryEnvelope, Subscription
 
 __all__ = [
+    "ActionItem",
+    "AgentCaller",
     "AgentMessenger",
+    "AgentResponse",
     "Attachment",
     "AttachmentType",
     "AuthorityCheckResult",
@@ -109,6 +140,22 @@
     "HierarchyResolver",
     "InMemoryMessageBus",
     "LoopPreventionConfig",
+    "MeetingAgenda",
+    "MeetingAgendaItem",
+    "MeetingAgentError",
+    "MeetingBudgetExhaustedError",
+    "MeetingContribution",
+    "MeetingError",
+    "MeetingMinutes",
+    "MeetingOrchestrator",
+    "MeetingParticipantError",
+    "MeetingPhase",
+    "MeetingProtocol",
+    "MeetingProtocolConfig",
+    "MeetingProtocolNotFoundError",
+    "MeetingProtocolType",
+    "MeetingRecord",
+    "MeetingStatus",
     "MeetingTypeConfig",
     "MeetingsConfig",
     "Message",
@@ -125,8 +172,15 @@
     "MessageRetentionConfig",
     "MessageType",
     "NotSubscribedError",
+    "PositionPapersConfig",
+    "PositionPapersProtocol",
     "RateLimitConfig",
+    "RoundRobinConfig",
+    "RoundRobinProtocol",
+    "StructuredPhasesConfig",
+    "StructuredPhasesProtocol",
     "Subscription",
+    "TaskCreator",
     "check_ancestry",
     "check_delegation_depth",
 ]

src/ai_company/communication/config.py

@@ -9,6 +9,7 @@
     CommunicationPattern,
     MessageBusBackend,
 )
+from ai_company.communication.meeting.config import MeetingProtocolConfig
 from ai_company.core.types import (
     NotBlankStr,
     validate_unique_strings,
@@ -109,6 +110,10 @@ class MeetingTypeConfig(BaseModel):
         gt=0,
         description="Token budget for the meeting",
     )
+    protocol_config: MeetingProtocolConfig = Field(
+        default_factory=MeetingProtocolConfig,
+        description="Meeting protocol configuration",
+    )
 
     @model_validator(mode="after")
     def _validate_frequency_or_trigger(self) -> Self:

src/ai_company/communication/enums.py

@@ -17,6 +17,7 @@ class MessageType(StrEnum):
     DELEGATION = "delegation"
     STATUS_REPORT = "status_report"
     ESCALATION = "escalation"
+    MEETING_CONTRIBUTION = "meeting_contribution"
 
 
 class MessagePriority(StrEnum):

src/ai_company/communication/meeting/__init__.py

@@ -0,0 +1,79 @@
+"""Meeting protocol subsystem (DESIGN_SPEC Section 5.7).
+
+Provides pluggable meeting protocol strategies for structured
+multi-agent conversations:
+
+- **Round-Robin**: Sequential turns with full transcript context.
+- **Position Papers**: Parallel independent papers, then synthesis.
+- **Structured Phases**: Phased agenda with conditional discussion.
+"""
+
+from ai_company.communication.meeting.config import (
+    MeetingProtocolConfig,
+    PositionPapersConfig,
+    RoundRobinConfig,
+    StructuredPhasesConfig,
+)
+from ai_company.communication.meeting.enums import (
+    MeetingPhase,
+    MeetingProtocolType,
+    MeetingStatus,
+)
+from ai_company.communication.meeting.errors import (
+    MeetingAgentError,
+    MeetingBudgetExhaustedError,
+    MeetingError,
+    MeetingParticipantError,
+    MeetingProtocolNotFoundError,
+)
+from ai_company.communication.meeting.models import (
+    ActionItem,
+    AgentResponse,
+    MeetingAgenda,
+    MeetingAgendaItem,
+    MeetingContribution,
+    MeetingMinutes,
+    MeetingRecord,
+)
+from ai_company.communication.meeting.orchestrator import MeetingOrchestrator
+from ai_company.communication.meeting.position_papers import (
+    PositionPapersProtocol,
+)
+from ai_company.communication.meeting.protocol import (
+    AgentCaller,
+    MeetingProtocol,
+    TaskCreator,
+)
+from ai_company.communication.meeting.round_robin import RoundRobinProtocol
+from ai_company.communication.meeting.structured_phases import (
+    StructuredPhasesProtocol,
+)
+
+__all__ = [
+    "ActionItem",
+    "AgentCaller",
+    "AgentResponse",
+    "MeetingAgenda",
+    "MeetingAgendaItem",
+    "MeetingAgentError",
+    "MeetingBudgetExhaustedError",
+    "MeetingContribution",
+    "MeetingError",
+    "MeetingMinutes",
+    "MeetingOrchestrator",
+    "MeetingParticipantError",
+    "MeetingPhase",
+    "MeetingProtocol",
+    "MeetingProtocolConfig",
+    "MeetingProtocolNotFoundError",
+    "MeetingProtocolType",
+    "MeetingRecord",
+    "MeetingStatus",
+    "PositionPapersConfig",
+    "PositionPapersProtocol",
+    "RoundRobinConfig",
+    "RoundRobinProtocol",
+    "StructuredPhasesConfig",
+    "StructuredPhasesProtocol",
+    "TaskCreator",
+]

src/ai_company/communication/meeting/_prompts.py

@@ -0,0 +1,28 @@
+"""Shared prompt builders for meeting protocol implementations."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ai_company.communication.meeting.models import MeetingAgenda
+
+
+def build_agenda_prompt(agenda: MeetingAgenda) -> str:
+    """Build the initial agenda prompt text.
+
+    Args:
+        agenda: The meeting agenda to format.
+
+    Returns:
+        Formatted agenda text for use in agent prompts.
+    """
+    parts = [f"Meeting: {agenda.title}"]
+    if agenda.context:
+        parts.append(f"Context: {agenda.context}")
+    if agenda.items:
+        parts.append("Agenda items:")
+        for i, item in enumerate(agenda.items, 1):
+            entry = f"  {i}. {item.title}"
+            if item.description:
+                entry += f" — {item.description}"
+            parts.append(entry)
+    return "\n".join(parts)

src/ai_company/communication/meeting/_token_tracker.py

@@ -0,0 +1,38 @@
+"""Shared token budget tracker for meeting protocol implementations."""
+
+import dataclasses
+
+
+@dataclasses.dataclass
+class TokenTracker:
+    """Mutable token budget tracker scoped to a single meeting execution.
+
+    Attributes:
+        budget: Total token budget for the meeting.
+        input_tokens: Total prompt tokens consumed so far.
+        output_tokens: Total response tokens generated so far.
+    """
+
+    budget: int
+    input_tokens: int = 0
+    output_tokens: int = 0
+
+    @property
+    def used(self) -> int:
+        """Total tokens consumed so far."""
+        return self.input_tokens + self.output_tokens
+
+    @property
+    def remaining(self) -> int:
+        """Tokens remaining in the budget."""
+        return max(0, self.budget - self.used)
+
+    @property
+    def is_exhausted(self) -> bool:
+        """Whether the budget is fully consumed."""
+        return self.remaining == 0
+
+    def record(self, input_tokens: int, output_tokens: int) -> None:
+        """Record token usage from an agent call."""
+        self.input_tokens += input_tokens
+        self.output_tokens += output_tokens