Which OpenMAIC Action Types Block Until Completion? Complete Technical Guide

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 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 – 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 – 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.

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:

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, 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 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 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 references these distinctions when generating agent prompts to ensure AI-generated lessons respect timing constraints.

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