# Which OpenMAIC Action Types Block Until Completion? Complete Technical Guide

> Discover which OpenMAIC action types block until completion. This guide details the 19 synchronous actions in OpenMAIC, including speech synthesis, video playback, and more.

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

---

**OpenMAIC defines 19 synchronous action types—enumerated in the `SYNC_ACTIONS` constant in `packages/@openmaic/dsl/src/action.ts` (lines 66‑87)—that block the runtime until completion, including speech synthesis, video playback, all whiteboard drawing operations, discussions, and widget interactions.**

The THU-MAIC/OpenMAIC repository implements a deterministic lesson playback engine where certain operations must finish before the timeline advances. Understanding which **OpenMAIC action types block until completion** is essential for designing educational workflows that synchronize audio, visual, and interactive elements without race conditions.

## Synchronous vs Fire-and-Forget Action Categories

OpenMAIC divides actions into two execution categories that determine runtime behavior:

* **Fire-and-forget** – Actions like `spotlight` and `laser` execute immediately and do **not** block subsequent actions. These are suitable for visual cues that can overlap with other operations.
* **Synchronous** – Actions that require the runtime to **wait** for completion signals before proceeding to the next step. This ensures deterministic, step-by-step lesson progression critical for educational content sequencing.

The distinction ensures that media playback, whiteboard animations, and interactive discussions complete in their entirety before the next instruction begins.

## Complete List of Blocking Action Types in OpenMAIC

The `SYNC_ACTIONS` constant in [`packages/@openmaic/dsl/src/action.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/packages/@openmaic/dsl/src/action.ts#L66-L87) explicitly declares the following 19 action types as synchronous:

### Audio and Media Playback

* **`speech`** – Text-to-speech narration that blocks until the audio finishes playing.
* **`play_video`** – Video playback that pauses the timeline until the video completes.

### Whiteboard Canvas Operations

* **`wb_open`** – Opens the whiteboard canvas; blocks until the opening animation finishes.
* **`wb_draw_text`** – Renders text blocks; waits for the typing/rendering animation.
* **`wb_draw_shape`** – Draws rectangles, circles, or triangles; waits for drawing completion.
* **`wb_draw_chart`** – Renders bar, line, or pie charts; blocks until visualization completes.
* **`wb_draw_latex`** – Typesets mathematical formulas; waits for LaTeX rendering.
* **`wb_draw_table`** – Draws tabular data; blocks until table rendering finishes.
* **`wb_draw_line`** – Draws lines or arrows; waits for drawing animation.
* **`wb_draw_code`** – Types code blocks with syntax highlighting; blocks until the typing animation completes.
* **`wb_edit_code`** – Performs insert, delete, or replace operations on existing code blocks; waits for edit animations.
* **`wb_clear`** – Clears all whiteboard elements; blocks until the clear animation finishes.
* **`wb_delete`** – Removes specific elements by ID; waits for delete animation.
* **`wb_close`** – Closes the whiteboard canvas; blocks until the closing animation completes.

### Discussion and Widget Interactions

* **`discussion`** – Triggers round-table discussions; blocks until the discussion session ends.
* **`widget_highlight`** – Highlights elements inside widget iframes; waits for the highlighting effect to finish.
* **`widget_setState`** – Updates widget simulation variables; blocks until the state change settles.
* **`widget_annotation`** – Adds floating annotations to widget elements; waits for rendering completion.
* **`widget_reveal`** – Displays hidden widget content; blocks until the reveal animation finishes.

## Implementation Details and Source Code

The blocking semantic is enforced at multiple layers in the OpenMAIC architecture:

* **`packages/@openmaic/dsl/src/action.ts`** – Contains the source of truth for action categorization. Lines 66‑87 define the `SYNC_ACTIONS` array that the runtime consults to determine blocking behavior.
* **[`lib/workbench/run-courses.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/run-courses.ts)** – Implements the execution engine that schedules actions. When processing the lesson timeline, this module detects synchronous actions and pauses the event loop until receiving completion callbacks.
* **[`lib/orchestration/prompt-builder.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/prompt-builder.ts)** – Generates agent prompts while respecting the distinction between blocking and non-blocking operations, ensuring AI-generated lesson plans account for timing constraints.

Because these actions are **synchronous**, the playback engine guarantees that whiteboard animations complete, audio finishes playing, and widget states settle before advancing to subsequent instructions.

## Code Examples: Creating Blocking Actions

The following TypeScript examples demonstrate how to construct synchronous actions using the OpenMAIC DSL. The runtime will pause at each blocking action until it receives a completion signal.

```typescript
import { SpeechAction, WbDrawTextAction } from '@openmaic/dsl';

// Blocks until TTS audio finishes
const speech: SpeechAction = {
  id: 's1',
  type: 'speech',
  text: 'Welcome to the lesson on quantum mechanics.',
  voice: 'en-US-Standard-B',
  speed: 1.0,
};

// Blocks until text rendering animation completes
const drawText: WbDrawTextAction = {
  id: 'wt1',
  type: 'wb_draw_text',
  content: 'Key concept: Superposition',
  x: 200,
  y: 150,
  width: 400,
  height: 80,
  fontSize: 24,
  color: '#0066CC',
};

const actions = [speech, drawText]; // Executes sequentially with blocking

```

You can interleave fire-and-forget actions with synchronous actions to create overlapping effects without breaking the deterministic flow:

```typescript
import { SpotlightAction } from '@openmaic/dsl';

const spotlight: SpotlightAction = {
  id: 'sp1',
  type: 'spotlight',
  elementId: 'slide-title',
};

// Spotlight fires immediately, then speech blocks, then drawText blocks
const timeline = [spotlight, speech, drawText];

```

## Summary

* OpenMAIC explicitly defines **19 synchronous action types** in the `SYNC_ACTIONS` constant at `packages/@openmaic/dsl/src/action.ts` (lines 66‑87).
* Blocking actions include **all whiteboard operations** (`wb_*`), **speech synthesis**, **video playback**, **discussions**, and **widget interactions**.
* The runtime enforces blocking semantics in [`lib/workbench/run-courses.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/run-courses.ts), ensuring deterministic lesson progression.
* **Fire-and-forget** actions like `spotlight` and `laser` can execute concurrently with blocking actions but do not pause the timeline.
* Synchronous actions are essential for timing-critical educational content where completion states must be guaranteed before proceeding.

## Frequently Asked Questions

### What is the difference between synchronous and fire-and-forget actions in OpenMAIC?

**Synchronous actions** block the lesson timeline until they report completion, ensuring deterministic sequencing for operations like text-to-speech or whiteboard animations. **Fire-and-forget actions** execute immediately without blocking, allowing overlapping effects such as spotlight highlights or laser pointers to run concurrently with other operations.

### How can I identify which action types are synchronous in the source code?

According to the OpenMAIC source code, the `SYNC_ACTIONS` constant array defined at lines 66‑87 in `packages/@openmaic/dsl/src/action.ts` serves as the authoritative registry of all blocking action types. Any action type string included in this array will trigger blocking behavior in the runtime.

### Can I combine blocking and non-blocking actions in the same lesson sequence?

Yes. The runtime in [`lib/workbench/run-courses.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/run-courses.ts) processes mixed sequences by executing fire-and-forget actions immediately while pausing the timeline for each synchronous action until it receives a completion signal. This allows you to trigger immediate visual cues (like spotlights) before or during longer blocking operations (like video playback).

### Where does the runtime enforce the blocking behavior for these action types?

The execution logic in [`lib/workbench/run-courses.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/run-courses.ts) schedules actions and implements the blocking semantics by awaiting completion promises for any action type listed in `SYNC_ACTIONS`. Additionally, [`lib/orchestration/prompt-builder.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/prompt-builder.ts) references these distinctions when generating agent prompts to ensure AI-generated lessons respect timing constraints.