# What Events Are Streamed by the Director Graph in OpenMAIC?

> Explore director graph events in OpenMAIC. Learn about directorState and directorToolTrace for real-time updates on turn progression, agent responses, tool invocations, and session lifecycle signals.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: internals
- Published: 2026-09-09

---

**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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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.

```typescript
// 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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/director-graph.ts) and validated in [`tests/lib/chat/pi/route-model-thinking.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/lib/chat/pi/route-model-thinking.test.ts) and [`route-cue-user.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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.