fix: address 9 agent UX issues from end-to-end feedback#15
Merged
Conversation
- Add shebang validity and ffmpeg filter checks to doctor - Validate ffmpeg filter availability for text/animate ops - Add minimal EDL example and required_fields to capabilities - Support named step references ($name) alongside positional ($N) - Clamp trim end times within 50ms tolerance instead of hard error - Warn on resolution mismatch in concat segments - Warn when animate keyframe t falls outside layer window - Standardize thumbnail --time flag (--at kept as alias) - Context-aware FFMPEG_FAILED recovery hints (filter/codec/path) Co-authored-by: Cursor <cursoragent@cursor.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Addresses all 9 issues from the AI-agent end-to-end feedback report. Changes span 7 files across the doctor, validation, engine, models, ffmpeg, and CLI layers.
Why
An AI agent used cutagent to build a 15s family highlight reel and reported specific friction points — stale shebang noise, missing filter validation, undiscoverable EDL format, fragile positional references, sub-ms trim precision errors, silent resolution mismatches, inconsistent flags, generic error hints, and undocumented absolute keyframe timing.
How
Issue 1 — Stale shebang (Critical):
doctor.pynow checks the cutagent script shebang and reports if the interpreter path is missing, with recovery hints.Issue 2 — Filter availability (High):
validation.pywarns when text/animate ops require ffmpeg filters (e.g. drawtext) that aren't available.doctor.pynow checks for drawtext, subtitles, overlay, and scale filters.Issue 3 — EDL discoverability (Medium):
capabilitiesoutput now includesrequired_fields,minimal_example, andnamed_reference_examplein theedl_formatsection.Issue 4 — Named step references (Medium): All 13 operation dataclasses gain an optional
idfield. Engine and validation support$namereferences alongside$Nand$input.N. Duplicate IDs produce warnings.Issue 5 — Trim precision (Medium): Trim end times within 50ms of duration are clamped silently (with warning) instead of producing a hard error, in both validation and execution.
Issue 6 — Resolution mismatch (Medium): Validation warns when concat segments have different resolutions, reporting the detected sizes and expected output dimensions.
Issue 7 — Thumbnail flags (Low):
--timeis now the primary flag (matching probe/summarize/scenes), with--atkept as backward-compatible alias.-oremains as alias for--output.Issue 8 — FFMPEG_FAILED hints (Low): Recovery hints are now context-aware — detecting "No such filter", codec errors, file-not-found, and permission issues in stderr.
Issue 9 — Keyframe timing (Low): Validation warns when animate keyframe
tvalues fall outside the layer's[start, end]window, with a note that t is absolute timeline time.Checklist
pytest) — 231 passed, 28 skippedMade with Cursor