Protocol Version Schema for Preview-Bundle/v1 and Preview-Trajectory/v1 in CLI-Anything

CLI-Anything uses two protocol version identifiers—"preview-bundle/v1" for bundle manifests and "preview-trajectory/v1" for trajectory files—following a strict "<type>/v<major>" schema defined in each agent harness's preview_bundle.py utility.

The CLI-Anything repository provides agent harnesses for multiple software applications that generate preview bundles and live trajectories. Understanding the protocol version schema ensures your integrations correctly interpret manifest files and trajectory data across different versions of the toolkit.

Protocol Version Schema Definition

CLI-Anything implements a simple, extensible versioning pattern for its preview system. The schema follows the format:

"<type>/v<major>"

Where:

• <type> specifies the entity type, either preview-bundle or preview-trajectory.
• v<major> indicates the major version number, currently v1 for both protocols.

When maintainers release breaking changes, the version increments to v2 while preserving the same structural pattern (e.g., "preview-bundle/v2").

Where Protocol Versions Are Defined

The protocol version constants reside in each agent harness's preview_bundle.py utility module. All harnesses—including FreeCAD, Blender, Shotcut, RenderDoc, and OpenScreen—maintain identical definitions in their respective paths:

• freecad/agent-harness/cli_anything/freecad/utils/preview_bundle.py
• blender/agent-harness/cli_anything/blender/utils/preview_bundle.py
• shotcut/agent-harness/cli_anything/shotcut/utils/preview_bundle.py
• renderdoc/agent-harness/cli_anything/renderdoc/utils/preview_bundle.py
• openscreen/agent-harness/cli_anything/openscreen/utils/preview_bundle.py
• cli-anything-plugin/preview_bundle.py

Each file contains these constant definitions:

PROTOCOL_VERSION = "preview-bundle/v1"
TRAJECTORY_PROTOCOL_VERSION = "preview-trajectory/v1"

How Protocol Versions Are Used

The protocol version strings tag generated artifacts to ensure consuming applications can parse the data correctly.

In Preview Bundle Manifests

When finalizing a preview bundle, the finalize_bundle function writes PROTOCOL_VERSION to the manifest.json file under the protocol_version key. This occurs in .../utils/preview_bundle.py within each harness.

from cli_anything.freecad.utils.preview_bundle import prepare_bundle, finalize_bundle

# Initialize a new preview bundle

bundle = prepare_bundle(
    software="freecad",
    recipe="curiosity-rover",
    bundle_kind="preview",
    source_fingerprint="sha256:abc123",
)

# Complete the bundle and generate manifest

manifest = finalize_bundle(
    bundle_dir=bundle["bundle_dir"],
    bundle_id=bundle["bundle_id"],
    bundle_kind="preview",
    software="freecad",
    recipe="curiosity-rover",
    source={"project_fingerprint": "sha256:abc123"},
    artifacts=[],
    summary={"summary": "Automated preview generation"},
    cache_key=bundle["cache_key"],
    generator={"command": "/cli-anything freecad"},
)

# The manifest contains the protocol version

print(manifest["protocol_version"])  # Output: preview-bundle/v1

In Live Trajectory Files

For live trajectory tracking, the append_live_trajectory function records TRAJECTORY_PROTOCOL_VERSION in the trajectory.json file. This allows the CLI-Anything plugin to distinguish trajectory formats across different software agents.

from cli_anything.freecad.utils.preview_bundle import append_live_trajectory

# Update the live trajectory with a new step

trajectory = append_live_trajectory(
    session_dir="~/.cli-anything/previews/freecad/curiosity-rover",
    software="freecad",
    recipe="curiosity-rover",
    bundle_manifest=manifest,
    publish_reason="preview",
    project_path="/path/to/project",
)

# Verify the trajectory protocol version

print(trajectory["protocol_version"])  # Output: preview-trajectory/v1

Versioning Strategy and Future Compatibility

The current protocol version schema uses v1 for both bundle and trajectory protocols. When CLI-Anything introduces breaking changes—such as modified manifest structures or new required fields—the constants update to v2 following the same "<type>/v<major>" pattern.

This approach ensures backward compatibility: older bundles remain parseable by checking their protocol_version field, while newer implementations can gate features based on the version string.

Summary

• CLI-Anything defines two protocol version constants: "preview-bundle/v1" and "preview-trajectory/v1".
• The schema follows "<type>/v<major>", where type identifies the data format and v<major> tracks breaking changes.
• PROTOCOL_VERSION is written to manifest.json by finalize_bundle in each agent harness's preview_bundle.py.
• TRAJECTORY_PROTOCOL_VERSION is written to trajectory.json by append_live_trajectory.
• All software harnesses (FreeCAD, Blender, Shotcut, RenderDoc, OpenScreen) share identical protocol version definitions.

Frequently Asked Questions

What is the exact format of the protocol version schema?

The protocol version schema follows "<type>/v<major>". For example, "preview-bundle/v1" indicates a preview bundle at major version 1, while "preview-trajectory/v1" indicates a trajectory file at major version 1. This pattern remains consistent across all CLI-Anything agent harnesses.

Where is the protocol version stored in preview bundles?

The protocol version is stored in the bundle's manifest.json file under the key protocol_version. The finalize_bundle function in .../utils/preview_bundle.py populates this field using the PROTOCOL_VERSION constant ("preview-bundle/v1").

How does CLI-Anything handle protocol version updates?

When breaking changes occur, the maintainers increment the major version number in the constants (e.g., from v1 to v2). The schema pattern "<type>/v<major>" remains unchanged, allowing downstream tools to parse the version string consistently while detecting format differences via the version number.

Are protocol versions consistent across different software harnesses?

Yes. All agent harnesses—including FreeCAD, Blender, Shotcut, RenderDoc, and OpenScreen—use identical protocol version strings. Each harness's preview_bundle.py file defines PROTOCOL_VERSION = "preview-bundle/v1" and TRAJECTORY_PROTOCOL_VERSION = "preview-trajectory/v1", ensuring cross-platform compatibility.

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