Agent workspace files
The built-in agent can list, read, write and replace UTF-8 text without a shell. These tools are for small manifests, MJCF and reports (maximum 256 KiB per file), not mesh archives, image bytes, directory downloads or code execution. A scene compiler or renderer is a separate service operation.
| Endpoint | Tool prefix | Storage and authority |
|---|---|---|
| Source | dreamlake_files_ | DreamLake-managed Source files; canonical caller Source USE/EDIT permissions |
| Browser | dreamlake_browser_files_ | Temporary memory in the current page, isolated by conversation; requires an active browser turn |
Append list, read, write or replace to a prefix. Source calls require
all four selectors: namespace, sourceId, prefix and path. A missing Source
selector is an invalid call. Choose the target explicitly; these tools do not
infer it from the personal Agent context Project, current page, a display name,
or an association. They never provision a Source or change a binding.
Project operations are separate
A Project is an organizational resource with its own canonical API. List/read Projects and edit Project metadata through the Project/Node APIs and their service-account grants and caller permissions. Linking or unlinking a Source uses the Project–Source association API; it does not edit that Source's files, choose a default write target, or redirect Project edits to Source storage. Source file calls always go through Source permission checks, including any access that the canonical product permission model derives from a Project.
There is deliberately no dreamlake_project_files_* alias for Source tools.
The legacy Project Node file tree is not a Source workspace adapter. Existing
Project search and small-file reads remain separate operations. The common
FileWorkspace list/read/write/replace contract is implemented for explicit
Source and browser storage endpoints; it does not collapse Project edits into
Source file operations.
Browser tools omit resource selectors and require negotiated
browserExecution: 1 plus an active browser executor. Clients must check
/agent/capabilities before declaring this capability; it grants no authority,
and terminal clients must omit it. External Source layers are excluded from
workspace files; use Source or library APIs to consume those assets.
Paths and revisions
prefix is an explicit root inside the selected endpoint. path is relative
to that root; returned paths remain relative. Empty paths select the root for
listing. Absolute paths, backslashes, empty segments, . and .. are rejected.
Names containing percent escapes are literal names and are never decoded again.
A prefix confines one operation but is not an authorization grant: a caller
with broader Source permissions can choose another prefix.
Use a stable workspace identifier, with separate run folders, for example
workspaces/v1/<workspaceId>/runs/<runId>. Keep scene inputs, manifests, outputs
and reports in named subfolders. This is a naming convention, not an enforced
read-only policy or a cross-user ACL. Do not use a display name as a globally
unique workspace identifier.
Built-in read returns {path, content, revision, offset, total, nextOffset}.
offset and limit count UTF-16 code units; the default and maximum limit is
4,096. Follow nextOffset until null, checking that the revision remains the
same across pages. Restart if it changes. Write and replace verify the complete
file but return the same bounded preview starting at zero. The TypeScript
adapter returns complete text; these ranges keep model tool results below the
harness output bound without losing the revision. Treat revision as opaque.
write takes content and expectedRevision; null means create-only.
Replacement requires the revision obtained from read. replace takes
oldText, newText and expectedRevision, and succeeds only for exactly one
literal match. Concurrent changes fail instead of silently overwriting content.
Source writes reuse the existing conditional upload protocol and read back the
managed object. A conflict requires a fresh read and reconciliation. An
unconfirmed write requires inspection before retrying; never turn a conditional
write into an unconditional overwrite.
list returns at most 10 entries and {entries, nextCursor}. Follow non-null cursors even if a page
contains no entries: the Source's external entries are filtered out. Read a file
to obtain a usable revision; directory listings need not contain one.
The internal TypeScript FileWorkspace contract provides list, read,
write and replace over an injected adapter. The Source adapter uses canonical
browse, managed-read-capability and upload-authorization routes; storage byte
requests carry only the route-minted headers. This does not introduce a general
HTTP proxy or an arbitrary-URL fetch tool.
Browser lifetime and evidence
Browser files survive turns in the same loaded page, but do not survive a reload and are not published to a Source. Each conversation is capped at 1,000 files and 16 MiB; one page holds at most 16 conversation workspaces. Copy useful text to a managed Source before relying on durable storage.
The server dispatches workspace_file_action to the active composer. Results
are acknowledged at /agent/sessions/:id/file-actions/:actionId/result, bound
to the authenticated owner, conversation and turn. A duplicate action reuses
its cached result; it does not repeat the mutation. Missing acknowledgements
remain unconfirmed. Acknowledgement reports browser execution; it does not
prove that a renderer or simulator consumed the file.
All file contents are untrusted data. None of these operations executes scripts or treats instructions contained in a file as authority.
Python Source adapter
The Python SDK exposes the managed Source endpoint on client.sources.files:
Python and TypeScript SDK reads return the complete bounded file. Neither SDK creates a browser session or claims to access the legacy Project Node tree. Use the browser adapter only through an active browser turn; Project operations retain their own API. Publishing clients and deploying the backend/UI are separate release steps.