What Events Are Streamed by the Director Graph in OpenMAIC?

The director graph in OpenMAIC streams two primary event types—directorState and directorToolTrace—that transmit real‑time updates about turn progression, agent responses, tool invocations, and session lifecycle signals.

The director graph serves as the central orchestration node for the "director" role within the THU-MAIC/OpenMAIC framework. Located in lib/orchestration/director-graph.ts, this component manages multi‑turn conversations by emitting structured events that downstream consumers use to render UI updates, log execution traces, and trigger state transitions. Understanding what events are streamed by the director graph is essential for debugging agent behavior and building reactive interfaces.

Core Event Types Streamed by the Director Graph

During an active director turn, the graph continuously emits events that fall into two distinct categories: state snapshots and execution traces.

directorState Events

The directorState event transmits a comprehensive snapshot of the current turn's context. According to the test suite in tests/lib/chat/pi/route-model-thinking.test.ts, these events contain:

• turnCount – The current turn number in the conversation sequence
• agentResponses – An ordered array of responses generated by subordinate agents
• whiteboardLedger – Shared state or context passed between agents
• endReason – Termination cause when the turn concludes
• type – State classification signals such as cue_user or soft_closing

These state updates enable the UI layer to display progress indicators and manage conversation flow without polling the underlying graph.

directorToolTrace Events

Parallel to state updates, the graph emits directorToolTrace events that provide an immutable chronological record of every tool invocation the director performs. As validated in tests/lib/chat/pi/route-model-thinking.test.ts, each trace entry includes:

• Tool name – The identifier of the invoked function or capability
• Arguments – The parameters passed to the tool
• Results – The return values or errors produced by execution

This event stream is critical for debugging, audit trails, and replaying director reasoning paths.

Event Structure and Implementation Details

The streaming implementation resides in lib/orchestration/director-graph.ts, where the graph implements an event emitter pattern. Consumers subscribe to specific channels to receive granular updates without blocking the main execution loop.

// Example: Subscribing to director events in a downstream consumer
directorGraph.on('directorState', (state) => {
  console.log(`Turn ${state.turnCount}: ${state.agentResponses.length} responses`);
  if (state.type === 'soft_closing') {
    prepareSessionShutdown();
  }
});

directorGraph.on('directorToolTrace', (trace) => {
  trace.forEach((call) => {
    console.log(`Tool ${call.name} executed with args:`, call.args);
  });
});

The events are emitted asynchronously during graph traversal, allowing real‑time monitoring of long‑running director operations.

Cue Signals and Lifecycle Events

Beyond generic state updates, the directorState event encodes specific control signals that drive interaction patterns. These cues are tested in tests/lib/chat/pi/route-cue-user.test.ts.

User Input Cues (cue_user)

When the director requires human clarification or additional input, the cue_user signal appears in the directorState.type field. This event pauses automated processing and prompts the UI to render input controls, ensuring synchronous handoff between autonomous and human‑in‑the‑loop modes.

Session Termination (soft_closing)

The soft_closing signal indicates the director is preparing to conclude the session gracefully. Downstream components monitoring directorState events can use this signal to trigger cleanup routines, save conversation history, or display termination confirmations before the graph halts.

Summary

• The director graph emits directorState events containing turn metadata (turnCount, agentResponses, whiteboardLedger) and lifecycle signals (cue_user, soft_closing).
• directorToolTrace events provide immutable execution logs of every tool call, including names, arguments, and results.
• Both event streams are implemented in lib/orchestration/director-graph.ts and validated in tests/lib/chat/pi/route-model-thinking.test.ts.
• Cue signals embedded within directorState enable real‑time coordination between autonomous director behavior and user interface components.

Frequently Asked Questions

What is the difference between directorState and directorToolTrace events?

directorState captures the semantic state of the conversation turn, including agent responses and session metadata, while directorToolTrace records the operational execution of tools. The former drives UI state, whereas the latter serves debugging and audit purposes.

How does the director graph signal that it needs user input?

The graph emits a directorState event with type: 'cue_user', as verified in tests/lib/chat/pi/route-cue-user.test.ts. Downstream listeners detect this signal and render appropriate input interfaces to pause autonomous execution.

Where is the director graph implementation located in the OpenMAIC repository?

The core streaming logic resides in lib/orchestration/director-graph.ts within the THU-MAIC/OpenMAIC repository. Test coverage demonstrating event structures appears in tests/lib/chat/pi/route-model-thinking.test.ts and route-cue-user.test.ts.

Can downstream components react to specific tool calls in real time?

Yes. By subscribing to the directorToolTrace event stream, components receive tool call notifications as they occur during graph execution, enabling real‑time logging, permission checks, or intermediate result processing without waiting for the full turn to complete.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}