feat(files): surface file versions in the File block and logs, with conditional writes

Author: waleedlatif1

apps/docs/content/docs/integrations/file.mdx

@@ -139,6 +139,7 @@ Create a new workspace file, either from text content or from an existing file.
 | `fileInput` | file | No | An existing file to store in the workspace, such as one produced by an earlier tool. Use this for anything that is not text — PDFs, images, audio, archives. Provide exactly one of content or fileInput. |
 | `contentType` | string | No | MIME type for new files \(e.g., "text/plain"\). Auto-detected from the file extension, or taken from the stored file, if omitted. |
 | `overwrite` | boolean | No | Replace the contents of an existing file at the exact target path \(folder and name\) instead of creating a suffixed copy. Creates the file when that path does not exist yet. |
+| `expectedRevision` | string | No | Refuse the write unless the file still holds the content this revision names, as returned by Get File or an earlier write. Use it so an edit computed from what you read cannot overwrite someone else’s change. |
 
 #### Output
 
@@ -148,6 +149,8 @@ Create a new workspace file, either from text content or from an existing file.
 | `name` | string | File name |
 | `size` | number | File size in bytes |
 | `url` | string | URL to access the file |
+| `version` | number | Version number of the content this write recorded |
+| `revision` | string | Opaque token for the content this write produced. Pass it back as expectedRevision to make a later write conditional on nothing having changed since. |
 
 ### File Append
 
@@ -171,6 +174,8 @@ Append content to an existing workspace file. The file must already exist. Conte
 | `name` | string | File name |
 | `size` | number | File size in bytes |
 | `url` | string | URL to access the file |
+| `version` | number | Version number of the content this write recorded |
+| `revision` | string | Opaque token for the content this write produced. Pass it back as expectedRevision to make a later write conditional on nothing having changed since. |
 
 ### Apply File Edit
 
@@ -194,6 +199,7 @@ Apply one precise edit to an existing text file without rewriting it. Use search
 | `startAnchor` | string | No | For delete_between, the complete first line to delete. The start anchor is removed. |
 | `endAnchor` | string | No | For delete_between, the complete ending boundary line. The end anchor remains in the file. |
 | `occurrence` | number | No | For anchored edits, which matching anchor occurrence to use, starting at 1. Defaults to 1. |
+| `expectedRevision` | string | No | Refuse the edit unless the file still holds the content this revision names, as returned by Get File or an earlier write. Use it so an edit computed from what you read cannot overwrite someone else’s change. |
 
 #### Output
 
@@ -203,6 +209,8 @@ Apply one precise edit to an existing text file without rewriting it. Use search
 | `name` | string | File name |
 | `size` | number | File size in bytes |
 | `lineCount` | number | Lines in the file after the edit |
+| `version` | number | Version number of the content this edit recorded |
+| `revision` | string | Opaque token for the content this edit produced. Pass it back as expectedRevision to make a later write conditional on nothing having changed since. |
 
 ### File Compress
 

apps/sim/app/workspace/[workspaceId]/logs/components/log-details/components/file-download/file-download.tsx

@@ -17,6 +17,8 @@ interface FileData {
   url: string
   storageProvider?: 's3' | 'blob' | 'gcs' | 'local'
   bucketName?: string
+  /** Workspace file version these bytes came from; absent on runs recorded before versioning. */
+  version?: number
 }
 
 interface FileCardsProps {
@@ -100,7 +102,10 @@ function FileCard({ file, isExecutionFile = false, workspaceId }: FileCardProps)
       </div>
 
       <div className='flex items-center justify-between'>
-        <span className='text-[var(--text-subtle)] text-xs'>{file.type}</span>
+        <span className='text-[var(--text-subtle)] text-xs'>
+          {file.type}
+          {file.version === undefined ? '' : ` · v${file.version}`}
+        </span>
         <Button
           variant='ghost'
           className='h-[20px]! px-1.5! py-0! text-xs'

apps/sim/blocks/blocks/file.ts

@@ -2350,6 +2350,15 @@ export const FileV5Block: BlockConfig<FileParserV3Output> = {
       type: 'number',
       description: 'Lines in the file after the change (edit, insert)',
     },
+    version: {
+      type: 'number',
+      description: 'Version number of the content a write recorded (write, append, edit)',
+    },
+    revision: {
+      type: 'string',
+      description:
+        'Opaque token for the content read or written, sent back as expectedRevision to make a later write conditional (get, write, append, edit)',
+    },
     results: {
       type: 'array',
       description: 'Matching lines as objects with fileId, lineNumber, and text fields (search)',

apps/sim/executor/types.ts

@@ -29,6 +29,12 @@ export interface UserFile {
   key: string
   context?: string
   base64?: string
+  /**
+   * Version number of a workspace file's content, present when the record was read with it. Each
+   * version owns its own storage key, so `key` already pins the bytes; this is the number that
+   * names them in the file version API.
+   */
+  version?: number
   /** Provider Files API handle (OpenAI/Anthropic `file_...` id) set when a large file is uploaded instead of inlined as base64. */
   providerFileId?: string
   /** Provider File API uri (Gemini `fileUri`) set when a large file is uploaded instead of inlined as base64. */

apps/sim/lib/api/contracts/primitives.ts

@@ -408,6 +408,8 @@ export const userFileSchema = z
     key: z.string().min(1),
     context: z.string().optional(),
     base64: z.string().optional(),
+    /** Workspace file version these bytes came from; absent on files with no version history. */
+    version: versionNumberSchema.optional(),
   })
   .passthrough()
 

apps/sim/lib/api/contracts/tools/file.ts

@@ -38,6 +38,18 @@ function validateFolderTarget(
   }
 }
 
+/**
+ * Makes a content write conditional on the file still holding the content the caller read, named
+ * by the opaque `revision` an earlier read or write returned. Version numbers cannot express this:
+ * collaborative and workflow writes fold into the current version rather than adding one, so the
+ * same number can name different bytes.
+ */
+const expectedRevisionSchema = z
+  .string()
+  .min(1)
+  .optional()
+  .describe('Revision from an earlier read or write; the write is refused if content moved on.')
+
 export const fileManageWriteBodySchema = z
   .object({
     operation: z.literal('write'),
@@ -52,9 +64,23 @@ export const fileManageWriteBodySchema = z
     fileInput: z.unknown().optional(),
     contentType: z.string().optional(),
     overwrite: z.boolean().optional(),
+    expectedRevision: expectedRevisionSchema,
+
     [PRIVATE_SECRET_PROVENANCE_FIELD]: privateSecretProvenanceBundleSchema.optional(),
   })
   .superRefine((body, context) => {
+    /*
+     * A precondition asserts something about an existing file, and only the overwrite branch
+     * writes into one. Refused here so the request fails before it uploads bytes or creates
+     * folders on the way to a write that could never satisfy it.
+     */
+    if (body.expectedRevision !== undefined && body.overwrite !== true) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['expectedRevision'],
+        message: 'expectedRevision requires overwrite: true.',
+      })
+    }
     const hasContent = body.content !== undefined
     const hasFileInput = body.fileInput !== undefined && body.fileInput !== null
     if (hasContent === hasFileInput) {
@@ -312,6 +338,7 @@ const fileEditTargetShape = {
   folderPath: v2FolderPathInputSchema.optional(),
   folderPaths: fileFolderPathsSchema.optional(),
   includeSubfolders: z.boolean().optional(),
+  expectedRevision: expectedRevisionSchema,
 } as const
 
 export const fileManageEditBodySchema = z

apps/sim/lib/core/security/redaction.test.ts

@@ -633,6 +633,26 @@ describe('redactApiKeys', () => {
       expect(result.processedFiles[0]).not.toHaveProperty('key')
       expect(result.processedFiles[0]).not.toHaveProperty('context')
     })
+
+    it.concurrent('should keep the workspace file version, which names the exposed bytes', () => {
+      const result = redactApiKeys({
+        files: [
+          {
+            id: 'file-123',
+            name: 'notes.md',
+            url: 'http://localhost/api/files/serve/notes.md',
+            size: 12,
+            type: 'text/markdown',
+            key: 'workspace/ws/notes.md',
+            context: 'workspace',
+            version: 4,
+          },
+        ],
+      })
+
+      expect(result.files[0].version).toBe(4)
+      expect(result.files[0]).not.toHaveProperty('key')
+    })
   })
 
   describe('primitive handling', () => {

apps/sim/lib/core/utils/user-file.ts

@@ -7,7 +7,15 @@ export type UserFileLike = Pick<UserFile, 'id' | 'name' | 'url' | 'key'> &
  * Fields exposed for UserFile objects in UI (tag dropdown) and logs.
  * Internal fields like 'key' and 'context' are not exposed.
  */
-export const USER_FILE_DISPLAY_FIELDS = ['id', 'name', 'url', 'size', 'type', 'base64'] as const
+export const USER_FILE_DISPLAY_FIELDS = [
+  'id',
+  'name',
+  'url',
+  'size',
+  'type',
+  'base64',
+  'version',
+] as const
 
 export type UserFileDisplayField = (typeof USER_FILE_DISPLAY_FIELDS)[number]
 

apps/sim/lib/internal/file/operations.test.ts

@@ -112,6 +112,11 @@ vi.mock('@/lib/uploads/contexts/workspace/workspace-file-manager', () => ({
   fetchWorkspaceFileBuffer: (...args: unknown[]) => mockFetchWorkspaceFileBuffer(...args),
   getWorkspaceFileByName: (...args: unknown[]) => mockGetWorkspaceFileByName(...args),
   getWorkspaceFile: (...args: unknown[]) => mockGetWorkspaceFile(...args),
+  /* The versioned read is the same row plus the number the metadata surface reports. */
+  getWorkspaceFileWithCurrentVersion: async (...args: unknown[]) => {
+    const file = await mockGetWorkspaceFile(...args)
+    return file ? { ...file, currentVersion: 1 } : file
+  },
   loadActiveWorkspaceContext: (...args: unknown[]) => mockLoadActiveWorkspaceContext(...args),
   loadActiveWorkspaceFileContext: (...args: unknown[]) =>
     mockLoadActiveWorkspaceFileContext(...args),
@@ -133,6 +138,11 @@ vi.mock('@/lib/uploads/contexts/workspace', () => ({
   fetchWorkspaceFileBuffer: (...args: unknown[]) => mockFetchWorkspaceFileBuffer(...args),
   getWorkspaceFileByName: (...args: unknown[]) => mockGetWorkspaceFileByName(...args),
   getWorkspaceFile: (...args: unknown[]) => mockGetWorkspaceFile(...args),
+  /* The versioned read is the same row plus the number the metadata surface reports. */
+  getWorkspaceFileWithCurrentVersion: async (...args: unknown[]) => {
+    const file = await mockGetWorkspaceFile(...args)
+    return file ? { ...file, currentVersion: 1 } : file
+  },
   loadActiveWorkspaceContext: (...args: unknown[]) => mockLoadActiveWorkspaceContext(...args),
   loadActiveWorkspaceFileContext: (...args: unknown[]) =>
     mockLoadActiveWorkspaceFileContext(...args),

apps/sim/lib/internal/file/operations.ts

@@ -43,6 +43,7 @@ import {
 import { normalizeWorkspaceFileItemName } from '@/lib/uploads/contexts/workspace/workspace-file-folder-manager'
 import type {
   getWorkspaceFile,
+  getWorkspaceFileWithCurrentVersion,
   WorkspaceFileRecord,
 } from '@/lib/uploads/contexts/workspace/workspace-file-manager'
 import {
@@ -51,6 +52,7 @@ import {
   type WorkspaceFileSecretProvenance,
   type WorkspaceFileSecretProvenanceIdentity,
 } from '@/lib/uploads/contexts/workspace/workspace-file-secret-provenance'
+import { INITIAL_WORKSPACE_FILE_VERSION } from '@/lib/uploads/contexts/workspace/workspace-file-versions'
 import {
   getFileExtension,
   getMimeTypeFromExtension,
@@ -68,14 +70,18 @@ import {
   createWorkspaceFileFromBuffer,
 } from '@/lib/workspace-files/application/create-workspace-file'
 import { editWorkspaceFileContent } from '@/lib/workspace-files/application/edit-workspace-file-content'
+import { workspaceFileRevision } from '@/lib/workspace-files/application/file-revision'
 import {
   listWorkspaceFilesInFolderScope,
   queryWorkspaceFilePage,
 } from '@/lib/workspace-files/application/list-workspace-files'
 import { moveWorkspaceFileItemsOperation } from '@/lib/workspace-files/application/move-workspace-file-items'
 import { fileOperations } from '@/lib/workspace-files/application/operations'
 import { readWorkspaceFileContent } from '@/lib/workspace-files/application/read-workspace-file-content'
-import { readWorkspaceFileMetadata } from '@/lib/workspace-files/application/read-workspace-file-metadata'
+import {
+  readWorkspaceFileMetadata,
+  readWorkspaceFileMetadataWithVersion,
+} from '@/lib/workspace-files/application/read-workspace-file-metadata'
 import { downloadWorkspaceFileRecord } from '@/lib/workspace-files/application/read-workspace-file-record'
 import { readWorkspaceFileSecretProvenance } from '@/lib/workspace-files/application/read-workspace-file-secret-provenance'
 import { resolveWorkspaceFileReference } from '@/lib/workspace-files/application/resolve-workspace-file-reference'
@@ -177,7 +183,14 @@ async function assertOperationFileAccess(
   }
 }
 
-const workspaceFileToUserFile = (file: Awaited<ReturnType<typeof getWorkspaceFile>>) => {
+/**
+ * A workspace file record as an execution file. `version` rides along only when the record was
+ * read with it — a file addressed by id — so the number always describes the very bytes this row
+ * carries rather than a version a second query might have raced ahead to.
+ */
+const workspaceFileToUserFile = (
+  file: (WorkspaceFileRecord & { currentVersion?: number }) | null
+) => {
   if (!file) return null
 
   return {
@@ -188,6 +201,7 @@ const workspaceFileToUserFile = (file: Awaited<ReturnType<typeof getWorkspaceFil
     type: file.type,
     key: file.key,
     context: 'workspace' as const,
+    ...(file.currentVersion === undefined ? {} : { version: file.currentVersion }),
   }
 }
 
@@ -1004,10 +1018,10 @@ export async function executeFileManageOperation(
           return Response.json({ success: false, error: 'File is required' }, { status: 400 })
         }
 
-        let file: Awaited<ReturnType<typeof getWorkspaceFile>>
+        let file: Awaited<ReturnType<typeof getWorkspaceFileWithCurrentVersion>>
         try {
           file = (
-            await readWorkspaceFileMetadata.execute({
+            await readWorkspaceFileMetadataWithVersion.execute({
               principal,
               input: { fileId: selectedFileId, assertedWorkspaceId: workspaceId },
             })
@@ -1031,6 +1045,8 @@ export async function executeFileManageOperation(
           success: true,
           data: {
             file: workspaceFileToUserFile(file),
+            /** The token a conditional write sends back; see `expectedRevision`. */
+            revision: workspaceFileRevision(file),
           },
         })
       }
@@ -1224,7 +1240,15 @@ export async function executeFileManageOperation(
       }
 
       case 'write': {
-        const { fileName, content, fileInput, contentType, overwrite, folderPath } = body
+        const {
+          fileName,
+          content,
+          fileInput,
+          contentType,
+          overwrite,
+          folderPath,
+          expectedRevision,
+        } = body
         signal?.throwIfAborted()
         const provenanceResolution = resolveFileWriteSecretProvenance({
           headers,
@@ -1365,6 +1389,7 @@ export async function executeFileManageOperation(
                 contentType: mimeType,
                 provenanceMode: 'replace_empty',
                 expectedUpdatedAt: existing.contentUpdatedAt ?? undefined,
+                expectedRevision,
                 ...(overwriteProvenance ? { secretProvenance: overwriteProvenance } : {}),
               },
             })
@@ -1382,6 +1407,7 @@ export async function executeFileManageOperation(
                 name: overwritten.name,
                 size: overwritten.size,
                 url: ensureAbsoluteUrl(overwritten.url ?? overwritten.path),
+                version: overwritten.currentVersion,
               },
             })
           }
@@ -1418,6 +1444,8 @@ export async function executeFileManageOperation(
             name: result.file.name,
             size: fileBuffer.length,
             url: ensureAbsoluteUrl(result.file.url ?? result.file.path),
+            /** A file created with its content has no history yet, so those bytes are version 1. */
+            version: INITIAL_WORKSPACE_FILE_VERSION,
           },
         })
       }
@@ -1591,7 +1619,7 @@ export async function executeFileManageOperation(
           })
           const finalContent = existingBuffer.toString('utf-8') + content
           const fileBuffer = Buffer.from(finalContent, 'utf-8')
-          await updateWorkspaceFileContent.execute({
+          const { file: appended } = await updateWorkspaceFileContent.execute({
             principal,
             input: {
               fileId: existing.id,
@@ -1617,6 +1645,7 @@ export async function executeFileManageOperation(
               name: existing.name,
               size: fileBuffer.length,
               url: ensureAbsoluteUrl(existing.path),
+              version: appended.currentVersion,
             },
           })
         } finally {
@@ -1721,13 +1750,21 @@ export async function executeFileManageOperation(
             fileId: target.id,
             assertedWorkspaceId: workspaceId,
             ...(secretProvenance ? { secretProvenance } : {}),
+            expectedRevision: body.expectedRevision,
             edit,
           },
         })
 
         return Response.json({
           success: true,
-          data: { id: file.id, name: file.name, size: file.size, lineCount },
+          data: {
+            id: file.id,
+            name: file.name,
+            size: file.size,
+            lineCount,
+            version: file.currentVersion,
+            revision: workspaceFileRevision(file),
+          },
         })
       }