fix(media): validate upload paths before generation

[j15z]

Summary

Media generation now accepts chat-scoped uploads/... paths as inputs, keeps outputs restricted to files/..., and reports invalid or missing paths before starting provider work. Previously, an uploaded reference could be silently dropped and leave the user with a generic generated subject.

The shared path boundary applies consistently to image, video, audio, and FFmpeg tools. Image generation also lets reference-loading failures reach the caller instead of catching and skipping them locally.

Related: https://github.com/simstudioai/mothership/pull/352

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation
• Other: ___________

Testing

• 30 focused tests passed across image generation, media path validation, media tool preflight behavior, and upload-file reading.
• bun run scripts/sync-tool-catalog.ts --check --input=../mothership/copilot/contracts/tool-catalog-v1.json
• The repository-wide typecheck still reports a pre-existing unrelated error in apps/sim/providers/meta/index.ts:122.

Reviewers should focus on the input/output path boundary and the guarantee that validation occurs before paid Gemini, Fal, or FFmpeg work begins.

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

Screenshots/Videos

Not applicable; this is server-side validation and generated tool-contract behavior.

---

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Jul 12, 2026 2:42am

[cursor]

PR Summary

Medium Risk
Touches paid media generation and workspace write policy; behavior change (required outputs, stricter inputs) can break callers that relied on implicit defaults or silently dropped references.

Overview
Media tools (image, video, audio, ffmpeg) now share file-paths helpers that resolve uploads/... chat attachments and files/... workspace paths, require an explicit outputs.files target under files/, and fail fast on missing inputs, invalid outputs, or wrong file counts—before Gemini, Fal, or ffmpeg runs.

resolveChatUpload wires chat uploads into the same record shape as workspace files. Image generation no longer skips unresolved reference images; those errors surface to the caller. Default auto-generated output paths and optional sandbox-mount inputs/outputs shapes are removed from the generated tool catalog/schemas so the model must declare concrete VFS paths.

^{Reviewed by Cursor Bugbot for commit 7c321ca. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Greptile Summary

This PR tightens media tool path handling for generated outputs and uploaded inputs. The main changes are:

• Shared validation for media input and output paths.
• Explicit output declarations for generated image, video, and audio tools.
• Chat-scoped uploads/... support for media inputs.
• Early output validation before Gemini, Fal, or FFmpeg work starts.
• ffmpeg probe behavior that skips unused output validation.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
apps/sim/lib/copilot/tools/server/media/file-paths.ts	Adds shared helpers for media input resolution and output validation.
apps/sim/lib/copilot/tools/server/media/ffmpeg.ts	Validates declared outputs before non-probe operations and lets probe return metadata without output validation.
apps/sim/lib/copilot/tools/server/image/generate-image.ts	Validates output paths before image generation and resolves declared reference files through the shared media helper.
apps/sim/lib/copilot/tools/server/media/generate-audio.ts	Validates output paths before audio generation and resolves an optional voice sample through the shared media helper.
apps/sim/lib/copilot/tools/server/media/generate-video.ts	Validates output paths before video generation and resolves an optional start-frame input through the shared media helper.
apps/sim/lib/copilot/generated/tool-catalog-v1.ts	Updates generated tool metadata for the new media input and output path boundary.
apps/sim/lib/copilot/generated/tool-schemas-v1.ts	Updates generated runtime schemas for explicit media outputs and constrained file declarations.

_{Reviews (2): Last reviewed commit: "fix(media): preflight all writable outpu..." | Re-trigger Greptile}

[j15z]

@greptile

[j15z]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 7c321ca. Configure here.}