@pixerate/flair 0.34.0 → 0.35.1

package/dist/index.d.ts

@@ -1448,16 +1448,34 @@ interface SceneOutline {
 }
 type SceneToolResult = {
     ok: true;
+    /** The scene after the tool ran: keep it as the new state. */
     scene: Scene;
     outline?: SceneOutline;
     issues: SceneIssue[];
     review?: Review;
+    /**
+     * What to send back to the model as the tool's result: only what the
+     * call asked for (the outline without the full scene, a summary of an
+     * edit, the review without its markdown), so the conversation stays small.
+     */
+    output: SceneToolOutput;
 } | {
     ok: false;
     error: string;
+    failedStep?: number;
+    output: SceneToolOutput;
+};
+/** The model-facing result of a scene tool call (see `SceneToolResult.output`). */
+type SceneToolOutput = {
+    ok: boolean;
+    [field: string]: unknown;
 };
+declare function outlineScene(scene: Scene): SceneOutline;
 /**
- * Pure state machine that applies tool operations to a Scene.
+ * Pure state machine that applies tool operations to a Scene. Arguments are
+ * checked against the tool's `input_schema` first; a refusal (`ok: false`)
+ * leaves the scene as it was and says what to fix. Send `result.output` to
+ * the model and keep `result.scene` as the new state.
  */
 declare function applySceneTool(scene: Scene, toolName: string, input?: Record<string, any>): Promise<SceneToolResult>;
 
@@ -1470,7 +1488,7 @@ declare function applySceneTool(scene: Scene, toolName: string, input?: Record<s
  */
 
 interface BatchCommand {
-    /** Name of the tool to execute (e.g. 'update_shot', 'insert_shots', 'set_rig_widget'). */
+    /** Name of the tool to execute (e.g. 'update_shot', 'insert_shots', 'set_rig_widget'; not 'batch_scene'). */
     tool: string;
     /** Parameters for the tool call. */
     params?: Record<string, any>;
@@ -1489,7 +1507,9 @@ interface BatchExecutionResult {
 }
 /**
  * Recursively substitutes `$stepIndex.path` references in parameters using previous step results.
- * E.g., "$1.scene.shots[0].duration" -> substituted with the duration value from step 1 result.
+ * E.g., "$1.scene.shots[0].hold" -> the hold of the first shot after step 1. A string that is
+ * only a reference takes the value as it is; a reference inside a longer string is filled in
+ * as text. Throws when a reference names a step that has not run or a path that is not there.
  */
 declare function substituteVariables(value: any, stepResults: Map<number, SceneToolResult>): any;
 /**
@@ -1672,4 +1692,4 @@ declare function exportFcp7Xml(scene: Scene, options?: Fcp7ExportOptions): strin
  */
 declare function exportCmx3600Edl(scene: Scene, options?: EdlExportOptions): string;
 
-export { ALL_BLEND_MODES, ALL_TRANSITION_TYPES, type AgentToolDefinition, type AscCdl, type BatchCommand, type BatchExecutionResult, type BatchExecutionStepResult, type Behavior, type BehaviorBase, type BlendMode, type BlockDissolveOptions, type BlurEffect, type BurstEffect, CAMERA_MS, CAMERA_STEPS, CAMERA_STEP_MS, CAMERA_TRANSITIONS, COMMON_FRAME_RATES, type CameraAngle, type CameraLens, type CameraSample, type CameraShot, type CameraTransition, type ClearCommand, Clock, type ColorRGB, type ColorRGBA, type ColorRgba, type ColorSpace, ControlValue, type CounterEffect, type CrossZoomOptions, type CustomCommand, DEFAULT_PERSPECTIVE, DEFAULT_STAGE, type DeleteCommand, type DynamicFraming, EASY_EASE, EFFECT_FADE_MS, EFFECT_TYPES, type EasingCurve, type EdlExportOptions, type Effect, type EffectBase, type ElementCommand, FLAIR_AGENT_TOOLS, type Fcp7ExportOptions, type FlowEffect, type FramingOptions, type GifOptions, type GlassWipeOptions, type GlowEffect, type GradientEffect, type GridWipeOptions, type HighlightEffect, type KeyframeEase, type LiftGammaGain, type LightLeakOptions, type LinearWipeOptions, type LottieAnimatable, type LottieAnimation, type LottieExportOptions, type LottieKeyframe, type LottieLayer, type LottieShapeItem, type LottieTransform, MAX_TILT, type MediaEffect, MemorySceneBoard, type MotnExportOptions, NO_CHECK, type OscillateBehavior, type OvershootBehavior, type PathWaypoint, type PlayOptions, type PlayResult, type Point, type PopupWidget, type RadialIrisOptions, type RampBehavior, type RateBehavior, type RationalFrameRate, type Rect, type ReplicatorConfig, type ReplicatorPattern, type ReplicatorSequence, type Review, type ReviewOptions, type RigWidget, type RippleEffect, type RunningEffect, SCROLL_SETTLE, SCROLL_SMOOTHING, SMALL_TEXT_PX, type SMPTEFields, type Scene, type SceneBoard, type SceneCommand, type SceneElement, type SceneIssue, type SceneMedia, type SceneOutline, type SceneOutlineShot, type SceneRig, type SceneToolResult, ScrollTracker, type ShimmerEffect, type Shot, type ShotCamera, type ShotCheck, type ShotLog, type ShotTiming, type SliderSnapshot, type SliderWidget, type SpatialMotionPath, type SpatialPathSample, type SpotlightEffect, type Stage, type StandaloneOptions, type StandardFrameRateKey, TRANSITION_BLUR, type ThrowBehavior, type ThumbnailHandle, ThumbnailPool, type ThumbnailPoolOptions, type TimerEffect, type ToggleWidget, type TransitionOptions, type TransitionSample, type TransitionType, type TwisterOptions, type UpdateCommand, type Vec2, type Vec3, type View, type WriggleBehavior, applyAscCdl, applyLiftGammaGain, applyRig, applySceneBatch, applySceneTool, applyVibrance, areaOf, between, bez1d, bez1dDerivative, blendRgba, blendTransitionPixel, boardHeight, boundsOf, calculateFramingRect, calculateShotTimings, cameraAngle, cameraAt, cameraBlur, cameraFilter, cameraSamples, cameraTrack, cameraTransform, centreOf, checkShot, convertColorSpace, createFrameRate, createLottieEase, createMotionPath, cutsHalfway, easeInOutCubic, easeProgress, effectGone, effectOpacity, evaluateBehavior, evaluateKeyframeSegment, expandReplicator, exportCmx3600Edl, exportFcp7Xml, exportLottie, exportMotn, formatTimecode, fractalWiggle, frame, framesToSMPTE, framesToTimecode, getColorGradingGLSL, getDropFrameCount, getGlslBlendFunction, getOklabGLSL, getTimecodeBase, getTransitionGLSL, getWhiteBalanceGains, hash64, holdTime, interpolateOklab, interpolateOklch, isAngled, isDeleteCommand, isElementCommand, isUpdateCommand, linearRgbToSrgb, linearSrgbToOklab, linearToSrgb, loopTime, mixSeeds, motionBlur, motionBlurAngle, moveBlur, noise1d, noise3d, oklabToLinearSrgb, oklabToOklch, oklabToSrgb, oklchToOklab, overlapArea, parseTimecode, pingPongTime, playScene, projectPoint, quinticFade, recordGif, registerThumbnail, reviewScene, sampleMotionPath, sampleMotionPathAtTime, sampleTransition, sceneStage, screenBox, setRigWidget, sharedThumbnailPool, shotMoveMs, shotView, simulateScene, smpteToFrames, solveBezierU, speedRampTime, srgbToLinear, srgbToLinearRgb, srgbToOklab, standaloneHtml, standaloneSceneHtml, strobeTime, substituteVariables, supportsDropFrame, timecodeToFrames, titleBox, touchedIds, transitionStrength, transitionView, unitFloat, validateScene, viewAt, viewportProgress, visibleRect };
+export { ALL_BLEND_MODES, ALL_TRANSITION_TYPES, type AgentToolDefinition, type AscCdl, type BatchCommand, type BatchExecutionResult, type BatchExecutionStepResult, type Behavior, type BehaviorBase, type BlendMode, type BlockDissolveOptions, type BlurEffect, type BurstEffect, CAMERA_MS, CAMERA_STEPS, CAMERA_STEP_MS, CAMERA_TRANSITIONS, COMMON_FRAME_RATES, type CameraAngle, type CameraLens, type CameraSample, type CameraShot, type CameraTransition, type ClearCommand, Clock, type ColorRGB, type ColorRGBA, type ColorRgba, type ColorSpace, ControlValue, type CounterEffect, type CrossZoomOptions, type CustomCommand, DEFAULT_PERSPECTIVE, DEFAULT_STAGE, type DeleteCommand, type DynamicFraming, EASY_EASE, EFFECT_FADE_MS, EFFECT_TYPES, type EasingCurve, type EdlExportOptions, type Effect, type EffectBase, type ElementCommand, FLAIR_AGENT_TOOLS, type Fcp7ExportOptions, type FlowEffect, type FramingOptions, type GifOptions, type GlassWipeOptions, type GlowEffect, type GradientEffect, type GridWipeOptions, type HighlightEffect, type KeyframeEase, type LiftGammaGain, type LightLeakOptions, type LinearWipeOptions, type LottieAnimatable, type LottieAnimation, type LottieExportOptions, type LottieKeyframe, type LottieLayer, type LottieShapeItem, type LottieTransform, MAX_TILT, type MediaEffect, MemorySceneBoard, type MotnExportOptions, NO_CHECK, type OscillateBehavior, type OvershootBehavior, type PathWaypoint, type PlayOptions, type PlayResult, type Point, type PopupWidget, type RadialIrisOptions, type RampBehavior, type RateBehavior, type RationalFrameRate, type Rect, type ReplicatorConfig, type ReplicatorPattern, type ReplicatorSequence, type Review, type ReviewOptions, type RigWidget, type RippleEffect, type RunningEffect, SCROLL_SETTLE, SCROLL_SMOOTHING, SMALL_TEXT_PX, type SMPTEFields, type Scene, type SceneBoard, type SceneCommand, type SceneElement, type SceneIssue, type SceneMedia, type SceneOutline, type SceneOutlineShot, type SceneRig, type SceneToolOutput, type SceneToolResult, ScrollTracker, type ShimmerEffect, type Shot, type ShotCamera, type ShotCheck, type ShotLog, type ShotTiming, type SliderSnapshot, type SliderWidget, type SpatialMotionPath, type SpatialPathSample, type SpotlightEffect, type Stage, type StandaloneOptions, type StandardFrameRateKey, TRANSITION_BLUR, type ThrowBehavior, type ThumbnailHandle, ThumbnailPool, type ThumbnailPoolOptions, type TimerEffect, type ToggleWidget, type TransitionOptions, type TransitionSample, type TransitionType, type TwisterOptions, type UpdateCommand, type Vec2, type Vec3, type View, type WriggleBehavior, applyAscCdl, applyLiftGammaGain, applyRig, applySceneBatch, applySceneTool, applyVibrance, areaOf, between, bez1d, bez1dDerivative, blendRgba, blendTransitionPixel, boardHeight, boundsOf, calculateFramingRect, calculateShotTimings, cameraAngle, cameraAt, cameraBlur, cameraFilter, cameraSamples, cameraTrack, cameraTransform, centreOf, checkShot, convertColorSpace, createFrameRate, createLottieEase, createMotionPath, cutsHalfway, easeInOutCubic, easeProgress, effectGone, effectOpacity, evaluateBehavior, evaluateKeyframeSegment, expandReplicator, exportCmx3600Edl, exportFcp7Xml, exportLottie, exportMotn, formatTimecode, fractalWiggle, frame, framesToSMPTE, framesToTimecode, getColorGradingGLSL, getDropFrameCount, getGlslBlendFunction, getOklabGLSL, getTimecodeBase, getTransitionGLSL, getWhiteBalanceGains, hash64, holdTime, interpolateOklab, interpolateOklch, isAngled, isDeleteCommand, isElementCommand, isUpdateCommand, linearRgbToSrgb, linearSrgbToOklab, linearToSrgb, loopTime, mixSeeds, motionBlur, motionBlurAngle, moveBlur, noise1d, noise3d, oklabToLinearSrgb, oklabToOklch, oklabToSrgb, oklchToOklab, outlineScene, overlapArea, parseTimecode, pingPongTime, playScene, projectPoint, quinticFade, recordGif, registerThumbnail, reviewScene, sampleMotionPath, sampleMotionPathAtTime, sampleTransition, sceneStage, screenBox, setRigWidget, sharedThumbnailPool, shotMoveMs, shotView, simulateScene, smpteToFrames, solveBezierU, speedRampTime, srgbToLinear, srgbToLinearRgb, srgbToOklab, standaloneHtml, standaloneSceneHtml, strobeTime, substituteVariables, supportsDropFrame, timecodeToFrames, titleBox, touchedIds, transitionStrength, transitionView, unitFloat, validateScene, viewAt, viewportProgress, visibleRect };

package/dist/index.js

@@ -9,7 +9,7 @@ import {
   standaloneHtml,
   standaloneSceneHtml,
   validateScene
-} from "./chunk-ZULFHADW.js";
+} from "./chunk-OLTY4APV.js";
 import {
   calculateShotTimings,
   createLottieEase,
@@ -870,11 +870,164 @@ function sampleMotionPathAtTime(path, time, duration, ease) {
   return sampleMotionPath(path, distanceFraction);
 }
 
+// src/agent/batch.ts
+function getByPath(obj, path) {
+  if (!obj || typeof obj !== "object") return void 0;
+  const parts = path.replace(/\[(\w+)\]/g, ".$1").split(".");
+  let curr = obj;
+  for (const part of parts) {
+    if (curr === void 0 || curr === null) return void 0;
+    curr = curr[part];
+  }
+  return curr;
+}
+var REFERENCE = /\$(\d+)\.([A-Za-z_][\w.[\]]*)/g;
+function resolve(stepResults, stepStr, path, text) {
+  const stepIdx = parseInt(stepStr, 10);
+  const prevResult = stepResults.get(stepIdx);
+  if (!prevResult) {
+    throw new Error(`"${text}" refers to step ${stepIdx}, which has not run before this step.`);
+  }
+  const resolved = getByPath(prevResult, path);
+  if (resolved === void 0) {
+    throw new Error(`"${text}" does not resolve: step ${stepIdx}'s result has nothing at "${path}".`);
+  }
+  return resolved;
+}
+function substituteVariables(value, stepResults) {
+  if (typeof value === "string") {
+    const match = /^\$(\d+)\.([A-Za-z_][\w.[\]]*)$/.exec(value);
+    if (match) return resolve(stepResults, match[1], match[2], value);
+    return value.replace(
+      REFERENCE,
+      (fullMatch, stepStr, path) => String(resolve(stepResults, stepStr, path, fullMatch))
+    );
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => substituteVariables(item, stepResults));
+  }
+  if (value !== null && typeof value === "object") {
+    const copy = {};
+    for (const [k, v] of Object.entries(value)) {
+      copy[k] = substituteVariables(v, stepResults);
+    }
+    return copy;
+  }
+  return value;
+}
+async function applySceneBatch(scene, commands) {
+  let currentScene = scene;
+  const stepResults = /* @__PURE__ */ new Map();
+  const executedSteps = [];
+  for (let i = 0; i < commands.length; i++) {
+    const stepNumber = i + 1;
+    const cmd = commands[i];
+    if (cmd.tool === "batch_scene") {
+      return {
+        ok: false,
+        scene,
+        // Rollback
+        steps: executedSteps,
+        error: `Step ${stepNumber} is a batch_scene; batches cannot be nested, so list its steps here instead.`,
+        failedStep: stepNumber
+      };
+    }
+    let resolvedParams;
+    try {
+      resolvedParams = substituteVariables(cmd.params || {}, stepResults);
+    } catch (err) {
+      return {
+        ok: false,
+        scene,
+        // Rollback
+        steps: executedSteps,
+        error: `Step ${stepNumber} (${cmd.tool}) failed: ${err.message}`,
+        failedStep: stepNumber
+      };
+    }
+    const stepResult = await applySceneTool(currentScene, cmd.tool, resolvedParams);
+    stepResults.set(stepNumber, stepResult);
+    executedSteps.push({
+      step: stepNumber,
+      tool: cmd.tool,
+      result: stepResult
+    });
+    if (!stepResult.ok) {
+      return {
+        ok: false,
+        scene,
+        // Rollback to initial
+        steps: executedSteps,
+        error: `Step ${stepNumber} (${cmd.tool}) failed: ${stepResult.error}`,
+        failedStep: stepNumber
+      };
+    }
+    currentScene = stepResult.scene;
+  }
+  return {
+    ok: true,
+    scene: currentScene,
+    steps: executedSteps
+  };
+}
+
+// src/agent/schema.ts
+function typeOf(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+  return typeof value;
+}
+function described(type) {
+  if (type === "integer") return "a whole number";
+  if (type === "null") return "null";
+  return `${/^[aeiou]/.test(type) ? "an" : "a"} ${type}`;
+}
+function fits(value, type) {
+  const actual = typeOf(value);
+  return actual === type || type === "number" && actual === "integer";
+}
+function checkSchema(schema, value, at = "arguments") {
+  const problems = [];
+  if (schema.type !== void 0) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    if (!types.some((t) => fits(value, t))) {
+      const actual = typeOf(value) === "integer" ? "number" : typeOf(value);
+      problems.push(`${at} must be ${types.map(described).join(" or ")}, not ${described(actual)}.`);
+      return problems;
+    }
+  }
+  if (schema.enum && !schema.enum.includes(value)) {
+    problems.push(`${at} must be one of ${schema.enum.map((v) => JSON.stringify(v)).join(", ")}.`);
+  }
+  if (typeof value === "number" && typeof schema.minimum === "number" && value < schema.minimum) {
+    problems.push(`${at} must be at least ${schema.minimum}.`);
+  }
+  if (Array.isArray(value) && schema.items) {
+    value.forEach((item, i) => problems.push(...checkSchema(schema.items, item, `${at}[${i}]`)));
+  }
+  if (typeOf(value) === "object") {
+    const obj = value;
+    const props = schema.properties ?? {};
+    for (const name of schema.required ?? []) {
+      if (obj[name] === void 0) problems.push(`${at}.${name} is required.`);
+    }
+    for (const [name, v] of Object.entries(obj)) {
+      if (props[name]) problems.push(...checkSchema(props[name], v, `${at}.${name}`));
+      else if (schema.additionalProperties === false) {
+        const known = Object.keys(props);
+        problems.push(`${at}.${name} is not a parameter${known.length ? `; expected ${known.map((k) => `"${k}"`).join(", ")}` : ""}.`);
+      }
+    }
+  }
+  return problems;
+}
+
 // src/agent/tools.ts
 var FLAIR_AGENT_TOOLS = [
   {
     name: "get_scene",
-    description: "Returns the current scene JSON (or a concise structural outline) and any static validation issues.",
+    description: 'Returns the current scene JSON, or with view "outline" a concise structural outline instead, and any static validation issues. Start here.',
     input_schema: {
       type: "object",
       properties: {
@@ -889,7 +1042,7 @@ var FLAIR_AGENT_TOOLS = [
   },
   {
     name: "write_scene",
-    description: "Overwrites the entire scene with a new specification and validates it.",
+    description: "Overwrites the entire scene with a new specification and validates it. Prefer update_shot, insert_shots and delete_shots for smaller changes.",
     input_schema: {
       type: "object",
       properties: {
@@ -909,7 +1062,10 @@ var FLAIR_AGENT_TOOLS = [
       type: "object",
       properties: {
         shot: { type: "integer", minimum: 1, description: "1-based index of the shot to update." },
-        set: { type: "object", description: "Fields to set or replace on this shot." },
+        set: {
+          type: "object",
+          description: "Fields to set or replace on this shot: caption, title, camera, hold (ms), run, effects, stopEffects, behaviors."
+        },
         remove: {
           type: "array",
           items: { type: "string" },
@@ -934,7 +1090,7 @@ var FLAIR_AGENT_TOOLS = [
         shots: {
           type: "array",
           items: { type: "object" },
-          description: "Array of Shot objects to insert."
+          description: "Shot objects to insert (fields as for update_shot)."
         }
       },
       required: ["after", "shots"],
@@ -966,7 +1122,7 @@ var FLAIR_AGENT_TOOLS = [
         id: { type: "string", description: "Media identifier." },
         media: {
           type: ["object", "null"],
-          description: 'SceneMedia object (e.g. { type: "shader", source: "..." }), or null to remove.'
+          description: 'SceneMedia object, or null to remove. A shader is { type: "shader", source } with a GLSL ES 3.00 Shadertoy-style void mainImage(out vec4 fragColor, in vec2 fragCoord); it is only compiled when the scene is rendered on a GPU.'
         }
       },
       required: ["id", "media"],
@@ -975,7 +1131,7 @@ var FLAIR_AGENT_TOOLS = [
   },
   {
     name: "preview_scene",
-    description: "Simulates the scene fast and off-screen, returning timing, layout checks, and review report.",
+    description: "Simulates the scene fast and off-screen, returning its total length, layout and timing warnings, and notes. Run it after a round of edits.",
     input_schema: {
       type: "object",
       properties: {},
@@ -997,208 +1153,174 @@ var FLAIR_AGENT_TOOLS = [
       required: ["name", "value"],
       additionalProperties: false
     }
+  },
+  {
+    name: "batch_scene",
+    description: `Runs several of these tools in order as one all-or-nothing change: if a step fails, none of the steps apply. A string param "$N.path" is replaced by that path in step N's result (1-based; e.g. "$1.output.outline.shots[0].hold" or "$2.scene.shots[1].title"), and "$N.path" inside a longer string is filled in; a reference that does not resolve fails its step.`,
+    input_schema: {
+      type: "object",
+      properties: {
+        steps: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              tool: { type: "string", description: "A tool name (not batch_scene)." },
+              params: { type: "object", description: "That tool's arguments." }
+            },
+            required: ["tool"],
+            additionalProperties: false
+          },
+          description: "The tool calls to run, in order."
+        }
+      },
+      required: ["steps"],
+      additionalProperties: false
+    }
   }
 ];
+var TOOL_NAMES = FLAIR_AGENT_TOOLS.map((t) => t.name);
+function fail(error, failedStep) {
+  return { ok: false, error, ...failedStep !== void 0 && { failedStep }, output: { ok: false, error } };
+}
+function edited(scene, summary) {
+  const issues = validateScene(scene);
+  return { ok: true, scene, issues, output: { ok: true, summary, shotCount: scene.shots.length, issues } };
+}
+var shotsWord = (n) => `${n} shot${n === 1 ? "" : "s"}`;
+function outlineScene(scene) {
+  return {
+    name: scene.name,
+    title: scene.title,
+    description: scene.description,
+    stage: scene.stage,
+    target: scene.target,
+    mediaIds: Object.keys(scene.media || {}),
+    shots: scene.shots.map((s, i) => ({
+      shot: i + 1,
+      caption: s.caption,
+      title: s.title,
+      hold: s.hold,
+      camera: s.camera,
+      commandCount: Array.isArray(s.run) ? s.run.length : 0,
+      effects: Array.isArray(s.effects) ? s.effects.map((e) => e.type) : void 0
+    }))
+  };
+}
 async function applySceneTool(scene, toolName, input = {}) {
+  const definition = FLAIR_AGENT_TOOLS.find((t) => t.name === toolName);
+  if (!definition) {
+    return fail(`There is no tool "${toolName}"; the tools are ${TOOL_NAMES.join(", ")}.`);
+  }
+  const problems = checkSchema(definition.input_schema, input ?? {});
+  if (problems.length) return fail(`Invalid arguments for ${toolName}: ${problems.join(" ")}`);
+  const shotCount = scene.shots.length;
+  const shotRange = `the scene has ${shotsWord(shotCount)} (1 to ${shotCount})`;
   switch (toolName) {
     case "get_scene": {
       const issues = validateScene(scene);
       if (input.view === "outline") {
-        const outline = {
-          name: scene.name,
-          title: scene.title,
-          description: scene.description,
-          stage: scene.stage,
-          target: scene.target,
-          mediaIds: Object.keys(scene.media || {}),
-          shots: scene.shots.map((s, i) => ({
-            shot: i + 1,
-            caption: s.caption,
-            title: s.title,
-            hold: s.hold,
-            camera: s.camera,
-            commandCount: s.run?.length ?? 0,
-            effects: s.effects?.map((e) => e.type)
-          }))
-        };
-        return { ok: true, scene, outline, issues };
+        const outline = outlineScene(scene);
+        return { ok: true, scene, outline, issues, output: { ok: true, outline, issues } };
       }
-      return { ok: true, scene, issues };
+      return { ok: true, scene, issues, output: { ok: true, scene, issues } };
     }
     case "write_scene": {
-      if (!input.scene || typeof input.scene !== "object") {
-        return { ok: false, error: "Expected scene object in arguments." };
+      const next = input.scene;
+      if (!Array.isArray(next.shots) || next.shots.some((s) => !s || typeof s !== "object" || Array.isArray(s))) {
+        return fail("The scene needs a shots array of shot objects; nothing was written.");
       }
-      const newScene = input.scene;
-      const issues = validateScene(newScene);
-      return { ok: true, scene: newScene, issues };
+      if (next.shots.length === 0) return fail("The scene needs at least one shot; nothing was written.");
+      return edited(next, `Wrote the scene "${next.name}" with ${shotsWord(next.shots.length)}.`);
     }
     case "update_shot": {
       const idx = input.shot - 1;
-      if (idx < 0 || idx >= scene.shots.length) {
-        return { ok: false, error: `Invalid shot number ${input.shot}; scene has ${scene.shots.length} shots.` };
-      }
-      const existing = scene.shots[idx];
-      const updated = { ...existing, ...input.set || {} };
-      if (Array.isArray(input.remove)) {
-        for (const k of input.remove) {
-          delete updated[k];
-        }
+      if (idx >= shotCount) return fail(`There is no shot ${input.shot}; ${shotRange}.`);
+      if (input.set === void 0 && input.remove === void 0) {
+        return fail('Give fields to change in "set", field names to delete in "remove", or both.');
       }
+      const updated = { ...scene.shots[idx], ...input.set || {} };
+      for (const k of input.remove ?? []) delete updated[k];
       const shots = [...scene.shots];
       shots[idx] = updated;
-      const newScene = { ...scene, shots };
-      return { ok: true, scene: newScene, issues: validateScene(newScene) };
+      const changed = [...Object.keys(input.set ?? {}), ...(input.remove ?? []).map((k) => `-${k}`)];
+      return edited({ ...scene, shots }, `Updated shot ${input.shot} (${changed.join(", ")}).`);
     }
     case "insert_shots": {
-      const after = input.after ?? scene.shots.length;
-      if (after < 0 || after > scene.shots.length) {
-        return { ok: false, error: `Invalid after index ${after}.` };
-      }
-      if (!Array.isArray(input.shots) || input.shots.length === 0) {
-        return { ok: false, error: "Expected non-empty shots array to insert." };
-      }
+      const after = input.after;
+      if (after > shotCount) return fail(`Cannot insert after shot ${after}; ${shotRange}, so "after" is 0 to ${shotCount}.`);
+      if (input.shots.length === 0) return fail("Give at least one shot to insert.");
       const shots = [...scene.shots.slice(0, after), ...input.shots, ...scene.shots.slice(after)];
-      const newScene = { ...scene, shots };
-      return { ok: true, scene: newScene, issues: validateScene(newScene) };
+      const first = after + 1;
+      const last = after + input.shots.length;
+      return edited(
+        { ...scene, shots },
+        `Inserted ${shotsWord(input.shots.length)} as ${first === last ? `shot ${first}` : `shots ${first}-${last}`}; later shots moved down.`
+      );
     }
     case "delete_shots": {
-      if (!Array.isArray(input.shots) || input.shots.length === 0) {
-        return { ok: false, error: "Expected non-empty shots array to delete." };
-      }
-      const toDelete = new Set(input.shots.map((n) => n - 1));
+      const numbers = input.shots;
+      if (numbers.length === 0) return fail("Give the shot numbers to delete.");
+      const missing = numbers.filter((n) => n > shotCount);
+      if (missing.length) return fail(`There is no shot ${missing.join(", ")}; ${shotRange}. Nothing was deleted.`);
+      const toDelete = new Set(numbers.map((n) => n - 1));
       const shots = scene.shots.filter((_, i) => !toDelete.has(i));
-      if (shots.length === 0) {
-        return { ok: false, error: "Cannot delete all shots in scene." };
-      }
-      const newScene = { ...scene, shots };
-      return { ok: true, scene: newScene, issues: validateScene(newScene) };
+      if (shots.length === 0) return fail("Cannot delete every shot; a scene needs at least one. Nothing was deleted.");
+      return edited({ ...scene, shots }, `Deleted ${shotsWord(toDelete.size)}; the scene has ${shotsWord(shots.length)} now.`);
     }
     case "set_media": {
-      if (!input.id || typeof input.id !== "string") {
-        return { ok: false, error: "Expected string media id." };
-      }
       const media = { ...scene.media || {} };
       if (input.media === null) {
+        if (!(input.id in media)) {
+          const ids = Object.keys(media);
+          return fail(`There is no media "${input.id}" to remove; ${ids.length ? `the media are ${ids.join(", ")}` : "the scene has no media"}.`);
+        }
         delete media[input.id];
-      } else {
-        media[input.id] = input.media;
+        return edited({ ...scene, media }, `Removed media "${input.id}".`);
       }
-      const newScene = { ...scene, media };
-      return { ok: true, scene: newScene, issues: validateScene(newScene) };
+      if (typeof input.media.type !== "string") return fail('Media needs a string type, e.g. { type: "shader", source: "..." }.');
+      const existed = input.id in media;
+      media[input.id] = input.media;
+      return edited({ ...scene, media }, `${existed ? "Replaced" : "Added"} ${input.media.type} media "${input.id}".`);
     }
     case "preview_scene": {
       const { review } = await simulateScene(scene);
-      return { ok: true, scene, issues: validateScene(scene), review };
+      const issues = validateScene(scene);
+      const { markdown: _markdown, ...summary } = review;
+      return { ok: true, scene, issues, review, output: { ok: true, issues, review: summary } };
     }
     case "set_rig_widget": {
-      if (!scene.rig || !scene.rig.widgets || !scene.rig.widgets[input.name]) {
-        return { ok: false, error: `Scene does not have a rig widget named "${input.name}".` };
+      const widgets = scene.rig?.widgets ?? {};
+      if (!scene.rig || !widgets[input.name]) {
+        const names = Object.keys(widgets);
+        return fail(`Scene does not have a rig widget named "${input.name}"; ${names.length ? `its widgets are ${names.join(", ")}` : "it has no rig widgets"}.`);
       }
       try {
         const updatedRig = setRigWidget(scene.rig, input.name, input.value);
-        const newScene = applyRig(updatedRig, scene);
-        return { ok: true, scene: newScene, issues: validateScene(newScene) };
+        return edited(applyRig(updatedRig, scene), `Set rig widget "${input.name}" to ${JSON.stringify(input.value)}.`);
       } catch (err) {
-        return { ok: false, error: err.message || String(err) };
+        return fail(err.message || String(err));
       }
     }
-    default:
-      return { ok: false, error: `Unknown tool name: ${toolName}` };
-  }
-}
-
-// src/agent/batch.ts
-function getByPath(obj, path) {
-  if (!obj || typeof obj !== "object") return void 0;
-  const parts = path.replace(/\[(\w+)\]/g, ".$1").split(".");
-  let curr = obj;
-  for (const part of parts) {
-    if (curr === void 0 || curr === null) return void 0;
-    curr = curr[part];
-  }
-  return curr;
-}
-function substituteVariables(value, stepResults) {
-  if (typeof value === "string") {
-    const match = /^\$(\d+)\.(.+)$/.exec(value);
-    if (match) {
-      const stepIdx = parseInt(match[1], 10);
-      const path = match[2];
-      const prevResult = stepResults.get(stepIdx);
-      if (prevResult) {
-        const resolved = getByPath(prevResult, path);
-        if (resolved !== void 0) {
-          return resolved;
-        }
-      }
-    }
-    return value.replace(/\$(\d+)\.([a-zA-Z0-9_.[\]]+)/g, (fullMatch, stepStr, path) => {
-      const stepIdx = parseInt(stepStr, 10);
-      const prevResult = stepResults.get(stepIdx);
-      if (prevResult) {
-        const resolved = getByPath(prevResult, path);
-        if (resolved !== void 0) {
-          return String(resolved);
-        }
-      }
-      return fullMatch;
-    });
-  }
-  if (Array.isArray(value)) {
-    return value.map((item) => substituteVariables(item, stepResults));
-  }
-  if (value !== null && typeof value === "object") {
-    const copy = {};
-    for (const [k, v] of Object.entries(value)) {
-      copy[k] = substituteVariables(v, stepResults);
-    }
-    return copy;
-  }
-  return value;
-}
-async function applySceneBatch(scene, commands) {
-  let currentScene = scene;
-  const stepResults = /* @__PURE__ */ new Map();
-  const executedSteps = [];
-  for (let i = 0; i < commands.length; i++) {
-    const stepNumber = i + 1;
-    const cmd = commands[i];
-    const resolvedParams = substituteVariables(cmd.params || {}, stepResults);
-    if (cmd.tool === "batch_scene_tool") {
-      return {
-        ok: false,
-        scene,
-        // Rollback
-        steps: executedSteps,
-        error: `Nested batch_scene_tool is not allowed at step ${stepNumber}.`,
-        failedStep: stepNumber
-      };
-    }
-    const stepResult = await applySceneTool(currentScene, cmd.tool, resolvedParams);
-    stepResults.set(stepNumber, stepResult);
-    executedSteps.push({
-      step: stepNumber,
-      tool: cmd.tool,
-      result: stepResult
-    });
-    if (!stepResult.ok) {
+    case "batch_scene": {
+      const batch = await applySceneBatch(scene, input.steps);
+      if (!batch.ok) return fail(`${batch.error} No steps were applied.`, batch.failedStep);
+      const issues = validateScene(batch.scene);
       return {
-        ok: false,
-        scene,
-        // Rollback to initial
-        steps: executedSteps,
-        error: `Step ${stepNumber} (${cmd.tool}) failed: ${stepResult.error}`,
-        failedStep: stepNumber
+        ok: true,
+        scene: batch.scene,
+        issues,
+        output: {
+          ok: true,
+          summary: `Ran ${batch.steps.length} step${batch.steps.length === 1 ? "" : "s"}.`,
+          steps: batch.steps.map((s) => ({ step: s.step, tool: s.tool, ...s.result.output })),
+          shotCount: batch.scene.shots.length,
+          issues
+        }
       };
     }
-    currentScene = stepResult.scene;
   }
-  return {
-    ok: true,
-    scene: currentScene,
-    steps: executedSteps
-  };
+  return fail(`There is no tool "${toolName}".`);
 }
 export {
   ALL_BLEND_MODES,
@@ -1353,6 +1475,7 @@ export {
   oklabToOklch,
   oklabToSrgb,
   oklchToOklab,
+  outlineScene,
   overlapArea,
   pageHidden,
   parseColor,