@mengine/medeo-tool 1.0.1-alpha.2 → 1.2.1-alpha.0

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { i as renderCompactProjection, n as collectAffectedPartIds, r as renderPreview, t as EditSandboxSession } from "./script-session-B8fc9Ccb.mjs";
+import { i as renderCompactProjection, n as collectAffectedPartIds, r as renderPreview, t as EditSandboxSession } from "./script-session-DdPA4tTf.mjs";
 import { MengineDocSession, MengineHttpClient, MengineHttpRequestError, ValidationError, createMirrorVideoDocument, createPlainMemoryAdapter, replayJournal, toVideoDocument } from "@mengine/medeo-client";
 import { Worker } from "node:worker_threads";
 import { randomUUID } from "node:crypto";
@@ -157,6 +157,777 @@ function runEditScript(options) {
 	});
 }
 //#endregion
+//#region src/sandbox/generated/edit-sandbox-model-context.ts
+/**
+* @generated by gen:sandbox-dts — DO NOT EDIT MANUALLY
+*
+* Runtime copy of the sandbox TypeScript disclosure. The model prompt imports
+* this value so its interface and the checked-in declaration cannot drift.
+*/
+const EDIT_SANDBOX_API_DTS = [
+	"/**",
+	" * @generated by gen:sandbox-dts — DO NOT EDIT MANUALLY",
+	" *",
+	" * Schema version: video-document/v0",
+	" * Semantic ops: 20",
+	" *",
+	" * Boundary: zod `superRefine` / custom refine rules are NOT introspectable and",
+	" * do not appear here. Business mutual-exclusion rules surface via runtime",
+	" * validation errors (L3 feedback channel).",
+	" *",
+	" * @example 读取→计算→批量写",
+	" * ```ts",
+	" * const clips = timeline.clipsInRange(0, 10_000);",
+	" * await edit.setVideoClipSpeedShift({",
+	" *   clips: clips.map((c) => ({ clip_id: c.id, speed_shift: { category: 'linear', mode: 'constant', config: { linear: { speed: 1.5 } } } })),",
+	" * });",
+	" * ```",
+	" *",
+	" * @example anchored 删除",
+	" * ```ts",
+	" * await edit.deleteVideoClips({ clip_ids: ['clip_a'], on_anchored: 'detach' });",
+	" * ```",
+	" */",
+	"",
+	"/**",
+	" * A clip's playback-speed fact, the only thing `SetVideoClipSpeedShift` writes.",
+	" */",
+	"export interface SpeedShift {",
+	"  category: 'linear' | 'curve';",
+	"  mode: string;",
+	"  config:",
+	"    | {",
+	"        linear: {",
+	"          /**",
+	"           * @constraint positive",
+	"           */",
+	"          speed: number;",
+	"        };",
+	"      }",
+	"    | {",
+	"        curve: {",
+	"          /**",
+	"           * @constraint minLength(2)",
+	"           */",
+	"          keyframes: {",
+	"            /**",
+	"             * @constraint min(0)",
+	"             * @constraint max(1)",
+	"             */",
+	"            position: number;",
+	"            /**",
+	"             * @constraint min(0)",
+	"             */",
+	"            rate: number;",
+	"            /**",
+	"             * Bezier tangent handle (x, y)",
+	"             */",
+	"            in_tangent?: { x: number; y: number };",
+	"            /**",
+	"             * Bezier tangent handle (x, y)",
+	"             */",
+	"            out_tangent?: { x: number; y: number };",
+	"          }[];",
+	"        };",
+	"      };",
+	"}",
+	"",
+	"/**",
+	" * TTS voice summary attached to a speech",
+	" */",
+	"export interface Voice {",
+	"  /**",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  id: string;",
+	"  name: string;",
+	"}",
+	"",
+	"/**",
+	" * A materialized speech-subtree write (speeches + their captions).",
+	" */",
+	"export interface SpeechAssets {",
+	"  /**",
+	"   * Materialized speech parts to write",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  speeches: {",
+	"    /**",
+	"     * The speech part ID (= side-effect speech_parts[].id)",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    speech_id: string;",
+	"    /**",
+	"     * Host video clip part ID the speech anchors to (RFC 02 §4)",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    anchor_part_id: string;",
+	"    /**",
+	"     * Offset within the host clip (speech.abs = host.abs + offset_ms)",
+	"     * @constraint int",
+	"     * @constraint min(0)",
+	"     */",
+	"    offset_ms: number;",
+	"    /**",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    audio_storage_key: string;",
+	"    /**",
+	"     * Duration in milliseconds (> 0)",
+	"     * @constraint int",
+	"     * @constraint positive",
+	"     */",
+	"    duration_ms: number;",
+	"    audio_script: string;",
+	"    /**",
+	"     * Volume in decibels (-60.0 to 20.0; 0.0 = original, -60 = mute, +20 = max)",
+	"     * @constraint min(-60)",
+	"     * @constraint max(20)",
+	"     */",
+	"    volume: number;",
+	"    /**",
+	"     * TTS voice summary attached to a speech",
+	"     */",
+	"    voice: {",
+	"      /**",
+	"       * @constraint minLength(1)",
+	"       */",
+	"      id: string;",
+	"      name: string;",
+	"    };",
+	"    /**",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    origin_speech_id: string;",
+	"    /**",
+	"     * Caption part IDs owned by this speech",
+	"     */",
+	"    caption_ids: string[];",
+	"  }[];",
+	"  /**",
+	"   * Materialized caption parts owned by the speeches",
+	"   */",
+	"  captions: {",
+	"    /**",
+	"     * The caption part ID (= side-effect created_caption_parts[].id)",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    caption_id: string;",
+	"    /**",
+	"     * The owning speech part ID",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    speech_part_id: string;",
+	"    text: string;",
+	"    /**",
+	"     * Offset within the host speech (caption.abs = speech.abs + start_ms)",
+	"     * @constraint int",
+	"     * @constraint min(0)",
+	"     */",
+	"    start_ms: number;",
+	"    /**",
+	"     * Duration in milliseconds (> 0)",
+	"     * @constraint int",
+	"     * @constraint positive",
+	"     */",
+	"    duration_ms: number;",
+	"  }[];",
+	"}",
+	"",
+	"export interface MoveVideoClipsInput {",
+	"  /**",
+	"   * List of video clips to move to new positions",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  clips: {",
+	"    /**",
+	"     * The video clip part ID to move",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    clip_id: string;",
+	"    /**",
+	"     * New absolute start time in milliseconds on the timeline",
+	"     * @constraint int",
+	"     * @constraint min(0)",
+	"     */",
+	"    new_start_ms: number;",
+	"    /**",
+	"     * Target track ID to move the clip to (optional)",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    new_track_id?: string;",
+	"  }[];",
+	"}",
+	"",
+	"export interface MoveVideoClipsByAnchorInput {",
+	"  /**",
+	"   * Clips to move as one block, keeping their relative order. Need not be contiguous on the track.",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  clip_ids: string[];",
+	"  /**",
+	"   * Where the moved block lands: before/after a reference clip, or at the head of the track",
+	"   */",
+	"  anchor:",
+	"    | {",
+	"        position: 'before';",
+	"        /**",
+	"         * The moved block lands immediately before this clip",
+	"         * @constraint minLength(1)",
+	"         */",
+	"        clip_id: string;",
+	"      }",
+	"    | {",
+	"        position: 'after';",
+	"        /**",
+	"         * The moved block lands immediately after this clip",
+	"         * @constraint minLength(1)",
+	"         */",
+	"        clip_id: string;",
+	"      }",
+	"    | { position: 'track_start' };",
+	"  /**",
+	"   * What happens to speeches anchored to the moved clips (required — see the policy doc)",
+	"   */",
+	"  on_anchored: 'follow' | 'keep_absolute';",
+	"}",
+	"",
+	"export interface DeleteVideoClipsInput {",
+	"  /**",
+	"   * List of video clip part IDs to delete from the main track",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  clip_ids: string[];",
+	"  /**",
+	"   * How to treat anchored children (default cascade)",
+	"   */",
+	"  on_anchored?: 'cascade' | 'detach';",
+	"}",
+	"",
+	"/**",
+	" * Add video clips to a track.",
+	" */",
+	"export interface AddVideoClipsInput {",
+	"  /**",
+	"   * List of video clips to create",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  clips: {",
+	"    /**",
+	"     * The media asset ID for the video clip",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    media_id: string;",
+	"    /**",
+	"     * Absolute start time in milliseconds on the timeline",
+	"     * @constraint int",
+	"     * @constraint min(0)",
+	"     */",
+	"    start_ms?: number;",
+	"    /**",
+	"     * The source media's intrinsic full length in ms",
+	"     * @constraint int",
+	"     * @constraint positive",
+	"     */",
+	"    media_duration_ms: number;",
+	"    /**",
+	"     * Trim window start in the media (default 0)",
+	"     * @constraint int",
+	"     * @constraint min(0)",
+	"     */",
+	"    play_in?: number;",
+	"    /**",
+	"     * Trim window end in the media (default media_duration_ms)",
+	"     * @constraint int",
+	"     * @constraint positive",
+	"     */",
+	"    play_out?: number;",
+	"    /**",
+	"     * Target track ID (optional, defaults to main track)",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    track_id?: string;",
+	"  }[];",
+	"  /**",
+	"   * Insert new clips before this clip ID",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  before_clip_id?: string;",
+	"  /**",
+	"   * Insert new clips after this clip ID",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  after_clip_id?: string;",
+	"}",
+	"",
+	"export interface AdjustVideoClipVolumeInput {",
+	"  /**",
+	"   * List of video clips with their new volume settings",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  clips: {",
+	"    /**",
+	"     * The video clip part ID to adjust volume for",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    clip_id: string;",
+	"    /**",
+	"     * Volume in decibels (-60.0 to 20.0; 0.0 = original)",
+	"     * @constraint min(-60)",
+	"     * @constraint max(20)",
+	"     */",
+	"    volume: number;",
+	"  }[];",
+	"}",
+	"",
+	"/**",
+	" * Set the playback speed of existing video clips.",
+	" */",
+	"export interface SetVideoClipSpeedShiftInput {",
+	"  /**",
+	"   * Video clips with their new speed settings",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  clips: {",
+	"    /**",
+	"     * The video clip part ID to set speed for",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    clip_id: string;",
+	"    /**",
+	"     * The new speed setting, or null to reset to 1×",
+	"     */",
+	"    speed_shift: {",
+	"      category: 'linear' | 'curve';",
+	"      mode: string;",
+	"      config:",
+	"        | {",
+	"            linear: {",
+	"              /**",
+	"               * @constraint positive",
+	"               */",
+	"              speed: number;",
+	"            };",
+	"          }",
+	"        | {",
+	"            curve: {",
+	"              /**",
+	"               * @constraint minLength(2)",
+	"               */",
+	"              keyframes: {",
+	"                /**",
+	"                 * @constraint min(0)",
+	"                 * @constraint max(1)",
+	"                 */",
+	"                position: number;",
+	"                /**",
+	"                 * @constraint min(0)",
+	"                 */",
+	"                rate: number;",
+	"                /**",
+	"                 * Bezier tangent handle (x, y)",
+	"                 */",
+	"                in_tangent?: { x: number; y: number };",
+	"                /**",
+	"                 * Bezier tangent handle (x, y)",
+	"                 */",
+	"                out_tangent?: { x: number; y: number };",
+	"              }[];",
+	"            };",
+	"          };",
+	"    } | null;",
+	"  }[];",
+	"}",
+	"",
+	"/**",
+	" * Replace the media backing existing video clips.",
+	" */",
+	"export interface ReplaceVideoClipContentInput {",
+	"  /**",
+	"   * Video clips whose media is being replaced",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  clips: {",
+	"    /**",
+	"     * Existing video clip part ID to re-point",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    clip_id: string;",
+	"    /**",
+	"     * The new media asset ID",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    origin_media_id: string;",
+	"    /**",
+	"     * The new media's intrinsic full length",
+	"     * @constraint int",
+	"     * @constraint positive",
+	"     */",
+	"    media_duration_ms: number;",
+	"    /**",
+	"     * Trim window start in the new media (usually 0)",
+	"     * @constraint int",
+	"     * @constraint min(0)",
+	"     */",
+	"    play_in: number;",
+	"    /**",
+	"     * Trim window end in the new media (usually = media_duration_ms)",
+	"     * @constraint int",
+	"     * @constraint positive",
+	"     */",
+	"    play_out: number;",
+	"    /**",
+	"     * Volume in decibels (-60.0 to 20.0; 0.0 = original, -60 = mute, +20 = max)",
+	"     * @constraint min(-60)",
+	"     * @constraint max(20)",
+	"     */",
+	"    volume: number;",
+	"  }[];",
+	"}",
+	"",
+	"export interface ReplaceVideoClipSequenceInput {",
+	"  /**",
+	"   * The clips being replaced: a contiguous main-track run, listed in timeline order",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  old_clip_ids: string[];",
+	"  /**",
+	"   * The replacement clips, in the order they take on the track",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  new_clips: {",
+	"    /**",
+	"     * The replacement media asset ID. Omit to create an empty placeholder clip.",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    media_id?: string;",
+	"    /**",
+	"     * The source media's intrinsic full length in ms",
+	"     * @constraint int",
+	"     * @constraint positive",
+	"     */",
+	"    media_duration_ms: number;",
+	"    /**",
+	"     * Trim window start in the media (default 0)",
+	"     * @constraint int",
+	"     * @constraint min(0)",
+	"     */",
+	"    play_in?: number;",
+	"    /**",
+	"     * Trim window end in the media (default media_duration_ms)",
+	"     * @constraint int",
+	"     * @constraint positive",
+	"     */",
+	"    play_out?: number;",
+	"  }[];",
+	"  /**",
+	"   * What happens to speeches anchored to the replaced clips (required — see the policy doc)",
+	"   */",
+	"  on_anchored: 'remap' | 'cascade';",
+	"}",
+	"",
+	"/**",
+	" * Re-trim existing video clips (the user-facing \"adjust duration\" gesture is a trim of the source window).",
+	" */",
+	"export interface AdjustVideoClipDurationInput {",
+	"  /**",
+	"   * Video clips with their new trim windows",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  clips: {",
+	"    /**",
+	"     * The video clip part ID to re-trim",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    clip_id: string;",
+	"    /**",
+	"     * New trim window start in the source media",
+	"     * @constraint int",
+	"     * @constraint min(0)",
+	"     */",
+	"    play_in: number;",
+	"    /**",
+	"     * New trim window end in the source media",
+	"     * @constraint int",
+	"     * @constraint positive",
+	"     */",
+	"    play_out: number;",
+	"  }[];",
+	"}",
+	"",
+	"/**",
+	" * Add speeches (and their captions).",
+	" */",
+	"export interface AddSpeechesInput extends SpeechAssets {}",
+	"",
+	"/**",
+	" * Delete speeches with their captions.",
+	" */",
+	"export interface DeleteSpeechesInput {",
+	"  /**",
+	"   * Speech part IDs to delete (their captions cascade-delete)",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  speech_ids: string[];",
+	"}",
+	"",
+	"/**",
+	" * Move speeches in time.",
+	" */",
+	"export interface MoveSpeechesInput {",
+	"  /**",
+	"   * Speeches to move to new positions",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  speeches: {",
+	"    /**",
+	"     * The speech part ID to move",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    speech_id: string;",
+	"    /**",
+	"     * New absolute start time on the timeline",
+	"     * @constraint int",
+	"     * @constraint min(0)",
+	"     */",
+	"    new_start_ms: number;",
+	"  }[];",
+	"}",
+	"",
+	"/**",
+	" * Change a speech's script or voice.",
+	" */",
+	"export interface ChangeSpeechScriptInput extends SpeechAssets {}",
+	"",
+	"export interface ChangeSpeechVoiceInput extends SpeechAssets {}",
+	"",
+	"export interface AdjustSpeechVolumeInput {",
+	"  /**",
+	"   * List of speeches with their new volume settings",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  speeches: {",
+	"    /**",
+	"     * The speech part ID to adjust volume for",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    speech_id: string;",
+	"    /**",
+	"     * Volume in decibels (-60.0 to 20.0; 0.0 = original)",
+	"     * @constraint min(-60)",
+	"     * @constraint max(20)",
+	"     */",
+	"    volume: number;",
+	"  }[];",
+	"}",
+	"",
+	"/**",
+	" * Toggle caption visibility (the caption track's `is_hidden` flag).",
+	" */",
+	"export interface SetCaptionVisibilityInput {",
+	"  /**",
+	"   * Whether the caption track is hidden",
+	"   */",
+	"  is_hidden: boolean;",
+	"}",
+	"",
+	"/**",
+	" * Set the caption visual style.",
+	" */",
+	"export interface SetCaptionStyleInput {",
+	"  /**",
+	"   * Font ID referencing a font from the font library",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  font_id?: string;",
+	"  /**",
+	"   * Font size in points",
+	"   * @constraint positive",
+	"   */",
+	"  font_size?: number;",
+	"  /**",
+	"   * Font color as hex string, e.g. \"#FFFFFF\"",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  font_color?: string;",
+	"  /**",
+	"   * Numeric font weight, e.g. 400 or 700",
+	"   * @constraint int",
+	"   */",
+	"  font_weight?: number;",
+	"  /**",
+	"   * Entrance animation preset ID, e.g. \"fade\" or \"none\"",
+	"   */",
+	"  entrance_animation?: string;",
+	"  /**",
+	"   * Entrance animation duration in ms",
+	"   * @constraint min(0)",
+	"   */",
+	"  entrance_animation_duration_ms?: number;",
+	"  /**",
+	"   * Outline/stroke color as hex string, e.g. \"#000000\"",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  stroke_color?: string;",
+	"  /**",
+	"   * Outline/stroke width in pixels",
+	"   * @constraint min(0)",
+	"   */",
+	"  stroke_width?: number;",
+	"  /**",
+	"   * Caption center X as a fraction (0.0 to 1.0)",
+	"   */",
+	"  position_x?: number;",
+	"  /**",
+	"   * Caption center Y as a fraction (0.0 to 1.0)",
+	"   */",
+	"  position_y?: number;",
+	"}",
+	"",
+	"/**",
+	" * Set the document BGM.",
+	" */",
+	"export interface SetBgmInput {",
+	"  /**",
+	"   * The bgm part ID to write",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  bgm_id: string;",
+	"  /**",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  audio_storage_key: string;",
+	"  /**",
+	"   * The media asset ID",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  origin_media_id: string;",
+	"  /**",
+	"   * Volume in decibels (-60.0 to 20.0; 0.0 = original, -60 = mute, +20 = max)",
+	"   * @constraint min(-60)",
+	"   * @constraint max(20)",
+	"   */",
+	"  volume: number;",
+	"}",
+	"",
+	"/**",
+	" * Remove the document BGM.",
+	" */",
+	"export interface DeleteBgmInput {",
+	"  [key: string]: never;",
+	"}",
+	"",
+	"export interface AdjustBgmVolumeInput {",
+	"  /**",
+	"   * List of bgm parts with their new volume settings",
+	"   * @constraint minLength(1)",
+	"   */",
+	"  bgm: {",
+	"    /**",
+	"     * The bgm part ID to adjust volume for",
+	"     * @constraint minLength(1)",
+	"     */",
+	"    bgm_id: string;",
+	"    /**",
+	"     * Volume in decibels (-60.0 to 20.0; 0.0 = original)",
+	"     * @constraint min(-60)",
+	"     * @constraint max(20)",
+	"     */",
+	"    volume: number;",
+	"  }[];",
+	"}",
+	"",
+	"/** Agent write surface — one method per SemanticOp kind. */",
+	"export interface EditApi {",
+	"  moveVideoClips(input: MoveVideoClipsInput): Promise<void>;",
+	"  moveVideoClipsByAnchor(input: MoveVideoClipsByAnchorInput): Promise<void>;",
+	"  deleteVideoClips(input: DeleteVideoClipsInput): Promise<void>;",
+	"  /** Add video clips to a track. */",
+	"  addVideoClips(input: AddVideoClipsInput): Promise<void>;",
+	"  adjustVideoClipVolume(input: AdjustVideoClipVolumeInput): Promise<void>;",
+	"  /** Set the playback speed of existing video clips. */",
+	"  setVideoClipSpeedShift(input: SetVideoClipSpeedShiftInput): Promise<void>;",
+	"  /** Replace the media backing existing video clips. */",
+	"  replaceVideoClipContent(input: ReplaceVideoClipContentInput): Promise<void>;",
+	"  replaceVideoClipSequence(input: ReplaceVideoClipSequenceInput): Promise<void>;",
+	"  /** Re-trim existing video clips (the user-facing \"adjust duration\" gesture is a trim of the source window). */",
+	"  adjustVideoClipDuration(input: AdjustVideoClipDurationInput): Promise<void>;",
+	"  /** Add speeches (and their captions). */",
+	"  addSpeeches(input: AddSpeechesInput): Promise<void>;",
+	"  /** Delete speeches with their captions. */",
+	"  deleteSpeeches(input: DeleteSpeechesInput): Promise<void>;",
+	"  /** Move speeches in time. */",
+	"  moveSpeeches(input: MoveSpeechesInput): Promise<void>;",
+	"  /** Change a speech's script or voice. */",
+	"  changeSpeechScript(input: ChangeSpeechScriptInput): Promise<void>;",
+	"  changeSpeechVoice(input: ChangeSpeechVoiceInput): Promise<void>;",
+	"  adjustSpeechVolume(input: AdjustSpeechVolumeInput): Promise<void>;",
+	"  /** Toggle caption visibility (the caption track's `is_hidden` flag). */",
+	"  setCaptionVisibility(input: SetCaptionVisibilityInput): Promise<void>;",
+	"  /** Set the caption visual style. */",
+	"  setCaptionStyle(input: SetCaptionStyleInput): Promise<void>;",
+	"  /** Set the document BGM. */",
+	"  setBgm(input: SetBgmInput): Promise<void>;",
+	"  /** Remove the document BGM. */",
+	"  deleteBgm(input: DeleteBgmInput): Promise<void>;",
+	"  adjustBgmVolume(input: AdjustBgmVolumeInput): Promise<void>;",
+	"}",
+	"",
+	"/** Clip hit from `clipsInRange`. */",
+	"export interface TimelineClipDescriptor {",
+	"  id: string;",
+	"  start_ms: number;",
+	"  end_ms: number;",
+	"  duration_ms: number;",
+	"  speed_shift: unknown;",
+	"  volume: number | undefined;",
+	"  media_id: string | undefined;",
+	"}",
+	"",
+	"/** Part descriptor from `part(id)`. */",
+	"export interface TimelinePartDescriptor {",
+	"  id: string;",
+	"  kind: string;",
+	"  lane: string;",
+	"  start_ms: number;",
+	"  end_ms: number;",
+	"  duration_ms: number;",
+	"  part: unknown;",
+	"}",
+	"",
+	"/** Opaque VideoDraft projection (full IDL lives in host document types). */",
+	"export type VideoDraftProjection = {",
+	"  readonly timeline?: { readonly duration_ms?: number };",
+	"  readonly [key: string]: unknown;",
+	"};",
+	"",
+	"/** Agent read surface over the forked document. */",
+	"export interface TimelineApi {",
+	"  /** Snapshot the current VideoDraft projection. */",
+	"  snapshot(): VideoDraftProjection;",
+	"  /** Clips whose midpoint falls in `[startMs, endMs)`. */",
+	"  clipsInRange(startMs: number, endMs: number): TimelineClipDescriptor[];",
+	"  /** Look up a part by id, or null if missing. */",
+	"  part(id: string): TimelinePartDescriptor | null;",
+	"}",
+	"",
+	"/** Opaque checkpoint handle for rollback. */",
+	"export interface SandboxCheckpoint {",
+	"  readonly index: number;",
+	"}",
+	"",
+	"export declare const edit: EditApi;",
+	"export declare const timeline: TimelineApi;",
+	"",
+	"/** Capture a rollback point. */",
+	"export declare function checkpoint(): SandboxCheckpoint;",
+	"/** Roll the sandbox document back to a prior checkpoint. */",
+	"export declare function rollbackTo(cp: SandboxCheckpoint): void;",
+	"/** Host-injected script arguments (opaque). */",
+	"export declare const inputs: unknown;",
+	""
+].join("\n");
+//#endregion
 //#region src/prompt.ts
 const MEDEO_TOOL_DESCRIPTION = `
 Edit a Medeo video document through a deterministic, side-effect-free JavaScript sandbox.
@@ -168,6 +939,31 @@ Operations:
 
 Default flow: snapshot → run-edit-script with auto_commit=false → inspect preview → commit-plan. Use auto_commit=true only for low-risk edits when the host does not need user confirmation. On version mismatch, rerun snapshot and the script; never try to patch a rejected journal by hand.
 `.trim();
+const MEDEO_TOOL_EXECUTION_RULES = `
+The host supplies the current document. Do not ask for, invent, or pass a document id.
+Use timeline.snapshot() for the whole draft projection. Its duration is timeline.snapshot().timeline?.duration_ms; there is no top-level duration_ms.
+Use only the globals and methods declared by the following TypeScript interface. Values not declared here are unavailable.
+`.trim();
+/** Render the complete MEngine-owned context injected before one model call. */
+function renderMedeoModelContext(input) {
+	const updated = input.updatedSincePreviousModelCall == null ? "unknown (first model call)" : String(input.updatedSincePreviousModelCall);
+	return `
+${MEDEO_TOOL_DESCRIPTION}
+
+${MEDEO_TOOL_EXECUTION_RULES}
+
+Current MEngine document state (sampled dynamically immediately before this model call):
+- document_version: ${JSON.stringify(input.documentVersion)}
+- updated_since_previous_model_call: ${updated}
+
+When updated_since_previous_model_call is true, the document changed after the previous model call. The change may have come from this tool or another editor, so take a fresh snapshot before planning further edits.
+
+Sandbox TypeScript interface:
+\`\`\`ts
+${EDIT_SANDBOX_API_DTS}
+\`\`\`
+`.trim();
+}
 //#endregion
 //#region src/schema.ts
 const MEDEO_TOOL_NAME = "medeo";
@@ -347,6 +1143,7 @@ function opConflict(index, op_kind, message) {
 //#endregion
 //#region src/host-tool.ts
 const DEFAULT_MAX_PLANS = 16;
+const DEFAULT_MAX_MODEL_CONTEXTS = 128;
 function isRecord(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -410,7 +1207,9 @@ function parseInput(value) {
 function createMedeoTool(options) {
 	const sessions = /* @__PURE__ */ new Map();
 	const plans = /* @__PURE__ */ new Map();
+	const modelContextVersions = /* @__PURE__ */ new Map();
 	const maxPlans = options.maxPlans ?? DEFAULT_MAX_PLANS;
+	const maxModelContexts = options.maxModelContexts ?? DEFAULT_MAX_MODEL_CONTEXTS;
 	let closed = false;
 	async function getSession(docId) {
 		if (closed) throw new Error("medeo tool is closed");
@@ -480,6 +1279,35 @@ function createMedeoTool(options) {
 		}
 		return planId;
 	}
+	async function getModelContext(input) {
+		const docId = input.doc_id.trim();
+		const contextId = input.context_id.trim();
+		if (docId.length === 0) throw new Error("doc_id must be a non-empty string");
+		if (contextId.length === 0) throw new Error("context_id must be a non-empty string");
+		const documentVersion = (await getSession(docId)).version();
+		const baselineKey = `${contextId}\u0000${docId}`;
+		const previousVersion = modelContextVersions.get(baselineKey);
+		const updatedSincePreviousModelCall = previousVersion == null ? null : previousVersion !== documentVersion;
+		modelContextVersions.delete(baselineKey);
+		modelContextVersions.set(baselineKey, documentVersion);
+		while (modelContextVersions.size > maxModelContexts) {
+			const oldest = modelContextVersions.keys().next().value;
+			if (oldest === void 0) break;
+			modelContextVersions.delete(oldest);
+		}
+		return {
+			prompt: renderMedeoModelContext({
+				documentVersion,
+				updatedSincePreviousModelCall
+			}),
+			document_version: documentVersion,
+			updated_since_previous_model_call: updatedSincePreviousModelCall
+		};
+	}
+	async function confirmCommitted(session, result) {
+		if (result.kind === "committed" && result.ops_applied > 0) await session.waitForServerAck();
+		return result;
+	}
 	async function snapshot(input) {
 		const session = await getSession(input.doc_id);
 		const document = session.snapshot();
@@ -527,7 +1355,7 @@ function createMedeoTool(options) {
 			duration_ms: result.durationMs
 		};
 		if (input.auto_commit !== true) return base;
-		const commit = await commitPlan(session, result.plan);
+		const commit = await confirmCommitted(session, await commitPlan(session, result.plan));
 		return {
 			...base,
 			committed: commit.kind === "committed",
@@ -539,7 +1367,7 @@ function createMedeoTool(options) {
 		if (cached == null || cached.docId !== input.doc_id) throw new Error(`plan_id ${input.plan_id} is not available for doc ${input.doc_id}`);
 		const session = await getSession(input.doc_id);
 		const commitOptions = input.validation === void 0 ? void 0 : { validation: input.validation };
-		const result = await commitPlan(session, cached.plan, commitOptions);
+		const result = await confirmCommitted(session, await commitPlan(session, cached.plan, commitOptions));
 		return {
 			ok: true,
 			op: "commit-plan",
@@ -553,6 +1381,7 @@ function createMedeoTool(options) {
 		name: MEDEO_TOOL_NAME,
 		description: MEDEO_TOOL_DESCRIPTION,
 		parameters: MEDEO_TOOL_PARAMETERS,
+		getModelContext,
 		async handle(input) {
 			try {
 				const parsed = parseInput(input);
@@ -572,6 +1401,7 @@ function createMedeoTool(options) {
 			const opening = [...sessions.values()];
 			sessions.clear();
 			plans.clear();
+			modelContextVersions.clear();
 			const errors = [];
 			for (const sessionPromise of opening) try {
 				(await sessionPromise).destroy();