Skip to content

Self-improving AI Employees for everyone

docs(gallery): document the workspace explorer and the rules behind it

trohitg41de70e87d98
diff --git a/docs-internal/media_transport.md b/docs-internal/media_transport.md
index 95d7d50c..21d242ad 100644
--- a/docs-internal/media_transport.md
+++ b/docs-internal/media_transport.md
@@ -1,7 +1,10 @@
# Media Transport — how files move through the engine
**Status:** shipped.
-**Scope:** `server/services/media/`, `server/routers/workspace.py`, `nodes/filesystem/_backend.py`.
+**Scope:** `server/services/media/`, `server/services/workspace_locator.py`,
+`server/routers/workspace.py`, `nodes/filesystem/_backend.py`,
+`nodes/filesystem/gallery/` (the second consumer of `preview.py`, and the
+producer of `FileRef` listing rows).
**Companion:** [Speech Provider RFC](./speech_provider_rfc.md) — the first consumer.
One rule underneath everything here:
@@ -38,25 +41,40 @@ because it makes the tool path *sometimes* catastrophic — which passes review.
---
-## 2. `AudioRef` — a reference, structurally
+## 2. `FileRef` / `AudioRef` — a reference, structurally
[`services/media/refs.py`](../server/services/media/refs.py). ~400 bytes
serialized, so thousands fit inside Temporal's *warning* threshold.
+Two classes, not one. `FileRef` is the base and the honest default —
+`kind="file"` asserts only that the thing exists in the workspace. A
+kind-specific subclass is added only when a probe actually produces extra
+metadata, which so far means audio alone.
+
```python
-class AudioRef(BaseModel):
- kind: Literal["audio"] = "audio"
+FileKind = Literal["file", "audio", "image", "video", "document"]
+
+class FileRef(BaseModel):
+ kind: FileKind = "file"
path: str # workspace-RELATIVE POSIX, no leading slash
workflow_id: Optional[str] # immutable id — survives rename
filename: str # display only, never used for resolution
mime_type: str
- format: str
size_bytes: int
+ modified_at: Optional[str] # ISO 8601, advisory — not a cache key
+ sha256: Optional[str]
+ url: Optional[str] # path-only, no scheme or host
+
+ model_config = ConfigDict(extra="forbid")
+
+
+class AudioRef(FileRef):
+ """A FileRef whose container has actually been probed."""
+ kind: Literal["audio"] = "audio"
+ format: str # wav, mp3, opus, ...
duration_seconds: Optional[float] # None when unmeasurable; never guessed
sample_rate: Optional[int]
channels: Optional[int]
- sha256: Optional[str]
- url: Optional[str] # path-only, no scheme or host
model_config = ConfigDict(extra="forbid")
```
@@ -166,20 +184,36 @@ because uploaded bytes land on disk and only a reference enters a payload.
## 5. HTTP surface
-[`routers/workspace.py`](../server/routers/workspace.py). A thin shell over the
-above — it owns no containment logic of its own.
+[`routers/workspace.py`](../server/routers/workspace.py). A thin shell — it owns
+no containment logic, no id → slug resolution
+([`services/workspace_locator.py`](../server/services/workspace_locator.py)) and
+no inline/attachment rule ([`services/media/preview.py`](../server/services/media/preview.py))
+of its own.
+
+**Listing is not here.** `list_workspace_files` (a WebSocket command owned by the
+`gallery` plugin) is the listing channel; these HTTP routes are the *content*
+channel. The consumer is the parameter panel, which already holds an
+authenticated socket with request correlation — a second HTTP listing surface
+would mean a second auth path and a second error envelope for no gain.
### `GET /api/workspace/{workflow_id}/files/{path:path}`
-- id → slug lookup, then `resolve_within`.
+- id → slug via `workspace_locator.resolve_workspace_root` (reads keep the
+ `"default"` fallback), then `resolve_within`.
- **404, never 403** — a distinct status would confirm the existence of files
outside the workspace.
- **Range/seeking is free.** Starlette's `FileResponse` already implements
`Accept-Ranges`, `206`, `Content-Range`, `If-Range` and `416`. Do not wrap it
in a `StreamingResponse`; that loses all of it and breaks `<audio>` seeking.
-- **Inline allowlist.** Only `audio/ image/ video/` render inline; everything
- else — emphatically including `text/html` and `image/svg+xml` — gets
- `Content-Disposition: attachment`, plus `X-Content-Type-Options: nosniff`.
+- **Inline allowlist — owned by [`services/media/preview.py`](../server/services/media/preview.py),
+ not by this route.** `serves_inline(mime)` decides the `Content-Disposition`;
+ `preview_kind(mime)` (gated on `serves_inline` first) gives the gallery
+ listing each row's `preview` verdict. **Two consumers, one function** — if
+ they ever disagreed, the panel would open a player for a file the route forces
+ to download, and the user would see a dead frame with no explanation. Only
+ `audio/ image/ video/` render inline; `NEVER_INLINE` is the full set
+ `{image/svg+xml, text/html, text/xml, application/xhtml+xml}`. Everything else
+ gets `Content-Disposition: attachment`, plus `X-Content-Type-Options: nosniff`.
This is load-bearing. `shell`, `fileDownloader` and `fileModify` can all
write arbitrary files into a workspace, so serving attacker-authored markup
@@ -241,15 +275,28 @@ a workflow that has never been saved and therefore has no workspace yet.
## 7. Extending to other media
-`AudioRef` is deliberately named for what it is rather than being a generic
-`MediaRef`, because the metadata that matters differs per kind (`duration` and
-`sample_rate` for audio; `width` / `height` for images). The transport layer
-underneath — containment, atomic write, the workspace routes, the limits — is
-already kind-agnostic.
-
-An `ImageRef` should be a sibling model in `refs.py` reusing the same
-`workspace.py` helpers, with `write_image` differing from `write_audio` only in
-subdirectory and probe.
+This already resolved, and not the way the original sketch guessed. What was
+rejected is a single fat `MediaRef` carrying every kind's optional metadata,
+because the metadata that matters differs per kind (`duration` and `sample_rate`
+for audio; `width` / `height` for images). What was *adopted* is a shared base
+carrying only kind-agnostic fields — `FileRef` — with `FileKind` already
+enumerating `image`, `video` and `document`, and `AudioRef(FileRef)` as the one
+narrowing subclass so far.
+
+So the rule for the next kind:
+
+- **`FileRef` is the honest default.** `kind="file"` asserts only that the file
+ exists in the workspace. The `gallery` node emits this for everything,
+ including a `.wav`.
+- **Subclass only when a probe produces real extra metadata.** `AudioRef` earns
+ its subclass because `inspect_audio` measures duration / sample rate /
+ channels. An `ImageRef` earns one the moment something actually reads
+ width / height — and not before, because `kind` is an assertion about what was
+ measured. A fabricated `duration_seconds` mis-bills a per-second provider
+ downstream; the same trap exists for any guessed field.
+- The transport layer underneath — containment, atomic write, the workspace
+ routes, the limits, `preview.py` — is already kind-agnostic, so `write_image`
+ would differ from `write_audio` only in subdirectory and probe.
---
@@ -264,4 +311,10 @@ subdirectory and probe.
| Route serves `text/html` and `image/svg+xml` as `attachment` | `tests/routers/test_workspace.py` |
| Range request returns `206` with correct `Content-Range` | `tests/routers/test_workspace.py` |
| Oversize upload is 413; traversal filename cannot escape `uploads/` | `tests/routers/test_workspace.py` |
+| The route delegates its disposition to `preview.serves_inline` rather than re-deriving it | `tests/routers/test_workspace.py::TestInlineDispositionHasOneDefinition` |
+| Listing paths are relative, POSIX, and round-trip through `resolve_media` | `tests/nodes/test_gallery.py::TestPathShape` |
+| Every listing row carries a finished `ref`, and `preview` matches `serves_inline` | `tests/nodes/test_gallery.py::TestRowsAreSelfSufficient` |
+| Traversal (`..`, `~`) refused; `/etc` and `C:/Windows` resolve *inside* the workspace | `tests/nodes/test_gallery.py::TestTraversal` |
+| An escaping symlink is not listed | `tests/nodes/test_gallery.py::TestWorkspaceContainmentOfSymlinks` |
+| A mutating caller with an unresolvable workflow id is refused, not defaulted | `tests/services/test_workspace_locator.py` |
| A returned ref round-trips through the GET route | `tests/routers/test_workspace.py` |
diff --git a/docs-internal/node-logic-flows/README.md b/docs-internal/node-logic-flows/README.md
index 1f8f59ec..77e22c91 100644
--- a/docs-internal/node-logic-flows/README.md
+++ b/docs-internal/node-logic-flows/README.md
@@ -92,6 +92,7 @@ match its doc here, and each doc must still describe what the code does.
- [File Modify (`fileModify`)](./code_fs_process/fileModify.md)
- [File Read (`fileRead`)](./code_fs_process/fileRead.md)
- [FS Search (`fsSearch`)](./code_fs_process/fsSearch.md)
+- [Gallery (`gallery`)](./code_fs_process/gallery.md)
- [JavaScript Executor (`javascriptExecutor`)](./code_fs_process/javascriptExecutor.md)
- [Monty Executor (`montyExecutor`)](./code_fs_process/montyExecutor.md)
- [Process Manager (`processManager`)](./code_fs_process/processManager.md)
diff --git a/docs-internal/node-logic-flows/code_fs_process/gallery.md b/docs-internal/node-logic-flows/code_fs_process/gallery.md
new file mode 100644
index 00000000..3eeb9621
--- /dev/null
+++ b/docs-internal/node-logic-flows/code_fs_process/gallery.md
@@ -0,0 +1,167 @@
+# Gallery (`gallery`)
+
+| Field | Value |
+|------|-------|
+| **Category** | code_fs_process / filesystem |
+| **Backend handler** | [`server/nodes/filesystem/gallery/__init__.py::GalleryNode.list_files`](../../../server/nodes/filesystem/gallery/__init__.py) (dispatched via `BaseNode.execute()` + `@Operation("list")`) |
+| **Backend** | Native `WorkspaceBackend` (`ls_info`, `glob_info`) in [`server/nodes/filesystem/_backend.py`](../../../server/nodes/filesystem/_backend.py), wrapped by [`_service.py`](../../../server/nodes/filesystem/gallery/_service.py) |
+| **WS handler** | `list_workspace_files` in [`_handlers.py`](../../../server/nodes/filesystem/gallery/_handlers.py) (`@ws_response`, self-registered from `__init__.py`) |
+| **Tests** | [`server/tests/nodes/test_gallery.py`](../../../server/tests/nodes/test_gallery.py) |
+| **Skill (if any)** | none |
+| **Dual-purpose tool** | **no** — `usable_as_tool = False` is deliberate (see Purpose) |
+
+## Purpose
+
+Browse the per-workflow workspace from the editor. The point is the panel: it
+lists what a workflow has actually produced and lets a file be dragged straight
+onto another node's parameter. Before this, using a produced file meant already
+knowing its path and typing it by hand.
+
+Running the node is not a no-op — it emits the listing as `FileRef` rows, so
+downstream nodes can consume workspace files inside a workflow, not just in the
+editor.
+
+**Deliberately not `usable_as_tool`.** `fsSearch` (ls/glob/grep) and `fileModify`
+(write/edit) already cover what an agent needs, and this node carries destructive
+operations; shipping an editor panel must not hand every agent a delete tool as a
+side effect. If agent-facing delete is ever wanted it belongs on `fileModify`,
+where the tool description can be written carefully.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | Not consumed |
+
+## Parameters
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `path` | string | `""` | no | - | Workspace-relative directory to list. Empty = workspace root |
+| `pattern` | string | `""` | no | - | Optional glob (e.g. `*.wav`). Set = recursive search under `path` |
+| `selection` | string[] | `[]` | no | - | Specific workspace-relative files to emit, pinned in the panel |
+| `include_dirs` | boolean | `false` | no | - | Include directories in the output as well as files |
+| `limit` | integer (`ge=1`, `le=1000`) | `200` | no | - | Row cap |
+
+`GalleryParams` uses `extra="ignore"`.
+
+**The panel writes these back.** Navigating a folder writes `path`; ticking a row
+writes `selection`. That coupling is the design: what you browse is what the node
+lists when it runs, so the panel cannot drift from the node. Note the panel's
+search box is *not* one of these — it is transient view state, sent as `search`
+on the WS request only.
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | Standard envelope payload |
+
+### Output payload
+
+```ts
+{
+ path: string; // the directory that was listed
+ files: FileRef[]; // serialized FileRef rows, always kind:"file"
+ directories: string[]; // [] unless include_dirs
+ count: number; // == files.length (capped, NOT the untruncated total)
+ truncated: boolean;
+ missing?: string[]; // selection mode only — pinned files that have gone
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[list] --> W{workspace_dir on ctx?}
+ W -- no --> Werr[raise NodeUserError:<br/>no workspace yet, save and run once]
+ W -- yes --> S{selection non-empty?}
+ S -- yes --> E[_emit_selection]
+ E --> Er[resolve_media each pinned path]
+ Er --> Em{any resolved?}
+ Em -- none --> Eerr[raise NodeUserError:<br/>none of the selected files exist]
+ Em -- some --> Eok[Return files + missing list]
+ S -- no --> P{pattern set?}
+ P -- yes --> G[list_matching: rglob, files only]
+ P -- no --> L[list_directory: one level, dirs + files]
+ G --> R[rows -> to_file_ref per row]
+ L --> R
+ R --> Rok[Return path, files, directories, count, truncated]
+```
+
+## Decision Logic
+
+- **Three mutually exclusive branches**, checked in this order: `selection`
+ wins over `pattern`, which wins over a plain directory listing.
+- **`_emit_selection` is partial-failure tolerant.** A pinned file that no
+ longer resolves is reported in `missing[]` rather than failing the node — the
+ node that writes it may simply not have run yet in this execution. Only an
+ *entirely* missing selection raises.
+- **`list_directory` never recurses.** `glob_info` uses `rglob`, so a `*`
+ pattern would walk the whole tree unbounded; directory-at-a-time is what a
+ browser needs anyway.
+- **`list_matching` is files-only** (`glob_info` filters directories out), and
+ omits `parent` / `crumbs` / `workspace_exists` / `path_exists`. The two
+ branches genuinely return different key sets — discriminate on `pattern`.
+- **Caps**: `max(1, min(limit, WORKSPACE_LIST_LIMIT=1000))`, default 500 on the
+ WS path. `count == len(entries)`; the untruncated total is never sent.
+- **Sort is `(not is_dir, name.lower())`** — directories first. Not cosmetic:
+ it means truncating at the cap can never strip navigation out of the response.
+
+## Side Effects
+
+- **Database writes**: none. (`resolve_workspace_root` *reads* the workflow row
+ to translate id → slug.)
+- **Broadcasts**: none.
+- **External API calls**: none.
+- **File I/O**: directory enumeration under the workspace root, via
+ `asyncio.to_thread` (`iterdir` on a large directory blocks, and the WS handler
+ runs on the shared event loop). `stat()` per entry for size/mtime.
+- **Subprocess**: none.
+
+## External Dependencies
+
+- **Python packages**: standard library only (`mimetypes`, `pathlib`, `asyncio`).
+- **Environment variables**: `WORKSPACE_BASE_DIR`.
+
+## Edge cases & known limits
+
+- **Rows are self-sufficient by contract.** Each carries a finished `ref`
+ (serialized `FileRef`, `null` for directories) and a `preview` verdict from
+ [`services/media/preview.py`](../../../server/services/media/preview.py). The
+ client re-derives neither — for `preview` that would be a second copy of a
+ *security* decision, and the two must agree or the panel offers a preview the
+ route refuses to serve inline.
+- **`kind` is always `"file"`, even for a `.wav`.** `kind="audio"` asserts
+ `inspect_audio` probed the container; this path only guessed a MIME type from
+ the extension, and a fabricated duration would mis-bill a per-second provider
+ downstream.
+- **Paths are workspace-relative with no leading slash.** `_file_info` emits
+ `/audio/x.wav`; `_relative()` strips it here because
+ `PurePosixPath('/audio/x.wav').is_absolute()` is `True` while the Windows
+ flavour is `False` — so a leading slash resolves fine on a Windows dev box and
+ raises "outside this workflow's workspace" on Linux. A production-only bug
+ class. `_file_info` is deliberately left alone: `fsSearch` output and its
+ LLM-facing prompt depend on the current shape.
+- **`/etc` and `C:/Windows` are not escapes.** A leading slash is the *virtual*
+ root and a drive prefix is stripped by `_validate_virtual_path`; both resolve
+ inside the workspace. Real traversal (`..`, `~`) does raise. Test containment,
+ not rejection.
+- **`workspace_exists` vs `path_exists` must be probed before `get_backend`,**
+ which mkdirs its root — probe after and the answer is always `True`, so the
+ panel could never distinguish "no workspace yet" from "empty folder".
+ `ls_info` returns `[]` for both.
+- **The cap bounds the payload, not the walk.** `ls_info` materialises the
+ directory before slicing. Fine until ~10k entries in one directory.
+- **Listing is a WS command, content is HTTP.** `list_workspace_files` is the
+ listing channel; `GET /api/workspace/{id}/files/{path}` stays the content
+ channel (preview, download, Range). The consumer already holds an
+ authenticated socket with request correlation, so a second HTTP listing
+ surface would mean a second auth path and a second error envelope for no gain.
+- **Reads may fall back to the anonymous `"default"` workspace.** The handler
+ calls `resolve_workspace_root(..., allow_default=True)`. Any future *mutating*
+ handler must pass `allow_default=False`, or an unresolvable id (stale tab,
+ workflow deleted in another window) silently operates on a different context's
+ files.
+- **No mutations yet.** mkdir / rename / move / delete are not implemented.
diff --git a/docs-internal/node_panels.md b/docs-internal/node_panels.md
index 962e3297..85a9a5cc 100644
--- a/docs-internal/node_panels.md
+++ b/docs-internal/node_panels.md
@@ -76,6 +76,28 @@ The drag payload is set on both MIME types:
`effectAllowed` is `'copy'`.
+### Drop discriminators
+
+`ParameterRenderer.handleDrop` branches on `application/json`'s `type`. The three
+have **different write semantics**, which is the whole reason they are separate —
+reusing one for another's payload silently destroys user input.
+
+| `type` | Produced by | Payload | Write semantics |
+|---|---|---|---|
+| `nodeVariable` | [`useDragVariable`](../client/src/hooks/useDragVariable.ts) (InputSection) | `{nodeId, nodeName, key, variableTemplate, dataType}` | **Appends** `variableTemplate` with smart spacing |
+| `nodeOutput` | *nothing currently* — the branch exists but has no producer | `{value}` | **Replaces** unconditionally |
+| `workspaceFile` | [`useDragWorkspaceFile`](../client/src/hooks/useDragWorkspaceFile.ts) (GalleryPanel) | `{path, ref}` — `ref` is a finished serialized `FileRef` from the server | **Conditional**: a `file` param takes `ref` whole; every other param **appends** `path` with smart spacing |
+
+Two details that look incidental and are not:
+
+- `workspaceFile` is deliberately **not** `nodeOutput`. That branch replaces the
+ target value with no type check, so dropping a file into a half-written prompt
+ would erase the prompt.
+- Its `text/plain` fallback is the bare workspace-relative path, so a drop onto a
+ plain `<textarea>` (or an editor outside the app) still lands something useful.
+ Directories are non-draggable — the server sends them `ref: null`, and appending
+ a bare folder path into a prompt was never the intent.
+
## 4. Parameter Visibility (`displayOptions.show`)
Each `INodeProperties` entry can include a `displayOptions.show` map. Values can be arrays
diff --git a/server/nodes/README.md b/server/nodes/README.md
index f922e4f7..c4df714a 100644
--- a/server/nodes/README.md
+++ b/server/nodes/README.md
@@ -115,7 +115,10 @@ search/ — Web search APIs (brave / serper / perplexity / duckduckgo)
scraper/ — Apify / Crawlee
document/ — RAG pipeline (scrape / download / parse / chunk / embed / store)
code/ — Python / Monty (sandboxed Python) / JS / TS executors
-filesystem/ — file_read / file_modify / shell / fs_search
+filesystem/ — file_read / file_modify / shell / fs_search / gallery
+ (gallery is the workspace file explorer; deliberately NOT
+ usable_as_tool — it carries destructive operations, and
+ fs_search + file_modify already cover what an agent needs)
proxy/ — Residential proxy (request / config / status)
location/ — Google Maps (create / locations / nearby places)
chat/ — chatSend / chatHistory
diff --git a/server/nodes/filesystem/gallery/__init__.py b/server/nodes/filesystem/gallery/__init__.py
index 45b882ec..11cbed7f 100644
--- a/server/nodes/filesystem/gallery/__init__.py
+++ b/server/nodes/filesystem/gallery/__init__.py
@@ -18,7 +18,7 @@ editor.
from __future__ import annotations
-from typing import Any, List, Literal, Optional
+from typing import Any, List, Optional
from pydantic import BaseModel, ConfigDict, Field
diff --git a/server/tests/nodes/test_gallery.py b/server/tests/nodes/test_gallery.py
index 1464a73a..e25b2ddc 100644
--- a/server/tests/nodes/test_gallery.py
+++ b/server/tests/nodes/test_gallery.py
@@ -11,7 +11,6 @@ matters most here.
from __future__ import annotations
-import asyncio
from pathlib import Path
import pytest