@starreel/mcp 0.1.206 → 0.1.208

package/SKILL.md

@@ -543,6 +543,12 @@ content that will be rejected.
    `review_frames` flags the two actionable states as `seam_unchained` / `seam_broken`
    (warnings — they do not block `generate_videos`, but this is the cheapest point to fix
    them: the video is generated from the first frame).
+   Joined seams can still jump when the same subject sits on opposite sides of the frame,
+   moves in opposite directions, or the shot size leaps several steps. Optional, before videos:
+   `audit_seam_directions` (`dry_run` first — quote, billed by text tokens; advisory,
+   never blocks) compares each previous last frame with the next first frame; read the
+   results with `get_seam_directions` (also summarised in `review_frames` as
+   `seam_direction_advisory`) and let the customer pick which seams to fix.
    **Image model**: images use a drama-level model (default **ChatGPT Image 2.5
    Flare** = `gpt-image-2.5-flare`), set via `create_drama` /
    `update_project_settings` field `image_model` for one consistent look across
@@ -635,6 +641,19 @@ content that will be rejected.
    `upload_shot_frame` is for art the customer already owns — the one exception is
    a **local touch-up of this shot's own platform candidate** (option 2 below).
 
+   **Only a small part of the frame is wrong?** (a face, an open mouth, a fringe of
+   halo pixels, a stray object) — use `quote_local_frame_edit` → `local_frame_edit`
+   instead of redrawing the whole frame or fixing it in an outside tool. Box the area
+   with normalized `regions` (≤ 40% of the frame) and say what it should become; the
+   platform pastes only that area back onto the original, so everything outside the
+   box stays pixel-identical. Face/mouth edits need `character_id` (only that
+   character's portrait is sent as the identity anchor) and are re-audited for
+   identity. Results are **candidates, not the new frame**: show `composited_url`
+   from `get_local_frame_edit` to the customer, then `adopt_local_frame_edit` the one
+   they pick. Each candidate is charged; candidates the platform rejects are **not
+   refunded** — tell the customer that with the quote. Rolled out per drama: a 403
+   `LOCAL_FRAME_EDIT_UNAVAILABLE` means fall back to `generate_shot_frame`.
+
    **When a shot frame fails, offer the customer three choices** (both
    `get_frame_candidates` and `get_frame_retry_diagnosis` return them as
    `recovery_options`, ordered free → free → paid; `needs_attention=false` means

package/dist/i18n/tools.en.json

@@ -42,7 +42,7 @@
   "get_health_report": "(★Recommended · free diagnosis) Read storyboards and output a health report: overlong duration / insufficient motif coverage / problematic shots. Read-only, free. Check before image generation; identify issues, fix first, and avoid discovering them only after the film is produced.",
   "review_script": "【Hard Gate ① · Free】Review the AI rewritten script: dialogue line length, completeness of emotional turns, opening hook, final-scene cliffhanger. ★Before extract_assets and generate_storyboards, this tool must run first—character profiles and storyboards are derived from the rewritten script; issues in the script will be amplified layer by layer into character sheets / image generation / video generation, and discovering them at final cut means redoing the whole episode. Tell the client each item in findings one by one, fix by action (use edit_rewritten_script for script edits), then re-review and proceed with the review_token.\n★【Agent manual QC · Free】The returned agent_qc contains this-layer checklist and the episode materials to inspect (materials, each with a ref; images/videos include links). The platform only judges “exists / present / rejected”; “looks alike / correct / good” must be checked by you: download and open images, sample at least beginning/middle/end frames for videos, read text through with tools. Answer each checklist item (ok / issue / na; for issue, specify which item and what problem), list every inspected ref in inspected, and call submit_qc_report to submit; relay the QC conclusion to the client verbatim. If agent_qc.required=true and no report is submitted, this review_token cannot enter the next step (400 agent_qc_required); a problematic report blocks by default just like a platform error.\n★【Script evaluation and suggestions】materials contains the client original script (script:original) and the rewritten script (script): first evaluate the client’s script itself (mainline, motivation, conflict, pacing, plot holes, filmability), then check the rewritten script; for each issue, provide concrete fixes in submit_qc_report suggestions (if wording can be directly changed, provide before/after). After submission, tell the client the evaluation and suggestions item by item and let the client choose: adopt some / execute all directly / continue without changes (which path to take follows the execution mode: professional mode / unconfirmed plan / this stage controlled by client → tell the client and proceed only after client approval; do not decide for the client; if this stage is autopiloted → do not ask the client, execute according to get_production_plan autopilot.default_decisions, and the platform records it in get_autopilot_log); autopiloted stages by default execute only priority=must items that do not change the client’s original dialogue; all others go into the delivery report. ★[Customer acceptance items] review_frames / review_videos append the customer's registered specific requirements (add_acceptance_criteria) to the checklist (ids start with req:) together with acceptance_criteria: the platform's generic review does not know these requirements, so passing it does not mean they are met. Check each one with your own eyes, answer it in submit_qc_report, tell the customer the result, and let the customer confirm via confirm_acceptance_criterion.",
   "review_storyboards": "【Hard gate ② · free】Review storyboards: forbidden terms (will be rejected by vendors and waste credits), shot duration distribution, repeated adjacent composition, character blocking drift in the same scene, emotional curve peaks/valleys, key-shot markers. ★Must run this tool before generate_frames—storyboard issues become a whole episode of wasted images once generated and cannot be fixed shot by shot. Fix per findings.action using update_shot/split_shot, then review again. ★A finding with code=forbidden_term includes `terms` (specific matched terms, e.g. \"background music\", \"strong light\") and `shots` (shot numbers); use those two to update_shot and remove them, no need to guess word by word. ★Forbidden terms are judged with **negative semantics**: writing \"no background music\" or \"do not add music\" is not a violation (it is obeying the constraint), so no edit is needed. ★\"Action overload\" in warnings (action_overload, advisory only, non-blocking): one shot contains more independent actions than its duration can support; before video generation, use split_shot to split it or delete actions—slow motion/dissolves cannot rescue it after final cut. Ignore if multiple people each do one thing or it is a naturally continuous action chain.\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors. ★[Customer acceptance items] review_frames / review_videos append the customer's registered specific requirements (add_acceptance_criteria) to the checklist (ids start with req:) together with acceptance_criteria: the platform's generic review does not know these requirements, so passing it does not mean they are met. Check each one with your own eyes, answer it in submit_qc_report, tell the customer the result, and let the customer confirm via confirm_acceptance_criterion.",
-  "review_frames": "【Hard gate ③ · free】Review the shot image layer: character identity-anchor coverage (characters without character sheets will drift in shots), image-generation failure rate, orphan character variants, scene images polluted by people. ★Must run this tool before generate_videos—video generation is the most expensive step in the whole chain, and generating a whole episode of video from drifting first frames is the most typical wasted-film failure. Fix per findings.action (mostly generate_character_portraits / generate_shot_frame single-shot regeneration), then review again. ★Also reports **inter-shot seams** (warning, non-blocking): code=seam_unchained (marked continuous but never did first/last-frame chaining, or initiated chained regeneration never landed / first frame was regenerated again after chaining) / seam_broken (chained but not connected, or previous shot's last frame was regenerated after chaining); shots is the shot whose \"seam with previous shot\" has the issue. Cheapest to fix before video generation—videos are generated from first frames; if a first frame does not match the previous shot's last frame, the final cut has a jump cut. See action for fixes (whole episode chain_frames dry_run first; single seam chain_shot_from_prev / chain_shot_from).\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors. ★[Customer acceptance items] review_frames / review_videos append the customer's registered specific requirements (add_acceptance_criteria) to the checklist (ids start with req:) together with acceptance_criteria: the platform's generic review does not know these requirements, so passing it does not mean they are met. Check each one with your own eyes, answer it in submit_qc_report, tell the customer the result, and let the customer confirm via confirm_acceptance_criterion.",
+  "review_frames": "【Hard gate ③ · free】Review the shot image layer: character identity-anchor coverage (characters without character sheets will drift in shots), image-generation failure rate, orphan character variants, scene images polluted by people. ★Must run this tool before generate_videos—video generation is the most expensive step in the whole chain, and generating a whole episode of video from drifting first frames is the most typical wasted-film failure. Fix per findings.action (mostly generate_character_portraits / generate_shot_frame single-shot regeneration), then review again. ★Also reports **inter-shot seams** (warning, non-blocking): code=seam_unchained (marked continuous but never did first/last-frame chaining, or initiated chained regeneration never landed / first frame was regenerated again after chaining) / seam_broken (chained but not connected, or previous shot's last frame was regenerated after chaining); shots is the shot whose \"seam with previous shot\" has the issue. Cheapest to fix before video generation—videos are generated from first frames; if a first frame does not match the previous shot's last frame, the final cut has a jump cut. See action for fixes (whole episode chain_frames dry_run first; single seam chain_shot_from_prev / chain_shot_from).\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors. ★[Customer acceptance items] review_frames / review_videos append the customer's registered specific requirements (add_acceptance_criteria) to the checklist (ids start with req:) together with acceptance_criteria: the platform's generic review does not know these requirements, so passing it does not mean they are met. Check each one with your own eyes, answer it in submit_qc_report, tell the customer the result, and let the customer confirm via confirm_acceptance_criterion. ★When there are adjacent shots, the response also carries seam_direction_advisory (advisory, does not affect review_token): existing results of the adjacent-shot direction check (subject side jump/reversed motion/shot-size jump); seams not yet observed need audit_seam_directions dry_run for a quote first, and run only after the client agrees.",
   "review_assets": "【Asset-layer hard gate · free】Review character appearance images, scene images, and prop images used **on screen** in this episode—coverage and quality: on-screen character missing character sheet / missing reference image / still generating / generation failed / reference image rejected by consistency gate (hint includes rejection reason); scene missing empty-scene base plate; prop referenced by storyboard missing prop image / rejected; prop image conflicts with this shot's era/form; missing color script (warning). ★Call once after producing character sheets, reference images, scene images, and prop images; must review before generate_frames / generate_shot_frame—pass the returned review_token as **asset_review_token**, together with the storyboard-layer review_token (both are required). Only checks the assets themselves: generating shot images later will not invalidate it; changing character sheets / scene images / prop images will invalidate it, just review again (free, seconds). Explain findings to the customer one by one (code=issue type, names=which character/scene/prop, shots=affected shot numbers, action=which tool to call to fix).\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors. ★[Customer acceptance items] review_frames / review_videos append the customer's registered specific requirements (add_acceptance_criteria) to the checklist (ids start with req:) together with acceptance_criteria: the platform's generic review does not know these requirements, so passing it does not mean they are met. Check each one with your own eyes, answer it in submit_qc_report, tell the customer the result, and let the customer confirm via confirm_acceptance_criterion.",
   "review_videos": "【Video and dubbing-layer hard gate · free】Review this episode's videos and dubbing—coverage and quality: missing video / still generating / generation failed / vendor rejected; first frame changed but video was generated from an old frame (video_stale); suspected hard cut at clip end, unexpected human voice in no-dialogue shots (warning); dubbed drama: dialogue shot missing dubbing, speaking character has no voice, missing narrator role; original-audio drama: shots not attached to current voice line at export time, characters without locked voice lines; missing music (warning). ★Call once after video, dubbing (generate_tts), and music are produced; must review before compose_episode, passing the returned review_token. Finer checks (requiring decoding picture/audio tracks) are available via scan_intra_shot_cuts / scan_dialogue_coverage / audit_silent_shot_audio; after assembling the final cut, run review_final_cut.\n★★【Pre-compose checks · after review_videos passes, before compose_episode】Don't hunt for problems by repeatedly exporting the whole cut and trying transitions by hand — per-shot and seam problems have dedicated tools; run them in order before stitching: ① portraits / turnarounds / scene images / shot frames were changed in this episode → first get_stale_portrait_frames(episode_id, free) to see which shots' in-use frames are still based on old assets; for shots where it is unclear which version to use, get_asset_versions(storyboard_id, free) shows each shot's versions and dependencies (unknown means insufficient evidence, not stale; regenerating is paid, so give the list to the customer and let them decide); ② scan_intra_shot_cuts(episode_id, free) finds shots where the vendor hard-cut inside a single shot; ③ per shot, recommend_trim_window(storyboard_id, free) shows a frozen tail and the effective action window (shots inside a scene group return applicable=false — skip them); apply a recommendation with trim_shot (free); ④ audit_seams(episode_id) checks editing continuity at seams between adjacent shots: by default dry_run only lists what would be audited (free); actually running it is billed by real text-token usage — tell the customer, and only after they explicitly accept pass dry_run:false + confirm_usage_billing:true; read the result from seam_review in get_storyboards; ⑤ then compose_episode. If the final cut shows jump cuts / dragging tails / seams that don't match, go back to these tools to locate the shots and fix only those — don't keep re-exporting the whole cut by trial and error. These checks are advisory, not gates; trimming and seam audits don't invalidate the review_videos token. The response's pre_compose_checks carries the same list in structured form (tool/scope/when/cost per item).\n★【Agent hands-on QC · free】Returned agent_qc contains this layer's checklist and materials to inspect for this episode (materials, each with a ref; images/videos include links). The platform only checks \"exists / present / rejected\"; \"looks like / is correct / is good\" must be judged by you: download and open images, sample at least beginning/middle/end frames for videos, read text fully with tools. Answer checklist items one by one (ok / issue / na; for issue, state which item has what problem), list every inspected ref in inspected, and call submit_qc_report; tell the customer the QC conclusion verbatim. When agent_qc.required=true, without a submitted report this review_token cannot proceed to the next step (400 agent_qc_required); issues in the report block by default just like platform errors. ★If the response includes post_production_advisory = narrative-required effects that the script marks as post-production are still unhandled (the platform will not composite them): tell the client verbatim and use get_post_production_checklist to see the list. ★[Customer acceptance items] review_frames / review_videos append the customer's registered specific requirements (add_acceptance_criteria) to the checklist (ids start with req:) together with acceptance_criteria: the platform's generic review does not know these requirements, so passing it does not mean they are met. Check each one with your own eyes, answer it in submit_qc_report, tell the customer the result, and let the customer confirm via confirm_acceptance_criterion.",
   "submit_qc_report": "Submit the QC report made by you (agent) after personally inspecting materials. Free. First call the corresponding review_* layer (script / storyboards / assets / frames / videos), open each returned agent_qc material in materials, answer every checklist item, then call this tool. ★The platform only verifies the report is **complete**, not whether your conclusions are correct: every checklist id must be answered (ok / issue / na; issue must include note explaining which item has what problem); every ref in materials must be listed in inspected (omit one and it is rejected with the missing refs named); if there are issues, set verdict=issues and list them in issues; reporting pass when issues exist will be rejected. ★Do not go through the motions: listing something in inspected without opening it means you signed off for the customer—wasted output will still be charged. ★When verdict=issues, this token cannot proceed to the next step by default: explain the problems to the customer, fix, then review + QC again; only if the customer is clearly informed and insists on proceeding as-is should the next step include acknowledge_review:true. ★suggestions (change suggestions): required at script layer when agent_qc.suggestions_required=true and issues were reported; optional for other layers. Each item includes problem + proposal; if text can be directly changed, also provide before/after; the response assigns each suggestion an id (s1…). Explain suggestions to the customer; the customer chooses accept some / execute all directly / proceed without changes (which route; autopilot = only execute priority=must suggestions that do not change the customer's original lines per execution mode: professional mode / unconfirmed plan / this step customer-controlled → explain to customer and only proceed after approval; do not decide for the customer. This step autopilot → do not ask customer; follow get_production_plan autopilot.default_decisions, recorded by the platform in get_autopilot_log). If content changes after the review, the report will be rejected; review again and QC against the new agent_qc.",
@@ -250,5 +250,11 @@
   "add_acceptance_criteria": "Register customer acceptance items (free): when the customer states a **specific requirement** for a shot or the whole episode (identity, wardrobe, prop color, lip sync, visual artifacts, etc.), record it in the customer's own words. review_frames / review_videos will then append it to agent_qc.checklist (ids start with req:) for you to check item by item, and the result is recorded separately. ★One requirement per item; for a shot use shot_number (current shot number) or storyboard_id, omit both for the whole episode. Registering invalidates review_tokens already issued for that stage — re-review. ★Only register what the customer actually said; never invent requirements.",
   "update_acceptance_criterion": "Edit a customer acceptance item (free). Changing the text / category / shot / stages resets all three states of that item (the requirement changed, old conclusions no longer count); re-run the review to check it. To delete, use delete_acceptance_criterion. item_id comes from get_acceptance_criteria. (Editing customer acceptance items requires explicit client consent in every execution mode, including autopilot.)",
   "confirm_acceptance_criterion": "Record the **customer's own** confirmation of an acceptance item (free): accepted / rejected / pending (undo). Only the client state is written; the platform auto review and your QC conclusion are untouched. ★Call it only after the customer has explicitly stated their decision, with confirm_client_statement:true; you must never confirm on the customer's behalf, autopilot included.",
-  "delete_acceptance_criterion": "Delete a customer acceptance item (free; its three states go with it). item_id comes from get_acceptance_criteria. (Deleting customer acceptance items requires explicit client consent in every execution mode, including autopilot.)"
+  "delete_acceptance_criterion": "Delete a customer acceptance item (free; its three states go with it). item_id comes from get_acceptance_criteria. (Deleting customer acceptance items requires explicit client consent in every execution mode, including autopilot.)",
+  "quote_local_frame_edit": "Quote: how many credits a **local edit of one frame of one shot** costs (fix a face, close a mouth, clean halo edges, remove a stray object). Zero cost. Use it when the customer only wants a small part of the image changed — do not edit it in an outside image tool and upload_shot_frame it back: outside tools also change details the customer already approved, bypass the identity anchors and audits, and break the provenance chain. To redraw the whole frame use quote_shot_frame / generate_shot_frame. The platform pastes the edited area back onto the original through a feathered mask: pixels outside the boxes stay unchanged. ★Billing: each candidate is charged as one image (unit_points × candidates; the image count is fixed, so estimated_points is the actual charge and equals typical_points). **Candidates rejected by the platform checks (visible seam, edit not applied, identity audit failed) are never refunded** — tell the customer this together with the points. Vendor failures are refunded automatically. ★Only available for dramas in the rollout; otherwise 403 LOCAL_FRAME_EDIT_UNAVAILABLE (fall back to generate_shot_frame). Face edits without character_id → 400 CHARACTER_REQUIRED; character without a portrait → 400 CHARACTER_NO_PORTRAIT.",
+  "local_frame_edit": "After confirmation, **locally edit one frame of one shot** (async, charged). Parameters must equal the quote_local_frame_edit call exactly (any change to regions / instruction / kind / character / candidates / base image → 409 QUOTE_PARAMS_CHANGED; re-quote for free). Returns edit_id; poll with get_local_frame_edit. ★**It never replaces the current frame automatically**: show the candidates (composited_url) to the customer first; only adopt_local_frame_edit writes the chosen one into the shot and marks the shot video as needing regeneration. ★Rejected candidates are charged and not refunded. Requires the review_storyboards review_token (and asset_review_token on rollout dramas), same as generate_shot_frame.",
+  "get_local_frame_edit": "Check progress and results of a local frame edit (free). status=running → keep waiting; when completed, look at each candidate: composited_url (the result pasted back onto the original — show this to the customer), verdict (pass = usable; warn = usable but needs a human look — REGION_SEAM_WARN possible seam / EDIT_NOT_APPLIED barely changed / IDENTITY_AUDIT_UNAVAILABLE identity not audited; reject = not recommended — REGION_MISALIGNED misaligned paste / IDENTITY_AUDIT_REJECTED does not look like the character), metrics, identity_audit. Download and look at composited_url yourself, tell the customer, then adopt_local_frame_edit the one they pick. Rejected candidates are not refunded.",
+  "adopt_local_frame_edit": "Adopt a local-edit candidate as this shot's current frame (free). Same follow-up as an uploaded frame: the shot video is marked for regeneration and adjacent seams are repaired. ★Only after the customer has looked and chosen. If the frame changed after the edit → 409 BASE_FRAME_CHANGED (start a new edit on the current frame); verdict=reject candidates are refused by default (409 CANDIDATE_REJECTED) — pass accept_rejected:true only when the customer insists after seeing it.",
+  "audit_seam_directions": "Pre-video seam direction check (advisory, never blocks any step): for every pair of adjacent shots, compares \"previous shot's last frame (or first frame if none) ↔ this shot's first frame\" for the same subject jumping left/right sides of the frame (a reversed eyeline is noted with it), reversed motion direction, and shot-size jumps (same subject, extreme long ↔ close-up). Eyeline alone and key-light direction are observed but not reported: production replay showed too many false positives on those (better to miss than to nag). Shots that look fine alone but jump when cut together usually fail on these. Complements audit_seams, which checks identity/wardrobe/props/object state but not direction or position. ★When: after first frames (and needed last frames) are done and chain_frames has run, before review_frames / generate_videos. Scene changes, declared jump cuts, insert shots and title/black cards are skipped automatically. ★dry_run first (default, free): returns the seams to observe plus estimated_points (upper bound) and typical_points (usual cost); tell the client both — billed by actual text tokens. After the client agrees, pass dry_run=false + confirm_usage_billing=true. Execution is asynchronous and returns immediately; read results with get_seam_directions a minute or two later. Seams already observed with unchanged frames are not billed again.",
+  "get_seam_directions": "(Free) Read audit_seam_directions results: each issue gives the seam shot numbers, the problem (subject jumps sides, reversed motion, shot-size jump) and fixes (chain_shot_from mode=reframe to regenerate this shot's first frame anchored on the previous last frame / update_shot to state facing then generate_shot_frame / align_prev_shot when the previous shot already has video / split_shot to insert an intermediate shot size). Results are advisory: explain them to the client and let the client pick which to fix; intentional reverse shots, turns or impact cuts can be ignored. not_audited>0 = seams not observed yet or frames changed since; running=true = still running. review_frames' seam_direction_advisory is a summary of the same results. This tool only looks at pre-video still frames; after videos are generated, check seams with preview_seams (free short-clip previews)."
 }