fix(copilot): reject unresolved image references

[j15z]

Summary

When generate_image declares reference files, Sim now either loads every reference or fails before calling Gemini. A missing or unreadable image can no longer be silently dropped and turn an intended image edit into an unrelated text-only generation. Text-to-image remains unchanged when inputs is omitted.

This supersedes #5615. The existing production save_upload flow already promotes uploads to canonical workspace files, so this replacement preserves that boundary instead of making uploads/... a second first-class media path.

Related contract and agent-guidance change: https://github.com/simstudioai/mothership/pull/465

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation-only change

Changes

• Reject a supplied but empty inputs.files array.
• Reject direct uploads/... references with guidance to use save_upload and the returned files/... path.
• Resolve, safety-check, and read every declared image before initializing or invoking the provider.
• Abort on the first unresolved or unreadable reference instead of silently continuing.
• Update the generated tool catalog and schema with the non-empty generate_image.inputs.files contract.
• Preserve Sim-local table TTL catalog descriptions so the generated diff stays scoped to this fix.

Testing

• cd apps/sim && bun run test lib/copilot/tools/server/image/generate-image.test.ts lib/copilot/tools/server/media/model-boundaries.test.ts — 14 tests passed.
• bunx biome check passed for all four changed Sim files.
• bun run check:api-validation passed.
• git diff --check passed.
• Paired code review: ready to merge, with no actionable findings.

The repository-wide typecheck is currently blocked by unrelated existing dependency drift, including missing @sim/deployment-config and browser-protocol packages. Filtering its diagnostics produced no errors for the changed image-generation or generated-contract files.

Post-Deploy Monitoring & Validation

• For 24 hours after deploy, search GenerateImageTool logs for Failed to load reference image, inputs.files must contain at least one, and save_upload guidance.
• Healthy behavior: image edits report referenceImageCount >= 1, while text-to-image calls continue succeeding with no inputs object.
• Failure signal: a sustained increase in image-tool failures or agents repeatedly retrying the upload-promotion sequence.
• Owner: Copilot/media on-call. If those signals regress, roll back this PR and mothership#465 together.

Checklist

• Focused tests cover empty, upload, unresolved, unsafe, unreadable, and successful multi-reference inputs.
• API validation and formatting checks pass.
• No database schema changes.

Screenshots / Videos

Not applicable; this is a server-side runtime and generated-contract change.

---

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Aug 31, 2026 7:40pm

[cubic-dev-ai]

No issues found across 4 files

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

_{Re-trigger cubic}

[greptile-apps]

Greptile Summary

This PR makes image-reference handling fail closed so declared references cannot be silently omitted before provider invocation.

• Requires a non-empty inputs.files array whenever inputs is supplied.
• Rejects direct chat-upload paths with guidance to promote them through save_upload.
• Resolves, safety-checks, and reads every reference before initializing Gemini.
• Updates the generated catalog and runtime schema to match the new contract.
• Adds focused tests for omitted, empty, unresolved, unreadable, upload, partial-list, and successful reference inputs.

Confidence Score: 5/5

The PR appears safe to merge because declared image references now fail before provider invocation unless every reference resolves, passes the model-safety boundary, and is readable.

The generated contract, runtime guard, workspace-scoped resolution, safety check, and focused tests consistently preserve prompt-only generation while preventing partial or silently dropped image-reference requests.

Important Files Changed

Filename	Overview
apps/sim/lib/copilot/tools/server/image/generate-image.ts	Replaces best-effort reference loading with all-or-nothing validation and defers provider initialization until every declared image is loaded.
apps/sim/lib/copilot/tools/server/image/generate-image.test.ts	Adds focused coverage for valid text-to-image behavior and the principal reference-loading success and failure paths.
apps/sim/lib/copilot/generated/tool-catalog-v1.ts	Declares that a supplied generate-image inputs object must contain at least one file.
apps/sim/lib/copilot/generated/tool-schemas-v1.ts	Mirrors the non-empty reference-file contract in the generated runtime schema.

Sequence Diagram

sequenceDiagram
  participant C as Copilot
  participant T as generate_image
  participant W as Workspace files
  participant G as Gemini
  C->>T: prompt + optional inputs.files
  alt inputs supplied without files
    T-->>C: Reject before provider call
  else direct uploads/... path
    T-->>C: Require save_upload and files/... path
  else references declared
    loop Every reference
      T->>W: Resolve, safety-check, and read
      alt Any reference fails
        W-->>T: Resolution/read error
        T-->>C: Reject entire request
      else Reference loads
        W-->>T: Image bytes and MIME type
      end
    end
    T->>G: All references + prompt
    G-->>T: Generated image
    T-->>C: Saved workspace image
  else inputs omitted
    T->>G: Prompt only
    G-->>T: Generated image
    T-->>C: Saved workspace image
  end

Loading

_{Reviews (1): Last reviewed commit: "fix(copilot): reject unresolved image re..." | Re-trigger Greptile}