Architecture
Overview
llm-chat-workspace provides workspace and path-access management for the llm-chat ecosystem. It is used by llm-chat-file and llm-chat-shell.
Design
Access model
DirectoryConfiguration defines which directories are accessible and at what permission level. Each access entry pairs an AccessType (read or write) with an absolute directory path. The configuration can be built from constructor arguments or read from LLM_CHAT_WORKSPACE_* environment variables, and is deduplicated according to precedence (write-wins by default).
Workspace
The Workspace class enforces access control for all path operations:
const ws = new Workspace(
new DirectoryConfiguration([
{ type: AccessType.Read, path: '/var/log' },
{ type: AccessType.Write, path: '/home/project' }
])
);
Key methods:
normalize(input): resolves relative paths againstcurrentPath; absolute paths are returned as-iscanRead(absPath): checks if a resolved path falls within any read or write access directorycanWrite(absPath): checks if a resolved path falls within a write access directorygetAccesses(): returns all configured directory accesses with their types and resolved pathswalk(dir, onError?): async generator that recursively walks directories, skipping names listed inskipDirs; throws when the root path does not exist or is not a directory, while nested unreadable directories are reported viaonError
Path security
All operations follow the same access control pattern:
- The raw user-supplied path is normalized via
ws.normalize(path) - The caller checks
ws.canRead()orws.canWrite()on the resolved path - Path traversal attempts (e.g.
../../etc/passwd) are blocked becausepath.resolve()resolves..segments before the access check
By default, symlinks are followed as-is: if a configured directory contains a symlink pointing outside, the symlink target is accessible. Set LLM_CHAT_WORKSPACE_RESOLVE_SYMLINKS=true (or pass resolveSymlinks: true to DirectoryConfiguration) to resolve symlinks via fs.realpathSync.native() before access checks. This prevents symlink-based path traversal but may break legitimate symlinks.
Access rules:
| Operation | Check |
|---|---|
switch_workspace |
within any configured directory |
Concurrency
switchWorkspace() uses async-mutex to prevent concurrent switches from interleaving. After a successful switch, the optional onSwitch hook is awaited before the tool result is returned. The hook is not fired when the path is set in the constructor, and not fired when the switch throws.
Tool classes
SwitchWorkspaceTool extends Tool from llm-chat-tool:
- The constructor accepts a
Workspaceinstance and callssuper(name, description, params) onExecute()validates parameters, callsswitchWorkspace(), and returnsPartialToolResult- All errors are caught and returned as plain-string messages. Tools never throw
Ephemeral workspaces
The package also provides a session-agnostic store for short-lived workspaces.
EphemeralWorkspaceProvisioner creates a private temp directory and a normal
Workspace restricted to it. WorkspaceStore owns the lifetime, byte
accounting, pinning, and LRU eviction:
maxTotalBytescaps the sum across every live workspace.maxBytesPerWorkspacecaps one workspace.maxWorkspacescaps the number of live workspaces.maxFilescaps files across every live workspace.maxFilesPerWorkspacecaps files in one workspace.- A
Mapmaintains the access order used to choose eviction victims. acquire(id)pins a workspace for one tool call and touches its LRU order.ensureCapacity(id, delta)reserves room before a write and evicts other least-recently-used unpinned workspaces when the global cap would be exceeded.dispose()removes every workspace and its temp directory.
The store knows only workspace ids, byte limits, and an opaque resource. It has no session, HTTP, or MCP concepts; a server can hold the process-global store and attach its own tool set to each workspace.
Dependencies
llm-chat-tool: framework providingTool,ToolParameters, etc.async-mutex: mutex used for thread-safe workspace switching