feat(files): add an overwrite option to file write

[TheodoreSpeaks]

Summary

• Adds an Overwrite Existing File toggle to the File block's Write operation, default off. Off, behavior is unchanged — a name collision still produces data (1).csv.
• On, a file already at exactly that path has its contents replaced. Nothing there, it creates the file, so the option is an upsert rather than a hard failure.
• Works for both write modes: text content and a stored fileInput (the bytes and encoding flow through unchanged, so a binary copy overwrites correctly).

Three things worth a look in review:

• Strict path matching. The shared reference resolver falls back to a workspace-wide name match, so overwriting report.txt at the root could otherwise have silently destroyed archive/report.txt. resolveWriteOverwriteTarget accepts a hit only when its folder and leaf name match the write target exactly; anything else falls through to create.
• No lock, CAS instead. Unlike append, overwrite is not read-modify-write, so it passes expectedUpdatedAt and fails with a conflict if the file changed underneath it, rather than taking the Redis lock append needs.
• user-only visibility. An agent calling file_write cannot set overwrite itself — replacing existing content stays an explicit choice on the block.

Provenance follows the append precedent: overwriting a file owned by another user downgrades exact resolved-secret provenance to unknown.

Type of Change

• New feature

Testing

Tested manually. 6 new unit tests cover the replace path, the create-when-absent fallback, the wrong-folder rejection, the default-off path, the cross-user provenance downgrade, and overwrite with a fileInput source. type-check, lint, check:audits (39 audits), and the block-registry check all pass.

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)

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 31, 2026 6:50pm

[greptile-apps]

Greptile Summary

The PR adds a user-controlled overwrite option to File Write while preserving suffixing as the default behavior.

• Resolves overwrite targets using exact folder and leaf-name matching.
• Uses optimistic concurrency for existing-file updates.
• Uses exact-name creation so concurrent absent-target writes conflict rather than create suffixed copies.
• Propagates the option through block configuration, tool contracts, generated metadata, documentation, and tests.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the previously reported absent-target race now uses exact-name creation backed by folder-and-name uniqueness and returns a conflict for the losing concurrent writer.

Important Files Changed

Filename	Overview
apps/sim/lib/internal/file/operations.ts	Implements exact-path overwrite resolution, optimistic update conflicts, provenance handling, and race-safe exact-name creation.
apps/sim/lib/internal/file/operations.test.ts	Covers replacement, absent-target creation, concurrent conflicts, folder matching, default suffixing, binary input, and provenance behavior.
apps/sim/blocks/blocks/file.ts	Adds the overwrite switch and maps its persisted boolean value into File Write execution.
apps/sim/tools/file/write.ts	Adds the user-only overwrite parameter to the executable tool contract.
apps/sim/lib/api/contracts/tools/file.ts	Extends write request validation with an optional boolean overwrite field.
apps/sim/tools/generated/tool-metadata.ts	Regenerates serializable tool metadata to include the overwrite option.
apps/docs/content/docs/integrations/file.mdx	Documents overwrite semantics and the unchanged default suffixing behavior.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[File Write request] --> B{Overwrite enabled?}
    B -->|No| C[Create file with suffixing allowed]
    B -->|Yes| D[Resolve exact folder and leaf name]
    D -->|Exact file exists| E[Update with expected content timestamp]
    D -->|No exact file| F[Create with exact name]
    F -->|Concurrent name collision| G[Return conflict]
    E --> H[Return overwritten file]
    F -->|Created| I[Return new file]

Loading

_{Reviews (3): Last reviewed commit: "docs(files): describe overwrite as an ex..." | Re-trigger Greptile}

[TheodoreSpeaks]

@greptile review

[cubic-dev-ai]

All reported issues were addressed

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[TheodoreSpeaks]

@greptile review