episode_clone

Default model descriptor

{
  "name": "episode_clone",
  "title": "Clone an episode",
  "description": "Creates a clean draft branch from an existing top-level episode: a separate version for comparison or a workshop reset that the user explicitly wants. The clone copies that one episode's source-backed segments, timeline music, overlays, title/copy, aspect ratio, caption setting, and project, but it does not copy rendered media, publish state, origin recording ownership, or revision history. A new reel from Project sources is one episode_create with ordered source ranges, and an in-place change to the current draft is an episode_edit; a clone is neither.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "episode_id": {
        "type": "string",
        "description": "Top-level episode public ID to branch from. A recording id alias (src_...) resolves to that recording's episode-of-one."
      },
      "title": {
        "type": "string",
        "description": "Optional title for the clone. Defaults to 'Copy of <source title>'."
      },
      "description": {
        "type": "string",
        "description": "Optional description for the clone. Defaults to the source episode's displayed description."
      },
      "idempotency_key": {
        "type": "string",
        "description": "Caller-stable key for safe retry of the same clone request."
      }
    },
    "required": [
      "episode_id",
      "idempotency_key"
    ],
    "additionalProperties": false
  },
  "annotations": {
    "title": "Clone an episode",
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "securitySchemes": [
    {
      "type": "noauth"
    }
  ],
  "_meta": {
    "securitySchemes": [
      {
        "type": "noauth"
      }
    ],
    "ui": {
      "visibility": [
        "model",
        "app"
      ]
    },
    "openai/widgetAccessible": true
  }
}

App descriptor

{
  "name": "episode_clone",
  "title": "Clone an episode",
  "description": "Creates a clean draft branch from an existing top-level episode: a separate version for comparison or a workshop reset that the user explicitly wants. The clone copies that one episode's source-backed segments, timeline music, overlays, title/copy, aspect ratio, caption setting, and project, but it does not copy rendered media, publish state, origin recording ownership, or revision history. A new reel from Project sources is one episode_create with ordered source ranges, and an in-place change to the current draft is an episode_edit; a clone is neither.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "episode_id": {
        "type": "string",
        "description": "Top-level episode public ID to branch from. A recording id alias (src_...) resolves to that recording's episode-of-one."
      },
      "title": {
        "type": "string",
        "description": "Optional title for the clone. Defaults to 'Copy of <source title>'."
      },
      "description": {
        "type": "string",
        "description": "Optional description for the clone. Defaults to the source episode's displayed description."
      },
      "idempotency_key": {
        "type": "string",
        "description": "Caller-stable key for safe retry of the same clone request."
      }
    },
    "required": [
      "episode_id",
      "idempotency_key"
    ],
    "additionalProperties": false
  },
  "annotations": {
    "title": "Clone an episode",
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "securitySchemes": [
    {
      "type": "noauth"
    }
  ],
  "_meta": {
    "securitySchemes": [
      {
        "type": "noauth"
      }
    ],
    "ui": {
      "visibility": [
        "model",
        "app"
      ]
    },
    "openai/widgetAccessible": true
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "episode_id": {
        "type": "string",
        "description": "New clone episode public ID."
      },
      "source_episode_id": {
        "type": "string",
        "description": "Episode public ID the clone branched from."
      },
      "cloned_from_episode_id": {
        "type": "string",
        "description": "Alias for source_episode_id for lineage displays."
      },
      "cloned_from_revision": {
        "type": "integer",
        "description": "Source episode revision captured by the clone."
      },
      "duration_seconds": {
        "type": "number",
        "description": "Kept play length in seconds."
      },
      "revision": {
        "type": "integer",
        "description": "Durable revision counter, always 1 for a fresh clone."
      },
      "segments": {
        "type": "array",
        "description": "The cloned segment manifest (index, source_id, source_range, episode_range, boundary)."
      },
      "edge_warnings": {
        "type": "array",
        "description": "Always present. Non-mutating warnings for cloned cut edges that land strictly inside transcript words.",
        "items": {
          "type": "object",
          "properties": {
            "segment_index": {
              "type": "integer"
            },
            "edge": {
              "type": "string",
              "enum": [
                "start",
                "end"
              ]
            },
            "at_seconds": {
              "type": "number",
              "description": "Recording source time for the flagged edge. This legacy field name is not Episode time."
            },
            "source_id": {
              "type": "string",
              "description": "Recording containing the flagged source edge."
            },
            "occurrence_id": {
              "type": "string",
              "description": "Exact created-target occurrence containing this edge, when mapped."
            },
            "episode_seconds": {
              "type": "number",
              "description": "Exact flagged point on the created target's Episode clock, usable directly as an episode_zoom edge; occurrence_id identifies its source side."
            },
            "word": {
              "type": "string"
            },
            "word_range_source": {
              "type": "array",
              "items": {
                "type": "number"
              },
              "minItems": 2,
              "maxItems": 2
            }
          }
        }
      },
      "status": {
        "type": "string",
        "description": "Always draft — cloned but not rendered."
      },
      "workspace_url": {
        "type": "string",
        "description": "Same-origin path that opens the new clone in the composite editor."
      },
      "already_applied": {
        "type": "boolean",
        "description": "true when this idempotency_key already created the same clone and the existing clone was returned."
      },
      "next_action": {
        "type": "object",
        "description": "Suggested next tool call: episode_edit on the clone at its current revision."
      },
      "blockers": {
        "type": "array",
        "items": {
          "type": "object"
        }
      },
      "duration": {
        "type": "number",
        "description": "Clone play length in seconds; the same value as duration_seconds."
      },
      "derived": {
        "type": "boolean",
        "description": "True when the clone is a derived Clip filed under a parent Episode; false for a clone of a top-level Episode."
      },
      "block_segments": {
        "type": "array",
        "description": "Template-backed segments carried by the clone.",
        "items": {
          "type": "object",
          "properties": {
            "position": {
              "type": "integer"
            },
            "template": {
              "type": "string"
            },
            "source_id": {
              "type": "string"
            },
            "status": {
              "type": "string",
              "enum": [
                "ready",
                "preparing",
                "failed"
              ],
              "description": "Whether the template-backed Recording is already renderable or still baking."
            }
          }
        }
      },
      "identity_plan": {
        "type": [
          "object",
          "null"
        ],
        "description": "Frozen identity plan carried from the source Episode; null when only identity warnings or row mappings were carried."
      },
      "identity_layers": {
        "type": "array",
        "description": "Resolved Signature layers of the carried identity plan, such as opener, cut style and outro."
      },
      "identity_segments": {
        "type": "array",
        "description": "Identity segment rows with role, final_position and segment_id."
      },
      "identity_warnings": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Identity warnings carried from the source Episode."
      },
      "request_row_map": {
        "type": "array",
        "description": "Mapping from the source Episode's requested rows to composition positions, including segment_id."
      }
    },
    "required": [],
    "additionalProperties": false
  }
}

Live Workspace descriptor

{
  "name": "episode_clone",
  "title": "Clone an episode",
  "description": "Creates a clean draft branch from an existing top-level episode: a separate version for comparison or a workshop reset that the user explicitly wants. The clone copies that one episode's source-backed segments, timeline music, overlays, title/copy, aspect ratio, caption setting, and project, but it does not copy rendered media, publish state, origin recording ownership, or revision history. A new reel from Project sources is one episode_create with ordered source ranges, and an in-place change to the current draft is an episode_edit; a clone is neither.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "episode_id": {
        "type": "string",
        "description": "Top-level episode public ID to branch from. A recording id alias (src_...) resolves to that recording's episode-of-one."
      },
      "title": {
        "type": "string",
        "description": "Optional title for the clone. Defaults to 'Copy of <source title>'."
      },
      "description": {
        "type": "string",
        "description": "Optional description for the clone. Defaults to the source episode's displayed description."
      },
      "idempotency_key": {
        "type": "string",
        "description": "Caller-stable key for safe retry of the same clone request."
      }
    },
    "required": [
      "episode_id",
      "idempotency_key"
    ],
    "additionalProperties": false
  },
  "annotations": {
    "title": "Clone an episode",
    "readOnlyHint": false,
    "destructiveHint": false,
    "idempotentHint": true,
    "openWorldHint": false
  },
  "securitySchemes": [
    {
      "type": "noauth"
    }
  ],
  "_meta": {
    "securitySchemes": [
      {
        "type": "noauth"
      }
    ]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "episode_id": {
        "type": "string",
        "description": "New clone episode public ID."
      },
      "source_episode_id": {
        "type": "string",
        "description": "Episode public ID the clone branched from."
      },
      "cloned_from_episode_id": {
        "type": "string",
        "description": "Alias for source_episode_id for lineage displays."
      },
      "cloned_from_revision": {
        "type": "integer",
        "description": "Source episode revision captured by the clone."
      },
      "duration_seconds": {
        "type": "number",
        "description": "Kept play length in seconds."
      },
      "revision": {
        "type": "integer",
        "description": "Durable revision counter, always 1 for a fresh clone."
      },
      "segments": {
        "type": "array",
        "description": "The cloned segment manifest (index, source_id, source_range, episode_range, boundary)."
      },
      "edge_warnings": {
        "type": "array",
        "description": "Always present. Non-mutating warnings for cloned cut edges that land strictly inside transcript words.",
        "items": {
          "type": "object",
          "properties": {
            "segment_index": {
              "type": "integer"
            },
            "edge": {
              "type": "string",
              "enum": [
                "start",
                "end"
              ]
            },
            "at_seconds": {
              "type": "number",
              "description": "Recording source time for the flagged edge. This legacy field name is not Episode time."
            },
            "source_id": {
              "type": "string",
              "description": "Recording containing the flagged source edge."
            },
            "occurrence_id": {
              "type": "string",
              "description": "Exact created-target occurrence containing this edge, when mapped."
            },
            "episode_seconds": {
              "type": "number",
              "description": "Exact flagged point on the created target's Episode clock, usable directly as an episode_zoom edge; occurrence_id identifies its source side."
            },
            "word": {
              "type": "string"
            },
            "word_range_source": {
              "type": "array",
              "items": {
                "type": "number"
              },
              "minItems": 2,
              "maxItems": 2
            }
          }
        }
      },
      "status": {
        "type": "string",
        "description": "Always draft — cloned but not rendered."
      },
      "workspace_url": {
        "type": "string",
        "description": "Same-origin path that opens the new clone in the composite editor."
      },
      "already_applied": {
        "type": "boolean",
        "description": "true when this idempotency_key already created the same clone and the existing clone was returned."
      },
      "next_action": {
        "type": "object",
        "description": "Suggested next tool call: episode_edit on the clone at its current revision."
      },
      "blockers": {
        "type": "array",
        "items": {
          "type": "object"
        }
      },
      "duration": {
        "type": "number",
        "description": "Clone play length in seconds; the same value as duration_seconds."
      },
      "derived": {
        "type": "boolean",
        "description": "True when the clone is a derived Clip filed under a parent Episode; false for a clone of a top-level Episode."
      },
      "block_segments": {
        "type": "array",
        "description": "Template-backed segments carried by the clone.",
        "items": {
          "type": "object",
          "properties": {
            "position": {
              "type": "integer"
            },
            "template": {
              "type": "string"
            },
            "source_id": {
              "type": "string"
            },
            "status": {
              "type": "string",
              "enum": [
                "ready",
                "preparing",
                "failed"
              ],
              "description": "Whether the template-backed Recording is already renderable or still baking."
            }
          }
        }
      },
      "identity_plan": {
        "type": [
          "object",
          "null"
        ],
        "description": "Frozen identity plan carried from the source Episode; null when only identity warnings or row mappings were carried."
      },
      "identity_layers": {
        "type": "array",
        "description": "Resolved Signature layers of the carried identity plan, such as opener, cut style and outro."
      },
      "identity_segments": {
        "type": "array",
        "description": "Identity segment rows with role, final_position and segment_id."
      },
      "identity_warnings": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Identity warnings carried from the source Episode."
      },
      "request_row_map": {
        "type": "array",
        "description": "Mapping from the source Episode's requested rows to composition positions, including segment_id."
      },
      "workspace_binding": {
        "type": "object",
        "properties": {
          "schema": {
            "type": "string",
            "enum": [
              "bitterclip.workspace-binding.v2"
            ]
          },
          "mode": {
            "type": "string",
            "enum": [
              "live_workspace"
            ]
          },
          "project_id": {
            "type": "string"
          },
          "target_kind": {
            "type": "string",
            "enum": [
              "episode",
              "clip"
            ]
          },
          "target_id": {
            "type": "string"
          },
          "revision": {
            "type": "integer"
          },
          "draft_revision": {
            "type": "string"
          },
          "workspace_url": {
            "type": "string"
          },
          "output_id": {
            "type": "string"
          },
          "output_status": {
            "type": "string",
            "enum": [
              "missing",
              "stale",
              "rendering",
              "ready",
              "failed"
            ]
          },
          "output_revision": {
            "type": "integer"
          },
          "parent_episode_id": {
            "type": "string"
          }
        },
        "required": [
          "schema",
          "mode",
          "target_kind",
          "target_id",
          "revision",
          "draft_revision",
          "workspace_url",
          "output_status"
        ],
        "additionalProperties": false
      }
    },
    "required": [],
    "additionalProperties": false
  }
}

Errors

[
  "composition_not_found",
  "recording_not_found",
  "idempotency_conflict",
  "invalid_input"
]

Examples

[
  {
    "label": "Branch an episode before trying an alternate cut",
    "input": {
      "episode_id": "comp_...",
      "title": "Workshop branch A",
      "idempotency_key": "clone-branch-a"
    }
  }
]