feat(files): folder operations for the File block, and folders as scope

Adds folder operations to file_v5 and to the agent tool surface, and makes a
folder a scope on the file operations that already existed rather than a second
set of operations beside them.

New operations: List, Create Folder, Move Folder, Delete Folder, Restore Folder,
and Move File. List answers "what is in here" — subfolders and files together,
direct children by default, the whole subtree under Recursive, subject to Max
Depth and Search. Its entries are a discriminated union on kind, so a consumer
narrows before reaching for the fields only one side has, and the listing is
capped with a truncated flag rather than being unbounded now that it includes
files.

Read, Get Content, Compress and Append gain an optional Folder above their file
picker. It narrows what the picker offers, and on the three read operations it
also stands for that folder's files when none are picked — resolved when the
workflow runs, so a file added later is included. Append only narrows: a folder
is not something you can append to, so it shapes the options and does not
travel. Write gains a folder destination, placed above File Name because it
names where before it names what.

Every folder field is one single-select tree control paired with a manual entry.
The picker cannot hold a reference expression — `<` autocomplete comes from
TagDropdown, which scans for the last `<` before the cursor and so only exists
on a text surface — which is why the pair exists rather than being a
convenience. Root is the absence of a selection rather than a row, since a root
row would be meaningless on create and wrong on delete.

Path handling is the part most worth reviewing. Two spellings circulate: the
stored display path, which backslash-escapes a slash inside a folder name, and
the canonical percent-encoded path the tools take. A folder genuinely named
"Q3/Q4" is one level in both and two if either is split on "/", so
folderPathSegments decodes by the leading slash the canonical form carries, and
resolveFolderIdsForPaths, isFileInFolderScope and selectDirectoryEntries are
pure and tested against exactly that case.

Delete Folder keeps its recursive flag as a guard rather than a scope: without
it, deleting a non-empty folder fails, and it is user-only so a model asked to
clean up a folder cannot set it on a guess.

Author: mzxchandra

apps/sim/app/api/tools/file/manage/route.ts

@@ -5,7 +5,6 @@ import {
   v2RelocateFileFolderContract,
 } from '@/lib/api/contracts/v2/files'
 import { defineV2JsonRoute, v2ApiKeyAuth, v2RateLimits } from '@/lib/api/server/routes'
-import { buildFolderPath, parentFolderPath, parseFolderPath } from '@/lib/folders/paths'
 import { v2FileErrorPolicies } from '@/lib/workspace-files/api'
 import { fileOperations } from '@/lib/workspace-files/application/operations'
 import {
@@ -14,28 +13,11 @@ import {
   listWorkspaceFileFoldersOperation,
   updateWorkspaceFileFolderOperation,
 } from '@/lib/workspace-files/application/workspace-file-folders'
-import { parseWorkspaceFileFolderDisplayPath } from '@/lib/workspace-files/folder-display-path'
+import { toWorkspaceFileFolderPathView } from '@/lib/workspace-files/folder-display-path'
 
 export const dynamic = 'force-dynamic'
 export const revalidate = 0
 
-function toV2Folder(folder: { name: string; path: string; createdAt: Date; updatedAt: Date }) {
-  const segments = folder.path.startsWith('/')
-    ? parseFolderPath(folder.path)
-    : parseWorkspaceFileFolderDisplayPath(folder.path)
-  if (segments.at(-1) !== folder.name) {
-    throw new Error('Workspace file folder path does not match its folder name')
-  }
-  const path = buildFolderPath(segments)
-  return {
-    name: folder.name,
-    path,
-    parentPath: parentFolderPath(path),
-    createdAt: folder.createdAt.toISOString(),
-    updatedAt: folder.updatedAt.toISOString(),
-  }
-}
-
 export const GET = defineV2JsonRoute({
   contract: v2ListFileFoldersContract,
   auth: v2ApiKeyAuth,
@@ -50,7 +32,10 @@ export const GET = defineV2JsonRoute({
     sortOrder: query.sortOrder,
   }),
   useCase: listWorkspaceFileFoldersOperation,
-  present: ({ folders }) => ({ data: folders.map(toV2Folder), nextCursor: null }),
+  present: ({ folders }) => ({
+    data: folders.map(toWorkspaceFileFolderPathView),
+    nextCursor: null,
+  }),
 })
 
 export const POST = defineV2JsonRoute({
@@ -61,7 +46,7 @@ export const POST = defineV2JsonRoute({
   errorPolicy: v2FileErrorPolicies.default,
   mapInput: ({ body }) => ({ workspaceId: body.workspaceId, path: body.path }),
   useCase: createWorkspaceFileFolderOperation,
-  present: ({ folder }) => ({ data: toV2Folder(folder) }),
+  present: ({ folder }) => ({ data: toWorkspaceFileFolderPathView(folder) }),
 })
 
 export const PATCH = defineV2JsonRoute({
@@ -76,7 +61,7 @@ export const PATCH = defineV2JsonRoute({
     destinationPath: body.destinationPath,
   }),
   useCase: updateWorkspaceFileFolderOperation,
-  present: ({ folder }) => ({ data: toV2Folder(folder) }),
+  present: ({ folder }) => ({ data: toWorkspaceFileFolderPathView(folder) }),
 })
 
 export const DELETE = defineV2JsonRoute({

apps/sim/app/api/v2/files/folders/route.ts

@@ -14,6 +14,8 @@ import { isApiClientError } from '@/lib/api/client/errors'
 import { requestJson } from '@/lib/api/client/request'
 import { fileDeleteContract } from '@/lib/api/contracts/storage-transfer'
 import { getExtensionFromMimeType } from '@/lib/uploads/utils/file-utils'
+import { parseWorkspaceFileFolderDisplayPath } from '@/lib/workspace-files/folder-display-path'
+import { isFileInFolderScope } from '@/lib/workspace-files/folder-path-selection'
 import { formatDisplayText } from '@/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/formatted-text'
 import { getWorkflowSearchLabelHighlight } from '@/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/workflow-search-highlight'
 import { useSubBlockValue } from '@/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/hooks/use-sub-block-value'
@@ -45,6 +47,11 @@ interface FileUploadProps {
   isPreview?: boolean
   previewValue?: any | null
   disabled?: boolean
+  /**
+   * A sibling folder field that narrows what this picker offers, and the switch
+   * saying whether that scope descends. See `SubBlockConfig.folderScope`.
+   */
+  folderScope?: { fieldId: string; recursiveFieldId?: string }
   /**
    * Controlled value. When `onValueChange` is provided the component reads from
    * this prop and writes through `onValueChange` instead of the subblock store,
@@ -55,12 +62,56 @@ interface FileUploadProps {
   onValueChange?: (value: UploadedFile | UploadedFile[] | null) => void
 }
 
+/**
+ * Label for a workspace file, prefixed with its folder so two files sharing a
+ * name are distinguishable.
+ *
+ * The stored folder path escapes a slash inside a folder name, so it is decoded
+ * into segments rather than split — otherwise a folder named `Q3/Q4` reads as
+ * two levels.
+ */
+function workspaceFileOptionLabel(file: { name: string; folderPath?: string | null }): string {
+  if (!file.folderPath) return file.name
+  try {
+    return `${parseWorkspaceFileFolderDisplayPath(file.folderPath).join(' / ')} / ${file.name}`
+  } catch {
+    return file.name
+  }
+}
+
+/** Groups files by folder, then by name, so the list reads folder by folder. */
+function byFolderThenName(
+  a: { name: string; folderPath?: string | null },
+  b: { name: string; folderPath?: string | null }
+): number {
+  const folderOrder = (a.folderPath ?? '').localeCompare(b.folderPath ?? '')
+  return folderOrder !== 0 ? folderOrder : a.name.localeCompare(b.name)
+}
+
 export interface UploadedFile {
   name: string
   path: string
   key?: string
   size: number
   type: string
+  /**
+   * Canonical workspace file id, present when the file was chosen from the
+   * workspace rather than uploaded in place.
+   *
+   * Carrying it is what makes a chosen file resolvable to exactly one row. A
+   * name alone is ambiguous the moment the same one exists in two folders, and
+   * the reference resolver then falls back to the oldest match anywhere in the
+   * workspace — so dropping the id here turned a precise choice into a guess.
+   *
+   * Optional, because an upload has no workspace id until it lands.
+   */
+  id?: string
+  /**
+   * Folder of a chosen workspace file, as the stored backslash-escaped display
+   * path (`a\/b` is one folder named `a/b`). Decode it with
+   * `parseWorkspaceFileFolderDisplayPath` — never by splitting on `/`.
+   */
+  folderPath?: string
 }
 
 interface SingleFileSelectorProps {
@@ -180,6 +231,7 @@ export function FileUpload({
   isPreview = false,
   previewValue,
   disabled = false,
+  folderScope,
   value: controlledValue,
   onValueChange,
 }: FileUploadProps) {
@@ -274,7 +326,40 @@ export function FileUpload({
     })
   }
 
-  const availableWorkspaceFiles = workspaceFiles.filter((workspaceFile) => {
+  /*
+   * A sibling folder field narrows what this picker offers. Choosing a folder
+   * means the run only touches that folder, so listing files from anywhere else
+   * would let a selection be built that the operation then ignores — the picker
+   * has to describe the same set the run will read.
+   *
+   * Falling back to this control's own id keeps the hook call unconditional for
+   * a picker with no folder scope; its own value is never a folder path, so the
+   * scope reads as absent.
+   */
+  const [folderScopeValue] = useSubBlockValue<unknown>(blockId, folderScope?.fieldId ?? subBlockId)
+  const [folderScopeRecursive] = useSubBlockValue<unknown>(
+    blockId,
+    folderScope?.recursiveFieldId ?? subBlockId
+  )
+  const folderScopePath =
+    folderScope && typeof folderScopeValue === 'string' ? folderScopeValue.trim() : ''
+  const folderScopeIncludesSubfolders =
+    !folderScope?.recursiveFieldId ||
+    folderScopeRecursive === undefined ||
+    folderScopeRecursive === null ||
+    folderScopeRecursive === '' ||
+    folderScopeRecursive === true ||
+    folderScopeRecursive === 'true'
+
+  const scopedWorkspaceFiles = folderScopePath
+    ? workspaceFiles.filter((workspaceFile) =>
+        isFileInFolderScope(workspaceFile.folderPath, folderScopePath, {
+          includeSubfolders: folderScopeIncludesSubfolders,
+        })
+      )
+    : workspaceFiles
+
+  const availableWorkspaceFiles = scopedWorkspaceFiles.filter((workspaceFile) => {
     const existingFiles = Array.isArray(value) ? value : value ? [value] : []
 
     const isAlreadySelected = existingFiles.some(
@@ -486,6 +571,8 @@ export function FileUpload({
       key: selectedFile.key,
       size: selectedFile.size,
       type: selectedFile.type,
+      id: selectedFile.id,
+      folderPath: selectedFile.folderPath ?? undefined,
     }
 
     if (multiple) {
@@ -620,11 +707,11 @@ export function FileUpload({
   const comboboxOptions = useMemo(
     () => [
       { label: 'Upload New File', value: '__upload_new__', disabled: cloudUploadBlocked },
-      ...availableWorkspaceFiles.map((file) => {
+      ...[...availableWorkspaceFiles].sort(byFolderThenName).map((file) => {
         const isAccepted =
           !acceptedTypes || acceptedTypes === '*' || isFileTypeAccepted(file.type, acceptedTypes)
         return {
-          label: file.name,
+          label: workspaceFileOptionLabel(file),
           value: file.id,
           // When cloud is required, local workspace files are also unpublishable.
           disabled: !isAccepted || cloudUploadBlocked,
@@ -638,11 +725,11 @@ export function FileUpload({
   const singleFileOptions = useMemo(
     () => [
       { label: 'Upload New File', value: '__upload_new__', disabled: cloudUploadBlocked },
-      ...workspaceFiles.map((file) => {
+      ...[...scopedWorkspaceFiles].sort(byFolderThenName).map((file) => {
         const isAccepted =
           !acceptedTypes || acceptedTypes === '*' || isFileTypeAccepted(file.type, acceptedTypes)
         return {
-          label: file.name,
+          label: workspaceFileOptionLabel(file),
           value: file.id,
           disabled: !isAccepted || cloudUploadBlocked,
         }

apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/file-upload/file-upload.tsx

@@ -0,0 +1,28 @@
+/**
+ * Reads a stored folder value into a canonical percent-encoded path.
+ *
+ * The picker stores a plain string, but the manual half of the pair is a text
+ * field, so a reference like `<block.folderPath>` resolves to a string before it
+ * gets here. A JSON array is tolerated because an earlier revision of this
+ * control stored one, and reading only its first entry is closer to the intent
+ * than discarding the value.
+ */
+export function readFolderPath(value: unknown): string {
+  if (typeof value === 'string') {
+    const trimmed = value.trim()
+    if (!trimmed) return ''
+    if (trimmed.startsWith('[')) {
+      try {
+        return readFolderPath(JSON.parse(trimmed))
+      } catch {
+        return trimmed
+      }
+    }
+    return trimmed
+  }
+  if (Array.isArray(value)) {
+    const first = value.find((entry) => typeof entry === 'string' && entry.length > 0)
+    return typeof first === 'string' ? first : ''
+  }
+  return ''
+}