Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
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.mdindex 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 bytesserialized, 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 slashworkflow_id: Optional[str] # immutable id — survives renamefilename: str # display only, never used for resolutionmime_type: str- format: strsize_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 guessedsample_rate: Optional[int]channels: Optional[int]- sha256: Optional[str]- url: Optional[str] # path-only, no scheme or hostmodel_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 filesoutside the workspace.- **Range/seeking is free.** Starlette's `FileResponse` already implements`Accept-Ranges`, `206`, `Content-Range`, `If-Range` and `416`. Do not wrap itin 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 allwrite 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.mdindex 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.mdnew file mode 100644index 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.mdindex 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 arraysdiff --git a/server/nodes/README.md b/server/nodes/README.mdindex 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 / Crawleedocument/ — 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 / chatHistorydiff --git a/server/nodes/filesystem/gallery/__init__.py b/server/nodes/filesystem/gallery/__init__.pyindex 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, Optionalfrom pydantic import BaseModel, ConfigDict, Fielddiff --git a/server/tests/nodes/test_gallery.py b/server/tests/nodes/test_gallery.pyindex 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 asynciofrom pathlib import Pathimport pytest