Understanding the Preflight Protocol in OpenMontage: Capability Verification Explained

The Preflight Protocol in OpenMontage is a mandatory, side-effect-free validation phase that executes before any tool or workflow to discover and verify runtime capabilities, required providers, and available credentials.

OpenMontage uses this protocol to prevent costly execution failures by validating the entire execution environment upfront. Before any video processing begins, the system performs a comprehensive audit of what resources are actually available versus what the workflow requires. Understanding how the Preflight Protocol verifies capabilities allows developers to build more resilient tools and autonomous agents that fail fast with clear diagnostics.

What Is the Preflight Protocol in OpenMontage?

The Preflight Protocol serves as a mandatory gate that every tool must pass through before entering the execution phase. According to the source code in tools/base_tool.py, this protocol is explicitly designed as a "Preflight check without side effects" that returns a description of what the tool would accomplish without performing any real work.

This validation system addresses three critical questions before resource-intensive media generation starts:

• Which runtimes are available? (HyperFrames, Remotion, FFmpeg)
• Which external providers are accessible? (ElevenLabs, HeyGen, local voice generators)
• Are the necessary credentials present? (API keys, authentication tokens)

By answering these questions upfront, the Preflight Protocol in OpenMontage ensures that missing capabilities surface as user-friendly warnings rather than runtime exceptions during video rendering.

How the Preflight Protocol Verifies Capabilities

The verification process follows a strict five-stage pipeline implemented across the core tooling infrastructure.

Tool-Level Preflight Checks

Every tool in the system inherits from BaseTool, which defines the abstract preflight() method at line 400 of tools/base_tool.py. Concrete tool implementations override this method to declare their specific requirements and expected outputs. When invoked, preflight() returns a dictionary describing the intended action—for example, {'action': 'stitch', 'clips': 5, 'output': 'stitched.mp4'}—without modifying any state or consuming API quotas.

Runtime Availability Discovery

The ToolRegistry queries the environment to report which media processing engines are actually installed and functional. As documented in skills/core/hyperframes.md at line 193, the protocol specifically checks for runtimes like HyperFrames, Remotion, and FFmpeg. This step prevents scenarios where a tool attempts to invoke ffmpeg commands that would fail due to missing binaries.

Provider Menu Validation

The system constructs a mandatory Provider Menu that catalogs all external services required for the workflow. According to the comment at line 321 of tools/tool_registry.py, this menu is "Mandatory at Preflight" and cross-referenced against the requirements defined in AGENT_GUIDE.md (line 263). If a workflow requires ElevenLabs for voice generation but the provider is not configured, the preflight flags this dependency gap immediately.

Credential Discovery and Authentication

The protocol executes authentication status commands—typically npx hyperframes auth status—to verify which API keys are present in the environment. The website-to-video skill documentation at line 39 demonstrates this pattern, showing how the system checks sign-in status before proceeding. If credentials are missing, the preflight aborts and prompts the user to authenticate or switch to offline engines.

Generating the Capability Summary

After completing all checks, the system invokes registry.provider_menu_summary() to produce a human-readable report. The animation pipeline's proposal director, documented at line 135 of skills/pipelines/animation/proposal-director.md, demonstrates this final step. This summary displays exactly what will happen and what is missing, allowing users to make informed decisions before committing compute resources.

Implementing Preflight Checks in Python

Developers can programmatically invoke the Preflight Protocol in OpenMontage to validate capabilities before executing custom workflows. The following example demonstrates how to inherit from BaseTool and leverage the ToolRegistry for comprehensive capability verification:

from tools.base_tool import BaseTool
from tools.tool_registry import ToolRegistry

# Example: a custom video-stitch tool that inherits the base preflight behavior

class VideoStitchTool(BaseTool):
    def run(self, clips):
        # Real implementation goes here …

        pass

# Instantiate the registry (holds information about runtimes & providers)

registry = ToolRegistry()

# 1️⃣ Run the tool’s preflight check

tool = VideoStitchTool()
preflight_report = tool.preflight()          # → dict describing what would happen

# 2️⃣ Ask the registry which runtimes are actually available

runtime_status = registry.runtime_status()   # e.g. {'hyperframes': True, 'ffmpeg': True}

# 3️⃣ Get a provider-menu summary (mandatory at preflight)

provider_summary = registry.provider_menu_summary()  # Human-readable list

print("Preflight report:", preflight_report)
print("Runtimes:", runtime_status)
print("Available providers:", provider_summary)

Executing this script produces side-effect-free output similar to:

Preflight report: {'action': 'stitch', 'clips': 5, 'output': 'stitched.mp4'}
Runtimes: {'hyperframes': True, 'remotion': False, 'ffmpeg': True}
Available providers: ElevenLabs ✓, image_selector ✓, video_selector ✗ (no API keys)

This output confirms exactly which operations can proceed and which dependencies require resolution before the actual video processing begins.

Summary

• The Preflight Protocol in OpenMontage is mandatory and executes before any tool runs to verify capabilities without side effects.
• All tools inherit the preflight() method from BaseTool at line 400 of tools/base_tool.py to declare their requirements.
• The ToolRegistry validates runtime availability (HyperFrames, FFmpeg) and enforces the mandatory Provider Menu check at line 321 of tools/tool_registry.py.
• Credential discovery uses authentication status commands to verify API keys before costly remote API calls occur.
• The protocol generates a human-readable summary via provider_menu_summary() so users can see exactly what is available and what is missing before execution.

Frequently Asked Questions

What happens if the Preflight Protocol detects missing credentials?

If the protocol discovers missing API keys or expired authentication tokens—typically via commands like npx hyperframes auth status—it aborts the preflight step and surfaces a clear error message. As shown in the website-to-video skill documentation, the system prompts the user to sign in or explicitly continue with offline-only engines that do not require remote credentials.

Is the Preflight Protocol optional for custom tools?

No, the Preflight Protocol is mandatory for all tools in the OpenMontage ecosystem. The AGENT_GUIDE.md at line 263 explicitly requires the Provider Menu validation at preflight time, and the ToolRegistry enforces these checks regardless of whether the tool uses local or remote resources. Custom tools must inherit from BaseTool and implement the preflight() method to participate in this validation.

How does preflight verification differ from actual tool execution?

The preflight() method is strictly side-effect-free—it describes what would happen without performing any real work, consuming API quotas, or writing files. The actual run() method performs the resource-intensive operations. This separation allows developers to validate entire workflow chains cheaply before committing to expensive video rendering or external API calls.

Which specific runtimes does the preflight check verify?

According to skills/core/hyperframes.md at line 193, the protocol specifically reports on the availability of HyperFrames, Remotion, and FFmpeg runtimes. The ToolRegistry checks for installed binaries and executable paths, ensuring that tools do not attempt to invoke commands that would fail due to missing system dependencies.

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