@pixeldojo/mcp 0.18.0 → 0.19.0

package/dist/cli.js

@@ -593,7 +593,7 @@ var init_generate = __esm({
     DRAFT_DESCRIPTION = "Seedance 2.5 draft mode: render a cheap 480p draft (runs on seedance-2-5) so the user can try takes before paying for full resolution. The reply gives the draft's job id and duration; pass them to upgrade_draft to render that exact take at 1080p.";
     UPGRADE_DESCRIPTION = "Job id of a finished Seedance 2.5 draft to render at 1080p, the same take with full detail. Also pass `duration` equal to the draft's (the draft reply states it). The draft's prompt and media are reused, so prompt and references are ignored. Billed as a 1080p run.";
     InputSchema = z.object({
-      prompt: z.string().min(1).max(8e3).describe("Prompt describing what to generate."),
+      prompt: z.string().min(1).max(8e3).describe('Prompt describing what to generate. Write @Name to use a character or element the user saved in Character Studio ("@Mara on a beach"): its photos are attached automatically on models that take reference images. pixeldojo_library source=characters lists them.'),
       model: z.string().optional().describe(
         `Model apiId. Recommended (the models the PixelDojo studios use): "seedream-5" for images (the default), "seedance-2-5" for video (prompt only or a starting image), "wan-3-0-video" for video the others refuse. Use another model only when the user names one. Full catalog: https://pixeldojo.ai/api/v1/models; one model's fields: https://pixeldojo.ai/llm/{apiId}.txt. Omit for seedream-5, which makes still images only; name a video model to get a video.`
       ),
@@ -633,7 +633,7 @@ var init_generate = __esm({
     InputJsonSchema = {
       type: "object",
       properties: {
-        prompt: { type: "string", description: "Prompt describing what to generate." },
+        prompt: { type: "string", description: 'Prompt describing what to generate. Write @Name to use a character or element the user saved in Character Studio ("@Mara on a beach"): its photos are attached automatically on models that take reference images. pixeldojo_library source=characters lists them.' },
         model: {
           type: "string",
           description: `Model apiId. Recommended (the models the PixelDojo studios use): "seedream-5" for images (the default), "seedance-2-5" for video (prompt only or a starting image), "wan-3-0-video" for video the others refuse. Use another model only when the user names one. Full catalog: https://pixeldojo.ai/api/v1/models; one model's fields: https://pixeldojo.ai/llm/{apiId}.txt. Omit for seedream-5, which makes still images only; name a video model to get a video.`
@@ -847,7 +847,7 @@ var init_edit = __esm({
     InputJsonSchema2 = {
       type: "object",
       properties: {
-        prompt: { type: "string", description: "Edit instruction." },
+        prompt: { type: "string", description: 'Edit instruction. Write @Name to use a character or element the user saved in Character Studio ("@Mara on a beach"): its photos are attached automatically on models that take reference images. pixeldojo_library source=characters lists them.' },
         image_url: {
           type: "string",
           format: "uri",
@@ -1453,6 +1453,13 @@ async function filmApi(ctx, method, path, body) {
   const data = await res.json().catch(() => ({}));
   return { status: res.status, data };
 }
+function keepGoing(filmId, afterSec, extra = {}) {
+  const set = Object.fromEntries(Object.entries(extra).filter(([, v]) => v !== void 0));
+  return { input: { film_id: filmId, action: "status", ...set }, afterSec };
+}
+function shotLabels(f) {
+  return new Map(f.scenes.flatMap((s, si) => s.shots.map((sh, i) => [sh.id, `${si + 1}.${i + 1}`])));
+}
 async function applyCast(ctx, filmId, cast) {
   let charged = false;
   const lines = await Promise.all(cast.map(async (c) => {
@@ -1572,12 +1579,13 @@ async function plan(input, ctx) {
   const castStarted = Date.now();
   const cast = input.cast?.length ? await applyCast(ctx, id, input.cast) : { lines: [], charged: false };
   const pollBudget = Math.max(0, PLANNER_MAX_POLLS - Math.ceil((Date.now() - castStarted) / PLANNER_POLL_MS));
-  const reply = (text) => ({
+  const reply = (text, followUp) => ({
     kind: "text",
     text: [
       ...cast.lines,
       cast.charged ? text.replace(/Nothing has been charged( yet)?\./g, "Only the cast portraits above have been charged.") : text
-    ].join("\n")
+    ].join("\n"),
+    ...followUp ? { followUp } : {}
   });
   let planned;
   if (music) {
@@ -1588,14 +1596,14 @@ ${input.lyrics.trim()}` : ""].filter(Boolean).join("\n\n");
     let script = input.script?.trim() ?? "";
     if (!script) {
       const wrote = await runPlanner(ctx, id, `/api/films/${id}/script`, { idea: input.idea.trim() }, pollBudget);
-      if ("pending" in wrote) return reply(stillPlanningText(id, "script"));
+      if ("pending" in wrote) return reply(stillPlanningText(id, "script"), keepGoing(id, 30, { soundtrack: input.soundtrack }));
       if ("error" in wrote) return reply(`Script writing failed: ${wrote.error}`);
       script = wrote.film.script ?? "";
       if (!script) return reply("Script writing failed: the studio returned an empty script.");
     }
     planned = await runPlanner(ctx, id, `/api/films/${id}/plan`, { script });
   }
-  if ("pending" in planned) return reply(stillPlanningText(id));
+  if ("pending" in planned) return reply(stillPlanningText(id), keepGoing(id, 30, { soundtrack: input.soundtrack }));
   if ("error" in planned) return reply(`Shot planning failed: ${planned.error}`);
   const film = planned.film;
   if (needsSlice(film)) {
@@ -1608,17 +1616,17 @@ ${err} Call action "status" to retry the cut.`);
   return reply([plannedText(film, ctx), uncast.length ? `
 ${castNeededText(id, uncast)}` : ""].filter(Boolean).join("\n"));
 }
-async function resumePlanning(film, ctx) {
+async function resumePlanning(film, ctx, soundtrack) {
   if (film.scenes.length > 0 && film.llmJob?.status !== "running") return null;
   if (film.llmJob?.status === "running") {
-    return { kind: "text", text: stillPlanningText(film.id, film.llmJob.kind === "script" ? "script" : "plan") };
+    return { kind: "text", text: stillPlanningText(film.id, film.llmJob.kind === "script" ? "script" : "plan"), followUp: keepGoing(film.id, 30, { soundtrack }) };
   }
   const prior = film.llmJob?.status === "error" ? `The last planning run failed (${film.llmJob.error ?? "unknown"}). ` : "";
   if (!film.script?.trim()) {
     return { kind: "text", text: `${prior}This film has nothing to plan from. Start a new one with action "plan".` };
   }
   const planned = await runPlanner(ctx, film.id, `/api/films/${film.id}/plan`, { script: film.script }, 0);
-  if ("pending" in planned) return { kind: "text", text: `${prior}${stillPlanningText(film.id)}` };
+  if ("pending" in planned) return { kind: "text", text: `${prior}${stillPlanningText(film.id)}`, followUp: keepGoing(film.id, 30, { soundtrack }) };
   if ("error" in planned) return { kind: "text", text: `Shot planning failed: ${planned.error} Call action "status" to retry.` };
   if (needsSlice(planned.film)) {
     const err = await sliceSong(ctx, planned.film);
@@ -1628,22 +1636,30 @@ ${err} Call action "status" to retry the cut.` };
   }
   return { kind: "text", text: plannedText(planned.film, ctx) };
 }
-async function produce(filmId, ctx) {
+async function produce(filmId, soundtrack, ctx) {
   const { data } = await filmApi(ctx, "GET", `/api/films/${filmId}`);
   if (!data.film) return { kind: "text", text: `Film not found: ${data.error ?? filmId}` };
-  const planning = await resumePlanning(data.film, ctx);
+  const planning = await resumePlanning(data.film, ctx, soundtrack);
   if (planning) return planning;
   const uncast = await uncastRolesOf(ctx, filmId);
   if (uncast.length) return { kind: "text", text: `Nothing was charged. ${castNeededText(filmId, uncast)}` };
   const pending = shots(data.film).filter((sh) => sh.status === "idle" || sh.status === "failed" && !sh.frameUrl);
   let fired = 0;
+  let refused;
   for (const sh of pending.slice(0, 6)) {
     const r = await filmApi(ctx, "POST", `/api/films/${filmId}/shots/${sh.id}/generate`, { kind: "frame" });
     if (r.status === 200) fired += 1;
+    else if (!benignDispatchRefusal(r.status, r.data.error)) refused ??= r.data.error ?? `HTTP ${r.status}`;
+  }
+  if (fired === 0 && refused) {
+    return { kind: "text", text: `Production could not start on "${data.film.title}": ${refused}` };
   }
   return {
     kind: "text",
-    text: `Production started on "${data.film.title}": ${fired} frame(s) dispatched (each is a normal frame charge; the server's Frame check reviews every one). Poll pixeldojo_film with {"film_id": "${filmId}", "action": "status"} every ~30 seconds \u2014 each poll advances the pipeline.`
+    text: `Production started on "${data.film.title}": ${fired} frame(s) dispatched (each is a normal frame charge; the server's Frame check reviews every one).${refused ? ` Some could not start: ${refused}` : ""} Poll pixeldojo_film with {"film_id": "${filmId}", "action": "status"} every ~30 seconds \u2014 each poll advances the pipeline.`,
+    // The caller's soundtrack choice rides along: the follow-up status calls
+    // are the ones that reach the score.
+    followUp: keepGoing(filmId, 30, { soundtrack })
   };
 }
 function buildScorePlanBody(film) {
@@ -1689,30 +1705,49 @@ async function advance(filmId, soundtrack, musicJobId, ctx) {
   if (film.status === "exported" && film.exportUrl) {
     return {
       kind: "text",
-      text: `Film finished: "${film.title}"
+      text: [
+        `Film finished: "${film.title}"
 Watch/download: ${film.exportUrl}
 Workspace: ${ctx.baseUrl}/film-studio/${film.id}
-It is saved in the Library folder "Film: ${film.title}".`
+It is saved in the Library folder "Film: ${film.title}".`,
+        shotIndex(film)
+      ].filter(Boolean).join("\n")
     };
   }
-  if (film.exportError) {
-    return { kind: "text", text: `Export failed: ${film.exportError} Poll again with action "status" to retry.` };
+  const startExport = async () => {
+    const r = await filmApi(ctx, "POST", `/api/films/${filmId}/export`, {});
+    return r.status === 200 || r.status === 409 ? null : r.data.error ?? `HTTP ${r.status}`;
+  };
+  if (film.exportError && all.length > 0 && all.every((sh) => sh.status === "clip-ready")) {
+    const again = await startExport();
+    return {
+      kind: "text",
+      text: again ? `Export failed: ${film.exportError} Starting it again failed too: ${again}` : `The last export failed (${film.exportError}). Started it again; exports are free. Call pixeldojo_film with {"film_id": "${filmId}", "action": "status"} in about a minute for the finished film.`
+    };
   }
-  const planning = await resumePlanning(film, ctx);
+  const planning = await resumePlanning(film, ctx, soundtrack);
   if (planning) return planning;
   if (needsSlice(film)) {
     const err = await sliceSong(ctx, film);
     if (err) return { kind: "text", text: `${err} Poll again with action "status" to retry.` };
-    return { kind: "text", text: `Song cut into one slice per shot. Poll again with {"film_id": "${filmId}", "action": "status"} to keep production moving.` };
+    return {
+      kind: "text",
+      text: `Song cut into one slice per shot. Poll again with {"film_id": "${filmId}", "action": "status"} to keep production moving.`,
+      followUp: keepGoing(filmId, 5, { soundtrack })
+    };
   }
   if (shots(film).length > 0 && shots(film).every((sh) => sh.status === "idle")) {
     return { kind: "text", text: plannedText(film, ctx) };
   }
   let started = 0;
   const resent = /* @__PURE__ */ new Set();
+  const refusedStarts = [];
   const dispatch = async (sh, kind) => {
     const r = await filmApi(ctx, "POST", `/api/films/${filmId}/shots/${sh.id}/generate`, { kind });
-    if (r.status !== 200) return;
+    if (r.status !== 200) {
+      if (!benignDispatchRefusal(r.status, r.data.error)) refusedStarts.push(r.data.error ?? `HTTP ${r.status}`);
+      return;
+    }
     started += 1;
     if (sh.status === "failed") resent.add(sh.id);
   };
@@ -1742,27 +1777,47 @@ It is saved in the Library folder "Film: ${film.title}".`
         const outUrl = out?.audio ?? out?.video ?? out?.images?.[0];
         if (job.status === "completed" && typeof outUrl === "string") {
           await filmApi(ctx, "PATCH", `/api/films/${filmId}`, { audioStems: [{ kind: "music", url: outUrl }] });
-          await filmApi(ctx, "POST", `/api/films/${filmId}/export`, {});
-          return { kind: "text", text: `Score attached \u2014 export started. Poll again in ~60s with {"film_id": "${filmId}", "action": "status"} for the finished film URL.` };
+          const exportError2 = await startExport();
+          if (exportError2) return { kind: "text", text: `Score attached, but the export could not start: ${exportError2}` };
+          return {
+            kind: "text",
+            text: `Score attached \u2014 export started. Poll again in ~60s with {"film_id": "${filmId}", "action": "status"} for the finished film URL.`,
+            followUp: keepGoing(filmId, 60, { soundtrack })
+          };
         }
         if (job.status === "failed") {
           return { kind: "text", text: `The score failed (${job.error ?? "unknown"}) and was refunded. Poll again to retry, or pass soundtrack "none" to export without music.` };
         }
-        return { kind: "text", text: `Score still composing. Poll again in ~20s with {"film_id": "${filmId}", "action": "status", "music_job_id": "${musicJobId}"}.` };
+        return {
+          kind: "text",
+          text: `Score still composing. Poll again in ~20s with {"film_id": "${filmId}", "action": "status", "music_job_id": "${musicJobId}"}.`,
+          followUp: keepGoing(filmId, 20, { soundtrack, music_job_id: musicJobId })
+        };
       }
       const body = soundtrack === "scene-synced" ? buildScorePlanBody(film) : buildFlatMusicBody(film, all);
       const dispatch2 = await ctx.client.run("text-to-music", body);
-      return { kind: "text", text: `All ${all.length} clips ready \u2014 the ${soundtrack} score is composing (charged like any music generation). Poll again in ~20s with {"film_id": "${filmId}", "action": "status", "music_job_id": "${dispatch2.jobId}"}.` };
+      return {
+        kind: "text",
+        text: `All ${all.length} clips ready \u2014 the ${soundtrack} score is composing (charged like any music generation). Poll again in ~20s with {"film_id": "${filmId}", "action": "status", "music_job_id": "${dispatch2.jobId}"}.`,
+        followUp: keepGoing(filmId, 20, { soundtrack, music_job_id: dispatch2.jobId })
+      };
     }
-    await filmApi(ctx, "POST", `/api/films/${filmId}/export`, {});
-    return { kind: "text", text: `All clips ready \u2014 export started (${progressLine(film)}). Poll again in ~60s with action "status" for the finished film URL.` };
+    const exportError = await startExport();
+    if (exportError) return { kind: "text", text: `All clips ready, but the export could not start: ${exportError}` };
+    return {
+      kind: "text",
+      text: `All clips ready \u2014 export started (${progressLine(film)}). Poll again in ~60s with action "status" for the finished film URL.`,
+      followUp: keepGoing(filmId, 60, { soundtrack })
+    };
   }
   const failed = all.filter((sh) => sh.status === "failed");
   const refused = failed.filter(isRefused);
   const retrying = failed.filter((sh) => !isRefused(sh));
   const sentAgain = retrying.filter((sh) => resent.has(sh.id)).length;
-  const paused = refused.length > 0 && started === 0 && !all.some((sh) => sh.status === "frame-generating" || sh.status === "clip-generating");
-  const labels = new Map(film.scenes.flatMap((s, si) => s.shots.map((sh, i) => [sh.id, `${si + 1}.${i + 1}`])));
+  const rendering = all.some((sh) => sh.status === "frame-generating" || sh.status === "clip-generating");
+  const paused = refused.length > 0 && started === 0 && !rendering;
+  const moving = started > 0 || rendering;
+  const labels = shotLabels(film);
   const reason = (sh) => {
     const text = (sh.errorMessage ?? "no reason given").replace(/\s*Retry (?:the shot|it)\.\s*$/i, "");
     return text.length > 300 ? `${text.slice(0, 297)}...` : text;
@@ -1774,14 +1829,75 @@ It is saved in the Library folder "Film: ${film.title}".`
       `${paused ? "Paused" : "In progress"}: ${progressLine(film)}.`,
       refused.length > 0 ? `${one ? "Shot" : "Shots"} ${refused.map((sh) => labels.get(sh.id)).join(", ")} need${one ? "s" : ""} a new frame or prompt. The provider refused ${one ? "it" : "them"} (${reason(refused[0])}) and usually refuses the same input again, so status does not resend ${one ? "it" : "them"}: every retry is a charged render. Change ${one ? "it" : "them"} and render again at ${ctx.baseUrl}/film-studio/${filmId}.` : "",
       retrying.length > 0 ? `${retrying.length} shot(s) failed (${reason(retrying[0])}): ${sentAgain === retrying.length ? "sent again" : sentAgain > 0 ? `${sentAgain} sent again, the rest on a later poll` : "sent again on a later poll"}.` : "",
-      paused ? `Nothing else is rendering. Once the shot${one ? "" : "s"} render${one ? "s" : ""} again, call pixeldojo_film with {"film_id": "${filmId}", "action": "status"} to carry on.` : `Poll again in ~30s with {"film_id": "${filmId}", "action": "status"}.`
-    ].filter(Boolean).join("\n")
+      refusedStarts.length > 0 ? `${refusedStarts.length} render(s) could not start: ${refusedStarts[0]}` : "",
+      paused ? `Nothing else is rendering. Once the shot${one ? "" : "s"} render${one ? "s" : ""} again, call pixeldojo_film with {"film_id": "${filmId}", "action": "status"} to carry on.` : moving ? `Poll again in ~30s with {"film_id": "${filmId}", "action": "status"}.` : `Nothing is rendering. Fix what is above, then call pixeldojo_film with {"film_id": "${filmId}", "action": "status"} to carry on.`
+    ].filter(Boolean).join("\n"),
+    ...moving && !paused ? { followUp: keepGoing(filmId, 30, { soundtrack }) } : {}
+  };
+}
+function shotIndex(f) {
+  const all = shots(f);
+  if (all.length === 0 || all.length > 24) return "";
+  const labels = shotLabels(f);
+  let at = 0;
+  const clock = (sec) => `${Math.floor(sec / 60)}:${String(Math.round(sec % 60)).padStart(2, "0")}`;
+  const lines = all.map((sh) => {
+    const from = at;
+    at += sh.durationSec || 0;
+    const what = sh.prompt.replace(/\s+/g, " ").trim();
+    return `  ${labels.get(sh.id)} (about ${clock(from)}-${clock(at)}): ${what.length > 70 ? `${what.slice(0, 67)}...` : what}`;
+  });
+  return ['Shots (redo any with action "redo" and its label):', ...lines].join("\n");
+}
+async function redoShots(input, ctx) {
+  const filmId = input.film_id;
+  if (!input.shots?.length) {
+    return { kind: "text", text: 'Pass shots: the labels status reports, like ["2.3"] for scene 2, shot 3.' };
+  }
+  const { data } = await filmApi(ctx, "GET", `/api/films/${filmId}`);
+  const film = data.film;
+  if (!film) return { kind: "text", text: `Film not found: ${data.error ?? filmId}` };
+  const labels = shotLabels(film);
+  const byLabel = new Map(shots(film).map((sh) => [labels.get(sh.id), sh]));
+  const byId = new Map(shots(film).map((sh) => [sh.id, sh]));
+  const kind = input.redo;
+  const lines = [];
+  let started = 0;
+  let credits = 0;
+  for (const ref of Array.from(new Set(input.shots))) {
+    const sh = byLabel.get(ref) ?? byId.get(ref);
+    if (!sh) {
+      lines.push(`No shot ${ref} in this film (shots run 1.1 to ${Array.from(byLabel.keys()).pop()}).`);
+      continue;
+    }
+    const label = labels.get(sh.id);
+    if (kind === "clip" && !sh.frameUrl) {
+      lines.push(`Shot ${label} has no frame yet, so there is no clip to redo. Redo it with redo "frame".`);
+      continue;
+    }
+    const r = await filmApi(ctx, "POST", `/api/films/${filmId}/shots/${sh.id}/generate`, { kind });
+    if (r.status === 200) {
+      started += 1;
+      credits += r.data.creditCost ?? 0;
+      lines.push(`Shot ${label}: new ${kind} rendering${r.data.creditCost ? ` (${r.data.creditCost} credits)` : ""}.`);
+    } else {
+      lines.push(`Shot ${label}: could not start: ${r.data.error ?? `HTTP ${r.status}`}`);
+    }
+  }
+  if (started === 0) return { kind: "text", text: [...lines, "Nothing was started."].join("\n") };
+  return {
+    kind: "text",
+    text: [
+      ...lines,
+      `${credits ? `${credits} credits charged for the new take${started > 1 ? "s" : ""}. ` : ""}${kind === "frame" ? "Each new frame gets the Frame check, then a new clip. " : ""}The new take replaces the old one; keep calling pixeldojo_film with {"film_id": "${filmId}", "action": "status"}, which saves it and cuts a new export with it.`
+    ].join("\n"),
+    followUp: keepGoing(filmId, 30, { soundtrack: input.soundtrack })
   };
 }
 async function run8(input, ctx) {
   const action = input.action === "plan" && input.film_id ? input.cast?.length ? "cast" : "status" : input.action;
   if (action === "plan") return plan(input, ctx);
-  if (!input.film_id) return { kind: "text", text: "produce/status/cast need the film_id returned by the plan step." };
+  if (!input.film_id) return { kind: "text", text: "produce/status/cast/redo need the film_id returned by the plan step." };
   if (action === "cast") {
     if (!input.cast?.length) return { kind: "text", text: "Pass cast: [{ name, prompt | image_urls | character_id }] to cast characters (add replace: true to swap someone already cast, or remove: true to take them off)." };
     const { lines } = await applyCast(ctx, input.film_id, input.cast);
@@ -1794,10 +1910,11 @@ async function run8(input, ctx) {
       ].join("\n")
     };
   }
-  if (action === "produce") return produce(input.film_id, ctx);
+  if (action === "produce") return produce(input.film_id, input.soundtrack, ctx);
+  if (action === "redo") return redoShots(input, ctx);
   return advance(input.film_id, input.soundtrack, input.music_job_id, ctx);
 }
-var STORY_LOOKS, MUSIC_VIDEO_LOOKS, LOOKS, MUSIC_CLIP_ENGINE_ID, InputSchema8, InputJsonSchema8, shots, count, frameDone, RETRY_CLEARS, REFUSED, isRefused, PLANNER_POLL_MS, PLANNER_MAX_POLLS, isMusicVideo, needsSlice, stillPlanningText, LOOK_MUSIC, ARC, filmSkill;
+var STORY_LOOKS, MUSIC_VIDEO_LOOKS, LOOKS, MUSIC_CLIP_ENGINE_ID, InputSchema8, InputJsonSchema8, shots, benignDispatchRefusal, count, frameDone, RETRY_CLEARS, REFUSED, isRefused, PLANNER_POLL_MS, PLANNER_MAX_POLLS, isMusicVideo, needsSlice, stillPlanningText, LOOK_MUSIC, ARC, filmSkill;
 var init_film = __esm({
   "src/skills/film.ts"() {
     init_upload_helpers();
@@ -1815,8 +1932,10 @@ var init_film = __esm({
       lyrics: z.string().max(1e4).optional().describe("Music video mode: the song lyrics, so shots land on the right lines. Optional."),
       aspect: z.enum(["16:9", "9:16"]).default("16:9"),
       length: z.enum(["30s", "60s", "2-3min", "5min"]).default("60s").describe("Target length; drives the shot count (~6/12/24/60 shots)."),
-      film_id: z.string().max(40).optional().describe("Existing film id (from a previous call) for produce/status/cast."),
-      action: z.enum(["plan", "produce", "status", "cast"]).default("plan").describe("'plan' creates + storyboards (free). 'cast' casts, replaces or removes characters on an existing film. 'produce' starts charged generation. 'status' advances production and reports progress; poll it every ~30s until it returns the finished film."),
+      film_id: z.string().max(40).optional().describe("Existing film id (from a previous call) for produce/status/cast/redo."),
+      action: z.enum(["plan", "produce", "status", "cast", "redo"]).default("plan").describe("'plan' creates + storyboards (free). 'cast' casts, replaces or removes characters on an existing film. 'produce' starts charged generation. 'status' advances production and reports progress; poll it every ~30s until it returns the finished film. 'redo' renders a new take of the listed shots (charged), then status re-saves and re-exports."),
+      shots: z.array(z.string().trim().min(1).max(40)).min(1).max(12).optional().describe('Redo: the shots to render again, by the labels status reports ("2.3" is scene 2, shot 3) or shot id.'),
+      redo: z.enum(["clip", "frame"]).default("clip").describe("Redo: 'clip' (default) renders a new take of the clip from the same frame; 'frame' paints a new storyboard frame, then a new clip from it."),
       cast: z.array(
         z.object({
           name: z.string().trim().min(1).max(60),
@@ -1851,11 +1970,22 @@ var init_film = __esm({
         lyrics: { type: "string", description: "Plan step, music video mode (optional): the song lyrics, so shots land on the right lines." },
         aspect: { type: "string", enum: ["16:9", "9:16"], description: "Plan step: frame aspect ratio. Default 16:9." },
         length: { type: "string", enum: ["30s", "60s", "2-3min", "5min"], description: "Plan step: target length, which sets the shot count (~6/12/24/60 shots). Default 60s. Ignored for a music video, whose length is the song." },
-        film_id: { type: "string", description: 'The film_id returned by the plan step. Required for produce and status; with it, action "plan" is treated as "status".' },
+        film_id: { type: "string", description: 'The film_id returned by the plan step. Required for produce, status and redo; with it, action "plan" is treated as "status".' },
         action: {
           type: "string",
-          enum: ["plan", "produce", "status", "cast"],
-          description: "plan (default, free): writes the script and plans shots, returns film_id, a cost estimate, and any characters still to cast. cast: casts, replaces or removes characters on an existing film (pass film_id and cast). produce (charged): starts rendering frames; refused until every named character is cast. status: advances production one step and reports progress; call it every ~30s until it returns the finished film URL."
+          enum: ["plan", "produce", "status", "cast", "redo"],
+          description: "plan (default, free): writes the script and plans shots, returns film_id, a cost estimate, and any characters still to cast. cast: casts, replaces or removes characters on an existing film (pass film_id and cast). produce (charged): starts rendering frames; refused until every named character is cast. status: advances production one step and reports progress; call it every ~30s until it returns the finished film URL. redo (charged): renders a new take of the shots listed in `shots`, on a film in production or already finished; then call status, which saves the new take and cuts a new export with it."
+        },
+        shots: {
+          type: "array",
+          items: { type: "string" },
+          maxItems: 12,
+          description: 'Redo only: the shots to render again, by the labels status and the finished film report ("2.3" is scene 2, shot 3), or by shot id.'
+        },
+        redo: {
+          type: "string",
+          enum: ["clip", "frame"],
+          description: "Redo only: 'clip' (default) renders a new take of the clip from the same storyboard frame, the fix for a glitch, bad motion or lip sync. 'frame' paints a new frame first (and then a new clip from it), the fix for a wrong look, face or composition. Each is charged like any render of that shot. To change what a shot shows, edit it on the storyboard."
         },
         cast: {
           type: "array",
@@ -1895,6 +2025,7 @@ var init_film = __esm({
       }
     };
     shots = (f) => f.scenes.flatMap((s) => s.shots);
+    benignDispatchRefusal = (status2, error) => status2 === 429 || status2 === 409 && /already generating/i.test(error ?? "");
     count = (f, pred) => shots(f).filter(pred).length;
     frameDone = (sh) => Boolean(sh.frameUrl) && sh.status !== "idle" && sh.status !== "frame-generating";
     RETRY_CLEARS = /automatic audio check flagged|output audio\b[\s\S]*?sensitive information|temporarily unavailable/i;
@@ -1925,8 +2056,8 @@ var init_film = __esm({
     };
     filmSkill = {
       name: "pixeldojo_film",
-      description: "Make a finished short film from one idea: screenplay, storyboard frames (AI-reviewed), video clips with spoken dialogue, scene-synced soundtrack, stitched export. Or a music video: pass song_path (a local file) or song_url (your own PixelDojo upload from pixeldojo_upload, never a third-party link) with optional lyrics; the film is cut to that song, each clip lip-synced to its slice on the studio music video engine, and no score is composed: the export plays the song. Every named character must be cast (cast: your own images, a portrait prompt, or a Character Studio character) before frames render; cast entries can also replace or remove someone. Phased: plan is free; cast; produce starts charged generation; status advances production (poll every ~30s).",
-      hostedDescription: "Make a finished short film from one idea: screenplay, storyboard frames (AI-reviewed), video clips with spoken dialogue, scene-synced soundtrack, stitched export. Or a music video: pass song_url (your own PixelDojo upload made with POST /api/v1/upload, never a third-party link) with optional lyrics; the film is cut to that song, each clip lip-synced to its slice on the studio music video engine, and no score is composed: the export plays the song. Every named character must be cast (cast: your own images, a portrait prompt, or a Character Studio character) before frames render; cast entries can also replace or remove someone. Phased: plan is free; cast; produce starts charged generation; status advances production (poll every ~30s).",
+      description: "Make a finished short film from one idea: screenplay, storyboard frames (AI-reviewed), video clips with spoken dialogue, scene-synced soundtrack, stitched export. Or a music video: pass song_path (a local file) or song_url (your own PixelDojo upload from pixeldojo_upload, never a third-party link) with optional lyrics; the film is cut to that song, each clip lip-synced to its slice on the studio music video engine, and no score is composed: the export plays the song. Every named character must be cast (cast: your own images, a portrait prompt, or a Character Studio character) before frames render; cast entries can also replace or remove someone. Phased: plan is free; cast; produce starts charged generation; status advances production (poll every ~30s); redo renders a new take of chosen shots and status re-exports.",
+      hostedDescription: "Make a finished short film from one idea: screenplay, storyboard frames (AI-reviewed), video clips with spoken dialogue, scene-synced soundtrack, stitched export. Or a music video: pass song_url (your own PixelDojo upload made with POST /api/v1/upload, never a third-party link) with optional lyrics; the film is cut to that song, each clip lip-synced to its slice on the studio music video engine, and no score is composed: the export plays the song. Every named character must be cast (cast: your own images, a portrait prompt, or a Character Studio character) before frames render; cast entries can also replace or remove someone. Phased: plan is free; cast; produce starts charged generation; status advances production (poll every ~30s); redo renders a new take of chosen shots and status re-exports.",
       inputZod: InputSchema8,
       inputJsonSchema: InputJsonSchema8,
       allowedModels: [],
@@ -2140,7 +2271,7 @@ var init_video = __esm({
         },
         prompt: {
           type: "string",
-          description: "What to change, how the character should move, or what happens next. Required for change and extend. Optional for move (wan-video-character-swap ignores it)."
+          description: "What to change, how the character should move, or what happens next. Required for change and extend. Optional for move (wan-video-character-swap ignores it). @Name uses a character or element the user saved in Character Studio (photos attached automatically)."
         },
         video_url: {
           type: "string",
@@ -2743,7 +2874,7 @@ async function run13(input, ctx) {
   );
   return {
     kind: "handoff",
-    text: `Campaign ${result.campaignId}: ` + (stillRunning.length > 0 ? `${stillRunning.length} of ${result.subJobs?.length ?? 0} sub-jobs still ${stillRunning[0].status}. Wait a few seconds, then poll again.` : `aggregate state pending. Poll again shortly.`),
+    text: `Campaign ${result.campaignId}: ` + (result.progress ? `${result.progress}. Wait a few seconds, then poll again.` : stillRunning.length > 0 ? `${stillRunning.length} of ${result.subJobs?.length ?? 0} sub-jobs still ${stillRunning[0].status}. Wait a few seconds, then poll again.` : `aggregate state pending. Poll again shortly.`),
     jobId: result.campaignId,
     statusUrl: result.statusUrl ?? ctx.buildStatusUrl(result.campaignId)
   };
@@ -2923,6 +3054,26 @@ var init_audio = __esm({
   }
 });
 async function run16(input, ctx) {
+  if (input.source === "characters") {
+    const { characters } = await ctx.client.listCharacters({ q: input.q, limit: input.limit ?? 25 });
+    if (characters.length === 0) {
+      return {
+        kind: "text",
+        text: input.q ? `No saved character or element matches "${input.q}".` : "No saved characters or elements yet. Save one from photos with pixeldojo_save_character."
+      };
+    }
+    const lines2 = characters.map(
+      (c) => `- ${c.mention} (${c.kind})${c.description ? `: ${c.description.slice(0, 100)}` : ""}
+  images: ${c.image_urls.slice(0, 4).join(" ")}`
+    );
+    return {
+      kind: "text",
+      text: `${characters.length} saved character(s)/element(s):
+${lines2.join("\n")}
+
+Write the @Name in a pixeldojo_generate / pixeldojo_video / pixeldojo_edit prompt and their photos are attached automatically (models that take reference images).`
+    };
+  }
   const res = await ctx.client.listLibrary({
     q: input.q,
     model: input.model,
@@ -2957,6 +3108,7 @@ var InputSchema16, InputJsonSchema16, librarySkill;
 var init_library = __esm({
   "src/skills/library.ts"() {
     InputSchema16 = z.object({
+      source: z.enum(["media", "characters"]).optional().describe("media (default): saved and recent results. characters: saved Character Studio characters and elements, usable as @Name in prompts."),
       q: z.string().optional().describe("Substring match against the prompt that produced the asset."),
       model: z.string().optional().describe("Restrict to a single model (apiId)."),
       modality: z.enum(["image", "video", "audio"]).optional().describe("Restrict to one output type."),
@@ -2965,6 +3117,11 @@ var init_library = __esm({
     InputJsonSchema16 = {
       type: "object",
       properties: {
+        source: {
+          type: "string",
+          enum: ["media", "characters"],
+          description: "media (default): saved media and recent generations. characters: the saved Character Studio characters, products, outfits, locations, props and styles. Write @Name in any prompt to use one."
+        },
         q: {
           type: "string",
           description: "Substring match against the prompt that produced the asset. Omit to list the newest items."
@@ -2981,7 +3138,7 @@ var init_library = __esm({
     };
     librarySkill = {
       name: "pixeldojo_library",
-      description: "Search your Library: saved media (permanent) and recent API/MCP generations (deleted 1 hour after they finish), newest first. Returns asset URLs to reuse as reference inputs.",
+      description: "Search your Library, newest first. source=media (default): saved media (permanent) and recent API/MCP generations (deleted 1 hour after they finish), as URLs to reuse as references. source=characters: saved Character Studio characters and elements, each usable as @Name in any prompt.",
       inputZod: InputSchema16,
       inputJsonSchema: InputJsonSchema16,
       allowedModels: [],
@@ -2990,6 +3147,100 @@ var init_library = __esm({
     };
   }
 });
+async function run17(input, ctx) {
+  const res = await ctx.client.saveMedia({
+    url: input.url,
+    prompt: input.prompt,
+    tool_name: input.tool_name,
+    modality: input.modality,
+    job_id: input.job_id
+  });
+  return {
+    kind: "text",
+    text: `Saved to My Media (permanent): ${res.url}
+It will appear at https://pixeldojo.ai/my-images and in pixeldojo_library searches.`
+  };
+}
+var InputSchema17, InputJsonSchema17, saveSkill;
+var init_save = __esm({
+  "src/skills/save.ts"() {
+    InputSchema17 = z.object({
+      url: z.string().url().describe("The asset URL to save (image or video)."),
+      prompt: z.string().optional().describe("The prompt that produced it \u2014 makes it findable in the library later."),
+      tool_name: z.string().optional().describe("Tool/model slug that produced it."),
+      modality: z.enum(["image", "video", "audio"]).optional(),
+      job_id: z.string().optional().describe("The jobId that produced this asset, when known.")
+    });
+    InputJsonSchema17 = {
+      type: "object",
+      properties: {
+        url: { type: "string", format: "uri", description: "The result URL to keep (image or video from a PixelDojo job)." },
+        prompt: { type: "string", description: "The prompt that produced it, so it is findable in the library later." },
+        tool_name: { type: "string", description: "Model apiId that produced it, when known." },
+        modality: { type: "string", enum: ["image", "video", "audio"], description: "Output type, when the URL does not make it obvious." },
+        job_id: { type: "string", description: "The jobId that produced it, when known." }
+      },
+      required: ["url"]
+    };
+    saveSkill = {
+      name: "pixeldojo_save",
+      description: `Save a generated image or video into the user's My Media library permanently ("save this", "keep it"). Results otherwise expire 1 hour after they finish. Pass the result URL; it is safety-checked before it is kept.`,
+      inputZod: InputSchema17,
+      inputJsonSchema: InputJsonSchema17,
+      allowedModels: [],
+      defaultModel: "",
+      run: run17
+    };
+  }
+});
+async function run18(input, ctx) {
+  const res = await ctx.client.saveCharacter({
+    name: input.name,
+    kind: input.kind ?? "character",
+    image_urls: input.image_urls,
+    description: input.description
+  });
+  return {
+    kind: "text",
+    text: `Saved ${res.kind} "${res.name}" to Character Studio (${res.image_urls.length} image${res.image_urls.length === 1 ? "" : "s"}). Use it in any prompt as ${res.mention}, for example "${res.mention} walking on a beach at sunset". It also appears at https://pixeldojo.ai/characters.`
+  };
+}
+var KINDS, InputSchema18, InputJsonSchema18, saveCharacterSkill;
+var init_save_character = __esm({
+  "src/skills/save-character.ts"() {
+    KINDS = ["character", "product", "outfit", "location", "object", "style"];
+    InputSchema18 = z.object({
+      name: z.string().min(1).max(60).describe("What to call it. Used as @Name in prompts."),
+      kind: z.enum(KINDS).optional().describe("Default character."),
+      image_urls: z.array(z.string().url()).max(8).optional().describe("3 to 5 photos from different angles works best for a character."),
+      description: z.string().max(1500).optional().describe("Appearance notes, or the scene text for an element.")
+    });
+    InputJsonSchema18 = {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "What to call it. Used as @Name in prompts afterwards." },
+        kind: { type: "string", enum: KINDS, description: "character (default), product, outfit, location, object (a prop) or style." },
+        image_urls: {
+          type: "array",
+          items: { type: "string", format: "uri" },
+          maxItems: 8,
+          description: "Photos of it. For a person, 3 to 5 clear photos from different angles. Required for a character."
+        },
+        description: { type: "string", description: "Optional appearance notes, or the scene text for an element without photos." }
+      },
+      required: ["name"]
+    };
+    saveCharacterSkill = {
+      name: "pixeldojo_save_character",
+      description: "Save a character (a person, from 3-5 photos) or an element (product, outfit, location, prop, style) to the user's Character Studio library. Afterwards write @Name in any prompt to use it. List saved ones with pixeldojo_library source=characters.",
+      inputZod: InputSchema18,
+      inputJsonSchema: InputJsonSchema18,
+      allowedModels: [],
+      defaultModel: "",
+      run: run18
+    };
+  }
+});
 function substitutePlaceholders(args, inputs, prevUrl) {
   const missing = [];
   const fill = (value) => {
@@ -3246,6 +3497,8 @@ __export(skills_exports, {
   librarySkill: () => librarySkill,
   listWorkflowsSkill: () => listWorkflowsSkill,
   runWorkflowSkill: () => runWorkflowSkill,
+  saveCharacterSkill: () => saveCharacterSkill,
+  saveSkill: () => saveSkill,
   saveWorkflowSkill: () => saveWorkflowSkill,
   statusSkill: () => statusSkill,
   storyboardSkill: () => storyboardSkill,
@@ -3291,6 +3544,8 @@ var init_skills = __esm({
     init_upload();
     init_audio();
     init_library();
+    init_save();
+    init_save_character();
     init_workflows();
     ALL_SKILLS = [
       generateSkill,
@@ -3300,6 +3555,8 @@ var init_skills = __esm({
       upscaleSkill,
       audioSkill,
       librarySkill,
+      saveSkill,
+      saveCharacterSkill,
       saveWorkflowSkill,
       runWorkflowSkill,
       listWorkflowsSkill,
@@ -3347,6 +3604,8 @@ var init_skills = __esm({
       pixeldojo_status: read("Check job status"),
       pixeldojo_campaign_status: read("Check campaign status"),
       pixeldojo_library: read("Search media library"),
+      pixeldojo_save: render("Save to My Media"),
+      pixeldojo_save_character: render("Save character or element"),
       pixeldojo_list_workflows: read("List saved workflows"),
       pixeldojo_from_url: { ...read("Read product page"), openWorldHint: true }
     };
@@ -3403,8 +3662,8 @@ function makeRedactedLogger(target = console) {
 }
 
 // src/server.ts
-var PACKAGE_VERSION = "0.18.0" ;
-var SERVER_INSTRUCTIONS = "PixelDojo generates images, video, audio and short films across 100+ models, billed in credits from the connected PixelDojo account. A job that runs past the 30-second wait returns a jobId to check later; check it rather than submitting again, since every new submission is charged. Generated asset URLs are deleted one hour after they are created, so download anything the user wants to keep. Finished films are the exception and stay in the account library.";
+var PACKAGE_VERSION = "0.19.0" ;
+var SERVER_INSTRUCTIONS = "Pixel Dojo generates images, video, audio and short films from one catalog of AI models, billed in credits from the connected Pixel Dojo account. A job that runs past the 30-second wait returns a jobId to check later; check it rather than submitting again, since every new submission is charged. Generated asset URLs are deleted one hour after they are created: pixeldojo_save keeps one in the user's My Media permanently (after a safety check), and finished films stay in the account library. In any prompt, @Name uses a character, product, outfit, location, prop or style the user saved in Character Studio: its photos are attached automatically. pixeldojo_library source=characters lists them, and pixeldojo_save_character saves a new one from 3 to 5 photos.";
 function buildServer(options) {
   if (!options.apiKey) {
     throw new Error(