How OpenMontage Ensures Tools Write Outputs to the Correct Project Workspace Paths

OpenMontage enforces a mandatory workspace_path property in every tool's input schema and validates it through the centralized _require_workspace helper, which resolves absolute paths and raises ValueError on missing inputs to guarantee all artifacts are written to the designated project directory.

The calesthio/OpenMontage repository implements a strict workspace contract to ensure reproducible builds and prevent artifacts from leaking outside project boundaries. By treating the workspace directory as the single source of truth for all tool-generated outputs, OpenMontage eliminates path ambiguity through schema validation, canonical path resolution, and runtime safety checks.

Mandatory Workspace Declaration in Tool Schemas

Every tool in OpenMontage declares its workspace dependency explicitly through a declarative input schema. This contract forces the orchestrating pipeline to supply a concrete directory before any operation begins.

In tools/video/hyperframes_compose.py, the tool defines workspace_path as a required property in its input schema (lines 45-52). This schema-level requirement ensures that the pipeline cannot invoke the tool without explicitly specifying where outputs should be written. The validation occurs before execution, preventing any ambiguity about target locations for HTML, CSS, assets, or rendered video files.

Canonical Path Resolution via _require_workspace

Once the pipeline supplies the workspace_path string, OpenMontage centralizes all path handling through the private helper _require_workspace. This method serves as the single source of truth for workspace directory resolution across all internal operations.

Located at lines 988-992 in hyperframes_compose.py, the helper extracts the raw input, validates its presence, and immediately resolves it to an absolute Path object:

def _require_workspace(inputs: dict[str, Any]) -> Path:
    raw = inputs.get("workspace_path")
    if not raw:
        raise ValueError("workspace_path is required for this operation")
    return Path(raw).resolve()  # ← canonical absolute path

If the property is missing, the helper raises a clear ValueError, aborting the tool early. By using .resolve(), the method guarantees a canonical absolute path that lives inside the project tree, eliminating relative path traversal issues before any file operations occur.

Enforcing Workspace Boundaries at Runtime

All internal file operations invoke _require_workspace to obtain the validated directory before reading or writing. For example, in the _scaffold method (line 339), the tool retrieves the workspace and immediately creates the target structure:

def _scaffold(self, inputs: dict[str, Any]) -> ToolResult:
    workspace = self._require_workspace(inputs)   # ← same path everywhere

    workspace.mkdir(parents=True, exist_ok=True)  # create the target dir

    (workspace / "assets").mkdir(exist_ok=True)   # copy assets inside it

    (workspace / "index.html").write_text(html)   # write the HTML output

To prevent accidental escapes from the project boundary, OpenMontage implements the _is_inside helper (lines 1010-1014). This safety net verifies that any staged assets remain within the workspace directory:

def _is_inside(path: Path, root: Path) -> bool:
    try:
        path.resolve().relative_to(root.resolve())
        return True
    except ValueError:
        return False

The runtime calls this check before copying files, ensuring that symbolic links or malicious relative paths cannot redirect outputs outside the designated project workspace.

Explicit Side-Effect Documentation

Beyond runtime enforcement, OpenMontage requires tools to declare their intended side effects explicitly. The side_effects attribute (lines 229-232 in hyperframes_compose.py) documents exactly which files will be written to the workspace_path, including copied assets and generated MP4 files.

This declaration enables the runtime to audit operations before execution and supports provenance tracking, giving downstream tooling visibility into exactly which paths will be modified during the tool's lifecycle.

Implementation Across the Codebase

While tools/video/hyperframes_compose.py implements the primary workspace contract, the pattern propagates through related modules:

• tools/video/video_compose.py: Calls hyperframes_compose and forwards the same workspace_path, demonstrating end-to-end propagation of the workspace contract.
• lib/paths.py (if present): Centralizes path utilities used across the codebase for project-relative directory handling.

Summary

• Schema Enforcement: Tools declare workspace_path as required in their input schemas, preventing invocation without a designated output directory.
• Centralized Validation: The _require_workspace helper is the sole authority for converting input strings to absolute Path objects, raising ValueError immediately if the path is missing.
• Canonical Resolution: All paths are resolved using .resolve() to eliminate relative traversal and ensure project-tree containment.
• Boundary Safety: The _is_inside helper verifies that all copied assets remain within the workspace directory, preventing path escape vulnerabilities.
• Observable Contracts: The side_effects attribute explicitly lists all files written to the workspace, enabling runtime auditing and provenance tracking.

Frequently Asked Questions

What happens if a tool receives inputs without a workspace_path?

OpenMontage aborts execution immediately. The _require_workspace helper checks for the presence of workspace_path in the input dictionary and raises a ValueError with the message "workspace_path is required for this operation" before any file operations occur (lines 988-992 in hyperframes_compose.py).

How does OpenMontage prevent tools from writing files outside the project workspace?

The framework uses a combination of canonical path resolution and boundary checking. First, _require_workspace resolves the path to an absolute canonical form using Path.resolve(). Second, when staging assets, the _is_inside helper verifies that the resolved path is actually contained within the workspace directory by attempting a relative_to operation (lines 1010-1014).

Why does OpenMontage require absolute resolved paths instead of relative paths?

Absolute resolved paths eliminate ambiguity from symbolic links, parent directory references (..), and varying working directories. By calling .resolve() in _require_workspace, OpenMontage guarantees that all downstream operations reference the same canonical location on the filesystem, preventing race conditions and path traversal vulnerabilities during complex build pipelines.

Where is the workspace contract formally defined for external tool consumers?

The contract is defined in the tool's JSON input schema within the Python source (lines 45-52 of hyperframes_compose.py), which specifies workspace_path as a required string property. Additionally, formal schema files such as schemas/tools/hyperframes_workspace.schema.json (if present) provide external validation contracts for pipeline orchestrators integrating with OpenMontage tools.

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